trace-grader

技能：trace-grader

评估 Agent 的执行轨迹，而不只是输出。一次运行可能通过错误路径返回正确答案（强制推送、重试风暴、编辑了从未读取过的文件）——这就是“成功但有损坏”；也可能不稳定（通过一次，重跑时失败）。仅检查答案的校验器无法发现这两种情况；TraceGrader 会检查执行路径。

是什么

目的和背景

• 目的：评估 Agent 的执行路径（工具选择、顺序、重试、可重复性、依据），而不只是答案，以便通过可在 CI 中设置门禁的确定性信号，发现“成功但有损坏”和不稳定性。
• 触发条件（何时使用）：
• 你有一次或多次 Agent 运行（轨迹），想了解答案是如何得出的，而不只是是否得出。
• 你需要一个可重复性门禁：“这项任务在所有 k 次重跑中都能通过吗？”（pass^k）。
• 在考虑使用大模型评审器之前，你想要一个针对工具选择／顺序／重试／步骤预算的确定性、可用于 CI 门禁的信号。
• **非目标：**不评估最终答案的质量；配置仍为 verified:false 时，不启用 Agent-as-judge 维度（桩实现，尚未调用）；不修复被标记的运行。

心智模型

trace 源（traces.json · audit jsonl · session transcript）→ parser → run = [{step, tool, args, observation, ok}] → rule checks（config）+ pass^k → 每次运行的 verdict（clean-pass · pass-with-warnings · corrupt-success · fail）→ 若 corrupt 或 flaky 则退出码为 3。规则参数仅位于适配器 harness/trace-grader.config.yaml 中（详情请见下方 Reference）。

输入和输出约定

	Field	Required?	含义
In	--traces / --audit / --transcript	是（三选一）	canonical traces.json；audit jsonl（每个 session_id 对应一次运行）；Claude Code 会话 transcript
In	--task	使用 audit/transcript 时	将运行归入相应任务，以计算 pass^k
In	--json	否	机器可读输出
In	harness/trace-grader.config.yaml	是	禁用的工具、retry_threshold、step_budget、order_constraints、grounding.enabled
Out	每次运行的 verdict + flags + pass^k 块	是	报告
Out	exit code	是	若存在 corrupt-success 或任务不稳定，则为 3

规则和能力

• RULE-01（MUST）：规则参数唯一的存放位置是配置文件。在两个位置设置相同的猜测值，就属于信息泄漏。
• RULE-02（MUST）：切勿将猜测的阈值说成已验证——完成验证前，文件必须保持 verified:false。
• RULE-03（MUST）：Agent-as-judge 维度在配置并验证前必须保持关闭，且不得调用；切勿伪造推断评分。
• RULE-04（MUST）：audit parser 无法查看每个步骤的 ok／observation，因此仅使用 audit log 时不会触发 retry_storm——需要进行依赖失败状态的检查时，请使用完整的 traces.json。
• 能力：读取本地 trace/log/transcript 文件；读取一个适配器配置文件；不调用模型（judge 已关闭），除报告外不写入任何内容。

失败边界

• 存在 corrupt-success 运行或 pass^k = FAIL → 退出码为 3（CI 门禁判定为失败）——这是信号，不是工具错误。
• 来源仅为 audit log → 无法查看每个步骤的 ok／observation，因此不会触发 retry_storm → 结果为部分，如有需要请使用完整的 traces.json。
• Transcript 不包含任务判定 → run.ok 会被强制设为 True → 相信 FLAGS，不要相信已交付的 verdict。
• 尚未在真实 trace 上验证的阈值 → 保持 verified:false，不要将其说成已验证。

如何使用

主要工作流

步骤	类型	输入	操作	输出/退出	失败/下一步
W01	确定性	运行记录	收集轨迹（traces.json 或 --audit/--transcript）	轨迹来源	仅有 audit → 部分支持（B01）
W02	判断	项目	设定边界：只修改 harness/trace-grader.config.yaml	配置	—
W03	确定性	轨迹 + 配置	评分：运行 trace-grader.py	判定结果 + 标记 + pass^k，rc	rc 3 → W04
W04	判断	报告	根据结果采取行动：调查被标记的步骤 / 将不稳定任务视为不可信	结论	—
W05	判断	真实轨迹	（稍后）验证适配器，然后将 verified:true 设为 true	已验证的配置	证据不足 → 保持 false（B02）

各步骤详情（W01–W05 的事实依据）：

1. 收集轨迹。 按上述架构生成 traces.json，或将 --audit 指向 hooklib.audit() 生成的 jsonl（每个 session_id 对应一次运行）。
2. 设定边界。 只编辑 harness/trace-grader.config.yaml — 禁用的工具、retry_threshold、step_budget、order_constraints。这些值应只在此处定义。
3. 评分。 运行评分器；查看每次运行的判定结果 + 标记 + pass^k 区块。
4. 根据结果采取行动。 corrupt-success = 答案正确，但路径不佳/不安全 → 调查被标记的步骤。pass^k = FAIL = 不稳定 → 不宜依赖。
5. （稍后）验证适配器。 根据真实轨迹验证阈值，然后将 verified:true 设为 true。只有此后才考虑启用 agent-as-judge 维度。

运行方法

# bundled 3-case self-test (clean / corrupt / flaky)
python3 harness/scripts/trace-grader.py --self-test

# grade canonical traces, an audit log, or a full session transcript; --json for machine output
python3 harness/scripts/trace-grader.py --traces traces.json
python3 harness/scripts/trace-grader.py --audit .claude/audit/<date>.jsonl --task my-task
python3 harness/scripts/trace-grader.py --transcript ~/.claude/projects/<proj>/<session>.jsonl --task my-task

如果任何一次运行的结果为 corrupt-success，或任何任务不稳定，退出代码为 3（因此 CI 可以设置门禁）。

分支

ID	类型	条件	行为	跳过/失败	汇合点
B01	必需条件	来源是纯 audit jsonl	可以评分，但不会触发 retry_storm；报告限制	需要感知失败 → 改用 traces.json 或 --transcript	W03
B02	可选能力	已配置 judge model 且配置为 verified:true	才考虑启用 agent-as-judge 维度（judge_trajectory()）	条件不满足 → STUB，不调用	W04

验证和停止

确定性验证：python3 harness/scripts/trace-grader.py --self-test（3 个用例：正常 / 错误 / 不稳定），判定结果和退出代码由引擎决定。需要人工审查：将阈值与真实轨迹进行比较后，再将 verified:true 设为 true。在 W04 后停止；W05 是后续步骤，如果没有真实轨迹，不要在同一轮中运行。

示例

• 正向： 在有一次 Edit 但此前从未 Read 文件的会话上运行 python3 harness/scripts/trace-grader.py --transcript ~/.claude/projects/<proj>/<session>.jsonl --task my-task → 标记 edited_without_read（medium），判定结果为 pass-with-warnings，并指出被标记的步骤。
• 边界/失败： 同一任务运行 3 次，其中 1 次失败 → pass^k = FAIL → 退出代码为 3，该任务被视为不稳定；某次运行返回了正确答案，但使用了 forbidden_tool（force-push，high）→ corrupt-success，退出代码为 3。

参考 — 构建内容与适配器

当前已构建 — 确定性，无未知项：

• 跟踪记录架构（契约）： 一次运行 = 步骤列表 {step, tool, args, observation, ok}。
• 解析器： 规范的 traces.json；由 llmwiki/.claude/hooks/hooklib.audit() 写入的审计 jsonl 格式（以及代码记录器的 events.jsonl）；或完整的 Claude Code 会话转录（--transcript）——这是最丰富的数据源：它能还原检索参数（Grep pattern、Read file_path）、observation 和每步的 ok，因此可以观察依据是否充分以及执行结果。跳过 Sidechain（子 Agent）行；转录不包含任务判定，因此其 run.ok 强制设为 True——请相信 FLAGS。
• pass^k： 一个任务运行 k 次 → 要求 k 次全部交付；报告 pass^k。
• 规则检查（由配置驱动）： forbidden_tool（高）、out_of_order（中，通过 must_precede）、retry_storm（中，连续 >N 次同一工具失败）、excessive_steps（低，超过预算）、edited_without_read（中 — 依据充分性的代理指标：对文件执行 Edit/MultiEdit 前，从未先用 Read/Grep 读取或用 Write 写入；由 grounding.enabled 控制）。
• 每次运行的判定： clean-pass / pass-with-warnings / corrupt-success（已交付 且 存在高严重级别标记）/ fail（未交付）。

隔离在单个适配器之后 — harness/trace-grader.config.yaml，verified:false：

• 规则参数（禁止列表、重试阈值、步骤预算、顺序约束）——针对项目的最佳猜测，每项均标注 # ASSUMPTION；
• 推断性 Agent-as-judge 维度（任务完成情况 / 工具使用理由 / 规划评分标准）——judge_trajectory() 是一个 STUB，只有在配置了裁判模型并将文件切换为 verified:true 后才会调用。

后续适配 = 编辑这一个文件，绝不修改引擎。

参考 — 文件

文件	作用
harness/scripts/trace-grader.py	确定性引擎：架构、解析器、pass^k、规则检查、报告、裁判 STUB
harness/trace-grader.config.yaml	唯一适配器（verified:false）——每个值都标注 # ASSUMPTION
harness/tests/trace-grader.fixtures.json	自测样例：clean / corrupt-success / flaky