mnote/design/old/07-ai/reference/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md

# [recycle] 7-12 [reference] 页面 AI Hermes 工具路由与编辑审阅面设计 v1

> 更新时间：2026-05-19
>
> 当前状态：`reference / frozen`
>
> 归档说明（2026-05-22）：本文保留 Hermes 工具路由、manifest 和 review surface 的设计边界；Phase C Review Mode 继续冻结。`7-14` 已移入 `design/old/07-ai/process/7-14-local-first-ai-markdown-editing-convergence-v1.md`，当前 active AI 编辑口径以 `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md` 为准。
>
> 本稿目的：修正“页面 AI 快速块编辑”后续方向，明确 mnote 不再建设独立 AI agent runtime；mnote 只建设 Hermes 可消费的编辑工具路由、工具 manifest、上下文冻结、dry-run/review 和 Rust 写入安全边界。
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.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/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-14-online-local-ai-markdown-editing-convergence-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/cli-main`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/blocknote-ai`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/reference-code/tiptap-apcore`

---

## 0. 2026-05-18 状态更新

本稿仍作为 Hermes 工具路由与审阅面设计保留在 `process/`，但以下口径已经更新：

- `/api/page-ai/block-edit-workflow` 当前不再以 `local_rule -> apply_block_ops` 作为主路径；local-first 普通 Markdown 编辑默认给 Hermes / Reasonix 授权文件引用，由 agent 使用自身 patch / diff / 文件编辑能力写本地 `.md`。
- `mnote.doc.markdown_edit` 不再作为 local-first 默认、fallback 或 remote fallback；本文后续出现的 `markdown_edit` 只代表历史 tool / review surface 证据，不指导新 agent 文件编辑主路径。当前 active 口径见 `design/07-ai/process/7-18-local-first-agent-file-editing-control-plane-v1.md`。
- `page_ai_workflow` 已复用统一 mnote tool executor，不再绕过 Hermes tool toggle / audit / write contract。
- `mnote.doc.apply_block_ops` / `mnote.block.*` 保留为结构性块操作辅助，不再作为普通正文 search/replace 的优先入口。
- 本稿中的 `PageAIReviewSession` 只定义 Phase C 的安全合同和状态机边界；当前 Phase C 仍冻结，不实施流式 apply 或新的审阅 UI。
- 当前已闭合缺陷见 `bugs/07-ai/done/7-18` 到 `7-25`。

### 0.1 2026-05-21 Batch J 状态更新

- profile disabled tool list 已在 `/api/hermes/client/tools` listing、前端 UI、`execute_mnote_tool_call()` guard 三处同源，均读取 Hermes profile YAML 的 `mnote.tools.disabled`。
- `capabilityScope` 已由 `7-34` 接入 `execute_mnote_tool_call()` 中心校验：缺省 scope 兼容旧调用方，显式声明但不足时拒绝执行；写 scope 可覆盖同前缀 read scope。
- `is_read_tool()` 仍是硬编码读工具列表；它与 manifest annotations 的同源化属于维护性缺口，后续可随 capabilityScope 校验一起处理。
- Phase C Review Mode 继续冻结，不因 `dryRun` / changedBlocks 已可用而提前实现新的审阅 UI。

## 1. 本轮结论

页面 AI 编辑卡顿的根因不是“Rust apply 慢”，而是模型和工具之间缺少稳定、低歧义、可审计的编辑命令面：

```text
用户说一句自然语言
  -> Hermes/模型需要猜：读哪个范围、改哪个块、调用哪个工具、如何传参
  -> 如果猜错 blockId 或工具参数，mnote 再 fallback / 重跑 / 整页写入
  -> 用户感知为慢、卡、偶发失败
```

正确方向不是再造一个 mnote 自有 AI runtime，而是：

> **Hermes 继续作为唯一页面 AI agent runtime；mnote 提供 Agent-native editor command layer。**

**新增（2026-05-16，按 7-14）**：AI 编辑的主路径应降维到 markdown 文本层。`mnote.doc.markdown_edit`（搜索替换文本对）是 AI 写入的主入口，覆盖 80%+ 场景；`mnote.block.*` 保留为结构性辅助。在线 Convex 文档和本地 `.md` 文件通过 `mnote.doc.fetch(format: "markdown")` + `mnote.doc.markdown_edit` 共用同一条 AI 写入路径。

因此，`本地意图解析 + Rust apply` 必须被重新定义为：

- Hermes 的工具路由提示层。
- 低风险确定性编辑的本地 shortcut。
- Rust 写工具的参数校验和执行面。
- review/dry-run/session 的安全边界。

它不是：

- 第二套对话 runtime。
- 第二套 agent tool loop。
- 绕过 Hermes profile/tool toggle/audit 的长期写入口。
- 让模型直接产 operations 并立刻写入的通用方案。

---

## 2. 现有问题

### 2.1 `/api/page-ai/block-edit-workflow` 方向需要收口

**当前口径修正（2026-05-16，按 7-14）**：

- `direct_block_edit_operations`（正则抠「」内文本的快路径）应退役。这不是 AI，是命令行。
- `/api/page-ai/block-edit-workflow` 底层应切换到 `mnote.doc.markdown_edit`：用户自然语言 → 模型产出 search/replace 文本对 → markdown_edit apply。
- 不再维持 direct path / model fallback 双路径，markdown_edit 是唯一主路径。

当前 route 对低歧义中文的加速效果不应成为保留一条非 AI 路径的理由。快路径作为 deterministic shortcut 的定位不变，但其实现必须改为调用 `mnote.doc.markdown_edit`，而不是绕过模型直接拼 operations。

### 2.2 模型直接输出 operations 仍不可靠

`09-page-ai-fast-block-edit-runtime-review.md` 已记录失败案例：模型输出了 operations，但 block 定位没有命中 Page Aggregate projection，最终触发 fallback 并拉长耗时。

长期规则应改为：

- 模型可以建议工具调用。
- 模型可以输出候选 operations。
- mnote 必须用 Page Aggregate projection 解析、校验、dry-run。
- blockId、revisionRef、allowedTargetBlockIds、editable、scope 必须由 mnote 校验。
- 未通过校验不能隐式 fallback 到整页写或另一次 agent run。

### 2.3 当前工具面还缺少 `cli-main` 式 agent 合同

`cli-main` 的关键价值是把平台能力压成 Agent 可靠调用的命令面：

- shortcut / API / generic 三层调用。
- `--dry-run` 预览真实请求。
- `Risk: high-risk-write` 与 `confirmation_required`。
- structured error / hint。
- skill 文档指导 agent 何时调用什么。
- event consume 的 schema、ready marker、bounded run。

mnote 当前已有 Hermes tool manifest，但还需要把 manifest 提升为 Hermes/model 可直接消费的编辑合同，而不是只做 UI 列表。

---

## 3. 设计原则

### 3.1 单一 agent runtime

```text
Hermes owns:
  session / message / model / tool loop / streaming / usage / profile / memory / skill

mnote owns:
  Page Aggregate / tool manifest / context snapshot / validation / Rust command / audit / readback
```

页面 AI 面板只是 Hermes 的页面内客户端；mnote 不再新增独立 agent 编排中心。

### 3.2 本地层只做“路由和校验”

本地层可以做：

- 判断是不是低歧义块编辑。
- 生成 `recommendedToolCall`。
- 附带 `confidence`、`risk`、`requiresReview`。
- 生成 `allowedTargetBlockIds`。
- 做 dry-run、validate、readback。

本地层不能做：

- 自己维护长期对话状态。
- 自己成为默认模型调用链。
- 自己绕过 Hermes tool manifest 和 profile 开关。
- 自己吞掉工具错误并隐式改走其他写入口。

### 3.3 所有写入都通过 Rust-owned mnote tools

写工具必须满足：

- `dryRun` 显式传入。
- `idempotencyKey` 显式传入。
- `revision/conflictDetectionKey/revisionRef` 或等价冲突键参与校验。
- `allowedTargetBlockIds` 限制 selection / scoped run。
- 返回 `diff/warnings/risk/blocked/changedBlocks/audit`。
- 写入后通过 Page Aggregate 和 `mnote.doc.fetch` 回读验证。

### 3.4 快路径是 shortcut，不是 runtime

低歧义场景可以保留快路径，但必须改口径：

```text
PageAICommandRouter
  -> recommendedToolCall
  -> direct tool shortcut 或 Hermes run with tool hint
  -> shared mnote tool executor
  -> shared audit/readback
```

如果走 direct tool shortcut，也必须产生 Hermes-compatible tool event / audit 语义，避免 UI 与历史记录断裂。

---

## 4. 总体架构

```text
Browser Page AI panel
  -> PageAIContextBuilder
  -> MnoteAIToolManifestProvider
  -> PageAICommandRouter
      -> deterministic shortcut? ---- yes -> MnoteToolExecutor
      |                                      -> PageAIReviewSession/readback
      no
      -> Hermes run request with:
           - frozen page context
           - tool manifest
           - recommendedToolCall hint
           - risk/review policy
         -> Hermes tool loop
         -> /api/hermes/tools/mnote/call
         -> Rust mnote tools
         -> PageAIReviewSession/readback
```

这里 `PageAICommandRouter` 不是 agent，只是类似 `cli-main` shortcut 的工具路由器。

---

## 5. 组件设计

### 5.1 `PageAIContextBuilder`

职责：

- 从 Page Aggregate block projection 构建冻结上下文。
- 支持 `scope=full/outline/block/selection/keyword`。
- 输出 `text/page_xml/json` 三种视图。
- 生成 `allowedTargetBlockIds`。
- 记录 `revision/conflictDetectionKey/revisionRef`。
- 大页面默认裁剪，返回 `truncated/warnings/continuation`。

输出示例：

```json
{
  "schema": "mnote.page_ai_context.v1",
  "workspaceId": "tree_workspace",
  "documentId": "tree_doc",
  "scope": "selection",
  "revision": 12,
  "conflictDetectionKey": "body:12:hash",
  "allowedTargetBlockIds": ["p_1", "p_2"],
  "selectedBlockIds": ["p_1", "p_2"],
  "pageText": "第一段\n第二段",
  "pageXml": "<page id=\"tree_doc\" revision=\"12\"><block id=\"p_1\">第一段</block></page>",
  "blocks": [
    {
      "blockId": "p_1",
      "type": "paragraph",
      "text": "第一段",
      "revisionRef": "body:12:p_1",
      "editable": true
    }
  ]
}
```

### 5.2 `MnoteAIToolManifestProvider`

职责：

- 从 Rust Hermes tool manifest 输出当前页面可用工具。
- 合并 profile tool toggle、capability、scope、document permissions。
- 输出 Hermes/model 可直接使用的 tool schema。
- 输出风险和审批语义。

工具 manifest 必须包含：

```json
{
  "name": "mnote.doc.apply_block_ops",
  "description": "Apply validated block operations to the current mnote document.",
  "inputSchema": {
    "type": "object",
    "required": ["operations", "dryRun", "idempotencyKey"],
    "additionalProperties": false
  },
  "annotations": {
    "readonly": false,
    "destructive": false,
    "idempotent": false,
    "requiresApproval": true,
    "approvalMode": "review",
    "selectionEffect": "destroy",
    "runtimeOwner": "mnote-web",
    "writeOwner": "rust-runtime-kernel"
  },
  "availability": {
    "enabled": true,
    "unsupportedReason": ""
  }
}
```

### 5.3 `PageAICommandRouter`

替代当前继续扩大的 `block-edit-workflow` 概念。

**新增（2026-05-16，按 7-14）**：Router 的 `recommendedToolCall` 主输出改为 `mnote.doc.markdown_edit`（search/replace 文本对），块级 `mnote.doc.apply_block_ops` 仅在明确的结构性编辑场景（拖拽排序等）下推荐。

输入：

- 用户 prompt。
- 冻结后的 `mnote.page_ai_context.v1`。
- 当前 tool manifest。
- 当前 profile / approval mode。

输出：

```json
{
  "schema": "mnote.page_ai_command_route.v1",
  "intent": "markdown_edit",
  "confidence": 0.94,
  "recommendedToolCall": {
    "toolName": "mnote.doc.markdown_edit",
    "args": {
      "operations": [
        {"search": "原文片段", "replace": "新文本"}
      ]
    }
  },
  "risk": "low",
  "requiresHermesRun": false,
  "requiresReview": false,
  "reason": "明确文本替换表达，目标文本唯一命中"
}
```

规则：

- 默认推荐 `mnote.doc.markdown_edit`（search/replace 文本对，AI 不需要理解 blockId）。
- 仅在明确的结构性编辑场景（"把第三块拖到第一块后面"）推荐 `mnote.doc.apply_block_ops`。
- 不能为复杂改写、总结、跨页面直接生成写入。
- 不能调用第二套长链模型；如需模型，交给 Hermes run。
- 输出必须可被 Hermes 当作 tool hint 消费。

### 5.4 Hermes run hint 注入

当 `requiresHermesRun=true` 或 router 不确定时，页面 AI 发起 Hermes run，并附带：

```json
{
  "pageContext": "mnote.page_ai_context.v1",
  "toolManifest": "mnote.ai_tool_manifest.v1",
  "toolHint": "mnote.page_ai_command_route.v1",
  "reviewPolicy": {
    "mode": "yolo|review|required",
    "defaultDryRun": true
  }
}
```

Hermes 仍负责：

- 选择模型。
- 工具调用循环。
- stream message / tool event。
- abort/retry。
- session persistence。

mnote 只负责工具结果和写入安全。

### 5.5 `PageAIReviewSession`

职责：

- 承接所有写工具 `dryRun=true` 或 `requiresApproval=true` 的结果。
- 保存 plan/diff/warnings/risk/blocked。
- 提供 accept/reject/retry/abort。
- accept 时二次读取 Page Aggregate 并校验 revision。

状态：

```text
draft
planning
previewing
awaiting_user
accepted
rejected
applying
applied
failed
aborted
stale
```

第一阶段可以保留 yolo，但仍应让工具返回 review-compatible 数据结构，避免后续 UI 重写。

最小稳定合同：

```json
{
  "schema": "mnote.page_ai_review_session.v1",
  "sessionId": "review_01",
  "workspaceId": "tree_workspace",
  "documentId": "tree_doc",
  "runId": "run_01",
  "toolCallId": "tool_01",
  "traceId": "trace_01",
  "state": "awaiting_user",
  "mode": "review",
  "source": {
    "runtimeOwner": "mnote-web",
    "writeOwner": "rust-runtime-kernel",
    "toolName": "mnote.doc.markdown_edit"
  },
  "base": {
    "revision": 12,
    "conflictDetectionKey": "body:12:hash",
    "allowedTargetBlockIds": ["p_1"]
  },
  "proposal": {
    "format": "markdown",
    "operations": [
      {
        "op": "replace",
        "search": "旧文本",
        "replace": "新文本"
      }
    ],
    "fullContent": null
  },
  "preview": {
    "dryRun": true,
    "changedBlocks": [
      {
        "blockId": "p_1",
        "before": "旧文本",
        "after": "新文本",
        "revisionRef": "pageRev:12:block:p_1"
      }
    ],
    "diff": [],
    "warnings": [],
    "risk": "low",
    "blocked": false
  },
  "actions": {
    "accept": {
      "requiresFreshRevision": true,
      "requiresIdempotencyKey": true
    },
    "reject": true,
    "retry": {
      "allowed": true,
      "requiresNewToolCallId": true
    },
    "abort": true
  },
  "audit": {
    "createdAt": "2026-05-18T00:00:00Z",
    "createdBy": "actor_01"
  }
}
```

状态语义：

- `draft`：已创建 session，但尚未生成 dry-run preview。
- `planning`：正在构造 tool args 或请求模型生成候选。
- `previewing`：正在执行 `dryRun=true`。
- `awaiting_user`：preview 已完成，等待 accept / reject / retry / abort。
- `accepted`：用户已确认，等待正式 apply。
- `rejected`：用户拒绝，本 session 不可再写入。
- `applying`：accept 后正在正式写入。
- `applied`：正式写入已完成，并已通过 Page Aggregate / `mnote.doc.fetch` 回读。
- `failed`：preview 或 apply 失败，需保留 structured error / hint。
- `aborted`：用户或系统中断，不能继续写入。
- `stale`：accept 时 revision / conflictDetectionKey / revisionRef 过期，必须重新 preview，不能直接 apply。

动作约束：

- `accept` 必须重新读取 Page Aggregate，并校验 `revision/conflictDetectionKey/revisionRef`；过期时转 `stale`。
- `accept` 必须提供新的或既有合法 `idempotencyKey`，重复提交必须 replay 同一结果。
- `reject` 与 `abort` 不能产生写入。
- `retry` 不能复用旧 `toolCallId` 伪装成同一次写入；必须生成新 proposal 或新 dry-run preview。
- yolo 模式可以跳过 `awaiting_user` UI，但仍应生成同构的 review-compatible audit 数据。

---

## 6. 关键流程

### 6.1 低歧义块替换

```text
用户：把「第二段」替换为「第二段已修改」
  -> ContextBuilder 冻结页面与 block ids
  -> CommandRouter 命中 direct_block_edit
  -> recommendedToolCall=mnote.doc.apply_block_ops
  -> dryRun validate 唯一命中
  -> yolo 模式：direct tool shortcut 正式 apply
  -> 记录 tool event/audit
  -> Page Aggregate readback
```

验收：

- 不进入通用 Hermes agent run 也可以，但必须复用 mnote tool/audit/readback 语义。
- 若非 yolo 模式，则停在 review session。

### 6.2 复杂自然语言改写

```text
用户：把这段整理得更专业，并保留原意
  -> Router 无法确定操作
  -> Hermes run with context + manifest + hint
  -> Hermes 调 mnote.doc.fetch / block.fetch
  -> Hermes 调 mnote.doc.plan_update(dryRun=true)
  -> mnote 返回 review session draft
  -> 用户 accept 后 Rust apply
```

验收：

- 模型不能直接改正文。
- dry-run 不改变 Page Aggregate。
- accept 时校验 revision。

### 6.3 selection 编辑

```text
用户选中块 A/B：改成列表
  -> ContextBuilder 冻结 selectedBlockIds
  -> allowedTargetBlockIds=[A,B]
  -> 所有写工具自动带 allowedTargetBlockIds
  -> 写工具尝试修改 C 时 blocked=true
```

验收：

- 用户后续改变选区不影响当前 run。
- selection 外写入被阻断。

### 6.4 工具禁用

```text
profile disabled mnote.block.fetch
  -> ToolManifestProvider 输出 enabled=false 或不输出该工具
  -> Router 不推荐该工具
  -> Hermes 直接调用仍被 /api/hermes/tools/mnote/call 拦截
```

验收：

- UI 工具列表、Hermes manifest、后端执行拦截一致。

---

## 7. 与参考代码的吸收边界

### 7.1 `cli-main`

吸收：

- shortcut/API/generic 三层工具面。
- dry-run 作为写入前置能力。
- structured error/hint。
- risk/confirmation_required。
- skill 文档让 agent 不靠猜。
- event/schema/ready marker 的 agent-friendly contract。

不吸收：

- 不复制 Go CLI 框架。
- 不把 CLI 作为页面 AI 唯一执行面。
- 不用命令行 prompt 作为 Web 审批 UI。

### 7.2 `blocknote-ai`

吸收：

- `DocumentStateBuilder` 的 selection/full context 分离。
- `StreamToolsProvider` 的工具集合思想。
- AI lifecycle：thinking / ai-writing / user-reviewing / error。
- accept/reject/retry/abort 的交互形态。

不吸收：

- 不引入 `@blocknote/xl-ai` 运行时依赖。
- 不复制 GPL/PROPRIETARY 代码。
- 不让 BlockNote/ProseMirror suggestion 成为 mnote 事实源。

### 7.3 `tiptap-apcore`

吸收：

- tool schema。
- annotations。
- ACL / role。
- query/content/destructive/selection/history 分类。
- executor 前置检查。

不吸收：

- 不把 Tiptap command 作为长期写入事实源。
- 不让浏览器 editor instance 直接持久化写入。

### 7.4 AI SDK / Context7 核验结论

可用方向：

- 用 schema/structured output 约束模型输出。
- 用 tool calling 让模型选择工具。
- 用 repair/validation 处理无效参数。
- 工具执行结果必须由 mnote 校验后返回。

不可用方向：

- 不把 structured output 当最终写入结果。
- 不让模型输出的 blockId 绕过 projection resolve。

---

## 8. 迁移计划

### Phase A：设计治理

- [x] 新增本文作为当前口径。
- [x] `7-10` 继续作为执行 checklist。
- [x] `7-11` 作为旧“自有 AI runtime”口径移入 `design/old/07-ai/process/`。

### Phase B：Manifest 合同收口

- [ ] `mnote.doc.*` / `mnote.block.*` manifest 输出完整 `inputSchema/outputSchema/annotations/availability`。
- [ ] profile toggle、capability、scope 共同影响 manifest。
- [ ] manifest 可直接转换为 Hermes/model tools。
- [ ] 禁用工具在 manifest、UI、执行拦截三处一致。

### Phase C：`block-edit-workflow` 改造成 router

- [ ] 将 route 命名和返回 schema 改为 `mnote.page_ai_command_route.v1` 或新增等价 route。
- [ ] 本地规则只输出 `recommendedToolCall`。
- [ ] 低风险 yolo shortcut 走共享 mnote tool executor。
- [ ] 非低风险或低置信度任务发起 Hermes run with tool hint。
- [ ] 删除“模型 fallback 后再 Hermes agent run”的重复链路。

### Phase D：Review session

- [x] 定义 `mnote.page_ai_review_session.v1` 最小 schema 与状态机边界（2026-05-18 已补；Phase C UI 仍冻结）。
- [ ] `mnote.doc.plan_update` 与 `mnote.doc.apply_block_ops dryRun=true` 返回 review-compatible draft。
- [ ] 页面 AI UI 展示 diff/warnings/risk/blocked。
- [ ] accept/reject/retry/abort 可用。
- [ ] stale revision 被阻断。

### Phase E：状态与事件统一

- [ ] direct shortcut 和 Hermes run 都产生统一 tool event 形态。
- [ ] 页面 AI 面板按 `runId/toolCallId/reviewSessionId` 聚合展示。
- [ ] abort 不留下半写入正文。
- [ ] 刷新后未提交 review session 不自动写入。

### Phase F：验收 smoke

- [ ] 低歧义替换：可 <1s 可见，且有 tool audit。
- [ ] 复杂改写：进入 Hermes run，先 dry-run/review。
- [x] selection 外写入：blocked。
- [ ] 禁用工具：manifest 不推荐，后端仍拦截。
- [ ] 旧 revision accept：stale。

2026-05-16 补充验收证据：

- `scripts/task-page-block-ai-context-format-smoke.js` 已验证 `mnote.doc.apply_block_ops dryRun=true` 携带 `allowedTargetBlockIds=["p_2"]` 时，尝试 replace `p_1` 会被 Rust mnote tool 拒绝。
- 证据：`tmp/page-block-ai-context-format-smoke/mp8ddr4n.json`；错误路径为 HTTP `400`、`mnote_block_target_out_of_scope`。
- 同一 smoke 还验证了 context / manifest 基础合同：`mnote.doc.fetch scope=selection format=page_xml/text`、`mnote.block.fetch format=page_xml/text`、manifest annotations 与 `mnote.page.save` 粗粒度兜底定位。
- 边界：本证据不代表完整 review session、旧 revision accept、复杂改写或单个 `mnote.block.*` selection guard 已完成。

---

## 9. `7-10` 与 `7-11` 的处理结论

### 9.1 `7-10` 继续执行

`7-10` 是页面块 AI 工具执行 checklist，包含真实代码和 smoke 证据。它仍然有效，继续保留在：

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

但后续执行必须按本文修正口径：

- `PageAIIntentParser` 读作 `PageAICommandRouter`。
- `PageAIOperationPlanner` 读作 `recommendedToolCall` 构造器。
- `PageAIOperationValidator` 继续有效，但归属 mnote tool executor / Rust validation。
- `PageAIApplyController` 不应成为独立 runtime，改为 review session / tool executor / readback controller。
- “不进入 Hermes run”只能表示 deterministic shortcut，不表示 mnote 新建了 agent runtime。

### 9.2 `7-11` 移入 old

`7-11` 的参考资料价值仍然成立，但标题和核心分层写成了“mnote 自有 AI 工具 runtime”。这会误导后续实现继续扩出第二套 runtime。

因此本轮将其移入：

```text
design/old/07-ai/process/7-11-blocknote-tiptap-ai-reference-and-mnote-ai-tool-runtime-v1.md
```

保留原因：

- 记录 BlockNote / Tiptap 参考取证。
- 保留 GPL/PROPRIETARY 许可证边界。
- 保留 selection/context/review 的参考价值。

不再作为当前执行口径；当前执行口径以本文为准。

---

## 10. 禁止项

- 不新增 mnote 自有 agent runtime。
- 不把 `/api/page-ai/block-edit-workflow` 扩成通用 AI 编排中心。
- 不让模型直接输出未经校验的 blockId 并写入。
- 不绕过 Hermes profile/tool toggle/audit。
- 不让前端 editor instance 直接执行正式持久化写入。
- 不以 HTML / Tiptap JSON / ProseMirror position 作为长期 AI tool contract。
- 不复制 BlockNote XL AI 或 GPL/PROPRIETARY 实现代码。
- 不把 `mnote.page.save` 描述为精确块编辑主入口。

---

## 11. 成功标准

完成本文后，页面 AI 编辑应满足：

- 简单明确块编辑有低延迟 shortcut。
- 复杂编辑仍走 Hermes agent runtime。
- Hermes 不再盲猜工具和参数，而是拿到 mnote 提供的 context、manifest、tool hint。
- 所有写入都能 dry-run、review、audit、readback。
- 工具禁用、权限、scope、selection 与后端执行一致。
- 设计文档不再鼓励建设第二套 AI runtime。