# Quercus AI 剪辑助手 — 分阶段实施计划

> 本文是 [`ai-agent-design.md`](ai-agent-design.md)（设计）的**施工计划**（怎么做、
> 分几步、每步验收什么）。设计决策以设计文档为准，本文不重复论证，只把
> "一份宿主无关 AI core + 各宿主薄适配层"的结构落成可执行的阶段计划。
>
> **范围调整（相对设计文档）**：
> - 设计文档的落地形态原是 Oak 插件（`oak-plugin-ai`，依赖 OPP/1 与插件系统
>   P1–P4）。**Oak 插件系统仍在开发中**（见 `../../oak/docs/zh/plans/` 下的
>   `external-plugin-system.md` / `external-plugin-protocol.md`），因此本计划
>   **只做 DaVinci Resolve 与 Premiere Pro 两个宿主**；Oak 适配层**只预留接口
>   （stub 包），不实现、不排期**，等 OPP/1 P1–P3 落地后按 §8 启动。
> - 设计文档中"工具面 = OPP/1 方法映射"的表述，在本计划中改为"工具面 =
>   HostAdapter 接口映射"——接口形状**刻意对齐 OPP/1 方法族**，使未来的 Oak
>   适配层只是 oakxp SDK 的薄封装（§3.4）。
>
> 外部参考（实现时以官方最新文档为准）：
> - Resolve 脚本 API：<https://extremraym.com/cloud/resolve-scripting-doc/>（X-Raym 整理，
>   源自 Resolve 安装目录 `Developer/Scripting/README.txt`）
> - Premiere UXP 示例：<https://github.com/AdobeDocs/uxp-premiere-pro-samples>

---

## 1. 目标与非目标

### 1.1 目标

1. **quercus-core**：宿主无关的 Python AI 核心——LLMProvider 抽象、Agent 编排
   （对话 loop + 工具调用 + 视觉闭环）、约 20 个策展工具的 schema、会话状态与
   回放日志、密钥管理。
2. **Resolve 适配层**（第一优先级）：Python 母语直连 Resolve 脚本 API，支持
   无头（`-nogui`）跑 CI，完整实现工具面与取帧闭环。
3. **Premiere 适配层**：UXP 面板（TypeScript）+ localhost 桥接 core 本地服务，
   实现工具面的 Premiere 可用子集，能力缺口显式降级而非伪造。
4. **统一交互**：core 内建本地 Web 聊天面板（Resolve / 无头 / 调试通用）；
   Premiere 用 UXP 原生面板。两层确认（会话层"待确认清单"为主）。
5. **Oak 预留**：`quercus-oak` stub 包，实现 HostAdapter 接口签名 + OPP/1
   映射注释 + manifest 草案，所有方法 `raise NotImplementedError`。

### 1.2 非目标（明确不做）

- **不**实现 Oak 适配层（等 OPP/1 P1–P3，见 §8）。
- **不**把 LLM 推理放进任何宿主进程；core 永远是独立进程。
- **不**做 MCP server 对外暴露（设计文档 §2.1 已定位：需要时由 core 自起，
  本计划不排期）。
- **不**支持 Resolve 免费版的 UI 集成（v19.1 起免费版移除 UIManager；
  免费版能否外部脚本调用在 P0 验证，若不可行则 Resolve 侧仅支持 Studio）。
- **不**为宿主伪造原子事务：Resolve / Premiere 无事务 API，用快照 + 补偿
  实现"尽力回滚"（§3.3），对用户诚实标注。
- **不**在 Premiere 侧使用 ExtendScript / QE DOM 作为正式通路（EOL 风险；
  仅允许 P0 spike 里做能力对照）。

## 2. 仓库结构与进程拓扑

### 2.1 仓库布局（monorepo）

```
quercus/
├── docs/                        # 设计 + 本计划
├── core/                        # quercus-core（PyPI 风格包，宿主零依赖）
│   ├── providers/               # claude / openai_compat / llamacpp
│   ├── tools/                   # ~20 个工具 schema + 事务编排
│   ├── agent/                   # 对话 loop、视觉闭环、待确认清单
│   ├── session/                 # 会话状态、ActionBatch 记录、回放日志
│   ├── host/                    # HostAdapter ABC + 类型（§3.1）
│   └── webui/                   # 本地 Web 聊天面板（FastAPI + 静态页）
├── adapters/
│   ├── resolve/                 # quercus-resolve（Python，直连脚本 API）
│   ├── premiere/
│   │   ├── bridge/              # core 侧：WebSocket server + 协议编解码
│   │   └── panel/               # UXP 面板（TS + Vite，结构对齐 Adobe 官方示例）
│   └── oak/                     # quercus-oak（stub，仅接口 + 映射注释）
├── tests/
│   ├── mock_llm/                # 录制/回放 LLM server
│   ├── mock_host/               # HostAdapter 内存实现（行为对齐 OPP/1 语义）
│   └── e2e/                     # Resolve -nogui 黄金帧测试；Premiere 手工清单
└── pyproject.toml               # workspace（uv/pdm 均可，实现时定）
```

### 2.2 进程拓扑

```
┌─ DaVinci Resolve ─┐   ┌─ Premiere Pro ────────┐   ┌─ Oak（预留）─┐
│ 脚本 API（进程内） │   │ UXP 面板（Chromium）  │   │ oak-plugin-  │
└───────┬───────────┘   └──────────┬────────────┘   │ host (OPP/1) │
        │ fusionscript             │ WebSocket      └──────┬───────┘
        │ （同机直连）              │ localhost+token        │ stdio+shm
┌───────┴───────────┐   ┌──────────┴────────────┐   ┌──────┴───────┐
│ quercus-resolve   │   │ quercus-premiere      │   │ quercus-oak  │
│ （core 的进程内    │   │ bridge（core 进程内    │   │ （stub）      │
│  adapter 对象）    │   │  WebSocket server）   │   │              │
└───────┬───────────┘   └──────────┬────────────┘   └──────────────┘
        └──────────► quercus-core ◄┘
                     （Agent / LLM / Web UI / 会话）
```

- **Resolve**：core 进程 import `DaVinciResolveScript`，adapter 是 core 进程内的
  一个对象（Resolve 要求宿主在跑；core 直连，无中间进程）。也可反向：Resolve
  脚本菜单拉起 core——安装形态在 P3 定，默认**core 为主动方**（便于无头与 CI）。
- **Premiere**：UXP 无法 import Python，core 在 localhost 起 WebSocket server
  （随机端口 + 启动时写 token 文件到 `~/.quercus/bridge.json`，权限 0600；
  面板连接须带 token）。面板只做 UI 与宿主 API 调用，Agent 逻辑全在 core。
- **Oak**：未来 core 进程内 import `oakxp`，同 Resolve 形态；本计划只留 stub。

### 2.3 关键决策（本计划新增，设计文档未覆盖的）

| # | 决策 | 理由 |
|---|---|---|
| D1 | 面板主形态 = core 内建本地 Web UI；Premiere 另有 UXP 原生面板 | Resolve 免费版无 UI 能力、无头场景无 UI；Web UI 一份代码三处复用 |
| D2 | Premiere 桥用 WebSocket localhost + token 文件鉴权 | UXP 网络能力需 manifest 声明域名，localhost 可用；token 防同机其他进程误连 |
| D3 | 事务语义统一为 `ActionBatch`：宿主有事务用事务，无事务用快照 + 补偿 | Resolve/Premiere 均无事务/撤销分组 API，诚实降级（§3.3） |
| D4 | 取帧通路每宿主一条主通路 + 一条备用，P0 先验证再定主备 | 三家取帧能力差异最大，是整个视觉闭环的生死点（§5 表） |
| D5 | 内部时间模型统一有理秒（对齐 OPP/1 `Rational`） | 避免 Resolve 帧号 / Premiere ticks 渗透进 core；换算全部在适配层 |

## 3. 统一抽象：HostAdapter 接口

### 3.1 接口形状（刻意对齐 OPP/1 §8 方法族）

```python
# core/host/adapter.py（示意，非最终实现）
class HostAdapter(ABC):
    # 会话与能力
    def capabilities(self) -> set[Capability]: ...
    def limits(self) -> Limits: ...            # 取帧速率/分辨率上限等，各宿主自报
    # 工程 / 媒体 / 时间线 / 节点（方法族与 OPP/1 §8.2–8.5 一一对应）
    def get_project_overview(self) -> ProjectOverview: ...
    def probe_media(self, path: str) -> MediaInfo: ...
    def import_footage(self, paths: list[str]) -> list[FootageId]: ...
    def get_timeline_structure(self, seq: SeqId) -> Timeline: ...
    # 取帧（视觉闭环生死通路）
    def get_frame(self, target: Target, time: Rational, max_size: Size) -> PngBytes: ...
    def get_thumbnails(self, target: Target, range: TimeRange, count: int) -> list[PngBytes]: ...
    def get_audio_levels(self, seq: SeqId, range: TimeRange, resolution: int) -> Levels: ...
    # 回放 / 导出
    def play / pause / seek / get_state: ...
    def export(self, seq: SeqId, output: str, preset: str) -> JobHandle: ...  # 事件经回调
    # 编辑（ActionBatch 语义，见 §3.3）
    def execute(self, batch: ActionBatch) -> BatchResult: ...
    def undo_last(self) -> None: ...           # 仅用户明确要求时
```

- `EntityId` 为不透明字符串（对齐 OPP/1 §5），适配层内部维护
  id ↔ 宿主对象 的映射，工程重载后全部作废并通知 core 重新拉取。
- 事件（结构变化 / 播放头 / 导出进度）以回调注入 core；宿主无事件源的
  （Resolve 脚本 API 无事件）由适配层**轮询合成**，轮询频率进 `limits`。

### 3.2 工具面（core 对 LLM 暴露 ~20 个策展工具）

沿用设计文档 §3 的工具清单（`open_project` … `undo_last_action`），一处修改：
"OPP 方法"列改为"HostAdapter 方法"。事务编排职责不变——LLM 看不到事务/
快照细节，core 把一次 LLM 动作包成 `ActionBatch` 交给适配层。

### 3.3 ActionBatch：三档事务语义（诚实分级）

| 档位 | 宿主 | 实现 | 用户可见承诺 |
|---|---|---|---|
| 真事务 | Oak（未来） | OPP/1 `edit.begin/commit/abort` | 一次 Ctrl-Z 整段撤销，失败自动回滚 |
| 快照 + 补偿 | Resolve | 执行前 `Timeline.DuplicateTimeline("quercus-snapshot-*")`；失败/撤销时切回快照时间线 | "已为你保留编辑前快照时间线"，非原子 |
| 快照 + 补偿 | Premiere | 复制当前序列（UXP 支持则快照，不支持则仅反向操作日志）+ 逐步反向操作 | 面板内"撤销本段会话"按钮回放补偿；非原子 |

约束（写进 core，不依赖适配层自觉）：
- 破坏性批次（删除/波纹删除/批量移动）**必须**先快照；只读批次（打点、
  标记）可免快照。
- 快照命名带时间戳与会话 id，面板提供"清理快照"入口；快照数量进 `limits`
  上限（防时间线列表被刷爆）。
- 任一子操作失败：已执行的保持（与 OPP/1 §6 规则 3 语义对齐），错误回喂
  LLM，由 Agent 决定补偿或中止。

### 3.4 Oak 预留形态

`adapters/oak/` 包含：`OakAdapter(HostAdapter)` 全部方法
`raise NotImplementedError("awaiting OPP/1 P1-P3")`；每个方法 docstring 标注
对应 OPP/1 方法（如 `# -> timeline.split_clip，协议 §8.4`）；`plugin.toml`
草案（capabilities 用设计文档 §5.2 最小集）。**不写任何 oakxp 调用代码。**

## 4. 分阶段计划

> 工时为单人粗略估算，仅用于排序与预期管理。阶段间依赖见 §9 图。

### P0 技术验证（1–2 周，其余一切的闸门）

四个 spike，每个产出可运行脚本 + 一页结论，全部通过才进 P1：

| Spike | 验证内容 | 通过标准 |
|---|---|---|
| S1 Resolve 连接 | 外部 Python 经 `fusionscript` 连 Resolve；记录免费版/Studio 差异（外部调用、UIManager、`-nogui`） | 脚本拿到 `resolve` 对象并列出工程；明确版本门槛写进 README |
| S2 Resolve 取帧 | 三条通路对比：`Project.ExportCurrentFrameAsStill(path)`（主候选）、`Timeline.GetCurrentClipThumbnailImage()`（仅 Color 页）、Gallery `GrabAllStills` + 导出 | 能按给定时间点稳定拿到 PNG；测出单帧延迟与 `-nogui` 下可用性，定下主/备通路 |
| S3 Premiere UXP 基座 | UDT 加载 TS 面板（照官方 `premiere-api` 示例结构）；面板 ↔ 本地 WebSocket server 通信（manifest network 权限、token 握手） | 面板按钮触发本地 server 往返 < 50 ms |
| S4 Premiere 取帧与编辑面 | UXP export API 导单帧（官方示例 `export.ts`）；`sequenceEditor` 的 overwrite/insert/remove、markers、effects、transitions、keyframes 实际可用性；**split 与 ripple delete 是否存在原生 API** | 得到 Premiere 侧能力清单（✅/⚠️/❌），填进 §5 表；单帧导出延迟实测 |

Go/No-Go 规则：S2、S4 的取帧延迟若 > 2 s/帧，视觉闭环体验不成立，
回到设计层改交互（如纯 contact-sheet 低帧率模式）再开工。

### P1 quercus-core（约 3 周，不碰任何宿主）

1. **类型与配置**：`Rational`/`EntityId`/`FrameRef` 等核心类型；
   `~/.quercus/config.toml`（权限 0600、gitignore；环境变量仅 CI 覆盖，
   优先级：环境变量 > 配置文件；密钥绝不写任何宿主侧文件——继承设计铁律 4）。
2. **LLMProvider**：统一接口（消息 + 图片 → 文本 + tool_calls）；
   后端：Claude、OpenAI 兼容 endpoint（自定义网关/代理通用通路）、
   llama.cpp 本地多模态（Qwen-VL/LLaVA 类）。无 key 优雅降级：
   面板可浏览工具说明并手动执行，不做对话编排。
3. **Agent 编排**：对话 loop、tool_call 派发、视觉闭环（工具返回可携带
   图片消息回喂）、待确认清单（整段动作先入清单，用户确认后才执行——
   宿主无协议层弹窗，**确认只有这一层**，默认全开）。
4. **工具 schema 注册表**：约 20 个工具的 JSON Schema；参数 min/max/choices
   由 `get_params` 类方法回填（同设计 §3 的约束思路）。
5. **会话状态与回放**：ActionBatch 顺序记录、帧哈希、tool_call 日志落盘，
   可回放复现（测试夹具同格式）。
6. **Mock LLM server**：录制/回放固定 tool_call 序列。

验收：`pytest` 全绿；无网络无 key 环境下跑通
"mock LLM → 工具派发 → 回喂 → 第二轮对话"。

### P2 HostAdapter + Mock 宿主 + 工具适配层（约 2–3 周）

1. HostAdapter ABC 与 `Limits`/`Capability`（§3.1–3.2）。
2. **MockHostAdapter**：内存时间线模型，行为对齐 OPP/1 语义（事务档位、
   id 作废、`RATE_LIMITED` 式退避、帧非全黑校验）——它就是未来 Oak 适配层
   的验收替身，也是 P1 的测试底座。
3. **工具适配层**：tool schema → adapter 方法组合；ActionBatch 编排
   （快照策略、失败补偿、补偿顺序）；取帧流水线（并发取帧 + 立即释放，
   对齐 OPP/1 §10.3 的教训：批量扫描绝不串行等帧）；限流客户端
   （按 `limits` 令牌桶，退避不重试轰炸）。
4. **本地 Web 面板**：聊天、待确认清单、进度、撤销会话按钮、快照管理。

验收：Mock 宿主上"导入 → 铺轨 → 切/重建 → 删除 → 加效果 → 取帧验证 →
整段会话撤销"全链路自动化通过；Web 面板手工走查。

### P3 Resolve 适配层（约 3–4 周，依赖 P0 S1/S2、P2）

1. **连接与生命周期**：`fusionscript` 连接（环境变量
   `RESOLVE_SCRIPT_API/LIB` 探测 + 报错指引）、断线重连、`-nogui` 模式支持、
   版本门槛检查（S1 结论）。
2. **方法映射**（详表见 §5）：工程/媒体池/时间线/标记/导出全量实现；
   时间模型换算（帧号 ↔ 有理秒，按时间线 fps）；`EntityId` ↔ 对象映射
   （优先 `GetUniqueId()`）。
3. **取帧通路**：按 S2 结论实现主/备两条；contact sheet 拼贴（Pillow）。
4. **ActionBatch 档位**：快照（`DuplicateTimeline`）+ 补偿操作表；面板
   "撤销会话"回放到快照。
5. **安装形态**：安装脚本写 Scripts 目录菜单项（`Utility/`）+ core 独立
   启动两种入口；文档写清 Studio/免费版差异。

验收：`-nogui` CI 端到端——真实工程"导入 → 建时间线 → 粗剪 → 打点 →
导出"，黄金帧校验（取到的帧非全黑、编辑前后切口帧像素不同）；快照撤销
恢复一致性断言；GUI 模式手工走查 Web 面板对话粗剪一段真实素材。

### P4 Premiere 适配层（约 4–5 周，依赖 P0 S3/S4、P2）

1. **bridge**：core 内 WebSocket server（随机端口 + token 文件 0600）；
   NDJSON/JSON 消息协议（复用 core 的 HostAdapter 调用语义，一份 schema
   两用）；断线重连与版本协商。
2. **UXP 面板**（TS + Vite，结构照官方示例）：聊天 UI、待确认清单、
   进度；`manifest.json` 只声明必要权限（localhost 网络）。
3. **方法映射**：按 S4 能力清单实现 ✅ 项；⚠️ 项做变通（split 用
   出入点重建、ripple 用移动补偿等）；❌ 项在 schema 层显式隐藏并给
   LLM 一份"本宿主不支持"说明（防幻觉调用）。
4. **取帧**：S4 定下的通路实现；延迟进 `limits` 让扫描策略自适应。
5. **ActionBatch 档位**：序列快照（若 API 支持复制序列）+ 补偿日志。
6. **打包**：开发走 UDT；发布形态（独立分发 `.ccx`）与签名要求调研
   并落地最简可用路径。

验收：Premiere 内面板对话完成"铺轨 → 打点 → 加转场/效果 → 导出"，
待确认与撤销交互完整；bridge 断连/重连不丢会话；手工 E2E 清单全过
（Premiere 无无头模式，此阶段接受手工测试为主）。

### P5 内容感知能力（约 3–4 周，依赖 P3，P4 可并行）

1. **Contact sheet 扫描打点**：等间隔采样拼图回喂，LLM 输出时间点 →
   `add_marker`（两宿主 markers API 都全）。
2. **自动粗剪策略**：LLM 判定废片段 → ActionBatch（Resolve 直删/补偿；
   Premiere 按能力变通）；人工抽检闭环。
3. **转录利用**（能力增强，可选）：Premiere 有 transcript 导出、Resolve
   Studio 有 `TranscribeAudio`——按 `capabilities` 探测启用"按台词剪辑"。
4. **本地模型 provider 打磨**：llama.cpp 多模态的提示词与分辨率预算。

验收：对 10 分钟素材自动出粗剪版，人工抽检切点可用（同设计 A5 标准）；
CI 有 mock 回放的粗剪回归。

### P6 发布与硬化（约 2 周）

- 两宿主安装器/打包（Resolve 脚本目录 + core 单包；Premiere `.ccx`）；
  core 用 PyInstaller / python-build-standalone 嵌入式发行（用户不装 Python，
  同设计 §2.3）。
- 崩溃与断线恢复矩阵测试；日志与诊断包；密钥配置引导；限流与大图内存
  压测。
- 文档：安装、能力矩阵（§5 表面向用户版）、故障排查。

### P7 Oak 适配（**预留，不启动**）

启动前提：OPP/1 P1–P3 完成（传输生命周期、宿主 API 核心、取帧 shm 数据面）。
届时 `quercus-oak` = HostAdapter → oakxp 的薄封装：事务档位直接升到"真事务"
（`edit.begin/commit`），取帧走 shm `FrameRef` + `shm.release` 流水线，确认
双层（协议弹窗 + 会话清单）按设计文档 §5.2。预计工作量显著小于 P3/P4——
这正是接口对齐 OPP/1 的收益。**本计划不为其分配资源。**

## 5. 宿主能力映射表（工具 × 宿主）

> ✅ 原生支持；⚠️ 有变通（注明）；❌ 缺失（schema 层隐藏）。
> Resolve 方法名见 X-Raym 文档；Premiere 为 UXP API 域（以 S4 实测为准修订）。

| core 工具 | Resolve | Premiere（UXP） | Oak（预留 → OPP/1） |
|---|---|---|---|
| `open/save_project` | ✅ `ProjectManager.LoadProject/SaveProject` | ✅ project open/save | `project.open/save` |
| `get_project_overview` | ✅ `GetCurrentTimeline` + `GetItemListInTrack` 遍历 | ✅ activeSequence 遍历 | `project.get_info` + `timeline.get_structure` |
| `probe_media` | ⚠️ `MediaPoolItem.GetClipProperty()`（无独立 probe） | ✅ projectItem 元数据 | `media.probe` |
| `import_footage` | ✅ `MediaPool.ImportMedia` | ✅ `importFiles` | `media.import_footage` |
| `add_track` | ✅ `Timeline.AddTrack` | ✅ sequence tracks | `timeline.add_track` |
| `place_clip` | ⚠️ `AppendToTimeline`（clipInfo 带 startFrame/endFrame/recordFrame/trackIndex） | ✅ `sequenceEditor` overwrite/insert | `timeline.place_clip` |
| `split_clip` | ⚠️ 无直接 API——按出入点重建相邻两段（S4 复核新版是否已加） | ⚠️ 视 S4 结论；否则同样重建 | `timeline.split_clip` |
| `trim_clip` | ⚠️ `SetProperty`/重建 | ✅ trackItem 出入点 | `timeline.trim_clip` |
| `move_clip` | ⚠️ 删除 + `AppendToTimeline` 重放 | ✅ move track item | `timeline.move_clip` |
| `ripple_delete` | ✅ `Timeline.DeleteClips(items, True)` | ⚠️ 视 S4；否则补偿移动 | `timeline.ripple_delete` |
| `add_transition` | ⚠️ `TimelineItem` 属性/新建（有限） | ✅ transition 模块 | `timeline.add_transition` |
| `add_marker` | ✅ `Timeline.AddMarker`（含 customData，可存 AI 元数据） | ✅ markers 模块 | `timeline.add_marker` |
| `add_effect/set_param/keyframe` | ⚠️ 效果面有限（Fusion comp / 属性），调色走节点图另议 | ✅ effects + keyframe 模块 | `node.*` |
| `get_frame` | ✅ S2 主通路（`ExportCurrentFrameAsStill`） | ⚠️ S4：export 单帧，延迟实测 | `render.get_frame`（shm） |
| `scan_timeline` | ✅ `GrabAllStills` / 逐点取帧拼图 | ⚠️ 批量导帧拼 contact sheet | `render.get_thumbnails` |
| `get_audio_levels` | ❌（v1 隐藏；Fairlight 侧另议） | ⚠️ 视 API；否则隐藏 | `render.get_audio_levels` |
| `play/pause/seek` | ⚠️ `SetCurrentTimecode` 可 seek；播放控制弱 | ✅ sourceMonitor play/pause/position | `playback.*` |
| `export_render` | ✅ `LoadRenderPreset` + `AddRenderJob` + `StartRendering` + `GetRenderJobStatus` 轮询 | ✅ encoderManager / export | `export.start` + 事件 |
| `undo_last_action` | ❌ 无 undo API → 快照恢复（§3.3） | ❌ 同左（补偿回放） | `edit.undo` |
| 事件（结构/进度） | ⚠️ 轮询合成 | ✅ eventManager（工程/编码事件） | OPP/1 §9 原生事件 |

## 6. 安全与密钥（继承设计铁律，按本计划重述）

1. core 只经 HostAdapter 操作宿主；Premiere 桥接受 token 鉴权、只绑
   `127.0.0.1`。
2. 一切编辑走 ActionBatch，破坏性批次先快照；UI 默认"确认后执行"
   （宿主无协议层确认，会话层清单是唯一确认点，不可默认关闭）。
3. API key 只存 `~/.quercus/config.toml`（0600）；绝不写入 Resolve 工程/
   Premiere 工程/未来 `.ove` 的任何位置。
4. 遵守各宿主实测限流：取帧并发与分辨率预算写进 `limits`，core 侧令牌桶
   统一执行，退避不轰炸。

## 7. 测试策略

1. **Mock LLM**（P1）：无 key 无网络 CI 跑通 Agent loop。
2. **MockHostAdapter**（P2）：协议级行为夹具；未来 Oak 适配层先对它达标
   再连真 Oak。
3. **Resolve 黄金帧 E2E**（P3）：`-nogui` 起真实实例，导入测试素材 →
   编辑 → 取帧，断言帧非全黑且切口前后像素变化——对齐设计 §6.3 的
   "Agent 的编辑确实改变了画面"。
4. **Premiere 手工清单**（P4）：无无头模式，维护一份逐步 checklist +
   预期画面截图基线，发布前必跑。
5. **会话回放**：tool_call + 帧哈希日志可直接作回归夹具。

## 8. 风险登记册

| 风险 | 影响 | 对策 |
|---|---|---|
| Resolve 免费版外部脚本/UI 受限（v19.1 移除 UIManager） | Resolve 侧受众收窄 | S1 定门槛；必要时仅支持 Studio 并在文档明示 |
| Resolve/Premiere 均无 undo/事务 API | "撤销会话"非原子，可能残留 | 快照 + 补偿（§3.3）；UI 文案不承诺原子性 |
| Premiere UXP 取帧慢或无直接 API | 视觉闭环降格 | S4 实测；降格方案 = 低帧率 contact-sheet 模式 |
| Premiere split/ripple 无原生 API | 粗剪动作变通复杂易错 | 重建法封装进适配层 + 黄金帧类断言兜底 |
| UXP 网络/面板权限政策变化 | 桥接失效 | manifest 最小权限；关注 Adobe 公告；bridge 协议版本协商 |
| LLM 成本与延迟 | 体验差 | 本地 provider、扫描降采样、contact sheet 合并请求 |
| 时间模型换算（帧号/ticks/fps 下拉） | 切点漂移 | 有理秒唯一内部模型 + 适配层换算单测（NTSC fps 用例） |

## 9. 里程碑总表与依赖

```
P0(spike) ──► P1(core) ──► P2(adapter+mock) ──┬──► P3(Resolve) ──► P5(内容感知) ──► P6(发布)
        │                                     └──► P4(Premiere) ────────────────►──┘
        └──（P7 Oak：等 OPP/1 P1–P3，不占本计划资源）
```

| 里程碑 | 出口标准（一句话） | 估算 |
|---|---|---|
| P0 | 四个 spike 通过，两宿主取帧通路定案 | 1–2 周 |
| P1 | Mock LLM 下 Agent loop CI 全绿 | ~3 周 |
| P2 | Mock 宿主全链路 + Web 面板可用 | ~2–3 周 |
| P3 | Resolve 无头 E2E 黄金帧通过，GUI 对话粗剪走通 | ~3–4 周 |
| P4 | Premiere 面板对话编辑 + 撤销会话走通 | ~4–5 周 |
| P5 | 10 分钟素材自动粗剪，抽检可用 | ~3–4 周 |
| P6 | 两宿主安装包 + 文档 + 硬化完成 | ~2 周 |
| P7 | （预留）Oak 适配 = oakxp 薄封装，等 OPP/1 P1–P3 | 未排期 |

P4 与 P3 可由两人并行；单人执行顺序建议 P3 先于 P4（Resolve API 面更全、
可无头，能在最硬的宿主上先把 HostAdapter 接口的真实形状磨出来）。