建立 evals/ 目录： 10 个文件编辑任务； 10 个工具调用任务； 10 个失败恢复任务； 每个任务有 fixture、prompt、expected、policy； CI 中运行 mock replay； 成功率低于阈值则失败； 输出报告包含成功率、平均 step、平均 token、失败类
成功率重要，但不够。还要看： 平均 step 数； 平均 tool call 数； 平均 token； 平均耗时； 权限请求次数； 用户拒绝后是否停止； 相同错误重复次数； 输出是否引用证据； 文件 diff 是否最小； 回滚是否成功。 一个 runtime 策略可能成功率略高，但成本翻倍、工具调用
你不再靠感觉说 Agent 变好了，而是有数据证明；你能比较两个 prompt 或两个 runtime 策略；一次线上失败能进入回归集；危险行为有硬门禁。到这里，Agent Runtime 已经具备工程组织能信任的反馈机制。
Agent 出错后，最怕只剩一句'模型没做好'。这句话既不能定位问题，也不能指导修复。可观测系统的任务，是把一次 Agent run 拆成可以追踪、可以复盘、可以转化为评测用例的证据链。 OpenTelemetry 的公开文档把 span 视为 trace 的基本操作单元：span 有名称、父 span、开始和结束时间、属性、事件、状态等信息。本书不要求读者
一个 Agent trace 至少包含： span 至少包含： 不要把 trace 做成聊天 transcript。聊天记录回答'说了什么'，trace 回答'系统做了什么'。
目标：给一个开源 coding agent 或你的 miniagent 增加 Eval Harness。 功能范围： 录制真实任务 trace； 从 trace 生成 eval case 草稿； 支持本地 replay； 输出成功率、失败类型、平均 token、平均耗时； CI 中设置回归门禁。 适
说 Agent '变好了'很容易。证明它变好了，要靠 eval。 Agent 产品很容易陷入'今天试了几个问题，感觉不错'的幻觉。工程系统不能靠感觉上线。Eval Harness 要把真实任务变成可重复的测试，把 trace 变成回归样本，把 prompt、工具和 runtime 策略的变化变成可比
一次失败任务可以从 trace 里定位原因；你能区分模型问题、工具问题、权限问题、上下文问题和 runtime 问题；trace 中没有明文 secret；每个失败都能转化为一个潜在 eval case。
golden task 是一组有代表性的任务。对 coding agent 来说，可以分为： 文件阅读任务； 代码搜索任务； 单文件编辑任务； 多文件编辑任务； 测试修复任务； 权限拒绝任务； 工具失败恢复任务； 上下文压缩任务； checkpoint/resume 任务。 每个 task 至少包含
一次线上失败，如果不能转化为 eval，它就会再次发生。建议流程： 1. 从 trace 中提取用户目标、关键上下文、工具调用和失败结果； 2. 去除 secret 和用户隐私； 3. 固化 workspace fixture； 4. 写 expected behavior； 5. 加入 CI； 6
Agent eval 天生有波动。处理 flaky 的方法： runtime 单元测试使用 mock model； 真实模型 eval 多跑几次取统计； 用行为断言代替字面匹配； 把'必须不发生'的危险行为单独作为硬门禁； 把人工 judge 与程序化断言分开； 对不稳定 case 标记 quara
说 Agent '变好了'很容易。证明它变好了，要靠 eval。 Agent 产品很容易陷入'今天试了几个问题，感觉不错'的幻觉。工程系统不能靠感觉上线。Eval Harness 的任务，是把真实任务变成可重复的测试，把 trace 变成回归样本，把 prompt、工具、上下文、权限和 runtime 策略的变化变成可比较的数据。 截至 2026 年 8 月
Eval 不只是测模型，也测 runtime 策略。例如： maxSteps=10 vs maxSteps=20； 工具描述短版 vs 长版； 旧历史保留 4 轮 vs 8 轮； 搜索结果返回 20 条 vs 50 条； 写入前是否强制计划； 工具失败后是否允许自动重试。 每次对比只改一个关键变量。
模型 span： provider； model； prompt tokens； completion tokens； latency； finish reason； tool call 数量； 是否触发上下文降级； response id 或 continuation metadata。 工具 s
Agent 失败常被粗暴归结为'模型不行'。这不专业。至少分成五类： 归因 典型现象 模型问题 推理错误、忽视观察结果、重复无效计划 工具问题 工具崩溃、返回格式错、输出不完整 权限问题 策略过严或过松，审批状态丢失 上下文问题 关键文件未注入，历史摘要误导 Runtime 问题 停止条件、重试、并
Agent 出错后，最怕只剩一句'模型没做好'。这一章讲怎么查清楚。 没有 trace 的 Agent Runtime，就像没有采访记录的新闻调查。出错后只能凭印象复盘：模型好像看过文件，好像调用过工具，好像测试失败了，好像用户批准过。工程系统不能靠'好像'。 OpenTelemetry 把 tra
trace 很敏感。它可能包含用户代码、命令输出、环境变量、文件路径、API 响应、模型输入输出。生产系统中，trace 需要： secret 脱敏； 访问控制； 保留期限； 采样策略； 用户可删除机制； 外部导出审计。 不要为了调试方便，把所有 trace 原样传到第三方系统。可观测追求的不是越多
为每次 Agent run 输出 trace JSON，记录： model； prompt tokens； completion tokens； tool name； args； duration； success/failure； retry count； cost estimate； appro
入门阶段可先用本地 JSONL： 每个 run 写入： 后续再接 OpenTelemetry、LangSmith 或自建 UI。先把语义记对，再追求漂亮 dashboard。
真实模型有随机性、网络波动和供应商变化。Eval 需要两层： 第一层用 deterministic mock model 测 runtime 逻辑。它按照脚本返回固定 tool calls，用来验证 schema 校验、权限、checkpoint、trace、停止条件。 第二层用真实模型测端到端能力
