0 Fork 0

Files

T

cv-cat dc078b248b catbus：一个命令操作小红书、抖音、TikTok、B 站、快手、微博、闲鱼、淘宝、京东、X

10 个平台的 web 端全部用 TypeScript 移植自 cv-cat 的开源项目，请求与上游逐字节对拍。
统一的命令语法与 JSON 输出、按 平台 × 端 × 账号 隔离的登录态、给 AI Agent 用的技能与 llms.txt。

2026-10-06 19:24:55 +08:00

11 KiB

Raw Permalink Blame History

小红书（xhs）

项	值
平台 id	`xhs`
别名	`xiaohongshu`、`rednote`
`item` 指	笔记
上游仓库	cv-cat/Spider_XHS
移植基线	master 上的 `ebb6c4f`，记录在 `src/platforms/xhs/UPSTREAM`
端	web ✓ · app ○ 规划中 · pc ○ 规划中
命令（web）	已实现 43 条（✓ 38 · ◐ 5），规划中 ○ 28 条

命令表由注册表生成，与 catbus platforms xhs 一致；选项以 catbus xhs <resource> <action> --help 为准。通用的命令语法、输出结构见 AGENTS.md 第 4 节。

方式	命令	说明
扫码（默认）	`catbus xhs auth login`	目前手机确认后常被要求人机验证（HTTP 471），报 `RISK_CONTROL`，见下方「已知限制」。建议先用 cookie 导入
短信	`catbus xhs auth login --method sms --phone <手机号>`	终端里会提示输入验证码；非交互环境分两步，第二步用 `--code <验证码>`
cookie	`catbus xhs auth login --method cookie --cookie @xhs-cookie.txt`	从 www.xiaohongshu.com 的 DevTools → Network 复制完整的 Cookie 请求头

cookie 里必须有 a1（长度 52）和 web_session。web_session 是 HttpOnly 的，Console 里的 document.cookie 拿不到，一定要从请求头复制。
子站点 creator（创作者中心）：item list、item publish、topic search、poi search、media upload 走创作者中心。catbus 用主站登录态自动换取创作者中心的会话，失效时自动重新换一次，一般不需要单独登录。换取失败时会报 AUTH_REQUIRED，hint 是 catbus xhs auth login --scope creator（支持扫码、短信，或 --method cookie 导入 creator.xiaohongshu.com 的 cookie）。
更完整的登录说明见登录指南。

支持的命令

✓ 上游已有，◐ 上游部分支持（限制写在说明里），○ 规划中（执行时返回 NOT_IMPLEMENTED，退出码 4）。表里没有的命令表示小红书没有这个概念，执行时报 UNSUPPORTED（退出码 2）。

auth

命令	状态	说明
`auth login`	✓	登录，方式见上文「登录」。
`auth status`	✓	在线校验登录态。
`auth logout`	✓	登出并删除本地凭证。
`auth list`	✓	本平台、本端的账号。
`auth use`	✓	切换当前账号。

user

命令	状态	说明
`user get`	✓	用户资料。
`user search`	✓	搜索用户。
`user items`	✓	用户发布的笔记。
`user likes`	✓	用户点赞的笔记。
`user collects`	✓	用户收藏的笔记。
`user following`	◐	关注列表。只支持 me。
`user followers`、`user follow`、`user unfollow`	○	规划中

item

命令	状态	说明
`item get`	✓	笔记详情。
`item search`	✓	搜索笔记。取值：`--sort` general / latest / popular / comments / collects；`--type` all / video / image；`--time` all / day / week / half_year。
`item list`	✓	我发布的笔记，带审核状态。走创作者中心（creator 子站点）。
`item media`	✓	笔记的媒体地址。
`item download`	✓	下载笔记的媒体。
`item publish`	✓	发布笔记。走创作者中心；`--image` 和 `--video` 二选一，视频要同时给 `--cover`；`--poi` 要和 `--poi-name` 一起用。取值：`--visibility` public / private。不支持 `--mention`、`--category`、`--price`。私有选项 `--poi-name`。
`item related`、`item like`、`item unlike`、`item collect`、`item uncollect`、`item delete`	○	规划中

comment

命令	状态	说明
`comment list`	◐	评论列表。`--product` 规划中。
`comment replies`	✓	评论的回复。
`comment add`、`comment delete`、`comment like`、`comment unlike`	○	规划中

feed

命令	状态	说明
`feed list`	◐	推荐 / 热门 / 关注流。following 规划中。取值：`--kind` recommend / following。
`feed categories`	✓	推荐流分类。

live

命令	状态	说明
`live get`	✓	直播间信息。
`live list`	✓	直播列表。
`live categories`	✓	直播分类。
`live listen`	✓	监听弹幕、礼物、进场等事件。持续输出 jsonl。
`live send`	◐	发弹幕，或用 `--gift` 送礼。`--gift` 规划中。送礼（`--gift`）需要确认。
`live gifts`	✓	礼物列表。
`live products`	✓	直播间商品。
`live search`、`live history`、`live like`、`live rank`、`live media`、`live start`、`live stop`	○	规划中

keyword

命令	状态	说明
`keyword suggest`	✓	搜索联想词。
`keyword hot`	✓	热搜词。

notice

命令	状态	说明
`notice list`	✓	通知列表。
`notice count`	✓	未读通知数。

msg

命令	状态	说明
`msg list`	✓	会话列表。含群聊，群聊会话 id 为 `group:<群 id>`。
`msg history`	✓	会话的消息记录。单聊传对方 id，群聊传 `group:<群 id>`。
`msg send`	✓	发私信。只支持文本；`--to <用户>` 或 `--conversation <对方 id>`，只能单聊。
`msg listen`	✓	监听新消息。持续输出 jsonl。
`msg read`	✓	标记会话已读。
`msg revoke`	✓	撤回消息。危险操作，需要确认。
`msg delete`	✓	删除会话。危险操作，需要确认。

media

命令	状态	说明
`media upload`	✓	上传媒体。走创作者中心。

folder

命令	状态	说明
`folder list`	◐	收藏夹列表。上游只有收藏夹列表（公开的收藏夹），没有收藏夹内容接口（`folder items` 规划中）。
`folder items`、`folder create`、`folder update`、`folder delete`	○	规划中

topic

命令	状态	说明
`topic search`	✓	搜索话题。走创作者中心。

poi

命令	状态	说明
`poi search`	✓	搜索地点。走创作者中心。

整组规划中

下面这些 resource 在本平台还没有已实现的命令，执行时都返回 NOT_IMPLEMENTED（退出码 4）。

resource	命令
`product`	`get`
`series`	`list` `items`
`history`	`list`

私有选项与平台扩展

命令	选项	说明
`item publish`	`--poi-name <名称>`，可配 `--poi <id>`	地点。小红书的地点只能按名称搜，所以 `--poi` 要和 `--poi-name` 一起用（取 id 相同的那个）；只给 `--poi-name` 时取名称完全相同的；都找不到时报 `USAGE` 并列出相近的地点。先用 `catbus xhs poi search <名称>` 查名称和 id

小红书没有扩展命令。定义见 AGENTS.md 4.7。

参数格式

参数	接受的形式
笔记 `<item>`	笔记链接 `https://www.xiaohongshu.com/explore/<id>?xsec_token=...`（也认 `/discovery/item/<id>`、`/user/profile/<uid>/<id>`）、分享短链 `xhslink.com/...`，或 24 位十六进制的笔记 ID
用户 `<user>`	主页链接 `https://www.xiaohongshu.com/user/profile/<id>?xsec_token=...`、分享短链、24 位十六进制的用户 ID，或 `me`
直播间 `<room>`	房间号（数字），或直播间链接 `.../livestream/<room_id>`
会话 `<conversation>`	单聊传对方的用户 ID；群聊传 `group:<群 id>`（`msg list` 输出的 `id`）

优先传链接：小红书取笔记详情、评论等要带 xsec_token，它只在链接里。只给纯 ID 时缺这个参数，很多接口会失败。catbus 输出的 url 都带 xsec_token，可以直接作为下一条命令的参数。

示例

# 导入 cookie（从文件读取，避免 cookie 出现在 shell 历史里）
catbus xhs auth login --method cookie --cookie @xhs-cookie.txt

# 搜索最新的笔记，取 20 条
catbus xhs item search 露营 --sort latest --limit 20

# 笔记详情、全部评论（jsonl，一行一条）
catbus xhs item get "<note_url>"
catbus xhs comment list "<note_url>" --all -o jsonl > comments.jsonl

# 某个用户发布的全部笔记
catbus xhs user items "<user_url>" --all -o jsonl > notes.jsonl

# 下载笔记的图片 / 视频
catbus xhs item download "<note_url>" --dir ./xhs

# 推荐流的分类，以及某个分类下的推荐
catbus xhs feed categories
catbus xhs feed list --category <category_id> --limit 30

# 发一篇仅自己可见的图文笔记（本地图片自动上传）
catbus xhs item publish --title 周末露营 --text @note.md --image 1.jpg --image 2.jpg --visibility private

# 监听直播间弹幕 10 分钟
catbus xhs live listen <room_id> --duration 10m > live.jsonl

已知限制

扫码登录被要求人机验证：手机确认后服务端返回 HTTP 471（verifytype 120），上游 Spider_XHS 同样失败。catbus 报 RISK_CONTROL（detail.kind 为 captcha），hint 提示改用 cookie 导入。cookie 导入实测可用。
评论接口间歇性要求人机验证：comment list 偶尔返回 HTTP 461（verifytype 124），请求越密越容易触发。报 RISK_CONTROL，error.hint 和 detail.verify_url 里是网页验证链接：在登录了同一账号的浏览器里打开、完成验证后再重试。不验证时有时几分钟自己恢复，也见过持续 8 小时以上的；批量翻页时放慢节奏。
字段恒为空：列表里的 stats.views（公开接口不返回播放量）、keyword hot 的 heat（热搜接口不给热度值）。
还没真机验证：msg send / read / revoke / delete、msg listen、live listen、live send。关注列表与群聊的字段名参考了第三方代码（上游没有样本）。
删不掉笔记：item delete 上游没有（○），发出去的笔记要在 App 里手动删除。测试发布请用 --visibility private。
视频发布要给封面：catbus 不解码视频，截不了首帧，--video 必须配 --cover。
蒲公英（达人）、千帆（分销）接口不提供：普通账号访问会被拒，而且被拒后评论等接口会要求人机验证。见 AGENTS.md 4.12。

11 KiB Raw Permalink Blame History Unescape Escape