跳转到主要内容
Recipes 把 benchmark task metadata 和 provider-specific environment settings 连接起来。它们在默认 execution plan 构造之后、environment 启动之前运行。 当重型 benchmark 需要 task image、snapshot、workspace layout、resource hints 或 compatibility checks 时，应该使用 recipe，而不是把这些逻辑硬编码在 benchmark 或 CLI 命令里。

​
Recipes 负责什么

Image selection

读取 public Docker image metadata 或 provider snapshot，并设置 provider params。

Workspace layout

对齐 /testbed、/workspace、/root 等 benchmark workspace。

Resource hints

合并 task CPU、memory、disk、GPU 或 provider resources，并保留用户显式 override。

Compatibility failure

当缺少必须的 image、snapshot 或 task metadata 时，在 sandbox 启动前失败。
Recipes 不执行命令、不创建 sandbox、不评分、不调用模型 API。

​
核心接口

Method职责
matches(req, task, plan)判断 recipe 是否适用于当前 benchmark、provider、task 和 plan。
apply(plan, req, task)返回新的 ExecutionPlan，包含 provider-aware overrides。
Recipe 通过 id 注册。runtime 可以自动应用默认 recipe，也可以通过 --recipe 限定使用的 recipe。

​
外部 Recipe Package

受信任的私有 recipe 可以只对当前 run 注入，不需要放进 src/agentcompass： 
company_recipes/
  __init__.py
  swe_recipe.py

# company_recipes/__init__.py
from .swe_recipe import CompanySWERecipe

RECIPE_CLASSES = (CompanySWERecipe,)
导出的类必须是具有稳定 id、可零参数构造的具体 BaseRecipe 子类。外部类不能使用全局 @RECIPES.register()；AgentCompass 会把它们加入当前 run 的局部 registry，避免后续 SDK run 意外看到这些 recipe。 
agentcompass run <benchmark> <harness> <model> \
  --recipe-dir ./company_recipes \
  --recipe company_swe_recipe
--recipe-dir 可以重复传入。Python SDK 使用 recipe_dirs=["./company_recipes"]，配置文件使用 runtime.recipe_dirs。目录相对启动工作目录解析。执行顺序为内置 recipe、外部目录参数顺序、各目录的 RECIPE_CLASSES 声明顺序；重复 recipe id 会在创建 run 输出目录前报错。 外部 package 会作为受信任 Python 代码在 AgentCompass 进程内执行。同一规范化路径在进程生命周期内缓存，不支持热重载，并且每个 worker 都必须能访问该路径。读取已有 run 的 summary 或离线 analysis 不会加载其中记录的外部 package。

​
示例：Modal SWE-bench Verified

export MODAL_TOKEN_ID="..."
export MODAL_TOKEN_SECRET="..."

agentcompass run \
  swebench_verified \
  mini_swe_agent \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["astropy__astropy-12907"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
swebench_verified_modal_prebaked recipe 可以从 SWE-bench metadata 或 instance id 推导 image，并把 workspace root 设置为 /testbed。

​
示例：Daytona Terminal-Bench

export DAYTONA_API_KEY="..."

agentcompass run \
  terminal_bench_2 \
  terminus2 \
  your-model \
  --env <env-provider> \
  --benchmark-params '{"sample_ids":["overfull-hbox"]}' \
  --model-base-url "$MODEL_BASE_URL" \
  --model-api-key "$MODEL_API_KEY"
Terminal-Bench Daytona recipe 读取 task.environment.docker_image，设置 environment image，并使用 /root 作为 default workspace root。

​
用户 Override

Override效果
--env-params '{"image":"..."}'在 recipe 支持 registry image 时强制使用某个 image。
--env-params '{"named_image":"..."}'在支持时使用 Modal named image。
--env-params '{"snapshot":"..."}'在支持时使用 provider snapshot，而不是推导 image。
--recipe <recipe_id>只启用显式指定的 recipe id。
--recipe-dir <package_dir>为当前 run 加载受信任的外部 recipe package；可重复。
不要仅仅因为 benchmark 是 remote 就手动传 image。如果 recipe 可以推导 task image，短命令更可复现。

​
当前 Recipe 家族

Benchmark familyProviders
SWE-bench Verifiedhost_process, docker, modal, daytona
SWE-bench Multilingual / Prodocker, modal, daytona
Terminal-Bench 2modal, daytona
PinchBench / SkillsBench / GDPvalprovider-specific cluster 或 gateway recipes

​
开发者说明

当兼容性规则由 benchmark、task metadata 和 provider 的组合决定时，新增 recipe。如果设置是 provider-wide，放在 environment config；如果设置影响 scoring，放在 benchmark。

​
相关页面