docs: 继续收口设计稿状态与主线口径

2026-05-09 21:12:57 +08:00
parent ac7023988e
commit 3adc2b5e85
18 changed files with 110 additions and 66 deletions
@@ -1,4 +1,8 @@
-# 3-11 [process] Rust Web Legacy Next Retirement Gates v1
+# 3-11 [done] Rust Web Legacy Next Retirement Gates v1
+
+> 状态说明：
+> - 本稿定义的 default gate 已在当前主线代码中成立：`mnote-web` 是 `3000` owner，Next 仅保留 legacy compat/debug 边界
+> - `MNOTE_WEB_ENABLE_LEGACY_NEXT_COMPAT` 默认关闭与 `task117` guard 已落地，故迁入 `done/`

 ## 目标

@@ -1,7 +1,11 @@
-# 3-14 [process] Rust Web 双窗格可编辑文档壳方案 v1
+# 3-14 [done] Rust Web 双窗格可编辑文档壳方案 v1

 > 更新时间：2026-05-08
 >
+> 状态说明：
+> - 本稿对应的双窗格文档壳、共享 session、事件流复用、URL 恢复与自动化 smoke 已完成，故迁入 `done/`
+> - 下文第 2 节保留的是实现前问题基线；当前真实完成状态与验证证据以第 15-16 节为准
+>
 > 关联文档：
 > - `/mnt/Data1T/mnote/design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
 > - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
@@ -11,9 +15,17 @@

 ## 1. 结论

-当前 `3000` 已经把“在右侧边栏打开”挂到了右键菜单和搜索提示上，但实际只发出了 `tree.page.open-right` 事件，还没有真正的右侧文档容器、窗格状态和多实例同步模型。
+截至 2026-05-09，当前 `3000` 已经具备：

-这一步不应该做成“再开一个完整页面”或“在右侧塞一个 iframe”，而应该在现有 `workspace shell` 内引入：
+- 右侧 `secondary pane` 文档容器
+- pane 状态模型与 URL 恢复
+- 同文档双开共享 session 与即时同步
+- tree live stream / local-folder 事件流复用
+- 对应 Rust 单测与浏览器 smoke
+
+本稿记录的是这条双窗格能力从问题定义到完成验收的收口过程。
+
+最终实现没有做成“再开一个完整页面”或“在右侧塞一个 iframe”，而是在现有 `workspace shell` 内引入了：

 - 双窗格文档宿主
 - 可复用的文档 session 层
@@ -241,7 +241,7 @@

 - [ ] `Sidebar` 仍然是超大客户端组件
  - [sidebar.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/sidebar.tsx)
- [ ] 页面树 / 文件树虽然已统一协议，legacy Next 侧整体执行面仍主要在客户端；当前 Rust Web 3000 SSR 壳也尚未直接消费 live EventSource
+- [ ] 页面树 / 文件树虽然已统一协议，legacy Next 侧整体执行面仍主要在客户端；当前 Rust Web 3000 SSR 壳已接入 live EventSource，但 live cache、preferred snapshot 与补偿链还未完全统一
 - [x] `buildDocumentTree(...)` 仅剩兼容 helper 与旧单测，不再位于树域主路径
 - [ ] 主布局仍然默认常驻挂载 Sidebar
 - [ ] 还不能叫“服务端输出 + 局部 island”，现在更像“服务端首包 + 超大客户端壳”
@@ -1,12 +1,24 @@
 # 3-13 [process] Rust Web 本地 Markdown GFM AST 解析器迁移方案 v1

-> 更新时间：2026-05-08关联：`/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/local_folder_source.rs/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/web_shell.rs/mnt/Data1T/mnote/design/04-tree-domain/done/4-21-local-folder-convex-unified-tree-source-v1.md/mnt/Data1T/mnote/design/04-tree-domain/done/4-22-local-folder-convex-unified-tree-execution-checklist-v1.md`
+> 更新时间：2026-05-09
+>
+> 关联：
+> - `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/local_folder_source.rs`
+> - `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/local_markdown_parser.rs`
+> - `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/web_shell.rs`
+> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-21-local-folder-convex-unified-tree-source-v1.md`
+> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-22-local-folder-convex-unified-tree-execution-checklist-v1.md`

 ## 1. 结论

-当前本地 Markdown 渲染链路是 `mnote-web` 自己写的轻量 parser，不是 VSCode 解析器，也不是成熟 GFM AST pipeline。它已经被补到能覆盖一部分常见语法，但本质上仍是“自己造轮子”，后续维护成本会持续上升。
+当前本地 Markdown 渲染链路已经进入“读侧 AST、写侧仍在过渡”的 partial 状态：

-本方案建议把本地 `.md` 读取侧迁移到 Rust 侧成熟 GFM AST 解析器，再把 AST 映射到现有 `PageAggregate` / Tiptap bridge。当前手写 parser 只保留为过渡层，不再作为长期语义来源。
+- 读侧已新增 Rust `local_markdown_parser.rs`，并基于成熟 GFM AST 解析常见语法
+- 写侧回 Markdown 仍主要依赖 `local_folder_source.rs` 里的手写规则
+
+因此当前问题已经不再是“要不要迁到 AST”，而是“如何把剩余写侧与兼容补丁继续收口”。
+
+本方案当前聚焦的是：继续把 AST 映射到现有 `PageAggregate` / Tiptap bridge，并让剩余手写 parser/回写逻辑逐步退回过渡层，不再作为长期语义来源。

 ## 2. 当前问题

@@ -300,7 +300,7 @@ MNOTE_UI_BASE_URL=http://127.0.0.1:3000 node scripts/task127-rust-web-mindmap-ke
 - Modify: `rust/crates/mnote-web/src/routes/gateway.rs`
 - Modify: `rust/crates/mnote-web/src/config.rs`
 - Modify: `scripts/task117-next-retirement-guard.js`
- Create or Modify: `design/03-rust-web/process/3-11-rust-web-legacy-next-retirement-gates-v1.md`
+- Create or Modify: `design/03-rust-web/done/3-11-rust-web-legacy-next-retirement-gates-v1.md`

 **Checklist：**
 - [x] 盘点 `routes/mod.rs` 中所有 `/api/compat/next`、fallback proxy、legacy debug route 的入口和调用方。
@@ -1,6 +1,6 @@
 # 3 [process] Rust Web 长期架构方案 v1

-> 更新时间：2026-04-16
+> 更新时间：2026-05-09
 >
 > 相关文档：
 > - `/mnt/Data1T/mnote/ARCHITECTURE.md`
@@ -26,7 +26,7 @@
 - 前端哪些部分应该退出当前重 React 壳
 - `axum`、`Leptos` 这类 Rust Web 方案是否值得采用
 - `mnote-cli` 应如何成为唯一长期 agent 执行面
- `BlockNote` 应如何被隔离到最后处理
+- 默认主编辑器已经切到页面内 `leptos-tiptap` island 后，剩余重编辑兼容链应如何继续收口

 ---

@@ -58,17 +58,17 @@
 - **Web 承载层：`axum`**
 - **页面渲染模型：`Leptos Islands`**
 - **AI 执行面：`mnote-cli`**
- **最后保留的重前端孤岛：`BlockNote`**
+- **最后保留的重编辑兼容孤岛：少量编辑器 runtime（当前默认主编辑器已是页面内 `leptos-tiptap` island，`BlockNote` 仅保留为 fallback / 对照链）**

 一句话概括：

 > **mnote 的长期正确方向不是“Next 外壳上继续打补丁”，也不是“只把 API 改成 Rust”，而是“Rust 内核 + Rust Web 壳 + server-first 页面 + 少量交互孤岛”。**

-### 2.3 `BlockNote` 不是第一刀，而是最后一刀
+### 2.3 重编辑兼容链不是第一刀，而是最后一刀

 当前真正难替代的主要是：

- `BlockNote`
+- 以 `BlockNote` fallback、转换链和剩余兼容保存链为代表的重编辑 runtime

 而下面这些能力，从长期看都可以先退出当前大前端壳：

@@ -81,7 +81,7 @@

 所以长期路线应当是：

-> **先把能 Rust 化、能 server-first 化、能 island 化的东西全部迁走，最后再处理 `BlockNote`。**
+> **先把能 Rust 化、能 server-first 化、能 island 化的东西全部迁走，最后再处理重编辑兼容链。**

 ---

@@ -353,12 +353,14 @@ Leptos Islands 很适合承接下面这类长期目标：

 对应的执行细节、逐阶段清单和可验证项，当前应先以 `/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` 保留为 Rust Web 分阶段全景参考。

-### 8.4 当前已落地的最小里程碑（2026-04-16）
+### 8.4 当前已落地的最小里程碑（2026-05-09）

 到目前为止，长期路线里已经有几条可以被源码直接证明的最小里程碑：

- Rust Web 承载层已经有 `mnote-web` crate 骨架，`router / middleware / request context / SSE / WS / AI bridge` 的主接缝已立住；历史上这条线曾经包含 Hermes bridge。
- 文档页已经从“默认先进编辑器”改成“先阅读、后编辑”：服务端先读 `meta + content`，阅读态单独渲染，`BlockNote` 只在进入编辑态后挂载。
+- `mnote-web` 已经不是只停留在 crate 骨架；`3000` 公开入口已由 Rust Web 主壳承接，`3104` 已退到仅显式 debug / internal 边界。
+- Rust Web 主壳已经接入 `/api/tree/events` snapshot / delta / resync consumer，双 pane 也已复用同一条 tree realtime 主链，而不是每个页面壳各自维护第二条流。
+- 文档页读取已经进入 Rust-first `page aggregate` 过渡态：`/api/documents/page` 优先消费 Rust `/api/page-aggregate/:id` 的 `mnote.page_aggregate.v1` snapshot，失败时才回退 TS builder。
+- 默认主编辑区已经切到页面内 `leptos-tiptap` island；阅读态、页头、页面设置和页面内 AI 面板都在 `3000` 主壳上继续收口，`BlockNote` 只保留为 fallback / 对照链。
 - Sidebar 已形成“服务端首包 + 客户端局部 island”的最小边界，导航数据聚合契约不再散落在布局层。
 - SearchPalette 与页面级 AI 面板都已经收成轻 host + 按需 runtime island，重量运行态不再默认跟随主布局常驻。
 - Global AI 继续保留为实验入口，但不再回到 app layout 主链，避免长期路线再次滑回“全局大面板常驻”模式。