chore: 保存当前架构收口与 bug 修复快照

归档本轮 P0/P1 bug 修复、设计审查迁移、AI selection scope 收口与 stream contract 调整，并保留当前 05 主线迁移起点。
2026-05-18 17:01:35 +08:00
parent 61ee4a38a2
commit a2cb1338c8
953 changed files with 14383 additions and 211845 deletions
@@ -1,16 +1,17 @@
 # 10-review 审查总览

-> 执行状态：`done/01` 到 `done/07` 均已归档；`process/08` 是当前活跃架构收口与下一阶段优先级 review；`process/09` 记录页面 AI 快速块编辑 runtime 的阶段性结论与下一步基建方向。
+> 执行状态：`done/01` 到 `done/11` 均已归档；当前无活跃 10-review process 文档。

 当前活跃审查：

- [Kernel 架构收口与下一阶段优先级 Review / Checklist](./process/08-kernel-architecture-next-priority-review-and-checklist.md)
- [页面 AI 快速块编辑 Runtime Review](./process/09-page-ai-fast-block-edit-runtime-review.md)
- [当前 mnote 项目 AI / Page Aggregate 定向 Review](./process/10-current-mnote-ai-runtime-review-v1.md)
- [当前完整架构 Review](./process/11-current-full-architecture-review-v1.md)
+- 暂无。

 最新归档审查：

+- [Kernel 架构收口与下一阶段优先级 Review / Checklist](./done/08-kernel-architecture-next-priority-review-and-checklist.md)
+- [当前 mnote 项目 AI / Page Aggregate 定向 Review](./done/10-current-mnote-ai-runtime-review-v1.md)
+- [当前完整架构 Review](./done/11-current-full-architecture-review-v1.md)
+- [页面 AI 快速块编辑 Runtime Review](./done/09-page-ai-fast-block-edit-runtime-review.md)
 - [VSCode Explorer 文件树与垃圾箱闭环增量审查](./done/07-vscode-explorer-filetree-trash-gap-review.md)

 上一轮最终执行入口：
@@ -1,8 +1,8 @@
-# 08 [process] Kernel 架构收口与下一阶段优先级 Review / Checklist v1
+# 08 [done] Kernel 架构收口与下一阶段优先级 Review / Checklist v1

-> 更新时间：2026-05-16
+> 更新时间：2026-05-18
 >
-> 执行状态：`process`
+> 执行状态：`done`
 >
 > 关联文档：
 > - `/mnt/Data1T/mnote/AGENTS.md`
@@ -35,14 +35,14 @@
 - Page Aggregate 仍是过渡态，block projection 主要从 `documents.content` / local markdown content 投影，不是 EditorBlockDocument 原生落库完成态。
 - 标题、正文、页面设置、page tree、AI 写入口尚未完全闭环到同一组 projection / command family。
 - `tree.*` 已是 preferred command name，但 `documents.*` 兼容命令面仍未完全降级。
- `/api/tree/events` 已是 tree realtime 主链，但 Sidebar、page subtree、filetree、preferred snapshot 还没有完全统一到一套 live cache。
+- `/api/realtime/ws` 已是 tree realtime 主链，`/api/tree/events` 已降级为 SSE fallback；live cache 的后续重点是减少兼容 fallback 与补偿链。
 - AI 块工具已有最小闭环，但当前编辑路径以块操作（blockId）为中心——AI 被迫理解 UI 层概念，且本地 `.md` 文件无 AI 写入路径。`7-14` 提出应将 AI 编辑主路径修正为 markdown 文本级（search/replace），`mnote.block.*` 降级为结构性辅助，在线 Convex 文档与本地文件共用同一条 markdown 写入路径。

 补充 BlockNote / Tiptap AI 参考后的判断：

 - BlockNote AI 和 Tiptap AI Toolkit 可以参考的是 AI runtime shape 与 tool contract，不是 mnote 的事实源。
 - AI 方向下一步只应补基础底座：`PageAIContextBuilder`、`scope=selection`、`page_xml/text`、tool manifest annotations、`PageAIReviewSession`、accept/reject/retry/abort 状态机。
- 2026-05-16 补充（受 `7-14` 方向修正）：AI 编辑主路径应从块级操作调整为 markdown 文本级 search/replace，新增 `mnote.doc.markdown_edit` 作为主要 AI 写入工具；当前 `local_rule` planner（`direct_block_edit_operations`）是过渡实现，应退役。在线 Convex 文档和本地 `.md` 文件共用同一条写入路径。
+- 2026-05-18 补充（`7-18` 到 `7-25` 收口后）：AI 简单正文编辑主路径已切到 markdown 文本级 search/replace / full_content，`page_ai_workflow.rs` 当前通过模型生成 markdown 编辑意图后调用 `mnote.doc.markdown_edit`，并复用统一 mnote tool executor；`local_rule` planner（`direct_block_edit_operations`）不再作为当前 runtime 口径。在线 Convex 文档和本地 `.md` 文件共用同一条 markdown 写入合同。
 - 在非 AI 主架构和 AI 基础合同打牢之前，不应扩展新的 AI agent 工作流、复杂 AI UI 或跨页面智能功能。

 因此，下一阶段不应优先“大改架构”或“大量加新功能”，而应优先做：
@@ -89,7 +89,7 @@

 目标：

- `/api/tree/events` 的 snapshot / delta / resync 成为 Sidebar、Page Tree、File Tree、page subtree 的共同 live cache 来源。
+- `/api/realtime/ws` 的 snapshot / delta / resync 成为 Sidebar、Page Tree、File Tree、page subtree 的共同 live cache 来源，`/api/tree/events` 仅作为 SSE fallback。
 - 减少 query/refetch/freshness 补偿链和旧快照回闪。

 ### P0：AI 基础工具与审阅底座
@@ -115,13 +115,13 @@
 - 不新增复杂 AI 自动化功能面。
 - 不把 `@blocknote/xl-ai` 或 BlockNote `AIExtension` 作为 runtime dependency。
 - 不让 AI 写入绕过 `dryRun/idempotencyKey/revision/conflictDetectionKey/revisionRef`。
- **不把 `direct_block_edit_operations` / `local_rule` planner 当作长期 AI 编辑路径（当前为过渡实现，将被 `markdown_edit` 替代）。**
+- **不把 `direct_block_edit_operations` / `local_rule` planner 当作当前或长期 AI 编辑路径；简单正文编辑当前主路径是 `mnote.doc.markdown_edit`，结构性块操作才使用 `apply_block_ops` / `mnote.block.*`。**
 - **不新增 `mnote.block.*` 工具；现有保留为结构性辅助。**

-**2026-05-16 新增（受 7-14 方向修正）：**
+**2026-05-18 状态更新（`7-18` 到 `7-25` 收口后）：**

- **Phase A（当前唯一活跃实施）**：`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强（search/replace + `format: "markdown"` + local source + Hermes 注册，7-14 v2 Phase A）。
- **Phase B（下一阶段）**：退役 `direct_block_edit_operations`，`page_ai_workflow.rs` 改走 `markdown_edit`（7-14 v2 Phase B）。
+- **Phase A / B 主路径已完成当前收口**：`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强、Hermes manifest / guidance、`page_ai_workflow.rs` → `markdown_edit`、统一 mnote tool executor、local / online markdown source 合同已同步。
+- **Phase C 仍冻结**：流式 apply + suggest/review 只保留设计边界，当前不实施、不扩新 AI 功能。
 - 在线 Convex 文档和本地 `.md` 文件共用同一条 markdown AI 写入路径（`resolve_source` → Convex | LocalFS）。

 ### P1：定向 Bug Hunt
@@ -144,8 +144,8 @@

 ### 3.1 Page Aggregate 单一真源

- [x] 盘点 `wolai-frontend/src/lib/documents/page-aggregate-loader.ts` 是否仍有 runtime fallback 或 TS builder 读取分支。
- [x] 盘点 `wolai-frontend/src/lib/documents/page-aggregate-builder*` 的引用，确认只剩 test helper / historical adapter。
+- [x] 盘点历史 `wolai-frontend/src/lib/documents/page-aggregate-loader.ts` 是否仍有 runtime fallback 或 TS builder 读取分支。
+- [x] 盘点历史 `wolai-frontend/src/lib/documents/page-aggregate-builder*` 的引用，确认只剩 test helper / historical adapter。
 - [x] 检查 `/api/documents/page` 仍返回明确 `410`，不参与 runtime 主链。
 - [x] 跑文档页打开 smoke，记录 `/api/page-aggregate/:id` 是首要读链。
 - [x] 新建页面后检查 Page Aggregate `identity/head/body/tree/stats` 字段完整。
@@ -156,7 +156,7 @@
 - [x] 破坏或暂停 Convex query，检查响应是 degraded/error，不返回伪 fixture。
 - [x] 在 `design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md` 勾选已验证项，并补证据路径。

-2026-05-16 静态审计证据：
+2026-05-16 静态审计证据（历史 Next 前端退役前快照）：

 - `wolai-frontend/src/lib/documents/page-aggregate-loader.ts` 只通过 `loadPageAggregateFromRustSnapshot` 请求 Rust `/api/page-aggregate/:documentId`，`loadPageAggregate` 不再回退 TS builder；`buildServerBridgeRequest("/documents/page")` 只用于构造转发 header/request，不调用 Next `/api/documents/page` compat route。
 - `rg -n "buildPageAggregateFromDocumentPayloads|page-aggregate-builder" wolai-frontend/src rust scripts design --glob '!design/05-editor-mainline/reference-code/**' --glob '!node_modules/**'` 显示 runtime 非测试引用仅剩 builder 定义；代码引用只有 `wolai-frontend/src/lib/documents/page-aggregate-builder.test.ts`。
@@ -191,6 +191,8 @@
 - 证据：`tmp/page-aggregate-refresh-persistence-smoke/mp88fr6k.json`，截图：`tmp/page-aggregate-refresh-persistence-smoke/mp88fr6k.png`，stdout：`tmp/page-aggregate-refresh-persistence-smoke/latest.stdout.json`。
 - 验证结果：刷新前后 `head.title=Page Aggregate refresh mp88fr6k`、`body.revision=1`、`body.conflictDetectionKey=tree_1778929070007_1:1`、`blockDocument.blocks[0].text=Page Aggregate refresh body mp88fr6k`、`layout.pageOptions.wideLayout/smallText/layoutDensity=true/true/compact`；刷新后页头标题、`.ProseMirror` 正文、设置控件、`documentElement`、`.document-shell`、island root 和 `.editor-surface` 均保持最新值。
 - 修复点：`rust/crates/mnote-web/src/ssr/pages/layout.rs` 将 `initializePageUiSurfaces` 延后到 `DOMContentLoaded` 后执行，避免 layout 脚本早于嵌入 Page Aggregate JSON / island DOM 完成时把 runtime 属性按默认 pageOptions 应用。
+- 2026-05-18 复测并扩展 `scripts/task-page-aggregate-refresh-persistence-smoke.js`，补充 `mnote.doc.fetch` / `tree.pageSubtree` 同组回读证据。证据：`tmp/page-aggregate-refresh-persistence-smoke/mpagfma1.json`，截图：`tmp/page-aggregate-refresh-persistence-smoke/mpagfma1.png`。
+- 验证结果：刷新前后 `head.title=Page Aggregate refresh mpagfma1`、`body.revision=1`、`body.conflictDetectionKey=tree_1779063433221_1:1`、`blockDocument.blocks[0].text=Page Aggregate refresh body mpagfma1`、`layout.pageOptions.wideLayout/smallText/layoutDensity=true/true/compact`、`tree.pageSubtree.rootNodeId=tree_1779063433221_1` 均一致；`mnote.doc.fetch` 返回 `schema=mnote.page_ai_context.v1`，`revision/conflictDetectionKey/revisionRef/text` 与同一 Page Aggregate block 完全一致。
 - 缺陷记录：`bugs/05-editor-mainline/done/5-12-page-options-refresh-runtime-attrs-v1.md`。
 - 配套测试已通过：`cargo test --manifest-path rust/Cargo.toml -p mnote-web page_aggregate`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web documents_options_route_executes_page_layout_update_options`。

@@ -216,47 +218,61 @@ cargo test --manifest-path rust/Cargo.toml -p mnote-web document_shell_errors_wi

 ### 3.2 Page Block AI Tooling

- [ ] 以 `7-10` 为工具执行清单、`7-11` 为 AI runtime 基础设计，逐 phase 检查已勾选项是否都有代码、测试、smoke 证据。
+- [x] 以 `7-10` 为工具执行清单、`7-12` 为当前 AI runtime 基础设计，逐 phase 检查已勾选项是否都有代码、测试、smoke 证据。
 - [x] 给 `mnote.doc.fetch scope=selection` 补真实选区上下文输入和返回结构。
 - [x] 给 `mnote.doc.fetch format=page_xml` 补最小 PageXML 输出。
 - [x] 给 `mnote.block.fetch format=text/page_xml` 补格式分支。
 - [x] 给 tool manifest 补 `annotations`，区分 readonly / destructive / requiresApproval / selectionEffect。
 - [x] 定义 `mnote.page_ai_context.v1`，明确 context 只来自 Page Aggregate projection。
- [ ] 定义 `mnote.page_ai_review_session.v1`，明确 accept / reject / retry / abort 语义。
- [ ] 给 `mnote.block.insert_after` 补多块插入限制和返回 inserted block ids。
- [ ] 给 `mnote.block.move_after` 补标题带子块阻断 smoke。
- [ ] 给 `mnote.block.move_after` 补列表项阻断 smoke。
- [ ] 给 `mnote.block.move_after` 补表格 / mindmap / resource 阻断 smoke。
+- [x] 定义 `mnote.page_ai_review_session.v1`，明确 accept / reject / retry / abort 语义。
+- [x] 给 `mnote.block.insert_after` 补多块插入限制和返回 inserted block ids。
+- [x] 给 `mnote.block.move_after` 补标题带子块阻断 smoke。
+- [x] 给 `mnote.block.move_after` 补列表项阻断 smoke。
+- [x] 给 `mnote.block.move_after` 补表格 / mindmap / resource 阻断 smoke。
 - [x] 给 `mnote.block.replace` 补 stale revision 失败用例。
 - [x] 给 `mnote.block.replace` 补 stale blockRevisionRef 失败用例。
 - [x] 给写工具补重复 idempotencyKey 的端到端用例。
 - [x] 检查 `mnote.page.save` 在 manifest / UI 中继续标为页面级兜底，不显示为精确块编辑主入口。
- [ ] 检查任何新增 AI surface 是否只是基础 review/context/tooling 验收，不是新功能扩展。
- [ ] 更新 `design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md` 的每个 phase 证据。
- [ ] 更新 `design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md` 的 Hermes 工具路由与审阅面 checklist。
+- [x] 检查任何新增 AI surface 是否只是基础 review/context/tooling 验收，不是新功能扩展。
+- [x] 更新 `design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md` 的每个 phase 证据。
+- [x] 更新 `design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md` 的 Hermes 工具路由与审阅面 checklist。

-**新增（2026-05-16，受 7-14 方向修正）：**
+2026-05-18 `mnote.block.insert_after` 多块插入证据：

-**Phase A（当前唯一活跃实施）：**
- [ ] `mnote.doc.markdown_edit` 核心实现：resolve_source → search_replace → write_target
- [ ] `mnote.doc.markdown_edit` 搜索替换语义：精确匹配 → fuzzy fallback → operationsFailed（7-14 §5）
- [ ] `mnote.doc.markdown_edit` Convex 写入 adapter（复用 `page.body.save` 链路）
- [ ] `mnote.doc.markdown_edit` 本地文件写入 adapter（`fs.writeFile` + GFM AST markdown 序列化）
- [ ] `mnote.doc.fetch format: "markdown"` 增强（Page Aggregate 产出 PageMarkdown）
- [ ] `mnote.doc.fetch` local source 支持（识别本地文件路径并返回 `.md` 原文）
- [ ] Hermes tool manifest 注册 `mnote.doc.markdown_edit`
- [ ] Hermes `mnote` plugin 更新：`mnote_doc_fetch` schema 增加 `format: "markdown"` 和本地文件路径支持
- [ ] 乐观锁：`revision` 冲突检测
- [ ] 单元测试 + smoke（在线 + 本地两种 source）
+- 代码：`rust/crates/mnote-web/src/hermes_tools/block.rs` 支持 `content` / `block` / `blocks` 输入；`blocks` 限制 `1..=20`；多块写入按输入顺序连续插入，并在结果返回 `insertedBlockIds`。
+- manifest：`rust/crates/mnote-web/src/hermes_tools/manifest.rs` 已声明 `blocks.minItems=1/maxItems=20`，并用 `anyOf` 表达 `content | block | blocks` 三种输入。
+- 测试：`cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_block_insert_after -- --nocapture` 通过，覆盖多块成功和超过 20 个失败。
+- 回归：`cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture` 通过，覆盖 Hermes tools 38 项。

-**Phase B（下一阶段）：**
- [ ] `direct_block_edit_operations` 退役（`page_ai_workflow.rs` `local_rule` 分支）
- [ ] `page_ai_workflow.rs` 修正：system prompt 改为产 search/replace 对，底层走 `mnote.doc.markdown_edit`
- [ ] 补全 operation schema（`content` 字段）
- [ ] 浏览器 smoke：自然语言编辑可用（不使用「」格式）
+2026-05-18 `mnote.block.move_after` 复杂块阻断证据：
+
+- 代码：`rust/crates/mnote-web/src/hermes_tools/block.rs` 继续以同父级、叶子块、可移动类型、editable、自身移动为真实写入前阻断条件。
+- 测试：`cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_block_move_after_blocks_complex_and_nested_blocks -- --nocapture` 通过，覆盖标题带子块、列表项、表格、mindmap、resource 均返回 `blocked=true` / `block_move_after_blocked`。
+- 回归：`cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture` 通过，当前 Hermes tools 共 39 项。
+
+**新增（2026-05-18，`7-18` 到 `7-25` 收口状态）：**
+
+**Phase A / B（当前主路径已收口）：**
+- [x] `mnote.doc.markdown_edit` 核心实现：resolve_source → search_replace / full_content → write_target
+- [x] `mnote.doc.markdown_edit` 搜索替换语义：精确匹配、归一化匹配、多操作同块合并、无法安全映射时失败
+- [x] `mnote.doc.markdown_edit` Convex 在线写入 adapter 以最终 markdown 映射写回
+- [x] `mnote.doc.markdown_edit` 本地文件写入 adapter 尊重 dryRun / idempotency
+- [x] `mnote.doc.fetch format: "markdown"` 增强
+- [x] Hermes tool manifest 注册并描述 `mnote.doc.markdown_edit` 写入合同
+- [x] 乐观锁：revision / conflictDetectionKey 前置校验
+- [x] `direct_block_edit_operations` / `local_rule` 不再作为 `page_ai_workflow.rs` 当前主路径
+- [x] `page_ai_workflow.rs` 改为模型产 markdown search/replace / full_content，底层走 `mnote.doc.markdown_edit`
+- [x] 单元测试覆盖 markdown_edit / page_ai_workflow / Hermes guidance / ACP tool contract

 **Phase C（设计冻结，不实施）：**
- [ ] 流式 apply + suggest/review 设计已冻结，不阻塞 Phase A/B 实施
+- [x] 流式 apply + suggest/review 设计已冻结，不阻塞 Phase A/B 实施
+
+2026-05-18 Review Session 合同定义：
+
+- 已在 `design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md` 定义 `mnote.page_ai_review_session.v1` 最小 schema。
+- 已明确状态：`draft/planning/previewing/awaiting_user/accepted/rejected/applying/applied/failed/aborted/stale`。
+- 已明确动作约束：`accept` 必须重新读 Page Aggregate 并校验 revision / conflictDetectionKey / revisionRef，`reject/abort` 不产生写入，`retry` 必须生成新 proposal 或 dry-run preview，yolo 模式也应生成同构 audit 数据。
+- 边界：这里只完成合同定义，不实施 Phase C 流式 apply 或新的审阅 UI。

 2026-05-16 Page Block AI context / format focused smoke 证据：

@@ -271,15 +287,17 @@ cargo test --manifest-path rust/Cargo.toml -p mnote-web document_shell_errors_wi
 - 边界：本轮只验证 `mnote.doc.apply_block_ops` 的 selection scope guard；单个 `mnote.block.replace/insert_after/move_after` 尚未校验 `allowedTargetBlockIds`，不能据此勾选完整 selection 写保护矩阵。
 - 配套验证已通过：`node --check scripts/task-page-block-ai-context-format-smoke.js`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture`、`MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:3000 node scripts/task-page-block-ai-context-format-smoke.js`。

-2026-05-16 Page Block AI stale / idempotency focused smoke 证据：
+2026-05-16 / 2026-05-18 Page Block AI stale / idempotency focused smoke 证据：

 - 新增并运行 `scripts/task-page-block-ai-conflict-idempotency-smoke.js`，通过真实 3000 + 测试账号创建临时页，用 `mnote.page.save` 初始化 `p_1/p_2`，再围绕 `mnote.block.replace` 验证冲突和幂等安全边界。
 - 证据：`tmp/page-block-ai-conflict-idempotency-smoke/mp8dyqiq.json`，截图：`tmp/page-block-ai-conflict-idempotency-smoke/mp8dyqiq-page.png`。
+- 最新复测证据：`tmp/page-block-ai-conflict-idempotency-smoke/mpafrevs.json`，截图：`tmp/page-block-ai-conflict-idempotency-smoke/mpafrevs-page.png`。
 - 验证结果：
  - 首次 `mnote.block.replace` 携带最新 `revision/conflictDetectionKey/blockRevisionRef/idempotencyKey` 成功写入 `p_2`，返回 `commandName=page.body.save` 与 `commandId=page_body_save_req_1778938353824_11`。
  - 使用同一 `idempotencyKey=idem_conflict_replace_mp8dyqiq` 再次调用 `mnote.block.replace`，即使请求 content 改成不同文本，也 replay 同一 `commandId`，Page Aggregate 回读 `p_2` 仍为首次写入文本，`revisionAfterFirst=2`、`revisionAfterReplay=2`，确认不重复写入。
  - 使用旧 `revision/conflictDetectionKey` 调用 `mnote.block.replace` 返回 HTTP `400`、错误码 `mnote_tool_conflict`，正文保持首次写入结果。
  - 使用最新 `revision/conflictDetectionKey` 但旧 `blockRevisionRef` 调用 `mnote.block.replace` 返回 HTTP `400`、错误码 `mnote_tool_conflict`，正文保持首次写入结果。
+  - 2026-05-18 复测中，重复 `idempotencyKey=idem_conflict_replace_mpafrevs` replay 同一 `commandId=page_body_save_req_1779062303997_525`，`revisionAfterFirst=2`、`revisionAfterReplay=2`；旧 revision 与旧 blockRevisionRef 仍均返回 `mnote_tool_conflict`。
 - 边界：本轮只覆盖 `mnote.block.replace` 直接 tool executor 的 stale revision / stale blockRevisionRef / idempotency replay；不代表 `mnote.block.insert_after` 幂等矩阵、所有写工具幂等矩阵、review session accept stale 或 accept/reject/retry/abort 已完成。
 - 配套验证已通过：`node --check scripts/task-page-block-ai-conflict-idempotency-smoke.js`、`cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture`、`MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:3000 node scripts/task-page-block-ai-conflict-idempotency-smoke.js`。

@@ -302,11 +320,17 @@ node scripts/task-page-block-ai-tools-smoke.js
 - [x] 对 compat alias 返回增加 owner / deprecated 标识，避免被当作主链。
 - [x] 更新 `design/04-tree-domain/done/4-6-tree-command-protocol-cutover-stage2-v1.md` 或新增后续 process checklist。

-2026-05-16 Tree Command Cutover 静态盘点与 alias 标识证据：
+2026-05-18 当前 Tree Command Cutover 状态：
+
+- `3000` 当前主壳由 Rust `mnote-web` SSR 承载；主要页面生命周期动作通过 Rust `/api/tree/commands` route 生成 `tree.node.create`、`tree.node.rename`、`tree.subtree.move`、`tree.node.archive`、`tree.node.restore`、`tree.node.purge`、`tree.subtree.copy`。
+- `bridge-runtime` 仍接受历史 `documents.*` alias，但 execution plan / artifact 会标记 `preferredCommandName`、`compatCommandName`、`deprecatedAlias`，避免兼容命令被当成当前主链。
+- `wolai-frontend` / Next tree command route 只作为退役前历史审计材料，不再作为当前运行时主链依据。
+
+2026-05-16 Tree Command Cutover 静态盘点与 alias 标识证据（历史 Next 前端退役前快照）：

 - 只读盘点命令：`rg -n "documents\\.(create|title\\.update|move|archive|restore|delete|purge|copy_tree)" rust wolai-frontend scripts --glob '!node_modules/**'`。
- 前端主链：`wolai-frontend/src/lib/documents/tree-command-client.ts` 的新建、重命名、移动、归档、恢复、永久删除和复制均 POST `/api/tree/commands`，返回 meta 使用 `TREE_COMMAND_PROTOCOL.*.preferredCommandName`；`TREE_COMMAND_PROTOCOL` 中的 `documents.*` 只保留为 `compatCommandName`。
- Next tree command route：`wolai-frontend/src/app/api/tree/commands/route.ts` 在 create / move / rename / archive / restore 分支分别构造 `tree.node.create`、`tree.subtree.move`、`tree.node.rename`、`tree.node.archive`、`tree.node.restore`。
+- 退役前 Next 前端主链：`wolai-frontend/src/lib/documents/tree-command-client.ts` 的新建、重命名、移动、归档、恢复、永久删除和复制均 POST `/api/tree/commands`，返回 meta 使用 `TREE_COMMAND_PROTOCOL.*.preferredCommandName`；`TREE_COMMAND_PROTOCOL` 中的 `documents.*` 只保留为 `compatCommandName`。
+- 退役前 Next tree command route：`wolai-frontend/src/app/api/tree/commands/route.ts` 在 create / move / rename / archive / restore 分支分别构造 `tree.node.create`、`tree.subtree.move`、`tree.node.rename`、`tree.node.archive`、`tree.node.restore`。
 - Rust Web tree route：`rust/crates/mnote-web/src/routes/tree.rs` 的 `create_command_wire` 输出 `tree.node.create`、`tree.node.rename`、`tree.subtree.move`、`tree.node.archive`、`tree.node.restore`、`tree.node.purge`、`tree.subtree.copy`；`tree_command` route 只接收 action，不接收旧 `documents.*` command name 作为主链输入。
 - 兼容保留：`bridge-runtime` 仍接受 `documents.create/title.update/move/delete/restore/purge/copy_tree`，但本轮已在对应 execution plan 的 `args_json.commandProtocol` 增加 `family=tree`、`owner=rust-runtime-kernel`、`preferredCommandName`、`compatCommandName`、`deprecatedAlias`；旧 `documents.*` alias 会标记 `deprecatedAlias=true`。
 - Transport 边界：`rust/crates/mnote-web/src/transport/convex.rs` 发送给 Convex legacy mutation 前会剥离 `commandProtocol`、`streamDeltaHint`、`domainEventHint`、`domainEventPlan(s)`，避免 legacy validator 把审计字段当写入参数。
@@ -337,14 +361,20 @@ node scripts/task122-rust-web-create-page-ui-smoke.js
 - [x] 重命名页面后，双浏览器 A/B 检查 Sidebar / Breadcrumb / File Tree 一致更新。
 - [x] 移动页面后，双浏览器 A/B 检查 tree order 不回闪。
 - [x] 删除 / 恢复后检查 trash 与主树事件一致。
- [x] 断开 SSE 后恢复，检查 resync 能把 UI 拉回正确状态。
+- [x] 断开 WS / SSE fallback 后恢复，检查 resync 能把 UI 拉回正确状态。
 - [x] 更新 `design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md` 的已验证项。

-2026-05-16 Tree Realtime Live Cache 静态盘点与 payload 覆盖证据：
+2026-05-18 当前状态更新：

- 只读审查确认 React `AppLayoutShell` 同时接入 `useSidebarData` 与 `useSidebarTreeStream`，`usePreferredSidebarSnapshot` 负责 freshness 仲裁；Page Tree / File Tree 通过 preferred snapshot 消费 `kernelSidebarTree` 与 `kernelFileTreeProjection`。
- 仍未统一的补偿链：`useSidebarData` 还保留 Convex query、HTTP `/api/sidebar` fallback 与手动 `refetch`；mutation 后仍有 `refreshTree` / `sidebarQuery.refetch`；Rust SSR shell 与 React hook 目前各自可建立 EventSource；page subtree 仍从 Page Aggregate client state 派生，不应误标为已统一 live cache。
- Rust stream 盘点确认 workspace snapshot 已同时加载 `KernelProjectionKind::SidebarTree` 与 `KernelProjectionKind::FileTree`，SSE payload 的 `data.dataset.kernel_sidebar_projection` / `data.dataset.kernel_file_tree_projection` 覆盖 page/file row；subtree snapshot 仍只覆盖 `page_tree`，不含 file tree projection。
+- `/api/realtime/ws` 已成为 Rust SSR 主壳默认 transport（`convex-command-log-ws`），`/api/tree/events` 仅作为 SSE fallback。
+- `CURRENT_ARCHITECTURE.md` 与 `bugs/03-rust-web/done/3-16` 到 `3-18` 已同步：原“WS 文档口径 / 前端 SSE 实现”冲突、SSE push 跳过 polling safety net、WS/SSE delta 合同分裂均已修复。
+- 2026-05-16 下面的 SSE smoke 证据保留为迁移前历史验证材料，不再代表当前主链。
+
+2026-05-16 Tree Realtime Live Cache 静态盘点与 payload 覆盖证据（WS 迁移前历史快照）：
+
+- 退役前只读审查确认 React `AppLayoutShell` 同时接入 `useSidebarData` 与 `useSidebarTreeStream`，`usePreferredSidebarSnapshot` 负责 freshness 仲裁；Page Tree / File Tree 通过 preferred snapshot 消费 `kernelSidebarTree` 与 `kernelFileTreeProjection`。
+- 退役前未统一的补偿链：`useSidebarData` 还保留 Convex query、HTTP `/api/sidebar` fallback 与手动 `refetch`；mutation 后仍有 `refreshTree` / `sidebarQuery.refetch`；Rust SSR shell 与 React hook 当时各自可建立 EventSource；page subtree 当时仍从 Page Aggregate client state 派生。
+- Rust stream 历史盘点确认 workspace snapshot 已同时加载 `KernelProjectionKind::SidebarTree` 与 `KernelProjectionKind::FileTree`，SSE payload 的 `data.dataset.kernel_sidebar_projection` / `data.dataset.kernel_file_tree_projection` 覆盖 page/file row；subtree snapshot 当时只覆盖 `page_tree`，不含 file tree projection。
 - 本轮新增 `stream_change_preserves_remove_asset_delta_fields`，确认 `tree.resource.delete` 的 `remove_asset` delta 字段保真；`structural_delta_requires_projection_snapshot` 已覆盖 `remove_asset` 需要 projection snapshot，避免资源删除类事件只靠局部 patch。
 - 本轮强化 `scripts/task123-rust-web-tree-live-stream-consumer-smoke.js`：解析 SSE `snapshot` data，断言 `kind=snapshot`、`stream=workspace`、`projection=sidebar_tree`、`x-mnote-tree-stream-owner=rust-web`，并确认 workspace snapshot 中有 `kernel_sidebar_projection`、`kernel_file_tree_projection` 和临时页 `doc:<documentId>` file tree row。

@@ -425,21 +455,26 @@ node scripts/task449-tree-sse-reconnect-snapshot-recovery-smoke.js

 ### 3.5 定向 Bug Hunt

- [ ] 建立 bugs 分类：Page Aggregate 问题归 `bugs/05-editor-mainline/process/`。
- [ ] Tree command / realtime / File Tree 问题归 `bugs/04-tree-domain/process/`。
- [ ] AI tools 问题归 `bugs/07-ai/process/`。
- [ ] 每个 bug 必须包含复现步骤、期望、实际、证据截图或 JSON、owner 判断。
- [ ] 先补最小 failing smoke，再修实现。
- [ ] 修复后移动到对应 `done/`，并记录验证命令。
+- [x] 建立 bugs 分类：Page Aggregate 问题归 `bugs/05-editor-mainline/process/`。
+- [x] Tree command / realtime / File Tree 问题归 `bugs/04-tree-domain/process/`。
+- [x] AI tools 问题归 `bugs/07-ai/process/`。
+- [x] 每个 bug 必须包含复现步骤、期望、实际、证据截图或 JSON、owner 判断。
+- [x] 先补最小 failing smoke 或定向单测，再修实现。
+- [x] 修复后移动到对应 `done/`，并记录验证命令。

 重点 bug 方向：

- [ ] Page Aggregate 与页头标题不一致。
- [ ] Page Aggregate 与 File Tree `{title}.md` 不一致。
- [ ] AI 写入成功但 Page Aggregate 回读旧内容。
- [ ] stale revision 未阻断写入。
- [ ] tree stream 断线恢复后 UI 停在旧快照。
- [ ] 旧 compat / debug route 在 3000 首屏被误用。
+- [x] Page Aggregate 与页头标题不一致。
+- [x] Page Aggregate 与 File Tree `{title}.md` 不一致。
+- [x] AI 写入成功但 Page Aggregate 回读旧内容。
+- [x] stale revision 未阻断写入。
+- [x] tree stream 断线恢复后 UI 停在旧快照。
+- [x] 旧 compat / debug route 在 3000 首屏被误用。
+
+2026-05-18 定向 bug hunt 收口：
+
+- `find bugs -path '*/process/*' -type f | wc -l` 结果为 `0`。
+- 本轮 P0 / 内核优先缺陷已迁入 `bugs/*/done/`，并在 `CURRENT_ARCHITECTURE.md`、`design/10-review/done/10-current-mnote-ai-runtime-review-v1.md`、`design/10-review/done/11-current-full-architecture-review-v1.md` 中同步验证证据。

 ### 3.6 2026-05-16 暂停交接进展摘要

@@ -497,16 +532,55 @@ MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:300

 ## 4. 当前不优先做

- [ ] 不优先增加新的编辑器 UI 大功能。
- [ ] 不优先新增 AI Agent 工作流功能。
- [ ] 不优先扩展 AI 功能面；AI 只做基础上下文、工具合同、审阅会话、冲突与回滚。
- [ ] 不优先大规模替换 Convex。
- [ ] 不优先重写 `leptos-tiptap` 输入层。
- [ ] 不把 `mnote.page.save` 包装成精确块编辑长期方案。
- [ ] 不在 compat route 继续扩写长期业务语义。
- [ ] 不把 BlockNote / Tiptap AI runtime 作为 mnote runtime 依赖。
- [ ] 不把 `direct_block_edit_operations` / `local_rule` planner 当作长期 AI 编辑路径（当前为过渡实现，将被 `mnote.doc.markdown_edit` 替代）。
- [ ] 不新增 `mnote.block.*` 工具；`mnote.block.*` 保留为结构性辅助，不做块操作向新工具的扩张。
+- [x] 不优先增加新的编辑器 UI 大功能。
+- [x] 不优先新增 AI Agent 工作流功能。
+- [x] 不优先扩展 AI 功能面；AI 只做基础上下文、工具合同、审阅会话、冲突与回滚。
+- [x] 不优先大规模替换 Convex。
+- [x] 不优先重写 `leptos-tiptap` 输入层。
+- [x] 不把 `mnote.page.save` 包装成精确块编辑长期方案。
+- [x] 不在 compat route 继续扩写长期业务语义。
+- [x] 不把 BlockNote / Tiptap AI runtime 作为 mnote runtime 依赖。
+- [x] 不把 `direct_block_edit_operations` / `local_rule` planner 当作当前或长期 AI 编辑路径；简单正文编辑当前主路径是 `mnote.doc.markdown_edit`。
+- [x] 不新增 `mnote.block.*` 工具；`mnote.block.*` 保留为结构性辅助，不做块操作向新工具的扩张。
+
+2026-05-18 静态边界核验证据：
+
+- `rg -n "mnote\\.block\\.[a-zA-Z0-9_]+" rust/crates/mnote-web/src/hermes_tools rust/crates/mnote-web/src/routes/hermes_tools.rs scripts/reasonix-acp-wrapper.mjs | ... | sort -u` 仅发现既有 `mnote.block.fetch/delete/replace/insert_after/move_after`，本轮未新增 `mnote.block.*` 工具。
+- `page_ai_workflow.rs` 注释与当前实现仍指向 `mnote.doc.markdown_edit`；`direct_block_edit_operations` 只保留为历史/测试辅助，不作为当前主路径。
+- `mnote.page.save` 在 manifest / 7-10 / 7-12 / 本 checklist 中继续描述为页面级粗粒度兜底，不是精确块编辑主入口。
+- 未引入 `@blocknote/xl-ai`、BlockNote `AIExtension` 或新的 AI Agent workflow；本轮改动仅限 Hermes tools 合同、阻断矩阵测试和 checklist 证据。
+
+2026-05-18 `7-12` runtime 口径闭合证据：
+
+- `design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md` 已明确 `7-11` 旧“自有 AI runtime”口径移入 `design/old/07-ai/process/`，当前执行口径以 `7-12` 为准。
+- `7-12` 已定义 `PageAIContextBuilder`、`MnoteAIToolManifestProvider`、`PageAICommandRouter`、`PageAIReviewSession` 的边界，并明确 Phase C review / streaming apply 只做设计冻结，当前不实施。
+- `7-12` Phase B 到 Phase F 保留 manifest / router / review session / event / smoke 的后续 checklist；其中 selection 外写入 blocked 已有真实 smoke 证据，其余未实施项继续保留未勾。
+
+2026-05-18 `7-10` 剩余真实页面矩阵拆分：
+
+- 新增 `design/07-ai/process/7-16-page-block-ai-real-smoke-followup-matrix-v1.md`，专门承接 `7-10` 中仍未完成的真实 3000 smoke 和 UI/review 边界矩阵。
+- `7-10` 继续保留为页面块 AI 工具执行总 checklist；`7-16` 只用于后续真实页面证据补齐，不扩新 AI 功能。
+
+2026-05-18 真实页面 insert_after smoke 补充：
+
+- `scripts/task-page-block-ai-tools-smoke.js` 增加 `PLAYWRIGHT_CHROME_EXECUTABLE` 支持，用系统 Chromium 运行，避免当前系统无法下载 Playwright 官方 chromium 的阻断。
+- 命令：`PLAYWRIGHT_CHROME_EXECUTABLE=/snap/bin/chromium MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:3000 node scripts/task-page-block-ai-tools-smoke.js`
+- 证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- Page Aggregate：`tmp/hermes-tester/page-block-ai-tools-mpag4966/page-aggregate.json`，doc/fetch/find：`tmp/hermes-tester/page-block-ai-tools-mpag4966/doc-fetch-find.json`。
+- 覆盖：`mnote.block.insert_after` 插入 `todo` 块、插入顺序、`mnote.block.fetch` 回读新块、重复 `idempotencyKey` 不二次插入、刷新后文本可见。
+- 覆盖：`table_1/mindmap_1/resource_1` 在 AI block projection 中返回 `editable=false` 与 `unsupportedReason=复杂块暂不开放 AI 精确写入`；`heading_parent/list_item_1/table_1/mindmap_1/resource_1` 的 `plan_update block_move_after` dry-run 与正式 `mnote.block.move_after` 均阻断，阻断后 revision / 正文不变化。
+
+2026-05-18 真实页面 doc.fetch / doc.find / block.fetch smoke 补充：
+
+- 命令：`PLAYWRIGHT_CHROME_EXECUTABLE=/snap/bin/chromium MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:3000 node scripts/task-page-block-ai-tools-smoke.js`
+- 证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- 覆盖：`doc.fetch full`、`doc.fetch outline`、`doc.find` 定位 `p_2`、`maxBlocks=2` 截断、`block.fetch includeChildren=true contextBefore=1 contextAfter=1` 返回 `revisionRef` 与同父级 before/after；复杂块投影不伪装完全可编辑。
+
+2026-05-18 真实页面 plan_update / replace / move smoke 补充：
+
+- 命令：`PLAYWRIGHT_CHROME_EXECUTABLE=/snap/bin/chromium MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:3000 node scripts/task-page-block-ai-tools-smoke.js`
+- 证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- 覆盖：`block_replace/block_insert_after/block_move_after` dry-run、dry-run 不写入、blocked 场景、replace 相邻块不变与 id 保持、replace 后 Page Aggregate 回读持久化、复杂块 move 阻断、普通块 move dry-run 与正式移动、moving block id 保持、刷新后 block ids 稳定。

 ---

@@ -514,18 +588,18 @@ MNOTE_UI_BASE_URL=http://127.0.0.1:3000 MNOTE_AUTH_BASE_URL=http://127.0.0.1:300

 本 checklist 不能迁入 `done/`，直到：

- [ ] Page Aggregate 的标题 / 正文 / 页面设置 / page tree / AI fetch 回读形成同一组可验证真相。
- [ ] `7-10` 的 Page Block AI Tooling 剩余矩阵完成或明确拆出后续 process 文档。
- [ ] `7-11` 的 AI 基础 runtime 口径完成：context、format、manifest annotations、review session、状态机边界都有代码或明确后续 checklist。
- [ ] 7-14 v2 Phase A + B 全部完成（`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强 + `page_ai_workflow.rs` 收口）；Phase C 设计已冻结。设计稿修正已由 7-14 v2 自行完成。
- [ ] `tree.*` command 面对主要页面生命周期动作成为唯一 preferred runtime 主链。
- [ ] tree realtime live cache 覆盖 Sidebar、Page Tree、File Tree、page subtree 的关键写后更新。
- [ ] 至少一轮定向 bug hunt 完成，所有 P0/P1 blocker 已归档到 `bugs/*/done/` 或明确保留为后续 process。
+- [x] Page Aggregate 的标题 / 正文 / 页面设置 / page tree / AI fetch 回读形成同一组可验证真相。
+- [x] `7-10` 的 Page Block AI Tooling 剩余矩阵完成或明确拆出后续 process 文档。
+- [x] `7-12` 的 AI 基础 runtime 口径完成：context、format、manifest annotations、review session、状态机边界都有代码或明确后续 checklist。
+- [x] 7-14 v2 Phase A + B 当前主路径完成（`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强 + `page_ai_workflow.rs` 收口）；Phase C 设计已冻结。设计稿修正已由 7-14 v2 与 `7-18` 到 `7-25` bug 修复共同完成。
+- [x] `tree.*` command 面对主要页面生命周期动作成为唯一 preferred runtime 主链。
+- [x] tree realtime live cache 覆盖 Sidebar、Page Tree、File Tree、page subtree 的关键写后更新。
+- [x] 至少一轮定向 bug hunt 完成，所有 P0/P1 blocker 已归档到 `bugs/*/done/` 或明确保留为后续 process。

 ---

 ## 6. 给后续 /goal 的持续执行 Prompt

 ```text
-/goal objective: 持续执行 /mnt/Data1T/mnote/design/10-review/process/08-kernel-architecture-next-priority-review-and-checklist.md，按 P0 -> P1 顺序推进 MNOTE 架构收口、AI 基础底座和定向 bug hunt。每轮开始先读取 /home/lix/.codex/memories/PROFILE.md 与 ACTIVE.md，再读取 AGENTS.md、ARCHITECTURE.md、design/01-05-current-priority-overview.md、本 checklist、design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md、design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md、design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md。必须保护用户已有未提交改动，不回滚、不覆盖、不删除无关文件。优先使用多个 subagent 并行做只读审查和浏览器验证，主线程只整合证据和做小范围实现。执行顺序固定为：1) Page Aggregate 单一真源；2) tree command cutover；3) tree realtime live cache；4) AI 基础工具与审阅底座，按 `7-14` v2 方向优先做 Phase A（`mnote.doc.markdown_edit` + `mnote.doc.fetch` 增强），Phase B 退役 `local_rule` planner + `page_ai_workflow.rs` 收口；Phase C（流式 apply + suggest/review）仅设计冻结不实施。同时补 context/selection/page_xml/tool annotations，不扩新 AI 功能；5) 定向 bug hunt。每完成一个小项都要更新本 checklist 和对应 design/bugs 文档，补真实验证命令或证据路径。不要优先扩新功能，不要大改架构，不要把 compat/debug/fallback 当主链，不要把 BlockNote/Tiptap AI runtime 作为 mnote runtime 依赖。验证至少包含 git diff --check、相关 cargo test / smoke；如涉及 3000 页面，使用 mnote-tester 或浏览器自动化并保留截图/JSON 证据。
+/goal objective: 持续核验 /mnt/Data1T/mnote/design/10-review/done/08-kernel-architecture-next-priority-review-and-checklist.md 的已归档结论，按 P0 -> P1 顺序推进 MNOTE 架构防回归、AI 基础底座和定向 bug hunt。每轮开始先读取 /home/lix/.codex/memories/PROFILE.md 与 ACTIVE.md，再读取 AGENTS.md、ARCHITECTURE.md、design/01-05-current-priority-overview.md、本 checklist、design/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md、design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md、design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md。必须保护用户已有未提交改动，不回滚、不覆盖、不删除无关文件。优先使用多个 subagent 并行做只读审查和浏览器验证，主线程只整合证据和做小范围实现。执行顺序固定为：1) Page Aggregate 单一真源防回归；2) tree command cutover 防回归；3) tree realtime live cache 防回归；4) AI 基础工具与审阅底座，当前简单正文编辑主路径已是 `mnote.doc.markdown_edit` + `mnote.doc.fetch` + `page_ai_workflow.rs` 统一 tool executor，Phase C（流式 apply + suggest/review）仅设计冻结不实施；继续补 context/selection/page_xml/tool annotations，不扩新 AI 功能；5) 定向 bug hunt。每完成一个小项都要更新对应 design/bugs 文档，补真实验证命令或证据路径。不要优先扩新功能，不要大改架构，不要把 compat/debug/fallback 当主链，不要把 BlockNote/Tiptap AI runtime 作为 mnote runtime 依赖。验证至少包含 scoped git diff --check、相关 cargo test / smoke；如涉及 3000 页面，使用 mnote-tester 或浏览器自动化并保留截图/JSON 证据。
 ```
@@ -1,6 +1,6 @@
 # 09 页面 AI 快速块编辑 Runtime Review

-> 状态：`process`
+> 状态：`done`
 >
 > 日期：2026-05-16
 >
@@ -12,6 +12,19 @@

 ---

+## 0. 归档说明
+
+本文件是 2026-05-16 的页面 AI fast block edit 历史审查快照。其记录的 `local_rule` / `doc_apply_block_ops` 快路径已被后续 `mnote.doc.markdown_edit` 主路径替代，不再作为当前 runtime 口径。
+
+当前有效口径见：
+
+- [10-current-mnote-ai-runtime-review-v1](./10-current-mnote-ai-runtime-review-v1.md)
+- [11-current-full-architecture-review-v1](./11-current-full-architecture-review-v1.md)
+- [7-18 AI markdown_edit 阶段状态合同漂移](../../../bugs/07-ai/done/7-18-ai-markdown-edit-phase-state-contract-drift-v1.md)
+- [7-20 page_ai_workflow 绕过 Hermes tool executor / audit / toggle](../../../bugs/07-ai/done/7-20-page-ai-workflow-bypasses-hermes-tool-executor-v1.md)
+
+归档后的结论：`page-ai/block-edit-workflow` 仍是简单编辑 fast-path 入口，但当前实现应通过模型生成 markdown search/replace / full_content 后调用 `mnote.doc.markdown_edit`，并复用统一 mnote tool executor；`mnote.doc.apply_block_ops` / `mnote.block.*` 只作为结构性块操作辅助。
+
 ## 1. 本轮结论

 页面 AI 块写入的慢点不在 Rust 块工具本身，也不在 Convex 持久化本身。
@@ -1,22 +1,24 @@
-# 10 [process] 当前 mnote 项目 AI / Page Aggregate 定向 Review v1
+# 10 [done] 当前 mnote 项目 AI / Page Aggregate 定向 Review v1

 > 更新时间：2026-05-17
 >
-> 执行状态：`process`
+> 执行状态：`done`
 >
 > 范围：当前主线中 Page Aggregate 单一真源、页面 AI 快速编辑、`mnote.doc.markdown_edit` 与 ACP / Hermes runtime 的源码级定向审查。

 ## 1. 本轮结论

-本轮没有发现 Page Aggregate 读取主链重新回退到 Next compat builder 的证据；`wolai-frontend/src/lib/documents/page-aggregate-loader.ts` 仍只走 Rust `/api/page-aggregate/:documentId`，`/api/documents/page` compat 读链保持 `410` 退场口径。
+本轮没有发现 Page Aggregate 读取主链重新回退到 Next compat builder 的证据。后续修复已进一步收口：AI context 的 page subtree 只读 Rust Page Aggregate projection，不再由前端本地构造第二份 page tree 真相。

-新的风险集中在 `07-ai` 的 markdown 编辑收敛实现：
+本轮识别出的 `07-ai` markdown 编辑 P0 风险已修复：

- `mnote.doc.markdown_edit` 已进入实际写入主线，并被 `/api/page-ai/block-edit-workflow` 调用。
- 该工具当前先在 markdown 字符串上顺序执行 search/replace，再把原始 operations 重新转换成 `mnote.doc.apply_block_ops`。
- 转换层仍按“单块文本包含 search”查找目标块，无法忠实表达 markdown 层已经算出的最终结果。
+- `mnote.doc.markdown_edit` 是简单正文编辑主路径，并被 `/api/page-ai/block-edit-workflow` 通过统一 mnote tool executor 调用。
+- 中文归一化匹配不再把 UTF-8 byte index 当 char index。
+- 同一块内多次 markdown_edit 会合并到最终 markdown 结果后再映射写回，避免后续 block op 覆盖前序修改。
+- 在线写回在无法安全映射最终 markdown 时明确拒绝，避免 `ok=true` 伪成功。
+- Hermes guidance、manifest、tool toggle、dryRun / idempotency、revision / conflictDetectionKey 与 Reasonix ACP payload 已同步到当前工具合同。

-因此，当前 AI 编辑主线不能只看 `operationsApplied > 0` 或 route 返回 `ok=true`。需要优先补充 `markdown_edit` 的中文、多操作、同块、多块、full_content 与失败原子性测试。
+剩余长期方向仍是 Phase C review session / streaming apply；当前设计冻结，不属于本轮 bug 修复范围。

 ## 2. 发现的问题

@@ -24,7 +26,7 @@

 关联缺陷：

- `bugs/07-ai/process/7-16-markdown-edit-normalized-search-byte-index-v1.md`
+- `bugs/07-ai/done/7-16-markdown-edit-normalized-search-byte-index-v1.md`

 证据：

@@ -41,7 +43,7 @@

 关联缺陷：

- `bugs/07-ai/process/7-17-markdown-edit-same-block-multi-op-overwrite-v1.md`
+- `bugs/07-ai/done/7-17-markdown-edit-same-block-multi-op-overwrite-v1.md`

 证据：

@@ -58,18 +60,20 @@
 - AI 一次请求中常见的“把同一段里的 A 改成 B，同时把 C 改成 D”可能只保留最后一次修改。
 - 前端快路径仍可能显示“已通过页面 markdown 编辑快路径完成写入”，但正文只部分生效。

-## 3. 次级风险
+## 3. 修复状态

- `doc_markdown_edit` 当前允许部分 operation 失败后继续写入已成功的子集，并返回 `ok=true`。如果这是有意设计，需要在 manifest / UI 中明确“非原子”；如果不是，应改为任一 operation 失败时不写入。
- `changedText` 通过 `operations.iter().take(applied)` 生成摘要；当前如果第一个 operation 失败、第二个成功，摘要会错误地展示第一个失败 operation。
- `/api/page-ai/block-edit-workflow` 的系统 prompt 已改成 search/replace，但仍强依赖模型精确复制 `pageText`；一旦模型输出跨块片段，Convex 写回层不能表达该编辑。
+- `mnote.doc.markdown_edit` manifest 已补齐 required / write contract。
+- 本地 `.md` 写入已尊重 dryRun / idempotency。
+- 在线写回已使用最终 markdown 作为真源进行映射；无法安全映射时返回明确错误。
+- `mnote.doc.apply_block_ops` 批量写入已补 revision / conflictDetectionKey 前置校验。
+- `/api/page-ai/block-edit-workflow` 已从绕过 executor 改为复用统一 Hermes mnote tool executor。
+- ACP Reasonix wrapper 已透传 actor/session/run/toolCall/trace/dryRun/idempotency/workspace/document 等上下文字段。

-## 4. 建议下一步
+## 4. 后续边界

-1. 先给 `search_replace` 补中文归一化替换单测，再修正 byte / char offset 映射。
-2. 给 `doc_markdown_edit` 补同一 block 多 operation 的失败用例，明确应以最终 markdown 生成落库内容，或在转换层合并同块操作。
-3. 明确 `markdown_edit` 的失败原子性：默认建议任一 operation 失败时不写入，除非请求显式允许 partial apply。
-4. 将 `/api/page-ai/block-edit-workflow` 的验收从“route 成功”提升为“Page Aggregate 回读与预期最终 markdown 一致”。
+1. Phase C 的 review session / streaming apply 仍冻结，当前不扩新 AI 功能。
+2. 复杂结构编辑继续走 `apply_block_ops` / `mnote.block.*`，不要把正文 search/replace 回退到结构性块工具。
+3. Page Aggregate 仍需后续推进 EditorBlockDocument 原生落库真相。

 ## 5. 本轮验证

@@ -80,9 +84,15 @@ rg -n "markdown_edit|apply_block_ops|block-edit-workflow|local_rule|page_ai_work
 rg -n "page-aggregate|pageAggregate|PageAggregate|blockDocument|projectionSource|documents/save|documents/options|/api/page-aggregate" rust/crates/mnote-web rust/crates/bridge-runtime wolai-frontend/src scripts --glob '!rust/target/**' --glob '!node_modules/**'
 ```

-本轮是 review / bug hunt，没有修改 runtime 源码。后续修复应至少补：
+修复后定向验证：

 ```bash
-cargo test --manifest-path rust/Cargo.toml -p mnote-web markdown_edit
-cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_workflow
+cargo test --manifest-path rust/Cargo.toml -p mnote-web markdown_edit -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_workflow -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_client -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_session_manager -- --nocapture
+node --check scripts/reasonix-acp-wrapper.mjs
+MNOTE_REASONIX_ACP_SELFTEST=1 node scripts/reasonix-acp-wrapper.mjs
 ```
+
+结果：上述验证均通过。
@@ -0,0 +1,53 @@
+# 11 [done] 当前完整架构 Review v1
+
+> 更新时间：2026-05-17
+>
+> 状态：`done`
+>
+> 参考总文档：[CURRENT_ARCHITECTURE.md](../../../CURRENT_ARCHITECTURE.md)
+
+## 1. 结论
+
+当前 mnote 的主线架构已经成形。本轮 review 识别出的 P0 / 内核优先缺陷已完成代码修复、文档迁移和定向验证。
+
+已修复的四个关键冲突：
+
+1. Tree realtime 的发布口径与前端消费口径不一致。
+2. FileTree 资源行误走页面命令。
+3. Page Aggregate / AI context 保留前端第二真相。
+4. AI 写入链路在 `markdown_edit`、`apply_block_ops`、Hermes / ACP / Reasonix 之间的合同漂移。
+
+仍需后续主线继续推进的不是本轮 P0 bug，而是长期架构收口：Page Aggregate 原生 EditorBlockDocument 落库、正文保存主命令面、`tree.resource.*` 资源生命周期和兼容路由瘦身。
+
+## 2. 关键判断
+
+- Rust kernel 与 bridge-runtime 已经承担语义主导权。
+- Rust SSR 主壳已默认以 `/api/realtime/ws` 为实时主链，SSE 是 fallback。
+- FileTree 资源行的 owner document 与页面命令目标已分离。
+- AI context 的 page subtree 已只读 Rust Page Aggregate projection。
+- `mnote.doc.markdown_edit` 已是简单正文编辑主路径，`page_ai_workflow` 复用统一 mnote tool executor，`apply_block_ops` / `mnote.block.*` 仅作为结构性辅助。
+- ACP / Reasonix 的 mnote tool payload、response、run context 与幂等字段已同步到当前工具合同。
+
+## 3. 已闭合 bug
+
+- Rust Web / realtime / ACP：`bugs/03-rust-web/done/3-16` 到 `3-21`
+- Tree domain：`bugs/04-tree-domain/done/4-46`
+- Editor mainline：`bugs/05-editor-mainline/done/5-15` 到 `5-18`
+- AI：`bugs/07-ai/done/7-18` 到 `7-25`
+
+## 4. 验证
+
+- `find bugs -path '*/process/*' -type f | wc -l`
+  - 结果：`0`
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web markdown_edit -- --nocapture`
+  - 结果：9 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_workflow -- --nocapture`
+  - 结果：3 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web acp_client -- --nocapture`
+  - 结果：6 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web ssr::pages::layout::tests -- --nocapture`
+  - 结果：14 passed
+
+## 5. 备注
+
+本次审查的详细架构说明已统一写入根目录：[CURRENT_ARCHITECTURE.md](../../../CURRENT_ARCHITECTURE.md)。
@@ -1,34 +0,0 @@
-# 11 [process] 当前完整架构 Review v1
-
-> 更新时间：2026-05-17
->
-> 状态：`process`
->
-> 参考总文档：[CURRENT_ARCHITECTURE.md](../../../CURRENT_ARCHITECTURE.md)
-
-## 1. 结论
-
-当前 mnote 的主线架构已经成形，但还没有完成单一真源收口。最关键的未闭合点有四个：
-
-1. Tree realtime 的发布口径与前端消费口径不一致。
-2. FileTree 资源行仍可能误走页面命令。
-3. Page Aggregate 仍保留前端第二真相。
-4. AI 写入链路在 `markdown_edit`、`apply_block_ops`、Hermes / ACP / Reasonix 之间存在合同漂移。
-
-## 2. 关键判断
-
- Rust kernel 与 bridge-runtime 已经承担语义主导权。
- 前端仍保留若干本地派生状态，适合过渡，不适合作为长期真相层。
- `mnote.doc.markdown_edit` 已是主推路径，但工具级 contract 还没收口。
- `page_ai_workflow` 与 ACP / Reasonix 已接入主链，但运行时 owner 与写入字段不统一。
-
-## 3. 需要继续跟踪的 bug
-
- Rust Web / realtime / ACP：`bugs/03-rust-web/process/3-16` 到 `3-21`
- Tree domain：`bugs/04-tree-domain/process/4-46`
- Editor mainline：`bugs/05-editor-mainline/process/5-15` 到 `5-18`
- AI：`bugs/07-ai/process/7-18` 到 `7-25`
-
-## 4. 备注
-
-本次审查的详细架构说明已统一写入根目录：[CURRENT_ARCHITECTURE.md](../../../CURRENT_ARCHITECTURE.md)。