xhs-publisher

description: "将 Markdown 文章自动发布到小红书（XHS）草稿箱。支持多图上传（封面+素材）、标题/正文填充、标签匹配、排版优化检查。基于 Playwright file_chooser API + CDP 操作。" license: MIT metadata: version: 1.5.0 author: xiaocode + CCO Ives domains: [content, publishing, automation, xiaohongshu] type: automation requires: [playwright, openclaw-browser]

XHS Publisher — 小红书自动发布 v1.5

将 Markdown 文章一键发布到小红书创作者平台草稿箱。支持多图上传。

什么时候用

• 有了写好的 XHS 文章（markdown），需要上传到草稿箱
• 需要上传封面 + 多张素材图（最多18张）
• 批量发布内容到 XHS
• 自动化内容分发 pipeline 中的一环
• 其他 agent 需要发布 XHS 内容时

📋 发布前请确认内容合规：~/clawd/projects/MediaClaw/references/platforms/xiaohongshu.md

不适用

• ❌ 需要直接正式发布（不是草稿）— 当前仅支持存草稿，由人工最终发布
• ❌ 视频内容 — 仅支持图文笔记
• ❌ 需要编辑已发布笔记

前置条件

条件	说明	检查方法
Playwright	Python playwright 库	pip show playwright
OpenClaw Browser	浏览器服务运行中	curl -s http://127.0.0.1:18800/json/version
XHS Cookie	Playwright state 文件有效	~/.playwright-data/xiaohongshu/state-default.json
Cookie 未过期	cookies.expires > 当前时间	检查 cookie 中 a1 的 expires 字段
unset代理	CDP WebSocket会被代理阻断	unset ALL_PROXY all_proxy https_proxy http_proxy

输入

输入参数:
  article_path: string        # Markdown 文件路径
  cover_path: string          # 封面图路径 (jpg/png/webp, 推荐 3:4 ≥720x960)
  images: list[string]        # 追加素材图片 (可选, 最多17张, 总计≤18)
  decision: draft             # 当前仅支持 draft

Markdown 格式要求

📌 标题：你的标题（≤20字）
🏷️ 标签：#标签1 #标签2 #标签3

📝 正文：

正文内容...
（≤1000字）

输出

输出:
  status: ok | error
  draft_saved: true/false
  draft_count: "草稿箱(N)"
  title: string
  title_truncated: boolean
  content_length: number
  images_uploaded: number    # 上传图片总数 (含封面)
  tags_added: list[string]

使用方法

单图（封面 only）

unset ALL_PROXY all_proxy https_proxy http_proxy
python3 ~/clawd/projects/MediaClaw/skills/xhs-publisher/scripts/publish.py \
  --article /path/to/article.md \
  --cover /path/to/cover.jpg \
  --decision draft

多图（封面 + 素材图）

unset ALL_PROXY all_proxy https_proxy http_proxy
python3 ~/clawd/projects/MediaClaw/skills/xhs-publisher/scripts/publish.py \
  --article /path/to/article.md \
  --cover /path/to/cover.jpg \
  --images img1.jpg img2.png img3.jpg \
  --decision draft

Shell glob 批量素材

python3 publish.py \
  --article article.md \
  --cover cover.jpg \
  --images 素材/*.png 素材/*.jpg

作为模块调用

import asyncio
from scripts.publish import publish_to_xhs

result = asyncio.run(publish_to_xhs(
    article_path="/path/to/article.md",
    cover_path="/path/to/cover.jpg",
    images=["img1.jpg", "img2.png"],  # 可选
    decision="draft",
))
print(result)

Agent 调用（推荐）

请发布文章到 XHS 草稿箱：
- 文章: ~/clawd/projects/MediaClaw/output/articles/2026-04-16/claude-vs-codex/xhs/article.md
- 封面: ~/clawd/projects/MediaClaw/output/articles/2026-04-16/claude-vs-codex/xhs/cover-3x4.jpg
- 素材: ~/clawd/projects/MediaClaw/output/articles/2026-04-16/claude-vs-codex/素材/*.png

核心流程

解析 Markdown → 验证图片 → 启动浏览器 → 加载 Cookie → 打开创作者页面
→ 切换到"上传图文"tab（最后一个可见tab）
→ file_chooser 上传封面 → 等待编辑器出现
→ 逐张追加素材图（通过编辑器内 file input）
→ 填充标题 → 填充正文 → 匹配标签 → 截图 → 存草稿

v1.5 关键技术变更

❌ 旧方案（v1.4，已废弃）

# 不工作：set_input_files 不触发 XHS React change 事件
await file_input.set_input_files(paths)

✅ 新方案（v1.5，已验证）

# 1. 用 file_chooser API（Playwright 标准文件上传方式）
async with page.expect_file_chooser() as fc:
    await file_input.evaluate("el => el.click()")
file_chooser = await fc.value
await file_chooser.set_files(path)

# 2. 点击最后一个可见的"上传图文"tab（XHS 有3个重复 tab）
tabs = document.querySelectorAll('div.creator-tab')
imageTabs = tabs.filter(t => t.text === '上传图文' && visible)
imageTabs[imageTabs.length - 1].click()  # 最后一个！

多图上传流程

1. 封面 → file_chooser.set_files(cover) → 等待8s → 编辑器出现
2. 素材图1 → 编辑器内 file_input.click() → file_chooser.set_files(img1) → 等待4s
3. 素材图2 → 同上
...
N. 最多封面+17张追加（XHS 总上限18张）

关键发现：

• XHS file input 没有 [multiple] 属性（Playwright 读取到的 multiple=false）
• 即使注入 multiple=true，set_input_files([file1, file2]) 也不触发 React
• file_chooser.set_files() 是唯一可靠的上传方式
• 编辑器内追加图片通过隐藏的 input[type='file'] 触发

关键 Selector

元素	CSS Selector	说明
Tab切换	div.creator-tab (文本="上传图文")	点击最后一个可见的
图片上传	input.upload-input[type="file"]	隐藏元素，用 file_chooser
编辑器内图片	input[type="file"]	编辑器内的隐藏 file input
标题输入	input.d-text[type="text"]	placeholder="填写标题会有更多赞哦"
正文编辑器	div.tiptap.ProseMirror[contenteditable="true"]	TipTap ProseMirror
话题按钮	button.contentBtn.topic-btn	打开标签面板
存草稿按钮	"暂存离开" (button text)	JS click by textContent
发布按钮	"发布" (button text)	JS click by textContent

边界处理

1. 标题 20 字限制

XHS 标题严格限制 20 字（含标点），超出自动截断并标记。

2. 正文 1000 字限制

XHS 正文限制 1000 字（含空格和 emoji），超出自动截断。

3. 图片上限 18 张

封面 + 追加图片总计不超过 18 张。超出自动截断并警告。

4. ProseMirror 填充

await page.evaluate('''([el, html]) => {
    el.innerHTML = html;
    el.dispatchEvent(new Event("input", { bubbles: true }));
}''', [editor, body_html])

5. 标签策略

使用策略 1：将标签以 #标签1 #标签2 追加到正文末尾。XHS 自动识别并高亮。

6. 上传图文 Tab 切换（踩坑）

XHS 有 3个 重复的 div.creator-tab（文本="上传图文"）。

• 第一个：可能指向视频区域（点击后进入错误状态）
• 最后一个：正确的图文上传入口

# 点击最后一个可见的"上传图文"tab
tabs = document.querySelectorAll('div.creator-tab')
imageTabs = Array.from(tabs).filter(t => t.textContent.trim() === '上传图文' && t.getBoundingClientRect().x > 0)
imageTabs[imageTabs.length - 1].click()

7. 代理问题

ALL_PROXY / socks:// 环境变量会阻断 Playwright CDP WebSocket 连接。 运行脚本前必须：

unset ALL_PROXY all_proxy https_proxy http_proxy

安全机制

Pre-flight Health Check

每次发布前自动检查：浏览器连接、Cookie有效性、文件存在性、图片格式。

安全截图（Safety Screenshots）

打开页面 → [截图#1] → 上传封面 → [截图#2]
→ 填标题 → [截图#3] → 填正文 → [截图#4]
→ 存草稿 → [截图#5] → 草稿确认 → [截图#6]

截图目录：/tmp/xhs_safety/

重试机制

失败场景	重试次数	退避策略
网络超时	3次	10s → 20s → 40s
Selector 未找到	2次	5s → 10s
文件上传失败	3次	10s → 20s → 40s
页面加载失败	2次	15s → 30s

常见问题

Q: 图片上传后编辑器没出现？

A: 可能点错了tab。XHS有3个重复tab，必须点最后一个。v1.5已修复。

Q: 多图上传报 "Non-multiple file input"？

A: v1.5已改用file_chooser API，不再依赖input[multiple]属性。

Q: CDP连接超时？

A: 检查是否设置了代理环境变量：unset ALL_PROXY all_proxy https_proxy http_proxy

Q: Cookie 过期怎么办？

A: Daniel通过浏览器登录XHS创作者平台，Cookie自动保存。

依赖

playwright>=1.40.0
Pillow (可选, 图片尺寸验证)

触发词

• "发布到小红书"、"发XHS"、"上传到XHS草稿箱"
• "小红书发布"、"XHS publish"、"小红书草稿"
• "publish xhs"、"xhs draft"、"MediaClaw XHS"
• "XHS多图发布"、"小红书多图上传"

更新日志

• v1.5.0 (2026-04-16): 多图上传 + 核心修复
  • ✅ 多图上传：封面 + 追加素材图（最多18张）
  • ✅ 修复：使用 file_chooser API 替代 set_input_files（React不响应后者）
  • ✅ 修复：点击最后一个可见"上传图文"tab（XHS有3个重复tab）
  • ✅ 新增 --images 参数（可选，支持shell glob）
  • ✅ 新增图片验证（存在性、格式、上限18张）
  • ✅ 新增代理环境变量 unset 提醒
  • 🧪 实测通过：单图草稿(24) ✅ 多图(1封面+2素材)草稿(26) ✅
• v1.2.0 (2026-04-16): 安全增强
  • Pre-flight health check
  • 安全截图机制
  • 重试机制 + 指数退避
  • 错误处理策略细化
• v1.1.0 (2026-04-14): 初始版本
  • 完整 selector 验证
  • ProseMirror 填充方案
  • 标题/正文限制处理
  • 标签嵌入策略