mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v1.md

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

> 更新时间：2026-04-22
>
> 状态说明：
> - 本稿已被 `/mnt/Data1T/mnote/design/old/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/done/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](/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-1-tree-first-graph-kernel-checklist-v2.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)
> - [ai-first-rust-block-editor-baseline-v1.md](/mnt/Data1T/mnote/design/old/05-editor-mainline/process/ai-first-rust-block-editor-baseline-v1.md)
> - [rust-block-editor-ai-tool-contract-v0.md](/mnt/Data1T/mnote/design/old/05-editor-mainline/done/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` 视为唯一推进入口。

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

1. `Phase 7` 中 AI 子系统到底要落什么
2. 为什么当前更适合采用 `openai-agents-python` 做 `mnote` 专用编排层，而不是继续把 `Hermes` 当长期主线，也不是直接从零手写完整 agent 平台
3. Rust kernel / Rust runtime / OpenAI Agents / Hermes 各自的边界是什么
4. 如何分阶段把当前 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 长期推荐结构

```text
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` 中优先打通下面三条链：

1. 文档页 AI -> summary node / ai_note node / reference edge
2. 文档页 AI -> block editor Rust command
3. 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 最终状态

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

1. Hermes 退化为非主链实验平台
2. 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` 主链。**