docs: archive completed C ABI campaign docs under plans/completed/

Move the finished migration campaign docs (handoffs v3-v6, roadmap, R5 guides, R6 cleanup, R7 pure-ABI) from docs/zh/ into docs/zh/plans/completed/ with an archive README; fix all cross-references; refresh plans/README.md index (active plans now marked unlocked).
2026-07-27 01:52:52 +08:00
parent d7c0970d91
commit dd5508e571
32 changed files with 1122 additions and 1438 deletions
@@ -89,7 +89,7 @@ ctest --test-dir build --output-on-failure
 - 所有测试必须使用 **Google Test** 编写，
 - 面向引擎代码的 C ABI 边界契约。

-更多项目文档：[中文文档目录](./)、[`facade-migration-roadmap.md`](facade-migration-roadmap.md)、[`riir.md`](plans/riir.md)、[`gtest-migration-guide.md`](plans/gtest-migration-guide.md)。
+更多项目文档：[中文文档目录](./)、[`facade-migration-roadmap.md`](plans/completed/facade-migration-roadmap.md)、[`riir.md`](plans/riir.md)、[`gtest-migration-guide.md`](plans/gtest-migration-guide.md)。

 ## 许可证

@@ -1,25 +1,31 @@
 # 长期计划（plans）

-本目录收纳 Oak 的**中长期规划文档与并行执行计划**。当前正在进行的
-**C ABI 迁移战役**的文档在上一层（`docs/zh/`），见下方"当前进行中"。
+本目录收纳 Oak 的**中长期规划文档与并行执行计划**。已完成的战役
+文档归档在 [`completed/`](completed/)；进行中的计划在下方目录。

 ## 目录

 | 文档 | 内容 | 启动前提 |
 |---|---|---|
 | [`riir.md`](riir.md) | **RIIR 绞杀者模式执行计划**：C ABI 迁移完成后，把 liboakengine 安全拆成若干小模块，再逐个用 Rust 重写；含 API 冻结保证、模块图、六步流程与验证门禁 | C ABI 迁移战役验收完成 |
-| [`riir/`](riir/) | **模块拆分执行手册**（riir.md 第一阶段落地）：00 总览 → 01 双层适配器规范 → 02 依赖矩阵与拆分顺序 → 03 测试规范 → M1-M9 逐模块手册（C API 冻结）；只拆分不重写，模块间 C ABI | R7 完成后启动（可与 R7 并行准备） |
+| [`riir/`](riir/) | **模块拆分执行手册**（riir.md 第一阶段落地）：00 总览 → 01 双层适配器规范 → 02 依赖矩阵与拆分顺序 → 03 测试规范 → M1-M9 逐模块手册（C API 冻结）；只拆分不重写，模块间 C ABI | 已解锁（R7 完成），随时启动 |
 | [`ai-agent-design.md`](ai-agent-design.md) | **AI Agent 设计**：多模态 LLM 经 MCP 调用策展工具面自动剪辑，渲染帧回喂形成"编辑→看图→再编辑"视觉闭环；含工具面、回放回路、安全与测试 | RIIR 拆分完成（面对一堆小库） |
-| [`gtest-migration-guide.md`](gtest-migration-guide.md) | **测试统一到 Google Test**：把 OAK_ADD_TEST 宏框架、纯 C assert、已有 gtest 三套收敛为单一 Google Test，ctest 仅作运行器 | R5 验收完成后启动（可与 UI 改版并行） |
-| [`ui-redesign-plan.md`](ui-redesign-plan.md) | **主界面 UI 改版**：依据 `design/` 三张设计图落地 10 个工作包（工具条、双监看、效果栈检查器、节点编辑器移位、电平条、状态栏等），全部文字精确定义 | R5 验收完成后启动（可与 GTest 迁移并行） |
+| [`gtest-migration-guide.md`](gtest-migration-guide.md) | **测试统一到 Google Test**：把 OAK_ADD_TEST 宏框架、纯 C assert、已有 gtest 三套收敛为单一 Google Test，ctest 仅作运行器 | 已解锁（R5-R7 完成），可与 UI 改版并行 |
+| [`ui-redesign-plan.md`](ui-redesign-plan.md) | **主界面 UI 改版**：依据 `design/` 三张设计图落地 10 个工作包（工具条、双监看、效果栈检查器、节点编辑器移位、电平条、状态栏等），全部文字精确定义 | 已解锁（R5-R7 完成），可与 GTest 迁移并行 |

-## 当前进行中（不在本目录）
+## 已完成（completed/）

-C ABI 迁移战役的执行文档在 `docs/zh/`：
+C ABI 迁移战役（B1-R7，nm 557→0 + visibility 收口 3486→19）的
+全套文档归档在 [`completed/`](completed/)：

- `c-abi-migration-handoff.md`（v3 交接）、`c-abi-migration-handoff-v4.md`（v4 重做计划）
- `facade-migration-roadmap.md`（批次记录）
- `r5-app-migration-guide.md`、`r5-phase2-detailed-guide.md`（R5 app 侧迁移指引）
+- 交接：[`c-abi-migration-handoff.md`](completed/c-abi-migration-handoff.md)（v3）、`-v4`、`-v5`、`-v6`
+- 战役记录：[`facade-migration-roadmap.md`](completed/facade-migration-roadmap.md)
+- R5：[`r5-app-migration-guide.md`](completed/r5-app-migration-guide.md)、
+  [`r5-phase2-detailed-guide.md`](completed/r5-phase2-detailed-guide.md)、
+  [`r5-phase3-final-guide.md`](completed/r5-phase3-final-guide.md)、
+  [`r5-final-sprint.md`](completed/r5-final-sprint.md)
+- R6/R7：[`r6-cleanup-plan.md`](completed/r6-cleanup-plan.md)、
+  [`r7-pure-abi-plan.md`](completed/r7-pure-abi-plan.md)

 ## 其他参考

@@ -0,0 +1,24 @@
+# 已完成战役归档（completed）
+
+本目录归档 **C ABI 迁移战役（B1-R7）** 的全套文档。战役已结束：
+
+- 成果：oak-editor / oak-render-worker / oak-cli 的 `U _ZN5olive` 从
+  557 降为 **0**；liboakengine.so 导出 C++ 符号从 3486 收至 19
+  （oakgl/oakvulkan dlopen 插件 ABI）；ctest 45/45。
+- 合并：压合为 6 个主题提交合入 main（`6ea653e6d`）。
+
+## 文档索引
+
+- **战役记录**：`facade-migration-roadmap.md`（各批次完成记录）
+- **交接文档**（执行过程的快照，记录历任执行者状态）：
+  `c-abi-migration-handoff.md`（v3）、`-v4`、`-v5`、`-v6`
+- **R5**（app 侧符号消除 557→58）：
+  `r5-app-migration-guide.md`、`r5-phase2-detailed-guide.md`、
+  `r5-phase3-final-guide.md`、`r5-final-sprint.md`
+- **R6**（豁免清单清零 58→0）：`r6-cleanup-plan.md`
+- **R7**（display.h POD 化 + visibility 收口）：
+  `r7-pure-abi-plan.md`
+
+这些文档**只作历史参考**，其中的"当前状态/进行中"描述均已是
+过去时。后续工作在上一层：`../riir/`（模块拆分）、
+`../gtest-migration-guide.md`、`../ui-redesign-plan.md`。
@@ -81,7 +81,7 @@ cd cmake-build-debug && ctest --output-on-failure -j$(nproc)
  colorcodingapp、filefunctionsapp、hashstreamapp、htmlapp、xmlutilsapp、debugapp）、
  各 handle 头（keyframehandle/markerhandle/cliphandle/trackhandle/colorprocessorhandle/
  vieweroutpututils）、`markerpainting.*`、`app/timeline/`、`app/ui/icons/`。
- **文档**：v3 交接文档（`c-abi-migration-handoff.md`）、RIIR 计划（`plans/riir.md`）、
+- **文档**：v3 交接文档（`c-abi-migration-handoff.md`）、RIIR 计划（`../riir.md`）、
  roadmap 批次记录（经 LocalHistory 恢复，`facade-migration-roadmap.md`）。
 - **结构性改动**：B1 图标（engine 返回图标名 + app from_name 映射，已修复一致）、
  B2 布局 POD（SerializedLayoutInfo 全链路，已修复一致）、B3 coreengine.h、
@@ -102,7 +102,7 @@ UndoCommand(3)。
 4. ✅ 反作弊审计：app 无 `dlfcn.h`/dlsym/QLibrary 解析 engine 符号；
   engine 无 inline 化（oakengine/*.h 纯 C 声明）。
 5. ✅ `facade-migration-roadmap.md` 附 C R6 节已记录；
-   `plans/riir.md` §1.1 状态已更新为"边界已纯"。
+   `../riir.md` §1.1 状态已更新为"边界已纯"。

 > 已知遗留（已论证，不泄漏符号）：app 仍 include 约 40 个 engine C++ 头
 > （node/render/timeline/undo/pluginSupport，用于类型与 inline 访问器），
@@ -4,7 +4,7 @@
 > 所有架构决策、边界契约、禁止事项已在本文钉死，执行时不得另行发明新方案；
 > 遇到本文未覆盖的决策点，按"§8 决策兜底原则"处理，不得自由发挥。
 >
-> 相关文档：`docs/zh/facade-migration-roadmap.md`（各批次完成记录 + 附 D 事件机制 SOP）。
+> 相关文档：`facade-migration-roadmap.md`（各批次完成记录 + 附 D 事件机制 SOP）。
 >
 > v3（2026-07-23）：K2.7 对 DeepSeek Flash 的产出做了验收，修复了 6 个真实缺陷
 > （详见 §2.2，每条都附教训——**这些错误模式不得再犯**）。当前符号 39、
@@ -309,7 +309,7 @@ set_value_at_time/staticMetaObject）从 inline 函数拉入，进豁免清单

 ### R6：豁免清单清零（58 → 0，100% C ABI）— 完成

-> 详见 `docs/zh/r6-cleanup-plan.md`（各 P 节已标 ✅）。目标：把 R5 遗留的
+> 详见 `r6-cleanup-plan.md`（各 P 节已标 ✅）。目标：把 R5 遗留的
 > 58 个豁免符号全部消除到 0，为 engine 模块化拆分与 RIIR 打地基。

 - **P1（F 类 facade 补齐，17）**：NodeValue 静态方法、VideoParams 构造器、
@@ -1,8 +1,8 @@
 # R5 终局计划：181 → 豁免清单（≤6）

 > 面向执行者（DeepSeek Flash），自包含。工作分支：`c-abi-migration`。
-> 前置文档：`../facade-migration-roadmap.md`（批次记录）、
-> `../r5-app-migration-guide.md`（R5 总指引）、`../c-abi-migration-handoff.md`
+> 前置文档：`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 复核 + 立即提交。
@@ -5,7 +5,7 @@
 > **背景**：R5 已把 app 对 engine 的 `olive::` C++ 符号从 557 降到 58，
 > 剩余 58 个以"豁免清单"形式记录在 `c-abi-migration-handoff.md` §6.4。
 > 本计划的目标是把它们**全部消除到 0**——这是后续 engine 模块化拆分
-> 与 Rust 重写（RIIR，见 `plans/riir.md`）的硬前提：C ABI 边界上不能
+> 与 Rust 重写（RIIR，见 `../riir.md`）的硬前提：C ABI 边界上不能
 > 残留任何 C++ 渗漏。
 >
 > **三条红线**（违反即返工）：
@@ -476,7 +476,7 @@ app 侧：`manageddisplay`/`viewerdisplay` 不再 `new OpenGLRenderer`，
   （`grep -rn '#include "' app/ | grep -E '"(node|undo|task|render|timeline|pluginSupport)/'`
   应为空或只剩极个别已论证的）。
 4. `c-abi-migration-handoff.md` §6.4 豁免清单清空（改为"无豁免"），
-   roadmap 补 R6 批次记录，`plans/riir.md` 状态更新为"边界已纯"。
+   roadmap 补 R6 批次记录，`../riir.md` 状态更新为"边界已纯"。

 ## 执行顺序与节奏建议

@@ -207,7 +207,7 @@ grep -E '"(node|render|timeline|undo|task|pluginSupport)/'`）。不产生
 1. `display.h` 全文无 C++ 类型签名/契约注释；app 无 TexturePtr/FramePtr。
 2. liboakengine.so ` T _Z` = 0；oak-editor ` U _ZN5olive` 保持 0。
 3. 全量构建 0 error；全量 ctest 绿。
-4. 更新 `plans/riir.md` 状态（边界已纯 → 可进 Step 1 拆分）、
+4. 更新 `../riir.md` 状态（边界已纯 → 可进 Step 1 拆分）、
   `facade-migration-roadmap.md` R7 批次记录。
 5. 向用户报告，由用户宣布进入 riir.md §4 的模块拆分阶段。

@@ -225,4 +225,4 @@ grep -E '"(node|render|timeline|undo|task|pluginSupport)/'`）。不产生
 - R7-C（app 的 ~40 个 engine C++ 头清理）未做，转入 riir/ 模块
  拆分阶段顺带处理（M 系列手册的适配头天然覆盖）。
 - 验收：构建 0 error、ctest 45/45、双二进制 nm U _ZN5olive = 0。
-  **RIIR 模块拆分（plans/riir/ M1-M9）解锁。**
+  **RIIR 模块拆分（../riir/ M1-M9）解锁。**
@@ -1,6 +1,6 @@
 # RIIR 绞杀者模式执行计划：liboakengine 模块化拆分与渐进式 Rust 重写

-> 本文档描述在 C ABI 迁移战役（见 `c-abi-migration-handoff.md`）完成之后，
+> 本文档描述在 C ABI 迁移战役（见 `completed/c-abi-migration-handoff.md`）完成之后，
 > 如何用绞杀者模式（Strangler Fig）把 liboakengine.so 安全地拆成若干小模块，
 > 再逐个重写为 Rust。
 > **核心约束：每一步都可验证、可回退；任何一步失败都不影响已验证的部分。**
@@ -103,7 +103,7 @@

 ### Step 1 — 冻结 ABI
 - 评审模块对外 C ABI 头（公开 facade 已有部分直接复用；模块间内部调用需要的
-  新增内部头，按 `c-abi-migration-handoff.md` §6.1 的同一套规则写：纯 C 类型、
+  新增内部头，按 `completed/c-abi-migration-handoff.md` §6.1 的同一套规则写：纯 C 类型、
  buf/size 约定、owned/borrowed 注释、错误码）。
 - 用门禁脚本生成 ABI 快照（§5-G1）并入库。**此后该头的任何改动都是显式评审行为。**

@@ -22,7 +22,7 @@ oakrender/

 ### 2.1 `oakrender/renderer.h`（渲染器/纹理/blit）

-签名照 R7-A（`docs/zh/r7-pure-abi-plan.md` §A.2）的 display.h 重写版
+签名照 R7-A（`docs/zh/plans/completed/r7-pure-abi-plan.md` §A.2）的 display.h 重写版
 **原样采用**——R7-A 先做的话，M7 直接把它从 facade 层搬进
 oakrender 并改前缀 `oakrender_display_*`；本表不重复，以 R7-A 为准。
 补充后端管理：
@@ -1,7 +1,7 @@
 # Oak 主界面 UI 改版计划

 > 本文是主界面重新设计的执行手册，面向 DeepSeek Flash（**不识字图，本文全部
-> 用文字精确定义目标形态**）。详细程度对齐 `../r5-app-migration-guide.md`。
+> 用文字精确定义目标形态**）。详细程度对齐 `completed/r5-app-migration-guide.md`。
 > 工作分支：`c-abi-migration`。**启动前提：R5（C ABI app 侧迁移）验收完成之
 > 后**；启动后可与 Google Test 统一迁移并行——协调规则见 §2。
 > 依据：`design/Oak-UI设计图-主界面-标注版.png`、`...-效果栈版.png`、
@@ -13,7 +13,6 @@

 ```
 ┌ 菜单栏：文件(F) 编辑(E) 视图(V) 回放(P) 序列(S) 窗口(W) 工具(T) 帮助(H)
-├ 工具条(31px)：14 个工具图标 + 吸附开关 + 缩放滑块 + 轨道高度滑块
 ├────────────────────────────────────────────────────────────────────
 │ 素材查看器(源)        │ 序列查看器(节目) │  检查器│历史记录
 │  ·适合/安全框         │  ·适合/安全框     │  ┌──────────────────┐
@@ -24,6 +23,7 @@
 │                     │                │  [+ 添加效果]        │
 │                     │                │  └──────────────────┘
 ├────────────────────────────────────────────────────────────────────
+├ 工具条(31px)：14 个工具图标 + 吸附开关 + 缩放滑块 + 轨道高度滑块
 │ 时间线(全宽贯通)                                                │
 │ 轨道头180px │ 轨道区                                              │
 │ V2 视频轨道1 [锁定][显示]  ████████                               │