herdr

Herdr

Herdr 将终端组织为工作区（workspace）、标签页（tab）和分屏（pane），能够识别在分屏内运行的编程 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 来寻找可用选项，因为这会启动或附加到 TUI 界面。也不要通过省略参数来探测带有修改性质（mutating）的嵌套命令。像 herdr workspace create 这类命令在带有默认值时即为有效命令并会直接执行。

大多数控制命令都会返回 JSON 格式数据。请直接从这些响应中读取标识符（ID）和状态，而不是靠推测。

理解布局、分屏与 Agent

选择与具体任务相匹配的原语（primitive）：

• 工作区（Workspace）、标签页（Tab）和分屏（Pane）拓扑结构用于组织终端的位置。
• 分屏（Pane）命令用于控制原生终端、Shell、测试、服务端程序、输入与输出。
• Agent 命令用于控制当前占据某个分屏且已被识别的编程 Agent。

无论分屏内是否包含 Agent，分屏都是独立存在的。agent start 需要在一个现成可用的 Shell 分屏中运行，并且绝不会自动创建、拆分或移动布局。普通进程请使用分屏命令；当 Herdr 需要校验 Agent 身份或解读 idle（空闲）、working（工作中）、blocked（被阻塞）、done（已完成）和 unknown（未知）等生命周期状态时，请使用 Agent 命令。

Agent 命令接收活跃 Agent 的唯一名称或当前承载该 Agent 的分屏 ID。不接收终端 ID 或纯 Agent 类型（agent-kind）标签。名称必须符合 [a-z][a-z0-9_-]{0,31} 正则规范，且在当前活跃的 Agent 中保持唯一。名称会跟随当前分屏的占用者，当该 Agent 退出、被释放或被替换时，名称将被清除。

idle 表示 Agent 已准备好接收输入，且其对应的标签页已在当前聚焦的 Herdr UI 中被查阅过。done 本质上是相同的空闲状态，表示未被查阅的后台工作已完成。聚焦该标签页，或者通过聚焦命令指定该分屏或 Agent，都会将其标记为已查阅。仅通过 CLI 读取输出不会将其标记为已查阅。blocked 表示 Herdr 识别到了需要人工审批或提问互动界面。unknown 表示存在 Agent，但 Herdr 无法确定其具体状态；这并不代表执行已完成。

使用 ID 与调用者上下文

公开 ID 均为不透明且稳定的句柄：

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

已关闭的标签页和分屏 ID 不会被重复使用。被移动到另一个工作区的分屏会获得一个新的带工作区前缀的分屏 ID。在执行 pane move 之后，请继续使用 .result.move_result.pane.pane_id 或活跃 Agent 的名称。旧值会以 .result.move_result.previous_pane_id 返回；只有被移动进程继承的调用者上下文会继续解析该旧 ID，因此切勿将其作为通用的 Agent 目标。

Herdr 会将调用者的上下文注入到每个受管理的分屏中：

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

当分屏命令需要以当前调用者分屏为目标时，优先使用 --current 参数。如果省略目标，可能会默认作用于 UI 当前聚焦的分屏，而该分屏可能属于用户或其他客户端。

使用以下命令探索当前活跃状态：

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 返回。

启动与协调 Agent

默认在当前标签页和当前工作目录中创建同级（sibling）分屏。除非用户明确要求特定的拓扑结构或位置，否则不要创建新的工作区、标签页、工作树（worktree）或更改工作目录（cwd）。

如果用户指定了分屏方向，请遵照执行。否则，先检查调用者分屏的几何布局：

herdr pane layout --pane "$HERDR_PANE_ID"

较宽的分屏向右拆分（right），较窄或较高分屏向下拆分（down）。避免同方向连续拆分导致出现无法实用的超窄列或超矮行。保持用户的焦点在调用者分屏中，并明确保留调用者的工作目录：

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>

使用用户要求的 Agent 类型（kind）。运行 herdr agent 可查看已安装的类型列表与选项。原生 Agent 参数必须放在 -- 之后传入：

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

agent start 仅在 Herdr 检测到预期 Agent 已在目标分屏中就绪并准备好接收交互输入后才会返回。默认启动超时时间为 30 秒。

通过 Agent 接口提交工作：

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

agent prompt 会原子化地提交文本和编码后的回车符（Enter），同时遵循分屏当前的括号粘贴模式（bracketed-paste mode）。对于常规 Agent 任务，使用 --wait 就足够了：它会等待状态首次结算为 idle、done 或 blocked。不要使用 --until 重复这些默认行为。

从非工作状态发送的提示词必须在 5 秒内产生观察到的生命周期变更。否则 Herdr 将返回 agent_prompt_stalled 而不是无限期等待。该等待追踪的是生命周期状态，而非单个轮次；如果 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）。pane wait-output 会立即检索选定的快照，因此已存在的输出也可以匹配成功。使用 --match <text> 进行精确子字符串匹配，或使用 --regex <pattern> 进行 Rust 正则表达式匹配。省略 --timeout 则允许无限期等待。

选择与任务匹配的读取来源（source）：

• visible：当前渲染的视口。
• recent：最近渲染的输出，包含软换行（soft wrap）。
• recent-unwrapped：最近渲染的输出，已合并软换行；日志和转录（transcript）推荐使用此项。
• detection：用于检测 Agent 的纯文本底部缓冲区快照。

当颜色和终端样式属于关键证据时，使用 --format ansi。否则使用 plain text。

--lines 用于向 Herdr 请求分屏可用屏幕和宿主回滚缓冲区（scrollback）中的更多行数。如果增加行数仍无法显现更多已完成的响应内容，可能是因为该分屏正在终端的备用屏幕（alternate screen）上运行 Agent。离开备用屏幕的行不会进入 Herdr 的宿主回滚缓冲区，因此增加行数也无法恢复它们。

遇到这种读取失败后，可以要求 Agent 将完整响应以 Markdown 格式写入临时目录，并仅回复文件路径，然后直接读取该文件。注意：此方法仅作为兜底方案，切勿在初始提示词中就要求文件输出。

安全与协调规则

• 后台工作务必使用 --no-focus，除非用户明确要求切换上下文。
• 使用 --current、显式分屏 ID 或唯一 Agent 名称。切勿依赖其他客户端聚焦的分屏。
• 从 JSON 响应中解析 ID。切勿从侧边栏顺序或示例推断 ID。
• 不要关闭非你自己创建的工作区、标签页、分屏或会话，除非用户明确要求。
• 绝不要从活动会话中运行 herdr server stop，除非用户明确打算停止服务器及其分屏进程。
• 绝不要杀掉 Herdr 主进程。需要隔离服务器的实验请使用命名测试会话（named test session）。
• CLI 服务器错误会以 JSON 形式输出至 stderr 并以状态码 1 退出。CLI 语法错误以状态码 2 退出。