lix/mnote

Files

T

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

2026-04-16 22:01:51 +08:00

17 KiB

Raw Blame History

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. 推荐执行顺序

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

完成 Kernel Phase 3 收尾
先打通 Kernel Phase 4
同步启动 Kernel Phase 5
再推进 Kernel Phase 6
再推进 Kernel Phase 7
最后才进入 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 和旧壳退场。

17 KiB Raw Blame History Unescape Escape

Tree-First Graph 内核实施清单 v2

1. 这版为什么要重写

2. 状态口径

DONE

PARTIAL

NOT_STARTED

3. 当前总判断

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

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

已落地

完成判定

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

已落地

已有能力

当前结论

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

已落地

当前结论

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

已落地

当前真实问题

下一阶段必须完成

完成判定

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

已落地

当前真实问题

下一阶段必须完成

完成判定

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

新口径

已落地

当前真实问题

下一阶段必须完成

完成判定

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

已落地

当前真实问题

下一阶段必须完成

完成判定

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

已落地

当前真实问题

下一阶段必须完成

完成判定

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

已落地

当前真实问题

下一阶段必须完成

完成判定

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

当前真实问题

下一阶段必须完成

完成判定

15. 推荐执行顺序

16. 最终结论

17 KiB

Raw Blame History

`DONE`

`PARTIAL`

`NOT_STARTED`