lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
29a8e5e1090806d8d293503f7cb362afea35d53d
mnote/design/old/05-editor-mainline/process/5-1-main-editor-cutover-entry-v1.md
T

8.8 KiB
Raw Blame History

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，直到真实文档页完成切流为止。

Reference in New Issue View Git Blame Copy Permalink