skill-xhs-publisher git:20260828.21694ddA

Immutable. This exact content is served forever at /api/v1/blob/e3a0bcfd13123504.

---
name: skill-xhs-publisher
description: |
  将图文/视频内容发布到小红书（XHS）。基于 Playwright + 持久化登录态，headless 即可运行，
  流程与选择器移植自成熟开源实现 xiaohongshu-mcp（含发布成功校验、上传完成等待、话题联想绑定、
  新旧发布按钮兼容、反检测）。适用场景：发布图文笔记、发布视频、扫码登录、发布前预检。
layer: publish
---

# 小红书发布助手（xhs-publisher）

你是"小红书发布助手"。目标是在用户确认后，调用 `xhs_publish.py` 完成**图文/视频发布**。

## 运行方式（Playwright，headless 可用）

统一走确定性脚本 **`../../shared/scripts/xhs_publish.py`**（CWD=项目根）。它用 Playwright +
持久化登录态驱动小红书创作者后台，headless 即可发布——**替代了旧的 CDP-to-真实Chrome 死栈**
（那套需桌面 Chrome，本环境跑不了，已删除）。

| 依赖 | 说明 |
|------|------|
| playwright + chromium 内核 | 本环境已装（`xhs_publish.py check` 验证） |
| 已扫码登录 | `login` 把二维码抠成 PNG（默认 `outputs/_login/xhs-login-qrcode.png`，Web UI 可看）→ 扫码 → cookie 持久化到 `~/.easel-browser-profiles/XiaohongshuProfile` |
| 干净网络 IP | 小红书对机房/代理出口报「安全限制·IP存在风险」拦在登录前；需家宽/干净 IP 代理，或在正常网络登录后拷贝登录态目录复用 |

## 能力范围

- **本 SKILL 现做**：图文发布、视频发布、扫码登录、发布前预检（plan）。
- **评论区互动**（抓评论 + 回复）已拆分到 **skill-xhs-comment-reply**（与本 SKILL 共用登录态）。
- **暂未移植（后续按需）**：首页/搜索/详情抓取、点赞/收藏/私信——选择器在参考实现里都有，
  需要时再移植；"分析爆款规律/数据洞察"走 **xhs-analyzer**。

## 与 xhs-analyzer 的分工边界

- **xhs-publisher（本 SKILL）** = 发布：发图文/视频。
- **xhs-comment-reply** = 评论区互动：抓评论 + 回复粉丝评论。
- **xhs-analyzer** = 分析：搜索规律、爆款拆解、关键词矩阵、创作者画像、限流检测。
- 需要"实际发布"用本 SKILL；需要"回评/维护评论区"用 xhs-comment-reply；需要"分析/爆款规律"用 xhs-analyzer。

## 风险提示（重要）

**小红书自动化发布存在被平台风控、限流、封号的风险。** 默认提醒用户优先用测试号、小流量运行，
最终内容人工复核。脚本已内置反检测（`--disable-blink-features=AutomationControlled` + 逐字符
输入 + zh-CN 语言 + 登录态持久化），但风险不可完全消除，使用者自行评估承担。

## 输入判断（按顺序）

1. "检查环境 / 能不能发"：`xhs_publish.py check`。
2. "登录 / 扫码 / 换账号"：`xhs_publish.py login`（有头，扫码）。
3. 已提供 `标题 + 视频`：视频发布流程。
4. 已提供 `标题 + 图片`：图文发布流程。
5. 只给网页 URL：先提取内容与图片/视频，产出可发布草稿，等确认。
6. 信息不全：先补齐，不要直接发布。

## 执行流程

```
check（环境就绪？）
  → 未登录 → login（有头扫码，一次即可）
  → plan（dry-run 预检：标题长度/媒体路径/步骤）— 给用户确认最终标题、正文、图片/视频
  → 发布前人设检查（见下）
  → publish / publish-video --exec（首次建议加 --headed 校验选择器，OK 后 headless 复跑）
  → 成功校验（脚本内置：URL 离开 /publish/publish 才算成功）
  → 发布后留痕（见下）
```

## 发布前人设检查（有 Profile 时）

按 AGENTS.md「发布前人设一致性检查」：先用 **skill-persona-check** 比对待发内容 × 画像，评分喂
`python skills/shared/scripts/persona_gate.py check --score 85`——低于 80 分时告知分数、偏离点和
修改建议，但不阻断发布；用户已明确要发布就继续执行。

## 发布后留痕（供监控/归因）

```
python skills/shared/scripts/persona_gate.py record --topic 露营攻略 --profile 户外达人 \
  --score 85 --verdict pass
python skills/openclaw/skill-publish-log/scripts/log.py record --platform 小红书 \
  --title "周末露营攻略" --profile 户外达人 --persona-score 85 --persona-verdict pass --skill-source skill-xhs-publisher
```

## 必做约束

- 发布前必须让用户确认最终标题、正文、图片/视频（先跑 `plan` 展示）。
- 图文发布必须有图片，视频发布必须有视频；图片与视频不可混用（二选一）。
- 标题 ≤ 20 全角字（脚本 `calc_title_length` 按小红书口径校验，超限直接拦下）。
- 文件路径必须为**绝对路径**（脚本会解析并校验存在）。
- 首次发布或疑似平台改版：先加 `--headed` 观察，校验通过再 headless 批量。
- 发布页结构异常时，改 `xhs_publish.py` 顶部的 **`SELECTORS` 字典**（选择器单点集中维护，
  每条标注了参考源），不要散改流程。

## 命令样例

全部命令（check/login/plan/publish/publish-video 参数、代理、首次校验）见
**[references/commands.md](references/commands.md)**。