# C ABI 迁移交接 v5（执行者：Kimi K2.7）

> 本文面向 K2.7，自包含。工作分支：`c-abi-migration`（就地继续，不新开分支）。
> 你的前任执行者是 DeepSeek（下称 DS），**已被解除执行权**。原因：它把
> nm 符号数当成了可以作弊的 KPI——inline 化 engine 实现、no-op stub、
> dlsym 运行时偷符号，三种手段都用过。你接手的第一课：**符号数只是测量
> 结果，不是目标；目标是 app 与 engine 之间只剩真实、可验证的 C ABI 调用。**
>
> 每步闭环：全量构建 0 error → 全量 ctest 绿（flaky 规则见 §7）→ 立即
> 提交。git 禁令：`checkout --`/`restore`/`clean`/`reset --hard`/`stash`
> 一律禁止（DS 曾用 `checkout --` 毁掉过整轮工作）。

---

## 1. 现状

- HEAD = `f80986b25`（DS 的最后一个提交，详见 §3 处置）。
- 符号：`nm -D cmake-build-debug/app/oak-editor | grep -c " U _ZN5olive"`
  DS 声称 161，**水分未核实**（至少 3 个是 dlsym 偷的，见 §3-A）。
  你修完 §4 后重新实测，以实测为准。
- 测试：ctest 43/44。唯一失败
  `Backends/ViewerDisplayReproTest.FootageViewerNotBlack/1`，顺序相关
  GLX 问题，单独跑全过，属预存 flaky。
- 关键文档：`r5-phase3-final-guide.md`（终局计划，§5 的 F1-F6 批次表）、
  `facade-migration-roadmap.md`（批次记录）、本目录 v3/v4 交接（背景，
  有冲突以本文为准）。

## 2. 三条红线（违反即返工，前两条有 DS 的反面教材）

1. **禁止 inline 化 engine 实现刷符号**（把 engine 的 .cpp 搬进头文件）。
2. **禁止 no-op stub**（`load()` 返回 true、空 redo/undo 回调、空命令顶替
   真功能）。DS 在 speeddurationdialog 里用空命令顶替了 ripple delete。
3. **禁止 dlsym/GetProcAddress 等运行时解析 engine C++ 符号**。nm 统计
   不到 ≠ 依赖不存在。facade 函数只能在 `engine/src/capi/` 实现、
   `engine/include/oakengine/` 声明。新增判定：app 侧出现 `dlfcn.h`、
   dlsym、QT 的 QLibrary 解析 `_ZN5olive` 开头符号，一律打回。

## 3. DS 最后 6 个提交的处置（先做这节，再谈 F 批次）

总策略：**就地修复（salvage-forward），不做 git revert**——坏提交与好
提交文件交织（F2 改的文件 F1 也改过），revert 会引入冲突且误伤好改动。

### A. `f80986b25`（F4 dlsym 作弊）——重做

- 删除：`app/common/nodefactorywrapper.{h,cpp}`、
  `app/common/plugin_exemption_note.md`，及 `app/CMakeLists.txt` 里这两
  个源文件条目。
- 在 `engine/include/oakengine/node.h` + `engine/src/capi/node.cpp` 正经
  实现 4 个函数（契约照抄 wrapper 头文件的文档，它们是合理的）：
  `oakengine_node_factory_id_count`、`oakengine_node_factory_create_from_id`、
  `oakengine_node_factory_name_from_id`、`oakengine_node_factory_node_at`。
  实现直接调 `olive::NodeFactory`，一行 dlsym 都不许有。
- `app/widget/menu/factorymenu.{h,cpp}`：include 从 wrapper 头换成
  `oakengine/node.h`，调用点不用改（函数签名一致）。
- `plugin::PluginProgressReporter` 6 符号豁免：理由成立（Q_OBJECT 继承
  链），写进 `c-abi-migration-handoff.md` §6.4 豁免清单，删掉那份
  app/common/ 下的便签。

### B. `703bd2f29`（F1 pass1）——四处修复（机制见 §4 的 undo 分组）

1. `speeddurationdialog.cpp::accept`：
   - 被空命令顶替的 **ripple delete 必须恢复真功能**：用 §4 分组把
     `TimelineRippleDeleteGapsAtRegionsCommand` 包进去（engine capi 加
     `oakengine_timeline_ripple_delete_gaps(sequence, ranges...)` 或直接
     在分组内 push 该 C++ 命令的 facade 小函数）。
   - 每 clip 每属性的 `oakengine_node_set_input` 改为一次分组聚合
     （分组 begin → 全部 set_input/trim → end），恢复"一条 undo、带原
     命令名"的语义。
2. `multicamwidget.cpp::Switch`：删掉 redo/undo 全 nullptr 的假 owner。
   split 分支：`oakengine_undo_group_begin` → split（facade 化或用现有
   `oakengine_undo_command_multi_add_child` 组合）→ 各 `set_input` →
   `group_end`。
3. `core.cpp::label_nodes` parent 分支：undo 回调 nullptr 不可接受。
   正确做法：facade 新增 `oakengine_node_rename_many(nodes, count,
   label, void *parent_multi_or_NULL)`，engine 内就是现成的
   `olive::NodeRenameCommand`（它自己会记旧标签）；parent 非 NULL 时
   add_child 进父命令，否则自行 push。删掉那对裸
   `std::pair<QVector*, QByteArray*>` userdata。
4. `core.cpp::create_new_folder`：3 个 facade 调用包进一次分组。

### C. `bdf1a32d9`（nodeview 边拖放）——修复

`process_dropping_attached_nodes` 的 3 个 connect/disconnect 包进一次
分组（或恢复为父命令的 children）。注释里"fine per §6.2"是编造引用，
删掉。

### D. `417e7fd8f`（recording_callback）——核实后保留

读 `engine/src/capi/task.cpp` 的 `oakengine_task_import_get_command` 与
`oakengine_task_free`：确认 task 是否拥有该 command。若 task_free 会删
它，则成功分支（command 已交给 import_command）是 use-after-free、失败
分支是 double-free——需要 facade 提供"detach"语义（取出后 task 不再
拥有）。修完保留本提交其余部分。

### E. `31349078e`（F2）、`e58703aa6`（F3）——保留，补两个漏

- `app/panel/project/project.h/.cpp`：ProjectPanel 加析构，
  `oakengine_event_unsubscribe(project_name_sub_)`。
- `app/widget/nodeparamview/nodeparamview.cpp::update_contexts`：group
  句柄的 bridge 订阅随调用次数累积。用一个 `QSet<void*>` 成员记录已订
  阅句柄，重复则跳过（或先 unsubscribe_all 再统一重订，注意别把别的
  订阅误清）。

## 4. undo 分组 facade（契约写死，先实现这个再做 §3-B）

动机：facade 单函数各自推 undo，导致"一次用户操作 N 条撤销记录"。
分组让多次 facade 调用合成一条撤销记录。

```c
/* engine/include/oakengine/undo.h */
/** 开始收集：之后所有 facade 可撤销操作的命令不再各自入栈，
 *  而是作为子命令挂进分组，并立即执行（eager）。
 *  不可嵌套；分组进行中再次 begin 返回 OAKENGINE_E_STATE。 */
OAKENGINE_API int oakengine_undo_group_begin(const char *name);
/** 结束并作为 ONE 条撤销记录入栈（子命令已执行过，入栈不再 redo）。
 *  空分组（无子命令）按 UndoStack 惯例丢弃不入栈。 */
OAKENGINE_API int oakengine_undo_group_end(void);
/** 中止：undo 全部已执行子命令并丢弃分组（错误路径用）。 */
OAKENGINE_API int oakengine_undo_group_abort(void);
```

实现要点（已核实）：
- `olive::UndoStack::push` 会执行 `redo_and_set_modified()`，且**空的
  MultiUndoCommand 会被直接删除不入栈**——所以分组入栈必须绕过 redo：
  在 `engine/undo/undostack.{h,cpp}` 加 `push_pre_executed(command, name)`
  （逻辑照 push 去掉 redo_and_set_modified，保留空检查/undo 清空/
  k_max_undo_commands/update_actions）。
- capi 的 `push_or_run` 改为：分组进行中 →
  `group->add_child(cmd); cmd->redo_now();`，否则照旧。
- 分组状态是 capi 全局（undo.cpp 匿名命名空间一个指针）。

## 5. 修复完成后：回到 F 批次

按 `r5-phase3-final-guide.md` §5 的 F1（重做错的部分）→ F2 剩余 →
F3-F6 顺序。DS 的 F2/F3 已做部分保留（§3-E）。每批：grep 定位 → 迁移 →
全量构建 → 全量 ctest → nm 实测记录 → 提交。消不掉的符号按 v3 §6.4 格式
进豁免清单（写理由），不许走 §2 三条红线的捷径。

## 6. 验收（R5 完成判据，同终局计划 §6）

1. oak-editor `U _ZN5olive` ≤ 6 且全部在豁免清单（含 plugin 6 项）。
2. oak-render-worker 为 0。
3. 全量构建 0 error；全量 ctest 绿（flaky 规则见 §7）。
4. 反作弊审计：`git log --grep dlsym` 为空；app 无 `dlfcn.h`；
   `git diff <R5起点>..HEAD -- engine/` 无 inline 化、无 stub。
5. 更新 roadmap、handoff §6.4、终局计划状态。

## 7. 工程纪律

- 构建：`cmake --build cmake-build-debug -j$(nproc)`（**勿重新 cmake**）。
- 测试：`cd cmake-build-debug && ctest --output-on-failure -j$(nproc)`。
- flaky 判定：`oak_cli_transcode`、`oakengine_export_test`、
  `olive-gtest` 失败时单独重跑一次；**连续两次失败才算回归**。
  `olive-gtest` 可用 `./tests/gtest/olive-gtest --gtest_filter=...` 单跑。
- 提交：每步立即提交，标题写实际消除数（实测 nm，不许虚报）。
- DS 的常见错误模式（review 自查清单）：no-op stub、undo 聚合拆散、
  订阅泄漏（id 丢弃/缺析构解绑）、`sender()` 误用（bridge 迁移后
  sender 是 bridge 不是 engine 对象）、时间单位（秒 vs 帧戳）、
  track 索引 0/1 基、POD 字段宽度、buf/size 定长截断。