docs: 继续收口设计稿状态与主线口径

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

@@ -3,7 +3,7 @@
 > 更新时间：2026-04-22
 >
 > 状态说明：
-> - 本稿已被 `/mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v2.md` 覆盖
+> - 本稿已被 `/mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v2.md` 覆盖
 > - 保留在 `design/old/` 仅作为上一轮判断稿与历史参考，不再作为当前执行口径
 >
 > 当前主线依据：

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

@@ -0,0 +1,807 @@
+# 7 [process][recycle] mnote Kernel Phase 7 AI 编排与 Kernel Projection 实施计划 v2
+
+> 更新时间：2026-04-22
+>
+> 状态说明：
+> - 本稿记录的是 `openai-agents-python` 作为过渡主链时期的 `Phase 7` 执行口径
+> - 当前长期方向已被 `/mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md` 覆盖
+> - 因此本稿迁入 `design/old/`，仅保留为历史过渡基线
+>
+> 当前主线依据：
+> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+> - `/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/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
+> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-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`
+>
+> 本稿与 `v1` 的关系：
+> - `/mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v1.md` 已降级为上一轮判断稿
+> - 当前如要真正执行 `Phase 7`，应以本 `v2` 为执行口径
+>
+> 当前状态补充：
+> - `/mnt/Data1T/mnote/design/07-ai/done/7-1-phase7-document-ai-minimum-loop-checklist-v1.md` 对应的“文档页 AI 最小闭环”已完成
+> - 但本 `v2` 的后续阶段，尤其 `summary node / ai_note node / reference edge / kernel index` 仍未完成，因此本稿继续保留在 `process/`
+> - 2026-04-23 验证补充：
+>   - `cd /mnt/Data1T/mnote/wolai-backend && ./.venv/bin/python -m pytest -q tests/test_ai_document_agent.py` -> `15 passed`
+>   - `cd /mnt/Data1T/mnote/wolai-frontend && pnpm test -- --runInBand src/app/api/ai-agent/run/route.test.ts src/app/api/ai-agent/document/config/route.test.ts src/components/editor/DocumentAiAgentPanel.runtime.test.tsx src/components/ai-agent/panelShared.test.ts` -> `202 passed`
+> - 2026-05-05 口径修正：
+>   - 本稿记录的 `openai-agents-python` 文档页主链收口，当前仅作为过渡阶段基线
+>   - 长期方向已被 `/mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md` 覆盖
+>   - 当前长期口径固定为：`mnote-cli` 是唯一长期 agent 执行面；`openai-agents-python`、Hermes、Codex 都视为可插拔外置 agent
+
+---
+
+## 1. 文档目的
+
+这份 `v2` 只做一件事：
+
+> **把 `Phase 7` 从“抽象地谈 AI 最终形态”改写成“能接在当前 page aggregate / tree command / realtime 主线之后执行的现实方案”。**
+
+当前不再适合继续直接沿用 `v1` 的原因，不是方向完全错了，而是：
+
+- `v1` 更像长期判断稿
+- 它对当前真实工具面、命令面、依赖顺序仍然写得过于理想化
+- 它没有充分吸收 `Page Aggregate` 这几天已经形成的收口事实
+
+因此本稿要解决的不是“要不要做 Phase 7”，而是：
+
+1. 如果现在开始做 `Phase 7`，第一交付物到底是什么
+2. `Phase 7` 应该接在哪条现有主线之后，而不是另起一套理想结构
+3. 过渡期 `openai-agents-python` 适配链到底如何接入当前文档页 AI 主链
+4. 哪些 `v1` 里的目标继续保留，哪些必须降级到后续阶段
+
+一句话收口：
+
+> **`Phase 7` 当前第一目标不是“做完整 AI 平台”，而是让文档页 AI 先沿着 `page aggregate command family` 进入主编辑区正式主链。**
+
+---
+
+## 2. 当前结论
+
+当前推荐口径固定如下：
+
+> **本稿原始判断是“Rust kernel / Rust runtime 做唯一事实源与真执行面，`openai-agents-python` 作为 `mnote` 专用编排层，`Hermes` 退回过渡与实验平台”。**
+>
+> **该判断现已退化为历史过渡口径；当前长期口径改为：`Rust kernel / Rust runtime` 做唯一事实源与真执行面，`mnote-cli` 做唯一长期 agent 执行面，`openai-agents-python` 与 `Hermes` 都作为可插拔外置 agent。**
+
+但如果按真实执行顺序来排，当前 `Phase 7` 必须服从下面这个前置条件：
+
+1. `Page Aggregate` 继续作为文档页真相收口主线
+2. `tree command cutover` 继续作为页面生命周期正式命名面主线
+3. `tree realtime event stream` 继续作为工作区树实时主线
+4. `Phase 7` 只在这三条主线已形成可接入的最小面之后，切入文档页 AI 最小闭环
+
+因此当前不能把 `Phase 7` 表述成：
+
+- 先做一套完整 AI 产品平台
+- 先把所有 AI 工具都切到全新命名
+- 先把 `summary node / ai_note node / reference edge / kernel index` 全部一口气打通
+
+当前正确表述应是：
+
+> **`Phase 7` 的第一闭环，是“文档页 AI 读取 page aggregate 上下文，并通过 `page.head.updateTitle / page.body.save / tree.*` 正式命令面回写主编辑区”。**
+
+---
+
+## 3. 当前真实基线
+
+`v2` 必须建立在当前已经真实成立的代码事实之上。
+
+### 3.1 文档页主编辑器已经切到正式 island
+
+当前默认主编辑区已经是页面内 `leptos-tiptap` island，不再是 `iframe bridge`，`BlockNote` 只保留为 fallback / 对照链。
+
+这意味着 `Phase 7` 的文档页 AI 主写链，默认目标已经不是旧编辑器壳，而是当前正式主编辑区。
+
+### 3.2 文档页已经开始消费统一 page aggregate
+
+当前文档页首屏与客户端补拉已经围绕 `PageAggregateProjection` 收口，页面本地状态也开始收口到统一 client aggregate state。
+
+这意味着：
+
+- AI 上下文已经不必继续只围绕零散 `title / content / options / pageSubtree` getter 组织
+- 文档页 AI 可以以 page aggregate snapshot 作为第一上下文来源
+
+### 3.3 页面命令面已经开始收口到 `page.*`
+
+当前前端与 route 执行面已经开始统一到下面三组页面命令：
+
+- `page.head.updateTitle`
+- `page.layout.updateOptions`
+- `page.body.save`
+
+这组命令面已经成为文档页 AI 后续接入的第一正式写入口。
+
+这也是本稿与 `v1` 的关键差异之一：
+
+> **`Phase 7` 第一阶段不再直接凭空引入一套全新的 `editor.*` 产品命名面，而是优先挂接已经开始收口的 `page aggregate command family`。**
+
+### 3.4 树域命令面正在切到 `tree.*`
+
+当前页面新建、重命名、移动、归档、恢复、嵌入等生命周期命令，长期正式命名已固定为：
+
+- `tree.node.create`
+- `tree.node.rename`
+- `tree.subtree.move`
+- `tree.node.archive`
+- `tree.node.restore`
+- `tree.node.purge`
+- `tree.node.embed`
+- `tree.subtree.copy`
+
+这意味着：
+
+- AI 若需要跨页面生命周期操作，不应继续以 `documents.*` 作为长期契约
+- 但 `Phase 7` 第一闭环仍以当前页正文编写为先，不先扩大全树操作面
+
+### 3.5 当前 AI runtime 仍以 Hermes 兼容桥为主
+
+当前文档页 AI 面板仍主要通过 `Hermes bridge` 工作，前端默认工具面仍以这些运行时工具为主：
+
+- `slash_run`
+- `doc_get`
+- `doc_find`
+- `doc_insert_blocks`
+- `doc_replace_range`
+- `docs_search`
+- `docs_read`
+- `image_read`
+
+并且当前结构化结果恢复，明确只对以下文档页写工具做了正式回接：
+
+- `slash_run`
+- `doc_insert_blocks`
+- `doc_replace_range`
+
+这意味着当前现实不是：
+
+- 已有一套完整 `mnote-native` agent 编排层
+
+而是：
+
+- 已有一个可工作的文档页 AI 过渡链
+- 这条链已经开始向 `page aggregate command family` 回接
+- `Phase 7` 的第一任务，应是把这条链从 Hermes 兼容桥收口到统一 `mnote-cli` host / adapter；`openai-agents-python`、Hermes、Codex 只作为可插拔外置 agent
+
+---
+
+## 4. 为什么 `v1` 不能直接当执行稿
+
+`v1` 里最需要修正的不是方向，而是以下四个执行偏差。
+
+### 4.1 工具命名过于理想化
+
+`v1` 直接把第一批工具写成：
+
+- `editor.insert_block_after`
+- `editor.replace_block`
+- `editor.delete_block`
+- `kernel.summary.create`
+- `kernel.ai_note.create`
+
+这在长期上未必错，但它跳过了当前已经开始成形的两层真实命名：
+
+- 页面命令面：`page.head.* / page.layout.* / page.body.*`
+- 树域命令面：`tree.*`
+
+如果现在按 `v1` 直接执行，容易在现有 `page.*` / `tree.*` 之外，再长出第三套 AI 专用命名面。
+
+### 4.2 没有明确把 Phase 7 锚定到 Page Aggregate
+
+`v1` 虽然提到了 `Page Aggregate`，但没有把它明确设为 `Phase 7` 的第一依赖。
+
+而当前真实主线已经很明确：
+
+> **文档页 AI 若不先对齐 `Page Aggregate`，后面很容易再次绕回“前端局部快照 + 兼容副作用链”的旧路。**
+
+### 4.3 第一阶段战线铺得过宽
+
+`v1` 把下面这些目标放得过于靠前：
+
+- `summary node`
+- `ai_note node`
+- `reference edge`
+- `PDF / Book -> kernel index`
+
+这些目标仍然重要，但当前如果要先做 `Phase 7`，第一交付物不应是它们。
+
+当前第一交付物应是：
+
+> **文档页 AI 直接编写主编辑区，人审核后应用，且整个过程沿 `page aggregate` 正式命令面回写。**
+
+### 4.4 没有充分吸收当前 Hermes 兼容桥已形成的过渡事实
+
+当前已经存在一条可运行的 Hermes 文档页 AI 过渡链，且它已经开始把结果恢复成：
+
+- `page.body.save` 语义
+- `page.head.updateTitle` 语义
+
+所以 `Phase 7` 的正确做法不是假装这条链不存在，而是：
+
+1. 明确它是过渡链
+2. 冻结它的保留边界
+3. 用 `mnote-cli` 统一承接长期 agent 执行面，而不是把 `openai-agents-python` 或 Hermes 继续写成长期主编排
+
+---
+
+## 5. 架构边界冻结
+
+### 5.1 长期推荐结构
+
+```text
+Document Page / Read View / AI Panel
+        |
+        v
+AI Gateway / SSE Event Adapter
+        |
+        +---- long-term execution surface: mnote-cli
+        |          |
+        |          +---- external agent adapter: openai-agents-python
+        |          +---- external agent adapter: Hermes
+        |          +---- external agent adapter: Codex
+        |
+        +---- current fallback: Hermes bridge
+        |
+        v
+Rust runtime / mnote-web / bridge-runtime
+        |
+        +---- page aggregate command family
+        |       - page.head.updateTitle
+        |       - page.layout.updateOptions
+        |       - page.body.save
+        |
+        +---- tree command family
+        |       - tree.node.*
+        |       - tree.subtree.*
+        |
+        v
+Rust kernel truth
+```
+
+### 5.2 各层职责
+
+#### Rust kernel / Rust runtime
+
+负责：
+
+- 对象真相
+- projection / query / command
+- page aggregate 命令面
+- tree command 命令面
+- 审计、trace、失败回放与回滚基线
+
+不负责：
+
+- 通用 agent 编排框架
+- 通用聊天产品壳
+
+#### `mnote-cli`
+
+负责：
+
+- 文档页 AI 会话编排
+- 外置 agent adapter 调度
+- mnote page tools / tree tools 统一入口
+- CLI host / Web AI host 之间的执行契约
+
+不负责：
+
+- 保存产品真相
+- 绕过 Rust runtime 直接写产品数据
+- 自己持有第二套页面真相
+
+#### `openai-agents-python`
+
+负责：
+
+- 作为可插拔外置 agent adapter / 对照实现
+- tools / handoffs / tracing / guardrails / HITL
+- 调用 OpenAI `Responses API`
+- 通过 `mnote-cli` 暴露的工具合同接入 `mnote`
+
+不负责：
+
+- 保存产品真相
+- 绕过 Rust runtime 直接写产品数据
+- 自己持有第二套页面真相
+- 文档页 AI 长期默认主编排
+
+#### Hermes
+
+负责：
+
+- 过渡期 fallback
+- 回归对照
+- 试验非主链场景
+
+不负责：
+
+- 文档页 AI 长期主编排
+- 产品正式工具契约
+
+#### 前端 AI Host / Panel
+
+负责：
+
+- 会话 UI
+- 流式事件渲染
+- 审核与应用入口
+- 挂接当前页面的 page aggregate snapshot
+- 展示当前页面 AI 的正式配置真源与运行时能力面
+
+不负责：
+
+- 私下拼出第二份页面真相
+- 私下定义长期 AI 工具协议
+- 私下持有 `profile` 真源
+- 私下硬编码一份长期工具注册表
+
+### 5.3 页面 AI 配置真源冻结
+
+当前页面 AI 的配置真源，必须额外冻结为下面三层。
+
+#### 模型层：前端保存 `model_key`，不保存底层 provider model
+
+页面 AI 的模型配置真源，不应是：
+
+- `slow / fast / codex` 这类 combo 内部路由名
+- `ju/gpt-5.4` 这类底层 provider model id
+
+页面 AI 应保存的是**产品层可识别的 `model_key`**，例如：
+
+- `gpt-5.4`
+- `gpt-5.4-mini`
+- `gpt-5.3-codex`
+- `gemini-3.1-pro-preview`
+- `third`
+
+其长期原则固定如下：
+
+- `model_key` 是前端设置与产品语义真源
+- `resolved_combo` 是运行时解析结果，例如 `slow / fast / codex`
+- `resolved_runtime_model` 是最终底层节点 / provider model，仅用于调试、trace 与排障
+
+也就是说：
+
+> **页面 AI 配置真源固定为 `model_key -> resolved_combo -> resolved_runtime_model`，而不是直接把 combo 名或底层 provider model 暴露成产品配置键。**
+
+#### 设定层：前端可设 `profile`，后端持有真源
+
+当前 `Soul / Profile` 的正确落点不是前端自由文本壳，也不是 `openai-agents-python` 自己的长期真相层，而是：
+
+- 前端可以选择与查看 `profile`
+- 后端持有正式 `profile registry`
+- 编排层把 `profile` 编译成最终 instructions / policy / defaults
+
+固定原则如下：
+
+- 前端只提交 `profileId`
+- `profile` 内容、版本、默认值、升级策略由后端持有
+- 前端可显示 profile 说明、用途、默认工具集、session 策略
+- 不允许前端静态硬编码出第二份长期 `profile` 真相
+
+#### 工具层：工具注册表必须前端可见
+
+当前页面 AI 的正式工具面，不允许只在后端注册、前端不可见。
+
+必须固定为：
+
+- 后端持有正式 tool registry
+- 前端设置页可以看见当前 scope 已注册工具
+- 工具显示至少包含：
+  - `name`
+  - `description`
+  - `scope`
+  - `read/write`
+  - `status`
+  - `version`（如有）
+
+这样后续若新增 `mindmap`、阅读态、搜索态等工具，前端设置页会直接反映真实能力面，而不是继续依赖人工记忆。
+
+---
+
+## 6. `Phase 7` 的当前目标重写
+
+本稿把 `Phase 7` 当前目标重写为两层。
+
+### 6.1 第一层目标：文档页 AI 最小闭环
+
+这是当前必须优先完成的唯一第一闭环。
+
+完成口径如下：
+
+- AI 读取当前文档页 page aggregate 上下文
+- AI 能对当前页正文执行插入、改写、重命名
+- AI 回写沿正式 `page aggregate command family`
+- 主编辑区 island 能正式回显结果
+- 人可以作为审核者决定是否应用或继续编辑
+- 人可以在页面 AI 设置中看见当前 `model_key / profile / tool registry` 的正式状态
+
+一句话说：
+
+> **先让 AI 真正进入当前页主编辑区主链，而不是先做大而全的 AI 能力矩阵。**
+
+### 6.2 第二层目标：结构化知识写链
+
+下面这些目标保留，但降到文档页最小闭环之后：
+
+- `summary node`
+- `ai_note node`
+- `reference edge`
+- `PDF / Book -> kernel index`
+
+它们属于 `Phase 7` 的后续扩展，不再作为第一交付物。
+
+---
+
+## 7. 第一闭环的冻结验收口径
+
+当前如要宣称 `Phase 7` 进入执行，应只以以下验收口径作为第一阶段成功标准。
+
+### 7.1 读侧
+
+AI 至少能稳定拿到：
+
+- `documentId`
+- 当前页 `blocks`
+- 当前页 `pageSubtree`
+- `pageOptions`
+- `editorRuntimePageOptions`
+- 必要时的 `outline / evidence`
+
+说明：
+
+- 当前不要求所有上下文都来自 Rust 原生 `Page Aggregate route`
+- 允许过渡期继续使用当前文档页已经收口出的 page aggregate loader 与 client aggregate snapshot
+- 但不再允许继续围绕零散页面壳对象拼装新的 AI 私有上下文
+
+### 7.2 写侧
+
+AI 第一批正式写能力只冻结为：
+
+- 当前页标题改名
+- 当前页正文插入
+- 当前页正文改写
+
+其长期命令语义分别锚定为：
+
+- 标题改名 -> `page.head.updateTitle`
+- 正文插入 / 改写 -> `page.body.save`
+
+说明：
+
+- 过渡期运行时仍可继续通过 `slash_run / doc_insert_blocks / doc_replace_range` 承接
+- 但这些运行时工具必须被视为过渡工具，不得继续上升为长期产品契约
+
+### 7.3 审核侧
+
+当前文档页 AI 的产品定位固定为：
+
+> **AI 直接接入主编辑区编写，人负责审核、继续编辑、确认结果。**
+
+因此第一闭环里必须明确：
+
+- AI 输出不是单纯聊天文本
+- AI 输出必须能映射到页面正式写链
+- 人能在主编辑区中继续接手与修订
+
+### 7.4 不在第一闭环内的项
+
+当前不纳入第一闭环：
+
+- 页面设置类 AI 写工具
+- 跨页大规模树操作
+- mindmap AI 主链
+- PDF / Book 结构化摄取
+- `summary node / ai_note node / reference edge`
+
+### 7.5 配置侧
+
+第一闭环内，页面 AI 的配置面至少要有可冻结的正式口径：
+
+- 模型真源为 `model_key`
+- `resolved_combo / resolved_runtime_model` 只作为运行时调试信息
+- `profile` 前端可设，但由后端 registry 持有真源
+- 当前 scope 的 tool registry 必须前端可见
+
+说明：
+
+- 第一闭环不要求一开始就做完整 AI 设置产品壳
+- 但必须把“谁是配置真源、哪些信息必须可见”冻结下来
+- 否则后续模型、profile、工具会继续散落在前端本地状态、后端环境变量和隐式注册代码里
+
+---
+
+## 8. 正式工具面与过渡工具面的双层口径
+
+为避免混乱，本稿把工具合同拆成两层。
+
+### 8.1 长期正式命令面
+
+这是产品长期应围绕的正式语义面：
+
+#### 页面命令面
+
+- `page.head.updateTitle`
+- `page.layout.updateOptions`
+- `page.body.save`
+
+#### 树域命令面
+
+- `tree.node.create`
+- `tree.node.rename`
+- `tree.node.archive`
+- `tree.node.restore`
+- `tree.node.purge`
+- `tree.node.embed`
+- `tree.subtree.move`
+- `tree.subtree.copy`
+
+### 8.2 过渡运行时工具面
+
+这是当前 Hermes 兼容链与 bridge-runtime 已经真实承接的工具面：
+
+- `slash_run`
+- `doc_get`
+- `doc_find`
+- `doc_insert_blocks`
+- `doc_replace_range`
+- `docs_search`
+- `docs_read`
+- `image_read`
+
+固定原则如下：
+
+> **`Phase 7` 不删除过渡工具面，但也不把过渡工具名继续写成长期产品契约。**
+
+### 8.3 外置 agent adapter 的接入原则
+
+`openai-agents-python`、Hermes、Codex 作为外置 adapter 接入时，优先接的不是抽象理想工具名，而是 `mnote-cli` 暴露的统一工具契约：
+
+1. 当前页最小闭环所需的正式命令语义
+2. 当前已真实存在的过渡运行时工具能力
+3. 两者之间的明确映射关系
+
+也就是说：
+
+- 对外长期文档写正式命令语义
+- 对内迁移期允许 adapter 调用当前 bridge-runtime 能跑通的过渡工具
+
+### 8.4 工具注册表可见原则
+
+文档页 AI 长期不能只做到“后端注册工具”，还必须做到“前端能看见当前真正注册了哪些工具”。
+
+因此冻结如下：
+
+1. 后端需要提供正式能力面 / 注册表接口
+2. 前端页面 AI 设置页默认展示当前 scope 的真实工具注册表
+3. 前端手动工具选择只允许在真实注册工具集合内进行
+4. 新增 `mindmap`、阅读态、搜索态工具时，必须同步进入注册表可见面
+
+一句话收口：
+
+> **工具不是隐藏在编排层里的实现细节，而是页面 AI 产品能力面的一部分。**
+
+---
+
+## 9. 分阶段实施计划
+
+## 阶段 0：冻结 `Phase 7` 依赖关系
+
+### 目标
+
+明确 `Phase 7` 是文档页主线的下一层，而不是脱离 `Page Aggregate` 单独启动的平行工程。
+
+### 需要完成
+
+- [x] 明确 `Phase 7` 第一依赖是 `5-6 Phase J`
+- [x] 明确当前第一闭环只覆盖文档页 AI 主写链
+- [x] 明确 `summary / ai_note / reference / index` 降为后续扩展
+- [x] 明确 `Hermes` 只保留为 fallback / 对照链
+- [x] 明确 `openai-agents-python` 仅作为过渡期可插拔外置 agent / adapter 示例
+- [x] 明确页面 AI 模型配置真源是 `model_key`，不是 combo 名或 provider model
+- [x] 明确 `profile` 前端可设、后端持有真源
+- [x] 明确 tool registry 必须前端可见
+
+### 完成判定
+
+- [ ] 团队口径统一为“先文档页最小闭环，再扩结构化知识写链”
+- [ ] 团队口径统一为“`model_key / profile / tool registry` 都有正式真源，不再散落在隐式实现里”
+
+---
+
+## 阶段 1：冻结文档页 AI 正式语义面
+
+### 目标
+
+先把文档页 AI 到底面向哪一组正式语义面写清楚。
+
+### 需要完成
+
+- [x] 冻结当前页 AI 写入第一批正式动作：
+  - 改标题
+  - 插入正文
+  - 改写正文
+- [x] 冻结这些动作对应的长期正式命令语义：
+  - `page.head.updateTitle`
+  - `page.body.save`
+- [x] 冻结树域相关动作的长期正式命令语义为 `tree.*`
+- [x] 写清 `过渡工具面 -> 正式命令面` 的映射关系
+- [x] 禁止新增第三套 AI 专用产品命名面
+- [x] 冻结页面 AI 模型配置真源为 `model_key`
+- [x] 冻结 `model_key -> resolved_combo -> resolved_runtime_model` 的分层关系
+- [x] 冻结 `profile` 前端可设、后端 registry 持有真源
+- [x] 冻结当前 scope tool registry 必须前端可见
+
+### 完成判定
+
+- [x] 文档页 AI 已有一套与 `page aggregate command family` 对齐的稳定语义面
+- [x] 文档页 AI 已有一套与 `model_key / profile / tool registry` 对齐的稳定配置语义面
+
+---
+
+## 阶段 2：冻结文档页 AI 上下文装配
+
+### 目标
+
+让 AI 输入上下文显式锚定到 page aggregate，而不是继续围绕零散页面壳字段。
+
+### 需要完成
+
+- [x] 固定当前页 AI 最小上下文字段：
+  - `documentId`
+  - `blocks`
+  - `pageSubtree`
+  - `pageOptions`
+  - `editorRuntimePageOptions`
+  - `outline`
+  - `evidence`
+- [x] 明确上下文优先级：
+  - page aggregate snapshot
+  - page subtree / outline / evidence
+  - 必要的兼容页面壳快照
+- [x] 不再继续扩散新的 AI 私有页面 getter
+- [x] 为 AI 会话定义上下文裁剪规则
+
+### 完成判定
+
+- [x] 文档页 AI 读侧可以被明确描述为“消费 page aggregate 上下文”
+
+---
+
+## 阶段 3：整理并保留 `openai-agents-python` 过渡适配链
+
+### 目标
+
+在不推翻现有文档页 AI 回写链的前提下，保留 `openai-agents-python` 这条已跑通的过渡外置 adapter，用它作为 `mnote-cli`-first 迁移期间的对照与行为基线，而不是把它定义成长期默认文档页编排层。
+
+### 需要完成
+
+- [x] 建立独立的 `mnote-ai-orchestrator` Python 服务或 sidecar
+- [x] 接入 OpenAI `Responses API`
+- [x] 先只注册文档页第一闭环所需工具
+- [ ] 打通 session / tracing / guardrails / HITL 最小能力
+- [x] 对齐当前前端 SSE 协议，或提供新的稳定 event adapter
+- [x] 前端 provider 切换具备 `Hermes fallback`
+- [x] 建立页面 AI capability/config route，至少返回：
+  - `model_key` 列表
+  - 默认 `profile`
+  - 当前 scope tool registry
+  - `resolved_combo / resolved_runtime_model` 调试字段
+- [x] 让 online provider 也能稳定进入正式 session 模式，而不只是在 codex provider 下启用
+
+### 完成判定
+
+- [x] 在不依赖 Hermes 主编排的情况下，文档页 AI 已能跑通第一闭环
+- [x] 当前过渡 adapter 已具备“模型 / profile / 工具”统一能力面出口
+
+---
+
+## 阶段 4：切文档页 AI 默认执行路径
+
+### 目标
+
+让文档页 AI 在产品可见行为上从 Hermes 兼容链过渡到 `mnote-cli` host / adapter；当前已跑通的 `openai-agents-python` 链只保留为外置 adapter 行为基线。
+
+### 需要完成
+
+- [x] 历史基线中，文档页 AI panel 曾默认走 `openai-agents-python`
+- [x] 长期口径中，文档页 AI panel 默认应走 `mnote-cli` host / adapter
+- [x] 标题改名沿 `page.head.updateTitle` 回写
+- [x] 正文改写沿 `page.body.save` 回写
+- [x] 主编辑区 island 稳定回显 AI 结果
+- [x] 审核与继续编辑行为维持在主编辑区内完成
+- [x] Hermes 仅保留 fallback 开关
+- [x] 页面 AI 设置页显示正式 `model_key` 下拉，而不是自由文本底层 model
+- [x] 页面 AI 设置页显示当前 `profile`
+- [x] 页面 AI 设置页显示当前 scope 已注册工具列表
+- [x] 页面 AI 设置页显示当前 `resolved_combo / resolved_runtime_model` 作为调试信息，而不是产品主键
+
+### 完成判定
+
+- [x] 可以明确说“AI 已正式进入当前页主编辑区主链”
+- [x] 可以明确说“页面 AI 的模型 / 设定 / 工具状态对用户是可见且可解释的”
+
+---
+
+## 阶段 5：扩展结构化知识写链
+
+### 目标
+
+在文档页最小闭环稳定后，再向更完整的 `Phase 7` 目标扩展。
+
+### 需要完成
+
+- [ ] `summary node`
+- [ ] `ai_note node`
+- [ ] `reference edge`
+- [ ] `PDF / Book -> kernel index`
+- [ ] 对这些写链补齐 trace / audit / rollback / evidence
+
+### 完成判定
+
+- [ ] `Phase 7` 才能开始被描述为“进入结构化知识写链阶段”
+
+---
+
+## 10. Hermes 的过渡策略重写
+
+当前不建议立刻删除 Hermes，但必须缩边界。
+
+### 10.1 继续保留的价值
+
+- 承接现有文档页 AI 运行链
+- 作为 `mnote-cli` host 与其他外置 adapter 的回归对照
+- 作为 fallback 开关
+- 承接非主链实验场景
+
+### 10.2 明确禁止的事情
+
+- 不让 Hermes 成为文档页长期主编排
+- 不让 Hermes memory 取代 page aggregate / kernel-aware retrieval
+- 不让 Hermes 工具名继续成为长期产品契约
+- 不让 Hermes 默认 shell/fs 能力绕过 Rust runtime 写业务数据
+
+### 10.3 最终可接受状态
+
+最终可接受状态有两种：
+
+1. Hermes 退化为非主链实验平台 / 外置 agent adapter
+2. Hermes 完全下线，只保留 `mnote-cli` + Rust runtime，并按需接入 `openai-agents-python` / Codex 等外置 agent adapter
+
+---
+
+## 11. 非目标
+
+本稿当前不覆盖：
+
+- 完整 AI 平台产品化
+- 完整 suggestion review 产品壳
+- 多平台消息网关
+- 通用桌面 agent / shell agent
+- mindmap AI 主线
+- OnlyOffice AI 主线
+- 完整长期记忆产品壳
+
+这些都不是当前 `Phase 7` 的第一任务。
+
+---
+
+## 12. 当前冻结口径
+
+当前冻结如下：
+
+> **本稿原始判断里，`openai-agents-python` 曾被写成长期推荐编排层；该口径现已失效。当前长期口径应以 `v4` 为准：`mnote-cli` 是唯一长期 agent 执行面，Rust runtime 仍是唯一事实源与真执行面；`openai-agents-python`、Hermes、Codex 都只是可插拔外置 agent。**
+
+> **但当前 `Phase 7` 的第一交付物不再定义为“完整 AI 平台”或“完整结构化知识写链”，而是“文档页 AI 直接进入主编辑区，并沿 `page aggregate command family` 正式回写”。**
+
+> **`Hermes` 可以继续作为过渡平台与实验平台存在，但不再作为文档页 AI 的长期语义中心。`openai-agents-python` 也只保留为外置 adapter。**
+
+> **页面 AI 的模型真源固定为 `model_key`，`resolved_combo / resolved_runtime_model` 只作为运行时调试信息；`profile` 前端可设但由后端持有真源；tool registry 必须前端可见。**
+
+一句话收口：
+
+> **当前如要先做 `Phase 7`，正确起点不是继续抽象谈 kernel-aware AI，而是先让 AI 真正沿 `page aggregate -> 主编辑区 island` 这条当前主线闭环。**

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

@@ -0,0 +1,339 @@
+# 7 [process][recycle] mnote Kernel Phase 7 AI 与 CLI 外置 Agent 边界实施方案 v3
+
+> 更新时间：2026-05-05
+>
+> 上位依据：
+> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+> - `/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/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-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/07-ai/done/7-1-phase7-document-ai-minimum-loop-checklist-v1.md`
+> - `/mnt/Data1T/mnote/design/old/07-ai/process/7-phase7-ai-kernel-projection-plan-v2.md`
+>
+> 本稿与 `v2` 的关系：
+> - `v2` 记录的是文档页 AI 最小闭环与 `openai-agents-python` sidecar 的主线收口
+> - 本稿记录的是从“双中心并存”过渡到 `CLI-first` 之前的边界判断，重点保留当时为何要把页面内 AI 与外置 agent 拆层
+> - 若未来继续演进，长期口径以 `v4` 为准；本稿不再作为当前长期判断依据
+>
+> 2026-05-05 追加说明：
+> - 本稿已被 `/mnt/Data1T/mnote/design/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md` 覆盖
+> - `v3` 只保留用于记录“双中心并存”的过渡判断
+> - 当前长期口径不再采用本稿，而采用 `v4` 的 `CLI-first`
+> - 当前统一口径是：`mnote-cli` 是唯一长期 agent 执行面，`openai-agents-python`、Hermes、Codex 都只是可插拔外置 agent
+
+---
+
+## 1. 文档目的
+
+这份稿只回答一个问题：
+
+> **`mnote` 的 AI 能力到底应该以“内置 agent”为中心，还是以“CLI 兼容外置 agent”为中心。**
+
+当前长期结论已被 `v4` 修正为单一执行面：
+
+1. Web 文档页 AI 面板继续保留，但只作为页面内交互壳 / CLI host
+2. `mnote-cli` 是唯一长期 agent 执行面
+3. Hermes、Codex、`openai-agents-python` 这类外置 agent 不再直接依赖产品内编排细节，而是统一通过 CLI / 稳定工具面进入系统
+4. Rust kernel 继续作为唯一事实源与真执行面
+
+一句话收口：
+
+> **本稿原始判断是“不要退回成只有 CLI”；该口径现已被 `v4` 覆盖。当前长期口径是：CLI 作为唯一执行面，Web AI 只保留为页面内交互壳。**
+
+---
+
+## 2. 当前完成情况
+
+### 2.1 文档页 AI 最小闭环已完成
+
+`7-1` 已经完成，说明当前文档页 AI 至少已经跑通：
+
+- 当前页 page aggregate 上下文读取
+- `openai-agents-python` sidecar 编排
+- 标题改名与正文写回
+- `Hermes` fallback / 对照链
+- `model_key / profile / tool registry` 的可见配置面
+
+这意味着当前系统已经不是“要不要有 AI”，而是“AI 的长期边界该放在哪一层”。
+
+### 2.2 `mnote-cli` 已经不是空壳
+
+当前 Rust 侧已有 `mnote-cli`，并且已经覆盖：
+
+- `page`
+- `block`
+- `mindmap`
+- `search`
+- `sidebar`
+- `editor`
+- `tool`
+
+同时它已经有较清晰的执行参数面：
+
+- `--json`
+- `--execute`
+- `--session-id`
+- `--reason`
+- `--idempotency-key`
+- `--validate-only`
+- `--dry-run`
+
+这说明 CLI 已经具备成为“外置 agent 统一兼容层”的基础，而不是只做调试壳。
+
+### 2.3 内置 AI 现在的定位已经足够清晰
+
+当前 `wolai-backend/app/services/ai_document_agent.py` 这一层已经把文档页 AI 约束成：
+
+- 只处理当前文档页
+- 只使用有限工具面
+- 通过 page aggregate 组织上下文
+- 通过 `slash_run / doc_insert_blocks / doc_replace_range` 这类写链回写
+
+所以内置 AI 的价值不是“全能 agent 平台”，而是“产品内即时编辑体验”。
+
+---
+
+## 3. 核心判断
+
+### 3.1 `v3` 当时对 CLI-first 的顾虑
+
+本节保留的是 `v3` 当时尚未接受 `CLI-first` 时的顾虑：
+
+1. 担心产品内即时体验变差
+2. 担心页面上下文、审核、回写被拆散
+3. 担心外置 agent 变强但产品主链变弱
+
+这些顾虑在 `v4` 中的处理方式不是退回“双中心”，而是明确：
+
+- Web AI 面板继续保留
+- 但它只作为 `mnote-cli` 的页面内 host / client
+- 执行面不再由产品内 AI 单独持有
+
+### 3.2 也不建议把内置 AI 变成唯一中心
+
+相反，如果继续把内置 AI 当唯一中心，另一个问题会变得更严重：
+
+- agent 更新能力受限
+- 记忆层容易变成产品私有状态
+- 能力面会偏向单一页面操作
+- Hermes / CLI 这类外置 agent 很难稳定接入
+
+所以正确做法不是“只保留内置 AI”，而是**把 `mnote-cli` 收口为唯一长期 agent 执行面**。
+
+### 3.3 当前长期分层应理解为三层
+
+1. **Web AI 面板 / 页面内交互壳**
+   - 负责文档页内交互、上下文读取、局部回写、审核辅助
+
+2. **`mnote-cli`**
+   - 负责唯一长期 agent 执行面，以及外置 agent、脚本、批处理、离线任务、可观测执行
+
+3. **Rust kernel**
+   - 负责所有事实源、命令、查询、投影、审计与回放
+
+这三层之间不应该互相抢语义中心。
+
+---
+
+## 4. 架构边界
+
+### 4.1 Rust kernel
+
+负责：
+
+- 页面、树、边、投影、查询、命令
+- 结构化写入的最终事实源
+- 审计、trace、回放、恢复
+
+不负责：
+
+- 直接承担 UI 体验
+- 直接承担通用 agent 编排
+
+### 4.2 Web AI 面板（产品内交互壳）
+
+负责：
+
+- 当前文档页的即时编辑
+- 选中上下文的解释与改写
+- 通过正式命令面回写
+- 审核与继续编辑的体验闭环
+
+不负责：
+
+- 成为全局 agent 平台
+- 取代 CLI 的批处理入口
+- 持有独立长期记忆真源
+- 成为第二个长期执行面
+
+### 4.3 `mnote-cli`
+
+负责：
+
+- 作为唯一长期 agent 执行面与统一命令面
+- 作为人类与脚本的可执行入口
+- 作为 Hermes、Codex、批处理、定时任务的兼容层
+
+应该提供：
+
+- 稳定的 JSON 输出
+- 明确的 plan / execute 分层
+- 会话与 trace 参数
+- 幂等键
+- 校验模式与 dry-run
+- 可发现的 capability manifest
+
+### 4.4 Hermes / Codex / `openai-agents-python`
+
+负责：
+
+- 可插拔外置 agent 场景
+- 过渡平台
+- 回归对照
+
+不负责：
+
+- 成为产品内部独立长期主编排
+- 直接绕过 Rust runtime 写业务数据
+
+---
+
+## 5. CLI 应该补什么
+
+### 5.1 统一能力发现
+
+CLI 需要先变成“可发现能力集合”，而不是一堆散命令。
+
+最少要能回答：
+
+- 当前可写什么
+- 当前可读什么
+- 当前哪些命令是计划态
+- 当前哪些命令可直接执行
+- 当前命令属于哪个 scope
+
+### 5.2 统一执行元数据
+
+外置 agent 真正缺的不是命令本身，而是执行元数据一致：
+
+- `session_id`
+- `actor_id`
+- `actor_type`
+- `reason`
+- `idempotency_key`
+- `validate_only`
+- `dry_run`
+- trace / audit id
+
+这些都应该在 CLI 层成为一等参数。
+
+### 5.3 统一记忆入口
+
+这里的“记忆”不应该是产品壳里的隐式状态，而应该拆成三层：
+
+1. 会话记忆
+   - 某次 agent 运行的上下文与结果
+
+2. 配置记忆
+   - profile、工具注册、运行时偏好
+
+3. kernel 记忆
+   - 真实业务对象、projection、历史变更
+
+CLI 负责把这三层显式化，外置 agent 通过它读取或写入，不再自己猜。
+
+### 5.4 统一机器可读输出
+
+如果 Hermes、Codex、脚本都要接入，CLI 输出必须稳定机器可读。
+
+最低要求：
+
+- `--json` 必须完整
+- 错误结构必须稳定
+- 成功结构必须能直接喂给上层 agent
+- 人类输出和机器输出要分开
+
+---
+
+## 6. Web AI 面板继续保留什么
+
+### 6.1 继续保留
+
+- 当前页正文改写
+- 当前页标题改名
+- 当前页上下文读取
+- 页面内审核与继续编辑
+- 与 page aggregate 对齐的最小闭环
+
+### 6.2 不继续扩写
+
+- 通用多 agent 平台壳
+- 全局记忆产品壳
+- 独立于页面主链的第二份真相
+- 把 CLI 功能重复做一遍
+
+### 6.3 设计原则
+
+Web AI 面板只做“最近的一层”，不要做“全部层”。
+
+因为页面内 AI 交互壳的目标是让用户快，不是让系统像一个独立平台那样完整。
+
+---
+
+## 7. 迁移策略
+
+### 阶段 1：收口 CLI 兼容面
+
+- 把 `mnote-cli` 明确成唯一长期 agent 执行面
+- 保持现有命令树不乱长
+- 先统一 JSON / plan / execute / trace / idempotency
+
+### 阶段 2：补稳定能力发现
+
+- 输出 capability manifest
+- 区分 read / write / job
+- 区分 document / tree / workspace scope
+
+### 阶段 3：外置 agent 接入
+
+- Hermes 通过 CLI 进入系统
+- 后续其他 agent 也通过同一 CLI 进入
+- 不再为每个 agent 单独做一套产品内桥接逻辑
+
+### 阶段 4：保留页面内 AI host
+
+- 文档页 AI 继续保留当前页面内主路径
+- 只做 UI 内最小闭环
+- 不回退到全局壳
+- 不再把页面内 host 叙述成独立长期执行面
+
+---
+
+## 8. 非目标
+
+本稿不做：
+
+- 重新实现一个新的通用 AI 平台
+- 把 Hermes 直接升级成产品内主编排中心
+- 把内置 AI 删除掉
+- 把所有页面内交互体验都删除并强制改成手工 CLI 操作
+- 在 CLI 里重复一套产品 UI
+
+---
+
+## 9. 完成判定
+
+当下面几项成立时，才算这个方向真正站稳：
+
+- `mnote-cli` 是唯一长期 agent 执行面，而不是纯调试壳
+- Web AI 面板只负责页面内最小闭环
+- `openai-agents-python`、Hermes、Codex 等外置 agent 通过 CLI 进入系统
+- Rust kernel 仍然是唯一事实源
+- `model_key / profile / tool registry` 这些产品语义不被页面内 host 私有化
+
+一句话收口：
+
+> **本稿保留的是“产品内 AI + CLI 兼容层”并存的过渡判断；当前长期口径已经改为：`mnote-cli` 是唯一执行面，Web AI 只是页面内交互壳，Rust kernel 继续负责真相。**