chore: align local-first control plane and editor fixes

- wire SQLite control-plane access/session paths into Rust web local-folder routes

- preserve local Markdown attachment semantics across upload, reload, and secondary-pane resource tabs

- refresh design governance docs, Reasonix task templates, and bug records

- retire root .mcp.json local MCP config

design/old/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md

@@ -0,0 +1,490 @@
+# 7-10 [recycle] 页面块 AI 工具执行 checklist v1
+
+> 更新时间：2026-05-16
+>
+> 当前状态：`recycle / old`。
+>
+> 归档说明（2026-05-22）：本文的块级 AI 执行路线已被 local-first Markdown 编辑收敛口径覆盖；当前 active AI 编辑入口以 `design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md` 为准。
+>
+> 关联文档：
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-13-page-block-identity-and-command-contract-v1.md`
+> - `/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/done/2-1-page-block-storage-projection-alignment-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/done/7-9-page-block-ai-tooling-roadmap-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/done/7-6-mnote-hermes-plugin-tool-contract-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md`
+
+---
+
+## 1. 目的
+
+本 checklist 把 `7-9` 的路线图拆成可验收执行链，避免页面块 AI 工具停留在“工具名已设计、真实页面不可回读”的状态。
+
+## 1.0 执行口径修正（2026-05-16）
+
+本文继续作为页面块 AI 工具执行 checklist 保留在 `process/`，不移入 `old/`。但后续所有“页面 AI runtime / fast workflow / planner / apply controller”相关任务必须按 `7-12` 的边界解释：
+
+- Hermes 继续是唯一页面 AI agent runtime。
+- mnote 本地层只提供工具路由、工具提示、上下文冻结、dry-run/review、Rust 写入校验和 readback。
+- `PageAIIntentParser` 后续读作 `PageAICommandRouter`，输出 `recommendedToolCall`，不维护独立对话 runtime。
+- `PageAIOperationPlanner` 后续只构造 tool args 或 dry-run plan，不能绕过 Hermes tool manifest/profile toggle/audit。
+- `PageAIOperationValidator` 继续有效，但归属 mnote Rust tool executor / projection validation。
+- `PageAIApplyController` 后续应收口为 review session / tool executor / readback controller，不能成为第二套 agent 编排中心。
+- 当前 `usedHermesRun=false` 的快路径只能理解为 deterministic shortcut，不代表 mnote 新建长期 agent runtime。
+
+## 1.0.1 当前主路径修正（2026-05-19）
+
+`2-2 local-first` 完成后，本文继续保留为页面块 / 结构性工具 checklist，但普通 Markdown 正文编辑主路径已经转为 VSCode-like 文件编辑：
+
+- local-first 普通正文编辑默认给 Hermes / Reasonix 当前文件引用、selection 和 allowed roots，由 agent 使用自身 patch / diff / 文件编辑能力写本地 `.md`。
+- `mnote.doc.markdown_edit` 是 cloud / remote agent / compat fallback，不再是 local-first 普通 Markdown 编辑唯一主路径。
+- `/api/page-ai/block-edit-workflow` 只保留为兼容门面或非 local source 的快捷路径，不作为 local-first 默认主路径。
+- `mnote.doc.apply_block_ops` / `mnote.block.*` 保留为结构性块操作辅助，例如块移动、资源块、复杂子块或必须按 blockId 精确处理的场景。
+- Phase C 的 review session / streaming apply 仍冻结；本文只继续跟踪基础工具合同、上下文、冲突校验、幂等和审阅面边界。
+- 当前 page AI runtime 口径以 `design/02-convex-rust-long-term-architecture/done/2-2-local-first-workspace-convex-control-plane-v1.md`、`design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md` 和 `design/07-ai/process/7-15-page-ai-acp-agent-runtime-unified-layer-v1.md` 为准。
+
+## 1.1 当前执行状态（2026-05-16）
+
+已完成并有代码/测试/smoke 证据：
+
+- Page Aggregate 输出 `blockDocument/blockProjectionVersion/projectionSource`。
+- `mnote.doc.fetch`、`mnote.doc.find`、`mnote.block.fetch` 已接入 Hermes tool manifest 与 dispatch。
+- `mnote.doc.plan_update` 已提供块级 dry-run 计划和移动阻断诊断。
+- `mnote.block.replace`、`mnote.block.insert_after`、`mnote.block.move_after` 已通过 Rust `EditorCommand` 生成 canonical content，再经 `page.body.save -> documents:updateContent` 持久化。
+- `revision/conflictDetectionKey/revisionRef/idempotencyKey/dryRun` 写入前置约束已接入，并修复 `content_revision` 投影对齐。
+- 真实 smoke：`/mnt/Data1T/mnote/scripts/task-page-block-ai-tools-smoke.js`，证据位于 `/mnt/Data1T/mnote/tmp/page-block-ai-tools-smoke/mp7xgyqs.json` 与同名截图。
+- 页面 AI Runtime `mnote tools` 面板已读取真实 manifest，展示 13 个 mnote tools，并支持当前 Hermes profile 下开关工具。
+- `/api/hermes/client/tools/toggle` 已持久化 `mnote.tools.disabled`；`/api/hermes/tools/mnote/call` 在执行前按 profile 拦截关闭工具，返回 `mnote_tool_disabled`。
+- Hermes 外部 mnote plugin/skill 已完成，不改 Hermes 应用本体：
+  - `/home/lix/.hermes/plugins/mnote/plugin.yaml`
+  - `/home/lix/.hermes/plugins/mnote/__init__.py`
+  - `/home/lix/.hermes/skills/note-taking/mnote-block-ai/SKILL.md`
+- Hermes 外部 plugin schema 已对齐真实块工具参数：`mnote_doc_fetch(scope/detail/format/query/maxBlocks/blockId/selectedBlockIds/allowedTargetBlockIds)`、`mnote_doc_plan_update(command/blockId/anchorBlockId/content)`、`mnote_block_fetch(blockId/includeChildren/contextBefore/contextAfter/format)`。
+- Hermes CLI 真实 plugin 块操作已通过：
+  - 测试页：`workspaceId=tree_1777430834634_3`，`documentId=tree_1778915893346_1`，`suffix=mp80lbze`。
+  - 工具链：`mnote_doc_fetch -> mnote_block_fetch -> mnote_doc_plan_update(dryRun block_replace) -> mnote_block_replace -> mnote_doc_plan_update(dryRun block_insert_after) -> mnote_block_insert_after -> mnote_doc_plan_update(dryRun block_move_after) -> mnote_block_move_after -> mnote_doc_fetch`。
+  - 结果：`finalOrder=["p_1","p_3","ai_block_req_1778916033994_21","p_2"]`，`finalTexts` 分别为 `Hermes 块插件第一段 mp80lbze`、`Hermes 块插件第三段 mp80lbze`、`Hermes 插件插入段 mp80lbze`、`Hermes 插件替换第二段 mp80lbze`，`errors=[]`。
+  - 修复点：Hermes 可能把 `doc.fetch` 返回的 projection `payload/contentNodes` 形状传回写工具，`rust/crates/mnote-web/src/hermes_tools/block.rs` 已补齐 `content_to_text` 解析并加单测，避免 replace/insert 写成空段。
+- 浏览器回读验证已通过：打开 `http://127.0.0.1:3000/documents/tree_1778915893346_1?workspaceId=tree_1777430834634_3` 后四段目标文本可见，截图 `/mnt/Data1T/mnote/tmp/hermes-plugin-block-ai/mp80lbze-page.png`。
+- 页面 AI 工具面板浏览器验证：3000 最新 `mnote-web` 进程下 Runtime 面板可见 13 个工具；关闭 `mnote.block.fetch` 后 `/api/hermes/client/tools` 显示 `enabled=false/status=disabled`，直接调用 `mnote.block.fetch` 返回 `mnote_tool_disabled`，随后已恢复开启；截图 `/mnt/Data1T/mnote/tmp/page-ai-tools-runtime/mnote-page-ai-tools-runtime-20260516.png`。
+- 页面 AI context / format focused smoke 已完成：
+  - 脚本：`/mnt/Data1T/mnote/scripts/task-page-block-ai-context-format-smoke.js`。
+  - 证据：`/mnt/Data1T/mnote/tmp/page-block-ai-context-format-smoke/mp8ddr4n.json`，截图 `/mnt/Data1T/mnote/tmp/page-block-ai-context-format-smoke/mp8ddr4n-page.png`。
+  - 覆盖：`mnote.doc.fetch scope=selection selectedBlockIds=["p_2"] format=page_xml/text`、`mnote.block.fetch format=page_xml/text`、manifest annotations、`mnote.page.save` destructive/yolo 粗粒度兜底定位、`mnote.doc.apply_block_ops allowedTargetBlockIds` 越界阻断 `mnote_block_target_out_of_scope`。
+  - 边界：`doc.apply_block_ops` 与单个 `mnote.block.*` 写工具的 `allowedTargetBlockIds` selection scope guard 均已完成矩阵验证。
+- 页面 AI 快速块编辑第一阶段已完成：
+  - 新增 `/api/page-ai/block-edit-workflow`，简单块增删改不再默认进入 Hermes agent run。
+  - 对明确中文指令 `把「A」替换为「B」/ 在「C」后插入「D」/ 删除「E」` 已先由 mnote 本地 planner 生成 `mnote.doc.apply_block_ops` operations；无法解析时才进入小模型 operations 路径。
+  - 快路径失败时，除 `page_ai_workflow_not_block_edit` 外不再自动 fallback 到 `/api/hermes/client/runs`，避免一次请求叠加“快路径失败成本 + Hermes agent 成本”。
+  - 真实浏览器 smoke：`/mnt/Data1T/mnote/scripts/task-page-ai-block-edit-workflow-smoke.js`，最新证据 `/mnt/Data1T/mnote/tmp/page-ai-block-edit-workflow-smoke/mp86uciu.json`。
+  - 验证结果：`pageAiWriteVisible=788ms`、`usedFastWorkflow=true`、`usedHermesRun=false`；后端日志 `operation_source=local_rule`、`model_ms=0`、`apply_ms=42`、`total_ms=42`。
+  - 详细 review 历史快照：`/mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md`。
+
+仍未完成，本文继续留在 `process/`：
+
+- 剩余真实页面 smoke 已由 `/mnt/Data1T/mnote/design/07-ai/done/7-16-page-block-ai-real-smoke-followup-matrix-v1.md` 完成并归档；本文只保留总 checklist、历史证据和 Phase 8 / Review Mode 冻结缺口。
+- 复杂块移动阻断矩阵已补隔离 route smoke 覆盖标题带子块、列表项、表格、mindmap/resource；真实浏览器页面 smoke 仍未补。
+- 持久审阅/preview UI 仍是后续可选项；当前默认 yolo 模式不做写入审批，`scope=selection` 与 `format=page_xml/text` 已进入工具与 PageAIContextBuilder 首版。
+- PageAIIntentParser / PageAIOperationPlanner / PageAIOperationValidator / PageAIApplyController 仍需继续建设；当前本地 planner 只覆盖低歧义文本块增删改，不应被视为完整 AI 编辑 runtime。
+
+执行顺序固定为：
+
+```text
+fetch/find
+  -> block.fetch
+  -> plan_update
+  -> block.replace
+  -> block.insert_after
+  -> block.move_after
+```
+
+每一步都必须满足：
+
+- Rust command 或 projection 有测试。
+- Hermes tool 有结构化返回。
+- 真实页面 smoke 通过。
+- 写入后能通过 Page Aggregate 与 AI fetch 回读。
+
+---
+
+## 2. Phase 0：设计与基线冻结
+
+- [x] `5-13` 已冻结 block identity、command、Tiptap boundary。
+- [x] `2-1` 已冻结 `documents.content`、`blocks` 表、Page Aggregate、revision/conflict key 的关系。
+- [x] `7-9` 已更新 Tiptap AI Toolkit 对照，不再写成“Tiptap 没有官方 AI 文档工具”。
+- [x] `7-9` 明确 `mnote.page.save` 是粗粒度兜底，不是精确块工具。
+- [x] 当前 reference code 已在 `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-docs` 与 `tiptap-main` 可读。
+
+验收：
+
+- [x] `rg -n "Tiptap AI Toolkit|tiptapRead|tiptapEdit|UniqueID|_hash|blockDocument" design/05-editor-mainline/{process,done} design/02-convex-rust-long-term-architecture/{process,done} design/07-ai/{process,done}` 能找到对应设计。
+
+---
+
+## 3. Phase 1：Page Aggregate Block Projection
+
+目标：
+
+> 每个可编辑块都能从 Page Aggregate 读到稳定身份和冲突辅助信息。
+
+任务：
+
+- [x] `PageBody` 增加 `blockDocument` 或等价稳定字段。
+- [x] 从 `documents.content` 生成 `EditorBlockDocument`。
+- [x] 从 Tiptap JSON 生成 `EditorBlockDocument` 的 bridge 测试覆盖当前主类型。
+- [x] 每个块输出 `blockId/type/text/attrs/children/parentBlockId/order/path/depth/revisionRef/editable`。
+- [x] 对无 id legacy block 生成稳定迁移策略或 warning。
+- [x] 复杂块输出 `editable=false` 或受限能力。
+
+验证命令：
+
+```bash
+cargo test -p core-protocol editor_tiptap_bridge
+cargo test -p bridge-runtime editor_document
+```
+
+真实页面 smoke：
+
+- [x] 登录测试账号并创建综合页面 `TEST-AI-BLOCK-TOOLS-<timestamp>`。
+- [x] 写入段落、标题、todo、列表、mindmap/resource 占位。
+- [x] 调 `/api/page-aggregate/:id` 保存响应到 `tmp/hermes-tester/page-block-ai-tools-<run-id>/page-aggregate.json`。
+- [x] 断言所有普通可编辑块有 `blockId` 和 `revisionRef`。
+
+通过标准：
+
+- [x] 页面刷新后 block ids 不变化。
+- [x] projection 中 `blockCount` 与页面块数量一致；复杂块返回 `editable=false` 与 `unsupportedReason`。
+
+2026-05-18 补充真实页面 smoke 证据：
+
+- 最新证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，Page Aggregate：`tmp/hermes-tester/page-block-ai-tools-mpag4966/page-aggregate.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- 覆盖：Page Aggregate `blockProjectionVersion=1`、`projectionSource=documents.content`、`aggregateBlockCount=10`，与 `mnote.doc.fetch` 块顺序一致；刷新后 `afterRefreshBlockIds` 保持最终顺序；`table_1/mindmap_1/resource_1` 返回 `editable=false` 与 `unsupportedReason=复杂块暂不开放 AI 精确写入`。
+
+---
+
+## 4. Phase 2：`mnote.doc.fetch` / `mnote.doc.find`
+
+目标：
+
+> AI 能先读取和定位，不需要猜整页 `content` shape。
+
+任务：
+
+- [x] tool manifest 增加 `mnote.doc.fetch`。
+- [x] tool manifest 增加 `mnote.doc.find`。
+- [x] `doc.fetch` 支持 `scope=full/outline/keyword/block/selection`。
+- [x] `doc.fetch` 支持 `detail=simple/with_ids/full`。
+- [x] `doc.find` 支持按 text/type/blockId 查找。
+- [x] 返回 page `revision/conflictDetectionKey`。
+- [x] 返回可直接传入 `block.fetch/replace/insert_after` 的 `blockId`。
+
+验证命令：
+
+```bash
+cargo test -p mnote-web hermes_tools
+cargo test -p bridge-runtime doc_find
+```
+
+真实页面 smoke：
+
+- [x] 使用综合页面 `TEST-AI-BLOCK-TOOLS-<timestamp>`。
+- [x] `mnote.doc.fetch scope=full detail=with_ids` 读取整页。
+- [x] `mnote.doc.fetch scope=outline detail=with_ids` 只返回标题结构。
+- [x] `mnote.doc.find query=<唯一前缀>` 定位目标段落。
+- [x] 保存工具返回到 `tmp/hermes-tester/page-block-ai-tools-<run-id>/doc-fetch-find.json`。
+
+补充 smoke 证据：
+
+- [x] `mnote.doc.fetch scope=selection selectedBlockIds=["p_2"] format=page_xml` 读取真实页面选区上下文，只返回 `p_2`，返回 `schema=mnote.page_ai_context.v1`、`allowedTargetBlockIds=["p_2"]`、`revision/conflictDetectionKey` 和 block `revisionRef`。证据：`tmp/page-block-ai-context-format-smoke/mp8ddr4n.json`。
+- [x] `mnote.doc.fetch scope=selection format=text` 只返回 `[p_2] 第二段 mp8ddr4n`，不包含未选中块。证据：`tmp/page-block-ai-context-format-smoke/mp8ddr4n.json`。
+
+通过标准：
+
+- [x] 不读取浏览器 DOM。
+- [x] `doc.find` 返回的 block id 能被 `block.fetch` 读取。
+- [x] 大页面默认分块或限制输出，不默认返回无限正文。
+
+2026-05-18 补充证据：
+
+- `mnote.doc.fetch` 从 `aggregate_value` / Page Aggregate block projection 构造上下文，不读取浏览器 DOM；代码入口：`rust/crates/mnote-web/src/hermes_tools/doc.rs`。
+- `hermes_tools_doc_find_and_block_fetch_use_block_projection` 覆盖 `doc.find` 返回 `heading_1` 后继续用同一个 id 调 `mnote.block.fetch`。
+- `mnote.doc.fetch` 默认 `maxBlocks=120`，运行时 clamp 到 `1..=240`；超限返回 `truncated/continuation/warnings`。
+- 真实 3000 smoke：`tmp/page-block-ai-tools-smoke/mpaes2hg.json` 覆盖 `doc.fetch full` 读取 `heading_1/p_1/p_2/p_3`，`doc.fetch outline` 只返回 `heading_1`，`doc.find` 定位 `p_2`，`maxBlocks=2` 返回 `truncated=true`。
+
+---
+
+## 5. Phase 3：`mnote.block.fetch`
+
+目标：
+
+> AI 能读取单块、子块和同父级上下文，形成写入前确认。
+
+任务：
+
+- [x] tool manifest 增加 `mnote.block.fetch`。
+- [x] 支持 `includeChildren`。
+- [x] 支持 `contextBefore/contextAfter`。
+- [x] 支持 `format=json/markdown/page_xml/text`。
+- [x] 返回 `revisionRef`、`editable`、`unsupportedReason`。
+- [x] 不存在 block 返回 `mnote_block_not_found`。
+
+验证命令：
+
+```bash
+cargo test -p mnote-web block_fetch
+```
+
+真实页面 smoke：
+
+- [x] 从 `doc.find` 结果选择一个段落 block。
+- [x] 调 `mnote.block.fetch includeChildren=true contextBefore=1 contextAfter=1`。
+- [x] 断言 before/after 只来自同父级。
+
+补充 smoke 证据：
+
+- [x] `mnote.block.fetch blockId=p_2 format=page_xml/text contextBefore=1 contextAfter=1` 返回目标块 `p_2`、`revisionRef` 与同父级 before/after `p_1/p_3`。证据：`tmp/page-block-ai-context-format-smoke/mp8ddr4n.json`。
+- [x] `doc.find` 定位 `p_2` 后，`mnote.block.fetch includeChildren=true contextBefore=1 contextAfter=1` 回读 `p_2`，返回 `revisionRef`、同父级 before `p_1` 和 after `p_3`。证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`。
+- [x] `table_1/mindmap_1/resource_1` 复杂块在真实 3000 smoke 中返回 `editable=false` 与 `unsupportedReason=复杂块暂不开放 AI 精确写入`。证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`。
+
+通过标准：
+
+- [x] block 文本与页面显示一致。
+- [x] `revisionRef` 可被后续 dry-run 使用。
+- [x] 复杂块不会伪装成完全可编辑。
+
+---
+
+## 6. Phase 4：`mnote.doc.plan_update`
+
+目标：
+
+> 所有写入先 dry-run，返回 diff、warnings、risk，不改变页面。
+
+任务：
+
+- [x] tool manifest 增加 `mnote.doc.plan_update`。
+- [x] 支持 `command=block_replace`。
+- [x] 支持 `command=block_insert_after`。
+- [x] 支持 `command=block_move_after` dry-run。
+- [x] `command=str_replace` 不再作为本 checklist 当前目标；cloud / remote / compat 的普通正文 search/replace 已收口到 `mnote.doc.markdown_edit`，多重匹配/无法安全映射阻断由 markdown_edit 合同覆盖。local-first 普通 Markdown 编辑默认走授权文件 + agent 原生 patch/diff。
+- [x] 缺少 `revision/conflictDetectionKey` 时只允许 dry-run。
+- [x] 返回 `planId`、`diff`、`warnings`、`risk`、`blocked`。
+
+2026-05-19 口径修正：
+
+- `7-18` 到 `7-25` 收口后，普通正文替换不再继续扩 `mnote.doc.plan_update command=str_replace`；compat 实现路径是 `page_ai_workflow.rs -> mnote.doc.markdown_edit`。
+- `mnote.doc.markdown_edit` 已覆盖精确匹配、归一化匹配、多操作同块合并、无法安全映射时失败；相关测试由 `cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture` 覆盖。它不再代表 local-first 普通 Markdown 编辑默认入口。
+
+验证命令：
+
+```bash
+cargo test -p mnote-web plan_update
+cargo test -p bridge-runtime doc_replace_range
+cargo test -p bridge-runtime doc_insert_blocks
+```
+
+真实页面 smoke：
+
+- [x] 对目标段落执行 `block_replace dryRun=true`。
+- [x] 对目标段落执行 `block_insert_after dryRun=true`。
+- [x] 对两个同父级普通块执行 `block_move_after dryRun=true`。
+- [x] dry-run 前后分别读取 `/api/page-aggregate/:id` 与 `mnote.doc.fetch`，确认 revision / conflictDetectionKey / 正文文本不变。
+
+通过标准：
+
+- [x] dry-run 不写 Convex。
+- [x] plan 能解释 before/after。
+- [x] 不支持场景返回 `blocked=true`。
+
+2026-05-18 补充真实页面 smoke 证据：
+
+- 最新证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- 覆盖：`plan_update.dry_run.replaceDiff.before/after`、`insertDiff.after/content`、`block_move_after p_3 -> p_1 dryRun` 不阻断、不支持 `p_3 -> p_3` 返回 `blocked=true`、dry-run 后 revision / Page Aggregate conflictDetectionKey / 正文文本不变。
+
+---
+
+## 7. Phase 5：`mnote.block.replace`
+
+目标：
+
+> 第一条最小精确块写入闭环。
+
+任务：
+
+- [x] tool manifest 增加 `mnote.block.replace`。
+- [x] 输入必须包含 `blockId/revision/conflictDetectionKey/idempotencyKey/dryRun`。
+- [x] `dryRun=true` 只返回 plan。
+- [x] `dryRun=false` 生成 `EditorCommand::ReplaceBlock`。
+- [x] Rust 应用命令生成 canonical content。
+- [x] 通过 `page.body.save -> documents:updateContent` 持久化。
+- [x] 返回新 revision、changedBlocks、audit。
+
+验证命令：
+
+```bash
+cargo test -p mnote-web block_replace
+cargo test -p bridge-runtime doc_replace_range_tool_executes_in_rust_runtime
+```
+
+真实页面 smoke：
+
+- [x] 使用综合页面 `TEST-AI-BLOCK-TOOLS-<timestamp>`。
+- [x] 写入两段不同文本。
+- [x] `doc.find` 找到第二段 block id。
+- [x] `block.replace dryRun=true` 查看 plan。
+- [x] `block.replace dryRun=false` 替换第二段。
+- [x] 页面截图和工具回读证明只替换第二段。
+- [x] `/api/page-aggregate/:id` 回读证明持久化。
+- [x] `mnote.doc.fetch` 再次证明 AI 可读回。
+
+通过标准：
+
+- [x] 相邻块不变化。
+- [x] 目标 block id 保持不变。
+- [x] 旧 revision 写入返回 conflict。
+
+2026-05-18 补充真实页面 smoke 证据：
+
+- 最新证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- 覆盖：`block.replace.changedBlocks[0]={blockId:"p_2",op:"replace"}`，`targetBlockStillExists=true`，相邻块仍为 `第一段 mpag4966` / `第三段 mpag4966`，最终 `mnote.doc.fetch` 与 Page Aggregate 均回读到 `第二段已替换 mpag4966`，Page Aggregate `aggregateRevision=2`、`aggregateConflictDetectionKey=tree_1779062903017_3:2`。
+- 冲突 / 幂等补充证据：`tmp/page-block-ai-conflict-idempotency-smoke/mpafrevs.json`，截图：`tmp/page-block-ai-conflict-idempotency-smoke/mpafrevs-page.png`。
+- 覆盖：首次 `block.replace` 携带最新 `revision/conflictDetectionKey/blockRevisionRef/idempotencyKey` 成功写入；重复同一 `idempotencyKey` replay 同一 `commandId` 且 revision 不再次递增；旧 `revision/conflictDetectionKey` 与旧 `blockRevisionRef` 均返回 HTTP `400` / `mnote_tool_conflict`，正文保持首次替换结果。
+
+---
+
+## 8. Phase 6：`mnote.block.insert_after`
+
+目标：
+
+> AI 能在指定块后插入新块，并拿到新 block id。
+
+任务：
+
+- [x] tool manifest 增加 `mnote.block.insert_after`。
+- [x] 输入必须包含 `anchorBlockId/revision/conflictDetectionKey/idempotencyKey/dryRun`。
+- [x] 新块 id 由 Rust runtime 分配。
+- [x] 支持单块和最多 20 个普通块插入。
+- [x] 第一阶段支持 paragraph/heading/todo。
+- [x] 返回 inserted block ids 和新 revision。
+
+2026-05-18 补充证据：
+
+- `rust/crates/mnote-web/src/hermes_tools/block.rs` 的 `mnote.block.insert_after` 已支持 `content` / `block` 单块兼容输入，以及 `blocks` 数组输入。
+- `blocks` 运行时限制为 `1..=20`，超过 20 个返回 `mnote_tool_bad_request`；多块写入按输入顺序连续插在 anchor 后。
+- `rust/crates/mnote-web/src/hermes_tools/manifest.rs` 的 manifest 已将 `content | block | blocks` 写为 `anyOf`，并声明 `blocks.minItems=1/maxItems=20`。
+- 新增回归：`hermes_tools_block_insert_after_accepts_multiple_blocks_and_returns_ids`、`hermes_tools_block_insert_after_rejects_more_than_twenty_blocks`。
+
+验证命令：
+
+```bash
+cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_block_insert_after -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture
+cargo test -p bridge-runtime doc_insert_blocks_tool_emits_editor_commands
+```
+
+真实页面 smoke：
+
+- [x] 使用综合页面 `TEST-AI-BLOCK-TOOLS-<timestamp>`。
+- [x] 在第一段后插入 todo。
+- [x] 截图证明位置准确。
+- [x] 刷新页面后再次确认。
+- [x] `mnote.block.fetch` 能读取新 block id。
+
+通过标准：
+
+- [x] 插入位置准确。
+- [x] 新 block id 不是 AI 自造未校验 id。
+- [x] 重复同一 `idempotencyKey` 不重复插入。
+
+2026-05-18 补充证据：
+
+- `mnote.block.insert_after` 运行时分配 `ai_block_{request_id}` 或多块 `ai_block_{request_id}_{index}`，不会采用模型输入中的未校验 id。
+- `hermes_tools_block_insert_after_accepts_multiple_blocks_and_returns_ids` 断言返回的 `insertedBlockIds` 均以 `ai_block_` 开头。
+- 真实 3000 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`。
+- 覆盖：`insert_after` 插入 `todo` 块、`orderAfterInsert=["heading_1","p_1","ai_block_req_1779061213631_259","p_2","p_3"]`、`block.fetch` 可读取新块、重复 `idempotencyKey` replay 同一 `commandId` 且 revision 不再次递增、刷新后插入文本仍可见。
+
+---
+
+## 9. Phase 7：`mnote.block.move_after`
+
+目标：
+
+> 第一阶段只开放同父级普通叶子块移动。
+
+任务：
+
+- [x] tool manifest 增加 `mnote.block.move_after`。
+- [x] `dryRun=true` 支持同父级叶子块 diff。
+- [x] `dryRun=false` 前先继续阻断所有复杂块。（已有同父级/叶子/类型/editable/self 阻断，复杂块矩阵 route smoke 已补。）
+- [x] 检查 `blockRevisionRef` 与 `anchorRevisionRef`。
+- [x] 阻断移动到自身、移动到子树、跨页面移动。
+- [x] 返回 from/to parent/order。
+
+2026-05-18 补充证据：
+
+- `mnote.block.move_after` 保持同父级、叶子块、可移动类型、editable、自身移动阻断条件。
+- 新增隔离 fixture route smoke：`hermes_tools_block_move_after_blocks_complex_and_nested_blocks`，覆盖标题带子块、列表项、表格、mindmap、resource，均返回 `blocked=true` 与 `block_move_after_blocked`。
+
+验证命令：
+
+```bash
+cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_block_move_after_blocks_complex_and_nested_blocks -- --nocapture
+cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools -- --nocapture
+cargo test -p mnote-editor-core command_executor
+```
+
+真实页面 smoke：
+
+- [x] 使用综合页面 `TEST-AI-BLOCK-TOOLS-<timestamp>`，包含三段普通段落。
+- [x] dry-run 移动第三段到第一段后。
+- [x] 正式执行同父级移动。
+- [x] 截图证明顺序为第一段、第三段、第二段。
+- [x] `mnote.doc.fetch` 回读顺序一致。
+- [x] 对标题带子块、列表项、表格、mindmap 执行 move dry-run，必须返回 blocked。
+
+通过标准：
+
+- [x] moving block id 保持不变。
+- [x] 同父级顺序正确。
+- [x] 复杂块不被误移动。
+
+2026-05-18 补充真实页面 smoke 证据：
+
+- 最新证据：`tmp/page-block-ai-tools-smoke/mpag4966.json`，截图：`tmp/page-block-ai-tools-smoke/mpag4966-page.png`。
+- 覆盖：`heading_parent/list_item_1/table_1/mindmap_1/resource_1` 的 `plan_update block_move_after dryRun=true` 与正式 `mnote.block.move_after dryRun=false` 均返回 `blocked=true` / `block_move_after_blocked`，阻断后 `revisionAfterBlocked=1` 且正文不变化；普通 `block.move_after.dryRunBlocked=false`，正式写入后顺序为 `heading_1,p_1,p_3,ai_block_...,p_2,...`，`movingBlockStillExists=true`。
+
+---
+
+## 10. Phase 8：UI 与 Review Mode
+
+目标：
+
+> AI 写入可解释、可确认，不把 preview 当持久审阅事实。
+
+任务：
+
+- [ ] Hermes tool event UI 展示 `plan/diff/warnings/risk`。
+- [x] `page.save` 标记为粗粒度高风险兜底。
+- [x] `block.replace/insert_after/move_after` 展示 changedBlocks。
+- [x] manifest annotations 能区分只读 / 粗粒度破坏性写入 / selectionEffect / runtimeOwner / writeOwner；`mnote.page.save` 在 manifest 中为 `destructive=true`、`approvalMode=yolo`，不作为精确块编辑主入口。证据：`tmp/page-block-ai-context-format-smoke/mp8ddr4n.json`。
+- [ ] 本地 preview/suggestion 与持久 comment/tracked-change 分开。
+- [ ] 协作可见审阅必须另走正式 comment/history/tracked-change 设计。
+
+通过标准：
+
+- [ ] 用户能看到 AI 将改哪个 block。
+- [ ] `blocked=true` 的工具调用不会出现写入按钮。
+- [ ] preview 不写入正式 comment/history。
+
+---
+
+## 11. DONE 条件
+
+本 checklist 不能移动到 `done/`，直到：
+
+- [x] Phase 1 到 Phase 6 全部完成。
+- [x] Phase 7 至少完成 dry-run 和阻断规则；若真实 move 未完成，`7-9` 必须仍标注受限。
+- [x] 每个写工具都有真实页面 smoke 证据。
+- [x] 失败项已经写入 `bugs/07-ai/process/` 或真实 owner 分类。
+- [x] `mnote.page.save` 不再被任何设计描述为精确块编辑主入口。
+- [ ] Phase 8 UI / Review Mode 仍按 Phase C 边界冻结；若后续进入实施，需要另补 UI smoke。

design/old/07-ai/process/7-14-local-first-ai-markdown-editing-convergence-v1.md

@@ -0,0 +1,758 @@
+# 7-14 [recycle][process] Local-first AI Markdown 编辑路径收敛 v2
+
+> 创建时间：2026-05-16
+>
+> 更新时间：2026-05-22（recycle：本文仍受 CLI Main / tool-first 旧口径影响，已移入 old，不再作为当前 AI 编辑实现依据）
+>
+> 归档说明（2026-05-22）：本文试图从旧在线 / 本地收敛稿修正为 local-first，但仍把 CLI Main 与 `mnote.doc.*` 兼容工具放在过高位置，不符合当前 SQLite control-plane + local-first `.md` + agent 原生文件 patch/diff 主线。后续应新建更小的 active 设计稿，直接基于 SQLite、allowed roots、file refs、watcher、BufferStore、Page Aggregate 前台同步和审计链设计。
+>
+> 2026-05-18 口径补充：
+> - local-first workspace 已成为早期产品默认形态；本地 `.md` 是默认 AI 编辑目标；旧 Convex 文档只作为历史迁移源或显式 compat/source replica 边界。
+> - 本文早期把 `mnote.doc.markdown_edit` 描述为统一主路径；最新口径改为：local-first 普通 Markdown 编辑优先给 agent 授权文件引用，由 agent 使用自身成熟的 diff / apply_patch / 文件编辑能力完成；`mnote.doc.markdown_edit` 保留为显式 remote agent / compat fallback。
+> - 页面内图片 / 附件上传已在 local source 下写入 `{mdBase}.assets/` 并保存相对 Markdown 路径，AI 后续处理附件引用时也应保留相对路径，不改写为历史 media asset。
+>
+> 2026-05-22 口径纠正：
+> - 当前 Convex runtime / functions 已退役，不再作为当前正文主链、默认控制面、AI 会话主存储或新增能力目标。
+> - 本文中的“在线文档”仅可理解为历史迁移源、显式 cloud compat / remote agent 边界或未来 sync replica，不再与 local-first `.md` 并列为当前主路径。
+> - 当前主线应写成：本地 `.md` 文件 + Rust SQLite control-plane + allowed roots / file references + agent 原生 patch/diff + watcher / BufferStore / Page Aggregate 前台同步。
+>
+> 当前状态：`PROCESS`
+>
+> 本稿目的：
+> 1. 纠正 7-9 / 7-10 / 7-12 / 7-13 中隐含的「块级编辑是 AI 唯一写入路径」假设
+> 2. 基于 CLI Main 参考实现，确立 mnote 的「agent 原生文件 patch/diff 为 local-first 默认路径，MNote 文本级兼容工具 + 块级结构性操作为 fallback / 辅助」两层模型
+> 3. 规划 BlockNote AI 流式/review 能力的远期方向（当前不实施）
+> 4. 明确历史 cloud / remote / compat 文档边界，并把当前 AI 读取、权限、冲突与回读口径收口到 local-first `.md` 文件
+>
+> 关联文档：
+> - `/mnt/Data1T/mnote/design/07-ai/done/7-9-page-block-ai-tooling-roadmap-v1.md`
+> - `/mnt/Data1T/mnote/design/old/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/reference/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/done/7-13-page-block-editor-runtime-actor-v1.md`
+> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-13-rust-web-local-markdown-gfm-ast-parser-migration-v1.md`
+> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-22-local-folder-convex-unified-tree-execution-checklist-v1.md`
+> - `/mnt/Data1T/mnote/bugs/07-ai/process/page-ai-block-edit-model-fallback-missing-content.md`
+>
+> 参考实现（已分析）：
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/cli-main/` — **主参考**：skill 系统、scope/detail 上下文、两层操作、工作流、参考文件模式、CI 校验
+>   - `skills/lark-doc/SKILL.md` + `references/`
+>   - `skill-template/`（master-skill-template.md、skill-template.md）
+>   - `shortcuts/doc/`、`internal/skillscheck/`
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocknote-ai/packages/xl-ai/` — 远期参考：流式/review
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-ai-autocomplete/` — 独立功能：内联补全
+>
+> 上位依据：
+> - `/mnt/Data1T/mnote/ARCHITECTURE.md`
+> - `/mnt/Data1T/mnote/design/01-05-current-priority-overview.md`
+
+---
+
+## 1. 结论
+
+**当前事实源是 local-first `.md` 文件，Tiptap 只是块级 UI 表现层。** Convex 相关正文链已经退役为历史 / compat 边界，不能再和本地 `.md` 并列描述为当前主路径。既然默认对象已经是普通 Markdown 文件，就不需要再为常规正文编辑发明一套 MNote 专用块级工具。当前 07-ai 设计把 AI 编辑契约钉死在 `EditorBlockDocument` 的块级操作上，导致三个连锁问题：
+
+1. **AI 被迫在块级操作**：对「改写这段话」「补充一段总结」「调整语气」「把所有 TODO 改成 DONE」等自然请求，AI 必须产出 `{ op: "replace", blockId: "block_1", ... }` 格式的块操作，而不能直接产出修改后的文本或搜索替换对。这增加了 AI 的认知负担和出错概率。
+
+2. **旧块级工具不适合 local-first `.md`**：本地文件没有稳定的 `blockId`（每次解析重新分配），因此块级工具不能作为普通 Markdown 编辑默认路径。
+
+3. **历史 compat 容易污染当前主线**：如果继续把 Convex / online 文档写成并列路径，后续实现会误把 `mnote.doc.*` 或 `documents.save` 当成新增能力入口，而不是 local-first 的 fallback / 迁移边界。
+
+### 参考实现的验证
+
+分析了三个参考实现后，确认 mnote 的方向是正确的：
+
+| 参考实现 | AI 编辑模型 | mnote 采纳 |
+|----------|-----------|-----------|
+| **CLI Main (Lark Doc)** | 文本级 `str_replace` + 块级 `block_replace/insert_after/delete/move_after` 两层操作 | ✅ **主参考**：两层模型 + AI skill 合同设计 |
+| **BlockNote AI** | 纯块级 `add/update/delete`（依赖 blockId），流式 apply + suggest/review | ✅ **远期参考**：流式/review 能力，Phase C 规划 |
+| **Tiptap AI Autocomplete** | 纯文本补全，单句接龙，无工具 | ⏳ 独立功能：内联 AI 补全（非本文讨论范围） |
+
+**CLI Main 最关键的设计决策**：它不把 AI 钉死在某一层。`str_replace` 用于文本级修改（不需要 blockId），`block_*` 用于精确块结构调整。格式上，**XML 用于精确编辑场景，Markdown 用于整篇导入/导出**。mnote 的不同之处在于：local-first 之后，默认对象就是本地 `.md` 文件，因此可以直接复用 Codex / Hermes / Reasonix 自身成熟的 diff、apply_patch、文件编辑能力；MNote 的职责收口为权限沙箱、文件引用解析、审计和刷新。
+
+### 正确方向
+
+> mnote 的 AI 编辑路线：**本地授权文件 + agent 原生 patch/diff 为主；MNote 兼容工具仅用于显式 cloud/remote compat 或结构化辅助；BlockNote AI 的流式/review 只作为远期交互参考。**
+
+具体：
+
+- **当前实施**（Phase A/B）：local-first 页面 AI 只传当前文件引用、可选 selection 和用户指令；MNote 校验 `AiAccessScope` 后让 agent 在受限目录中使用原生 patch/diff 编辑 `.md`。`mnote.doc.markdown_edit` 只作为显式 cloud / remote agent / compat fallback，`mnote.block.*` 只作为复杂结构辅助。
+- **远期规划**（Phase C）：BlockNote AI 的流式增量 apply + suggest/review 层。当前先设计，不实施。
+
+---
+
+## 2. 参考实现详解
+
+### 2.1 CLI Main（Lark Doc）— 两层操作模型
+
+CLI Main 的 `skills/lark-doc/SKILL.md` 是飞书文档的 AI skill 定义。它把文档操作分成两层：
+
+**文本级操作**（不需要 blockId）：
+
+```
+docs +update --command str_replace --search "原文片段" --replace "新文本"
+```
+
+AI 只需要匹配文本，不需要知道块在哪儿。适用于所有内容修改场景。
+
+**块级操作**（需要 blockId）：
+
+```
+docs +update --command block_replace --block-id "block_1" --content "<xml>...</xml>"
+docs +update --command block_insert_after --block-id "block_1" --content "<xml>...</xml>"
+docs +update --command block_delete --block-id "block_1"
+docs +update --command block_move_after --block-id "block_3" --target-block-id "block_1"
+```
+
+适用于精确块结构调整。AI 需要知道 `blockId`，因此依赖前置的 `docs +fetch` 返回带 id 的内容。
+
+**格式选择规则**（CLI Main 的 skill 中内联）：
+
+| 场景 | 格式 | 原因 |
+|------|------|------|
+| 精确块编辑（替换/插入/删除指定块） | XML | XML 保留块 id、类型、属性 |
+| 整篇文档导入/导出 | Markdown | 人类可读，和 `.md` 文件互通 |
+| AI 对话中的内容引用 | Markdown | 模型理解 markdown 远好于 XML |
+
+**对 mnote 的启示**：
+
+1. **两层操作模型直接适用**。mnote 的 `markdown_edit` = CLI Main 的 `str_replace`（文本级），`apply_block_ops` = CLI Main 的 `block_*`（块级）。
+2. **但 mnote 的主格式是 markdown 而非 XML**。当前 local-first 正文事实源就是本地 `.md`，历史 cloud / compat 内容也只能先投影为 markdown 后进入兼容工具。所以我们不需要 XML 这一层——markdown 既是 AI 编辑格式，也是人类可读格式。
+3. **CLI Main 的 skill 格式**（YAML frontmatter + Markdown body，定义 tool shortcuts + 上下文格式规范）值得学习。mnote 的 Hermes `mnote` plugin 可以用类似方式组织。
+
+#### 2.1.1 Skill YAML 前端元数据
+
+> 参考文件：`skill-template/master-skill-template.md`、`skill-template/skill-template.md`、`scripts/skill-format-check/index.js`
+
+每个 skill 文件以 YAML frontmatter（`---` 包裹）开头：
+
+```yaml
+---
+name: lark-doc
+description: "飞书云文档 / Docx / 知识库 Wiki 文档（v2）：创建、打开、读取..."
+metadata:
+  requires:
+    bins: ["lark-cli"]
+  cliHelp: "lark-cli docs --api-version v2 --help; ..."
+---
+```
+
+CI 自动化校验（`skill-format-check.yml` + `scripts/skill-format-check/index.js`）确保 `name` 和 `description` 必填。
+
+**→ mnote 采纳**：Hermes 的 `mnote` plugin 已采用 YAML frontmatter（`/home/lix/.hermes/plugins/mnote/plugin.yaml`）。在此基础上规范化：
+- `name`：`mnote`
+- `description`：一段完整的 skill 描述，含覆盖的工具和适用场景
+- `metadata.domain`：`mnote-doc`（文档域），后续可扩展 `mnote-tree`、`mnote-file`
+- CI 校验：确保每个 plugin 的 `plugin.yaml` 含必填字段
+
+#### 2.1.2 Scope / Detail 上下文控制
+
+> 参考文件：`skills/lark-doc/references/lark-doc-fetch.md`、`shortcuts/doc/docs_fetch_v2.go`
+
+CLI Main 的 `docs +fetch` 支持五个 `--scope` 级别，精确控制注入 AI 上下文的文档量：
+
+| `--scope` | 返回内容 | AI 场景 |
+|-----------|---------|--------|
+| `outline` | 标题树（h1-hN）+ blockId | "给我看目录" |
+| `section` | 指定标题下的完整节 | "精读第三章" |
+| `range` | blockId 区间 | "给我 100-200 行" |
+| `keyword` | 关键词周围最小片段 | "找提到 deployment 的地方" |
+| `full`（默认） | 全文 | 最后手段 |
+
+三个 `--detail` 级别控制元数据量：
+
+| `--detail` | blockId | 样式属性 | AI 场景 |
+|-----------|---------|---------|--------|
+| `simple` | ❌ | ❌ | 只读、总结 |
+| `with-ids` | ✅ | ❌ | 需要精确寻址时 |
+| `full` | ✅ | ✅ | 即将编辑该节 |
+
+片段包装：`<fragment requested-start="..." requested-end="...">` 和 `<excerpt top-block-id="..." parent-block-path="...">` 标记告知 AI"这是部分视图，非完整块"。
+
+**→ mnote 采纳**（高优先级）：
+
+```
+mnote.doc.fetch({
+  scope: "section" | "outline" | "keyword" | "full",
+  detail: "simple" | "with_ids" | "full",
+  format: "markdown",
+  maxChars: 8000
+})
+```
+
+- `scope` 的四级映射：outline（标题树）、section（当前节）、keyword（搜索关键词）、full（全文）
+- `detail` 的三级映射：simple（纯文本）、with_ids（带块标记）、full（带属性）
+- 片段包装：markdown 中用 `<!-- fragment: section "标题" -->` 注释标记部分视图边界
+- 实现位置：`mnote-web` 的 `mnote.doc.fetch` handler
+
+#### 2.1.3 更新工作流：Code-Act Loop
+
+> 参考文件：`skills/lark-doc/references/style/lark-doc-update-workflow.md`
+
+CLI Main 的文档编辑遵循 **Plan → Execute → Observe → Iterate** 四步循环：
+
+```
+1. Plan（先读后改）：
+   docs +fetch --scope section --detail full
+   → 分析当前状态 → 制定操作序列
+
+2. Execute（精准手术，不全量覆盖）：
+   默认用 str_replace / block_insert_after / block_delete
+   block_move_after 用于重排
+   overwrite 仅在有明确指令时使用
+   append + block_delete 组合优于 overwrite
+
+3. Observe（每次写后回读）：
+   docs +fetch --scope section
+   → 确认修改正确
+
+4. Iterate（修复差异）：
+   如发现偏差 → 回到 Plan
+```
+
+更新命令决策树：
+
+```
+需要修改文本内容（不改块结构）？
+  → str_replace（文本级，不需要 blockId）
+需要整段替换？
+  → block_replace --block-id xxx（需要先 fetch --detail with_ids）
+需要插入/删除？
+  → block_insert_after / block_delete
+需要重排结构？
+  → block_move_after / block_copy_insert_after
+```
+
+**→ mnote 采纳**（当前 Hermes 的 `mnote` plugin 应内置此工作流）：
+
+- Hermes `mnote` skill 的 `SKILL.md` 中内联 Code-Act Loop 指导
+- `mnote.doc.markdown_edit`（文本级搜索替换）优先于 `mnote.doc.apply_block_ops`（块级精确操作）
+- 模型 system prompt 追加："永远不要在不确定时使用全文覆盖；优先搜索替换；每次写入后回读确认"
+
+#### 2.1.4 参考文件分离模式
+
+> 参考文件：`skills/lark-doc/references/`（24 个独立 .md 文件）
+
+CLI Main 把详细工具规格从主 `SKILL.md` 中分离到 `references/` 子目录：
+
+```
+skills/lark-doc/
+  SKILL.md              ← 技能概述 + 决策表 + 路由规则
+  references/
+    lark-doc-fetch.md   ← fetch 工具详细规格
+    lark-doc-update.md  ← update 工具详细规格
+    lark-doc-xml.md     ← XML 块语法参考
+    lark-doc-md.md      ← Markdown 格式规则
+    style/
+      lark-doc-update-workflow.md  ← 编辑工作流
+      lark-doc-style.md            ← 写作风格指南
+```
+
+**→ mnote 采纳**：Hermes `mnote` plugin 应采用相同结构：
+
+```
+~/.hermes/plugins/mnote/
+  plugin.yaml              ← YAML 前端元数据
+  SKILL.md                 ← 技能概述 + 工具决策表
+  references/
+    mnote-doc-fetch.md     ← fetch 详细规格（scope/detail/format）
+    mnote-doc-update.md    ← 更新命令规格（search/replace + block ops）
+    mnote-doc-workflow.md  ← Code-Act Loop
+    mnote-doc-context.md   ← 上下文冻结与格式化规则
+```
+
+#### 2.1.5 跨域资源路由
+
+> 参考文件：`skills/lark-doc/SKILL.md`（嵌入式资源路由表）
+
+CLI Main 的 lark-doc skill 定义了嵌入式资源的显式路由表：
+
+```
+| 嵌入标签                     | 提取字段                  | 代理 skill    |
+|-----------------------------|--------------------------|---------------|
+| <sheet token="..." ...>     | token → spreadsheet_token | lark-sheets   |
+| <bitable token="..." ...>   | token → app_token        | lark-base     |
+| <whiteboard token="...">    | board_token              | lark-whiteboard|
+```
+
+**→ mnote 采纳**（远期，当文档内嵌入其他资源类型时）：
+- local-first Markdown 中嵌入的思维导图资源 → 路由到 `mnote-mindmap` skill
+- 嵌入的附件/文件 → 路由到 `mnote-file` skill
+- 当前 Phase A 不实施，预留路由表字段
+
+#### 2.1.6 格式策略：XML vs Markdown
+
+> 参考文件：`skills/lark-doc/references/lark-doc-xml.md`、`lark-doc-md.md`
+
+CLI Main 的格式选择规则：
+
+| 场景 | 格式 | 原因 |
+|------|------|------|
+| 精确块编辑 | XML（默认） | 保留 blockId、样式属性、结构 |
+| 整篇导入/导出 | Markdown | 人类可读，和 `.md` 互通 |
+| AI 对话引用 | Markdown | 模型理解 markdown 远好于 XML |
+
+**→ mnote 采纳**：CLI Main 用 XML 做默认格式是因为飞书文档本身是 XML 存储。mnote 当前主存储是 local-first `.md` 文件，历史 cloud / compat 内容也必须先投影成 markdown 后再进入 AI 编辑面，因此 markdown 是 mnote 的默认和唯一 AI 格式。这是正确的差异化决策。
+
+#### 2.1.7 Skill CI 校验
+
+> 参考文件：`.github/workflows/skill-format-check.yml`、`scripts/skill-format-check/`
+
+CLI Main 的 CI 自动检查每个 `SKILL.md`：
+1. 以 `---\n` 开头
+2. YAML frontmatter 语法有效
+3. `name` 和 `description` 必填
+4. `metadata` 缺失仅为警告
+
+**→ mnote 采纳**：对 Hermes `mnote` plugin 和所有 `~/.hermes/skills/note-taking/mnote-*/SKILL.md` 执行同等校验。在 CI 中增加 `skill-format-check` 步骤。
+
+### 2.2 BlockNote AI — 流式 apply + suggest/review
+
+BlockNote AI 的 `StreamTool` 实现了一套完整的 AI 编辑体验闭环：
+
+**核心机制**：
+
+```
+LLM 流式输出 partial JSON
+  → StreamToolExecutor 逐 chunk 解析
+  → 匹配 operation type → validate → execute
+  → ProseMirror 事务逐条 apply（带延迟，模拟"AI 正在打字"）
+  → suggestChanges 标记 AI 编辑为 suggestion（红绿对比）
+  → 用户逐条 accept / reject
+  → 确认后才写入持久层
+```
+
+**关键组件**：
+
+| 组件 | 功能 | mnote 远期对标 |
+|------|------|---------------|
+| `StreamTool` | 单操作的定义：name + inputSchema + validate + execute | mnote 已有（`mnote.block.*` / `mnote.doc.*`），不需要重构 |
+| `StreamToolExecutor` | 流式解析 partial JSON → 逐条 enqueue → 按顺序 execute | Phase C 新增：`StreamApplyController` |
+| `suggestChanges` | ProseMirror suggestion marks：AI 编辑不直接落盘，先标记为待审阅 | Phase C 新增：local-first `ReviewSession` / 临时审阅层 |
+| `RebaseTool` | 协作场景：用户同时在编辑 → AI 操作 rebase 到最新文档状态 | Phase C 考虑；local-first 下优先基于 file version / BufferStore 冲突模型 |
+| `delayAgentStep` | 逐条 apply 之间加 50-200ms 延迟，给用户"AI 正在操作"的可见性 | Phase C 可选改善 |
+
+**BlockNote AI 不适合直接搬的原因**：它的所有操作都通过 `id`（blockId）寻址。`add` 需要 `referenceId`、`update` 需要 `id`、`delete` 需要 `id`。这意味着：
+
+- 本地 `.md` 文件无法使用（没有稳定 blockId）
+- 跨块内容修改（"把所有 TODO 改成 DONE"）需要模型逐一产出 N 个带 blockId 的操作
+- 这和 mnote 的"markdown 优先"方向背道而驰
+
+**但我们可以在 markdown_edit 之上叠加流式/review**：Phase C 时，`mnote.doc.markdown_edit` 的 apply 过程可以流式化——逐条 search/replace 执行后推送 BlockDelta，编辑器逐条渲染，用户可逐条撤回。这和 BlockNote AI 的体验效果一致，但底层是文本级操作而非块级操作。
+
+### 2.3 Tiptap AI Autocomplete — 内联补全（独立功能）
+
+纯文本补全器：发送光标前文本 → 返回下一句。不是文档编辑方案。mnote 将来可以考虑作为独立的"内联 AI 补全"功能，和本文讨论的文档编辑工具分开设计。
+
+---
+
+## 3. 当前问题
+
+### 3.1 块级编辑是 AI 的过度抽象
+
+> 参考对照：CLI Main 证明 `str_replace` 足以覆盖大多数 AI 编辑场景，不需要强迫模型理解 blockId。
+
+当前 AI 写入链路的问题不在于技术实现，而在于**模型必须理解 blockId 这个 UI 层的概念**：
+
+```
+用户: "把第一段改简洁一些"
+  → 当前路径：模型 → { op: "replace", blockId: "block_1", content: "..." }
+  → 期望路径：模型 → { search: "第一段原文", replace: "改写后文本" }
+```
+
+「把文章中所有 TODO 改成 DONE」这类跨块请求，当前需要逐一产出 N 个 `{ op: "replace", blockId: "..." }`。文本级 search/replace 只需一条：`{ search: "TODO", replace: "DONE" }`。
+
+### 3.2 旧块级工具没有 local-first 默认写入语义
+
+> 参考对照：CLI Main 的 skill 可以操作任何 `doc-token`（包括本地文件和云端文档），因为它用的是文本级 + XML 级工具，不依赖特定存储。
+
+mnote 当前主线：页面已能定位 local folder `.md`，但普通 AI 正文编辑不能回到“必须构造完整 page context 或 block ops”的旧模型。AI 视角应看到受控文件引用、selection 和 allowed roots，而不是一份由前端拼出的第二事实源。
+
+### 3.3 两套体系互不相认
+
+| | 历史 cloud / compat 文档 | 当前 local-first `.md` 文件 |
+|---|---|---|
+| 存储 | 历史迁移源 / 显式 cloud compat / sync replica | 文件系统 `*.md` |
+| AI 读取 | `mnote.doc.fetch` 兼容投影 | 当前文件引用 / Page Aggregate / local markdown |
+| AI 写入 | `mnote.doc.*` 或 `mnote.block.*` 兼容 fallback | agent 原生 patch/diff + watcher 同步 |
+| 写入粒度 | 工具代理，不能作为新增默认入口 | 文件级 patch + selection 辅助 |
+| 设计定位 | 历史 / compat 边界 | 当前主路径 |
+
+旧设计把 compat 文档和本地文件写成两套体系，容易让后续实现继续往旧 cloud / block 工具堆逻辑。当前必须收敛：**local-first `.md` 是默认事实源，markdown 是共同格式，compat 只服务迁移、显式 cloud 或 remote agent 边界。**
+
+---
+
+## 4. 设计原则
+
+### 4.1 Markdown 是 AI 编辑的第一公民
+
+> 参考对照：CLI Main 用 Markdown 做整篇导入/导出和对话引用，用 XML 做精确块编辑。mnote 直接用 Markdown 做所有 AI 操作，因为 mnote 没有 XML 存储层。
+
+AI 最自然的编辑方式是对文本进行操作。块是 UI 概念，不是 AI 概念。当前 local-first 持久化格式就是 markdown；历史 cloud / compat 内容若需要进入 AI 编辑，也必须先投影成 markdown。
+
+### 4.2 两层操作模型（兼容层）
+
+| 层 | 工具 | 寻址方式 | 适用场景 | 占比 |
+|----|------|---------|---------|------|
+| **文件级（主）** | agent 原生 `diff/apply_patch/文件编辑` | 授权文件引用 / selection | local-first 普通 Markdown 改写 | 80%+ |
+| **文本级（兼容）** | `mnote.doc.markdown_edit` | search/replace 文本对 | 显式 cloud / remote agent / 兼容旧页面 AI | 次要 |
+| **块级（辅助）** | `mnote.doc.apply_block_ops` | blockId / matchText | "把第三块拖到第一块后面"、"精确删除引用块" | <20% |
+
+### 4.3 local-first 主写入路径
+
+```
+页面 AI / ACP
+  → resolve_current_file(documentId, sourceKind=local_folder, rootUri)
+  → 传授权文件引用 / selection / allowed roots 给 agent runtime
+  → agent 原生 patch/diff 写入文件
+  → MNote 做权限 / 审计 / watcher refresh / BufferStore 冲突
+  → 仅在显式 cloud / remote compat 时 fallback 到 mnote.doc.markdown_edit
+```
+
+当前执行层不再二选一。默认只有 local-first 授权文件路径；cloud 或受限 remote runtime 无法直接访问本地文件时，才显式走 `mnote.doc.markdown_edit` 代理。这和 CLI Main 的 `docs +update` 可以操作任何 `doc-token` 的设计一致，只是 mnote 进一步把“编辑算法”让渡给 agent runtime。
+
+### 4.4 Diff 是内部实现细节
+
+对兼容 `mnote.doc.markdown_edit` 来说，AI **不**产出 unified diff（行号/上下文极易出错），而是产出两种形式之一：
+
+| 形式 | 适用场景 | AI 负担 |
+|------|---------|---------|
+| `operations: [{ search, replace }]` | 局部修改 | 低：只需找原文片段 |
+| `full_content: "..."` | 小文档全文改写 | 低：直接写完整 markdown |
+
+而在 local-first 主路径中，agent runtime 自己可以安全使用成熟的 diff / apply_patch / 直接文件编辑能力；MNote 只要求这些写入被限制在授权路径内，并把 changed files / diff 摘要收回审计。
+
+---
+
+## 5. 工具合同
+
+### 5.1 `mnote.doc.fetch`（已有，增强）
+
+```json
+{
+  "toolName": "mnote.doc.fetch",
+  "args": {
+    "documentId": "tree_xxx 或 /path/to/file.md",
+    "format": "markdown",
+    "scope": "full",
+    "query": "TODO",
+    "maxChars": 8000
+  }
+}
+```
+
+增强点：
+- `format: "markdown"` — 兼容值。local-first 文档直接返回 `.md` 原文；历史 cloud / compat 文档必须经 Page Aggregate 投影成 markdown。
+- `documentId` — 当前默认解析为 local-first 文档；只有显式 sourceKind / compat 标记允许进入 cloud adapter。
+
+返回：
+
+```json
+{
+  "ok": true,
+  "source": "local_folder",
+  "documentId": "local-md:README.md",
+  "fileVersion": "local-md:README.md:...",
+  "format": "markdown",
+  "content": "# 标题\n\n段落内容...\n\n## 子标题\n\n...",
+  "truncated": false,
+  "charCount": 1234
+}
+```
+
+### 5.2 `mnote.doc.markdown_edit`（新增，兼容 / fallback）
+
+```json
+{
+  "toolName": "mnote.doc.markdown_edit",
+  "args": {
+    "documentId": "tree_xxx 或 /path/to/file.md",
+
+    "operations": [
+      { "search": "原文片段", "replace": "新文本" },
+      { "search": "另一段", "replace": "改写后的内容" }
+    ]
+  }
+}
+```
+
+服务端处理流程：
+
+```
+1. resolve_source(documentId, sourceKind, rootUri) → LocalFSAdapter | explicit CompatAdapter
+2. 读取当前 markdown 全文
+3. 逐条 search_replace（精确匹配 → fuzzy fallback）
+4. 计算内部 diff（用于 BlockDelta 推送）
+5. 写入目标
+6. 返回结果
+```
+
+返回：
+
+```json
+{
+  "ok": true,
+  "source": "local_folder",
+  "documentId": "local-md:README.md",
+  "fileVersion": { "before": "local-md:README.md:...", "after": "local-md:README.md:..." },
+  "operationsApplied": 2,
+  "operationsFailed": 0,
+  "failedOperations": [],
+  "changedText": "已将「原文片段」替换为「新文本」\n已将「另一段」替换为「改写后的内容」",
+  "blockDelta": {
+    "documentId": "local-md:README.md",
+    "fileVersion": "local-md:README.md:...",
+    "operations": [...]
+  }
+}
+```
+
+### 5.3 `mnote.doc.apply_block_ops`（已有，辅助路径）
+
+保留不变。用于精确块结构调整（拖拽排序、指定 blockId 的精确删除）。在 Hermes tool manifest 中 `markdown_edit` 排在 `apply_block_ops` 前面。
+
+---
+
+## 6. 搜索替换语义
+
+> 参考对照：CLI Main 的 `str_replace` 使用精确子串匹配。mnote 增加 fuzzy fallback 以提高模型输出容错率。
+
+| 优先级 | 策略 | 说明 |
+|--------|------|------|
+| 1 | 精确匹配 | 原文字串精确匹配，区分大小写 |
+| 2 | 宽松匹配 | 忽略首尾空白、全角/半角差异后匹配 |
+| 3 | 段落 fuzzy | 按换行分段，每段独立 fuzzy match（允许 30% 字符差异） |
+| 4 | 失败 | 返回 `operationsFailed`，列出无法匹配的 search 和原因 |
+
+多条 operation 按数组顺序串行执行。前一条的替换结果对后一条可见（和 sed 语义一致）。
+
+**乐观锁**：local-first 下执行前用 file version / conflict detection key 检测。如果写入时文件版本已过期，返回冲突错误，让 AI 重新 fetch + edit；历史 cloud compat 才能使用旧 revision 语义。
+
+---
+
+## 7. 远期规划：流式 apply + suggest/review（Phase C，当前不实施）
+
+> 参考对照：BlockNote AI 的 `StreamToolExecutor` + `suggestChanges` + `delayAgentStep`。本节仅做设计规划，不列入当前实施阶段。
+
+### 7.1 目标
+
+当用户通过页面 AI 面板发起编辑后，不是等所有操作完成后一次性刷新，而是：
+
+1. AI 逐条产出 search/replace 对（流式）
+2. 服务端逐条 apply 并推送 BlockDelta
+3. 编辑器逐条渲染修改（带延迟，模拟"AI 正在编辑"）
+4. 用户可逐条 accept / reject（suggestion 模式）
+5. 确认后才最终写入本地 `.md` 或显式 compat 目标（review 模式）
+
+### 7.2 与 BlockNote AI 的差异
+
+| | BlockNote AI | mnote Phase C |
+|---|---|---|
+| 操作粒度 | 块级（add/update/delete block） | 文本级（search/replace 文本对） |
+| blockId 依赖 | 必须 | 不需要（文本匹配） |
+| 本地文件支持 | 不支持（无稳定 blockId） | 支持（文本匹配不依赖 blockId） |
+| Suggestion 层 | ProseMirror `suggestChanges` marks | Tiptap 的 suggestion 扩展或自建 |
+| 写入时机 | 用户 accept 后统一写入 | 同 |
+
+### 7.3 组件设计（草图）
+
+```
+StreamApplyController（新增）
+  输入：LLM 流式输出的 partial operations JSON
+  处理：
+    1. 解析 partial JSON → 提取已完成的 operation
+    2. 执行 search_replace → 产生 BlockDelta
+    3. 通过 SSE 推送 delta 到编辑器
+    4. 可选：注入 delay（50-200ms）模拟人类编辑节奏
+  输出：逐条 BlockDelta
+
+ReviewSession（新增，local-first 审阅层）
+  状态：pending → accepted | rejected
+  存储：SQLite control-plane / 本地 transient review state；不依赖 Convex
+  生命周期：
+    - AI 编辑 → 创建 ReviewSession → 所有修改标记为 pending
+    - 用户逐条操作 → accept/reject → 更新 session 状态
+    - 全部处理或用户确认 → 最终写入 → 关闭 session
+
+GhostTextOverlay（新增，编辑器）
+  参考：Tiptap AI Autocomplete 的 ghost text 覆盖层
+  用于：展示 AI 修改前后的 diff（红删绿增），用户 hover 查看详情
+```
+
+### 7.4 分阶段实施顺序
+
+| 阶段 | 内容 | 依赖 |
+|------|------|------|
+| C-1 | `StreamApplyController`：流式 apply + SSE 逐条推送 delta | 7-13 EditorRuntimeActor delta 通道 |
+| C-2 | `GhostTextOverlay`：编辑器内 diff 展示（红删绿增） | leptos-tiptap 的 decoration 能力 |
+| C-3 | `ReviewSession`：local-first accept/reject session | SQLite control-plane / editor transient review state 设计 |
+| C-4 | `delayAgentStep`：可选的编辑节奏模拟 | C-1 完成 |
+
+**当前不做实施决策**。Phase C 的启动时机以 Phase A/B 完成后，编辑器 decoration 能力、BufferStore/file version 冲突模型和 SQLite control-plane review state 设计就绪为前置条件。
+
+---
+
+## 8. 实施阶段（当前）
+
+### Phase A：文件引用主路径 + `mnote.doc.*` 兼容层
+
+- [x] `mnote.doc.fetch` 增加 `format: "markdown"`（local-first `.md` / Page Aggregate markdown 投影）
+- [x] `mnote.doc.fetch` 增加本地文件 source 路由（`local_folder` / `rootUri` / `local-md:*`）
+- [x] 实现 `resolve_source(documentId, sourceKind, rootUri)` — 默认 `local_folder`；历史 cloud / compat 必须显式进入 compat adapter
+- [ ] 页面 AI / ACP 普通正文编辑默认只传当前文件引用、可选 selection 和用户指令，不再默认构造完整 page context
+- [ ] 本地 agent runtime 在 `allowed_roots / allowed_file_paths` 内执行 patch/diff，并把 changed files / diff 摘要回传 MNote
+- [x] 实现 `search_replace(text, operations)` — 四级匹配策略（精确→宽松→段落 fuzzy→失败）
+- [x] 历史 cloud / compat 写入 adapter 已降级为 fallback，不再作为 local-first 默认入口
+- [x] 实现本地文件写入 adapter（`mnote.doc.markdown_edit` 检测到本地文件路径时直接 `fs::write` 写回，不经过 Convex）
+- [ ] 内部 diff 生成 + BlockDelta 推送（复用 7-13 delta 基础设施，待 Phase C 实现）
+- [x] Hermes tool manifest 注册 `mnote.doc.markdown_edit`
+- [x] Hermes `mnote` plugin 更新：`mnote_doc_fetch` schema + `mnote_doc_markdown_edit` 新增
+- [x] 乐观锁：local-first 使用 file version / conflict detection key；compat 路径才保留 revision 语义
+- [x] 历史 browser smoke（cloud compat `format: "markdown"` + `markdown_edit` 搜索替换）仅作兼容证据，不代表当前主路径
+- [x] 单元测试（`search_replace` 精确/失败/全文、`blocks_to_markdown` with_ids/heading 共 5 测试通过）
+- [x] 浏览器 smoke（本地 `.md` 文件读取 `mnote_doc_fetch` + 写入 `mnote_doc_markdown_edit`，`full_content` 创建 + `operations` 搜索替换 + 回读验证全部通过）
+
+### Phase B：`page_ai_workflow.rs` 收口
+
+- [x] 退役 `direct_block_edit_operations`（正则抠「」的快路径，代码保留但路由跳过）
+- [x] `/api/page-ai/block-edit-workflow` 不再被当作 local-first 主路径
+- [x] 模型 system prompt 重构：从产块操作 JSON 改为产 search/replace 文本对
+- [x] 补全 operation schema：`extract_markdown_operations_from_model_text` 处理新旧格式
+- [x] 浏览器 smoke：`markdown_edit` 搜索替换通过，自然语言编辑路径可用
+
+### Phase C：流式/review（规划中，不实施）
+
+- [ ] 流式 apply（`StreamApplyController`）
+- [ ] suggest/review（`ReviewSession` + `GhostTextOverlay`）
+- [ ] `delayAgentStep` 编辑节奏模拟
+
+> 见 §7。当前仅做设计规划，不实施。
+
+---
+
+## 9. 与参考实现和其他设计稿的关系
+
+### 9.1 与 CLI Main 的关系
+
+| CLI Main 概念 | mnote 对应 |
+|--------------|-----------|
+| `str_replace`（文本级） | `mnote.doc.markdown_edit`（兼容 / fallback） |
+| `block_replace/insert_after/delete/move_after`（块级） | `mnote.doc.apply_block_ops`（辅助路径） |
+| XML 用于精确编辑 | mnote 不用 XML（没有 XML 存储层），direct path 退役后全部走 markdown |
+| Markdown 用于导入/导出/对话引用 | mnote 全部 AI 交互走 markdown |
+| Skill 格式（YAML + Markdown + tool shortcuts） | Hermes `mnote` plugin（`plugin.yaml` + `SKILL.md` + tool manifest） |
+
+### 9.2 与 BlockNote AI 的关系
+
+| BlockNote AI 概念 | mnote 远期对应 | 状态 |
+|-------------------|---------------|------|
+| `StreamTool` + `StreamToolExecutor` | `StreamApplyController` | Phase C 规划 |
+| `suggestChanges` + `AIExtension` state machine | `ReviewSession` + `GhostTextOverlay` | Phase C 规划 |
+| `delayAgentStep` | 可选改善 | Phase C 规划 |
+| `RebaseTool` | revision 乐观锁（已有） | 当前已覆盖 |
+| 纯 blockId 寻址 | ❌ 不采用。mnote 用文本匹配 | — |
+
+### 9.3 与其他设计稿的关系
+
+| 设计稿 | 关系 | 修正状态 |
+|--------|------|---------|
+| 7-9 路线图 | 块级编辑降级为辅助，local-first 普通编辑改为授权文件 + agent patch/diff，markdown_edit 退到兼容层 | ✅ 已修正 |
+| 7-10 checklist | 新增 Phase 9 markdown_edit | ✅ 已修正 |
+| 7-12 工具路由 | PageAICommandRouter 主输出改为 markdown_edit | ✅ 已修正 |
+| 7-13 EditorRuntimeActor | 补充 markdown_edit 的 delta 适配 | ✅ 已修正 |
+| 3-13 本地 markdown | 新增 AI 工具接入章节 | ✅ 已修正 |
+
+---
+
+## 10. 禁止项
+
+- 不删除 `mnote.block.*` 工具（保留为辅助路径）。
+- 不强迫 local-first agent 产出 MNote 自定义 diff；Hermes / Reasonix 可使用自身成熟 patch / diff / apply_patch 能力，MNote 负责白名单权限、文件版本冲突和审计。
+- 不要求本地文件有稳定的 `blockId`（本地文件没有 block identity）。
+- 不在 markdown_edit 内部引入新的 AI 模型调用（diff 是确定性算法）。
+- 不把 Convex / `documents:updateContent` 重新提升为当前正文主存储；`markdown_edit` 只在显式 cloud / compat 场景复用受控保存路径。
+- 不把 `mnote.page.save` 重新描述为精确编辑主入口（它仍是兜底工具）。
+- **不照搬 BlockNote AI 的纯 blockId 寻址模式**（与 mnote 的 markdown 优先策略冲突）。
+
+---
+
+## 11. 成功标准
+
+- [x] `mnote.doc.fetch(documentId, format: "markdown")` 对历史 cloud / compat 文档返回正确 markdown（兼容证据）
+- [ ] `mnote.doc.fetch(documentId, format: "markdown")` 对本地 `.md` 文件返回正确 markdown（兼容路径）
+- [x] `mnote.doc.markdown_edit` 的简单搜索替换（1 条 operation）浏览器 smoke 通过
+- [ ] `mnote.doc.markdown_edit` 的复杂改写（3+ 条 operations）成功率 > 80%
+- [ ] 本地 `.md` 文件通过页面 AI 面板可被读取和写入，且默认通过 agent 原生 patch/diff 完成
+- [x] 历史 cloud / compat markdown_edit 不增加额外 RTT（兼容证据，不代表当前主路径）
+- [x] `direct_block_edit_operations` 已退役（路由跳过，代码保留）
+- [x] `page_ai_workflow.rs` 的 system prompt 已补全 search/replace schema
+- [x] Phase C（流式/review）的设计已冻结，不阻塞 A/B 实施
+
+---
+
+## 12. CLI Main 成熟度采纳清单
+
+以下清单按优先级排列，标注当前状态和对应 CLI Main 参考位置。
+
+### 12.1 当前 Phase A/B 必须完成的
+
+| # | CLI Main 模式 | mnote 实施项 | 状态 | 参考文件 |
+|---|-------------|-------------|------|---------|
+| 1 | 两层操作模型 | local-first 默认 agent 原生 patch/diff；`markdown_edit`（compat fallback）+ `apply_block_ops`（结构辅助）已在 7-10 Phase 9 登记 | 📋 设计完成，已按 2-2 改口径 | `lark-doc-update.md` |
+| 2 | Scope 四级控制 | `mnote.doc.fetch` 增加 `scope: full/section/outline/keyword` | 🔜 Phase A | `lark-doc-fetch.md` |
+| 3 | Detail 三级控制 | `mnote.doc.fetch` 增加 `detail: simple/with_ids/full` | 🔜 Phase A | `lark-doc-fetch.md` |
+| 4 | 片段包装 | fetch 返回中标记 `<!-- fragment -->` / `<!-- excerpt -->` 告知 AI 部分视图 | 🔜 Phase A | `lark-doc-fetch.md`（fragment/excerpt 模式） |
+| 5 | Code-Act Loop | Hermes `mnote` plugin SKILL.md 中内联 Plan→Execute→Observe→Iterate 指导 | ✅ 已写入 `~/.hermes/skills/note-taking/mnote-block-ai/SKILL.md` | `lark-doc-update-workflow.md` |
+| 6 | 更新命令决策树 | 模型 system prompt 追加"优先搜索替换，不全文覆盖"规则 | 🔜 Phase B | `lark-doc-update.md`（str_replace vs block_* 决策） |
+| 7 | 写后回读 | Hermes 每次写操作结束后自动 `mnote.doc.fetch` 回读 | 🔜 Phase B | `lark-doc-update-workflow.md` |
+| 8 | Markdown 优先格式策略 | mnote 默认和唯一 AI 格式为 markdown（不需要 XML） | ✅ 已确认 | `lark-doc-md.md`（对比 XML 路线） |
+
+### 12.2 Phase A/B 完成后应补充的
+
+| # | CLI Main 模式 | mnote 实施项 | 状态 | 参考文件 |
+|---|-------------|-------------|------|---------|
+| 9 | Skill YAML 规范化 | Hermes `mnote` plugin 的 `plugin.yaml` 增加 `description`、`metadata.domain` | ✅ 已更新 v0.2.0 | `master-skill-template.md` |
+| 10 | 参考文件分离 | `~/.hermes/skills/note-taking/mnote-block-ai/references/` 目录已创建，`mnote-doc-fetch.md` 已写入 | ✅ 已创建（fetch），其余按需补充 | `skills/lark-doc/references/` |
+| 11 | Skill CI 校验 | CI 步骤：检查所有 plugin.yaml 和 SKILL.md 的 YAML frontmatter 有效性 | 📋 待实施 | `skill-format-check.yml` |
+| 12 | 格式规则文档 | `references/mnote-doc-md.md`：定义 markdown 中 AI 应理解的特殊语法（任务列表标记 `- [ ]`、附件链接 `[file:...]` 等） | 📋 待实施 | `lark-doc-md.md` |
+| 13 | 上下文冻结规范 | `references/mnote-doc-context.md`：冻结时保留哪些字段、截断规则、revision 注入方式 | 📋 待实施 | `lark-doc-fetch.md`（fetch body 构建） |
+
+### 12.3 远期规划（Phase C 及以后）
+
+| # | CLI Main 模式 | mnote 实施项 | 状态 | 参考文件 |
+|---|-------------|-------------|------|---------|
+| 14 | 跨域资源路由 | 文档内嵌思维导图/附件时，路由到对应 skill（见 §2.1.5） | ⏳ Phase C 后 | `lark-doc/SKILL.md`（路由表） |
+| 15 | 流式增量 apply | BlockNote AI 的 `StreamToolExecutor` 模式，见 §7 | ⏳ Phase C 规划 | `blocknote-ai/packages/xl-ai/` |
+| 16 | suggest/review | BlockNote AI 的 `suggestChanges` 模式，见 §7 | ⏳ Phase C 规划 | `blocknote-ai/packages/xl-ai/` |
+
+### 12.4 与 BlockNote AI / Tiptap AI Autocomplete 的采纳清单
+
+| # | 参考模式 | mnote 采纳 | 时机 | 参考文件 |
+|---|---------|-----------|------|---------|
+| B1 | `StreamTool` 流式 apply | `StreamApplyController`（§7.3） | Phase C | `blocknote-ai/packages/xl-ai/src/streamTool/` |
+| B2 | `suggestChanges` review 层 | `ReviewSession` + `GhostTextOverlay`（§7.3） | Phase C | `blocknote-ai/packages/xl-ai/src/AIExtension.ts` |
+| B3 | `delayAgentStep` 编辑节奏 | 可选改善 | Phase C | `blocknote-ai/packages/xl-ai/src/streamTool/` |
+| T1 | ghost text 内联补全 | 独立功能（非本文档范围） | 独立立项 | `tiptap-ai-autocomplete/src/` |
+
+### 12.5 实施优先级总结
+
+```
+Phase A（当前立即）
+  ├── #2 Scope 四级控制  ← mnote.doc.fetch 增强
+  ├── #3 Detail 三级控制 ← mnote.doc.fetch 增强
+  ├── #4 片段包装        ← fetch 返回值增强
+  ├── #8 Markdown 优先   ← 已确认
+  └── 授权文件引用 + agent 原生 patch/diff 主路径；mnote.doc.markdown_edit 作为 compat fallback
+
+Phase B（Phase A 完成后）
+  ├── #5 Code-Act Loop   ← Hermes plugin SKILL.md
+  ├── #6 更新决策树      ← 模型 system prompt
+  └── #7 写后回读        ← Hermes tool loop 逻辑
+
+Phase A/B 完成后补充
+  ├── #9-#13 Skill 规范化、参考文件分离、CI 校验、格式文档、上下文规范
+
+Phase C（远期）
+  ├── #14 跨域路由（Phase C 后）
+  ├── #15 流式 apply（Phase C）
+  └── #16 suggest/review（Phase C）
+```