# 6 [process] Mindmap Kernel Phase 6：leptos-mindmap Projection Editor v1 > 更新时间：2026-05-10 > > 当前口径：`leptos-mindmap` > > 旧稿归档： > - `/mnt/Data1T/mnote/recycle/design/06-mindmap/process/6-mindmap-kernel-phase6-projection-editor-v1.rust-native-2026-05-10.md` > > 当前主线依据： > - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md` > - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md` > - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md` > - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md` > > 参考实现： > - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/lx-doc/mind-map` > - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/kmind-plugin` > - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/siyuan-kmind-plugin` ## 1. 文档目的 这份文档重新修正 Mindmap Phase 6 的落地口径。 旧稿把 Phase 6 定义为 `Rust / Leptos 原生 Projection Editor`，并把 `simple-mind-map` 排除在本轮 runtime 主链之外。该口径在长期上最干净，但在当前阶段等同于用 Rust 重写 `lx-doc/mind-map` / `simple-mind-map` 的编辑器和布局引擎，短期会继续产出可验证但不可用的导图纵切。 当前口径改为： > **leptos-mindmap：Rust kernel 持有导图事实源与命令语义，`simple-mind-map` / KMind-like runtime 作为 Leptos 文档页中的编辑器 adapter。** 这份文档回答的是： > **如何在不放弃 tree-first graph kernel 的前提下，先交付接近 KMind 可用度的导图编辑器。** ## 2. 先给结论 Phase 6 不再以 Rust 自绘导图 renderer 为第一目标。 Phase 6 的主目标是建立： ```text kernel truth -> mindmap.kernel_projection.v1 -> mindmap.simple_mind_map_scene.v1 -> leptos-mindmap editor island -> simple-mind-map / KMind-like runtime -> adapter diff / command bridge -> kernel command ``` 其中： - Rust kernel 是事实源。 - `simple-mind-map` 是显示与交互 runtime。 - `leptos-mindmap` 是二者之间的稳定 adapter。 - `lx-doc/mind-map` 和 KMind 插件是行为、视觉、工具栏、侧栏和主题的参考实现。 - 旧 React `MindmapBlock.tsx` 只能作为 legacy/compat 参考，不作为当前文档页主链。 - TypeScript NodeView / bridge 只允许作为 `leptos-tiptap` 与 `simple-mind-map` 的薄兼容层；toolbar、sidebar、navigator、context menu 等 UI shell 的长期归属应逐步迁到 Leptos/Rust 组件，避免继续扩散 React/Vue/TS UI 运行时。 这不是“直接嵌入 `lx-doc/mind-map` 保存 blob”，也不是“立即 Rust 重写 `lx-doc/mind-map`”。它是中间路线： > **Rust 内核 + lx-doc/KMind 级显示编辑体验。** ## 3. 三条路线的定位 ### 3.1 Rust 重写 lx-doc/mind-map 这是长期最干净的路线。 优点： - kernel、projection、layout、hit-test、selection、history 都能完全统一。 - AI/CLI 可直接操作导图内核，不被前端库字段绑架。 - 长期不受 `simple-mind-map` 事件粒度、数据格式和插件边界限制。 问题： - 实际上要重写的是 `simple-mind-map` 引擎，而不只是 `lx-doc/mind-map` 的 Vue UI。 - 需要自研布局、节点测量、连线、概要、外框、关联线、拖拽、快捷键、导入导出、主题、MiniMap、富文本等完整编辑器能力。 - 短期会牺牲可用体验。 结论： > 保留为长期方向和后续 Rust-native engine 路线，但不再作为 Phase 6 的主验收。 ### 3.2 Rust 内核 + lx-doc/mind-map 显示 这是当前推荐路线，即 `leptos-mindmap`。 优点： - 能快速获得接近 KMind 的可用编辑体验。 - Rust kernel 仍然持有事实源、projection 和 command。 - 可以逐步把 `simple-mind-map` 字段提升为 kernel-native 语义。 - 与 `leptos-tiptap` 的定位一致：前端编辑器是 runtime，不是系统事实源。 问题： - `simple-mind-map` 的事件不一定足够细，需要 adapter diff。 - 高级能力短期可能需要 `compat_payload`。 - 必须严格防止回退成“保存整棵前端 blob”。 结论： > 作为 Phase 6 主线。 ### 3.3 直接嵌入 lx-doc/mind-map 这是最快路线，但不作为主线。 优点： - 最快得到完整 UI。 - 迁移成本看起来最低。 问题： - `lx-doc/mind-map` 会重新成为事实源。 - 长期仍保存 `simple-mind-map` blob。 - kernel、AI、Page Aggregate、tree realtime 只能在外围补偿。 结论： > 只可作为短期 demo 或对照，不作为 mnote 主线。 ## 4. leptos-mindmap 的边界 `leptos-mindmap` 是一个编辑器 adapter，不是新的事实源。 它负责： - 在 `leptos-tiptap` NodeView 中挂载导图编辑器。 - 把 kernel projection 转成 `simple-mind-map` 可消费的数据。 - 初始化并管理 `simple-mind-map` runtime 和必要插件。 - 监听导图数据与视图变化。 - 把变化转成 kernel command 或 adapter diff。 - 渲染 KMind-like toolbar、右侧样式栏、底部工具和错误状态。 - 承载 floating overlay canvas shell，并逐步把 UI shell 从临时 TypeScript DOM 渲染迁回 Leptos/Rust 组件边界。 它不负责： - 长期保存整棵导图 blob。 - 绕过 kernel command 直接把前端 runtime 数据写成 canonical truth。 - 在 UI 层创造第二套树真相、顺序真相或引用边真相。 - 把 `window.__mindmapInstance`、React mount 点或占位 DOM 作为完成判定。 - 把 TypeScript NodeView 扩写成长期 UI 框架；TS 只保留 tiptap / runtime bridge、动态加载、事件转发和最小 DOM mount 职责。 ## 5. 数据分层 ### 5.1 kernel truth 长期事实源应表达： - `Mindmap` - `MindmapNode` - parent / child order - collapsed state - summary / generalization - associative line - node style - link / reference edge - theme / layout / view state 这些字段应属于 kernel 或 kernel projection，不能只存在于 `simple-mind-map` blob。 ### 5.2 mindmap.kernel_projection.v1 这是稳定投影，供 AI、CLI、独立页、文档页和后续 Rust-native renderer 使用。 它应包含： - `schema` - `documentId` - `mindmapId` - `rootNodeId` - `revision` - `nodes` - `edges` - `summaries` - `associativeLines` - `layout` - `theme` - `view` - `capabilities` - `source` ### 5.3 mindmap.simple_mind_map_scene.v1 这是 adapter projection，只服务 `simple-mind-map` runtime。 它应包含： - `root` - `layout` - `theme` - `themeConfig` - `view` - `config` - `compatPayload` - `projectionRevision` - `kernelRevision` 注意：这层可以长得像 `simple-mind-map`，但它不是 canonical truth。 ### 5.4 compat_payload 短期无法语义化的字段进入 `compat_payload`。 允许先放入： - 高级节点样式 - 图片 - 公式 - 附件 - 富文本片段 - 第三方插件私有字段 - KMind 专有扩展 但每个字段必须有提升策略，不能无限期成为黑箱。 ## 6. 命令桥接 Phase 6 最小命令集： - `mindmap.node.update_text` - `mindmap.node.insert_child` - `mindmap.node.insert_sibling_after` - `mindmap.node.delete` - `mindmap.node.move` - `mindmap.view.patch` - `mindmap.layout.set` - `mindmap.theme.set` - `mindmap.summary.set` - `mindmap.associative_line.upsert` 桥接方式分两级。 ### 6.1 直接命令 如果 toolbar 或快捷键能明确知道用户意图，直接发 kernel command。 示例： - 点击“子节点” -> `mindmap.node.insert_child` - 点击“同级节点” -> `mindmap.node.insert_sibling_after` - 节点文本提交 -> `mindmap.node.update_text` - 删除节点 -> `mindmap.node.delete` ### 6.2 adapter diff 如果 `simple-mind-map` 只给出 `data_change`，则对比上一份 adapter projection 和当前 runtime data。 diff 输出： - 可识别变化转 kernel command。 - 暂不可识别变化转 `compat_payload.patch`，并打上 `source="adapter-diff"`。 禁止把整棵 runtime data 直接作为 canonical success。 ## 7. UI 对标范围 第一阶段对标 `image copy 60.png` 和 KMind/lx-doc 体验，但不追全量功能。 必须有： - 顶部工具栏：撤销、重做、编辑节点、同级节点、子节点、删除节点、标签、超链接、备注、图片、图标、概要、关联线、公式、格式刷、导入、导出。 - 中央画布：真实节点、连线、pan、zoom、选择、双击编辑、键盘基本操作。 - 右侧触发栏：节点样式、导图样式、主题、结构、大纲。 - 底部工具：节点数/字数、回到根节点、搜索、缩放百分比、全屏或只读入口。 - 错误状态：projection 获取失败、command 失败、adapter diff 失败要可定位。 可延期： - 完整主题设计器。 - 多根节点。 - 思源块悬浮预览。 - 镜像块。 - MOC 模式。 - PDF 标注跳转。 - 全量 XMind/Freemind 导入导出。 ## 8. 代码落点建议 ### 8.1 Rust 协议层 - `rust/crates/core-protocol/src/mindmap.rs` - 定义 kernel projection DTO。 - 定义 adapter projection DTO。 - 定义 command DTO。 - 标记旧 `MindmapTreeNode` / `MindmapOp` 为 compat。 ### 8.2 Rust runtime 层 - `rust/crates/bridge-runtime/src/lib.rs` - 构建 `mindmap.kernel_projection.v1`。 - 构建 `mindmap.simple_mind_map_scene.v1`。 - 执行 kernel command。 - 维护 compat snapshot。 ### 8.3 Rust Web 层 - `rust/crates/mnote-web/` - 暴露 projection / command route。 - 保持 3000 是前端公开入口。 - 不在 Rust Web 内联第三方编辑器业务逻辑。 ### 8.4 Leptos / Tiptap 层 - `rust/spikes/leptos-tiptap-spike/src/lib.rs` - 提供 mindmap NodeView。 - 挂载 `leptos-mindmap` island。 - Tiptap 节点只保存 `mindmapId/rootNodeId/projectionVersion` 等引用。 ### 8.5 前端 adapter 层 建议新增或收口到： - `wolai-frontend/src/lib/mindmap/leptos-mindmap-adapter.ts` - `wolai-frontend/src/lib/mindmap/simple-mind-map-bridge.ts` - `wolai-frontend/src/lib/mindmap/mindmap-command-diff.ts` 实际目录可随现有 runtime 打包方式调整，但职责必须清楚。 ## 9. 验收标准 Phase 6 新验收不再要求 Rust 自绘 scene。 必须验证： - 文档页 `/` 插入 mindmap block 后进入 `leptos-tiptap` NodeView。 - NodeView 挂载 `leptos-mindmap`。 - 画布由 `simple-mind-map` / KMind-like runtime 渲染真实节点与连线。 - 默认骨架可见 `KMIND`、`二级节点`、两个 `分支主题` 和 `概要`。 - 修改节点文本后通过 kernel command 回写。 - reload 后从 kernel projection 恢复修改结果。 - smoke 输出结构化 JSON 和截图。 - 失败时能定位到 projection、adapter init、runtime render、diff、command 或 reload 阶段。 明确不通过： - 只看到标题或空容器。 - 只断言 React mount 点。 - 只断言 `window.__mindmapInstance`。 - 只保存整棵 blob 且无 kernel command。 - 把 `simple-mind-map` runtime data 当成唯一事实源。 ## 10. 2026-05-10 现实复核：当前实现差距 当前代码已打通 `mindmap.simple_mind_map_scene.get`、`mindmap.command.apply`、reload 后文本保留和最小 smoke，但这只能证明 projection / command 的纵切闭环。 它还不能证明 `leptos-mindmap` 已完成。 已确认的差距： - `leptos-tiptap` NodeView 当前仍在 `tiptap_paragraph.ts` 内手写 DOM。 - 当前所谓 `simple-mind-map-runtime` 只是一个带 `data-runtime="simple-mind-map"` 的容器，不是 `new MindMap(...)` 创建的真实实例。 - 节点是手写 `