herdr 入门教程：用主智能体调度子智能体，告别“一个模型干到底”

在日常使用 AI 辅助编程时，很多人最习惯的做法是“一个智能体用到底”：打开某一个熟悉的 AI 编程助手，从理解需求、出方案、写代码、查 Bug 到写测试，全程全包给这一个智能体。

这种“单打独斗”的模式看着省事，任务一复杂，短板就出来了：不同模型各有长处，一个智能体很难把所有环节都做好。

  • 有的模型擅长全局推理与架构设计，但让它做琐碎的代码修改，响应偏慢，也可能扩大改动范围；

  • 有的工具在代码规范、执行风险审核和挑刺上更细，适合当“质检员”，却不适合做首轮需求设计；

  • 有的轻量级助手在本地终端编辑、执行命令时反应快，适合承担具体实施；

  • 同一个智能体自编、自审、自改，相当于“既当裁判又当运动员”，方案里的问题不容易在实施前暴露。

我的做法是，让一个具备全局统筹能力的主智能体担任“项目主管”，按任务特点调度不同的子智能体，各自只管一个环节。

而且最关键的是：你根本不需要在终端里手敲调度命令。借由 herdr 提供的终端能力，你只需向主智能体发出一句自然语言指令，它自己就会在后台拆分终端、启动子智能体、多轮博弈迭代，并最终验收交付。

一、herdr 的角色：面向 Agent 自动化的终端底座

很多人初见多 Agent 编排，会以为开发者必须像敲 Shell 脚本一样，自己一行行去敲分屏、派发命令；或者退回老路，在多个窗口间人工复制粘贴当“人肉传话筒”。

herdr（The runtime your coding agents live on）把这件事做得更顺手：它是一个自带状态感知与可编程 API 的终端运行时。

它给主智能体补上了几样可以直接调用的工具：

01统一生命周期状态机：herdr 能原生识别主流 Agent 的状态（idle 待命、working 执行中、blocked 等待确认、done 当前轮次完成）。

02第一类 Agent CLI 原语：终端里的主智能体可以直接调用 herdr 命令行（如 pane split、agent start、agent prompt、agent read），动态掌控周围的窗格。

03真实可视终端：所有子智能体依然在独立的真实终端窗格中运行。人类开发者既不用手动干预，又能全程在大屏幕上直观看到各个 Agent 的分屏输出和状态流转。

二、基础准备：两分钟完成环境搭建

1. 安装并启动 herdr

macOS 或 Linux 环境下直接一键安装：

1
curl -fsSL https://herdr.dev/install.sh | sh

或使用 Homebrew 安装：

1
brew install herdr

进入代码仓库根目录，启动 herdr 会话：

1
herdr

herdr 采用 Client/Server 架构。启动后即使窗口关闭，后台进程依然保活。你可以随时用 ctrl+b 再按 q 进行 detach（脱离），下次输入 herdr 便可无缝接回。

2. 安装 Agent Integration（确保状态判定精准）

为了让主智能体在调度子智能体时，--wait、done、blocked 的判定绝对精准，提前安装好对应 agent 的集成插件：

1
2
3
4
5
6
7
# 查看所有支持的 agent 及集成状态
herdr integration status

# 安装实战所需的三个集成
herdr integration install copilot
herdr integration install qodercli
herdr integration install pi

注意：

  • kind 是 herdr 内置的官方枚举。即使你在本地为命令起过别名（例如 qodercncli），在 herdr 参数中统一对应官方 kind qodercli。

  • 安装 integration 后，herdr 能够精准捕获子 Agent 何时停止输出、何时需要授权，避免主智能体调度超时。

三、实战案例：一句话让主智能体自主调度全流程

我们来看一个真实的工程改进过程。为避免公开具体项目，下面把它泛化成一个内部业务工作台。

1. 业务背景与角色特长分工

当前工作目录里是一个供专业人员使用的业务工作台。我希望三个工具各做自己更擅长的部分：

  • 主智能体（Copilot）：先完整试用系统，从实际使用者的视角提出改进建议，并负责调度和最终验收。

  • 审核子智能体（Qoder CLI）：只负责挑刺，检查建议有没有设计缺陷、越权改动或遗漏的验收条件。

  • 实施子智能体（pi）：只拿通过审核的计划，负责改代码和运行验证，不再重新解释需求。

2. 人类只需输入的一句话 Prompt

在 herdr 中打开主智能体（Copilot），人类开发者完全不需要敲任何 herdr 命令行，直接把下面这段 Prompt 发送给它：

“请认真试用当前目录里的业务工作台，从实际使用者视角提出改进建议。通过 herdr 启动新的 qodercncli 审核方案；根据审核意见继续完善，直到通过。再把通过审核的详细计划交给 pi 实施，最后由你核对实际改动并验收。”

3. 这句话背后的协作逻辑拆解

这句话看着普通，实际把协作闭环需要的几件事都交代了：

主智能体调度审核与实施的协作闭环

主智能体调度审核与实施的协作闭环

01给出角色与观察角度：“从实际使用者视角提出改进建议”，让主智能体先理解项目，再形成整体方案。

02引入独立审核：“通过 herdr 启动新的 qodercncli 审核”，避免主智能体自己写方案、自己判定通过。

03允许打回重审：“根据审核意见继续完善，直到通过”，把修改和复审留在同一条线上，不需要我在几个窗口之间搬话。

04实施与验收分开：“交给 pi 实施，最后由你验收”，实施者按定稿动手，主智能体回到最初目标检查结果。

四、透视幕后：主智能体自主执行了哪些动作？

当人类发出上述指令后，herdr 窗口会显示几个 agent 的状态变化。主智能体通过命令行，在后台完成以下调用：

阶段 1：业务试用与起草方案

Copilot 探索项目结构与业务逻辑，草拟出改进建议文档并暂存到磁盘（例如 00_META/tmp/project-improvement-plan.md）。

阶段 2：自主拆屏并唤醒 Qoder CLI 审核

主智能体在后台自动调用 herdr CLI，拆开右侧窗格并拉起 Qoder CLI：

1
2
3
4
5
6
7
8
9
10
11
12
13
# 主智能体自动执行：拆分右侧窗格获取 pane_id
REV_PANE=$(herdr pane split --direction right --no-focus | jq -r '.result.pane.pane_id')

# 主智能体自动执行：启动 qodercli 作为 reviewer
herdr agent start reviewer --kind qodercli --pane "$REV_PANE"

# 主智能体自动执行：派发审核任务并阻塞等待结果
herdr agent prompt reviewer \
  "请严格审核方案 00_META/tmp/project-improvement-plan.md。重点检查使用逻辑、向前兼容性、改动边界和验收条件。如无阻塞问题请回复【APPROVED】；如有问题请回复【REJECTED: 详细意见】" \
  --wait --until done --timeout 180000

# 主智能体自动执行：读取审核结果
herdr agent read reviewer --source recent-unwrapped --lines 80

阶段 3：根据反馈自我完善（直到通过）

主智能体读取到输出：

  • 如果 Qoder CLI 指出“方案第 3 点缺少人工确认，可能扩大改动边界”；

  • Copilot 不会向人类抱怨，而是直接重新打开方案文件进行修改修正；

  • 修正后再次调用 herdr agent prompt reviewer ... --wait 重新提审；

  • 直到 Qoder CLI 给出 【APPROVED】，主智能体执行 herdr pane close "$REV_PANE" 关闭审核窗格。

阶段 4：自主拉起 pi 窗格进行落地实施

审核通过后，Copilot 自动向下拆分窗格，拉起敏捷执行者 pi：

1
2
3
4
5
6
7
8
9
10
11
12
# 主智能体自动执行：向下拆屏启动 pi
BLD_PANE=$(herdr pane split --direction down --no-focus | jq -r '.result.pane.pane_id')
herdr agent start builder --kind pi --pane "$BLD_PANE"

# 主智能体自动执行：派发已审定的落地改动指令
herdr agent prompt builder \
  "请严格按照 00_META/tmp/project-improvement-plan.md 中已定稿的方案修改代码，完成后运行语法与构建检查。" \
  --wait --until done --timeout 300000

# 收集实施产物并关闭窗格
herdr agent read builder --source recent-unwrapped --lines 100
herdr pane close "$BLD_PANE"

阶段 5：闭环验收并向人类汇报

实施完成后，Copilot 在自己的主窗格中运行 git diff 与测试验证命令，核验改动是否符合最初确定的目标，最后向你生成一份结构清晰的交付报告。

到这里，三个工具的分工就落到了实处：Copilot 负责整体判断，Qoder 负责审核，pi 负责代码实施。用户只需要给出最初那句话，并处理必要的授权和取舍。

遇到权限确认时，人可以直接接管真实终端

遇到权限确认时，人可以直接接管真实终端

五、幕后原语备查：主智能体使用的五条 herdr 指令

虽然人类不用手动输入，但了解主智能体背后调用的 5 个核心命令，能帮助你在需要排错或自定义流水线时心中有数：

指令 语法示例 作用
拆分窗格 herdr pane split --direction right --no-focus 动态开辟独立终端，返回新 pane_id
拉起助手 herdr agent start <name> --kind <kind> --pane <id> 在目标窗格中启动指定类型的子智能体
派发等待 herdr agent prompt <name> "..." --wait --until done 提交任务并阻塞等待直到任务完毕
读取产物 herdr agent read <name> --source recent-unwrapped 读取去除折行的干净终端输出文本
回收资源 herdr pane close <id> 任务完成后关闭窗格，释放终端空间

六、工程避坑要点：如何确保多 Agent 协作稳定

在放手让主智能体调度子智能体时，以下几个经验细节能够确保流程稳健不翻车：

1. 验收绝不凭文字描述（Attested Completion）

主智能体不能只看子智能体说“我已经改好了”就判定通过。Prompt 里要写清楚：验收必须以真实的 git diff、可执行的验证命令或生成的产物文件为准。子智能体的文字汇报只能当线索，不能当结果。

验收要看实际改动、验证命令和产物

验收要看实际改动、验证命令和产物

2. 警惕权限确认导致的 blocked 挂起

如果某个子智能体在执行命令时触发了高风险操作（例如危险写入、系统权限），终端会弹出 [y/N] 提示，其状态会变为 blocked。

  • 此时主智能体的 --wait 会暂停等待；

  • 作为坐镇的人类开发者，你在屏幕上看到黄色 blocked 提示时，可以直接用鼠标点进该窗格敲个 y 放行。这就是 herdr 保留真实终端交互界面的核心价值。

3. 严格限定子智能体的行动边界

  • 审核智能体（Qoder CLI）只赋给“只读与评审”的职责，绝不让它直接动代码；

  • 实施智能体（pi）只拿“已审定的定稿文档”，不让它自行发挥改动架构；

  • 职责越明确，多智能体协同就越稳定。

七、总结

告别“一个智能体用到底”，不是为了多开几个窗口，而是把不同模型放到合适的位置：主智能体负责判断和收口，审核工具负责挑刺，执行工具负责落地。

借助 herdr，这些助手都待在真实终端里，主智能体能看状态、能派任务、能收结果，人也能随时接管。下一次遇到稍复杂的工程任务，可以先从一条三段式指令试起：先出方案，交给另一个智能体审核，通过后再实施，最后回到主智能体验收。