709 lines
24 KiB
Markdown
709 lines
24 KiB
Markdown
# 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。
|