lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e1681331a3bbc04745469ce065aa58b2e95be641
mnote/design/old/01-tree-first-graph-kernel/process/tree-first-graph-kernel-checklist-v1.md
T

16 KiB
Raw Blame History

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. 新的总体验收定义

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

  • 已存在 Rust 主导的 kernel node / edge 真相层
  • 页面树、文件树、Mindmap、RAG 结构索引、AI 结构操作都开始直接依赖 kernel，而不是各有一套真相
  • Rust Web 层开始作为 kernel 的主 query / command / projection 承载层
  • 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 已有事实

5.3 仍需完成

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

5.4 完成判定

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

5.5 当前落地说明

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

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

当前状态：DONE

6.1 目标

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

6.2 实施清单

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

6.3 最小首批节点建议

  • workspace
  • folder
  • page
  • section
  • asset
  • book
  • pdf
  • mindmap_node
  • summary
  • ai_note
  • reference_anchor

6.4 最小首批边建议

  • parent_of
  • child_of
  • contains
  • references
  • backlinks_to
  • source_of
  • summarizes
  • indexes

6.5 完成判定

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

6.6 当前落地说明

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

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

当前状态：DONE

7.1 目标

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

7.2 实施清单

  • 定义 get_node
  • 定义 get_subtree
  • 定义 list_children
  • 定义 list_edges
  • 定义 traverse_graph
  • 定义 create_node
  • 定义 update_node
  • 定义 move_subtree
  • 定义 attach_edge
  • 定义 detach_edge
  • 定义 project_view

7.3 与当前已有能力的关系

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

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

但还没有：

  • 统一 kernel query / command 面

7.4 完成判定

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

7.5 当前落地说明

  • 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
  • 当前首条真实 projection 样板已选用 Sidebar 数据集，经 Rust runtime 统一输出 kernel subtree / projection 结果

8. Kernel Phase 3：Rust Web 接入 kernel

当前状态：DONE

8.1 目标

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

8.2 当前已有事实

  • mnote-web 骨架已存在
  • 已有 request context / SSE / WS / Hermes bridge skeleton

8.3 仍需完成

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

8.4 完成判定

  • mnote-web 已承接至少一条真实 kernel 主链

8.5 当前落地说明

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

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

当前状态：PARTIAL

9.1 目标

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

9.2 当前真实状态

  • Sidebar 有服务端首包
  • 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 完成判定

  • Sidebar / 页面树 / 文件树已经开始直接消费 kernel projection

9.5 当前落地说明

  • 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 当前基础

  • 搜索已有前端 runtime
  • Rust 有 FTS 与 Mindmap subtree 能力雏形
  • 已有 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 当前已有事实

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

11.3 仍需完成

  • 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 当前基础

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

12.5 完成判定

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

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

当前状态：NOT_STARTED

13.1 目标

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

13.2 当前已有事实

  • 文档页默认已不再直接强挂 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
    • 关注当前代码状态下的 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 与旧前端壳退场。

Reference in New Issue View Git Blame Copy Permalink