用途
Handoff 用于把一项开发任务以书面简报的形式交给一个 ACP 智能体执行。该智能体在它自己的 git worktree 和 herdr 工作区中工作,完成后由人检查其成果,再决定是否合并。一次交接由两部分组成:一份带日期的文档,以及在仓库使用 beads 时额外创建的一个 epic。文档就是简报。会话或智能体只有在用户明确表示开始后才会启动。
主要能力
脚本 scripts/handoff 负责所有机械步骤,智能体的职责是写好文档并报告脚本输出的内容。可用命令包括:
scripts/handoff new "Report importer":生成 docs/YYYY-MM-DD-report-importer-handoff.md 文档。scripts/handoff start DOC:创建 epic、worktree 并分离式启动智能体。scripts/handoff start DOC --supervise:等待智能体完成,然后收集结果。scripts/handoff start DOC --here:只创建 worktree、分支、简报和 epic,不启动智能体。scripts/handoff start DOC --agent "codex-acp":指定任意 ACP 智能体命令。scripts/handoff status ID:查看提交、脏文件、智能体退出状态和日志尾部。scripts/handoff collect ID:验证并在 epic 上记录结果。scripts/handoff close ID [--discard]:合并后移除 worktree。scripts/handoff list:列出交接项。
这些命令需在目标仓库内运行。状态保存在 <git-common-dir>/handoff/<id>/(包含 state.json、brief.md、run.log),因此不会向工作树添加任何内容。
使用方式
- 写文档。使用
handoff new "<title>"或项目自身约定:先查看已有的 handoff 或 spec 文档,匹配其文件夹和命名。填写问题、范围、不在范围内的内容以及“完成标准”。把验证命令放在名为 Checks(或 Verify)的标题下的围栏代码块中;collect 会在 worktree 中逐行运行它们。 - 停下并等待用户表示开始。写文档不等于同意启动。
- 启动。
handoff start DOC会打印它切出的基础分支和提交;转述该行,以及源检出中存在 worktree 不会包含的未提交更改的提示。若没有 bd 或 .beads/ 文件夹,epic 会被跳过并给出一行说明。 - 用
handoff status ID查看进度。不要循环轮询;当用户想等待时使用 --supervise。 - 收集。
handoff collect ID会检查智能体是否完成、分支是否有提交、worktree 是否干净、源检出是否有新变化,以及每条简报检查是否通过。它把结果记录为 epic 上的评论,任何失败都会以非零状态退出。 - 合并由用户决定。报告结论和分支名,然后停止。
- 合并后关闭:
handoff close ID移除 worktree 和工作区、删除已合并分支并关闭 epic。对未合并分支会拒绝,除非使用 --discard,后者移除 worktree 但始终保留分支。
智能体收到的指令
文档作为提示发送,并附加固定规则:留在 worktree 内,只在 handoff 分支上用显式路径提交,绝不合并、变基、推送或开 PR,不触碰 worktree 之外的文件,遇到阻塞要报告而不是绕过,最后给出简短报告。acp-run 会对权限请求以及文件读写强制执行路径规则。
适用场景
适合需要把开发任务交给 ACP 智能体、同时希望隔离工作环境并在合并前人工验证结果的场景。
限制
需要 git、Python 3、运行中的 herdr 以及 herdr 的 acp-run 脚本。脚本会在 PATH、本技能旁边的同级 herdr 技能中以及常见技能文件夹中查找 acp-run;可用 HANDOFF_ACP_RUN 覆盖。仅支持 ACP 智能体,脚本绝不会回退到 TUI 智能体。worktree 从已提交历史切出,未提交的更改(包括未提交的文档)不在其中;简报仍能到达智能体,因为它作为文件传递。“worktree 之外没有变化”是通过比较源检出的 git 状态与启动时的快照来判断的。在与其他会话共享的检出中,那里的变化可能来自它们,因此 collect 会列出文件名而不是猜测。