935 lines
26 KiB
Markdown
935 lines
26 KiB
Markdown
# 6 [process] Mindmap Kernel Phase 6：降级为 Projection / Editor v1
|
||
|
||
> 更新时间：2026-04-22
|
||
>
|
||
> 当前主线依据：
|
||
> - `/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/04-tree-domain/process/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md`
|
||
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
|
||
>
|
||
> 历史参考：
|
||
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-1-tree-first-graph-kernel-checklist-v2.md`
|
||
> - `/mnt/Data1T/mnote/design/old/05-editor-mainline/process/ai-first-rust-block-editor-baseline-v1.md`
|
||
|
||
## 1. 文档目的
|
||
|
||
这份文档用于重写 `Kernel Phase 6` 的落地口径。
|
||
|
||
这里仍沿用 `Phase 6` 命名，是为了保留与旧阶段拆分的一致性；当前执行依据应以 `design/01-05-current-priority-overview.md` 和相关现行主线文档为准，不再以 `1-1-tree-first-graph-kernel-checklist-v2.md` 作为唯一推进入口。
|
||
|
||
这里回答的不是：
|
||
|
||
- “要不要马上把导图 UI 全量重写成 Rust”
|
||
|
||
而是：
|
||
|
||
> **在当前仓库代码现实下，Mindmap 如何从独立对象中心，降级成 `tree-first graph kernel` 的一种 projection / editor。**
|
||
|
||
这份文档必须同时满足三件事：
|
||
|
||
- 服从 `tree-first graph kernel` 主线
|
||
- 对齐当前仓库里的真实实现，而不是抽象设想
|
||
- 给出可迁移、可双写、可分阶段切流的方案
|
||
|
||
---
|
||
|
||
## 2. 先给结论
|
||
|
||
结论固定如下：
|
||
|
||
> **Mindmap 后续必须进行 Rust 内核化重构，但重构重点不是先替换 `simple-mind-map` 画布，而是先把“导图真相、导图命令、导图 projection、AI 工具入口”切到 Rust kernel。**
|
||
|
||
换句话说：
|
||
|
||
- **必须 Rust 化的部分**
|
||
- 导图事实源
|
||
- 导图命令层
|
||
- 导图 projection 层
|
||
- AI / CLI 直接调用的导图工具层
|
||
- **不必第一阶段 Rust 化的部分**
|
||
- 具体画布渲染器
|
||
- 工具栏、缩略图、拖拽动画、局部 DOM 细节
|
||
|
||
因此：
|
||
|
||
> **Phase 6 的正确目标不是“把导图换个前端库”，而是“让导图不再以 `simple-mind-map` JSON 为系统真相”。**
|
||
|
||
---
|
||
|
||
## 3. 当前代码现实
|
||
|
||
当前导图主链已经部分接入 Rust runtime，但整体仍然是“前端重交互壳 + blob 持久化 + Rust compat 工具”的形态，还不是 kernel truth。
|
||
|
||
### 3.1 前端主壳仍然由 `simple-mind-map` 驱动
|
||
|
||
当前主组件：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx`
|
||
|
||
现状特征：
|
||
|
||
- 直接加载 `simple-mind-map` 与大量插件
|
||
- 同时承担内嵌块、独立页、全屏态、工具栏、缩略图、右键菜单、图片处理、导入导出
|
||
- 直接调用：
|
||
- `mindmap.setData(...)`
|
||
- `mindmap.getData(...)`
|
||
- `mindmap.execCommand(...)`
|
||
- 直接请求：
|
||
- `fetch(/api/mindmap/${docId}/${mindmapId})`
|
||
|
||
这说明当前导图编辑器仍然以画布库数据结构为第一现场。
|
||
|
||
### 3.2 当前所谓 projection 仍然是前端摘要层，不是 kernel projection
|
||
|
||
当前文件：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/lib/mindmap/mindmap-projection.ts`
|
||
|
||
当前 `buildMindmapProjection(...)` 的本质是：
|
||
|
||
- 接受一份 raw mindmap blob
|
||
- 做 `simple-mind-map` 兼容归一化
|
||
- 输出一个前端摘要对象
|
||
- 同时保留 `data` 原始树
|
||
|
||
这意味着当前 projection 还是：
|
||
|
||
- **blob 的摘要**
|
||
|
||
而不是：
|
||
|
||
- **kernel subtree / graph 的正式投影**
|
||
|
||
### 3.3 当前持久化仍然是整棵导图 blob
|
||
|
||
当前持久化主链：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/convex/mindmaps.ts`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/mindmap/[docId]/[mindmapId]/route.ts`
|
||
|
||
现状特征：
|
||
|
||
- `mindmaps.get` 返回整棵 `data`
|
||
- `mindmaps.put` 写回整棵 `data`
|
||
- `mindmaps` 表持有的是一份完整导图 JSON
|
||
- 独立页服务端入口仍然走：
|
||
- `mindmaps.get`
|
||
- 然后在前端侧 `buildMindmapProjection(...)`
|
||
|
||
这说明当前“导图真相”依然是：
|
||
|
||
- **可直接存取的一整棵导图 blob**
|
||
|
||
而不是：
|
||
|
||
- **kernel node / edge / subtree**
|
||
|
||
### 3.4 Rust runtime 已经介入，但仍是 compat mindmap 树语义
|
||
|
||
当前 Rust 侧相关实现：
|
||
|
||
- `/mnt/Data1T/mnote/rust/crates/core-protocol/src/mindmap.rs`
|
||
- `/mnt/Data1T/mnote/rust/crates/bridge-runtime/src/lib.rs`
|
||
|
||
已存在的事实：
|
||
|
||
- Rust 侧已经有：
|
||
- `MindmapTreeNode`
|
||
- `MindmapOp`
|
||
- `mindmap_get`
|
||
- `mindmap_get_subtree`
|
||
- `mindmap_put`
|
||
- `mindmap_apply_ops`
|
||
- `mindmap_outline_to_mindmap`
|
||
- `bridge-runtime` 已能在 Rust 内部应用 `MindmapOp`
|
||
|
||
但这些能力当前本质上仍然是：
|
||
|
||
- 对一棵 `MindmapTreeNode` JSON 树做读取、修改、返回
|
||
|
||
不是：
|
||
|
||
- 对 `KernelNode` / `KernelEdge` / `KernelSubtree` 做正式操作
|
||
|
||
### 3.5 Kernel 协议已具备导图进入统一内核的入口
|
||
|
||
当前 kernel 类型：
|
||
|
||
- `/mnt/Data1T/mnote/rust/crates/core-protocol/src/kernel.rs`
|
||
|
||
已经有：
|
||
|
||
- `KernelNodeType::Mindmap`
|
||
- `KernelNodeType::MindmapNode`
|
||
- `KernelProjectionKind::Mindmap`
|
||
|
||
这说明协议层已经承认：
|
||
|
||
> **导图应该属于统一 kernel，而不是永远停留在专用 blob 协议。**
|
||
|
||
问题不在方向，而在主线尚未切换完成。
|
||
|
||
---
|
||
|
||
## 4. 当前架构问题
|
||
|
||
如果继续维持当前模式，会有四类问题。
|
||
|
||
### 4.1 导图真相仍被视图库数据结构绑架
|
||
|
||
现在真正被保存、被读取、被回写的是：
|
||
|
||
- `simple-mind-map` 兼容树
|
||
|
||
这会导致：
|
||
|
||
- 领域模型被 UI 库字段形状反向约束
|
||
- 导图语义无法稳定进入 kernel
|
||
- 不同视图无法共享统一对象真相
|
||
|
||
### 4.2 AI 仍然不是直接操作 kernel
|
||
|
||
虽然已经有 `mindmap_apply_ops` 等工具，但它们当前语义仍然是：
|
||
|
||
- 取出一棵树
|
||
- 在 runtime 里改树
|
||
- 返回新树
|
||
|
||
这仍然不是：
|
||
|
||
- 直接创建 `mindmap_node`
|
||
- 直接移动 subtree
|
||
- 直接挂接 reference edge
|
||
|
||
因此 AI 还没有真正“直接写导图内核”。
|
||
|
||
### 4.3 导图还没有进入统一 projection 家族
|
||
|
||
当前 Sidebar / 页面树 / 文件树 正在往 kernel projection 收敛。
|
||
|
||
但导图仍然主要是：
|
||
|
||
- 专用 route
|
||
- 专用 blob
|
||
- 专用前端大组件
|
||
|
||
这会让导图继续成为一个旁路系统。
|
||
|
||
### 4.4 前端壳过重，迁移边界不清
|
||
|
||
`MindmapBlock.tsx` 当前同时承担：
|
||
|
||
- 读取
|
||
- 兼容转换
|
||
- 渲染
|
||
- 编辑
|
||
- 保存
|
||
- 资产替换
|
||
- 导入导出
|
||
- 页面模式切换
|
||
|
||
这意味着：
|
||
|
||
> **只要导图真相还留在这里，Phase 6 就不会真正成立。**
|
||
|
||
---
|
||
|
||
## 5. Phase 6 的正确目标
|
||
|
||
Phase 6 的正确目标固定为：
|
||
|
||
> **让 Mindmap 从“独立对象中心 + blob 真相 + 前端重壳”降级成“kernel subtree / graph 的一种 projection 与 editor”。**
|
||
|
||
再收口成一句：
|
||
|
||
> **Mindmap 不是对象真相层，Mindmap 只是树/图真相的一种空间化编辑视图。**
|
||
|
||
这意味着：
|
||
|
||
- 导图不能再拥有第二份对象真相
|
||
- 导图不能再以整棵 blob 作为长期 canonical model
|
||
- 导图编辑器只能操作 kernel
|
||
- 导图 route 只能消费 kernel projection
|
||
|
||
---
|
||
|
||
## 6. 目标分层
|
||
|
||
长期建议把导图域拆成四层。
|
||
|
||
### 6.1 Kernel Truth
|
||
|
||
这一层只存系统真相。
|
||
|
||
建议对象：
|
||
|
||
- `mindmap`
|
||
- 作为导图根容器节点
|
||
- `mindmap_node`
|
||
- 作为导图树节点
|
||
- `reference edge`
|
||
- 作为节点到页面、附件、PDF anchor、summary、ai_note 的横向关系
|
||
|
||
这层只负责：
|
||
|
||
- 节点存在性
|
||
- 父子结构
|
||
- sibling 顺序
|
||
- 节点稳定 ID
|
||
- 节点元信息
|
||
- 引用边
|
||
- 审计与版本
|
||
|
||
### 6.2 Mindmap Projection Layer
|
||
|
||
这一层负责把 kernel truth 投影为导图视图可消费的数据。
|
||
|
||
长期至少应有两类 projection：
|
||
|
||
- `mindmap_preview`
|
||
- 给文档内嵌卡片、轻量预览使用
|
||
- `mindmap_editor`
|
||
- 给导图独立页、沉浸编辑器使用
|
||
|
||
这层输出的应是：
|
||
|
||
- 稳定 node id
|
||
- parent / child 关系
|
||
- sibling order
|
||
- depth
|
||
- child count
|
||
- 引用摘要
|
||
- capability flags
|
||
- 视图提示信息
|
||
|
||
而不是直接把前端控件内部状态回吐出去。
|
||
|
||
### 6.3 Editor Adapter Layer
|
||
|
||
这一层负责：
|
||
|
||
- 把 kernel projection 转成 `simple-mind-map` 当前所需的数据形状
|
||
- 把画布交互翻译成 kernel command
|
||
|
||
这一层是 compat adapter，不是事实源。
|
||
|
||
### 6.4 View Shell
|
||
|
||
这一层只负责：
|
||
|
||
- 画布
|
||
- 工具栏
|
||
- 右键菜单
|
||
- 缩略图
|
||
- 全屏壳
|
||
- 交互状态
|
||
|
||
这里可以继续用 `simple-mind-map` 过渡，但不能再持有对象真相。
|
||
|
||
---
|
||
|
||
## 7. 哪些语义必须进入 kernel
|
||
|
||
下面这些语义必须进入 kernel，而不是继续停留在 `simple-mind-map` blob 中。
|
||
|
||
### 7.1 节点级稳定语义
|
||
|
||
- `mindmap` 根节点
|
||
- `mindmap_node` 子节点
|
||
- `title / text`
|
||
- `note`
|
||
- `hyperlink`
|
||
- `refs`
|
||
- `collapsed`
|
||
- sibling 排序键
|
||
- 节点归档/删除状态
|
||
|
||
### 7.2 树语义
|
||
|
||
- 创建子节点
|
||
- 创建同级节点
|
||
- 重命名
|
||
- 移动 subtree
|
||
- 重排顺序
|
||
- 删除 subtree
|
||
|
||
### 7.3 图语义
|
||
|
||
- 节点引用页面
|
||
- 节点引用块
|
||
- 节点引用附件
|
||
- 节点引用 PDF 页码/anchor
|
||
- AI 生成节点引用证据节点
|
||
|
||
### 7.4 审计语义
|
||
|
||
- command id
|
||
- trace id
|
||
- actor id
|
||
- revision / version
|
||
|
||
---
|
||
|
||
## 8. 哪些语义不应进入 kernel
|
||
|
||
下面这些内容不应进入 kernel truth。
|
||
|
||
- 当前缩放比例
|
||
- 当前视口位置
|
||
- 当前选中节点
|
||
- minimap 展开状态
|
||
- 文本编辑框 DOM 状态
|
||
- 鼠标拖拽中的临时态
|
||
- 纯视图级动画状态
|
||
- `simple-mind-map` 内部 history 栈
|
||
- 仅服务当前画布库的缓存字段
|
||
|
||
这些内容属于：
|
||
|
||
- editor session state
|
||
- view shell state
|
||
|
||
不是 kernel truth。
|
||
|
||
---
|
||
|
||
## 9. 命令层重构口径
|
||
|
||
当前 `mindmap_apply_ops` 和 `mindmap_put` 不能再继续被当作长期真相接口。
|
||
|
||
### 9.1 `mindmap_put`
|
||
|
||
长期应降级为：
|
||
|
||
- 导入整图
|
||
- 替换快照
|
||
- 迁移回放
|
||
- 故障恢复
|
||
|
||
不应再作为常规编辑主路径。
|
||
|
||
### 9.2 `mindmap_apply_ops`
|
||
|
||
长期应保留，但语义要改。
|
||
|
||
它应变成：
|
||
|
||
- **compat facade**
|
||
|
||
内部行为应是：
|
||
|
||
- 把 `MindmapOp` 翻译成 kernel command 序列
|
||
|
||
例如：
|
||
|
||
- `addChild`
|
||
- `kernel.node.create`
|
||
- `addSiblingAfter`
|
||
- `kernel.node.create` + sibling order 调整
|
||
- `updateText`
|
||
- `kernel.node.update`
|
||
- `setHyperlink`
|
||
- `kernel.node.update`
|
||
- `setRefs`
|
||
- `kernel.edge.attach` / `kernel.edge.detach`
|
||
- `deleteNode`
|
||
- `kernel.subtree.delete` 或 `kernel.node.archive`
|
||
|
||
也就是说：
|
||
|
||
> **`mindmap_apply_ops` 可以继续存在，但它不能继续直接修改一棵 compat 树。**
|
||
|
||
### 9.3 新的正式命令面
|
||
|
||
Phase 6 后导图应以 kernel command 为正式写面：
|
||
|
||
- `create_node`
|
||
- `update_node`
|
||
- `move_subtree`
|
||
- `reorder_siblings`
|
||
- `archive_node`
|
||
- `restore_node`
|
||
- `attach_edge`
|
||
- `detach_edge`
|
||
|
||
如果 kernel 当前缺少某些命令，就应在 Phase 6 补入，而不是继续把缺口留给前端 blob。
|
||
|
||
---
|
||
|
||
## 10. Projection 重构口径
|
||
|
||
当前导图 route 仍然主要走：
|
||
|
||
- `mindmaps.get`
|
||
|
||
然后前端：
|
||
|
||
- `buildMindmapProjection(...)`
|
||
|
||
这条链必须调整。
|
||
|
||
### 10.1 正式读路径
|
||
|
||
长期正式读路径应是：
|
||
|
||
- `kernel.project_view`
|
||
- projection=`mindmap`
|
||
|
||
而不是：
|
||
|
||
- `mindmaps.get`
|
||
- 返回 raw blob
|
||
|
||
### 10.2 Projection 输出要求
|
||
|
||
导图 projection 输出至少应包括：
|
||
|
||
- `projection_id`
|
||
- `root_node_id`
|
||
- `items`
|
||
- `edges`
|
||
- `depth`
|
||
- `sort_key`
|
||
- `expand_hint`
|
||
- `capability_flags`
|
||
- `resource_meta`
|
||
|
||
### 10.3 前端 adapter 的角色
|
||
|
||
前端可以继续存在一个：
|
||
|
||
- `projection -> simple-mind-map` adapter
|
||
|
||
但这层只能是 view adapter。
|
||
|
||
它不能再同时承担：
|
||
|
||
- canonical model
|
||
- 持久化模型
|
||
- AI 写入模型
|
||
|
||
---
|
||
|
||
## 11. AI / CLI 口径
|
||
|
||
如果目标是“AI 能直接编写思维导图，而不是外挂组件”，那 Phase 6 的 AI 路线必须明确。
|
||
|
||
### 11.1 AI 读取导图
|
||
|
||
AI 应读取：
|
||
|
||
- kernel subtree
|
||
- mindmap projection
|
||
- node refs / evidence
|
||
|
||
而不是只读取一棵视图库 JSON。
|
||
|
||
### 11.2 AI 修改导图
|
||
|
||
AI 应直接发 kernel command，或通过 compat facade 发命令。
|
||
|
||
正确路径应是：
|
||
|
||
- AI 意图
|
||
- tool / command plan
|
||
- kernel command
|
||
- projection 刷新
|
||
|
||
不是：
|
||
|
||
- AI 输出一整棵导图 JSON
|
||
- 再整体覆盖保存
|
||
|
||
### 11.3 AI 生成导图
|
||
|
||
`mindmap_outline_to_mindmap` 这类能力可以保留，但输出应优先写入：
|
||
|
||
- `mindmap`
|
||
- `mindmap_node`
|
||
- `reference edge`
|
||
|
||
而不是先生成一棵孤立 blob 再把它塞进存储。
|
||
|
||
---
|
||
|
||
## 12. 与当前代码对应的重构任务
|
||
|
||
### 12.1 Rust 协议层
|
||
|
||
需要重构或补充：
|
||
|
||
- `/mnt/Data1T/mnote/rust/crates/core-protocol/src/kernel.rs`
|
||
- `/mnt/Data1T/mnote/rust/crates/core-protocol/src/mindmap.rs`
|
||
|
||
建议动作：
|
||
|
||
- 保留 `MindmapOp` 作为 compat DTO
|
||
- 不再把 `MindmapTreeNode` 当长期 canonical model
|
||
- 为导图补齐正式 projection / command 契约
|
||
|
||
### 12.2 Rust runtime
|
||
|
||
需要重构：
|
||
|
||
- `/mnt/Data1T/mnote/rust/crates/bridge-runtime/src/lib.rs`
|
||
|
||
建议动作：
|
||
|
||
- 增加正式 `mindmap` projection builder
|
||
- 把 `mindmap_apply_ops` 改成 command translator
|
||
- 让 `mindmaps.get` 逐步降级为 compat query
|
||
- 新增或补齐导图相关 kernel command
|
||
|
||
### 12.3 前端 mindmap adapter
|
||
|
||
需要重构：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/lib/mindmap/mindmap-projection.ts`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/lib/mindmap/mindmapOps.ts`
|
||
|
||
建议动作：
|
||
|
||
- `mindmap-projection.ts`
|
||
- 从“blob 摘要器”转成“kernel projection adapter”
|
||
- `mindmapOps.ts`
|
||
- 从“本地真相修改器”降级为 compat / fallback 层
|
||
|
||
### 12.4 前端视图壳
|
||
|
||
需要重构：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/mindmap-page-client.tsx`
|
||
|
||
建议动作：
|
||
|
||
- 将读取从 `mindmaps.get` 切到 kernel projection
|
||
- 将写入从 `getData()/POST whole blob` 切到命令流
|
||
- 将 `MindmapBlock.tsx` 缩成 view shell + adapter
|
||
|
||
### 12.5 持久化与兼容层
|
||
|
||
需要重构：
|
||
|
||
- `/mnt/Data1T/mnote/wolai-frontend/convex/mindmaps.ts`
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/app/api/mindmap/[docId]/[mindmapId]/route.ts`
|
||
|
||
建议动作：
|
||
|
||
- 迁移期允许双写
|
||
- 长期让 `mindmaps` 表退到 compat snapshot / import-export 层
|
||
- 正式真相切到 kernel backing store
|
||
|
||
---
|
||
|
||
## 13. 迁移分期
|
||
|
||
### 13.1 Phase 6-A：冻结边界
|
||
|
||
目标：
|
||
|
||
- 停止在前端和 compat blob 上继续追加长期业务语义
|
||
|
||
详细 checklist：
|
||
|
||
- [ ] 冻结口径：
|
||
- 明确 `MindmapTreeNode` 只作为 compat DTO
|
||
- 明确 `mindmaps` blob 只作为过渡存储，不再新增长期业务语义
|
||
- 明确 `simple-mind-map` 只作为 renderer / editor adapter，不再定义系统真相
|
||
- [ ] 协议边界盘点：
|
||
- 盘点 `/mnt/Data1T/mnote/rust/crates/core-protocol/src/mindmap.rs` 中哪些字段属于 compat 语义
|
||
- 盘点 `/mnt/Data1T/mnote/rust/crates/core-protocol/src/kernel.rs` 中已有 `mindmap` / `mindmap_node` / `projection` 能力
|
||
- 列出 Phase 6 后必须新增的 kernel command / projection 契约缺口
|
||
- [ ] 前端边界盘点：
|
||
- 盘点 `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx` 中哪些逻辑属于真相层
|
||
- 将这些逻辑标记为后续待迁移：
|
||
- 读主链
|
||
- 写主链
|
||
- 本地摘要
|
||
- 引用回写
|
||
- 资产 URL 反写
|
||
- 明确哪些逻辑继续保留在 view shell：
|
||
- 画布渲染
|
||
- 右键菜单
|
||
- 工具栏
|
||
- 缩略图
|
||
- 全屏壳
|
||
- [ ] 持久化边界盘点：
|
||
- 盘点 `/mnt/Data1T/mnote/wolai-frontend/convex/mindmaps.ts` 的现有字段与索引
|
||
- 盘点 `/mnt/Data1T/mnote/wolai-frontend/src/app/api/mindmap/[docId]/[mindmapId]/route.ts` 的现有读写语义
|
||
- 明确哪些接口后续降级为 compat：
|
||
- `mindmaps.get`
|
||
- `mindmaps.put`
|
||
- `mindmaps.delete`
|
||
- `mindmaps.restore`
|
||
- [ ] AI / CLI 边界盘点：
|
||
- 盘点 `mindmap_get` / `mindmap_get_subtree` / `mindmap_put` / `mindmap_apply_ops`
|
||
- 标注哪些工具后续保留为 facade，哪些应切到 kernel command
|
||
- 明确 AI 不再以“整图 JSON 覆盖”作为长期主路径
|
||
- [ ] 文档口径冻结：
|
||
- 当前文档作为 Phase 6 主文档继续维护
|
||
- checklist / architecture / 后续任务拆分不再把导图描述为独立事实源
|
||
- 新增导图相关设计时默认引用本文件，而不是继续围绕 `simple-mind-map` 数据结构展开
|
||
- [ ] 代码约束冻结：
|
||
- 在未完成 Phase 6-B 之前，不再给 `MindmapTreeNode` 增加新的长期业务字段
|
||
- 在未完成 Phase 6-C 之前，不再新增新的“整图读取后本地改树再整体提交”的主路径
|
||
- 在未完成 Phase 6-D 之前，不再新增绕过 kernel 的 AI 写入链路
|
||
|
||
出阶段判定：
|
||
|
||
- [ ] 新导图语义默认先判断是否落 kernel，而不是先落前端 blob
|
||
- [ ] `MindmapBlock.tsx` 不再继续承担新的长期对象真相职责
|
||
- [ ] 团队已统一接受：
|
||
- compat blob 不是长期真相
|
||
- `simple-mind-map` 不是对象中心
|
||
- Phase 6 后正式主线是 kernel truth + projection + adapter
|
||
|
||
### 13.2 Phase 6-B：先切读路径
|
||
|
||
目标：
|
||
|
||
- 独立页与内嵌预览先读取正式 kernel projection
|
||
|
||
详细 checklist：
|
||
|
||
- [ ] 定义 projection 家族：
|
||
- 定义 `mindmap_preview` projection
|
||
- 定义 `mindmap_editor` projection
|
||
- 明确两者共享的稳定字段：
|
||
- `projection_id`
|
||
- `root_node_id`
|
||
- `items`
|
||
- `edges`
|
||
- `capability_flags`
|
||
- `resource_meta`
|
||
- [ ] 定义 projection item 结构：
|
||
- 稳定 node id
|
||
- `parent_id`
|
||
- `sort_key`
|
||
- `depth`
|
||
- `child_count`
|
||
- `title/text`
|
||
- `collapsed`
|
||
- `refs summary`
|
||
- `style hint`
|
||
- [ ] Rust runtime 补 projection builder：
|
||
- 在 `/mnt/Data1T/mnote/rust/crates/bridge-runtime/src/lib.rs` 中增加正式 `mindmap` projection builder
|
||
- 让 `kernel.project_view` 可返回 `KernelProjectionKind::Mindmap`
|
||
- 明确 preview 与 editor 的输出差异，不再直接返回 compat 整树
|
||
- [ ] 前端 adapter 改造：
|
||
- 将 `/mnt/Data1T/mnote/wolai-frontend/src/lib/mindmap/mindmap-projection.ts` 从“blob 摘要器”改为“kernel projection adapter”
|
||
- 把 adapter 输出限定为 `simple-mind-map` 所需最小数据形状
|
||
- 不再让 adapter 同时承担 canonical model 职责
|
||
- [ ] 独立页读路径切换：
|
||
- `/mnt/Data1T/mnote/wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx`
|
||
改为优先读取 kernel projection
|
||
- SSR 初始数据不再以 `mindmaps.get` raw blob 为主
|
||
- `mindmap-page-client.tsx` 仅接收 projection / adapter 输出
|
||
- [ ] 文档内嵌预览切换：
|
||
- 内嵌卡片优先消费 `mindmap_preview`
|
||
- 预览态不再默认依赖整棵 blob
|
||
- 轻量预览和沉浸编辑使用不同 projection，避免主编辑壳过早挂载
|
||
- [ ] 兼容回退策略：
|
||
- kernel projection 不可用时，可临时回退到 compat `mindmaps.get`
|
||
- 回退路径必须显式标记为 compat/fallback
|
||
- 回退逻辑不得反向成为新主路径
|
||
- [ ] 可观测性与追踪：
|
||
- projection 响应带 `request_id` / `trace_id`
|
||
- 前端记录当前页面命中的 projection 来源：
|
||
- kernel
|
||
- compat fallback
|
||
- 为后续切流留出观测点
|
||
- [ ] 测试与验收：
|
||
- 增加 runtime 单测：`mindmap_preview` / `mindmap_editor` 输出稳定
|
||
- 增加 adapter 单测：projection -> `simple-mind-map` data
|
||
- 增加独立页 smoke：首屏读 projection 成功
|
||
- 增加内嵌态 smoke：文档页不再依赖整图 blob 才能显示摘要
|
||
|
||
出阶段判定：
|
||
|
||
- [ ] 独立页正式主读链已经是 kernel projection
|
||
- [ ] 文档内嵌预览正式主读链已经是 preview projection
|
||
- [ ] compat `mindmaps.get` 只作为 fallback，而不是默认主链
|
||
- [ ] 前端已有清晰的 `projection -> adapter -> renderer` 三层边界
|
||
|
||
### 13.3 Phase 6-C：再切写路径
|
||
|
||
目标：
|
||
|
||
- 常规编辑改为命令流
|
||
|
||
详细 checklist：
|
||
|
||
- [ ] 明确正式写面：
|
||
- `create_node`
|
||
- `update_node`
|
||
- `move_subtree`
|
||
- `reorder_siblings`
|
||
- `archive_node`
|
||
- `restore_node`
|
||
- `attach_edge`
|
||
- `detach_edge`
|
||
- [ ] 补齐 kernel command 缺口：
|
||
- 若当前 kernel 缺少 sibling reorder 命令，需补齐
|
||
- 若当前 kernel 缺少 subtree archive/delete 语义，需补齐
|
||
- 若当前 kernel 缺少导图节点 refs 的 attach/detach 语义，需补齐
|
||
- [ ] compat `MindmapOp` 到 kernel command 的翻译表落地：
|
||
- `addChild`
|
||
- `addSiblingAfter`
|
||
- `updateText`
|
||
- `setHyperlink`
|
||
- `setRefs`
|
||
- `appendNote`
|
||
- `deleteNode`
|
||
- 为每个 op 指定唯一的 kernel command 映射与错误语义
|
||
- [ ] Rust runtime 改造：
|
||
- `/mnt/Data1T/mnote/rust/crates/bridge-runtime/src/lib.rs`
|
||
中的 `mindmap_apply_ops` 改为 command translator
|
||
- 不再直接对 compat 树做 canonical 修改
|
||
- 执行完成后返回：
|
||
- command 执行结果
|
||
- 最新 projection 或 refresh token
|
||
- trace / audit 信息
|
||
- [ ] 前端保存链改造：
|
||
- `MindmapBlock.tsx` 中工具栏操作不再默认走 `getData()/POST whole blob`
|
||
- 节点编辑、移动、删除、引用更新都发命令，而不是整体回传 snapshot
|
||
- 本地只保留短暂 optimistic state，不再作为长期真相
|
||
- [ ] 导图 route 改造：
|
||
- `/api/mindmap/[docId]/[mindmapId]`
|
||
的 `POST` 从常规编辑主入口降级
|
||
- 新增或切换到专用 command route / command envelope
|
||
- `mindmap_put` 只保留：
|
||
- 导入
|
||
- 替换快照
|
||
- 恢复
|
||
- 迁移回放
|
||
- [ ] 双写与迁移策略：
|
||
- 迁移期允许 kernel truth + compat snapshot 双写
|
||
- 双写失败时要有清晰告警，不得静默漂移
|
||
- 明确哪一侧是主真相，哪一侧只是镜像
|
||
- [ ] 冲突与审计：
|
||
- 所有命令返回 revision / version
|
||
- 写入链保留 `command_id` / `request_id` / `trace_id`
|
||
- 并发冲突时优先按 kernel command 冲突规则处理，而不是前端最后一次整图覆盖
|
||
- [ ] 测试与验收：
|
||
- runtime 单测：各类 `MindmapOp` 均正确翻译为 kernel command
|
||
- route 单测：常规编辑不再依赖整图 `put`
|
||
- UI smoke：增删改拖拽节点后可稳定刷新 projection
|
||
- 回归测试：导入/恢复仍可通过 `mindmap_put` 正常工作
|
||
|
||
出阶段判定：
|
||
|
||
- [ ] 常规编辑链路已经以 kernel command 为主
|
||
- [ ] `mindmap_put` 已从常规编辑主链退出
|
||
- [ ] 前端不再依赖 `getData()` 作为长期提交真相
|
||
- [ ] compat snapshot 即使保留，也只是双写镜像或导入导出格式
|
||
|
||
### 13.4 Phase 6-D：统一 AI / CLI
|
||
|
||
目标：
|
||
|
||
- AI / CLI 改为直接操作 kernel truth
|
||
|
||
详细 checklist：
|
||
|
||
- [ ] AI 工具口径统一：
|
||
- 明确 AI 读导图优先读取 kernel projection / subtree
|
||
- 明确 AI 写导图优先发送 kernel command
|
||
- 明确 AI 不再以“输出完整 mindmap JSON 并整体覆盖”作为主模式
|
||
- [ ] compat tool 重构：
|
||
- `mindmap_get`
|
||
降级为 compat read facade
|
||
- `mindmap_get_subtree`
|
||
降级为 compat read facade
|
||
- `mindmap_apply_ops`
|
||
降级为 compat write facade
|
||
- `mindmap_put`
|
||
降级为导入/恢复工具
|
||
- [ ] 新 kernel-aware tool 面补齐：
|
||
- 面向 node / subtree / edge 的导图工具定义
|
||
- 工具参数默认使用：
|
||
- `nodeId`
|
||
- `rootNodeId`
|
||
- `workspaceId`
|
||
- `pageId`
|
||
- `edgeType`
|
||
- 避免继续以 compat `uid + whole tree` 为中心
|
||
- [ ] AI host/runtime 接缝改造：
|
||
- 导图 agent route 优先走 kernel-aware tool
|
||
- `mindmap_outline_to_mindmap` 的输出优先落 kernel truth
|
||
- AI 修改后的刷新结果优先返回 projection，而不是 raw blob
|
||
- [ ] CLI 改造：
|
||
- CLI 新增或切换到导图 kernel command 子命令
|
||
- 现有 `mindmap get/put/op` 标记 compat/legacy 语义
|
||
- CLI smoke 优先验证 kernel command 与 projection 输出
|
||
- [ ] 权限与审计：
|
||
- AI / CLI 导图写入保留 actor / trace / command id
|
||
- 区分：
|
||
- 用户直接编辑
|
||
- AI 代理修改
|
||
- 导入/恢复
|
||
- 确保后续 bridge log / audit 能区分来源
|
||
- [ ] 结果返回规范：
|
||
- AI / CLI 执行导图写命令后，默认返回：
|
||
- command 执行结果
|
||
- 受影响 node / edge
|
||
- 最新 projection 摘要
|
||
- 非必要不再回传整棵 compat 树
|
||
- [ ] 迁移与兼容：
|
||
- 迁移期 compat tools 仍可保留
|
||
- 但默认优先级必须低于 kernel-aware tools
|
||
- 新增 AI 能力时不得再优先扩写 compat blob 工具
|
||
- [ ] 测试与验收：
|
||
- AI tool 单测：至少一条创建节点、修改节点、挂接 refs 的链路走 kernel command
|
||
- CLI smoke：至少一条真实导图操作链不依赖整图覆盖
|
||
- 回归测试：compat tool 仍可用于迁移和紧急 fallback
|
||
|
||
出阶段判定：
|
||
|
||
- [ ] AI 已能直接创建、修改、移动导图节点与引用边
|
||
- [ ] CLI 已能直接操作导图 kernel truth
|
||
- [ ] compat tools 只剩 facade / import-export / fallback 职责
|
||
- [ ] 导图 AI / CLI 主链已经和 Sidebar / 页面树 / 阅读页一样，正式回到统一 kernel command / projection 体系
|
||
|
||
### 13.5 Phase 6-E：压缩旧壳
|
||
|
||
目标：
|
||
|
||
- 把 `MindmapBlock.tsx` 收缩为可替换 view shell
|
||
|
||
要求：
|
||
|
||
- 真相、命令、projection 已完全外移
|
||
- 前端只剩渲染与交互适配
|
||
|
||
---
|
||
|
||
## 14. 完成判定
|
||
|
||
只有同时满足下面几条，才能说 `Kernel Phase 6` 完成。
|
||
|
||
- [ ] 导图正式事实源已经进入 kernel node / edge / subtree
|
||
- [ ] 导图独立页读取的是 kernel projection，而不是 `mindmaps.get` raw blob
|
||
- [ ] 文档内嵌导图读取的是 preview projection，而不是前端直接拼整棵树
|
||
- [ ] 常规编辑操作已经回写 kernel command，而不是 `POST` 整棵 `getData()`
|
||
- [ ] AI / CLI 可以直接创建、修改、移动导图节点，而不依赖整图覆盖
|
||
- [ ] `simple-mind-map` 已经退到 renderer / adapter 层
|
||
- [ ] `mindmaps` blob 存储已降级为 compat snapshot 或导入导出用途
|
||
|
||
---
|
||
|
||
## 15. 非目标
|
||
|
||
这阶段不以这些事情为主目标：
|
||
|
||
- 立即把整个导图画布改写成 Rust 前端
|
||
- 立即替换全部导图 UI 细节
|
||
- 把 `simple-mind-map` 的所有样式字段完整提升为 kernel 语义
|
||
- 在第一阶段就清空全部历史兼容接口
|
||
|
||
Phase 6 的重点只有一个：
|
||
|
||
> **先把导图真相、导图命令、导图 projection 从前端 blob 体系里拔出来，正式并入 `tree-first graph kernel`。**
|