eval

eval skill 概览

eval 在 AgentHub 会话中做什么

eval 是一个用于给已完成 agent 结果排序的 AgentHub skill。它面向 /hub:eval 命令：多个 agent 已经围绕同一个任务完成了工作，你需要打分、比较，或选出最终赢家。eval skill 支持在已配置 eval command 时进行基于指标的评估；在没有可用指标时使用 LLM judge 评估；当客观分数和代码判断都重要时，也支持混合式决策。

适合的用户和任务

eval skill 最适合采用 AgentHub 风格多 agent 工作流的开发者：一个任务，多个 agent branch 或 worktree，然后进入最终对比环节。当你想稳定回答这类问题时，它很有帮助： “哪个 agent 做出了最快的实现？”、“哪个 patch 最适合安全合并？”、“哪个结果最符合原始任务？” 如果你想把它当作独立的 benchmark 框架，它就没那么合适，因为它默认依赖 AgentHub 的会话结构、agent result posts、branches 和 diffs。

eval 与普通 prompt 的区别

普通 prompt 也可以让 LLM 比较多个输出，但 eval 提供的是一条更具体的评估路径：有可用 metric command 时，对每个 agent 运行指标命令；使用 judge mode 时，则检查每个 agent 的 diff 和 result post。关键差异在于，这个 skill 会把 assistant 的判断锚定在已完成的 AgentHub artifacts 上，而不是自由发挥式的意见。这能减少猜测，也让排序结果更容易审计。

采用前需要重点确认

在安装或依赖 eval 之前，先确认你的工作流会把 agent 结果保存到预期的 AgentHub 位置，并且 agent branches 或 worktrees 仍然可用。Metric mode 还依赖可正常运行的 evaluation command、metric name，以及方向设置，例如 lower-is-better 的 latency，或 higher-is-better 的 score。这个 skill 的仓库路径中只有 SKILL.md，因此大多数行为由命令说明定义，而不是由 skill 目录里的额外 helper files 提供。

如何使用 eval skill

eval 安装与仓库检查

使用你常用的 skill installer 从 GitHub skill repository 安装，例如：

npx skills add alirezarezvani/claude-skills --skill eval

安装后，先阅读 engineering/agenthub/skills/eval/SKILL.md。这个 skill 目录下没有本地 rules/、resources/、references/ 或 scripts/ 文件夹，所以 SKILL.md 是事实来源。注意，skill 文本中提到 metric mode 会用到 scripts/result_ranker.py；在依赖基于 metric 的排序之前，需要确认你的更完整 AgentHub 环境是否提供了这个脚本，或等价的 evaluation runner。

基本 eval 使用命令

在 agents 完成一次 session 后使用该命令：

/hub:eval
/hub:eval 20260317-143022
/hub:eval --judge

/hub:eval 会评估最新 session。传入 session ID 可以指定某一次运行。--judge 会强制使用 LLM judge mode，适合 metric command 缺失、不可靠，或指标过窄、无法覆盖正确性判断的情况。

让 eval 效果更好的输入

对于 metric mode，需要提供或配置：session ID、eval command、metric label 和 direction。一个更好的请求应该足够具体：

“Run /hub:eval 20260317-143022 using the configured benchmark. Rank by latency_ms, lower is better, and call out any agent whose result fails tests.”

对于 LLM judge mode，需要确保 assistant 可以访问 base branch、agent branches、git diffs，以及 result posts，例如 .agenthub/board/results/agent-1-result.md。更强的 prompt 会包含任务目标和优先级顺序：

“Use /hub:eval --judge for the latest session. Prioritize correctness first, then minimal risk, then simplicity. Treat changed public APIs as risky unless justified in the result post.”

获得可靠排序的实用工作流

只在所有 agents 都已提交结果，并且它们的 branches 足够干净、可以进行 diff 后再运行 eval。如果任务有客观分数，例如 runtime、test count、accuracy、size 或 benchmark output，优先从 metric mode 开始。对于设计、重构、bug fix，或指标容易被“刷分”的任务，使用 LLM judge mode。对于重要合并，要求 eval 不只给出赢家，还要报告主要风险、来自 diffs 的证据，以及任何用于打破平局的假设。

eval skill 常见问题

eval 是用于 Model Evaluation，还是用于 agent 结果排序？

这个 eval skill 主要用于 AgentHub agent 结果排序，而不是通用的 Model Evaluation 套件。它可以评估模型生成的工作，但比较单位是某个 agent 已完成的 session result：它的 branch、diff、result note，以及可选的在其 worktree 中运行的 metric command。

什么时候该用 metric mode，而不是 judge mode？

当成功标准可以稳定测量时，使用 metric mode：tests passed、benchmark score、latency、memory、accuracy、bundle size，或其他数值输出。当真正的问题是 patch 是否正确、可维护、且安全时，使用 judge mode。如果指标只覆盖了目标的一部分，可以要求混合式评估：先按 metric 排序，再从 diffs 中标出正确性或回归风险。

新手可以使用 eval skill 吗？

如果新手已经理解 AgentHub session 的概念，就可以使用 eval。命令本身很简单，但评估质量取决于 repository state：branches、worktrees、result posts，以及已配置的 eval commands。如果这些 artifacts 缺失，新手可能会看到令人困惑或不完整的排序结果。

什么时候 eval 不是合适工具？

不要在 agents 尚未完成、只有一个结果，或 assistant 无法访问 diffs 和 result files 时使用 eval。对于大范围 model benchmarking、prompt leaderboard 创建，或离线 dataset evaluation，除非你改造外围工作流，否则它也并不合适。这些场景更适合使用专门的 evaluation harness。

如何改进 eval skill

用更清晰的标准提升 eval 结果

提升质量最明显的方法，是给出精确的排序策略。告诉 eval 哪些因素最重要：correctness、passing tests、performance、simplicity、security、compatibility，或 minimal code churn。避免“pick the best”这类模糊请求。更推荐这样写：“Rank agents by correctness first; if tied, prefer fewer changed files and no new dependencies; mention any untested assumptions.”

避免常见的 eval 失败模式

常见失败包括：根据误导性指标排序、忽略失败的边界情况、比较过期 branches，或过度看重较小 diff 但它并没有解决任务。为避免这些问题，评估前先确认 base branch、session ID、metric direction 和 task objective。对于 judge mode，要求给出有证据支撑的排序，并明确关联到具体 diffs 和 result posts。

在第一次排序后继续迭代

把第一次 eval 输出当作决策草稿。如果赢家让人意外，可以围绕有争议的标准要求第二轮检查：“Re-evaluate only the top two agents for regression risk,” 或 “Explain whether agent-2’s faster metric comes from skipping required behavior.” 这样不用重新跑完整的 agent session，也能保持 eval 工作流的实用性。

针对自己的工作流增强这个 skill

如果你维护的是一套 AgentHub 环境，可以通过标准化 result post format、统一 metric 命名，并让 eval command 具备确定性来改进 eval。补充项目专属规则：什么算 correctness、哪些 tests 必须通过、哪些风险会阻止 merge。这个 skill 本身很精简，因此日常使用中 eval 是否可信，很大程度取决于你围绕 sessions、branches 和 metrics 建立的本地约定。