lix/mnote
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
61ee4a38a27c1e6175371f26cc7a90899162d385
mnote/design/07-ai/process/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md
T

602 lines
18 KiB
Markdown
Raw Normal View History

feat: EditorRuntimeActor - 三层缓存/delta/事件架构
2026-05-16 22:03:14 +08:00
# 7-12 [process] 页面 AI Hermes 工具路由与编辑审阅面设计 v1
> 更新时间：2026-05-16
>
> 当前状态：`PROCESS`
>
> 本稿目的：修正“页面 AI 快速块编辑”后续方向，明确 mnote 不再建设独立 AI agent runtime；mnote 只建设 Hermes 可消费的编辑工具路由、工具 manifest、上下文冻结、dry-run/review 和 Rust 写入安全边界。
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/10-review/process/09-page-ai-fast-block-edit-runtime-review.md`
> - `/mnt/Data1T/mnote/design/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/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`
---
## 1. 本轮结论
页面 AI 编辑卡顿的根因不是“Rust apply 慢”，而是模型和工具之间缺少稳定、低歧义、可审计的编辑命令面：
```text
用户说一句自然语言
-> Hermes/模型需要猜：读哪个范围、改哪个块、调用哪个工具、如何传参
-> 如果猜错 blockId 或工具参数，mnote 再 fallback / 重跑 / 整页写入
-> 用户感知为慢、卡、偶发失败
```
正确方向不是再造一个 mnote 自有 AI runtime，而是：
> **Hermes 继续作为唯一页面 AI agent runtime；mnote 提供 Agent-native editor command layer。**
因此，`本地意图解析 + 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` 方向需要收口
当前 route 已证明低歧义中文块编辑可以很快完成：
```text
local_rule -> mnote.doc.apply_block_ops -> Rust apply -> page readback
```
但如果把这个 route 继续扩成 `PageAIIntentParser / OperationPlanner / ApplyController`，它会自然变成第二套 runtime：
- 自己判断意图。
- 自己调用模型。
- 自己解析模型输出。
- 自己决定 fallback。
- 自己写入并展示结果。
这会和 Hermes 的 session、profile、tool toggle、tool event、usage、audit、abort/retry 产生重叠。
### 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` 概念。
输入：
- 用户 prompt。
- 冻结后的 `mnote.page_ai_context.v1`。
- 当前 tool manifest。
- 当前 profile / approval mode。
输出：
```json
{
"schema": "mnote.page_ai_command_route.v1",
"intent": "direct_block_edit",
"confidence": 0.94,
"recommendedToolCall": {
"toolName": "mnote.doc.apply_block_ops",
"args": {
"operations": [
{"op": "replace", "matchText": "A", "content": "B"}
],
"dryRun": true
}
},
"risk": "low",
"requiresHermesRun": false,
"requiresReview": false,
"reason": "明确中文引号替换表达，目标文本唯一命中"
}
```
规则：
- 只覆盖低歧义命令。
- 不能为复杂改写、总结、跨页面、多块结构化编辑直接生成写入。
- 不能调用第二套长链模型；如需模型，交给 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 重写。
---
## 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
- [ ] 定义 `mnote.page_ai_review_session.v1`。
- [ ] `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/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。
Reference in New Issue Copy Permalink