mnote/design/old/05-editor-mainline/process/5-1-main-editor-cutover-entry-v1.md

# 5-1 [recycle] 主编辑器接入点与 Runtime Shell 退场策略 v1

> 更新时间：2026-04-19
>
> 这份文档只解决一件事：
>
> **冻结 `P0.5` 的主编辑器接入点，避免后续又回到“把 spike、runtime shell、独立 demo 当成主链”的旧路径。**

## 1. 结论先行

`P0.5` 的主编辑器切流，必须发生在当前真实文档页主链里，而不是发生在 `localhost:8123` 或 `mnote-web /document` 的独立壳里。

冻结后的结论如下：

1. 当前真实文档页入口是 Next App Router：
   `/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/documents/[id]/page.tsx`
2. 当前真实页面壳入口是：
   `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-shell.tsx`
   `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx`
3. 当前编辑态默认挂载的仍是 `BlockNoteEditor`：
   `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx`
4. `mnote-web /document` 与 `/document-debug` 当前都仍属于 `debug/prototype`，不能视为正式主编辑器页面。
5. `P0.5` 的目标不是先把 `runtime shell` 做成正式页面，而是先把 **`8123` 那套真实 `Leptos + Tiptap` 页面壳与 editor surface** 接进真实文档页。

## 2. 当前事实基线

### 2.1 真实文档页主链

当前真实主链是：

`/documents/[id]` page
-> 服务端桥接拉 `documents.meta.get` 与 `documents.content.get`
-> `DocumentShell`
-> `DocumentContent`
-> 进入编辑态后挂载 `BlockNoteEditor`

关键文件：

- 页面入口：
  `/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/documents/[id]/page.tsx`
- 页面壳薄封装：
  `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-shell.tsx`
- 真正的页面壳与编辑/阅读态切换：
  `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx`
- 当前默认编辑器实现：
  `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocknote-editor.tsx`

### 2.2 BlockNote 默认挂载点

当前不是文档页一进来就挂编辑器，而是：

- `DocumentContent` 控制阅读态/编辑态
- 只有进入编辑态后才挂载 `<BlockNoteEditor />`

这意味着：

> **`DocumentContent` 才是主编辑器切流的真正入口，不是 `blocknote-editor.tsx` 单文件本身。**

`blocknote-editor.tsx` 是当前编辑器 runtime 的实现集中区，但它不是产品页入口决策点。

### 2.3 Rust 侧 `runtime shell` 当前事实

当前 `mnote-web` 已经注册了：

- `/document-debug`
- `/document`

对应文件：

- 路由注册：
  `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/mod.rs`
- 当前实现：
  `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/editor.rs`

但当前事实是：

1. `wolai-frontend` 真实文档页并没有把 `/document` 当成默认文档页。
2. 当前 `/document` 和 `/document-debug` 都还在返回 `runtime shell` 风格页面。
3. 这条路线目前只能算 `debug/prototype`，不能算正式主编辑器切流完成。

## 3. 主编辑器接入点

### 3.1 冻结后的主编辑器接入点

`P0.5` 正式冻结如下：

> **主编辑器接入点 = `DocumentContent` 的编辑态 host 替换位。**

也就是：

- 保持 `/documents/[id]` 页面入口不变
- 保持 `DocumentShell` 作为薄封装不变
- 在 `DocumentContent` 内，把当前编辑态挂载的 `BlockNoteEditor` 替换为新的主编辑器 host

这样做的原因是：

1. 真实页面的布局、读写切换、评论、历史、检查器、AI 面板、移动/嵌入弹层都已经挂在这条链上。
2. 如果不从这里切流，很多真实 bug 根本不会暴露。
3. 这条链已经消费了 Rust `documents.content.get` 与 `pageSubtree`，最接近最终主链。

### 3.2 不冻结成主入口的点

下面这些点都不能被当成 `P0.5` 的正式主入口：

- `localhost:8123`
  原因：它只是 `leptos-tiptap` 的 spike/验证页。

- `mnote-web /document`
  原因：它当前仍是 `runtime shell`/独立宿主页，不是产品默认文档页。

- `mnote-web /document-debug`
  原因：它明确只应保留给诊断、回归和 debug。

## 4. 切流 Flag 策略

### 4.1 Flag 归属

主编辑器切流 flag 必须归属于真实文档页主链，而不是归属于 `runtime shell`。

冻结后的原则：

1. flag 归 `wolai-frontend` 文档页 host 所有。
2. flag 控制的是 `DocumentContent` 编辑态里挂哪个 editor host。
3. 不复用 `mnoteWebTreeShellEnabled` 之类的 tree shell 开关。

### 4.2 Flag 语义

`P0.5` 推荐的切流语义应当是：

- `blocknote`
- `leptos_tiptap`

也就是说：

- 阅读态继续保持现有 `DocumentReadView`
- 只替换编辑态 host
- 页面路由不改
- 文档 query/load 主链不改

### 4.3 Flag 不该控制的内容

切流 flag 不应控制：

- `mnote-web /document-debug` 是否可访问
- tree shell 是否启用
- 任何与 sidebar/filetree 实验壳有关的逻辑

原因：

这些不是主编辑器切流本身，混在一起只会让验证口径再次失真。

## 5. Runtime Shell 退场策略

### 5.1 `runtime shell` 的保留定位

`runtime shell` 不是立即删除，而是降级为下面两种用途：

1. `debug/prototype`
2. 独立验收与对照环境

也就是说：

- `/document-debug` 继续存在
- `/document` 在 `P0.5` 前也仍可保留为 Rust 侧独立 host
- 但它们都不代表正式主编辑器切流完成

### 5.2 明确退场线

从这版开始，下面这句话固定下来：

> **只要默认文档页仍然不是 `Next /documents/[id] -> DocumentContent -> 新 editor host`，就不能宣称主编辑器已经切流完成。**

这条线用来防止后面再次把：

- 独立 demo
- `runtime shell`
- debug 页
- 仅可单独访问的 Leptos 页面

误当成正式交付。

## 6. `P0.5` 的实际落点

`P0.5` 后续任务的实际落点应当按下面顺序推进：

1. 在 `DocumentContent` 中抽出“编辑态 host”这一层
2. 先让 **`8123` 的真实 editor surface** 能进入真实文档页
3. 再打通 load/save 与 Rust truth
4. 再补 block id、schema、command、验收链

这里最重要的不是“先做更多 feature”，而是：

> **先让真实文档页开始消费新的 editor host。**

## 7. 未支持能力降级

在 `P0.5` 内，下面这些能力允许暂不支持，但必须显式降级：

- 图片上传
- 表格
- 页面引用
- 块引用
- heading collapse
- 普通块缩进增强

原则：

1. 未支持能力不允许伪装成已完成。
2. 未支持能力不能污染正式保存合同。
3. 降级策略必须发生在真实主编辑器链路里，而不是藏在 `runtime shell` 中。

## 8. 对 task-002 的直接要求

`task-002` 开始时应直接按这份冻结结果执行：

1. 不改真实文档页入口
2. 不先把 `mnote-web /document` 做成产品页
3. 先在 `DocumentContent` 的编辑态 host 位接入 **`8123` 的真实 `leptos-tiptap` surface**
4. `runtime shell` 继续只作为 debug/prototype 与对照验收环境

## 8.1 对 task-002 的额外冻结

从这版开始，`task-002` 的完成标准额外加上一条：

> **真实 `/documents/[id]` 页面里看到的编辑态，必须直接继承 `8123` 那套页面壳 / editor stage / toolbar / slash / handle 行为模型；不接受“只是换成另一个新的 host，但长得不像 8123”。**

这也意味着：

1. 不接受把 `/document` 或 `/document-debug` 的 runtime shell 套壳后冒充成主编辑器。
2. 如果临时桥接层需要嵌入式承载 `8123` surface，也必须承载 **`rust/spikes/leptos-tiptap-spike` 的真实页面壳**，而不是另一套重新发明的 debug UI。
3. `task-002` 只解决“让 8123 体验进入真实文档页”；load/save、Rust truth、block id 等正式合同继续留给后续 `task-003+`。

## 8.2 对接入方式的额外冻结

`task-002` 允许临时使用 `iframe` 承载真实 `8123` runtime，但不允许再走下面这条错误路线：

1. 把 `rust/spikes/leptos-tiptap-spike/dist` 直接当成 `wolai-frontend/public` 下的静态页面来嵌。
2. 依赖宿主侧轮询 iframe DOM、注入一大段 CSS，去“修”出像 8123 的样子。
3. 在真实页面外面再包一层新的 bridge card / bridge banner / debug 文案，导致最终截图看起来已经不是 8123 行为模型。

冻结后的临时接法应当是：

1. 真实 `/documents/[id]` 页面继续作为唯一验收入口。
2. `MainEditorHost` 只负责承载 `8123` runtime，不再重新发明一层页面壳。
3. `8123` 自己提供嵌入模式，把 standalone/debug UI 在 spike 内原生收掉。
4. host 与 spike 之间通过显式 embed 协议同步 `ready` / `height`，而不是依赖脆弱的跨文档 DOM 轮询。

## 9. 最终口径

这份文档固定下来的最终口径是：

> **主编辑器接入点是 `wolai-frontend` 的真实文档页编辑态 host，不是 `runtime shell`；`mnote-web /document` 与 `/document-debug` 继续只保留为 `debug/prototype`，直到真实文档页完成切流为止。**