mnote/design/10-review/done/09-page-ai-fast-block-edit-runtime-review.md

09 页面 AI 快速块编辑 Runtime Review

状态：done

日期：2026-05-16

关联主线：

• design/old/07-ai/process/7-10-page-block-ai-tooling-execution-checklist-v1.md
• design/07-ai/reference/7-12-page-ai-hermes-tool-routing-and-review-surface-v1.md
• design/07-ai/done/7-9-page-block-ai-tooling-roadmap-v1.md
• design/05-editor-mainline/done/5-13-page-block-identity-and-command-contract-v1.md

---

0. 归档说明

本文件是 2026-05-16 的页面 AI fast block edit 历史审查快照。其记录的 local_rule / doc_apply_block_ops 快路径曾被后续 mnote.doc.markdown_edit 阶段替代，但该阶段也已被 local-first agent 文件编辑控制面覆盖；本文不再作为当前 runtime 口径。

2026-06-01 当前有效口径：local-first 普通 Markdown 编辑默认走授权文件引用 + allowed roots/files + agent 原生 patch/diff + watcher/BufferStore/Page Aggregate 同步；mnote.doc.markdown_edit 只保留为 remote/cloud/compat fallback 或结构校验辅助。

当前有效口径见：

• 10-current-mnote-ai-runtime-review-v1
• 11-current-full-architecture-review-v1
• 7-18 AI markdown_edit 阶段状态合同漂移
• 7-20 page_ai_workflow 绕过 Hermes tool executor / audit / toggle

归档时的历史结论：page-ai/block-edit-workflow 仍是简单编辑 fast-path 入口，但当时实现应通过模型生成 markdown search/replace / full_content 后调用 mnote.doc.markdown_edit，并复用统一 mnote tool executor；mnote.doc.apply_block_ops / mnote.block.* 只作为结构性块操作辅助。该结论不指导当前 local-first 新实现。

1. 本轮结论

页面 AI 块写入的慢点不在 Rust 块工具本身，也不在 Convex 持久化本身。

本轮真实浏览器 smoke 显示：

• 旧路径：页面 AI 先调用 /api/page-ai/block-edit-workflow，快路径模型阶段耗时约 7695ms，随后因模型输出的块定位未命中 projection，doc_apply_block_ops 返回 mnote_block_not_found，前端继续 fallback 到 /api/hermes/client/runs，最终由 Hermes agent 调 mnote.doc.apply_block_ops 写入，总可见耗时约 13246ms。
• 新路径：同一类简单中文块操作先由 mnote 本地 planner 解析为 replace/insert_after/delete operations，再直接调用 Rust doc_apply_block_ops。浏览器 smoke 回读可见耗时 788ms；后端日志显示 operation_source=local_rule、model_ms=0、apply_ms=42、total_ms=42，且未进入 /api/hermes/client/runs。

因此，当前要继续做的是 Hermes 工具路由、上下文冻结、dry-run/review 与 Rust 写入校验基建，而不是继续让 Hermes agent 反复执行同一个端到端动作，也不是在 mnote 内新建第二套 AI runtime。

---

2. 慢的直接原因

2.1 通用 agent 编排链路太长

旧页面 AI 编辑链路实际包含：

浏览器输入
  -> Hermes session/profile/tools 初始化
  -> 模型理解页面任务
  -> 模型选择工具
  -> 工具调用
  -> 回读或继续推理
  -> 最终回复

这适合复杂任务，但不适合“把 A 替换为 B / 在 A 后插入 C / 删除 D”这类明确块操作。

2.2 模型直接产 operations 不够可靠

本轮快路径第一版已经绕开 Hermes agent，但仍让 DeepSeek 直接根据 page_xml/page_text 生成 operations。失败点是：

model_ms ~= 7695
operations = 3
apply -> mnote_block_not_found
fallback -> Hermes agent

说明模型输出了看似正确的操作数，但 block 定位信息没有命中当前 Page Aggregate projection。这个问题不能靠增加 smoke 次数解决，必须让 mnote runtime 在模型前后都掌握定位与校验。

2.3 失败后 fallback 放大了耗时

第一版前端逻辑在快路径失败时继续进入 /api/hermes/client/runs。这导致一次用户请求可能经历：

快路径模型失败成本 + Hermes agent 成功成本

本轮已改为：只有后端明确返回 page_ai_workflow_not_block_edit 才允许 fallback；其他快路径错误直接在本轮 run 中失败展示，避免重复写入和重复等待。

---

3. 已完成的修正

3.1 页面 AI 快速块编辑 route

已新增并接入：

• POST /api/page-ai/block-edit-workflow
• 文件：rust/crates/mnote-web/src/routes/page_ai_workflow.rs

该 route 负责：

• 接收当前页面冻结后的 mnote.page_ai_context.v1。
• 为明确中文编辑语句先走本地 operation planner。
• 无法本地解析时才调用小模型生成 operations。
• 最终统一走 mnote.doc.apply_block_ops，由 Rust 生成 canonical content 并保存。

3.2 简单块操作本地 planner

已支持这类明确表达：

把「A」替换为「B」；
在「C」后插入「D」；
删除「E」。

输出直接是：

[
  {"op":"replace","matchText":"A","content":"B"},
  {"op":"insert_after","matchText":"C","content":"D"},
  {"op":"delete","matchText":"E"}
]

该层的目的不是做通用自然语言理解，而是把高频、低歧义、可确定的块编辑从模型路径剥离出来。

3.3 快路径可观测性

后端日志已记录：

• workflow started/completed
• operation source：local_rule 或 model
• operations 数量
• model 耗时
• apply 耗时
• total 耗时

smoke 也已在失败时写出 evidence JSON，并记录 /api/page-ai/* 与 /api/hermes/client/* 请求/响应。

---

4. 验证证据

命令：

cargo test -p mnote-web page_ai_workflow -- --nocapture
cargo test -p mnote-web hermes_tools -- --nocapture
MNOTE_PAGE_AI_FAST_TIMEOUT_MS=60000 node scripts/task-page-ai-block-edit-workflow-smoke.js

结果：

• page_ai_workflow：2 passed。
• hermes_tools：22 passed。
• 浏览器 smoke：通过。

最新浏览器 evidence：

/mnt/Data1T/mnote/tmp/page-ai-block-edit-workflow-smoke/mp86uciu.json

关键值：

{
  "timingsMs": {
    "pageAiWriteVisible": 788
  },
  "usedFastWorkflow": true,
  "usedHermesRun": false,
  "finalTexts": [
    "第一段 mp86uciu",
    "插入段 mp86uciu",
    "第二段已修改 mp86uciu"
  ]
}

后端关键日志：

operation_source="local_rule"
model_ms=0
apply_ms=42
total_ms=42

---

5. 剩余问题

5.1 不能把本地 planner 当成完整 AI runtime

当前本地 planner 只覆盖低歧义中文引号表达。它证明了正确的 runtime 方向，但不是最终答案。

需要继续建设：

• PageAIContextBuilder：冻结 selection/page context，减少模型输入。
• PageAIIntentParser：先判定是明确块操作、结构化改写、摘要问答、还是复杂编辑。
• PageAIOperationPlanner：把明确操作转成 mnote.doc.apply_block_ops，复杂操作才调用小模型。
• PageAIOperationValidator：模型输出后必须用 projection 校验 blockId/matchText/allowedTargetBlockIds。
• PageAIApplyController：统一处理 yolo 写入、失败展示、回读验证、审计日志。

5.2 模型输出 operations 仍需修

当请求不能被本地 planner 解析时，仍会调用模型。该路径必须补：

• 输出 schema 更严格，禁止模型臆造 blockId。
• 优先 matchText 或由服务端根据 text resolve block，而不是信任模型 blockId。
• 模型输出后做 dry-run validate，不命中时不要 fallback Hermes agent 重新跑。
• 把 validation error 反馈给用户或进入后续 clarify/retry，而不是隐式整页写。

5.3 Hermes agent 不应承担短路径编辑

Hermes 仍适合：

• 多步骤页面理解。
• 跨页面检索。
• 工具不可直接表达的复杂任务。
• 外部 skill/plugin 编排。

但对当前页面小段落块增删改，mnote 自己的 runtime 应该在浏览器/Rust route 内完成 intent -> operations -> apply -> readback。

---

6. 下一步建议

优先级应从“继续 smoke”切到“补 AI runtime 基建”：

1. PageAIIntentParser

   • 输入：用户 prompt、scope、selection、page context。
   • 输出：direct_block_ops | model_block_ops | question | unsupported。
   • 目标：不让每条简单编辑都进入 Hermes agent。

2. PageAIOperationPlanner

   • 扩展当前本地 planner。
   • 支持常见中文/英文明确表达。
   • 支持选区内“改成/润色/拆成列表”等可控操作。

3. PageAIOperationValidator

   • 所有 operations apply 前先 resolve projection。
   • 对 blockId、matchText、allowedTargetBlockIds、editable、children、revisionRef 做统一校验。
   • 失败返回结构化错误，不 fallback 通用 agent。

4. PageAIApplyController

   • 统一 yolo 模式下的写入、回读、状态展示和失败提示。
   • 后续再接 preview/review session，而不是现在把 review 作为默认阻塞。

5. 模型路径瘦身

   • 对必须调用小模型的任务，发送 page_xml/text + allowed operations schema。
   • 模型只负责生成候选 operations；最终定位、校验和写入仍由 Rust runtime 负责。

---

7. 当前判断

小段落编辑低于 10s 已经被证明可达，且当前 smoke 为 788ms。

下一阶段的关键不是再证明“能写”，而是把这条快路径产品化：

用户意图
  -> mnote intent/parser
  -> operation planner
  -> projection validator
  -> Rust apply
  -> readback
  -> UI 状态/审计

Hermes agent 应从默认编辑执行器退回到复杂任务编排器。