第 7 章：多步任务——steps、早停与恢复

真实世界的 agent 工作往往是长程的：先搭环境、再改代码、最后验证交付。Harbor 的多步任务（multi-step task）让你把一次评测拆成多个里程碑，在每个里程碑之间插入验证、按得分决定是否继续，并跨步骤保留环境甚至 agent 会话。本章讲清 steps 目录结构、[[steps]] 配置、reward 聚合策略、min_reward 早停与 --resume-trajectory 会话恢复。

什么时候需要多步任务

单步任务只看最终结果；多步任务则提供两种单步做不到的能力：

1. 把验证穿插进 agent 运行过程。每完成一个阶段就判一次分，而不是等全部跑完再"算总账"。
2. 衡量 agent 从上一个会话继续工作的能力。这对考察长程任务中的记忆与持续学习（memory、continual learning）尤其有用。

典型适用场景：带早停条件的长程任务（前一步做得差就没必要继续烧钱跑后面几步），以及考察 agent 能否"接手上一班"的多阶段协作式任务。

目录结构：steps/ 目录

多步任务的目录结构与普通 Harbor task 不同，每个步骤是一个独立子目录：

task.toml
environment/
├── Dockerfile    # 或其他环境定义
└── ...
tests/
├── helpers.py    # 可选的共享判分工具
└── ...
steps/
├── step-1/
│   ├── instruction.md
│   ├── tests/
│   │   ├── test.sh
│   │   └── ...
│   ├── solution/
│   │   ├── solve.sh
│   │   └── ...
│   └── workdir/
│       ├── setup.sh    # 可选
│       └── ...
└── step-2/
    └── ...

每个 step 可以包含以下内容：

条目	是否必需	作用
instruction.md	必需	本步给 agent 的指令
tests/	可选	本步的判分脚本（test.sh）
solution/	可选	本步的参考解法（solve.sh）
workdir/	可选	本步开始前注入 agent 工作目录的文件

共享判分工具放在根目录的 tests/ 里：Harbor 会先把基础 tests/ 复制到 /tests/，再用 step 自己的 tests/ 覆盖同名文件。这样 helpers.py 这类公共工具只需写一份。

task.toml 中的 [[steps]] 配置

步骤在根目录 task.toml 中按执行顺序声明，每个 name 对应 steps/ 下的一个目录；其余设置沿用标准 task 配置：

multi_step_reward_strategy = "mean"

[agent]
timeout_sec = 600

[[steps]]
name = "step-1"
min_reward = 1.0

[steps.agent]
timeout_sec = 300

[[steps]]
name = "step-2"

[steps.verifier]
timeout_sec = 120

这个例子里，step-1 的 agent 超时被覆盖为 300 秒；step-2 没写 [steps.agent]，于是继承任务级的 600 秒；同时 step-2 只有在 step-1 的 reward 达到 1.0 时才会运行（早停见下文）。

每个 [[steps]] 条目接受以下字段：

字段	类型	默认值	说明
name	string	必需	steps/ 下唯一、可移植的目录名
agent	AgentConfig	—	本步的 agent 设置，使用任务级 [agent] 的 schema
verifier	VerifierConfig	—	本步的 verifier 设置，使用任务级 [verifier] 的 schema，也支持隔离 verifier 环境
min_reward	number | object | null	null	继续执行的 reward 门槛，见"早停"一节
healthcheck	HealthcheckConfig | null	null	本步环境搭建之后、agent 运行之前的额外健康检查，使用环境 healthcheck schema
artifacts	list[string | ArtifactConfig]	[]	验证结束后额外收集的产物，存入 steps/<name>/artifacts/，与任务级、trial 级产物并列

每步独立 reward 与聚合策略

多步任务的每个 step 拥有自己的 verifier，各自产出独立的 reward。整个 trial 的 reward 则由 multi_step_reward_strategy（写在 task.toml 顶层）决定：

• "mean"（默认）：对有 verifier 结果的步骤求 reward 平均值，缺失的指标键计为 0。
• "final"：使用最后执行的步骤的 verifier 结果。

注意"最后执行的步骤"不一定是声明中的最后一步——如果后面的步骤被早停跳过，"final" 取的是实际执行到的最后一步。被跳过的步骤不参与 trial reward 的计算。

min_reward 早停

给某个 step 设置 min_reward，当它的得分低于门槛时，Harbor 会跳过其余步骤，避免浪费算力。门槛有两种写法：

[[steps]]
name = "step-1"
min_reward = { accuracy = 0.9, safety = 1.0 }

[[steps]]
name = "step-2"

• 写一个数字：检查 reward 的 reward 键是否达标；
• 写一个对象：要求每一个命名指标都达到各自的阈值（上例要求 accuracy ≥ 0.9 且 safety ≥ 1.0）。

判定规则：缺失的 reward 键视为不通过；恰好相等视为通过。不设置 min_reward 时，低分不会中断执行。

两个边界情况：当验证被禁用时，门槛会被忽略；但如果某一步出错且没有产生 verifier 结果，任务依然会终止。

步骤间的状态：workdir 与环境持久化

有时你需要在本步开始时向 agent 的工作区投放文件（比如新的输入数据）。把文件放进 steps/<step-name>/workdir/ 即可，Harbor 会在该步开始前把它们复制进 agent 的工作目录，同名文件直接覆盖：

steps/step-2/workdir/
├── input.csv
└── setup.sh

其中可选的 setup.sh 会在复制完成后用 Bash 执行，适合做本步的准备工作。另一点对设计多步任务很关键：文件系统的改动在步骤之间是持久的——前一步留下的文件，后一步仍然可见。

恢复中断的多步评测：--resume-trajectory

默认情况下，每个 step 都开启一段全新的 agent 对话。如果你希望 agent 接着上一步的会话继续工作（考察"记忆与延续"能力时正是如此），加上 --resume-trajectory：

harbor run \
  --path "" \
  --agent "" \
  --model "" \
  --resume-trajectory

在 YAML 配置文件中，则通过 resume_trajectory 开关表达同样的意图：

tasks:
  - path: ""
agents:
  - name: ""
    model_name: ""
    resume_trajectory: true

前提是所用 agent 原生支持会话恢复（native resume support）；无论该开关如何设置，环境本身始终跨步骤持久，恢复的只是对话轨迹。

此外，"从指定步骤开始运行"的功能已在计划中（coming soon）。如果你想为它做准备，确保前面的步骤都带有 solution/solve.sh 文件即可。

下面这张图总结了多步任务的执行与早停逻辑：

flowchart TD
    S[开始 step-1] --> A1[Agent 执行本步]
    A1 --> V1[本步 verifier 打分]
    V1 --> C1{达到 min_reward?}
    C1 -->|是| N[还有下一步?]
    C1 -->|否| H[早停: 跳过剩余步骤]
    N -->|是| S2[开始下一 step]
    S2 --> A2[Agent 执行本步]
    A2 --> V2[本步 verifier 打分]
    V2 --> C2{达到 min_reward?}
    C2 -->|是| E[所有步骤完成]
    C2 -->|否| H
    H --> M[按 multi_step_reward_strategy 聚合已执行步骤]
    E --> M
    M --> R[得到 trial reward]

本章小结

• 多步任务用于两类需求：把验证穿插进 agent 运行过程，以及衡量 agent 从上一个会话继续工作的能力（记忆、持续学习）。
• 每个 step 是 steps/ 下的一个目录，instruction.md 必需，tests/、solution/、workdir/ 可选；基础 tests/ 先复制、step 的 tests/ 后覆盖。
• 步骤在 task.toml 中按顺序以 [[steps]] 声明，name 对应目录名；agent、verifier 未配置的字段继承任务级设置。
• 每步有独立 verifier 与 reward；trial reward 由 multi_step_reward_strategy 决定："mean"（默认，缺失键计 0）或 "final"（最后执行的步骤）。
• min_reward 支持数字（检查 reward 键）与对象（所有命名指标须达标）；缺失键不通过、相等算通过；不设置则低分不停。
• 验证被禁用时门槛失效，但步骤出错且无 verifier 结果仍会终止任务；被跳过的步骤不计入 trial reward。
• workdir/ 在步骤开始前注入 agent 工作目录（同名覆盖），可选 setup.sh 在复制后执行；文件系统改动跨步持久。
• --resume-trajectory（配置文件中 resume_trajectory: true）让 agent 接续上一步会话，需要 agent 原生支持；环境无论如何都持久。

延伸阅读

• Multi-step——本章主源页面
• Verifier——每步判分脚本的写法（第 6 章）
• Separate verifier——step 级隔离 verifier 环境
• Task configuration——[agent]、[verifier]、artifacts 等标准配置
• Multi-step tasks 发布公告——该特性的背景介绍