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

design/rust-web-long-term-checklist-v2.md

@@ -0,0 +1,462 @@
+# Rust Web 长期架构实施清单 v2
+
+> 更新时间：2026-04-16
+>
+> 基于以下实际状态重写：
+> - 当前未提交代码
+> - `/mnt/Data1T/mnote/harness-tasks.json` 中 `task-059` ~ `task-069`
+> - `/mnt/Data1T/mnote/design/rust-web-long-term-architecture-v1.md`
+> - `/mnt/Data1T/mnote/design/rust-web-long-term-checklist-v1.md`
+> - `/mnt/Data1T/mnote/design/tree-first-graph-kernel-v1.md`
+
+## 1. 这版为什么要重写
+
+这次重写的原因很明确：
+
+- `task-059` ~ `task-069` 目前在 `harness-tasks.json` 里已经被标为 `completed`
+- 但从当前未提交代码实际看，很多项只证明了：
+  - 文档已补
+  - 骨架已建
+  - 局部组件已拆
+  - `eslint` / `cargo check` 可过
+- **并不能证明对应长期阶段已经真正完成**
+
+因此这版 checklist 的目标不是重复愿景，而是：
+
+> **把长期路线重新落回“真实代码状态”，明确哪些已经落地、哪些只是最小接缝、哪些仍未开始。**
+
+---
+
+## 2. 当前总判断
+
+从当前代码看，长期路线的真实状态是：
+
+### 2.1 已有明确进展
+
+- [x] `Phase 0` 的文档化边界梳理已经完成
+- [x] `Phase 1` 已落了一个最小 `axum` Web 骨架：`rust/crates/mnote-web/`
+- [x] `Phase 2` 文档阅读态分离已经有实质代码
+- [x] `Phase 3` 主 Sidebar 已出现 `kernelSidebarTree` 消费接缝
+- [x] `Phase 4` 搜索已做 host/runtime 拆分，并开始返回 `nodeId` / `subtreeRootId` / `evidence`
+- [x] `Phase 5` AI 面板已做 host/runtime 拆分，并开始向 Hermes bridge 传递 `node` / `subtree` / `outline` / `evidence`
+- [x] `Phase 6` Mindmap 独立页已去掉 `editorStub` 主入口
+- [x] `Phase 7` 阅读态已直接消费 `pageSubtree`，`BlockNote` 也已不是文档页默认唯一入口
+
+### 2.2 但大部分阶段都只是“部分落地”
+
+- [ ] `Phase 1` 还不是主 Web 路径，只是 Rust Web skeleton
+- [ ] `Phase 3` Sidebar 仍是超大客户端组件，其他树域也未统一切到 kernel projection
+- [ ] `Phase 4` 搜索仍是前端 runtime 主导，不是 server-first 搜索页
+- [ ] `Phase 5` AI runtime 仍然很重，只是懒挂载了
+- [ ] `Phase 6` Mindmap 仍然是重前端交互壳，不是独立对象页壳
+- [ ] `Phase 7` 文档页外围面板仍集中在 `DocumentContent`
+- [ ] `Phase 8` 旧 Next/React 主路径完全没有完成切换
+
+### 2.3 结论
+
+> **当前真实状态不是“Phase 0 ~ 8 已全部完成”，而是“Phase 0 基本完成，Phase 1/2/4/5/6/7 处于不同程度的部分落地，Phase 3 和 Phase 8 仍远未完成”。**
+
+---
+
+## 3. 重新定义状态口径
+
+为了避免再次把“有骨架”写成“已完成”，v2 统一使用下面三种状态：
+
+### `DONE`
+
+定义：
+
+- 代码主路径已经切换
+- 不是只有文档或骨架
+- 用户可感知行为已经变了
+- 后续只剩清理和补强
+
+### `PARTIAL`
+
+定义：
+
+- 已有真实代码改动
+- 但仍是局部接缝、最小骨架、阶段性拆分
+- 主路径尚未彻底切换
+
+### `NOT_STARTED`
+
+定义：
+
+- 还停留在设计或口径层
+- 或只有零散基础，不足以算阶段开始
+
+---
+
+## 4. 基于真实代码的阶段总览
+
+| 阶段 | v1 口径 | 当前真实状态 | 说明 |
+| --- | --- | --- | --- |
+| Phase 0 | 边界冻结 | `DONE` | 文档、候选模块、边界口径已经成形，但性能基线更多还是文档定义，不是完整观测系统 |
+| Phase 1 | Rust Web 基础层 | `PARTIAL` | `mnote-web` 已创建，`axum` 骨架已存在，sidebar kernel route 也已接到真实 query plan，但远不是主流量入口 |
+| Phase 2 | 文档阅读页 server-first 化 | `PARTIAL` 接近 `DONE` | 阅读态/编辑态已明显分离，但仍有旧链回退和大量客户端状态集中在 `DocumentContent` |
+| Phase 3 | Sidebar / 树结构 Rust 化 | `PARTIAL` 偏早期 | 主 Sidebar 已以 `kernelSidebarTree` 作为主树来源，但整体仍是超大客户端组件 |
+| Phase 4 | 搜索 Rust 化与 island 化 | `PARTIAL` | host/runtime 懒加载拆分已做，结果形状也开始带 `nodeId` / `subtreeRootId` / `evidence`，但仍未完成 server-first 搜索页 |
+| Phase 5 | AI 面板 bridge island 化 | `PARTIAL` | host/runtime 拆分已做，且已开始把 `node` / `subtree` / `outline` / `evidence` 送入 Hermes，但 runtime 仍重，协议也未统一到真正“最小壳” |
+| Phase 6 | Mindmap 独立对象化 | `PARTIAL` | 独立页脱离 editor stub 主入口，并补出 `standalone` / `documentBridge` 边界，但仍是客户端重壳 |
+| Phase 7 | BlockNote 孤岛化 | `PARTIAL` | 阅读态已直接消费 `pageSubtree`，编辑器按需挂载，但外围 drawer/panel 仍集中在同一内容组件 |
+| Phase 8 | 旧前端壳下线 | `NOT_STARTED` | 当前主入口仍是 Next/React，不能宣称主路径切换完成 |
+
+---
+
+## 5. Phase 0：基线与边界冻结
+
+**当前状态：`DONE`**
+
+### 5.1 已有事实
+
+- [x] 已有长期架构文档
+- [x] 已有长期 checklist 文档
+- [x] 已有 `tree-first graph kernel` 文档
+- [x] 已对文档页、Sidebar、Search、AI、Mindmap、OnlyOffice、`BlockNote` 做了模块级边界识别
+
+### 5.2 当前仍不足的地方
+
+- [ ] 真正可自动回归的性能基线系统仍未建立
+- [ ] 统一 performance trace 采样点仍未进入运行时
+- [ ] “冻结旧壳继续膨胀”目前更多靠文档与人工约束，不是代码级 guardrail
+
+### 5.3 v2 完成判定
+
+- [x] 设计层边界冻结已完成
+- [ ] 运行时观测层冻结仍未完成
+
+---
+
+## 6. Phase 1：Rust Web 基础层落地
+
+**当前状态：`PARTIAL`**
+
+### 6.1 已落地事实
+
+- [x] Rust workspace 已并入 `mnote-web`
+  - [Cargo.toml](/mnt/Data1T/mnote/rust/Cargo.toml)
+- [x] 已存在 `axum` Web 骨架
+  - [Cargo.toml](/mnt/Data1T/mnote/rust/crates/mnote-web/Cargo.toml)
+- [x] 已有统一 app/router 骨架
+  - [app.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/app.rs)
+  - [mod.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/mod.rs)
+- [x] 已有 request context / middleware
+  - [context.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/context.rs)
+  - [request_context.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/middleware/request_context.rs)
+- [x] 已有最小 Hermes bridge route
+  - [hermes.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes.rs)
+- [x] 已有 SSE / WS / compat route 骨架
+- [x] kernel sidebar route 已通过 `sidebar.dataset.list` runtime plan + `execute_sidebar_dataset_query(...)` 读取数据集
+  - [kernel.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/kernel.rs)
+
+### 6.2 明确还没完成
+
+- [ ] `mnote-web` 还不是主 Web 服务入口
+- [ ] 还没有主页面壳 SSR
+- [ ] 还没有主 API 大面积从 Next route 切到 Rust Web
+- [ ] 当前 `compat_next_base_path` 仍说明它主要还是兼容层，不是主承载层
+- [ ] `MNOTE_WEB_KERNEL_SIDEBAR_FIXTURE_JSON` fixture fallback 仍然存在，不能把当前接缝写成正式主链
+- [ ] 还不能说“后续页面迁移已不依赖 Next API route 作为唯一入口”，只能说“已经开始脱钩”
+
+### 6.3 v2 后续任务
+
+- [ ] 把 `mnote-web` 从 skeleton 提升为真实服务入口
+- [ ] 先把 sidebar kernel route 上的 fixture fallback 收到测试/开发边界，再承接一条真实页面壳或真实查询主链
+- [ ] 明确 Next -> Rust Web 的流量切换边界
+- [ ] 增加主 API / 页面壳级集成验证，而不只是 `cargo check`
+
+---
+
+## 7. Phase 2：文档阅读页 server-first 化
+
+**当前状态：`PARTIAL`，但已经是最实的进展之一**
+
+### 7.1 已落地事实
+
+- [x] 文档页已在服务端预取 `meta + content`
+  - [page.tsx](/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/documents/[id]/page.tsx)
+- [x] `DocumentShell` 已去掉 mounted gating
+  - [document-shell.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-shell.tsx)
+- [x] `DocumentReadView` 已作为阅读态渲染器落地
+  - [document-read-view.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-read-view.tsx)
+- [x] `DocumentContent` 已有 `isEditing` / `keepEditorMounted`
+  - [document-content.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx)
+- [x] `BlockNoteEditor` 已不是默认唯一入口
+
+### 7.2 当前还没完成
+
+- [ ] 服务端读链失败时仍回退旧链
+- [ ] 阅读态与编辑态虽已分开，但大量页面状态仍集中在 `DocumentContent`
+- [ ] 评论、历史、回链、AI、页面选项虽然不是首屏阻塞，但仍在同一组件层集中管理
+- [ ] 阅读页还不是一个真正极薄的 server-first 页面壳
+
+### 7.3 v2 完成判定
+
+- [x] “先阅读、后编辑”的主行为已经出现
+- [ ] “阅读页已经彻底轻壳化”还不能成立
+
+---
+
+## 8. Phase 3：Sidebar / 页面树 / 文件树 Rust 化与 island 化
+
+**当前状态：`PARTIAL` 偏早期**
+
+### 8.1 已落地事实
+
+- [x] Sidebar 数据 query 契约此前已经有 Rust 化前进
+- [x] 布局服务端会先加载 `sidebarInitialData`
+  - [layout.tsx](/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/layout.tsx)
+- [x] `sidebar-data.ts` 已生成 `kernel_sidebar_projection` 与 `kernelSidebarTree`
+  - [sidebar-data.ts](/mnt/Data1T/mnote/wolai-frontend/src/lib/sidebar-data.ts)
+- [x] 主 Sidebar 已以 `sidebarData.kernelSidebarTree` 作为初始树与同步来源
+  - [sidebar.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/sidebar.tsx)
+
+### 8.2 当前真实问题
+
+- [ ] `Sidebar` 仍然是超大客户端组件
+  - [sidebar.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/sidebar.tsx)
+- [ ] 页面树 / 文件树仍主要在客户端组装与交互
+- [ ] `buildDocumentTree(...)` 等旧拼树 helper 仍残留在 `move-embed-picker-dialog.tsx`、`lib/documents.ts` 等兼容场景
+- [ ] 主布局仍然默认常驻挂载 Sidebar
+- [ ] 还不能叫“服务端输出 + 局部 island”，现在更像“服务端首包 + 超大客户端壳”
+
+### 8.3 v2 后续任务
+
+- [ ] 先拆 Sidebar 自身为 host / runtime 或分片 island
+- [ ] 把树结构首包与交互态严格分层
+- [ ] 把主 Sidebar 之外的 page tree、file tree、embed/move picker 也统一切到 kernel projection
+- [ ] 把局部刷新协议显式化
+- [ ] 给 Sidebar 建立真正的切页重渲染基线
+
+---
+
+## 9. Phase 4：搜索系统 Rust 化与 island 化
+
+**当前状态：`PARTIAL`**
+
+### 9.1 已落地事实
+
+- [x] `SearchPalette` 已收口为轻量 host
+  - [search-palette.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/search/search-palette.tsx)
+- [x] 搜索 runtime 已按需动态加载
+  - [SearchPaletteHost.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/search/SearchPaletteHost.tsx)
+  - [search-palette.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/search/search-palette.runtime.tsx)
+- [x] 搜索结果契约已开始带 `nodeId` / `subtreeRootId` / `evidence`
+  - [search-query-adapter.ts](/mnt/Data1T/mnote/wolai-frontend/src/lib/search/search-query-adapter.ts)
+  - [search.ts](/mnt/Data1T/mnote/wolai-frontend/src/types/search.ts)
+
+### 9.2 当前还没完成
+
+- [ ] 主布局仍然默认挂载搜索 host
+- [ ] 搜索仍主要是纯前端 runtime
+- [ ] 没有真正的 server-first 搜索页
+- [ ] 没有看到搜索 UI 直接接入 Rust Web 页面壳
+- [ ] 结果形状虽已开始 kernel-aware，但检索真相层仍不是 Rust Web / kernel 真正主链
+- [ ] 不能宣称“搜索系统 Rust 化”已完成，只能说“搜索 UI 体量开始拆分，结果契约开始收口”
+
+### 9.3 v2 后续任务
+
+- [ ] 把搜索页与浮层分开
+- [ ] 先建立服务端搜索结果页壳
+- [ ] 让 host 只保留热键与打开逻辑
+- [ ] 减少全局常驻 store 对搜索的依赖
+- [ ] 把 `nodeId` / `subtreeRootId` / `evidence` 结果形状继续推进到更真实的 Rust/kernel 检索主链
+
+---
+
+## 10. Phase 5：AI 面板进一步收口为纯桥接 island
+
+**当前状态：`PARTIAL`**
+
+### 10.1 已落地事实
+
+- [x] 文档页 AI 已拆为 host + runtime
+  - [DocumentAiAgentPanel.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.tsx)
+  - [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx)
+- [x] Mindmap / OnlyOffice 也有类似 runtime 拆分
+- [x] `GlobalAiAgentHost` 已不在 `(app)/layout.tsx` 主布局中挂载
+- [x] 文档页 AI 已开始把 `node` / `subtree` / `outline` / `evidence` 传给 Hermes bridge
+  - [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx)
+  - [route.ts](/mnt/Data1T/mnote/wolai-frontend/src/app/api/ai-agent/run/route.ts)
+
+### 10.2 当前还没完成
+
+- [ ] runtime 组件仍然非常重
+- [ ] “最小会话协议、统一流式协议、页面上下文协议”还更多体现在组件内部，不是系统级协议层
+- [ ] 还不能说 AI 面板已经变成“纯桥接壳”
+- [ ] 页面级 AI adapter 仍然很大，只是改成了懒加载
+- [ ] AI 已能消费 `node` / `subtree` / `outline` / `evidence` 上下文，但还不是统一的 kernel-first tool 协议
+
+### 10.3 v2 后续任务
+
+- [ ] 继续下沉 runtime 内状态与协议
+- [ ] 把会话、tool event、client action 收口到共享协议层
+- [ ] 让 runtime 再减重，而不只是拆文件
+- [ ] 把当前上下文注入进一步收口为更稳定的 kernel node / subtree / edge bridge
+
+---
+
+## 11. Phase 6：Mindmap 独立对象化与独立页面化
+
+**当前状态：`PARTIAL`**
+
+### 11.1 已落地事实
+
+- [x] Rust 侧已有 Mindmap 对象协议与操作
+- [x] 独立页已先在服务端抓 initial projection，再交给客户端页面壳
+- [x] 独立页已直接使用 `StandaloneMindmapView`
+  - [page.tsx](/mnt/Data1T/mnote/wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx)
+- [x] 旧 `editorStub` 依赖已经不在独立页入口上
+- [x] `MindmapBlock.tsx` 中已有 `standalone` / `documentBridge` 边界
+  - [MindmapBlock.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx)
+- [x] 文档内嵌导图已默认走 preview-first 入口
+
+### 11.2 当前还没完成
+
+- [ ] 独立导图页仍是客户端页面，不是独立对象页壳
+- [ ] 仍然直接复用同一个重前端组件
+- [ ] 文档内嵌导图虽然已经 preview-first，但进入编辑/沉浸态后仍复用同一套重组件
+- [ ] Mindmap 还没有脱离“重交互前端壳优先”的事实
+- [ ] 导图数据真相仍未通过 kernel subtree / command 形成稳定主链
+
+### 11.3 v2 后续任务
+
+- [ ] 把独立导图页壳和导图操作壳分离
+- [ ] 让文档内嵌导图先变成轻预览/轻入口
+- [ ] 继续把对象真相留在 Rust，而不是留在前端组件状态
+
+---
+
+## 12. Phase 7：文档编辑态与 BlockNote 孤岛化
+
+**当前状态：`PARTIAL`**
+
+### 12.1 已落地事实
+
+- [x] `DocumentContent` 已存在阅读态/编辑态切换
+- [x] `BlockNoteEditor` 已变成按需挂载
+- [x] `keepEditorMounted` 说明已开始按进入编辑态再保留编辑器
+  - [document-content.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx)
+- [x] 阅读态已直接消费 `pageSubtree`
+  - [document-content.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx)
+  - [document-read-view.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-read-view.tsx)
+
+### 12.2 当前还没完成
+
+- [ ] `DocumentContent` 仍然同时管理：
+  - `DocumentAiAgentPanel`
+  - `DocumentHistoryDrawer`
+  - `DocumentCommentsDrawer`
+  - `PageBacklinksPanel`
+  - `PageOptionsSidebar`
+- [ ] `pageSubtree` 当前仍在前端内容层生成和消费，不是更薄的 Rust/kernel 输出边界
+- [ ] 搜索/AI/阅读态虽然开始共享 `node` / `subtree` / `outline` / `evidence` 口径，但还没有回到统一的 kernel projection / subtree 真相协议面
+- [ ] 这说明外围能力虽然不再阻塞首屏，但仍未真正完全从编辑器宿主层拆开
+- [ ] `BlockNote` 还不能算“完全孤岛化”，只能算“默认不再首屏强挂”
+
+### 12.3 v2 后续任务
+
+- [ ] 把外围 drawer/panel 再次拆层
+- [ ] 让编辑宿主只负责编辑
+- [ ] 让阅读宿主只负责阅读
+- [ ] 把 `pageSubtree` 的生成与消费继续下沉到更稳定的 server/kernel 边界
+
+---
+
+## 13. Phase 8：旧前端壳下线与兼容清理
+
+**当前状态：`NOT_STARTED`**
+
+### 13.1 直接证据
+
+- [x] 当前主应用入口仍是 Next App Router
+  - [layout.tsx](/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/layout.tsx)
+- [x] 当前主文档页仍是 Next 页面
+  - [page.tsx](/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/documents/[id]/page.tsx)
+- [x] 当前主搜索、主 Sidebar、主 Mindmap 页都仍在旧前端壳内
+
+### 13.2 因此不能成立的说法
+
+- [ ] “Rust Web 主路径切换已完成”
+- [ ] “双栈收缩已完成”
+- [ ] “旧 Next/React 页面壳已清理”
+
+### 13.3 v2 后续任务
+
+- [ ] 先定义哪条真实流量先切到 `mnote-web`
+- [ ] 先建立一条真实主路径，而不是只有 compat bridge
+- [ ] 等真正有主路径后，再谈 Phase 8 清理
+
+---
+
+## 14. 与 task-059 ~ task-069 的关系重定义
+
+这组任务不应再被理解成：
+
+- “长期 Phase 0 ~ 8 已全部完成”
+
+更准确的理解应是：
+
+- `task-059` ~ `task-061`
+  - 主要完成了长期路线的**设计与口径定义**
+- `task-062`
+  - 完成了 `mnote-web` 的**最小骨架落地**
+- `task-063`
+  - 完成了文档阅读态分离的**核心第一步**
+- `task-064`
+  - 只证明 Sidebar 主树已出现 kernel projection 消费接缝，不代表 Sidebar 重构完成
+- `task-065`
+  - 只证明搜索运行时开始拆重，不代表搜索系统完成 server-first 重构
+- `task-066`
+  - 只证明 AI host/runtime 拆分，不代表最小协议壳已经完成
+- `task-067`
+  - 只证明独立导图页切走 editor stub 主入口，并补出 `standalone` / `documentBridge` 边界，不代表 Mindmap 独立对象页完成
+- `task-068`
+  - 只证明 BlockNote 默认首屏强挂已解除，不代表完整孤岛化完成
+- `task-069`
+  - 只能算“统一回写了阶段口径”，不能算“Phase 8 真完成”
+
+---
+
+## 15. v2 推荐执行顺序
+
+如果从真实代码继续往前推进，建议顺序改成：
+
+1. `Phase 1` 继续做实
+   - 先让 `mnote-web` 承接一条真实页面壳或真实查询主链
+2. `Phase 2` 收尾
+   - 把文档阅读页进一步轻壳化
+3. `Phase 3`
+   - 先打 Sidebar 本体，而不是继续写“已完成”
+4. `Phase 4` / `Phase 5`
+   - 继续减 Search / AI runtime 重量
+5. `Phase 6`
+   - 让 Mindmap 真正从“重前端壳”中继续独立
+6. `Phase 7`
+   - 再拆 `DocumentContent` 外围面板
+7. 最后才进入 `Phase 8`
+
+---
+
+## 16. 最终结论
+
+当前未提交代码的真实含义是：
+
+> **长期架构方向是对的，且已经开始进入真实代码；但 59-69 当前被标记为 `completed` 的口径明显偏乐观。**
+
+更准确的结论应是：
+
+- `Phase 0`：基本完成
+- `Phase 1`：已开始，骨架已落
+- `Phase 2`：已明显落地，但未完全收尾
+- `Phase 3`：仍远未完成
+- `Phase 4`：只完成轻量拆分
+- `Phase 5`：只完成轻量拆分
+- `Phase 6`：只完成独立页去耦第一步
+- `Phase 7`：只完成阅读/编辑分离第一步
+- `Phase 8`：尚未开始
+
+因此，从当前实际代码出发，接下来最需要的不是继续宣布完成，而是：
+
+> **把 v1 的“愿景式 checklist”，改成 v2 的“基于真实代码状态的 checklist”，并据此重排后续 harness 任务状态。**

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` 和旧壳退场。**