herdr

Herdr

Herdr 将终端组织为工作区、标签页和窗格，识别在窗格中运行的编码 Agent，并通过 herdr CLI 提供当前会话。

在发出任何控制命令之前，请确认此 Agent 正在 Herdr 管理的窗格中运行：

test "${HERDR_ENV:-}" = 1

如果检查未通过，请说明你不在 Herdr 中运行，然后停止。不要从 Herdr 外部检查或控制当前获得焦点的 Herdr 会话。

检查通过后，PATH 中的 herdr 二进制文件会与当前会话通信。使用它检查相邻工作、创建终端布局、启动 Agent 和命令、读取输出，以及等待状态变化。

了解当前 CLI

已安装的二进制文件是命令语法的权威来源。请从以下命令开始：

herdr --help

然后，不带子命令运行相关命令组，以显示该组的命令：

herdr agent
herdr pane
herdr workspace
herdr tab
herdr worktree
herdr terminal
herdr notification
herdr integration
herdr session
herdr machine

不要直接运行裸 herdr 来探索命令；它会启动或连接到 TUI。不要省略参数来试探会修改状态的嵌套命令。像 herdr workspace create 这样的命令可以使用默认值运行，并会实际执行。

大多数控制命令都会返回 JSON。请从这些响应中读取标识符和状态，而不要自行猜测。

了解布局、窗格和 Agent

根据任务选择合适的基本操作：

• 工作区、标签页和窗格拓扑用于组织终端位置。
• 窗格命令用于控制原始终端、Shell、测试、服务器、输入和输出。
• Agent 命令用于控制当前占据某个窗格且已被识别的编码 Agent。

无论是否包含 Agent，窗格都存在。agent start 要求已有可用的 Shell 窗格，且不会创建、拆分或移动布局。普通进程请使用窗格命令。需要 Herdr 验证 Agent 身份或解读 idle、working、blocked、done 和 unknown 生命周期状态时，请使用 Agent 命令。

Agent 命令接受唯一的活动 Agent 名称，或当前托管该 Agent 的窗格 ID。它们不接受终端 ID 或不带其他信息的 Agent 类型标签。名称必须匹配 [a-z][a-z0-9_-]{0,31}，并且在活动 Agent 中唯一。名称会跟随当前窗格占用者，并会在该 Agent 退出、释放或被替换时清除。使用 Ctrl+Z 暂停 Agent 并运行非 Agent 命令时，只要原进程仍然存活，其身份就会保留。但如果另一个已识别的 Agent 接管，则原身份不会保留。保留身份不代表 Agent 位于前台；发送输入前请先检查窗格。

idle 和 done 通常表示 Agent 已准备好接收输入；但这两种状态都不能保证陌生的审批对话框已被识别，也不能保证保留身份的 Agent 位于前台。CLI/API 使用服务器记录的已查看状态来区分这两种状态；显式的聚焦命令会将目标标记为已查看，而读取操作不会。每个 TUI 客户端会独立跟踪已查看的完成状态，因此其 Done 徽标可能与 CLI 或其他客户端上的徽标不同。Antigravity 和 Grok 在后台任务或子 Agent 仍在运行时也可能处于空闲状态，因此等待状态稳定并不能证明这些任务已完成。blocked 表示 Herdr 识别到了审批或提问界面。unknown 表示存在 Agent，但 Herdr 无法有把握地对其分类；这并不能证明任务已完成。

使用 ID 与调用方上下文

公共 ID 是不透明的稳定句柄：

• workspace：w1
• tab：w1:t1
• pane：w1:p1

已关闭的 tab 和 pane ID 不会被复用。移动到另一个 workspace 的 pane 会获得一个带 workspace 限定的新 pane ID。执行 pane move 后，请继续使用 .result.move_result.pane.pane_id 或当前活跃的 agent 名称。旧值会通过 .result.move_result.previous_pane_id 报告；只有被移动进程继承的调用方上下文仍能解析该旧 ID，因此不要将其用作通用的 agent 目标。

Herdr 会将调用方的上下文注入到每个受管理的 pane 中：

printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"

当 pane 命令应指向调用方 pane 时，优先使用 --current。省略 pane split 目标时，如果 HERDR_PANE_ID 可用，则使用调用方 pane，否则使用当前聚焦的 pane。其他命令可能使用 UI 聚焦的 pane，该 pane 可能属于用户或另一个客户端。

使用以下命令发现实时状态：

herdr workspace list
herdr tab list --workspace "$HERDR_WORKSPACE_ID"
herdr pane current --current
herdr pane list --workspace "$HERDR_WORKSPACE_ID"
herdr agent list

创建操作的响应会给出接下来要使用的 ID。workspace create 返回 .result.workspace、.result.tab 和 .result.root_pane。tab create 返回 .result.tab 和 .result.root_pane。pane split 以 .result.pane 返回新 pane。

ID 和活跃 agent 名称的作用域限定在单个服务内。两台已保存的 SSH 机器可能都有 w1:p1 或一个名为 reviewer 的 agent。在 TUI 中选择某台机器不会重定向你 pane 中运行的命令：如果不加 --machine，它们仍使用继承的会话和 socket 上下文。

要控制一台已保存的 SSH 机器，请在发现和后续每条命令中使用相同的全局前缀：

herdr --machine <label-or-id> agent list
herdr --machine <label-or-id> pane list
herdr --machine <label-or-id> agent prompt <remote-agent-name> "Reply with your current status." --wait --timeout 120000

选择器必须是已启用的已保存 profile ID 或唯一且区分大小写的 label，而不是任意的 SSH 主机名。命令会在没有打开 TUI 的情况下使用该 profile 的远程会话。不要将 --machine 与 --session 或 --remote 组合使用。要在该机器上发现 ID；继承的本地 ID 和 --current 无法标识远程 pane。

两个安装都必须支持 machine API 转发，并且远程服务必须已在运行且 API 兼容。转发绝不会安装、启动或重启服务，也绝不会回退到 Local。本地配置、会话管理、安装命令和交互式附加不会被转发。远程 worktree 路径必须是绝对路径、~ 或以 ~/ 开头；插件链接路径必须是绝对路径。连接失败并不能证明某项变更未被应用：重试前请检查远程状态。

herdr machine list 列出的是已保存的连接 profile，而不是跨机器的 pane 清单；脚本中可加 --json。仅在用户要求时添加、删除、启用或禁用 profile。删除 profile 会断开客户端连接，但不会停止远程会话。交互式 machine add 会发现正在运行的远程会话，并可能要求用户选择其中一个；非交互式设置使用远程默认会话，除非显式提供 --remote-session。使用 herdr machine status [<label-or-id>] --json 诊断故障机器。herdr machine reconnect 需要用户在其终端中完成 SSH 认证；不要替他们运行它。设置过程会在停止不兼容服务前询问，默认选择 No；未经用户同意不要批准替换。实验性 handoff 不属于 machine add 的一部分。

启动并协调一个 Agent

默认使用当前标签页中的同级窗格和当前工作目录。除非用户明确要求该拓扑结构或位置，否则不要创建工作区、标签页、worktree 或不同的 cwd。

遵循用户要求的方向。否则检查调用方窗格：

herdr pane layout --pane "$HERDR_PANE_ID"

将宽窗格向右拆分，将窄窗格或高窗格向下拆分。避免重复进行同方向拆分，以免产生窄得无法使用的列或短得无法使用的行。将用户焦点保留在调用方窗格中，并显式保留调用方的工作目录：

herdr pane split --current --direction right --cwd "$PWD" --no-focus

在适当情况下将 right 替换为 down。从 .result.pane.pane_id 读取新窗格 ID。

可用的 shell 窗格必须处于其交互式提示符下，shell 本身在前台运行，且没有前台命令、编辑器或 Agent 正在运行。在该窗格中启动一个受支持的 Agent，并使用一个有用且唯一的名称：

herdr agent start reviewer --kind codex --pane <returned-pane-id>

使用用户请求的类型。运行 herdr agent 以查看已安装的类型列表和选项。仅在 -- 之后传递原生 Agent 参数：

herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>

agent start 只有在 Herdr 在同一窗格中检测到预期的 Agent 并认为其已准备好接受交互式输入后才会成功返回。如果 Agent 在启动期间被阻塞，该命令会立即返回 agent_not_ready，但会保留该名称供 agent read 和 agent send-keys 使用。等待 Agent 变为空闲后再向其发送提示词。启动默认超时时间为 30 秒。

通过 Agent 接口提交工作：

herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000

agent prompt 遵循窗格当前的括号粘贴模式，并将文本及编码后的 Enter 作为一个有序提交一并发送。只有在两者都已写入后，它才会报告提交成功；这本身并不能证明 Agent 已开始一轮处理。对于 Windows 上的 Codex，Herdr 会在 Enter 之前发送一个粘贴边界，因此提交不依赖于提示词大小。如果 Agent 已在审批或提问对话框处等待，它会在发送任何输入之前以 agent_blocked 拒绝。检查被阻塞的 UI，并在回答之前询问用户。对于正常的 Agent 工作，--wait 就足够了：它会等待第一个稳定为 idle、done 或 blocked 的状态。不要用 --until 重复这些默认行为。

使用 --wait 时，从非工作状态发送的提示词必须产生可观察到的 working 或 blocked 活动。提交后，Herdr 最多等待五秒以获取该活动；无关的 idle、done 或会话变化不满足此门槛。如果未观察到任何活动，则返回 agent_prompt_stalled；如果调用方超时先到期，则返回 timeout。调用方超时包括提交时间。如果没有设置超时，则在观察到活动后，对稳定状态的等待会无限期持续。此等待跟踪的是生命周期状态，而不是单轮处理；如果 Agent 已在工作，则当前轮次的完成可能会满足该等待。

仅在特定状态的工作流中使用 --until，例如等待一个已在运行的 Agent 请求输入：

herdr agent wait reviewer --until blocked --timeout 120000

如果不使用 --until，独立的 agent wait 会使用与 agent prompt --wait 相同的稳定状态默认行为。

使用逻辑键进行交互式 Agent UI 控制：

herdr agent send-keys reviewer esc
herdr agent send-keys reviewer ctrl+c

Herdr 会在写入任何字节之前验证所有键。通过解析后的 Agent 读取结果：

herdr agent get reviewer
herdr agent read reviewer --source recent-unwrapped --lines 120

如果等待失败或返回 blocked，在决定发送什么输入之前，先检查 agent get 和 agent read。超时或停滞响应并不能证明提示词从未送达；不要盲目再次提交。仅在有意进行原始终端控制时才使用窗格接口。

在另一个窗格中运行普通命令

创建一个采用相同几何规则的同级窗格，保留调用方的工作目录，并保持用户焦点不变：

herdr pane split --current --direction right --cwd "$PWD" --no-focus

从 .result.pane.pane_id 读取新窗格 ID，然后运行并检查命令：

herdr pane run <returned-pane-id> "just test"
herdr pane wait-output <returned-pane-id> --match "test result" --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

pane run 会将命令文本和 Enter 一并排入队列；成功表示命令已被接收，而非已执行。在 macOS 上，如果命令超出终端当前的规范行输入限制，pane run 和 agent start 会在排队前拒绝该命令。请等待交互式 shell 提示符出现后再重试。此检查仅针对本次提交，不涵盖之前未完成的命令行，也不涵盖之后的终端模式变更。pane wait-output 会立即搜索所选快照，因此已有输出也可能匹配。使用 --match <text> 匹配字面子串，或使用 --regex <pattern> 匹配 Rust 正则表达式。省略 --timeout 可无限等待。

请根据任务选择匹配的读取源：

• visible：当前渲染的视口。
• recent：近期渲染的输出，包括软换行。
• recent-unwrapped：近期输出，并将软换行拼接起来；读取日志和转录文本时优先使用。
• detection：用于 Agent 检测的纯文本底部缓冲区快照。

当颜色和终端样式是证据时，使用 --format ansi。否则使用 text。

--lines 会让 Herdr 从窗格可用的屏幕内容和主机滚动缓冲区中读取更多行。备用屏幕中的行不会进入普通主机滚动缓冲区。对于受支持的空闲 Agent，Herdr 可以收集应用拥有的历史记录并在之后恢复视口，但并非所有应用或响应都能以这种方式恢复。

如果扩大近期读取范围后仍看不到已完成的响应，请让 Agent 将其以 Markdown 格式写入临时目录，并且只回复文件路径，然后在同一台机器上读取该文件。仅将此作为后备方案；不要在初始提示中要求输出文件。

安全与协作规则

• 除非用户要求切换上下文，否则后台工作请使用 --no-focus。
• 使用 --current、明确的窗格 ID 或唯一的 Agent 名称。不要依赖其他客户端当前聚焦的窗格。
• 从 JSON 响应中解析 ID。不要根据侧边栏顺序或示例推断 ID。
• 除非用户明确要求，否则不要关闭由你创建的工作区、标签页、窗格或会话。普通 CLI/API 关闭操作不会沿用 TUI 的最后一个窗格确认机制。workspace close --group 会关闭主工作区及其关联的 worktree 工作区；绝不要为了绕过 workspace_group_close_required 而添加它。
• 仅在用户已验证仓库后，才使用 --trust-repository。它会授予单次请求的 Git 信任；不要把它作为 worktree 命令失败后的常规重试方式。
• 更新后，客户端和服务端版本可能不同。依赖新的服务端功能前，请检查 herdr status。缺少某个方法并不意味着可以停止或升级服务端。
• 除非用户明确打算停止服务端及其窗格进程，否则绝不要在活动会话中运行 herdr server stop。
• 绝不要终止 Herdr 主进程。需要隔离服务端进行实验时，请使用命名测试会话。
• CLI 服务端错误会以 JSON 格式输出到 stderr，退出状态为 1。CLI 语法错误的退出状态为 2。