4.9 KiB
4.9 KiB
ADR-0007: AI 编辑交互——对话式剪辑作为预设插件
状态：已接受。日期：2026-09-01。来源：编辑器与 AI 交互能力整合决策；建立在 ADR-0002（命令协议）与 ADR-0005（预设插件）之上。
背景
编辑器需要与 AI 交互：用户用自然语言表达剪辑意图，AI 直接驱动时间线。Concat 没有对话式 AI 编辑（桌面引擎，AI 只能模拟 UI 操作，脆弱且不可测试）；影策因两个既有决策天然支持：
- 命令协议（ADR-0002）：时间线唯一修改入口是
{op, payload}序列化命令，单队列 apply、可撤销、可重放——AI 只需输出命令 JSON 即可驱动时间线，与人手势编辑完全同构。 - 插件化（ADR-0005）：AI 交互能力可作为预设插件注册（对话面板插槽 + 权限），不动核心。
- 既有资产：模型渠道已统一中转（
custom-channel-relay.ts//api/ai/custom）；画布侧已有云端 Agent 聊天 UI（canvas-cloud-agent-chat-ui.tsx、canvas-cloud-agent-panel.tsx、canvas-prompt-optimizer-drawer.tsx）；AI 字幕高亮纯函数层已存在（subtitle-highlight-*）。
决策
AI 编辑交互 = 预设插件 editor-ai-assistant
- 新增
ai-assistant贡献类型与ai.text/timeline.command/timeline.read权限；插件注册对话面板插槽（right 或弹层）。 - 对话面板复用云端 Agent 聊天 UI 的交互模式（流式输出、上下文面板、可停止），复用现有组件或同构实现，不复制不移植画布运行协议；编辑器上下文（时间线摘要）由本插件构造。
- AI 是时间线的一等公民编辑者：AI 命令与手势命令同构、同队列、同撤销栈。
AI 命令协议（受约束命令 JSON）
- LLM 输出受约束的命令序列 JSON：
{ commands: [{ op, payload }], reasoning?: string }，op必须来自命令白名单（editor-commands.ts注册的 ops），payload按 per-op schema 校验（新增ai-command-schema.ts，与命令 handler 同源维护）。 - 宿主 fail-closed：任一命令 schema 校验失败、op 未知、权限未声明，整批拒绝并返回错误给对话（不执行部分命令）；失败信息回填对话供 AI 自纠。
- 命令 schema 版本化（
aiCommandSchemaVersion）：模型演进或命令集变更时显式升级，避免 AI 输出与新命令集失配。
执行语义：默认直接执行 + 一键撤销，批量改动需确认
- 单条/少量命令（≤3 条）：解析校验通过后直接入队执行，撤销即回退（符合剪辑工具直觉，与手势编辑一致）。
- 批量改动（>3 条或涉及删除/整体重排）：先展示命令 diff 预览（将改哪些片段/轨道），用户点「应用」才入队。
- 所有 AI 命令与手势命令共享同一撤销栈，AI 误操作可逐批撤销，不留特殊回退路径。
AI 只读能力
- 对话可读时间线状态（
timeline.read）做分析问答（"这段节奏怎么样"、"哪里该剪"）；只读回答不需要timeline.command。 - 时间线摘要为结构化精简版（轨道/片段/时长/关键属性，不含媒体二进制），作为 AI 上下文输入；大对象不进 prompt。
素材层 AI 不重复决策
- 自动转写（ADR-0004）、AI 字幕高亮（既有能力接入）、AI 生成素材入轨（既有生成链路 + asset-ingest）不属于本 ADR 的对话式编辑范围；
editor-ai-assistant可聚合它们的入口，但各自能力边界与协议不变。
考虑过的方案
- AI 直接操作 DOM/UI（模拟点击拖拽）：脆弱、不可测试、与命令协议割裂；否决。
- AI 走后端执行编辑：网络往返破坏交互延迟，撤销/错误回填难做，且后端无时间线真相源；否决。
- AI 生成完整时间线整体替换：高风险（覆盖用户已有编辑），无 diff 预览；否决，只允许命令增量。
- AI 命令立即全量执行不确认：批量误操作无法挽回；否决，采用上述批量确认语义。
后果
- 命令 schema 成为 AI 与宿主的双契约：同一 schema 同时服务命令校验（宿主）与 LLM 提示词约束（AI 端）；
ai-command-schema.ts与命令 handler 同源维护，黄金文件测试扩展到 AI 命令序列。 - 编辑器获得 Concat 不具备的能力：自然语言驱动的时间线编辑，且与人编辑共享撤销/可测试/可重放语义。
- 新增预设插件使首版插件数从 7+2 变为 7+3（editor-ai-assistant 加入）；插件清单与权限矩阵同步更新。
- 上下文窗口与 token 成本受时间线摘要精简策略影响；摘要生成是纯函数（
timeline-summary.ts），可测试。 - 画布 agent 聊天 UI 与编辑器 AI 面板并存：两者共享模型渠道与交互模式，但不共享会话上下文（画布会话 ≠ 编辑器会话），避免会话串扰。