lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0def494f7964409aec00d61ca15de7482ad02333
mnote/docs/superpowers/plans/2026-05-10-mindmap-phase6-projection-editor-checklist.md
T
lix-2026 b4a452a8b7 20260513 mindmap优化01
2026-05-13 22:43:16 +08:00

20 KiB
Raw Blame History

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。

口径修正状态

  • 已确认旧 Rust / Leptos 原生 Projection Editor 口径过时。
  • 已将旧设计稿归档到 recycle/design/06-mindmap/process/。
  • 已将旧 checklist 归档到 recycle/design/superpowers-plans/。
  • 已把当前执行口径修正为 leptos-mindmap。
  • 后续每完成一个实现节点，必须在本 checklist 中勾选对应项。
  • 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

  • 定义 MindmapKernelProjection，包含 schema、documentId、mindmapId、rootNodeId、revision、nodes、edges、summaries、associativeLines、layout、theme、view、capabilities、source。

  • 定义 MindmapAdapterProjection，包含 schema、runtime="simple-mind-map"、root、layout、theme、themeConfig、view、config、compatPayload、kernelRevision。

  • 定义最小 command DTO：updateText、insertChild、insertSiblingAfter、deleteNode、moveNode、patchView、setLayout、setTheme。

  • 标记 MindmapTreeNode / MindmapOp 为 compat DTO。

  • 补 Rust 单测：kernel projection 与 adapter projection 都能序列化为 camelCase JSON。

  • 验证命令：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

  • 增加 mindmap.kernel_projection.get 查询。

  • 增加 mindmap.simple_mind_map_scene.get 查询。

  • 从 kernel truth 或 compat substrate 构建 simple-mind-map 可消费的 root/layout/theme/view/config。

  • projection 返回明确 source，如 kernel、compat-blob、adapter-cache。

  • 默认骨架包含 KMIND、二级节点、两个 分支主题 和 概要。

  • 补 Rust 单测：同一 mindmapId 能输出 kernel projection 和 adapter projection，节点数量一致。

  • 验证命令：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

  • 列出本轮需要注册的 simple-mind-map 插件。

  • 列出 toolbar 命令到 kernel command 的映射。

  • 列出右侧栏第一阶段保留项：节点样式、导图样式、主题、结构、大纲。

  • 列出底部工具第一阶段保留项：统计、搜索、缩放、回根节点、全屏或只读。

  • 列出必须进入 compat_payload 的字段。

  • 明确哪些 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

  • 动态加载 simple-mind-map，避免 SSR 阶段访问 window/document。

  • 注册本轮必需插件：Drag、KeyboardNavigation、Export、Select、RichText、AssociativeLine、Search、Scrollbar、OuterFrame 等按审计结果取舍。

  • 支持从 MindmapAdapterProjection 初始化 runtime。

  • 监听 data_change、view_data_change、node_active、back_forward、scale、translate。

  • 暴露 execCommand 安全包装，不让 UI 任意写 blob。

  • 销毁时清理 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

  • 直接命令优先：toolbar 明确动作直接发 kernel command。

  • data_change diff 能识别文本更新、插入子节点、插入同级节点、删除节点、移动节点。

  • view_data_change 转成 mindmap.view.patch。

  • 主题与结构变化转成 mindmap.theme.set / mindmap.layout.set。

  • 暂不可识别字段进入 compat_payload.patch，并记录字段路径。

  • command 成功后刷新 projection revision。

  • 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

  • / 命令插入 mindmap block 时，Tiptap 节点只保存 mnoteBlockType="mindmap"、mindmapId、rootNodeId、projectionVersion。

  • NodeView 创建 data-testid="mnote-mindmap-editor-root"。

  • NodeView 挂载 leptos-mindmap island。

  • island 初始化时请求 mindmap.simple_mind_map_scene.get。

  • adapter 初始化失败时显示 adapter_init_failed。

  • projection 获取失败时显示 projection_load_failed。

  • 不创建 .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

  • 顶部工具栏包含撤销、重做、编辑节点、同级节点、子节点、删除节点、标签、超链接、备注、图片、图标、概要、关联线、公式、格式刷、导入、导出。

  • 工具栏按钮禁用状态跟随 active node。

  • 右侧栏包含节点样式、导图样式、主题、结构、大纲。

  • 底部栏包含字数/节点数、回根节点、搜索、缩放百分比、全屏或只读入口。

  • 默认主题对齐 KMind 截图：根节点红色、二级节点蓝色、分支蓝色文本、概要括号线。

  • 移动端或窄宽度下工具栏能折叠为更多菜单。

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

  • smoke 启动前检查 3000 / 8000 端口占用，并输出 PID、进程名、命令行。

  • 使用真实测试账号登录。

  • 新建或打开临时文档，通过 / 命令插入 mindmap block。

  • 断言 data-testid="mnote-mindmap-editor-root" 存在。

  • 断言 simple-mind-map runtime 画布存在且 bounding box 非零。

  • 断言至少 4 个可见节点和 3 条可见连线。

  • 截图保存插入后、编辑后、reload 后三张图。

  • 编辑一个节点文本，等待 kernel command 成功，再 reload，断言新文本仍存在。

  • 结构化输出 JSON，包含 ok、task、baseUrl、documentId、mindmapId、nodeCount、edgeCount、kernelRevision、adapterSource、screenshots、resultPath。

  • 失败时错误信息必须指出阶段，例如 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 与静态断言覆盖）

  • 给旧 React mindmap 文件增加注释：仅为 legacy/compat/reference，不是 3000 文档页默认主链。

  • 禁止新增代码把 .mnote-mindmap-react-mount 作为 Phase 6 主验收合同。

  • 禁止新增代码把 window.__mindmapInstance 作为 smoke 成功条件。

  • 保留旧 blob 导入能力，但明确它是 import/compat，不是 canonical edit path。

  • 补静态断言或 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

  • 独立导图页读取同一 mindmap.simple_mind_map_scene.get。

  • 独立页和文档 block 共用 command bridge。

  • 独立页可以有更完整 chrome，但 projection、command、revision contract 必须一致。

  • compat fallback 必须带 source="compat-blob"，UI 或日志可见。

  • 补 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

  • 运行 cd /mnt/Data1T/mnote/rust && cargo test -p core-protocol mindmap。

  • 运行 cd /mnt/Data1T/mnote/rust && cargo test -p bridge-runtime mindmap。

  • 重新构建 leptos-tiptap island。

  • 启动本地服务，确认 3000 主链来自 mnote-web 文档页。

  • 运行 node scripts/task166-mindmap-phase6-block-smoke.js。

  • 人工查看 smoke 输出截图，确认不是标题占位、不是空容器、不是旧 React mount。

  • 每完成一个 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

  • 确认当前 tiptap_paragraph.ts 的 NodeView 是手写 DOM/SVG：renderScene() 拼接 toolbar、<button data-testid="mindmap-node"> 和 <path data-testid="mindmap-edge">。

  • 确认当前截图 /mnt/Data1T/mnote/tmp/task166-mindmap-phase6-block-smoke/03-after-reload.png 与 image copy 70.png、image copy 60.png 的真实工作台形态差距明显。

  • 确认当前 wolai-frontend/src/lib/mindmap/simple-mind-map-bridge.ts 已有真实 new MindMap(...) bridge，但没有接入 leptos-tiptap NodeView 主链。

  • 把 tiptap_paragraph.ts 中的 renderScene() 手写节点/连线逻辑改为只创建 runtime mount element、状态层和错误层。

  • 建立 leptos-tiptap 可加载的 browser-side adapter 入口，复用 createLeptosMindmapAdapter()，避免在 generated bridge 中复制第二套 simple-mind-map 初始化逻辑。

  • adapter 初始化时请求 mindmap.simple_mind_map_scene.get，把 projection 的 root/layout/theme/themeConfig/view/config 传给真实 simple-mind-map。

  • adapter 内部真实调用 new MindMap({ el, data, layout, theme, themeConfig, viewData, config })。

  • NodeView 销毁时调用 bridge destroy()，清理 runtime、监听器和 DOM。

  • data_change / view_data_change 通过 mindmap-command-diff.ts 转换为 kernel command 或 compatPayload.patch，再调用 mindmap.command.apply。

  • command 成功后刷新 adapter projection 或同步 runtime revision；失败时显示 command_failed，不得伪装保存成功。

  • toolbar 的“子节点 / 同级节点 / 删除 / 回根 / 缩放”优先调用 runtime command，再经 command bridge 回写 kernel。

  • 右侧栏和底部栏只保留第一阶段 chrome，不再占据画布主要宽度；视觉对齐 image copy 60.png 的内嵌 KMind 工作台。

  • 删除或降级旧 .mnote-mindmap-node、手写 mindmap-edge、固定 svg viewBox 成为 fallback/debug，不作为默认主链。

  • 更新 smoke：禁止以手写 .mnote-mindmap-node 和 path[data-testid="mindmap-edge"] 作为成功条件。

  • 更新 smoke：断言真实 runtime mount 内存在 simple-mind-map 生成的 SVG/HTML 层、节点布局非零、连线来自 runtime 渲染层。

  • 更新 smoke：保存插入后、编辑后、reload 后截图，并人工对比 image copy 60.png / image copy 70.png 的工作台结构。

  • 运行 cd /mnt/Data1T/mnote/wolai-frontend && pnpm test -- mindmap 或等效 TS 单测，验证 adapter/diff 合同。

  • 重新构建 leptos-tiptap island。

  • 运行 node scripts/task166-mindmap-phase6-block-smoke.js。

  • 只有 smoke 结果 JSON、截图和代码检查都证明真实 simple-mind-map runtime 已接入后，才允许勾选本 Task 完成。

备注：2026-05-10 首轮真实 runtime cutover 已通过；仍未勾选的 view_data_change 持久化与 toolbar 缩放绑定属于后续交互完善项，不能反向否定真实 runtime 已接入。

Task 13: UI Shell Reuse 后续收口

Current Checklist:

  • design/06-mindmap/process/6-mindmap-phase6-leptos-ui-shell-reuse-checklist-v1.md

  • 2026-05-11 已将后续 UI 可用度收口迁入独立 checklist，目标是 leptos-mindmap + simple-mind-map runtime + Leptos/Rust floating overlay UI shell。

  • 新 checklist 已完成 Task 5A/5B/6/7/8/9/10/11/12/13 的核心验收：floating overlay、Leptos/Rust shell、toolbar/sidebar/navigator/context menu、command bridge、smoke 截图与旧 React 边界。

  • 后续 KMind/lx-doc 视觉细化、图标体系、主题细节和高级面板内容按新 checklist 继续，不再把本旧计划的手写伪画布阶段作为 UI 完成判定。

退出标准

2026-05-10 现实复核后，本段退出标准重新打开。旧勾选只代表伪画布阶段的最小闭环，不能作为最终完成依据。

  • 文档页 / 插入 mindmap block 后，默认主链是 leptos-tiptap NodeView + 真实 leptos-mindmap adapter。
  • 插入后截图可见 KMind-like 真实根节点、分支节点、概要和连线，且节点/连线由 simple-mind-map runtime 渲染。
  • simple-mind-map runtime 只作为 editor adapter，不是 canonical truth。
  • 最小节点编辑动作通过 Rust kernel command 回写，reload 后仍存在。
  • smoke 输出结构化 JSON 和截图证据，失败信息能定位到 projection、adapter、runtime、command 或 reload 阶段。
  • 旧 React/simple-mind-map block 不在 Phase 6 默认文档页主链内。
  • 默认 smoke 不再把手写 .mnote-mindmap-node / path[data-testid="mindmap-edge"] 当作完成条件。

暂不作为阻塞的尾项

  • Rust-native mindmap renderer。
  • 完整复杂布局算法 Rust 化。
  • KMind 多根节点。
  • MOC / 文档树导图。
  • 思源块悬浮预览与镜像块。
  • PDF 标注跳转。
  • 导图 blob 存储彻底移除。
  • Page Aggregate 写后完整回灌统一 projection。
  • tree realtime 全域单 live cache。

建议执行顺序

  • 第 1 天：Task 1 + Task 2，冻结 projection 和 adapter scene contract。
  • 第 2 天：Task 3 + Task 4，审计参考实现并建立 simple-mind-map bridge。
  • 第 3 天：Task 5，打通 command bridge 和 adapter diff。
  • 第 4 天：Task 6 + Task 7 + Task 8，完成的是手写伪画布最小闭环，不是最终真实 runtime。
  • 下一步：Task 12，真实 simple-mind-map runtime cutover，替换手写 DOM/SVG 画布。
  • Task 12 通过后：复核 Task 9 + Task 10 + Task 11，确认 legacy、独立页和验证口径没有回到伪画布。
    • 2026-05-11 复核：新 UI shell checklist 已完成旧 React 边界注释、editor-host-config 静态断言和 task166 smoke；默认成功条件为 mnote-mindmap-editor-root、simple-mind-map-runtime、mindmap-rust-shell。
Reference in New Issue View Git Blame Copy Permalink