diff --git a/docs/zh/plans/riir/M14-direct-rlib.md b/docs/zh/plans/riir/M14-direct-rlib.md new file mode 100644 index 000000000..2314dfef0 --- /dev/null +++ b/docs/zh/plans/riir/M14-direct-rlib.md @@ -0,0 +1,66 @@ +# M14:前端绕过 facade 直链 rlib(纯 Rust ABI) + +> 前置:单库化(single-lib.md)+ 模块 bridge/ffi 清除已完成; +> liboakengine.dylib 的 C ABI 冻结,专供插件/外部消费者。 +> 本计划把三个第一方前端(app / oak-cli / oak-worker)从 dylib + C ABI +> 切换为直接静态链接各模块 rlib、纯 Rust 调用,根除 C ABI 边界的 +> 内存安全问题(P5a 双释放/悬空两次真实崩溃均发生在该边界)。 + +## 0. 形态决策(2026-08,已定) + +- **A 方案(用户拍板)**:app / oak-cli / oak-worker 只依赖 + oakcommon / oakundo / oaknode / oaktimeline / oakcodec / oakaudio / + oakrender / oaktask / oakplugin / oakstorage 的 rlib;不链接 + liboakengine(连 rlib 形态都不用)。 +- **oakengine 保留为纯 cdylib**:只给 OFX 插件和未来的外部消费者 + 用;它继续依赖同一批模块,C ABI 冻结不变(只增不改+大版本)。 +- **facade 里的胶水逻辑下沉**(不复制): + 1. **全局 undo 栈 + 分组**(oakengine undo.rs)→ oakundo 新增 + 进程全局栈模块(stack 已是 oakundo 的,facade 只是加了全局 + 单例 + 组 + capi 兼容动作)。 + 2. **写穿绑定**(oakengine storage.rs:project↔库会话绑定、undo + 路径挂钩、快照线程、退出 flush)→ oakstorage 的会话管理器 + + oakundo 全局栈的命令通知钩子。 + 3. **任务编排**(facade task.rs 的 meta 簿记/进度订阅)→ oaktask + 原生(订阅/take 已有,facade 只是包装)。 + 4. **库管理**(oakengine library.rs)→ oakstorage 直接面。 + 5. **效果链便捷函数 / sequence 编辑组合**(facade node.rs / + timeline.rs 的 effect_*、split/trim/ripple 组合)→ 多数已在 + oaktimeline/oaknode 有命令级原语;确属组合的,收到 oaknode + 的 ops.rs(它已是这个职责)。 + 6. **编码参数助手 / exporter 家族** → oakcodec::encodingparams + + oaktask::export(ExportTask 直接驱动)。 + 7. **渲染管理器 init/可用性** → oakrender::manager 直接。 + 8. **testmedia / 测试媒体** → oakcodec::testmedia(已在)。 +- **unsafe 边界收敛**:前端代码零 unsafe(gpui 必要的除外); + 模块内部 unsafe 只在插件边界(OFX C ABI)和底层库绑定 + (ffmpeg-next/ocio-sys)处。 +- **内存安全验收线**:前端不出现任何裸指针/CHandle;模块间对象 + 引用一律 Arc/引用(M13 的 CHandle 内部清除随本计划逐模块完成)。 + +## 1. 分期 + +| 期 | 内容 | 完成判据 | +|----|------|----------| +| R1 | 胶水下沉:oakundo 全局栈+通知、oakstorage 会话管理器、oaktask 任务面补齐、oaknode ops 组合函数 | 各模块自带测试绿;facade 改为转发下沉版(行为不变,全量绿) | +| R2 | oak-cli + oak-worker 切换(小,先蹚路) | 两 crate 零 oakengine 依赖,测试绿 | +| R3 | app 切换:src/oakui/ffi.rs、host_syms.rs 删除,real.rs 全量改 Rust 调用;AppEngine trait 不动(Mock 保留) | `cargo test`(根 crate)全绿;真机冒烟(导入/播放/编辑/导出) | +| R4 | oakengine 转纯 cdylib(workspace default-members 移除 rlib 使用点清零)、根 build.rs 链接逻辑删除、CD 去掉 app 内嵌 dylib | CI 绿;dmg 体积显著缩小(不再嵌 37-56MB dylib) | +| R5 | M13 遗留的 CHandle 内部清除逐模块完成(bridge 已删,剩 handle.rs 与模块内 CHandle 传参) | 模块内部无 CHandle 传参;C ABI 导出层(oakengine)独占 CHandle | + +依赖:R1→R2→R3→R4;R5 与 R2-R4 可并行。 + +## 2. 风险 + +| 风险 | 对策 | +|------|------| +| facade 胶水下沉破坏现有行为 | R1 先下沉+facade 转发,全量测试绿才进 R2 | +| app 调用面大(170 个 facade 函数) | real.rs 按面板/功能域分片迁移,每片绿后提交 | +| 模块 pub API 缺口 | 按需把内部函数升 pub(crate 内 #[doc] 注释) | +| 插件依赖 facade 路径行为差异 | oakengine 测试(it_* 全套)保留并继续绿 | +| CD 打包依赖 dylib 内嵌 | R4 更新 cd.yml(去掉 embed 步骤) | + +## 3. 不在本期 + +- 插件 ABI 改版(OFX 仍 C ABI);oakengine C ABI 任何签名变更; + Windows 打包启用(等 Windows 链接实测)。