AI Video Studio Agent

本目录把现有的本地 AI 视频生产工作流产品化为 Web 制片控制台 + HTTP 控制平面 + MCP 适配器 + 本地视频 Worker。真实出片闭环已通过人工批准和正式交付验收，MCP 已进入本地可用阶段。

设计蓝图基于只读盘点：

• 现有工程：../数字人自媒体开源 git hub/video-agent
• 代表性 production run：2026-08-10_kimi-k3-caught-up_v1
• 当前渲染边界：每个 Production 创建时固定选择 HyperFrames 或 Remotion 作为唯一完整时间轴引擎；两条任务链不互相调用。FFmpeg 只负责受控媒体处理与客观检查。

当前文档

• 系统架构蓝图
• 领域模型与版本规则
• MCP 与 HTTP API 契约
• 制片控制台产品结构
• 资料库分类注册表
• 本地 Web + Worker 运行形态（远程部署部分仅为休眠参考）
• 当前实施状态
• 商业化、费用与许可证备忘（非当前路线图或验收门槛）
• 实现路线图
• AGENTS.md（代码库开发约束）
• prompts/production-agent.md（产品运行时制片 Agent 合同）

核心原则

1. Project -> Production -> Revision -> Scene -> Shot -> Asset -> Job -> Review -> Delivery 是统一数据模型。
2. MCP、Web 控制台和未来的其他客户端只调用应用服务，不直接操作渲染目录。
3. Agent 生成提案；确定性编排器负责状态、依赖、审批、幂等、费用与失效传播。
4. 锁定的时间轴修订是人物、素材、动效、字幕和渲染共同的时间与语义来源。
5. HyperFrames 与 Remotion 是两个可独立复用的完整时间轴引擎；Production 固定使用其中一个，Shotcraft 只作为 Remotion 的本地镜头配方与声音参考库，FFmpeg 是受控媒体工具。
6. 所有外部调用、素材、生成结果和交付物必须可审计、可回看、可局部重跑。
7. 当前只以“本地独立应用真正好用、自动出片闭环稳定”为产品目标；上线、商业化、开源发行和公网 MCP 均不属于当前验收，是否启动由用户以后单独决定。

日常操作界面

Web 控制台按实际制作动作收敛为五步，不要求使用者先理解控制平面术语：

1. 项目：选择“剪一段现有素材”或“从选题生成完整视频”，并查看当前最安全的下一步；
2. 自动初剪：导入素材、分析母带，或填写选题并生成可审片首版；
3. 正文剪辑：校对、查找替换、拆分合并句段、恢复历史修订，并按明确提案生成不覆盖母带的剪辑副本；
4. 审片修改：播放冻结 Preview、定位 Scene、记录修改单、对比版本和局部重建；
5. 导出交付：只展示通过精确 Preview 审批门禁后的正式产物和交付下载。

界面只保留一条持续可见的五步制作轨，底部是导演场记条：对整片或某一场说一句短指令，只会生成新草案。项目首页把下一步、两个真实开始入口和成片气质放在首屏。正文与审片保留专业工作台结构；390px 窄屏使用可横向浏览的步骤轨与精简顶部操作。

MCP、Worker、DAG、Timeline Revision、内容哈希、Provider 状态、任务日志、额度和审计记录仍完整保留，但统一收进“高级信息”。打开高级信息只改变显示层级，不改变状态机或审批规则。自动初剪、普通对话和 Preview 成功都不会创建正式渲染；正式渲染仍必须在审片室对当前精确 Preview 单独批准。

顶部“资料库”是跨 Production 的个人资产入口，逻辑上分为画面素材、知识证据、声音和动效配方四区。数字人、品牌、B-roll、优秀开场/结尾和官方证据是这些入口里的稳定子分类，不建立八套互不相通的数据库。四区与 21 个子类只定义在一份分类注册表中；Web 右侧“分类索引”抽屉显示每类 ID、含义、引擎边界和个人/共享实时数量。前三类共用 Workspace 级冻结存储、SHA-256 去重、标签/正文检索、可恢复归档和来源授权字段；每个资产保存稳定 categoryId。Agent 先经 MCP 读取同一分类表、按分类检索个人库，再考虑 Pexels/Pixabay；整个知识大类只支持文案、证据与复盘，不会被直接绑定为时间轴媒体。

当前可运行能力

当前 1.0 RC 已经把“选题研究 → 素材 → 自动初剪 → 控制台审片 → 局部修改 → 正式渲染 → 交付打包”串成可独立运行、可断点续跑的产品，并提供 MCP 本地 Beta：

• SQLite 本地持久化；DATABASE_URL 可切换到 PostgreSQL JSONB repository 与生产 migration；
• 本地文件或 S3-compatible 对象存储；远程 Worker 会通过受权 API 拉取冻结素材并回传生成素材/交付物；
• local/OIDC 两种认证模式、workspace principal、owner/producer/editor/reviewer RBAC、OAuth scope claim，以及独立 Worker service token；
• 创建 Production、时间轴 draft revision、锁定、审批、Job 与审计 API；
• Worker 注册、心跳、capability、幂等 Job 和租约；
• 受授权目录限制的 HyperFrames 工程安全预检、完整 check、冻结 draft 审片副本、可选 Studio preview 和审批门后的高质量 render；
• Worker 对 MP4 执行非空、媒体规格和 SHA-256 校验，控制平面通过受限 Range 接口播放与下载产物；
• 从选题、观众、平台、时长和画幅生成结构化 Creative Brief；规划器会按目标时长动态选择 2–7 个场景，短视频不再套用七段长脚本；
• 创建 Production 时选择 HyperFrames 或 Remotion；该选择进入不可变方案，控制台逐 Scene 编辑旁白、语义目的、画面指导、素材检索词、动效和呈现方式，但不允许混用或逐 Scene 偷换引擎；
• 内置 Apache-2.0 的 video-shotcraft 本地快照与可检索配方库；Remotion 项目可由控制台或 Agent 查看配方、样片与音效建议，并把精确 catalog revision、card、style 写入新方案修订，HyperFrames 项目确定性拒绝 Shotcraft 选择；快照随附的 5 首 BGM 和 149 个 SFX 通过安全试听接口显示在声音页，可按需加入个人声音库，其中 6 个来源记录不完整的文件始终标记为商用前复核；
• “我的制作偏好”把复盘结果先保存为待确认候选；只有用户明确确认后才晋升为可复用偏好，拒绝的候选保留审计记录，不让 Agent 依据一次修改擅自改变后续视频；
• 每次保存生成不可变 Production Plan Revision，方案锁定需要与内容哈希绑定的明确审批；
• 锁定方案按固定引擎提交 hyperframes.materialize 或 remotion.materialize Job，由 Worker 创建或安全更新专属工程；
• 自动写入 BRIEF.md、STORYBOARD.md、SCRIPT.md、Composition 和归属标记，并在交付给 Studio 前强制运行 check；
• hyperframes.assemble 使用本机 Tingting/Meijia/Sinji 旁白、FFmpeg AAC、确定性视觉底板和字幕时间，把工程骨架装配成可播放初剪；
• 每个冻结媒体写入 .media/manifest.jsonl、SHA-256、provider 与授权来源；旁白超预算时自动提高一次本地语速，仍超时则明确失败，不再静默把短视频扩成一分钟；
• 控制台“一键生成可审片初剪”会自动创建 Production、锁定本次草案、物化工程、装配本地媒体并启动 Studio，任务链记录在 SQLite 中；
• 内置一张完全虚构的合成数字人演示图，只用于首尾 avatar 场占位并明确标记“非实时口型”，不依赖第三方图库；
• 自动阶段失败后可在任务列表点击“重试并继续闭环”，在剩余 attempt 内从原阶段续跑；
• Agent 制片场记提供 Production 级“安全检查点”：即使单个 Job 已耗尽尝试次数，或服务在成功阶段与下游排队之间中断，也可一键创建幂等替代任务；已完成镜头和产物复用，方案与正式渲染 Approval 绝不被恢复动作跨越；
• 素材导入台支持拖入多个图片、视频、音频或整个文件夹，先做本机快速预检，再冻结 SHA-256、授权说明与 Scene binding；相同内容哈希只保存一次；
• Workspace 级“我的资料库”支持跨视频保存画面、知识和声音资产；图片/视频/音频及 PDF/TXT/Markdown/JSON 均可受控导入，文本类资料建立本地全文索引，所有 API 与 Agent 结果只返回安全句柄而不返回存储路径；
• 资料库素材可幂等引用到当前 Production，再通过素材柜绑定 Scene；知识文档被确定性拒绝进入时间轴，归档不删除文件，Shotcraft 配方和随附声音继续使用现有共享 catalog，只有用户选中的音频才冻结进个人声音库；
• 母带分析台通过受控 media.analyze Job 在本机读取真实规格、镜头切点和停顿，生成带分数的候选片段；找到本地 whisper-cli 与经过架构校验的多语言 GGML 模型时附带原声转写，否则清楚降级为画面/停顿选段且绝不自动下载模型。控制台可把受支持的模型安全导入固定 .data/models 目录，Worker 心跳会在数秒内刷新状态；
• 已有 SRT、VTT 或带时间戳的逐词 JSON 可作为冻结转写侧车附加到当前母带，下一次分析会按内容哈希信任该侧车并生成整句与疑似口癖建议；候选仍可试听、逐 Scene 绑定或显式自动填充，HyperFrames 装配使用冻结的精确入点；
• 正文剪辑器可试听并校对每个句段、合并相邻段，或只按冻结逐词时间点拆分；全文查找支持上一个/下一个匹配，全部替换只写入浏览器草稿，仍需点击“保存文字修订”，长文稿可按段落编号跳转；
• 每次保存都生成带父版本和内容哈希的不可变转写修订；可从历史选择旧文稿恢复，但恢复同样只会追加新修订并记录被恢复的 transcript ID，不覆盖任何旧版本。正文变化后旧分析提案会标为过期并要求重新分析；
• 同一分析还会产生可逐条试听的删停顿/疑似口癖/整句提案；只有控制台明确勾选的提案 ID 才能排队 media.cut，控制平面反查可信区间并计算保留段，Worker 用固定 FFmpeg 参数生成不覆盖母带的新视频副本，同时保存母带、分析 Job、决策和内容哈希来源链；
• Scene 覆盖轨逐场标明真实素材或本地占位，批量导入可按顺序绑定尚未覆盖的 Scene；正式装配仍由 Worker 使用 ffprobe 验证冻结媒体；
• 装配阶段会把上传的 BGM 派生为冻结的 -18 LUFS / -3 dBTP 本地 AAC，并以 0.32 音量置于旁白下方；派生哈希、原始素材 ID、授权和混音参数都写入媒体账本与 ASSEMBLY.json，避免低电平音乐被误判为静音；
• 支持 OpenAI-compatible 模型规划器，本地结构化规划器始终可用，auto 模式在模型失败时确定性回退；
• 支持带 URL、标题、发布方、时间和核验状态的 Research Packet；没有研究模型时只保存用户提供来源，不编造 claim；
• Pexels/Pixabay 语义 B-roll 适配器会在每版 Production Plan 生成后读取逐 Scene assetQuery，只为适合真实画面的 Scene 检索视频，按来源结果位次、画幅、分辨率和时长做确定性推荐；一键初剪默认冻结并绑定合格候选，已有真实素材不替换，无候选或未配置密钥时使用本地图形回退；每项素材保留 Provider asset ID、作者、来源页、检索词、许可提示与交付前 rights-review 标记；
• HeyGen V2 真实口型数字人适配器支持提交、轮询、停止本地等待、下载与冻结；未配置密钥时控制台明确显示不可用，静态合成演示图只作免费占位；外部任务已提交后不承诺能撤销 Provider 计费；
• Remotion 独立任务链为 remotion.materialize → remotion.preview → review → exact-preview approval → remotion.render → delivery；HyperFrames 链保持独立，二者不会相互嵌套；
• 每次成功 Preview 都生成带 SHA-256 的冻结 MP4 审片副本；控制台可直接播放、按 Scene 定位，并将当前与上一可播放版本并排对比；
• Preview 完成后自动运行零密钥技术审片：每个 Scene 抽取 entry/mid/exit 三张冻结关键帧，并检测黑帧、静帧、静音、响度、时长、画幅、字幕安全区、文字溢出和主体遮挡；
• 每个生成工程写入 QUALITY_CONTRACT.json，冻结该版的发布安全区、字幕带、主体保护区和文字容量；HyperFrames check 同时启用 caption-zone 与媒体出框扫描，审片室按“字幕安全 / 文字可读 / 主体避让”显示结果；
• macOS 本地 Worker 使用 Apple Vision 核对关键帧中的实际字幕与冻结 cue 文本，跳过 Scene 转场后的字幕首帧以避免边界假阳性；OCR 工具从仓库内源码编译并按哈希缓存，不联网；非 macOS 明确显示不可用但不阻断其他检查；
• “生成旁白、字幕与初剪”每次主动点击都会生成新的幂等请求，可在 Plan 不变时重新应用升级后的模板与质量规则；
• 自动审片会对静音/旁白节奏、响度、黑帧/冻结画面、字幕安全区和文字溢出等确定性问题执行最多两轮零付费安全修复，并自动重新生成 Preview 与复检；相同问题不改善、达到轮次上限或涉及语义/创意判断时立即停止并转人工。语义建议仍只作为提案，所有修复片次和停止原因保留审计记录；
• 本地旁白会在不改变已批准文案和 Scene 时长的前提下逐 Scene 自适应语速，优先填满叙事节奏并避免因短文案产生长静音；
• 可选 OpenAI-compatible 视觉模型对照旁白、语义目的、画面指导和禁止误读进行语义审片；只有用户明确点击并确认外部费用后才发送低清关键帧；未配置 REVIEW_MODEL_API_URL、REVIEW_MODEL_API_KEY、REVIEW_MODEL 时，全部确定性检查仍可用；
• 审片项绑定 Preview、Scene 和秒级时间点，未解决的修改单会阻止正式渲染；
• 审片项可绑定帧号和画面矩形；Program Monitor 可直接拖出批注区域；
• 正式帧时间轴支持 Scene 拖拽排序和右侧拉伸，保存为不可变 Timeline Revision；Plan Revision 可视 diff；
• Job 提供单调进度、日志尾部、取消请求和 Worker 子进程 Abort；控制台显示进度条并可取消运行任务；
• Scene 局部重建只在当前 Production 的固定引擎内重做受影响内容，再自动生成新控制台审片版本；
• 正式渲染成功后自动生成包含 MP4、SRT、锁定 Plan、媒体台账和 manifest 的交付压缩包；
• 自动写入 motion sidecar，检查首场入场顺序、画面范围，并在 Studio 审片批准后才允许正式渲染；
• 可创建 Production、切换项目、修订时间轴、审批和查看任务的 Web 控制台；
• 控制台“视频项目”按最近活动和当前动作整理 Production，支持标题/ID 搜索、状态分组，以及不删除任何工程或产物的可恢复归档；运行中的 Production 会拒绝归档；
• 控制台提供 Agent 制片场记：从同一套 Job、Approval 与 AuditEvent 实时投影六段闭环、当前动作、自动质检修复片次/规则、精确方案/预览 hash、MCP 工具来源和阻塞原因，服务重启后无需重建第二套状态；
• workspace entitlement、配额与 usage ledger 会在高成本作业前阻断超额调用，并在控制台展示；
• 旧 state.json、timeline contract 和 manifests 导入器。
• 官方 MCP TypeScript SDK 2.0 的 stdio 与 stateless Streamable HTTP；30 个工具和 3 个资源模板按 OAuth scope 过滤，其中包含统一资料库分类表读取、个人资料检索/引用、语义 B-roll、HyperFrames/Shotcraft 动效查询/选择、成片气质确认、导演指令草案和经验复盘/确认工具；运行时 instructions 从版本化制片 Agent 合同加载；入口按 workspace 限流；get_review 返回当前锁定方案的冻结审片、自动 QC、字幕 OCR 与安全关键帧 URL；MCP 输出不包含工程/存储路径或 Worker 日志；正式渲染必须单独请求并明确决定 exact preview hash 的 Approval。

完整范围与先后顺序见 实现路线图。

运行当前原型

当前原型要求 Node.js 24 或更高版本：

npm install
npm run check
npm run audit:prod
npm run studio

也可双击 start-local.command。浏览器打开 http://127.0.0.1:4310。统一启动器会创建 .data/projects 与 .data/assets，同时启动 API、MCP Streamable HTTP（http://127.0.0.1:4311/mcp）和 Worker，并在退出时一起关闭。数据保存在 .data/studio.db。

Worker 当前实现独立的 hyperframes.preflight/doctor/check/materialize/assemble/preview/render 与 remotion.materialize/preview/render，以及 experience.distill、avatar.generate 和 delivery.package。所有操作映射到固定参数，不暴露任意 Shell。Shotcraft 的许可证和归属见 THIRD_PARTY_NOTICES.md，完整部署变量见 .env.example。

接入 MCP

本地 Codex/ChatGPT Desktop/IDE 可直接使用项目内的 Streamable HTTP 配置；需要由客户端独立拉起 MCP 时再使用 stdio。两种方式都不需要把服务公开到互联网：

项目已经包含 .codex/config.toml。在受信任项目中启动 Codex 后，它会连接正在运行的本地 Streamable HTTP 服务；读取工具自动执行，写工具按 writes 策略提示确认。该文件只作用于本项目，不修改全局 Codex 配置。

[mcp_servers.video_studio]
command = "node"
args = ["/absolute/path/to/自建视频剪辑项目/apps/mcp/src/stdio.ts"]
cwd = "/absolute/path/to/自建视频剪辑项目"
default_tools_approval_mode = "writes"
tool_timeout_sec = 120

[mcp_servers.video_studio.env]
MCP_CONTROL_PLANE_URL = "http://127.0.0.1:4310"
MCP_PROJECT_ROOT = "/absolute/path/to/自建视频剪辑项目/.data/projects"

Cursor 使用项目内 .cursor/mcp.json，同样连接 http://127.0.0.1:4311/mcp。先运行 npm run studio，再在 Cursor 里启用该 MCP。

本地 Streamable HTTP 可配置为：

[mcp_servers.video_studio_http]
url = "http://127.0.0.1:4311/mcp"
default_tools_approval_mode = "writes"

先运行 npm run studio；也可分别运行 npm run mcp:stdio 或 npm run mcp:http。npm run mcp:smoke 使用官方客户端执行只读联调，npm run mcp:review-smoke 真实验证当前方案的自动 QC、OCR、关键帧 URL 与路径脱敏，npm run mcp:multiclient 并发验证两个官方 SDK client profile 和两个 JSON-RPC 协议版本。设置 SMOKE_TARGET_ROOT 后运行 npm run e2e:quality-repair，会用一条 15 秒免费数字人占位片验证首轮 QC → 安全重剪 → 新 Preview → 自动复检，并确认未创建正式渲染批准。npm run mcp:agent-e2e 会只经 MCP 创建一条 15 秒免费数字人占位 Production，并在精确方案 hash 与精确预览 hash 两个门禁分别停下；只有把脚本打印的 Approval ID 和完整 hash 作为环境变量重新运行，才会继续初剪或正式渲染。当前只验收本机 stdio 与 loopback HTTP；远程公网部署不是当前目标或待办。仓库保留的远程安全配置只作未来兼容参考，只有用户明确决定后才重新启用对应规划。

附加验收命令：

npm run e2e:providers-media
E2E_API_MODEL=true npm run e2e:providers-media

第一条先验证本地 HTTP 模型 Stub 协议并用本地规划执行完整闭环；第二条要求当前服务已配置测试用 OpenAI-compatible endpoint，并进一步断言模型规划来源已经持久化到 Production Plan。两条都会把仓库内生成的真实 MP4 与 WAV 走完整自动初剪链，不会调用付费外部服务。