[Ideas] edit 工具是否应该明确提示：同一文件的多个编辑不能并行执行？

[HandleCoding]

问题概述

edit 工具面向模型的说明中，是否应该明确写出下面这条约束？

针对同一个文件的多个 edit 调用必须串行执行；只有目标文件不同的编辑才适合并行。如果遇到 FS_STALE_VERSION，应重新读取文件后再重试。

目前底层文件系统的行为是安全且合理的：写操作会按照 targetKey 加锁，带保护的编辑会校验会话最近观察到的文件版本。原生工具调度器也会把修改类工具按排他方式执行。

不过，如果模型通过更高层的编排工具或并行调用包装器同时发起多个 edit，这些调用仍可能在第一个编辑记录新版本之前取得相同的旧版本。第一个编辑成功后，文件版本发生变化，后续调用就会因为版本过期而返回 FS_STALE_VERSION。

这里不是建议削弱版本保护。版本检查正在正确地防止更新丢失。想讨论的是：这种安全使用约束是否也应该明确展示给模型。

当前模型能看到的说明

当前 master 分支中的 tool:edit 提示说明了字面匹配、replace_all 和编辑前读取文件的要求，但没有提到同一文件不能并行编辑：

Use the edit tool for targeted changes to existing UTF-8 text files. It replaces literal old_string with new_string; by default old_string must appear exactly once. If old_string appears multiple times, provide a more specific old_string or set replace_all to true. Read the file first (the default fs-observation-policy requires it), unless you just created or edited it in this session.

工具描述本身也比较简短：

Edit an existing UTF-8 text file by replacing literal text.

通用复现方式

以 /tmp/edit-probe.txt 为例：

1. 先读取文件一次。
2. 通过能够并行分发工具调用的编排层，同时发起多个 edit，分别修改该文件中不同且唯一的区域。
3. 多个调用可能在进入后端的目标级修改锁之前取得相同的已观察版本。
4. 第一个编辑推进文件版本后，后续受版本保护的调用返回 FS_STALE_VERSION。
5. 重新读取文件，并按顺序执行这些编辑，则可以成功。

这与当前实现一致：

• fs-observation-policy 将会话观察到的版本作为编辑意图传递；
• fs-local 按 targetKey 串行化修改，并拒绝旧的预期版本；
• tool-fs 在编辑成功后记录新版本；
• 原生调度器会排他执行修改类工具，但外部或更高层的并行编排不一定保留这一调度约束。

建议的最小改动

建议给 tool:edit 的系统提示补充一句：

Never invoke multiple edit calls targeting the same file in parallel. Execute edits to the same file sequentially; edits to different files may run in parallel. If an edit fails with FS_STALE_VERSION, re-read the file and retry.

也可以在工具 description 中加入更短的版本，确保没有加载工具专属 prompt section 的场景也能看到这一约束。

为什么原生调度已经排他，仍值得写进说明？

• 模型可能使用具有独立并发语义的编排工具或包装器；
• “并行处理相互独立的工作”是常见的 Agent 策略，而同一文件的不同代码区域表面上看起来互不相关；
• 失败虽然符合预期，但本来可以避免，并且恢复需要额外一次读取和工具调用；
• 明确写成“同文件串行、不同文件可并行”，不会不必要地阻止跨文件并行。

其他可能方案

1. 保持现状，完全依赖原生排他调度器；
2. 让并行编排层识别相同的规范化目标并自动串行化；
3. 在分发前检测同目标调用，并返回更明确的诊断信息。

不建议在 FS_STALE_VERSION 后直接自动盲重试。其他编辑改变文件后，原始字面替换可能已经不再表达相同意图；重新读取后由模型重新判断更安全。

想请教维护者

1. “同一文件串行编辑”是否应该成为模型可见的 edit 使用约定，而不仅是内部调度属性？
2. 工具自身的提示是否应该说明常见高层编排方式引入的约束？
3. 更推荐只补充提示，还是进一步在编排层实现目标感知的自动串行化？

这是英文 Ideas 讨论 #3017 的中文问答版本，方便中文社区参与讨论。

[Rianico]

个人认为靠提示词去约束模型效果还是不太稳定，这个应该属于工具层，由它们自己去决定是否支持串行还是并行，如果 edit 自身支持同个文件多个 edit，那这个其实就不是问题了，甚至可以减少调用的 round

可以看下我这个dsh-better-edit，基于 hashline 设计，对于并发跟多次修改，我是这样设计的：

1. 设计成单个文件允许多个 chained edit（单 edit 多个 patch），一次调用就可以进行多轮修改，这样一来其实就没理由并发地去调用 edit 去操作同个文件
2. 如果模型依旧并发去 edit 同个文件，那应该是工具的职责去保障正确性，我的工具内部做了正确性校验，哪个 edit 成功了其他 edit 就会被拒绝并返回错误码跟理由
3. 多个 edit 操作同个文件肯定是不好的设计，这样就造成了竞态条件，我觉得 claude 的 subagent + git worktree 组合已经给出了答案