xhs-publisher 是一个面向小红书（XHS）创作者平台的自动化发布工具，主要用途是把已经写好的 Markdown 文章一键上传到小红书草稿箱，并支持多图上传。它适合需要上传封面加多张素材图、批量发布内容、或作为自动化内容分发 pipeline 一环的场景，也方便其他 agent 调用完成 XHS 内容发布。
主要能力包括：解析 Markdown 文章，验证图片，启动浏览器并加载 Cookie，打开创作者页面，切换到“上传图文”tab，通过 file_chooser 上传封面，等待编辑器出现后逐张追加素材图，填充标题与正文，匹配标签，截图并保存草稿。图片方面，封面加追加素材图总计不超过 18 张（封面 1 张，追加素材最多 17 张）。标题限制 20 字（含标点），正文限制 1000 字（含空格和 emoji），超出会自动截断并标记。标签策略为将标签以 #标签1 #标签2 形式追加到正文末尾，由 XHS 自动识别并高亮。
使用方式上，需先满足前置条件：安装 Python playwright 库（playwright>=1.40.0），OpenClaw Browser 浏览器服务运行中，XHS Cookie 的 Playwright state 文件有效且未过期，并取消代理环境变量（unset ALL_PROXY all_proxy https_proxy http_proxy），因为 CDP WebSocket 会被代理阻断。输入参数包括 article_path（Markdown 文件路径）、cover_path（封面图路径，jpg/png/webp，推荐 3:4 且不小于 720x960）、images（可选追加素材图片列表，最多 17 张）、decision（当前仅支持 draft）。Markdown 格式要求包含标题（≤20字）、标签（#标签1 #标签2 #标签3）和正文（≤1000字）。可通过命令行单图或多图方式运行，也支持 shell glob 批量素材，还可作为模块调用或由 agent 调用。输出包含 status、draft_saved、draft_count、title、title_truncated、content_length、images_uploaded、tags_added 等字段。
核心流程为：解析 Markdown → 验证图片 → 启动浏览器 → 加载 Cookie → 打开创作者页面 → 切换到“上传图文”tab（最后一个可见 tab）→ file_chooser 上传封面 → 等待编辑器出现 → 逐张追加素材图（通过编辑器内 file input）→ 填充标题 → 填充正文 → 匹配标签 → 截图 → 存草稿。v1.5 的关键技术变更是使用 file_chooser API 替代 set_input_files，因为后者不触发 XHS React change 事件；同时需点击最后一个可见的“上传图文”tab，因为 XHS 有 3 个重复 tab。
安全机制方面，每次发布前自动进行 Pre-flight Health Check，检查浏览器连接、Cookie 有效性、文件存在性和图片格式；过程中生成安全截图（打开页面、上传封面、填标题、填正文、存草稿、草稿确认），截图目录为 /tmp/xhs_safety/；并具备重试机制与指数退避策略，覆盖网络超时、Selector 未找到、文件上传失败、页面加载失败等场景。
限制方面：当前仅支持存草稿，不支持直接正式发布，需人工最终发布；仅支持图文笔记，不支持视频内容；不支持编辑已发布笔记。依赖 playwright>=1.40.0，Pillow 为可选（用于图片尺寸验证）。触发词包括“发布到小红书”“发XHS”“上传到XHS草稿箱”“小红书发布”“XHS publish”“小红书草稿”“publish xhs”“xhs draft”“MediaClaw XHS”“XHS多图发布”“小红书多图上传”等。