Herdr pane run 与 wait-output 完整指南：脚本等待终端输出的正确姿势-开发者社区

Herdr pane run 与 wait-output 完整指南：脚本等待终端输出的正确姿势

【免费下载链接】herdrthe runtime your coding agents live on项目地址: https://gitcode.com/GitHub_Trending/her/herdr

Herdr 是编码智能体运行的终端运行时，它的pane run与pane wait-output命令对，正是让脚本可靠地"向终端发命令、等终端出结果"的标准姿势。告别sleep盲等和脆弱的grep轮询，两行命令就能完成"发送 + 等待匹配输出"的完整闭环。

为什么需要 pane run + wait-output

脚本操作终端窗口时最常见的坑是：命令发出去了，但不知道它什么时候跑完。传统做法要么sleep 30盲等（慢且不可靠），要么反复读屏轮询（代码啰嗦还容易漏输出）。

Herdr 把这件事拆成了两个原子操作：

命令	职责
`pane run`	原子发送命令文本并自动按 Enter 提交
`pane wait-output`	阻塞等待终端输出中出现指定文本或正则，命中即返回

pane run的实现在 src/cli/pane.rs 中：它把命令文本和Enter键合并为一次输入事件发送给目标窗格，不会出现"文本发了一半回车没跟上"的竞态。

第一步：用 pane run 原子提交命令

herdr pane run w1:p3 "just test"

格式非常简单：herdr pane run <pane_id> <command>。窗格 ID 形如w1:p3，可用herdr pane list查询。命令文本会被完整拼接后一次性提交，多词命令直接整体加引号即可。

第二步：用 wait-output 等待输出匹配

herdr pane wait-output w1:p3 --match "test result" --timeout 120000

wait-output的完整用法（定义见 src/cli/pane.rs）：

herdr pane wait-output <pane_id> (--match <text> | --regex <pattern>) \ [--source visible|recent|recent-unwrapped] [--lines N] [--timeout MS] [--raw]

--match 与 --regex 怎么选

--match <text>：在单行内查找字面子串，最简单直接，适合等待done、BUILD SUCCESS这类固定文本。
--regex <pattern>：使用 Rust 正则语法，同样逐行匹配，适合"通过或失败都算结束"的场景，例如--regex "passed|failed"。

两者互斥，必须提供其中之一。

三个关键参数的含义

--source：默认recent，即最近 80 个已渲染终端行的"未折行"输出；也可选visible（当前可见屏幕）或recent-unwrapped。
--lines N：调整等待时检索的行数窗口，默认 80 行。
--timeout MS：超时毫秒数。省略--timeout会无限等待，自动化脚本强烈建议显式设置。

服务端等待逻辑在 src/api/wait.rs：它会立即检查一次当前快照（所以输出已经存在时也能秒中），随后按固定间隔轮询直到匹配或超时；正则非法时返回invalid_regex错误而不是默默失败。

用退出码写健壮的脚本判断

wait-output的退出状态非常适合if判断：

退出码	含义
`0`	匹配成功，stdout 输出含`.result.matched_line`与快照的 JSON
`1`	超时或服务端错误，stderr 输出 JSON 错误（如`timeout`）
`2`	命令行用法错误

成功响应包含.result.pane_id、.result.matched_line和位于.result.read的匹配快照，方便脚本二次解析。

实战示例：跑测试并等待结果

完整的"发送 + 等待 + 判断"套路（更多配方见 docs/next/website/src/content/docs/agent-automation.mdx）：

herdr pane run w1:p3 "just test --watch" if herdr pane wait-output w1:p3 --regex "passed|failed" --timeout 120000; then echo "测试有结果了" else echo "测试超时" >&2 exit 1 fi

如果窗口还没准备好，也可以先拆分新窗格再操作，pane split的返回值里直接包含新窗格 ID：

split=$(herdr pane split --current --direction right --no-focus) pane_id=$(printf '%s\n' "$split" | jq -r '.result.pane.pane_id')

常见误区：pane wait-output vs agent wait

⚠️ 这是新手最容易混淆的点：

普通命令、测试、服务器→ 用pane wait-output（按文本/正则匹配，不解释智能体生命周期）。
编码智能体（Claude、Codex 等）→ 用agent wait，它按idle/done/blocked等生命周期状态等待，而不是碰运气猜输出文本。

官方文档 cli-reference.mdx 也明确建议：普通流程用pane wait-output，智能体流程用agent wait。完整的命令速查（包括pane split、pane read、协作配方）收录在 skills/herdr/SKILL.md 中。

Herdr pane run 与 wait-output 完整指南：脚本等待终端输出的正确姿势