与 Agent 协作
让 Claude Code、Codex 或脚本驱动 OpenBBQ——机器可读输出、随包 Skill 和操作守则。
OpenBBQ 天生适合被“驾驶”：你可以手动执行每条命令，也可以把烤夹交给 Claude Code、Codex 这样的 AI Agent，让它来烤。这一页讲清楚驾驶者与 CLI 之间的约定：输出如何保持机器可读、如何安装能教会 Agent 整个流程的随包 Skill，以及 Agent 需要遵守的规则。
默认路径：跟随 Agent facade
要从一句提示词得到字幕底稿，只初始化一次，然后让 agent next 决定每一步：
openbbq --json agent init '<source>' --workspace workspaces/demo --to zh
openbbq --json agent next --workspace workspaces/demo收到 run_command 时原样运行返回的 argv；收到 review_source 或 translate 时，
用 agent apply 提交完整响应；收到 finish 时运行它给出的收尾命令；收到 done 时
交付报告的产物。每个 action 成功后，再调用一次 agent next。
不要猜测下一条命令，也不要再创建一个翻译批次。当前 lease 会固定 selected ID 与内容
hash，所以重复调用 next 是安全的，不完整或过期的 apply 会被拒绝。翻译 action 还会
带上生成规则、glossary 上下文，以及需要参考的本地证据。完整协议见
工作流模型。
机器可读输出
JSON 是一种结构化文本格式，程序读起来很方便。把根级 --json 放在命令名之前，每条命令就只回答一个紧凑的 JSON 对象：
openbbq --json status --workspace workspaces/demo
openbbq --json export --workspace workspaces/demo --to zh --mode bilingual当输出不是去往交互式终端（TTY——也就是你敲命令的那个窗口）时，比如在 Codex 或 CI 里，OpenBBQ 会自动改用紧凑 JSON。但 Agent 仍应显式传 --json，把这份约定声明出来，而不是依赖自动检测。
给人类看的进度和长任务提示会写到 stderr（一条专门传消息的旁路）或工作区的 manifest 里，所以机器读的那一路始终保持可解析。
退出与错误行为
- 成功：输出一个结果对象，退出码为 0。
- 领域错误——命令听懂了，但事情没办成：输出结构化错误，带
error代码、上下文，通常还有一个fix。照fix做，不要解析给人看的文字，也不要自己编造恢复命令。 - CLI 用法错误（参数写错、缺参数）使用
usage代码。 - 未预期的错误使用
internal代码。
轮询长任务
fetch、transcribe 和 burn 可能要跑几分钟。它们会把阶段进度写进工作区的 manifest.json，所以另一个进程可以不打扰地旁观：
openbbq --json status --workspace workspaces/demo如果 running 阶段超过 60 秒没有心跳更新，status 会把它标记为 stale——意思是“去看看”，而不是“做完了“。
一键教会 Agent 整个流程
OpenBBQ 随包附带 Skill——一份写好的说明文件，Agent 读完就懂得整个字幕流程。一条命令装进 Agent 的技能目录：
openbbq skill install默认装进共享的 agents 目录 ~/.agents/skills/。也可以按产品选位置：
| 命令 | 安装位置 |
|---|---|
openbbq skill install（或 --agent agents) | ~/.agents/skills/ |
openbbq skill install --agent claude | ~/.claude/skills/ |
openbbq skill install --agent codex | ~/.codex/skills/ |
openbbq skill install --agent all | 所有支持的目标 |
用 --target PATH 指定自定义父目录；已经装过时用 --force 覆盖。
随包有两个 Skill:
openbbq-subtitles（默认）——从生肉到熟肉的完整流程。bilibili-cover-safe-area——把视频缩略图做成符合 B 站投稿版式的封面。
用 --name 选择：
openbbq skill install --name bilibili-cover-safe-area只想看看内容、不安装，直接打印：
openbbq skill show
openbbq skill show --language zh-CN
openbbq skill show --name bilibili-cover-safe-area --language en有边界的上下文
长视频意味着几百行字幕——Agent 一次记不住这么多。这些“审阅类“命令把内容分成小页（offset/limit）端上来，Agent 每次专注处理一小批：
openbbq asr batch——存疑的听写，一次几条；见听写与检查openbbq translate batch——等待翻译的字幕行；见翻译与审校openbbq glossary audit——术语审校；见术语表
Agent 操作守则
- 安装系统依赖、下载大模型、写入浏览器登录态之前，先问人。
- 保证
OPENBBQ_HOME和工作区路径可写。 - 翻译保持有界；手动分批时，每批之间跑
openbbq translate check。 - 除非确实要丢弃已有成果，否则不要用
translate init --force。 - 发布或烧录之前，先预览导出的字幕。