> ## 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 明确划分 Model、Benchmark、Harness、Environment、Recipe、分析器和 runtime 的职责。这些部分通过请求、计划、尝试和结果等共享契约协同工作。 AgentCompass 将 CLI 或 Python 输入解析为一个或多个 `RunRequest`，由 Benchmark 发现任务，为每次语义尝试构建 `ExecutionPlan`，再交给共享 runtime 执行。runtime 将完成评测的尝试持久化为任务明细，并把这些明细聚合为请求摘要。 ## 从请求到结果与职责边界 AgentCompass 从 RunRequest 经 Benchmark 发现任务，为每次尝试进行规划与执行，再完成评测、可选分析和结果持久化的架构流程。 组件注册表不包含 `ModelSpec`。Model 是请求中描述端点和推理设置的值。runtime 组件注册表负责发现 Benchmark、Harness、Environment、Recipe 和分析器实现；其源码位置见[源码地图](/zh/developer_guide/architecture/source_map)。 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 请求，定位需要修改的代码 | [源码地图](/zh/developer_guide/architecture/source_map) | | 修改共享契约、配置合并优先级、每次尝试的规划过程或 Recipe 行为 | [runtime 契约与规划](/zh/developer_guide/architecture/contracts) | | 修改准备、推理、产物收集、评测、尝试、重试、调度、取消或资源释放逻辑 | [执行、调度与清理](/zh/developer_guide/architecture/execution_lifecycle) | | 修改明细、摘要、分析产物、结果复用或兼容性 | [结果与复用](/zh/developer_guide/architecture/results_and_reuse) | 实现新组件时，继续阅读 [Benchmark 集成](/zh/developer_guide/extensions/benchmark/overview)、[Harness 集成](/zh/developer_guide/extensions/harness/overview) 或 [Environment 集成](/zh/developer_guide/extensions/environment/overview)；准备提交变更时，使用[通用贡献流程](/zh/developer_guide/contributing/overview)。