20260513 mindmap优化01

design/10-review/01-rust-kernel-web-review.md

@@ -0,0 +1,119 @@
+# Rust Kernel / Web 实现偏差审查
+
+## 范围
+
+本次只审查 Rust kernel / protocol / bridge-runtime / mnote-web / storage-convex-bridge 与当前设计主线的一致性。
+
+重点对照设计：
+
+- `ARCHITECTURE.md`
+- `design/01-05-current-priority-overview.md`
+- `design/01-tree-first-graph-kernel/process/1-tree-first-graph-kernel-v1.md`
+- `design/01-tree-first-graph-kernel/process/1-1-tree-first-graph-kernel-checklist-v2.md`
+- `design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md`
+- `design/03-rust-web/process/3-rust-web-long-term-architecture-v1.md`
+- `design/03-rust-web/process/3-1-rust-web-long-term-checklist-v2.md`
+- `design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
+- `design/03-rust-web/process/3-15-runtime-fallback-retirement-checklist-v1.md`
+- `design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
+
+重点代码：
+
+- `rust/crates/core-protocol/`
+- `rust/crates/core-domain/`
+- `rust/crates/bridge-runtime/`
+- `rust/crates/mnote-web/`
+- `rust/crates/storage-convex-bridge/`
+
+## 结论
+
+Rust kernel / protocol / bridge-runtime / mnote-web 的主干方向与当前设计基本一致：`core-protocol` 已有统一 kernel node / edge / projection / page aggregate 协议；`bridge-runtime` 已能执行 kernel query / command / projection；`mnote-web` 已持有 3000 主入口、文档页 shell、`/api/page-aggregate/:id`、tree command、`/api/tree/events`、Search shell 等关键接缝；`storage-convex-bridge` 明确把 `tree.*` / `page.*` 等语义命令映射到底层 Convex mutation。
+
+主要偏差不是“Rust 主线没有落地”，而是当前仍存在几类收口缺口：
+
+1. 部分 Rust Web 主路径仍会静默合成 fallback / fixture 数据，和 `Runtime Fallback 退场` 的激进口径不完全一致。
+2. Page Aggregate 对外标记为 `KernelProjection`，但 Rust Web 仍先取 `documents.meta/content` 再在 runtime 内拼成聚合；这是合理过渡实现，但“单一 kernel 真源”口径容易被写得过满。
+3. Tree realtime 已有正式 SSE 主链，但实现仍偏轮询 bridge overview，WS 仍是 snapshot/resync 骨架，尚未成为完整实时主链。
+4. Legacy / compat 能力默认大多关闭，但配置位、proxy 辅助函数和兼容源枚举仍在，设计文档中“全部退场”的勾选状态可能偏乐观。
+
+## 关键发现表格
+
+| 编号 | 分类 | 严重度 | 发现 | 证据 |
+| --- | --- | --- | --- | --- |
+| RK-01 | 未完成 | 中 | Kernel projection 仍主要从 `sidebar.dataset.list` 这一份 Convex 数据集构建，广义 node pool / reference edge / summary/index 真相层尚未完全独立。 | `rust/crates/mnote-web/src/routes/snapshot_support.rs:27` 定义 `sidebar.dataset.list`；`:93` 先加载 sidebar dataset 再执行 `kernel.project_view`；`rust/crates/bridge-runtime/src/lib.rs:8010` 后续由 sidebar 数据构建 subtree；`:8111` 再转为 projection。 |
+| RK-02 | 实现偏差 / 风险 | 高 | Rust Web 主路径仍存在静默 fallback：workspace shell 在 projection 加载失败时无条件合成最小 workspace/documents；sidebar/filetree 在 `allow_dev_fixtures` 时合成开发数据；Search 在 Convex query 失败时返回内置搜索数据。这与 `3-15-runtime-fallback-retirement` 的“默认不再 fallback”口径冲突。 | `rust/crates/mnote-web/src/routes/web_shell.rs:2379` 到 `:2401` 无条件 fallback 最小 dataset；`:2432` 到 `:2461` 合成 sidebar dev dataset；`:2493` 到 `:2519` 合成 filetree dev dataset；`rust/crates/mnote-web/src/routes/search.rs:233` 到 `:247` 搜索失败后走 `fallback_search_dataset`。 |
+| RK-03 | 方向变化 / 文档滞后 | 中 | Page Aggregate 已由 Rust Web 暴露正式 route，但实现仍是先读 `documents.meta/content`，再把 joined data 交给 `page.aggregate.get` 生成 projection。代码对外 source 标成 `KernelProjection`，但底层仍是 meta/content join 的迁移形态；需要文档明确这是 Rust runtime adapter，而非完整 kernel storage 真源。 | `rust/crates/mnote-web/src/routes/web_shell.rs:2282` 到 `:2315` 先读 meta/content 再执行 `page.aggregate.get`；`rust/crates/bridge-runtime/src/lib.rs:8246` 到 `:8253` 将 source 传为 `PageAggregateSource::KernelProjection`；`:5303` 到 `:5324` 从 meta/content 中抽取 title/content/revision。 |
+| RK-04 | 未完成 | 中 | Tree realtime 正式 route 已存在，但当前 SSE 仍通过 polling `bridge.workspace.overview` 生成 snapshot/delta/resync；WS 只发送初始 snapshot，并只支持客户端请求 resync，不是完整主实时链路。 | `rust/crates/mnote-web/src/routes/sse.rs:51` 到 `:91` 循环 sleep/poll overview 后生成 delta；`rust/crates/mnote-web/src/routes/ws.rs:32` 发送 snapshot，`:40` 到 `:80` 只处理 resync 或 unsupported ack。 |
+| RK-05 | 风险 / 文档滞后 | 低 | Legacy Next compat 默认关闭，但代码仍保留 env-gated proxy 能力、Next proxy 辅助函数和 compat 配置位。若文档继续写“legacy compat 已删除”，会与代码事实不一致；若保留，应写成显式调试/迁移边界。 | `rust/crates/mnote-web/src/app.rs:42` 到 `:54` 仍读取 `MNOTE_WEB_LEGACY_NEXT_BASE_URL` / `MNOTE_WEB_ENABLE_LEGACY_NEXT_COMPAT`；`rust/crates/mnote-web/src/routes/gateway.rs:86` 到 `:87` auth API 可转 legacy proxy；`:402` 到 `:499` legacy proxy 实现仍在；`rust/crates/mnote-web/src/routes/documents.rs:153` 当前 `should_proxy_via_next` 返回 false，但 Next proxy helper 仍保留。 |
+| RK-06 | 实现一致 | 低 | Tree command cutover Stage 2 的长期命名面已在 Rust route / bridge / storage mapping 中落地，`documents.*` 仍作为 alias/底层 Convex mutation 名称存在，和 Stage 2A/2B 过渡口径基本一致。 | `rust/crates/storage-convex-bridge/src/mapping.rs:37` 到 `:43` 映射 `tree.*`；`:52` 到 `:68` 保留 `documents.*` / `page.*` alias；`rust/crates/mnote-web/src/tree_shell/dispatcher.rs:16` 到 `:23` 使用 `tree.*`；`rust/crates/mnote-web/src/routes/tree.rs:7634` 附近测试确认 documents alias 映射仍存在。 |
+| RK-07 | 实现一致 | 低 | Debug shell 默认关闭，符合 `3104`/debug 壳默认退场口径。 | `rust/crates/mnote-web/src/routes/mod.rs:120` 到 `:124` 仅在 `enable_debug_shell_routes` 时挂 `/tree` 和 `/document-debug`；同文件测试 `:142` 到 `:184` 验证默认 404。 |
+
+## 证据
+
+### 1. Kernel / projection 已落地，但底层仍主要基于 sidebar dataset
+
+- `rust/crates/core-protocol/src/kernel.rs:7` 到 `:42` 定义 `KernelNodeType`、`KernelEdgeType`、`KernelProjectionKind`。
+- `rust/crates/mnote-web/src/routes/kernel.rs:62` 到 `:85` 暴露 projection route，并经 `load_projection_snapshot` 获取投影。
+- `rust/crates/mnote-web/src/routes/snapshot_support.rs:27` 到 `:47` 固定 `sidebar.dataset.list` 为数据获取入口。
+- `rust/crates/bridge-runtime/src/lib.rs:8119` 到 `:8137` 在没有 root 时由当前数据构建 subtree，再生成 projection；`file_tree` 另走 `build_file_tree_projection_result`。
+
+判断：这符合 `1-1` 中“真实主线已落地，但更广义 node pool/reference edge 仍后续”的口径，不应被写成“尚未开始”；也不应被写成“完整 kernel 真源已闭环”。
+
+### 2. Runtime fallback 仍在主路径附近
+
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2379` 到 `:2401`：workspace shell projection 加载失败时合成 `active_workspace_id`、`workspaces`、`documents`。
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2432` 到 `:2461`：`allow_dev_fixtures` 时合成 sidebar dev dataset。
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2493` 到 `:2519`：`allow_dev_fixtures` 时合成 filetree dev dataset。
+- `rust/crates/mnote-web/src/routes/search.rs:233` 到 `:247`：搜索 Convex 查询失败后执行 `fallback_search_dataset(workspace_id)`。
+
+判断：这与 `design/03-rust-web/process/3-15-runtime-fallback-retirement-checklist-v1.md` 的“默认运行时不再 fallback / 不静默降级”存在偏差。尤其 Search fallback 会产生看似真实的固定结果，风险高于空状态降级。
+
+### 3. Page Aggregate 是 Rust route，但仍是迁移期 adapter
+
+- `rust/crates/mnote-web/src/routes/mod.rs:53` 到 `:56` 挂载 `/api/page-aggregate/{document_id}`。
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2264` 到 `:2319` 构建 aggregate。
+- `rust/crates/bridge-runtime/src/lib.rs:5291` 到 `:5442` 从 meta/content 形状构建 `PageAggregateProjection`。
+- `rust/crates/core-protocol/src/page_aggregate.rs:4` 到 `:10` 协议层仍保留 `KernelProjection`、`CompatMetaContentJoin`、`Fixture` 三种 source。
+- `rust/crates/mnote-web/src/page_aggregate/builder.rs:66` 默认 source 仍是 `CompatMetaContentJoin`，但当前检索未发现该 builder 进入主要 route 主路径。
+
+判断：当前代码已摆脱 TS builder runtime 主链，但还不是“页面域全部直接来自独立 kernel storage 真源”。文档应保留“Rust-first Page Aggregate 过渡态”的精确口径。
+
+### 4. Tree realtime 主链已成立，但不是完整实时闭环
+
+- `rust/crates/mnote-web/src/routes/mod.rs:113` 挂载 `/api/tree/events`，`:114` 挂载 `/api/stream/events`，`:115` 挂载 `/api/realtime/ws`。
+- `rust/crates/mnote-web/src/routes/sse.rs:127` 到 `:146` 给 `/api/tree/events` 打 `x-mnote-web-owner: mnote-web` 与 `x-mnote-tree-stream-owner: rust-web`。
+- `rust/crates/mnote-web/src/routes/sse.rs:51` 到 `:91` 通过 sleep/poll bridge overview 发现变化。
+- `rust/crates/mnote-web/src/routes/ws.rs:32` 到 `:80` WebSocket 当前只发 snapshot，并响应 resync 请求。
+
+判断：这与 `3-3` 中“已完成 route / snapshot / delta / resync 基础，WS 尚未成为主链，live cache 未完全统一”一致；若 `3-15` 写成 tree realtime 补偿链已完全删除，则偏乐观。
+
+### 5. Compat / legacy 未成为默认主链，但未完全删除
+
+- `rust/crates/mnote-web/src/app.rs:42` 到 `:54` 仍读取 legacy Next 相关环境变量，默认 `enable_legacy_next_compat` 为 false。
+- `rust/crates/mnote-web/src/routes/gateway.rs:86` 到 `:87` 在 compat 开启且配置 legacy base URL 时，`/api/auth` 可走 legacy proxy。
+- `rust/crates/mnote-web/src/routes/documents.rs:153` 当前 `should_proxy_via_next` 返回 false，说明文档 API 默认不走 Next proxy。
+
+判断：代码实际状态更像“默认关闭、残留显式迁移/调试能力”，不是“所有 legacy proxy 代码已删除”。
+
+## 建议优先级
+
+### P0
+
+- 移除或显式隔离 Search 的 `fallback_search_dataset`。失败时应返回明确错误或空 projection，并带可观测错误头；不要返回固定假结果。
+- 对 `load_workspace_shell_projection` 的无条件合成 dataset 做决策：若用于首屏容错，应在响应或 contract 中显式标记 degraded；若严格执行 fallback 退场，应改为失败或空树，不再伪装成真实 workspace projection。
+
+### P1
+
+- 将 `allow_dev_fixtures` 相关 fallback 全部加上更明确的 debug/dev 标识，并确认 `desktop:hot` / 3000 默认启动链不会误开。
+- 补一条 Rust Web smoke：Convex/query 不可用时，搜索、Sidebar、filetree 不应返回假业务数据。
+- Page Aggregate 文档补一句：当前 Rust route 已是主读链，但底层仍通过 Rust runtime adapter 消费 meta/content substrate；完整页面域单一真源仍在推进。
+
+### P2
+
+- Tree realtime 后续应把 SSE polling overview 与真正 domain event stream 的边界写清楚，并继续推进 page subtree / filetree / preferred snapshot 同一 live cache。
+- Legacy Next proxy 若仍需保留，建议统一命名为 explicit migration/debug boundary；若不再需要，后续单独删除 proxy helper、配置位和测试样例，避免和 `3-15` 的退场状态长期冲突。
+- `PageAggregateSource::CompatMetaContentJoin` / `Fixture` 是否继续保留在 `core-protocol` 需要架构决策：保留则标记为迁移态 source；删除则需先确认没有测试、local folder、fixture 依赖。
+
+## 修改的文件路径
+
+- `/mnt/Data1T/mnote/design/10-review/01-rust-kernel-web-review.md`

design/10-review/02-frontend-editor-tree-review.md

@@ -0,0 +1,123 @@
+# 前端编辑器 / 树体验实现偏差审查
+
+## 范围
+
+本报告只审查 `wolai-frontend` 当前文档页、`leptos-tiptap` island host、`Page Aggregate` 消费链、Sidebar / tree shell / tree stream 与设计文档的一致性。
+
+重点对照设计：
+
+- `ARCHITECTURE.md`
+- `design/01-05-current-priority-overview.md`
+- `design/04-tree-domain/done/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md`
+- `design/04-tree-domain/done/4-2-sidebar-pagetree-filetree-product-interaction-contract-v1.md`
+- `design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md`
+- `design/04-tree-domain/done/4-18-tree-final-dom-shell-cutover-hard-gate-v1.md`
+- `design/04-tree-domain/process/4-23-local-cloud-explicit-bridge-p3-candidate-v1.md`
+- `design/05-editor-mainline/process/5-4-leptos-tiptap-mainline-correction-v1.md`
+- `design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`
+- `design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`
+- `design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`
+
+重点读取代码：
+
+- `wolai-frontend/src/app/(app)/documents/`
+- `wolai-frontend/src/components/editor/`
+- `wolai-frontend/src/lib/documents/`
+- `wolai-frontend/src/components/sidebar/`
+- `wolai-frontend/src/lib/tree-stream/`
+- `wolai-frontend/src/lib/documents/tree-command-client.ts`
+
+## 结论
+
+当前实现总体方向与最新设计主线一致：文档页 SSR 入口已消费 Rust `mnote.page_aggregate.v1`，默认主编辑器已折返到页面内 `leptos_tiptap_island`，tree command 前端主调用已进入 `/api/tree/commands` + `tree.*` 元数据口径，Sidebar 的默认 tree shell 已切到 `rust_wasm_dom_shell_host`，并且 `iframe_srcdoc` 只在显式 legacy flag 下存在。
+
+但不能把当前状态描述为“前端编辑器 / 树体验已经完全收口到 Rust 单一真源”。主要未完成点集中在三处：页面本地 aggregate reducer 仍承担临时真相与补偿选择，`pageSubtree` 在本地正文变更后会被置空而不是形成同一份可持续 projection，Sidebar 仍通过 initial / query / tree stream 三源 freshness 选择维持一致性。此外，部分页面设置仍明确是 `planned` / `downgrade`，属于设计清单中尚未完成的范围。
+
+## 关键发现表格
+
+| 编号 | 分类 | 严重度 | 发现 | 证据 |
+| --- | --- | --- | --- | --- |
+| F-01 | 未完成 | 中 | Page Aggregate 读链已 Rust-first，但客户端仍有本地 aggregate reducer 持有标题、正文、设置、子树快照等临时真相；设计中的“页面域单一真源”尚未闭环。 | `wolai-frontend/src/components/editor/page-aggregate-client-state.ts:7` 定义本地 `PageAggregateClientState`，包含 `serverPageTitle / persistedPageTitle / draftPageTitle / options / content / serverPageSubtreeSnapshot / contentRevision / conflictDetectionKey`；`wolai-frontend/src/components/editor/document-content.tsx:144` 使用 reducer 作为文档页核心状态。 |
+| F-02 | 实现偏差 | 中 | `pageSubtree` 不是跟随本地正文和标题持续更新的 page projection；一旦本地正文对象与服务器快照不同，就直接返回 `null`，AI 面板和阅读结构面会失去这份 projection。 | `wolai-frontend/src/components/editor/page-aggregate-client-state.ts:163` 通过 `content === serverContentSnapshot` 判断；`wolai-frontend/src/components/editor/page-aggregate-client-state.ts:166` 只有未改动时返回 `serverPageSubtreeSnapshot`，否则 `:169` 返回 `null`；`wolai-frontend/src/components/editor/document-content.tsx:867` 将该选择结果作为 AI snapshot 的 `pageSubtree` 来源，`:1162` 也传给阅读视图。 |
+| F-03 | 未完成 | 中 | Sidebar / Breadcrumb / 文档页头已共享 preferred snapshot，但 live cache 仍不是唯一来源；当前仍在 initial、query refetch、tree stream 之间做 freshness 选择。 | `wolai-frontend/src/components/app-layout-shell.tsx:20` 同时创建 `useSidebarData` 与 `useSidebarTreeStream`；`:22` 用 `usePreferredSidebarSnapshot` 选择；`wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts:29` 在 `query / tree_stream / initial` 间选择；`wolai-frontend/src/components/sidebar/sidebar.tsx:201` Sidebar 内部也消费同样选择结果。 |
+| F-04 | 未完成 | 低 | 页面设置运行时语义已有代码级分类，但仍有正式 UI 中可见的 planned / downgrade 项；这与 `5-6` 清单中“页面设置未整体收口”的口径一致。 | `wolai-frontend/src/lib/documents/page-option-semantics.ts:60` 将 `protectEditing` 标记为 `planned`，`:84` 将 `showBlockRefCount` 标记为 `planned`；`wolai-frontend/src/components/editor/page-options-sidebar.tsx:416` 对 downgrade 项显示 `待接线`，`:71` 让 `showBlockRefCount` 成为不可交互占位。 |
+| F-05 | 方向变化/文档滞后 | 低 | `5-5-1` 中仍写着 `showHeadingNumbers / embedDefaultBlockId` 只完成字段贯通，但当前代码已把它们纳入 island runtime payload；这里更像文档滞后，而不是实现偏差。 | `design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md` 第 2.3 节仍说明两项“不可描述成正式支持”；`wolai-frontend/src/lib/documents/page-option-semantics.ts:48` 与 `:88` 均标记为 `wired`；`:121` 的 `pickLeptosTiptapRuntimePageOptions` 会把 `showHeadingNumbers / embedDefaultBlockId` 传给 island，`wolai-frontend/src/components/editor/leptos-tiptap-island-editor-host.tsx:717` 运行时更新这些选项。 |
+| F-06 | 风险 | 低 | Tree final DOM shell 默认路径已符合 `4-18`，但 legacy iframe host 仍可被环境变量显式打开；后续需要保持负向 smoke，防止默认路径回退。 | `wolai-frontend/src/components/sidebar/tree-shell-host.tsx:131` 默认 `rust_family` 且有 workspace 时使用 DOM host，`:133` 仅在 `NEXT_PUBLIC_TREE_SHELL_LEGACY_IFRAME_HOST=1` 时启用 legacy iframe；`wolai-frontend/src/components/sidebar/tree-shell-host.test.tsx:182` 覆盖默认不能进入 `iframe_srcdoc`，`:199` 覆盖显式 legacy flag。 |
+
+## 证据
+
+### 已对齐部分
+
+1. 文档页读取主链已进入 Rust Page Aggregate。
+   - `wolai-frontend/src/app/(app)/documents/[id]/page.tsx:51` 调用 `loadPageAggregateFromNextHeaders`。
+   - `wolai-frontend/src/lib/documents/page-aggregate-loader.ts:170` 请求 `/api/page-aggregate/:id`。
+   - `wolai-frontend/src/lib/documents/page-aggregate-loader.ts:130` 校验 schema 必须是 `mnote.page_aggregate.v1`。
+   - `wolai-frontend/src/lib/documents/page-aggregate-loader.ts:225` 的 `loadPageAggregate` 只返回 Rust snapshot，不再在运行时 fallback 到 TS builder。
+
+2. 默认编辑器 host 已是页面内 `leptos_tiptap_island`。
+   - `wolai-frontend/src/components/editor/editor-host-config.ts:1` 只保留 `EditorHostKind = "leptos_tiptap_island"`。
+   - `wolai-frontend/src/components/editor/editor-host.tsx:7` 动态加载 `leptos-tiptap-island-editor-host`。
+   - `wolai-frontend/src/components/editor/leptos-tiptap-island-editor-host.tsx:619` 直接调用 runtime module 的 `mount(container, ...)`，不是 iframe。
+
+3. 页面写命令已经开始按 page command family 收口。
+   - `wolai-frontend/src/lib/documents/page-command-contract.ts:15` 固定 `page.head.updateTitle / page.layout.updateOptions / page.body.save`。
+   - `wolai-frontend/src/lib/documents/page-command-client.ts:72` 标题写入发送 `commandName: page.head.updateTitle`。
+   - `wolai-frontend/src/lib/documents/page-command-client.ts:89` 页面设置写入发送 `commandName: page.layout.updateOptions`。
+   - `wolai-frontend/src/app/api/documents/save/route.ts:35` 服务端 envelope 使用 `PAGE_COMMAND_NAMES.saveBody`。
+
+4. tree command 前端调用主面已以 `tree.*` 为结果元数据口径。
+   - `wolai-frontend/src/lib/documents/tree-command-client.ts:26` 定义 `tree.node.create / tree.node.rename / tree.subtree.move / tree.node.archive` 等 preferred command。
+   - `wolai-frontend/src/lib/documents/tree-command-client.ts:185` 统一 POST 到 `/api/tree/commands`。
+   - `wolai-frontend/src/app/api/tree/commands/route.ts:205` 由 `action` 分发 tree command，`:278` 创建命令使用 `tree.node.create`。
+
+5. tree final DOM shell 默认路径已符合硬门禁。
+   - `wolai-frontend/src/components/sidebar/tree-shell-host.tsx:139` 默认 implementation 为 `rust_wasm_dom_shell_host`。
+   - `wolai-frontend/src/components/sidebar/tree-shell-surface.tsx:113` 旧 React page tree renderer 已显示为 removed fallback，不再作为正常 renderer。
+   - `wolai-frontend/src/components/sidebar/tree-shell-host.test.tsx:189` 测试断言默认 implementation 是 `rust_wasm_dom_shell_host`，`:194` 断言没有 iframe host。
+
+### 仍需收口部分
+
+1. 客户端 `PageAggregateClientState` 仍是混合态。
+   - 它把 server snapshot、persisted title、draft title、本地 content、server subtree snapshot、revision/conflict key 放在同一个前端 reducer 中。
+   - 这符合当前过渡态，但不等于 Rust page aggregate 已成为页面域唯一运行时真相。
+
+2. `pageSubtree` 与正文编辑没有同源更新。
+   - 本地正文变更只会触发 `apply_local_content_snapshot`，不会同步生成新的 `pageSubtree`。
+   - selector 在内容对象不同于 server snapshot 时返回 `null`，因此 `AI / read view / TOC` 只能等待后续持久化与重新拉取。
+
+3. Sidebar live cache 仍有 freshness 选择层。
+   - `AppLayoutShell` 和 `Sidebar` 都依赖 `usePreferredSidebarSnapshot`。
+   - 当前算法没有基于 Rust stream cursor / projection version 做统一仲裁，而是通过 sync key 与 `treeStreamStatus` 在 `query` 与 `tree_stream` 之间选择。
+
+4. 页面设置中仍有显式未完成项。
+   - `protectEditing` 与 `showBlockRefCount` 的代码状态已经诚实标为 `planned / downgrade`。
+   - 这避免了误导用户，但也说明 `Page Aggregate -> island runtime` 的设置语义还没有完全完成。
+
+## 建议优先级
+
+### P0
+
+暂无需要立即阻断主链的 P0。默认 Page Aggregate 读链、默认 island host、默认 DOM tree shell 均未发现与最新主线相反的实现。
+
+### P1
+
+1. 收口 `pageSubtree` 与本地正文编辑的关系。
+   - 至少明确它是“server projection only”还是“本地编辑也应生成临时 projection”。
+   - 如果 AI 面板需要稳定结构上下文，不应在用户正常编辑后直接拿到 `null`。
+
+2. 将 Sidebar 的三源 preferred snapshot 推进为统一 live cache。
+   - 建议以 Rust stream cursor / projection version / query snapshot version 为仲裁字段，减少仅靠 sync key 的 freshness 判断。
+
+### P2
+
+1. 继续移除或强门禁 legacy tree iframe host。
+   - 当前显式 env flag 符合设计，但应保留负向 smoke，避免后续默认路径误回退。
+
+2. 同步修正文档滞后。
+   - `5-5-1` 对 `showHeadingNumbers / embedDefaultBlockId` 的描述已经落后于当前代码，应在后续文档整理时更新。
+
+3. 页面设置 planned 项保持降级展示，直到真正进入 island runtime 或被产品侧移除。
+
+## 修改的文件
+
+- `/mnt/Data1T/mnote/design/10-review/02-frontend-editor-tree-review.md`

design/10-review/03-convex-realtime-storage-review.md

@@ -0,0 +1,215 @@
+# Convex / Realtime / Storage 实现偏差审查
+
+## 范围
+
+本报告审查 Convex / storage bridge / realtime / Page Aggregate 数据底座与当前设计主线的一致性，重点对照以下方向：
+
+- Convex 保留为自托管 storage / realtime substrate，不作为树语义 owner。
+- Rust kernel / bridge-runtime / mnote-web 持有 tree-first graph、projection、command、Page Aggregate 的语义主导权。
+- `/api/page-aggregate/:id` 作为文档页 Rust-first 读取主链。
+- `/api/tree/events` 作为 Rust Web tree realtime snapshot / delta / resync 主链。
+- 前端只消费稳定 projection、Page Aggregate 与 tree stream，不重新持有第二套对象真相。
+
+重点读取范围：
+
+- `ARCHITECTURE.md`
+- `design/01-05-current-priority-overview.md`
+- `design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md`
+- `design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`
+- `design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`
+- `design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`
+- `design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`
+- `infra/convex/README.md`
+- `wolai-frontend/convex/`
+- `rust/crates/storage-convex-bridge/`
+- `rust/crates/mnote-web/src/transport/convex.rs`
+- `rust/crates/mnote-web/src/routes/documents.rs`
+- `rust/crates/mnote-web/src/routes/tree.rs`
+- `rust/crates/mnote-web/src/routes/sse.rs`
+- `rust/crates/mnote-web/src/routes/stream_support.rs`
+- `wolai-frontend/src/lib/documents/`
+- `wolai-frontend/src/lib/tree-stream/`
+
+## 结论
+
+整体方向与设计主线基本一致：Convex 没有被拆掉，仍承担本地自托管存储、文件和实时底座；Rust Web 已注册 `/api/page-aggregate/:document_id` 与 `/api/tree/events`；前端 tree stream 已直接使用 `EventSource("/api/tree/events")`；Next 的 `/api/documents/page` 与 `/api/mnote-web/stream` 已明确作为 410 compat 边界退场。
+
+但当前实现仍是明显过渡态，主要问题集中在三处：
+
+1. Page Aggregate 读链虽然是 Rust endpoint，但实际数据仍由 `documents:getMeta` + `documents:getContent` 分别取回后在 bridge-runtime 中拼 projection，`source` 标识存在“看起来比真实实现更 canonical”的风险。
+2. Rust Web 的 `/api/documents/title`、`/api/documents/options` 与 Next route 的 page write adapter 在 bridge artifact 记录上不一致；tree stream 依赖 bridgeLogs 时，Rust page write 路径可能漏掉 command/domain event。
+3. `/api/tree/events` 是正式 SSE 入口，但当前 change detection 依赖周期性查询 `bridgeLogs:listWorkspaceOverview`，且 Convex query 内部会按 workspace collect 全量 command/domain rows 后内存过滤排序，实时性和规模风险较高。
+
+## 关键发现表格
+
+| 编号 | 分类 | 严重度 | 发现 | 证据 |
+| --- | --- | --- | --- | --- |
+| F1 | 实现偏差 | 高 | Rust Page Aggregate endpoint 对外是 `mnote.page_aggregate.v1`，但构建过程仍先分别读取 meta/content，再在 bridge-runtime 中拼 projection；`source=KernelProjection` 容易掩盖底层仍是兼容 join。 | `rust/crates/mnote-web/src/routes/web_shell.rs:2282`、`:2291`、`:2301`；`rust/crates/bridge-runtime/src/lib.rs:8246`、`:8252`、`:5291`、`:5303`、`:5386` |
+| F2 | 风险 | 高 | Rust Web 的 title/options 写路由只执行 Convex mutation，不记录 bridge command/domain artifacts；而 tree stream 以 bridgeLogs 为事件来源，主路径 page 写入可能不进入实时流。 | `rust/crates/mnote-web/src/routes/documents.rs:714`、`:802`；`rust/crates/mnote-web/src/routes/command_support.rs:65`；对比 `rust/crates/mnote-web/src/routes/tree.rs:6529` 与 `wolai-frontend/src/lib/documents/page-write-command-adapter.ts:63` |
+| F3 | 风险 | 高 | tree realtime 当前是 SSE transport，但后端通过 `sleep(poll_ms)` 周期性轮询 Convex bridgeLogs，而不是直接利用 Convex subscription/push；默认 2s，实时性和负载都需继续验证。 | `rust/crates/mnote-web/src/routes/sse.rs:25`、`:26`、`:51`、`:58`、`:60`；`rust/crates/mnote-web/src/routes/stream_support.rs:610` |
+| F4 | 风险 | 中高 | `bridgeLogs:listWorkspaceOverview` 会按 workspace collect 全量 `command_logs` 与 `domain_events` 后在内存中过滤、排序、分页；SSE 轮询叠加后，历史日志增长会放大 Convex 读压力。 | `wolai-frontend/convex/bridgeLogs.ts:283`、`:287`、`:292`、`:301`、`:305` |
+| F5 | 方向变化/文档滞后 | 中 | `storage-convex-bridge` 把 `page.aggregate.get` 映射到 `documents:getPageAggregate`，但 Convex `documents.ts` 只发现 `getMeta` / `getContent`，未发现 `getPageAggregate` export；当前真实 Page Aggregate 路线已绕到 Rust adapter。 | `rust/crates/storage-convex-bridge/src/mapping.rs:101`；`wolai-frontend/convex/documents.ts:684`、`:803`；全仓 `rg getPageAggregate` 未发现 Convex 实现 |
+| F6 | 已完成/方向一致 | 中 | Next compat 读链和旧 stream alias 已显式退场，前端 tree stream 直接构造 `/api/tree/events`，符合当前主线口径。 | `wolai-frontend/src/app/api/documents/page/route.ts:17`；`wolai-frontend/src/app/api/mnote-web/stream/route.ts:9`；`wolai-frontend/src/lib/tree-stream/protocol.ts:66`、`:72` |
+| F7 | 未完成 | 中 | Page Aggregate TS builder 已不在 runtime 主链中被引用，但文件仍保留；当前定位应继续写成 fallback / adapter / 测试材料，不能作为运行时主路径描述。 | `wolai-frontend/src/lib/documents/page-aggregate-builder.ts:51`；全仓非测试引用仅剩定义，runtime loader 只调用 Rust snapshot：`wolai-frontend/src/lib/documents/page-aggregate-loader.ts:225` |
+
+## 证据
+
+### 1. Page Aggregate 读链已收口到 Rust endpoint，但仍由 meta/content join 生成
+
+`mnote-web` 注册了正式 endpoint：
+
+- `rust/crates/mnote-web/src/routes/mod.rs:53` 到 `:56` 注册 `/api/page-aggregate/{document_id}`。
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2227` 到 `:2252` 返回 `schema: "mnote.page_aggregate.v1"` 和 `result: aggregate`。
+
+但实际构建流程仍是：
+
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2282` 到 `:2290` 读取 `load_document_meta_result`。
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2291` 到 `:2299` 读取 `load_document_content_result`。
+- `rust/crates/mnote-web/src/routes/web_shell.rs:2301` 到 `:2315` 把 `meta + content` 作为数据传给 `page.aggregate.get`。
+- `rust/crates/bridge-runtime/src/lib.rs:5291` 到 `:5312` 的 `build_page_aggregate_projection_result` 明确从 `data.meta` 和 `data.content` 中拆字段。
+
+这说明“Rust-first 读取主链”成立，但“Page Aggregate 已经由 kernel 原生投影独立产出”仍未成立。该点与 `5-5/5-6` 的过渡态判断一致，但需要在后续文档和汇报中保持精确。
+
+需进一步验证：`PageAggregateSource::KernelProjection` 是否应在这种 `meta/content join` 场景下继续使用，还是应保留 `CompatMetaContentJoin` 以避免 provenance 误导。
+
+### 2. Page write side effects 在 Rust route 与 Next adapter 之间不一致
+
+Next route 侧：
+
+- `wolai-frontend/src/app/api/documents/title/route.ts:58` 调用 `executePageWriteBridgeCommand`。
+- `wolai-frontend/src/app/api/documents/options/route.ts:47` 调用 `executePageWriteBridgeCommand`。
+- `wolai-frontend/src/app/api/documents/save/route.ts:43` 调用 `executePageWriteBridgeCommand`。
+- `wolai-frontend/src/lib/documents/page-write-command-adapter.ts:63` 到 `:69` 成功后调用 `recordRustBridgeCommandArtifacts`。
+
+Rust route 侧：
+
+- `rust/crates/mnote-web/src/routes/documents.rs:579` 的正文保存使用 `execute_runtime_command_via_convex_with_artifacts`。
+- `rust/crates/mnote-web/src/routes/documents.rs:714` 的标题更新使用 `execute_runtime_command_via_convex`。
+- `rust/crates/mnote-web/src/routes/documents.rs:802` 的页面设置更新使用 `execute_runtime_command_via_convex`。
+- `rust/crates/mnote-web/src/routes/command_support.rs:65` 到 `:73` 的 `execute_runtime_command_via_convex` 只执行 Convex command plan，不持久化 artifacts。
+- `rust/crates/mnote-web/src/routes/command_support.rs:75` 到 `:93` 的 artifact 版本才会调用 `execute_convex_command_plan_with_artifacts`。
+
+tree command route 是一致的：
+
+- `rust/crates/mnote-web/src/routes/tree.rs:6529` 使用 `execute_runtime_command_via_convex_with_artifacts`。
+
+风险是：如果当前 3000 主入口走 Rust Web `/api/documents/title` 或 `/api/documents/options`，这些 page 写入不会进入 `command_logs/domain_events`，而 `/api/tree/events` 正是通过 bridgeLogs 检测变化。标题类写入尤其可能影响 sidebar/breadcrumb/page tree 的实时一致性。
+
+需进一步验证：当前文档页标题编辑在 3000 主壳中到底走 `/api/documents/title` 还是 `/api/tree/commands`；如果走前者，应补 Rust route artifact 记录或统一到 tree/page command route。
+
+### 3. Tree realtime 是正式 SSE 入口，但实现仍是 polling-backed stream
+
+正式入口成立：
+
+- `rust/crates/mnote-web/src/routes/mod.rs:130` 注册 `/api/tree/events`。
+- `rust/crates/mnote-web/src/routes/sse.rs:127` 到 `:146` 给 tree events 加 `x-mnote-tree-stream-owner: rust-web`。
+- `wolai-frontend/src/lib/tree-stream/protocol.ts:66` 到 `:77` 构造 `/api/tree/events` URL。
+- `wolai-frontend/src/lib/tree-stream/use-sidebar-tree-stream.ts:136` 到 `:143` 用 `EventSource` 监听 `snapshot/delta/resync`。
+
+但服务端 change detection 是轮询：
+
+- `rust/crates/mnote-web/src/routes/sse.rs:25` 到 `:26` 读取 `max_polls` 和 `poll_ms`，默认 `2000ms`，最低 `250ms`。
+- `rust/crates/mnote-web/src/routes/sse.rs:51` 到 `:58` 循环中 `sleep(Duration::from_millis(poll_ms))`。
+- `rust/crates/mnote-web/src/routes/sse.rs:60` 到 `:67` 每轮调用 `load_stream_overview` 再 `resolve_stream_change`。
+- `rust/crates/mnote-web/src/routes/stream_support.rs:610` 到 `:625` 的 `load_stream_overview` 通过 `bridge.workspace.overview` 查询 Convex。
+
+这与“Rust Web 提供正式实时 transport”一致，但还不是“基于 Convex realtime subscription 的 push stream”。短期可接受为过渡实现，长期如果继续承载主链，需要明确性能和延迟边界。
+
+### 4. bridgeLogs overview 查询存在规模风险
+
+`wolai-frontend/convex/bridgeLogs.ts` 的 `listWorkspaceOverview`：
+
+- `:283` 到 `:286` 按 workspace 查询并 `collect()` 所有 `command_logs`。
+- `:287` 到 `:290` 按 workspace 查询并 `collect()` 所有 `domain_events`。
+- `:292` 到 `:301` 在内存中过滤、排序、切片 command logs。
+- `:303` 到 `:312` 再用 commandId 集合过滤 domain events。
+
+该实现作为调试/小数据过渡可以工作，但被 `/api/tree/events` 默认每 2 秒调用时，日志增长后会造成：
+
+- Convex query 读放大。
+- SSE 连接数量增加时成倍放大。
+- cursor 语义依赖内存排序，历史数据规模变大后容易出现延迟或超时。
+
+建议后续至少增加按 `workspace_id + created_at/id` 的索引分页，避免每次 stream poll 全量扫描。
+
+### 5. storage-convex-bridge 中存在疑似过时的 `page.aggregate.get` 映射
+
+`rust/crates/storage-convex-bridge/src/mapping.rs:101`：
+
+```text
+"page.aggregate.get" => "documents:getPageAggregate"
+```
+
+但当前 `wolai-frontend/convex/documents.ts` 中只发现：
+
+- `getMeta`：`wolai-frontend/convex/documents.ts:684`
+- `getContent`：`wolai-frontend/convex/documents.ts:803`
+
+全仓搜索未发现 Convex `documents:getPageAggregate` 实现。当前真实 Page Aggregate 读取是 Rust Web 先读 meta/content，再由 bridge-runtime 生成 projection。因此该映射要么是未来目标，要么已经滞后；如果有代码路径直接通过 storage-convex-bridge 执行 `page.aggregate.get`，会存在运行时函数不存在风险。
+
+需进一步验证：`storage-convex-bridge` 是否仍有生产路径直接执行 `page.aggregate.get -> documents:getPageAggregate`；如果没有，应把映射标注为 future/stale，或改为当前真实读链。
+
+### 6. Convex substrate 定位总体一致
+
+正向证据：
+
+- `infra/convex/README.md` 明确自托管 Convex backend/dashboard、HTTP Actions 和文件存储。
+- `wolai-frontend/convex/schema.ts:35` 到 `:91` 的 `documents` 表继续承接页面结构、正文、页面设置、统计字段。
+- `wolai-frontend/convex/schema.ts:121` 到 `:162` 的 `media_assets` 与 `_storage` 字段保留文件底座。
+- `rust/crates/storage-convex-bridge/README.md:5` 到 `:13` 明确 bridge 只做协议到 Convex 读写请求映射，不复制主事实层、不维护第二数据库。
+
+这与“Convex 不拆，Rust 收口语义”的设计一致。
+
+## 建议优先级
+
+### P0：修正 Rust page write route 的 artifact 一致性
+
+目标：让当前 3000 主入口的 `/api/documents/title`、`/api/documents/options` 至少在 side effect 上与 Next `page-write-command-adapter` 保持一致。
+
+建议：
+
+- 将 `rust/crates/mnote-web/src/routes/documents.rs` 中 title/options 的 `execute_runtime_command_via_convex` 改为 artifact 版本，或统一复用 tree/page command route。
+- 对标题更新补最小回归：更新标题后 `bridgeLogs:listWorkspaceOverview` 能看到对应 command/domain event，`/api/tree/events` 能输出 delta 或 resync。
+- 对 artifact 写失败的策略重新定级：当前 `rust/crates/mnote-web/src/transport/convex.rs:759` 到 `:770` 是主 mutation 成功、artifact 失败仍返回成功；对 tree-relevant command 至少应打可观测错误并触发保守 resync。
+
+### P1：收口 Page Aggregate provenance
+
+目标：避免把 `meta/content join` 误标为已完成的 kernel-native projection。
+
+建议：
+
+- 明确 `PageAggregateSource::KernelProjection` 与 `CompatMetaContentJoin` 的使用边界。
+- 如果 `build_page_aggregate_snapshot` 仍通过 `load_document_meta_result + load_document_content_result` 构建，应在返回 source 或 header 中反映真实来源。
+- 如果目标是 kernel-native projection，则补正式 kernel/query 数据路径，避免 route 层长期手工拼装。
+
+### P1：优化 tree stream 的 Convex 查询模型
+
+目标：让 `/api/tree/events` 可以长期承载主链，而不是随着日志增长退化。
+
+建议：
+
+- 为 `command_logs`、`domain_events` 增加按 `workspace_id + created_at/id` 的查询索引和 cursor 查询。
+- `listWorkspaceOverview` 不再 `collect()` 全量 workspace 日志后内存分页。
+- 明确 polling-backed SSE 是过渡实现，还是长期 realtime transport；若长期使用，应补连接数、日志量、延迟上限的 smoke/bench。
+
+### P2：清理或标注 stale mapping
+
+目标：降低后续 worker 误用 `page.aggregate.get -> documents:getPageAggregate` 的风险。
+
+建议：
+
+- 若 `documents:getPageAggregate` 不计划实现，移除或注释 `storage-convex-bridge` 中的映射。
+- 若计划实现，补 Convex query 与最小测试，并让 mnote-web Page Aggregate route 直接消费它或说明为什么不消费。
+
+### P2：保留 Next compat 退场边界，但避免双实现继续发散
+
+目标：Next route 继续作为 legacy/adapter 参考时，不与 Rust Web 主入口形成不同 side effects。
+
+建议：
+
+- 对 `/api/documents/title/options/save` 明确 owner：Rust Web 主路径与 Next legacy 路径只能有一份 canonical side-effect 规则。
+- 对 `wolai-frontend/src/lib/documents/page-aggregate-builder.ts` 保留测试/adapter 标签，避免被重新接回 runtime 主链。
+
+## 修改的文件路径
+
+- `design/10-review/03-convex-realtime-storage-review.md`

design/10-review/04-secondary-domains-and-design-governance-review.md

@@ -0,0 +1,64 @@
+# 次级域与设计治理实现偏差审查
+
+## 范围
+
+本次只审查 Mindmap、AI、OnlyOffice、Wolai-aline、SiYuan reference，以及 `design/process/done` 治理口径与当前实现方向的一致性。重点读取了 `ARCHITECTURE.md`、`design/README.md`、`design/06-mindmap/process/*`、`design/07-ai/process/*`、`design/08-wolai-aline-test-flow/process/wolai-aline-test-flow-v1.md`、`design/09-siyuan-reference/process/9-siyuan-reference-boundary-and-adoption-v1.md`、`design/90-reference/*`，并对照了 Mindmap、AI route/lib、OnlyOffice route/adapter 与相关 Convex/Rust runtime 代码。
+
+## 结论
+
+总体方向与当前主线基本一致：Mindmap 已明确降为 `tree-first graph kernel` 的视图/编辑挂件，AI 主执行面正在向 `mnote-cli` 收口，OnlyOffice 仍是独立页面型编辑器边界，SiYuan 参考稿没有发现被提升为上位架构来源的证据。
+
+主要风险集中在三处：OnlyOffice 在 `mnote-web` 主入口里的 callback/forcesave 仍是 no-op，而 legacy Next route 已有真实写回链；Mindmap 的导出 action 在 schema/action map 中暴露，但 bridge 安全命令集不支持；Mindmap AI 补完 route 当前硬返回 501，和 Rust tool 已登记的能力面不闭合。
+
+## 关键发现表格
+
+| ID | 分类 | 级别 | 发现 | 简短证据 | 建议 |
+| --- | --- | --- | --- | --- | --- |
+| F-01 | 实现偏差 / 风险 | P1 | OnlyOffice `mnote-web` 主入口已挂载 callback/forcesave，但当前实现不写回，只返回成功或 noop，可能让 3000 主链下的 OnlyOffice 保存丢失。 | `rust/crates/mnote-web/src/routes/mod.rs:78-84` 挂载 `/api/onlyoffice/callback` 与 `/api/onlyoffice/forcesave`；`rust/crates/mnote-web/src/routes/onlyoffice.rs:717-759` callback 只记录日志并返回 `{error:0}`，forcesave 返回 `mnote-web-rust-noop`；而 `wolai-frontend/src/app/api/onlyoffice/callback/route.ts:93-192` 有真实 Convex 写回链。 | 优先把 Rust route 接到 `onlyoffice_prepare_callback` / media asset writeback，或显式把该路由代理到 legacy Next，避免主入口 shadow 掉真实写回。 |
+| F-02 | 未完成 | P2 | Mindmap `export` 动作暴露给 UI action map，但 simple-mind-map 安全执行器不允许 `EXPORT`，默认路径可能显示能力却执行失败。 | `wolai-frontend/src/lib/mindmap/mindmap-action-map.ts:65` 将 `export` 映射为 runtimeCommand `EXPORT`；`wolai-frontend/src/lib/mindmap/simple-mind-map-bridge.ts:119-129` 的 `SIMPLE_MIND_MAP_SAFE_COMMANDS` 不包含 `EXPORT`。 | 要么把 `EXPORT` 加入安全命令并补 smoke，要么在 UI state 中继续禁用导出并标注为延期。 |
+| F-03 | 未完成 / 方向变化 | P2 | Mindmap AI 补完 route 当前直接 501，后续大段旧 Supabase/在线 AI 实现被注释；但 Rust tool registry 已登记 `mindmap_expand_node`，形成“工具存在、产品入口不可用”的断层。 | `wolai-frontend/src/app/api/mindmap-ai/expand-node/route.ts:90-97` 校验后直接返回 `501`；同文件后续注释块仍保留旧 Supabase/AI 逻辑；`rust/crates/core-protocol/src/tool.rs:231-240` 与 `rust/crates/bridge-runtime/src/lib.rs:3803-3812` 已有 `mindmap_expand_node`。 | 若该能力仍在 Phase 6/7 范围内，应按 CLI/Rust bridge 路线重接；若延期，应把 route 标成 retired/debug，避免前端或测试误以为可用。 |
+| F-04 | 方向变化 / 文档滞后 | P2 | AI 主 Web route 已收口到 `mnote-cli` host，但 `wolai-backend` 仍暴露 `openai_agents_python` 文档 agent route 与旧工具面；是否仍部署为可访问入口需进一步验证。 | `wolai-frontend/src/app/api/ai-agent/run/route.ts:36-57` 明确拒绝 codex/hermes/claudecode 并进入 `startMnoteCliAgentHostRun`；`wolai-backend/app/routers/ai_agent.py:34-57` 仍暴露 `/ai-agent/health`、`/ai-agent/document/run`，health 返回 `bridge: openai_agents_python`；`wolai-backend/app/services/ai_document_agent.py:1174-1470` 仍指令 agent 使用 `doc_insert_blocks`、`doc_replace_range`、`slash_run`。 | 在设计或代码注释中明确该后端只作为可插拔外置 agent/对照链；若不再使用，补退场计划和访问边界，尤其确认 `mnote_ai_orchestrator_api_key` 未配置时的开放行为。 |
+| F-05 | 文档治理风险 | P3 | `design/90-reference` 符合“参考资料”目录定位，但内容仍带有问答式残留，容易被后续 worker 误用为正式设计结论。 | `design/README.md` 明确 `90-reference/` 不参与 process/done 状态判断；`design/90-reference/90-1-filetree.md` 末尾保留“需要我给你...”类对话尾巴；`design/90-reference/90-2-yemianshu.md` 同样保留示例请求口吻。 | 低优先级清理为中性参考笔记，并在引用时强制以 `ARCHITECTURE.md` 和主线设计为上位依据。 |
+
+## 证据
+
+### Mindmap
+
+- 设计口径清晰：`design/06-mindmap/process/6-mindmap-kernel-phase6-projection-editor-v1.md` 明确 Phase 6 主线是 `Rust kernel truth -> mindmap.simple_mind_map_scene.v1 -> leptos-mindmap editor island -> simple-mind-map runtime -> command bridge`，并禁止把 runtime data 当唯一事实源。
+- 实现已对齐主线壳：`rust/crates/mnote-web/src/routes/mindmap_shell.rs:105-123` 输出 `mnote.mindmap_shell.v1`、`mindmap.simple_mind_map_scene.get` 与 `mindmap.command.apply`；`rust/crates/mnote-web/src/ssr/pages/mindmap.rs:50-56` 提供 standalone island 挂载点。
+- 旧 React 块已自我标注为 legacy/compat/reference：`wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx:3-5` 明确 3000 文档页默认主链是 `leptos-tiptap NodeView + leptos-mindmap adapter`。
+- 仍有 compat 数据层：`wolai-frontend/convex/schema.ts:164-184` 的 `mindmaps.data: v.any()` 仍承载导图数据；这与当前过渡态兼容，但不应被描述为长期 canonical truth。
+
+### AI
+
+- CLI-first 入口基本对齐：`wolai-frontend/src/app/api/ai-agent/run/route.ts:36-57` 将默认执行入口限定到 `mnote-cli host`，拒绝旧 provider。
+- 结构化 artifact 设计仍有未完成项：`design/07-ai/process/7-phase7-ai-kernel-projection-plan-v4.md` 中“后续权限收口”仍未勾选，说明 AI 写链权限模型尚未完全闭环。
+- 旧后端 agent 仍存在：`wolai-backend/app/routers/ai_agent.py:47-57` 仍提供 streaming run；这可作为外置 agent，但需要避免被误认为长期默认主编排。
+
+### OnlyOffice
+
+- 正确边界已有：`rust/crates/adapter-onlyoffice/src/lib.rs:124-126` 明确 adapter 只定义资产定位、会话、签名、代理、callback/forcesave 边界，不把 OnlyOffice 变成主事实层。
+- `mnote-web` 页面是独立编辑页：`rust/crates/mnote-web/src/routes/onlyoffice.rs:325-630` 直接渲染 `/onlyoffice`，通过 DocsAPI 创建编辑器，未嵌入正文主编辑画布。
+- 关键风险是写回链 owner 分裂：Rust 主入口 no-op 与 legacy Next 真写回并存，见 F-01。
+
+### Wolai-aline
+
+- 流程文档严格要求“Wolai 基线 -> RED smoke -> 小范围实现 -> 本地验证 -> subagent 复测 -> 主线程截图复核”：`design/08-wolai-aline-test-flow/process/wolai-aline-test-flow-v1.md`。
+- 本次不是具体 Wolai 对标实现任务，未执行浏览器对标；未发现该流程被错误提升为产品架构来源。
+
+### SiYuan Reference
+
+- `design/09-siyuan-reference/process/9-siyuan-reference-boundary-and-adoption-v1.md` 的边界与当前主线一致：思源只作为产品能力与交互参考，不替代 `tree-first graph kernel`、Rust kernel、Page Aggregate、tree command 与 tree realtime。
+- 当前只读检索未发现将 SiYuan `.sy`、SQL API 或前端 runtime 直接提升为 mnote 长期事实源的实现证据；若后续新增属性视图/数据库视图，应继续先做对象域评估。
+
+## 建议优先级
+
+1. P1：补齐或明确代理 OnlyOffice Rust callback/forcesave 写回链，避免主入口下保存成功但内容未持久化。
+2. P2：收口 Mindmap action 可用性，先修 `export` 映射与安全命令不一致，再继续扩展 UI 能力。
+3. P2：处理 Mindmap AI route：要么按 Rust bridge/CLI-first 重接 `mindmap_expand_node`，要么显式退役该 Next route。
+4. P2：明确 `wolai-backend` AI agent 的外置/对照定位与访问边界，避免与 `mnote-cli` 唯一执行面口径冲突。
+5. P3：清理 `design/90-reference` 的问答残留，并在引用规范里再次强调它不是 process/done 设计稿。
+
+## 本次修改文件
+
+- `/mnt/Data1T/mnote/design/10-review/04-secondary-domains-and-design-governance-review.md`

design/10-review/05-tree.md

@@ -0,0 +1,152 @@
+结论
+  我基本同意你的方向，但要把“文件树为根源”说得更精确：不应让“文件树 UI 组件”成为真源，而应让 Rust kernel 中的 workspace resource tree / file tree projection 背后
+  的资源层级 成为页面、附件、mindmap、OnlyOffice 等对象的组织根源。页面树则是从这棵资源/对象树派生出的导航投影，类似快捷方式、收藏视图或文档视图。
+
+  对当前 bug 来说，最核心的规则应固定为：
+
+  1. index.md 只代表页面正文，即 Page Aggregate body。
+  2. mindmap 不是主编辑区正文替身，而是页面内某个 block 关联的 object / asset editor。
+  3. 文件树点击 mindmap 应打开 mindmap object editor，不能被 index.md 吞掉，也不能用临时 mindmap-only bootstrap 覆盖真实页面正文。
+  4. 页面树不应再持有独立结构真相，只显示“文档导航关系”；文件树显示“资源组织关系”。
+
+  主编辑区与插件
+  主编辑区应该是一个工作区 tab host，而不是只等于文档正文编辑器。index.md 是其中一种 tab，mindmap、OnlyOffice、附件预览、代码附件都是其他 object tab/model。
+
+  Siyuan 这里值得借鉴：doc 和 asset 是不同 model/tab，asset 打开不伪装成 doc 正文；插件、widgets、assets、.sy 文档也在存储层分开。mnote 也应采用类似原则：插件/附
+  件/mindmap 可以嵌入页面，但它们的持久化真源不能变成页面正文本身，只能通过 block-asset relation 被 Page Aggregate 引用。
+
+  文件树与页面树
+  我建议改成三层表述：
+
+  - Resource Tree：长期 canonical 对象组织树，Rust kernel 持有语义，Convex 只是底层存储。
+  - File Tree：Resource Tree 的主组织投影，展示页面文件夹、index.md、附件、mindmap、OnlyOffice、代码附件等。
+  - Page Tree：面向阅读/导航的快捷投影，只显示页面关系，不拥有排序、父子、附件归属的最终真相。
+
+  这样你的“文件树为根源”可以落地，但不会和现有 tree-first graph kernel 冲突。更准确地说：文件树背后的 resource hierarchy 是根源，页面树是它的页面导航视图。
+
+  建议路线
+  短期先修当前 bug：保留 /mindmap/{doc}/{asset} 作为 object editor，但彻底隔离草稿 key、保存 command 和 Page Aggregate body，smoke 必须真实网页验证“点击 mindmap、
+  编辑长中文、保存、切回 index.md、再打开 mindmap 内容仍在”。
+
+  中期做主编辑区 asset tab：index.md | mindmap.json | xxx.docx，每个 tab 有自己的 object identity 和保存命令。
+
+  长期补 resource projection / block-asset relation：文件树 row、页面内 mindmap block、mindmap projection 必须来自同一关系索引，而不是前端临时按路由拼。
+
+
+
+  推荐路线
+  我建议采用“分阶段收口 Resource Tree”的方案，不做一次性大重构。
+
+  可选方案有三种：
+
+  - 只修 mindmap bug：最快，但会继续留下页面树/文件树真源分裂。
+  - 分阶段建立 Resource Tree -> File Tree/Page Tree projection：最稳，能解决当前 bug，也能承接附件、OnlyOffice、插件对象。
+  - 全量重写 tree/page/resource 模型：理论干净，但当前工作区和主链都很活跃，风险太高。
+
+  我推荐第二种。
+
+  阶段 0：冻结合同
+  先把 design/10-review/05-tree.md 升级为正式设计合同，建议后续移动或补一份到：
+
+  - design/04-tree-domain/process/4-24-resource-tree-filetree-pagetree-source-contract-v1.md
+  - 或 design/05-editor-mainline/process/5-11-main-editor-object-tab-resource-tree-alignment-v1.md
+
+  合同里固定四句话：
+
+  - Resource Tree 是组织真源。
+  - File Tree 是资源组织主投影。
+  - Page Tree 是页面导航投影/快捷视图。
+  - index.md、mindmap、OnlyOffice、附件是不同 object model，不能互相伪装。
+
+  阶段 1：先关闭当前 mindmap bug
+  目标：文件树 mindmap 仍可编辑保存，但不污染 index.md。
+
+  重点文件：
+
+  - rust/crates/mnote-web/src/ssr/pages/layout.rs
+  - rust/crates/mnote-web/src/routes/mindmap_shell.rs
+  - rust/spikes/leptos-tiptap-spike/src/lib.rs
+  - scripts/task169-mindmap-realtime-smoke.js
+
+  验收必须是真实浏览器链路：
+
+  1. 从文件树点击 mindmap asset。
+  2. 进入明确的 mindmap object editor。
+  3. 输入长中文并保存。
+  4. 切回同页 index.md，正文仍是 Page Aggregate body。
+  5. 再打开 mindmap，刚才内容仍在。
+  6. 确认没有用真实 documentId 写 standalone 草稿 key。
+
+  阶段 2：补 Resource Projection 协议
+  在 Rust 协议层明确资源节点和 block-asset 关系。
+
+  建议新增或扩展：
+
+  - ResourceNode
+  - ResourceKind: page | index | mindmap | attachment | onlyoffice | code
+  - ObjectIdentity: { objectKind, documentId, blockId?, assetId? }
+  - BlockAssetRelation: { documentId, blockId, assetId, assetKind }
+
+  落点优先看：
+
+  - rust/crates/core-protocol/
+  - rust/crates/bridge-runtime/
+  - rust/crates/mnote-web/src/tree_shell/
+
+  这个阶段不要求立刻迁移所有数据，只要协议和 projection 能表达清楚。
+
+  阶段 3：让 File Tree 从 Resource Tree 派生
+  当前 file tree 已有 resourceMeta、assetKind、file_tree projection 基础。下一步是收口为：
+
+  - 页面节点下面固定有 index.md
+  - mindmap/附件/OnlyOffice 都是同一 Resource Tree 下的 child resource
+  - 文件树 row 不再临时从多份前端数据拼出第二真相
+
+  同时保留 tree.asset.open，但它必须只表达 object open intent，不直接决定“把谁当正文”。
+
+  阶段 4：Page Tree 降级为导航投影
+  Page Tree 不再拥有资源归属、附件归属、mindmap 归属。它只显示页面导航关系：
+
+  - 页面标题
+  - 页面层级
+  - 快捷入口/收藏/最近打开这类导航语义
+
+  如果页面树需要显示某个资源状态，也只读 Resource Projection，不自己维护。
+
+  阶段 5：主编辑区变成 Object Tab Host
+  这是中期关键体验：
+
+  - index.md tab：加载 Page Aggregate body。
+  - mindmap.json tab：加载 mindmap projection/command。
+  - xxx.docx tab：打开 OnlyOffice object editor。
+  - attachment tab：预览/代码编辑/外部打开。
+
+  这样 mindmap 不会被 index.md 吞掉，也不会伪装成正文。
+
+  阶段 6：命令面统一
+  后续命令应逐步收口到：
+
+  - tree.asset.attach
+  - tree.asset.detach
+  - tree.resource.rename
+  - tree.resource.move
+  - page.body.save
+  - mindmap.command.apply
+
+  关键规则：改资源关系走 tree/resource command，改页面正文走 page command，改导图内容走 mindmap command。
+
+
+  落地入口
+
+  以上判断已落实到两个主线 done checklist：
+
+  - /mnt/Data1T/mnote/design/04-tree-domain/done/4-24-resource-tree-filetree-pagetree-source-contract-checklist-v1.md
+    用于冻结 Resource Tree / File Tree / Page Tree 的真源合同和 projection / command 边界。
+  - /mnt/Data1T/mnote/design/05-editor-mainline/done/5-12-main-editor-object-tab-resource-alignment-checklist-v1.md
+    用于落实主编辑区 Object Tab、mindmap object editor、草稿隔离和真实浏览器 smoke 验收。
+
+  执行顺序固定为：
+
+  1. 先完成 4-24：协议、projection、command 边界必须能表达 `index.md`、mindmap、OnlyOffice、附件、代码附件的不同 object identity，并确认 Page Tree 只是页面导航投影。
+  2. 再完成 5-12：主编辑区只消费 4-24 输出的 object identity / resourceMeta / open intent，先关闭 mindmap 污染 `index.md` 的 P0 bug，再推进 Object Tab Host。
+  3. 验收以真实浏览器 smoke 为准，尤其是 `scripts/task169-mindmap-realtime-smoke.js` 覆盖“打开 mindmap、长中文编辑、保存、切页、回 `index.md`、再开 mindmap”的链路。

design/10-review/README.md

@@ -0,0 +1,44 @@
+# 10-review 审查总览
+
+本目录汇总当前设计与实现的偏差审查结果。四份分域报告分别覆盖 Rust kernel/web、前端编辑器与树体验、Convex/realtime/storage、次级域与设计治理。
+
+## 结论
+
+当前主线方向总体没有跑偏，但实现仍停留在“主链已切、收口未完”的状态。最需要继续收口的是：
+
+1. `Page Aggregate` 的单一真源边界
+2. `tree realtime` 的统一 live cache 与查询模型
+3. `documents.*` / `tree.*` / `page.*` 的 side effect 一致性
+4. legacy / compat / fallback 的显式退场边界
+
+## 优先级摘要
+
+### P0
+
+- Rust page write 路由与 artifact 一致性
+- 搜索 / workspace shell / fallback 数据不要再伪装成真实主链
+
+### P1
+
+- `pageSubtree` 与正文编辑的关系需要明确
+- Sidebar 的 `initial / query / tree_stream` 三源选择要继续向统一 live cache 收口
+- `PageAggregateSource` 的 provenance 口径要和真实读链对齐
+- Convex overview 查询要避免全量扫描放大
+
+### P2
+
+- 继续清理或标注 legacy compat、debug host、stale mapping
+- 对 `design/90-reference` 和次级参考材料保持只读、非上位来源定位
+
+## 报告文件
+
+- [Rust Kernel / Web 实现偏差审查](./01-rust-kernel-web-review.md)
+- [前端编辑器 / 树体验实现偏差审查](./02-frontend-editor-tree-review.md)
+- [Convex / Realtime / Storage 实现偏差审查](./03-convex-realtime-storage-review.md)
+- [次级域与设计治理实现偏差审查](./04-secondary-domains-and-design-governance-review.md)
+
+## 统一判断
+
+当前最准确的描述不是“已经完成单一真源收口”，而是：
+
+> Rust 已经持有主语义主导权，前端与 Convex 也已切到新主线，但 projection、command、realtime、fallback 仍有若干兼容态残留，需要继续按优先级收口。