AI Skills
herdr

herdr

热门

控制 Herdr，一个用于编码代理的终端复用器。仅在用户明确提到 Herdr 或要求使用 Herdr 检查或控制窗格、标签、工作区、终端、命令或与另一个代理通信时使用。不要仅仅因为任务可以从后台终端、委托或并行工作中受益而使用。需要 HERDR_ENV=1。

1.7万Star
1140Fork
更新于 2026/7/16
获取 Skill源代码

相关 Skills

video-editing23万ponytail-help8.4万obsidian-markdown3.6万
SKILL.md
readonly只读
name
herdr
description

控制 Herdr，一个用于编码代理的终端复用器。仅在用户明确提到 Herdr 或要求使用 Herdr 检查或控制窗格、标签、工作区、终端、命令或与另一个代理通信时使用。不要仅仅因为任务可以从后台终端、委托或并行工作中受益而使用。需要 HERDR_ENV=1。

Herdr

Herdr 是一个用于编码代理的终端复用器和运行时。它将终端组织成工作区、标签和窗格，检测代理身份和状态，并通过 herdr CLI 暴露运行中的会话。

在发出任何控制命令之前，检查此代理是否在 Herdr 管理的窗格内运行：

test "${HERDR_ENV:-}" = 1

如果检查失败，说明你不在 Herdr 内部运行，并停止。不要从 Herdr 外部检查或控制聚焦的 Herdr 会话。

当检查通过时，PATH 中的 herdr 二进制文件与运行中的会话通信。使用它来检查相邻工作、创建隔离的终端上下文、启动代理和命令、读取其输出以及等待状态变化。

了解当前 CLI

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

herdr --help

然后通过运行不带子命令的相关命令组来打印：

herdr pane
herdr workspace
herdr worktree
herdr tab
herdr wait
herdr terminal
herdr notification
herdr integration
herdr session

不要运行裸的 herdr 进行发现；它会启动或附加 TUI。不要通过省略参数来探测变异的嵌套命令；某些命令，包括 herdr workspace create，在默认情况下是有效的并且会执行。请改用上面的命令组输出。

大多数控制命令输出 JSON。从这些响应中读取标识符和状态，而不是预测它们。

ID 和当前上下文

公共 ID 是简短稳定的句柄：

  • 工作区：w1
  • 标签：w1:t1
  • 窗格：w1:p1
  • 终端：term_...

编码的后缀可以包含字母，并且可以超过一个字符。将每个 ID 视为不透明字符串。

关闭的标签和窗格 ID 不会被重用，也不会重新定位到后来的资源。移动到另一个工作区的窗格会获得一个新的公共窗格 ID。在变更后重新读取创建、拆分、移动、列表或获取响应；永远不要从工作区或显示编号构造 ID。

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"

通过窗格控制代理

代理在窗格内运行。使用窗格 ID 作为代理、shell、服务器、测试和日志的控制目标。这使生成、输入、读取、等待和清理保持在一个稳定的控制面上。

使用工作区和标签命令进行组织。仅在你故意希望 Herdr 创建、打开或删除 Git 检出时使用工作树命令。

窗格记录在可用时暴露 agent、agent_status 和原生会话元数据。代理状态为 idle、working、blocked、done 或 unknown。

idle 和 done 是相同的底层语义状态，但具有不同的注意状态：

  • idle：代理正在等待，其结果被视为已查看。
  • done：代理已完成，其结果尚未被查看。

首次在其提示符处打开的代理报告 idle，包括在后台窗格中。在 working 或 blocked 代理完成后，当其标签或工作区在后台时，它报告 done。当它在活动标签中完成且前台客户端聚焦时，它报告 idle。如果前台客户端明确取消聚焦，即使是在活动标签中，完成也可能变为 done。

聚焦窗格、切换到其标签或重新获得外部终端焦点会将可见标签标记为已查看，因此 done 变为 idle。切换离开不会将现有的 idle 状态变为 done；done 是由稍后在窗格不可见时的完成创建的。没有前台客户端时，全局活动标签中的新完成被视为已查看，而后台标签中的完成仍变为 done。

交互式启动代理

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

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

herdr pane layout --pane "$HERDR_PANE_ID"

将宽窗格向右拆分，将窄或高窗格向下拆分。避免重复同方向拆分，以免创建不可用的窄列或短行。将用户的焦点保持在调用窗格中：

herdr pane split --current --direction right --no-focus

当布局需要时，将 right 替换为 down。

从 JSON 响应中读取 result.pane.pane_id。为窗格提供一个有用的标签，然后通过仅运行其正常可执行文件来启动请求的代理，以便其交互式 TUI 打开：

herdr pane rename <returned-pane-id> "reviewer"
herdr pane run <returned-pane-id> "codex"

使用属于请求代理的可执行文件：

  • Codex：codex
  • Claude Code：claude
  • pi：pi
  • OpenCode：opencode
  • OMP：omp

默认情况下，不要将任务作为 argv 提示传递。不要添加非交互式标志。仅当用户明确要求不同的启动模式或命令时，才更改正常的交互式启动。

启动后检查窗格。如果 agent_status 还不是 idle，则等待 idle 转换。一旦 idle，使用 pane run 提交任务：

herdr pane get <returned-pane-id>
herdr wait agent-status <returned-pane-id> --status idle --timeout 30000
herdr pane run <returned-pane-id> "Review the current diff and report only actionable findings."

状态等待立即匹配当前状态，或等待未来的匹配转换。

pane run 同时发送文本和回车。将其用于初始提示和后续操作，而不是分别协调 send-text 和 send-keys。

对于正常的后台工作，等待代理开始工作。如果窗格保持在后台标签或工作区中，则在读取其记录之前等待 done：

herdr wait agent-status <returned-pane-id> --status working --timeout 30000
herdr wait agent-status <returned-pane-id> --status done --timeout 120000
herdr pane read <returned-pane-id> --source recent-unwrapped --lines 120

如果用户正在观看该标签，则完成报告 idle 而不是 done，因此等待 idle。在检查 pane get 时，始终将 idle 或 done 视为已完成；区别在于结果是否已被查看。

如果等待超时，在决定做什么之前检查 herdr pane get <returned-pane-id> 和 pane read。blocked 代理需要输入；unknown 窗格可能尚未包含检测到或集成的代理。

以相同方式提交后续操作：

herdr pane run <returned-pane-id> "Now check the failing test."

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

使用相同的几何规则拆分调用窗格，而不移动用户的焦点：

herdr pane split --current --direction right --no-focus

从 JSON 响应中读取新的 pane_id，然后运行并检查命令：

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

在等待未来输出之前检查现有输出。等待超时以状态 1 退出。

使用与任务匹配的读取源：

  • visible：当前渲染的视口
  • recent：最近的滚动回退（已渲染），包括软换行
  • recent-unwrapped：最近的滚动回退，软换行已合并；优先用于日志和记录
  • detection：代理检测使用的底部缓冲区快照

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

如果用户明确要求另一个标签、工作区或工作树，发现该命令组并使用返回的 ID。不要从启动代理或命令的请求中推断出更大的拓扑。

安全和协调规则

  • 对于后台工作使用 --no-focus，除非用户要求切换上下文。
  • 使用 --current 或显式 ID。不要依赖另一个客户端的聚焦窗格。
  • 从 JSON 响应中解析 ID。不要从侧边栏顺序或示例中推导。
  • 先检查再等待。先读取当前输出，然后等待你期望的下一个状态或输出。
  • 除非用户明确要求，否则不要关闭你未创建的工作区、标签、窗格或会话。
  • 除非用户明确意图停止服务器及其窗格进程，否则不要从活动会话中运行 herdr server stop。
  • 永远不要杀死主 Herdr 进程。对于需要隔离服务器的实验，使用命名的测试会话。