Workflow Model

OpenBBQ has two complementary interfaces:

• the Agent facade is the default for one-prompt subtitle drafts;
• atomic commands remain available for professional editing, diagnosis, and explicit manual workflows.

One authoritative next action

An Agent initializes once:

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

It then repeatedly asks for the next action:

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

agent next returns one of these actions:

Semantic responses are applied atomically:

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

Leases and bounded batches

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.

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. It also includes a generation_policy: the driving Agent generates the wording from the supplied source, context, glossary, and rules, then echoes the requested generation_mode when applying the batch. External translation services and automatic translation scripts are outside this contract.

Mechanical command execution

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.

If the execution tool returns a process or session id, keep polling that same process until it exits. Empty output or an outer tool ending is not permission to start the command again.

Source correction and glossary learning

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.

Some cues include compact reference_evidence when a local phrase disagrees with an available timed caption. Treat it as a hint, not canonical source. Ordinary ambiguity should produce a warning; it should not trigger a web search, a second recognizer run, or a speculative rewrite.

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.

Finish and delivery

agent finish requires current translation evidence, exports out/zh.ass, burns out/zh-burned.mp4, runs the delivery gate, and publishes eligible glossary learning. It chooses fansub for landscape video and mobile for portrait video. Fresh completed artifacts make finish idempotent.

The automatic result reports quality: "draft" and human_reviewed: false. A complete current review made with openbbq review changes the quality to human-reviewed.

Workspaces and recovery

All state belongs to one workspace. manifest.json records mechanical stages; .openbbq/agent-session.<lang>.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.

The facade does not run visual QA and does not automatically choose fansub-compact. Expert atomic commands are documented in the CLI reference.