DeepSeek Harness 从 0 开始:21 goal-round-driver Agent runtime 的 controller

28 阅读13分钟

DeepSeek Harness 从 0 开始:21 Agent控制器设计goal-round-driver

本文从 controller 视角拆解 DeepSeek Harness 的 goal-round-driver:driver 不是更聪明的 agent,而是通过 active/armed 状态与 reconcile 循环维护运行时一致性。文中给出三种状态流转、伪代码示意和常见失败场景,帮助你理解 Agent 长任务为什么会断档、重复和状态漂移。

关键词:goal-round-driver、Agent 长时运行、agent loop、followup、reconcile controller、active、armed、运行时控制

在 DeepSeek Harness 里,session、tools、system-prompt、agent-loop 解决的是“一轮怎么跑”:模型怎么调用、工具怎么执行、上下文怎么拼。

但长任务真正难的地方不在单轮执行,而在轮与轮之间。

一轮结束后,如果没有人继续输入,Agent 就停在 idle。短任务没问题;几小时、几天的任务里,人必须反复说“继续”。直觉上可以写一个 while 循环:

while (goal.active) {
  agent.followup("继续")
  await agent.whenIdle()
}

这个循环能跑,但它不是工程化的长时运行:

  • 它分不清 Agent 是真空闲,还是有人类输入在排队;
  • 它没有预算和停止条件;
  • 它不能暂停、恢复、卸载;
  • 重启后不知道跑到第几轮;
  • 多个事件同时到达时,没有统一的检查点。

goal-round-driver 就是补这个缺口的模块。

一、先纠正一个定位:driver 不是“更聪明的 Agent”

普通 Agent 的循环是 turn-based 的:

用户输入 -> agent loop 跑一轮 -> 输出 -> idle

agent loop 负责执行:调用模型、执行工具、开 turn、跑 step。
goal-round-driver 负责另一件事:在什么时候允许调用 agent.followup(),把下一轮接上。

所以 driver 不判断目标对不对,不执行轮次,也不拼上下文。

driver 是 agent runtime 的 controller:它不判断目标、不执行轮次、不拼上下文;它只维护期望运行状态与实际运行状态的一致,并通过统一准入、轮次租约、四种收尾和明确恢复边界,把“自动续跑”从隐式 while 循环变成可治理的运行时控制。

这句话里最重要的是“controller”,不是“更聪明的 agent”。

driver 不提升单轮能力,它提升的是长时运行的可治理性。

二、一张图看清:agent loop 和 driver 怎么分工

sequenceDiagram
    participant U as 用户
    participant L as agent loop
    participant M as 模型
    participant G as goal 服务
    participant D as driver

    U->>L: 下达任务
    L->>M: 调用模型
    M-->>L: tool_call(create_goal)
    L->>G: 写 goal/change
    G-->>D: goal/changed
    Note over D: 检查 active + armed + 预算
    D->>L: agent.followup(goal_round)
    L->>L: claim,开始 turn
    L->>D: agent/pre-step(准入)
    D-->>L: enter
    L->>M: 跑 goal round
    M-->>L: 最终回复
    L->>D: agent/status(idle)
    alt 仍 active + armed 且预算有余量
        D->>L: 下一轮 followup
    else complete / pause / 预算耗尽
        D->>D: 不再发
    end
    Note over U,L: 长任务期间,用户可随时插话、pause、resume

图 1:agent loop 负责执行一轮,driver 负责决定这一轮之后还要不要有下一轮。

这张图里,三个角色的边界很清楚:

角色负责不负责
agent loop跑 turn、调用模型和工具、维护 idle/running判断下一轮还要不要继续
driver检查准入、调用 followup、跟踪轮次、收尾执行 turn、判断目标、拼上下文
goal 工具 / GoalService维护 goal 状态、发出 goal/changed调度轮次

有一个容易误解的点:

followup 是 driver 的动作,但 followup 不等于执行。

driver 只是把下一轮任务放进队列;真正从 inbox 取消息、开 turn、调用模型和工具的,仍然是 agent loop。

三、reconcile:driver 到底在维护什么

与其说 driver 是调度器,不如说它是一个很小的 reconcile loop。

它不断比较两边:

  • 期望运行状态:目标还该不该继续(active + armed + 预算);
  • 实际运行状态:Agent 现在是 idle 还是 running,driver 是 Idle / Armed / Running,有没有被暂停或卸载。

然后只做三类动作:

期望实际driver 动作
继续可跑(idle、armed、预算可用)调用 followup,进入下一轮
继续暂时不可跑(running、未 arm、预算不足)等待下一次事件
停止还在跑或还有待发轮次收尾,不再调用 followup

这里的工程化,不是“写一个更复杂的 while”,而是把四件事显式化:

  • 统一准入:这一轮 followup 允不允许发;
  • 轮次租约:发出去的一轮由 driver 跟踪到 round end,期间不重复发;
  • 收尾:complete / pause / 预算耗尽 / 卸载 四种结束路径;
  • 恢复:暂停后重新 arm、预算调整后恢复、重新装载后 resume。

四、两个标志,三个状态

入门最容易混淆的是 active 和 armed。

  • active:这个 goal 还在生命周期内,还没有被完成或终结。它回答的是:这个目标还要不要管?
  • armed:driver 当前是否被允许在条件满足时自动发起下一轮。它回答的是:现在能不能自动续跑?

两者不是一回事:

  • goal 可以 active = true,但 armed = false。比如用户暂停了自动续跑,目标还在,但 driver 不应该继续发轮次;
  • armed = true 通常要求 active = true。目标已经终结,就不应该再武装 driver;
  • 第一轮发出后,goal 仍然是 active;一轮结束以后,driver 再根据条件决定是否继续。

一句话:

active 是目标层的事实,armed 是调度层的许可。

driver 自己则有三个状态:

状态含义典型行为
Idle没有可驱动目标,或已经收尾/解除武装不发起轮次,等待新的 goal 或重新 arm
Armed有 active goal,且允许自动续跑等待 Agent 空闲或上一轮结束,准备发下一轮
Running已经发出一轮,正在等待这一轮结束不重复发轮,轮末统一做续跑/收尾判断

重点不是状态名,而是职责分离:

  • Armed 表示“可以发,但还没发”;
  • Running 表示“已经发了,等结果”;
  • 轮次结束后,不要直接在回调里递归调用下一轮,而是回到 Armed,再由统一入口决定是否 kick()。

这样第一轮和后续轮次才能走同一套判断逻辑。

五、第一轮什么时候发

第一轮不是 driver 一加载就无条件发。它通常要同时满足:

  • goal 已经创建并处于 active;
  • driver 已经装载并完成 arm,即 goal.armed = true;
  • agent loop 当前空闲,没有正在跑的轮次;
  • 预算还可用,没有被暂停或卸载。

伪代码大致是:

// 伪代码:只表达调度关系,不是真实 API
function startDriver(goal, loop, driver) {
  if (!goal.active) {
    driver.state = "Idle";
    return;
  }

  goal.armed = true;
  driver.state = "Armed";

  if (loop.isIdle() && canKick(goal, driver)) {
    kickRound(goal, loop, driver);
  }
}

function canKick(goal, driver) {
  return (
    goal.active &&
    goal.armed &&
    driver.state === "Armed" &&
    !driver.disposed &&
    driver.budget.ok()
  );
}

这里有个关键点:

第一轮和后续轮次,必须复用同一个 canKick 判断。

不要把“启动时发第一轮”和“轮末发下一轮”写成两套逻辑。否则暂停、预算、卸载这些条件,很容易只在一处生效。

六、轮末怎么接下一轮

一轮结束后,driver 会收到 round end。

此时不要立刻“无脑续跑”,而是按顺序判断:

  • 这一轮是否已经让 goal 完成?
  • goal 是否被暂停,或 armed 被解除?
  • 预算是否已经耗尽?
  • driver 是否正在卸载?
  • 如果以上都没有,goal 是否仍然 active + armed?

只有最后一条成立,才调度下一轮。

function onRoundEnd(result, goal, driver) {
  driver.state = "Armed";

  if (result.completed) {
    finish(driver, "complete");
    return;
  }

  if (!goal.armed || result.paused) {
    finish(driver, "pause");
    return;
  }

  if (!driver.budget.ok()) {
    finish(driver, "budget_exhausted");
    return;
  }

  if (driver.disposed) {
    finish(driver, "unload");
    return;
  }

  if (goal.active && goal.armed) {
    scheduleNextRound(goal, driver);
  }
}

scheduleNextRound 可以理解为“回到 Armed,等下一次可发时机”。

如果 agent loop 已经空闲,就可以立即 kick;如果还不空闲,就等 idle 事件。

没有递归,也没有定时器。每一轮都是:

idle / round end -> 检查 -> followup

七、四种收尾

入门阶段先记住四种收尾路径:

收尾方式触发条件goal.activegoal.armeddriver 行为是否还能恢复
complete目标完成变为 falsefalse停止续跑,记录完成否,目标已终结
pause用户/策略暂停通常仍为 truefalse解除武装,停止自动续跑是,重新 arm 后可继续
预算耗尽轮数/时间/token 等预算到上限通常仍为 truefalse停止自动续跑,标记预算耗尽通常可调整预算后恢复
卸载driver 被 dispose / 插件卸载 / harness 关闭不强行改 goalfalse取消待调度、解除监听、停止续跑取决于上层是否重新装载并 resume

有两个容易写错的地方:

  1. 暂停不是完成。pause 只是停止自动续跑,目标还在;把暂停当成完成,会让目标被错误终结。
  2. 卸载不是完成。卸载是 driver 生命周期层面的收尾,不是目标完成;它只保证不再续跑,goal 的持久状态是否保留,是上层恢复策略的事。

八、真正难的不是 followup,而是这些边界

把主链路讲通之后,工程实现里最容易出问题的是边界。

1. 统一准入入口

所有 kick 都必须经过同一个 canKick。

无论是第一轮、loop idle 后、round end 后,还是恢复后重新 arm,都不能绕过这个入口。

2. 不要在 round end 回调里递归

轮末回调只负责判断收尾条件,然后把 driver 放回 Armed,由调度入口决定是否 kick()。

递归调用会让暂停、预算、卸载检查散落在多个地方。

3. Running 期间防重复发轮

Running 期间不重复发轮。

即使又收到一次 idle 或恢复事件,也要先检查 driver 状态,避免同一个 goal 同时跑多轮。

4. 暂停/卸载与 round end 的竞态

实际运行中,round end 可能与 pause、dispose 同时到达。

实现上应以收尾条件优先:如果已经 pause 或 disposed,即使 round end 到达,也不应该再调度下一轮。

5. 可观测性

至少记录状态迁移和收尾原因,例如:

Idle -> Armed
Armed -> Running
Running -> Armed
Armed -> Idle (pause / budget_exhausted / unload / complete)

日志里要能看出是“完成”“暂停”“预算耗尽”还是“卸载”,不能最后只剩一个 idle。

6. 恢复不是 driver 自动完成的

  • pause 后恢复,需要重新 arm;
  • 预算耗尽后恢复,通常需要调整预算;
  • 卸载后恢复,取决于上层是否重新装载并 resume。

driver 自己只保证:不该续跑的时候,一定停。

九、FAQ:goal-round-driver 常见问题

Q1:goal-round-driver 是什么?

A:goal-round-driver 是 DeepSeek Harness 中围绕 goal 生命周期工作的运行时控制器。它不执行单轮、不生成答案,只在允许时调用 agent.followup(),把下一轮接上。

Q2:goal-round-driver 和 agent loop 有什么区别?

A:agent loop 负责“跑一轮”:调用模型、执行工具、开 turn、跑 step。driver 负责“轮与轮之间”:判断下一轮还要不要有、什么时候允许调用 followup、什么时候停止。followup 是 driver 的动作,但执行仍然由 agent loop 完成。

Q3:为什么不直接写一个 while 循环?

A:隐式 while 只表达了“继续”,没有表达“什么时候允许继续”。它处理不了真正空闲与人类输入排队的区别,也没有预算、暂停、卸载、重启恢复这些条件。driver 把这些条件收进统一的准入判断。

Q4:active 和 armed 有什么区别?

A:active 是目标层的事实:这个 goal 还要不要管;armed 是调度层的许可:现在允不允许自动续跑。一个 goal 可以 active 但 armed = false,例如用户暂停了自动续跑。

Q5:driver 的四种收尾方式是什么?

A:complete、pause、预算耗尽、卸载。complete 是目标完成;pause 只是停止自动续跑,目标还在;预算耗尽是被边界拦住;卸载是 driver 生命周期结束。暂停和卸载都不能误写成完成。

Q6:为什么需要 Idle / Armed / Running 三个状态?

A:Armed 表示“可以发,但还没发”;Running 表示“已经发了,等结果”。没有 Running,一次 idle 或恢复事件就可能让同一个 goal 同时发两轮。三个状态把“允许发”和“已经发了”分开。

Q7:重启后 driver 会自动恢复吗?

A:不会自动恢复。driver 只保证“不该续跑的时候一定停”;重启后是否重新装载、是否 resume、是否恢复 goal 的持久状态,是上层恢复策略要回答的问题。

Q8:为什么所有 kick 都要经过同一个 canKick?

A:第一轮、loop idle 后、round end 后、恢复后重新 arm,最终都可能导致一次 followup。每个入口各写一套判断,暂停、预算、卸载这些条件很容易只在一处生效。统一入口才能保证“不该续跑的时候一定不续跑”。

十、术语表

术语解释
goal-round-driverAgent 长时运行的运行时控制器;负责在轮与轮之间调用 followup、收尾和恢复边界
agent loopAgent 执行循环;负责 turn、step、模型调用、工具执行和 idle/running
followupdriver 把下一轮任务放进队列的动作;不等于执行
reconcile controller不断把期望运行状态与实际运行状态对齐的控制器
active目标层事实:这个 goal 还要不要管
armed调度层许可:现在允不允许自动续跑
Idle / Armed / Runningdriver 自身的运行状态:无目标 / 可发未发 / 已发等结果
统一准入所有 kick 都走同一个 canKick,避免条件只在一处生效
轮次租约followup 后跟踪到 round end,Running 期间不重复发

十一、总结

goal-round-driver 的价值,不是让 Agent 多跑几轮,而是把“继续”从一段隐式循环,变成运行时可以治理的对象。

driver 是 agent runtime 的 controller:它不判断目标、不执行轮次、不拼上下文;它只维护期望运行状态与实际运行状态的一致,并通过统一准入、轮次租约、四种收尾和明确恢复边界,把“自动续跑”从隐式 while 循环变成可治理的运行时控制。

拆开看,它做的四件事都不“聪明”,但缺一不可:

  • 统一准入:第一轮、idle 后、round end 后、恢复后,都走同一个 canKick;
  • 轮次租约:followup 发出去不是结束,driver 要跟踪到 round end;Running 期间不重复发;
  • 四种收尾:complete、pause、预算耗尽、卸载各有明确语义,不能互相误写;
  • 恢复边界:driver 只保证“不该续跑的时候一定停”;重新 arm、调整预算、重新装载,是上层的事。

所以它和 agent loop 不是替代关系,而是分工:

loop 把一轮跑完,driver 决定这一轮之后还要不要有下一轮。

普通 Agent 的能力上限由模型决定;长时 Agent 能不能跑住,由这层 runtime 控制决定。

这就是 goal-round-driver 的位置。