如何确认 Agent 真的跑了测试?OpenCollab 原生测试证据账本与 Duo 裁决机制详解
如何确认 Agent 真的跑了测试?OpenCollab 原生测试证据账本与 Duo 裁决机制详解
OpenCollab 是一个研究友好的高性能多智能体协作编码框架,它内置原生测试证据账本,自动记录并校验 Agent 执行的每次测试运行,再通过 Duo 工作流的裁决机制比较两个候选方案的证据、择优交付——帮你确认"Agent 是否真的跑了测试、是否真的通过"。
为什么"Agent 说测试通过了"不可信?
让 AI 写代码时,最常见的信任危机莫过于这句回答:"测试全部通过了。"
但仔细想想,这句话可能是伪造的:
- Agent 可能根本没跑测试,只是复述了历史输出;
- 退出码为 0 不等于"测试通过"——一个空操作命令、零测试模式甚至拼错的路径,都可能"成功"退出;
- 即使测试通过了,Agent 在跑完测试后又改了代码,那这次"通过"对最终代码也已失效。
OpenCollab 的回答是:不采信模型的口述,只采信可验证的行为证据。这正是它的标语——Program how coding agents collaborate. Verify that they did.(编程化地让 Agent 协作,并验证它们确实做到了)。
原生测试证据账本:给每次测试运行留档
OpenCollab 的测试证据账本由 evidence_tools 提供(入口见 opencollab/bootstrap/evidence_tools.py)。它与普通工具集完全同源,只是在 Bash 外面多包了一层执行观察器——命令照常执行,但执行结果会被记入账本。工作流通过 candidate.test_records 与 candidate.verified_targets 拿到这些留存记录,官方说明见 docs/test-evidence.md。
观察器认识哪些测试命令?
命令解析器(opencollab/adapters/tools/evidence/command_evidence.py)能识别三类真实测试执行:
| 运行器 | 说明 |
|---|---|
| pytest | 直接调用及其支持的 Python/包管理器封装(如 python -m pytest) |
go test -json |
Go 标准测试,要求 JSON 输出以便解析 |
| Django | python tests/runtests.py 形式 |
细节上也考虑了真实用法:命令开头若带 cd 目录 &&,会被解析为执行工作区,测试目标按该工作区换算成相对路径;运行 pytest 时加 -rA 可保留逐条测试的通过结果(观察器甚至会为可证明的 pytest 命令自动补上 -rA,保证证据足够完整)。
"正面证据"原则:不看退出码,看通过证明
账本的核心判定函数是 has_pass_evidence(opencollab/adapters/tools/evidence/_test_results.py),它只依据正面证据给"绿"(GREEN)判定:
- 输出被截断 → 直接判为未验证(可能丢掉了唯一的通过/失败证据);
- pytest:必须恰好有一条结果汇总行,
failed/error计数为 0、退出码为 0、passed数大于 0,还要在-rA的逐条PASSED摘要中证明请求的测试目标确实执行了; - go:解析输出中的
PASS行与目标匹配; - 没有解析器的运行器 → 构造上就无法授权"绿"判定。
换句话说:退出码为 0 只是必要条件,"请求的测试真实执行并通过"才是充分条件。每条记录(目标、运行器、命令、工作区、退出码、verified 状态)都会深拷贝留存,供后续比较,实现见 opencollab/adapters/tools/evidence/bash_evidence.py。
证据会自动失效:测试之后又改了代码
这是账本最容易被忽略、也最关键的机制——适用性(applicability):
- 每次识别到的测试执行创建一条
applicability="current"记录; - 之后完成的
file_write/apply_patch若观察到内容变化:verified_targets清空,此前记录全部降为unknown,被改路径按完成顺序追加进post_test_edits; - 识别范围外的 Bash 命令(包括失败或被中断的)同样使旧记录失效,命令留存于
post_test_commands——因为 shell 命令哪怕执行失败也可能已经改过文件; - 只读工具不影响适用性;重新跑一次测试则会新增一条 current 记录,与历史记录并存。
原有的退出码和解析器判定的 verified 值始终保留在历史里——账本只回答"此刻这条证据还作不作数",而不是抹掉事实。
Duo 裁决机制:两个候选、机械比较、只读裁决
有了账本,OpenCollab 内置的 Duo 工作流(opencollab/builtin_workflows/duo.py)就把"验证"变成了流程化的五阶段:
candidate-a → candidate-b → mechanical-selection → adjudication → adoption
- 候选 A:追求最简单、完整的解法;
- 候选 B:端到端检查依赖、交互与边界情况,并且会收到 A 实际观察到的公开验证命令,在相关且可用时执行同一检查;
- 两个候选运行在隔离的 worktree 中,改动、测试、证据互不污染。
先做机械比较:绿/红证据直接定胜负
进入裁决前,运行时先做机械的公开测试比较(opencollab/builtin_workflows/_candidate_records.py):
- 只有
applicability="current"的记录参与比较; - 两条记录在目标、运行器、命令完全一致时才可比;
- 若同一检查 A 为绿(退出码 0 且 verified)、B 为红,且这是唯一分歧点 → 直接选出 A,无需裁决;
- 其他情况交给裁决者。
这一步的意义:能用事实判的,绝不让模型再"说"一遍。
只读裁决者:看证据,不看口供
机械选择仍未定论时,Duo 保存完整候选证据交给一个只读裁决 Agent:
- 比较数据在 128,000 UTF-8 字节以内时,裁决者直接收到两个完整 diff、各自的完整公开测试记录、可比较的共同记录与双方报告;超过则通过
read_candidate_evidence分页读取; - 模型撰写的结果报告被明确标注为候选陈述(claim)——它只是待评估的断言;
- 裁决者逐条需求追踪"输入/状态 → 实现路径 → 预期输出"的完整行为,每项判断的
a_evidence/b_evidence必须引用候选的真实改动路径。
裁决有明确的优先级规则:正确性与兼容性优先,"改动多、报告长、架构更炫"不构成优势;证据相当时默认选 B;diff 完全相同选 B;裁决缺项或矛盾时最多补做一轮聚焦会话,仍不可用则回退默认 B。裁决证据可通过 candidate_evidence_dir 参数落盘到宿主目录,供调用方事后复查。
最终结果会分别记录 winner 与 adopted——采用可能失败并回退另一候选,status 取 done / incomplete / error,选择理由、证据与 token 消耗全部留痕。
快速上手:跑一次 Duo
按 configs/README.md 配置好模型端点后,Duo 随 OpenCollab 一起安装,无需自建 workflows/ 目录:
opencollab workflow run duo --workspace /path/to/workspace \
--task 'Complete the task described here.' \
--args '{"allow_unisolated_shell":true}'
需要自行实现工作流时,证据工具集可直接组合使用:
from opencollab.tools import evidence_tools
tools = evidence_tools(
"bash", "file_read", "file_write", "apply_patch", "grep", "git_diff",
headless=True,
)
candidate = await ctx.candidate_agent(prompt, tools=tools, label="coder")
print(candidate.test_records) # 完整测试证据账本
print(candidate.verified_targets) # 当前仍然有效的通过目标
完整用法参见 docs/duo.md 与中文指南 docs/duo/README.zh-CN.md。
核心源码与文档索引
- 证据账本入口:opencollab/bootstrap/evidence_tools.py
- Bash 执行观察器:opencollab/adapters/tools/evidence/bash_evidence.py
- 通过判定(GREEN 规则):opencollab/adapters/tools/evidence/_test_results.py
- 测试命令识别:opencollab/adapters/tools/evidence/command_evidence.py
- Duo 工作流:opencollab/builtin_workflows/duo.py
- 机械比较与采用:opencollab/builtin_workflows/_candidate_records.py
- 官方文档:docs/test-evidence.md、docs/duo.md、docs/runtime-design.md
小结
OpenCollab 用三层设计回答"如何确认 Agent 真的跑了测试":
- 账本层:观察器记录每次真实测试执行,"正面证据"原则杜绝伪造的绿判定;
- 失效层:测试后的任何编辑或可疑 shell 命令自动使旧证据失效,防止"先跑后改"偷换证据;
- 裁决层:Duo 先机械比较可比记录,再让只读裁决者基于完整证据而非模型口供做出选择,全程留痕、可复查。
对新手而言,这套机制的价值在于:它把"验证"从一句无法证实的口头承诺,变成了一条可以打开、逐条核对的证据链。🔍


