对齐 Wolai 侧栏体验并收拢设计入库

2026-04-30 16:18:54 +08:00
parent 8c895b3dc0
commit afb2a5b8a0
89 changed files with 23188 additions and 84 deletions
@@ -0,0 +1,538 @@
+# 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` 与旧前端壳退场。**