架构概览

AgentCompass 明确划分 Model、Benchmark、Harness、Environment、Recipe、分析器和 runtime 的职责。这些部分通过请求、计划、尝试和结果等共享契约协同工作。

AgentCompass 将 CLI 或 Python 输入解析为一个或多个 RunRequest，由 Benchmark 发现任务，为每次语义尝试构建 ExecutionPlan，再交给共享 runtime 执行。runtime 将完成评测的尝试持久化为任务明细，并把这些明细聚合为请求摘要。

​

从请求到结果与职责边界

组件注册表不包含 ModelSpec。Model 是请求中描述端点和推理设置的值。runtime 组件注册表负责发现 Benchmark、Harness、Environment、Recipe 和分析器实现；其源码位置见源码地图。

Environment 的具体关闭时机取决于 evaluation_environment_mode：评测可以在任务 Environment 中执行、不使用 Environment，或在一个全新的 Environment 中执行。三种模式都通过 finally 路径完成清理。

层	负责	主要源码
Model	端点标识、API 协议、凭证和推理参数	src/agentcompass/runtime/models/model.py
Benchmark	数据集加载、稳定的任务标识、任务准备、评测和指标聚合	src/agentcompass/benchmarks/ 与 src/agentcompass/runtime/base.py 中的 BaseBenchmark
Harness	agent 或 Model 执行循环、会话生命周期、轨迹和用量数据规范化	src/agentcompass/harnesses/ 与 src/agentcompass/runtime/base.py 中的 BaseHarness
Environment	命令、文件、端点、可强制执行的网络策略、资源和 sandbox 生命周期	src/agentcompass/environments/ 与 src/agentcompass/runtime/base.py 中的 BaseEnvironment
Recipe	在不产生副作用的情况下，按任务调整 ExecutionPlan	src/agentcompass/recipes/、BaseRecipe 与 Planner
runtime	跨组件编排、尝试、重试、限制、取消、清理和持久化	src/agentcompass/runtime/
分析器	对已评测的尝试做可选解释，但不改变 Benchmark 的权威得分	src/agentcompass/analyzers/ 与 src/agentcompass/runtime/analysis.py

策略应由对应的组件负责。例如，Benchmark 可以通过计划要求隔离评测，Environment 负责打开和关闭 sandbox，runtime 则决定何时执行这些操作。

执行作用域。 AgentCompass 有两个不应混淆的嵌套执行单元：

• 语义尝试 是 Benchmark 的 k 次执行之一。runtime 会在每次尝试开始时调用一次 Planner.plan，因此每次尝试都会重新生成一份计划。
• runtime 重试 根据 ExecutionSpec.max_retries 与 retry_pattern_list 重复同一次尝试中失败的工作。它复用已经解析的 ExecutionPlan，不会再次调用 Planner.plan。

还要区分不同层级的结果：RunResult 是 Harness 或无 Harness Benchmark 返回的执行层对象。Benchmark.evaluate 将其转换为已评测的尝试，_run_attempts 将多个已评测的尝试组成一条任务记录，UnifiedEvaluationRuntime.finalize 再把任务记录聚合为请求结果。

​

必须保持的约束

• 从 agentcompass.runtime 导入共享契约，不要让一个扩展依赖另一个扩展的私有模块。
• 规划应保持确定性；sandbox 创建、网络调用、依赖安装和文件修改应位于明确的生命周期阶段。
• 默认值或 Recipe 补齐缺失设置时，不得覆盖兼容的用户显式值。
• 网络、文件系统、资源和密钥边界应由 runtime 或 Environment provider 强制执行，不能依赖提示词。
• 保留运行错误、评测错误、有效零分和跳过执行之间的区别。
• 记录足以解释结果的最终解析状态，并在每个持久化边界脱敏密钥。

​

按任务继续阅读

你的任务	阅读页面
沿真实函数跟踪 CLI 或 SDK 请求，定位需要修改的代码	源码地图
修改共享契约、配置合并优先级、每次尝试的规划过程或 Recipe 行为	runtime 契约与规划
修改准备、推理、产物收集、评测、尝试、重试、调度、取消或资源释放逻辑	执行、调度与清理
修改明细、摘要、分析产物、结果复用或兼容性	结果与复用

实现新组件时，继续阅读 Benchmark 集成、Harness 集成 或 Environment 集成；准备提交变更时，使用通用贡献流程。