在 Herdr 托管的 pane 内需要检查或控制…

仅当用户明确提到 Herdr 或要求用 Herdr 检查/控制 pane、tab、workspace、命令或其他 agent，且当前 agent 运行在 Herdr 管理的 pane 中时，按 herdr CLI 流程安全操作。

适用场景

解决思路

1. 先验证当前 agent 是否运行在 Herdr 管理的 pane 中：执行 `test "${HERDR_ENV:-}" = 1`；如果失败，说明自己不在 Herdr 内并停止，不要从 Herdr 外部检查或控制当前聚焦的 Herdr session。
2. 检查通过后，使用 `PATH` 中的 `herdr` 二进制与当前 session 通信，用它检查邻近工作、创建终端布局、启动 agent 和命令、读取输出、等待状态变化。
3. 以已安装二进制为命令语法权威：先执行 `herdr --help`。
4. 通过不带子命令运行命令组来打印相关帮助：`herdr agent`、`herdr pane`、`herdr workspace`、`herdr tab`、`herdr worktree`、`herdr terminal`、`herdr notification`、`herdr integration`、`herdr session`、`herdr machine`。
5. 不要为了探索而运行裸 `herdr`；它会启动或附加 TUI。不要通过省略参数来探测会修改状态的嵌套命令；例如 `herdr workspace create` 使用默认值也有效并会执行。多数控制命令返回 JSON；从响应中读取标识符和状态，不要预测。
6. 按任务选择原语：workspace、tab、pane 拓扑组织终端位置；pane 命令控制原始终端、shell、测试、服务器、输入和输出；agent 命令控制当前占用 pane 的已识别 coding agent。
7. pane 无论是否包含 agent 都存在；`agent start` 需要已有可用 shell pane，且从不创建、拆分或移动布局。普通进程用 pane 命令；需要 Herdr 验证 agent 身份或解释 idle、working、blocked、done、unknown 生命周期状态时用 agent 命令。
8. agent 命令接受唯一的 live agent 名称或当前托管该 agent 的 pane ID；不接受 terminal ID 或裸 agent-kind 标签。名称必须匹配 `[a-z][a-z0-9_-]{0,31}`，且在 live agents 中唯一；名称跟随当前 pane occupant，并在该 agent 退出、释放或被替换时清除。
9. 理解状态：`idle` 和 `done` 都表示 agent 准备好输入；CLI/API 用服务器 seen state 区分，显式 focus 命令会标记目标已 seen，读取不会。每个 TUI 客户端独立跟踪 viewed completions，所以 Done 徽标可能不同。`blocked` 表示 Herdr 识别到 approval/question UI。`unknown` 表示 agent 存在但无法自信分类，不证明完成。
10. 使用 ID 和 caller context：公开 ID 是 opaque stable handles：workspace `w1`、tab `w1:t1`、pane `w1:p1`。已关闭 tab 和 pane ID 不会复用。pane 移到另一个 workspace 后获得新的 workspace-qualified pane ID。
11. `pane move` 后继续使用 `.result.move_result.pane.pane_id` 或 live agent 名称；旧值在 `.result.move_result.previous_pane_id`；只有被移动进程继承的 caller context 还能解析旧 ID，不要把它作为通用 agent 目标。
12. Herdr 向每个 managed pane 注入 caller context：`printf '%s\n' "$HERDR_WORKSPACE_ID" "$HERDR_TAB_ID" "$HERDR_PANE_ID"`。
13. 当 pane 命令应针对调用 pane 时优先用 `--current`。省略 `pane split` 目标时，如果 `HERDR_PANE_ID` 可用则使用调用 pane，否则使用 focused pane。其他命令可能使用 UI-focused pane，它可能属于用户或另一个客户端。
14. 用以下命令发现 live state：`herdr workspace list`；`herdr tab list --workspace "$HERDR_WORKSPACE_ID"`；`herdr pane current --current`；`herdr pane list --workspace "$HERDR_WORKSPACE_ID"`；`herdr agent list`。
15. 创建响应暴露后续要用的 ID：`workspace create` 返回 `.result.workspace`、`.result.tab`、`.result.root_pane`；`tab create` 返回 `.result.tab`、`.result.root_pane`；`pane split` 返回新 pane 为 `.result.pane`。
16. ID 和 live agent 名称的作用域是一个 server。两个保存的 SSH machine 可能都有 `w1:p1` 或名为 `reviewer` 的 agent。在 TUI 中选择 machine 不会重定向你 pane 中运行的命令：没有 `--machine` 时，它们仍使用继承的 session 和 socket context。
17. 要控制已保存的 SSH machine，发现和后续每条命令都使用相同 global prefix：`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`。
18. machine selector 必须是 enabled saved profile ID 或唯一、大小写敏感的 label，不是任意 SSH hostname。命令使用该 profile 的 remote session，且不需要打开 TUI。不要把 `--machine` 与 `--session` 或 `--remote` 组合。要在该 machine 上发现 ID；继承的本地 ID 和 `--current` 不能标识 remote panes。
19. 两侧安装都必须支持 machine API forwarding，remote server 必须已运行且 API 兼容。Forwarding 从不安装、启动或重启 server，也从不回退到 Local。本地 configuration、session management、installation commands 和 interactive attachment 不会转发。Remote worktree paths 必须是绝对路径、`~` 或以 `~/` 开头；plugin link paths 必须是绝对路径。连接失败不证明 mutation 未应用：重试前先检查 remote state。
20. `herdr machine list` 列出已保存连接 profile，不是跨 machine pane inventory；脚本加 `--json`。只在用户要求时 add、remove、enable 或 disable profile。移除 profile 会断开 client，但不会停止 remote sessions。添加 machine 默认使用 remote default session，除非显式提供 `--remote-session`。设置会在停止不兼容 server 前询问且默认 No；未经用户同意不要批准替换。Experimental handoff 不属于 `machine add`。
21. 启动和协调 agent 时默认在当前 tab、当前工作目录的 sibling pane 中操作。除非用户明确要求该拓扑或位置，不要创建 workspace、tab、worktree 或不同 cwd。
22. 尊重用户要求的方向。否则检查调用 pane：`herdr pane layout --pane "$HERDR_PANE_ID"`。宽 pane 向右拆，窄或高 pane 向下拆。避免重复同方向拆分导致窄列或短行不可用。保持用户焦点在调用 pane，并显式保留调用者工作目录：`herdr pane split --current --direction right --cwd "$PWD" --no-focus`；适当时把 `right` 换成 `down`。从 `.result.pane.pane_id` 读取新 pane ID。
23. 可用 shell pane 必须位于交互提示符，shell 本身在前台，且无前台命令、编辑器或 agent 运行。在该 pane 中用有用且唯一的名称启动受支持 agent：`herdr agent start reviewer --kind codex --pane <returned-pane-id>`。
24. 使用用户要求的 kind。运行 `herdr agent` 查看已安装 kind 列表和选项。仅在 `--` 后传 native agent 参数：`herdr agent start reviewer --kind codex --pane <returned-pane-id> -- <agent-args...>`。
25. 成功的 `agent start` 只在 Herdr 在同一 pane 检测到预期 agent 并认为其准备好交互输入后才返回。如果 agent 在启动期间 blocked，命令立即返回 `agent_not_ready`，但保留名称供 `agent read` 和 `agent send-keys` 使用。等 agent 变为 idle 后再 prompt。启动默认 30 秒 timeout。
26. 通过 agent surface 提交工作：`herdr agent prompt reviewer "Review the current diff and report only actionable findings." --wait --timeout 120000`。
27. `agent prompt` 遵循 pane 的 live bracketed-paste mode，并将文本后跟 encoded Enter 作为一个有序提交发送。只有两者都写入后才报告 successful submission；这本身不证明 agent 开始了 turn。对于 Windows 上的 Codex，Herdr 在 Enter 前发送 paste boundary，使提交不依赖 prompt 大小。如果 agent 已在 approval 或 question dialog 等待，它会在发送任何输入前以 `agent_blocked` 拒绝。检查 blocked UI 并在回答前询问用户。常规 agent 工作用 `--wait` 足够：它等待第一个 settled 的 `idle`、`done` 或 `blocked` 状态。不要用 `--until` 重复这些默认值。
28. 使用 `--wait` 时，从 non-working 状态发送的 prompt 必须产生观察到的 `working` 或 `blocked` 活动。提交后 Herdr 最多等待五秒观察该活动；无关的 `idle`、`done` 或 session 变化不满足此门。若未观察到活动则返回 `agent_prompt_stalled`，若 caller timeout 先到则返回 `timeout`。Caller timeout 包含提交时间。没有 timeout 时，观察到活动后的 settled-state wait 是无限期。此等待跟踪生命周期状态，不是单个 turn；如果 agent 已在 working，完成当前 turn 可能满足它。
29. 仅在 state-specific workflow 中使用 `--until`，例如等待已运行 agent 请求输入：`herdr agent wait reviewer --until blocked --timeout 120000`。不带 `--until` 的独立 `agent wait` 使用与 `agent prompt --wait` 相同的 settled-state 默认值。
30. 为交互式 agent UI 控制使用逻辑键：`herdr agent send-keys reviewer esc`；`herdr agent send-keys reviewer ctrl+c`。Herdr 在写入任何字节前验证所有键。通过 resolved agent 读取结果：`herdr agent get reviewer`；`herdr agent read reviewer --source recent-unwrapped --lines 120`。
31. 如果 wait 失败或返回 `blocked`，在决定发送什么输入前检查 `agent get` 和 `agent read`。timeout 或 stalled response 不证明 prompt 从未送达；不要盲目再次提交。仅在有意进行原始终端控制时使用 pane surface。
32. 在另一个 pane 中运行普通命令：按相同 geometry rule 创建 sibling pane，保留调用者工作目录，并保持用户焦点不变：`herdr pane split --current --direction right --cwd "$PWD" --no-focus`。
33. 从 `.result.pane.pane_id` 读取新 pane 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`。
34. `pane run` 原子地发送命令文本和 Enter。`pane wait-output` 立即搜索所选 snapshot，所以已存在的 output 也能匹配。`--match <text>` 用于字面子串，`--regex <pattern>` 用于 Rust 正则表达式。省略 `--timeout` 允许无限期等待。
35. 使用与任务匹配的 read source：`visible`：当前渲染 viewport；`recent`：最近渲染输出，包括 soft wraps；`recent-unwrapped`：最近输出，soft wraps 已合并，优先用于 logs 和 transcripts；`detection`：用于 agent detection 的 plain-text bottom-buffer snapshot。当颜色和终端样式是证据时用 `--format ansi`，否则用 text。
36. `--lines` 请求 Herdr 从 pane 可用 screen 和 host scrollback 提供更多行。Alternate-screen rows 不会进入普通 host scrollback。对于受支持的 idle agents，Herdr 可以收集 application-owned history 并在之后恢复 viewport，但不是每个 application 或 response 都能用此方式恢复。
37. 如果更大的 recent read 仍未显示已完成 response，请 agent 将内容写成 Markdown 到临时目录，并只回复文件路径，然后在同一 machine 上读取该文件。仅作为 fallback 使用；不要在初始 prompt 中请求文件输出。
38. 安全协调：除非用户要求切换上下文，否则后台工作使用 `--no-focus`。
39. 使用 `--current`、显式 pane ID 或唯一 agent 名称。不要依赖另一个客户端的 focused pane。
40. 从 JSON 响应解析 ID。不要从 sidebar 顺序或示例推导 ID。
41. 不要关闭不是你创建的 workspaces、tabs、panes 或 sessions，除非用户明确要求。`workspace close --group` 会关闭 primary workspace 及其 linked worktree workspaces；不要仅为绕过 `workspace_group_close_required` 而添加它。
42. 仅在用户已验证 repository 后使用 `--trust-repository`。它授予 per-request Git trust；不是 failed worktree command 的常规重试。
43. 更新后 client 和 server 版本可能不同。在依赖新 server features 前检查 `herdr status`。缺失 method 不是停止或升级 server 的许可。
44. 除非用户明确打算停止 server 及其 pane processes，否则不要从 active session 运行 `herdr server stop`。
45. 绝不要杀掉主 Herdr 进程。需要 isolated server 的实验使用 named test sessions。
46. CLI server errors 是 stderr 上的 JSON，exit status 1；CLI syntax errors 以 exit status 2 退出。

适用边界 · 注意事项

• 用户未明确提到 Herdr，或未要求用 Herdr 检查/控制 pane、tab、workspace、命令或其他 agent 时，不要仅因任务可受益于后台终端、委派或并行工作而使用。
• 当前 agent 不在 Herdr 管理的 pane 中（`HERDR_ENV` 不是 1）时，不要从 Herdr 外部检查或控制聚焦的 Herdr session。
• 不要把 `--machine` 与 `--session` 或 `--remote` 组合；也不要使用任意 SSH hostname 作为 machine selector。