当AI编码代理说"测试通过"时，它到底测了哪些文件？

一个被忽视的问题：通过的测试属于哪个版本的代码？

当你同时运行两个编码代理窗口处理同一个项目时，一个窗口报告测试通过，另一个窗口完成了代码审查。在你合并之前，有人做了一处小修改——聊天记录里仍然留着两条令人安心的消息，但没有任何一条能告诉你：眼前这些文件，是否就是被检查过的那些。

这是 Squadra 作者（MIT 许可的开源技能与本地 Python 工具包，用于协调 Claude Code、Codex 和交互式 Cursor 窗口）提出的核心问题。测试通过和代码审查，都属于某一个特定版本的代码。一旦文件在检查之后发生变更，先前的证据就不再描述当前的文件。

这个洞察看似显而易见，却是多代理协作中最容易被低估的环节。

一个典型的失控场景

假设任务是修复一个空状态（empty-state）的 UI Bug。以下是作者给出的示意性工作流——不是基准测试或真实客户记录：

步骤	发生了什么	确立了什么
1	Claude 修改了空状态处理逻辑	存在一个候选版本可供检查
2	约定的测试命令在该候选版本上通过	那些检查在那些文件上通过了
3	另一个 Codex 窗口审查冻结的候选版本	非作者方审查了那个版本
4	有人编辑了已检查的文件	候选版本已改变
5	对新候选版本重新执行测试和审查	可以基于当前证据考虑关闭任务

第 4 步是最容易被轻视的。那处编辑可能无关紧要——这恰恰是需要按比例检查的理由，但它不会让先前的结果自动描述新文件。测试通过只对它所运行的那个代码快照有效。

这个问题的实际后果是：聊天窗口里的"测试通过"和"审查通过"两条消息，可能在文件被修改后仍然存在，给你一种虚假的安全感。合并的代码从未被真正验证过。

聊天之外需要留下什么记录

对于多代理之间的交接，一份有用的记录需要回答几个具体问题：谁拥有这个任务、实际运行了什么命令、返回了什么结果、检查了哪些文件、谁审查了它们。

Squadra 的做法是将任务分配、确认、证据、审查和决策保存在一个共享的本地注册表中。代理遵循一套技能规范并使用 CLI 操作；浏览器仪表盘让协调者可以看到完整的任务历史。

具体机制包括：

• prove 命令：记录检查结果和文件指纹（fingerprints）
• deliver 命令：创建不可变的审查包
• 关闭前校验：在任务关闭之前，候选版本、证据和审查会被一起重新检查
• 失效机制：对源文件的更改会使先前的证据和审查在关闭流程中失效

最后这项检查至关重要——即使仪表盘看起来一切正常。仪表盘展示的是历史记录，而不是当前文件状态的保证。

文件指纹（fingerprints） 是 Squadra 证据链的核心机制，值得展开说明。在软件工程中，指纹通常指对文件内容计算的加密哈希值（如 SHA-256），任何字节级的改动都会产生完全不同的摘要。Squadra 的 prove 命令记录检查结果时，会同时绑定当时被检查文件的指纹。这样一来，文件在检查之后哪怕只被改动一个字符，其指纹也会变化，关闭流程在重新校验时就能立刻检测到不匹配。指纹并不记录文件的历史内容，只标识某个具体版本的唯一性，因此它既轻量又可靠。需要注意的是，指纹只覆盖被显式纳入计算的文件，未跟踪的依赖、生成产物或外部资源不会被自动包含，这正是原文强调"源文件指纹不能证明运行环境的一切"的技术根源。

第二个窗口不等于独立审查

一个关键的设计约束：审查者必须拥有与作者不同的身份。给同一个窗口起另一个别名，并不会让它变得独立。

即使满足了身份独立性，仍然存在判断空间：

• 测试是否覆盖了任务本应修复的那个故障？
• 一个通过的测试命令可能是不充分的
• 独立的审查者也可能遗漏问题

记录交接过程使其可被检查，但这并不证明软件是正确的或可以上生产环境。作者明确指出了这一边界。

同样的原则适用于范围问题。被忽略的依赖项需要它们自己的证据。一个源文件指纹不能证明代码运行环境的一切——环境依赖、系统库版本、配置差异，都不在源文件指纹的覆盖范围内。

身份独立性在协作系统中是一个比界面独立性更严格的概念。给同一个代理窗口起两个别名、开两个标签页，底层仍然是同一模型、同一上下文、同一读写权限，因此它无法提供对抗性的视角——它倾向于确认自己的决定，而不是质疑。真正的独立审查要求审查者与作者在身份、会话状态乃至所依据的上下文上都有区分。更进一步，独立只是必要条件而非充分条件：即使身份不同，两者也可能共享同样的盲区或对任务目标的理解偏差。这正是原文所说的"记录交接过程使其可被检查，但这并不证明软件是正确的"——可检查意味着证据可被追溯和复核，但不等于结论一定成立。把可检查性误当成正确性，是自动化流程中常见的认知陷阱。

如何上手

建议从一个有明确检查标准的小改动开始，然后跟踪一个任务走完分配、证据、审查和关闭的完整流程。这能让你在应用到更大项目之前，判断额外的记录开销是否值得。

安装与运行要求：

• Python 3.12+ 和 Git（必需）
• Node.js：自测中的仪表盘检查需要
• 测试环境：macOS/POSIX
• Cursor：以交互模式工作
• 没有 Squadra 账号系统，你的编码代理保持各自通常的费用

仓库包含安装说明、截图和一段 80 秒的动画演示。

多代理协作的核心张力

Squadra 所解决的问题本质上是一个证据时效性问题。在单代理、单窗口的工作流中，测试通过和代码合并之间通常没有其他修改，聊天记录就是足够的证据。但在多代理并行工作时，不同窗口对同一项目进行读写，文件状态在检查与合并之间发生变化的概率大幅上升。

解决方向不是让代理更聪明，而是让证据与代码版本显式绑定。文件指纹、不可变审查包、关闭前重新校验——这些机制的共同目标是确保"通过"这个结论始终指向一组具体的、可追溯的文件。

作者在文末提出了一个值得思考的问题：如果你使用多个编码代理，在信任一次审查之前，你需要在交接中看到什么——diff、命令输出、独立复现，还是别的什么？

证据时效性（evidence freshness）借鉴了分布式系统中的乐观并发控制思想。在多副本环境中，读取时看到的状态可能在写入前已经过期，因此系统需要版本号、乐观锁或校验和来检测冲突。Squadra 的关闭前重新校验，本质上是把这一思路搬到了代理协作流程里：不是假设证据长期有效，而是在使用证据的那一刻重新验证它是否仍指向当前版本。与数据库不同的是，这里的"写入"可能是人类的一次随手编辑或另一个代理的并行改动，触发源更多、更隐蔽。理解这一点有助于举一反三——任何"先检查、后合入"的流程，只要中间存在并发写入的可能，就都需要类似版本绑定的保护，否则检查结论就会悄悄失去意义。