第 5 章 HarborClaude CodeEDD

第 5 章：Agent 与 Framework 方法解析

本章核心

框架的选择决定了评估的粒度和可复现性。 没有"最好的框架"，只有"最适合当前评估对象和基础设施约束的框架"。

这一章回答三个问题：

主流的 Agent 评估框架（Harbor、EDD、ADK、RAGAS）各自解决什么问题？
可观测性驱动的评估平台（Opik/LangSmith/Langfuse 等）和评估框架是什么关系？
怎么选？面对一个具体评估需求，从哪个框架起步？

5.1 Harbor：Agent 评估的标准化 Harness

Harbor 是什么

Harbor 由 Terminal-Bench 团队开发，是 Terminal-Bench-2.0 的官方 harness，支持评估任意 Agent（Claude Code、OpenHands、Codex CLI 等）。它的定位是"Agent 评估的通用运行时"。

四大核心能力

统一接口：通过 harbor run 命令运行任意基准和 Agent
并行环境：通过 Daytona、Modal、LangSmith 等 provider 实现数千环境并行
RL rollout 生成：为强化学习优化生成轨迹数据（轨迹导出为 ATIF 格式，可直接喂给 SFT/RL）
数据集注册表：274+ 数据集，包括 Terminal-Bench、SWE-bench、Aider Polyglot 等

一个典型命令：

harbor run --dataset terminal-bench@2.0 \
  --agent claude-code \
  --model anthropic/claude-opus-4-1 \
  --n-concurrent 100 \
  --env daytona

为什么 Harbor 的设计值得学习

Harbor 最核心的设计是 Dataset × Agent × Model × Environment 四层解耦：

换 Agent 不改数据集
换模型不改环境
换环境不改评分逻辑

这保证了评估的可复现性——每次运行的元数据（commit SHA、harness 版本、镜像 ID、seed、prompt 哈希）都被记录，未来可以回答"为什么 6 月那版分数高 5 分"。

一个工业化 Harness 必须具备的六大能力

参考 Harbor 的设计（也来自 evaluation-first 博客）：

能力	为什么重要
沙箱隔离	任务之间互不污染，Agent 可随意执行命令
确定性	同一 seed + 版本跑出同样结果
并行调度	1000 tasks 串行跑要一周，并行才能迭代快
轨迹采集	直接导出做 SFT/RL
结构化日志	cost、latency、API 失败率一目了然
失败重试	区分环境故障和 Agent 真正失败

5.2 Claude Code 的评估体系：EDD 原则

Eval-Driven Development

Claude Code 的 Eval Harness 实现了 Eval-Driven Development（EDD） 原则，把 evals 视为"AI 开发的单元测试"。核心理念：

先定义期望行为，再实现：在编码之前定义成功标准
持续运行 evals：开发过程中持续跟踪回归
pass@k 指标：pass@1（首次尝试成功率）、pass@3（三次内成功），典型目标 pass@3 > 90%
三级评分器体系：
- 代码评分器：确定性检查（grep、测试通过、构建成功）
- 模型评分器：LLM 评估开放式输出，1-5 分制
- 人工评分器：安全相关变更的强制审查

EDD 的心智模型转换（来自 evaluation-first 博客）：

传统 Prompt 开发	EDD 开发
改动后靠"例子看起来对"	改动后看 Benchmark 总分 + 分桶 + 置信区间
"这个改动挺好的"	"子集 A +3.1，子集 B -0.4，总 +1.2，95% CI 不含 0，接受"
靠直觉挑 case	靠消融实验找真正起作用的组件
经验存在人脑子里	经验存在 Benchmark 历史记录里

第三方工具链

coding-agent-evals：通过 claude -p 进行 headless 运行，在 fixture repository 中对六个维度自动评分
curiocity：通过真实 PTY 驱动 Claude Code 和 Codex CLI，读取 CLI 原生 on-disk transcript 作为 source of truth，并 gate CI

5.3 Codex 的评估实践

独立基准平台

Codex 的评估聚焦于独立基准平台（vals.ai）上的表现。2026 年的数据（以项目博客为参考）：

GPT-5.6 Sol 在 Terminal-Bench 2.1 上达到 85.8%
SWE-bench Verified 上约 49%-74%（因任务类型而异）
每 DeepSWE 任务成本 $8.39

任务级别的错误分析

更有价值的是任务级别分析揭示的规律：

Codex 在 chore 类任务上 PR 接受率达 88.6%
但在 test 类任务上降至 59.6%
且集中了 78% 的 git 错误和 79% 的依赖错误

这个分析的启示：整体分数掩盖了任务类型的巨大差异。 如果你的 Agent 主要做 test 类任务，看"整体 85%"没有意义——你应该看"test 类 59.6%"并针对 git/依赖错误做专项优化。（呼应第 2 章的分桶分析。）

5.4 Google ADK 的评估框架

User Simulation：用 LLM 模拟用户

ADK 的评估框架围绕两个核心创新构建。第一个是 User Simulation——用 LLM 驱动的用户提示生成器替代硬编码测试脚本：

开发者定义 ConversationScenario（starting_prompt + conversation_plan）
模拟器动态生成多轮对话直至目标达成
这使测试对 Agent 的对话风格变化具有鲁棒性

为什么需要模拟用户？因为真实用户对话是开放的——用户下一轮说什么取决于 Agent 上一轮答了什么。硬编码脚本覆盖不了这种开放性（呼应第 2 章多轮对话难点三）。

Golden Path 与轨迹评估

第二个创新是 Golden Path 与轨迹评估：

捕获 golden-path 会话（golden sessions）
配置工具轨迹（tool_trajectory_avg_score）和响应相似度（response_match_score）指标
通过 UI 或 CLI 运行评估

ADK 的评估指标体系包括：tool_trajectory_avg_score（工具调用序列精确匹配）和 response_match_score（响应相似度）。（详见第 2 章 2.3。）

5.5 RAGAS：无参考评估框架

RAGAS 是什么

RAGAS 是面向 RAG 系统的自动化评估框架，已与 MLflow 集成，其指标可作为 scorer 使用。它的核心指标：

指标	评估内容
context_precision	检索到的相关项目是否排名靠前
context_recall	基于标注答案和检索上下文估计 TP/FN
faithfulness	生成响应是否基于提供的上下文（抗幻觉）
answer_relevancy	答案与问题的相关性
answer_correctness	事实正确性（事实性 0.75 + 语义相似度 0.25 加权组合）

RAGAS 的适用边界

RAGAS 适用于 RAG 系统的比较研究——提供快速可靠的相对性能评估（A 方案 vs B 方案哪个好）。但绝对分数存在局限：它的指标依赖 LLM 估计，绝对数值不宜作为"合格线"。

一个务实的用法：用 RAGAS 做日常迭代的相对对比，用人工标注的黄金集（第 8 章）做最终的绝对门禁。

5.6 可观测性驱动的评估平台：Opik 与同类平台

评估与可观测性正在合并

一个明显的行业趋势：评估与可观测性正在合并成同一件事。 传统上，"观测"回答"Agent 在生产环境跑了什么"，"评估"回答"Agent 表现好不好"。现在它们在同一套平台里完成——观测平台长出了评估能力，评估工具长出了追踪能力。

Opik（comet-ml/opik，Apache-2.0，可自托管）是这一趋势的代表：

Agent tracing：@track 装饰器记录函数调用，构建多步 Agent 与工具调用的完整 trace tree；通过 OpenTelemetry 支持 Java/Ruby/.NET 等其他语言
评估一体化：dataset 管理 → experiment 跑批 → LLM-as-judge 评分 → 在线评估规则（online evaluation rules）在 production trace 上持续打分
内置判官指标：Hallucination、Answer Relevance、Context Precision、moderation（内容审核）等开箱即用，也支持自定义 metric
CI 集成：PyTest 集成让"每次 commit 都测 LLM 管线"成为可能
生态集成：LangChain/LangGraph/LlamaIndex/CrewAI/AutoGen/DSPy/RAGAS 等 60+ 框架
MCP server：Claude Code、Cursor、Codex 等编码 Agent 可直接在对话中读取 trace、评分输出、运行评估
Agent Optimizer SDK 与 Guardrails：把评估信号接回优化与护栏

平台	定位	关键差异
Opik	开源可自托管	Apache-2.0、60+ 框架集成、内置 RAG 判官指标、PyTest CI
LangSmith	LangChain 生态观测+评估	eval 深度绑定 LangChain/LangGraph、在线评估器、prompt 管理
Langfuse	开源 LLM 可观测	追踪 + prompt 管理 + eval、低成本自托管、多框架 SDK
Arize Phoenix	开源 AI 可观测/LLM eval	OpenInference 标准、RAG 评估、嵌入可视化、数据集/实验管理
MLflow Evaluations	通用 ML 平台评估	与 MLflow 实验跟踪打通、RAGAS/metric 插件、统一模型生命周期
coze-loop（字节 Coze）	Agent 优化平台	观测 + 评估 + 迭代一体化，"评估驱动进化"产品化闭环
traccia-py	OTel 原生 SDK	OpenTelemetry 原生，tracing/eval/debug/治理一体

选型要点（来自 Langfuse vs LangSmith 博客）

数据不能出内网（金融/医疗/政务）→ Langfuse 自托管（MIT 核心），Docker Compose 半小时起一套
技术栈就是 LangChain/LangGraph → LangSmith，trace 与 graph 状态原生映射、Studio 单步调试
要长期留存证据链 → Langfuse 云端 Pro 保留 3 年、自托管完全自定；LangSmith 基础 trace 只留 14 天（延长要加钱）
成本曲线要可预测 → Langfuse 按 unit 计费；LangSmith 按 trace + LCU + LSU 组合计价，越用越难预估

5.7 HuggingFace 评估工具链

HF 的 Leaderboard & Evals 团队把"评测开源模型"做成了一整套工具链：

lighteval：LLM 评估工具包，1000+ 任务（MMLU-Pro、GPQA、GSM8K、MATH、AIME、LiveCodeBench 等），多后端（已服务中的模型 / 内存中加载的模型），逐样本保存、可复现
evaluate：通用模型/数据集评估库，与 datasets 无缝衔接
evaluation-guidebook：Open LLM Leaderboard 团队官方评估指南
community-evals / model-evaluator：社区评测工具与 Hub 模型一键评测

为什么对本书重要：当你要评估自己的 Agent 时，不需要从零搭评测栈——用 lighteval 固定基准与 metric，用 Open Benchmark Index 检索任务，用 HF Hub 托管评测数据与结果，把"评测"本身变成可复现、可版本化的资产。

5.8 开源评估框架速览：从"平台"到"代码"

观测平台（Opik 等）解决"跑在哪、怎么看"，评估框架解决"评估逻辑怎么写"。二者互补。

框架对比

框架	定位	关键能力
Inspect AI（UK AISI）	官方级评测框架	solver + scorer + attack 三件套，Python 定义评估，内置工具调用与 agentic 轨迹评分
promptfoo	配置驱动评测	YAML 定义用例 + 判官 + 阈值，CLI/CI 集成，红队与回归一体
DeepEval	Python 评测库	单测风格断言（assert_test）、RAG/Agent 指标、Pytest 集成
OpenAI Evals	官方评测框架	registry 化评测集、模型逐题评分、可复现运行
RAGAS	RAG 专项	无参考评估，指标丰富（见 5.5）
rogue	Agent 专用评估器	多轮工具调用轨迹评估 + 红队测试，填补 DeepEval 侧重单轮输出的空白
workshop（raindrop-ai）	自我评估	让 coding agent 具备"编写并运行 agent evals"的能力
NVIDIA SkillSpector	技能安全扫描	安装前扫描 PII、Unicode 走私、脚本质量、许可证与安全隐患

skill-creator 的三维评估

Claude Code 官方 skill-creator 内建了 Skill 评估的三维体系：

触发准确率（Trigger Accuracy）：该触发时触发（Recall）＋不该触发时不误触（Precision）
输出质量（Output Quality）：触发后输出是否正确、符合预期
效率指标（Efficiency Metrics）：相对无 Skill 基线，是否更省 token、更快

这是 Skill 评估的最小可行框架，也是第 8 章评分器策略在技能场景的具体化。

最小可运行模式

各种评估框架共享同一个骨架：

# 伪代码：LLM-as-judge + 自定义打分器 + 轨迹级判定
from evals import evaluate, judge

cases = [{"input": q, "expected_tool": "search", "reference": ref} for q in queries]

def my_scorer(agent_trace, reference):
    if not any(call.name == "search" for call in agent_trace.tools):
        return {"score": 0, "reason": "missing required tool call"}
    return judge.llm_score(agent_trace.final_answer, reference, rubric=scale_1to5)

report = evaluate(cases, run=my_agent, scorers=[my_scorer])

5.9 长上下文与记忆评估

Agent 的持久记忆与长上下文是 2025-2026 热点，评估维度独立于普通问答：

长上下文：RULER（合成压力测试，定位"lost in the middle"）、LongBench v2、LongMemEval
记忆：LoCoMo（长对话记忆）、HaluMem（首个 Agent 记忆幻觉评估基准）
实践：Mem0 / Letta 等记忆框架的评测需同时看"回忆正确率"与"记忆污染率"

记忆评估的"罗生门"警示

本项目博客 Agent Memory 哪家强？8 家横评与 benchmark 罗生门（2026-09-07）指出了一个重要问题：8 家 Agent memory 方案的 benchmark 分数互相之间没有可比性——因为各家用不同的协议、不同的测试集、不同的判官。同一领域的不同基准经常给出矛盾排名。读记忆评估结果时，必须先确认协议是否一致。

框架选型速查

场景	推荐起点	备选
代码 Agent（Claude Code/Codex）评估	Harbor	ECC Eval Harness / coding-agent-evals
多轮对话模拟与轨迹评估	Google ADK	自建 ConversationScenario + LLM judge
RAG 系统评估	RAGAS	Opik 内置判官指标
通用 Agent 观测 + 评估 + CI	Opik	Langfuse / LangSmith
单模型/开源模型对比	lighteval + Open LLM Leaderboard	evaluate
安全评估与红队	Inspect AI	Garak / AgentDojo

本章小结

Harbor 提供"Dataset × Agent × Model × Environment"四层解耦的标准化 harness
Claude Code 的 EDD 把 evals 变成"AI 开发的单元测试"，先定义成功标准再实现
Codex 的任务级分析揭示整体分数掩盖任务类型差异
ADK 用 User Simulation + Golden Path 解决多轮对话评估的开放性问题
RAGAS 适合 RAG 的相对比较，绝对分数有局限
Opik/LangSmith/Langfuse 等把观测与评估合并成同一件事
HuggingFace 工具链（lighteval/evaluate）把评测变成可复现资产
开源评估框架（Inspect/promptfoo/DeepEval/rogue）解决"评估逻辑怎么写"

参考资料

官方文档

Harbor — Agent 评估通用运行时；Terminal-Bench 2.0 官方文档（tbench.ai）
Claude Code Eval Harness SKILL.md（ECC 项目）— EDD 原则、pass@k、三级评分器
Google ADK Evaluation 文档（adk.dev）— User Simulation、golden path、轨迹评估
RAGAS — 无参考评估框架；Evaluating Using Your Test Set
Opik — Agent 观测与评测一体平台
lighteval / evaluate / evaluation-guidebook — HF 评估工具链

GitHub 仓库

博客与文章

基于 Evaluation 的 AI Agent 开发实践全景指南（本项目博客 2026-08-28）— Harness 六大能力、度量体系
Harbor Framework 深度拆解：Agent 评估的通用运行时（本项目博客 2026-08-27）
Opik：Comet 开源的 LLM 可观测性与评测平台（本项目博客 2026-09-20）
Langfuse 和 LangSmith：LLM 可观测性两大平台怎么选（本项目博客 2026-09-08）
Skill 写好了怎么测？Claude Code 官方 skill-creator 评估全拆解（本项目博客 2026-05-28）
Agent Memory 哪家强？8 家横评与 benchmark 罗生门（本项目博客 2026-09-07）
NVIDIA 开源 SkillEvaluator：给 Agent Skill 称体重（本项目博客 2026-08-24）

第 5 章：Agent 与 Framework 方法解析

第 5 章：Agent 与 Framework 方法解析

本章核心

5.1 Harbor：Agent 评估的标准化 Harness

Harbor 是什么

四大核心能力

为什么 Harbor 的设计值得学习

一个工业化 Harness 必须具备的六大能力

5.2 Claude Code 的评估体系：EDD 原则

Eval-Driven Development

第三方工具链

5.3 Codex 的评估实践

独立基准平台

任务级别的错误分析

5.4 Google ADK 的评估框架

User Simulation：用 LLM 模拟用户

Golden Path 与轨迹评估

5.5 RAGAS：无参考评估框架

RAGAS 是什么

RAGAS 的适用边界

5.6 可观测性驱动的评估平台：Opik 与同类平台

评估与可观测性正在合并

同类平台横向对比

选型要点（来自 Langfuse vs LangSmith 博客）

5.7 HuggingFace 评估工具链

5.8 开源评估框架速览：从"平台"到"代码"

框架对比

skill-creator 的三维评估

最小可运行模式

5.9 长上下文与记忆评估

记忆评估的"罗生门"警示

框架选型速查

本章小结

参考资料

📑 Agent Evaluation and Evolving: All in One