第 4 章：任务环境——environment 目录与工具注入
第 4 章：任务环境——environment 目录与工具注入
环境决定了 agent 在什么世界里干活：有哪些工具、能访问什么网络、外部服务如何提供。本章讲清
environment/目录的职责边界、Dockerfile 与预构建镜像的关系，以及 MCP servers、skills 等工具注入手段和/logs/verifier/等特殊路径约定。
environment/ 目录与 BaseEnvironment
environment/ 目录定义了 agent 和 verifier 运行所在的环境，最常见的内容就是一个 Dockerfile 或 docker-compose.yaml。
在框架层面，Harbor 对"环境"的抽象是 BaseEnvironment 接口，它定义了以下方法：
exec：在环境中执行命令upload_file/upload_dir：向环境上传文件/目录download_file/download_dir：从环境下载文件/目录start/stop：启动与停止环境
这些方法通常针对 Docker 等容器运行时，或 Daytona、Modal 等云沙箱 provider 实现。换句话说，无论底下是本机容器还是云端沙箱，框架眼中的环境都只是这几个"类系统调用"的原语——这个设计让任务可以无缝换底座。
用 Dockerfile 定制环境
从目录构建
最直接的方式是把环境定制写进 environment/Dockerfile：安装系统依赖、准备数据、预装工具，都在镜像构建阶段完成。多容器场景（比如任务需要同时有应用容器和数据库容器）则改用 environment/docker-compose.yaml。
预构建镜像
对追求速度与可复现性的场景，可以先构建好 Docker 镜像，托管到 Docker Hub 或 GitHub Packages 等容器仓库，再在 task.toml 中引用：
[environment]
docker_image = "apple/unix-os:latest"设置了 [environment].docker_image 后，大多数 provider 会优先使用预构建镜像而不是从 environment/ 目录现构建，而且此时 environment/ 目录可以整个省略。
资源声明与操作系统
资源的量化声明写在 [environment] 段：
[environment]
cpus = 2
memory_mb = 4096
storage_mb = 10240
gpus = 1
gpu_types = ["H100", "A100"]
[environment.tpu]
type = "v6e"
topology = "2x4"这些字段都是可选的，省略时 Harbor 使用 provider 的默认规格。运行时也可以用 --cpus 和 --memory 标志控制这些声明的应用方式。操作系统由 [environment].os 指定，默认 "linux"，可选 "windows"（注意部分 agent 是否支持 Windows 要查 Agent capabilities 页）。
MCP servers：给 agent 接上外部工具
Harbor 支持通过 docker-compose.yaml 搭建多容器环境，而 MCP（Model Context Protocol）服务器常见用法就是 mock 数据库、API 之类的外部服务——把它们实现为 compose 里的 service。
关键一步：环境中可用的 MCP 服务器必须在 task.toml 里用 [[environment.mcp_servers]] 显式声明，这样兼容的 agent（如 Claude Code、Codex）才能自动注册它们：
[[environment.mcp_servers]]
name = "mcp-server"
transport = "streamable-http"
url = "http://mcp-server:8000/mcp"三种 transport 的选择：sse 和 streamable-http 走 URL（适合 compose sidecar），stdio 走本地命令启动。字段细节见第 3 章的速查表。
skills_dir：给 agent 捆绑技能
除了 MCP，Harbor 还支持把**技能（skills）**打包进环境：把技能文件放进环境内某个目录，再用 [environment].skills_dir 指向它，兼容的 agent 就能拿到这些技能：
[environment]
skills_dir = "/app/skills"技能目录内部要求特定的布局与镜像配置（详见 Tasks → Skills 文档），Harbor 会负责把技能传递给 agent。
工具的归属：环境还是 agent？
Harbor 有一个明确立场：工具是 agent 的组成部分，不是环境的组成部分。如果环境确实要提供工具，应以 MCP、skills、API 或 CLI 的形式呈现。
agent 可以运行在环境之内，也可以运行在环境之外：
- 在环境内：agent 想用什么工具都可以；
- 在环境外：agent 的工具只能由
BaseEnvironment的那几个原语（exec、上传下载等）组合而成——它们接近系统调用级别，因此几乎不构成约束。
外部服务怎么处理？
任务涉及数据库、Stripe 之类的真实服务时，有两条路：mock 或直连。官方的建议是尽量 mock——比如把 Stripe 的一小块能力做成 compose 服务，或者优先使用服务方的 sandbox/dev 模式——因为这样可控性和可复现性更好。
如果确实要直连生产服务，考虑用 [agent].allowed_hosts 把 agent 的出网限制到那个特定端点，缩小爆炸半径。
还有一种极端情况：agent 和环境本身就是紧耦合的外部服务（比如一个深度绑定自家 API 的 agent）。此时如果只拿 Harbor 环境去 ping 一下 agent API、再 ping 一下环境 API 来打分，那 Harbor 可能不适合你的场景——它擅长评测的是利用代码执行和文件系统工作的 coding/cowork agent。文档作者也认为多数 agent 正朝这个方向演进，产品方值得评估自己的 MCP、API、CLI 能否被 coding agent 用好。
特殊路径约定
容器内有几个由 Harbor 约定的特殊路径（Linux 路径，Windows 使用 C: 等价物）：
| 路径 | 用途 |
|---|---|
/logs/verifier/ |
Reward 与 verifier 输出（reward.txt / reward.json 写在这里） |
/logs/agent/ |
可选的 agent 日志 |
/solution/ |
Harbor 会把 solution/ 拷贝到这里供 Oracle 执行 |
/tests/ |
Harbor 会把 tests/ 拷贝到这里（共享 verifier 场景） |
Trial 结束后，/logs/ 会被同步回宿主机，用于调试——所以不要把重要产物写到别的临时位置，日志和 reward 都要落在约定路径里。
artifacts：把文件带出环境
如果任务需要从环境里带回文件（生成的报告、日志、产物等），在 task.toml 里声明根级路径即可，Harbor 会在 verification 之后把它们快照到 trial 的 artifacts 目录：
[environment]
# ...其他配置
[[artifacts]]
source = "/app/output"
exclude = ["*.tmp"]列表项可以是容器路径字符串，也可以是带 source / destination / exclude 的表格；多步任务中每步还会收集步骤级 artifacts。字段语义见第 3 章。
本章小结
- 环境的框架抽象是
BaseEnvironment：exec、上传/下载、start/stop 七个原语，屏蔽 Docker 与云沙箱差异。 - 环境定制首选
environment/Dockerfile（多容器用docker-compose.yaml）；追求速度与可复现可用docker_image预构建镜像，此时environment/可省略。 - MCP 服务器先在 compose 里实现为 service，再用
[[environment.mcp_servers]]声明，兼容 agent 自动注册。 - 技能通过
[environment].skills_dir暴露给兼容 agent。 - Harbor 的立场：工具属于 agent；环境侧提供工具只能走 MCP、skills、API、CLI 四种形式。
- 外部服务优先 mock 或用官方沙箱模式；直连时用
[agent].allowed_hosts收紧出网。 - 特殊路径：
/logs/verifier/（reward）、/logs/agent/（agent 日志）、/solution/、/tests/；/logs/会在 Trial 结束后同步回宿主机。 - 资源字段（
cpus、memory_mb、storage_mb、gpus、tpu）全部可选，省略时由 provider 决定。 artifacts把环境内文件快照到 trial artifacts 目录，是产出物的标准出口。