herdr-orchestration

herdr 编排

顶层 Agent 是 控制器（Codex、Claude、Fable 或其他 Agent）；它将任务委派给 工作者 TUI，由其收集证据、起草范围明确的补丁、运行测试并汇报。控制器负责分配任务、管理状态、控制冲突、验证、集成以及面向用户的最终答复。herdr 是底层支撑：每个工作者 TUI 都有一个具名标签页，而套接字 CLI（herdr …）为控制器提供放置工作者、发送输入、读取屏幕和等待原生 Agent 状态的功能。

一个工作者，一个具名标签页

每个工作者都有自己的标签页，在创建时通过 tab create --label 设置标签。标签栏就是控制器的仪表盘：标签清楚标明哪个模型正在处理哪个任务切片，无论有多少个工作者在运行，都一目了然。

标签页也不占用屏幕空间。拆分窗格会让所有工作者共享调用方的屏幕，而在笔记本电脑上，第三个工作者就会让每个窗格窄到无法阅读。只有在用户明确要求在调用方旁边查看工作者时，才拆分窗格。

每个工作者启动时都必须提供两个名称：

• 标签页标签 — <model>: <slice>，例如 opus: fix loops、 codex: audit auth。自由文本；请保持简短，标签栏会截断过长内容。
• Agent 名称 — 任务切片的 slug，例如 fix-loops。必须符合 [a-z][a-z0-9_-]{0,31}，且在运行中的 Agent 之间必须唯一。所有 agent … 动词都可用此名称代替窗格 ID。

工作者是 TUI — 不使用无头运行器

工作者是一个交互式 TUI — claude 或 codex — 通过 herdr agent start 启动。该命令会验证 Agent 的身份，并且只有在 herdr 检测到其已准备好接收输入后才会返回。herdr 的 Agent 状态集成会挂接这些 TUI，因此只有屏幕上存在真实 TUI 时，agent wait、agent list 以及阻塞／完成状态检测才可用。

无头运行器 — claude -p、codex exec，以及任何将 JSON 事件流写入窗格的程序 — 都不会报告状态，因此等待永远不会触发，委派任务也会悄无声息地失效。若工作者标签页里满是原始 JSON 事件行，说明委派已损坏：中断它（rtk herdr pane send-keys <pane_id> ctrl+c），然后通过 agent start 重新启动。

不变规则

• 除非用户指定其他目标，否则所有操作都限定在调用方工作区内。
• 在使用任何焦点窗口回退方式之前，先通过 HERDR_WORKSPACE_ID、HERDR_TAB_ID 和 HERDR_PANE_ID（注入到每个 herdr 窗格中）确定调用方上下文。
• 使用从命令 JSON 中解析出的 ID 指定工作者 — 对 agent … 动词使用 Agent 名称，对标签页和窗格动词使用 w2:t3／w2:p4 — 绝不要猜测位置。
• 每个创建类动词（tab create、workspace create、worktree create、pane split）都传入 --no-focus；只有用户提出要求时才使用焦点动词。
• 工作者的任务及计划中的集成后续工作完成后，结束你启动的每个工作者（参见“结束工作者”）。

预检

检查守护进程、集成和调用方上下文：

rtk herdr status                 # server running + socket path
rtk herdr integration status     # selected worker runtime must show `current`
rtk herdr pane current --current # caller pane / tab / workspace ids
rtk herdr agent list             # agents already running

只检查／安装各个选定运行时对应的集成。当守护进程和集成保持不变时，可在同一工作区复用此预检；仅有新的任务包并不需要重复执行。

启动工作者

除非用户要求覆盖配置，否则使用各工作者运行时配置的模型。启动分两条命令：创建具名标签页，然后在该标签页的根窗格中启动 TUI。

# 1. named tab — returns .result.tab.tab_id and .result.root_pane.pane_id
rtk herdr tab create --workspace "$HERDR_WORKSPACE_ID" --cwd "$PWD" \
  --label "opus: fix loops" --no-focus

# 2. worker TUI in that tab's root pane; native flags follow `--`
rtk herdr agent start fix-loops --kind claude --pane <root_pane_id> -- \
  --dangerously-skip-permissions "<packet>"

rtk herdr agent start audit-auth --kind codex --pane <root_pane_id> -- \
  --yolo

在注册表中记录 tab_id、pane_id 和 Agent 名称 — 结束工作者和读取屏幕都需要这三项信息。

Claude 启动时始终使用 --dangerously-skip-permissions，Codex 始终使用 --yolo — 工作者会在无人值守的情况下运行，不得因权限提示而停滞。先规划再执行的任务还需添加 Claude 的 --permission-mode plan；这些标志可以组合使用（参见“先规划再委派”）。

agent start 只有在 herdr 检测到 Agent 已准备就绪后才会成功返回，因此非零退出状态表示启动失败 — 重试前先读取该标签页的根窗格（rtk herdr pane read <pane_id> --source visible）。通过 rtk herdr tab list --workspace "$HERDR_WORKSPACE_ID" 确认标签已生效；如果标签页显示的是默认标签，则恢复为原标签：

rtk herdr tab rename <tab_id> "opus: fix loops"

向正在运行的 TUI 发送提示词

优先将初始数据包作为启动参数传递（如上所示）——会话会立即开始工作，跳过等待 TUI 就绪的竞态情况。例外：Codex 的先规划模式会以空白状态启动（参见“先规划再委派”）。

后续操作请使用 agent prompt——它会以原子方式提交文本并按下 Enter，同时遵循窗格当前的括号粘贴模式；--wait 会阻塞，直到工作进程完成：

rtk herdr agent prompt fix-loops "<follow-up prompt>" --wait --timeout 300000

pane send-text 末尾的 \n 不会提交内容——TUI 会将其渲染为软换行，提示词仍未提交。未经确认的发送不会送达：如果 --wait 返回 agent_prompt_stalled，说明工作进程状态从未改变——读取屏幕内容并重新发送。

先规划再委派（可选启用）

只有在用户启用后才会运行先规划模式——用户明确要求（“先规划”或“规划模式”），或在调用时指定 --plan-mode 标志。默认委派方式是直接执行：启动后放手运行。仅仅是调查复杂度高，并不足以增加规划审批步骤。

启用后，工作进程先制定计划，控制器审核并接受计划，然后工作进程放手运行。启动标志、Shift+Tab 序列、状态检查和接受菜单都必须精确操作，且各个 TUI 之间有所不同。启动先规划模式的工作进程之前，请完整阅读 references/plan-mode.md。

委派数据包

将每个工作进程的提示词作为独立的任务约定发送。请包含：

• 仓库路径和确切目标
• 工作进程的角色和模型
• 执行模式：直接执行（默认）或先规划再执行（由用户启用）
• 涉及的文件、包或界面范围
• 明确不在范围内的文件和行为
• 已认领的文件或工作部分，以避免冲突
• 工作进程可依赖的依赖项和当前接口／约定
• 此任务所需的证明材料：已更改的文件、附带结果和已检查输入的命令、相关产物，以及尚存的不确定性
• 验证责任：工作进程检查、控制器集成检查，以及外层工作流负责的任何最终交付检查
• 停止条件：代码结构出乎意料、命令重复失败、身份验证／模型阻碍，或需要修改范围外的内容

分配彼此独立且目标完整的工作。如果消费者依赖尚未确定的接口，请先确定该接口，或将生产者和消费者交由同一负责人处理。文件数量本身不是拆分工作的理由。告知工作进程它们共用同一个代码库，必须保留他人的更改，并且在依赖工作继续之前，必须报告接口变更。对于相关的集成问题，请复用同一个工作进程；发送已更改的约定和剩余工作，而不是重新分配一个全新的探索任务。

Worktree 隔离

当多个工作进程需要并行编辑有重叠的文件时，请为每个工作进程分配独立的 worktree——herdr 会以原生方式管理它们，并将其作为带标签的独立工作区：

rtk herdr worktree create --workspace "$HERDR_WORKSPACE_ID" \
  --branch <slug> --label "<slug>" --no-focus --json

在该工作区中创建工作进程的标签页（tab create --workspace <worktree_workspace_id>），使其当前工作目录指向隔离的检出目录。

跟踪工作器

编排会持续很长时间——工作器切片可能需要几分钟到几小时，绝不会因为等待超时而放弃工作器。使用 herdr 的原生 Agent 状态，按 签到间隔（3–5 分钟，时长根据切片调整；切片越繁重，间隔越长）进行阻塞等待，而不是轮询屏幕：

rtk herdr agent wait fix-loops --until done --timeout 300000     # completion check-in
rtk herdr agent wait fix-loops --until blocked --timeout 300000  # question or menu
rtk herdr pane wait-output <pane_id> --match "<text>" --timeout 300000

控制器读取不会将标签页标记为已查看，因此未聚焦的工作器会变为 done，而不是 idle——等待 done。--timeout 是签到间隔，绝不是工作器的截止时间。超时后，读取屏幕（rtk herdr agent read fix-loops --source recent-unwrapped --lines 120），然后重新进入等待；循环等待，直到工作器达到终态、提出问题或触发停止条件。报告的状态看起来不对时，使用 rtk herdr agent explain <pane_id> --json 调试状态检测。

在现有任务记录或交接文档中维护一份简明登记表：控制器身份；工作器 Agent 名称、标签页标签、角色、模型；工作区／标签页／面板 ID；发送的目标和开始时间；状态（starting、planning、plan-review、plan-accepted、running、blocked、reported、verified、retired）；认领的文件或工作切片；工作器报告的命令和结果；控制器执行的验证；最终处置结果（accepted、rejected、superseded 或 blocked）。

随着切片变化及时更新标签页标签，并在不抢占焦点的情况下宣布里程碑：

rtk herdr tab rename <tab_id> "opus: fix loops (verifying)"
rtk herdr notification show "Workers done" --body "2/2 verified" --sound done

验证工作器输出

在验证之前，将工作器输出视为不可信内容。监控和验证时不要改变焦点：

• 以只读方式读取工作器标签页（agent read <name> --source recent-unwrapped --lines 200）；输出不清楚时，请工作器提供简明的状态摘要。
• 在本地重新打开引用的文件，验证影响较大的发现。对于视觉输出，请并排打开交付的图像和指定的视觉参考；文件数量、尺寸和工作器的结论都不足以证明视觉效果合适。在启动成本高昂的批量生成前，先检查一张有代表性的图像。
• 检查命令结果、退出状态、已检查的输入和证据路径。对于未变更的输入，复用可信的工作器证据；对于缺失、过时、相互矛盾或无法验证的检查，重新运行。控制器需要运行工作器未覆盖的集成检查，以及项目策略要求的任何检查。仅有工作器交接本身并不会使证据失效，也不要求再完整运行一次测试套件。
• 接受任何工作器补丁之前，审查最终差异。
• 如果工作器编辑了认领范围以外的内容，请暂停集成并作出决定：接受、请求用户批准清理，或由控制器编辑并取代。

当 --lines 不再显示已完成响应的更多内容时，TUI 位于终端的备用屏幕上，那些行已经消失。请工作器将完整报告以 Markdown 格式写入临时目录并回复文件路径，然后读取该文件。

退役工作器

委派结束时，应退役工作器——关闭标签页。若预计会有相关后续工作，在审查或集成结果期间保留已报告的工作器。记录处置结果并完成相关工作后，将其退役：

rtk herdr tab close <tab_id>

关闭标签页会结束 TUI 会话并清除其滚动缓冲区，因此先记录登记表所需的内容——报告文本、引用的行号、命令输出。文件、差异和工作树会保留在磁盘上。

工作器在运行中、受阻、等待计划中的集成后续工作、其屏幕是未解决故障的证据，或用户要求检查时，应保持打开状态——在登记表中记录原因。只有当 rtk herdr agent list 显示此控制器的所有工作器都不再运行时，编排才算完成：每个工作器都已退役，或其标签页仍打开的理由已记录在登记表中。

停止条件

遇到以下情况时，应停止操作并报告，而不是自行变通：

• herdr 拒绝有效的工作区、标签页或窗格引用，或者 rtk herdr status 显示没有正在运行的服务。
• 工作线程 TUI 拒绝模型别名、身份验证状态、工作目录或启动标志——报告确切的阻碍，并在降级模型或切换工具前征得用户同意。
• 身份验证阻止 TUI 正常运行。
• 工作线程的状态一直为 unknown，但输出仍在滚动，且 agent explain 未显示匹配规则——检测功能已失效，或者窗格正在运行无头进程。
• 无法通过 agent read 或 pane wait-output 确认计划模式状态行或接受菜单，或者工作线程在一轮重新规划后仍未将计划调整到任务范围内。
• 工作线程需要进行重叠编辑，而控制器无法安全地整合这些编辑。
• 任务需要使用用户尚未批准的、会改变焦点的 herdr 动词。