【免费下载链接】harborFramework for evaluating and improving agents项目地址https://gitcode.com/gh_mirrors/harbor17/harbor点击查看免费下载Harbor 是一个用于评估与改进 Agent 的框架而skills/create-task/SKILL.md给出了创建新 Harbor 任务benchmark problem / eval的完整流程。本文以该技能文档为骨架结合仓库内harbor task init等 CLI 实现、template-task脚手架模板与examples/tasks/下的真实示例系统讲解如何从零设计一个可评测的 Harbor 任务包括 instruction 编写、容器环境构建、验证器verifier三大方案选型、task.toml网络策略配置、Oracle 验证与多步任务设计。读完本文你将能够独立完成一个可运行、可发布、可被harbor run评测的完整任务。整体流程概览一个 Harbor 任务的创建是一个九步闭环核心决策点集中在验证器设计通常也是难度最高的部分。整体流程为Scaffoldharbor task init生成任务目录骨架编写 instruction.md即 Agent 收到的任务提示词构建环境编写environment/Dockerfile并用harbor task start-env交互式验证决定验证方案Reward Kit / pytest / 自定义 shell 三选一并决定共享环境还是独立验证环境编写 solution/solve.sh参考解法供 Oracle Agent 冒烟测试配置 task.toml资源、超时、网络策略、关键字等Oracle 验证harbor run -a oracle确认任务可解、测试可过真实 Agent 测试观察难度是否合理完善 README.md让未来的开发者和 Agent 能快速理解任务。下面按步骤深入。Step 1Scaffold 任务骨架创建任务的第一步是使用harbor task init生成标准目录结构harbor task init org/task-name任务名必须符合org/name格式。从源码看该命名规则由 src/harbor/models/task/config.py 中的PackageInfo.validate_name_format强制校验只允许字母数字、连字符、下划线与点号且不能以点开头或包含..org与short_name属性分别用于提取组织名与任务短名。常用参数详解CLI 实现位于 src/harbor/cli/tasks.py 的init命令除--org、-p/--tasks-dir等基础参数外常用参数如下参数作用--description ...任务一句话描述写入task.toml的[task].description--author Jane Doe janeexample.com作者信息可重复传入支持Name email与纯Name两种格式由_parse_authors解析--no-pytest跳过 pytest 测试模板改用 Reward Kit 或自定义 verifier 时使用--no-solution跳过solution/目录--metadata-template path.toml用模板 TOML 预填充task.toml--steps N直接以 N 个 step 脚手架一个多步任务--include-canary-strings在任务文件中注入 canary 字符串防止评测数据污染训练语料从 src/harbor/cli/init.py 的实现可以确认两个易被忽略的细节当未通过--metadata-template指定 agent 超时时_init_task会默认将agent.timeout_sec设为 600.0 秒--metadata-template中的metadata、verifier、agent、environment各节会被合并进生成的task.toml因此它是团队标准化任务配置的推荐入口。生成的任务结构单步任务初始化后得到如下布局与 src/harbor/cli/template-task/ 模板一致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如果你需要的是一个多步任务按顺序执行、每步有独立指令/测试/提前终止、共享同一个容器先按单步布局 scaffold再按下文《多步任务》章节转换为steps/布局。Step 2编写 instruction.mdinstruction.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. Dont make them password protected.仓库中 examples/tasks/hello-world/instruction.md 展示了更极致的形态Create a file called hello.txt with Hello, world! as the content.一句话即是一个完整任务。注意如果测试脚本泄露进instruction.mdAgent 看到评分细则后刷分将变得极其容易这是创建任务时最需要防住的泄露点。Step 3构建环境编辑environment/Dockerfile安装任务所需依赖Agent 将在该容器内工作。模板默认基于ubuntu:24.04见 src/harbor/cli/template-task/environment/DockerfileFROM 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/*两个关键原则只安装任务所需依赖绝不安装解法依赖——把答案装进 Dockerfile 等于让 Agent 直接拿到答案需要多容器时用environment/docker-compose.yaml注意多数云 sandbox 提供商只支持 Dockerfile。交互式测试环境在编写 solution 与测试之前先用交互模式启动环境这一步往往能暴露 Dockerfile 缺依赖的问题harbor task start-env -p task-path -e docker -a -istart-env的实现位于 src/harbor/cli/tasks.py默认-e docker也可传入自定义环境导入路径module.path:ClassName-a会把solution/与tests/上传进环境-i进入交互模式启动时还会强制重建镜像force_buildTrue若配置了 healthcheck 会先执行健康检查再附加会话。Step 4决定验证方案最关键决策这是整个任务设计中最重要的一步。先问自己两个问题这个任务该怎么打分决定用 Reward Kit、pytest 还是自定义 shell验证器应该跑在 Agent 的同一环境里还是独立的验证环境里共享环境 vs 独立验证环境默认共享环境适合测试需要检查 Agent 完整工作区、已安装工具或服务的情况独立验证环境environment_mode separate适合代码、依赖、API Key 或 OS 要求需要向 Agent 隐藏的场景也适合从干净镜像出发做验证。独立验证容器时tests/目录即验证镜像的构建上下文镜像必须提供/tests/test.shLinux或/tests/test.batWindows。Harbor 只把/logs/artifacts和配置的 artifacts 复制进验证环境不会复制 Agent 的整个工作区[verifier] environment_mode separate [verifier.environment] docker_image ubuntu:24.04从 src/harbor/models/task/config.py 的VerifierConfig源码可确认其默认行为未显式声明environment_mode时若设置了[verifier.environment]则默认separate否则默认shared而environment_modeshared与[verifier.environment]同时出现会直接报错。Option AReward Kit多数情况推荐当验证器有多条判据、需要部分得分、使用 LLM/Agent 评判或希望复用可组合检查项时优先选择 Reward Kit。适合场景信号需要检查多个方面文件存在 内容正确 命令可运行存在主观质量维度可读性、文本正确性想要部分得分而非简单通过/失败想组合内置判据如file_contains、command_succeeds、json_key_equals。tests/test.sh入口#!/bin/bash uvx --from harbor-rewardkit0.2.* rewardkit /tests易错点包名是harbor-rewardkit但可执行文件叫rewardkit所以必须写--from harbor-rewardkit0.2.* rewardkit直接uvx harbor-rewardkit会失败。仓库 examples/tasks/reward-kit-example/tests/test.sh 即是这一形态。随后在tests/下补充checks.py程序化判据和/或judge.tomlLLM 评判判据设计可参阅 skills/rewardkit/SKILL.md。Reward Kit 会把/tests/下的判据跑在/app工作区并写出/logs/verifier/reward.json默认约定与 Harbor 一致、无需额外配置。程序化判据可直接调用内置函数import rewardkit as rk rk.file_exists(output.txt) rk.file_contains(output.txt, hello) rk.command_succeeds(python main.py, weight2.0) rk.json_key_equals(result.json, status, ok)内置判据覆盖文件file_exists、file_contains_regex、files_equal等、命令command_succeeds、command_output_matches等、数据json_key_equals、csv_cell_equals、sqlite_query_equals等、HTTPhttp_status_equals、图片image_similarity与轨迹trajectory_tool_used等类别需要 LLM 评判的 judge 判据若调用外部 API需在验证环境配置public基线或 allowlist。Option Bpytest确定性单测风格验证逻辑是直白的断言式 Python 时使用若未传--no-pytest这是默认模板。模板内容见 src/harbor/cli/template-task/pytest-tests/#!/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 pytest8.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.pyfrom pathlib import Path def test_file_exists(): assert (Path.home() / .ssh / id_rsa).exists()从 examples/tasks/hello-world/tests/test.sh 可以看到生产级版本会在 pytest 基础上叠加pytest-json-ctrf输出标准 CTRF 报告--ctrf /logs/verifier/ctrf.json便于日志与结果归档。Option 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 fiReward 文件格式所有方案通用文件含义/logs/verifier/reward.txt单个数值通常为0或1/logs/verifier/reward.json多指标{accuracy: 0.95, runtime_sec: 1.2}test.sh中务必使用绝对路径——Harbor 可能从不同 cwd 执行该脚本。另需注意test.sh必须在每个代码路径上都重写 reward 文件绝不能信任 Agent 运行期间可能写入的旧 reward 文件这是 src/harbor/cli/adapter_review.py 中明确的适配器审查要求。Step 5编写 solutionOracle 参考解法编写solution/solve.sh——一个真正能解出任务的脚本。Oracle Agent 会执行它来做冒烟测试确认任务可解、测试能通过正确解法#!/bin/bash ssh-keygen -t rsa -f ~/.ssh/id_rsa -N 务必执行chmod x solution/solve.sh——漏掉这一步 Oracle Agent 会直接失败。另外harbor task init的模板中solve.sh只有注释占位见 src/harbor/cli/template-task/solution/solve.sh需要作者自行填充。Step 6配置 task.tomltask.toml是任务的配置与元数据中枢核心字段如下完整 schema 可通过harbor task schema输出 JSON Schema由 src/harbor/models/task/config.py 的TaskConfig定义[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 MBkeywords必须填充。选取 3–8 个小写 token覆盖领域语言/框架/benchmark 家族、验证器风格rewardkit、judge-grading、pytest以及特殊硬件gpu。它们会出现在harbor datasets list与 registry 搜索中——keywords []会让任务对搜索不可见。EnvironmentConfig还支持更多字段源码见 src/harbor/models/task/config.pybuild_timeout_sec默认 600 秒、docker_image预构建镜像、oslinux/windows、gpus与gpu_types、tpu、mcp_servers、env支持${VAR}与${VAR:-default}模板语法、healthcheck、workdir、network_mode/allowed_hosts。旧的memory/storage/allow_internet字段已弃用并自动迁移到memory_mb/storage_mb/network_mode迁移逻辑在EnvironmentConfig._migrate_legacy_resource_fields中可接受2G这类字符串并换算成 MB。网络策略三层体系网络访问控制分为三层Baselines基线——环境启动时设定阶段之间恢复Phase overrides阶段覆盖——可选仅在agent.run()或verify()期间生效Run-time merges运行时合并——harbor run上的--allow-environment-host、--allow-agent-host。字段层级生效时机[environment].network_modeBaselineAgent 环境启动共享验证器同样使用[verifier.environment].network_modeBaseline独立验证环境启动[agent].network_mode、[steps.agent].network_modeOverride对应的agent.run()期间[verifier].network_mode、[steps.verifier].network_modeOverride对应的verify()期间--allow-environment-hostRun-time合并进environment.extra_allowed_hosts→[environment]基线--allow-agent-hostRun-time合并进agent.extra_allowed_hosts→ Agent 阶段允许列表模式public、no-network、或allowlist配合allowed_hosts [pypi.org]支持精确主机名、IPv4/IPv6 地址字面量或 CIDR 范围、以及环境支持时前导通配符主机名不是URL、端口或路径。省略[environment].network_mode时默认为public对应BaselineNetworkPolicyConfig.network_mode的默认值。[agent]/[verifier]是可选的阶段覆盖——仅当设置且与阶段基线不同时才生效与基线相同则是 no-op。共享验证器默认验证器运行在 Agent 容器内基线为[environment]。独立验证器基线为[verifier.environment]若设置否则复制[environment]。典型场景——Agent 离线启动、Agent 阶段开放网络、验证器保持离线[environment] network_mode no-network [agent] network_mode public [verifier] network_mode no-network重要限制如果阶段覆盖与基线不同环境提供商必须支持dynamic_network_policy能力E2B 支持纯 Docker 不支持详见 docs-mintlify/tasks/network-policies.mdx 的能力矩阵。当 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在public基线上使用运行时主机放行会给出警告并被忽略。--allow-environment-host与--allow-agent-host的实现定义在 src/harbor/cli/trials.py前者合并进[environment]网络基线环境启动时生效后者只在agent.run()阶段合并进 Agent 阶段允许列表。参考示例在 examples/tasks/network-policy-matrix/完整参考文档为 docs-mintlify/tasks/network-policies.mdx。为 Reward Kit judge 传递 API Key[verifier.env] ANTHROPIC_API_KEY ${ANTHROPIC_API_KEY}[verifier.env]支持从宿主机解析${VAR}模板语法VerifierConfig.env字段。Step 7用 Oracle Agent 验证harbor run -p task-path -a oracleOracle 会先运行solution/solve.sh再运行验证器reward 应为1.0。若不是按此顺序排查solve.sh真的能解题吗用start-env -a -i手动运行它验证器能正确检测成功吗检查/logs/verifier/输出路径正确吗绝对路径 vs 相对路径依赖装进 Dockerfile 了吗这一可解性冒烟测试是任务发布前的质量底线——Harbor 的适配器审查清单src/harbor/cli/adapter_review.py同样要求所有 oracle solution 以 100% reward 通过。Step 8用真实 Agent 测试可选harbor run -p task-path -a terminus-2 -m anthropic/claude-sonnet-4-6如果任务太简单所有模型都拿 1.0或不可能完成所有模型都是 0.0应当调整难度。这一环节验证的是任务的区分度而不只是可解性。Step 9更新 README.md永远是最后一步harbor task init只留下一个 stub README。收尾前务必填充它让未来的开发者和 Agent 无需逐个读文件就能理解任务。内容包括Agent 做什么——一段话链接到instruction.md环境——基础镜像、关键安装包、缓存数据、硬件GPU/CPU/RAM、Agent 超时验证器——Reward Kit 任务给出奖励维度表类型programmatic / LLM judge / agent judge与各自衡量什么、如何聚合布局——带一行注释的任务目录树运行方式——具体的harbor run命令Oracle 真实 Agent若需要 GPU 则带上正确的 provider 参数。把它当文档而非营销文案来写——读者想知道的是修改这个任务需要改动什么。多步任务Multi-step tasks当工作被拆成应分别打分的有序阶段、想要阶段间提前终止、或想测试 Agent 在自身先前成果上继续构建的能力时使用多步任务。所有步骤共享一个容器文件跨步骤持久保留。目录布局将任务根目录的instruction.md、tests/、solution/替换为steps/目录每个子目录对应一个 steptask-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命名约束每个[[steps]].name必须匹配一个目录名不超过 255 个 UTF-8 字节且在大小写折叠与 Unicode 归一化后唯一避免路径分隔符、控制字符、Windows 保留字符/设备名以及结尾的点或空格。发布任务时共享输入用常规文件与目录校验只允许任务目录内的共享链接。任务级tests/会在每步验证时上传到/tests然后叠加该 step 自己的tests/同名文件以 step 内为准因此任务级tests/适合放共享辅助函数。steps/{name}/workdir/setup.sh是保留文件名若存在它会在workdir/上传之后、Agent 之前以该 step 的 Agent 用户身份运行cwd WORKDIR。非零退出会中止该 step 与整个 trial。如果不想让 Agent 看到它请在最后一行执行rm -- $0自删除。多步任务 task.tomlschema_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 steps 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 steps 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。未设置的字段回退到任务级值。StepConfig源码见 src/harbor/models/task/config.py。选择奖励聚合策略mean——跨所有 step 聚合信号适合连续进度型奖励对产生了结果的 step 按 key 取均值缺失 key 视为 0final——以最后一步的verifier_result作为 trial 奖励适合最后一步是覆盖整个任务的端到端检查且其 dict 已代表完整任务的场景。注意若min_reward触发了提前中止final使用的是被中止step 的结果而非预期中的最后一步。MultiStepRewardStrategy枚举与TaskConfig.multi_step_reward_strategy的默认行为多步任务未设置时默认mean都在 src/harbor/models/task/config.py 中有据可查。提前终止语义min_reward支持两种形式数值检查rewardkey或字典要求每个声明的 key 都达到阈值任一 key 低于阈值或缺失即中止缺失的verifier_result验证器崩溃或缺失的 key 视为 -inf。注意min_reward是数值时检查的是 1D 约定的rewardkey以字典形式 gate 多维奖励的典型示例见 examples/tasks/hello-multi-step-advanced/task.toml。Artifacts 收集step 级artifacts在该 step 验证结束后收集到steps/{name}/artifacts/任务级与 trial 级 artifacts 在每步都会额外收集因此 step 级 artifacts 会叠加在任务级之上。参考示例中hello-multi-step-advanced的 task 级artifacts [/app/greet.sh]与 document step 的artifacts [/app/README.md]组合展示了只在该 step 才产出的文件的快照策略。Oracle 验证与完整参考harbor run -p task-path -a oracle该命令按顺序运行每个 step 的solution/solve.sh与每个 step 的验证器trial reward 在所有聚合策略下都应达到1.0。文档docs-mintlify/tasks/multi-step.mdx示例任务examples/tasks/hello-multi-step-advanced/特殊功能按需使用网络策略基线在[environment]/[verifier.environment]阶段覆盖在[agent]/[verifier]详见上文 Step 6 的《网络策略》小节MCP servers在task.toml中添加[[environment.mcp_servers]]为 Agent 提供工具。MCPServerConfigsrc/harbor/models/task/config.py支持stdio、sse、streamable-http三种 transportsse/streamable-http必须提供urlstdio必须提供command。示例examples/tasks/hello-mcp/task.tomlHealthcheck为需要就绪等待的服务添加[environment.healthcheck]。其语义镜像 Docker HEALTHCHECK环境启动后反复运行command退出码 0 即健康连续失败retries次才算失败start_period_sec是启动宽限期期间失败不计入重试。示例examples/tasks/hello-healthcheck/task.tomlGPU设置environment.gpus与可选environment.gpu_types配置模型还支持tpu切片规格TpuSpec的typetopologychip 数由 topology 各维乘积推导预构建镜像设置environment.docker_image代替从 Dockerfile 构建。此时可省略environment/Dockerfile把运行时文件配置、脚本、数据直接放在environment/下Harbor 会在环境启动时把它们上传进容器 workdir非 root 用户设置agent.user/verifier.user用户名或 UID缺省使用环境的默认 USER实现隔离。常见陷阱清单陷阱后果 / 正确做法忘记写 reward 文件任务静默通过但 reward 为 0test.sh用相对路径Harbor 从不同 cwd 执行时会失败——必须用绝对路径把解法装进 DockerfileAgent 直接拿到答案任务失效测试脚本泄露进instruction.mdAgent 看到评分细则刷分变得 trivial忘记chmod x solution/solve.shOracle Agent 直接失败task.toml留下keywords []任务对 registry 搜索不可见README.md 保持 stub队友无法快速理解任务把network_mode放在[agent]期望启动时生效[agent]/[verifier]字段是阶段覆盖基线要用[environment].network_mode阶段覆盖与基线不同且 provider 不支持dynamic_network_policy任务被拒绝如纯 Docker——改用独立验证环境或让阶段与基线一致其中重写 reward 文件还有一条生产级要求test.sh必须在每个代码路径上都重写/logs/verifier/reward.txt或reward.json覆盖 Agent 运行期间可能写入的任何旧文件绝不能信任已存在的 reward 文件见 src/harbor/cli/adapter_review.py 的适配器审查清单。小结创建 Harbor 任务的完整闭环可以浓缩为一句话脚手架生成结构instruction 定义目标Dockerfile 提供环境verifier 决定评分oracle 验证可解性README 沉淀知识。其中验证器选型Reward Kit / pytest / 自定义 shell × 共享/独立环境与网络策略三层体系是最值得花时间的两个决策点。你可以从 examples/tasks/hello-world 这类最小任务出发逐步叠加 healthcheck、MCP、GPU、多步与独立验证环境等能力最终产出一个可被harbor run稳定评测、可发布到 registry 的高质量任务。赞分享【免费下载链接】harborFramework for evaluating and improving agents项目地址https://gitcode.com/gh_mirrors/harbor17/harbor点击查看免费下载相关推荐用 ZenML Sandbox 运行 Harbor 评测任务解析 tasks/hello 冒烟任务的指令、验证与端到端链路用 ZenML Sandbox 运行 Harbor 评测任务解析 tasks/hello 冒烟任务的指令、验证与端到端链路 ZenML 仓库中的 examplMLOps机器学习后端工作流自动化AI AgentAIBrix Console 错误注入端到端实战从任务创建到 Trace 查询的混沌工程指南AIBrix Console 错误注入端到端实战从任务创建到 Trace 查询的混沌工程指南 导读 本文以 AIBrix Console 的 error_in人工智能大模型云原生模型推理服务LLM 网关API网关弹性伸缩Windmill Agent Worker 本地端到端调试指南从 Feature 编译到 dbt 任务验证Windmill Agent Worker 本地端到端调试指南从 Feature 编译到 dbt 任务验证 Agent Worker 是 Windmill 中后端工作流自动化任务调度低代码前端上一篇深入理解 Graphile Build 插件系统从 Preset 配置到 Schema 构建全指南下一篇EOS 投票实战指南使用 cleos system voteproducer 为区块生产者投票创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考