kitherd

使用 Kitty 的无头 Herdr

本技能指导 AI 协调器（master）Agent 如何使用 Herdr 作为无头后台进程管理器、使用 Kitty 作为原生 GUI 窗口管理器来管理 worker Agent。

在此架构中：

• 无头 Herdr 服务（default 会话）： 作为后台守护进程运行（Linux 上为 systemd 服务，macOS 上为 launchd Agent）。它管理面板、终端模拟器、Agent 进程和持久生命周期，不提供交互式 TUI。
• Kitty 终端： 作为可视化界面。worker Agent 不通过复用器 UI 运行，而是通过 kitty @ launch ... herdr agent attach <name> 以原生 Kitty 分屏和标签页的形式查看。关闭 Kitty 分屏只会断开视图；worker Agent 会继续在后台运行。
• 交互式切换器（herdr_panel.py）： 用户可以打开交互式 fzf 面板，其中列出所有 Agent 及其实时状态，并通过指定的按键绑定连接到它们或终止它们。

---

核心编排规则

1. 使用默认会话： 始终使用不带 --session <name> 的普通 herdr 命令。命名会话用于交互式 TUI 工作流；除非有明确指示，否则不要在其中创建无头 worker。

2. 严格的 master-worker 层级： master Agent 是唯一负责启动、发送提示词、监控和停止 worker Agent 的协调器。worker 绝不能启动或控制其他 Agent；递归启动 Agent 或同级 Agent 之间互相启动会模糊决策流程并破坏协调。

3. Herdr 环境防护： 标准 Herdr 技能的 HERDR_ENV=1 防护适用于交互式 TUI 面板，不适用于无头默认会话。可以在任何 shell 中安全地运行 herdr CLI 命令。由于 master 在受管理的 Herdr 面板之外运行，--current 和 $HERDR_PANE_ID 不可用；始终使用明确的面板 ID 或唯一的 Agent 名称作为目标。

4. 通过工作区隔离目录： 每个项目目录都必须有专属的 Herdr 工作区。同一项目的多个 worker 共用该工作区。切勿在同一个工作区中混用来自不同代码库或项目的 worker，以免并发运行时发生上下文污染。

5. 必须指定绝对路径 --cwd： 每次执行 workspace create、tab create 和 pane split 都必须指定 --cwd。它必须是绝对路径（当前项目根目录请使用 "$PWD"）。Herdr CLI 不会自动继承调用方的工作目录；省略 --cwd 会导致新面板继承先前聚焦的工作区，或回退到 $HOME。启动 Agent 前，请确认 JSON 响应中的 cwd 字段。

6. Kitty 远程启动时保持参数一致（--copy-env 和 --cwd）： 使用 kitty @ launch 打开 Kitty 窗口或标签页时，始终同时传入 --copy-env 和 --cwd="$PWD"：

   kitty @ launch --type=window --location=vsplit --copy-env --cwd="$PWD" herdr agent attach <worker-name>
   

   • --copy-env：Kitty 的 GUI 进程由 systemd、launchd 或桌面管理器以精简环境启动。--copy-env 会传递当前 shell 环境（PATH、API 密钥、virtualenv、direnv）。
   • --cwd="$PWD"：设置 Kitty 窗口容器的工作目录。否则，在该 Kitty 窗口内创建的新分屏（alt+enter）、标签页或辅助终端默认使用 $HOME。注意：herdr agent attach 是客户端代理，不是 shell，因此 Kitty 的 --cwd=last_reported 无法自动检测 Agent 的目录。

7. 优先使用分屏，而非标签页： 连接新的 worker Agent 时，始终默认使用 Kitty 垂直分屏（--location=vsplit），以便用户并排查看进度。只有在用户要求或屏幕空间受限时，才使用水平分屏（--location=hsplit）或标签页（--type=tab --tab-title <worker-name>）。

---

分步工作流

步骤 1：确保项目工作区存在

检查活动工作区：

herdr workspace list

如果没有与项目目录（"$PWD"）对应的工作区，则创建一个：

herdr workspace create --cwd "$PWD" --label "<project-name>" --no-focus

从 .result.workspace.workspace_id 中解析 workspace_id（例如 w1）。

Step 2：为 Worker 创建专用标签页／面板

在项目的工作区中创建一个新标签页：

herdr tab create --workspace <workspace-id> --cwd "$PWD" --label "<worker-name>" --no-focus

从 JSON 响应的 .result.root_pane.pane_id 中提取 pane_id（例如 w1:p2）。确认 .result.root_pane.cwd 与你的项目路径一致。

Step 3：在面板中启动 Agent

在新创建的面板中启动 Worker Agent：

herdr agent start <worker-name> --kind <kind> --pane <pane-id> -- <agent-args...>

• 支持的 --kind 值包括：claude、codex、copilot、opencode、agy、pi、gemini、cursor、amp、cline、omp、devin 等。
• 在 -- 之后传入 Agent 专用的标志（例如 --dangerously-skip-permissions 或 --model ...）。
• herdr agent start 会一直阻塞，直到 Herdr 检测到交互式 Agent 已启动并到达空闲、就绪的提示符。

Step 4：在 Kitty 中打开可视视图

附加一个 Kitty 分屏以查看 Agent：

kitty @ launch --type=window --location=vsplit --copy-env --cwd="$PWD" herdr agent attach <worker-name>

若要使用水平分屏，请使用 --location=hsplit。若要创建新标签页，请使用 --type=tab --tab-title <worker-name>。

Step 5：协调、发送提示词并监控

向 Worker 提交指令：

herdr agent prompt <worker-name> "<instruction-text>" --wait

• --wait：等待 Agent 返回空闲、完成或阻塞状态。
• 随时检查整个 Agent 集群的状态：

  herdr agent list
  

Step 6：处理 Agent 阻塞和审批

当 herdr agent list 报告某个 Agent 的状态为 blocked 时：

1. 检查终端屏幕，了解 Agent 的请求：

   herdr agent read <worker-name> --source visible
   

2. 使用 Claude Code 时请谨慎： Claude Code 的行内自动建议（输入框中的幽灵文本）有时会导致 Herdr 的检测器在 Agent 实际处于空闲状态时报告 blocked。在尝试回复提示词之前，务必先使用 herdr agent read 确认。
3. 发送所需的确认或按键：

   herdr agent send-keys <worker-name> y
   herdr agent send-keys <worker-name> enter
   

Step 7：拆除和清理

Worker 完成分配的任务且不再需要时：

1. 关闭服务器上的 Herdr 面板：

   herdr pane close <pane-id>
   

2. 附加进程退出后，相应的 Kitty 分屏或窗口将自动终止。

---

CLI 命令速查

操作	命令
列出工作区	herdr workspace list
创建工作区	herdr workspace create --cwd "$PWD" --label <name> --no-focus
创建标签页／面板	herdr tab create --workspace <ws> --cwd "$PWD" --label <name> --no-focus
启动 Agent	herdr agent start <name> --kind <kind> --pane <pane-id> -- <args>
在 Kitty 中附加视图	kitty @ launch --type=window --location=vsplit --copy-env --cwd="$PWD" herdr agent attach <name>
向 Agent 发送提示词	herdr agent prompt <name> "<prompt>" --wait
检查 Agent 集群状态	herdr agent list
读取 Agent 输出	herdr agent read <name> --source visible（或 --source recent-unwrapped）
向 Agent 发送按键	herdr agent send-keys <name> <key>
关闭面板	herdr pane close <pane-id>