5.9 KiB
5.9 KiB
KMind 移植阶段实施方案
背景速览
- 确认 simple-mind-map（wanglin2/mind-map）MIT 许可要求并在项目中保留版权声明
- 评估 siyuan-KMind（widget-release 分支）中可直接复用的 UI、主题、交互素材及其许可
- 汇总 simple-mind-map 提供的关键插件（RichText、Drag、Export、MiniMap、RainbowLines、Cooperate 等）并决定接入方式（ESM/UMD/动态加载）
阶段 0：许可与能力基线
- 输出《能力与许可调研报告》，列出：
- simple-mind-map 强制插件、可选插件及依赖版本
- KMind 插件增量功能列表（MOC、镜像块、主题设计器、直觉按钮等）及其复用策略
- 明确导图 JSON 模型与当前 Supabase/BlockNote 数据结构的兼容边界
- 拟定“上游更新同步流程”（如何追踪 simple-mind-map / KMind 的 release）
阶段 1：核心渲染封装 PoC
- 在 Next.js 客户端组件中创建
KMindRenderer，使用 simple-mind-map 官方初始化方式验证渲染/缩放/主题切换 - 接入最小 JSON 数据结构，落库到 Supabase JSON 字段并实现导入导出（json/png/svg/pdf/md/xmind/txt）
- 提供
/lab/mindmapPoC 页面与自动化冒烟脚本（创建节点→缩放→导出 JSON）
阶段 2：SiYuan 特性对齐（常规导图）
- 复刻 KMind 的节点编辑体验：富文本弹窗、Markdown 支持、节点格式刷、彩虹线/连线风格、浮动工具栏、禅模式、直觉按钮（
/lab/mindmap已上线工具栏、禅模式、直觉按钮；RainbowLines 与 Painter 可即时切换） - 支持节点扩展类型：图片、checkbox、备注、标签、数学公式等，对应 simple-mind-map 插件链路（新增节点扩展抽屉，直连 simple-mind-map 命令链路）
- 实现“全局节点超链接”与 Alt+Click 悬浮预览（React Portal），并定义
app://mindmap/{id}?node={nodeId}协议（支持app://document/app://mindmap，Alt+Click 预览已验证） - 编写 Storybook/Playwright 场景覆盖上述交互（基于 Storybook 交互实验室 + Playwright e2e） -参考资料：https://wanglin2.github.io/mind-map-docs/course/course1.html -参考文件夹kmind-plugin -对标：https://wanglin2.github.io/mind-map/#/
阶段 3：BlockNote / MOC 集成
- 设计导图 JSON 与 BlockNote 块 schema 的映射策略，完成“导图嵌入块”+ 双向同步 MVP（
mindmapEmbed已替换旧版块并支持 app://document 链接，节点扩展面板可写回子文档链接，Slash / “思维导图” 插入即绑定当前文档导图） - 在 BlockNote 斜杠命令中插入只读导图，提供点击进入
/mindmap/[id]的入口（Slash 菜单新增“思维导图”项，插入块带跳转按钮） - 实现 MOC 模式 MVP：Supabase 递归 CTE 拉取文档树 → 构建只读 mindmap → 节点跳转
/documents/[id]#block-x（导入文档树按钮调用/api/mindmap/moc，节点携带app://document/{id}） - 节点右键创建子文档，触发 Supabase RPC 并写回导图节点链接（节点扩展面板新增“创建子文档并绑定”按钮，调用
/api/documents/create-child并自动写入 hyperlink）
阶段 4：高级功能对齐
- 支持导图/节点镜像块（参考 KMind v2.7.0），确保主导图变更实时同步到 BlockNote 镜像
- 实现全局配置面板（鼠标模式、默认主题/结构、自动禅模式等），设置保存在用户配置表
- 当前状态：全局配置已在客户端持久化并应用到实例，补充 Supabase 云端存储与多端实时同步
- 迁移 KMind 主题设计器与分享功能，适配括号连线、彩虹线条、主题导入导出 API
- 补充 “一键转导图插入文档树”“Freemind 导入导出”等增值功能
阶段 5：协作、历史、性能与质检
- 接入 Yjs + Hocuspocus/Supabase Realtime，实现节点数据与视图状态（zoom/pan）协同，包含冲突合并策略
- 仿 KMind v2.5.0 实现历史版本/兜底保护（定时快照、异常写入拦截、恢复 UI）
- 本地兜底：前端记录最多 15 条本地快照，支持下拉恢复/清空（先于云端协同/版本库）
- 针对大规模导图加入虚拟化、懒加载、Worker 分流，确保首屏 < 1s 并输出性能基准报告（右侧大纲已虚拟化，画布/导出仍需分流）
- 构建端到端自动化测试链（拖拽节点→保存→嵌入同步→链接跳转）与视觉回归/压力测试
UI 对齐行动计划（对标 https://wanglin2.github.io/mind-map/#/）
- 布局重构：
/mindmap/[id]使用全屏画布容器 + 悬浮工具条 + 可隐藏右侧抽屉，顶部透明/毛玻璃工具条，窄屏折叠 - 右侧抽屉：组件化 Tabs（节点样式/大纲/预览/设置），支持动画收起/展开并记忆状态，未选节点时显示占位提示
- 悬浮工具条：对齐上游按钮集合（撤销/重做/格式刷/同级/子节点/删除/图片/图标/超链/备注/标签/概要/关联线/公式/外框/AI 等），封装命令调度器直连 simple-mind-map
- 全屏画布体验：容器 100vw/100vh，隐藏页面滚动，给工具条/抽屉预留安全区，禅模式隐藏所有 UI 层
- 状态管理与持久化：抽屉/tab/禅模式/工具条吸附位置写入全局 store，并本地持久化以便刷新恢复
- 视觉规范：统一 icon 尺寸与间距，CSS 变量主题（亮/暗），轻量阴影与圆角，抽屉/工具条过渡动效
- 验证用例：本地
npm run desktop:hot冒烟（创建/删除节点、主题切换、抽屉收起、适应画布、禅模式、导出 JSON），补充快照/Playwright 场景
里程碑与交付物
- 阶段 1 完成：提供 PoC 页面、保存/导出 demo、冒烟测试日志
- 阶段 3 完成：上线
/mindmap/[id]页面 + BlockNote 嵌入 + 基础 MOC - 阶段 5 完成：协作 & 历史 & 性能报告 + 自动化测试通过