docs: plan runtime module maintainability split
This commit is contained in:
lix-2026
@@ -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()` 的大型 `<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 行。
|
||||
|
||||
验收命令：
|
||||
|
||||
```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。
|
||||
- 工作区干净，相关提交已保存。
|
||||
Reference in New Issue
Block a user