mnote/design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md

# 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 本地检查为准：

```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` 等模块。

创建本 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）：

```text
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`

拆分项：

- [x] A1. 把 `render_editor_island_adapter_script()` 的大型 `<script type="module">...</script>` 主体迁入 `document-editor-adapter-runtime.js`。
- [x] A2. `web_shell.rs` 改为输出 `<script type="module" src="/api/mnote-browser-runtime/document-editor-adapter-runtime.js"></script>`。
- [x] A3. 新增 asset route：`/api/mnote-browser-runtime/document-editor-adapter-runtime.js`。
- [x] A4. 保留并更新测试断言，至少覆盖：
  - [x] script tag 出现在 document shell HTML。
  - [x] runtime asset 包含 `PANES_BOOTSTRAP_ID`、`ROOT_SELECTOR`、`BRIDGE_PROTOCOL`。
  - [x] runtime asset 包含 `legacyInlineContentToTiptap`、`openSecondaryDocument`、`openPrimaryMindmap`。
- [x] 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`

拆分项：

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

验收标准：

- [x] 每个新 JS 文件少于 1,500 行。
- [x] entrypoint 少于 900 行。
- [x] `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`
- 新建：`rust/crates/mnote-web/browser/sidebar-page-settings-runtime.js`

拆分项：

- [x] C1. `sidebar-workspace-runtime.js`：workspace source switch、sidebar tabs、collapse/resize 状态。
- [x] C2. `sidebar-page-tree-runtime.js`：page tree row selection、rename title patch、breadcrumb/title sync。
- [x] C3. `sidebar-filetree-open-runtime.js`：local markdown / resource open target、active resource tab dispatch。
- [x] C4. `sidebar-filetree-command-runtime.js`：create/rename/delete/copy/move/trash/restore/purge command payload。
- [x] C5. `sidebar-filetree-upload-runtime.js`：local upload target plan、drop/paste preflight、readonly guard。
- [x] C6. `sidebar-attachment-open-runtime.js`：OnlyOffice/PDF/code/image open mode guard。
- [x] C7. `sidebar-tree-live-apply-runtime.js`：WS/SSE snapshot/delta/resync DOM apply。
- [x] 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
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`

拆分项：

- [x] D1. `tree-shell-state-runtime.js`：state hydration、serialization、patch dispatch。
- [x] D2. `tree-shell-page-runtime.js`：page tree keyboard、expand、focus、drag/drop intent。
- [x] D3. `tree-shell-filetree-runtime.js`：filetree row normalization、resource meta、open target。
- [x] D4. `tree-shell-picker-runtime.js`：picker search/focus/pick root。
- [x] D5. `tree-shell-dom-runtime.js`：DOM patch/render helpers。
- [x] D6. `tree-shell-icons-runtime.js`：icon templates 和 resource kind badge。
- [x] 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`

拆分项：

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

验收标准：

- [x] `lib.rs` 少于 5,000 行。
- [x] `block_handle_menu_view.rs` 可以超过 1,500 行，但必须有清晰入参 struct，避免二十多个 signal 直接散落。
- [x] 不改变 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。

拆分项：

- [x] F1. 审计 `sidebar-tree-runtime.js` 中所有 Page AI / ACP / Hermes / Reasonix 字符串和函数。
- [x] F2. 纯 UI panel host 已迁入 `browser/sidebar-page-ai-runtime.js`。
- [x] 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`。

验收命令：

```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/sidebar-page-ai-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。
- 工作区干净，相关提交已保存。