> ## Documentation Index
> Fetch the complete documentation index at: https://agent-compass.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 代码实现

实现 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`。将官方逐 sample 的 baseline、run 和 evaluation 限制分别放入 `TaskSpec.baseline_network_policy`、`TaskSpec.run_network_policy` 和 `TaskSpec.evaluation_network_policy`，并将逐 sample 的 evaluation sandbox 选择放入 `TaskSpec.evaluation_environment_mode`；不要在 BenchmarkPlan 或不透明 metadata 中重复保存。不要调用 provider SDK，也不要在模块导入时下载数据。

## 3. 构建 provider 中立计划

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

有意选择评测 Environment 模式：

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

只有所有 sample 共用同一默认值时，才在 Benchmark class 设置 `evaluation_environment_mode`。内部 Benchmark 和 task 字段只接受 `none`、`reuse` 或 `fresh`；上游专属词汇应在 loader 边界转换，例如将 Harbor verifier 的 `separate` 映射为 `fresh`。作用于整次运行的 `--env-params` 覆盖优先于 sample，sample 又优先于 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`、保持确定性，并遵循：

```text theme={"system"}
explicit provider-native selector
  > explicit environment image
  > task metadata
  > recipe fallback
```

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

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

## 8. 显式解析网络阶段

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

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

Planner 按 `Environment 覆盖 > TaskSpec sample > Recipe > runtime 默认值` 分别解析每个阶段。包括 `--env-params` 在内的 Environment 值作用于整次运行；上游数据会逐 sample 变化时，Benchmark loader 应使用 TaskSpec 字段。每次 attempt 的 resolved execution plan 会保存最终策略及其来源。

## 9. 注册并检查组件

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

```bash theme={"system"}
uv run agentcompass list benchmark
uv run agentcompass config docs benchmark <benchmark-id>
```

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