跳转到主要内容
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。 
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 诊断。

​
组合模型

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 的情况下重新做诊断。