源码地图

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

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

​

入口与运行调用链

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

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 的中间调用：

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：

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 接管已解析的请求后，处理每个任务的调用路径如下：

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 契约与规划。

​

根据现象定位

现象或变更	从这里开始	接着检查
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、MetricResult.counts

继续阅读 执行、调度与清理 了解这些调用的阶段顺序。