# Mindmap Phase 6 leptos-mindmap Projection Editor v1 Implementation Plan > **For agentic workers:** REQUIRED SUB-SKILL: Use `superpowers:subagent-driven-development` where independent code slices exist, or `superpowers:executing-plans` when running this checklist task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. > > 旧 Rust-native 计划已归档： > `/mnt/Data1T/mnote/recycle/design/superpowers-plans/2026-05-10-mindmap-phase6-projection-editor-checklist.rust-native.md` **Goal:** 交付 `leptos-mindmap`：以 Rust kernel 作为导图事实源与命令面，以 `simple-mind-map` / KMind-like runtime 作为 `leptos-tiptap` NodeView 中的显示与交互 adapter。 **Architecture:** `kernel truth -> mindmap.kernel_projection.v1 -> mindmap.simple_mind_map_scene.v1 -> leptos-mindmap island -> simple-mind-map runtime -> adapter diff / command bridge -> kernel command`。 **Tech Stack:** Rust `core-protocol`、Rust `bridge-runtime`、Rust `mnote-web`、`leptos-tiptap` island、`simple-mind-map`、KMind/lx-doc reference code、Playwright smoke、Convex compat substrate。 --- ## 口径修正状态 - [x] 已确认旧 `Rust / Leptos 原生 Projection Editor` 口径过时。 - [x] 已将旧设计稿归档到 `recycle/design/06-mindmap/process/`。 - [x] 已将旧 checklist 归档到 `recycle/design/superpowers-plans/`。 - [x] 已把当前执行口径修正为 `leptos-mindmap`。 - [x] 后续每完成一个实现节点，必须在本 checklist 中勾选对应项。 - [x] 2026-05-10 现实复核：当前已勾选的 Task 6/7/8/退出标准只代表“projection / command 最小闭环 + 手写伪画布 smoke”通过，不代表真实 `simple-mind-map` runtime 已接入。最终 UI/runtime 完成判定以后续 `Phase 6.1` 为准。 ## 范围冻结 ### 本计划明确要做 - [ ] 定义 kernel projection 与 `simple-mind-map` adapter projection 的边界。 - [ ] 在 `leptos-tiptap` NodeView 中挂载 `leptos-mindmap`。 - [ ] 使用 `simple-mind-map` runtime 渲染真实导图画布。 - [ ] 参考 `lx-doc/mind-map` 和 KMind 插件复刻第一阶段 toolbar/sidebar/bottom bar。 - [ ] 通过 adapter command bridge 把用户编辑写回 Rust kernel。 - [ ] 对 `data_change` 这类粗粒度事件建立 diff 到 kernel command 的转换。 - [ ] 保留 `compat_payload` 承接暂未语义化的高级字段。 - [ ] 更新 smoke，验证真实节点、连线、编辑、reload 和截图证据。 ### 本计划明确不做 - [ ] 不把 `simple-mind-map` runtime data 作为 canonical truth。 - [ ] 不直接嵌入完整 Vue2 `lx-doc/mind-map` 应用并保存 blob。 - [ ] 不恢复旧 React `MindmapBlock.tsx` 作为 3000 文档页默认主链。 - [ ] 不要求本轮完成 Rust-native renderer。 - [ ] 不在本轮完整复刻 KMind 多根、MOC、镜像块、思源块预览、PDF 标注跳转。 - [ ] 不立即移除 Convex `mindmaps` blob；它只作为 compat substrate / import-export / fallback snapshot。 ## 文件职责图 - `design/06-mindmap/process/6-mindmap-kernel-phase6-projection-editor-v1.md` - 当前 `leptos-mindmap` 设计口径。 - `rust/crates/core-protocol/src/mindmap.rs` - kernel projection、adapter projection、command DTO。 - `rust/crates/bridge-runtime/src/lib.rs` - projection builder、adapter scene builder、command apply。 - `rust/crates/mnote-web/` - projection / command route 与 3000 文档页运行时分发。 - `rust/spikes/leptos-tiptap-spike/src/lib.rs` - mindmap NodeView 与 island 挂载。 - `wolai-frontend/src/lib/mindmap/*` - adapter、diff、simple-mind-map bridge、legacy compat。 - `wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx` - legacy React/simple-mind-map 参考实现，不作为默认主链。 - `design/05-editor-mainline/reference-code/lx-doc/mind-map` - UI、命令、插件和主题参考。 - `design/05-editor-mainline/reference-code/kmind-plugin` - KMind 打包实现和视觉行为参考。 - `scripts/task166-mindmap-phase6-block-smoke.js` - Phase 6 浏览器 smoke。 --- ### Task 1: 冻结 leptos-mindmap Contract **Files:** - Modify: `rust/crates/core-protocol/src/mindmap.rs` - Modify: `rust/crates/core-protocol/src/lib.rs` - Test: `rust/crates/core-protocol/src/lib.rs` - [x] 定义 `MindmapKernelProjection`，包含 `schema`、`documentId`、`mindmapId`、`rootNodeId`、`revision`、`nodes`、`edges`、`summaries`、`associativeLines`、`layout`、`theme`、`view`、`capabilities`、`source`。 - [x] 定义 `MindmapAdapterProjection`，包含 `schema`、`runtime="simple-mind-map"`、`root`、`layout`、`theme`、`themeConfig`、`view`、`config`、`compatPayload`、`kernelRevision`。 - [x] 定义最小 command DTO：`updateText`、`insertChild`、`insertSiblingAfter`、`deleteNode`、`moveNode`、`patchView`、`setLayout`、`setTheme`。 - [x] 标记 `MindmapTreeNode` / `MindmapOp` 为 compat DTO。 - [x] 补 Rust 单测：kernel projection 与 adapter projection 都能序列化为 camelCase JSON。 - [x] 验证命令：`cd /mnt/Data1T/mnote/rust && cargo test -p core-protocol mindmap`。 ### Task 2: 建立 Adapter Projection Builder **Files:** - Modify: `rust/crates/bridge-runtime/src/lib.rs` - Test: `rust/crates/bridge-runtime/src/lib.rs` - [x] 增加 `mindmap.kernel_projection.get` 查询。 - [x] 增加 `mindmap.simple_mind_map_scene.get` 查询。 - [x] 从 kernel truth 或 compat substrate 构建 `simple-mind-map` 可消费的 `root/layout/theme/view/config`。 - [x] projection 返回明确 `source`，如 `kernel`、`compat-blob`、`adapter-cache`。 - [x] 默认骨架包含 `KMIND`、`二级节点`、两个 `分支主题` 和 `概要`。 - [x] 补 Rust 单测：同一 mindmapId 能输出 kernel projection 和 adapter projection，节点数量一致。 - [x] 验证命令：`cd /mnt/Data1T/mnote/rust && cargo test -p bridge-runtime mindmap_projection`。 ### Task 3: 审计 lx-doc / KMind Runtime 能力 **Files:** - Inspect: `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/Edit.vue` - Inspect: `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/ToolbarNodeBtnList.vue` - Inspect: `design/05-editor-mainline/reference-code/lx-doc/mind-map/src/pages/Edit/components/SidebarTrigger.vue` - Inspect: `design/05-editor-mainline/reference-code/kmind-plugin/app/app.js` - Output Optional: `design/06-mindmap/process/6-mindmap-leptos-adapter-reference-notes-v1.md` - [x] 列出本轮需要注册的 `simple-mind-map` 插件。 - [x] 列出 toolbar 命令到 kernel command 的映射。 - [x] 列出右侧栏第一阶段保留项：节点样式、导图样式、主题、结构、大纲。 - [x] 列出底部工具第一阶段保留项：统计、搜索、缩放、回根节点、全屏或只读。 - [x] 列出必须进入 `compat_payload` 的字段。 - [x] 明确哪些 KMind 专有能力延期。 ### Task 4: 实现 simple-mind-map Bridge **Files:** - Create/Modify: `wolai-frontend/src/lib/mindmap/simple-mind-map-bridge.ts` - Create/Modify: `wolai-frontend/src/lib/mindmap/leptos-mindmap-adapter.ts` - Create/Modify: `wolai-frontend/src/lib/mindmap/mindmap-command-diff.ts` - [x] 动态加载 `simple-mind-map`，避免 SSR 阶段访问 `window/document`。 - [x] 注册本轮必需插件：Drag、KeyboardNavigation、Export、Select、RichText、AssociativeLine、Search、Scrollbar、OuterFrame 等按审计结果取舍。 - [x] 支持从 `MindmapAdapterProjection` 初始化 runtime。 - [x] 监听 `data_change`、`view_data_change`、`node_active`、`back_forward`、`scale`、`translate`。 - [x] 暴露 `execCommand` 安全包装，不让 UI 任意写 blob。 - [x] 销毁时清理 runtime、事件监听和定时器。 ### Task 5: 建立 Command Bridge 与 Diff **Files:** - Modify: `wolai-frontend/src/lib/mindmap/mindmap-command-diff.ts` - Modify: `rust/crates/bridge-runtime/src/lib.rs` - Test: relevant Rust and TS tests - [x] 直接命令优先：toolbar 明确动作直接发 kernel command。 - [x] `data_change` diff 能识别文本更新、插入子节点、插入同级节点、删除节点、移动节点。 - [x] `view_data_change` 转成 `mindmap.view.patch`。 - [x] 主题与结构变化转成 `mindmap.theme.set` / `mindmap.layout.set`。 - [x] 暂不可识别字段进入 `compat_payload.patch`，并记录字段路径。 - [x] command 成功后刷新 projection revision。 - [x] command 失败时 UI 显示可定位错误，不伪装保存成功。 ### Task 6: 嵌入 Leptos Tiptap Mindmap NodeView **Files:** - Modify: `rust/spikes/leptos-tiptap-spike/src/lib.rs` - Modify: relevant generated island runtime - Inspect/Modify: `design/05-editor-mainline/reference-code/leptos-tiptap/tiptap/src/extensions/tiptap_paragraph.ts` - [x] `/` 命令插入 mindmap block 时，Tiptap 节点只保存 `mnoteBlockType="mindmap"`、`mindmapId`、`rootNodeId`、`projectionVersion`。 - [x] NodeView 创建 `data-testid="mnote-mindmap-editor-root"`。 - [x] NodeView 挂载 `leptos-mindmap` island。 - [x] island 初始化时请求 `mindmap.simple_mind_map_scene.get`。 - [x] adapter 初始化失败时显示 `adapter_init_failed`。 - [x] projection 获取失败时显示 `projection_load_failed`。 - [x] 不创建 `.mnote-mindmap-react-mount` 作为主链合同。 ### Task 7: 复刻第一阶段 KMind-like UI **Files:** - Create/Modify: relevant leptos-mindmap UI files - Reference: `lx-doc/mind-map/src/pages/Edit/components/Toolbar.vue` - Reference: `lx-doc/mind-map/src/pages/Edit/components/SidebarTrigger.vue` - Reference: `lx-doc/mind-map/src/pages/Edit/components/NavigatorToolbar.vue` - [x] 顶部工具栏包含撤销、重做、编辑节点、同级节点、子节点、删除节点、标签、超链接、备注、图片、图标、概要、关联线、公式、格式刷、导入、导出。 - [x] 工具栏按钮禁用状态跟随 active node。 - [x] 右侧栏包含节点样式、导图样式、主题、结构、大纲。 - [x] 底部栏包含字数/节点数、回根节点、搜索、缩放百分比、全屏或只读入口。 - [x] 默认主题对齐 KMind 截图：根节点红色、二级节点蓝色、分支蓝色文本、概要括号线。 - [x] 移动端或窄宽度下工具栏能折叠为更多菜单。 ### Task 8: 更新 Browser Smoke **Files:** - Modify: `scripts/task166-mindmap-phase6-block-smoke.js` - Reference: `scripts/TESTING_REFERENCE.md` - Output: `tmp/task166-mindmap-phase6-block-smoke/*.png` - Output: `tmp/task166-mindmap-phase6-block-smoke/result.json` - [x] smoke 启动前检查 3000 / 8000 端口占用，并输出 PID、进程名、命令行。 - [x] 使用真实测试账号登录。 - [x] 新建或打开临时文档，通过 `/` 命令插入 mindmap block。 - [x] 断言 `data-testid="mnote-mindmap-editor-root"` 存在。 - [x] 断言 `simple-mind-map` runtime 画布存在且 bounding box 非零。 - [x] 断言至少 4 个可见节点和 3 条可见连线。 - [x] 截图保存插入后、编辑后、reload 后三张图。 - [x] 编辑一个节点文本，等待 kernel command 成功，再 reload，断言新文本仍存在。 - [x] 结构化输出 JSON，包含 `ok`、`task`、`baseUrl`、`documentId`、`mindmapId`、`nodeCount`、`edgeCount`、`kernelRevision`、`adapterSource`、`screenshots`、`resultPath`。 - [x] 失败时错误信息必须指出阶段，例如 `projection_load_failed`、`adapter_init_failed`、`runtime_render_failed`、`command_failed`、`reload_mismatch`。 ### Task 9: 调整 Legacy React / Blob 边界 **Files:** - Modify: `wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx` - Modify: `wolai-frontend/src/lib/mindmap/mindmap-projection.ts` - Modify: `wolai-frontend/src/lib/mindmap/mindmap-renderer-adapter.ts`（当前文件已不存在，边界由 `leptos-mindmap-adapter.ts` / `simple-mind-map-bridge.ts` 与静态断言覆盖） - [x] 给旧 React mindmap 文件增加注释：仅为 legacy/compat/reference，不是 3000 文档页默认主链。 - [x] 禁止新增代码把 `.mnote-mindmap-react-mount` 作为 Phase 6 主验收合同。 - [x] 禁止新增代码把 `window.__mindmapInstance` 作为 smoke 成功条件。 - [x] 保留旧 blob 导入能力，但明确它是 import/compat，不是 canonical edit path。 - [x] 补静态断言或 smoke：默认文档页 host 为 `leptos_tiptap_island` 时不加载旧 React mindmap 主链。 ### Task 10: 独立导图页接同一 Adapter Contract **Files:** - Modify: `rust/crates/mnote-web/src/routes/mindmap_shell.rs` - Modify: `rust/crates/mnote-web/src/ssr/pages/mindmap.rs` - Modify: `wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx` - [x] 独立导图页读取同一 `mindmap.simple_mind_map_scene.get`。 - [x] 独立页和文档 block 共用 command bridge。 - [x] 独立页可以有更完整 chrome，但 projection、command、revision contract 必须一致。 - [x] compat fallback 必须带 `source="compat-blob"`，UI 或日志可见。 - [x] 补 smoke 或 route 单测：同一个 `mindmapId` 在 block 和独立页返回相同 root、node count、revision。 ### Task 11: 验证与复核 **Files:** - Test: Rust protocol/runtime tests - Test: leptos-tiptap island build - Test: `scripts/task166-mindmap-phase6-block-smoke.js` - [x] 运行 `cd /mnt/Data1T/mnote/rust && cargo test -p core-protocol mindmap`。 - [x] 运行 `cd /mnt/Data1T/mnote/rust && cargo test -p bridge-runtime mindmap`。 - [x] 重新构建 leptos-tiptap island。 - [x] 启动本地服务，确认 3000 主链来自 `mnote-web` 文档页。 - [x] 运行 `node scripts/task166-mindmap-phase6-block-smoke.js`。 - [x] 人工查看 smoke 输出截图，确认不是标题占位、不是空容器、不是旧 React mount。 - [x] 每完成一个 checklist 项，必须基于代码或验证结果再勾选。 ### Task 12: Phase 6.1 现实复核与真实 Runtime Cutover **Files:** - Modify: `design/05-editor-mainline/reference-code/leptos-tiptap/tiptap/src/extensions/tiptap_paragraph.ts` - Modify: `rust/spikes/leptos-tiptap-spike/src/lib.rs` - Modify: `rust/spikes/leptos-tiptap-spike/generated/island/snippets/leptos-tiptap-c355e6ec24c3df4c/src/js/generated/tiptap_paragraph.js` - Reuse/Modify: `wolai-frontend/src/lib/mindmap/simple-mind-map-bridge.ts` - Reuse/Modify: `wolai-frontend/src/lib/mindmap/leptos-mindmap-adapter.ts` - Reuse/Modify: `wolai-frontend/src/lib/mindmap/mindmap-command-diff.ts` - Modify: `scripts/task166-mindmap-phase6-block-smoke.js` - Output: `tmp/task166-mindmap-phase6-block-smoke/*.png` - Output: `tmp/task166-mindmap-phase6-block-smoke/result.json` - [x] 确认当前 `tiptap_paragraph.ts` 的 NodeView 是手写 DOM/SVG：`renderScene()` 拼接 toolbar、`