概览

AgentCompass 运行时模块地图，以及各模块如何协作。

AgentCompass 围绕 direct evaluation runtime 组织代码，但更重要的设计选择是把评测组件解耦。一次 run 本质上是四个独立轴的组合：

Benchmark x Harness x Model x Environment

Benchmark 负责加载任务、准备任务材料和 scoring。Harness 负责 agent loop 或外部 agent framework 的执行。Model spec 负责 endpoint、protocol、credential 和 generation 参数。Environment 负责命令执行、文件操作、workspace 和可选 remote sandbox 生命周期。

Runtime 通过同一个 RunRequest，以及 PreparedTask、EnvironmentSession、ExecutionPlan、RunResult 等小型契约把它们连接起来。因此同一个 benchmark 可以评测不同 harness，同一个 harness 可以从本地环境迁移到 Modal 或 Daytona，同一个 model endpoint 也可以替换，而不需要改 benchmark 代码。

AgentCompass 的目标是自由组合，但现实约束会被显式表达。Harness 可以通过 supports(...) 拒绝不兼容的 environment/model 组合，recipe 可以在 sandbox 启动前适配 image、workspace 和 resource。

​

模块地图

Runtime

构造 RunRequest，加载组件，控制并发，发送 progress，并持久化产物。

Configuration

说明默认配置文件、覆盖顺序、作用域参数，以及如何避免把 secrets 写进共享配置。

Benchmarks

加载任务、准备 benchmark material、评分 harness 输出并聚合指标。

Harnesses

把模型、CLI agent 和外部 agent framework 适配到统一的 PreparedTask 契约。

Environments

为本地、容器、远程 sandbox 和集群 provider 暴露统一执行与文件接口。

Recipes

在 sandbox 启动前改写执行计划，处理 image、workspace 和 provider resource。

Models

保存每次 run 的 endpoint、protocol、API key 和采样参数。

Results

保存 per-task details、summary、progress、logs 和 analysis artifacts。

Analyzers

对已有 trajectory 做 latency、行为模式和 qualitative 后置分析。

​

一次 Run 的生命周期

CLI / Python API
  -> RunRequest
  -> benchmark.load_tasks()
  -> benchmark.select_tasks()
  -> planner builds ExecutionPlan
  -> recipes may rewrite plan
  -> environment.open()
  -> benchmark.prepare_task()
  -> harness.run_task()
  -> benchmark.evaluate()
  -> details + summary + progress + logs
  -> optional analyzers

​

设计原则

原则	含义
独立选择轴	benchmark、harness、model 和 environment 是 RunRequest 中的独立 spec，而不是被写死在一个 runner 里。
窄契约通信	模块通过 PreparedTask、EnvironmentSession、ExecutionPlan、RunResult 通信，不依赖彼此的私有实现。
Benchmark 拥有真相	Benchmark 拥有 dataset、task material、evaluation 和 aggregation；harness 不给自己评分。
Provider-neutral execution	Benchmark 和 harness 使用 environment primitive，不直接调用 Modal、Daytona、Docker 或集群 SDK。
Recipe 适配而不耦合	Recipe 在启动前解析 provider-specific 的 image、workspace、snapshot 和 resource，不把这些逻辑塞进 benchmark。
Durable artifacts	details/*.json、summary、log、progress event 和 analyzer output 保存足够信息，方便之后 debug 或重新 analysis。

​

这种解耦带来的能力

改动	保持稳定的部分
把 glm-5.2 换成另一个 OpenAI-compatible endpoint	Benchmark 任务、harness 逻辑、environment setup 和 scoring。
把 mini_swe_agent 从 Daytona 切到 Modal	Harness 行为和 SWE-bench scoring 保持不变，recipe 负责适配 image 和 workspace。
在 SWE-bench Verified 上比较多个 harness	Dataset loading、task metadata 和 pass/fail evaluation。
把 terminal benchmark 从本地迁移到 remote sandbox	Benchmark selection 和 harness contract 不变，只有 environment provider 改变执行面。
对已有结果新增 analyzer	原始执行产物可复用，analysis 是后置处理层。

​

按目标阅读

目标	建议入口
运行已有 benchmark	Runtime、Configuration、Models、Results
选择执行后端	Environments、Recipes
新增 benchmark	Benchmarks、Data Protocol
新增 agent adapter	Harnesses、Runtime Extensions
调试已有 run	Results、Analyzers

​

组合示例

下面这些例子展示同一种 runtime shape 如何覆盖不同评测方式。可复制的命令放在 Setup 和 cookbooks 中；这里重点说明模块边界。

GUI grounding，本地执行

screenspot + qwen3vl_gui + host_process：benchmark 拥有图片和评分逻辑，harness 适配 VLM-style interaction loop，environment 只需要本地命令和文件 primitive。

Agentic coding，远程 sandbox

swebench_verified + mini_swe_agent + modal 或 daytona：benchmark 提供仓库任务和 pass/fail evaluation，recipe 在 sandbox 启动前推导 image 和 workspace。

Terminal tasks，隔离 shell

terminal_bench_2 + terminus2 + daytona 或 modal：harness 驱动 terminal 行为，environment provider 为每个任务提供隔离文件系统和 shell。

Research 与 tool use，API-first

browsecomp + researchharness + host_process：benchmark 提供问题和 judge 逻辑，harness 处理 research workflow 和 model calls，不需要 benchmark-specific sandbox provider。

后续页面会解释每一层分别负责什么、默认值从哪里来，以及扩展时应该修改哪一层。