lix/mnote

Files

T

Agent Board d16eccfe10 chore: checkpoint pi lab rust integration work

2026-07-11 20:39:18 +08:00

24 KiB

Raw Blame History

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 慢”，而是模型和工具之间缺少稳定、低歧义、可审计的编辑命令面：

用户说一句自然语言
  -> 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

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

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

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. 总体架构

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。

输出示例：

{
  "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 必须包含：

{
  "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。

输出：

{
  "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，并附带：

{
  "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。

状态：

draft
planning
previewing
awaiting_user
accepted
rejected
applying
applied
failed
aborted
stale

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

最小稳定合同：

{
  "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 低歧义块替换

用户：把「第二段」替换为「第二段已修改」
  -> 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 复杂自然语言改写

用户：把这段整理得更专业，并保留原意
  -> 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 编辑

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

验收：

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

6.4 工具禁用

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：设计治理

新增本文作为当前口径。
7-10 继续作为执行 checklist。
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 最小 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。
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 证据。它仍然有效，继续保留在：

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。

因此本轮将其移入：

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。

24 KiB Raw Blame History Unescape Escape

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

0. 2026-05-18 状态更新

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

1. 本轮结论

2. 现有问题

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

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

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

3. 设计原则

3.1 单一 agent runtime

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

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

3.4 快路径是 shortcut，不是 runtime

4. 总体架构

5. 组件设计

5.1 PageAIContextBuilder

5.2 MnoteAIToolManifestProvider

5.3 PageAICommandRouter

5.4 Hermes run hint 注入

5.5 PageAIReviewSession

6. 关键流程

6.1 低歧义块替换

6.2 复杂自然语言改写

6.3 selection 编辑

6.4 工具禁用

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

7.1 cli-main

7.2 blocknote-ai

7.3 tiptap-apcore

7.4 AI SDK / Context7 核验结论

8. 迁移计划

Phase A：设计治理

Phase B：Manifest 合同收口

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

Phase D：Review session

Phase E：状态与事件统一

Phase F：验收 smoke

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

9.1 7-10 继续执行

9.2 7-11 移入 old

10. 禁止项

11. 成功标准

24 KiB

Raw Blame History

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

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

5.1 `PageAIContextBuilder`

5.2 `MnoteAIToolManifestProvider`

5.3 `PageAICommandRouter`

5.5 `PageAIReviewSession`

7.1 `cli-main`

7.2 `blocknote-ai`

7.3 `tiptap-apcore`

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

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

9.1 `7-10` 继续执行

9.2 `7-11` 移入 old