diff --git a/website/content/docs/getting-started/index.mdx b/website/content/docs/getting-started/index.mdx index 6b0e4ae..c4a7d7e 100644 --- a/website/content/docs/getting-started/index.mdx +++ b/website/content/docs/getting-started/index.mdx @@ -1,16 +1,16 @@ --- title: Getting Started -description: Install OpenBBQ, create a workspace, and understand the processing model. +description: Install OpenBBQ and run the default one-prompt Agent workflow. --- - Requirements, CLI installation, models, upgrades, and development setup. + Install the CLI, ASR backend, model, and packaged Agent skill. - A complete local-video workflow from source to bilingual ASS. + One prompt for either a URL or local video, through final delivery. - Workspaces, stage invalidation, status, artifacts, and reruns. + Agent actions, leases, workspaces, artifacts, and recovery. diff --git a/website/content/docs/getting-started/index.zh.mdx b/website/content/docs/getting-started/index.zh.mdx index f22d3e2..be8e6e0 100644 --- a/website/content/docs/getting-started/index.zh.mdx +++ b/website/content/docs/getting-started/index.zh.mdx @@ -1,16 +1,16 @@ --- title: 入门 -description: 安装 OpenBBQ、创建 workspace，并理解处理模型。 +description: 安装 OpenBBQ，并运行默认的一句话 Agent 工作流。 --- - 前置要求、CLI 安装、模型、升级和开发环境。 + 安装 CLI、ASR 后端、模型和随包 Agent Skill。 - 从本地视频到双语 ASS 的完整工作流。 + URL 或本地视频都用一句提示词完成交付。 - Workspace、阶段失效、状态、产物和重跑方式。 + Agent action、lease、workspace、产物与恢复方式。 diff --git a/website/content/docs/getting-started/installation.mdx b/website/content/docs/getting-started/installation.mdx index 84ee387..686b035 100644 --- a/website/content/docs/getting-started/installation.mdx +++ b/website/content/docs/getting-started/installation.mdx @@ -16,15 +16,24 @@ description: Install OpenBBQ and the dependencies required by your workflow. OpenBBQ is pre-alpha. The current workflow is developed primarily on macOS; Windows and Linux support is still on the roadmap. -## Install the CLI +## Install the CLI and Agent skill -Install the published package with the whisper.cpp backend and the local review UI: +Install the published package with the default whisper.cpp backend: ```bash -uv tool install 'openbbq[whispercpp,review]' +uv tool install 'openbbq[whispercpp]' +openbbq skill install --agent all ``` -If you do not need browser-based subtitle review, the `review` extra may be omitted. +The skill teaches supported Agents to follow the one authoritative +`agent next/apply/finish` workflow. Use `--agent codex`, `--agent claude`, or +the default shared `agents` target when only one installation is needed. + +Professional users who want the local browser review UI can include its extra: + +```bash +uv tool install --force 'openbbq[whispercpp,review]' +``` If the `openbbq` command is not found after installation, follow the PATH instruction printed by uv, then open a new shell. @@ -79,6 +88,7 @@ Downloads are resumable and stored under `~/.openbbq/models/whisper.cpp/` by def ```bash openbbq doctor +openbbq --version openbbq --help ``` @@ -88,9 +98,11 @@ For hard-subtitle workflows, confirm that `ffmpeg subtitle filters` reports both ```bash uv tool upgrade openbbq +openbbq skill install --agent all --force +openbbq doctor ``` -To change extras or repair the installation: +To change extras or repair the CLI installation: ```bash uv tool install --force 'openbbq[whispercpp,review]' diff --git a/website/content/docs/getting-started/installation.zh.mdx b/website/content/docs/getting-started/installation.zh.mdx index a629fbf..2856d8f 100644 --- a/website/content/docs/getting-started/installation.zh.mdx +++ b/website/content/docs/getting-started/installation.zh.mdx @@ -16,15 +16,24 @@ description: 安装 OpenBBQ，以及当前工作流需要的依赖。 OpenBBQ 仍处于 pre-alpha 阶段，当前工作流主要在 macOS 上开发；Windows 和 Linux 支持仍在路线图中。 -## 安装 CLI +## 安装 CLI 与 Agent Skill -安装发布包、whisper.cpp 后端和本地审核界面： +安装发布包和默认 whisper.cpp 后端： ```bash -uv tool install 'openbbq[whispercpp,review]' +uv tool install 'openbbq[whispercpp]' +openbbq skill install --agent all ``` -如果不需要浏览器字幕审核，可以省略 `review` extra。 +Skill 会指导受支持的 Agent 遵循唯一权威的 `agent next/apply/finish` 工作流。只需 +安装一个目标时，可使用 `--agent codex`、`--agent claude`，或默认共享的 `agents` +目标。 + +专业用户需要本地浏览器审核界面时，再加入对应 extra： + +```bash +uv tool install --force 'openbbq[whispercpp,review]' +``` 如果安装后找不到 `openbbq`，按 uv 输出的提示配置 PATH，然后打开新的 shell。 @@ -79,6 +88,7 @@ openbbq models pull large-v3-turbo ```bash openbbq doctor +openbbq --version openbbq --help ``` @@ -88,9 +98,11 @@ openbbq --help ```bash uv tool upgrade openbbq +openbbq skill install --agent all --force +openbbq doctor ``` -修改 extra 或修复安装： +修改 extra 或修复 CLI 安装： ```bash uv tool install --force 'openbbq[whispercpp,review]' diff --git a/website/content/docs/getting-started/quickstart.mdx b/website/content/docs/getting-started/quickstart.mdx index 7094a2a..0e29f4e 100644 --- a/website/content/docs/getting-started/quickstart.mdx +++ b/website/content/docs/getting-started/quickstart.mdx @@ -1,141 +1,97 @@ --- title: Quickstart -description: Create bilingual subtitles from a local video, one explicit stage at a time. +description: Create an editable bilingual subtitle draft and hard-subtitled video with one Agent prompt. --- -This guide uses an English local video and produces Chinese-over-English ASS subtitles. Replace paths and language codes to match your material. +This is the recommended path for both online videos and local files. OpenBBQ +handles workflow state and validation; your Agent handles the semantic +translation. -## 1. Check the environment +## 1. Check the installation ```bash +openbbq --version openbbq doctor openbbq models list ``` -If you do not have a cached model yet: +Install a production ASR model if one is not already cached: ```bash openbbq models pull large-v3-turbo ``` -## 2. Create a workspace +Make sure the packaged skill is current: ```bash -openbbq init --workspace workspaces/demo /path/to/video.mp4 +openbbq skill install --agent all --force ``` -`init` records the source and creates `workspaces/demo/manifest.json`. It does not copy or process the video. +## 2. Send one prompt -Move into the workspace so later commands can discover it automatically: +Give your Agent a URL: -```bash -cd workspaces/demo -openbbq status -``` - -You can stay elsewhere and pass `--workspace workspaces/demo` to every command instead. - -## 3. Normalize the audio - -```bash -openbbq extract-audio -``` - -This writes `media/audio.16k.wav`, a 16 kHz mono WAV suitable for ASR. - -## 4. Transcribe - -```bash -openbbq transcribe --model large-v3-turbo --language en --gpu -``` - -The result is `transcript.json`. `--gpu` is the default; use `--cpu` if the native backend cannot use the available accelerator or fails in a restricted environment. - -If the model name is missing from the cache, either pull it first or opt into automatic download: - -```bash -openbbq transcribe --model large-v3-turbo --language en --auto-download -``` - -## 5. Build subtitle cues - -```bash -openbbq segment -``` - -This deterministically converts the transcript into `cues.json`, using a language profile for timing, characters per line, and characters per second. The result reports any over-CPS or over-width cues for review. - -## 6. Create a translation worksheet +> Make this video into a bilingual Chinese-English subtitled video: +> https://www.youtube.com/watch?v=... -```bash -openbbq translate init zh -``` +Or a local path: -Open `translation.zh.json`. Every item has a stable cue `id`, source text, timing information, translation budget, and a `target` field to fill. +> Make `/path/to/video.mp4` into a bilingual Chinese-English subtitled video. -For a small project, edit the `target` fields directly. For repeatable batches, create a JSON object: +You do not need to describe download, ASR, batching, glossary maintenance, +subtitle export, or burning. The Agent skill supplies those instructions. -```json -{ - "1": "第一句译文", - "2": "第二句译文" -} -``` +## 3. Let the Agent finish -Save it as `targets.json`, then merge it: +The normal run is: -```bash -openbbq translate apply zh targets.json -openbbq translate check zh +```text +fetch (URL only) -> extract audio -> transcribe -> validate/segment + -> translate in batches of at most 20 cues + -> export ASS -> burn once -> delivery check -> done ``` -`apply` is repeatable. `check` reports missing cues, translations over budget, and glossary term warnings. - -## 7. Export bilingual ASS - -```bash -openbbq export --to zh --mode bilingual --format ass --ass-preset fansub -``` +OpenBBQ returns one authoritative next action at a time. Mechanical actions +include exact command arguments and an execution policy. GPU transcription, +authenticated fetches, and final burning may need to run outside a restricted +sandbox. The Agent should not silently replace an available host GPU with CPU. -The default output is `out/zh.ass`. Bilingual mode renders the target language above the source language. +Translation batches include the target-language rules, title and author, +neighbor context, and matching glossary terms. If a translation reveals an +obvious ASR error, the Agent can submit a cue-scoped source fix. Reusable fixes +become glossary candidates and are published safely after successful delivery. -Preview the ASS file in a compatible player before burning it into a video. +## 4. Receive the outputs -## 8. Burn subtitles (optional) +A completed `done` response returns: -```bash -openbbq burn -``` +- `out/zh.ass`: editable bilingual ASS subtitles; +- `out/zh-burned.mp4`: the hard-subtitled video; +- `quality: "draft"` unless a complete current human review exists; +- `human_reviewed: false` for the normal automatic path; +- any non-blocking quality or glossary publication warnings. -`burn` uses the last exported ASS artifact and creates `out/zh-burned.mp4`. It requires a video source and FFmpeg with libass filters. +The default workflow exports and burns once. It does not run visual QA or +automatically switch to `fansub-compact`. -## Inspect progress at any time + + The automatic result is intended as a useful 70–80 point first draft. It + should remain aligned and structurally valid, but it is not a promise that + every cue has been professionally verified. + -```bash -openbbq status -``` +## Continue with professional editing -For scripts or agents: +Open the same workspace in the optional browser editor: ```bash -openbbq --json status +openbbq review --workspace /path/to/workspace --to zh ``` -Long-running commands update `manifest.json`; another process can poll `status` without parsing progress bars. - -## Final workspace - -```text -workspaces/demo/ -├── manifest.json -├── media/ -│ └── audio.16k.wav -├── transcript.json -├── cues.json -├── translation.zh.json -└── out/ - ├── zh.ass - └── zh-burned.mp4 -``` +You can also import `out/zh.ass` into Aegisub or an NLE. Human edits are +authoritative; do not rerun the automatic Agent workflow over completed manual +work. -Next, see [Local files and online video](/en/docs/guides/sources) for URL sources or [Export and burn](/en/docs/guides/export-and-burn) for SRT, ASS modes, and presets. +For authentication and local-file details, see [Local files and online +video](/en/docs/guides/sources). Agent implementers can read [Agents and +JSON](/en/docs/guides/agents). diff --git a/website/content/docs/getting-started/quickstart.zh.mdx b/website/content/docs/getting-started/quickstart.zh.mdx index c7ee1a2..c840f0b 100644 --- a/website/content/docs/getting-started/quickstart.zh.mdx +++ b/website/content/docs/getting-started/quickstart.zh.mdx @@ -1,141 +1,89 @@ --- title: 快速开始 -description: 按显式阶段从本地视频制作双语字幕。 +description: 用一句 Agent 提示词生成可编辑的双语字幕底稿和烧录后的视频。 --- -本指南以英文的本地视频为例，输出“中文在上、英文在下”的 ASS 双语字幕。请根据素材替换路径和语言代码。 +这是在线 URL 与本地文件都推荐使用的默认路径。OpenBBQ 负责工作流状态和确定性校验， +Agent 负责语义翻译。 -## 1. 检查环境 +## 1. 检查安装 ```bash +openbbq --version openbbq doctor openbbq models list ``` -如果还没有缓存模型： +尚未缓存正式字幕模型时，先下载： ```bash openbbq models pull large-v3-turbo ``` -## 2. 创建 workspace +确保随包 Skill 为最新版： ```bash -openbbq init --workspace workspaces/demo /path/to/video.mp4 +openbbq skill install --agent all --force ``` -`init` 只记录来源并创建 `workspaces/demo/manifest.json`，不会复制或处理视频。 +## 2. 发送一句提示词 -进入 workspace 后，后续命令可以自动向上查找它： +在线视频： -```bash -cd workspaces/demo -openbbq status -``` - -也可以留在其他目录，并在每个命令中传 `--workspace workspaces/demo`。 - -## 3. 标准化音频 - -```bash -openbbq extract-audio -``` - -命令会生成 `media/audio.16k.wav`，即适合 ASR 的 16 kHz 单声道 WAV。 - -## 4. 转录 - -```bash -openbbq transcribe --model large-v3-turbo --language en --gpu -``` - -结果写入 `transcript.json`。`--gpu` 是默认选项；如果原生后端无法使用当前加速器，或在受限环境中失败，请改用 `--cpu`。 - -模型不在缓存中时，可以先 pull，也可以明确允许自动下载： - -```bash -openbbq transcribe --model large-v3-turbo --language en --auto-download -``` - -## 5. 生成字幕 cue - -```bash -openbbq segment -``` - -该命令根据对应语言的时长、每行字符数和 CPS 配置，将 transcript 确定性地转换为 `cues.json`。输出会报告需要复查的 over-CPS 和 over-width cue。 - -## 6. 创建翻译工作表 +> 帮我把这个视频制作成中英双语字幕视频：https://www.youtube.com/watch?v=... -```bash -openbbq translate init zh -``` +本地文件： -打开 `translation.zh.json`。每个项目都有稳定的 cue `id`、原文、时间信息、翻译长度预算，以及待填写的 `target`。 +> 帮我把 `/path/to/video.mp4` 制作成中英双语字幕视频。 -小项目可以直接编辑 `target`；需要可重复的分批处理时，创建一个 JSON 对象： +提示词中不需要解释下载、ASR、分批翻译、glossary 维护、字幕导出或烧录步骤；这些规则 +由 Agent Skill 提供。 -```json -{ - "1": "第一句译文", - "2": "第二句译文" -} -``` +## 3. 让 Agent 完成任务 -保存为 `targets.json`，然后合并并检查： +正常流程如下： -```bash -openbbq translate apply zh targets.json -openbbq translate check zh +```text +fetch（仅 URL）-> 抽取音频 -> 转录 -> 校验/分段 + -> 每批不超过 20 条 cue 的翻译 + -> 导出 ASS -> 烧录一次 -> 交付检查 -> done ``` -`apply` 可以重复执行；`check` 会报告缺失 cue、超预算译文和术语警告。 - -## 7. 导出双语 ASS - -```bash -openbbq export --to zh --mode bilingual --format ass --ass-preset fansub -``` +OpenBBQ 每次只返回一个权威的下一步。机械 action 会提供精确 argv 和执行策略。GPU +转录、带登录态的 fetch 与最终烧录可能需要在受限 sandbox 外运行；Agent 不应在宿主机 +GPU 可用时擅自改用 CPU。 -默认输出为 `out/zh.ass`。双语模式会把译文放在原文上方。 +翻译批次会携带目标语言规则、标题与作者、相邻上下文和命中的 glossary 术语。翻译时 +发现明确 ASR 错误，Agent 可以提交 cue-scoped source fix；可复用的修正会成为 +glossary candidate，并在成功交付后安全发布。 -烧录前，请先用支持 ASS 的播放器预览字幕文件。 +## 4. 获取产物 -## 8. 烧录字幕（可选） +完成后的 `done` 响应返回： -```bash -openbbq burn -``` +- `out/zh.ass`：可编辑的双语 ASS 字幕； +- `out/zh-burned.mp4`：烧录后的视频； +- 默认自动路径的 `quality: "draft"`； +- 默认自动路径的 `human_reviewed: false`； +- 非阻塞的质量提示或 glossary 发布告警。 -`burn` 会使用最近一次导出的 ASS 产物，创建 `out/zh-burned.mp4`。该步骤要求来源是视频，并且 FFmpeg 支持 libass filter。 +默认流程只导出和烧录一次，不运行视觉 QA，也不会自动改用 `fansub-compact`。 -## 随时检查进度 + + 自动结果定位为可用的 70–80 分底稿。它应保持结构和 cue 对齐，但不代表每条字幕都 + 经过专业人工确认。 + -```bash -openbbq status -``` +## 继续专业精修 -脚本或 Agent 使用： +可以在同一个 workspace 中打开可选的浏览器编辑器： ```bash -openbbq --json status +openbbq review --workspace /path/to/workspace --to zh ``` -长任务会持续更新 `manifest.json`，其他进程可以轮询 `status`，不需要解析进度条。 - -## 最终 workspace - -```text -workspaces/demo/ -├── manifest.json -├── media/ -│ └── audio.16k.wav -├── transcript.json -├── cues.json -├── translation.zh.json -└── out/ - ├── zh.ass - └── zh-burned.mp4 -``` +也可以把 `out/zh.ass` 导入 Aegisub 或剪辑软件。人工修改具有最高权威，不要让自动 +Agent 流程覆盖已经完成的人工工作。 -URL 来源请继续阅读[本地文件与在线视频](/zh/docs/guides/sources)；SRT、ASS 模式和预设见[导出与烧录](/zh/docs/guides/export-and-burn)。 +登录与本地文件细节见[本地文件与在线视频](/zh/docs/guides/sources)；Agent 实现细节见 +[Agent 与 JSON](/zh/docs/guides/agents)。 diff --git a/website/content/docs/getting-started/workflow.mdx b/website/content/docs/getting-started/workflow.mdx index 54a5a37..d3ea2cf 100644 --- a/website/content/docs/getting-started/workflow.mdx +++ b/website/content/docs/getting-started/workflow.mdx @@ -1,90 +1,92 @@ --- title: Workflow Model -description: Understand workspaces, stage state, dependencies, and safe reruns. +description: Understand the Agent facade, actions, leases, workspaces, and safe recovery. --- -OpenBBQ exposes separate commands instead of hiding the process behind one fixed pipeline. A human or Agent can inspect each artifact, make semantic edits, and choose the next operation. +OpenBBQ has two complementary interfaces: -## Workspaces +- the Agent facade is the default for one-prompt subtitle drafts; +- atomic commands remain available for professional editing, diagnosis, and + explicit manual workflows. -A workspace is a directory containing an OpenBBQ `manifest.json`. `openbbq init` creates it and records the source: +## One authoritative next action + +An Agent initializes once: ```bash -openbbq init --workspace workspaces/demo /path/to/video.mp4 +openbbq --json agent init '' --workspace workspaces/demo --to zh ``` -Most commands resolve the workspace in this order: - -1. The directory passed with `--workspace` or `-w`. -2. The current directory, then each parent directory. -3. A structured `no_workspace` error when no OpenBBQ manifest is found. - -This allows commands to run from anywhere inside a workspace tree. - -## Sources +It then repeatedly asks for the next action: -`init` recognizes three source types: - -| Source | Examples | Required acquisition step | -| --- | --- | --- | -| URL | `https://www.youtube.com/watch?v=...` | Run `fetch` first | -| Local video | `.mp4`, `.mkv`, `.mov`, `.webm`, and others | Skip `fetch` | -| Local audio | `.wav`, `.mp3`, `.m4a`, `.flac`, and others | Skip `fetch`; `burn` is unavailable | - -Local paths are resolved to absolute paths. The source file is used in place rather than copied into the workspace. +```bash +openbbq --json agent next --workspace workspaces/demo +``` -## Stages and artifacts +`agent next` returns one of these actions: -The manifest is a work log, not a prefilled checklist. A stage appears only after its command runs. +| Action | Agent responsibility | +| --- | --- | +| `run_command` | Execute the returned `argv` exactly and obey its execution policy. | +| `review_source` | Resolve the complete bounded batch only when a structural ASR blocker remains. | +| `translate` | Translate every selected cue and return the exact batch and policy hashes. | +| `finish` | Run `openbbq agent finish` once. | +| `done` | Deliver the returned artifacts, quality state, and warnings. | -| Stage | Command | Main artifact | -| --- | --- | --- | -| fetch | `openbbq fetch` | downloaded media under `media/` | -| extract_audio | `openbbq extract-audio` | `media/audio.16k.wav` | -| transcribe | `openbbq transcribe` | `transcript.json` | -| segment | `openbbq segment` | `cues.json` | -| translate | `openbbq translate ...` | `translation..json` | -| review | `openbbq review` | `review..json` (or `review.source.json`), synchronized cue and worksheet edits | -| export | `openbbq export` | subtitle under `out/` | -| burn | `openbbq burn` | hard-subtitled MP4 under `out/` | +Semantic responses are applied atomically: -Stages can be `running`, `done`, `failed`, or `pending`. Long tasks include a progress heartbeat. `status` marks a running stage as stale when it has not updated for more than 60 seconds. +```bash +openbbq --json agent apply --workspace workspaces/demo response.json +``` -## Rerunning upstream stages +## Leases and bounded batches -When an upstream stage starts or completes, later recorded stages are changed to `pending`. For example, rerunning `transcribe` invalidates segment, translate, review, export, and burn state because their artifacts may no longer match the new transcript. +Every semantic action has a persistent lease containing its selected ids, +source hash, worksheet hash, and policy hash. Until the response is applied, +repeated `next` calls return the same lease. An apply is rejected when ids are +missing, extra, stale, or bound to the wrong policy. -After segmentation and optional translation, run `openbbq review --workspace PATH`. The local browser editor writes source text, translations, and cue timing back to their canonical workspace files. Export is blocked until the selected review scope is complete; `--allow-unreviewed` is an explicit escape hatch for draft output. +Translation batches contain at most 20 cues. The active batch includes a +reproducible translation brief, relevant glossary context, and neighboring cues +for disambiguation. Neighbors are context only; content must remain aligned to +the selected cue ids. -OpenBBQ does not automatically delete edited files. Review or regenerate downstream artifacts explicitly. +## Mechanical command execution - - `openbbq translate init --force` overwrites the worksheet and discards filled targets. Without `--force`, OpenBBQ refuses to replace an existing worksheet. - +`run_command` includes machine-readable execution guidance. Fetch, native GPU +transcription, and finish commonly require host execution outside a restricted +sandbox. Repeated mechanical commands wait for the active stage and reuse its +fresh completed artifact instead of starting competing work. -## Human and machine output +## Source correction and glossary learning -Interactive terminals receive Rich tables and progress bars. `--json`, CI, and other non-TTY environments receive one compact JSON object on stdout: +Deterministic checks repair known structural caption problems before +translation. If translation reveals an obvious ASR mistake, the Agent may +submit a bounded source fix for the current cue. It also marks whether the fix +is reusable. -```bash -openbbq --json status --workspace workspaces/demo -``` +OpenBBQ records that discovery in the task-local glossary overlay. For URL +sources without an explicit glossary, fetched author metadata selects a stable +author-and-target glossary. Reusable non-conflicting terms publish only after +successful delivery; publication conflicts do not block the video. -The root `--json` flag must appear before the command name. Successful and failed commands use different exit codes, making the output suitable for agents and scripts. +## Finish and delivery -## Global OpenBBQ data +`agent finish` requires current translation evidence, exports `out/zh.ass`, +burns `out/zh-burned.mp4`, runs the delivery gate, and publishes eligible +glossary learning. Fresh completed artifacts make finish idempotent. -Workspace artifacts belong to one media project. Shared data is stored under `OPENBBQ_HOME`, defaulting to `~/.openbbq`: +The automatic result reports `quality: "draft"` and +`human_reviewed: false`. A complete current review made with `openbbq review` +changes the quality to `human-reviewed`. -```text -~/.openbbq/ -├── auth/ # saved site sessions -├── glossaries/ # named glossary JSON files -└── models/ # ASR model cache -``` +## Workspaces and recovery -Set a different writable location when running in a restricted environment: +All state belongs to one workspace. `manifest.json` records mechanical stages; +`.openbbq/agent-session..json` records leases and translation evidence. +If a task is interrupted, call `agent next` again in the same workspace. Do not +guess the next command or create a second semantic batch. -```bash -OPENBBQ_HOME=/path/to/openbbq-home openbbq doctor -``` +The facade does not run visual QA and does not automatically choose +`fansub-compact`. Expert atomic commands are documented in the [CLI +reference](/en/docs/reference/cli). diff --git a/website/content/docs/getting-started/workflow.zh.mdx b/website/content/docs/getting-started/workflow.zh.mdx index b4b42d9..d657b41 100644 --- a/website/content/docs/getting-started/workflow.zh.mdx +++ b/website/content/docs/getting-started/workflow.zh.mdx @@ -1,90 +1,81 @@ --- title: 工作流模型 -description: 理解 workspace、阶段状态、依赖关系和安全重跑。 +description: 理解 Agent facade、action、lease、workspace 与安全恢复。 --- -OpenBBQ 将处理过程拆成独立命令，而不是隐藏在一条固定管线中。人或 Agent 可以检查每个产物、进行语义编辑，再决定下一步操作。 +OpenBBQ 提供两套互补接口： -## Workspace +- Agent facade 是一句提示词生成字幕底稿的默认路径； +- 原子命令继续服务于专业编辑、诊断和显式手动流程。 -Workspace 是包含 OpenBBQ `manifest.json` 的目录。`openbbq init` 会创建它并记录来源： +## 唯一权威的下一步 + +Agent 只初始化一次： ```bash -openbbq init --workspace workspaces/demo /path/to/video.mp4 +openbbq --json agent init '' --workspace workspaces/demo --to zh ``` -大多数命令按以下顺序解析 workspace： - -1. `--workspace` 或 `-w` 显式指定的目录。 -2. 当前目录，然后逐级向上查找。 -3. 找不到 OpenBBQ manifest 时返回结构化 `no_workspace` 错误。 - -因此可以在 workspace 目录树内的任何位置执行命令。 - -## 来源类型 +之后持续请求下一步： -`init` 识别三种来源： - -| 来源 | 示例 | 获取步骤 | -| --- | --- | --- | -| URL | `https://www.youtube.com/watch?v=...` | 必须先运行 `fetch` | -| 本地视频 | `.mp4`、`.mkv`、`.mov`、`.webm` 等 | 跳过 `fetch` | -| 本地音频 | `.wav`、`.mp3`、`.m4a`、`.flac` 等 | 跳过 `fetch`；不能 `burn` | - -本地路径会解析为绝对路径。OpenBBQ 会直接使用源文件，不会把它复制进 workspace。 +```bash +openbbq --json agent next --workspace workspaces/demo +``` -## 阶段与产物 +`agent next` 只返回以下一种 action： -Manifest 是工作日志，而不是预先填好的检查表。只有执行过命令，阶段才会出现。 +| Action | Agent 职责 | +| --- | --- | +| `run_command` | 原样执行返回的 `argv`，并遵守 execution policy。 | +| `review_source` | 仅在仍有结构性 ASR blocker 时处理完整的有界批次。 | +| `translate` | 翻译所有 selected cue，并返回精确的 batch 与 policy hash。 | +| `finish` | 只运行一次 `openbbq agent finish`。 | +| `done` | 交付返回的产物、质量状态和告警。 | -| 阶段 | 命令 | 主要产物 | -| --- | --- | --- | -| fetch | `openbbq fetch` | `media/` 下的下载媒体 | -| extract_audio | `openbbq extract-audio` | `media/audio.16k.wav` | -| transcribe | `openbbq transcribe` | `transcript.json` | -| segment | `openbbq segment` | `cues.json` | -| translate | `openbbq translate ...` | `translation..json` | -| review | `openbbq review` | `review..json`（或 `review.source.json`），并同步 cue 与翻译工作表修改 | -| export | `openbbq export` | `out/` 下的字幕 | -| burn | `openbbq burn` | `out/` 下的硬字幕 MP4 | +语义响应通过以下命令原子应用： -阶段状态包括 `running`、`done`、`failed` 和 `pending`。长任务会写入进度心跳；running 阶段超过 60 秒没有更新时，`status` 会将它标记为 stale。 +```bash +openbbq --json agent apply --workspace workspaces/demo response.json +``` -## 重跑上游阶段 +## Lease 与有界批次 -上游阶段开始或完成时，已经记录的后续阶段会变成 `pending`。例如重跑 `transcribe` 会使 segment、translate、review、export 和 burn 状态失效，因为它们可能已经与新 transcript 不一致。 +每个语义 action 都有持久化 lease，包含 selected ID、source hash、worksheet hash 与 +policy hash。在 apply 前，重复调用 `next` 会返回同一个 lease。缺少 ID、额外 ID、 +过期内容或错误 policy 的响应都会被拒绝。 -完成分段和可选翻译后，运行 `openbbq review --workspace PATH`。本地浏览器编辑器会把原文、译文和 cue 时间同步写回工作区的规范文件。所选审核范围完成前 export 会被阻止；如需草稿输出，可显式使用 `--allow-unreviewed`。 +翻译批次最多包含 20 条 cue，并携带可复现的翻译 brief、相关 glossary 上下文与相邻 +cue。相邻 cue 只用于消歧，内容必须留在选中的 cue ID 中。 -OpenBBQ 不会自动删除人工编辑过的文件，请显式检查或重新生成下游产物。 +## 机械命令执行 - - `openbbq translate init --force` 会覆盖工作表并丢弃已经填写的 target。不传 `--force` 时，OpenBBQ 会拒绝替换现有工作表。 - +`run_command` 包含机器可读的执行指导。Fetch、原生 GPU 转录与 finish 通常需要在受限 +sandbox 外的宿主环境执行。重复机械命令会等待当前阶段，并复用已经完成的新鲜产物， +不会启动相互竞争的重复任务。 -## 人类与机器输出 +## 原文纠错与 glossary 学习 -交互式终端会显示 Rich 表格和进度条；`--json`、CI 和其他非 TTY 环境会在 stdout 输出一个紧凑 JSON 对象： +确定性检查会在翻译前修复已知结构性字幕问题。翻译时发现明确 ASR 错误，Agent 可以 +提交当前 cue 内的有界 source fix，并判断该修正是否可复用。 -```bash -openbbq --json status --workspace workspaces/demo -``` +OpenBBQ 会把发现记录到任务本地 glossary overlay。URL 来源没有显式 glossary 时， +fetch 得到的作者元数据会绑定稳定的“作者+目标语言” glossary。可复用且无冲突的条目 +只在成功交付后发布；发布冲突不会阻塞视频。 -根级 `--json` 必须放在命令名称之前。成功和失败使用不同退出码，适合 Agent 和脚本处理。 +## Finish 与交付 -## OpenBBQ 全局数据 +`agent finish` 要求当前翻译证据完整，导出 `out/zh.ass`、烧录 +`out/zh-burned.mp4`、运行交付门禁，并发布符合条件的 glossary 学习。产物仍然新鲜 +时，重复 finish 会幂等返回，不会再次烧录。 -Workspace 产物属于单个媒体项目；共享数据保存在 `OPENBBQ_HOME` 下，默认是 `~/.openbbq`： +自动结果报告 `quality: "draft"` 和 `human_reviewed: false`。通过 +`openbbq review` 完成全部当前人工审核后，质量状态才会变为 `human-reviewed`。 -```text -~/.openbbq/ -├── auth/ # 保存的网站会话 -├── glossaries/ # 命名术语表 JSON -└── models/ # ASR 模型缓存 -``` +## Workspace 与恢复 -受限环境中可以指定其他可写位置： +所有状态都属于一个 workspace。`manifest.json` 记录机械阶段； +`.openbbq/agent-session..json` 记录 lease 与翻译证据。任务中断后，在同一 +workspace 再次调用 `agent next`；不要猜测下一条命令，也不要创建第二个语义批次。 -```bash -OPENBBQ_HOME=/path/to/openbbq-home openbbq doctor -``` +Facade 默认不运行视觉 QA，也不会自动选择 `fansub-compact`。专家原子命令见 +[CLI 参考](/zh/docs/reference/cli)。 diff --git a/website/content/docs/guides/agents.mdx b/website/content/docs/guides/agents.mdx index 2edb7ca..334e9b2 100644 --- a/website/content/docs/guides/agents.mdx +++ b/website/content/docs/guides/agents.mdx @@ -1,78 +1,95 @@ --- title: Agents and JSON -description: Use OpenBBQ safely from coding agents, automation, and non-interactive processes. +description: Drive the one-shot workflow through one machine-readable next-action interface. --- -## Machine-readable output - -Place the root `--json` flag before the command: +## Install the packaged skill ```bash -openbbq --json doctor -openbbq --json status --workspace workspaces/demo -openbbq --json export --workspace workspaces/demo --to zh --mode bilingual +openbbq skill install --agent all ``` -OpenBBQ automatically selects compact JSON when stdout is not an interactive TTY, but agents should pass `--json` explicitly to declare the contract. - -Each command emits one final JSON object on stdout. Human progress and long-task hints go to stderr or the workspace manifest, so stdout remains parseable. - -## Exit and error behavior +Use `--force` after upgrading OpenBBQ. Product-specific targets include +`codex`, `claude`, and the shared `agents` directory. `openbbq skill show` +prints the packaged instructions without installing them. -- Success emits a result object and exits successfully. -- Domain failures emit a structured error with an `error` code, context, and often a `fix`. -- CLI usage errors use the `usage` error code. -- Unexpected failures use the `internal` error code. +## Start once -Agents should follow the provided `fix` instead of parsing human prose or inventing recovery commands. +```bash +openbbq --json agent init '' --workspace workspaces/demo --to zh +``` -## Poll long-running work +An explicit `--glossary NAME` is optional. Without one, URL tasks wait for +fetched author metadata and bind a stable author-and-target glossary. Local +files without an explicit glossary use only their task overlay. -`fetch`, `transcribe`, and `burn` update stage status and progress in `manifest.json`. Poll from another process: +## Follow only `agent next` ```bash -openbbq --json status --workspace workspaces/demo +openbbq --json agent next --workspace workspaces/demo ``` -A running stage with no heartbeat for more than 60 seconds is marked stale by `status`. +Do not infer a parallel checklist. After every successful command or apply, +call `agent next` again. Only `done` with `terminal: true` completes the task. -## Install the packaged skill +### `run_command` -The default target is the shared agents directory: +Execute the returned `argv` exactly. The response includes an `execution` +object describing whether the command may run in the current sandbox or must +run on the host. It also states whether CPU fallback is allowed. -```bash -openbbq skill install -``` +Fetch, GPU transcription, and finish often need host access. Do not replace a +host GPU transcription with sandbox CPU unless the host attempt actually fails +and the returned policy permits fallback. -Target a specific product: +### `translate` + +Translate every `selected_id` in the active batch, never more than 20 cues. +Follow the returned `brief`, glossary context, and target-language rules. +Neighbor cues are context only. + +Write a response matching `response_schema`, then apply it: ```bash -openbbq skill install --agent codex -openbbq skill install --agent claude -openbbq skill install --agent all +openbbq --json agent apply --workspace workspaces/demo response.json ``` -Use `--force` to replace an existing installed copy. A custom parent directory can be passed with `--target`. +The response echoes the exact `batch_id` and `policy_hash`. It must contain the +complete selected ID set. If the current source is clearly wrong, include the +cue-scoped `source_fix` defined by the schema and mark only whether it is +reusable. OpenBBQ creates the glossary candidate automatically; do not duplicate +the same correction in `glossary_updates`. -Two packaged skills are available: +### `review_source` -```bash -openbbq skill install --name openbbq-subtitles -openbbq skill install --name bilibili-cover-safe-area -``` +This action is exceptional. It appears only when a structural ASR problem could +not be repaired deterministically. Submit the complete requested batch using +the returned schema, apply once, and continue. -Print packaged Markdown without installing it: +### `finish` and `done` -```bash -openbbq skill show -openbbq skill show --language zh-CN -openbbq skill show --name bilibili-cover-safe-area --language zh-CN -``` +Run the returned `openbbq agent finish` command once. It exports, burns, checks +delivery, and publishes eligible glossary learning. At `done`, return the +subtitle and video paths and report `quality`, `human_reviewed`, and warnings +verbatim. + +## Machine-readable behavior + +Place the root `--json` before the command name. Successful commands emit one +JSON object. Domain errors include a stable error code and usually an exact +`fix`. Long-running commands update workspace state; repeated mechanical calls +wait and reuse a completed stage. + +Active semantic leases are persistent and hash-bound. Repeating `next` is safe; +submitting partial, stale, or mismatched responses is rejected atomically. -## Operational rules for agents +## Operational boundaries -- Ask before installing system dependencies, downloading large models, or writing browser login state. -- Keep `OPENBBQ_HOME` and workspace paths writable. -- Prefer small translation batches and run `translate check` between batches. -- Do not use `translate init --force` unless discarding existing translation work is intentional. -- Preview exported subtitles before publishing or burning. +- Ask before installing system dependencies, downloading large models, or + writing browser login state. +- Keep `OPENBBQ_HOME`, model caches, and the workspace writable. +- Do not hand-edit Agent session state or create parallel leases. +- Do not run visual QA or choose `fansub-compact` unless the user explicitly + requests that expert work. +- Treat the automatic result as an editable draft. Use `openbbq review`, + Aegisub, or an NLE for professional finishing. diff --git a/website/content/docs/guides/agents.zh.mdx b/website/content/docs/guides/agents.zh.mdx index cb4fbed..b186534 100644 --- a/website/content/docs/guides/agents.zh.mdx +++ b/website/content/docs/guides/agents.zh.mdx @@ -1,78 +1,83 @@ --- title: Agent 与 JSON -description: 从 Coding Agent、自动化和非交互进程中安全使用 OpenBBQ。 +description: 通过唯一的机器可读下一步接口驱动一句提示词工作流。 --- -## 机器可读输出 - -把根级 `--json` 放在命令前： +## 安装随包 Skill ```bash -openbbq --json doctor -openbbq --json status --workspace workspaces/demo -openbbq --json export --workspace workspaces/demo --to zh --mode bilingual +openbbq skill install --agent all ``` -Stdout 不是交互式 TTY 时，OpenBBQ 会自动选择紧凑 JSON；但 Agent 应显式传入 `--json`，以声明输出契约。 - -每个命令最终只在 stdout 输出一个 JSON 对象。人类进度和长任务提示会写入 stderr 或 workspace manifest，stdout 始终可解析。 - -## 退出与错误行为 +升级 OpenBBQ 后加 `--force`。产品专用目标包括 `codex`、`claude`，以及共享的 +`agents` 目录。`openbbq skill show` 可以不安装，直接输出随包说明。 -- 成功时输出结果对象并正常退出。 -- 领域错误输出结构化 `error` code、上下文，通常还带 `fix`。 -- CLI 用法错误使用 `usage` code。 -- 未预期错误使用 `internal` code。 +## 只初始化一次 -Agent 应优先执行返回的 `fix`，不要解析人类文案或凭空猜恢复命令。 +```bash +openbbq --json agent init '' --workspace workspaces/demo --to zh +``` -## 轮询长任务 +`--glossary NAME` 是可选显式设置。未指定时，URL 任务会等待 fetch 得到作者元数据， +再绑定稳定的“作者+目标语言” glossary；未显式指定 glossary 的本地文件只使用任务 +overlay。 -`fetch`、`transcribe` 和 `burn` 会更新 `manifest.json` 中的阶段与进度。可以从另一进程轮询： +## 只遵循 `agent next` ```bash -openbbq --json status --workspace workspaces/demo +openbbq --json agent next --workspace workspaces/demo ``` -Running 阶段超过 60 秒没有心跳时，`status` 会标记 stale。 +不要自行推断并行 checklist。每次 command 或 apply 成功后，再次调用 `agent next`。 +只有 `terminal: true` 的 `done` 才表示任务完成。 -## 安装随包 Skill +### `run_command` -默认目标是共享 agents 目录： +原样执行返回的 `argv`。响应中的 `execution` 对象说明命令可以在当前 sandbox 内运行， +还是必须在宿主环境执行，以及是否允许 CPU fallback。 -```bash -openbbq skill install -``` +Fetch、GPU 转录和 finish 经常需要宿主环境。只有宿主 GPU 尝试本身确实失败，并且返回 +策略允许时，才能改用 CPU；不能直接用 sandbox CPU 替代。 -安装到指定产品： +### `translate` + +翻译活动批次中的全部 `selected_id`，每批不会超过 20 条 cue。遵循返回的 `brief`、 +glossary 上下文和目标语言规则；相邻 cue 只用于消歧。 + +按 `response_schema` 写出响应，再应用： ```bash -openbbq skill install --agent codex -openbbq skill install --agent claude -openbbq skill install --agent all +openbbq --json agent apply --workspace workspaces/demo response.json ``` -使用 `--force` 替换已有副本；通过 `--target` 可以指定自定义父目录。 +响应必须原样带回 `batch_id` 与 `policy_hash`，并包含完整的 selected ID 集合。当前原文 +明确错误时，按 schema 提交 cue-scoped `source_fix`，只判断它是否 reusable。OpenBBQ +会自动生成 glossary candidate，不要再把同一修正重复写入 `glossary_updates`。 -当前包含两个 Skill： +### `review_source` -```bash -openbbq skill install --name openbbq-subtitles -openbbq skill install --name bilibili-cover-safe-area -``` +这是例外 action，只在确定性修复无法解决结构性 ASR 问题时出现。按返回 schema 提交 +完整批次，apply 一次后继续。 -不安装，直接输出随包 Markdown： +### `finish` 与 `done` -```bash -openbbq skill show -openbbq skill show --language zh-CN -openbbq skill show --name bilibili-cover-safe-area --language zh-CN -``` +只运行一次返回的 `openbbq agent finish`。它负责导出、烧录、交付检查与发布符合条件 +的 glossary 学习。收到 `done` 后交付字幕和视频路径，并原样报告 `quality`、 +`human_reviewed` 与 warnings。 + +## 机器可读行为 + +根级 `--json` 必须放在命令名称前。成功命令输出一个 JSON 对象；领域错误包含稳定 +error code，通常还提供精确 `fix`。长任务会更新 workspace 状态；重复机械命令会等待 +并复用已完成阶段。 + +活动语义 lease 会持久化并绑定 hash。重复 `next` 是安全的；部分、过期或不匹配的响应 +会被原子拒绝。 -## Agent 操作原则 +## 操作边界 - 安装系统依赖、下载大型模型或写入浏览器登录态前先询问用户。 -- 确保 `OPENBBQ_HOME` 和 workspace 路径可写。 -- 优先使用小型翻译批次，并在批次间运行 `translate check`。 -- 除非明确要丢弃已有翻译，否则不要使用 `translate init --force`。 -- 发布或烧录前预览导出的字幕。 +- 保证 `OPENBBQ_HOME`、模型缓存和 workspace 可写。 +- 不手工编辑 Agent session，也不创建并行 lease。 +- 除非用户显式要求，不运行视觉 QA，也不选择 `fansub-compact`。 +- 自动结果是可编辑底稿；专业精修使用 `openbbq review`、Aegisub 或剪辑软件。 diff --git a/website/content/docs/guides/export-and-burn.mdx b/website/content/docs/guides/export-and-burn.mdx index 6c40654..abb04fb 100644 --- a/website/content/docs/guides/export-and-burn.mdx +++ b/website/content/docs/guides/export-and-burn.mdx @@ -3,6 +3,22 @@ title: Export and Burn description: Render source, target, or bilingual SRT/ASS subtitles and optionally burn ASS into video. --- +## Default Agent delivery + +The one-prompt workflow ends with: + +```bash +openbbq --json agent finish --workspace workspaces/demo --to zh +``` + +Only run it when `agent next` returns `finish`. It exports `out/zh.ass`, burns +`out/zh-burned.mp4`, runs `delivery check`, and publishes eligible glossary +learning. Landscape video uses `fansub`; portrait video uses `mobile`. Fresh +completed outputs are reused, so finish does not burn the same result twice. + +The default path does not sample frames, run visual QA, or automatically retry +with a different preset. + ## Export modes `openbbq export` reads `cues.json` and, when needed, one translation worksheet. @@ -45,9 +61,12 @@ ASS presets: | --- | --- | | `default` | Standard 16:9 horizontal video | | `fansub` | More prominent translated line | +| `fansub-compact` | Explicit smaller, raised bilingual stack | | `mobile` | 9:16 vertical canvas and larger bottom safe area | -`--ass-preset` is valid only with `--format ass`. The mobile preset changes rendering geometry; it does not shorten long subtitles. +`--ass-preset` is valid only with `--format ass`. Presets change rendering, +not translation meaning. OpenBBQ cannot predict where arbitrary text will +appear inside a video. ## Review gate @@ -57,7 +76,9 @@ When a matching `review..json` or `review.source.json` exists, export requ openbbq review --to zh --workspace workspaces/demo ``` -For an intentional draft only, bypass the gate explicitly with `--allow-unreviewed`. This does not mark any cue reviewed. +For an intentional atomic-command draft only, bypass the gate explicitly with +`--allow-unreviewed`. This does not mark any cue reviewed or create Agent-draft +delivery evidence. ## Incomplete translations @@ -115,3 +136,9 @@ Burning may take minutes. Progress is written to the manifest and can be polled ```bash openbbq --json status --workspace workspaces/demo ``` + +Validate hand-built outputs with: + +```bash +openbbq --json delivery check --workspace workspaces/demo --to zh +``` diff --git a/website/content/docs/guides/export-and-burn.zh.mdx b/website/content/docs/guides/export-and-burn.zh.mdx index dd4bf2b..7c1d1b3 100644 --- a/website/content/docs/guides/export-and-burn.zh.mdx +++ b/website/content/docs/guides/export-and-burn.zh.mdx @@ -3,6 +3,21 @@ title: 导出与烧录 description: 渲染原文、译文或双语 SRT/ASS，并按需烧录 ASS 到视频。 --- +## 默认 Agent 交付 + +一句提示词流程最终执行： + +```bash +openbbq --json agent finish --workspace workspaces/demo --to zh +``` + +只有 `agent next` 返回 `finish` 时才运行。它会导出 `out/zh.ass`、烧录 +`out/zh-burned.mp4`、执行 `delivery check`，并发布符合条件的 glossary 学习。横屏 +使用 `fansub`，竖屏使用 `mobile`。产物仍然新鲜时会直接复用，因此 finish 不会对同一 +结果重复烧录。 + +默认路径不抽样视频帧、不运行视觉 QA，也不会自动换 preset 重试。 + ## 导出模式 `openbbq export` 读取 `cues.json`，需要译文时再读取一个翻译工作表。 @@ -45,9 +60,11 @@ ASS 预设： | --- | --- | | `default` | 常规 16:9 横屏视频 | | `fansub` | 更醒目的译文行 | +| `fansub-compact` | 显式选择的、更小且抬高的双语字幕栈 | | `mobile` | 9:16 竖屏画布和更大的底部安全区 | -`--ass-preset` 只能与 `--format ass` 一起使用。Mobile 预设只改变渲染几何，不会自动缩短长字幕。 +`--ass-preset` 只能与 `--format ass` 一起使用。Preset 只改变渲染，不改变翻译含义； +OpenBBQ 无法预测视频画面中任意文字出现的位置。 ## 审核门禁 @@ -57,7 +74,8 @@ ASS 预设： openbbq review --to zh --workspace workspaces/demo ``` -只有明确需要草稿时才使用 `--allow-unreviewed` 绕过门禁；该选项不会把任何 cue 标为已审核。 +只有明确需要原子命令草稿时才使用 `--allow-unreviewed` 绕过门禁；该选项不会把任何 +cue 标为已审核，也不会生成 Agent 底稿交付证据。 ## 未完成译文 @@ -115,3 +133,9 @@ openbbq burn --workspace workspaces/demo --ffmpeg /path/to/ffmpeg ```bash openbbq --json status --workspace workspaces/demo ``` + +手动构建的产物可以这样校验： + +```bash +openbbq --json delivery check --workspace workspaces/demo --to zh +``` diff --git a/website/content/docs/guides/glossaries.mdx b/website/content/docs/guides/glossaries.mdx index 437d74e..18ed0b9 100644 --- a/website/content/docs/guides/glossaries.mdx +++ b/website/content/docs/guides/glossaries.mdx @@ -1,97 +1,86 @@ --- title: Glossaries -description: Reuse canonical names, aliases, translation choices, and context across workspaces. +description: Learn reusable ASR corrections and terminology without turning one-off edits into global rules. --- -A glossary is a named JSON document stored globally under `$OPENBBQ_HOME/glossaries/`. It can influence three parts of the workflow: +A glossary stores canonical source terms, known ASR aliases, translation +targets or keep rules, notes, and domain context under +`$OPENBBQ_HOME/glossaries/`. -1. Canonical source terms bias supported ASR backends. -2. Known aliases are corrected to canonical source spelling during segmentation. -3. Translation targets and keep rules are included in translation worksheets and checks. +## Automatic scope for one-prompt tasks -## Create a glossary +An explicit `--glossary NAME` always wins: ```bash -openbbq glossary new project-name --context "Technical interviews about AI developer tools" +openbbq --json agent init '' --workspace workspaces/demo --to zh --glossary project-name ``` -The result is `~/.openbbq/glossaries/project-name.json` by default: +Without one, a URL task waits until fetch discovers the author and derives a +stable author-and-target glossary name. Later videos from the same author and +target language reuse that glossary. A local file without an explicit glossary +keeps its learning in the task only because author scope is unknown. -```json -{ - "schema": "openbbq/glossary@1", - "name": "project-name", - "context": "Technical interviews about AI developer tools", - "terms": [] -} -``` +The Agent does not choose among global glossaries by semantic guesswork. -## Add terms +## Task-local overlay -Edit the JSON file and add entries: +During the task, new learning is written to +`.openbbq/glossary-overlay.json`. Base glossary plus overlay are immediately +visible to segmentation and later translation batches, but the global library +is not modified mid-run. -```json -{ - "source": "OpenBBQ", - "target": null, - "aliases": ["Open BBQ", "Open BQ"], - "note": "Project and CLI name", - "keep": true -} -``` +When translation corrects an obvious ASR occurrence, OpenBBQ records a glossary +candidate containing: -Fields: +- canonical corrected source text; +- the observed ASR alias; +- evidence and origin; +- whether the Agent marked it reusable. -| Field | Meaning | -| --- | --- | -| `source` | Canonical source spelling; also used for ASR biasing | -| `target` | Canonical translation when the term should be translated | -| `aliases` | Known ASR mistakes or alternate source forms corrected to `source` | -| `note` | Disambiguation context for translators or agents | -| `keep` | Keep the source spelling in target text | +A reusable correction is promoted into the overlay automatically. The Agent +must not duplicate the same correction as a manual glossary update. -Use `target` for a canonical translation, or `keep: true` for a brand/proper noun that should remain unchanged. Leaving both unset means the translation decision is still open. +## Safe publication -## Inspect the library +After successful delivery, OpenBBQ publishes reusable non-conflicting overlay +entries to the bound global glossary. Publication is idempotent and never +overwrites an incompatible existing term. A conflict or permission failure does +not block the subtitle video; the overlay remains in the workspace and `done` +returns a structured retry warning. -```bash -openbbq glossary list -openbbq glossary show project-name -``` +Failed or unfinished tasks do not publish their overlay. -## Bind a glossary to a workspace +## Glossary fields -At initialization: +| Field | Meaning | +| --- | --- | +| `source` | Canonical source spelling and ASR bias term. | +| `target` | Required canonical translation when present. | +| `aliases` | Confirmed alternate or ASR forms corrected to `source`. | +| `note` | Context supplied to translation batches. | +| `keep` | Preserve source spelling in target text. | -```bash -openbbq init /path/to/video.mp4 --workspace workspaces/demo --glossary project-name -``` +Terms with only a note and no target are still included when relevant, so the +Agent can use their context without inventing a fixed translation. + +## Expert library commands -Or later: +Create, inspect, and explicitly bind a glossary: ```bash +openbbq glossary new project-name --context "Technical interviews about developer tools" +openbbq glossary list +openbbq glossary show project-name openbbq glossary use project-name --workspace workspaces/demo ``` -The binding is written to `manifest.glossary`. `transcribe`, `segment`, and `translate init` use it unless their own `--glossary` option overrides the name. - -## Mine candidate terms - -After transcription, ask OpenBBQ to surface repeated proper-noun-shaped or low-confidence words: +The compatibility interface also exposes deterministic suggestions, full +transcript audit batches, and atomic curated updates: ```bash openbbq glossary suggest --workspace workspaces/demo +openbbq glossary audit --workspace workspaces/demo --offset 0 --limit 20 +openbbq glossary apply --workspace workspaces/demo glossary-terms.json ``` -Useful filters: - -```bash -openbbq glossary suggest \ - --workspace workspaces/demo \ - --glossary project-name \ - --max-prob 0.6 \ - --min-count 2 \ - --max 30 -``` - -Suggestions are deterministic candidates, not automatic semantic edits. Review them, then add appropriate terms manually. +These are expert tools, not required steps in the normal one-prompt flow. diff --git a/website/content/docs/guides/glossaries.zh.mdx b/website/content/docs/guides/glossaries.zh.mdx index f28c036..5e42899 100644 --- a/website/content/docs/guides/glossaries.zh.mdx +++ b/website/content/docs/guides/glossaries.zh.mdx @@ -1,97 +1,78 @@ --- title: 术语表 -description: 在多个 workspace 中复用标准名称、别名、译名和上下文。 +description: 学习可复用的 ASR 修正和术语，同时避免把一次性修改变成全局规则。 --- -术语表是保存在 `$OPENBBQ_HOME/glossaries/` 下的全局命名 JSON 文档，会影响三个环节： +Glossary 保存在 `$OPENBBQ_HOME/glossaries/`，可以存储标准原文、已知 ASR alias、 +固定译名或 keep 规则、备注与领域上下文。 -1. 标准原文术语可为支持的 ASR 后端提供提示。 -2. 已知别名在 segment 时纠正为标准原文拼写。 -3. 标准译名和保留规则会加入翻译工作表与检查。 +## 一句话任务的自动作用域 -## 创建术语表 +显式 `--glossary NAME` 始终优先： ```bash -openbbq glossary new project-name --context "关于 AI 开发工具的技术访谈" +openbbq --json agent init '' --workspace workspaces/demo --to zh --glossary project-name ``` -默认生成 `~/.openbbq/glossaries/project-name.json`： +未指定时，URL 任务会等待 fetch 得到作者，并生成稳定的“作者+目标语言” glossary 名称。 +同作者、同目标语言的后续视频会复用它。未显式指定 glossary 的本地文件因为无法确认 +作者作用域，只在当前任务中保留学习结果。 -```json -{ - "schema": "openbbq/glossary@1", - "name": "project-name", - "context": "关于 AI 开发工具的技术访谈", - "terms": [] -} -``` +Agent 不会依靠语义猜测在全局 glossary 之间自行选择。 -## 添加术语 +## 任务本地 overlay -编辑 JSON 并添加条目： +任务中的新学习写入 `.openbbq/glossary-overlay.json`。Base glossary 与 overlay 会立即 +用于分段和后续翻译批次，但全局库不会在任务中途被修改。 -```json -{ - "source": "OpenBBQ", - "target": null, - "aliases": ["Open BBQ", "Open BQ"], - "note": "项目和 CLI 名称", - "keep": true -} -``` +翻译阶段修正明确 ASR occurrence 时，OpenBBQ 会记录 glossary candidate，包括： -字段含义： +- 修正后的标准原文； +- 实际观察到的 ASR alias； +- 证据与来源； +- Agent 是否将它判断为 reusable。 -| 字段 | 含义 | -| --- | --- | -| `source` | 标准原文拼写，也用于 ASR 提示 | -| `target` | 需要翻译时采用的标准译名 | -| `aliases` | 会被纠正为 `source` 的 ASR 错词或其他原文形式 | -| `note` | 给译者或 Agent 的消歧上下文 | -| `keep` | 在译文中保留原文拼写 | +Reusable correction 会自动提升到 overlay。Agent 不需要再把同一修正重复提交为手动 +glossary update。 -有固定译名时设置 `target`；品牌或专有名词不翻译时使用 `keep: true`。两者都不设置表示翻译决策尚未确定。 +## 安全发布 -## 查看术语表库 +成功交付后，OpenBBQ 才把 overlay 中可复用且无冲突的条目发布到绑定的全局 glossary。 +发布是幂等的，不会覆盖不兼容的旧条目。冲突或权限失败不会阻塞字幕视频；overlay 会 +留在 workspace 中，`done` 返回结构化重试 warning。 -```bash -openbbq glossary list -openbbq glossary show project-name -``` +失败或未完成的任务不会发布 overlay。 -## 绑定到 workspace +## Glossary 字段 -初始化时绑定： +| 字段 | 含义 | +| --- | --- | +| `source` | 标准原文拼写与 ASR bias term。 | +| `target` | 存在时必须使用的标准译名。 | +| `aliases` | 已确认并会修正为 `source` 的其他形式或 ASR 错词。 | +| `note` | 提供给翻译批次的上下文。 | +| `keep` | 在译文中保留原文拼写。 | -```bash -openbbq init /path/to/video.mp4 --workspace workspaces/demo --glossary project-name -``` +只有 note、没有 target 的相关术语也会进入翻译批次，让 Agent 使用上下文，但不会因此 +编造固定译名。 + +## 专家术语表命令 -也可以之后绑定： +创建、查看和显式绑定 glossary： ```bash +openbbq glossary new project-name --context "关于开发工具的技术访谈" +openbbq glossary list +openbbq glossary show project-name openbbq glossary use project-name --workspace workspaces/demo ``` -名称写入 `manifest.glossary`。`transcribe`、`segment` 和 `translate init` 默认使用它，各命令的 `--glossary` 可以临时覆盖。 - -## 挖掘候选术语 - -转录后，让 OpenBBQ 找出重复出现、形似专有名词或低置信度的词： +兼容接口也保留确定性 suggest、全文 audit batch 与原子 curated update： ```bash openbbq glossary suggest --workspace workspaces/demo +openbbq glossary audit --workspace workspaces/demo --offset 0 --limit 20 +openbbq glossary apply --workspace workspaces/demo glossary-terms.json ``` -常用筛选： - -```bash -openbbq glossary suggest \ - --workspace workspaces/demo \ - --glossary project-name \ - --max-prob 0.6 \ - --min-count 2 \ - --max 30 -``` - -Suggest 返回的是确定性候选，不会自动进行语义编辑。请人工检查后再加入合适术语。 +这些属于专家工具，不是正常 one-shot 流程的必做步骤。 diff --git a/website/content/docs/guides/index.mdx b/website/content/docs/guides/index.mdx index 795f3f1..64c70a3 100644 --- a/website/content/docs/guides/index.mdx +++ b/website/content/docs/guides/index.mdx @@ -5,8 +5,8 @@ description: Task-oriented guides for media, translation, publishing, and Agent Choose the correct acquisition path and handle YouTube authentication. - Create, fill, validate, and preserve translation worksheets. - Keep names consistent across ASR, segmentation, and translation. - Render SRT or ASS and optionally create a hard-subtitled video. - Use stable machine output and install the packaged Agent skill. + Understand bounded Agent batches, target-language briefs, and editable worksheets. + Learn reusable ASR fixes and terminology through task-local overlays. + Finish once, validate delivery, or use the expert export controls. + Drive the complete workflow through one authoritative next-action interface. diff --git a/website/content/docs/guides/index.zh.mdx b/website/content/docs/guides/index.zh.mdx index 7ea65a9..890e5d9 100644 --- a/website/content/docs/guides/index.zh.mdx +++ b/website/content/docs/guides/index.zh.mdx @@ -5,8 +5,8 @@ description: 面向媒体、翻译、发布和 Agent 工作流的任务指南。 选择正确的媒体获取路径，并处理 YouTube 登录。 - 创建、填写、校验并保护翻译工作表。 - 在 ASR、切分和翻译阶段保持名称一致。 - 渲染 SRT 或 ASS，并按需制作硬字幕视频。 - 使用稳定的机器输出，并安装随包 Agent Skill。 + 理解有界 Agent 批次、目标语言 brief 与可编辑工作表。 + 通过任务本地 overlay 学习可复用 ASR 修正与术语。 + 只 finish 一次、校验交付，或使用专家导出控制。 + 通过唯一权威下一步接口驱动完整工作流。 diff --git a/website/content/docs/guides/sources.mdx b/website/content/docs/guides/sources.mdx index dd621e3..db34d1a 100644 --- a/website/content/docs/guides/sources.mdx +++ b/website/content/docs/guides/sources.mdx @@ -3,6 +3,20 @@ title: Local Files and Online Video description: Initialize local media or URL sources, fetch online video, and manage YouTube authentication. --- +## Recommended Agent entry + +The same facade accepts a URL, local video, or local audio: + +```bash +openbbq --json agent init '' --workspace workspaces/demo --to zh +openbbq --json agent next --workspace workspaces/demo +``` + +For a URL, `agent next` returns fetch before audio extraction. Local files skip +fetch. Execute the returned `argv` exactly; its `execution` policy states when +host network, authentication state, or native GPU access requires running +outside a restricted sandbox. + ## Local video Initialize a workspace with an existing video file: @@ -77,9 +91,12 @@ openbbq fetch --workspace workspaces/demo --no-auth `--auth` and `--no-auth` are mutually exclusive in intent; use only one. - Browser login needs a desktop session, and authentication storage needs a writable `OPENBBQ_HOME`. Run login and authenticated fetch outside a restricted sandbox, or point `OPENBBQ_HOME` at a writable directory. + Browser login needs a desktop session, and authentication storage needs a writable `OPENBBQ_HOME`. Run login and authenticated fetch outside a restricted sandbox, or point `OPENBBQ_HOME` at a writable directory. Native GPU transcription should also run on the host; use CPU only after that host attempt genuinely fails and the returned execution policy permits fallback. ## Rerunning fetch -Fetch progress and failures are recorded in the workspace manifest. Rerunning the command replaces the fetch stage state and invalidates downstream stages. Inspect the downloaded media before regenerating downstream artifacts. +Fetch progress and failures are recorded in the workspace manifest. In the +Agent facade, repeated fetch calls wait for the active stage and reuse its fresh +completed artifact. An intentional new upstream result invalidates dependent +downstream state. diff --git a/website/content/docs/guides/sources.zh.mdx b/website/content/docs/guides/sources.zh.mdx index 6bed6db..27c136f 100644 --- a/website/content/docs/guides/sources.zh.mdx +++ b/website/content/docs/guides/sources.zh.mdx @@ -3,6 +3,19 @@ title: 本地文件与在线视频 description: 初始化本地媒体或 URL 来源，下载在线视频，并管理 YouTube 登录态。 --- +## 推荐 Agent 入口 + +同一 facade 可以接收 URL、本地视频或本地音频： + +```bash +openbbq --json agent init '' --workspace workspaces/demo --to zh +openbbq --json agent next --workspace workspaces/demo +``` + +URL 的 `agent next` 会先返回 fetch，本地文件则跳过 fetch。应原样执行返回的 `argv`； +其中的 `execution` policy 会说明宿主网络、登录态或原生 GPU 是否要求在受限 sandbox 外 +运行。 + ## 本地视频 使用已有视频初始化 workspace： @@ -77,9 +90,10 @@ openbbq fetch --workspace workspaces/demo --no-auth `--auth` 与 `--no-auth` 意图互斥，请只使用一个。 - 浏览器登录需要桌面会话，鉴权存储需要可写的 `OPENBBQ_HOME`。请在受限 sandbox 外执行登录和带鉴权的 fetch，或把 `OPENBBQ_HOME` 指向可写目录。 + 浏览器登录需要桌面会话，鉴权存储需要可写的 `OPENBBQ_HOME`。请在受限 sandbox 外执行登录和带鉴权的 fetch，或把 `OPENBBQ_HOME` 指向可写目录。原生 GPU 转录也应在宿主环境运行；只有宿主尝试确实失败并且返回策略允许时，才能改用 CPU。 ## 重跑 fetch -Fetch 的进度和失败会记录在 manifest 中。重跑会替换 fetch 阶段状态，并使下游阶段失效。重新生成下游产物前，请先检查下载的媒体。 +Fetch 的进度和失败会记录在 manifest 中。Agent facade 中的重复 fetch 会等待活动阶段， +并复用已经完成的新鲜产物；只有有意生成新的上游结果时，才会使依赖的下游状态失效。 diff --git a/website/content/docs/guides/translation.mdx b/website/content/docs/guides/translation.mdx index bf5aea1..c929faf 100644 --- a/website/content/docs/guides/translation.mdx +++ b/website/content/docs/guides/translation.mdx @@ -1,103 +1,76 @@ --- -title: Translation Workflow -description: Create, fill, batch-apply, and validate per-language translation worksheets. +title: Translation +description: Understand Agent translation batches, reproducible briefs, and editable worksheets. --- -Translation is intentionally not an automatic black box. OpenBBQ prepares a structured worksheet; a human or Agent supplies semantic translations and can validate them incrementally. +OpenBBQ does not embed a translation provider. An external Agent supplies the +semantic translation while OpenBBQ controls batch size, context, ids, hashes, +and atomic application. -## Prerequisite +## Default Agent translation -Create source cues first: +The one-prompt workflow creates a `translation@2` worksheet and returns one +active `translate` action at a time. Each batch contains at most 20 selected +cues and includes: -```bash -openbbq segment --workspace workspaces/demo -``` - -## Create a worksheet - -Use a BCP-47-style target language code such as `zh`, `ja`, or `pt-BR`: - -```bash -openbbq translate init zh --workspace workspaces/demo -``` - -This creates `translation.zh.json`. Each item is tied to a cue id and includes source text, timing, target budget, glossary hints, and `target: null`. - -If a worksheet already exists, `init` refuses to overwrite it. Regenerate only when you accept losing all filled targets: - -```bash -openbbq translate init zh --workspace workspaces/demo --force -``` - -## Fill targets directly - -Edit `translation.zh.json` while preserving its schema and cue ids. Change only the semantic target fields unless you understand the integrity checks: - -```json -{ - "id": 1, - "source": "Tools should expose the process.", - "target": "工具应该让过程透明。" -} -``` +- source and target language; +- fetched title and author when available; +- glossary domain context; +- matching terms from selected and neighboring cues, including pending terms; +- neighboring cue text for disambiguation; +- fixed target-language rules and a `policy_hash`. -## Apply translations in batches +The response must translate every selected id and echo the exact `batch_id` and +`policy_hash`. Missing, extra, stale, or mismatched ids are rejected. -For long videos, use small `{id: text}` files that are easy to review and retry: +## Simplified Chinese rules -```json -{ - "1": "第一句译文", - "2": "第二句译文" -} -``` +Targets `zh`, `zh-Hans`, and `zh-CN` use the `zh-Hans` brief. It asks the Agent +to produce natural concise Simplified Chinese while preserving negation, +degree, numbers, entities, causality, conditions, and operational steps. -```bash -openbbq translate apply zh batch-01.json --workspace workspaces/demo -openbbq translate apply zh batch-02.json --workspace workspaces/demo -``` +Commands, code, paths, flags, URLs, shortcuts, product names, and model names +remain accurate unless the glossary provides a translation. Neighbor cues may +resolve ambiguity but content must not drift between ids. Meaning and alignment +take priority over aggressive shortening. -Applying a batch is repeatable. Existing ids are overwritten and reported; unknown or malformed ids are rejected instead of silently corrupting the worksheet. +Traditional Chinese tags such as `zh-TW`, `zh-Hant`, and `zh-HK` use the generic +fallback rather than incorrectly applying Simplified Chinese rules. -## Validate completeness and quality signals +## Translation-time ASR correction -```bash -openbbq translate check zh --workspace workspaces/demo -``` +When the target meaning exposes an obvious ASR error in the current cue, the +Agent can submit a cue-scoped source fix with evidence and a reusable decision. +OpenBBQ updates `cues.json` and the worksheet atomically before applying the +translation. Reusable fixes become glossary candidates automatically. -If only one worksheet exists, omit the language: +Uncertain guesses should remain warnings, not invented corrections. -```bash -openbbq translate check --workspace workspaces/demo -``` +## Quality signals -The report includes: +`translate check` reports completeness, target budgets, and terminology +warnings. In the default draft workflow, display budgets and ordinary glossary +consistency are advisory. Hard gates cover complete ids, non-empty text, +current hashes, valid timing, translation evidence, and fresh artifacts. -- Filled and total cue counts. -- Missing cue ids. -- Targets that exceed the generated character budget. -- Glossary term warnings. -- Worksheet/cue integrity problems. +The default workflow does not run a second full-coverage AI audit. A complete +human review is the route to `quality: "human-reviewed"`. -Over-budget and terminology results are review signals. Completeness is required for target or bilingual export unless `--allow-missing` is used. +## Expert worksheet commands -## Multiple target languages - -Each language has an independent worksheet: +The atomic interface remains available for manual or custom-provider workflows: ```bash openbbq translate init zh --workspace workspaces/demo -openbbq translate init ja --workspace workspaces/demo +openbbq --json translate batch zh --workspace workspaces/demo --limit 20 --only-missing +openbbq translate apply zh batch-01.json --workspace workspaces/demo +openbbq translate check zh --workspace workspaces/demo ``` -Export the desired language explicitly with `--to`. - -## Using a glossary - -A glossary bound in `manifest.json` is included automatically. Override it for one worksheet: - -```bash -openbbq translate init zh --workspace workspaces/demo --glossary project-name -``` +`translate apply` accepts a `{id: target}` object and is repeatable. Atomic +commands do not create Agent-draft delivery evidence; use the facade for a +one-shot deliverable or complete a human review before final delivery. -See [Glossaries](/en/docs/guides/glossaries) for schema and lifecycle details. +One worksheet exists per target language. `translate init --force` overwrites +an existing worksheet and discards filled targets, so use it only when that loss +is intentional. diff --git a/website/content/docs/guides/translation.zh.mdx b/website/content/docs/guides/translation.zh.mdx index 3581ba6..c0f8a98 100644 --- a/website/content/docs/guides/translation.zh.mdx +++ b/website/content/docs/guides/translation.zh.mdx @@ -1,103 +1,66 @@ --- -title: 翻译工作流 -description: 创建、填写、分批合并并校验多语言翻译工作表。 +title: 翻译 +description: 理解 Agent 翻译批次、可复现 brief 与可编辑工作表。 --- -翻译阶段有意不做成自动黑盒。OpenBBQ 负责准备结构化工作表，由人或 Agent 提供语义翻译，并支持增量校验。 +OpenBBQ 不内置翻译 provider。外部 Agent 负责语义翻译，OpenBBQ 负责批次大小、上下文、 +ID、hash 与原子应用。 -## 前置条件 +## 默认 Agent 翻译 -先生成原文 cue： +一句提示词流程会创建 `translation@2` 工作表，并且同时只返回一个活动 `translate` +action。每批最多选择 20 条 cue，并包含： -```bash -openbbq segment --workspace workspaces/demo -``` - -## 创建工作表 - -使用 `zh`、`ja`、`pt-BR` 这类 BCP-47 风格目标语言代码： - -```bash -openbbq translate init zh --workspace workspaces/demo -``` - -命令会创建 `translation.zh.json`。每个项目都绑定 cue id，并包含原文、时间、目标长度预算、术语提示和 `target: null`。 - -工作表已存在时，`init` 会拒绝覆盖。只有明确接受丢失全部译文时才重新生成： - -```bash -openbbq translate init zh --workspace workspaces/demo --force -``` - -## 直接填写 target - -编辑 `translation.zh.json` 时保留 schema 和 cue id。除非理解完整性校验，否则只修改语义 target： - -```json -{ - "id": 1, - "source": "Tools should expose the process.", - "target": "工具应该让过程透明。" -} -``` +- 原语言与目标语言； +- fetch 能获取到的标题和作者； +- glossary 领域上下文； +- 当前与相邻 cue 命中的术语，包括 pending term； +- 用于消歧的相邻 cue 文本； +- 固定目标语言规则与 `policy_hash`。 -## 分批合并译文 +响应必须翻译所有 selected ID，并原样带回 `batch_id` 和 `policy_hash`。缺失、额外、 +过期或 policy 不匹配的 ID 都会被拒绝。 -长视频适合使用小型 `{id: text}` 文件，便于检查和重试： +## 简体中文规则 -```json -{ - "1": "第一句译文", - "2": "第二句译文" -} -``` +`zh`、`zh-Hans` 和 `zh-CN` 使用 `zh-Hans` brief：输出自然、简洁的简体中文，同时 +保留否定、程度、数字、实体、因果、条件与操作步骤。 -```bash -openbbq translate apply zh batch-01.json --workspace workspaces/demo -openbbq translate apply zh batch-02.json --workspace workspaces/demo -``` +命令、代码、路径、flag、URL、快捷键、产品名和模型名应保持准确，除非 glossary +明确提供译名。相邻 cue 只用于消歧，内容不能跨 ID 漂移。含义与对齐优先于激进压缩。 -批次可以重复应用。已有 id 会被覆盖并报告；未知或格式错误的 id 会被拒绝，不会静默破坏工作表。 +`zh-TW`、`zh-Hant` 和 `zh-HK` 等繁体标签使用 generic fallback，不会误套简体规则。 -## 校验完整性与质量信号 +## 翻译时修正 ASR -```bash -openbbq translate check zh --workspace workspaces/demo -``` +译文语义暴露当前 cue 中的明确 ASR 错误时，Agent 可以提交带证据和 reusable 判断的 +cue-scoped source fix。OpenBBQ 会先原子同步 `cues.json` 与工作表，再应用译文；可复用 +修正会自动成为 glossary candidate。 -只有一个工作表时，可以省略语言： +不确定的猜测应保留为 warning，不能编造 source correction。 -```bash -openbbq translate check --workspace workspaces/demo -``` +## 质量信号 -报告包括： +`translate check` 报告完整度、target budget 与术语提示。默认底稿流程中，显示预算和 +普通 glossary 一致性只是 advisory；硬门禁覆盖完整 ID、非空文本、当前 hash、有效 +时间轴、翻译证据与新鲜产物。 -- 已填写和总 cue 数。 -- 缺失 cue id。 -- 超过生成字符预算的 target。 -- 术语警告。 -- 工作表与 cue 的完整性问题。 +默认流程不再运行第二轮全量 AI audit。只有完整人工审核才会得到 +`quality: "human-reviewed"`。 -超预算和术语结果是审校信号。目标或双语导出默认要求全部翻译完成，除非使用 `--allow-missing`。 +## 专家工作表命令 -## 多个目标语言 - -每个语言使用独立工作表： +手动流程或自定义 provider 仍可使用原子接口： ```bash openbbq translate init zh --workspace workspaces/demo -openbbq translate init ja --workspace workspaces/demo +openbbq --json translate batch zh --workspace workspaces/demo --limit 20 --only-missing +openbbq translate apply zh batch-01.json --workspace workspaces/demo +openbbq translate check zh --workspace workspaces/demo ``` -导出时通过 `--to` 明确选择语言。 - -## 使用术语表 - -绑定在 `manifest.json` 中的术语表会自动加入。也可以只为当前工作表覆盖： - -```bash -openbbq translate init zh --workspace workspaces/demo --glossary project-name -``` +`translate apply` 接受 `{id: target}` 对象，可以重复执行。原子命令不会生成 Agent 底稿 +交付证据；一句提示词交付请使用 facade，或在最终交付前完成人工审核。 -Schema 和生命周期见[术语表](/zh/docs/guides/glossaries)。 +每种目标语言有独立工作表。`translate init --force` 会覆盖现有工作表并丢弃已填 target， +只应在明确接受损失时使用。 diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx index e3b8b01..84bf3be 100644 --- a/website/content/docs/index.mdx +++ b/website/content/docs/index.mdx @@ -1,12 +1,12 @@ --- title: Documentation -description: Install OpenBBQ and build a complete video translation workflow. +description: Turn a video into an editable bilingual subtitle draft with one Agent prompt. --- -OpenBBQ is an agent-friendly CLI for video translation and subtitle production. It provides composable commands for acquiring media, transcription, subtitle segmentation, translation review, export, and hard-subtitle burning. +OpenBBQ is an Agent-friendly CLI for video translation and subtitle production. Its default workflow turns one simple request into an editable bilingual ASS subtitle and a hard-subtitled video. Fine-grained commands remain available for professional review and recovery. - OpenBBQ is pre-alpha software. The current implementation is centered on Python 3.12, FFmpeg, yt-dlp, and the whisper.cpp ASR backend. Verify important output before publishing it. + OpenBBQ is pre-alpha software. The automatic workflow aims for a useful 70–80 point draft, not a professionally certified final subtitle. Review important output before publishing it. ## Start here @@ -16,31 +16,28 @@ OpenBBQ is an agent-friendly CLI for video translation and subtitle production. Install the CLI, FFmpeg, an ASR backend, and a model. - Produce bilingual subtitles from a local video. + Start with the same one-shot prompt for a URL or local video. - Understand workspaces, stages, and resumable commands. + Understand actions, leases, artifacts, and safe recovery. Look up every command, argument, option, and default. -## The pipeline +## The default path ```text -source - -> init - -> fetch (URL sources only) - -> extract-audio - -> transcribe - -> segment - -> translate init/apply/check - -> export - -> burn (optional) +one prompt + -> agent init + -> agent next (one authoritative action) + -> run mechanical commands or apply translation batches (<=20 cues) + -> agent finish (export + burn + delivery check once) + -> done ``` -Each command writes a validated artifact and records its state in `manifest.json`. You can inspect progress with `openbbq status`, rerun an upstream stage, and continue from the resulting workspace. +Repeated `agent next` calls return the same active lease until it is applied. OpenBBQ validates ids, hashes, timing, and artifact freshness while the Agent handles semantic translation and obvious cue-scoped ASR corrections. ## Choose a guide diff --git a/website/content/docs/index.zh.mdx b/website/content/docs/index.zh.mdx index ff5e9aa..67f81a8 100644 --- a/website/content/docs/index.zh.mdx +++ b/website/content/docs/index.zh.mdx @@ -1,12 +1,12 @@ --- title: 文档 -description: 安装 OpenBBQ，并搭建完整的视频翻译工作流。 +description: 用一句 Agent 提示词把视频制作成可编辑的双语字幕底稿。 --- -OpenBBQ 是一个面向 Agent 的视频翻译和字幕制作 CLI，提供媒体获取、转录、字幕切分、翻译审校、导出和硬字幕烧录等可组合命令。 +OpenBBQ 是一个面向 Agent 的视频翻译和字幕制作 CLI。默认流程把一句简单请求变成可编辑的双语 ASS 字幕和烧录后的视频；专业审校与故障恢复仍可使用细粒度命令。 - OpenBBQ 仍处于 pre-alpha 阶段。当前实现主要基于 Python 3.12、FFmpeg、yt-dlp 和 whisper.cpp ASR 后端，发布前请人工检查重要输出。 + OpenBBQ 仍处于 pre-alpha 阶段。自动流程的目标是可用的 70–80 分底稿，不是经过专业认证的最终字幕；发布重要内容前仍应人工检查。 ## 从这里开始 @@ -16,31 +16,28 @@ OpenBBQ 是一个面向 Agent 的视频翻译和字幕制作 CLI，提供媒体 安装 CLI、FFmpeg、ASR 后端和模型。 - 从本地视频制作一份双语字幕。 + 对 URL 或本地视频使用相同的一句话提示词。 - 理解 workspace、阶段和可恢复命令。 + 理解 action、lease、产物与安全恢复。 查询所有命令、参数、选项和默认值。 -## 处理管线 +## 默认路径 ```text -source - -> init - -> fetch（仅 URL 来源） - -> extract-audio - -> transcribe - -> segment - -> translate init/apply/check - -> export - -> burn（可选） +一句提示词 + -> agent init + -> agent next（唯一权威 action） + -> 执行机械命令或提交翻译批次（每批 <=20 条） + -> agent finish（一次导出、烧录与交付检查） + -> done ``` -每个命令都会写入经过校验的产物，并在 `manifest.json` 中记录状态。你可以通过 `openbbq status` 查看进度，重新运行上游阶段，再从更新后的 workspace 继续。 +活动批次应用前，重复调用 `agent next` 会返回同一个 lease。OpenBBQ 校验 ID、hash、时间轴和产物新鲜度；Agent 负责语义翻译，并可修正明确的 cue-scoped ASR 错误。 ## 按任务选择指南 diff --git a/website/content/docs/reference/cli.mdx b/website/content/docs/reference/cli.mdx index fb23ee6..ed6084f 100644 --- a/website/content/docs/reference/cli.mdx +++ b/website/content/docs/reference/cli.mdx @@ -12,6 +12,7 @@ openbbq [--json] COMMAND [ARGS]... | Option | Description | | --- | --- | | `--json` | Emit one machine-readable JSON object. Must appear before the command. | +| `--version` | Print the installed OpenBBQ version. | | `--help` | Show help for the current command or group. | | `--install-completion` | Install shell completion. | | `--show-completion` | Print shell completion code. | @@ -48,6 +49,22 @@ openbbq status [--workspace PATH] Reports source metadata, glossary binding, worksheets, recorded stages, progress, artifacts, failures, and stale running stages. +## `agent` + +The default one-prompt facade: + +```text +openbbq agent init [--workspace PATH] [--to CODE] [--glossary NAME] SOURCE +openbbq agent next [--workspace PATH] [--to CODE] +openbbq agent apply [--workspace PATH] [--to CODE] RESPONSE.json +openbbq agent finish [--workspace PATH] [--to CODE] +``` + +`init` creates the editable-draft session. `next` returns the one authoritative +action. `apply` atomically accepts the complete active semantic response. +`finish` exports, burns, checks delivery, and publishes eligible glossary +learning once. + ## `fetch` ```text @@ -58,6 +75,7 @@ openbbq fetch [--workspace PATH] [--auth SITE | --no-auth] | --- | --- | | `--auth SITE` | Use a saved site app session, currently `youtube`. | | `--no-auth` | Force anonymous yt-dlp download. | +| `--max-height INT` | Limit downloaded video height; yt-dlp best quality is the default. | Valid only for URL sources. Supported YouTube URLs automatically use a configured YouTube session unless `--no-auth` is passed. @@ -123,6 +141,16 @@ openbbq translate apply [--workspace PATH] LANG TARGETS.json Merges a JSON object mapping cue ids to translated text. Repeat for multiple batches. +## `translate batch` + +```text +openbbq translate batch [--workspace PATH] [--from ID] [--limit 1..200] + [--only-missing] [--context 0..5] [LANG] +``` + +Reads a bounded worksheet slice with neighboring context. The compatibility +default limit is 20; the Agent facade independently enforces a maximum of 20. + ## `translate check` ```text @@ -151,17 +179,21 @@ openbbq export [OPTIONS] | `--mode source\|target\|bilingual` | source, or target with `--to` | Render mode. | | `--format srt\|ass` | `srt` | Subtitle format. | | `--output PATH` | `out/.` | Destination path. | -| `--ass-preset default\|fansub\|mobile` | `default` | ASS style preset; valid only with ASS. | +| `--ass-preset default\|fansub\|fansub-compact\|mobile` | `default` | ASS style preset; valid only with ASS. | | `--allow-missing` | off | Fall back to source text for missing target cues. | | `--allow-unreviewed` | off | Bypass the review-completion gate for an explicit draft export. | ## `burn` ```text -openbbq burn [--workspace PATH] [--subtitle FILE.ass] [--output FILE.mp4] [--ffmpeg PATH] +openbbq burn [--workspace PATH] [--subtitle FILE.ass] [--output FILE.mp4] + [--ffmpeg PATH] [--allow-stale] ``` -Uses the last export artifact when `--subtitle` is omitted. The default output is based on the subtitle filename, for example `out/zh-burned.mp4`. Requires a video source and ASS input. +Uses the last export artifact when `--subtitle` is omitted. The default output +is based on the subtitle filename, for example `out/zh-burned.mp4`. Requires a +video source and ASS input. `--allow-stale` is an explicit expert escape hatch +for an intentional untracked or stale subtitle. ## `models` @@ -192,6 +224,8 @@ openbbq glossary show NAME openbbq glossary new [--context TEXT] NAME openbbq glossary use [--workspace PATH] NAME openbbq glossary suggest [OPTIONS] +openbbq glossary audit [--workspace PATH] [--offset N] [--limit N] +openbbq glossary apply [--workspace PATH] [--glossary NAME] CHANGES.json ``` `suggest` options: @@ -203,6 +237,48 @@ openbbq glossary suggest [OPTIONS] | `--min-count INT` | `1` | Minimum occurrences. | | `--max INT` | `30` | Maximum candidates returned. | +`audit` pages through resolved transcript segments with contextual evidence. +`apply` atomically adds or updates at most 20 curated terms. These are expert +compatibility tools; the Agent facade uses a task-local overlay and publishes +eligible learning after delivery. + +## `asr` + +Expert ASR diagnosis and correction commands: + +```text +openbbq asr check [--workspace PATH] [--max-prob FLOAT] +openbbq asr batch [--workspace PATH] [--offset N] [--limit N] + [--only-unresolved | --all] [--max-prob FLOAT] +openbbq asr apply [--workspace PATH] DECISIONS.json +openbbq asr amend [--workspace PATH] AMENDMENTS.json +``` + +`check` and `batch` expose deterministic issues. `apply` records explicit issue +decisions. `amend` applies bounded contextual phrase corrections without a +detector issue id. Normal one-prompt tasks use these only when `agent next` +returns an exceptional source-review action. + +## `delivery` + +```bash +openbbq delivery check [--workspace PATH] [--to CODE] +``` + +Returns non-zero until source, translation evidence, export, and burn artifacts +are complete, current, structurally valid, and non-empty. + +## `qa` + +```text +openbbq qa render +openbbq qa check +openbbq qa attest +``` + +Optional expert visual-evidence commands. They are not part of the default +Agent workflow. `render` alone does not perform visual inspection. + ## `auth` ```bash diff --git a/website/content/docs/reference/cli.zh.mdx b/website/content/docs/reference/cli.zh.mdx index 64f7e47..adac846 100644 --- a/website/content/docs/reference/cli.zh.mdx +++ b/website/content/docs/reference/cli.zh.mdx @@ -12,6 +12,7 @@ openbbq [--json] COMMAND [ARGS]... | 选项 | 说明 | | --- | --- | | `--json` | 输出一个机器可读 JSON 对象，必须放在命令之前。 | +| `--version` | 输出当前安装的 OpenBBQ 版本。 | | `--help` | 显示当前命令或命令组帮助。 | | `--install-completion` | 安装 shell 补全。 | | `--show-completion` | 输出 shell 补全代码。 | @@ -48,6 +49,20 @@ openbbq status [--workspace PATH] 报告来源元数据、术语表绑定、工作表、已记录阶段、进度、产物、失败和 stale running 阶段。 +## `agent` + +默认一句提示词 facade： + +```text +openbbq agent init [--workspace PATH] [--to CODE] [--glossary NAME] SOURCE +openbbq agent next [--workspace PATH] [--to CODE] +openbbq agent apply [--workspace PATH] [--to CODE] RESPONSE.json +openbbq agent finish [--workspace PATH] [--to CODE] +``` + +`init` 创建可编辑底稿 session；`next` 返回唯一权威 action；`apply` 原子接收完整的活动 +语义响应；`finish` 只执行一次导出、烧录、交付检查和符合条件的 glossary 发布。 + ## `fetch` ```text @@ -58,6 +73,7 @@ openbbq fetch [--workspace PATH] [--auth SITE | --no-auth] | --- | --- | | `--auth SITE` | 使用保存的网站会话，目前为 `youtube`。 | | `--no-auth` | 强制匿名 yt-dlp 下载。 | +| `--max-height INT` | 限制下载视频高度；默认使用 yt-dlp 最佳质量。 | 只适用于 URL 来源。支持的 YouTube URL 会自动使用已配置会话，除非传入 `--no-auth`。 @@ -123,6 +139,16 @@ openbbq translate apply [--workspace PATH] LANG TARGETS.json 合并 cue id 到译文的 JSON 对象，可用于多个批次。 +## `translate batch` + +```text +openbbq translate batch [--workspace PATH] [--from ID] [--limit 1..200] + [--only-missing] [--context 0..5] [LANG] +``` + +读取带相邻上下文的有界工作表切片。兼容接口默认 limit 为 20；Agent facade 会独立强制 +每批最多 20 条。 + ## `translate check` ```text @@ -151,17 +177,20 @@ openbbq export [OPTIONS] | `--mode source\|target\|bilingual` | 无 `--to` 时 source，否则 target | 渲染模式。 | | `--format srt\|ass` | `srt` | 字幕格式。 | | `--output PATH` | `out/.` | 输出路径。 | -| `--ass-preset default\|fansub\|mobile` | `default` | ASS 样式预设，只对 ASS 有效。 | +| `--ass-preset default\|fansub\|fansub-compact\|mobile` | `default` | ASS 样式预设，只对 ASS 有效。 | | `--allow-missing` | 关闭 | 缺少译文的 cue 回退到原文。 | | `--allow-unreviewed` | 关闭 | 显式绕过审核完成门禁，用于草稿导出。 | ## `burn` ```text -openbbq burn [--workspace PATH] [--subtitle FILE.ass] [--output FILE.mp4] [--ffmpeg PATH] +openbbq burn [--workspace PATH] [--subtitle FILE.ass] [--output FILE.mp4] + [--ffmpeg PATH] [--allow-stale] ``` -省略 `--subtitle` 时使用最近的 export 产物。默认输出根据字幕文件命名，例如 `out/zh-burned.mp4`。要求视频来源和 ASS 输入。 +省略 `--subtitle` 时使用最近的 export 产物。默认输出根据字幕文件命名，例如 +`out/zh-burned.mp4`。要求视频来源和 ASS 输入。`--allow-stale` 是专家显式选择，用于 +有意烧录未跟踪或 stale 的字幕。 ## `models` @@ -192,6 +221,8 @@ openbbq glossary show NAME openbbq glossary new [--context TEXT] NAME openbbq glossary use [--workspace PATH] NAME openbbq glossary suggest [OPTIONS] +openbbq glossary audit [--workspace PATH] [--offset N] [--limit N] +openbbq glossary apply [--workspace PATH] [--glossary NAME] CHANGES.json ``` `suggest` 选项： @@ -203,6 +234,45 @@ openbbq glossary suggest [OPTIONS] | `--min-count INT` | `1` | 最小出现次数。 | | `--max INT` | `30` | 最大候选数。 | +`audit` 分页读取带上下文证据的 resolved transcript segment；`apply` 原子增加或更新最多 +20 个 curated term。它们是专家兼容工具；Agent facade 使用任务本地 overlay，并在 +交付后发布符合条件的学习结果。 + +## `asr` + +专家 ASR 诊断与修正命令： + +```text +openbbq asr check [--workspace PATH] [--max-prob FLOAT] +openbbq asr batch [--workspace PATH] [--offset N] [--limit N] + [--only-unresolved | --all] [--max-prob FLOAT] +openbbq asr apply [--workspace PATH] DECISIONS.json +openbbq asr amend [--workspace PATH] AMENDMENTS.json +``` + +`check` 与 `batch` 暴露确定性问题；`apply` 记录显式 issue decision；`amend` 在没有 +detector issue ID 时应用有界上下文 phrase correction。正常 one-shot 任务只在 +`agent next` 返回例外 source-review action 时使用这些能力。 + +## `delivery` + +```bash +openbbq delivery check [--workspace PATH] [--to CODE] +``` + +原文、翻译证据、导出和烧录产物完整、当前、结构有效且非空前，命令会返回非零。 + +## `qa` + +```text +openbbq qa render +openbbq qa check +openbbq qa attest +``` + +这些是可选专家视觉证据命令，不属于默认 Agent 流程。单独 `render` 不代表已经进行 +视觉检查。 + ## `auth` ```bash diff --git a/website/content/docs/reference/troubleshooting.mdx b/website/content/docs/reference/troubleshooting.mdx index 843ea97..d12bfce 100644 --- a/website/content/docs/reference/troubleshooting.mdx +++ b/website/content/docs/reference/troubleshooting.mdx @@ -7,6 +7,7 @@ description: Recover from common installation, media, ASR, translation, export, ```bash openbbq doctor +openbbq --json agent next --workspace workspaces/demo openbbq --json status --workspace workspaces/demo ``` @@ -49,13 +50,16 @@ Interrupted model downloads retain a temporary file and resume when the server s ## GPU or native backend failure -The default is `--gpu`. Retry on CPU: +The default is `--gpu`. Native GPU work may fail only because an Agent ran it +inside a restricted sandbox. First rerun the exact command on the host. Retry +on CPU only after that host attempt fails and the `agent next` execution policy +permits fallback: ```bash openbbq transcribe --model large-v3-turbo --cpu --workspace workspaces/demo ``` -Native GPU backends may fail inside restricted sandboxes even when they work in a normal terminal. Run transcription in a regular user environment before concluding that the backend is broken. +Do not treat a sandbox GPU failure as evidence that the accelerator is broken. ## FFmpeg missing or subtitle filters unavailable @@ -104,10 +108,36 @@ openbbq auth browser-login youtube ## Incomplete translation ```bash -openbbq translate check zh --workspace workspaces/demo +openbbq --json agent next --workspace workspaces/demo ``` -Fill the reported ids and recheck. Use `--allow-missing` only for an intentional draft that should fall back to source text. +The facade returns the current lease or the next missing batch. Do not invent a +new batch or edit Agent session state. Expert atomic workflows can still use +`openbbq translate check zh` and fill the reported ids. + +## The Agent stopped before `done` + +Continue in the same workspace: + +```bash +openbbq --json agent next --workspace workspaces/demo +``` + +Repeated `next` is safe and returns the same active lease. Continue after every +successful command or apply until `done` reports `terminal: true`. + +## A mechanical command was called twice + +Fetch, extract, transcribe, and segment use workspace execution leases. A +second call waits for the active stage and returns `reused: true` when the fresh +artifact already exists. This prevents duplicate Agent or harness polling from +corrupting the workspace. + +## `agent apply` rejects a response + +Use the exact response schema, `batch_id`, `policy_hash`, and complete selected +ID set from the current `agent next`. If source or worksheet content changed, +discard the old response and request the next action again. ## Worksheet no longer matches cues @@ -124,6 +154,13 @@ openbbq export --to zh --mode bilingual --format ass --workspace workspaces/demo openbbq burn --workspace workspaces/demo ``` +For the default workflow, do not assemble these commands manually. Continue +until `agent next` returns `finish`, then run its returned `agent finish` command +once. + ## Stale running stage -`status` marks running work stale after 60 seconds without a heartbeat. Confirm that no process is still active, inspect its stderr/logs, then rerun the affected command. Rerunning updates that stage and invalidates dependent downstream state. +`status` marks running work stale after 60 seconds without a heartbeat. Confirm +that no process is still active, inspect its stderr/logs, then call `agent next` +for the authoritative recovery action. Do not delete locks or hand-edit the +manifest. diff --git a/website/content/docs/reference/troubleshooting.zh.mdx b/website/content/docs/reference/troubleshooting.zh.mdx index 69da9de..901ba34 100644 --- a/website/content/docs/reference/troubleshooting.zh.mdx +++ b/website/content/docs/reference/troubleshooting.zh.mdx @@ -7,6 +7,7 @@ description: 恢复常见的安装、媒体、ASR、翻译、导出和烧录失 ```bash openbbq doctor +openbbq --json agent next --workspace workspaces/demo openbbq --json status --workspace workspaces/demo ``` @@ -49,13 +50,15 @@ openbbq transcribe --model large-v3-turbo --auto-download ## GPU 或原生后端失败 -默认使用 `--gpu`。可以改用 CPU： +默认使用 `--gpu`。原生 GPU 任务可能只是因为 Agent 在受限 sandbox 内运行而失败。先在 +宿主环境原样重跑命令；只有宿主尝试失败，并且 `agent next` execution policy 允许时， +才改用 CPU： ```bash openbbq transcribe --model large-v3-turbo --cpu --workspace workspaces/demo ``` -原生 GPU 后端可能只在受限 sandbox 中失败。请先在普通用户终端运行转录，再判断后端本身是否损坏。 +不能把 sandbox 内的 GPU 失败当作加速器损坏的证据。 ## 缺少 FFmpeg 或字幕 filter @@ -104,10 +107,33 @@ openbbq auth browser-login youtube ## 翻译未完成 ```bash -openbbq translate check zh --workspace workspaces/demo +openbbq --json agent next --workspace workspaces/demo ``` -填写报告中的 id 后重新检查。只有明确需要未翻译 cue 回退到原文的草稿时，才使用 `--allow-missing`。 +Facade 会返回当前 lease 或下一个缺失批次。不要自行创建新批次，也不要编辑 Agent +session。专家原子流程仍可运行 `openbbq translate check zh` 并填写报告中的 ID。 + +## Agent 在 `done` 前停止 + +在同一个 workspace 继续： + +```bash +openbbq --json agent next --workspace workspaces/demo +``` + +重复 `next` 是安全的，会返回同一个活动 lease。每次 command 或 apply 成功后继续， +直到 `done` 报告 `terminal: true`。 + +## 机械命令被重复调用 + +Fetch、extract、transcribe 与 segment 使用 workspace execution lease。第二次调用会等待 +活动阶段；新鲜产物已经存在时返回 `reused: true`。这可以避免 Agent 或 harness 重复 +轮询破坏 workspace。 + +## `agent apply` 拒绝响应 + +使用当前 `agent next` 返回的精确 response schema、`batch_id`、`policy_hash` 和完整 +selected ID 集合。Source 或 worksheet 已变化时，丢弃旧响应并重新请求下一步。 ## 工作表不再匹配 cues @@ -124,6 +150,11 @@ openbbq export --to zh --mode bilingual --format ass --workspace workspaces/demo openbbq burn --workspace workspaces/demo ``` +默认工作流不要手工拼装这些命令。持续运行到 `agent next` 返回 `finish`，再只执行一次 +其中返回的 `agent finish`。 + ## Stale running 阶段 -Running 工作超过 60 秒没有心跳时，`status` 会标记 stale。确认没有进程仍在运行，检查 stderr/日志，然后重跑对应命令。重跑会更新该阶段，并使依赖的下游状态失效。 +Running 工作超过 60 秒没有心跳时，`status` 会标记 stale。确认没有进程仍在运行并检查 +stderr/日志，然后调用 `agent next` 获取权威恢复 action；不要删除 lock 或手工编辑 +manifest。 diff --git a/website/content/docs/reference/workspace.mdx b/website/content/docs/reference/workspace.mdx index 718b3fd..31d5754 100644 --- a/website/content/docs/reference/workspace.mdx +++ b/website/content/docs/reference/workspace.mdx @@ -17,13 +17,12 @@ workspace/ ├── transcript.json ├── cues.json ├── translation.zh.json -├── review.zh.json -├── .openbbq/review/ -│ ├── journal.json -│ ├── checkpoints/ -│ └── cache/ +├── .openbbq/ +│ ├── agent-session.zh.json +│ ├── glossary-overlay.json +│ ├── artifacts.json +│ └── review/ # only after browser review └── out/ - ├── en.srt ├── zh.ass └── zh-burned.mp4 ``` @@ -60,13 +59,36 @@ Translation worksheets and exports depend on cue identity. Rerunning segmentatio ## `translation..json` -One editable worksheet per target language. The file intentionally keeps unfilled targets as `null` so humans and agents can discover remaining work. Use `translate apply` for controlled batch updates and `translate check` for integrity. +One editable worksheet per target language. The current `translation@2` schema +includes a reproducible translation brief in addition to cue ids, source text, +targets, timing, budgets, and glossary context. The Agent facade updates it in +hash-bound batches of at most 20 cues. + +## Agent session and glossary overlay + +`.openbbq/agent-session..json` stores the active lease, translation +evidence bound to cue/policy/glossary hashes, finish state, and warnings. It is +workflow state maintained by OpenBBQ, not a file to hand-edit. + +`.openbbq/glossary-overlay.json` records task-local entries, evidence, and +glossary candidates. It identifies the base glossary but does not modify the +global library until delivery succeeds. + +`.openbbq/artifacts.json` records export and burn provenance. Delivery uses it +to reject stale or mismatched outputs and to make a fresh finish idempotent. ## Review state -`review..json` (or `review.source.json` for source-only review) uses the `openbbq/review@1` schema and stores per-cue status, notes, content fingerprints, the selected target language, and revision metadata. It does not duplicate subtitle text. Review edits keep `cues.json` and all translation worksheets aligned. Mutations use recoverable checkpoints and a cross-file journal; undo and redo are also available during the active review session. +Professional review is optional. `review..json` (or +`review.source.json`) uses the `openbbq/review@1` schema and stores per-cue +status, notes, content fingerprints, the selected target language, and revision +metadata. It does not duplicate subtitle text. A complete current review is the +evidence for `quality: "human-reviewed"`. -`.openbbq/review/` contains recoverable transaction checkpoints, the current journal, the single-editor lock, and derived waveform/proxy caches. These files are implementation state rather than authored subtitle content. +`.openbbq/review/` contains recoverable transaction checkpoints, the current +journal, the single-editor lock, and derived waveform/proxy caches. These files +appear only after using the review UI and are implementation state rather than +authored subtitle content. ## `out/` diff --git a/website/content/docs/reference/workspace.zh.mdx b/website/content/docs/reference/workspace.zh.mdx index 82f94c0..4f3a296 100644 --- a/website/content/docs/reference/workspace.zh.mdx +++ b/website/content/docs/reference/workspace.zh.mdx @@ -17,13 +17,12 @@ workspace/ ├── transcript.json ├── cues.json ├── translation.zh.json -├── review.zh.json -├── .openbbq/review/ -│ ├── journal.json -│ ├── checkpoints/ -│ └── cache/ +├── .openbbq/ +│ ├── agent-session.zh.json +│ ├── glossary-overlay.json +│ ├── artifacts.json +│ └── review/ # 仅在浏览器审核后出现 └── out/ - ├── en.srt ├── zh.ass └── zh-burned.mp4 ``` @@ -60,13 +59,31 @@ ASR 输出，包括检测或指定的语言、媒体时长、后端/模型信息 ## `translation..json` -每个目标语言一个可编辑工作表。未填写 target 会显式保留为 `null`，便于人和 Agent 发现剩余工作。使用 `translate apply` 控制分批更新，使用 `translate check` 检查完整性。 +每个目标语言一个可编辑工作表。当前 `translation@2` schema 除 cue ID、原文、target、 +时间、预算与 glossary 上下文外，还包含可复现的翻译 brief。Agent facade 以每批最多 +20 条、绑定 hash 的方式更新它。 + +## Agent session 与 glossary overlay + +`.openbbq/agent-session..json` 保存活动 lease、绑定 cue/policy/glossary hash 的 +翻译证据、finish 状态与 warnings。它由 OpenBBQ 维护，不应手工编辑。 + +`.openbbq/glossary-overlay.json` 保存任务本地条目、证据与 glossary candidate，并记录 +base glossary；成功交付前不会修改全局库。 + +`.openbbq/artifacts.json` 保存 export 与 burn provenance。Delivery 依靠它拒绝 stale 或 +不匹配的产物，并让仍然新鲜的 finish 幂等返回。 ## 审核状态 -`review..json`（仅原文审核时为 `review.source.json`）使用 `openbbq/review@1` schema，保存每条 cue 的状态、备注、内容指纹、当前目标语言和 revision 元数据，不重复保存字幕正文。审核修改会保持 `cues.json` 与所有翻译工作表对齐。变更通过可恢复的 checkpoint 与跨文件 journal 写入；当前审核会话中也支持撤销和重做。 +专业审核是可选路径。`review..json`（仅原文审核时为 `review.source.json`）使用 +`openbbq/review@1` schema，保存每条 cue 的状态、备注、内容指纹、当前目标语言和 +revision 元数据，不重复保存字幕正文。完整且当前的审核是 +`quality: "human-reviewed"` 的证据。 -`.openbbq/review/` 保存可恢复的事务 checkpoint、当前 journal、单编辑者锁和派生 waveform/proxy 缓存。这些属于实现状态，不是用户编写的字幕正文。 +`.openbbq/review/` 保存可恢复的事务 checkpoint、当前 journal、单编辑者锁和派生 +waveform/proxy 缓存。它只会在使用 review UI 后出现，属于实现状态，不是用户编写的 +字幕正文。 ## `out/` diff --git a/website/src/components/home-page.tsx b/website/src/components/home-page.tsx index fbd6a29..5eec3e8 100644 --- a/website/src/components/home-page.tsx +++ b/website/src/components/home-page.tsx @@ -4,62 +4,61 @@ type Locale = "en" | "zh"; const copy = { en: { - eyebrow: "Open-source video translation", + eyebrow: "One prompt. Editable output.", title: "Turn video into bilingual subtitles.", lede: - "A resumable command-line workflow for transcription, translation, subtitle export, and hard-subtitle burning.", + "Give your Agent a video. OpenBBQ keeps the workflow deterministic and returns an editable bilingual subtitle draft plus a hard-subtitled video.", start: "Getting started", github: "View on GitHub", install: "Install with uv", - workflow: "Workflow", + workflow: "Ask your Agent", + prompt: "Make this video into a bilingual Chinese-English subtitled video: https://www.youtube.com/watch?v=...", workspace: "Workspace output", inspectEyebrow: "Inspectable by default", - inspectTitle: "Each stage leaves an artifact you can review.", + inspectTitle: "A useful first draft, with every artifact left editable.", reference: "CLI reference", stages: [ ["Source", "Fetch a URL or use a local video.", "media/audio.16k.wav"], - ["Transcribe", "Create a timed source transcript.", "transcript.json"], - ["Translate", "Review an editable target worksheet.", "translation.zh.json"], - ["Export", "Write subtitles or a burned video.", "out/zh.ass"], + ["Transcribe", "Create and validate a timed source transcript.", "transcript.json"], + ["Translate", "Process at most 20 aligned cues per Agent batch.", "translation.zh.json"], + ["Deliver", "Export ASS and burn the video once.", "out/zh-burned.mp4"], ], agentsEyebrow: "Built for agents and people", agentsTitle: "Automate the routine. Keep every artifact editable.", agentsBody: - "Commands are composable, progress is recorded in the workspace, and interrupted stages can be resumed without hiding the intermediate files.", + "The Agent follows one authoritative next-action interface. Leases, hashes, timing checks, and artifact provenance keep the run resumable without hiding intermediate files.", agentsLink: "See the workflow model", }, zh: { - eyebrow: "开源视频翻译工具", + eyebrow: "一句提示词，产物始终可编辑", title: "把视频制作成双语字幕。", - lede: "一套可恢复的命令行工作流，覆盖转录、翻译、字幕导出与硬字幕烧录。", + lede: "把视频交给 Agent。OpenBBQ 负责确定性工作流，返回可编辑的双语字幕底稿和烧录后的视频。", start: "开始使用", github: "在 GitHub 查看", install: "使用 uv 安装", - workflow: "工作流", + workflow: "发送给 Agent", + prompt: "帮我把这个视频制作成中英双语字幕视频：https://www.youtube.com/watch?v=...", workspace: "Workspace 产物", inspectEyebrow: "默认可检查", - inspectTitle: "每个阶段都会留下可供检查的产物。", + inspectTitle: "先得到可用底稿，并保留每一份可编辑产物。", reference: "CLI 参考", stages: [ ["输入", "下载在线视频或使用本地视频。", "media/audio.16k.wav"], - ["转录", "生成带时间轴的原文转录。", "transcript.json"], - ["翻译", "检查并编辑目标语言工作表。", "translation.zh.json"], - ["导出", "输出字幕文件或烧录后的视频。", "out/zh.ass"], + ["转录", "生成并校验带时间轴的原文转录。", "transcript.json"], + ["翻译", "Agent 每批处理不超过 20 条对齐 cue。", "translation.zh.json"], + ["交付", "只导出一次 ASS，并只烧录一次。", "out/zh-burned.mp4"], ], agentsEyebrow: "为 Agent 和人而设计", agentsTitle: "让自动化处理重复工作，让产物始终可编辑。", agentsBody: - "命令可以自由组合，进度会记录在 workspace 中；中断后可以继续执行，同时保留所有中间文件。", + "Agent 只遵循一个权威的下一步接口。Lease、hash、时间轴检查和产物 provenance 让流程可恢复，同时保留所有中间文件。", agentsLink: "了解工作流模型", }, } as const; -const commands = [ - "openbbq init --workspace workspaces/demo ./video.mp4", - "openbbq transcribe --workspace workspaces/demo", - "openbbq segment --workspace workspaces/demo", - "openbbq translate init --workspace workspaces/demo --target-language zh", - "openbbq export --workspace workspaces/demo --target-language zh --format ass", +const setupCommands = [ + "uv tool install 'openbbq[whispercpp]'", + "openbbq skill install --agent all", ]; const artifacts = [ @@ -68,7 +67,10 @@ const artifacts = [ "transcript.json", "cues.json", "translation.zh.json", + ".openbbq/agent-session.zh.json", + ".openbbq/glossary-overlay.json", "out/zh.ass", + "out/zh-burned.mp4", ]; export function HomePage({ locale }: { locale: Locale }) { @@ -95,13 +97,13 @@ export function HomePage({ locale }: { locale: Locale }) {
{text.install}
- uv tool install 'openbbq[whispercpp]' +
    + {setupCommands.map((command) =>
  1. {command}
    2. )} +
{text.workflow}
-
    - {commands.map((command) =>
  1. {command}
    2. )} -
+ {text.prompt}
{text.workspace}