mnote/design/old/01-tree-first-graph-kernel/process/tree-first-graph-kernel-checklist-v1.md

# 1-0 [recycle] Tree-First Graph 内核实施清单 v1

> 更新时间：2026-04-16
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md`
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
> - `/mnt/Data1T/mnote/design/06-mindmap/process/6-mindmap-kernel-phase6-projection-editor-v1.md`
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`

## 1. 文档目的

这份清单是基于**新架构前提**重写的。

此前的长期清单主要站在：

- Rust Web 层
- 页面访问性能
- islands 化

这些视角来拆解任务。

现在架构前提已经变化：

> **mnote 的长期中心不再只是“Rust Web + 页面瘦身”，而是“Tree-First Graph Kernel + 多投影 + Rust 主执行面”。**

因此这份清单的目标是：

- 先定义统一结构内核要怎么落地
- 再定义 Sidebar / 页面树 / 文件树 / Mindmap / 搜索 / AI / BlockNote 如何接入这个内核
- 最后再定义 Rust Web 层与前端投影视图如何围绕内核重构

---

## 2. 先给结论

长期路线应改成下面这个顺序：

1. **先立 kernel**
2. **再让 Rust Web 承接 kernel 的 query / command / projection**
3. **再让 Sidebar、搜索、Mindmap、AI、阅读页都开始直接消费 kernel**
4. **最后才边缘化 `BlockNote` 与旧前端壳**

这意味着：

- Rust Web 仍然重要
- 页面性能重构仍然重要
- 但它们现在都不是第一原则

第一原则变成：

> **所有对象最终都要回到统一的 `tree-first graph kernel`，而不是继续各自挂在不同前端壳和对象模型上。**

---

## 3. 新的总体验收定义

只有同时满足下面几条，才能说新架构真正成立：

- [x] 已存在 Rust 主导的 kernel node / edge 真相层
- [ ] 页面树、文件树、Mindmap、RAG 结构索引、AI 结构操作都开始直接依赖 kernel，而不是各有一套真相
- [x] Rust Web 层开始作为 kernel 的主 query / command / projection 承载层
- [x] Sidebar / 搜索 / 阅读页 / Mindmap / AI 至少有一部分已变成 kernel projection
- [ ] `BlockNote` 不再定义页面结构本体，只负责某类内容节点编辑
- [ ] 旧前端壳不再承担对象真相，只承担过渡投影或兼容层

---

## 4. 重新定义阶段

新架构下，阶段顺序应改成：

- Kernel Phase 0：边界冻结与术语统一
- Kernel Phase 1：Node / Edge / Projection 基础模型落地
- Kernel Phase 2：Kernel Query / Command / Subtree / Graph Traversal 协议落地
- Kernel Phase 3：Rust Web 接入 kernel，成为主承载层
- Kernel Phase 4：Sidebar / 页面树 / 文件树切到 kernel projection
- Kernel Phase 5：结构知识刷新与 kernel-aware 检索
- Kernel Phase 6：Mindmap 降级为 projection / editor，而不是对象中心
- Kernel Phase 7：文档阅读页与 AI 面板切到 kernel projection
- Kernel Phase 8：`BlockNote` 退化为内容编辑挂件
- Kernel Phase 9：旧前端壳与旧对象模型下线

---

## 5. Kernel Phase 0：边界冻结与术语统一

**当前状态：`DONE`**

### 5.1 目标

先把“什么是 kernel，什么只是 projection”说清楚。

### 5.2 已有事实

- [x] 已有：
  - [tree-first-graph-kernel-v1.md](/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md)
  - [rust-web-long-term-checklist-v2.md](/mnt/Data1T/mnote/design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md)
- [x] 已明确：
  - `Mindmap` 不是中心
  - `BlockNote` 不是中心
  - `tree-first graph` 才是中心

### 5.3 仍需完成

- [x] 统一术语：
  - `node`
  - `edge`
  - `projection`
  - `subtree`
  - `content node`
  - `reference edge`
  - `summary node`
  - `index node`
- [x] 统一“事实源 / 投影 / 编辑器 / 外挂”的四层边界
- [x] 明确哪些现有对象暂时继续存在，哪些将来必须并入 kernel

### 5.4 完成判定

- [x] 后续文档和任务不再把“导图页”“页面树”“BlockNote 文档”当作独立事实源

### 5.5 当前落地说明

- [x] `tree-first-graph-kernel-v1.md` 已补术语冻结、四层边界与并入策略
- [x] 当前口径明确：
  - 导图页不是事实源
  - 页面树不是事实源
  - `BlockNote` 文档结构不是事实源

---

## 6. Kernel Phase 1：Node / Edge / Projection 基础模型落地

**当前状态：`DONE`**

### 6.1 目标

把设计文档中的 kernel 定义，变成真正的 Rust 类型与协议。

### 6.2 实施清单

- [x] 在 Rust core 中定义统一 `Node` 模型
- [x] 定义统一 `Edge` 模型
- [x] 定义统一 `Projection` 请求模型
- [x] 定义 node type 枚举或稳定字符串集合
- [x] 定义 edge type 枚举或稳定字符串集合
- [x] 定义 node metadata / content payload / refs payload 边界
- [x] 定义 subtree 标识方式
- [x] 定义 projection 标识方式
- [x] 定义版本、审计、trace 在 kernel 上的挂载方式

### 6.3 最小首批节点建议

- [x] `workspace`
- [x] `folder`
- [x] `page`
- [x] `section`
- [x] `asset`
- [x] `book`
- [x] `pdf`
- [x] `mindmap_node`
- [x] `summary`
- [x] `ai_note`
- [x] `reference_anchor`

### 6.4 最小首批边建议

- [x] `parent_of`
- [x] `child_of`
- [x] `contains`
- [x] `references`
- [x] `backlinks_to`
- [x] `source_of`
- [x] `summarizes`
- [x] `indexes`

### 6.5 完成判定

- [x] Rust core 中已经存在可被 Web / CLI / AI 共用的 kernel 类型定义

### 6.6 当前落地说明

- [x] `rust/crates/core-protocol/src/kernel.rs` 已进入主线
- [x] `core-protocol/src/lib.rs` 已导出 kernel 类型，供 Web / runtime 复用

---

## 7. Kernel Phase 2：Kernel Query / Command / Subtree / Graph Traversal 协议落地

**当前状态：`DONE`**

### 7.1 目标

让 kernel 不是静态类型，而是可以被查询和操作。

### 7.2 实施清单

- [x] 定义 `get_node`
- [x] 定义 `get_subtree`
- [x] 定义 `list_children`
- [x] 定义 `list_edges`
- [x] 定义 `traverse_graph`
- [x] 定义 `create_node`
- [x] 定义 `update_node`
- [x] 定义 `move_subtree`
- [x] 定义 `attach_edge`
- [x] 定义 `detach_edge`
- [x] 定义 `project_view`

### 7.3 与当前已有能力的关系

当前已有一些可复用基础：

- [x] Mindmap 的 subtree / op 思想
- [x] Rust command/query/tool envelope
- [x] CLI / AI / runtime 可共用的调用结构

但还没有：

- [x] 统一 kernel query / command 面

### 7.4 完成判定

- [x] 至少有一组 kernel 查询和写入协议进入 Rust core-protocol / bridge-runtime 主线

### 7.5 当前落地说明

- [x] `bridge-runtime` 已支持：
  - `kernel.node.get`
  - `kernel.subtree.get`
  - `kernel.children.list`
  - `kernel.edges.list`
  - `kernel.graph.traverse`
  - `kernel.project_view`
  - `kernel.node.create`
  - `kernel.node.update`
  - `kernel.subtree.move`
  - `kernel.edge.attach`
  - `kernel.edge.detach`
- [x] 当前首条真实 projection 样板已选用 Sidebar 数据集，经 Rust runtime 统一输出 kernel subtree / projection 结果

---

## 8. Kernel Phase 3：Rust Web 接入 kernel

**当前状态：`DONE`**

### 8.1 目标

让 `mnote-web` 不只是通用骨架，而是开始承接 kernel。

### 8.2 当前已有事实

- [x] `mnote-web` 骨架已存在
- [x] 已有 request context / SSE / WS / Hermes bridge skeleton

### 8.3 仍需完成

- [x] 让 `mnote-web` 开始提供 kernel query route
- [x] 让 `mnote-web` 提供 subtree / projection route
- [x] 至少切一条真实主路径，不再只是 compat bridge
- [x] 为 kernel route 增加集成验证

### 8.4 完成判定

- [x] `mnote-web` 已承接至少一条真实 kernel 主链

### 8.5 当前落地说明

- [x] `rust/crates/mnote-web/src/routes/kernel.rs` 已新增：
  - `/api/kernel/projections/sidebar`
  - `/api/kernel/subtree`
  - `/api/kernel/edges`
  - `/api/kernel/graph`
- [x] `mnote-web` 已通过路由级测试，说明 kernel projection 已经不再只是骨架声明

---

## 9. Kernel Phase 4：Sidebar / 页面树 / 文件树切到 kernel projection

**当前状态：`PARTIAL`**

### 9.1 目标

把工作区导航从“前端组件 + 自己拼树”，改成“kernel tree projection”。

### 9.2 当前真实状态

- [x] Sidebar 有服务端首包
- [x] Sidebar 有 Rust query 契约基础
- [ ] 但主 Sidebar 仍是超大客户端组件
- [ ] 页面树 / 文件树还没有真正基于 kernel node / edge

### 9.3 实施清单

- [ ] 用 kernel node/edge 重新定义 Sidebar 数据源
- [ ] 用 projection query 输出 Sidebar tree
- [ ] 用 projection query 输出 file tree
- [ ] 用 projection query 输出 page tree
- [ ] 把展开/折叠/拖拽从对象真相层剥离成局部 UI 状态
- [ ] 把主布局里的 Sidebar 继续拆轻

### 9.4 完成判定

- [x] Sidebar / 页面树 / 文件树已经开始直接消费 kernel projection

### 9.5 当前落地说明

- [x] Rust runtime 已经可以把 `sidebar.dataset.list` 转成统一 kernel projection / subtree 结果
- [ ] 当前前端主 Sidebar 还没有直接切到这个结果，仍保留 `DocumentRecord[] -> buildDocumentTree(...)` 的旧拼树逻辑

---

## 10. Kernel Phase 5：结构知识刷新与 kernel-aware 检索

**当前状态：`NOT_STARTED`**

### 10.1 目标

让系统不再依赖一个独立的传统 RAG 子系统，而是：

- 通过定时知识刷新持续生成和维护结构化知识
- 通过 kernel-aware 检索直接命中 node / subtree / evidence
- 通过 Mindmap / BookMindmap / summary node / reference edge 构成知识索引层

一句话说：

> **不是“部署一个 RAG 系统”，而是“把 kernel 本身建设成可刷新、可检索、可追溯的知识底座”。**

### 10.2 需要完成

- [ ] 定义知识刷新任务模型
- [ ] 定义 cron 驱动的定时刷新入口
- [ ] 定义增量刷新输入：workspace / book / pdf / page / subtree
- [ ] 定义知识刷新输出：
  - `summary node`
  - `ai_note node`
  - `index node`
  - `reference edge`
  - `book subtree`
  - `chapter subtree`
- [ ] 定义 kernel-aware 搜索输入
- [ ] 定义按 node type / subtree / edge 的过滤
- [ ] 让检索结果可以返回 node / subtree / evidence
- [ ] 定义“结构命中 -> 正文/附件/页码回查”的两段式检索
- [ ] 把书籍 / PDF / 章节树 / BookMindmap 纳入 kernel index
- [ ] 把 `Mindmap` / `BookMindmap` 定义成结构知识索引的一种 projection，而不是独立 RAG 页面
- [ ] 如果现有 `LightRAG` 仍有残留，明确其过渡边界与移除计划

### 10.3 当前基础

- [x] 搜索已有前端 runtime
- [x] Rust 有 FTS 与 Mindmap subtree 能力雏形
- [x] 已有 `BookRAG` / `Mindmap` / `BookMindmap` 方向上的结构索引思路
- [ ] 但还没有真正的知识刷新任务层
- [ ] 还没有 kernel-aware 检索面
- [ ] 还没有把“定时刷新知识 -> 更新 kernel 节点/边 -> 查询回查证据”串成主链

### 10.4 完成判定

- [ ] 至少有一条 cron 驱动的知识刷新链可以稳定更新 kernel 中的结构知识节点
- [ ] 至少有一条检索路径能直接返回 kernel node / subtree 命中结果
- [ ] 至少有一条命中结果能继续回查正文、附件、页码或证据节点

---

## 11. Kernel Phase 6：Mindmap 降级为 projection / editor

**当前状态：`PARTIAL`**

### 11.1 目标

让 Mindmap 从“独立对象中心 + blob 真相 + 前端重壳”退回到“kernel subtree / graph 的一种 projection / editor”。

### 11.2 当前已有事实

- [x] Rust `core-protocol` 已有：
  - `KernelNodeType::Mindmap`
  - `KernelNodeType::MindmapNode`
  - `KernelProjectionKind::Mindmap`
- [x] Rust runtime 已有：
  - `mindmap_get`
  - `mindmap_get_subtree`
  - `mindmap_put`
  - `mindmap_apply_ops`
- [x] 导图独立页已脱离 `editorStub`
- [x] 当前主线理念已明确：
  - `Mindmap` 不是中心
  - `tree-first graph kernel` 才是中心
- [x] 但当前真实主链仍然主要是：
  - `MindmapBlock.tsx` 持有重交互壳
  - `mindmaps.get/put` 读写整棵 blob
  - 前端 `buildMindmapProjection(...)` 对 blob 做摘要
  - `mindmap_apply_ops` 仍直接操作 compat mindmap 树

### 11.3 仍需完成

- [x] Phase 6 的详细口径改以：
  - `/mnt/Data1T/mnote/design/06-mindmap/process/6-mindmap-kernel-phase6-projection-editor-v1.md`
  - 为准
- [ ] 把导图事实源切到 kernel node / edge / subtree
- [ ] 把 `MindmapTreeNode` / `MindmapOp` 降级为 compat DTO，而不是长期 canonical model
- [ ] 让导图独立页读取正式 `mindmap` kernel projection，而不是继续以 `mindmaps.get` raw blob 为主
- [ ] 让文档内嵌导图读取 `mindmap_preview` / subtree preview，而不是直接拼整棵树
- [ ] 让导图编辑操作回写 kernel command，而不是继续以 `getData()/POST whole blob` 为主
- [ ] 让 `mindmap_apply_ops` 改成 compat facade，内部翻译到 kernel command
- [ ] 让 AI / CLI 可以直接创建、修改、移动 `mindmap_node` 与 reference edge
- [ ] 让 `mindmaps` 表退到 compat snapshot / import-export 层，而不是长期事实源

### 11.4 完成判定

- [ ] 导图独立页与内嵌预览都已经直接消费 kernel projection
- [ ] 常规编辑不再依赖整图 blob 覆盖保存
- [ ] AI / CLI 已能直接操作导图 kernel truth
- [ ] `simple-mind-map` 已退到 renderer / adapter 层
- [ ] `Mindmap` 可以被正式定义为 kernel 的一种 projection / editor，而不是独立事实源

---

## 12. Kernel Phase 7：文档阅读页与 AI 面板切到 kernel projection

**当前状态：`NOT_STARTED`**

### 12.1 目标

让阅读页和 AI 都不再直接围绕旧页面对象模型打转，而是围绕 kernel。

### 12.2 阅读页部分

- [ ] 阅读页改成读取 page subtree projection
- [ ] 阅读页大纲来自 kernel subtree
- [ ] 回链、引用、结构信息来自 kernel edge
- [ ] 页面阅读流作为 projection，而不是事实源

### 12.3 AI 部分

- [ ] AI tool 直接面向 node / subtree / edge
- [ ] AI 不再默认面向“页面前端壳”
- [ ] AI 能创建 summary node / ai_note node / reference edge
- [ ] AI 能把 PDF / Book 解析结果落进 kernel index

### 12.4 当前基础

- [x] 文档阅读态已出现
- [x] AI host/runtime 已拆分
- [ ] 但两者都还没开始直接面向 kernel projection

### 12.5 完成判定

- [ ] 阅读页与 AI 至少有一条主路径已经直接消费 kernel projection

---

## 13. Kernel Phase 8：BlockNote 退化为内容编辑挂件

**当前状态：`NOT_STARTED`**

### 13.1 目标

把 `BlockNote` 从“页面定义者”改成“某类内容节点编辑器”。

### 13.2 当前已有事实

- [x] 文档页默认已不再直接强挂 `BlockNote`

### 13.3 仍需完成

- [ ] 定义 page subtree 与 content node 的关系
- [ ] 定义哪些节点仍由 `BlockNote` 编辑
- [ ] 定义哪些结构节点改由 kernel-aware editor 操作
- [ ] 把页面结构与 `BlockNote` 块结构彻底分离
- [ ] 把 `DocumentContent` 里外围 panel 再次拆出去

### 13.4 完成判定

- [ ] 页面结构已经不再由 `BlockNote` 数据结构定义

---

## 14. Kernel Phase 9：旧前端壳与旧对象模型下线

**当前状态：`NOT_STARTED`**

### 14.1 目标

当 kernel + Rust Web + projection 都建立后，再下线旧对象模型和旧主壳。

### 14.2 实施清单

- [ ] 盘点哪些旧页面/route 仍直接承载对象真相
- [ ] 盘点哪些旧 helper 仍在拼装第二套对象模型
- [ ] 删除已被 kernel projection 替代的旧 route
- [ ] 删除已被 kernel command/query 替代的旧 adapter
- [ ] 更新最终架构文档与对外口径

### 14.3 完成判定

- [ ] 旧前端壳与旧对象模型都不再是主事实来源

---

## 15. 这份清单与 Rust Web v2 的关系

这份清单不是替代：

- [rust-web-long-term-checklist-v2.md](/mnt/Data1T/mnote/design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md)

而是对它做“上位重排”。

关系应理解为：

- `rust-web-long-term-checklist-v2`
  - 关注当前代码状态下的 Web / 页面重构现实进度
- `tree-first-graph-kernel-checklist-v1`
  - 关注在新内核架构下，整体路线应该如何重新排序

一句话说：

> **Rust Web v2 告诉你“现在代码做到哪了”，这份新清单告诉你“在新架构下，接下来应该围绕什么继续做”。**

---

## 16. 最终结论

采用新架构后，长期 checklist 的中心必须变化。

不再是：

- 先 Web 重构，再考虑对象模型

而应该是：

- **先 Kernel，再 Projection，再 Web，再 Editor**

因此后续真正的主线应改成：

> **以 `tree-first graph kernel` 为事实中心，Rust Web 承接其 query/command/projection，Sidebar/搜索/Mindmap/阅读页/AI 都逐步切到 kernel projection，最后再让 `BlockNote` 与旧前端壳退场。**