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

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

- [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 全部赶出主路径，只保留主路径白名单”。**
