docs: align runtime architecture guidance
This commit is contained in:
lix-2026
@@ -1,6 +1,12 @@
|
||||
# 01-05 当前主线与优先级总览
|
||||
|
||||
> 更新时间：2026-05-22
|
||||
> 更新时间：2026-05-26
|
||||
>
|
||||
> 2026-05-26 口径补充：
|
||||
> - 前端 runtime 第一轮模块级拆分已完成并归档到 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`；`layout.rs` / `tree.rs` / `web_shell.rs` 大型 raw string 已不再是 CodeGraph 符号定位的主要问题。
|
||||
> - 当前定位浏览器功能默认看 `rust/crates/mnote-web/browser/*.js`，定位 tiptap island 行为默认看 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`。
|
||||
> - 当前 smoke 分类和默认基线以 `scripts/TESTING_REFERENCE.md` 为准；退役 Convex / Next / 3104 / BlockNote 路径只在显式 legacy/cloud/compat 任务中运行。
|
||||
> - Reasonix 只作为受控叶子 worker；不得自行启动 runner/subagent/worktree，结果必须由 Codex/Hermes 主控复核 handoff、diff、验证证据和 git 状态。
|
||||
>
|
||||
> 2026-05-22 口径补充：
|
||||
> - Rust SQLite control-plane 已承接默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 控制面。
|
||||
@@ -119,6 +125,22 @@ P0-P6 已经有最小闭环证据；P7 已完成阶段性瘦身，但还不是
|
||||
- 本地 folder sidebar watch 已从整页 HTML refetch 改为 projection API 刷新
|
||||
- 当前重点已从“是否接入 live stream”转为减少补偿链、缩薄 legacy consumer 和补稳定 smoke。
|
||||
|
||||
### 2.4 Runtime 模块级可维护收口
|
||||
|
||||
当前状态：
|
||||
|
||||
- `/mnt/Data1T/mnote/design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`
|
||||
- `/mnt/Data1T/mnote/design/03-rust-web/process/3-23-sidebar-local-folder-resource-runtime-followup-v1.md`
|
||||
- `/mnt/Data1T/mnote/design/07-ai/process/7-38-page-ai-sidebar-runtime-owner-split-v1.md`
|
||||
|
||||
阶段性结论：
|
||||
|
||||
- `web_shell.rs` 文档页 host adapter 已外置到 `browser/document-editor-adapter-runtime.js` 并继续拆成 pane、resource tab、mindmap host、slash position、Tiptap conversion、session 等模块。
|
||||
- `sidebar-tree-runtime.js` 已降到 3,000 行以下，sidebar workspace、page tree、filetree open/command/upload、attachment open、page settings、live apply 等边界已模块化；Page AI 主体属于 `sidebar-page-ai-runtime.js` 和 `07-ai` owner。
|
||||
- `tree-shell-runtime.js` 已降到 2,500 行以下，debug/internal tree shell 的 page/filetree/picker/render/DOM/icons/state 已有模块边界。
|
||||
- `leptos-tiptap-spike/src/lib.rs` 已降到 5,000 行以下，编辑器 runtime 模块位于 `editor_runtime/`。
|
||||
- CodeGraph 当前应直接索引这些 JS / Rust 模块；后续不再通过“继续拆 raw string”解决问题，而是按 `3-23`、`7-38` 和 BufferStore / Page Aggregate / live cache 等 owner 继续收口。
|
||||
|
||||
## 3. 当前仍应保留但不在第一线的 reference / done
|
||||
|
||||
下面这些文档仍然有效，但当前不应排在第一优先；引用时必须叠加 2026-05-21 之后的 local-first MVP 后阶段口径：
|
||||
|
||||
@@ -303,10 +303,10 @@ UI / 浏览器可见项必须有真实浏览器截图或结构化 smoke 证据
|
||||
| filetree keyboard/clipboard/DND/context menu | ✅ | filetree-dnd-runtime.js + filetree-keyboard-runtime.js |
|
||||
| document pane host / conflict panel runtime | ✅ | acceptDiskVersion/keepCurrentEditorVersion/writeMergedConflictResult + 已迁出的 DOM helper |
|
||||
| local upload 主流程审计 | ✅ | 全部 6 个函数已迁入 local-upload-runtime.js |
|
||||
| WS/SSE tree live smoke | ⚠️ | task487 RED（tree live transport 尚未接入 local_folder），task479/488/489/451 ✅ |
|
||||
| WS/SSE tree live smoke | ✅ | task487 已收敛为 `local-folder-events`，task479/488/489/451 ✅ |
|
||||
| **SIDEBAR_TREE_JS 主 runtime 外置** | ✅ | 10,655 行 → sidebar-tree-runtime.js（超出原计划范围） |
|
||||
|
||||
### browser/ 最终模块清单（11 文件）
|
||||
### browser/ 阶段模块清单（3-20 归档时 11 文件）
|
||||
|
||||
| 文件 | 行数 | 说明 |
|
||||
|------|------|------|
|
||||
|
||||
@@ -191,12 +191,12 @@ codegraph sync .
|
||||
| browser/ 模块 | 11 个 JS 文件，总计 ~11,000 行 |
|
||||
| editor_runtime/ 模块 | 19 个 Rust 模块（另有 mod.rs） |
|
||||
| 浏览器 smoke | task479/488/489/451 全部 PASS |
|
||||
| 测试 | editor 13/13；web full 最近一次 529/549（20 failed，非本轮 editor runtime / sidebar 外置改动面） |
|
||||
| 测试 | editor 13/13；web full 在 3-21 当时最近一次为 529/549（20 failed，非本轮 editor runtime / sidebar 外置改动面）；后续 `10-review/done/16` 已完成全量 `mnote-web --lib` 通过 |
|
||||
| CodeGraph | 350+ 文件索引完成 |
|
||||
|
||||
### 后续已拆出
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| mnote-web 全量 lib 测试失败 | `cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1` 最近一次仍 20 failed（watcher OS limit、legacy proxy、access policy dialog、Hermes block tools 403、local search index、resource trash 503、web_shell 旧断言等），已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`，不再阻塞本文件归档。 |
|
||||
| sidebar runtime 二阶段瘦身 | `sidebar-tree-runtime.js` 已解决 Rust raw string 定位问题，但仍是 1 万行 JS 巨文件；后续拆分计划已拆到 `design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md`。 |
|
||||
| mnote-web 全量 lib 测试失败 | 这是 3-21 归档时的历史状态；后续已由 `10-review/done/16` 收口到全量 `mnote-web --lib` 通过。 |
|
||||
| sidebar runtime 二阶段瘦身 | `sidebar-tree-runtime.js` 已解决 Rust raw string 定位问题；后续二阶段拆分已完成并记录到 `design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md` 与 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`。 |
|
||||
|
||||
@@ -62,7 +62,7 @@ rust/crates/mnote-web/browser/sidebar-tree-runtime.js
|
||||
## 4. 不建议的下一步
|
||||
|
||||
- 不建议直接整体重写 `sidebar-tree-runtime.js`。
|
||||
- 不建议把 `mnote-web --lib` 全量失败作为本文件前置阻塞；该问题已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`。
|
||||
- 不建议把 `mnote-web --lib` 在 3-22 创建时的全量失败作为本文件前置阻塞；后续已由 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md` 收口到全量 `mnote-web --lib` 通过。
|
||||
- 不建议为了 DRY 把 shell 业务编排强行迁入小 helper，尤其是需要 workspace/root/document/session 状态的函数。
|
||||
|
||||
## 5. 验收基线
|
||||
|
||||
+1
-1
@@ -2,7 +2,7 @@
|
||||
|
||||
> 创建时间：2026-05-25
|
||||
> 状态：`process`
|
||||
> 来源：`design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch B / Batch D。
|
||||
> 来源：`design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch B / Batch D。
|
||||
|
||||
## 1. 背景
|
||||
|
||||
|
||||
+1
-1
@@ -6,7 +6,7 @@
|
||||
> 触发背景：
|
||||
> - `bugs/0524.md` 第 4 条删除本地 Markdown 附件链接后 `Ctrl+Z/Ctrl+Y` 不可用，根因是编辑器删除路径绕过 Tiptap/ProseMirror history。
|
||||
> - 修复过程中 CodeGraph 能索引 Rust 符号，但 `rust/spikes/leptos-tiptap-spike/src/lib.rs` 单文件约一万行，职责过多，主控和 worker 都需要反复字面搜索。
|
||||
> - `design/03-rust-web/process/3-19-rust-web-browser-runtime-module-extraction-v1.md` 解决 Rust Web shell/browser host runtime 外置化；本设计补齐编辑器主线拆分。
|
||||
> - `design/03-rust-web/done/3-19-rust-web-browser-runtime-module-extraction-v1.md` 解决 Rust Web shell/browser host runtime 外置化；本设计补齐编辑器主线拆分。
|
||||
|
||||
## 1. 结论
|
||||
|
||||
|
||||
@@ -400,7 +400,9 @@ UI / 浏览器可见项必须有真实浏览器截图或结构化 smoke 证据
|
||||
- `history_safe_commands.rs` 已有 `delete_top_level_block_with_history` / `delete_selected_attachment_link_with_history` 可复用模式。
|
||||
- 建议：实现 `move_top_level_block_with_history` 和 `duplicate_top_level_block_with_history`。
|
||||
|
||||
## 7. 最终完成状态
|
||||
## 7. 5-29 阶段完成状态
|
||||
|
||||
> 注：本节记录 5-29 归档时的阶段状态。后续 `design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md` 已继续拆分 `leptos-tiptap-spike/src/lib.rs`，当前根文件已降到 5,000 行以下。
|
||||
|
||||
### 文件规模变化
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 创建时间：2026-05-25
|
||||
> 状态：`process`
|
||||
> 来源：`design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch A。
|
||||
> 来源：`design/03-rust-web/done/3-22-sidebar-tree-runtime-second-stage-split-v1.md` Batch A。
|
||||
> 2026-05-26 更新：`design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md` 已把 Page AI 主体迁入 `browser/sidebar-page-ai-runtime.js`；本文件继续作为后续 AI owner 收口 checklist。
|
||||
|
||||
## 1. 背景
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
|
||||
本 checklist 不重新打开已经完成的 raw string 外置化任务。`layout.rs` / `tree.rs` 的原始巨型 JS raw string 问题已经解决；本轮聚焦剩余的文档页 host adapter、sidebar-tree JS 巨文件、tree-shell JS 巨文件和 Tiptap island runtime 巨型 Rust 文件。
|
||||
|
||||
## 2. 当前基线
|
||||
## 2. 创建时基线
|
||||
|
||||
代码基线以 2026-05-26 本地检查为准：
|
||||
|
||||
@@ -36,13 +36,24 @@ rust/spikes/leptos-tiptap-spike/src/lib.rs 7,951 行
|
||||
- `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. 范围边界
|
||||
|
||||
本轮做模块拆分，不做语义重写。
|
||||
@@ -76,7 +87,7 @@ rust/spikes/leptos-tiptap-spike/src/lib.rs 7,951 行
|
||||
|
||||
优先级：最高。
|
||||
|
||||
原因：这是当前仍留在 Rust raw string 里的最大前端 runtime，直接影响最初的 CodeGraph 问题。
|
||||
原因：这是创建本 batch 时仍留在 Rust raw string 里的最大前端 runtime，直接影响最初的 CodeGraph 问题。
|
||||
|
||||
目标文件：
|
||||
|
||||
|
||||
+7
-1
@@ -1,6 +1,6 @@
|
||||
# design 设计稿索引
|
||||
|
||||
> 更新时间：2026-05-22
|
||||
> 更新时间：2026-05-26
|
||||
>
|
||||
> 当前产品口径：`VSCode 简化版工作区 + tiptap 的 Markdown 前端编辑器 + Hermes/Reasonix agent + simplemindmap/office 插件 + Wolai 主题 Web 壳 + 鉴权控制面`。
|
||||
>
|
||||
@@ -10,6 +10,10 @@
|
||||
>
|
||||
> 后续新增设计默认以 MVP 后阶段为基线：优先推进 `WorkspacePath/ObjectIdentity`、`DocumentBuffer/BufferStore`、Page Aggregate compat 瘦身、tree command context、live cache 统一、agent diff / 冲突合并 / 本地索引 / 分享同步产品化；不要再把旧 Convex / Next / BlockNote 主链、根 `convex/` functions 源码或 Convex Auth 默认控制面当作新增能力默认方向。
|
||||
>
|
||||
> Runtime 可维护口径：`3-19`、`3-20`、`3-21`、`3-22`、`5-28`、`5-29` 与 `10-review/done/16` 已完成第一轮前端 runtime 模块级拆分。`layout.rs` / `tree.rs` / `web_shell.rs` 大型 raw string 问题不再是当前主问题；浏览器 JS 默认从 `rust/crates/mnote-web/browser/*.js` 定位，tiptap island 默认从 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs` 定位。剩余 runtime 专项按 owner 分流：local folder/resource 编排看 `03-rust-web/process/3-23`，Page AI sidebar owner 看 `07-ai/process/7-38`。
|
||||
>
|
||||
> Smoke 口径：当前分类与默认基线以 `/mnt/Data1T/mnote/scripts/TESTING_REFERENCE.md` 为准；退役 Convex / Next / 3104 / BlockNote 脚本不再占用默认 smoke 基线。
|
||||
>
|
||||
> 状态口径以当前仓库真实代码为准：
|
||||
> - `[done]`：对应阶段或收口目标已经在当前主线代码中成立
|
||||
> - `[process]`：方向已进入主线，且当前可以直接拆 checklist / owner / 验收继续执行
|
||||
@@ -21,6 +25,8 @@
|
||||
|
||||
- `01-05` 当前有效主线与优先级，请先看：
|
||||
`/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
|
||||
- Runtime 模块级拆分完成态，请看：
|
||||
`/mnt/Data1T/mnote/design/10-review/done/16-mnote-web-runtime-module-maintainability-checklist-v1.md`
|
||||
- MVP 后阶段剩余 `process/` 的执行顺序，请看：
|
||||
`/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-8-mvp-post-process-execution-order-v1.md`
|
||||
|
||||
|
||||
Reference in New Issue
Block a user