> ## 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 围绕直接评测运行时组织代码。架构上最重要的规则是：组件依赖 runtime 契约，而不是依赖彼此的具体实现。

Runtime 把 `benchmark`、`harness`、`model` 和 `environment` 作为 `RunRequest` 中的独立 spec。Benchmark 可以准备和评分任务，而不需要知道使用哪一个 sandbox provider。Harness 可以执行 agent loop，而不拥有 benchmark scoring。Environment 只提供执行和文件 primitive，不需要知道任务来自 SWE-bench、Terminal-Bench、GUI grounding 还是 research benchmark。

```text theme={null}
CLI / Python SDK
  -> RunRequest
  -> UnifiedEvaluationRuntime
  -> Benchmark / Harness / Environment / Recipe
  -> FileManager / ResultProcessor / ProgressReporter
```

## 主要模块

* `agentcompass.cli`：命令行入口。
* `agentcompass.launcher`：Python SDK 入口和 request 构造。
* `agentcompass.runtime.models`：request、plan、task、result 和 progress dataclass。
* `agentcompass.runtime.runner`：核心 orchestration loop。
* `agentcompass.runtime.registry`：benchmark、harness、environment、recipe、analyzer 注册表。
* `agentcompass.benchmarks`：数据加载和评分。
* `agentcompass.harnesses`：agent/model 执行。
* `agentcompass.environments`：执行和文件 primitive。
* `agentcompass.recipes`：provider-aware plan rewrite。
* `agentcompass.analyzers`：后置 analysis 和 badcase 诊断。

## 组合模型

```text theme={null}
RunRequest
  benchmark: BenchmarkSpec
  harness: HarnessSpec
  environment: EnvironmentSpec
  model: ModelSpec
```

这个结构是主要扩展点。新增 benchmark 不应该要求新增 harness；新增 environment provider 不应该要求重写 benchmark；新增 model endpoint 不应该改变任务加载和 scoring。兼容性检查发生在边界上，例如 `BaseHarness.supports(...)` 和 recipe matching。

## 边界原则

* Benchmark 拥有 task data、preparation、scoring 和 aggregation。
* Harness 拥有 agent execution，并返回标准化的 `RunResult`。
* Environment 暴露 `EnvironmentSession` primitive，例如 `exec`、upload/download、text I/O 和可选 endpoint。
* Model 通过 `ModelSpec` 传递；harness 决定如何调用 endpoint 或把 credential 传给 agent CLI。
* Recipe 在 sandbox 启动前适配 benchmark/provider 组合，尤其是 image、workspace root、snapshot 和 resource hint。
* Results 和 analyzers 位于 execution 下游，因此可以在不重跑 benchmark 的情况下重新做诊断。