mnote/bugs/07-ai/done/7-18-ai-markdown-edit-phase-state-contract-drift-v1.md

7-18 [done][bug] AI markdown_edit 阶段状态合同漂移 v1

发现时间：2026-05-17

状态：[done]

关联主线：07-ai

1. 问题定义

当前仓库的顶层协作口径仍描述 AI 侧“当前只做 Phase A，Phase B 退役 local_rule planner 仍未实施”，但 design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md 与源码已经把 mnote.doc.markdown_edit 推到实际运行链路。

这造成阶段合同漂移：文档与实现同时在表达“仍处 Phase A”和“Phase A / B 已开始切主”两种状态。

2. 影响

• 后续开发者无法判断 page_ai_workflow 是否应继续保留 local_rule 快路径。
• AI 编辑验收标准会混乱：到底验 apply_block_ops，还是验 markdown_edit 回读一致性。
• 新功能容易继续堆到过渡路径，而不是收敛到正式工具合同。

3. 证据

• rust/crates/mnote-web/src/routes/page_ai_workflow.rs 已直接调用 doc::doc_markdown_edit。
• design/07-ai/process/7-14-online-local-ai-markdown-editing-convergence-v1.md 已记录在线 / 本地 markdown 编辑收敛方向。
• 根目录协作口径仍强调 Phase B 退役 local_rule planner 属于后续项。

4. 建议修复

• 明确当前真实阶段：markdown_edit 是否已经是页面 AI 简单编辑主路径。
• 若已切主，应把 page_ai_workflow、Hermes guidance、manifest 和 smoke 都同步到该口径。
• 若未切主，应限制 markdown_edit 的 runtime 使用面，并把设计稿状态回退为实验态。

5. 修复

2026-05-18 已完成运行时侧收口与顶层协作口径同步：

• page_ai_workflow 当前运行时已统一走模型输出 search/replace → mnote.doc.markdown_edit → 统一 mnote tool executor。
• Hermes run guidance 已改为普通正文编辑优先 mnote_doc_markdown_edit，apply_block_ops 仅作为结构性块操作辅助。
• markdown_edit 在线写回在无法安全映射最终 markdown 时明确拒绝，避免 ok=true 伪成功。
• 根目录 AGENTS.md 已同步为当前真实阶段：简单正文编辑主路径是 mnote.doc.markdown_edit，page_ai_workflow 通过模型生成 markdown 编辑意图后调用统一 mnote tool executor，apply_block_ops / mnote.block.* 仅作为结构性辅助。

6. 验证

• rg -n "local_rule|Phase A|Phase B|当前只做|过渡实现为 .*block-edit-workflow" AGENTS.md
  • 结果：无输出，旧阶段合同表述已移除。
• cargo test --manifest-path rust/Cargo.toml -p mnote-web markdown_edit -- --nocapture
  • 结果：通过。
• cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_workflow -- --nocapture
  • 结果：通过。
• cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_client_run_guidance_prefers_markdown_edit_for_plain_body_edits -- --nocapture
  • 结果：通过。