Eval harness

评估测试框架（zeroclaw eval run，crate crates/zeroclaw-eval）会通过真实的智能体循环运行智能体评估_用例_（JSON 轨迹测试夹具），并依据声明式的预期对每次运行进行评分。它用于防止 ZeroClaw 的智能体循环行为（工具分发、多轮顺序、响应格式化、拒绝回答）出现回归。

它与 [agent.eval]（循环内的响应质量评分器）不同。该评测框架在 [eval] 下配置，并通过 CLI 子命令调用。

模式

Suite 分类

Suites 是由 *.json 夹具文件组成的目录（参见 evals/README.md）：

• evals/regression/：必须保持 100% 通过。通过 crates/zeroclaw-eval/tests/regression_suite.rs 在 CI 中进行门禁控制；任何失败都会阻止合并。这是默认的 [eval].suite_dir。
• evals/capability/（计划中）：高难度任务，通过率较低；随时间持续跟踪，但从不作为门禁。
• evals/live/（计划中）：针对真实模型提供方执行的用例；默认情况下不会在 CI 中运行。

运行中

# 重放默认回归测试套件:
zeroclaw eval run

# 指定某个测试套件，输出机器可读的 JSON：
zeroclaw eval run --suite evals/regression --format json

--suite 会覆盖 [eval].suite_dir；--mode 会覆盖 [eval].mode。套件加载是非递归的：只有套件目录的直接子级 *.json 文件会被视为用例。

退出码约定

zeroclaw eval run 仅在每个用例都通过时以 0 退出，否则以 1 退出（包括任何检查失败或运行错误）。这是 CI 关卡：进程退出码即为信号。同样的判定逻辑以纯函数 SuiteReport::exit_code() 的形式对外暴露，便于在其真实边界上进行测试。

大小写格式

每个 fixture 都是一个 LlmTrace：包含 model_name、一组对话 turns（每个 turn 有 user_input 和预设响应 steps），以及声明式的 expects。每个用例要么是正向用例（必须发生某种行为），要么是负向用例（禁止发生某种行为，例如 tools_not_used、response_not_contains、max_tool_calls: 0）。编写规则（包括“双专家测试”和仅使用占位身份的隐私要求）请参见 evals/README.md。

基于派发边界（tool_arguments_contain、tool_results_contain 和 exact_tool_calls）的期望，检验的是工具调用的派发过程，而不是脚本化的文本。当用例声称某个值经过工具往返传递，或声称发生了特定次数的工具调用时，应使用这些期望，参见 crates/zeroclaw-eval/README.md 中的说明。仅对最终响应设置期望无法证明上述任一点，因为回放提供方（replay provider）会预先编排该响应本身。已记录的调用列表是派发事实的权威来源。工具名称和整体成功状态都在评分时由它推导得出，因此更丰富的边界证据不会产生第二份可独立修改的工具调用摘要。

夹具加载采用失败即关闭（fail closed）策略，因为必需的门禁不得为一个无法失败的用例出具通过结论。LlmTrace::from_file() 会拒绝以下夹具：未声明任何对话轮次的夹具（回放将驱动智能体运行零次，并将其期望与一次空运行进行比对）；期望块被省略或为空的夹具；在字符串类期望族（response_contains、response_not_contains、response_matches、tools_used、tools_not_used）中包含零长度条目的夹具；以及包含未知顶层键或未知期望键的夹具。分派边界族同样遵循这一原则：空的 tool 或 needle、空洞的 min_tool_calls: 0，以及彼此矛盾的计数上下限，都会在加载时被拒绝。每条拒绝信息都会指明出错的夹具及相应字段。

准入检查无法识别一种残留的空泛断言：对于一个什么都不产生的运行也能满足的断言，例如单独的 max_tool_calls: 0。门控套件测试会用空运行评估每个已提交的 fixture，并要求至少一项检查失败，因此不能验证任何行为的用例无法加入必需门禁。