feat(kernel): complete tree-first graph tasks 074-080

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

@@ -0,0 +1,475 @@
+# 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` 和旧壳退场。**