Mike-Solar
c486c853ff
Complete documentation set for the facade migration (B1-R6) and beyond: facade-migration-roadmap, handoffs v3-v6, R5 guides, R6 cleanup plan, R7 pure-ABI plan, long-term plans (riir/ai-agent/gtest/ui-redesign), updated Chinese README draft, UI design mockups, and the Google Test + struct-typedef rules in CONTRIBUTING.
142 lines
7.4 KiB
Markdown
142 lines
7.4 KiB
Markdown
# AI Agent 设计文档（RIIR 拆分后长期规划）
|
||
|
||
> 本文是 Oak 引入 AI 能力的长期设计，**执行前提是 RIIR 绞杀者拆分完成**
|
||
> （见 [`riir.md`](riir.md)）。彼时 `liboakengine.so` 已不存在，取而代之的是
|
||
> 一组以纯 C ABI 为缝的小动态库。本文面向没有当前对话记忆的执行者，自包含。
|
||
>
|
||
> **一句话**：把多模态 LLM 当成引擎 C ABI 的**第三个一等消费者**
|
||
> （继 oak-cli、oak-render-worker 之后），用 MCP 暴露策展过的工具面，
|
||
> 用渲染管线把帧喂回给多模态模型，形成"编辑 → 看图 → 再编辑"的视觉闭环。
|
||
|
||
---
|
||
|
||
## 1. 定位与前提
|
||
|
||
### 1.1 前提（未满足不动工）
|
||
|
||
- RIIR 拆分战役完成：引擎已拆为 §2.1 的小库；各库导出仅 C 符号；
|
||
`oakengine_*` facade 壳稳定且全量测试绿。
|
||
- Google Test 已是唯一测试框架；`gtest_discover_tests` 已接入。
|
||
- 本文不改动 RIIR 既定的模块划分，只在模块化树上**新增叶子**。
|
||
|
||
### 1.2 设计铁律（继承自迁移/拆分战役）
|
||
|
||
1. AI Agent **只经 C ABI** 访问引擎，一行 engine C++ 都不碰；不污染符号边界。
|
||
2. Agent 的一切编辑动作**必须可撤销**（undoable 原语），UI 默认"确认后执行"。
|
||
3. 不为 AI 发明新的引擎内部机制；工具面是现有 facade/小库的组合。
|
||
4. 引擎各模块**不得新增 Qt 依赖、不得新增 QObject 信号/moc 类**。
|
||
|
||
## 2. 总体架构
|
||
|
||
### 2.1 在模块化树上的位置
|
||
|
||
```
|
||
app / oak-cli / oak-render-worker / oak-agent / oak-mcp-server
|
||
│
|
||
liboakengine-facade（壳：capi + 事件 + init）
|
||
│
|
||
┌────────┬────────┼─────────┬──────────┐
|
||
oaktask oakrender oakplugin oakaudio oakserialize
|
||
│ │ │ │ │
|
||
└────────┴────┬───┴──────────┴──────────┘
|
||
│
|
||
oakmodel（节点图 + 项目模型 + 时间线模型）
|
||
│
|
||
┌────────┼─────────┐
|
||
oakcodec liboakcore oakbackend（GPU 插件）
|
||
│
|
||
ffmpeg_bridge
|
||
```
|
||
|
||
**新增三个叶子组件**（与 oak-cli、oak-render-worker 平级，都是纯消费者）：
|
||
|
||
- **`oak-mcp-server`**：把策展过的工具面经 MCP 暴露给任何 LLM 客户端。
|
||
- **`oak-agent`**：无头 Agent 运行时（对话编排 + 视觉闭环），供脚本/CI/本地使用。
|
||
- **editor AI 面板**：app 内的聊天/操作日志/确认界面，与 `oak-agent` 复用同一工具面。
|
||
|
||
AI 功能**不进入** oakmodel、oakrender 等引擎模块，引擎核心对 AI 无感知。
|
||
|
||
### 2.2 视觉闭环（本设计的核心）
|
||
|
||
```
|
||
多模态 LLM ──► oak-agent ──► facade/小库执行编辑 ──► 渲染取帧 ──► PNG ──► 回喂 LLM
|
||
▲ │
|
||
└──────────────── 看图判断（效果/切点/内容定位） ◄───────────────┘
|
||
```
|
||
|
||
- **验证式**：每次编辑后取一帧，LLM 判断"效果对不对"。
|
||
- **内容感知式**：沿时间线批量取缩略图拼 contact sheet，LLM 扫图定位
|
||
（"人何时进画面""哪里该切"），Agent 据此下刀——自动粗剪/打点的雏形。
|
||
- **连续回放**：经 playback 族起范围播放，按间隔采样帧。
|
||
|
||
## 3. 工具面（策展，非全量 facade）
|
||
|
||
**不暴露全部 ~200+ facade 函数**，而是策展约 25 个高层工具，每个是 facade/小库
|
||
的组合。`oak-mcp-server` 内部就是一个薄模块，链接 facade 壳与相关小库。
|
||
|
||
| 工具 | 落到哪个库 | 说明 |
|
||
|---|---|---|
|
||
| `create_project` / `open_project` / `save_project` | facade 壳 + oakmodel | 工程生命周期 |
|
||
| `probe_media` / `import_footage` / `get_media_info` | oakcodec + facade 壳 | 媒体探测与导入 |
|
||
| `add_track` / `add_clip` / `trim_clip` / `ripple` / `add_transition` / `add_marker` | oakmodel（经 facade 时间线族） | 时间线编辑 |
|
||
| `add_effect(effect_id)` / `set_param` / `set_keyframe` | oakmodel（经 facade node 族） | 节点与关键帧 |
|
||
| `apply_lut` / `set_color_transform` | oakmodel + facade color 族 | 调色 |
|
||
| `get_frame(time)` / `get_thumbnails(range,n)` / `get_audio_levels` | oakrender + oakbackend | **视觉闭环的取帧口** |
|
||
| `export_render(params)` | oaktask + oakcodec | 导出 |
|
||
|
||
**取帧→PNG 通路**（视觉闭环关键路径）：
|
||
`get_frame` 经 oakrender 的预览请求得到 RGBA 帧（POD：`宽/高/字节流`），
|
||
再经 oakcodec 的 OIIO 编码器出 PNG，base64 后作为图片消息发给 LLM。
|
||
缩略图用同一路径降采样，多张拼 contact sheet。
|
||
|
||
## 4. 协议：MCP（Model Context Protocol）
|
||
|
||
工具协议**定为 MCP**，理由：
|
||
|
||
- render-worker 已在用 **NDJSON over stdin/stdout 的 IPC**——MCP 本质是该模式
|
||
的标准化，实现路径一致。
|
||
- 暴露成 `oak-mcp-server` 后，**外部 LLM 客户端（Claude Desktop、各类 agent
|
||
框架）可直接连接复用**，无需自研对话编排。
|
||
- `oak-agent` 与 editor AI 面板都连同一个 MCP server，**一份工具面，多处消费**。
|
||
|
||
## 5. 模型层
|
||
|
||
抽象 `LLMProvider` 接口（输入：消息 + 图片；输出：文本 + tool_calls），两个后端：
|
||
|
||
- **云端**：Claude / GPT 多模态（效果优先）。
|
||
- **本地**：llama.cpp 跑 Qwen-VL / LLaVA 类多模态模型（隐私、离线优先）。
|
||
|
||
API key 只走环境变量，**绝不写入 config / 工程文件**。无 key 时优雅降级为
|
||
"仅本地工具"（仍可用 MCP，但不做对话编排）。
|
||
|
||
## 6. 安全
|
||
|
||
- **可撤销**：所有编辑走 undoable 原语；AI 面板提供"撤销整段会话"。
|
||
- **确认模式**：默认每次 Agent 动作需用户确认才 apply；可切换自动模式。
|
||
- **沙箱会话**：Agent 默认在临时工程中操作，用户接受后才落盘到真实工程。
|
||
- **资源**：取帧/扫描限帧率与分辨率上限，防止批量取帧拖垮渲染进程。
|
||
|
||
## 7. 可测试（与项目风格一致）
|
||
|
||
1. **Mock LLM server**：录制/回放 tool_call 序列与固定回复，让 Agent loop 在
|
||
CI 无 key 无网络跑通（Google Test）。
|
||
2. **黄金帧校验**：复用 render-worker 端到端 harness（真实渲染 ≥2 帧 +
|
||
像素非全黑 + 一致性断言），验证"Agent 的编辑确实改变了画面"。
|
||
3. **会话回放**：tool_call + 帧哈希落盘日志，可回放复现、可作测试夹具。
|
||
|
||
## 8. 里程碑（RIIR 完成后启动）
|
||
|
||
1. **M1 工具面**：`oak-mcp-server`（facade → MCP，~25 工具）+ 取帧→PNG 通路。
|
||
2. **M2 无头闭环**：Mock LLM + `oak-agent`，跑通"LLM→工具→取帧→回喂"，
|
||
CI 可测（无网络）。
|
||
3. **M3 AI 面板**：editor 内聊天 + 操作日志 + 确认模式 + 撤销会话。
|
||
4. **M4 本地模型与内容感知**：llama.cpp provider、时间线扫描打点、自动粗剪。
|
||
|
||
## 9. 风险与边界（明确不做）
|
||
|
||
- **不**把 LLM/推理放进 oakmodel 或任何引擎模块（引擎对 AI 无感知）。
|
||
- **不**为 AI 绕过 C ABI 直接调 engine C++（边界不污染）。
|
||
- **不**把 API key 落盘到工程/config。
|
||
- **不**让取帧回路阻塞 GUI 线程（取帧走渲染/后台路径，UI marshal 回主线程）。
|
||
- 第三方大模型客户端的接入细节（OAuth、计费、配额）**超出本文范围**，按需另立文档。
|