mnote/bugs/07-ai/done/7-19-hermes-tool-guidance-markdown-edit-contract-drift-v1.md

7-19 [done][bug] Hermes 工具指导仍优先 apply_block_ops 而非 markdown_edit v1

发现时间：2026-05-17

状态：[done]

关联主线：07-ai

1. 问题定义

mnote.doc.markdown_edit 已被设计为普通页面正文编辑的主路径，但 Hermes run 的工具指导仍要求简单正文编辑优先调用 mnote_doc_apply_block_ops。

这导致模型策略与工具主线冲突。

2. 证据

• hermes_client.rs 构造工具指导。
• hermes_client.rs 要求上下文足够时直接调用 mnote_doc_apply_block_ops。
• hermes_client.rs 明确“简单小段落编辑”优先用 apply_block_ops。

3. 影响

• Hermes 与 page AI fast-path 会走不同编辑工具。
• markdown 级 search/replace 的收敛设计无法成为唯一验收口径。
• apply_block_ops 的 revision / conflictDetectionKey 合同缺陷会被继续放大。

4. 建议修复

• 将普通正文 search/replace、局部段落替换、全文 markdown 替换统一引导到 mnote_doc_markdown_edit。
• 仅在需要结构性块移动、资源块、复杂定位时才引导模型使用 apply_block_ops 或 mnote.block.*。
• 同步更新 smoke：模型生成工具调用时应优先产出 mnote_doc_markdown_edit。

5. 修复

• hermes_client.rs 将 Hermes run instructions 改为：普通正文 search/replace、局部段落替换、全文 markdown 替换优先调用 mnote_doc_markdown_edit。
• hermes_client.rs 将 blockEditingToolOrder 首位调整为 mnote_doc_markdown_edit，mnote_doc_apply_block_ops 仅保留给 markdown_edit 不能表达的结构性块操作。
• hermes_client.rs 增加 run guidance 合同测试，防止普通正文编辑重新退回 apply_block_ops 优先口径。

6. 验证

• cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_client_run_guidance_prefers_markdown_edit_for_plain_body_edits -- --nocapture
  • 结果：1 passed
• cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_client_run_body -- --nocapture
  • 结果：2 passed