> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-335-0.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 源码地图

可沿以下调用链，从用户可见行为定位到实际负责该行为的函数。

本页路径均相对于仓库根目录。列出这些实现路径仅为方便导航；公开扩展代码仍应从 `agentcompass.runtime` 导入共享类型。

## 入口与运行调用链

`run` 命令与高层 Python 辅助函数会在进入编排前汇合：

```text theme={"system"}
src/agentcompass/cli/main.py::run_command
  -> src/agentcompass/launcher.py::run_evaluation
  -> src/agentcompass/launcher.py::async_run_evaluation
  -> src/agentcompass/launcher.py::_build_run_request_from_config
  -> src/agentcompass/launcher.py::async_run_evaluation_request
  -> src/agentcompass/runtime/models/orchestration.py::Orchestration.from_requests
  -> src/agentcompass/runtime/orchestration.py::Orchestrator.execute
```

`build_run_request` 是供调用方在执行前检查或修改请求的公开 SDK 构造函数，并不是 `run_command` 的中间调用：

```text theme={"system"}
src/agentcompass/launcher.py::build_run_request
  -> RunRequest
  -> src/agentcompass/launcher.py::run_evaluation_request
  -> src/agentcompass/launcher.py::async_run_evaluation_request
```

`async_run_evaluation_request` 会把选中的运行配置合并到已构建的请求中，将它包装为只含一个请求的 `Orchestration`，再与多请求启动共用同一个 `Orchestrator`。

**多请求入口。** `launch` 命令与 SDK 通过以下调用链进入同一个 `Orchestrator`：

```text theme={"system"}
src/agentcompass/cli/main.py::launch_command
  -> src/agentcompass/runtime/orchestration.py::load_orchestration_spec
  -> src/agentcompass/launcher.py::async_launch
  -> src/agentcompass/runtime/orchestration.py::resolve_orchestration
  -> src/agentcompass/runtime/orchestration.py::Orchestrator.execute
```

同步 SDK 函数 `agentcompass.launch` 由 `src/agentcompass/launcher.py` 中的 `launch()` 实现，它使用 `asyncio.run` 包装 `async_launch`。

**进入 runtime 后。** `Orchestrator` 接管已解析的请求后，处理每个任务的调用路径如下：

```text theme={"system"}
Orchestrator._preflight
  -> UnifiedEvaluationRuntime.preflight

Orchestrator._prepare_in_order
  -> UnifiedEvaluationRuntime.prepare
  -> BaseBenchmark.load_tasks
  -> BaseBenchmark.select_tasks
  -> RunStore.materialize_reused_details
  -> RunStore.load_partial_results

Orchestrator._worker
  -> UnifiedEvaluationRuntime.execute_task
  -> UnifiedEvaluationRuntime._run_attempts
  -> Planner.plan                         # 每次 k 尝试一次
  -> UnifiedEvaluationRuntime._run_single_attempt
  -> BaseEnvironment.open
  -> BaseBenchmark.prepare_task
  -> BaseHarness.start_session / run_task / close_session
  -> runtime.artifacts.run_artifact_collect_commands（声明命令时）
  -> runtime.artifacts.download_artifacts
  -> BaseBenchmark.evaluate
  -> analyze_task
  -> RunStore.save_partial_result

Orchestrator._finalize_one
  -> UnifiedEvaluationRuntime.finalize
  -> summarize_results
  -> BaseBenchmark.aggregate_metrics
  -> RunStore.save_results
```

对于 `HarnessFreeBenchmark`，runtime 会调用它的 `run_task()` 方法，而不是三个 Harness 方法；其余计划构建、Environment 管理、产物收集、评测、分析和持久化仍走相同的实现。

## 目录与符号地图

| 区域 | 具体符号 | 仓库路径 |
| - | - | - |
| 公开 Python API | 导出的启动与请求辅助函数 | `src/agentcompass/__init__.py`、`src/agentcompass/launcher.py` |
| CLI | `run_command`、`launch_command`、检查命令 | `src/agentcompass/cli/main.py` |
| 配置 | `load_run_config`、`deep_merge`、runtime 设置 | `src/agentcompass/runtime/config/` |
| 编排模型 | `OrchestrationSpec`、`Orchestration`、`RequestOutcome` | `src/agentcompass/runtime/models/` 下的 `orchestration.py` |
| 请求模型 | `RunRequest` 及其八个配置段 | `src/agentcompass/runtime/models/request.py` |
| 任务与计划模型 | `TaskSpec`、`PreparedTask`、`ExecutionPlan` | `src/agentcompass/runtime/models/task.py`、`src/agentcompass/runtime/models/plan.py` |
| 组件接口 | `BaseBenchmark`、`BaseHarness`、`BaseEnvironment`、`BaseRecipe`、`BaseAnalyzer` | `src/agentcompass/runtime/base.py` |
| 组件发现 | 组件注册表与内置模块导入 | `src/agentcompass/runtime/registry.py` |
| 规划 | `Planner.plan`、运行级 Recipe 加载 | `src/agentcompass/runtime/planner.py`、`src/agentcompass/runtime/recipes.py` |
| 调度 | `Orchestrator`、`TaskExecutor`、provider 限制器 | `src/agentcompass/runtime/orchestration.py`、`src/agentcompass/runtime/tasks.py`、`src/agentcompass/runtime/limits.py` |
| 尝试执行 | `UnifiedEvaluationRuntime` | `src/agentcompass/runtime/runner.py` |
| 结果处理流程 | 明细结构整理、聚合、渲染与存储 | `src/agentcompass/runtime/results/`、`src/agentcompass/runtime/metrics/` |
| 具体实现 | 内置组件 | `src/agentcompass/benchmarks/`、`src/agentcompass/harnesses/`、`src/agentcompass/environments/`、`src/agentcompass/recipes/`、`src/agentcompass/analyzers/` |

Model 直接存储在请求中，不通过组件注册表选择。相关类型、配置限制和修改边界见 [runtime 契约与规划](/zh/developer_guide/architecture/contracts)。

## 根据现象定位

| 现象或变更 | 从这里开始 | 接着检查 |
| - | - | - |
| CLI 与 SDK 解析值不同 | `src/agentcompass/launcher.py` | 请求模型与配置加载器 |
| 任务集合错误或任务 ID 不稳定 | 选定 Benchmark 的 `load_tasks` 与 `select_tasks` | `BaseBenchmark.filter_tasks_by_sample_ids` |
| 镜像、工作区或评测模式错误 | `Planner.plan` 与匹配的 Recipe | Benchmark `build_plan`、Environment 配置 |
| agent 输出结构错误 | 选定 Harness 的 `run_task` | `RunResult`、轨迹模型 |
| 得分错误 | 选定 Benchmark 的 `evaluate` | 其 `aggregate_metrics` 与共享指标协议 |
| 任务重复执行或长期得不到调度 | `Orchestrator._worker` 与 `_select_state` | `PreparedRun.pending_tasks` 与 provider 限制器 |
| 失败后 sandbox 未释放 | `_run_single_attempt` 与 `_run_fresh_evaluate` | provider `close` 实现与取消路径 |
| 已有结果无法复用 | `RunStore._get_reuse_source_directory` | `materialize_reused_details`、明细命名 |
| 摘要分母错误 | `summarize_results` | Benchmark `aggregate_metrics`、每个 `MetricSeries.counts` |

继续阅读 [执行、调度与清理](/zh/developer_guide/architecture/execution_lifecycle) 了解这些调用的阶段顺序。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.