概览

理解 AgentCompass 系统边界、runtime 契约、执行流和各组件变更的影响。

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

​

系统概览

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

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

​

runtime 结构

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

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 为每个选中任务创建计划，因为镜像、资源、工作区和验证器要求可能逐任务不同。

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

​

规划与优先级

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

provider 选择字段遵循：

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 强制。准备、agent 执行和验证策略分离，因为可信准备与不可信执行需要不同权限。

​

让可复现性可观察

记录版本、修订版本、解析后计划、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 配置	用户显式覆盖不再生效
新准备/运行/验证器阶段行为	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 构造，并同时测试新运行与已有结果目录的分析。

​

继续阅读集成指南

• 通用贡献流程
• Benchmark 集成
• Harness 集成
• Environment 集成