用途 agent-eval 用于评估单个智能体会话。评估对象可以是已完成的会话导出文件(trace、JSONL 或 markdown),也可以是刚结束的实时会话。它依据一份「活的、可编辑」的评估标准列表,对智能体行为评分,检测是否调用了正确的技能,记录分数,并生成改进建议。
主要能力
- 轨迹读取:支持 Markdown 会话导出、JSONL 结构化事件流(如 Codex --json 输出)和纯文本记录。从中提取任务描述(首条用户消息)、智能体回复、工具调用及参数、文件变更、执行的命令和技能调用(通过 /skill:name 或 $skill-name 模式识别)。
- 确定性检查:不需要 LLM 的快速规则检查,给出通过/失败结果与具体证据。包括技能调用、命令执行、文件创建与修改、测试执行、循环检测(同一文件编辑次数超限)、并行化(独立调用是否批量执行)、验证行为(是否读取输出或对照规范)等。
- LLM-as-judge 评分:对需要语义理解的维度采用结构化评分规则,而非直接打分。每个 llm_judge 标准定义离散等级(含分数、标签、判定标准、所需证据),评判模型需引用轨迹中的具体证据、说明理由并自报置信度。对关键标准可运行 3 次自洽检查:方差小于 0.15 取中位数,否则标记人工复核。
- 维度加权评分:正确性 40%、效率 25%、工具使用 20%、验证 15%,总体为加权平均。每个维度结合确定性锚点与语义判断,避免单一 LLM 判断主导。
- 技能调用检测:优先运行的特殊检查。若预期技能未被调用,正确性得分上限为 0.50。
- 日志与报告:将结果追加到 ~/.pi/agent/evals/results.jsonl,包含评估 ID、时间戳、标签、git SHA、各维度分数、确定性检查结果、失败模式、建议和评估候选。并在输出目录生成 report.md 报告。
- 活标准列表:标准存于 config/default-criteria.json,可随新发现的边缘情况更新。支持确定性标准(模式匹配、命令模式、序列、并行化、响应模式)与评分规则式 LLM 判断标准。
- 趋势追踪:通过 --tag 标记不同 harness 版本,对同一任务重复评估,再用 agent-benchmark 的 plot-trends.py 绘制趋势,判断每次改动是改进还是退步。
使用方式(命令示例,按资料原样保留) /skill:agent-eval /path/to/session-export.md /skill:agent-eval --tag "prompt-v2.1" /path/to/session-export.md /skill:agent-eval --criteria ~/my-criteria.json /path/to/session-export.md cat session.md | /skill:agent-eval --stdin
主要参数:位置参数为轨迹文件路径(除非用 --stdin);--stdin 从标准输入读取;--tag 为 harness 版本标签(默认 git SHA 或时间戳);--criteria 指定自定义标准 JSON(默认 config/default-criteria.json);--task 指定任务描述(默认从首条用户消息推断);--expected-skill 指定预期技能名;--judge-model 指定评判模型(默认 gpt-4o);--output-dir 指定报告与日志目录(默认 ~/.pi/agent/evals/);--no-grade 跳过 LLM 评分,仅做确定性检查。
适用场景
- 分析已完成的智能体会话导出
- 会话结束后对实时会话评分
- 检查智能体在提示下是否调用了正确技能
- 构建与维护活的评估标准列表
- 通过记录分数追踪脚手架(scaffold)随时间的改进
- 生成评估候选和 harness 修复建议
- harness 改动后的快速检查(多模型比较、回归测试、定时/CI 评估建议使用 agent-benchmark)
限制与说明
- LLM 评判可能出现评分偏差、幻觉引文或高方差,需通过自洽检查、调整评判模型、收紧评分规则等级或人工复核来处理。
- 技能未被识别可能是匹配模式过严,误报可能是模式过松,需调整标准 JSON;标准 JSON 无效时可用 python -m json.tool 校验。
- 轨迹过长或证据分散时可能缺失证据,可用 --task 聚焦或拆分轨迹。
- 资料未提供该技能的收费、价格、平台要求或安装方式等信息。