Agent Video Toolkit

供 Codex 等宿主平台使用的本地视频执行工具，版本 0.1.0。English

宿主平台理解原文并安排最多 4 名同岗员工，各自处理不同的相邻完整段落。每名员工都负责本段文意、解释画面、字幕图形、镜头包装及可运行的 Canvas 代码。工具负责冻结输入、领取与提交、校验、合并、逐帧执行、样帧和无声成片导出。

程序独立运行，不依赖 Studio、Core、账户服务器或私有二进制。执行流程没有模型 API、ASR、配音、素材生成和钱包调用。宿主平台自身的模型与额度由宿主管理。

安装与完整演示

需要 Python 3.11+、可执行的 ffmpeg 与 ffprobe（支持 libx264），以及 Playwright 安装的 Chromium。依赖和浏览器的首次安装需要联网。

git clone https://github.com/zhuyusong/agent-video-toolkit.git
cd agent-video-toolkit
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
.\.venv\Scripts\python.exe -m playwright install chromium

Linux/macOS 将解释器路径换成 .venv/bin/python；Linux 可使用虚拟环境中的 python -m playwright install --with-deps chromium 安装浏览器系统依赖。后文简写的 python 均指已安装本项目的虚拟环境解释器。把 FFmpeg 的 bin 放入 PATH，或设置两个可执行文件的绝对路径：

$env:AVT_FFMPEG = 'C:\tools\ffmpeg\bin\ffmpeg.exe'
$env:AVT_FFPROBE = 'C:\tools\ffmpeg\bin\ffprobe.exe'

在仓库根目录运行：

.\.venv\Scripts\python.exe -m agent_video --root runtime demo demo-output

演示目录必须尚不存在。该命令生成 4 秒、12 fps 的合成底片和明确标为 synthetic 的测试词钟，再完成四员工提交、320 像素宽派生预览、48 帧真实执行、编码、全解码及实际成片样帧提取。结束的 JSON 给出 video、receipt 和 samples 路径。示例没有用户数据或真实 ASR；synthetic_not_asr 会保留在任务和证明中。

只生成并准备输入可加 --prepare-only，随后由宿主完成任务。演示画面用于验证管线，不代表视频设计质量。

Related MCP server: video-agent-mcp

Codex 接入

按照 Codex 官方 MCP 文档，在 Codex 配置中注册 stdio 服务。解释器必须指向已安装本项目的虚拟环境，--root 使用专用的绝对目录。以下路径只是示例，需替换为本机位置：

[mcp_servers.agent_video]
command = 'C:\work\agent-video-toolkit\.venv\Scripts\python.exe'
args = ["-m", "agent_video.mcp_server", "--root", 'C:\work\agent-video-runtime']
env = { PYTHONIOENCODING = "utf-8", AVT_FFMPEG = 'C:\tools\ffmpeg\bin\ffmpeg.exe', AVT_FFPROBE = 'C:\tools\ffmpeg\bin\ffprobe.exe' }

也可用 CLI 注册：

codex mcp add agent_video -- C:\work\agent-video-toolkit\.venv\Scripts\python.exe -m agent_video.mcp_server --root C:\work\agent-video-runtime

服务进程需要继承可用的 FFmpeg 环境。其他支持本地 stdio MCP 的平台使用相同启动命令。

可以这样给宿主下任务：

读取已准备的项目，安排最多四名同岗员工分别处理相邻完整段落。每个人完成文意、解释状态、字幕图形、镜头包装和 Canvas 代码。遵守冻结的 visual_brief、真实 ASR 全局词钟和全部帧数。收齐后合并渲染，查看实际样帧和成片，再报告画面结论。

使用自己的输入

创建 project.json、真实最终 ASR 转录和对应文件。路径相对于清单所在目录，详见 输入和员工协议。

{
  "schema": "avt-project/v1",
  "source": "base.mp4",
  "audio": "recognition.wav",
  "transcript": "transcript.json",
  "assets": []
}

转录必须保存精确原文、毫秒词钟、段落的零基半开词范围，以及视频与识别音频的 SHA-256。词文本按顺序拼接必须与原文完全相同，包括标点与空格。ASR 在本工具外完成；不要把估时填成 kind: "asr"。caller_supplied_final_asr 只记录调用方的声明及文件摘要绑定，不证明识别来源真实性、识别准确性或口型同步。

等价 CLI 流程如下；将尖括号占位符替换成实际返回值：

python -m agent_video --root runtime projects
python -m agent_video --root runtime prepare project.json --visual-brief "按原文解释因果，保留人物，文字清晰克制" --workers 4
python -m agent_video --root runtime task <run_id> worker-1 --claimant worker-1
python -m agent_video --root runtime submit <run_id> worker-1 result.json --claim-token <claim_token>
# 每名员工分别 task / submit；全部完成后：
python -m agent_video --root runtime assemble <run_id>
python -m agent_video --root runtime render <run_id> --wait
python -m agent_video --root runtime status <run_id>

首次提交不传 --expected-sha256；修订时重新读取 task，并传 --expected-sha256 <previous_result_sha256>。同一个 claimant 可读取已领取的任务，其他 claimant 不能覆盖。请求渲染后结果冻结。重复调用 render 返回同一请求，包括失败状态；修改代码或从失败、中断重做需创建新运行。

prepare --preview-width 540 可实际生成更小的底片，宽度须是偶数且不超过源宽度。程序核验派生片帧率、完整帧数、时长与源一致，保留双源摘要及 clock_mapping: "identity"，不会把派生片标成原分辨率或新 ASR。

证明和当前边界

每次运行保存在独立的 runtime 子目录。输入和素材复制后绑定摘要；结果按内容摘要保留历史；跨进程锁和 CAS 保护提交；渲染独占锁防止同一运行重复执行。成功状态会核对证明和产物摘要。

渲染器读取实际源帧，每帧创建新的 Canvas Worker，按原全局帧序合并各员工程序，输出无声 H.264 MP4。证明记录输入、词钟、员工结果、派生源、执行帧序摘要、实测媒体及成片抽样。technical_execution_verified 和 full_decode_verified 是技术事实；quality_status 始终为 host_review_required。宿主仍需查看画面、文字、人物和视觉解释，不能从哈希或可解码性推断审美通过。

0.1.0 支持恒定帧率（1–120 fps）、从零开始的规则时间戳、方形像素、2–4096 的偶数宽高，以及最多 432,000 帧；非零旋转元数据会被拒绝。先在外部规范化不合格源，再把真实 ASR 绑定到最终源文件。所有输入 JSON 上限为 16 MiB。现有素材仅支持最多 16 张 PNG/JPEG 图片，每张不超过 20 MiB、1600 万像素。暂不提供额外视频 B-roll、透明人物抠像、配音或音频混合。

Canvas 执行的是宿主提交的 JavaScript。Worker、无网络页面和帧截止时间用于执行隔离及故障限制，不构成操作系统安全沙箱。只执行可信、审查过的代码；运行用户应有权读取输入文件并写入专用 runtime。字体取本机可用的 sans-serif，不同机器的排版可能不同；仓库不附带字体。

开发与许可

python -m pytest -m "not integration"
python -m pytest -m integration
python -m build

集成测试需要上述 FFmpeg 和 Chromium，实际执行渲染、样帧检查、失败防重放及 MCP stdio。详见 贡献说明 和 安全边界。

本项目新创作的自有代码采用 MIT：便于不同宿主集成、修改和分发，同时要求保留版权与许可文本。第三方依赖保留各自许可，见 THIRD_PARTY.md。仓库不发布用户视频、人像、会话、密钥、私有配置、第三方学习帧或未知许可字体。