工作流模型

OpenBBQ 提供两套互补接口：

Agent facade 是一句提示词生成字幕底稿的默认路径；
原子命令继续服务于专业编辑、诊断和显式手动流程。

唯一权威的下一步

Agent 只初始化一次：

openbbq --json agent init '<source>' --workspace workspaces/demo --to zh

之后持续请求下一步：

openbbq --json agent next --workspace workspaces/demo

agent next 只返回以下一种 action：

Action	Agent 职责
`run_command`	原样执行返回的 `argv`，并遵守 execution policy。
`review_source`	仅在仍有结构性 ASR blocker 时处理完整的有界批次。
`translate`	翻译所有 selected cue，并返回精确的 batch 与 policy hash。
`finish`	只运行一次 `openbbq agent finish`。
`done`	交付返回的产物、质量状态和告警。

语义响应通过以下命令原子应用：

openbbq --json agent apply --workspace workspaces/demo response.json

Lease 与有界批次

每个语义 action 都有持久化 lease，包含 selected ID、source hash、worksheet hash 与 policy hash。在 apply 前，重复调用 next 会返回同一个 lease。缺少 ID、额外 ID、过期内容或错误 policy 的响应都会被拒绝。

翻译批次最多包含 20 条 cue，并携带可复现的翻译 brief、相关 glossary 上下文与相邻 cue。相邻 cue 只用于消歧，内容必须留在选中的 cue ID 中。批次还会提供 generation_policy：驱动流程的 Agent 必须根据给定原文、上下文、glossary 和规则生成译文，并在 apply 时回传要求的 generation_mode。外部翻译服务和自动翻译脚本不属于这份约定。

机械命令执行

run_command 包含机器可读的执行指导。Fetch、原生 GPU 转录与 finish 通常需要在受限 sandbox 外的宿主环境执行。重复机械命令会等待当前阶段，并复用已经完成的新鲜产物，不会启动相互竞争的重复任务。

如果执行工具返回了 process 或 session ID，就持续轮询同一个进程直到它退出。暂时没有输出，或外层工具已经结束，都不代表可以重新运行同一条命令。

原文纠错与 glossary 学习

确定性检查会在翻译前修复已知结构性字幕问题。翻译时发现明确 ASR 错误，Agent 可以提交当前 cue 内的有界 source fix，并判断该修正是否可复用。

当局部短语与已有的定时参考字幕不一致时，cue 可能带有精简的 reference_evidence。它只是线索，不是权威原文。普通歧义应该留下 warning，不应触发网页搜索、第二次识别或猜测式改写。

OpenBBQ 会把发现记录到任务本地 glossary overlay。URL 来源没有显式 glossary 时， fetch 得到的作者元数据会绑定稳定的“作者+目标语言” glossary。可复用且无冲突的条目只在成功交付后发布；发布冲突不会阻塞视频。

Finish 与交付

agent finish 要求当前翻译证据完整，导出 out/zh.ass、烧录 out/zh-burned.mp4、运行交付门禁，并发布符合条件的 glossary 学习。产物仍然新鲜时，重复 finish 会幂等返回，不会再次烧录。横屏视频使用 fansub，竖屏视频使用 mobile。

自动结果报告 quality: "draft" 和 human_reviewed: false。通过 openbbq review 完成全部当前人工审核后，质量状态才会变为 human-reviewed。

Workspace 与恢复

所有状态都属于一个 workspace。manifest.json 记录机械阶段； .openbbq/agent-session.<lang>.json 记录 lease 与翻译证据。任务中断后，在同一 workspace 再次调用 agent next；不要猜测下一条命令，也不要创建第二个语义批次。

Facade 默认不运行视觉 QA，也不会自动选择 fansub-compact。专家原子命令见 CLI 参考。