chore: 收口 review 执行清单与 runtime 验证

- 补齐 design/10-review 执行清单、验收标准与相关设计治理记录 - 迁移已完成的 tree、mindmap、runtime fallback、AI kernel 等设计和缺陷条目 - 推进 Rust Web runtime、tree/sidebar、page aggregate、mindmap 与 OnlyOffice 路由侧验证支撑 - 增加 task177-task180 smoke/audit 脚本及前端相关测试覆盖
2026-05-14 05:52:08 +08:00
parent b4a452a8b7
commit 96e03645f7
69 changed files with 4780 additions and 979 deletions
@@ -3,10 +3,11 @@
 > 状态说明：
 > - 本稿定义的 default gate 已在当前主线代码中成立：`mnote-web` 是 `3000` owner，Next 仅保留 legacy compat/debug 边界
 > - `MNOTE_WEB_ENABLE_LEGACY_NEXT_COMPAT` 默认关闭与 `task117` guard 已落地，故迁入 `done/`
+> - 2026-05-13 追加说明：本文中“长期 agent 执行面收口到 `mnote-cli`”是历史完成口径；当前 AI 长期方向已由 `design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md` 覆盖为 Hermes 页面内客户端 + mnote Hermes skill/plugin

 ## 目标

-将 Next App Router 从 3000 默认主链降级为显式 legacy/debug/internal 兼容边界。默认首页、文档页、搜索页、导图页、tree SSE 与 AI bridge host 均由 `mnote-web` 承接；长期 agent 执行面收口到 `mnote-cli`。
+将 Next App Router 从 3000 默认主链降级为显式 legacy/debug/internal 兼容边界。默认首页、文档页、搜索页、导图页、tree SSE 与 AI bridge host 均由 `mnote-web` 承接；AI 会话与编排长期归 Hermes，mnote 通过 Hermes skill/plugin 暴露业务工具。

 ## 当前 owner

@@ -15,7 +16,7 @@
 - `/search`：Rust Web `search::shell`，Search projection owner `rust-kernel`。
 - `/mindmap/{doc_id}/{mindmap_id}`：Rust Web `mindmap_shell::mindmap_object_shell`，Mindmap projection owner `rust-kernel`。
 - `/api/tree/events`：Rust Web SSE，stream owner `rust-web`。
- `/api/hermes/bridge`：Rust Web 兼容 AI bridge；仅作为过渡边界，不是长期 agent 执行面。
+- `/api/hermes/bridge`：Rust Web 兼容 AI bridge；仅作为过渡边界，不是新的 Hermes 页面内客户端代理。
 - `/api/compat/next/*`：legacy compat boundary，仅用于迁移期兼容与调试。

 ## Gate
@@ -23,12 +24,12 @@
 - `MNOTE_WEB_ENABLE_LEGACY_NEXT_COMPAT` 默认关闭；只有显式设置为 `1/true/yes` 才允许 fallback proxy。
 - 默认主路径不得返回 `x-mnote-legacy-upstream: next-app-router`。
 - 导图、搜索、文档页 contract 不得再把 `next-app-router` 声明为主 runtime。
- `/api/ai-agent/run` 当前仍保留兼容 route，但长期应降为 `mnote-cli` host / adapter，结构化写入必须经 Rust runtime，外置 agent 不得拥有第二执行面。
+- `/api/ai-agent/run` 当前仍保留兼容 route，但长期应退出页面 AI 主路径；新的页面 AI 应走 Hermes client proxy，结构化写入必须经 mnote Hermes plugin -> Rust runtime / kernel。

 ## 删除条件

 - 删除 `/api/compat/next/sidebar`：Sidebar、workspace shell、file tree smoke 均证明 Rust projection 可覆盖默认入口。
- 删除 `/api/compat/next/ai-agent/run`：AI 面板默认请求统一 CLI host，legacy 调用方清零；Hermes 仅保留为可插拔外置 agent。
+- 删除 `/api/compat/next/ai-agent/run`：AI 面板默认请求统一 Hermes client proxy，legacy 调用方清零；`mnote-cli` 只可作为 mnote plugin 内部适配器或调试入口。
 - 删除 fallback proxy：`task117` 默认关闭 legacy compat 后覆盖首页、文档页、搜索页、导图页与 tree SSE。

 ## 验收命令
@@ -1,4 +1,4 @@
-# 3-15 [process] Runtime Fallback 退场 Checklist v1
+# 3-15 [done] Runtime Fallback 退场 Checklist v1

 > 更新时间：2026-05-09
 >
@@ -9,7 +9,12 @@
 > - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-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/process/7-phase7-ai-kernel-projection-plan-v4.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md`
+>
+> 2026-05-13 口径修正：
+> - 本清单中“删除 `provider=hermes` 直连分支”的结论仍然有效，含义是旧 `/api/ai-agent/run` 不再把 Hermes 当 fallback/provider 分支。
+> - 新长期方向不是恢复旧 provider 分支，而是新增正式 Hermes 页面内客户端与 mnote Hermes skill/plugin。
+> - 因此“退场旧 direct Hermes fallback”和“页面 AI 长期调用 Hermes”不冲突。

 ## 1. 目标

@@ -59,14 +64,14 @@
 - [x] 把 `BlockNote` 从“系统默认可退回编辑器”降为 `recycle` 参考实现
 - [x] 活跃设计稿中不再把 `BlockNote` 写成系统 fallback，只允许写成历史对照链

-### 4.2 AI provider 直连分支
+### 4.2 旧 AI provider 直连分支

 - [x] 删除 Next `/api/ai-agent/run` 中 `provider=codex` 直连分支
 - [x] 删除 Next `/api/ai-agent/run` 中 `provider=hermes` 直连分支
 - [x] 删除 Rust `compat` 中代理到 legacy Next AI route 的优先分支
 - [x] 删除 Rust `compat` 中 direct Hermes 分支
 - [x] 删除 Rust `compat` 中 document AI orchestrator fallback 分支
- [x] 统一只保留 `mnote-cli` host 作为默认主执行入口
+- [x] 旧 `/api/ai-agent/run` 不再作为页面 AI 主执行入口；历史 `mnote-cli` host 只保留为兼容/内部适配，不再代表长期页面 AI 主线
 - [x] 次要 provider 请求改为明确失败，不再静默降级

 ### 4.3 legacy Next compat / alias / debug 壳
@@ -133,7 +138,7 @@
 ### 8.2 必须消失

 - [x] 默认运行时不再自动触发 `BlockNote` fallback
- [x] 默认 AI 运行时不再直连 `Hermes` / `Codex` / 旧 orchestrator compat
+- [x] 默认 AI 运行时不再通过旧 `/api/ai-agent/run` provider 分支直连 `Hermes` / `Codex` / 旧 orchestrator compat；新的 Hermes 页面内客户端应走正式 Hermes client proxy
 - [x] 默认 gateway 不再把 legacy Next 当作未迁路径的总兜底
 - [x] `/api/documents/page` 不再在 runtime 中组装 TS fallback projection

@@ -120,6 +120,8 @@

 ### 3.2 Hermes / AI tool registry 归属仍需继续收口

+2026-05-13 口径更新：本文记录的是 `3104` 退役阶段的历史边界判断，不再代表当前 AI 长期编排主线。当前 AI 长期方向已改为 Hermes 页面内客户端 + mnote Hermes skill/plugin；旧 `openai-agents-python` 编排层与旧 `/api/hermes/bridge` 只作为历史或兼容路径看待。
+
 当前前端 AI route 与后端 `openai-agents-python` 编排层已经不再通过 `MNOTE_WEB_BASE_URL` 回源 `mnote-web /api/hermes/bridge` 获取 runtime tool 结果，而是走后端 orchestration + 本地 `bridge-runtime`。

 这意味着：
@@ -302,12 +304,12 @@
 目标：

 - AI runtime tool bridge 不再强依赖 `MNOTE_WEB_BASE_URL`
- `openai-agents-python` 编排层与工具桥接边界收口到正式 AI 服务面
+- 历史 `openai-agents-python` 编排层不再被描述为长期 AI 服务面；新的正式边界是 Hermes client proxy + mnote Hermes plugin

 推荐方向：

- 由 `wolai-backend:8000` 持有 AI orchestration 正式入口
- Rust `bridge-runtime` 作为内核语义执行层
+- 由 Hermes 持有 session / run / tool event / usage / model 编排
+- Rust `bridge-runtime` 作为 mnote 业务语义执行层，经 Hermes skill/plugin 暴露
 - `3000` 只负责页面与同源 API 边界，不再额外绕回 `3104`

 当前状态：
@@ -47,7 +47,7 @@
 - [x] `Phase 2` 文档阅读态分离已经有实质代码
 - [x] `Phase 3` 主 Sidebar 已出现 `kernelSidebarTree` 消费接缝
 - [x] `Phase 4` 搜索已做 host/runtime 拆分，并开始返回 `nodeId` / `subtreeRootId` / `evidence`
- [x] `Phase 5` AI 面板已做 host/runtime 拆分，并开始向 AI bridge 传递 `node` / `subtree` / `outline` / `evidence`；长期执行面应收口到 `mnote-cli`，Web 只作为 CLI host / client，`openai-agents-python` / Hermes / Codex 只作为可插拔外置 agent
+- [x] `Phase 5` AI 面板已做 host/runtime 拆分，并开始向 AI bridge 传递 `node` / `subtree` / `outline` / `evidence`；2026-05-13 起长期方向改为 Hermes 页面内客户端 + mnote Hermes skill/plugin，旧 CLI host 只保留为历史/兼容证据
 - [x] `Phase 6` Mindmap 独立页已去掉 `editorStub` 主入口
 - [x] `Phase 7` 阅读态已直接消费 `pageSubtree`，`BlockNote` 也已不是文档页默认唯一入口

@@ -107,7 +107,7 @@
 | Phase 2 | 文档阅读页 server-first 化 | `PARTIAL` 接近 `DONE` | 阅读态/编辑态已明显分离，但仍有旧链回退和大量客户端状态集中在 `DocumentContent` |
 | Phase 3 | Sidebar / 树结构 Rust 化 | `PARTIAL` 偏早期 | 主 Sidebar 已以 `kernelSidebarTree` 作为主树来源，但整体仍是超大客户端组件 |
 | Phase 4 | 搜索 Rust 化与 island 化 | `PARTIAL` | host/runtime 懒加载拆分已做，结果形状也开始带 `nodeId` / `subtreeRootId` / `evidence`，但仍未完成 server-first 搜索页 |
-| Phase 5 | AI 面板 bridge island 化 | `PARTIAL` | host/runtime 拆分已做，且已开始把 `node` / `subtree` / `outline` / `evidence` 送入 AI bridge；长期执行统一落在 `mnote-cli`，Web 面板只做 host / adapter，但 runtime 仍重，协议也未统一到真正“最小壳” |
+| Phase 5 | AI 面板 Hermes client island 化 | `PARTIAL` | host/runtime 拆分已做，且已开始把 `node` / `subtree` / `outline` / `evidence` 送入 AI bridge；后续应把 Web 面板退成 Hermes 页面内客户端，把 mnote 能力注册为 Hermes skill/plugin，但 runtime 仍重，协议也未统一到 Hermes session/run/tool contract |
 | Phase 6 | Mindmap 独立对象化 | `PARTIAL` | 独立页脱离 editor stub 主入口，并补出 `standalone` / `documentBridge` 边界，但仍是客户端重壳 |
 | Phase 7 | BlockNote 孤岛化 | `PARTIAL` | 阅读态已直接消费 `pageSubtree`，编辑器按需挂载，但外围 drawer/panel 仍集中在同一内容组件 |
 | Phase 8 | 旧前端壳下线 | `PARTIAL` 接近 `DONE` | 3000 gateway / 文档 shell / tree realtime / Search / AI bridge / Mindmap object shell 已由 `mnote-web` 持有；Next App Router 降为 legacy compat / island bundle source，旧链彻底删除仍待后续 |
@@ -290,10 +290,15 @@

 ---

-## 10. Phase 5：AI 面板进一步收口为 `mnote-cli` host / 纯桥接 island
+## 10. Phase 5：AI 面板收口为 Hermes 页面内客户端 / mnote plugin bridge

 **当前状态：`PARTIAL`**

+> 2026-05-13 口径更新：
+> - 本阶段原先把页面 AI 继续收口为 `mnote-cli host / client`，现在已被 `design/07-ai/process/7-3-page-ai-hermes-panel-and-mnote-plugin-v1.md` 覆盖。
+> - 新长期方向是：页面 AI 面板使用 Leptos 实现 Hermes 页面内客户端；Hermes session/message/tool event/usage/model 是 AI 会话真相；mnote 只通过 Hermes skill/plugin 暴露页面、树、artifact、edge 等业务能力。
+> - `mnote-cli` 只能作为 plugin 内部适配器或调试入口，不能再被写成页面 AI 唯一长期执行面。
+
 ### 10.1 已落地事实

 - [x] 文档页 AI 已拆为 host + runtime
@@ -301,24 +306,24 @@
  - [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx)
 - [x] Mindmap / OnlyOffice 也有类似 runtime 拆分
 - [x] `GlobalAiAgentHost` 已不在 `(app)/layout.tsx` 主布局中挂载
- [x] 文档页 AI 已开始把 `node` / `subtree` / `outline` / `evidence` 传给 AI bridge；长期执行面应收口到 `mnote-cli`，页面 AI 只保留为 CLI host / client，`openai-agents-python` / Hermes / Codex 只作为可插拔外置 agent
+- [x] 文档页 AI 已开始把 `node` / `subtree` / `outline` / `evidence` 传给 AI bridge；后续应改为 Hermes run/session context，由 Hermes 通过 mnote skill/plugin 回读和写入业务事实
  - [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx)
  - [route.ts](/mnt/Data1T/mnote/wolai-frontend/src/app/api/ai-agent/run/route.ts)

 ### 10.2 当前还没完成

 - [ ] runtime 组件仍然非常重
- [ ] “最小会话协议、统一流式协议、页面上下文协议”还更多体现在组件内部，不是系统级协议层
- [ ] 还不能说 AI 面板已经变成“纯桥接壳”
+- [ ] “最小会话协议、统一流式协议、页面上下文协议”还更多体现在组件内部，不是 Hermes client proxy / plugin tool contract
+- [ ] 还不能说 AI 面板已经变成“只调用 Hermes 的页面内客户端”
 - [ ] 页面级 AI adapter 仍然很大，只是改成了懒加载
- [ ] AI 已能消费 `node` / `subtree` / `outline` / `evidence` 上下文，但还不是统一的 `mnote-cli` kernel-first tool 协议；Web 面板也还没有彻底退成单纯 host / adapter
+- [ ] AI 已能消费 `node` / `subtree` / `outline` / `evidence` 上下文，但还没有进入稳定 Hermes session/run context 与 mnote plugin tool 协议；Web 面板也还没有彻底退成 Hermes client

 ### 10.3 v2 后续任务

- [ ] 继续下沉 runtime 内状态与协议
- [ ] 把会话、tool event、client action 收口到共享协议层
- [ ] 让 runtime 再减重，而不只是拆文件
- [ ] 把当前上下文注入进一步收口为更稳定的 kernel node / subtree / edge bridge
+- [ ] 移除页面 AI 对旧 `/api/ai-agent/run` 主路径的长期依赖，改走正式 Hermes client proxy
+- [ ] 把会话、message、tool event、usage、model 选择交给 Hermes session 存储
+- [ ] 把 mnote 页面、树、artifact、edge 能力注册为 Hermes skill/plugin tools
+- [ ] 把当前上下文注入进一步收口为 Hermes run context + 稳定 kernel node / subtree / edge tool bridge

 ---

@@ -25,7 +25,7 @@
 - Rust 内核和 Web 承载层如何分工
 - 前端哪些部分应该退出当前重 React 壳
 - `axum`、`Leptos` 这类 Rust Web 方案是否值得采用
- `mnote-cli` 应如何成为唯一长期 agent 执行面
+- 页面 AI 应如何作为 Hermes 页面内客户端接入，并让 mnote 通过 Hermes skill/plugin 暴露业务能力
 - 默认主编辑器已经切到页面内 `leptos-tiptap` island 后，剩余重编辑兼容链应如何继续收口

 ---
@@ -57,7 +57,8 @@
 - **业务执行面：现有 Rust workspace 继续作为唯一业务真执行面**
 - **Web 承载层：`axum`**
 - **页面渲染模型：`Leptos Islands`**
- **AI 执行面：`mnote-cli`**
+- **AI 会话与编排面：Hermes**
+- **mnote AI 能力面：Hermes skill/plugin -> Rust runtime / kernel**
 - **最后保留的重编辑兼容孤岛：少量编辑器 runtime（当前默认主编辑器已是页面内 `leptos-tiptap` island，`BlockNote` 仅保留为 `recycle/` 历史参考副本）**

 一句话概括：
@@ -180,7 +181,7 @@
 - 文档查询与聚合层
 - 树结构装配层
 - 搜索服务层
- AI bridge / CLI host 层；长期 agent 执行面只收口到 `mnote-cli`，Hermes 仅作为历史兼容 bridge / 外置 adapter
+- Hermes client proxy 与 mnote tool bridge 层；页面 AI 会话真相归 Hermes，mnote 业务工具最终回到 Rust runtime / kernel
 - 页面 SSR 外壳承载层
 - 流式更新、通知、事件推送层

@@ -413,14 +414,15 @@ Leptos Islands 很适合承接下面这类长期目标：

 目标：

- 继续桥接统一 CLI host
- 不再承担前端本地 orchestration
+- 作为 Hermes 页面内客户端运行
+- 不再承担前端本地 orchestration 或私有会话存储
 - 不再成为常驻大壳的一部分

 归位：

- 面板只保留最小 UI 与上下文桥接
- 工具执行全部走 `mnote-cli` + Rust tools
+- 面板只保留 Hermes chat/session/run/tool event 的页面内子集 UI 与当前页面上下文桥接
+- Hermes 持有 session / message / usage / model 真相
+- mnote 通过 Hermes skill/plugin 暴露页面、树、artifact、edge 工具，最终执行回到 Rust runtime / kernel
 - 面板按页面需要懒挂载成单独 island

 ### 9.5 Mindmap