mini-swe-agent ConTree 环境指南：基于 ConTree 沙箱执行 SWE-bench 任务

导读

本文围绕 ConTree 环境参考文档，系统讲解 mini-swe-agent 如何借助 ConTree 云端沙箱执行命令：从安装依赖、配置令牌与 Base URL，到通过 mini-extra swebench 命令行或 YAML 配置接入 SWE-bench 评测流程。读完本文，你将掌握 ConTree 环境的完整配置参数（镜像、工作目录、环境变量、超时、镜像导入等）、命令执行与结果解析的底层机制，以及如何与默认 Docker 环境无缝切换。

一、ConTree 环境在 mini-swe-agent 中的定位

mini-swe-agent 将“执行环境”抽象为统一的 Environment 协议（定义于 src/minisweagent/init.py），只要实现了 execute、get_template_vars、serialize 三个接口即可接入 Agent 主循环。ConTree 环境正是该协议的一个远程沙箱实现，类名为 ContreeEnvironment，源码位于 src/minisweagent/environments/extra/contree.py。

与内置的 Docker、Singularity、本地环境不同，ConTree 由外部平台提供，具备面向 Agent 的沙箱能力。mini-swe-agent 通过 _ENVIRONMENT_MAPPING 注册表（见 src/minisweagent/environments/init.py）将字符串标识 "contree" 映射到 ContreeEnvironment 类：

_ENVIRONMENT_MAPPING = {
    ...
    "contree": "minisweagent.environments.extra.contree.ContreeEnvironment",
}

因此，无论是 CLI 参数还是 YAML 配置中的 environment_class: contree，最终都会经过 get_environment_class 解析并实例化。

前提限制：ConTree 环境需要有效的 ConTree 平台令牌（token）与平台分配的 Base URL，属于外部服务依赖，无法离线使用。项目文档在 docs/advanced/environments.md 中将其定位为“为 Agent 构建、支持 Git 式执行”的沙箱方案。

二、环境安装与凭证配置（Setup）

2.1 安装依赖

ConTree 环境依赖 contree-sdk，mini-swe-agent 将其作为可选依赖组暴露：

pip install "mini-swe-agent[contree]"

对应 pyproject.toml 中的可选依赖声明（pyproject.toml）：

contree = [
    "contree-sdk>=0.2.0",
]

注意：该 SDK 是运行时依赖，测试与开发场景下也需安装 mini-swe-agent<a href="https://link.gitcode.com/i/8fd64acf3367f1604e5b0728974c14a6" target="_blank">dev] 才能运行相关测试用例。若将 ConTree 与 SWE-rex、Modal 等环境一起使用，可安装 mini-swe-agent[full] 一键聚合全部环境依赖（[pyproject.toml）。

2.2 配置令牌与 Base URL

安装完成后，通过环境变量提供凭证：

export CONTREE_TOKEN="your-contree-token"
export CONTREE_BASE_URL="your-given-base-url-for-contree"

这两个变量会被 contree-sdk 读取，用于构造 ContreeConfig。从源码看，ContreeEnvironment.__init__（src/minisweagent/environments/extra/contree.py）支持两种方式传入 SDK 配置：

1. 直接传入 ContreeConfig 实例；
2. 传入字典，例如 {"base_url": "...", "token": "..."}，此时环境会自动将其转换为 ContreeConfig：

if isinstance(self.config.contree_config, dict):
    self.config = self.config.model_copy(update={"contree_config": ContreeConfig(**self.config.contree_config)})

测试用例 tests/environments/extra/test_contree.py 正是以 contree_config={"base_url": "http://fake", "token": "fake-token"} 的字典形式构造环境的，并断言转换后 isinstance(env.config.contree_config, ContreeConfig) 成立。这意味着在 YAML 配置文件中，contree_config 同样可以直接写成键值对字典。

三、在 SWE-bench 评测中使用 ConTree 环境（Usage）

3.1 命令行方式

安装并配置好凭证后，即可像使用其他环境一样启动 mini-swe-agent：

mini-extra swebench \
    --subset verified \
    --split test \
    --workers 100 \
    --environment-class contree

参数说明：

参数	含义
--subset verified	使用 SWE-bench Verified 子集（对应 princeton-nlp/SWE-Bench_Verified，映射见 src/minisweagent/run/benchmarks/swebench.py）
--split test	评测数据划分
--workers 100	并发工作进程数
--environment-class contree	显式指定环境类型为 ConTree

mini-extra 是 mini-swe-agent 的附加命令入口（src/minisweagent/run/utilities/mini_extra.py），swebench 子命令通过 typer 解析上述参数。在 swebench.py 中，--environment-class 被定义为可选参数，随后写入环境配置：

"environment": {"environment_class": environment_class or UNSET},

3.2 YAML 配置方式

同样的效果也可以直接在 swebench.yaml 配置文件中声明：

environment:
  environment_class: contree
  cwd: "/testbed"
  timeout: 60

两种方式等价——文档明确指出“It can be specified both through cli parameter or by setting environment_class to contree in your swebench.yaml config”。CLI 参数会覆盖或补充配置文件中的对应字段。项目自带的基准配置模板位于 src/minisweagent/config/benchmarks/swebench.yaml，其中 environment_class 默认值为 docker，替换为 contree 即可切换后端，其余 cwd、timeout、env 等字段对 ConTree 环境同样生效。

3.3 ConTree 环境的镜像约定

切换到 ConTree 环境后，SWE-bench 运行器会自动为实例镜像添加 docker:// 前缀（src/minisweagent/run/benchmarks/swebench.py）：

if env_config["environment_class"] in ["docker", "swerex_modal"]:
    env_config["image"] = image_name
elif env_config["environment_class"] in ["singularity", "contree"]:
    env_config["image"] = "docker://" + image_name

也就是说，SWE-bench 实例的 image_name（如 docker.io/swebench/sweb.eval.x86_64.*:latest）会被统一改写为 OCI 镜像引用格式后交给 ConTree 拉取。这是 ConTree 环境在 SWE-bench 场景下与 Docker 环境的关键差异，了解这一点可以避免误以为镜像配置写错了。

四、ContreeEnvironment 配置参数详解

ContreeEnvironmentConfig 继承自 pydantic 的 BaseModel（src/minisweagent/environments/extra/contree.py），支持通过 YAML 或 **kwargs 传入。全部字段如下：

字段	类型	默认值	说明
contree_config	ContreeConfig | dict[str, Any]	必填	SDK 连接配置（token、base_url 等）
image	str	必填	容器镜像标识
image_tag	str | None	None	指定镜像标签拉取；若失败则按 image 导入并回填标签
cwd	str	"/"	容器内命令执行的工作目录
cwd_auto_create	bool	True	执行命令前自动 mkdir -p 创建工作目录
env	dict[str, str]	{}	注入容器的环境变量
forward_env	list[str]	[]	从宿主机转发的环境变量名列表（仅在宿主已设置时转发；与 env 冲突时 env 优先）
interpreter	list[str]	["bash", "-c"]	命令解释器
timeout	int	100	容器内单条命令的超时时间（秒）
import_username	str | None	None	镜像需要导入时使用的用户名
import_password	str | None	None	镜像需要导入时使用的密码

关键字段的行为细节：

• image_tag 的降级逻辑：_pull_image（src/minisweagent/environments/extra/contree.py）调用 SDK 的 client.images.oci(...)，若按 tag 拉取失败，则回退到按 image 导入，并把实际 tag 写回 image_tag。
• forward_env 的转发语义：execute 中通过字典推导式逐个检查宿主机环境变量，仅转发已设置的变量；随后用 env.update(self.config.env) 让显式配置的变量覆盖转发变量（src/minisweagent/environments/extra/contree.py）。对应测试见 tests/environments/extra/test_contree.py。
• cwd_auto_create 的初始化行为：构造环境时若为 True，会立即以 cwd="/" 执行一次 mkdir -p {cwd}（src/minisweagent/environments/extra/contree.py），确保后续命令不会因目录不存在而失败。
• timeout 的默认值：源码默认 100 秒，而 SWE-bench 内置模板中环境级 timeout 为 60，两处独立生效，配置时需注意区分。

五、命令执行与结果解析的底层实现

5.1 execute 的完整调用链

ContreeEnvironment.execute（src/minisweagent/environments/extra/contree.py）接收 Agent 产出的 action 字典，流程如下：

1. 取出 action["command"]；
2. 合并 forward_env 与 env 得到容器环境变量；
3. 用 _shell_command 将命令包装为 bash -c <shlex.quote(command)>（src/minisweagent/environments/extra/contree.py），shlex.quote 保证特殊字符安全；
4. 调用 self.session.run(shell=..., cwd=..., timeout=..., disposable=False, env=...) 并 .wait()；
5. 成功时返回 {"output": stdout + stderr, "returncode": exit_code, "exception_info": ""}；
6. 异常时捕获并返回 returncode=-1、exception_info 及 extra 字段（含异常类型、异常信息，若异常是 dataclass 还会序列化其字段）。

测试 tests/environments/extra/test_contree.py 验证了 shell、cwd、timeout、disposable、env 五个参数被原样传给 SDK；test_execute_exception 则验证了 SDK 抛异常时返回 returncode == -1 且异常信息被记录。

返回值结构遵循 ExecutionResult TypedDict（src/minisweagent/environments/extra/contree.py）：

class ExecutionResult(TypedDict):
    output: str
    returncode: int
    exception_info: str
    extra: NotRequired[dict[str, Any]]

Agent 的观察模板正是基于这些字段渲染 <returncode>、<output>、<exception> 的（见 src/minisweagent/config/benchmarks/swebench.yaml）。

5.2 任务提交标记（Submitted）

ConTree 环境复用了统一的提交协议：若命令输出以 COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT 开头且 returncode == 0，_check_finished（src/minisweagent/environments/extra/contree.py）会抛出 Submitted 异常，将剩余输出作为最终提交内容交给 Agent 主循环。对应测试 test_execute_raises_submitted 验证了该行为；同时 test_execute_no_submit_on_nonzero_returncode 确认命令失败时（returncode 非 0）不会触发提交，即标记仅在命令成功时生效。

5.3 模板变量与序列化

• get_template_vars（src/minisweagent/environments/extra/contree.py）将环境配置与宿主平台信息（platform.uname()）递归合并，供 Agent 提示词模板使用；
• serialize（src/minisweagent/environments/extra/contree.py）记录环境类型全限定名与完整配置，写入轨迹文件中，便于复现与审计。

六、与其它环境的对比与选型建议

维度	Docker（默认）	ConTree
沙箱位置	本地 Docker 守护进程	ConTree 云端沙箱（需 token + base_url）
镜像格式	直接使用 image_name	自动加 docker:// 前缀（OCI 格式）
网络依赖	本地拉镜像	全程依赖 ConTree 服务可用性
并发扩展	受本地资源限制	由平台侧资源决定，--workers 100 级并发更易横向扩展
安装成本	内置	需 pip install "mini-swe-agent[contree]"

从代码结构看，mini-swe-agent 的设计允许在 docker、singularity、local、swerex_docker、swerex_modal、bubblewrap、contree 之间无缝切换（src/minisweagent/environments/init.py），ConTree 主要适合希望将代码执行托管到云端沙箱、规避本地容器运行时限制的 SWE-bench 评测场景。

七、常见问题排查（基于源码与测试）

1. 安装后 import contree_sdk 失败：确认使用 pip install "mini-swe-agent[contree]" 而非基础包，SDK 版本要求 contree-sdk>=0.2.0（pyproject.toml）。
2. 提示 Unknown environment type：确认 environment_class 拼写为 contree（注册表键值见 src/minisweagent/environments/init.py），或直接使用类的全限定名。
3. 命令返回 returncode == -1 且 exception_info 非空：说明 SDK 调用抛异常（如网络中断、凭证失效），检查 CONTREE_TOKEN / CONTREE_BASE_URL 是否设置正确，并查看 extra.exception_type 定位具体错误（src/minisweagent/environments/extra/contree.py）。
4. 工作目录不存在报错：保持 cwd_auto_create: true（默认值），环境构造时会自动执行 mkdir -p；若手动关闭，需保证镜像内 cwd 已存在。
5. 提交未被触发：提交标记只在 returncode == 0 时生效，检查命令是否因超时（默认 100 秒）或非零退出被判定为失败（tests/environments/extra/test_contree.py）。

结语

ConTree 环境为 mini-swe-agent 提供了“免本地容器、云端沙箱化”的代码执行后端，只需一次安装、两个环境变量和一个 --environment-class contree 参数即可接入成熟的 SWE-bench 评测流水线。理解其配置字段、镜像约定与提交协议，能帮助你在多环境并存的评测体系中快速定位问题、按需选型。更进一步，可参考 SWE-bench 使用文档 了解完整的评测输出与结果验证流程，或在 tests/environments/extra/test_contree.py 中阅读环境行为的完整测试覆盖。