> ## 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.

# 概览

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

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

```text theme={null}
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 代码。

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

## 模块地图

<CardGroup cols={2}>
  <Card title="Runtime" icon="workflow" href="/zh/key_modules/runtime">
    构造 `RunRequest`，加载组件，控制并发，发送 progress，并持久化产物。
  </Card>

  <Card title="Configuration" icon="settings" href="/zh/key_modules/configuration">
    说明默认配置文件、覆盖顺序、作用域参数，以及如何避免把 secrets 写进共享配置。
  </Card>

  <Card title="Benchmarks" icon="gauge" href="/zh/key_modules/benchmarks">
    加载任务、准备 benchmark material、评分 harness 输出并聚合指标。
  </Card>

  <Card title="Harnesses" icon="bot" href="/zh/key_modules/harnesses">
    把模型、CLI agent 和外部 agent framework 适配到统一的 `PreparedTask` 契约。
  </Card>

  <Card title="Environments" icon="server" href="/zh/key_modules/environments">
    为本地、容器、远程 sandbox 和集群 provider 暴露统一执行与文件接口。
  </Card>

  <Card title="Recipes" icon="git-branch" href="/zh/key_modules/recipes">
    在 sandbox 启动前改写执行计划，处理 image、workspace 和 provider resource。
  </Card>

  <Card title="Models" icon="settings" href="/zh/key_modules/models">
    保存每次 run 的 endpoint、protocol、API key 和采样参数。
  </Card>

  <Card title="Results" icon="chart-no-axes-combined" href="/zh/key_modules/results">
    保存 per-task details、summary、progress、logs 和 analysis artifacts。
  </Card>

  <Card title="Analyzers" icon="scan-search" href="/zh/key_modules/analyzers">
    对已有 trajectory 做 latency、行为模式和 qualitative 后置分析。
  </Card>
</CardGroup>

## 一次 Run 的生命周期

```text theme={null}
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](/zh/key_modules/runtime)、[Configuration](/zh/key_modules/configuration)、[Models](/zh/key_modules/models)、[Results](/zh/key_modules/results) |
| 选择执行后端           | [Environments](/zh/key_modules/environments)、[Recipes](/zh/key_modules/recipes)                                                                       |
| 新增 benchmark     | [Benchmarks](/zh/key_modules/benchmarks)、[Data Protocol](/zh/developer/data_protocol)                                                                 |
| 新增 agent adapter | [Harnesses](/zh/key_modules/harnesses)、[Runtime Extensions](/zh/developer/runtime_extensions)                                                         |
| 调试已有 run         | [Results](/zh/key_modules/results)、[Analyzers](/zh/key_modules/analyzers)                                                                             |

## 组合示例

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

<CardGroup cols={2}>
  <Card title="GUI grounding，本地执行" icon="mouse-pointer-click">
    `screenspot` + `qwen3vl_gui` + `host_process`：benchmark 拥有图片和评分逻辑，harness 适配 VLM-style interaction loop，environment 只需要本地命令和文件 primitive。
  </Card>

  <Card title="Agentic coding，远程 sandbox" icon="code">
    `swebench_verified` + `mini_swe_agent` + `modal` 或 `daytona`：benchmark 提供仓库任务和 pass/fail evaluation，recipe 在 sandbox 启动前推导 image 和 workspace。
  </Card>

  <Card title="Terminal tasks，隔离 shell" icon="terminal">
    `terminal_bench_2` + `terminus2` + `daytona` 或 `modal`：harness 驱动 terminal 行为，environment provider 为每个任务提供隔离文件系统和 shell。
  </Card>

  <Card title="Research 与 tool use，API-first" icon="search">
    `browsecomp` + `researchharness` + `host_process`：benchmark 提供问题和 judge 逻辑，harness 处理 research workflow 和 model calls，不需要 benchmark-specific sandbox provider。
  </Card>
</CardGroup>

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