> ## 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.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 -> BaseBenchmark.collect_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) 了解这些调用的阶段顺序。