差异不是供词:先查清是谁写的,再去纠错

多个 agent 共用一个工作目录时,回合结束的文件检查怎样只找本线程写的改动,以及这么做没能解决的问题。
1. 被叫去改别人的稿子⌗
MaxClaw 在每个回合收尾前,会对绑定了工作目录的项目做一次确定性检查。回合开始时,Tool Host 记下项目里 Markdown 的内容和文件元数据;回合结束时再扫一遍,用文件集合、修改时间和大小算出「这一回合里变了什么」。差异里如果有新文档没登记进根 AGENTS.md 的文档索引,或者子文档里另立了一节 ## 当前状态,或者受管区被绕过工具改了,框架就发一条冻结事件,让模型在同一回合里接着改。这些 Markdown 改动还会打包成 diff,交给另一个模型做异步审核,意见再送回来。
只有一个线程在跑时,这套逻辑没毛病。问题出在这一句:
快照差异只回答「什么变了」,不回答「谁改的」。
同一个目录可能同时有这些写入者:
┌──────────── 同一个工作目录 ────────────┐
对话线程 A ──────►│ notes.md (A 的 write_file) │
对话线程 B ──────►│ (只读了几个文件,什么都没写) │
后台任务 T ──────►│ report.md (T 的 shell 脚本) │
落地通道 ────────►│ docs/x.md, AGENTS.md (merge --ff-only)│
└───────────────────────────────────────┘
B 回合结束时,它的快照差异里有 notes.md、report.md、docs/x.md,还有一份受管区被改动过的 AGENTS.md。旧逻辑会把这些全都算到 B 头上:B 会被告知「有未登记文档,去登记」「受管区被绕过修改了,恢复成这样」。
B 是个尽职的 agent,它真的会去改。结果是一个什么都没写的线程,按照框架的要求,回滚了落地通道刚合进来的受管区,或者替别人的半成品文档登记了索引。纠错机制自己成了干扰源。
把反馈发错对象,比不发反馈更糟。 不发反馈,最多是漏掉一个问题;发错了,会生出一个新问题,而且做这件事的 agent 认为自己在守规矩。
2. 两种证据,两种精度⌗
修复办法是在「变了什么」和「去纠正」之间加一步:按写入者归属。归属需要证据,这次的实现用了两种来源,精度不同:
| 证据 | 来源 | 匹配条件 | 精度 |
|---|---|---|---|
| 文件工具写入 | write_file / file_edit / apply_patch 成功后的目标路径;project_state 写的根文件和退役涉及的路径 | 路径相同,并且文件最后改动时间落在这次调用的起止之间 | 精确到路径 |
| shell 命令 | shell / exec_command / write_stdin 的运行区间 | 文件最后改动时间落在本线程任意一条 shell 命令的区间内 | 只到时间窗口 |
文件工具知道自己写了哪个路径,所以按路径匹配。shell 命令不行:python gen.py 会写哪些文件,只有跑完才知道,也可能根本没人知道。能记下来的只有「它从几点跑到几点」,所以只能按时间匹配。
记录发生在 Gateway 的工具路由处。所有 Host 调用都会经过 trackHostCall:
const from = Date.now()
try {
result = await run()
return result
} finally {
const to = Date.now()
if (shell) recordHostCall(threadId, { kind: 'shell', hostId, from,
to: result?.status === 'running' ? null : to })
else if (result !== undefined && !writeFailed(result))
recordHostCall(threadId, { kind: 'file', hostId, paths: writtenPaths(call, result), from, to })
}
这里有三个细节:
- 失败的写入不记。 被拒绝的
write_file就算真在磁盘上留下了东西,也不算这个线程的。测试里专门写了一个返回success: false但实际写了文件的调用,断言refused.md不出现在报告里。 - 还在跑的 shell 区间开到回合结束。 工具返回
status: 'running'时,命令已经转成后台会话,它之后写的文件仍然算这个线程的。writersOf在交给 Host 之前,把to: null补成当前时间。 - 调用记录只放在内存里,按线程、按回合存。 记录挂在
ActiveTurn.calls上,回合结束时,check/finish把它们作为writers交给 Host,由 Host 拿每个改动文件的 mtime 去核对。
Host 侧的判定函数 responsiblePaths 只有十来行:
const inside = (span) => span.from - MTIME_SLACK_MS <= at && at <= span.to + MTIME_SLACK_MS
if (written.some(file => file.path === target && inside(file))
|| (evidence.shells.some(inside) && !input.landed.has(path))) mine.add(path)
被删除的文件已经没有 mtime,就用它所在目录的改动时间;目录也没了,再往上找一级。
3. 20 毫秒的余量⌗
MTIME_SLACK_MS = 20。这个常量的注释写的是:Linux 给 mtime 打时间戳用的是一个粗粒度的内核时钟,可能比 Date.now() 慢几个 tick,所以一次写入的时间戳可能早于发起它的那次调用的开始时间。
如果不留这点余量,一个线程用 write_file 写完文件,归属检查会说「这个文件在你动手之前就改了」,然后把它判给别人。余量取 20ms,足以覆盖时钟粒度,又远小于两次人为写入之间通常的间隔。
这个余量还说明了一个前提:Gateway 记的是自己时钟下的区间,Host 读的是自己文件系统的 mtime。两者在同一台机器上时,比较才精确。设计文档写得很明确:远端 Host 的时钟偏差不做校正。这是有意的取舍,后面再说。
4. 落地通道:唯一能点名的外来写入者⌗
shell 归属有个明显的漏洞:线程 A 的 shell 命令正在跑时,落地通道恰好 merge --ff-only 了一个分支进来,于是落地带进来的文件全都落在 A 的时间窗口里。更极端的情况是,A 自己跑的就是落地脚本。
对一般目录,这无从区分。但 MaxClaw 的源码检出有个特殊之处:它只有一个非线程写入者,就是落地通道,而落地一定会移动 HEAD。所以对源码树多做了一步:
begin: landingOwned = 这是源码检出? head = git rev-parse HEAD
check: landed = git diff --name-only <head> HEAD
shell 归属的候选里剔除 landed 中的路径
文件工具归属不受影响
文件工具的写入不参与剔除,因为路径加时间的双重匹配已经足够有力:如果一个文件是线程亲手用 write_file 写的,后来又被落地覆盖,它的 mtime 会落在落地那一刻,不在写入调用的区间里,本来就不会判给这个线程。
那么落地带进来的未登记文档、受管区变化,谁来负责?设计上的回答是分支的作者:作者任务在自己的工作区里写文档时,已经经过这套检查,落地前就该登记好。这里不另设落地门,也不让碰巧声明了源码树的对话去「恢复」落地结果。
对应的测试场景构造得很刁钻:一个线程的 shell 区间完整覆盖了一次 commit,commit 里有新文档 landed.md,也改了受管区。断言是:这个线程和另一个安静的线程都收不到任何结构问题;第三个线程自己用 shell 写的 mine.md 照常被报告。
5. 受管区:只在「是你改的」时才去比对⌗
根 AGENTS.md 里有一段受管区(当前状态、证据、文档索引),只能通过 project_state 工具写。以前的检查是:回合结束时,受管区要么和回合开始时逐字节相同,要么等于本回合最后一次 project_state 写入,否则报 managed-region-changed,并附上应恢复成的版本。
改动后多了一个前置条件:
const regionIsOurs = input.responsible.has('AGENTS.md')
...
if (regionIsOurs && tracked && !issues.length && !accepted.includes(region)) {
issues.push({ type: 'managed-region-changed', path: 'AGENTS.md' })
}
普通文件工具改受管区会被同步拒绝,所以 AGENTS.md 能归到本线程名下的路径,实际上只剩它自己的 shell 命令。别人改了受管区,本线程就不收到恢复要求;判断本线程的文档有没有登记时,索引取文件当前的受管区。
structure.test.ts 用同一份输入、三种归属集合把行为固定下来:
responsible | 报告 |
|---|---|
{} | [] |
{'detail.md'} | unregistered-document: detail.md |
{'AGENTS.md'} | managed-region-changed: AGENTS.md |
输入完全一样,只是「谁写的」不同,报告就不同。
6. 审核意见只送给作者⌗
归属不只用在结构检查上,异步审核也改了两处:
- 打包。
finish生成审核 diff 时,先算changesOfThread,只打包归属于本线程的 Markdown 改动。别人的改动不进这个 diff,也就不会以本线程的名义产生一次审核。 - 投递。 审核意见挂起时,
store.pending()多了一个authorThreadId条件:thread_id = 作者线程。以前的条件是「这个线程能读到这条记录」,所以同一个项目的其他读者,或者因可见性规则能看到作者线程的线程,都可能在下次注入时收到别人文档的审核意见。本机说明的挂起意见(pendingHost)也同样收紧。
测试 a review of one thread's documents attaches to that thread only 断言:作者线程写了 notes.md 并收到审核后,同项目另一个线程的注入内容里不包含这条意见,作者自己的注入里包含。
这条改动背后的原则很朴素:可见不等于该你负责。 可见性回答的是「你能不能看到」,投递回答的是「这件事该谁去处理」。把前者当成后者,就是让旁观者来纠错。
7. 为什么不用更「干净」的方案⌗
| 方案 | 问题 |
|---|---|
| 每个线程一个工作副本(worktree / overlay) | 对写代码的任务很好,MaxClaw 的落地分支本来就这么做。但很多对话就是要在共享目录里协作,强制隔离会把这类工作变成 merge 冲突 |
| 文件系统层审计(fsevents / fanotify / eBPF) | 能精确拿到 pid,但要把 pid 映射回线程,需要跟踪每条 shell 命令的进程树,后台会话、nohup、ssh 到远端都会断链;而且每个平台都得单独实现 |
| 让模型在回复里自报改了哪些文件 | 这正是要检查的对象自己在作证 |
| 锁目录,同一时间只允许一个线程写 | 并发 agent 的意义就没了 |
| 工具调用记录 + mtime 区间(本次) | 零新依赖,跨平台,只用已有的工具路由钩子;代价是 shell 归属只到时间窗口 |
选这个方案,是因为它的错误方向是可以接受的。shell 区间有重叠时,两个线程都算候选,结果是可能多报,不会漏报自己的改动。一个改动不在本线程的任何写入里,就一定不报给它。这次修的就是「把别人的改动报给我」,所以误差偏向「宁可两边都提醒」也比原来好。
8. 没解决的,和一处我觉得不对的⌗
几处边界在设计文档里写明了:
- 重叠的 shell 区间无法区分。 两个线程同时在跑长命令,其间改动的文件两边都算。
- 远端 Host 不校正时钟。 Gateway 时钟下的区间去比远端文件系统的 mtime,偏差超过 20ms 就会错判。目前精确的范围只限本机 Host。
- 删除用目录 mtime 近似。 同一目录里的另一次写入会把目录 mtime 推到别处,删除就可能归不到真正的删除者。
- 落地剔除只覆盖源码检出。 其他 git 项目里,如果有另一个线程在本线程 shell 区间内做了 commit,仍然会算进来。
还有一处我读测试时觉得名实不符。structure.test.ts 最后一个用例名叫:
a damaged region left by another writer is not reported,
nor does it hide this thread's own document
断言却是:
expect(await checkAs(input, new Set(['detail.md']))).toEqual([])
也就是说,别人把受管区写坏了,本线程新写了一个未登记的 detail.md,报告是空的。追到实现里:受管区解析失败且 AGENTS.md 不归本线程时,checkProjectStructure 直接 return issues,后面的文档登记检查根本没有执行。用例名的后半句和实际行为相反:别人留下的损坏确实遮住了本线程自己的文档。
这个行为本身可以辩护:受管区坏了,就没有可信的索引可以比对,与其拿一个猜出来的索引去报「未登记」,不如这一回合先不说。但它和用例名的说法冲突,至少有一边该改:要么在受管区损坏时退回到 accepted.at(-1)(回合开始时或最后一次写入的受管区)继续检查本线程的文档(对自己写坏的情况,代码已经这么做了),要么把用例名改成「损坏期间暂不检查」。测试是规格,名字说错了,下一个读它的人会信错的那半句。
9. 一句话⌗
多 agent 系统里,「发现问题」和「找到该处理问题的那个人」是两件事。差异算法只负责第一件。第二件需要在写入发生时留下证据:路径、区间,还有发起调用的线程。之后每一条反馈都应该先查这份证据,再决定送给谁。