> ## 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 系统边界、runtime 契约、执行流和各组件变更的影响。

AgentCompass 是可组合的评测 runtime。修改代码前，应先在系统图中定位行为，并识别它生产和消费的契约，避免 Benchmark 专属要求泄漏到 Harness、Environment provider 或共享 runtime。

## 系统概览

CLI 与 Python SDK 最终进入同一个编排 runtime。`run` 包装一个 `RunRequest`；`launch` 将一组有序具名请求解析为一个 `Orchestration`。注册表解析请求的组件，规划器为每个任务创建 `ExecutionPlan`，共享调度器协调请求优先级、任务并发数、Environment、Benchmark、Harness、评测、结果和分析生命周期。

```mermaid theme={"system"}
flowchart TB
  subgraph interfaces["用户入口"]
    CLI["CLI"]
    SDK["Python SDK"]
    CONFIG["配置与环境变量"]
  end

  ORCHESTRATION["Orchestration<br/>有序请求 · 全局限制 · deadline"]
  REQUEST["RunRequest<br/>model · benchmark · harness · environment · execution · output"]

  subgraph resolution["解析与规划"]
    REGISTRY["组件注册表"]
    DEPENDENCY["可选依赖解析"]
    DATASET["Benchmark task 加载与选择"]
    PLANNER["Planner"]
    RECIPE["Recipes<br/>provider-aware plan adaptation"]
    PLAN["ExecutionPlan<br/>每个 task 一份 resolved plan"]
  end

  subgraph task["单 Task Runtime"]
    ENV["Environment provider<br/>open session"]
    PREPARE["Benchmark<br/>prepare task"]
    HARNESS["Harness<br/>start · run · close"]
    MODEL["Model endpoint"]
    COLLECT["Benchmark<br/>collect artifacts"]
    VERIFY["Benchmark<br/>evaluate / verify"]
    CLEANUP["Environment provider<br/>close session"]
  end

  subgraph outputs["持久化与可观测性"]
    RESULT["RunResult"]
    STORE["Details · progress · logs · summary"]
    ANALYZER["Analyzers"]
  end

  CLI --> ORCHESTRATION
  SDK --> ORCHESTRATION
  CONFIG --> ORCHESTRATION
  ORCHESTRATION --> REQUEST
  REQUEST --> REGISTRY
  REQUEST --> DEPENDENCY
  REGISTRY --> DATASET
  DATASET --> PLANNER
  RECIPE --> PLANNER
  PLANNER --> PLAN
  PLAN --> ENV
  ENV --> PREPARE
  PREPARE --> HARNESS
  MODEL <--> HARNESS
  HARNESS --> COLLECT
  COLLECT --> VERIFY
  VERIFY --> RESULT
  RESULT --> STORE
  RESULT --> ANALYZER
  VERIFY --> CLEANUP
```

图中展示常见的由 Harness 驱动的路径。`HarnessFreeBenchmark` 可以自己负责推理循环，但仍必须保留相同的任务、Environment、结果、评测和持久化契约。

## runtime 结构

runtime 围绕一组精简的类型化对象构建；它们是模块之间的稳定边界。

```text theme={"system"}
Orchestration
  ├─ global task concurrency, deadline, provider limits, and progress
  └─ ordered OrchestratedRun[]
       └─ RunRequest
            ├─ ModelSpec
            ├─ BenchmarkSpec
            ├─ HarnessSpec
            ├─ EnvironmentSpec
            ├─ ExecutionSpec
            └─ OutputSpec
                 │
                 ├─ load and select -> TaskSpec
                 ├─ plan            -> ExecutionPlan
                 ├─ prepare         -> PreparedTask
                 ├─ run             -> RunResult
                 └─ evaluate        -> normalized RunResult -> persisted artifacts
```

| 契约                   | 生产方                        | 主要消费方                                 | 变更影响                               |
| -------------------- | -------------------------- | ------------------------------------- | ---------------------------------- |
| `Orchestration`      | CLI/SDK 启动解析器              | 全局调度器、进度渲染器、runtime 初始化               | 跨请求优先级、并发、取消、失败隔离、CLI/SDK 一致性      |
| `RunRequest`         | CLI、Python SDK、配置加载器       | 注册表、规划器、runtime、所有组件                  | 公开配置、序列化、CLI/SDK 一致性、可复现性          |
| `TaskSpec`           | Benchmark 加载器              | 任务选择、规划器、Benchmark 准备、分析器             | 数据集标识、Recipe、重试、结果路径               |
| `ExecutionPlan`      | 规划器和 Recipe                | Environment、Benchmark、Harness、runtime | provider 设置、资源、网络阶段、评测 Environment |
| `PreparedTask`       | Benchmark                  | Harness 或无 Harness 推理循环               | 提示词、文件、媒体、工具、工作区、预期输出              |
| `EnvironmentSession` | Environment provider       | Benchmark 准备、Harness、验证器              | 所有 sandbox provider 间的命令与文件语义      |
| `RunResult`          | Harness，再由 Benchmark 评测器更新 | 持久化、指标、分析器                            | 状态语义、得分正确性、轨迹、摘要                   |

修改这些契约中的任何一个都是 runtime 变更，不是局部组件变更。应审计全部生产方和消费方、更新公开导出，并在已有结果产物依赖时保留序列化兼容性。

## 组件职责

| 组件          | 负责                                     | 不应负责                                  | 主要源码                             |
| ----------- | -------------------------------------- | ------------------------------------- | -------------------------------- |
| Model       | 端点标识、API 协议、凭证、推理参数                    | Benchmark 提示词、agent 生命周期、评分           | `ModelSpec` 和协议客户端               |
| Benchmark   | 数据集、稳定任务标识、准备、评分、聚合、评测器语义              | agent 循环、provider SDK、通用 sandbox 生命周期 | `src/agentcompass/benchmarks/`   |
| Harness     | agent 或 model 执行循环、Harness 准备、轨迹和用量规范化 | 数据集加载、Benchmark 得分、provider 镜像选择      | `src/agentcompass/harnesses/`    |
| Environment | 命令、文件、端点、sandbox 生命周期、资源、可强制网络策略       | Benchmark 规则、model 决策、得分解释            | `src/agentcompass/environments/` |
| Recipe      | 确定性的每个任务计划适配，用于 Benchmark/provider 兼容性 | 副作用、sandbox 创建、推理、评分                  | `src/agentcompass/recipes/`      |
| runtime     | 跨组件编排、并发、重试、网络阶段切换、清理、持久化              | Benchmark 专属捷径或 provider 专属业务规则       | `src/agentcompass/runtime/`      |
| 分析器         | 对标准化结果的后置解释                            | 改变权威 Benchmark 得分或执行结果                | `src/agentcompass/analyzers/`    |

使用职责判断代码应放在哪里。例如，数据集元数据中的任务镜像属于 Benchmark 契约；将该镜像映射到 Daytona 快照或 Modal 命名镜像属于 Recipe；创建和关闭 sandbox 属于 Environment provider。

## 执行生命周期

runtime 为每个选中任务创建计划，因为镜像、资源、工作区和验证器要求可能逐任务不同。

```mermaid theme={"system"}
sequenceDiagram
  participant R as Runtime
  participant B as Benchmark
  participant P as Planner and recipes
  participant E as Environment
  participant H as Harness
  participant V as Evaluator
  participant S as Result store

  R->>B: load_tasks and select_tasks
  loop each selected task, under concurrency limits
    R->>P: build ExecutionPlan
    R->>E: 在 baseline network policy 下 open
    R->>B: prepare_task
    R->>H: start_session
    R->>E: switch to run network policy
    R->>H: run_task
    R->>H: 在运行策略下 close_session
    R->>B: 在运行策略下 collect_artifacts
    alt reuse task environment
      R->>E: 直接切换到 evaluation 策略
      R->>V: evaluate
      R->>E: 恢复 baseline 并 close task environment
    else fresh evaluation environment
      R->>E: 在运行策略下 close task environment
      R->>E: 在基线策略下 open fresh evaluation environment
      R->>E: 覆盖 evaluation 策略
      R->>V: evaluate
      R->>E: 恢复 baseline 并 close evaluation environment
    else driver-side evaluation
      R->>E: close task environment
      R->>V: evaluate without environment
    end
    R->>S: persist detail and progress
  end
  R->>S: aggregate metrics, analysis, and summary
```

清理必须位于 `finally` 路径。准备、Harness 启动、model 执行、产物收集或验证失败时，都不能泄漏容器、云端 sandbox、代理、客户端或后台进程。

## 规划与优先级

执行前先标准化配置。Recipe 随后适配每个任务计划的副本，而不修改原始请求。每层适配都必须保留用户显式意图。

provider 选择字段遵循：

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

资源字典从任务默认值开始，再逐字段覆盖用户显式值。工作区根目录等标量默认值应使用`setdefault()`，不能无条件赋值。

这是一项有意的权衡：自动 Recipe 让官方任务镜像易于使用，而用户优先原则保留自定义预构建镜像和 provider 原生快照。显式值不兼容时，给出可操作错误；不要静默替换为“碰巧能运行”的配置。

## 设计原则

### 依赖契约，而非具体实现

组件通过 runtime 契约和公开注册表通信。共享类型从 `agentcompass.runtime` 导入，不要进入另一组件的私有模块，使 Harness 可复用于不同 Benchmark，Environment provider 可复用于不同 Harness。

### 分离策略与机制

Benchmark 定义评测策略，Environment 提供执行机制，runtime 负责排序。Benchmark 可以要求隔离验证，但应通过评测计划表达，而不是直接创建 Docker 容器。

### 保留用户显式意图

默认值与 Recipe 可以补齐缺失值，不能覆盖兼容的显式选择。任何便利逻辑如果改变用户提供的镜像、资源限制、工作区、网络策略、model 参数或超时，都是正确性缺陷。

### 保持规划纯净，限定副作用

任务加载、计划构造和 Recipe 应用应保持确定性。网络调用、软件包安装、sandbox 创建和文件修改属于明确生命周期阶段，使错误、限制和清理可见。

### 在 Environment 边界强制安全

提示词和 agent 指令不是安全控制。网络隔离、资源限制、文件系统边界和密钥处理必须由 provider 或 runtime 强制。baseline、run 和 evaluation 策略分离，因为可信准备与不可信执行需要不同权限。

### 让可复现性可观察

记录版本、修订版本、解析后计划、model 与 Harness 设置、评测器行为、失败和任务覆盖范围。设置和分母未对齐时，接近的得分不是对齐证据。

### 提前失败，并保留失败语义

昂贵操作前验证不支持的版本、协议、provider、策略和任务 ID。保留 Environment 错误、Harness 错误、model 错误、agent 超时、评测器错误和有效零分的区别；下游分析依赖这些区分。

### 保持专用依赖可选

默认安装只包含框架必需和广泛共享软件包。Benchmark/Harness 专属驱动依赖属于可选依赖和可信依赖工作流；任务 runtime 依赖属于任务镜像或受控准备阶段。

### 限制并发与外部压力

任务并发数、provider 打开速率限制、model 端点容量和资源配额是独立约束。provider 异步调用应保持非阻塞；在责任层应用有界并发；每个任务会话避免全局可变状态。

## 变更影响图

修改前使用下表识别最小代码与验证范围。

| 目标变更                           | 主要归属           | 同时检查                           | 放错位置的典型回归                  |
| ------------------------------ | -------------- | ------------------------------ | -------------------------- |
| 新数据集版本或评测器                     | Benchmark      | Recipe、文档、结果对齐                 | 新旧评分语义混合                   |
| 新 agent 框架或 CLI                | Harness        | 协议支持、安装策略、结果规范化                | Benchmark 与单一 agent 耦合     |
| 新 sandbox provider             | Environment    | 配置结构、网络、资源、限制、Recipe           | provider 专属行为泄漏进 Benchmark |
| 任务镜像或工作区映射                     | Recipe         | Benchmark 任务元数据、Environment 配置 | 用户显式覆盖不再生效                 |
| 新 baseline/run/evaluation 阶段行为 | runtime        | 所有 Environment 和受影响 Benchmark  | 某 provider 或评测模式绕过策略       |
| 新共享请求或结果字段                     | runtime 契约     | CLI、SDK、持久化、分析器、所有组件           | 序列化或旧结果分析损坏                |
| 新 CLI 选项                       | CLI 与配置        | `RunRequest`、Python SDK、用户指南   | CLI 与 SDK 解析出不同运行          |
| 新指标或分析                         | Benchmark 或分析器 | 结果结构、摘要渲染                      | 权威得分与评测后分析混淆               |

Benchmark 需要可复用 runtime 或 provider 能力时，应拆分工作：先合入基础变更，再把 Benchmark 集成变基到其上，使平台行为可以独立审查，而不是隐藏在 Benchmark PR 中。

## 公开接口与兼容性

稳定的面向开发者的接口包括：

* Python SDK 入口点和受支持外部 Recipe 类型使用 `agentcompass`。
* 共享契约与内置组件实现使用 `agentcompass.runtime`。
* 使用稳定 ID 发现组件的注册表。
* 公开组件参数的配置数据类。
* 供下游工具使用的已持久化详情、进度、运行信息 和摘要产物。

外部集成不要导入私有实现路径。契约必须变更时，优先添加带兼容默认值的字段，同步更新 CLI 和 SDK 构造，并同时测试新运行与已有结果目录的分析。

## 继续阅读集成指南

* [通用贡献流程](/zh/developer_guide/contributing)
* [Benchmark 集成](/zh/developer_guide/benchmark_integration)
* [Harness 集成](/zh/developer_guide/harness_integration)
* [Environment 集成](/zh/developer_guide/environment_integration)