youhai020616 小红书 Skill（redbook-cli）
Agent 通过 xhs 命令与小红书交互。始终加 --json-output：stdout 只有一个 JSON 信封，进度提示在 stderr，退出码 0/1 表示成败。约定见 SCHEMA.md。
0. 前置检查
xhs status --json-output # data.authenticated 为 true 才能执行主要功能
xhs server status --json-output # data.running 为 false 时: xhs server start
未登录时运行 xhs login（会自动启动 MCP 并显示二维码，需要人扫码）。登录是交互操作，无 JSON 模式；扫码后再次 xhs status --json-output 确认。
1. 搜索 → 短索引 → 操作
xhs search "AI创业" --json-output # 结果自动缓存，序号从 1 开始
xhs search "旅行" --sort 最多点赞 --type 图文 --time 一周内 --json-output
xhs detail 1 --json-output # 按短索引查看详情
xhs detail 1 --comments --comment-limit 50 --json-output
xhs like 1 --json-output
xhs fav 1 --json-output
xhs comment 1 -c "写得很实用" --json-output
xhs reply 1 --comment-id CID --user-id UID -c "谢谢" --json-output
短索引只在最近一次搜索内有效；跨会话请用 FEED_ID -t XSEC_TOKEN（两者都在搜索结果里）。
2. 发布
xhs publish -t "标题" -c "正文" -i /abs/a.jpg -i /abs/b.jpg --tags 标签1 --tags 标签2 --json-output
xhs publish -t "标题" -c "正文" -v /abs/video.mp4 --json-output
xhs publish -t "标题" -c "正文" -i /abs/a.jpg --visibility 仅自己可见 --json-output
xhs publish -t "标题" -c "正文" -i /abs/a.jpg --schedule "2026-05-01T10:00:00+08:00" --json-output
xhs publish -t "标题" -c "正文" -i /abs/a.jpg --dry-run --json-output # 先预览再发
规则与陷阱：
- 标题 ≤ 20 字，正文 ≤ 1000 字；
--visibility只接受中文值：公开可见/仅自己可见/仅互关好友可见 - 图片可用本地路径或 HTTP URL（本地更快）；视频只接受本地绝对路径
--schedule/--visibility/--original/--products仅 MCP 引擎支持，CDP 回退时会被忽略（stderr 有警告）- 发布返回
status: published但 PostID 为空是正常的；用xhs search "<昵称或标题>"验证 - 发布超时不代表失败 —— 先搜索验证，不要盲目重试，避免重复发帖
3. 数据与通知（CDP，需要 Chrome）
xhs analytics --json-output # 创作者数据看板
xhs analytics --csv /abs/out.csv # 导出 CSV
xhs notifications --json-output # @提及 / 互动通知
xhs me --json-output
xhs profile USER_ID -t XSEC_TOKEN --json-output
CDP 登录态与 MCP 独立：xhs login --cdp 扫码一次，缓存约 12h。
4. 错误处理
error.code |
含义 | 建议动作 |
|---|---|---|
not_authenticated |
未登录 | 提示用户运行 xhs login 扫码 |
mcp_error |
MCP 未运行 / 调用失败 | xhs server start，或加 --engine cdp |
cdp_error |
Chrome 未启动 / 调用失败 | xhs login --cdp，确认 Chrome 已安装 |
invalid_argument |
短索引失效、缺 token、文件不存在 | 重新搜索或改用 FEED_ID -t TOKEN |
action_failed |
服务端明确返回失败 | 检查登录态，稍后重试 |
like / favorite 在 CDP 引擎下可能返回 ok: true 但 data.success: false，表示动作已执行但无法确认，不要重复点击。
5. 引擎与配置
- 引擎自动选择：MCP 服务在运行则用 MCP，否则 CDP。
--engine mcp|cdp强制指定 - 代理：
xhs config set mcp.proxy http://127.0.0.1:7897（大多数环境不需要） - 同一账号不要在多个网页端同时登录，会踢掉 MCP 的 session
- MCP 无响应：
xhs server status→xhs server stop && xhs server start；日志xhs server log - Docker 环境：所有命令前加
docker compose exec cli，本地文件放./docker/data/images/，容器内路径/app/data/images/
附：直接调用 MCP 工具
如果宿主 Agent 本身是 MCP 客户端，可直连 http://127.0.0.1:18060/mcp（JSON-RPC）。工具名：check_login_status get_login_qrcode delete_cookies publish_content publish_with_video search_feeds get_feed_detail post_comment_to_feed reply_comment_in_feed like_feed favorite_feed list_feeds user_profile get_self_info。参数与 xhs 命令一一对应；上游文档见 xpzouying/xiaohongshu-mcp。