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](/mnt/Data1T/mnote/AGENTS.md:14) 已同步为当前真实阶段：简单正文编辑主路径是 `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`
  - 结果：通过。