oak-editor/docs/zh/plans/completed/r5-phase3-final-guide.md

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 复核理由是否成立。