企业官网建设流程全解析

• 人工智能
• 大模型
• AI Agent
• 代码智能体

导读

本文围绕 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[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

参数说明：

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 settingenvironment_classtocontreein 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传入。全部字段如下：

关键字段的行为细节：

• 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且异常信息被记录。

返回值结构遵循ExecutionResultTypedDict（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）记录环境类型全限定名与完整配置，写入轨迹文件中，便于复现与审计。

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

从代码结构看，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 中阅读环境行为的完整测试覆盖。

• 人工智能
• 大模型
• AI Agent
• 代码智能体