lix/mnote

Files

T

lix-2026 0a15595066 docs: align runtime architecture guidance

2026-05-26 07:29:15 +08:00

18 KiB

Raw Blame History

16 MNote Web Runtime 模块级可维护收口 Checklist v1

创建时间：2026-05-26 状态：done 归档说明（2026-05-26）：Batch A-F 已完成；全量 mnote-web --lib、leptos-tiptap-spike --lib、格式化、diff check 与 CodeGraph 验收通过；剩余 Page AI owner 细化已转入 design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md。

来源：

承接 design/03-rust-web/done/3-19-rust-web-browser-runtime-module-extraction-v1.md

承接 design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md

承接 design/05-editor-mainline/done/5-28-leptos-tiptap-editor-runtime-module-extraction-v1.md

承接 design/05-editor-mainline/done/5-29-editor-runtime-followup-checklist-v1.md

1. 目标

把当前仍影响 CodeGraph、IDE、浏览器 stack trace 和 agent 派工效率的前端 runtime 大文件，继续拆到“模块级可维护”状态。

本 checklist 不重新打开已经完成的 raw string 外置化任务。layout.rs / tree.rs 的原始巨型 JS raw string 问题已经解决；本轮聚焦剩余的文档页 host adapter、sidebar-tree JS 巨文件、tree-shell JS 巨文件和 Tiptap island runtime 巨型 Rust 文件。

2. 创建时基线

代码基线以 2026-05-26 本地检查为准：

rust/crates/mnote-web/src/ssr/pages/layout.rs                         1,159 行
rust/crates/mnote-web/src/routes/tree.rs                              4,114 行
rust/crates/mnote-web/src/routes/web_shell.rs                         5,954 行
rust/crates/mnote-web/browser/sidebar-tree-runtime.js                10,594 行
rust/crates/mnote-web/browser/tree-shell-runtime.js                   4,577 行
rust/spikes/leptos-tiptap-spike/src/lib.rs                            7,951 行

已完成事实：

layout.rs 的 SIDEBAR_TREE_JS 已外置为 browser/sidebar-tree-runtime.js，layout.rs 只保留极小 bootstrap fallback。
tree.rs 的 tree shell browser runtime 已外置为 browser/tree-shell-runtime.js。
mnote-web/browser/ 已有 12 个 JS runtime 文件，CodeGraph 已按 JavaScript 索引。
leptos-tiptap-spike/src/editor_runtime/ 已拆出 mindmap_node_view.rs、bridge_events.rs、bridge_dispatch.rs、slash_actions.rs、table_commands.rs、table_toolbar_view.rs 等模块。

创建本 checklist 时仍未达标：

web_shell.rs 的 render_editor_island_adapter_script() 仍是大型 inline module script。
sidebar-tree-runtime.js 已可索引，但单文件仍超过一万行，职责过多。
tree-shell-runtime.js 已可索引，但仍混合 page tree、file tree、picker、DOM patch、DND、icon/render 等职责。
leptos-tiptap-spike/src/lib.rs 仍接近八千行，CSS、mount、runtime bridge、slash UI、block menu、resource identity、command handler 仍混在一起。

归档后真实状态（2026-05-26）：

rust/crates/mnote-web/src/routes/web_shell.rs                         2,578 行
rust/crates/mnote-web/browser/sidebar-tree-runtime.js                 2,770 行
rust/crates/mnote-web/browser/tree-shell-runtime.js                   2,482 行
rust/spikes/leptos-tiptap-spike/src/lib.rs                            3,632 行

上述未达标项已由 Batch A-E 解决；剩余 Page AI owner 细化已转入 design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md，local folder/resource 编排细化已转入 design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md。

3. 范围边界

本轮做模块拆分，不做语义重写。

允许：

把 inline script 移到 mnote-web/browser/*.js 并通过现有 asset route 加载。
把 JS 巨文件拆成多个浏览器 runtime helper，并保留一个 thin entrypoint。
把 Tiptap island 的 Rust 大文件继续拆到 editor_runtime/*.rs。
为每一刀补窄范围断言，确认 runtime asset 被加载、关键函数/事件名仍存在。

不做：

不改变 Rust kernel / Page Aggregate / tree command 协议语义。
不把 Page AI runtime 混进 tree/filetree runtime；AI 大块需要单独进入 07-ai。
不重写 Tiptap editor、ProseMirror history 或 mindmap 事实源。
不用“换 CodeGraph 工具”替代源码组织修复。

4. 完成标准

全部完成时应满足：

web_shell.rs 不再包含大型 editor adapter inline JS；只保留 JSON bootstrap、script tag 和 Rust route/helper。
sidebar-tree-runtime.js 单文件目标降到 3,000 行以下，入口文件只负责装配。
tree-shell-runtime.js 单文件目标降到 2,500 行以下，page/filetree/picker 逻辑有明确模块边界。
leptos-tiptap-spike/src/lib.rs 目标降到 5,000 行以下，新增编辑器行为不得继续直接堆入根 lib.rs。
CodeGraph 可以直接定位核心 JS/Rust 模块中的 top-level function / enum / struct。
所有迁移批次均通过对应验证命令，并在最后提交。

5. Batch A：外置 `web_shell.rs` 文档页 host adapter

优先级：最高。

原因：这是创建本 batch 时仍留在 Rust raw string 里的最大前端 runtime，直接影响最初的 CodeGraph 问题。

目标文件：

新建：rust/crates/mnote-web/browser/document-editor-adapter-runtime.js
修改：rust/crates/mnote-web/src/routes/web_shell.rs
修改：rust/crates/mnote-web/src/routes/mod.rs

拆分项：

A1. 把 render_editor_island_adapter_script() 的大型 <script type="module">...</script> 主体迁入 document-editor-adapter-runtime.js。
A2. web_shell.rs 改为输出 <script type="module" src="/api/mnote-browser-runtime/document-editor-adapter-runtime.js"></script>。
A3. 新增 asset route：/api/mnote-browser-runtime/document-editor-adapter-runtime.js。
A4. 保留并更新测试断言，至少覆盖：
- script tag 出现在 document shell HTML。
- runtime asset 包含 PANES_BOOTSTRAP_ID、ROOT_SELECTOR、BRIDGE_PROTOCOL。
- runtime asset 包含 legacyInlineContentToTiptap、openSecondaryDocument、openPrimaryMindmap。
A5. web_shell.rs 行数显著下降，目标少于 3,200 行。

验收命令：

cargo fmt --manifest-path rust/Cargo.toml --all --check
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib routes::web_shell -- --test-threads=1
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib routes::tests::mnote_browser_runtime_assets_are_explicitly_mounted -- --test-threads=1

6. Batch B：拆 `document-editor-adapter-runtime.js`

优先级：高。

原因：Batch A 解决 Rust raw string，但新 JS 文件会很大。需要继续拆到模块级可维护。

目标文件：

rust/crates/mnote-web/browser/document-editor-adapter-runtime.js
新建：rust/crates/mnote-web/browser/document-pane-runtime.js
新建：rust/crates/mnote-web/browser/document-tiptap-conversion-runtime.js
新建：rust/crates/mnote-web/browser/document-resource-tab-runtime.js
新建：rust/crates/mnote-web/browser/document-mindmap-host-runtime.js
新建：rust/crates/mnote-web/browser/document-slash-position-runtime.js

拆分项：

B1. document-pane-runtime.js：secondary pane URL、pane resize、pane close、pane runtime registry。
B2. document-tiptap-conversion-runtime.js：legacy block / inline content / marks 转 Tiptap document。
B3. document-resource-tab-runtime.js：resource tab registry、MRU、close guard、resource text/image/frame editor mount。
B4. document-mindmap-host-runtime.js：primary mindmap object shell、mindmap resource tab mount/unmount。
B5. document-slash-position-runtime.js：slash menu active root、positioning、mutation observer。
B6. entrypoint 只负责读取 bootstrap、加载 runtime、装配各子模块。

验收标准：

每个新 JS 文件少于 1,500 行。
entrypoint 少于 900 行。
document_editor_adapter 相关测试不再依赖在 Rust raw string 中字面搜索。

验收命令：

node --check rust/crates/mnote-web/browser/document-editor-adapter-runtime.js
node --check rust/crates/mnote-web/browser/document-pane-runtime.js
node --check rust/crates/mnote-web/browser/document-tiptap-conversion-runtime.js
node --check rust/crates/mnote-web/browser/document-resource-tab-runtime.js
node --check rust/crates/mnote-web/browser/document-mindmap-host-runtime.js
node --check rust/crates/mnote-web/browser/document-slash-position-runtime.js
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib routes::web_shell -- --test-threads=1

7. Batch C：拆 `sidebar-tree-runtime.js`

优先级：高。

原因：原 raw string 痛点已解决，但该文件仍超过一万行，不利于 CodeGraph 结果阅读和 worker 派工。

目标文件：

rust/crates/mnote-web/browser/sidebar-tree-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-workspace-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-page-tree-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-filetree-open-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-filetree-command-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-filetree-upload-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-attachment-open-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-tree-live-apply-runtime.js
新建：rust/crates/mnote-web/browser/sidebar-page-settings-runtime.js

拆分项：

C1. sidebar-workspace-runtime.js：workspace source switch、sidebar tabs、collapse/resize 状态。
C2. sidebar-page-tree-runtime.js：page tree row selection、rename title patch、breadcrumb/title sync。
C3. sidebar-filetree-open-runtime.js：local markdown / resource open target、active resource tab dispatch。
C4. sidebar-filetree-command-runtime.js：create/rename/delete/copy/move/trash/restore/purge command payload。
C5. sidebar-filetree-upload-runtime.js：local upload target plan、drop/paste preflight、readonly guard。
C6. sidebar-attachment-open-runtime.js：OnlyOffice/PDF/code/image open mode guard。
C7. sidebar-tree-live-apply-runtime.js：WS/SSE snapshot/delta/resync DOM apply。
C8. sidebar-tree-runtime.js 保留为 entrypoint，目标少于 3,000 行。

验收命令：

node --check rust/crates/mnote-web/browser/sidebar-tree-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-workspace-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-tree-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-filetree-open-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-filetree-command-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-filetree-upload-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-attachment-open-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-tree-live-apply-runtime.js
node --check rust/crates/mnote-web/browser/sidebar-page-settings-runtime.js
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib ssr::pages::layout -- --test-threads=1

8. Batch D：拆 `tree-shell-runtime.js`

优先级：中。

原因：tree-shell-runtime.js 是 debug/internal tree shell 主 runtime。它已经不是 Rust raw string，但仍混合 page/filetree/picker 多模式逻辑。

目标文件：

rust/crates/mnote-web/browser/tree-shell-runtime.js
新建：rust/crates/mnote-web/browser/tree-shell-state-runtime.js
新建：rust/crates/mnote-web/browser/tree-shell-page-runtime.js
新建：rust/crates/mnote-web/browser/tree-shell-filetree-runtime.js
新建：rust/crates/mnote-web/browser/tree-shell-picker-runtime.js
新建：rust/crates/mnote-web/browser/tree-shell-dom-runtime.js
新建：rust/crates/mnote-web/browser/tree-shell-icons-runtime.js

拆分项：

D1. tree-shell-state-runtime.js：state hydration、serialization、patch dispatch。
D2. tree-shell-page-runtime.js：page tree keyboard、expand、focus、drag/drop intent。
D3. tree-shell-filetree-runtime.js：filetree row normalization、resource meta、open target。
D4. tree-shell-picker-runtime.js：picker search/focus/pick root。
D5. tree-shell-dom-runtime.js：DOM patch/render helpers。
D6. tree-shell-icons-runtime.js：icon templates 和 resource kind badge。
D7. entrypoint 少于 2,500 行。

验收命令：

node --check rust/crates/mnote-web/browser/tree-shell-runtime.js
node --check rust/crates/mnote-web/browser/tree-shell-state-runtime.js
node --check rust/crates/mnote-web/browser/tree-shell-page-runtime.js
node --check rust/crates/mnote-web/browser/tree-shell-filetree-runtime.js
node --check rust/crates/mnote-web/browser/tree-shell-picker-runtime.js
node --check rust/crates/mnote-web/browser/tree-shell-dom-runtime.js
node --check rust/crates/mnote-web/browser/tree-shell-icons-runtime.js
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib routes::tree -- --test-threads=1

9. Batch E：继续拆 `leptos-tiptap-spike/src/lib.rs`

优先级：中。

原因：编辑器 runtime 已拆出一批模块，但根 lib.rs 仍接近八千行。继续拆分可以提升 CodeGraph 定位和后续 editor worker 并行能力。

目标文件：

rust/spikes/leptos-tiptap-spike/src/lib.rs
新建：rust/spikes/leptos-tiptap-spike/src/editor_runtime/style.rs
新建：rust/spikes/leptos-tiptap-spike/src/editor_runtime/mount.rs
新建：rust/spikes/leptos-tiptap-spike/src/editor_runtime/runtime_bridge.rs
新建：rust/spikes/leptos-tiptap-spike/src/editor_runtime/block_transform.rs
新建：rust/spikes/leptos-tiptap-spike/src/editor_runtime/slash_menu_view.rs
新建：rust/spikes/leptos-tiptap-spike/src/editor_runtime/block_handle_menu_view.rs

拆分项：

E1. style.rs：迁出 SPIKE_STYLE，根 lib.rs 只引用常量。
E2. mount.rs：迁出 mount context、mounted handles、mount_app_into 周边可独立部分；#[wasm_bindgen] wrapper 可暂留根文件。
E3. runtime_bridge.rs：迁出 dispatch_runtime_event、dispatch_*_to_target、host command listener install。
E4. block_transform.rs：迁出 run_block_turn_into_action、top_level_block_matches_action、page/block transform helpers。
E5. slash_menu_view.rs：迁出 slash menu Leptos view 和 click handling。
E6. block_handle_menu_view.rs：迁出 block handle menu 和 submenu view，作为最后一刀。

验收标准：

lib.rs 少于 5,000 行。
block_handle_menu_view.rs 可以超过 1,500 行，但必须有清晰入参 struct，避免二十多个 signal 直接散落。
不改变 Tiptap command 行为，不新增编辑器功能。

验收命令：

cargo fmt --manifest-path rust/Cargo.toml --all --check
cargo test --manifest-path rust/spikes/leptos-tiptap-spike/Cargo.toml --lib
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib routes::web_shell -- --test-threads=1

10. Batch F：Page AI runtime 边界审计

优先级：低，但必须记录边界。

原因：sidebar-tree-runtime.js 中仍可能包含 Page AI panel / ACP runtime 的历史粘连。AI 主线应归 07-ai，不应继续混在 tree/filetree runtime。

拆分项：

F1. 审计 sidebar-tree-runtime.js 中所有 Page AI / ACP / Hermes / Reasonix 字符串和函数。
F2. 纯 UI panel host 已迁入 browser/sidebar-page-ai-runtime.js。
F3. ACP/Hermes session 行为不得迁入 tree runtime；已更新 design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md，后续 AI event delegation / session 语义收口归 07-ai。

验收命令：

rg -n "Page AI|page-ai|ACP|Hermes|Reasonix|hermes|reasonix" rust/crates/mnote-web/browser/sidebar-tree-runtime.js rust/crates/mnote-web/browser/sidebar-page-ai-runtime.js
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib ssr::pages::layout -- --test-threads=1

11. 全量验收

每个 batch 完成后至少运行：

cargo fmt --manifest-path rust/Cargo.toml --all --check
git diff --check
codegraph sync .
codegraph status . --json

全 checklist 收口时运行：

cargo test --manifest-path rust/spikes/leptos-tiptap-spike/Cargo.toml --lib
cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1
codegraph sync .
codegraph status . --json
git status --short --branch

codegraph status . --json 必须满足：

{
  "pendingChanges": {
    "added": 0,
    "modified": 0,
    "removed": 0
  }
}

12. 推荐执行顺序

推荐一次 goal 覆盖，但分批提交：

Batch A：先外置 web_shell.rs editor adapter，彻底解决剩余 Rust inline JS 大块。
Batch B：立刻拆新 adapter，避免制造新的 JS 巨文件。
Batch C：拆 sidebar-tree-runtime.js，把已可索引的大文件变成可维护模块。
Batch E：继续拆 Tiptap lib.rs，降低编辑器主线风险。
Batch D：拆 tree-shell-runtime.js，作为 debug/internal tree shell 收口。
Batch F：只做 AI 边界审计；如发现大块 AI runtime，再新建 07-ai checklist。

13. 建议 goal 文案

完成 MNote Web runtime 模块级可维护收口：按 design/10-review/process/16-mnote-web-runtime-module-maintainability-checklist-v1.md 分批外置 web_shell editor adapter，拆分 document adapter、sidebar-tree-runtime、tree-shell-runtime 和 leptos-tiptap lib.rs 剩余大块，保持行为不变，确保 mnote-web --lib、spike --lib、格式化、CodeGraph 全部通过，并分批提交保存。

14. 归档条件

满足以下条件后，本文件可从 process/ 移到 done/：

Batch A-E 全部完成。
Batch F 已完成审计；若发现 AI 运行时独立工作，已新建 design/07-ai/process/* 并在本文件记录链接。
mnote-web --lib 与 leptos-tiptap-spike --lib 全绿。
CodeGraph pending 为 0。
工作区干净，相关提交已保存。

18 KiB Raw Blame History Unescape Escape

16 MNote Web Runtime 模块级可维护收口 Checklist v1

1. 目标

2. 创建时基线

3. 范围边界

4. 完成标准

5. Batch A：外置 web_shell.rs 文档页 host adapter

6. Batch B：拆 document-editor-adapter-runtime.js

7. Batch C：拆 sidebar-tree-runtime.js

8. Batch D：拆 tree-shell-runtime.js

9. Batch E：继续拆 leptos-tiptap-spike/src/lib.rs

10. Batch F：Page AI runtime 边界审计

11. 全量验收

12. 推荐执行顺序

13. 建议 goal 文案

14. 归档条件

18 KiB

Raw Blame History

5. Batch A：外置 `web_shell.rs` 文档页 host adapter

6. Batch B：拆 `document-editor-adapter-runtime.js`

7. Batch C：拆 `sidebar-tree-runtime.js`

8. Batch D：拆 `tree-shell-runtime.js`

9. Batch E：继续拆 `leptos-tiptap-spike/src/lib.rs`