From 020545e07fdd5c55bc77c8253653f144aa8f5c4f Mon Sep 17 00:00:00 2001 From: lix-2026 Date: Tue, 26 May 2026 00:17:39 +0800 Subject: [PATCH] docs: plan runtime module maintainability split --- ...ime-module-maintainability-checklist-v1.md | 344 ++++++++++++++++++ 1 file changed, 344 insertions(+) create mode 100644 design/10-review/process/16-mnote-web-runtime-module-maintainability-checklist-v1.md diff --git a/design/10-review/process/16-mnote-web-runtime-module-maintainability-checklist-v1.md b/design/10-review/process/16-mnote-web-runtime-module-maintainability-checklist-v1.md new file mode 100644 index 00000000..243f70cf --- /dev/null +++ b/design/10-review/process/16-mnote-web-runtime-module-maintainability-checklist-v1.md @@ -0,0 +1,344 @@ +# 16 MNote Web Runtime 模块级可维护收口 Checklist v1 + +> 创建时间：2026-05-26 +> 状态：`process` +> +> 来源： +> - 承接 `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 本地检查为准： + +```text +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` 等模块。 + +仍未达标： + +- `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 仍混在一起。 + +## 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 + +优先级：最高。 + +原因：这是当前仍留在 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()` 的大型 `` 主体迁入 `document-editor-adapter-runtime.js`。 +- [ ] A2. `web_shell.rs` 改为输出 ``。 +- [ ] 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 行。 + +验收命令： + +```bash +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 中字面搜索。 + +验收命令： + +```bash +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` + +拆分项： + +- [ ] 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 行。 + +验收命令： + +```bash +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 +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 行。 + +验收命令： + +```bash +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 行为，不新增编辑器功能。 + +验收命令： + +```bash +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/page-ai-panel-runtime.js`。 +- [ ] F3. ACP/Hermes session 行为不得迁入 tree runtime；需要新建或更新 `design/07-ai/process/*` checklist 后再实施。 + +验收命令： + +```bash +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/page-ai-panel-runtime.js +cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib ssr::pages::layout -- --test-threads=1 +``` + +## 11. 全量验收 + +每个 batch 完成后至少运行： + +```bash +cargo fmt --manifest-path rust/Cargo.toml --all --check +git diff --check +codegraph sync . +codegraph status . --json +``` + +全 checklist 收口时运行： + +```bash +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` 必须满足： + +```json +{ + "pendingChanges": { + "added": 0, + "modified": 0, + "removed": 0 + } +} +``` + +## 12. 推荐执行顺序 + +推荐一次 goal 覆盖，但分批提交： + +1. Batch A：先外置 `web_shell.rs` editor adapter，彻底解决剩余 Rust inline JS 大块。 +2. Batch B：立刻拆新 adapter，避免制造新的 JS 巨文件。 +3. Batch C：拆 `sidebar-tree-runtime.js`，把已可索引的大文件变成可维护模块。 +4. Batch E：继续拆 Tiptap `lib.rs`，降低编辑器主线风险。 +5. Batch D：拆 `tree-shell-runtime.js`，作为 debug/internal tree shell 收口。 +6. Batch F：只做 AI 边界审计；如发现大块 AI runtime，再新建 `07-ai` checklist。 + +## 13. 建议 goal 文案 + +```text +完成 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。 +- 工作区干净，相关提交已保存。