入门 📋 6 个步骤 第 629 / 632 篇

用 Herdr 让多个编码 Agent 的会话不断线:detach/reattach、pane 状态与 agent 技能协同实操

Herdr 是 Apache 2.0 的 Rust 终端复用器,detach 后后台服务继续跑 pane,每格会被标记 working、blocked 或 idle,Agent 还能通过 CLI 与 socket API 互相发消息、等待对方真的卡住。本教程按官方 README、agent-skill 文档与 SKILL.md 六步落地:审阅安装脚本并练通断线重连、装载官方技能并核验 HERDR_ENV、发现布局与 pane ID、拆 pane 起第二个 Agent、委派任务与读取结果,最后处置 blocked 卡点、版本差异与会话收口。主线不需要新增模型密钥。

2026.11.16· 18 分钟阅读· 约 4261 字· 🖥️ Herdr / 🤝 多 Agent 委派

同时开三四个编码 Agent,最烦的不是模型不够强,而是终端一关、SSH 一断,所有会话全丢;更别提某个 Agent 正卡在审批弹窗上,你得挨个窗口翻。Herdr 是一个给编码 Agent 用的终端复用器:Rust 单二进制、Apache 2.0,detach 之后后台服务继续跑 pane,每个 pane 会被标记 working / blocked / idle,Agent 还能通过 CLI 与 socket API 互相发消息、等待对方真的卡住。本教程按官方 README、agent skill 文档与 SKILL.md 六步落地:安装与断线重连、装载官方技能、发现布局与状态、拆 pane 起第二个 Agent、委派任务并等待、最后处理审批卡点与会话保持。主线不需要模型 API Key,只要机器上已有任意可运行的编码 Agent 客户端。

🧩 适合谁:已经会用 Claude Code、Codex、OpenCode 之类终端 Agent,想同时跑多个实例、又不希望关掉终端就丢上下文的开发者;也适合在远程 GPU 机器上跑长任务的人。前置准备:macOS / Linux / Windows 一台机器、一个终端、已安装并登录好的编码 Agent 客户端、npx(用于装官方技能)、一个新建的练习仓库。Herdr 本身不调用模型,但你在 pane 里启动的 Agent 会按各自的账号计费;本文所有示例都在练习仓库里跑,不会碰你的真实项目文件。

动手前先记住三条边界:① 官方安装方式是 curl ... | sh 与 irm ... | iex 管道执行,先把脚本下载下来审阅再运行;② 裸 herdr 命令是「启动或附加 TUI」,不是命令发现入口,查命令要用 herdr --help 或 herdr agent 这样的命令组;③ 官方明确说明服务或机器重启后恢复的是保存的布局与受支持 Agent 的会话状态,原来的操作系统进程不会存活,别把 detach 当成进程级容灾。此外,Windows 提权运行的服务端默认只接受管理员客户端,若普通客户端连不上,需要按官方说明配置 [server] allow_unelevated_clients = true 或启动时加 --allow-unelevated-clients。

先弄清:Herdr 管的是终端,不是替你跑 Agent

官方 README 把定位写得很直白:它不包装、也不替换你已有的 Agent,只是「拥有它们的终端」。理解下面这组概念,后面的命令就不会用错对象。

概念官方口径本教程落在哪步
workspace / tab / pane终端位置的三层拓扑;pane 无论里面有没有 Agent 都存在Step 3 用 list 命令发现 ID
pane 命令管原始终端、shell、测试、服务器、输入输出Step 5 用 pane run 跑命令
agent 命令管被识别出来的编码 Agent,解释 idle / working / blocked / done / unknown 生命周期Step 4、Step 5 起 Agent 与委派任务
pane marks每个 pane 标记 working、blocked、idle;需要人回答时会提示Step 6 处理 blocked 卡点
agent skill一份 Markdown 指令文件,教 Agent 在 HERDR_ENV=1 时用 herdr CLI 控制会话Step 2 用 npx skills add 装载

状态标记不等于语义承诺:官方 SKILL.md 写明,idle 与 done 通常表示 Agent 可以接输入,但不代表陌生的审批弹窗已被识别,也不代表保留了身份的 Agent 仍在前后台正确位置;blocked 表示 Herdr 认出了审批或提问界面;unknown 表示有 Agent 但无法可靠分类。Antigravity 与 Grok 在后台任务或子智能体仍在跑时也可能显示 idle,因此「等到 settled 状态」不能当作那些任务已经完成的证据。

Step 1:审阅安装脚本,跑通启动与断线重连

1 装好二进制,先练一次 detach 与 reattach

官方给出四条安装路线:脚本、Homebrew、mise、Windows PowerShell,也可直接从 GitHub Releases 下二进制。装完先别急着拆 pane,用一条会持续输出的命令验证「关掉客户端,活仍在跑」这一核心行为。

# 先把脚本取下来审阅,再执行(macOS / Linux)
curl -fsSL https://herdr.dev/install.sh -o herdr-install.sh
less herdr-install.sh
sh herdr-install.sh

# 其它官方路线,任选其一:
# brew install herdr
# mise use -g herdr
# Windows PowerShell:
# powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

# 用 --help 做命令发现;裸 herdr 会启动或附加 TUI
herdr --help
herdr status

# 进入工作目录并启动(这一步会打开 TUI)
cd ~/practice-repo
herdr

# 在 TUI 里开一个持续输出的命令,例如:
# ping 127.0.0.1
# 然后按官方快捷键 ctrl+b q  detach,回到普通 shell
herdr          # 重新附加;刚才的命令输出应当还在继续
💡 官方 README 说明,detach 之后后台服务仍保留终端;服务端或机器重启后,Herdr 会恢复保存的布局并尝试恢复受支持的 Agent 会话,但原 OS 进程不会复活。另外 v0.9.5 起,在 Linux / macOS 上关闭启动 Herdr 的那个 shell 不再停止服务端,脚本里要停服务请改用 herdr server stop 或 SIGTERM,别再发 SIGHUP。

Step 2:装载官方 agent skill,并核验 HERDR_ENV

2 让 pane 里的 Agent 学会用 herdr CLI 互相协同

官方在 skills/herdr/SKILL.md 提供一份可直接装进编码 Agent 的技能文件,安装方式是用 npx skills。技能开头就有一条护栏:进程里没有 HERDR_ENV=1 时,Agent 应当停下并说明自己不在 Herdr 管理的 pane 里,避免外部进程越权控制会话。

# 全局安装官方技能(-g);省略 -g 则装到当前项目
npx skills add herdrdev/herdr --skill herdr -g

# 打印与本机二进制版本一致的那份技能副本,作为核对基准
herdr --skill > herdr-SKILL.md
head -n 12 herdr-SKILL.md 2>/dev/null || python -c "print(open('herdr-SKILL.md').read()[:600])"

# 在 Herdr pane 里启动 Agent 后,先做环境核验
# test "${HERDR_ENV:-}" = 1
# 官方还注入了三个上下文变量:
printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

# 给 Agent 用的命令发现入口(不带子命令即打印命令组)
herdr agent
herdr pane
herdr workspace
herdr tab
herdr session
herdr integration

别把技能文件和教学指南搞混:官方说明 skills/herdr/SKILL.md 是给「正在操作 Herdr 的 Agent」看的;而 herdr.dev/agent-guide.md 是给「帮人类学习、配置、排障的 Agent」看的,两者用途不同。另外官方提示:若你以前把技能装在仓库根目录,重新执行一次 npx skills add herdrdev/herdr --skill herdr -g 即可替换旧副本,不要用 skills update 顶替这一步。多数控制命令返回 JSON,请从响应里读 ID,别照抄本文示例里的 w1:p1。

Step 3:发现布局、pane ID 与 Agent 状态

3 用只读命令把当前会话画成一张清单

官方 SKILL.md 给出的 ID 形态是 workspace w1、tab w1:t1、pane w1:p1,关闭的 tab / pane ID 不会复用。先用一组只读命令拿到真实 ID,再决定往哪儿拆 pane;--current 用于把命令指向调用方所在 pane,比依赖「当前焦点 pane」更稳。

# 以下在 Herdr 管理的 pane 内执行(HERDR_ENV=1)
herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

# 看某个 pane 的布局,决定往右还是往下拆
herdr pane layout --pane "$HERDR_PANE_ID"

# 客户端与服务端版本可能在升级后不一致,用 status 核对
herdr status

# 官方约定:多数控制命令返回 JSON;服务端错误为 stderr 上的 JSON且退出码 1,
# 语法错误退出码 2。脚本里请按退出码与 JSON 字段判定,别匹配人话文案。
💡 官方建议:宽 pane 往右拆,窄或高的 pane 往下拆,避免同方向反复切出没法用的窄列;后台工作一律带 --no-focus 保持用户焦点不变;pane split 不指定目标时,在有 HERDR_PANE_ID 的环境里使用调用方 pane,否则使用焦点 pane。所有 ID 都从创建命令的 JSON 响应里取,别根据侧边栏顺序去猜。

Step 4:拆一个同级 pane,起第二个 Agent

4 在同一个 tab 里拉起一个「评审员」

官方 SKILL.md 强调:agent start 需要一个已存在且可用的 shell pane,它自己不会创建、拆分或移动布局;所以顺序是先用 pane split 造 pane,再从响应里取 .result.pane.pane_id,最后 agent start。Agent 名称需符合 [a-z][a-z0-9_-]{0,31} 且在存活的 Agent 里不重名。

# 在调用方 pane 的右侧拆一个新 pane,保留当前工作目录,不抢焦点
herdr pane split --current --direction right --cwd "$PWD" --no-focus
# 从上面命令的 JSON 里取 .result.pane.pane_id,填入下面变量
PANE_ID="w1:p2"     # 这里只是示意,请替换为真实返回值

# 查看安装时支持的 Agent 类型,再按类型启动
herdr agent
herdr agent start reviewer --kind codex --pane "$PANE_ID"
# 若需要给原生客户端传参,放在 -- 之后:
# herdr agent start reviewer --kind codex --pane "$PANE_ID" -- 原生参数

# 启动成功后确认身份与状态
herdr agent get reviewer
herdr agent list

启动成功不等于可以立刻派活:官方说明 agent start 要等 Herdr 在同一 pane 里识别到目标 Agent 并认为它可接受交互输入才返回,默认启动超时 30 秒;若启动时就被审批界面挡住,命令会立刻返回 agent_not_ready 但保留名称,此时应用 agent read / agent send-keys 排查,等它变成 idle 再发提示词。另外名称跟随当前 pane 的占用者,Agent 退出、被释放或被替换后名称会被清掉。

Step 5:委派任务、等待状态,并读取结果

5 让主 Agent 把评审工作交给 reviewer

这一步是 Herdr 相对 tmux 的差别所在:agent prompt 会按 pane 的 bracketed-paste 模式把文本与编码后的 Enter 作为一次有序提交写入,并可用 --wait 等 settled 状态出现;若目标正卡在审批或提问界面,会以 agent_blocked 拒绝发送任何输入。普通命令则走 pane run 与 pane wait-output。

# 给 reviewer 派一个只读评审任务,等待它进入 settled 状态
herdr agent prompt reviewer \
  "Review the current diff and report only actionable findings." \
  --wait --timeout 120000

# 只想知道「它是不是在等人回答」时,用状态特定的等待
herdr agent wait reviewer --until blocked --timeout 120000

# 读取结果与最近输出(source 选 recent-unwrapped 更适合日志)
herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

# 普通命令走 pane 通道:先拆 pane,再跑、等、读
herdr pane split --current --direction down --cwd "$PWD" --no-focus
herdr pane run "just test"
herdr pane wait-output --match "test result" --timeout 120000
herdr pane read --source recent-unwrapped --lines 120

# 需要给 Agent UI 发按键时,用逻辑键名,Herdr 会先校验再写入
herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c
💡 官方说明 --wait 默认等 idle / done / blocked 这类 settled 状态,不必再叠 --until;从非 working 状态发出的提示词必须观测到 working 或 blocked 活动,五秒内没观测到会返回 agent_prompt_stalled,调用方超时则返回 timeout。pane run 的「成功」只表示命令文本已被受理,不代表执行完成;pane wait-output 会立即检索当前快照,已有输出也能命中。读输出可用 visible / recent / recent-unwrapped / detection 四种来源,需要颜色证据时加 --format ansi。

Step 6:处理 blocked 卡点、版本差异与会话收口

6 让「卡住的那一格」变成可复现的运维动作

多 Agent 协作最常翻车的地方,是某个 pane 悄悄停在审批弹窗上。官方技能给出的处置顺序是:等待返回 blocked 后先读 UI,再问人,绝不替用户回答审批;同时用 herdr status 核对客户端与服务端版本,用 herdr integration install codex 更新集成(v0.9.5 起 Herdr 不再安装 Codex turn hooks,状态改由屏幕检测)。需要跨机器时,所有命令都要带同一个 --machine 前缀。

# 1) 发现 blocked:读 UI,再把决定交给人
herdr agent wait reviewer --until blocked --timeout 120000
herdr agent get reviewer
herdr agent read reviewer --source visible --lines 60

# 2) 版本与集成:客户端和服务端升级后可能不一致
herdr status
herdr integration install codex
herdr plugin update

# 3) 保存的机器:发现与后续命令使用同一个全局前缀
herdr machine list --json
herdr --machine agent list
herdr --machine pane list
herdr --machine agent prompt "Reply with your current status." --wait --timeout 120000

# 4) 排障与收尾
# herdr machine status MACHINE_ID --json
# 注意:官方说明 --machine 不能与 --session 或 --remote 组合;
# 重新连接需要用户自己完成 SSH 认证,别让 Agent 代跑 reconnect。
# 不要从活动会话里执行 herdr server stop,除非明确要停掉服务端与其 pane 进程。

四条官方安全规则请照抄进团队约定:① 不要关闭不是自己创建的 workspace / tab / pane / session,普通 CLI 关闭不会继承 TUI 的末 pane 确认;② workspace close --group 会连带关掉主 workspace 与关联 worktree workspace,别为了绕过 workspace_group_close_required 随手加;③ --trust-repository 只在人工核对仓库后使用,它是按次授予的 Git 信任,不是常规重试;④ 连接失败不代表变更没生效,跨机器场景要先查远端状态再决定是否重试。远程 worktree 路径需为完整路径或以 ~ 开头的写法。

做到哪一步算成功:交付前自查

把这张表当成多 Agent 会话的验收栏。前三行通过,说明会话保持已经生效;后几行通过,说明协作链路可被脚本稳定驱动。

检查项预期结果没过怎么办
安装与断线herdr --help 可用,detach 后命令输出继续增长,reattach 能接回确认没用裸 herdr 做命令发现;查 herdr status
技能装载npx skills add 成功,herdr --skill 能打印与版本匹配的副本确认 Agent 支持技能或自定义指令;否则手工把文件贴进项目说明
环境核验pane 内 HERDR_ENV=1 且三个 ID 变量有值说明 Agent 不在 Herdr 管理的 pane 里,按技能护栏停下
布局发现agent list / pane list 返回真实 ID,脚本从 JSON 读取别照抄示例 ID;检查是否误用了焦点 pane
第二个 Agentagent start 返回后 agent get 能看到该名称与状态先看是否 agent_not_ready,用 agent read 排查启动审批
委派与读取agent prompt --wait 有结果,agent read 能取到最近输出区分 agent_blocked / agent_prompt_stalled / timeout,别盲目重发
blocked 处置先读 UI、再问人,Agent 不代答审批把这条写进团队约定与技能提示词
重启预期明白恢复的是会话状态与布局,原 OS 进程不会存活给长任务另留服务端侧持久化方案
🎉 做到这些,你的多个编码 Agent 已经从「各开一个窗口、全靠人盯」变成「有布局、有状态、有 ID、可委派、可等待、可重连」的会话。之后把 agent prompt --wait 与 agent wait --until blocked 组合进自己的脚本,就能做更细的多智能体流水线。

交付前自查的最后一条:本教程命令来自 Herdr 官方 README、agent-skill 文档、v0.9.5 Release 与 skills/herdr/SKILL.md,按 2026-11-16 核对到的版本撰写。官方明确写了「已安装的二进制才是命令语法的权威」,因此每次升级后请重新执行 herdr --help 与各命令组,把本文示例当作结构参考而不是固定签名。

常见问题速查

现象大概率原因与处理
输入 herdr 后进了 TUI,没看到命令帮助裸命令是启动 / 附加;查帮助要用 herdr --help 或 herdr agent 这类命令组
Agent 说不敢控制会话技能护栏生效:先 test "${HERDR_ENV:-}" = 1,不满足就说明不在 Herdr pane 内
agent start 报 agent_not_ready启动时被审批界面挡住;名称会保留,用 agent read / agent send-keys 排查后等 idle
agent prompt 返回 agent_blocked目标正停在审批或提问界面,Herdr 在写入输入前就拒绝;先读 UI 并交给人决定
agent_prompt_stalled 或 timeout五秒内未观测到 working / blocked 活动,或调用方超时;超时不代表提示词没送达,别盲目重发
pane run 成功却看不到命令结果成功仅表示命令文本已被受理;补 pane wait-output 再 pane read
拆 pane 后 ID 对不上从 .result.pane.pane_id 取新 ID;pane move 之后旧 ID 不再通用
重启机器后 Agent 没接着跑官方说明恢复的是布局与会话状态,原 OS 进程不存活;别把 detach 当进程容灾
Windows 普通客户端连不上提权服务端按 v0.9.5 说明设 [server] allow_unelevated_clients = true 或加 --allow-unelevated-clients
跨机器命令作用到了本机--machine 需要对发现与后续每条命令使用同一前缀,且不能与 --session / --remote 组合
升级后新命令报错客户端与服务端版本可能不一致;先 herdr status,再按 herdr --help 核对语法
📌 配套阅读:本中心《用 Agent Autoloop 让命令行 Agent 在后台接活》讲的是定时与事件规则驱动的后台任务;本篇讲的是终端会话的保持、状态观测与多 Agent 协同,两者解决的是不同层面的问题。
← 返回教程中心