catbus

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

catbus

catbus（猫巴士）是一个命令行工具，用同一套命令、同一种 JSON 调用 10 个平台的 web 端接口。stdout 只有 JSON，日志、提示、二维码都在 stderr。

先确认它能用：

catbus version

、

catbus doctor

。找不到

catbus

命令时告诉用户安装（npm 包

catbus-cli

，或从源码

npm link

），不要自己去装。

catbus (Cat Bus) is a command-line tool that uses the same set of commands and the same JSON format to call the web interfaces of 10 platforms. stdout contains only JSON, while logs, prompts, and QR codes go to stderr.

First verify that it works:

catbus version

catbus doctor

. If the

catbus

command cannot be found, tell the user how to install it (the npm package

catbus-cli

, or

npm link

from the source); do not install it yourself.

按任务读对应的文件

Read the relevant files for the task

这个文件只放总纲。动手前，按任务再读一两个文件，不需要全读：

任务	读
涉及某个平台	`platforms/<id>.md` ：能做什么、做不到什么、参数怎么传、有哪些坑
搜索、采集、导出、翻页、下载、跨平台对比	workflows/collect.md
发布、评论、点赞、收藏、关注、删除等写操作	workflows/write.md
直播弹幕监听、私信	workflows/live-msg.md
命令报错：未登录、风控、不支持、网络	workflows/errors.md
查某条命令的参数、选项、输出字段	reference/commands.md

This file contains only the overview. Before acting, read one or two additional files based on the task; there is no need to read all of them.

Task	Read
Involving a specific platform	`platforms/<id>.md` : what it can and cannot do, how to pass parameters, and common pitfalls
Searching, collecting, exporting, pagination, downloading, and cross-platform comparison	workflows/collect.md
Write operations such as publishing, commenting, liking, favoriting, following, and deleting	workflows/write.md
Live-stream chat monitoring and direct messages	workflows/live-msg.md
Command errors: not logged in, risk control, unsupported, or network issues	workflows/errors.md
Checking a command's parameters, options, and output fields	reference/commands.md

平台

Platforms

平台	id	别名	`item` 是	登录	文件
小红书	`xhs`	`xiaohongshu` `rednote`	笔记	cookie（扫码常被拦）	platforms/xhs.md
抖音	`douyin`	`dy`	作品	扫码	platforms/douyin.md
TikTok	`tiktok`	`tt`	视频	cookie / 会话 JSON	platforms/tiktok.md
B 站	`bilibili`	`bili` `b`	稿件	扫码	platforms/bilibili.md
快手	`kuaishou`	`ks`	作品	扫码	platforms/kuaishou.md
微博	`weibo`	`wb`	微博	cookie	platforms/weibo.md
闲鱼	`xianyu`	`goofish` `xy`	闲置商品	扫码	platforms/xianyu.md
淘宝	`taobao`	`tb`	商品	cookie	platforms/taobao.md
京东	`jd`	`jingdong`	商品 SKU	扫码	platforms/jd.md
X	`x`	`twitter`	推文	cookie	platforms/x.md

还不支持：Instagram、YouTube、Facebook、知乎、微信公众号、今日头条、得物、拼多多、美团、大众点评正在开发，现在执行会报「未知的平台」（

USAGE

）。用户问到时直接说还不支持，不要尝试调用，也不要拿别的平台凑数。

Platform	id	Aliases	What `item` represents	Login	File
RedNote	`xhs`	`xiaohongshu` `rednote`	Note	cookie (QR-code sign-in is often blocked)	platforms/xhs.md
Douyin	`douyin`	`dy`	Work	QR-code sign-in	platforms/douyin.md
TikTok	`tiktok`	`tt`	Video	cookie / session JSON	platforms/tiktok.md
Bilibili	`bilibili`	`bili` `b`	Submission	QR-code sign-in	platforms/bilibili.md
Kuaishou	`kuaishou`	`ks`	Work	QR-code sign-in	platforms/kuaishou.md
Weibo	`weibo`	`wb`	Post	cookie	platforms/weibo.md
Xianyu	`xianyu`	`goofish` `xy`	Listing	QR-code sign-in	platforms/xianyu.md
Taobao	`taobao`	`tb`	Product	cookie	platforms/taobao.md
JD	`jd`	`jingdong`	Product SKU	QR-code sign-in	platforms/jd.md
X	`x`	`twitter`	Post	cookie	platforms/x.md

Not yet supported: Instagram, YouTube, Facebook, Zhihu, WeChat Official Accounts, Toutiao, Dewu, Pinduoduo, Meituan, and Dianping are under development. Attempting to execute them now will result in an “Unknown platform” error (

USAGE

). When users ask about them, say directly that they are not supported; do not attempt to invoke them, and do not substitute another platform.

命令语法

Command syntax

catbus <platform> <resource> <action> [参数...] [选项...]

resource / action 用规范词，所有平台同名：笔记、视频、推文、商品一律叫
```
item
```
，搜索叫
```
search
```
，收藏夹叫
```
folder
```
，私信叫
```
msg
```
。
```
note
```
、
```
video
```
、
```
tweet
```
这类原生叫法会报
```
UNSUPPORTED
```
，
```
hint
```
里给出规范词。
参数接受 ID、URL（包括分享短链）、平台自然标识（B 站 BV 号、X 用户名）；用户参数还可以是
```
me
```
。输出对象都带
id
和
url
，直接当下一条命令的参数，小红书一定要传
```
url
```
。
以
```
-
```
开头的位置参数放在
```
--
```
之后。选项可以出现在任意位置。
```
-e app|pc
```
都还没实现（
```
NOT_IMPLEMENTED
```
），只用默认的 web 端。

catbus <platform> <resource> <action> [参数...] [选项...]

Resource and action must use canonical terms, and they are identical across all platforms: notes, videos, posts, and products are all called
```
item
```
; search is called
```
search
```
; favorites folders are called
```
folder
```
; and direct messages are called
```
msg
```
. Native terms such as
```
note
```
,
```
video
```
, or
```
tweet
```
will cause an
```
UNSUPPORTED
```
error, and the
```
hint
```
will provide the canonical term.
Parameters accept IDs, URLs (including shared short links), and native platform identifiers (Bilibili BV IDs and X usernames). The user parameter can also be
```
me
```
. Every output object includes
id
and
url
, which can be passed directly to the next command; RedNote always requires
```
url
```
.
Positional arguments beginning with
```
-
```
go after
```
--
```
. Options can appear anywhere.
```
-e app|pc
```
has not been implemented (
```
NOT_IMPLEMENTED
```
); use only the default web interface.

先查能力，再调用

Check capabilities before making a call

平台之间差别很大，调用前先查，不要猜：

bash

catbus platforms xhs              # JSON：每条命令的 status（implemented / planned）、auth、note
catbus xhs item search --help     # 参数、选项、筛选取值、登录要求、输出类型

```
status
```
为
```
planned
```
的命令会报
```
NOT_IMPLEMENTED
```
，不要调用；
```
note
```
写着限制（例如「只支持 me」），调用前看一眼。
筛选取值（
```
--sort
```
```
--type
```
```
--time
```
）每个平台不同，以
```
--help
```
为准。
平台文件里的「能做 / 做不到」是摘要，与
```
catbus platforms
```
冲突时以后者为准。

Capabilities vary significantly between platforms, so check before calling rather than guessing:

bash

catbus platforms xhs              # JSON: each command's status (implemented / planned), auth, and note
catbus xhs item search --help     # Parameters, options, filter values, login requirements, and output types

A command with a
```
planned
```
status will cause a
```
NOT_IMPLEMENTED
```
error; do not call it. The
```
note
```
field lists limitations, such as “only supports me,” so check it before invoking the command.
Filter values for
```
--sort
```
,
```
--type
```
, and
```
--time
```
differ between platforms; use
```
--help
```
as the source of truth.
The “Can do / Cannot do” section in a platform file is only a summary. If it conflicts with
```
catbus platforms
```
, the latter takes precedence.

信封与退出码

Envelope and exit codes

stdout 恰好一个信封（

-o jsonl

时每行一条

data

，摘要信封在 stderr 最后一行）：

json

{ "ok": true, "platform": "bilibili", "resource": "item", "action": "get", "account": "default",
  "data": {}, "page": null, "error": null }

失败时

ok

为 false、

error

为

{code, message, hint, detail}

。先读
error.hint
，它是下一步该执行的命令或做法。

退出码	code	一句话
0	—	成功
2	`USAGE` / `UNSUPPORTED` / `CONFIRM_REQUIRED`	参数错 / 平台没有 / 危险操作没确认
3	`AUTH_REQUIRED` / `AUTH_EXPIRED`	让用户登录
4	`NOT_IMPLEMENTED`	规划中，别重试
5	`RISK_CONTROL`	风控，停下，别重试
6	`NETWORK`	网络 / 代理
7	`UPSTREAM`	平台业务错误，原始码在 `detail`
1	`ERROR`	其他

每种错误怎么处理见 workflows/errors.md。

stdout contains exactly one envelope. When using

-o jsonl

, each line contains one

data

object, and the summary envelope is on the final line of stderr:

json

{ "ok": true, "platform": "bilibili", "resource": "item", "action": "get", "account": "default",
  "data": {}, "page": null, "error": null }

On failure,

ok

is false and

error

{code, message, hint, detail}

. Read
error.hint
first; it indicates the next command or action to take.

Exit code	code	One-line meaning
0	—	Success
2	`USAGE` / `UNSUPPORTED` / `CONFIRM_REQUIRED`	Invalid arguments / platform unavailable / dangerous operation not confirmed
3	`AUTH_REQUIRED` / `AUTH_EXPIRED`	Ask the user to log in
4	`NOT_IMPLEMENTED`	Planned; do not retry
5	`RISK_CONTROL`	Risk control triggered; stop and do not retry
6	`NETWORK`	Network / proxy issue
7	`UPSTREAM`	Platform business error; the original code is in `detail`
1	`ERROR`	Other error

See workflows/errors.md for how to handle each error.

红线

Hard rules

这些规则在任何任务里都成立：

登录交给用户。扫码要用户的手机，短信、密码、cookie 要用户本人提供。把
```
hint
```
里的登录命令给用户，让他在自己的终端执行；不要索要或保存密码、验证码、cookie，不要读取、打印或修改
```
~/.catbus/
```
里的凭证文件。
写操作先确认。发布、评论、点赞、关注、私信、删除会真实改变用户的账号。用户没有明确要求就不做；危险操作只在用户同意这一次之后才加
```
-y
```
。
发布默认仅自己可见（
```
--visibility private
```
），除非用户明确要公开。平台只支持公开时（闲鱼、X、B 站动态），先告诉用户会公开发出去。
不主动联系真人：不给别人发私信、评论、@、关注，除非用户给出了对象和内容。不批量发送。
风控就停：
```
RISK_CONTROL
```
不要循环重试，连续请求同一平台时留出间隔，不并发。
照实汇报：结果为空、字段为 null、命令不支持，都照实告诉用户，不编造数据。

These rules apply to every task:

Delegate login to the user. QR-code sign-in requires the user's phone, while SMS codes, passwords, and cookies must be provided by the user. Give the user the login command from the
```
hint
```
and have them run it in their own terminal. Do not request or store passwords, verification codes, or cookies, and do not read, print, or modify credential files under
```
~/.catbus/
```
.
Confirm write operations first. Publishing, commenting, liking, following, sending direct messages, and deleting will genuinely change the user's account. Do not perform them unless the user explicitly requests it; add
```
-y
```
to a dangerous operation only after the user approves that specific action.
Published content is private by default (
```
--visibility private
```
) unless the user explicitly wants it to be public. For platforms that only support public visibility, such as Xianyu, X, and Bilibili posts, first tell the user that the content will be published publicly.
Do not proactively contact people: Do not send direct messages, comments, @ mentions, or follow requests to others unless the user has provided both the target and the content. Do not send messages in bulk.
Stop when risk control is triggered: Do not retry in a loop after
```
RISK_CONTROL
```
. Leave an interval between consecutive requests to the same platform, and do not run them concurrently.
Report accurately: If the results are empty, fields are null, or a command is unsupported, report the situation honestly and do not fabricate data.