catbus/docs/guide/faq.md

常见问题

基本

catbus 和 cv-cat 的那些 Python 仓库是什么关系？

catbus 的能力来自 cv-cat 的 10 个开源仓库（Spider_XHS、DouYin_Spider、TiktokApis、BilibiliApis、KuaiShou-Spider、WeiboApis、XianYuApis、TaoBaoApis、JdApis、XApis）。catbus 把它们的请求构造、签名和解析逻辑用 TypeScript 重写，并用对拍测试保证同样的输入产出逐字节相同的请求。运行时不调用上游的 Python。

区别在于：catbus 是一个统一的命令行，10 个平台用同一套命令、参数和 JSON 输出；上游是各自独立的 Python 库。每个平台基于哪个上游 commit，记录在 src/platforms/<platform>/UPSTREAM。

需要装 Python 吗？

不需要。用户只需要 Node（^22.22.2 || ^24.15.0 || >=26.0.0），不需要 Python、C/C++ 编译器或其他系统依赖。Python 只在开发时用来生成对拍数据。

支持哪些系统？

• Windows：x64、arm64
• macOS：arm64（Apple Silicon）、x64（Intel）
• Linux：x64、arm64，glibc 和 musl（Alpine）都支持

CI 在这 8 个目标上跑安装和冒烟测试。原生依赖（HTTP 库、@napi-rs/canvas）都带预编译包，安装时不需要编译。

怎么安装？

npm i -g catbus-cli

主包叫 catbus-cli，npm 上的 catbus 是别人的库，不是这个项目。想改代码或跟进 master 时从源码安装，步骤见 快速上手。

模型包为什么这么大？

catbus 依赖两个模型包：

• @cv-cat/catbus-assets-jd：京东验证码（JCAP）的 onnx 模型，约 81 MB；
• @cv-cat/catbus-assets-ocr：验证码 OCR 模型（ddddocr 1.6.1 的检测、识别模型和字符集），约 34 MB，B 站极验点选在用。

模型是自动过验证码必需的。拆成单独的包是因为模型很少变，放在主包里的话每次发版都要重新上传 100 多 MB。它们是主包的普通依赖，安装 catbus-cli 时自动装上，不需要单独安装。catbus 的原则是开箱即用、装完即可离线使用，安装体积不是优先考虑的因素。

从源码安装时，模型文件不进 git，要用 npm run assets:jd、npm run assets:ocr 取回，脚本会校验 sha256。

catbus 会收集或上传我的数据吗？

不会。catbus 没有遥测，不收集、不上传任何数据。登录态只保存在本机的 ~/.catbus/（目录 0700、文件 0600），请求只发往你操作的那个平台（以及你配置的代理）。

登录

为什么什么都要登录？

各平台的 web 端不登录几乎看不到内容（搜索、详情、评论都会被登录墙拦住），所以 catbus 的 web 端除 auth 以外的命令都需要登录，未登录时直接报 AUTH_REQUIRED 并提示登录命令。游客态留给将来的 app 端。

tiktok / weibo / taobao / x 为什么不能扫码？

TikTok、微博、淘宝的上游仓库只实现了 cookie 登录；X 的上游有账密登录，但依赖 Castle 反自动化令牌，catbus 没有移植。所以这 4 个平台要从浏览器导入 cookie。

导入的 cookie 提示缺少字段或登录失败

多半是用 document.cookie 或浏览器的 Application 面板只复制了一部分。关键的登录 cookie（小红书的 web_session、B 站的 SESSDATA、抖音的 sessionid 等）是 HttpOnly 的，document.cookie 里没有。请从 DevTools → Network → 任一请求的 Request Headers 里复制完整的 Cookie，见 login.md。

小红书扫码后报 RISK_CONTROL

扫码确认后，小红书服务端可能要求做一次人机验证（HTTP 471）。这是平台风控，上游 Spider_XHS 同样失败，catbus 和上游都还不能自动通过。请按 hint 改用 cookie 导入：

catbus xhs auth login --method cookie --cookie @xhs-cookie.txt

cookie 导入后，创作者中心会用主站登录态自动换取，不需要再扫码。

抖音 / TikTok 只导入了 cookie，写操作报 AUTH_REQUIRED

• 抖音的写操作需要和 cookie 同一次登录的 bd-ticket-guard 凭证，扫码或短信登录会自动拿到；只导入 cookie 时 catbus 在本地拦下，不发请求。
• TikTok 的写操作需要浏览器 security-sdk 的 ticket-guard 数据，只能从浏览器会话 JSON 导入。

导入格式见 login.md。

抖音发布一直失败

已知问题：即使凭证齐全，create_v2 仍返回空响应，上游在新登录的会话上同样失败，原因在上游的设备档案没有被服务端接受，正在等上游修复。另外，缺少设备素材时点赞会导致登录态被踢。详见 抖音的已知限制。

使用

xhs 为什么要传 URL，不能只传 ID？

小红书取笔记详情要带 xsec_token，而它只出现在链接里。所以 xhs 请优先传完整的笔记 URL（https://www.xiaohongshu.com/explore/<id>?xsec_token=...）。catbus 输出的 xhs 对象，url 字段都带着 xsec_token，可以直接当下一条命令的参数：

url=$(catbus xhs item search 咖啡 | jq -r '.data[0].url')
catbus xhs item get "$url"
catbus xhs comment list "$url"

NOT_IMPLEMENTED 是什么？

退出码 4，表示这个能力是规划中的：

• 能力矩阵里标 ○ 的命令：平台有这个概念，但上游还没有实现，catbus 先占了位置；
• app 端、pc 端：目前所有平台都只有 web 端，-e app / -e pc 一律返回 NOT_IMPLEMENTED。

重试没有用。哪些命令可用，看 catbus <platform> --help（带 ○ 的是规划中）或 能力矩阵。

NOT_IMPLEMENTED 和 UNSUPPORTED 有什么区别？

• NOT_IMPLEMENTED（退出码 4）：平台有这个概念，只是还没做。
• UNSUPPORTED（退出码 2）：平台本身没有这个概念（矩阵里的 —），或者命令不在词表里，或者平台不支持这个筛选取值 / 登录方式。

用了平台原生叫法（note、video、tweet……）也会报 UNSUPPORTED，hint 里给出规范词：catbus 的命令一律用 item、comment、msg 这样的规范词，原生叫法不做别名。

遇到 RISK_CONTROL 怎么办？

RISK_CONTROL（退出码 5）表示平台要求验证码、限流或封禁，detail.kind 为 captcha / rate_limit / blocked。

• 不要连续重试：短时间内反复请求会让账号被标记得更久，严重时会被封号。停一段时间再试。
• 上游能自动通过的验证码，catbus 会自动尝试（例如快手的滑块、B 站登录时的极验点选、京东的 JCAP）；自动通过不了才报 RISK_CONTROL。
• 小红书的人机验证（HTTP 461 / 471）：error.hint 里有网页验证链接，在登录了同一账号的浏览器里打开、完成验证后再重试。不验证时有时几分钟自己恢复，也可能持续好几个小时；请求越紧凑越容易触发。
• 连续执行很多命令时，命令之间留出间隔，不要并发请求同一个平台；翻页时 catbus 已经按平台加了间隔。
• 用 --all 抓取大量数据风险最高，优先用 --limit。

各平台已知的风控问题见 各平台说明 里的「已知限制」。

为什么有的字段总是 null？

归一化类型的字段总是存在，取不到时为 null。有些字段是上游接口本来就不返回，例如 B 站 user get 的粉丝数等计数、抖音作品的 title（抖音只有描述，放在 text）、抖音和小红书列表里的播放量。各平台说明的「已知限制」里列出了这些字段。需要平台原始字段时用 --raw。

结果不完整但没有报错

个别命令有已知限制，写在注册表的 note 里，--help 的「说明」一行和能力矩阵里都能看到。例如：

• 微博 item search 只能取第一页；
• 京东 comment list 只有第一页，--limit N 在一次请求里取 N 条；
• B 站 danmaku list 只能拿到前 2 分钟的弹幕，超过 6 分钟的视频直接报 UPSTREAM（上游 bug）。

危险操作为什么报 CONFIRM_REQUIRED？

所有 delete、msg revoke、B 站的 item coin / item triple、live send --gift 执行前需要确认。在终端里会在 stderr 上问 y/N；在脚本或 Agent 里（非 TTY）必须加 -y，否则报 CONFIRM_REQUIRED（退出码 2）。

测试写操作时怎样避免影响别人？

发布时用 --visibility private（仅自己可见），点赞、收藏只对自己的内容做，不要给真实用户发私信。注意有的平台发布只支持公开（例如闲鱼发布会上架真实商品，X 只有 public），B 站动态也没有仅自己可见。另外不少平台没有 item delete（矩阵里是 ○），测试内容需要在 App 里手动删。

能不能不设代理直接用系统代理？

不能。catbus 不读取 HTTP_PROXY / HTTPS_PROXY 环境变量，也不用系统代理，代理只能通过 --proxy、<platform>.proxy、proxy 显式配置，见 configuration.md。

能给 Claude Code 等 AI Agent 用吗？

可以。stdout 只输出 JSON、错误带 code 和 hint、退出码固定，适合 Agent 调用。用 npx skills add cv-cat/catbus 把 catbus 技能 装进 Agent，它会按任务读对应平台和场景的说明。

反馈

发现平台接口变了怎么办？

请用「平台接口变了 / 风控」模板提 issue，最好附上上游仓库是否同样失败。catbus 的修复流程是先修到上游仓库，再按新 commit 同步移植、重新生成对拍数据。