herdr-pair

Herdr Pair

在同一个 Herdr 标签页中配对使用 Claude 和 Codex。让配对会话及其 sid 在任务、已接受的工作周期和上下文压缩期间保持运行。用户可以阅读任一窗格中的内容，也可以随时插话。协议标头和标识符必须原样保留。

前提条件

将 SKILL_DIR 设为此技能目录，并将 PAIR_SCRIPT="$SKILL_DIR/scripts/herdr-pair.mjs"。始终使用此绝对路径；项目的当前工作目录与已安装技能的路径无关。

确保 PATH 中有带 Agent 自动化命令（herdr agent start、 herdr agent prompt）的 herdr、jq 和 trash，并且设置了 HERDR_ENV=1。如果缺少其中任何一项，请停止并告知用户安装或启动（或更新）Herdr。

执行任何 Herdr 修改操作之前，先阅读并执行 调用方窗格证明。它会解析明确指定的任务仓库，通过调用方自身的进程祖先关系证明唯一调用方；如果该祖先关系匹配的窗格不恰好有一个，则改用对话标记；然后返回 PAIR_PROOF 以及已固定的 PAIR_ID，其中包含 --tab-id。如果该证明未能恰好完成，请停止。

防护规则

1. 每项窗格操作都必须限定到经对话记录证明的 workspace_id、 tab_id、pane_id、Agent 类型、终端身份和仓库。绝不能操作仅通过工作区、焦点、标签、当前工作目录、方向、会话元数据或窗格编号发现的窗格。
2. 仅使用 herdr-pair.mjs send 传递合作伙伴消息。普通助手输出仅用于不带标头的用户交接。SendMessage、子 Agent 消息和直接写入窗格均属于不同的通道。
3. 每个文件范围只分配一个 Agent 持有写入权限：明确负责人、目标文件、禁止的更改、验证方式和停止点。在交接前，合作伙伴对该范围只能只读。
4. 用户提交的消息优先于合作伙伴流量。下一条回复中要指出任何冲突。合作伙伴启动失败一次，即结束本次尝试。
5. 各工作步骤之间都要返回提示符；切勿让窗格长时间停留在前台循环中（例如休眠并轮询接收消息、前台 CI 监视器）。永久忙碌的窗格会阻断传入的合作伙伴消息；长时间运行的监视器应放在后台终端中运行，并确保此窗格可以接收提示。
6. 每次有意制造工作区异常状态时都要发出通知。在进行变异测试、二分定位或有意回退之前，发送一条 task，注明受影响的路径和停止条件；工作树恢复并验证完毕后，发送 ready。无需等待 accepted：这些通知本身就是保护措施。合作伙伴一旦看到异常状态窗口开启，在收到关闭通知之前，就会将该工作区的测试结果视为不可用，并会提问而非报告。无法发出通知的实验，或持续时间超过几分钟的实验，应在单独的 worktree 中进行。

协议

消息以以下内容开头：

[agent <from> -> <to> kind=<kind> sid=<sid>]
[herdr-pair control seq=<n>: ...]

<body>

辅助程序会注入控制行，其中包含此消息对应的精确 receive 命令，以及通过发送方回复的规则。模型上下文压缩后，这一行是恢复锚点。

使用以下类型：

• task：提出或更新工作拆分及其写入权限。中途停止时，以 STOP — <原因> 开头。
• review：请求审查，并提供文件路径和简短的更改摘要。
• question：继续之前请求澄清。
• ready：报告已更改的文件、验证结果和剩余风险。
• accepted：接受合作伙伴的 ready，并推进工作周期。
• blocked：说明继续所需的用户决策。
• stalemate：报告相同的分歧已重复两次且没有进展。
• handoff：在普通本地输出中将控制权交还给用户。

启动或恢复

1. 运行 node "$PAIR_SCRIPT" discover "${PAIR_ID[@]}"。 如果不存在对端 Agent，则运行一次 node "$PAIR_SCRIPT" spawn "${PAIR_ID[@]}"。 如果存在多个候选项或启动失败，则停止。
2. 运行 node "$PAIR_SCRIPT" init "${PAIR_ID[@]}"。 它会创建一个新的标签页级会话，或以幂等方式恢复完全匹配的活动会话。 将其确切的 sid 记录为 PAIR_SID；每次发送都会绑定到该会话，因此错误的同类型窗格无法借用其他标签页的会话。
3. 通过辅助程序发送第一个 task。双方地位平等： 提议划分工作范围——每个范围对应一个写入租约；双方各自实现自己的范围，并审核对方的 ready—— 同时提供足够的上下文，确保双方可以独立工作；对方接受或提出反建议后再开始实现。没有可独立划分范围的任务只设一个租约：持有者负责推进，对方负责审核；租约在不同任务间轮换。

当确切的标签页拥有一个经过验证的会话，且第一个任务有已记录的回执时，即视为完成。重新加载技能和上下文压缩后始终恢复该会话。

发送

只将正文写入临时文件，然后调用：

BODY=$(mktemp); trap 'trash "$BODY"' EXIT
# Write the partner message body to "$BODY".
node "$PAIR_SCRIPT" send "${PAIR_ID[@]}" --sid "$PAIR_SID" \
  --kind "$KIND" --body-file "$BODY"

发送方会给忙碌的对端 Agent 一小段宽限时间，然后仍会发送。在 Herdr 0.8.0 上测得，Claude 可以在一轮处理中原子地接受提示词，而向 Codex 发送多行提示词仍需按 Enter。当对端 Agent 仍在工作时，辅助程序只发送一条包含标头、控制行和正文的 agent prompt，然后运行无害的 Enter 循环。它会跳过可见到达检查和完整重发，因为该状态没有可靠的输入框信号，而重发可能导致已排队的正文重复。只有 receive 能在 session.json 中证明序列完全匹配；没有此 ACK，回执会注明投递未经证实。

对于空闲的对端 Agent，辅助程序会从输入框确认消息已送达：必须先观察到输入框发生变化，因为未送达的粘贴和已提交的粘贴看起来完全相同；随后它会反复按 Enter，直到输入框释放文本，再进行一次完整重发。如果仍无法确认送达，则明确报错。无论使用哪种路径，序列 ACK 都可以在提交后立即发生中断时恢复状态。

• receipt=acknowledged：对端 Agent 已针对此消息运行 receive。
• receipt=pending-partner-may-be-busy-do-not-retry：消息已送达，对端 Agent 正在工作，因此消息已排队但尚未确认。请勿重发。稍后运行 node "$PAIR_SCRIPT" reconcile；只有在收到 ACK 后，状态才会推进。
• receipt=unproven-working-inspect-that-pane-then-reconcile：对端 Agent 正在工作，已收到一条提示词和 Enter 保护，但在截止时间前未发送 ACK。辅助程序无法判断提示词是已排队还是被静默丢弃。在其预留仍待处理时请勿重发；等待 Agent 完成后检查，再对账，或清除已证实未送达的投递后重试。
• receipt=lost-partner-idle-inspect-that-pane-then-reconcile：对端 Agent 处于空闲状态且始终未确认，因此没有收到消息。阅读该窗格，确认消息不存在，然后清除下方的待处理投递。通常是正文过长导致此问题；发送这类内容时，请发送简短消息并注明文件路径。
• 预留后出现非零退出码表示传输失败。待处理预留仍会保留，以便通过 ACK 对账；未经检查，切勿声称消息已送达或清除预留。

如果检查证实待处理消息从未送达对端 Agent，请在获得用户明确批准后，仅清除此条投递：

node "$PAIR_SCRIPT" reconcile "${PAIR_ID[@]}" --sid "<sid>" \
  --clear-pending true

压缩后接收并恢复

对于传入的 [agent ...] 流量：

1. 运行 [herdr-pair control ...] 中的确切命令。它会调用 receive，并传入 --sid、--from 和 --seq，验证当前标签页绑定，并持久化 收讫确认。
2. 处理消息，将回复正文写入临时文件，然后运行 node "$PAIR_SCRIPT" send ...。

当 receive 记录了序列号且回复的收讫确认已记录时，即表示完成。 失败时，向用户提供不带标题的传输报告。压缩后， 根据控制行和已验证的会话重建窗格 ID、sid、任务状态和关闭状态。

工作周期与持久化

持续工作，直到产出有用的成果。连续五轮没有新代码、测试结果、决策或更明确的选项时，必须执行 handoff。取得实质进展后重置计数。对于事实性分歧，必须先通过一项直接证据或有针对性的测试解决，避免陷入僵局。同一判断重复两次且没有进展后，发送 stalemate。

两个 accepted 状态即可完成一个工作周期。发起方应向用户进行本地交接，说明结果、验证证据、未解决的问题，以及仍处于活动状态的所有配对窗格、工作树或监视进程。两个 Agent 都可以暂停；下一个任务会恢复同一配对和 sid。会话仍保持活动状态。

blocked 和 stalemate 也会进行交接，但不会删除会话。仅在已验证的活动配对中，使用 node "$PAIR_SCRIPT" reset "${PAIR_ID[@]}" 清除工作周期计数器和状态；它会保留身份信息和交付历史。

只有在用户明确要求结束配对时，才结束并清理会话：

node "$PAIR_SCRIPT" end "${PAIR_ID[@]}" --sid "<sid>"

脚本会自行验证 sid、工作区、标签页和参与者，并在交付仍待处理时拒绝执行（等待 ACK，或使用经过检查的清除路径）。如果旧窗格 ID 或缺少配对方导致无法恢复，请说明不匹配情况；只有在用户明确批准后，才能使用 end "${PAIR_ID[@]}" --sid "<sid>" --stale true——仅当配对方窗格已不存在、其记录的绑定已过期，或其前台 Agent 进程／代码库不再匹配时，过期结束操作才可能丢弃待处理状态。关闭 Herdr 标签页会自然结束窗格；过期状态绝不会被其他标签页借用。

工作台标签页

仅当需要单独的标签页来运行长期共享进程时，才阅读 references/workbench-tab.md。

已弃用

此技能已冻结。其后继版本是同一代码库中的 pair 技能，它保留了此 Herdr 后端的逐字节内容，并添加了可在 Herdr 之外进行配对的无头后端。新工作请安装 pair；herdr-pair 会保留在此处，以确保现有安装继续运行。