docs: align runtime architecture guidance

2026-05-26 07:29:15 +08:00
parent e1681331a3
commit 0a15595066
14 changed files with 134 additions and 35 deletions
@@ -8,6 +8,7 @@
 - 本地文件夹是早期产品默认数据真相；本地 `.md` 是页面正文真相。Rust SQLite `control-plane` 是默认 auth、membership、share grants、sync state、AI policy、ACP/Hermes runtime session 控制面；`Convex` / 服务端只保留为历史迁移源、显式 cloud source、compat 和 sync replica 边界，不再作为新增能力的默认正文、附件、AI 会话全文主存储或默认控制面。
 - `Rust kernel` 持有树、子树、边、projection、query、command 的语义主导权；新增树规则不要继续散落到前端、Next route 或临时 compat 层。
 - `mnote-web` 是当前 Rust Web 承载层，负责 transport、projection 分发、兼容切流；`compat` 与 `fixture` 只用于过渡和测试，不应继续承载长期业务语义。`3000` 是唯一前端公开入口；`3104` 已退役为仅显式 debug/internal 使用的边界。`/tree`、`/document-debug` 等 debug 壳默认关闭，仅在显式 debug/runtime 验证时启用。
+- 前端 runtime 已完成第一轮模块级拆分：`layout.rs` / `tree.rs` / `web_shell.rs` 不再是大型内嵌 JS 的主要定位入口。查 Sidebar、FileTree、tree shell、document adapter 等浏览器功能时，默认先看 `rust/crates/mnote-web/browser/*.js`；查 tiptap island 行为时，默认先看 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/*.rs`，再回到根 `lib.rs` / Rust route。
 - 前端主路径应消费稳定 projection，不应在 UI 层重新拼出第二份对象真相。
 - Next `documents/page` 读取主链已优先消费 Rust `mnote.page_aggregate.v1` 快照；TS `page-aggregate-builder` 仅保留为历史 adapter / test helper，不再作为 runtime fallback，也不再把“前端手工拼 `meta + content`”描述为当前主路径。
 - `3000` 当前主壳已接入 Rust Web WebSocket push 主链（`/api/realtime/ws`）+ SSE fallback（`/api/tree/events`）的 snapshot / delta / resync consumer，并已有 browser smoke 验证（2026-05-17 WS 迁移 `57ec8322`）；后续收口重点是统一 live cache 与减少补偿链，而不是把它描述成“还没接 live stream”。
@@ -24,6 +25,17 @@
 - `page-ai/block-edit-workflow` route 只保留为兼容门面或非 local source 的快捷路径，不作为 local-first 普通 Markdown 编辑默认主路径；local-first 下优先给 Hermes / Reasonix 授权文件引用并让 agent 使用自身文件编辑能力。`mnote.doc.markdown_edit` 是 cloud / remote agent / compat fallback；`mnote.block.*` 保留为结构性辅助。
 - 树域三层模型：`Resource Tree`（kernel 对象组织真源）→ `File Tree`（主组织投影，`{title}.md` 为页面正文行）→ `Page Tree`（导航投影，不持有结构真相）。涉及资源归属优先走 Rust kernel 的 `KernelObjectIdentity` / `KernelProjectionResourceKind`。

+## Runtime 模块定位
+
+- `mnote-web` 浏览器 runtime 的当前 canonical 入口是 `rust/crates/mnote-web/browser/`：
+  - Sidebar 装配：`sidebar-tree-runtime.js`，已拆出 workspace、page tree、filetree command/open/upload、attachment open、page settings、live apply 等模块。
+  - FileTree 通用能力：`filetree-runtime.js`、`filetree-selection-runtime.js`、`filetree-context-menu-runtime.js`、`filetree-dnd-runtime.js`、`filetree-keyboard-runtime.js`。
+  - Page AI sidebar host：`sidebar-page-ai-runtime.js`，owner 属于 `07-ai`，不归 `03-rust-web` tree/filetree runtime。
+  - 文档页 host adapter：`document-editor-adapter-runtime.js`，已拆出 pane、resource tab、mindmap host、slash positioning、Tiptap conversion、session 等模块。
+  - debug/internal tree shell：`tree-shell-runtime.js`，已拆出 page、filetree、picker、DOM、render、icons、state 等模块。
+- `leptos-tiptap` island 的当前 canonical 入口是 `rust/spikes/leptos-tiptap-spike/src/editor_runtime/`；新增编辑器行为不得继续直接堆入 `lib.rs`，除非它确实是 wasm-bindgen entrypoint、Leptos 壳层信号编排或仍未形成稳定模块边界。
+- CodeGraph 查 JS 功能时应能直接定位这些 `.js` 文件中的顶层函数；若结果仍落到 Rust raw string 或大型旧壳，先检查是否查错历史 / recycle 路径或索引未同步。
+
 ## 目录优先级

 - `/mnt/Data1T/mnote/recycle/wolai-frontend/src/`
@@ -63,18 +75,20 @@
  - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
  - `/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md`
  - `/mnt/Data1T/mnote/design/05-editor-mainline/reference/5-5-page-aggregate-single-truth-alignment-v1.md`
-  - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`
-  - `/mnt/Data1T/mnote/design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`
+  - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-6-page-aggregate-alignment-checklist-v1.md`
+  - `/mnt/Data1T/mnote/design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`
  - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
-  - `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
+  - `/mnt/Data1T/mnote/design/03-rust-web/done/3-3-rust-web-tree-realtime-event-stream-v1.md`
  - `design/03-rust-web/done/3-14-rust-web-tree-realtime-ws-push-v1.md`
-  - `/mnt/Data1T/mnote/design/10-review/process/08-kernel-architecture-next-priority-review-and-checklist.md`
+  - `/mnt/Data1T/mnote/design/10-review/done/08-kernel-architecture-next-priority-review-and-checklist.md`
  - `/mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md`
  - `/mnt/Data1T/mnote/design/10-review/done/10-current-mnote-ai-runtime-review-v1.md`
  - `/mnt/Data1T/mnote/design/10-review/done/11-current-full-architecture-review-v1.md`
-  - `/mnt/Data1T/mnote/design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md`
  - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-24-resource-tree-filetree-pagetree-source-contract-checklist-v1.md`
  - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-12-main-editor-object-tab-resource-alignment-checklist-v1.md`
+  - `/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`

 ## 设计稿目录规则

@@ -104,6 +118,7 @@
 - 不要擅自恢复、覆盖、删除用户已有改动。
 - 若发现与当前任务无关的脏改动，保持不动；若怀疑会影响当前任务，先确认再处理。
 - 若当前问题只是 UI 表现异常，先确认是否是实验性 tree shell、compat 路径、轮询或 fallback 混入首屏主链，而不是直接怀疑 Convex 本身。
+- Reasonix / subagent 只能作为受控叶子 worker：任务书必须限定读写范围、验证命令、交付文件和禁止项；不得自行再启动 runner、subagent、额外 worktree 或修改任务书。Codex/Hermes 主控必须复核 diff、handoff/result、验证证据和 git 状态后才能采纳。

 ## CodeGraph 使用

@@ -126,6 +141,12 @@
 - 后端开发：`cd /mnt/Data1T/mnote/wolai-backend && uvicorn app.main:app --reload --port 8000`
 - Convex 自托管：仅在显式 cloud / compat / sync replica 或历史导出场景参考 `/mnt/Data1T/mnote/recycle/20260522-convex-runtime-retirement/infra/convex/README.md`

+## Smoke 基线
+
+- 当前 smoke 分类与默认基线以 `scripts/TESTING_REFERENCE.md` 为准。
+- 默认浏览器验证入口是 `3000 Rust SSR + leptos-tiptap island + local-first workspace + SQLite control-plane auth`。
+- 退役 Convex / Next / 3104 / BlockNote 路径的 smoke 不作为默认回归基线；只有显式 legacy/cloud/compat 任务才运行对应脚本。
+
 ## 默认测试账号

 - 后续网页测试、浏览和 smoke 默认使用当前 SQLite control-plane Auth 测试账号：邮箱 `mnote.e2e@example.com`，密码 `MnoteE2E123!`，用户名 `mnote-e2e`。