lix/mnote

Files

T

lix-2026 41e958769e feat: land page aggregate and phase7 document ai mainline

- 收口 page aggregate 读取、本地状态与命令客户端\n- 接入 phase7 document ai sidecar 与前端编排入口\n- 更新 architecture 与 design 状态迁移

2026-04-23 07:38:34 +08:00

16 KiB

Raw Blame History

7 [process][recycle] mnote Kernel Phase 7 AI 编排与 Kernel Projection 实施计划 v1

更新时间：2026-04-22

状态说明：

本稿已被 /mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v2.md 覆盖

保留在 design/old/ 仅作为上一轮判断稿与历史参考，不再作为当前执行口径

当前主线依据：

/mnt/Data1T/mnote/design/01-05-current-priority-overview.md

/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-rust-web-long-term-architecture-v1.md

/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md

/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md

/mnt/Data1T/mnote/design/04-tree-domain/process/4-6-tree-command-protocol-cutover-stage2-v1.md

/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md

历史参考：

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

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

ai-first-rust-block-editor-baseline-v1.md

rust-block-editor-ai-tool-contract-v0.md

1. 文档目的

本文用于冻结 mnote 在 Kernel Phase 7 中与 AI 相关的实施口径。

这里仍沿用 Phase 7 命名，是为了保留与旧阶段拆分的一致性；当前执行依据应以 design/01-05-current-priority-overview.md、3-rust-web-long-term-architecture-v1.md、5-5 / 5-6、4-6、3-3 这些仍在推进的主线文档为准，不再把 1-1 或 3-1 视为唯一推进入口。

这份计划只回答下面四件事：

Phase 7 中 AI 子系统到底要落什么
为什么当前更适合采用 openai-agents-python 做 mnote 专用编排层，而不是继续把 Hermes 当长期主线，也不是直接从零手写完整 agent 平台
Rust kernel / Rust runtime / OpenAI Agents / Hermes 各自的边界是什么
如何分阶段把当前 AI 面板切到真正的 kernel projection + kernel command 主链

一句话说：

在 Phase 7 中，AI 的核心任务不是“换一个聊天框架”，而是让 AI 真正直接面向 node / subtree / edge / editor command / kernel command 工作。

2. 对齐当前 AI 主线验收口径

当前 AI 主线的验收口径，应综合以下现行主线来理解：

tree-first graph kernel 的对象真相边界
Page Aggregate 对标题 / 正文 / 页面设置的单一真源收口
tree command cutover 对正式命令面的统一
tree realtime event stream 对 projection + delta 主链的统一

结合历史 Kernel Phase 7 清单中已经写明的目标，当前 AI 仍需满足下面这些验收要求：

AI tool 直接面向 node / subtree / edge
AI 不再默认面向“页面前端壳”
AI 能创建 summary node / ai_note node / reference edge
AI 能把 PDF / Book 解析结果落进 kernel index

因此本计划不把目标定义为：

再做一套前端 AI runtime
继续围绕页面对象和编辑器壳拼 prompt
继续把 Hermes 或某个 SDK 本身当事实中心

本计划把目标定义为：

让 AI 变成 kernel-aware 的业务执行者，而不是围绕旧页面壳工作的聊天插件。

3. 当前结论

当前推荐口径固定如下：

mnote 的长期主线应采用“Rust kernel / Rust runtime 做唯一事实源与真执行面，openai-agents-python 作为 mnote 专用 AI 编排层”的结构。Hermes 继续保留为过渡期外置 agent 平台或实验平台，但不再作为长期主链的语义中心。

再展开就是：

事实源：只有 Rust kernel 的 node / edge / subtree / projection / command
业务真执行面：只有 Rust runtime / Rust Web / Rust editor command
AI 编排层：优先采用 openai-agents-python
模型底座：优先采用 OpenAI Responses API
过渡平台：当前 Hermes 可继续承接已有会话、流式事件和部分工具桥接
浏览器前端：只保留 host / island / stream 渲染，不再承担主 AI 编排

一句话总结：

不是把 OpenAI Agents SDK 当事实源，而是把它当“比纯自建更省力、比 Hermes 更可塑”的编排层。

4. 为什么这次主线更适合 `openai-agents-python`

4.1 不是从零手写整套 agent 平台

如果纯自建，就必须自己补：

agent run loop
session/history
tool orchestration
tracing
guardrails
handoff
human in the loop

这条路线长期最干净，但在 Phase 7 并不是最优先的工作。

Phase 7 更应该把时间投到：

kernel-aware context assembly
Rust tool contract
summary / ai_note / reference edge 写链
PDF / Book -> kernel index 写链
阅读页与 AI 共用 pageSubtree / outline / evidence

因此当前不值得先把 agent 平台从头再造一遍。

4.2 也不继续把 Hermes 当长期主线

Hermes 的优势很明显：

skills
memory
cron
gateway
多后端模型
现成 agent 平台能力

但对 mnote 来说，它的问题也很明确：

它是通用 agent 平台，不是 mnote-native AI 架构
它自己的 memory / search / skill 体系，容易和 kernel-aware retrieval 冲突
它自己的工具心智模型，不适合作为 node / subtree / edge / command 的长期事实入口
它更适合做外置大脑壳，不适合做产品内核

所以当前口径不是“彻底弃用 Hermes”，而是：

让 Hermes 退回到过渡平台与实验平台的位置。

4.3 `openai-agents-python` 正好卡在中间层

openai-agents-python 当前已经提供：

agent primitives
tools
handoffs
guardrails
sessions
tracing
human in the loop
sandbox agents

这意味着：

不必从零重写 agent orchestration
也不必接受 Hermes 整个平台的产品壳
可以把 mnote 自己的 Rust tools / kernel retrieval / audit 规则深度塞进去

这条路线更符合当前项目的长期方向：

AI-first
CLI-first
Rust-native
工具直达 Rust command
UI 只剩薄壳

5. 架构边界冻结

5.1 长期推荐结构

UI Host / AI Panel / Document Read View
        |
        v
AI Gateway / Stream Adapter
        |
        v
openai-agents-python Orchestrator
        |
        +---- provider: OpenAI Responses API
        |
        +---- mnote tools:
        |       - kernel.node.*
        |       - kernel.subtree.*
        |       - kernel.edge.*
        |       - editor.command.*
        |       - search.kernel_aware.*
        |       - import_export.*
        |
        v
Rust runtime / mnote-web / bridge-runtime
        |
        v
Rust kernel truth

5.2 每层职责

Rust kernel / Rust runtime

负责：

统一对象真相
projection/query/command
editor command
audit / rollback / policy
summary node / ai_note node / reference edge / kernel index 的真写链

不负责：

多 agent handoff 框架
通用聊天 session UI
通用 agent 记忆产品壳

`openai-agents-python` 编排层

负责：

prompt / instructions / tool routing
session orchestration
tracing / guardrails
handoff / background agent / HITL
与 OpenAI Responses API 的 agent 级编排

不负责：

定义产品事实源
保存 mnote 的结构真相
直接写产品数据库
绕过 Rust runtime 调产品数据

Hermes

负责：

过渡期运行现有链路
保留实验平台和已有运营场景
提供短期 fallback

不负责：

长期 AI 主线语义中心
Phase 7 的最终实现基线

6. Phase 7 中 AI 的实施目标

本计划只覆盖 Phase 7 所需 AI 主链，不扩展到完整长期 AI 平台。

6.1 目标一：AI 输入上下文改成 `kernel-aware`

AI 读取上下文不再默认基于：

页面前端对象
BlockNote 临时结构
页面壳里拼出来的二次真相

AI 输入上下文统一改成：

node
subtree
outline
evidence
edges
可选的 pageSubtree projection

6.2 目标二：AI 工具改成 Rust tool contract

第一批 AI tools 固定围绕下面几类：

kernel.node.get
kernel.subtree.get
kernel.edges.list
kernel.project_view
editor.insert_block_after
editor.replace_block
editor.delete_block
editor.move_block
editor.indent_block
editor.outdent_block
editor.toggle_heading_collapse
kernel.summary.create
kernel.ai_note.create
kernel.reference.attach
kernel.index.ingest_pdf
kernel.index.ingest_book

原则固定为：

AI 不操作 UI，不操作 DOM，不操作页面壳；AI 只操作 Rust 暴露出来的真工具面。

6.3 目标三：先打通三条主写链

Phase 7 中优先打通下面三条链：

文档页 AI -> summary node / ai_note node / reference edge
文档页 AI -> block editor Rust command
PDF / Book AI 解析 -> kernel index

6.4 目标四：阅读页与 AI 共用一套 projection 口径

阅读页与 AI 共用：

pageSubtree
outline
evidence
edges

这样阅读页与 AI 才能真正围绕同一套真相工作。

7. 分阶段实施计划

阶段 0：边界冻结与过渡口径确认

目标

把 AI 主线从“继续围绕 Hermes 与前端 runtime 打补丁”改成“为 Rust kernel 准备长期编排层”。

需要完成

冻结 Phase 7 的 AI 主线目标，不再把“继续增强前端 AI runtime”当主任务
明确 openai-agents-python 为当前推荐编排层
明确 Hermes 只保留为过渡 fallback / 实验平台
明确 Rust runtime 才是唯一真执行面
明确前端 AI host 只负责会话壳与流式渲染

完成判定

团队口径统一为“AI 编排层可替换，但 Rust truth layer 不可替换”

阶段 1：定义 `mnote` 专用 AI tool surface

目标

先把 AI 能做什么冻结成稳定工具合同。

需要完成

基于 node / subtree / edge / editor command 定义第一批 tool schema
为所有写工具补齐审计字段：
- actor
- target node ids / block ids
- command list
- trace id
- rollback token
把现有前端临时工具名收口到统一命名
区分：
- read tools
- write tools
- index tools
- retrieval tools
为 summary node / ai_note node / reference edge 定义稳定写协议

完成判定

mnote 已有一套不依赖前端 UI 的 AI 工具合同

阶段 2：做 `kernel-aware context assembly`

目标

让 AI 的输入上下文改成以 kernel projection 为主。

需要完成

把文档页 AI 上下文切到：
- node
- subtree
- outline
- evidence
- edges
明确上下文优先级：
- page subtree > outline > evidence > page shell snapshots
移除或降级旧页面对象快照在主链中的权重
为 AI 会话定义可重复的上下文裁剪规则
让阅读页与 AI 共用同一套 projection 获取接口

完成判定

AI 已经不再默认围绕旧页面壳工作

阶段 3：引入 `openai-agents-python` 编排层

目标

用官方 agent primitives 取代当前以 Hermes 为中心的长期编排口径，但不触碰 Rust truth layer。

需要完成

建立独立的 mnote-ai-orchestrator Python 服务或 sidecar
接入 OpenAI Responses API
把 mnote Rust tools 注册到 openai-agents-python
打通 session / tracing / guardrails / handoff 基础设施
对齐当前前端 SSE 协议或定义新的稳定 event adapter
明确前端如何在 Hermes / Agents Python 之间切换
保留 Hermes fallback 开关，便于过渡期回退

完成判定

在不依赖 Hermes 的情况下，AI 已能跑通至少一条 mnote-native 主链

阶段 4：打通三条主写链

目标

让 Phase 7 的 AI 写能力真正落到 kernel。

需要完成

AI -> summary node 写链
AI -> ai_note node 写链
AI -> reference edge 写链
AI -> Rust block editor command 写链
PDF / Book -> AI 结构化解析 -> kernel index 写链
对所有写操作补齐：
- trace
- audit
- target evidence
- rollback

完成判定

AI 能稳定创建 summary node / ai_note node / reference edge
AI 能把 PDF / Book 解析结果落进 kernel index

阶段 5：切文档页与阅读页主路径

目标

让 Phase 7 在产品可见行为上成立。

需要完成

文档页 AI 面板默认走 kernel-aware 上下文
阅读页大纲来自 kernel subtree
回链 / 引用 / 结构信息来自 kernel edge
AI 输出的结构节点能在阅读页中被稳定消费
至少保留一条兼容 fallback，但不再是默认主链

完成判定

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

8. Hermes 的过渡策略

当前不建议立刻删除 Hermes。

8.1 Hermes 在过渡期继续保留的价值

承接现有运行链
作为 agent 行为回归对照
作为短期 fallback
承接不属于 mnote-native 主链的实验场景

8.2 需要限制的边界

不让 Hermes 直接成为产品事实源
不让 Hermes memory 取代 kernel-aware retrieval
不让 Hermes 默认 shell/fs 能力直接改业务数据
不让 Hermes 工具名继续成为长期产品契约

8.3 最终状态

最终可接受的状态有两种：

Hermes 退化为非主链实验平台
Hermes 完全下线，只保留 openai-agents-python + Rust runtime

9. 非目标

这份计划当前不覆盖：

完整 AI suggestion review UI
完整协作评论体系
多平台消息网关
完整长期记忆产品壳
通用桌面 agent / shell agent 平台
把前端页面壳继续增强成 AI 主执行面

这些都不是 Phase 7 的核心目标。

10. 风险与取舍

风险一：`openai-agents-python` 仍然不是 Rust

这是现实限制，但当前可接受，因为它只做编排层，不做事实层。

风险二：Hermes 与新编排层会短期并存

这是过渡期复杂度，但能换来更平滑的切换与回退能力。

风险三：如果先把“agent 平台能力”做太重，会挤压 `Phase 7` 主任务

因此必须坚持：

Phase 7 先做 kernel-aware tools 与写链，不先做通用 AI 平台产品化。

11. 最终冻结口径

当前冻结如下：

Kernel Phase 7 的 AI 主任务，是把 AI 从“页面壳上的聊天插件”升级为“直接围绕 Rust kernel / Rust editor command 工作的业务执行者”。

当前推荐采用 openai-agents-python 作为 mnote 专用编排层，以减少从零自建 agent 平台的成本；同时继续让 Rust runtime 保持唯一事实源和真执行面。

Hermes 可以继续作为过渡平台与实验平台存在，但不再应作为长期主线的语义中心。

12. 对应当前 AI 主线的落地映射

本计划与历史 Kernel Phase 7 检查项以及当前主线收口目标的一一对应如下：

`Phase 7` 检查项	本计划对应
AI tool 直接面向 `node / subtree / edge`	阶段 1、阶段 2
AI 不再默认面向“页面前端壳”	阶段 2、阶段 5
AI 能创建 `summary node / ai_note node / reference edge`	阶段 1、阶段 4
AI 能把 PDF / Book 解析结果落进 `kernel index`	阶段 4
阅读页与 AI 至少有一条主路径直接消费 kernel projection	阶段 5

一句话收口：

如果这份计划执行完成，那么 Phase 7 中 AI 这一半就不再只是“接了个 agent”，而是第一次真正进入 tree-first graph kernel 主链。

16 KiB Raw Blame History

7 [process][recycle] mnote Kernel Phase 7 AI 编排与 Kernel Projection 实施计划 v1

1. 文档目的

2. 对齐当前 AI 主线验收口径

3. 当前结论

4. 为什么这次主线更适合 openai-agents-python

4.1 不是从零手写整套 agent 平台

4.2 也不继续把 Hermes 当长期主线

4.3 openai-agents-python 正好卡在中间层

5. 架构边界冻结

5.1 长期推荐结构

5.2 每层职责

Rust kernel / Rust runtime

openai-agents-python 编排层

Hermes

6. Phase 7 中 AI 的实施目标

6.1 目标一：AI 输入上下文改成 kernel-aware

6.2 目标二：AI 工具改成 Rust tool contract

6.3 目标三：先打通三条主写链

6.4 目标四：阅读页与 AI 共用一套 projection 口径

7. 分阶段实施计划

阶段 0：边界冻结与过渡口径确认

目标

需要完成

完成判定

阶段 1：定义 mnote 专用 AI tool surface

目标

需要完成

完成判定

阶段 2：做 kernel-aware context assembly

目标

需要完成

完成判定

阶段 3：引入 openai-agents-python 编排层

目标

需要完成

完成判定

阶段 4：打通三条主写链

目标

需要完成

完成判定

阶段 5：切文档页与阅读页主路径

目标

需要完成

完成判定

8. Hermes 的过渡策略

8.1 Hermes 在过渡期继续保留的价值

8.2 需要限制的边界

8.3 最终状态

9. 非目标

10. 风险与取舍

风险一：openai-agents-python 仍然不是 Rust

风险二：Hermes 与新编排层会短期并存

风险三：如果先把“agent 平台能力”做太重，会挤压 Phase 7 主任务

11. 最终冻结口径

12. 对应当前 AI 主线的落地映射

16 KiB

Raw Blame History

4. 为什么这次主线更适合 `openai-agents-python`

4.3 `openai-agents-python` 正好卡在中间层

`openai-agents-python` 编排层

6.1 目标一：AI 输入上下文改成 `kernel-aware`

阶段 1：定义 `mnote` 专用 AI tool surface

阶段 2：做 `kernel-aware context assembly`

阶段 3：引入 `openai-agents-python` 编排层

风险一：`openai-agents-python` 仍然不是 Rust

风险三：如果先把“agent 平台能力”做太重，会挤压 `Phase 7` 主任务