给 Agent 文件工具设计 dry-run：一份可审核的 JSON 变更清单

Agent 批量写入知识库时，仅返回“执行成功”很难让人判断实际改了什么。把计划生成与文件写入分开，再用稳定的 JSON 描述计划，可以让调用方在执行前审核目标路径、冲突处理和变更范围。

本文是一份接口设计示例，不是 workvault 已实现功能的使用说明，也未提供经过运行验证的性能结论。思路来自阅读 AI 办公实践中心 workvault 的 README：它已有 run、compile、query 等命令，并提供 dry-run 参数。

一、先定义 dry-run 的边界

dry-run 应回答“如果现在执行，将发生什么”。它可以读取输入和目标目录，也可以计算摘要，但不应写入目标业务文件。如果计划生成需要调用模型或访问网络，应明确告知调用方；dry-run 不天然等于离线、零费用或零外部请求。

执行流程可拆为：读取输入 → 校验路径与参数 → 生成候选内容 → 计算变更计划 → 输出计划。正式执行时再重新检查目标状态，并执行计划。不要让 dry-run 和正式执行使用两套冲突判断逻辑，否则预览与实际结果可能不一致。

二、用 JSON 表达具体操作

下面是建议的数据结构，不代表现有命令已经支持此输出：

{
  "schemaVersion": 1,
  "summary": { "create": 1, "update": 0, "skip": 1 },
  "changes": [
    { "path": "people/alice.md", "action": "create", "reason": "target_missing" },
    { "path": "people/bob.md", "action": "skip", "reason": "content_unchanged" }
  ]
}

path 使用目标知识库内的相对路径。action 使用固定枚举；reason 同时保留稳定的原因代码与可选的人类说明。若支持 keep-both，还应输出最终选定的新文件名，避免预览只显示“保留副本”却看不见落点。

summary 应从 changes 计算，而不是单独维护一套计数。对同一输入与相同目录状态，清单按规范化后的路径排序，方便代码审查和差异比较。

三、预览之后仍要再次校验

预览完成到正式执行之间，用户可能修改文件，另一个进程也可能写入相同路径。可以在计划中记录每个既有目标的内容摘要，在执行前重新计算；摘要不一致时停止或要求重新生成计划。

这只是并发保护的一层，不能代替写入瞬间的检查。实现时还需考虑符号链接、大小写敏感性、同一批次内的重复路径，以及目标文件在检查后被替换的情况。单文件可考虑在同目录写临时文件再替换，多文件执行失败时则应返回明确的部分完成清单。

路径检查还应拒绝越出 vault 的目标。仅做字符串前缀比较并不足够，需要规范化路径并考虑目录边界；涉及符号链接时，应按实际解析后的路径复查。

四、让 Agent 和 CI 容易消费

结构化模式下，标准输出只保留 JSON，进度、警告和调试日志写入标准错误。退出码表达成功或失败，JSON 内保留可定位的错误项。这样调用方不用从“正在生成……完成”这类日志中猜测结果。

默认清单应尽量只包含路径、操作、原因与摘要。若需要 diff，可使用单独开关，避免日志系统意外保存资料正文、账号信息或密钥。

五、最小验证场景

可以准备一个临时目录，覆盖以下场景：新文件创建、内容不变时跳过、已有文件按策略处理、批次内路径冲突、预览后目标被修改，以及输入含越界路径。检查 dry-run 前后目标目录内容是否一致，并确认计划中的计数与条目相符。

这些验证比只检查“输出是合法 JSON”更有意义，因为接口的价值在于预览是否可信、是否能指导后续执行。

参考项目：https://gitcode.com/agent-best-practices/workvault
相关功能提案：https://gitcode.com/agent-best-practices/workvault/issues/42

本文为 AI 辅助撰写的设计讨论；示例结构与接口名用于说明方案，实际支持范围请以项目当前代码和官方文档为准。