# 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 只负责受控媒体处理与客观检查。

## 当前文档

- [系统架构蓝图](docs/ARCHITECTURE.md)
- [领域模型与版本规则](docs/DOMAIN_MODEL.md)
- [MCP 与 HTTP API 契约](docs/MCP_API.md)
- [制片控制台产品结构](docs/CONTROL_CONSOLE.md)
- [资料库分类注册表](docs/LIBRARY_TAXONOMY.md)
- [本地 Web + Worker 运行形态](docs/DEPLOYMENT.md)（远程部署部分仅为休眠参考）
- [当前实施状态](docs/IMPLEMENTATION_STATUS.md)
- [商业化、费用与许可证备忘](docs/COMMERCIALIZATION.md)（非当前路线图或验收门槛）
- [实现路线图](docs/ROADMAP.md)
- [`AGENTS.md`](AGENTS.md)（代码库开发约束）
- [`prompts/production-agent.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 个子类只定义在一份[分类注册表](docs/LIBRARY_TAXONOMY.md)中；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。

完整范围与先后顺序见 [实现路线图](docs/ROADMAP.md)。

## 运行当前原型

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

```bash
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`](THIRD_PARTY_NOTICES.md)，完整部署变量见 [`.env.example`](.env.example)。

### 接入 MCP

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

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

```toml
[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`](.cursor/mcp.json)，同样连接 `http://127.0.0.1:4311/mcp`。先运行 `npm run studio`，再在 Cursor 里启用该 MCP。

本地 Streamable HTTP 可配置为：

```toml
[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；远程公网部署不是当前目标或待办。仓库保留的远程安全配置只作未来兼容参考，只有用户明确决定后才重新启用对应规划。

附加验收命令：

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

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