用途：不同 AI 编程工具无法互相读取会话记录（Claude Code 存在 ~/.claude/projects 下的 jsonl，Codex/OpenCode 各有存储，Antigravity 为加密 .pb），唯一可移植的是自包含文档。handoff 就生成这份文档，记录当前目标、决策和精确的未提交改动，供其他 AI 代理接续。适用于 token 不足、任务中途换工具、换机器，或用户说 handoff / continue elsewhere / out of tokens 时。
主要能力：仅依赖 git 和 shell 即可运行；若 PATH 上有 specweave 二进制，则调用 specweave handoff 作为可选加速器（高保真、感知 increment），但无硬依赖。两条路径产出相同文档格式和粘贴提示词。
使用方式：先判断路径，command -v specweave >/dev/null 2>&1 && echo "ACCELERATOR" || echo "STANDALONE"。加速路径运行 specweave handoff [incrementId] [--reason ...] [--summary ...] [--next ...] [--gotcha ...] [--decision ...] [--inline]，按序原样输出其 stdout。独立路径用 shell 捕获 git 状态，把完整未提交改动写入 .handoff/handoff.diff，再通过约五个问题的简短访谈补齐 reason、summary、next、gotcha、decisions，写入 .handoff/HANDOFF.md，最后按绝对路径优先的顺序打印文档路径、可点击链接、diff 路径、粘贴提示词和各工具查找源会话的提示。
限制：文档与 diff 默认被 .handoff/.gitignore 忽略，不会自动提交。写入前对自由文本和 diff 做启发式密钥擦除（12 种模式，替换为 [REDACTED-<type>]），但空擦除列表不保证文件干净，分享或提交前应人工检查。若根目录已有不含 Doc format v1 标记的 HANDOFF.md，视为外来文件不覆盖。文档路径在目标机器不存在时应停止并请用户粘贴，不要自行编造上下文。