handover-to-herdr

移交给 Herdr

在 herdr 标签页中开启新的 Agent 会话，并向它发送起始提示词。调用此技能的 /handover 或 /init-effort 要求提供书面交接文档和提示词，并决定新会话要做什么。它会移交四项输入：工作树路径；主题，即这项工作的名称或内容；新会话的角色，例如 orchestrator、thinking 或其他单词组成的角色；以及起始提示词。

可在 herdr 面板内运行此技能，也可在面板外运行，例如在桌面应用会话中运行。凡是支持 --no-focus 的地方都使用该参数，以保持用户焦点不变。执行变更时使用明确的实时 ID；检查时使用调用方上下文来发现 ID。

参数

• <worktree-tool>：用于创建和释放工作树的工具，例如 treehouse，或原生 Git 工作树。
• <agent>：用于启动新 Agent 会话的命令，例如 claude 或 codex，以及相应的标志。

步骤

当 /settle-session 调用此技能时，请改为读取 settle-commands.md，而不是遵循以下步骤。

1. 检查 herdr status 是否能连接到服务器，并查看已安装命令的帮助信息。使用 test -n "$HERDR_PANE_ID" 检查是否存在调用方上下文；如果存在，使用 herdr pane current --current 解析当前上下文，并读取返回的面板、终端、标签页和工作区 ID。继承的 ID 可能会在面板移动后仍然有效，但对应的实时 ID 已发生变化。在面板外运行时，跳过调用方解析：没有调用方上下文时，该命令可能会解析到另一客户端当前聚焦的位置。

   • **如果没有服务器响应：**说明这一点，并交还给调用技能；随后调用技能会按没有会话主机的情况处理。

2. 在检出路径为目标工作树的工作区中打开标签页，或者从仓库自身的工作区将该工作树作为新工作区打开。变更前后都要检查目标：

   • 工作区清单：herdr workspace list 会显示每个工作区的 worktree，并列出其 checkout_path、repo_root 和 is_linked_worktree。使用 Git 验证工作树的规范路径和仓库。
   • **变更前检查：**每次变更之前，立即刷新调用方（如果存在），检查目标工作区、标签页和面板的层级结构，并确认其与预期的仓库和路径一致。
   • **现有面板：**使用 herdr pane get <pane_id> 和 herdr pane process-info --pane <pane_id> 检查实际前台位置和进程；仅凭工作区检出元数据和面板 cwd 无法确定进程的位置。
   • **目标不匹配或未知：**保留并报告该状态，不要猜测。
   • **创建工作树：**使用 <worktree-tool> 创建工作树，绝不要使用 herdr worktree create。
   • **创建后检查：**读取每项创建结果中的新 ID，并在启动 Agent 之前重新检查新面板的层级结构、实际位置和 Shell 占用情况。
   • **操作中断或结果不确定：**重试前检查实时状态，以免创建重复的拓扑结构。
   • **移动面板：**每次经授权移动面板后，使用返回的当前 ID，并再次检查这些 ID。

   然后打开标签页：

   • **如果某工作区的 checkout_path 就是目标工作树：**使用 herdr tab create --workspace <workspace_id> --cwd <worktree> --no-focus 在其中添加标签页。该命令会返回标签页和其根面板。

   • **否则：**从仓库自身的工作区打开目标工作树，即满足 repo_root 为该仓库且 is_linked_worktree 为 false 的工作区：

     herdr worktree open --workspace <repo workspace_id> --path <worktree> --label <topic> --no-focus
     

     它会返回工作区、其第一个标签页和根窗格。始终传入 --workspace，因为如果在窗格外调用，可能会因 linked_worktree_source 而失败。

   • 当仓库没有工作区时： 先使用 herdr workspace create --cwd <main checkout> --label <repo> --no-focus 创建一个工作区。主检出目录中的普通工作区即可作为来源。

3. 使用 herdr tab rename <tab_id> "<harness> · <role> · <topic>"，将标签页命名为 <harness> · <role> · <topic>，以便维护者知道其中运行的是什么。Harness 名称使用简写：Claude Code 用 CC，也可以用 Codex、OpenCode、Cursor 或该 harness 自身的名称。

4. 在标签页的根窗格中启动 <agent>，并将 Agent 命名为小写的 <topic>-<role>：

   herdr agent start <name> --kind <kind> --pane <pane_id> -- <agent flags>
   

   • **当启动屏幕阻止其运行时，**这会报告 agent_not_ready：使用 herdr agent read <name> --source visible 查看屏幕，将内容展示给维护者并由其决定。新的工作树路径通常会显示 harness 的“信任此文件夹？”提示；这属于安全决策，因此请维护者在标签页中接受。然后运行 herdr agent wait <name> --until idle。

5. 使用 herdr agent get <name> 确认新 Agent 仍位于创建的终端中，并处于已验证的实时层级中，然后再发送输入。严格按照调用技能编写的内容发送启动提示词，并确认新 Agent 正在工作。将提示词放在一行中，因为 herdr agent prompt 会将其作为粘贴内容发送。将提示词放在单引号中，以免 shell 展开 Codex 的 $skill 引用；其中每个 ' 都写成 '\''，以免撇号结束字符串：

   herdr agent prompt <name> '<starting prompt>'
   herdr agent wait <name> --until working --timeout 60000
   

   提示词不要加 --wait：它会一直等待，直到 Agent 再次进入空闲状态，长时间运行会在此之前超时。

   • 如果等待超时： 重新发送任何内容之前先检查 Agent。herdr agent get <name> 会显示其状态，herdr agent read <name> --source visible 会显示其屏幕；不要加 --lines，因为 Agent 工作期间此参数会导致失败。提示词可能已经送达，因此只有在屏幕显示未送达时才重新发送。

6. 此会话自身的工作完成后，阅读 settle-commands.md，并按照 settle-commands.md > “Settled marker” 中的说明，将其实时标签页标记为已结算。保持调用方会话、其占用的工作树以及所有 Herdr 拓扑处于打开状态。

7. 将新 Agent 运行所在的工作区和标签页告知调用技能，以便其转告维护者。

参考资料

• settle-commands.md：检查实时调用方和占用者、将会话标记为已结算，以及保留其会话和拓扑。