teamwiseflow xhs-content-ops — 工具说明
本文是
expert-xhs专家包内的工具说明书，不独立出现在技能列表中。由相关 Workflow 指引调用。
用途：按 URL 或 note-id 下载单篇小红书图文笔记的正文、图片、作者与互动数据（点赞/收藏/评论/分享），供对标分析、DNA 采样、仿写参考使用。
输入：笔记 URL（xhslink.com 短链或 xiaohongshu.com/explore/... 完整链接），或 note-id + xsec-token；外加输出目录。
输出：stdout JSON（正文 / 图片列表 / 作者 / stats）+ 图片落盘到输出目录。
边界：只处理图文笔记。视频笔记（noteType: "video"）返回 VIDEO_NOTE 错误，转 viral-chaser 处理。
小红书 URL 格式参考
| 页面 | URL |
|---|---|
| 搜索结果 | https://www.xiaohongshu.com/search_result?keyword=关键词 |
| 笔记详情 | https://www.xiaohongshu.com/explore/{feed_id}?xsec_token={token}&xsec_source=pc_feed |
| 用户主页 | https://www.xiaohongshu.com/user/profile/{user_id} |
从搜索结果或页面链接里提取 note_id 与 xsec_token：explore/{feed_id}?xsec_token={token}，feed_id 即 note_id。
使用方式
通过 PATH 调用 wrapper：xhs-content-ops <参数>，无需手动拼接 node 命令或脚本路径。
# 推荐：直接传 URL（支持 xhslink.com 短链和完整 explore 链接，脚本自动解析 note_id + xsec_token）
xhs-content-ops \
--url <url> \
--output-dir <output_dir>
# 或：已拿到 note-id 时（必须同时传 xsec_token，否则 HTML 路线拿到空页）
xhs-content-ops \
--note-id <note_id> \
--xsec-token <token> \
--xsec-source <source> \
--output-dir <output_dir>
参数：
| 参数 | 必填 | 说明 |
|---|---|---|
--url |
二选一 | 笔记 URL（xhslink.com 短链或 xiaohongshu.com/explore/... 完整链接），脚本自动解析 note_id + xsec_token |
--note-id |
二选一 | 小红书笔记 ID（与 --url 二选一） |
--xsec-token |
--note-id 时必填 |
xsec_token（用 --note-id 时必传，否则 HTML 路线拿空页；用 --url 时脚本自动提取） |
--xsec-source |
否 | xsec_source，默认 pc_feed |
--output-dir |
是 | 输出目录，必须工作区相对路径（如 xhs/ref/<dna-id>/<sample-id>/ 或 campaign_assets/<slug>/），图片和正文保存到此 |
⚠️
--output-dir必须用工作区相对路径，不要用/tmp。后续要用 image 工具读取下载的图片做视觉分析，而 image 工具只能读允许目录（工作区）下的文件，/tmp下的图片会被拒绝（Local media path is not under an allowed directory），导致整轮分析白跑。
输出： JSON 到 stdout
{
"ok": true,
"noteId": "xxx",
"noteType": "normal",
"title": "笔记标题",
"desc": "正文内容",
"author": "作者昵称",
"stats": { "likeCount": 100, "collectCount": 50, "commentCount": 20, "shareCount": 10 },
"images": ["output_dir/img_00.jpg", "output_dir/img_01.jpg"],
"coverUrl": "https://...",
"tags": ["话题1", "话题2"]
}
技术路线
- 脚本走无 cookie SSR HTML 路线（GET 笔记详情页 HTML 解析 og:meta +
__INITIAL_STATE__，不走 feed API / relay 签名）；带 xsec_token 的公开笔记无需登录态。 - 无 cookie 抓不到（滑块 / 空页）时才用本机
xhs-browsecookie + 同指纹 UA 回退一次（同时读~/.openclaw/logins/xhs-browse.json+xhs-browse.ua.json，同一指纹下的 cookie 才不会被风控错配）。 - cookie 回退仍失败 →
exit 2，走login-manager重登xhs-browse后重试。 - 脚本不依赖 relay 签名 / OFB_KEY（HTML 路线无需签名）。
注意事项
- 控制频率：批量下载时间隔 5-10 秒，串行执行，不并发。
- 仅处理图文笔记：遇到视频笔记（返回
VIDEO_NOTE），提示转viral-chaser。 - 复合流程（搜索 → 筛选 → 批量下载 → 分析）中每一步都应向用户报告进度。
失败处理
| 情况 | 处理 |
|---|---|
exit 1 + NO_XSEC_TOKEN |
缺 xsec_token；从笔记链接里补提后重试 |
exit 1 + NEED_VERIFY |
触发滑块；停止重试，走重登流程或换时间再试 |
exit 2（cookie 回退也失败） |
login-manager 重登 xhs-browse 后重试一次 |
| 笔记无法访问 | 该笔记可能已删除或设为私密，跳过 |
| 视频笔记 | 转 viral-chaser |