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 来发现命令；它会启动或连接到 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 退出、被释放或被替换时，名称会被清除。

idle 表示 Agent 已准备好接收输入，并且其标签页已在聚焦的 Herdr UI 中被查看。后台工作完成后，底层处于相同的空闲状态，但尚未被查看时，状态为 done。聚焦标签页，或通过聚焦命令指定窗格或 Agent，都会将其标记为已查看。CLI 读取操作不会将其标记为已查看。blocked 表示 Herdr 识别到了审批界面或提问界面。unknown 表示存在 Agent，但 Herdr 无法有把握地判断其状态；这并不能证明任务已完成。

使用 ID 和调用方上下文

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

• 工作区：w1
• 标签页：w1:t1
• 窗格：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

默认在当前标签页中打开一个同级窗格，并使用当前工作目录。除非用户明确要求使用其他拓扑或位置，否则不要创建工作区、标签页、工作树或不同的 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...>

只有当 Herdr 在同一窗格中检测到预期的 Agent，并确认其已准备好接收交互输入后，agent start 才会返回。默认启动超时时间为 30 秒。

通过 Agent 界面提交任务：

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

agent prompt 会原子性地提交文本和编码后的 Enter，同时遵循窗格当前的括号粘贴模式。对于常规 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 可无限期等待。

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

• visible：当前渲染的视口。
• recent：最近渲染的输出，包括软换行。
• recent-unwrapped：最近的输出，并将软换行合并；日志和对话记录优先使用此项。
• detection：用于 Agent 检测的纯文本底部缓冲区快照。

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

--lines 会要求 Herdr 从窗格可用的屏幕内容和主机回滚缓冲区中读取更多行。如果增加行数仍无法显示已完成的响应，则该窗格可能正在终端的备用屏幕上运行 Agent。离开备用屏幕的行不会进入 Herdr 的主机回滚缓冲区，因此增加行数无法恢复这些内容。

读取失败后，请让 Agent 将完整响应以 Markdown 格式写入临时目录，并且仅回复文件路径，然后直接读取该文件。仅将此作为后备方案；不要在初始提示词中要求输出到文件。

安全与协作规则

• 除非用户要求切换上下文，否则后台工作使用 --no-focus。
• 使用 --current、明确的窗格 ID 或唯一的 Agent 名称。不要依赖另一客户端的焦点窗格。
• 从 JSON 响应中解析 ID。不要根据侧边栏顺序或示例推断 ID。
• 除非用户明确要求，否则不要关闭你未创建的工作区、标签页、窗格或会话。
• 除非用户明确希望停止服务器及其窗格进程，否则绝不要在活动会话中运行 herdr server stop。
• 绝不要终止 Herdr 主进程。需要隔离服务器进行实验时，请使用命名测试会话。
• CLI 服务器错误以 JSON 格式输出到 stderr，退出状态为 1。CLI 语法错误的退出状态为 2。