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。

 ## 验收命令
@@ -0,0 +1,160 @@
+# 3-15 [done] Runtime Fallback 退场 Checklist v1
+
+> 更新时间：2026-05-09
+>
+> 关联：
+> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
+> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md`
+> - `/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-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. 目标
+
+这份 checklist 只回答一件事：
+
+> **把已经不该继续充当系统组件的 runtime fallback、compat、legacy 与对照链，尽快退出主路径。**
+
+本轮采用激进退场口径：
+
+- 能退场的先退场
+- 退场对象同时退出运行时、默认入口与活跃设计口径
+- `/mnt/Data1T/mnote/recycle` 只保留参考物，不再参与系统主路径
+
+## 2. 主路径白名单
+
+下面这些属于必须保活的主路径：
+
+- [x] 文档页打开链继续可用
+- [x] Sidebar 继续可用
+- [x] `/api/tree/events` realtime 主链继续可用
+- [x] 页面标题保存继续可用
+- [x] 页面设置保存继续可用
+- [x] 正文保存继续可用
+
+下面这些不再享有默认兼容资格，可直接进入退场名单：
+
+- [x] `BlockNote` fallback / 对照链
+- [x] AI provider 直连分支（`Hermes` / `Codex` / 旧 orchestrator compat）
+- [x] legacy Next compat / alias / debug 壳
+- [x] TS page aggregate builder fallback
+- [x] 仍以旧 owner / 旧 fallback 作为默认系统组件的活跃文档表述
+
+## 3. 总原则
+
+- [x] 不再把“开发态”作为保留 fallback 的理由
+- [x] 不再把“以后可能参考”作为继续挂在主路径上的理由
+- [x] 凡移入 `recycle/` 的对象，都必须先断开主路径 import / route / fallback 选择
+- [x] 主路径缺口优先补 Rust-first 正式链，不恢复 legacy fallback
+- [x] 次要入口允许直接 404 / 410 / 501，不再静默降级
+
+## 4. 第一波：立即退场
+
+### 4.1 `BlockNote` fallback / 对照链
+
+- [x] 删除页面壳里“显式切回 BlockNote”的默认入口
+- [x] 删除 `leptos-tiptap` host 中仅用于切回 `BlockNote` 的 fallback 触发链
+- [x] 把 `BlockNote` 从“系统默认可退回编辑器”降为 `recycle` 参考实现
+- [x] 活跃设计稿中不再把 `BlockNote` 写成系统 fallback，只允许写成历史对照链
+
+### 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] 旧 `/api/ai-agent/run` 不再作为页面 AI 主执行入口；历史 `mnote-cli` host 只保留为兼容/内部适配，不再代表长期页面 AI 主线
+- [x] 次要 provider 请求改为明确失败，不再静默降级
+
+### 4.3 legacy Next compat / alias / debug 壳
+
+- [x] 删除 `/api/mnote-web/stream` 这类 tree stream compat alias
+- [x] 删除 `legacy_next_proxy` 默认 fallback
+- [x] 删除仅为 legacy Next upstream 保留的 route fallback
+- [x] 删除默认可见 debug shell / compat shell 入口
+- [x] 仅在明确内部调试需要时，才允许保留隔离后的 debug 文件到 `recycle/`
+
+## 5. 第二波：主链清障后退场
+
+### 5.1 `page aggregate` TS fallback
+
+- [x] 删除 `/api/documents/page` 读链里的 TS builder fallback
+- [x] 文档页读取只保留 Rust `/api/page-aggregate/:id` 正式快照
+- [x] snapshot 不可用时直接显式失败，不再组装 fallback projection
+- [x] 活跃设计稿不再写“Rust-first + TS fallback 混合态”，改成单一路径
+
+### 5.2 页面域本地兼容状态
+
+- [x] 识别 `page aggregate client state` 中仅为旧链兜底存在的字段
+- [x] 删除标题 / 页面设置 / 正文之间的兼容性双轨状态
+- [x] 删除只服务旧 fallback editor host 的状态同步分支
+- [x] 页面域只保留围绕正式 `page.*` command family 的状态回流
+
+### 5.3 tree realtime / sidebar 补偿链
+
+- [x] 删除 preferred snapshot 选择链中只为旧链存在的补偿分支
+- [x] 删除 Sidebar / page subtree / filetree 中旧 snapshot 回闪兜底
+- [x] `3000` 主壳只保留 `/api/tree/events` snapshot + delta + resync 主链
+- [x] 不再为 legacy route 额外维护第二条 live cache 语义
+
+## 6. 第三波：统一归档到 `recycle/`
+
+### 6.1 设计稿与说明
+
+- [x] 将已退场实现对应的设计稿移到 `design/old/` 或 `recycle/design/`
+- [x] 活跃 `process/` 文档移除对已退场 runtime 的默认依赖描述
+- [x] `ARCHITECTURE.md` / `AGENTS.md` 不再把退场对象写成系统组件
+
+### 6.2 参考实现与脚本
+
+- [x] 将退场 runtime 的参考代码移动到 `recycle/` 对应目录
+- [x] 将只服务旧链的 smoke / fixture / helper 脚本移到 `recycle/`
+- [x] 清除主路径中对这些参考实现的 import、route 注册和 UI 入口
+
+## 7. 执行顺序
+
+- [x] 先完成第一波：砍掉次要入口默认资格
+- [x] 再完成第二波：清掉主路径底下的假单一路径
+- [x] 最后完成第三波：统一归档文档、脚本和参考代码
+
+## 8. 验收标准
+
+### 8.1 必须成立
+
+- [x] 文档页仍能打开
+- [x] Sidebar 仍能使用
+- [x] tree realtime 主链仍能工作
+- [x] 标题保存、页面设置保存、正文保存仍能工作
+- [x] 默认主路径不再出现“切回 legacy / fallback / compat”按钮或自动分支
+
+### 8.2 必须消失
+
+- [x] 默认运行时不再自动触发 `BlockNote` fallback
+- [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
+
+### 8.3 允许接受
+
+- [x] 次要入口直接报错
+- [x] 历史 debug 壳直接下线
+- [x] 某些只服务旧链的测试暂时删除后再按新主链重建
+
+## 9. 禁止项
+
+- [x] 不以“先保留一下，以后可能有用”为理由继续保活 fallback
+- [x] 不把已移入 `recycle/` 的代码继续通过主路径 import 回来
+- [x] 不再新增任何新的 compat / fallback / legacy route
+- [x] 不通过文档口径美化来掩盖 runtime 仍依赖 fallback 的事实
+
+## 10. 一句话收口
+
+> **这轮不是“继续整理兼容层”，而是“把不再属于系统组件的 fallback 全部赶出主路径，只保留主路径白名单”。**
@@ -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`

 当前状态：