# 7-21 [done][bug] mnote.doc.markdown_edit 本地文件写入绕过 dryRun / idempotency v1

> 发现时间：2026-05-17
>
> 状态：`[done]`
>
> 关联主线：`07-ai`

## 1. 问题定义

`mnote.doc.markdown_edit` 的本地文件分支没有调用统一写入合同校验，也没有检查 `dryRun` 与 `idempotencyKey`，在匹配成功后直接 `fs::write`。

## 2. 证据

- [doc.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/doc.rs:714) 进入 `doc_markdown_edit` 后没有先调用 `ensure_write_contract`。
- [doc.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/doc.rs:842) 注释说明本地文件直接写回。
- [doc.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/doc.rs:845) 对本地路径执行 `fs::write`。

## 3. 影响

- `dryRun=true` 时也可能落盘，违反工具预览语义。
- 缺少幂等键会让重试请求重复写入，尤其是 ACP / Hermes 断线重试场景。
- 本地 `.md` 与在线 Convex 文档的写入安全级别不一致。

## 4. 建议修复

- 在 `doc_markdown_edit` 写入前统一调用 `ensure_write_contract`。
- 对 `dryRun=true` 返回 diff / preview，不落盘。
- 增加本地 `.md` dryRun 单测，断言文件内容不变。

## 5. 修复

已修复：

- [block.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/block.rs:631) 将统一写入合同校验开放为 `pub(crate)`，供 `mnote.doc.markdown_edit` 复用。
- [doc.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/doc.rs:722) `mnote.doc.markdown_edit` 入口统一调用 `ensure_write_contract`，本地 `.md` 与在线文档一致要求 `idempotencyKey` 与显式 `dryRun`。
- [doc.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/doc.rs:845) 本地文件 `dryRun=true` 时只返回 `written=false` 预览结果，不再写入磁盘。
- [hermes_tools.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes_tools.rs:1557) 增加路由级回归测试，覆盖缺少 `idempotencyKey` 与本地 dry-run 不落盘。

## 6. 验证

```bash
cargo test --manifest-path rust/Cargo.toml -p mnote-web hermes_tools_markdown_edit_local -- --nocapture
```

结果：2 个测试通过。