> ## 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.

# 环境

> 本地、容器和远程 sandbox 后端的统一执行与文件接口。

Environments 是 execution providers。它们为 harness 提供统一的命令执行、文件传输、文本读写、endpoint 暴露和资源清理接口。

Benchmarks 和 harnesses 应依赖 `EnvironmentSession` 表面，而不是直接依赖 provider SDK。

## Environments 负责什么

<CardGroup cols={2}>
  <Card title="命令执行" icon="terminal">
    以 shell 或 argv 方式执行命令，并支持 cwd、env、timeout、detach 和 return-code capture。
  </Card>

  <Card title="文件传输" icon="files">
    在本地磁盘和 environment 之间 upload/download 文件或目录。
  </Card>

  <Card title="Workspace 访问" icon="folder">
    提供文本读写和 default workspace root 行为。
  </Card>

  <Card title="Provider 生命周期" icon="power">
    打开 session、返回可选 endpoint，并释放 sandbox、container 或本地 session。
  </Card>
</CardGroup>

## Session 接口

| Method                                                                       | 作用                                   |
| ---------------------------------------------------------------------------- | ------------------------------------ |
| `exec(command, shell=False, cwd=None, env=None, timeout=None, detach=False)` | 执行命令并返回 `ExecResult`。                |
| `upload(src, dst)` / `download(src, dst)`                                    | 跨 provider boundary 复制文件。            |
| `upload_dir(src, dst)` / `download_dir(src, dst)`                            | 递归复制目录。                              |
| `write_text(path, content)` / `read_text(path)`                              | 修改 environment 内文本文件。                |
| `endpoint()`                                                                 | 对支持服务暴露的 provider 返回 URL。            |
| provider `close()`                                                           | 释放 sandbox、container 或本地 session 状态。 |

## Provider 选择

| Provider                                    | 适用场景                                                               |
| ------------------------------------------- | ------------------------------------------------------------------ |
| [`host_process`](/zh/environments/overview) | 本地轻量 smoke test，或不需要 isolation 的 benchmark。                        |
| [`docker`](/zh/environments/docker)         | 本地可复现容器，前提是 Docker 可用。                                             |
| [`modal`](/zh/environments/modal)           | 远程 registry-image sandbox，尤其适合 SWE-bench 和 Terminal-Bench recipes。 |
| [`daytona`](/zh/environments/daytona)       | 远程 developer-style workspace 和 task images。                        |

通过 `--env` 选择 provider，默认值位于 `config/defaults.yaml` 的 `environments.<provider>` 下。当任务只需要本地文件或直接模型调用时，从 `host_process` 开始；当任务需要 isolation 或 benchmark 专用镜像时，再切换到容器或远程 sandbox。对于支持 recipe 的 benchmark/provider 组合，image 和 workspace root 会从 task metadata 推导，通常不需要手动传 `--env-params '{"image":"..."}'`。

<Note>
  各 provider 的凭据、配置步骤和可运行示例见[执行环境](/zh/environments/overview)章节；首次运行时如何挑选 provider，见[环境选择实战指南](/zh/cookbooks/first_runs/environment_selection)。
</Note>

## 并发与限制

| 控制项                                  | 作用范围                                 |
| ------------------------------------ | ------------------------------------ |
| `--task-concurrency`                 | 单次 run 中同时执行的任务数。                    |
| `execution.task_concurrency`         | YAML 中 per-run task concurrency 默认值。 |
| `runtime.provider_limits.<provider>` | 当前进程内打开 provider session 的全局上限。      |

提高 task concurrency 前，应先确认模型 endpoint 和 provider 账号限额可以承受。

## 开发者说明

当执行发生在新的 provider 或 runtime substrate 中，新增 environment。不要为了选择不同 task image 新增 environment；那属于 `environment.params` 或 recipe。

## 相关页面

* [执行环境概览](/zh/environments/overview)
* [Recipes](/zh/key_modules/recipes)
* [配置](/zh/reference/configuration)