# 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 面板并存：两者共享模型渠道与交互模式，但不共享会话上下文（画布会话 ≠ 编辑器会话），避免会话串扰。