add: post-to-xhs skills

2026-02-05 19:25:53 +08:00
parent c596ab1be3
commit b50f0aa633
14 changed files with 2066 additions and 0 deletions
--- a/skills/post-to-xhs/references/publish-workflow.md
+++ b/skills/post-to-xhs/references/publish-workflow.md
@@ -0,0 +1,196 @@
+# 小红书发布流程参考
+
+本文档描述通过 CDP（Chrome DevTools Protocol）自动发布内容到小红书创作者中心的完整流程。
+
+## 前置条件
+
+1. **Chrome 浏览器已安装** - 标准 Google Chrome
+2. **Python 依赖已安装** - `websockets`、`requests`
+3. **首次登录已完成** - 至少登录过一次小红书（cookie 持久化在专用 profile 中）
+
+## 流程概览
+
+```
+生成文案 → 用户确认 → 启动 Chrome → 检查登录 → 导航发布页 → 上传图片 → 填写标题 → 填写正文 → 用户确认发布
+```
+
+## 详细步骤
+
+### 1. 启动 / 连接 Chrome
+
+脚本: `scripts/chrome_launcher.py`
+
+- 检测 `127.0.0.1:9222` 端口是否已有 Chrome 实例
+- 若无，启动 Chrome 并附带以下参数:
+  - `--remote-debugging-port=9222`
+  - `--user-data-dir=%LOCALAPPDATA%/Google/Chrome/XiaohongshuProfile`
+  - `--no-first-run`
+  - `--no-default-browser-check`
+  - `--headless=new`（仅在无头模式下）
+- 等待端口就绪（最多 15 秒）
+
+**用户数据目录说明**: 使用独立的 `XiaohongshuProfile` 目录，与用户日常浏览器 profile 完全隔离，不会干扰正常使用。
+
+**无头模式说明**: 使用 `--headless` 参数启动时，Chrome 不会显示窗口，适合自动化发布。如需登录或切换账号，脚本会自动切换到有窗口模式。
+
+### 2. 检查登录状态
+
+脚本: `scripts/cdp_publish.py` → `check_login()`
+
+- 导航到 `https://creator.xiaohongshu.com`
+- 检查当前 URL 是否包含 "login"（被重定向到登录页）
+- 检查页面是否存在用户信息相关的 DOM 元素
+- 若未登录，提示用户在 Chrome 窗口中扫码登录
+
+### 3. 导航到发布页
+
+- 目标 URL: `https://creator.xiaohongshu.com/publish/publish`
+- 等待页面完全加载
+
+### 4. 上传图片
+
+脚本: `scripts/cdp_publish.py` → `_upload_images()`
+
+- 通过 CDP `DOM.querySelector` 定位 `input[type="file"]` 元素
+- 使用 CDP `DOM.setFileInputFiles` 命令设置文件路径
+- 等待图片上传和处理完成
+
+**图片来源**: 如果图片是 URL，先用 `scripts/image_downloader.py` 下载到临时目录，发布后自动清理。
+
+### 5. 填写标题
+
+脚本: `scripts/cdp_publish.py` → `_fill_title()`
+
+- 定位标题输入框
+- 设置 value 并触发 `input` 和 `change` 事件
+
+### 6. 填写正文
+
+脚本: `scripts/cdp_publish.py` → `_fill_content()`
+
+- 定位 contenteditable 编辑区域（TipTap/ProseMirror editor）
+- 将正文按段落拆分，包裹为 `<p>` 标签写入 innerHTML，段落之间插入 `<p><br></p>` 空行
+- 触发 `input` 事件
+
+### 7. 用户确认并发布
+
+- 脚本填写完成后暂停，提示用户在浏览器中检查预览
+- 用户确认后，脚本点击发布按钮
+- 或用户选择手动点击发布按钮
+
+## DOM 选择器参考
+
+> **注意**: 小红书前端可能随时更新，以下选择器基于编写时的页面结构。如果自动化失败，需要在浏览器 DevTools 中重新抓取选择器，并更新 `cdp_publish.py` 中的 `SELECTORS` 字典。
+
+| 元素 | 主选择器 | 备选选择器 | 说明 |
+|---|---|---|---|
+| 图片上传 | `input.upload-input` | `input[type="file"]` | 隐藏的文件输入，通过 CDP 直接操作 |
+| 标题输入 | `input[placeholder*="填写标题"]` | `input.d-text` | 标题输入框 |
+| 正文编辑 | `div.tiptap.ProseMirror` | `div.ProseMirror[contenteditable="true"]` | TipTap/ProseMirror 富文本编辑器 |
+| 发布按钮 | 文本匹配"发布"（`button` + `.d-button-content .d-text`） | - | 通过遍历按钮文本定位 |
+| 登录检测 | URL 包含 "login" | `.user-info, .creator-header` | 重定向检测 + DOM 元素检测 |
+
+## 选择器维护指南
+
+当小红书更新页面导致自动化失败时:
+
+1. 在 Chrome 中打开 `https://creator.xiaohongshu.com/publish/publish`
+2. 按 F12 打开开发者工具
+3. 使用元素选择器（Ctrl+Shift+C）定位目标元素
+4. 记录新的选择器
+5. 更新 `scripts/cdp_publish.py` 中 `SELECTORS` 字典对应的值
+
+## 错误处理
+
+| 错误 | 原因 | 解决方案 |
+|---|---|---|
+| Chrome 未启动 | 端口 9222 无响应 | 运行 `chrome_launcher.py` 或手动启动 Chrome |
+| 找不到 Chrome | 非标准安装路径 | 检查 Chrome 安装，或在脚本中指定路径 |
+| 未登录 | cookie 过期或首次使用 | 在 Chrome 窗口中扫码登录 |
+| 选择器失效 | 小红书页面更新 | 按上述维护指南更新选择器 |
+| 图片上传失败 | 文件路径错误或格式不支持 | 检查图片路径，确保格式为 jpg/png/webp |
+| 发布按钮找不到 | 页面未完全加载 | 增加等待时间或手动点击发布 |
+
+## CLI 用法
+
+所有脚本位于 `scripts/` 目录。
+
+### 方式 A: 统一 pipeline（推荐）
+
+```bash
+# 无头模式（推荐）- 无浏览器窗口，更快
+python publish_pipeline.py --headless --title "标题" --content "正文" --image-urls URL1 URL2
+
+# 无头模式 - 从文件读取标题和正文
+python publish_pipeline.py --headless --title-file title.txt --content-file body.txt --image-urls URL1
+
+# 有窗口模式 - 用于调试或首次登录
+python publish_pipeline.py --title "标题" --content "正文" --image-urls URL1 URL2
+
+# 使用本地图片文件
+python publish_pipeline.py --headless --title "标题" --content "正文" --images img1.jpg img2.jpg
+
+# 填写并自动发布
+python publish_pipeline.py --headless --title "标题" --content "正文" --image-urls URL1 --auto-publish
+```
+
+输出状态码:
+- 退出码 0 + `READY_TO_PUBLISH` = 表单已填写，等待确认
+- 退出码 0 + `PUBLISHED` = 已发布
+- 退出码 1 + `NOT_LOGGED_IN` = 未登录，需扫码（无头模式下会自动切换到有窗口模式）
+- 退出码 2 = 其他错误
+
+### 方式 B: 分步调用
+
+```bash
+# 1. 启动 Chrome（可选 --headless）
+python chrome_launcher.py
+python chrome_launcher.py --headless
+
+# 2. 检查登录（退出码 0=已登录, 1=未登录）
+python cdp_publish.py check-login
+python cdp_publish.py --headless check-login
+
+# 3. 填写表单
+python cdp_publish.py fill --title "标题" --content-file body.txt --images img1.jpg
+python cdp_publish.py --headless fill --title "标题" --content-file body.txt --images img1.jpg
+
+# 4. 用户确认后点击发布
+python cdp_publish.py click-publish
+
+# 或一步完成填写+发布
+python cdp_publish.py --headless publish --title "标题" --content-file body.txt --images img1.jpg
+```
+
+### 账号管理
+
+```bash
+# 首次登录或 session 过期 - 打开浏览器扫码登录
+python cdp_publish.py login
+
+# 切换账号 - 清除 cookie 并打开登录页
+python cdp_publish.py switch-account
+
+# 关闭 Chrome
+python chrome_launcher.py --kill
+
+# 重启 Chrome（可选无头模式）
+python chrome_launcher.py --restart
+python chrome_launcher.py --restart --headless
+```
+
+### Claude Code 集成
+
+在 Claude Code 中通过 Bash 工具调用。推荐使用 pipeline 方式:
+
+1. 将中文标题和正文写入临时文本文件（UTF-8 编码）
+2. 调用 `publish_pipeline.py --headless` 传入文件路径和图片 URL
+3. 根据输出状态码处理结果：
+   - 未登录 → 脚本自动切换到有窗口模式，提示用户扫码
+   - 已填写 → 请用户确认预览
+4. 用户确认后调用 `cdp_publish.py click-publish` 发布
+
+**切换账号流程**:
+1. 调用 `cdp_publish.py switch-account`
+2. 等待用户扫码确认
+3. 继续正常发布流程