create-task

引导用户端到端创建一个新的 Harbor 任务。不要只罗列命令，而要逐步引导用户做出每项决定，尤其是验证器的选择（这通常是最难的部分）。

步骤 1：搭建任务框架

harbor task init "<org>/<task-name>"

实用标志：

• --description "..."
• --author "Jane Doe <[email protected]>"（可重复指定多个作者）
• --no-pytest — 跳过 pytest 测试模板（计划使用 Reward Kit 或自定义验证器时使用）
• --no-solution — 跳过 solution/ 目录
• --metadata-template path.toml — 预先填入 task.toml

生成的内容：

<task-name>/
├── instruction.md         # Task prompt for the agent
├── task.toml              # Config and metadata
├── environment/Dockerfile # Container definition
├── solution/solve.sh      # Reference solution (optional)
└── tests/test.sh          # Verifier script

如果用户想创建多步骤任务（在共享容器中按顺序执行步骤，包含每步的说明和测试，并可提前停止），先搭建单步骤布局，再转换为下文 多步骤任务 部分所述的 steps/ 布局。

步骤 2：编写 instruction.md

这是 Agent 收到的提示词。帮助用户清晰地编写说明：

• 明确说明目标 — 要创建什么文件、要实现什么行为
• 指定预期输出 — 路径、格式、内容
• 列出约束 — 语言、工具、方法
• 不要泄露测试内容 — 描述怎样才算“完成”，而不是如何检查

示例（摘自 ssh-key-pair 教程）：

# SSH Key Pair Generation

Generate an SSH key pair in the files `~/.ssh/id_rsa` and `~/.ssh/id_rsa.pub`.

Don't make them password protected.

步骤 3：构建环境

编辑 environment/Dockerfile，安装任务所需的依赖。Agent 将在此容器中工作。

FROM ubuntu:24.04
WORKDIR /app

# Install what the task requires — NOT the solution
RUN apt-get update && apt-get install -y openssh-client && rm -rf /var/lib/apt/lists/*

对于多容器配置，请改用 environment/docker-compose.yaml（注意：大多数云端沙盒提供商仅支持 Dockerfile）。

在编写解决方案或测试之前，先以交互方式测试环境：

harbor task start-env -p "<task-path>" -e docker -a -i

通常，任务作者会在这一步发现 Dockerfile 中缺少内容。

步骤 4：决定如何验证

这是最重要的决定。 询问用户：“你想如何为此任务评分？” 然后帮助用户选择：

还要询问：“验证器应该与 Agent 在同一环境中运行，还是在单独的验证器环境中运行？”

• 如果测试需要检查 Agent 的整个工作区、已安装的工具或服务，请使用默认的共享环境。
• 如果评分时需要对代码、依赖项、API 密钥或操作系统要求保密，不让 Agent 知道，或者验证应在干净的镜像中运行，请使用单独的验证器环境。

对于单独的验证器容器，tests/ 是验证器镜像的构建上下文，且镜像必须提供 /tests/test.sh（Linux）或 /tests/test.bat（Windows）。Harbor 会将 /logs/artifacts 和已配置的制品复制到验证器环境中，而不会复制 Agent 的整个工作区。

[verifier]
environment_mode = "separate"

[verifier.environment]
docker_image = "ubuntu:24.04"

选项 A：Reward Kit（大多数情况下推荐）

适用于验证器包含多项标准、需要部分得分、使用 LLM/Agent 评审，或适合组合可复用检查的情况。参见 rewardkit 技能。

适用情况：

• 有多项检查内容（文件存在 + 内容正确 + 命令可运行）
• 涉及主观质量维度（可读性、文本正确性）
• 希望获得部分得分，而不是只有通过/不通过
• 希望组合使用 file_contains、command_succeeds、json_key_equals 等内置检查

tests/test.sh：

#!/bin/bash
uvx --python '>=3.12,<3.14' --from 'harbor-rewardkit==0.2.*' rewardkit /tests

注意：该包的名称是 harbor-rewardkit，但可执行文件名为 rewardkit，因此使用 --from 'harbor-rewardkit==0.2.*' rewardkit。直接运行 uvx harbor-rewardkit 会失败。

然后添加 tests/checks.py 和/或 tests/judge.toml。调用 rewardkit 技能来设计评分标准。

选项 B：pytest（适合确定性的单元测试式检查）

适用于验证逻辑简单，可通过 Python 断言完成的情况。如果未传入 --no-pytest，则默认使用此模板。

tests/test.sh：

#!/bin/bash
apt-get update && apt-get install -y curl
curl -LsSf https://astral.sh/uv/0.9.7/install.sh | sh
source $HOME/.local/bin/env

uvx --with pytest==8.4.1 pytest /tests/test_outputs.py

if [ $? -eq 0 ]; then
  echo 1 > /logs/verifier/reward.txt
else
  echo 0 > /logs/verifier/reward.txt
fi

tests/test_outputs.py 示例：

from pathlib import Path

def test_file_exists():
    assert (Path.home() / ".ssh" / "id_rsa").exists()

选项 C：自定义 shell

适用于简单的单命令检查（例如通过一条命令得出二元的通过/不通过结果）：

#!/bin/bash
if diff -q /app/output.txt /tests/expected.txt; then
  echo 1 > /logs/verifier/reward.txt
else
  echo 0 > /logs/verifier/reward.txt
fi

Reward 文件格式（所有选项）

• /logs/verifier/reward.txt — 单个数字（通常为 0 或 1）
• /logs/verifier/reward.json — 多项指标的格式：{"accuracy": 0.95, "runtime_sec": 1.2}

在 test.sh 中始终使用绝对路径。

第 5 步：编写解决方案

编写 solution/solve.sh — 一个实际解决任务的脚本。Oracle Agent 会运行此脚本，以进行健全性检查，确认任务可解且测试能在正确的解决方案上通过。

#!/bin/bash
ssh-keygen -t rsa -f ~/.ssh/id_rsa -N ""

使其可执行：chmod +x solution/solve.sh。

第 6 步：配置 task.toml

逐一了解重要字段：

[task]
name = "<org>/<task-name>"
version = "1.0.0"
description = "One-line description"
keywords = ["jax", "mnist", "rewardkit"]  # always populate — used for search/filtering

[metadata]
difficulty = "easy" | "medium" | "hard"
category = "programming" | "machine-learning" | "gpu" | ...
tags = ["..."]

[agent]
timeout_sec = 120.0       # How long the agent has

[verifier]
timeout_sec = 600.0       # How long tests have

[environment]
network_mode = "public"   # Baseline at env start (defaults to public)
cpus = 1                  # CPU cores
memory_mb = 2048          # RAM in MB
storage_mb = 10240        # Disk in MB

务必填写 keywords。 选择 3–8 个小写词条，涵盖领域（语言／框架／基准测试系列）、验证器类型（rewardkit、judge-grading、pytest）以及任何值得注意的硬件（gpu）。这些词条会显示在 harbor datasets list 和注册表搜索结果中。

网络策略

网络访问分为三层：

1. 基线 — 环境启动时设置，并在各阶段之间恢复
2. 阶段覆盖 — 可选；仅在 agent.run() 或 verify() 期间生效
3. 运行时合并 — 在 harbor run 中使用 --allow-environment-host、--allow-agent-host、--allow-verifier-host

字段	层级	生效时机
[environment].network_mode	基线	Agent 环境启动时；共享验证器也使用此设置
[verifier.environment].network_mode	基线	独立验证器环境启动时
[agent].network_mode、[steps.agent].network_mode	覆盖	对应的 agent.run() 期间
[verifier].network_mode、[steps.verifier].network_mode	覆盖	对应的 verify() 期间
--allow-environment-host	运行时	合并到 environment.extra_allowed_hosts → [environment] 基线
--allow-agent-host	运行时	合并到 agent.extra_allowed_hosts → Agent 阶段允许列表
--allow-verifier-host	运行时	合并到 verifier.extra_allowed_hosts → 验证器阶段允许列表（以及独立验证器环境基线）

模式：public、no-network，或使用 allowed_hosts = ["pypi.org"] 的 allowlist（精确主机名、IPv4／IPv6 地址字面量或 CIDR 网段，或者前导通配符主机名；具体取决于所选环境的支持情况；不能是 URL、端口或路径）。省略 [environment].network_mode 时，默认值为 public。

[agent]／[verifier] 是可选的阶段覆盖设置 — 仅当设置了该项且其值与阶段基线不同时才会应用。与基线相同则不执行任何操作。

共享验证器（默认）：验证器在 Agent 容器中运行；基线为 [environment]。独立验证器：如果设置了 [verifier.environment]，则使用该项作为基线；否则使用 [environment] 的副本。

# Agent starts offline; agent phase opens network; verifier stays offline
[environment]
network_mode = "no-network"

[agent]
network_mode = "public"

[verifier]
network_mode = "no-network"

如果阶段覆盖与其基线不同，环境提供方必须支持 dynamic_network_policy（E2B 支持；普通 Docker 不支持）。如果 Agent 和验证器需要不同的基线，但无需在运行时切换，优先使用 environment_mode = "separate"：

[environment]
network_mode = "no-network"

[verifier]
environment_mode = "separate"

[verifier.environment]
network_mode = "public"   # Verifier baseline — not a phase override

无需编辑 task.toml 即可为评估任务设置运行时主机标志：

harbor run -p "<task-path>" -a oracle \
  --allow-environment-host pypi.org \   # env start (Dockerfile apt/curl)
  --allow-agent-host files.pythonhosted.org \  # agent.run() only
  --allow-verifier-host llm-proxy.example.com   # verify() only (e.g. LLM judge proxy)

如果基线为 public，运行时主机标志会发出警告并被忽略。

示例：examples/tasks/network-policy-matrix/。完整参考文档： docs-mintlify/tasks/network-policies.mdx。

对于需要 API 密钥的 Reward Kit judge：

[verifier.env]
ANTHROPIC_API_KEY = "${ANTHROPIC_API_KEY}"

第 7 步：使用 Oracle Agent 验证

harbor run -p "<task-path>" -a oracle

Oracle 会运行 solution/solve.sh，然后运行验证器。Reward 应为 1.0。如果不是，请按以下顺序排查：

1. solve.sh 是否确实能解决任务？（使用 start-env -a -i 并手动运行）
2. 验证器是否能正确检测成功？（检查 /logs/verifier/ 输出）
3. 路径是否正确？（绝对路径还是相对路径）
4. Dockerfile 中是否安装了依赖？

第 8 步：使用真实 Agent 测试（可选）

harbor run -p "<task-path>" -a terminus-2 -m anthropic/claude-sonnet-4-6

如果任务太简单（每个模型的得分都是 1.0）或无法完成（每个模型的得分都是 0.0），可考虑调整难度。

第 9 步：更新 README.md（始终是最后一步）

harbor task init 会将 README.md 留作占位文件。收尾之前，请填写该文件，让今后查看的开发者（和 Agent）无需阅读每个文件就能了解任务。 请包含：

• Agent 的工作 — 用一段话说明，并链接到 instruction.md。
• 环境 — 基础镜像、安装的关键软件包、缓存数据、硬件（GPU/CPU/RAM）、Agent 超时时间。
• 验证器 — 对于 Reward Kit 任务，提供奖励维度表，列出类型（程序化 / LLM 评判 / Agent 评判）以及各维度的衡量内容；说明如何聚合。
• 目录布局 — 任务目录树，并为每项添加一行注释。
• 运行 — 具体的 harbor run 命令（Oracle + 真实 Agent）；如果任务需要 GPU，请使用正确的 provider 标志。

请把它当作文档，而不是宣传材料——读者想知道修改任务需要改动哪些内容。

多步骤任务

适用于工作分为有序阶段且需要分别评分、希望在阶段之间提前停止，或要测试 Agent 能否基于自己之前的成果继续工作的场景。所有步骤共用一个容器；文件会在步骤间保留。

目录布局

将任务根目录下的 instruction.md、tests/ 和 solution/ 替换为包含每个步骤子目录的 steps/ 目录：

每个 [[steps]].name 都必须与一个目录名一致，长度不超过 255 个 UTF-8 字节，且经过大小写折叠和 Unicode 规范化后仍唯一。避免使用路径分隔符、控制字符、Windows 保留字符或设备名称，以及以点或空格结尾的名称。所有任务输入和链接内容都必须位于任务目录内；验证允许在任务内部使用共享链接。发布任务时，共享输入请使用常规文件和目录。

<task-name>/
├── task.toml
├── environment/Dockerfile       # Built once, shared across all steps
├── steps/
│   ├── scaffold/
│   │   ├── instruction.md       # Prompt for this step
│   │   ├── workdir/             # Uploaded to WORKDIR before the agent runs
│   │   │   └── setup.sh         # Optional pre-agent hook (reserved filename)
│   │   ├── tests/test.sh        # Per-step verifier
│   │   └── solution/solve.sh    # Per-step Oracle solution (optional)
│   ├── implement/
│   │   └── ...
│   └── document/
│       └── ...
└── tests/                       # Optional shared helpers + fallback test.sh

任务级 tests/ 会上传到每个步骤的 /tests 目录用于验证，然后再叠加该步骤自己的 tests/（同名文件优先）。可用此方式放置共享辅助文件。

steps/{name}/workdir/setup.sh 是保留文件名：如果存在，它会在上传 workdir/ 后、Agent 运行前，以该步骤的 Agent 用户身份执行，且 cwd = WORKDIR。若退出码非零，该步骤和整个试验都会中止。如果不希望 Agent 看到此文件，请在最后一行使用 rm -- "$0" 删除它。

task.toml

schema_version = "1.4"

# How per-step rewards roll up into the trial-level verifier_result.
# "mean" (default): per-key mean across steps that produced a result.
# "final": the last step's verifier_result verbatim.
multi_step_reward_strategy = "mean"

[task]
name = "<org>/<task-name>"
version = "1.0.0"

[[steps]]
name = "scaffold"              # Must match the directory under steps/
min_reward = 1.0               # Abort trial if this step's reward < 1.0
[steps.agent]
timeout_sec = 60.0             # Overrides task-level [agent].timeout_sec
[steps.verifier]
timeout_sec = 30.0

[[steps]]
name = "implement"
# Dict form gates on specific keys from a multi-dim reward:
min_reward = { correctness = 0.8, style = 0.5 }
[steps.agent]
timeout_sec = 120.0
[steps.verifier]
timeout_sec = 30.0

[[steps]]
name = "document"
[steps.agent]
timeout_sec = 60.0
[steps.verifier]
timeout_sec = 30.0

可按步骤覆盖的字段：agent.timeout_sec、agent.user、agent.network_mode、verifier.timeout_sec、verifier.env、verifier.user、verifier.network_mode、verifier.environment_mode、verifier.environment、steps.verifier.environment.network_mode、healthcheck.*、artifacts。未设置的字段将回退到任务级值。

选择奖励策略

• "mean" — 聚合所有步骤的信号；适用于持续进度奖励。
• "final" — 将最后一个步骤的 verifier_result 作为试验奖励。适用于最后一步是端到端检查，且其字典已代表整个任务的情况。注意：如果 min_reward 触发提前中止，"final" 使用的是中止步骤的结果，而不是预期最后一步的结果。

工件

步骤级 artifacts 会在该步骤验证后收集到 steps/{name}/artifacts/。除步骤级工件外，每个步骤也会收集任务级和试验级工件。

Oracle 验证

harbor run -p "<task-path>" -a oracle 会按顺序运行每个步骤的 solution/solve.sh，然后运行每个步骤的验证器。根据所选聚合策略，试验奖励应为 1.0。

完整参考与示例

• 文档：docs-mintlify/tasks/multi-step.mdx
• 示例任务：examples/tasks/hello-multi-step-advanced/

特殊功能（相关时请提及）

• 网络策略：在 [environment] / [verifier.environment] 中设置基线；在 [agent] / [verifier] 中设置阶段覆盖项；参见第 6 步中的网络策略
• MCP 服务：在 task.toml 中添加 [[environment.mcp_servers]]，以提供 Agent 工具
• 健康检查：对于需要就绪的服务，添加 [environment.healthcheck]
• GPU：设置 environment.gpus，并可选择设置 environment.gpu_types
• 预构建镜像：设置 environment.docker_image，而不是从 Dockerfile 构建。可以省略 environment/Dockerfile，并将运行时文件（配置、脚本、数据）直接放在 environment/ 下。环境启动时，Harbor 会将这些文件上传到容器工作目录。
• 非 root 用户：设置 agent.user / verifier.user 以实现隔离

常见陷阱

• 忘记写入奖励文件 → 任务会悄无声息地“通过”，奖励为 0
• 在 test.sh 中使用相对路径 → Harbor 从其他 cwd 运行脚本时会出错
• 将解决方案安装到 Dockerfile 中 → Agent 会直接得到答案
• 测试脚本泄漏到 instruction.md 中 → Agent 会看到评分标准，轻易就能钻空子
• 忘记执行 chmod +x solution/solve.sh → Oracle Agent 会失败
• 在 task.toml 中保留 keywords = [] → 通过注册表搜索时无法找到该任务
• 将 README.md 留作空壳 → 队友无法快速了解任务
• 在 [agent] 上设置 network_mode，并期望它在环境启动时生效 → 基线应使用 [environment].network_mode；agent/verifier 字段是阶段覆盖项
• 在 Docker 上，阶段覆盖项与基线不同 → 除非提供方支持 dynamic_network_policy，否则任务会被拒绝；请使用独立的 verifier 环境，或使其与基线一致