mnote/design/03-rust-web/done/3-15-runtime-fallback-retirement-checklist-v1.md

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/done/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. 主路径白名单

下面这些属于必须保活的主路径：

• 文档页打开链继续可用
• Sidebar 继续可用
• /api/tree/events realtime 主链继续可用
• 页面标题保存继续可用
• 页面设置保存继续可用
• 正文保存继续可用

下面这些不再享有默认兼容资格，可直接进入退场名单：

• BlockNote fallback / 对照链
• AI provider 直连分支（Hermes / Codex / 旧 orchestrator compat）
• legacy Next compat / alias / debug 壳
• TS page aggregate builder fallback
• 仍以旧 owner / 旧 fallback 作为默认系统组件的活跃文档表述

3. 总原则

• 不再把“开发态”作为保留 fallback 的理由
• 不再把“以后可能参考”作为继续挂在主路径上的理由
• 凡移入 recycle/ 的对象，都必须先断开主路径 import / route / fallback 选择
• 主路径缺口优先补 Rust-first 正式链，不恢复 legacy fallback
• 次要入口允许直接 404 / 410 / 501，不再静默降级

4. 第一波：立即退场

4.1 BlockNote fallback / 对照链

• 删除页面壳里“显式切回 BlockNote”的默认入口
• 删除 leptos-tiptap host 中仅用于切回 BlockNote 的 fallback 触发链
• 把 BlockNote 从“系统默认可退回编辑器”降为 recycle 参考实现
• 活跃设计稿中不再把 BlockNote 写成系统 fallback，只允许写成历史对照链

4.2 旧 AI provider 直连分支

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

4.3 legacy Next compat / alias / debug 壳

• 删除 /api/mnote-web/stream 这类 tree stream compat alias
• 删除 legacy_next_proxy 默认 fallback
• 删除仅为 legacy Next upstream 保留的 route fallback
• 删除默认可见 debug shell / compat shell 入口
• 仅在明确内部调试需要时，才允许保留隔离后的 debug 文件到 recycle/

5. 第二波：主链清障后退场

5.1 page aggregate TS fallback

• 删除 /api/documents/page 读链里的 TS builder fallback
• 文档页读取只保留 Rust /api/page-aggregate/:id 正式快照
• snapshot 不可用时直接显式失败，不再组装 fallback projection
• 活跃设计稿不再写“Rust-first + TS fallback 混合态”，改成单一路径

5.2 页面域本地兼容状态

• 识别 page aggregate client state 中仅为旧链兜底存在的字段
• 删除标题 / 页面设置 / 正文之间的兼容性双轨状态
• 删除只服务旧 fallback editor host 的状态同步分支
• 页面域只保留围绕正式 page.* command family 的状态回流

5.3 tree realtime / sidebar 补偿链

• 删除 preferred snapshot 选择链中只为旧链存在的补偿分支
• 删除 Sidebar / page subtree / filetree 中旧 snapshot 回闪兜底
• 3000 主壳只保留 /api/tree/events snapshot + delta + resync 主链
• 不再为 legacy route 额外维护第二条 live cache 语义

6. 第三波：统一归档到 recycle/

6.1 设计稿与说明

• 将已退场实现对应的设计稿移到 design/old/ 或 recycle/design/
• 活跃 process/ 文档移除对已退场 runtime 的默认依赖描述
• ARCHITECTURE.md / AGENTS.md 不再把退场对象写成系统组件

6.2 参考实现与脚本

• 将退场 runtime 的参考代码移动到 recycle/ 对应目录
• 将只服务旧链的 smoke / fixture / helper 脚本移到 recycle/
• 清除主路径中对这些参考实现的 import、route 注册和 UI 入口

7. 执行顺序

• 先完成第一波：砍掉次要入口默认资格
• 再完成第二波：清掉主路径底下的假单一路径
• 最后完成第三波：统一归档文档、脚本和参考代码

8. 验收标准

8.1 必须成立

• 文档页仍能打开
• Sidebar 仍能使用
• tree realtime 主链仍能工作
• 标题保存、页面设置保存、正文保存仍能工作
• 默认主路径不再出现“切回 legacy / fallback / compat”按钮或自动分支

8.2 必须消失

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

8.3 允许接受

• 次要入口直接报错
• 历史 debug 壳直接下线
• 某些只服务旧链的测试暂时删除后再按新主链重建

9. 禁止项

• 不以“先保留一下，以后可能有用”为理由继续保活 fallback
• 不把已移入 recycle/ 的代码继续通过主路径 import 回来
• 不再新增任何新的 compat / fallback / legacy route
• 不通过文档口径美化来掩盖 runtime 仍依赖 fallback 的事实

10. 一句话收口

这轮不是“继续整理兼容层”，而是“把不再属于系统组件的 fallback 全部赶出主路径，只保留主路径白名单”。