mnote/bugs/07-ai/done/7-23-markdown-edit-manifest-schema-contract-drift-v1.md

# 7-23 [done][bug] mnote.doc.markdown_edit manifest schema 缺少 required 与写入字段 v1

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

## 1. 问题定义

`mnote.doc.markdown_edit` manifest 的 input schema 没有完整声明 `required` 字段，也缺少 `dryRun`、`idempotencyKey` 等写入合同字段。

这会让模型、ACP wrapper 和外部调用方无法从 manifest 得知真实写入要求。

## 2. 证据

- [manifest.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/manifest.rs:413) 附近定义 `mnote.doc.markdown_edit` manifest。
- 当前 schema 更像参数提示，没有完整表达写入前置条件。

## 3. 影响

- 调用方可能不传幂等字段或 dryRun 字段。
- tool toggle / schema validation 无法提前拒绝不合规请求。
- Reasonix / ACP 等多 runtime 接入时会继续复制不完整合同。

## 4. 建议修复

- 为 `mnote.doc.markdown_edit` 补全 JSON Schema：`required`、互斥的 `operations` / `full_content`、写入合同字段。
- manifest 与 Rust runtime 校验保持一致。
- 增加 manifest snapshot 测试，防止字段再次漂移。

## 5. 修复

已修复：

- [manifest.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/manifest.rs:413) `mnote.doc.markdown_edit` 改为复用统一 `write_tool` schema 生成器。
- [manifest.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/manifest.rs:302) manifest 现在声明 `dryRun`、`idempotencyKey` 与 actor/session/run/toolCall/trace 等写入合同字段。
- [manifest.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/hermes_tools/manifest.rs:449) 通过 `anyOf` 声明 `operations` / `full_content` 至少提供一个。
- [hermes_tools.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/hermes_tools.rs:730) 增加 manifest 路由级测试，防止 schema 再次漂移。

## 6. 验证

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

结果：1 个测试通过。