# 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`。**