第 3 章
第 3 章：task.toml——任务配置全字段参考
第 3 章：task.toml——任务配置全字段参考
task.toml是任务目录中唯一的配置文件，控制着超时、资源、网络、判分方式等一切行为开关。本章以 schema 1.3 为基准，逐段讲清每个配置段的用途与字段，可作为你编写任务时的速查手册。
全景示例
先看一个覆盖了大部分常用段的完整示例：
schema_version = "1.3"
[task]
name = "apple/create-unix-os"
authors = [{ name = "Steve Jobs", email = "steve@apple.com" }]
[metadata]
difficulty_explanation = "Trivial task for demonstration"
category = "programming"
[verifier]
timeout_sec = 120.0
env = { API_KEY = "sk-test-123" }
user = "root" # optional: run the verifier as this OS user
[agent]
timeout_sec = 120.0
user = "agent" # optional: run the agent as this OS user
[solution]
env = { API_KEY = "sk-test-123" }
[environment]
network_mode = "allowlist" # baseline; defaults to "public" when omitted
allowed_hosts = ["pypi.org"]
docker_image = "apple/unix-os:latest"
cpus = 1
memory_mb = 2048
storage_mb = 10240一个总体设计原则：Harbor 尽量把配置推迟到 environment/ 规格文件里（如 Dockerfile），因为这类文件已有成熟的工程惯例。只有当惯例缺失或存在常见踩坑时，才要求写进 task.toml。
[environment] 与 environment/ 的分工
官方文档列出了必须写进 task.toml 的少数 environment 字段及其存在理由：
| 字段 | 说明 |
|---|---|
environment.docker_image |
指定环境使用的 Docker 镜像；设置后可完全省略 environment/ 目录 |
environment.network_mode |
网络隔离模式（如 public、allowlist） |
environment.allowed_hosts |
当 network_mode 为 allowlist 时，允许出网访问的域名/IP 列表 |
environment.env |
注入环境的环境变量 |
environment.healthcheck |
检查环境是否健康/就绪的配置 |
environment.workdir |
环境中命令执行的工作目录；为免重建镜像而补设 workdir 而生 |
通用字段
位于文件顶层、不属于任何段的字段：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
schema_version |
string | "1.3" |
任务配置格式的版本号 |
multi_step_reward_strategy |
"mean" | "final" | null |
null | 多步任务中如何从各步 verifier 结果汇总 trial 级 reward；仅在设置 [[steps]] 时生效，多步默认 "mean"，单步任务应留空 |
[task] 与 [metadata]
[task] 段承载注册表包元数据，是可选段；一旦声明，task.name 必填。
| 字段 | 说明 |
|---|---|
task.name |
包名，org/name 格式（如 harbor/hello-world）；声明 [task] 时必填 |
task.authors |
作者列表，每项含必填 name 与可选 email |
task.description |
人类可读的任务描述，默认 "" |
task.keywords |
用于搜索和分类的关键词列表 |
[metadata] 段最自由：metadata 就是一个 object，可以放任务作者想要的任意元数据（难度说明、分类标签等），Harbor 不做结构约束。
[verifier]：判分配置
| 字段 | 默认值 | 说明 |
|---|---|---|
verifier.timeout_sec |
600 | verifier 超时秒数 |
verifier.network_mode |
null（不覆盖） | verify 阶段的网络覆盖项：no-network / public / allowlist，仅在设置且与 verifier 基线不同时生效 |
verifier.allowed_hosts |
null | allowlist 模式下的放行主机名 |
verifier.env |
{} |
运行 verifier 时设置的环境变量 |
verifier.user |
null | 以哪个 OS 用户/UID 运行 verifier；不设则用容器默认用户（通常为 root） |
verifier.environment_mode |
null | verifier 运行位置：shared 复用 agent 容器（未声明 [verifier.environment] 时的默认）；separate 启动独立 verifier 容器。声明了 [verifier.environment] 而不写此字段即隐含 separate；与 [verifier.environment] 同时声明 shared 是校验错误 |
verifier.environment |
null | 可选的 verifier 专属环境配置，schema 与 [environment] 相同；其镜像与 tests/ 构建定义优先于 agent 环境 |
verifier.environment 下的 network_mode 默认为 "public"，allowed_hosts 语义与主环境一致。
[agent] 与 [solution]
| 字段 | 默认值 | 说明 |
|---|---|---|
agent.timeout_sec |
null | agent 超时秒数；不设则不强制超时 |
agent.network_mode |
null（不覆盖） | agent.run() 期间的覆盖项，仅在设置且与 [environment] 不同时生效 |
agent.allowed_hosts |
null | allowlist 模式下的放行主机名 |
agent.user |
null | 以哪个 OS 用户/UID 运行 agent；设置后会先配置环境默认用户再执行 agent |
solution.env |
{} |
Oracle 执行 solution 时设置的环境变量 |
[environment]：环境全字段
镜像、系统与路径类：
| 字段 | 默认值 | 说明 |
|---|---|---|
build_timeout_sec |
600 | 环境构建超时秒数 |
network_mode |
"public" |
agent 环境的网络基线，可选 no-network / public / allowlist |
allowed_hosts |
null | allowlist 模式下的放行主机名 |
docker_image |
null | 预构建镜像；设置后受支持的环境类型可省略 environment/Dockerfile |
os |
"linux" |
目标操作系统，linux 或 windows；windows 时启用 Windows 风格路径、cmd.exe 执行等，启动时会校验镜像 OS，不匹配快速失败 |
workdir |
null | 环境中命令执行的默认工作目录，设置后覆盖容器 WORKDIR |
allow_internet |
null | 已废弃的兼容字段，优先用 network_mode；false 映射 no-network，true 映射 public |
资源类（均可省略，省略时由所选 provider 决定尺寸）：
| 字段 | 默认值 | 说明 |
|---|---|---|
cpus |
null | 请求的 CPU 核数 |
memory_mb |
null | 请求的内存（MB） |
storage_mb |
null | 请求的存储（MB） |
gpus |
null | 请求的 GPU 数量，不设则不请求 GPU |
gpu_types |
null | 可接受的 GPU 型号列表（如 ["H100", "A100", "T4"]），null 表示不限型号 |
tpu |
null | TPU slice 规格（type + topology），仅在支持 TPU 的环境（目前为 GKE）可用 |
tpu 是一张小表，两个字段都有讲究：
| 字段 | 说明 |
|---|---|
tpu.type |
加速器类型，可用友好别名（v6e、trillium、v4）或 GKE 规范标签（tpu-v6e-slice、tpu7x） |
tpu.topology |
拓扑，NxM 或 NxMxK（如 2x4、2x2x1）；必填——GKE 的隐式默认拓扑不属于稳定契约，省略会导致跨 GKE 版本不可复现；每 pod 芯片数 = 各维乘积 |
工具注入类字段（env、mcp_servers、skills_dir、healthcheck）与 artifacts 涉及较多机制，集中在第 4 章展开，这里先给出速查要点：
| 字段 | 默认值 | 说明 |
|---|---|---|
env |
{} |
任务所需环境变量，运行时从宿主机解析，支持 {VAR:-default} 模板语法 |
mcp_servers |
— | 以 [[environment.mcp_servers]] 声明的 MCP 服务器列表，兼容 agent 自动注册 |
skills_dir |
null | 环境内 skills 目录路径，内容会注册给兼容 agent |
healthcheck |
null | 环境启动后的健康检查配置块；省略整段即禁用 |
artifacts |
[] |
需要从环境快照到 trial artifacts 目录的根级路径列表 |
[[environment.mcp_servers]] 每项的字段：
| 字段 | 默认值 | 说明 |
|---|---|---|
name |
— | 每项唯一名称 |
transport |
"sse" |
连接方式：stdio / sse / streamable-http；旧值 http 会被规范化为 streamable-http |
url |
null | sse / streamable-http 传输的端点 URL（必填），如 Compose sidecar 的 http://mcp-server:8000/mcp |
command |
null | stdio 传输要启动的可执行文件（必填） |
args |
[] |
stdio 传输传给 command 的参数列表 |
[environment.healthcheck] 的字段与默认值：
| 字段 | 默认值 | 说明 |
|---|---|---|
command |
—（必填） | 环境启动后运行的 shell 命令，退出码 0 表示健康 |
interval_sec |
5 | 两次尝试的间隔秒数 |
timeout_sec |
30 | 单次检查命令的最大时长 |
start_period_sec |
0 | 启动宽限期，期间失败不计入 |
start_interval_sec |
5 | 宽限期内两次检查的间隔秒数 |
retries |
3 | 连续失败多少次判定健康检查失败 |
Artifacts 与 Provenance
artifacts 列表的每项既可以是容器路径字符串（等价于只写 source），也可以是表格：
| 字段 | 默认值 | 说明 |
|---|---|---|
source |
—（表格项必填） | 要下载的容器内路径（文件或目录） |
destination |
null | trial artifacts 目录下的相对路径；省略时 Harbor 从 source 推导宿主机路径 |
exclude |
[] |
source 为目录时的 glob 排除模式（以 tar --exclude 传参） |
单步任务在 verification 之后收集一次；多步任务每一轮收集都会包含这些根级路径，步骤级路径用 [[steps]].artifacts 声明。
Provenance 只有一个字段：顶层 source（string，默认 null），用于记录任务的来源信息。
多步配置与 TOML 模板
多步任务通过 [[steps]] 数组扩展，每一步可覆盖 agent、verifier、healthcheck、min_reward、artifacts，配合步骤内的 workdir/setup.sh 与 trial 级 reward 汇总（multi_step_reward_strategy）使用。
手工编写任务时，可以用模板预先填充 task.toml：模板中的段会覆盖 Harbor 内置默认值，未指定的字段回落到本章列出的默认值。
harbor task init [org]/[name] --metadata-template task-template.toml本章小结
task.toml是任务唯一配置文件，当前 schema 版本为1.3。- 设计原则：能写进
environment/规格的配置尽量不写进task.toml；docker_image、network_mode、allowed_hosts、env、healthcheck、workdir是少数例外。 [task]是可选段，声明后task.name（org/name格式）必填；[metadata]完全自由。- 超时语义不同：
verifier.timeout_sec默认 600，而agent.timeout_sec不设则不限时。 - verifier 默认与 agent 共享容器（
shared），声明[verifier.environment]即切换为独立 verifier 容器（separate）。 - 资源字段
cpus/memory_mb/storage_mb/gpus省略时由 provider 决定；tpu.topology必填以保证可复现。 allow_internet已废弃，统一改用network_mode（no-network/public/allowlist）。healthcheck省略整段即禁用；env支持{VAR:-default}模板。- 用
--metadata-template传入 TOML 模板可预填task.toml，未指定字段回落默认值。