Architecture: versioned AI-director workflow with native video understanding and multitrack editing

[zhuqingyv]

Architecture: versioned AI-director workflow with native video understanding and multitrack editing

Problem

Dirox 不是“带聊天框的剪辑器”，而应是一个能贯穿短视频生产全流程的 AI 导演：

1. 写文案
2. 设计镜头
3. 导入本地素材，并通过网络搜索、AI 生图、AI 生视频补充素材
4. 生成和编辑字幕
5. 在多视频、多音频、多字幕轨道中剪辑
6. 与主 Agent 讨论成片，继续修改任意前序阶段

用户必须能在任何阶段与主 Agent 讨论、反复修改，并且可以撤销、比较和回到此前版本。因此聊天记录不能成为项目状态；文案、镜头、素材、字幕和时间线必须是带版本与来源的结构化对象，Agent 只能通过可验证的操作修改它们。

第一条商业验证路径使用真实的“800 元工程师版本啤酒打泡器”短视频完成 dogfood，目标不是先做一个 Premiere 替代品，而是验证 Dirox 能否明显降低从素材到可发布初稿、以及从反馈到改稿的时间。

Evidence

• 当前仓库只有 README、LICENSE 和 .gitignore，没有现成架构、编辑引擎或可复用的项目状态模型；这是父级架构任务，实施状态为 not attempted。
• DeepSeek API 支持 JSON Output 和函数调用，但官方也提示 JSON Output 可能出现空内容，函数参数仍需在应用端校验。因此它适合低成本文本推理和生成结构化修改提案，不应直接写项目文件或执行未经验证的命令：https://api-docs.deepseek.com/guides/json_mode/、https://api-docs.deepseek.com/api/create-chat-completion
• “原生接收视频”不等于“逐帧理解”。Gemini 官方文档说明默认按 1 FPS 采样，快速动作和快速转场可能丢失细节，所以通用视频大模型不能单独负责帧级剪点：https://ai.google.dev/gemini-api/docs/video-understanding
• Twelve Labs Pegasus 1.5 能直接分析视频并返回结构化、带时间戳的分段；Marengo 3.0 面向跨视觉、音频、文字的片段搜索，并能理解运动、音乐、静音和运镜，更贴近素材检索和导演语义：https://docs.twelvelabs.io/docs/concepts/models/pegasus、https://docs.twelvelabs.io/docs/concepts/models/marengo
• OpenTimelineIO 是行业化的剪辑决策交换模型，支持 clips、timing、tracks、transitions、markers 和 metadata，但不承载媒体本体，也不原生覆盖 Dirox 的 Agent 版本、字幕样式和素材生成来源：https://opentimelineio.readthedocs.io/en/latest/index.html
• MLT 是为非线性编辑器设计的多轨音视频引擎，能 author/manage/run 多轨 composition；FFmpeg 的 complex filtergraph 能完成多输入 overlay、amix 和确定性导出，但它不是交互式时间线状态模型：https://mltframework.org/、https://ffmpeg.org/ffmpeg.html#Complex-filtergraphs
• FunASR 的 Paraformer-zh 提供中英文识别与时间戳，配合 VAD、标点恢复可本地完成中文字幕基础链路；WhisperX 提供多语种词级时间戳和说话人分离，可作为多语种适配器：https://github.com/modelscope/FunASR/blob/main/README_zh.md、https://github.com/m-bain/whisperX

Architecture Direction

1. 技术栈决策

• 桌面端：TypeScript + Electron + React。Electron 只负责壳、UI、文件授权和任务调度；渲染、转码、ASR、视频分析运行在隔离的 utility/child process 中，避免阻塞 UI。
• MVP 不用 Rust 重写媒体栈。真正重的工作由 MLT、FFmpeg、ASR 和云端视频模型承担；只有性能测试证明某个自研模块成为瓶颈后，才允许用 Rust sidecar 替换该模块。
• 本地项目存储：SQLite 保存结构化状态、版本、任务和索引；媒体、代理文件、波形、缩略图和模型产物保存在项目工作区，并以内容哈希关联。
• 安全边界：renderer 禁止 Node integration，启用 context isolation 和 sandbox；preload 仅暴露细粒度、参数校验后的 IPC。参考 Electron 官方进程与隔离建议：https://www.electronjs.org/docs/latest/tutorial/process-model、https://www.electronjs.org/docs/latest/tutorial/context-isolation

2. 项目不是聊天记录，而是可版本化的 ProjectDocument

ProjectDocument 至少包含：

• Brief：目标受众、平台、时长、风格、商业目标
• Script：文案及修订版本
• ShotPlan：镜头、意图、预计时长、所需素材、与文案段落的关联
• AssetCatalog：本地/搜索/生成素材、许可、来源、提示词、模型、哈希和代理文件
• MediaAnalysis：转写、说话人、场景、动作、物体、运镜、音乐、情绪及时间范围
• Timeline：有理数时间、视频/音频/字幕轨道、clip/gap/transition/effect、mute/lock/visibility
• SubtitleTrack：cue、词级时间、说话人、语言、样式、来源与人工修改标记
• ReviewNote：绑定项目版本和时间范围的审片意见
• AgentRun：模型、成本、输入版本、提案、用户是否接受、应用后的版本

每次 AI 修改必须先生成符合 JSON Schema 的 ProjectPatch，通过业务规则校验后展示 diff；只有用户接受后才提交新 revision。所有 revision 支持 undo/redo、分支和对比。媒体文件保持不可变，编辑只保存引用和时间范围。

3. Agent 与模型路由

• DeepSeek / TextDirector：文案、镜头计划、搜索词、字幕润色、剪辑说明、审片意见归纳，以及生成 ProjectPatch。失败或空 JSON 要重试并回退，所有参数使用运行时 schema 校验。
• Twelve Labs / VideoIntelligence（首选）：Pegasus 负责整段视频理解、结构化分段和审片；Marengo 负责在素材库中按画面、声音、台词、动作和运镜搜索时刻。
• Gemini / VideoIntelligence（备选）：处理通用视频问答与供应商故障回退，但 UI 和产品承诺必须明确其采样精度限制。
• ASRProvider：中文默认本地 FunASR；多语种可选 WhisperX。模型输出先写入独立转写/对齐产物，再生成可编辑字幕轨，不允许重新识别覆盖用户手工修改。
• AssetProvider：统一封装网页搜索、图片生成、视频生成。所有结果必须保存来源 URL、许可状态或生成 provenance；未知版权素材不得默认进入可发布时间线。

模型路由以能力和成本为依据，而不是把供应商名写死在 UI：文本请求不上传视频；视觉问题优先复用已存在的分析和索引；只有确实需要重新理解媒体时才调用视频供应商。

4. 视频理解采用“双层精度”

不能接受“模型说 12.3 秒就直接切 12.3 秒”的实现。正确链路是：

1. 视频模型对整段素材做语义理解，输出候选片段和粗时间范围。
2. 本地 FFmpeg/ffprobe、场景切换检测、音频静音/VAD 和 ASR 词级时间戳建立精确时间锚点。
3. BoundaryRefiner 将模型候选范围吸附到最近的场景边界、词边界、静音边界或真实帧时间码。
4. Agent 生成剪辑提案并解释选择；用户接受后才写入时间线。

这不是用抽帧替代视频理解：整段视频语义仍由视频模型完成；本地逐帧/逐音频分析只承担确定性边界校准。

5. 多轨剪辑引擎

• Dirox 自己的 Timeline 是唯一产品状态；时间模型借鉴 OTIO 的 RationalTime、Track、Clip、Gap、Transition，并提供 .otio 导入/导出适配器。OTIO 不直接承担字幕样式、Agent provenance 或 Dirox effects。
• 首选执行后端为 MLT：TimelineCompiler 将项目时间线编译为 MLT composition，用于多轨预览和最终合成，避免从零实现 NLE 引擎。
• FFmpeg 保留为基础设施和回退后端：格式探测、代理生成、波形/缩略图、精确切片、转码，以及 MLT 不可用时的确定性导出。
• 在 Phase 0 用同一组测试时间线对 MLT 与 FFmpeg backend 做打包、预览延迟、A/V 同步、导出一致性和许可验证。如果 MLT 无法满足跨平台打包门槛，则保留同一 TimelineCompiler 接口，MVP 改用 FFmpeg export + 代理预览，不改变项目模型。
• 字幕始终是独立轨道，可并存原文、校对版、翻译版和包装字幕；支持 SRT/WebVTT/ASS 适配，导出时可选择软字幕或烧录。

6. 主 Agent 贯穿全部阶段

Agent 对话始终绑定 project_id + revision_id + current_view + selected_entities。因此用户可以在任何阶段提出：

• “把开头改成更强的创业冲突，但不要改后半段”
• “第二个镜头换成电路板特写，并找一段能证明起泡效果的素材”
• “保留口播，把背景音乐降低 6 dB”
• “中文字幕短一点，同时生成英文字幕轨”
• “比较 v7 和 v9，解释为什么 v9 的前 3 秒更抓人”

Agent 先给出带时间码和对象引用的提案；项目变更与纯建议必须在 UI 上明确区分。

Reuse / Mature Solution

• 复用 Electron 的成熟桌面和进程模型，不在 MVP 为安装包体积引入 Rust/Tauri 的额外集成风险。
• 复用 MLT 的多轨 composition 能力和 FFmpeg 的媒体处理能力，不自研编解码器、滤镜图或多轨合成器。
• 复用 OTIO 的剪辑数据概念和交换格式，不自创不兼容的时间数学；Dirox 仅扩展自身确实需要的 Agent、字幕和素材来源字段。
• 复用 FunASR/WhisperX 的转写与时间对齐，不让视频大模型同时承担字幕精确对齐。
• 复用 Twelve Labs/Gemini 的视频理解，不自训练视频基础模型；通过 provider contract 和评测集避免供应商锁定。

许可门禁必须在打包前完成：OTIO 是 Apache-2.0；MLT core 为 LGPL-2.1；FFmpeg 的最终许可取决于构建参数，启用 GPL/nonfree 组件会改变分发义务；FunASR 代码与具体模型许可需分别检查。MVP 默认只分发许可清晰且可履约的二进制与模型。

Implementation Checklist

Phase 0 — 两周内消除最高风险

• 建立 10 个有人工标注的短视频评测样本：口播、快速产品演示、B-roll、音乐/环境声、快速转场。
• 实测 Twelve Labs Pegasus/Marengo 与 Gemini：语义检索、镜头描述、时间分段、中文理解、时延和单分钟成本。
• 实现最小 BoundaryRefiner spike：场景边界 + VAD/静音 + ASR 时间戳 + 帧时间码。
• 用包含 3 条视频、4 条音频、2 条字幕的同一时间线比较 MLT 与 FFmpeg backend。
• 验证 macOS 与 Windows 的引擎打包、启动、预览、导出和开源许可；形成 ADR，锁定 MVP backend。

Phase 1 — 项目状态与随时可聊

• 建立 Electron + React + TypeScript workspace，并隔离 renderer/main/media worker。
• 实现 SQLite workspace、ProjectDocument、schema migration、revision、undo/redo 和 diff。
• 实现 DeepSeek provider、结构化 ProjectPatch、schema 校验、成本记录和失败回退。
• 实现主 Agent 上下文绑定，使文案和镜头计划能在任意 revision 上讨论和修改。

Phase 2 — 素材与视频理解

• 实现本地素材导入、内容哈希、proxy、thumbnail、waveform 和 ffprobe metadata。
• 实现 VideoIntelligenceProvider，接入首选与备用供应商，并缓存 asset/index/analysis。
• 实现按画面、动作、声音、台词和运镜检索素材时刻。
• 实现 AssetProvider 与来源/许可/生成 provenance。

Phase 3 — 字幕与多轨时间线

• 实现 FunASR 中文链路和 WhisperX 多语种适配器。
• 实现多字幕轨 cue 编辑、词级时间、样式、翻译、人工修改保护和 SRT/VTT/ASS 交换。
• 实现多视频、多音频、多字幕轨 UI，以及 TimelineCompiler。
• 实现 BoundaryRefiner 正式版本和可解释的剪辑提案。

Phase 4 — 成片与审片闭环

• 实现代理预览、后台导出、进度、取消、重试和失败恢复。
• 将导出草稿送入视频理解 provider，生成绑定时间码的 ReviewNote。
• 支持用户接受/拒绝单条审片修改，并生成新 revision。
• 用啤酒打泡器项目完成 30–60 秒真实短视频 dogfood，记录首稿时间、人工操作时间、模型成本和修改轮次。

Validation

• 单元测试：时间换算、轨道覆盖、patch schema、revision、字幕 cue、来源/provenance、provider fallback。
• 契约测试：所有 provider 使用录制响应验证 schema、空响应、超时、限流、取消和重试；密钥不进入 fixture。
• Golden timeline：同一项目在两次导出中得到一致的时长、轨道布局、字幕时间和音频增益。
• 精度评测：人工标注视频上分别报告大模型粗分段误差与 BoundaryRefiner 后误差，不用“模型看懂了”替代数值。
• 桌面 E2E：导入素材 → 改文案 → 改镜头 → 生成字幕 → 生成多轨初剪 → 审片 → 接受修改 → 导出。
• 许可测试：对实际随安装包分发的 Electron、MLT、FFmpeg、字体、ASR 代码和模型生成 SBOM 与 notice；不得用项目主页许可代替实际二进制/模型许可。

Acceptance Criteria

• 用户可在六个阶段中的任意阶段对话；一次 Agent 修改只影响被引用对象，提交前可见 diff，提交后可撤销和比较 revision。
• 视频模型能处理整段素材并返回可追溯的语义片段；UI 同时显示 provider 粗范围和本地校准后的精确边界。
• 在评测集上，语义时刻 Top-3 recall ≥ 90%；有真实场景切换的边界校准到检测帧，口播词边界中位误差 ≤ 200 ms。未达到时不得宣传“精确剪辑”。
• 单一项目至少支持 3 个视频轨、4 个音频轨和 2 个字幕轨；支持顺序、裁切、移动、mute/lock/visibility，以及独立字幕开关。
• 预览与导出在 golden timeline 上视频位置误差 ≤ 1 帧、音频位置误差 ≤ 20 ms，字幕 cue 不逆序、不重叠到负时长。
• 中文字幕可本地生成并手工修改；重新识别、翻译或样式变更不会静默覆盖人工文本或时间校正。
• 所有搜索/生成素材都有来源或生成 provenance；许可未知的网络素材在导出前给出阻断性提示。
• 视频上传需要明确同意，并能查看和删除供应商 asset；默认不上传与当前任务无关的素材。
• 啤酒打泡器 dogfood 能从素材导入到 30–60 秒可审初稿，并完成至少一轮“按时间码审片 → 接受部分修改 → 新版本导出”；全流程记录时间和模型成本。

Acceptance Mapping

• apps/desktop：Electron 主进程、preload、React UI、项目/时间线/对话/审片界面
• packages/project-schema：ProjectDocument、ProjectPatch、revision 和 migrations
• packages/agent-runtime：主 Agent 上下文、能力路由、diff/approval、成本与审计
• packages/providers/*：DeepSeek、Twelve Labs、Gemini、FunASR、WhisperX、搜索与生成 provider
• packages/media-analysis：ffprobe、proxy、waveform、scene/VAD/silence、BoundaryRefiner
• packages/timeline：多轨时间模型、TimelineCompiler、OTIO adapter
• packages/engine-mlt / packages/engine-ffmpeg：预览与导出 backend
• packages/subtitles：字幕生成、编辑、翻译、样式与 SRT/VTT/ASS adapter
• packages/storage：SQLite、workspace、asset cache 和 job state
• packages/evals：视频理解、边界精度、golden timeline、成本与 dogfood 指标

Non-goals

• MVP 不追求 Premiere/Final Cut 的完整功能和第三方插件生态。
• MVP 不自研编解码器、通用特效引擎或视频基础模型。
• 不承诺任何通用视频大模型能独立给出帧级精确剪点。
• 不因“Rust 更快”而在没有 profile 证据时重写主应用。
• 不把聊天记录、FFmpeg 命令或 MLT XML 当作项目唯一真相。
• 不自动抓取并默认商用版权不明的网络素材。
• 不在用户确认前自动应用破坏性剪辑，也不在 MVP 自动发布到内容平台。