catbus/docs/examples/README.md

示例

展示脚本和 AI Agent 怎么组合 catbus：用 -o jsonl 接管道、按退出码分支、用 page.cursor 续翻、遇到风控停下。每个脚本开头都有完整的用法说明，不带参数运行会打印出来。

脚本	做什么	依赖
search-to-jsonl.sh	跨平台搜索同一个关键词，每个平台取 N 条，合并成一个 jsonl（每行加上 platform 字段）。默认搜索「item search 已实现、并且本机登录过」的平台；某个平台失败时跳过，平台之间 sleep	bash、jq
comments-export.sh	导出一条内容的全部评论到 jsonl。分批翻页，批与批之间把游标存到 <输出文件>.cursor；遇到 RISK_CONTROL / NETWORK 停下，再运行就从断点继续。REPLIES=1 时顺带导出评论的回复	bash、jq
user-items-backup.sh	备份一个用户发布的全部内容：user items --all 的元数据写成 items.jsonl，再逐条 item download --dir 下载媒体。已下载的记在 downloaded.txt，中断后续跑；平台还不支持下载时只备份元数据	bash、jq
live-to-file.sh	把直播间的弹幕、礼物、进场等事件 live listen --duration 一段时间写到文件；Ctrl-C 也能正常收尾，结束时按事件类型和礼物统计	bash（jq 可选，用于统计）
node-api.mjs	用 Node 的 child_process 调 catbus 的最小封装：解析信封，按退出码把错误分成 auth / usage / risk_control / network 等，带长连接的异步迭代器和风控重试。可以直接运行，也可以 import 到自己的代码里	Node

运行前

1. 装好 catbus 并登录要用的平台，见 快速上手 和 登录指南：

   catbus bilibili auth login
   catbus auth list        # 看看本机登录了哪些平台
   

2. 还没 npm link 时，用环境变量 CATBUS 指定命令，所有示例都认它：

   export CATBUS="node /path/to/catbus/dist/cli/main.js"
   

3. 脚本需要 jq（macOS：brew install jq；Debian / Ubuntu：apt install jq）。脚本在 macOS 自带的 bash 3.2 上也能跑。

例子

# 在已登录的平台上搜「露营」，每个平台 30 条
docs/examples/search-to-jsonl.sh 露营 30 camping.jsonl
jq -r '[.platform, .title, .url] | @tsv' camping.jsonl

# 导出一条 B 站稿件的全部评论；被风控拦下后过几分钟再运行同一条命令
docs/examples/comments-export.sh bilibili BV1xx411c7mD

# 备份自己在抖音发布的作品（元数据 + 媒体）
docs/examples/user-items-backup.sh douyin me ./douyin-backup

# 录 30 分钟 B 站直播弹幕
docs/examples/live-to-file.sh bilibili <room_id> 30m

# 在 Node 里调用
node docs/examples/node-api.mjs bilibili item search 猫 --limit 5

import { catbus, catbusStream, catbusWithRetry, CatbusError } from './node-api.mjs'

try {
  const { data: items, page } = await catbusWithRetry(['xhs', 'item', 'search', '露营', '--limit', '20'])
  console.log(items.map((i) => i.title), page)
} catch (err) {
  if (err instanceof CatbusError && err.kind === 'auth') console.error('先登录：', err.hint)
  else throw err
}

for await (const event of catbusStream(['bilibili', 'live', 'listen', '<room_id>', '--duration', '5m'])) {
  if (event.type === 'chat') console.log(event.user?.name, event.text)
}

写自己的脚本时

• 只解析 stdout：-o json（默认）时 stdout 恰好是一个信封；-o jsonl 时 stdout 每行一条 data，结束时的摘要信封（page、error）写在 stderr 的最后一行。帮助是 stdout 上唯一不是 JSON 的输出。
• 按退出码分支：3 登录（error.hint 就是登录命令）、5 风控（放慢、过一会儿再试）、6 网络、4 规划中、2 参数或平台不支持。完整的表见 AGENTS.md 6.4。
• 续翻用 page.cursor：游标是不透明字符串，可能以 - 开头，传的时候写成 --cursor=<值>。一次 --all 中途失败时拿不到游标，所以长任务按批调用、批与批之间保存游标（见 comments-export.sh）。
• 放慢节奏：翻页时 catbus 会在页与页之间自动等待；多条命令之间脚本自己 sleep。小红书的评论、快手的作品详情、京东的商品详情请求太密会被风控。
• 危险操作（删除、撤回、B 站投币 / 三连、直播送礼）在非交互环境里必须加 -y，否则报 CONFIRM_REQUIRED。
• 不要把 cookie 写进脚本或提交到仓库：登录态只在 ~/.catbus/，脚本里用 -a <账号名> 选择账号即可。