mnote/design/old/03-rust-web/process/rust-web-long-term-checklist-v1.md

# 3-0 [recycle] Rust Web 长期架构实施清单 v1

> 更新时间：2026-04-16
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/process/document-access-performance-root-cure-v1.md`
> - `/mnt/Data1T/mnote/design/old/08-legacy-rust-kernel/done/rust-kernel-cutover-v1.md`
> - `/mnt/Data1T/mnote/ARCHITECTURE.md`

## 1. 文档用途

这份清单不是短期提速清单，而是长期架构落地清单。

它服务的目标只有一个：

> **把 mnote 从“Rust 内核 + 重前端页面壳”推进到“Rust 内核 + Rust Web 承载 + server-first 页面 + 少量交互孤岛”的稳定形态。**

这份清单强调四件事：

- 做什么
- 不做什么
- 什么时候算完成
- 哪些东西必须最后处理

---

## 2. 总体完成定义

只有同时满足下面几条，才能认为长期架构目标基本达成：

- [ ] Rust workspace 成为唯一业务真执行面，Web 层不再承载第二套对象规则
- [ ] Rust Web 层已经接住主 API、主页面壳、主流式能力
- [ ] 文档访问路径已变成“先阅读、后交互、再编辑”
- [ ] Sidebar、搜索、AI、Mindmap 等外围模块已退出当前重前端主壳
- [ ] `BlockNote` 已被隔离为最后的重交互孤岛，而不是整页入口前提
- [ ] Next/旧 React 壳只保留过渡兼容边界或已被替换

---

## 3. 执行原则清单

在任何阶段开始前，先确认这些原则不被破坏：

- [ ] 不再把新的业务规则写回 TS route / Next 页面层
- [ ] 不再新增新的全局常驻前端大面板
- [ ] 不再把“临时懒加载”当作长期方案替代品
- [ ] 不在未完成阅读态分离前，继续扩张编辑态默认挂载内容
- [ ] 不把 `BlockNote` 当成第一阶段改造对象
- [ ] 不把 OnlyOffice 当成主性能阻塞项
- [ ] 不把“换成 Rust”简化成“只重写 API”

---

## 4. 阶段总览

推荐按下面顺序推进：

- Phase 0：基线与边界冻结
- Phase 1：Rust Web 基础层落地
- Phase 2：文档阅读页 server-first 化
- Phase 3：Sidebar / 页面树 / 文件树 Rust 化与 island 化
- Phase 4：搜索系统 Rust 化与 island 化
- Phase 5：AI 面板进一步收口为纯桥接 island
- Phase 6：Mindmap 独立对象化与独立页面化
- Phase 7：文档编辑态与 `BlockNote` 孤岛化
- Phase 8：旧前端壳下线与兼容清理

### 4.1 阶段依赖与并行规则

这条长期路线不是“看到哪里慢就改哪里”，而是有明确前后依赖。

- [x] `Phase 0` 必须先产出边界冻结、基线和 islands 候选，否则后续会重新滑回旧壳扩张。
- [x] 横向能力 `H1` 必须在 `Phase 1` 之前定口径，否则 Rust Web、阅读态、搜索、AI、Mindmap 会各自发明 trace、缓存和权限语义。
- [x] `Phase 1` 是 `Phase 2` ~ `Phase 6` 的共同前置；没有 Rust Web 承载层，后续只能继续堆 Next route。
- [x] `Phase 2` ~ `Phase 6` 可以分批并行推进，但都必须遵守“阅读优先、局部 island、对象规则只进 Rust core”。
- [x] `Phase 7` 依赖 `Phase 2` ~ `Phase 6` 基本就位后再开始，否则 `BlockNote` 会继续承担外围能力。
- [x] `Phase 8` 只能在 `Phase 1` ~ `Phase 7` 都有稳定替代路径后执行，不能靠“删旧代码”制造假完成。

### 4.2 每阶段输出给下一阶段的输入

- [x] `Phase 0` 输出：重模块审计表、性能基线、阅读态/编辑态边界、islands 候选、冻结口径。
- [x] `Phase 1` 输出：Rust Web 入口、统一 router/middleware/context/error/SSE/WS/Hermes bridge 协议。
- [x] `Phase 2` 输出：文档阅读态服务端主链、阅读工具栏 island、阅读缓存/预取策略。
- [x] `Phase 3` 输出：Sidebar/树结构服务端骨架、局部刷新协议、导航预取策略。
- [x] `Phase 4` 输出：搜索 server-first 页面壳、轻交互 Search island、分页/键盘导航协议。
- [x] `Phase 5` 输出：AI bridge panel 最小会话协议、流式 token/tool/client action 统一事件流。
- [x] `Phase 6` 输出：Mindmap 独立对象页壳、内嵌轻预览边界、独立操作协议。
- [x] `Phase 7` 输出：阅读态/编辑态切换协议、编辑岛错误边界、编辑态性能采样。
- [x] `Phase 8` 输出：Next/旧 React 壳保留清单、兼容层清理清单、最终对外口径。

---

## 5. Phase 0：基线与边界冻结

### 5.1 目标

在动长期架构之前，先冻结边界，避免迁移过程中又把旧模式继续扩写。

### 5.2 实施清单

- [ ] 盘点当前由 Next/React 页面层承载的重模块清单
- [ ] 标记哪些模块属于“必须保留浏览器交互”
- [ ] 标记哪些模块属于“可变为 server-first 页面”
- [ ] 标记哪些模块属于“可退化为独立 island”
- [ ] 标记哪些模块属于“外挂或独立页面，不进入主文档链”
- [ ] 冻结 `BlockNote` 外围继续加功能的入口
- [ ] 冻结 Sidebar、SearchPalette、Document 面板继续膨胀的入口
- [ ] 为页面切换与首屏建立统一性能基线
- [ ] 为文档页进入路径建立链路追踪点
- [ ] 为 Sidebar、搜索、AI、Mindmap 建立独立耗时采样点

### 5.2.1 当前前端重模块审计表

| 模块 | 当前主入口 | 当前主问题 | 长期归位 | 是否必须保留浏览器重交互 |
| --- | --- | --- | --- | --- |
| 文档页 | `wolai-frontend/src/app/(app)/documents/[id]/page.tsx` + `DocumentShell -> DocumentContent -> BlockNoteEditor` | 进入页面默认串到编辑器初始化，阅读态无法先出现 | `Phase 2` 先 server-first 阅读页，`Phase 7` 再把 `BlockNote` 孤岛化 | 是，但只限编辑态 |
| Sidebar / 页面树 / 文件树 | `wolai-frontend/src/app/(app)/layout.tsx` + `src/components/sidebar/sidebar.tsx` | 常驻在主布局内，切页时继续参与大组件状态与重渲染 | `Phase 3` 收口为 Rust query + 服务端壳 + 局部 island | 是，但只限展开/拖拽/快捷过滤 |
| SearchPalette | `src/components/search/search-palette.tsx` | 当前仍作为全局常驻大组件挂在布局内 | `Phase 4` 收口为独立 island 与 server-first 搜索页 | 是，但只限输入/联想/键盘导航 |
| AI 面板 | `src/components/ai-agent/**`、`DocumentAiAgentPanel`、`MindmapAiAgentPanel`、`OnlyOfficeAiAgentPanel` | 已切 Hermes bridge，但页面壳仍偏重，多个面板仍常驻挂载 | `Phase 5` 统一为最小 bridge shell + 按需 island | 是，但只限会话与浏览器 client capability |
| Mindmap | `src/components/editor/blocks/MindmapBlock.tsx` + `src/app/mindmap/[docId]/[mindmapId]/page.tsx` | 独立页仍与 BlockNote 形态绑得太近，内嵌/独立共用同一重壳 | `Phase 6` 收口为独立对象页 + 内嵌轻预览 | 是 |
| OnlyOffice | `src/app/onlyoffice/**` 与 `src/app/api/onlyoffice/**` | 属于外部编辑器桥，不是主文档性能瓶颈 | 继续维持外挂页面，不进入主文档链 | 是，但不进入主文档访问链 |
| `BlockNote` | `src/components/editor/blocknote-editor.tsx` | 当前仍然是文档页默认入口前提 | 最后处理，保留为 `Phase 7` 的重交互孤岛 | 是 |

### 5.2.2 冻结口径

- [x] 新增页面能力时，先判断是否能落到 server-first 页面或局部 island，不能再默认塞回主布局。
- [x] 新增对象规则、权限判断、聚合排序、工具编排，不允许直接写回 Next route 或页面层。
- [x] `BlockNote` 外围的新面板、新工具栏、新初始化逻辑一律冻结，除非是为“阅读态分离”服务。
- [x] Sidebar、SearchPalette、AI 面板不允许再继续增加全局常驻状态容器。

### 5.3 产物清单

- [ ] 当前前端重模块审计表
- [ ] 页面切换性能基线报告
- [ ] 文档阅读态与编辑态的边界定义
- [ ] 岛模型候选模块清单

### 5.3.1 页面切换性能基线报告

| 访问链路 | 当前入口 | 需要记录的统一指标 | 当前基线采样方式 | 迁移后对比目标 |
| --- | --- | --- | --- | --- |
| 普通文档打开 | `/documents/[id]` | 首字节、正文首屏、进入可点击阅读态、进入编辑态耗时、`BlockNote` 挂载耗时 | `scripts/task019-document-ui-regression.js` + 浏览器 performance trace | 把正文首屏与阅读交互从编辑器启动链里剥离 |
| Sidebar 切页 | 主布局 + Sidebar | 切页耗时、树结构重渲染数、导航预取命中率 | `pnpm test src/lib/sidebar-data.test.ts src/lib/file-tree/rows.test.ts` + React Profiler | Sidebar 仅做局部交互，不再放大整页挂载 |
| 搜索打开/关闭 | SearchPalette | 打开耗时、首次结果返回、键盘导航响应、关闭恢复耗时 | 搜索页/浮层交互 trace + `eslint`/定向 smoke | 搜索开关不再引发整页重计算 |
| AI 面板打开/关闭 | Document/Mindmap/OnlyOffice AI | 面板首开耗时、SSE 首 token、关闭后页面恢复耗时 | `runAgent.test.ts` + 页面侧 performance mark | AI 未打开时不占主页面主链 |
| Mindmap 独立页 | `/mindmap/[docId]/[mindmapId]` | 页面壳首屏、导图交互可用、独立页返回文档页耗时 | `scripts/task021-mindmap-ui-regression.js` | 独立页不再依赖文档编辑上下文 |

### 5.3.2 文档阅读态与编辑态的边界定义

- [x] 阅读态必须先拿到页面 meta 与正文读链，允许在没有编辑器的情况下稳定展示正文。
- [x] 编辑态必须显式进入，不能再把“打开文档”默认等同于“挂载完整编辑器”。
- [x] 阅读态负责：权限、只读/禁复制/禁下载策略、正文首屏、轻工具栏、回退与预取。
- [x] 编辑态负责：`BlockNote`、块级写入、Slash、评论/历史/AI/页面选项等重交互链路。
- [x] 只读渲染与可编辑渲染必须是两套不同初始化协议，不能靠 mounted gating 假装分离。

### 5.3.3 岛模型候选模块清单

| 模块 | 候选 island 形态 | 保留在服务端页面壳的内容 |
| --- | --- | --- |
| 文档阅读工具栏 | 轻工具栏 island | 标题、正文、权限壳、阅读统计 |
| Sidebar 树 | 展开/拖拽/快捷过滤 island | 工作区壳、树结构首屏 HTML |
| SearchPalette | 输入框、联想、结果列表 island | 搜索页结果首屏与分页壳 |
| AI 面板 | 单一 `AiBridgePanel` island | 页面上下文注入、SSE 桥接 route |
| Mindmap | 独立导图交互 island | 独立页 meta、权限与返回壳 |
| `BlockNote` | 最后保留的重编辑 island | 阅读页正文、阅读工具栏、权限与缓存壳 |

### 5.4 完成判定

- [ ] 后续任何人都能明确知道哪些模块先迁、哪些模块后迁
- [ ] 已经有统一基线可以验证迁移是否真的更快
- [ ] 不再接受“顺手往旧壳里再塞功能”的继续扩张

---

## 6. Phase 1：Rust Web 基础层落地

### 6.1 目标

建立真正的 Rust Web 承载层，而不是停留在“Rust 只做业务内核”。

### 6.2 实施清单

- [ ] 在 Rust workspace 中明确新增 Web 层 crate 或独立服务目录
- [ ] 选定 `axum` 作为主 HTTP 承载框架
- [ ] 建立统一 Router 组织方式
- [ ] 建立统一 middleware 链
- [ ] 建立统一 request id / trace id 注入
- [ ] 建立统一鉴权上下文注入方式
- [ ] 建立统一 workspace / actor / tenant 上下文透传
- [ ] 建立统一错误码与错误响应协议
- [ ] 建立统一 JSON 响应包装规范
- [ ] 建立统一 SSE 输出协议
- [ ] 建立统一 WebSocket 连接协议
- [ ] 建立统一静态资源与页面壳响应策略
- [ ] 打通 Rust Web 层到现有 Rust core runtime 的调用入口
- [ ] 打通 Rust Web 层到 Hermes 的桥接入口
- [ ] 明确保留哪些 Next route 作为过渡兼容壳
- [ ] 明确哪些旧 route 不允许再扩写

### 6.3 架构约束

- [ ] `axum` 只负责 Web 承载，不复制业务裁决
- [ ] Rust Web 层不再新建第二套对象模型
- [ ] Web 层只组合调用 Rust core，而不是重新实现 core 语义
- [ ] 仍需浏览器特定 transport 的旧接口必须标记为兼容层

### 6.4 完成判定

- [ ] 已有一个可运行的 Rust Web 入口
- [ ] 主 API、SSE、WS、trace 基础设施已可由 Rust Web 层承接
- [ ] 后续页面迁移不再必须依赖 Next API route 作为唯一入口

---

## 7. Phase 2：文档阅读页 server-first 化

### 7.1 目标

把“进入文档页就进入编辑器世界”的模式改成“先进入阅读页，再按需进入编辑态”。

### 7.2 实施清单

- [ ] 定义文档阅读页独立于编辑态的页面模型
- [ ] 定义阅读页所需最小数据模型
- [ ] 定义阅读页 HTML 输出协议
- [ ] 将文档 meta 与正文读取收敛成同一服务端读链
- [ ] 去掉进入文档页必须二次取正文的默认模式
- [ ] 去掉进入文档页必须等待客户端 mounted gating 的默认模式
- [ ] 去掉阅读页默认依赖 `BlockNote` 的前提
- [ ] 把评论、历史、回链、页面选项、AI 等外围面板改为非阻塞挂载
- [ ] 将文档阅读工具栏收缩为轻交互 island
- [ ] 将阅读页权限、只读、禁复制、禁下载等策略前移到服务端页面壳
- [ ] 为阅读页建立缓存与失效策略
- [ ] 为阅读页建立首屏、切页、回退、预取策略

### 7.3 禁止事项

- [ ] 不允许为了“看起来快一点”继续叠更多客户端 gating
- [ ] 不允许阅读页默认挂载完整编辑器依赖树
- [ ] 不允许把评论、AI、回链等周边作为阅读页首屏阻塞条件

### 7.4 完成判定

- [ ] 打开文档时可以先看到完整阅读态，而不是编辑器 loading 壳
- [ ] 文档访问主链已不依赖 `BlockNote` 初始化完成
- [ ] 页面切换性能的主要瓶颈已从“编辑器启动”转移出去

### 7.5 当前落地状态（2026-04-16）

- [x] 文档页已改成 server-first 阅读入口：服务端先拿 `meta + content + revision + conflictDetectionKey`，客户端只在服务端读链失败时才回退到旧 `/api/documents/content` 读链。
- [x] `DocumentShell` 已去掉 mounted gating，阅读页不再先显示“正在载入编辑器...”壳。
- [x] `DocumentReadView` 已承担正文只读渲染；`BlockNoteEditor` 仅在显式进入编辑态或 `openTableId` 直达场景时挂载。
- [x] 只读/禁复制/禁下载、评论、历史、回链、页面 AI 与页面选项都已从阅读首屏阻塞链上移开，阅读态可以先稳定出现。

---

## 8. Phase 3：Sidebar / 页面树 / 文件树 Rust 化与 island 化

### 8.1 目标

把高频访问、长期常驻、当前体量过大的导航系统，从主前端大壳里拆出去。

### 8.2 实施清单

- [ ] 定义 Sidebar 数据聚合协议
- [ ] 定义页面树 / 文件树查询协议
- [ ] 将排序、过滤、分组、收藏、最近访问、回收站等聚合逻辑收敛到 Rust
- [ ] 将大部分树结构渲染改为服务端输出
- [ ] 将展开、折叠、拖拽、快捷过滤等改为局部 island
- [ ] 拆分“静态结构”和“高交互局部状态”
- [ ] 减少全局布局对 Sidebar 的强耦合
- [ ] 让 Sidebar 切页时不重新参与重布局初始化
- [ ] 为树结构建立局部刷新协议，而不是整树重拉
- [ ] 为导航行为建立预取与轻量缓存策略

### 8.3 风险控制

- [ ] 拖拽重排不能倒逼回到全客户端大组件
- [ ] 树结构局部刷新不能破坏 SSR 壳稳定性
- [ ] 布局层不得继续持有超大导航状态容器

### 8.4 完成判定

- [ ] Sidebar 不再是主布局中的超大客户端核心组件
- [ ] 页面树 / 文件树的数据与主要规则已由 Rust 层统一提供
- [ ] 切页时 Sidebar 只参与局部交互，不再放大整页挂载成本

### 8.5 当前落地状态（2026-04-16）

- [x] `layout` 已在服务端先调用 `loadSidebarDataFromConvex(...)` 输出 `SidebarInitialData`，导航首屏数据不再默认延迟到客户端再拼。
- [x] `/api/sidebar`、`src/lib/sidebar-data.ts`、`src/lib/server/sidebar-data.ts` 与实时 hook 已统一复用 `sidebar.dataset.list` 的共享契约。
- [x] 当前 Sidebar 仍保留交互型客户端组件形态，但切页和刷新已建立“服务端首包 + 局部 island”边界，后续只需继续瘦身而不是回到旧的整页初始化模式。

---

## 9. Phase 4：搜索系统 Rust 化与 island 化

### 9.1 目标

让搜索成为一个轻页面、轻浮层、轻交互系统，而不是全局重组件。

### 9.2 实施清单

- [ ] 明确搜索索引层、召回层、结果聚合层全部由 Rust 提供
- [ ] 明确文档、块、标题、标签、对象搜索的统一协议
- [ ] 为搜索结果定义服务端可渲染的数据模型
- [ ] 将 SearchPalette 改造成独立 island
- [ ] 将输入框、联想、最近搜索、结果列表拆成最小交互单元
- [ ] 将搜索页主内容改成 server-first 页面
- [ ] 建立搜索结果分页、滚动续取、键盘导航协议
- [ ] 建立最近搜索与最近访问的轻量持久层
- [ ] 避免搜索组件再作为全局常驻重组件绑定整页布局

### 9.3 完成判定

- [ ] 搜索框打开与关闭不再引发整页级别的重计算
- [ ] 搜索结果主要由 Rust 提供，前端只负责最小交互呈现
- [ ] 搜索能力不再依赖当前全局 React 壳维持状态

### 9.4 当前落地状态（2026-04-16）

- [x] `SearchPalette` 已拆成轻量 `SearchPaletteHost` + `search-palette.runtime`，首次快捷键或首次打开前不再加载重量运行态。
- [x] 全局布局只保留搜索 host 接线，`Ctrl/Cmd+P` 与引用快捷键先由 host 接住，再按需拉起 runtime。
- [x] `SearchPaletteHost` 的动态导入已修正为直接指向 runtime，避免 host 自引用导致的错误懒加载。

---

## 10. Phase 5：AI 面板进一步收口为纯桥接 island

### 10.1 目标

让 AI 面板彻底变成“后端工具桥 + 最小 UI”，不再成为大前端的第二套系统。

### 10.2 实施清单

- [ ] 确认所有主线 AI tools 已收口到 Rust runtime / Hermes
- [ ] 删除或冻结旧前端 registry / orchestration 入口
- [ ] 统一 AI 面板的最小会话协议
- [ ] 统一页面上下文注入协议
- [ ] 统一 AI 输出渲染协议
- [ ] 统一流式 token / tool event / client action 回传协议
- [ ] 将页面级 AI 面板统一为单一 bridge shell
- [ ] 将 AI 面板按需挂载为 island
- [ ] 去掉常驻全局 AI host 对主布局的影响
- [ ] 去掉面板自身承载重量级对象逻辑的习惯

### 10.3 完成判定

- [ ] AI 面板已不再承担第二套工具编排
- [ ] AI 面板关闭或未打开时，不影响页面切换主链
- [ ] AI 页面壳只剩桥接、上下文、渲染，不剩对象真执行逻辑

### 10.4 当前落地状态（2026-04-16）

- [x] 文档页、导图页、OnlyOffice 三类 AI 面板都已收口为轻 host + 按需 runtime island，Hermes / Rust bridge / client-tool-result 主链继续复用现有接缝。
- [x] 文档页 host 只维护 `available/open` 生命周期；OnlyOffice host 只负责接住插件 `ready` 握手；导图 host 只在切到 AI tab 时按需挂载 runtime。
- [x] `GlobalAiAgentHost` 继续保留为实验入口组件，但不再回到 app layout 常驻主链，避免重新变成全局重量壳。

---

## 11. Phase 6：Mindmap 独立对象化与独立页面化

### 11.1 目标

把 Mindmap 从“BlockNote 的一类重自定义块”推进为“独立对象 + 独立页面 + 可嵌入轻预览”。

### 11.2 实施清单

- [ ] 定义 Mindmap 独立对象模型
- [ ] 定义 Mindmap 读写协议与操作协议
- [ ] 明确导图节点、边、布局、样式、视口状态的 Rust 持久化结构
- [ ] 明确导图页面独立于文档页的服务端壳
- [ ] 将独立导图页优先迁到 Rust Web 层
- [ ] 将文档内嵌导图降级为轻预览或轻交互卡片
- [ ] 把导图工具栏、侧栏、缩略图等拆成局部 island
- [ ] 去掉对 BlockNote editor context 的强依赖
- [ ] 去掉“文档内嵌导图”和“独立导图页”共用同一重前端壳的绑定方式

### 11.3 完成判定

- [ ] Mindmap 已可以在不依赖 BlockNote 主运行时的情况下独立打开
- [ ] 文档页不再因为导图组件而被迫挂载整套导图交互壳
- [ ] 导图对象已进入 Rust 主线，而不是继续主要依赖前端组件状态

### 11.4 当前落地状态（2026-04-16）

- [x] 独立导图页已切到 `StandaloneMindmapView`，不再依赖 fake `editorStub` 或 BlockNote editor context。
- [x] 文档内嵌导图已降级为轻预览 / 轻交互入口，文档主链不再因为独立导图壳而被迫进入重运行态。
- [x] Mindmap AI 与导图独立页都已按对象级接缝继续走 Rust / bridge 主线，而不是继续把主逻辑绑在文档编辑器里。

---

## 12. Phase 7：文档编辑态与 `BlockNote` 孤岛化

### 12.1 目标

最后再处理真正难替代的 `BlockNote`，把它从“默认页面入口前提”改成“按需挂载的重编辑岛”。

### 12.2 实施清单

- [ ] 明确阅读态与编辑态的切换协议
- [ ] 明确进入编辑态时的最小初始化协议
- [ ] 将 `BlockNote` 依赖的外围功能继续向外剥离
- [ ] 将评论、回链、历史、AI、页面选项等从编辑器默认初始化链上移走
- [ ] 将自定义 block 的读取协议改成可按需注入
- [ ] 将只读渲染与可编辑渲染彻底拆开
- [ ] 将文档打开路径改成“阅读态常驻，编辑态进入时挂编辑岛”
- [ ] 为编辑岛建立独立错误边界
- [ ] 为编辑岛建立独立性能采样
- [ ] 为编辑岛建立独立恢复机制

### 12.3 禁止事项

- [ ] 不允许在这一步之前就试图整体替换全部编辑器能力
- [ ] 不允许让阅读页重新回退为“先挂编辑器再展示内容”
- [ ] 不允许把新的外围面板重新绑回 `BlockNote` 初始化链

### 12.4 完成判定

- [ ] 绝大多数页面访问不需要等待 `BlockNote`
- [ ] 编辑器只在真正进入编辑态时才挂载
- [ ] `BlockNote` 已成为孤岛，而不是整个页面系统的基础前提

### 12.5 当前落地状态（2026-04-16）

- [x] 阅读态与编辑态的切换协议已经落地：默认阅读、显式进入编辑、`openTableId` 强制编辑、退出编辑后保留短暂 grace period 再卸载编辑岛。
- [x] 评论、历史、回链、页面 AI、页面选项等外围能力都已从 `BlockNote` 默认初始化链外移，阅读态可以单独存在。
- [x] `DocumentReadView` 与 `BlockNoteEditor` 已形成两套不同初始化协议，`BlockNote` 现在是按需进入的重编辑 island，而不是整页入口前提。

---

## 13. Phase 8：旧前端壳下线与兼容清理

### 13.1 目标

在新结构稳定后，清理旧壳，避免双栈长期共存。

### 13.2 实施清单

- [ ] 盘点仍保留的 Next 页面壳与 API 壳
- [ ] 标记哪些属于长期兼容层
- [ ] 标记哪些属于可删除过渡层
- [ ] 删除已被 Rust Web 层替代的 route
- [ ] 删除已被 Rust islands 替代的全局客户端面板
- [ ] 删除失效的桥接 helper、旧 registry、旧 adapter
- [ ] 清理不再使用的布局状态容器
- [ ] 清理不再使用的动态导入链
- [ ] 更新运行文档与架构文档
- [ ] 更新开发约束，禁止回流到旧模式

### 13.3 完成判定

- [ ] 旧前端壳已不再是主路径
- [ ] 双栈只是短期兼容，而不是长期事实
- [ ] 维护成本已经从“双系统并行”回到“单主线演进”

### 13.4 当前收缩口径（2026-04-16）

- [x] 已明确当前仍保留的 Next/React 页面壳：文档页、Sidebar、搜索、AI host 与 OnlyOffice 页面仍在兼容层内，但重运行态已被拆到按需 island。
- [x] 已完成这一轮最小清理：搜索与各类 AI 面板的重量 runtime 不再默认跟随主布局常驻，`GlobalAiAgentHost` 继续停留在实验入口而不是 app layout 主链。
- [x] 已把长期清单、长期架构方案与 harness 状态统一回写，后续 Phase 8 继续以“删旧壳前先写清保留边界”为准，而不是靠误删制造假完成。

---

## 14. 横向能力清单

这些事情不属于单一阶段，但必须贯穿全部阶段推进。

### 14.1 观测与性能

- [ ] 建立统一性能指标：首字节、首屏、交互可用、切页耗时、编辑器挂载耗时
- [ ] 建立统一错误指标：页面壳错误、island 错误、编辑器错误、桥接错误
- [ ] 建立统一 trace 关联：页面请求、Rust query、Rust command、Hermes tool、前端 island
- [ ] 建立按页面类型的性能对比面板

最低交付物：

- [x] 每个页面壳请求都必须生成 `request_id` / `trace_id`，并能串到 Rust query/command 与 Hermes tool。
- [x] 文档页、Sidebar、搜索、AI、Mindmap、编辑岛都要有统一的 performance mark 命名规则。
- [x] 回归脚本必须至少覆盖：文档页、Mindmap、OnlyOffice、AI tool runtime、Sidebar/文件树定向测试。

### 14.2 缓存与预取

- [ ] 建立阅读页缓存策略
- [ ] 建立树结构局部缓存策略
- [ ] 建立搜索结果缓存策略
- [ ] 建立文档邻近页面预取策略
- [ ] 建立失败回退与缓存失效策略

最低交付物：

- [x] 阅读页采用“meta + content”同一读链缓存键，不能再拆成首屏后二次正文请求作为默认主路径。
- [x] 树结构、搜索结果、邻近页面预取都必须显式声明失效来源，避免隐式常驻缓存。
- [x] 失败回退策略必须写明是回源、回旧壳还是退到只读页面。

### 14.3 安全与权限

- [ ] 统一页面壳权限校验
- [ ] 统一对象级读写鉴权
- [ ] 统一浏览器 island 的最小权限输入
- [ ] 统一 AI / Hermes 的工具权限边界

最低交付物：

- [x] 页面壳、对象查询、对象写入、AI tool 调用必须复用同一 workspace / actor / tenant 上下文。
- [x] browser island 只能收到最小权限输入，不能自己推导更高权限。
- [x] Hermes 与 mnote Rust 之间的 bridge 必须只暴露最小业务能力面，不复制前端编排逻辑。

### 14.4 开发规范

- [ ] 新功能默认先判断是否属于 server-first 页面
- [ ] 新交互默认先判断是否可以做成局部 island
- [ ] 新业务规则默认只进 Rust core
- [ ] 新页面默认不能直接复制旧重前端壳模式

最低交付物：

- [x] 提交新页面时必须回答四个问题：是否 server-first、是否 island、对象规则是否进 Rust、是否引入新的常驻壳。
- [x] 没有 trace / 缓存 / 权限口径的新页面或新 island，不允许直接并入长期主线。

---

## 15. 最终验收清单

只有下面这些问题都能回答“是”，这条长期路线才算真正跑通。

- [ ] 打开一个普通文档时，是否已经可以先稳定进入阅读态
- [ ] 切换页面时，是否已经不再默认触发重编辑器初始化
- [ ] Sidebar 是否已经不再是主布局里的超大客户端组件
- [ ] 搜索是否已经不再依赖全局大组件常驻
- [ ] AI 面板是否已经变成纯桥接 island
- [ ] Mindmap 是否已经能独立于 `BlockNote` 主运行时工作
- [ ] Rust Web 层是否已经能承接主 API、主页面壳、主流式链路
- [ ] Rust core 是否已经成为唯一业务真执行面
- [ ] `BlockNote` 是否已经被延后为最后处理的孤岛，而不是继续绑住整页架构
- [ ] 旧前端壳是否已经开始实质性退场，而不是继续成为默认主路径

当前可回答“是”的项（2026-04-16）：

- [x] 打开一个普通文档时，已经可以先稳定进入阅读态。
- [x] 切换页面时，已经不再默认触发重编辑器初始化。
- [x] 搜索已经不再依赖全局大组件常驻。
- [x] AI 面板已经收口为纯桥接 island。
- [x] Mindmap 已能独立于 `BlockNote` 主运行时工作。
- [x] `BlockNote` 已被延后为最后处理的孤岛，而不是继续绑住整页架构。

---

## 16. 一句话执行顺序

如果后续需要不断回看，这条路线可以压缩成一句话：

> **先冻结旧壳扩张，再立 Rust Web 层；先迁阅读页、Sidebar、搜索、AI、Mindmap，最后才处理 `BlockNote`；稳定后再清旧壳，而不是反过来。**