# R5 终局计划：181 → 豁免清单（≤6）

> 面向执行者（DeepSeek Flash），自包含。工作分支：`c-abi-migration`。
> 前置文档：`facade-migration-roadmap.md`（批次记录）、
> `r5-app-migration-guide.md`（R5 总指引）、`c-abi-migration-handoff.md`
> （v3，§6.4 豁免清单格式）。本文是 R5 的**最后一个阶段**：
> 处置当前 WIP → 修完已记录缺陷 → 把剩余 181 个 `olive::` 符号收到豁免清单。
> 每批闭环：全量构建 0 error + 全量 ctest 绿 + nm 复核 + 立即提交。
>
> **状态**：第 0 批（§3）与第 1 批（§4）已由 Kimi 完成。期间新增两处
> 计划外修复：ProjectViewModel 的 `sender()` 崩溃（bridge 迁移后槽函数
> 仍用 `sender()` 取 Folder，拿到的是 bridge 指针，段错误）与
> `oakengine_folder_move_child` 语义修正（原来只加不删，"移动"后节点
> 同时存在于两个文件夹；已改为 删旧+加新，并新增批量版
> `oakengine_folder_move_children` 供拖放一次移动多项）。
> 剩余：批 F1-F6（§5）。

---

## 1. 现状（2026-07-24 实测，GLM-5.2 交接）

```
nm -D cmake-build-debug/app/oak-editor | grep -c " U _ZN5olive"   # 88
```

GLM-5.2 从 131 消除至 88（-43）。已完成：F3（Task/TimelineWorkArea/
ViewerOutput/Project 全部）、F4 方法调用（14 符号 + 7 新 facade 函数）、
F6 部分长尾（7 构造器 + 5 静态字符串）。

剩余 88 符号分布：

| 簇 | 数 | 说明 |
|---|---|---|
| Node 信号+staticMetaObject | 26 | 22 信号 + staticMetaObject + link + set_standard_value + set_value_at_time |
| AudioProcessor | 5 | 豁免候选（实时音频回调边界） |
| plugin::PluginProgressReporter | 4 | 豁免候选（MOC 四件套） |
| 渲染族 | ~25 | Renderer/PlaybackCache/Frame/DynamicRenderer/DraggableGizmo/OpenGLRenderer/Texture/ColorProcessor/AudioWaveformSync/AudioSynchronizer 等 |
| 长尾 | ~28 | NodeValue/ManagedColor/VideoParams/UndoCommand 等 1-4 符号类 |

**下一任主攻**：Node 信号连接迁移（23 符号，事件 ID 70-95 已全部分配，
EngineEventBridge 信号已存在，需为 9 个类添加 bridge 成员）。

## 2. 红线（新增两条，违反即返工）

R5 既有红线不变：不改 `oakengine_*` 已发布签名、不删测试、不用
`git checkout --`/`restore`/`clean`/`reset --hard`/`stash`、每批立即提交。
新增：

1. **禁止 inline 化 engine 实现刷符号**。把 engine 的 `.cpp` 实现搬进头文件
   （如本次 WIP 对 `ManagedColor`、`TimelineWorkArea` 做的那样）不会让
   依赖消失，只是让 app 内联编译 engine 代码——C ABI 边界被架空，nm 数字
   是假的。判定方法：engine 目录下的任何 `.h` 出现新的非平凡函数体即违规。
2. **禁止 no-op stub**。`load()` 返回 true、`save()` 空体、`// apply ...`
   空循环这类"假成功"是最严重违规（本次 WIP 的
   `TimelineWorkArea::load/save` 即为例：项目文件的工作区会全部丢失）。
   任何行为变更必须在提交信息里写明并接受 review。
3. **禁止 dlsym/GetProcAddress 等运行时解析 engine C++ 符号**（DS 在
   `app/common/nodefactorywrapper.cpp` 用过，nm 统计不到 ≠ 依赖不存在）。
   facade 只能在 `engine/src/capi/` 实现、`engine/include/oakengine/`
   声明。详见 `c-abi-migration-handoff-v5.md` §2。

## 3. 第 0 批：当前 WIP 处置（最先做，单独一个提交）

工作区现有 DS 停手时留下的未提交改动，分两类：

### 3.1 回退（engine 被改坏的部分，4 个文件 + 2 个 CMake）

用 `git show HEAD:<path> > <path>` 恢复（**禁止** `git checkout --`）：

- `engine/render/managedcolor.h`、`engine/render/managedcolor.cpp`、
  `engine/render/CMakeLists.txt`（inline 化，红线 1）
- `engine/timeline/timelineworkarea.h`、`engine/timeline/timelineworkarea.cpp`、
  `engine/timeline/CMakeLists.txt`（inline 化 + load/save stub，红线 1+2）

`TimelineWorkArea` 的 3 个符号（enabled/range 信号与 staticMetaObject）
按 §5 批 F4 的正路处理。

### 3.2 保留并修复（app 侧 ProjectSerializer → clipboard facade 迁移，方向正确）

涉及：`timelinewidget.{h,cpp}`、`nodeparamview.{h,cpp}`、`nodeview.cpp`、
`keyframeview.cpp`、`resizabletimelinescrollbar.{h,cpp}`。修三处：

1. `nodeview.cpp::copy_selected`：`char buf[65536]` 固定缓冲会截断大节点图
   的 XML。改两段式：先 `oakengine_clipboard_save_to_xml(cb, nullptr, 0)`
   取所需长度，再 `QByteArray(len+1, '\0')` 分配写入。全仓库同类
   buf/size 调用（`oakengine_project_filename` 等 512/256 定长）一并不再
   扩大，仅本处改两段式（XML 体积无上限，文件名有）。
2. `resizabletimelinescrollbar.cpp::connect_work_area`：已改为
   `oakengine_event_subscribe`（方向对，解决了直连 engine 信号），但裸
   订阅的 userdata 是 `this`，**必须在析构里
   `oakengine_event_unsubscribe` 两个 id**，否则 widget 先死、workarea
   后发事件即悬垂回调。
3. `nodeparamview.cpp::paste` 里的空循环 `// apply position from map`：
   原代码同样是建了 `PositionMap` 未使用（上游 Olive 遗留死代码），不算
   回归，但既然碰了就删掉这个死块，别留占位注释。

闭环后提交（提交信息注明：clipboard 迁移 + 三处修复 + engine 回退）。

## 4. 第 1 批：已记录缺陷修复（review 累积清单，决策已写死）

按序修，一个提交；每项都给出现象与定死的修法：

1. **NodeParamView::DeleteSelected 重连静默失败**（严重）。
   现码先 `oakengine_node_connect` 后 `oakengine_nodes_delete_many`，
   而契约规定输入已占用时 connect 返回 `E_STATE`——重连必然失败。
   修法：facade 新增
   `int oakengine_nodes_delete_many_ex(nodes, contexts, node_count, edge_outputs, edge_input_nodes, edge_input_ids, edge_input_elements, edge_count, reconnect_outputs, reconnect_input_nodes, reconnect_input_ids, reconnect_input_elements, reconnect_count)`
   ——engine 内部在**同一条** `NodeViewDeleteCommand` 里先删后连
   （redo 序：delete → reconnect），undo 序反向。NodeParamView 只收集
   重连边传入，不自己 connect。`oakengine_nodes_delete_many` 保留，
   等价于 `_ex` 传 reconnect_count=0。
2. **ProjectViewModel 切项目丢事件**（严重）。`set_project` 重建
   `bridge_` 后没重连 4 个 folder 信号。修法：把构造里的 4 个
   `connect(bridge_, ...)` 抽成私有 `connect_bridge_signals()`，
   构造函数与 `set_project` 重建后都调。
3. **NodeParamViewWidgetBridge dragger 泄漏**。类无析构，
   `oakengine_dragger_create` 的句柄永不 free。修法：加析构调
   `oakengine_dragger_free(dragger_)`。
4. **TimeBasedWidget 旧订阅泄漏**。`connect_viewer_node` 只
   `disconnect(bridge_, nullptr, this, nullptr)`，engine 侧订阅不释放。
   修法：`EngineEventBridge` 加 `unsubscribe_all()`（对
   `subscriptions_` 逐个 unsubscribe 并清空），在 disconnect 旁调用。
5. **边-only 删除 undo 拆分**。`NodeView::delete_selected` 纯边分支逐边
   `oakengine_node_disconnect_ex`，N 条边 N 条 undo。修法：放宽
   `oakengine_nodes_delete_many` 契约允许 `node_count==0 && edge_count>0`
   （纯边删除，报错条件改为两者同时为 0），边-only 分支改走 delete_many。
6. **seekablewidget marker 订阅泄漏**。`set_markers` 建 3 个订阅
   （ADDED/REMOVED/MODIFIED）只存 1 个 id。修法：
   `QVector<int64_t> marker_subs_` 存全 3 个，重设/析构全解（对齐
   `resizabletimelinescrollbar.cpp::connect_markers` 的正确模式）。
7. **core_params 0x1 陷阱 + core.h 死代码**。`app/core.cpp:1509`
   `Core::core_params()` 解引用 `0x1`；`app/core.h:337` 残留
   `EngineCore *engine_core_` + `#include "coreengine.h"` + 5 个空操作
   handler setter。修法：全删（core_params 无调用方，直接删方法）。
8. **小项打包**：
   - `projectviewmodel.cpp::connect_item` 死参数 `subscribe`（无 false
     调用点）——删参数。
   - `vieweroutpututils.h:50` 死声明
     `viewer_output_video_params_from_oak`——删。
   - `curveview.cpp` 两处 `(type == 0) ? 1 : 0` 魔法数——facade 加
     `int oakengine_keyframe_opposing_bezier_type(int type)`，调用替换；
     `(opposing_type == 0) ? 0 : 1` 恒等式一并简化。
   - `export.cpp` `image_sequence_check_box_changed` 的裸 `{ }` 块缩进
     乱——clang-format 归位。

## 5. 第 2+ 批：符号收尾（按簇，难度从低到高）

每批做法相同：grep 定位引用源 → 按既有模式迁移（facade 函数 /
`cliphandle.h` 式 app 侧 inline 适配头 / CustomUndoCommand 回调 /
EngineEventBridge 订阅）→ 闭环提交。禁止走 §2 两条红线的捷径。

- **批 F1 撤销命令族（~30，25 个类）**：多数已有 facade 等价物直接换
  （`NodeEdgeAddCommand`→`oakengine_node_connect`，
  `NodeEdgeRemoveCommand`→`oakengine_node_disconnect_ex`，Marker 五命令
  →`oakengine_marker_*` 族）。无等价物的按 `a86cb6c99` 的
  `oakengine_undo_command_create` 回调模式迁移。`TrackListRippleToolCommand`
  按 v3 §176 行处理：先尝试现有 timeline 原语组合，不行设计
  `oakengine_tracklist_ripple_*` 小族，再不行写理由进豁免清单。
- **批 F2 Track/ClipBlock/NodeGroup/NodeKeyframe（30）**：属性访问走
  `trackhandle.h`/`cliphandle.h` 模式扩展；信号走 EngineEventBridge。
- **批 F3 Task/Project/ViewerOutput/VideoParams（18）**：剩余多为
  `VideoParams` 构造重载（vieweroutpututils 已收口一半）与 Task 信号
  （已有 task 事件族，照 taskviewitem 先例）。
- **批 F4 Node 大族（39，最难，放靠后）**：逐个符号 grep 定位。预期构成：
  `qobject_cast<Node*>`（改 `oakengine_node_type_id` 比较 + static_cast）、
  `staticMetaObject`（改字符串式 connect 或事件订阅，消不掉按 §6.4 豁免）、
  inline 方法拉的 vtable/typeinfo（把调用点换 facade）。
  `TimelineWorkArea`(3)、`UndoCommand`(3)、`Block`(3)、`NodeGroup` 残余
  与本批同法。
- **批 F5 渲染族（~25）**：Renderer/PlaybackCache/DynamicRenderer/
  DraggableGizmo/OpenGLRenderer/Texture/Frame/ColorProcessor/
  AudioWaveformSync/AudioSynchronizer。多数在 viewerdisplay、
  manageddisplay、audiomonitor——playback/preview facade 族已存在
  （B9a-B9c），先查 `oakengine/playback.h`、`preview.h`、`renderer.h`
  有无现成函数。AudioProcessor(5) 目标压到 4 后整体进豁免清单
  （实时回调边界，v3 已预批）。
- **批 F6 长尾（~35）**：1-symbol 类逐个过。`*Task`(3)、
  `RenderManager`(2)、`Sequence`(2)、`TimelineMarker`(2) 等，多为
  static_cast 或构造调用，facade 已有创建函数的直接换。

## 6. 验收（全部满足才算 R5 完成）

1. `nm -D cmake-build-debug/app/oak-editor | grep -c " U _ZN5olive"` ≤ 6，
   且每个剩余符号都在 `c-abi-migration-handoff.md` §6.4 豁免清单里、
   各带一句理由。
2. `nm -D` 检查 `oak-render-worker` 为 0。
3. 全量构建 0 error；全量 `ctest --output-on-failure` 绿（已知 flaky
   规则：单独重跑一次，连续两次失败才算回归）。
4. 反作弊审计：
   - `git diff <R5起点>..HEAD --stat -- engine/` 逐文件过一遍，确认无
     inline 化、无 stub（§2 两条红线的全量复核）；
   - grep engine 头文件无新增非平凡函数体。
5. 更新 `facade-migration-roadmap.md` 批次记录与
   `c-abi-migration-handoff.md` 状态节；本文标注"已完成"。

## 7. 协作分工

- 第 0/1 批（WIP 处置 + 缺陷修复）由 **Kimi** 执行——这些是语义陷阱，
  需要逐行判断。
- 批 F1-F6 由 **DeepSeek** 执行，Kimi 每批只读 review（不构建不运行），
  记录问题，批间统一修。
- 任何"消不掉"的符号：先写清尝试过的方案，再按 §6.4 格式进豁免清单，
  由 Kimi 复核理由是否成立。