代码实现

实现 Benchmark 的数据集、任务、评测器、依赖、Recipe 和网络契约。

在保留官方任务与评分语义的前提下，实现最小但完整的 Benchmark 路径。

​

1. 记录上游契约

设计适配器前记录以下输入：

领域	必要证据
数据集	发布版本、修订版本、数据划分、任务数量、许可证、访问权限和缓存要求
评测器	源代码版本、补丁或答案格式、指标、超时和失败语义
官方运行	model、Harness 版本、提示词、推理设置、重试和每个任务的尝试数
Environment	任务镜像、工作区、CPU、内存、存储、GPU 和网络行为
输出	官方聚合指标、类别指标、完成分母和可用轨迹

绝不能使用项目后续版本的实现、未来测试、参考补丁、隐藏答案，或在任务执行时不受限制地联网获取解答。即使 model 自行发现这些内容，也会污染评测。

​

2. 定义任务与配置契约

在 src/agentcompass/benchmarks/ 下创建实现。Benchmark 通常定义：

• 负责 Benchmark 负责的公共参数的 RuntimeBenchmarkConfig 子类。
• 保存每个任务准备和评测器状态的类型化 BenchmarkPlan。
• 注册到 BENCHMARKS 的 BaseBenchmark 子类。
• 多版本存在差异时的小型版本特定适配器。

复用 sample_ids、k、avgk、aggregation_mode 和 category_hierarchy 等通用 Benchmark 控制项，不要重新定义语义略有不同的重复字段。在启动 Environment 前验证版本、别名、版本、数据划分和未知任务 ID。

load_tasks() 必须返回确定性的 TaskSpec，并使用稳定公开任务 ID。将任务镜像、资源提示、工作区元数据、评测器输入和上游标识符放入 TaskSpec.metadata。不要调用 provider SDK，也不要在模块导入时下载数据。

​

3. 构建 provider 中立计划

build_plan() 只负责 Benchmark 负责的任务和评测器状态。保持 provider 中立，且不要修改RunRequest；runtime 与 Recipe 会在之后把它组合为 ExecutionPlan。

有意选择评测 Environment 模式：

模式	适用场景
none	评测在 AgentCompass 进程中运行，不需要任务 sandbox
reuse	评测必须在 agent 执行后检查现有任务 Environment
fresh	官方契约要求在新建 Environment 中隔离验证

如果不同版本需要不同模式，应根据 Benchmark 配置显式解析，而不是复制整套实现。

​

4. 只准备 Harness 契约

prepare_task() 把 TaskSpec 转换为 PreparedTask。只暴露兼容 Harness 需要的信息：

• TaskInput.prompt，以及可选系统提示词或消息。
• 文件、媒体、工具和解析后工作区。
• TaskOutput 答案或所需输出文件。
• 执行和复现所需的稳定元数据。

不要把仅用于评分信息放入提示词，也不要把 Harness 专属字段放进 Benchmark 元数据。准备必须能够在重试和恢复的运行中安全重复。

当任务 Environment 关闭前必须复制补丁或输出时，使用 collect_artifacts()；全新验证尤其如此。不要把产物收集与评分混在一起。

​

5. 保留官方评测语义

尽可能复用并固定官方评测器/验证器版本，让兼容性包装层保持精简。评测器必须区分：

• agent 失败或超时。
• Environment 或 Harness 失败。
• 产物收集失败。
• 验证器崩溃或超时。
• 合法评测失败或零分。
• 验证成功。

保留官方超时和状态规则。agent 超过官方时间预算后补丁仍可能通过验证器；如果 Benchmark 将超时定义为失败，应保存验证器证据，但应用官方最终规则。

只有上游数据集使用相对任务预算时，才优先提供 Benchmark 负责的超时倍数。如果同时存在共享验证器超时覆盖，必须记录并测试两者的优先级，避免两个控制项含义无法区分。

​

6. 把依赖放在正确位置

依赖类型	放置位置
框架必需或广泛共享	默认 pyproject.toml 依赖
Benchmark 专属驱动导入	具名可选依赖和 DependencySpec
Harness 专属 runtime	Harness 可选依赖或隔离 Harness 安装器
任务 runtime 或验证器	任务镜像、sandbox 准备或固定评测器 Environment
外部 CLI 或服务	文档化前置条件

自动依赖安装默认关闭。缺少可选导入时必须给出可执行的手动安装命令。不要在模块导入时安装，也不要通过降级通用框架软件包来满足专用集成。

​

7. 只在需要时添加 provider Recipe

Recipe 把任务元数据映射到 provider 设置。它们必须复制 ExecutionPlan、保持确定性，并遵循：

explicit provider-native selector
  > explicit environment image
  > task metadata
  > recipe fallback

根据任务元数据构建资源默认值，再逐字段覆盖用户显式 Environment 值。保留显式工作区、资源、超时、标签、凭证和网络设置。在移除互斥字段前先解析最终镜像或原生选择器。

Recipe 不得创建 sandbox、执行命令、调用 model 或评分。修改共享优先级行为时需要审计相邻 provider 和版本 Recipe。

​

8. 显式解析网络阶段

把准备、agent 执行和验证视为独立策略阶段。默认值遵循官方 Benchmark 行为，并通过 Environment 强制执行实施限制，绝不能依赖提示词指令。

可信 Harness 安装通常在准备阶段策略下完成，之后才应用更严格的运行阶段策略。如果用户显式限制准备，在缺少所需依赖时应清晰失败，不能静默开放网络。

​

9. 注册并检查组件

从 src/agentcompass/benchmarks/__init__.py 导出模块，并验证发现机制和生成的配置文档：

uv run agentcompass list benchmark
uv run agentcompass config docs benchmark <benchmark-id>

Benchmark 必须具有稳定 id 和非空 description。