ZeroClaw Eval Harness 实战指南：基于确定性回放的 Agent 循环回归测试体系

ZeroClaw Eval Harness 实战指南基于确定性回放的 Agent 循环回归测试体系【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw本文围绕 ZeroClaw 的评估工具链zeroclaw eval run实现于crates/zeroclaw-eval展开它通过把 JSON 轨迹夹具LlmTrace灌入真实 Agent 循环用声明式期望expects逐项打分为工具调度、多轮对话顺序、回复格式与拒绝行为提供免网络、零成本、完全确定的回归防线。读完本文你将掌握 eval harness 的模式与套件分类、用例格式与全部 11 种期望的语义、fail-closed 加载校验与空运行可证伪性设计并能在自己的改动合入前用它守护 Agent 行为不回退。Eval harness 是什么与 in-loop 评分的本质区别ZeroClaw 的 eval harness 由zeroclaw eval run子命令驱动核心 crate 为 crates/zeroclaw-eval。它的工作方式是把每个评估用例一个 JSON 轨迹夹具通过真实 Agent 循环回放一遍再针对运行产物与夹具中的声明式期望逐项比对产出通过/失败报告。它的使命是守卫 Agent 循环的行为工具分发、多轮排序、回复格式、拒绝应答不因代码演进而回归。一个容易混淆的点是harness不等于[agent.eval]配置段。后者是 Agent 循环内部对回复质量的在线评分器而 harness 是独立于循环之外的离线评估框架配置在[eval]段下通过 CLI 子命令调用。这一点在 crates/zeroclaw-config/src/scattered_types.rs 的EvalHarnessConfig注释中有明确区分。两种运行模式replay 与 live模式做什么成本CIreplay将夹具中脚本化的 LLM 回复经 Agent 循环回放完全确定性、无网络免费门禁默认live对真实 provider 执行用例规划中落地后见 live 模式章节真实 token默认绝不Mode枚举定义在 crates/zeroclaw-eval/src/lib.rsReplay与Live两个变体FromStr同时接受小写形式。当前阶段Phase 0runner 遇到Mode::Live会直接返回明确错误live mode is not implemented yet (Phase 0 supports --mode replay only)见 runner.rsCLI 解析--mode live本身是允许的只是执行会失败——这是为后续阶段预留的接口。套件分类谁必须 100% 通过套件suite是存放*.json夹具的目录规范见 evals/README.mdevals/regression/必须保持 100% 通过。由 crates/zeroclaw-eval/tests/regression_suite.rs 在 CI 中门禁任一失败即阻塞合并。这也是[eval].suite_dir的默认值。evals/capability/规划中难度高的任务通过率低随时间跟踪永不门禁。evals/live/规划中针对真实 provider 执行默认绝不进 CI。其中回归目录本身由一个测试硬性锁定gated_suite_directory_matches_the_configured_default断言EvalHarnessConfig::default().suite_dir evals/regression并检查该目录真实存在防止 CI 门禁的目录与zeroclaw eval run默认跑的目录漂移。运行方法与命令行参数# 回放默认回归套件 zeroclaw eval run # 指向指定套件输出机器可读 JSON zeroclaw eval run --suite evals/regression --format json--suite覆盖[eval].suite_dir--mode覆盖[eval].mode。套件加载是非递归的只有套件目录的直接*.json子文件才被视为用例见 case.rs 的load_suite路径按字典序排序保证输出稳定非 json 文件被忽略目录读取任一失败则整体中止绝不允许套件“悄悄变小”。输出格式有两种人类可读表格Table默认与机器可读 JSONJson适合 CI 产物对应OutputFormat枚举与 src/commands/eval.rs 中的print_report。CLI 子命令定义在 src/main.rszeroclaw eval run [--suite dir] [--format table|json]并通过 src/commands/eval.rs 转发到zeroclaw_eval::run_suite。表格渲染效果SuiteReport::render_tablereport.rs大致如下✓ single-tool-echo (single_tool_echo.json) 4/4 checks ✗ smoke-greeting (smoke_greeting.json) 1/3 checks ✗ response_not_contains(error): unexpectedly present in response: ... ... 7/8 cases passed (1 failed)JSON 输出to_json则包含passed/failed/total/all_passed汇总以及每个 case 的name、source、passed、error、grades数组可直接作为 CI 工件归档。退出码契约CI 门禁的信号zeroclaw eval run的进程退出码就是门禁信号所有用例通过则退出0否则任一检查失败或运行出错退出1。该决策被抽成纯函数SuiteReport::exit_code()report.rs使其能在真实边界被单元测试覆盖——report.rs 的测试直接验证了全通过返回 0、任一失败返回 1。regression_suite.rs的regression_suite_replays_green就是把这个契约接进#[tokio::test]的实例加载并运行回归套件后断言report.all_passed()且exit_code() 0。用例格式LlmTrace 轨迹夹具每个夹具是一个LlmTrace包含model_name报告里展示的用例名、turns对话轮列表每轮有user_input与脚本化回复steps以及声明式expects。用例分为正向行为必须发生与负向行为必须不发生例如tools_not_used、response_not_contains、max_tool_calls: 0。LlmTrace与TraceExpects的结构定义在 case.rs顶层与嵌套结构都带#[serde(deny_unknown_fields)]拼写错误的键会直接导致解析失败而不是被静默丢弃——这是 fail-closed 的第一层。steps中每步response按type标签区分为text含content可带input_tokens/output_tokens或tool_calls含id/name/arguments的调用列表token 字段缺省为 0。下面是一个完整可运行的回归用例与仓库 evals/regression/single_tool_echo.json 一致{ model_name: single-tool-echo, turns: [ { user_input: Echo hello for me, steps: [ { response: { type: tool_calls, tool_calls: [ { id: call_1, name: echo, arguments: {message: hello} } ], input_tokens: 30, output_tokens: 15 } }, { response: { type: text, content: The echo tool said: hello, input_tokens: 50, output_tokens: 10 } } ] } ], expects: { response_contains: [hello], tools_used: [echo], max_tool_calls: 1, all_tools_succeeded: true } }回放机制由TraceLlmProviderreplay.rs实现它是一个实现ModelProvider的 provider把每轮脚本化 steps 放进各自的 FIFO 队列chat()时按序弹出ReplayHandle::finish_turn在每轮结束时检查该轮 steps 是否全部被消费若轨迹为某轮“超规格”编写脚本步数多于实际 LLM 往返次数会直接报错杜绝回复跨轮串扰。这一行为有对应测试over_specified_turn_is_an_errorrunner.rs 测试。期望Expectations全表11 种声明式断言期望语义说明response_contains最终回复必须包含的子串列表针对脚本化最终文本response_not_contains最终回复必须不包含的子串列表负向断言response_matches最终回复必须匹配的正则列表无效正则记为该检查失败不 panic也不短路后续检查tools_used必须被调用过的工具名列表存在性断言tools_not_used必须没被调用过的工具名列表负向断言max_tool_calls工具调用次数上限上界含等于min_tool_calls工具调用次数下限下界含等于exact_tool_calls工具调用次数精确值比tools_usedmax_tool_calls强得多all_tools_succeeded是否所有工具调用都成功布尔可断言 true 或 falsetool_arguments_contain工具实际收到的参数负载必须包含指定子串边界级断言tool_results_contain工具实际返回的结果负载必须包含指定子串边界级断言这些检查全部实现在 grader.rs 的evaluate_expects中每个声明产生一个GradeResult { check, passed, detail }失败时detail会带上观察到的真实负载让 CI 失败无需本地重跑即可诊断。边界断言tool_arguments_contain/tool_results_containresponse_contains只能评价回放 provider 为自己脚本化的文本——它无法证明某个值真的穿过 Agent 循环往返成功。为此评估框架在分发边界记录了每一次真实调用RecordingObserverobserver.rs从ObserverEvent::ToolCall捕获(name, arguments, result, success)四元组存入RecordedCallRunRecord.tool_calls因此成为唯一权威的分发事实record.rs 注释明确工具名、聚合成功状态均由该列表派生而非另行存储一份可被改动的副本。tool_arguments_contain/tool_results_contain就基于这份事实打分expects: { exact_tool_calls: 2, tool_arguments_contain: [ { tool: echo, needle: alpha, call_index: 0 }, { tool: echo, needle: beta, call_index: 1 } ], tool_results_contain: [ { tool: echo, needle: alpha, call_index: 0 } ] }call_index可选、从 0 开始按分发顺序在对指定工具的全部调用中计数省略时只要该工具任意一次调用的负载含needle即通过。指定call_index后若实际调用次数不足、或第i次负载不含needle检查都会失败并给出观察到的负载内容——这是断言调用顺序的推荐方式grader.rs 的grade_payload。配套测试覆盖了交换顺序必失败indexed_payload_expect_grades_per_call_ordering与索引越界必失败indexed_payload_expect_fails_when_index_out_of_range。关键规则凡用例声称某个值经工具往返、或声称发生了 N 次分发就必须用tool_arguments_contain/tool_results_contain/exact_tool_calls来打分——因为tools_used是存在性断言、max_tool_calls只是上界两者组合在“某次分发悄悄丢失”时依然全绿而仅对最终回复的期望在回放机制下永远只能验证脚本化的文本。Fail-closed 加载校验门禁不允许“无法失败的用例”LlmTrace::from_file()case.rs在加载阶段就拒绝以下所有形态且每条错误都点名出问题的夹具文件与字段零轮对话回放会驱动 Agent 零次随后把期望打在一个空运行上max_tool_calls: 0之类的期望会空口认证门禁期望块缺失或为空TraceExpects::is_empty()判定无有效断言零条 grade 时CaseReport::passed()空真成立字符串型期望族response_contains、response_not_contains、response_matches、tools_used、tools_not_used含空字符串条目空子串是重言式、空正则匹配一切、空工具名永远不会被记录正向族会产生永真通过tools_not_used则是退化断言未知顶层键或未知期望键deny_unknown_fields拼写错误的键会静默丢弃期望必须显式失败边界断言族的空值空的tool或needle空泛/自相矛盾的计数边界min_tool_calls: 0空泛下界、min max、exact落在[min, max]之外。其中“零长度条目”与“空 expects 块”的判定还有细节is_empty()只检查向量非空与否而empty_entry_family()专门抓向量非空但条目为空串的形态——因为前者会通过is_empty但断言真空。这些规则在 case.rs 的单元测试中逐条验证省略 expects、空 expects 块、拼错response_contain、拼错顶层expect、五类空条目、四类非法边界、空 payload 字段、嵌套字段拼错如nedle全部被拒。空运行可证伪性admission 拦不住的最后一种空洞加载校验无法拦截一种真空形态一个“什么都不做就已满足”的断言例如孤立的max_tool_calls: 0零轮时会加载失败但只要有一轮且仅此一个断言空运行同样全绿。因此门禁测试对每一个已提交夹具额外执行“空运行打分”构造一个final_response为空、无任何历史与调用、token 为 0 的RunRecord要求至少产生一个失败检查否则该用例无法加入必需门禁。这就是regression_suite.rs中no_gated_fixture_passes_on_a_run_that_produced_nothing回归套件测试的职责。配套的另一个测试missing_argument_fixture_fails_when_the_dispatch_is_silently_repaired则验证了“夹具名字与期望必须一致”把missing_tool_argument_continues_loop的实际运行记录手工改写成“分发被静默修复”wrong_key被改成工具能读的键、一次成功echo断言边界期望必须变红——否则该用例无法检测它声称要防的回归。编写规则让每个用例都可证伪、可判定、可长期维护evals/README.md 给出了明确的用例作者守则源自真实失败从 bug 追踪、支持工单取材从小而精开始——20~50 个好用例胜过 500 个含糊用例。必须到达真实边界若回归发生在某个 bug 处用例必须到达该 bug 发生的边界只用回放 provider 自供文本的夹具无法证明 provider 序列化、流式、策略、历史或 UI 行为。命名与期望一致夹具名与期望必须相符声称的值往返用tool_arguments_contain/tool_results_contain声称的 N 次分发用exact_tool_calls: N声称的顺序用call_index做不到就改名。标注用例类别每个用例声明正向或负向保持套件正负平衡单向评测会催生单向优化。双专家测试two-experts test两人仅凭用例文本必须独立得出相同通过/失败结论否则用例有歧义需要收紧。脚本步即参考答案回放用例的脚本化步骤同时证明任务可解。最低要求至少回放一轮、至少声明一个非空断言加载阶段强制。空运行可证伪每个用例必须能在“什么都没发生”的运行上失败门禁测试强制。隐私夹具会永久流传只能使用占位身份如zeroclaw_user、example.com见 docs/book/src/contributing/privacy.md绝不粘贴真实对话、姓名、密钥或主机名。仓库内的真实回归套件巡礼当前 evals/regression 已落地 8 个用例覆盖不同行为面用例覆盖的行为smoke_greeting.json纯文本问候负向断言不出现 error零工具调用no_tools_on_greeting.json问候不应触发工具tools_not_used: [echo]single_tool_echo.json单轮单工具调用 脚本化最终回复multi_tool_chain.json同一轮内三次连续工具分发后收尾multi_turn_echo_tool_loop.json多轮工具循环用call_index断言每轮参数与结果顺序multi_turn_response_ordering.json多轮回复顺序最终回复必须是第二轮内容不含第一轮关键词unicode_tool_arguments_roundtrip.jsonUnicode 参数naïve café 日本語 ✓经分发边界字节级往返missing_tool_argument_continues_loop.json参数键错误时工具仍被真实调用、返回(empty)兜底、循环继续其中multi_turn_echo_tool_loop.json与unicode_tool_arguments_roundtrip.json是“边界期望”的教科书示例两者都同时声明exact_tool_calls、tool_arguments_contain、tool_results_contain并配合call_index断言顺序。missing_tool_argument_continues_loop.json的期望还包含response_matches: [^The echo tool received no usable message\\b]这样的正则锚定。之所以回放中只有echo一个工具可用是因为 Phase 0 注册的是无副作用的确定性内置工具集default_tools()tools.rs。EchoTool只读取message参数并原样返回参数缺失时返回(empty)兜底tools.rs且execute永远报成功——这正是missing_tool_argument_continues_loop期望tool_results_contain: [{ tool: echo, needle: (empty) }]能成立的依据。接线真实沙箱工具注册表留给 live 阶段的后续实现。运行时隔离与整体架构run_caserunner.rs为每个用例构建完全隔离的 Agent独立临时工作区tempfile::tempdir、后端为none的临时内存用例之间无法互相观察、独立的RecordingObserver与TraceLlmProvider再通过引擎的ScopedToolRegistry装配口把default_tools()以“恒等装配”方式注入所有扩展装配全关无外设、无 MCP、无技能、无 memory-strip确保评测 Agent 看到的工具集与预期完全一致。随后逐轮调用agent.turn(user_input)每轮结束强制finish_turn校验步数消费最后聚合出RunRecord。crate 的整体模块划分见 crates/zeroclaw-eval/README.md 的 Library shape 一节case——LlmTrace夹具格式 套件加载replay::TraceLlmProvider—— 按 FIFO 顺序回放轨迹步的ModelProvidertools—— 回放 Agent 可分发的确定性内置工具observer::RecordingObserver—— 捕获每次分发的RecordedCall名称、参数、结果、成功与 token 用量grader—— 不 panic 的GradeResult检查Gradertrait 是后续阶段副作用/预算/LLM 裁判类 grader 的扩展点runner—— 每个用例构建隔离 Agent、驱动并打分report—— 通过/失败聚合表格 JSON 渲染。配置项[eval]EvalHarnessConfigcrates/zeroclaw-config/src/scattered_types.rs提供两个字段均可在配置文件的[eval]段覆盖suite_dir省略--suite时使用的夹具目录默认evals/regression即 CI 门禁套件规划中的evals/capability/与evals/live/并列其旁mode省略--mode时的执行模式默认replay。该配置类型注册在Config的eval字段上crates/zeroclaw-config/src/schema.rs支持zeroclaw config体系的序列化与 schema 导出。在 CI 中的落地方式一句话总结门禁链路zeroclaw eval run的进程退出码是信号0 全过、1 有失败regression_suite.rs把它包装成 Rust 集成测试确保evals/regression全绿才允许合并套件目录与配置默认值之间由gated_suite_directory_matches_the_configured_default锁定不漂移。对使用者而言本地开发时随时可以zeroclaw eval run --suite evals/regression --format json验证改动或编写新的回归夹具并遵守上文的作者守则——只要遵循“至少一轮、至少一个非空断言、空运行必失败、只放占位身份”这几条铁律你的用例就能安全进入被门禁的套件成为 Agent 循环长期不回退的又一重保障。【免费下载链接】zeroclawFast, small, and fully autonomous AI personal assistant infrastructure, any OS, any platform — deploy anywhere, swap anything 项目地址: https://gitcode.com/gh_mirrors/ze/zeroclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考