mnote/design/tree-first-graph-kernel-checklist-v2.md

# Tree-First Graph 内核实施清单 v2

> 更新时间：2026-04-16
>
> 基于以下实际状态重写：
> - 当前未提交代码
> - `/mnt/Data1T/mnote/design/tree-first-graph-kernel-v1.md`
> - `/mnt/Data1T/mnote/design/rust-web-long-term-checklist-v2.md`
> - `/mnt/Data1T/mnote/harness-tasks.json`

## 1. 这版为什么要重写

`v1` 已经把长期方向改到了 `tree-first graph kernel`，方向是对的，但完成口径仍然偏乐观。

当前真实代码已经证明：

- Kernel 文档、Rust 类型、query/command 协议、`mnote-web` kernel route 不是空想，已经存在
- 但 Sidebar、搜索、AI、Mindmap、阅读页、`BlockNote` 还没有真正切到 kernel projection 主路径
- `mnote-web` 的 kernel route 已接到真实 `sidebar.dataset.list` query plan，但仍保留 fixture/testing fallback，不能写成“主流量切换完成”

因此 `v2` 的目的不是推翻之前工作，而是把长期清单统一到：

> **既承认已落地的 Rust kernel 代码，也不再把骨架、样板和 host/runtime 拆分误写成长期阶段已完成。**

---

## 2. 状态口径

### `DONE`

- 已有真实代码进入主线
- 不只是文档或骨架
- 对应阶段的最小目标已经成立

### `PARTIAL`

- 已有真实代码和明确接缝
- 但主路径仍未完成切换
- 仍存在 fixture/testing fallback、旧对象模型或重前端壳残留

### `NOT_STARTED`

- 还停留在设计、口径或局部能力
- 尚未形成稳定主链

---

## 3. 当前总判断

当前基线应统一理解为：

- `Kernel Phase 0`：`DONE`
- `Kernel Phase 1`：`DONE`
- `Kernel Phase 2`：`DONE`
- `Kernel Phase 3`：`PARTIAL`
- `Kernel Phase 4`：`PARTIAL`
- `Kernel Phase 5`：`PARTIAL`
- `Kernel Phase 6`：`PARTIAL`
- `Kernel Phase 7`：`PARTIAL`
- `Kernel Phase 8`：`PARTIAL`
- `Kernel Phase 9`：`NOT_STARTED`

一句话总结：

> **Kernel 基础层已经进入真实 Rust 主线，搜索/阅读页/AI 也开始带上 node、subtree、evidence 一类结构上下文，但 consumer 主路径仍未切完，旧前端壳依然是主要执行面。**

---

## 4. 新架构的真实验收定义

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

| 验收项 | 当前状态 | 说明 |
| --- | --- | --- |
| Rust 中存在统一的 kernel node / edge / projection / subtree 真相层 | `DONE` | `core-protocol` 已落地 |
| Rust 中存在统一的 kernel query / command 面 | `DONE` | `bridge-runtime` 已支持 kernel 查询与写协议 |
| Rust Web 能承接 kernel route | `PARTIAL` | `mnote-web` 已有 route，且已接到真实 sidebar dataset query plan，但仍是样板级接入 |
| Sidebar / 页面树 / 文件树直接消费 kernel projection | `PARTIAL` | 前端主 Sidebar 已以 `kernelSidebarTree` 作为主树来源，但仍是重客户端壳，其他树域仍残留旧拼树 helper |
| 搜索直接消费 kernel-aware 检索结果 | `PARTIAL` | cron 已有 `kernel-aware refresh` 过渡链，搜索结果也已带 `nodeId` / `subtreeRootId` / `evidence`，但仍是 LightRAG 过渡口径，不是 kernel 真相层检索 |
| 阅读页直接消费 page subtree projection | `PARTIAL` | `DocumentReadView` 已直接消费 `pageSubtree`，但 projection 仍在前端读链内生成，不是 Rust/kernel 真相层输出 |
| AI 直接面向 node / subtree / edge 操作 | `PARTIAL` | AI runtime 与 Hermes bridge 已开始携带 `node` / `subtree` / `outline` / `evidence` 上下文，但还不是完整的 kernel-first tool 面 |
| Mindmap 正式退化为 projection / editor | `PARTIAL` | 理念已定，独立页已去 stub，但数据真相尚未下沉到 kernel |
| `BlockNote` 只负责内容节点编辑 | `PARTIAL` | 阅读态已先走 `pageSubtree`，编辑器也已按需挂载，但外围 panel / drawer 仍集中在 `DocumentContent` |
| 旧前端壳不再承担对象真相 | `NOT_STARTED` | 当前主入口仍是 Next/React |

---

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

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

### 已落地

- `tree-first-graph-kernel-v1.md` 已冻结：
  - `node`
  - `edge`
  - `projection`
  - `subtree`
  - `content node`
  - `reference edge`
  - `summary node`
  - `index node`
- 已明确四层边界：
  - 事实源
  - 投影
  - 编辑器
  - 外挂
- 已明确：
  - `Mindmap` 不是事实源
  - `BlockNote` 不是事实源
  - 页面树/文件树不是事实源

### 完成判定

- 后续长期任务不再把导图页、页面树、`BlockNote` 文档结构当作独立真相层

---

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

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

### 已落地

- `rust/crates/core-protocol/src/kernel.rs` 已存在统一类型
- `rust/crates/core-protocol/src/lib.rs` 已导出 kernel 类型

### 已有能力

- `KernelNode`
- `KernelEdge`
- `KernelProjectionRequest`
- `KernelProjectionResult`
- `KernelSubtreeRef`
- `KernelSubtreeResult`
- `KernelAuditStamp`
- `KernelNodeType`
- `KernelEdgeType`
- `KernelProjectionKind`

### 当前结论

- 这一阶段不应再回退为“只有文档设计”
- 这里已经是实际代码事实

---

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

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

### 已落地

- `rust/crates/bridge-runtime/src/lib.rs` 已支持：
  - `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`
- `rust/crates/storage-convex-bridge/src/mapping.rs` 已补 kernel query / command 映射

### 当前结论

- 这一阶段也不应再写成“待设计”
- 真实缺口不在协议是否存在，而在谁来真正消费这些协议

---

## 8. Kernel Phase 3：Rust Web 接入 kernel，成为主承载层

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

### 已落地

- `rust/crates/mnote-web/` 已进入 workspace
- 已存在 `axum` app/router/context/middleware 骨架
- 已有 kernel route：
  - `/api/kernel/projections/sidebar`
  - `/api/kernel/subtree`
  - `/api/kernel/edges`
  - `/api/kernel/graph`
- sidebar kernel route 已通过 `sidebar.dataset.list` runtime plan + `execute_sidebar_dataset_query(...)` 读取数据集
- 已有路由测试，说明 route 不只是声明

### 当前真实问题

- `mnote-web` 还不是主 Web 入口
- kernel route 主链已经不再直接依赖 `demo_sidebar_dataset(...)` helper，但仍保留 `MNOTE_WEB_KERNEL_SIDEBAR_FIXTURE_JSON` 环境变量 fallback
- 当前更真实的接缝主要集中在 sidebar dataset 这一条查询上，还没有形成更广的 workspace / storage / bridge 主链
- 这只能证明“kernel route 已进入 Rust Web”，不能证明“真实主链已切过去”

### 下一阶段必须完成

- 把 fixture fallback 收紧到测试/开发边界，避免环境变量 fixture 成为隐性主链
- 在 sidebar dataset 之外，再打通至少一条真实 workspace / storage / bridge 查询主链
- 至少让一条真实页面树或工作区查询主链通过 `mnote-web` 提供
- 明确 Next -> Rust Web 的真实流量边界

### 完成判定

- 至少一条不依赖 fixture fallback 的 kernel 查询主链在 `mnote-web` 上稳定运行

---

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

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

### 已落地

- Sidebar 已有服务端首包
- Rust runtime 已能把 `sidebar.dataset.list` 转为统一 kernel subtree / projection 结果
- `sidebar-data.ts` 已生成 `kernel_sidebar_projection` 与 `kernelSidebarTree`
- 前端主 Sidebar 已以 `sidebarData.kernelSidebarTree` 作为初始化与同步的主树来源

### 当前真实问题

- 前端主 Sidebar 仍是超大客户端组件
- 主 Sidebar 已不再以 `DocumentRecord[] -> buildDocumentTree(...)` 作为主树入口，但 `move-embed picker`、`lib/documents.ts` 等兼容场景仍保留旧拼树 helper
- 页面树 / 文件树还没有完全统一到 kernel node / edge 真相层

### 下一阶段必须完成

- 把主 Sidebar 之外的 page tree、file tree、embed/move picker 也统一改读 kernel projection
- 把展开、折叠、拖拽、hover 之类状态收口为纯 UI 层
- 收敛 `buildDocumentTree(...)` 一类旧树 helper 的残留 consumer
- 让布局层只保留轻 host，不再常驻重树组件

### 完成判定

- 主 Sidebar 以及相关树域已直接消费 kernel projection
- 页面树 / 文件树 / 嵌入移动器等不再通过旧对象数组拼树

---

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

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

### 新口径

这阶段不再按“单独搭一个 RAG 系统”来定义。

长期正确方向是：

- 用 cron 定时刷新知识
- 直接把结构知识写回 kernel
- 用 kernel-aware 检索命中 node / subtree / evidence

这与传统 `LightRAG-first` 不同，更接近：

- Karpathy 的知识刷新思路：https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
- `llmwiki-cli` 这类结构化知识索引方案：https://github.com/doum1004/llmwiki-cli；https://github.com/stellarlinkco/llm-wiki/blob/main/README.zh-CN.md
- `Mindmap` / `BookMindmap` / 章节树 / 书籍子树作为结构索引投影

当前已经有直接代码证据，但只能算过渡态：

- `convex/crons.ts` 已新增 `kernel_aware_refresh_daily_transition`
- `convex/jobs.ts` 已新增 `enqueueKernelAwareRefresh`、`enqueueKernelAwareRefreshSweep` 与 `refresh.kernel_aware_transition`
- 刷新结果已带 `nodeIds`、`subtreeRootIds`、`evidenceAssetIds`
- 搜索结果类型与 adapter 已返回 `nodeId` / `subtreeRootId` / `evidence`

但这条链目前仍通过 `LightRAG` 过渡入库，还不能写成“kernel 真相层知识刷新已完成”。

### 已落地

- 已有 cron 驱动的 `kernel-aware refresh` 过渡入口
- 已有工作空间成员校验与刷新目标选择：
  - workspace
  - document
  - mindmap
  - asset
- 已有搜索结果结构化返回：
  - `nodeId`
  - `subtreeRootId`
  - `evidence`
- recent / 常规搜索在缺失 Rust evidence 时，也会补齐最小 evidence fallback

### 当前真实问题

- 结构知识仍未直接写回 kernel node / edge
- `summary node`、`ai_note node`、`index node`、`reference edge` 还没有形成真实 kernel 写链
- `BookMindmap` / 章节树还没有形成统一 kernel index 主链
- 当前刷新任务仍是 `kernel_aware_transition`，不是最终的 kernel truth pipeline
- 搜索虽已消费 kernel-aware 结果形状，但还没有 server-first 搜索页或 Rust Web 检索壳

### 下一阶段必须完成

- 把 `kernel_aware_transition` 从 LightRAG 过渡链继续收口到真实 kernel 节点/边写链
- 明确 `summary node`、`ai_note node`、`index node`、`reference edge` 的真实写入协议
- 把增量刷新输入继续稳定到：
  - workspace
  - page
  - subtree
  - book
  - pdf
- 把刷新输出真正落到：
  - `summary node`
  - `ai_note node`
  - `index node`
  - `reference edge`
  - `book subtree`
  - `chapter subtree`
- 把检索面继续推进到：
  - 按 node type 过滤
  - 按 subtree 过滤
  - 按 edge 过滤
  - 返回正文/附件/页码/证据回查
- 定义残留 `LightRAG` 的过渡边界与移除计划

### 完成判定

- 至少一条 cron 驱动的知识刷新链能稳定更新 kernel 节点/边
- 至少一条搜索链能直接返回 kernel node / subtree / evidence

---

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

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

### 已落地

- 理念上已经确认 `Mindmap` 不是中心
- Rust 侧已有 Mindmap 对象协议
- 独立导图页已先在服务端获取 initial projection，再进入客户端页面壳
- 独立导图页已直接使用 `StandaloneMindmapView`，不再以 `editorStub` 作为入口
- `MindmapBlock.tsx` 已出现 `standalone` / `documentBridge` 边界
- 文档内嵌导图已默认走 preview-first 入口

### 当前真实问题

- 独立导图页仍是客户端重壳，并且仍复用同一个重型 `MindmapBlock` 族组件
- 文档内嵌导图虽然已经 preview-first，但进入编辑/沉浸态后仍复用同一个重型 `MindmapSurfaceView`
- 导图操作尚未直接回写统一 kernel subtree

### 下一阶段必须完成

- 继续把独立导图页壳从文档编辑上下文与共享重组件中拆开
- 内嵌导图改为轻预览/轻编辑入口
- 把导图编辑动作收口为 kernel command

### 完成判定

- 独立导图页与文档内嵌导图都只作为 kernel projection / editor 入口，而不是独立事实源

---

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

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

### 已落地

- 阅读态/编辑态已经分离
- `DocumentContent` 已生成 `pageSubtree`
- `DocumentReadView` 已直接消费 `pageSubtree`
- 阅读态结构面板已直接消费 `outline` / `evidence`
- `BlockNote` 默认不再首屏强挂
- AI 已做 host/runtime 拆分
- `DocumentAiAgentPanel.runtime.tsx` 已向 AI route 发送 `node` / `subtree` / `outline` / `evidence`
- `/api/ai-agent/run` 已把这些上下文序列化进 Hermes 指令

### 当前真实问题

- 阅读页已经是 page subtree projection 驱动，但 projection 仍在前端读链内生成，不是 Rust/kernel 真相层直接输出
- `DocumentContent` 仍集中挂载 `DocumentAiAgentPanel`、`DocumentHistoryDrawer`、`DocumentCommentsDrawer`、`PageBacklinksPanel`、`PageOptionsSidebar`
- AI runtime 仍是页面级重壳，不是 kernel-first tool bridge
- 搜索/AI/阅读页之间虽然开始共享 `node` / `subtree` / `outline` / `evidence` 口径，但还没有统一到稳定的 node / subtree / edge 真相协议面

### 下一阶段必须完成

- 把 page subtree projection 从前端读链继续下沉到更稳定的 Rust/kernel 输出边界
- 阅读页大纲、回链、结构信息改读 kernel edge / subtree
- AI tool 直接面向 node / subtree / edge
- AI 可以创建：
  - `summary node`
  - `ai_note node`
  - `reference edge`
- 搜索与 AI 共用 kernel-aware 检索上下文

### 完成判定

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

---

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

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

### 已落地

- `src/lib/documents/page-subtree.ts` 已显式定义 `pageSubtree`
- `DocumentContent` 已把阅读态与编辑态拆开
- `DocumentContent` 已通过 `isEditing` / `keepEditorMounted` 让 `BlockNote` 按需挂载
- 阅读态已不再默认依赖 `BlockNote` 才能渲染正文

### 当前真实问题

- 页面结构仍未与 `BlockNote` 内容结构彻底解耦
- `DocumentContent` 仍挂着大量外围 panel / drawer
- page subtree 与 content node 的边界还没有正式回写到 kernel / editor 分层

### 下一阶段必须完成

- 把 page subtree 与 content node 的边界继续固化到更稳定的 kernel / editor 分层
- 明确哪些节点继续由 `BlockNote` 编辑
- 明确哪些结构节点改由 kernel-aware editor 处理
- 把外围 panel 从编辑宿主中继续拆走

### 完成判定

- 页面结构不再由 `BlockNote` 数据结构定义
- `BlockNote` 只承担内容节点编辑

---

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

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

### 当前真实问题

- 当前主应用入口仍是 Next App Router
- 当前主文档页、主 Sidebar、主搜索、主导图页都仍运行在旧前端壳内

### 下一阶段必须完成

- 盘点旧对象真相残留
- 盘点旧 helper / adapter 残留
- 删除已被 kernel projection 替代的旧 route
- 删除已被 kernel command/query 替代的旧 adapter
- 明确最终双栈收缩与切流计划

### 完成判定

- 旧前端壳与旧对象模型都不再承担主事实来源

---

## 15. 推荐执行顺序

如果按当前真实代码继续推进，建议顺序是：

1. 完成 `Kernel Phase 3` 收尾
2. 先打通 `Kernel Phase 4`
3. 同步启动 `Kernel Phase 5`
4. 再推进 `Kernel Phase 6`
5. 再推进 `Kernel Phase 7`
6. 最后才进入 `Kernel Phase 8` 和 `Kernel Phase 9`

原因很简单：

- 如果 `mnote-web` 仍是 demo route，后面的 projection consumer 都会继续挂在旧前端壳上
- 如果 Sidebar / 页面树还没切到 kernel，工作区主导航就还没换真相层
- 如果知识刷新与 kernel-aware 检索不成立，AI 和 BookMindmap 路线也无法形成长期闭环

---

## 16. 最终结论

当前最准确的表述不是“长期阶段已经做完”，而是：

> **Kernel 基础层已经做出来了，真正难的部分才刚开始，也就是让所有主视图与主工具链逐步切到 kernel projection。**

所以后续主线必须固定为：

> **先补齐 Rust Web 的真实 kernel 主链，再切 Sidebar / 页面树 / 文件树，再建立结构知识刷新与 kernel-aware 检索，之后才轮到 Mindmap、阅读页、AI、`BlockNote` 和旧壳退场。**