跨 Agent 任务续航 whaojie797-design/agent-handoff-kit

agent-handoff-kit

EN: 一个可移植、基于文件的工作交接协议，让长任务在上下文压缩、切换模型、崩溃或多人接手后不丢进度，也绝不把"计划"伪装成"已完成的事实"。
中文： 一个可移植、基于文件的工作交接协议，让长任务在上下文压缩、切换模型、崩溃或多人接手后不丢进度，也绝不把"计划"伪装成"已完成的事实"。

价值主张 / Value proposition
- EN: 不是待办清单，而是一份交接质量契约，明确区分 已验证 · 已完成 · 待完成 · 假设。
- 中文： 不是待办清单，而是一份"可移交、可恢复、可验证"的 Agent 工作状态协议，明确区分"已验证 / 已完成 / 待完成 / 假设"。

为什么需要它 / Why

长任务死于四种方式。本工具包全部拦截。

| 失败方式 | 本工具包如何防止 |
| 上下文窗口被压缩 → 计划被遗忘 | 状态存放在 4 个文件中，而非上下文里。 |
| 从 Claude 切换到 Codex → 无共享记忆 | 文件与厂商无关；任何 Agent 都能读取。 |
| 任务中途崩溃 → "到底完成了没有？"未知 | EVIDENCE_LOG.md 记录实际运行了什么 + 输出。 |
| 新人/新 Agent 接手 → 一切重新推导 | HANDOFF.md 支持在 30 秒内恢复。 |

中文： 长任务死于四种方式，本工具包全部拦截——上下文压缩丢失计划、切换厂商无共享记忆、崩溃后不知是否完成、接手者重复推导。状态写入 4 个文件，而非留在上下文里。

演示 / Demo

agent-handoff-kit demo

动画占位符。发布前请替换为真实的 30 秒 GIF（例如：任务中断 → 新 Agent 30 秒恢复的屏幕录制）。

安装 / Install

这是一个开放标准的 Agent Skill。请将它分别安装到你使用的每个宿主中——它们不共享 skill 目录。

Claude Code

mkdir -p ~/.claude/skills
cd ~/.claude/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit
or copy the folder here if you downloaded a tarball

然后在 Claude Code 中，当任务超过 30 分钟，或你说 继续 / 接手 / 恢复 / 下次再做 时，该 skill 会激活。

Cursor

mkdir -p ~/.cursor/skills
cd ~/.cursor/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit

Codex

mkdir -p ~/.codex/skills
cd ~/.codex/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit

Gemini CLI

mkdir -p ~/.gemini/skills
cd ~/.gemini/skills
git clone https://github.com/whaojie797-design/agent-handoff-kit.git agent-handoff-kit

重要 / Important: 每个宿主都有自己的 skills 目录。在 Claude Code 中安装并不意味着它在 Cursor 中可用。请在你使用的每个宿主中都安装。每个宿主读取相同的 SKILL.md 和 references/，因此跨厂商行为一致。

验证安装

python3 ~/.claude/skills/agent-handoff-kit/scripts/check_state.py --selfcheck

四个状态文件 / The Four State Files

| 文件 | 存放内容 |
| TASK_STATE.md | 目标、范围、当前阶段、状态、阻塞项。 |
| EVIDENCE_LOG.md | 运行过的命令、输出摘要、测试结果、链接。 |
| HANDOFF.md | 用于在 30 秒内恢复的单一文件。 |
| DECISIONS.md | 权衡取舍及其原因。 |

状态标记强制保证诚实：

| 标记 | 含义 |
| [x] | 已验证 — 已完成且由证据证明 |
| [~] | 已完成 — 已做，但尚未验证 |
| [ ] | 待处理 — 尚未开始 |
| [?] | 假设 — 需要确认 |

铁律： 永远不要把 [?] 标成 [x]。永远不要让 [~] 没有对应的验证步骤。

Natural-language workflow / 自然语言工作流

你不需要输入斜杠命令。只需说出你想要什么：

| 你说 | 等价于 | 会发生什么 |
| "保存检查点" / "save checkpoint" | /checkpoint | 刷新全部 4 个文件，诚实状态，写下下一步。 |
| "恢复任务" / "resume" | /resume | 读取状态 → 交接 → 决策 → 最近 5 条证据条目，继续。 |
| "交接给下一位" / "handoff" | /handoff | 完成 HANDOFF.md，附上 30 秒内恢复的说明。 |

Complete example: 任务中断 → 新 Agent 30 秒恢复上下文

Setup

你正在跨 3 个端点实现 Stripe checkout 集成。任务估计约 90 分钟。在第 40 分钟时会话被中断（达到上下文限制，一天结束）。

Step 1 — 中断之前，正在运行的 Agent 写下了 TASK_STATE.md

Task State

Goal
Integrate Stripe Checkout into the billing service with idempotent webhook handling.

Scope
- In: /api/checkout, /api/webhook, idempotency keys, unit tests.
- Out: refunds, customer portal, UI.

Current Phase
Phase 2 of 3: Implementation (Phase 1 setup done, Phase 3 tests pending).

Progress
- [x] Stripe SDK added + keys via env (EVIDENCE: E-003)
- [x] /api/checkout creates PaymentIntent (EVIDENCE: E-005, curl 200)
- [~] /api/webhook signature verification written, NOT yet tested
- [ ] Idempotency key handling
- [ ] Unit tests for webhook
- [?] Stripe sends payment_intent.succeeded for this account tier (assume yes, confirm)

Blockers
- None currently.

Last Updated
2026-07-30T12:41:00Z · claude-opus · session-7c3

Step 2 — 以及 HANDOFF.md

Handoff

Resume In 22 秒内恢复完成。状态摘要：
- 目标：Stripe Checkout 集成，3 个端点。
- 已验证完成：SDK 设置、/api/checkout。
- 已完成但未验证：webhook 签名校验（src/webhook.ts:42）。
- 根据 HANDOFF.md 的下一步：npm test test/webhook.spec.ts。
- 未决假设：payment_intent.succeeded 事件层级——需要确认。

现在运行测试。

结果： 零重新推导。新 agent 确切知道什么已被证明、什么只是写好了、下一步该做什么——因为协议强制前一个 agent 区分 Verified 和 Completed。

可选校验脚本 / Optional validation script

在任何交接之前，运行： bash
python3 scripts/check_state.py # checks TASK_STATE.md etc. in cwd
python3 scripts/check_state.py --strict # exit 1 on any warning

它会检测：缺失任务目标、缺失即时下一步、[~] 项缺失验证证据、未解决的 [?] 假设，以及过期的阻塞项。scripts/check_state.sh 中提供了 bash 回退方案。

隐私 / Privacy

- 不写入任何密钥。 状态文件引用环境变量名（STRIPE_SECRET_KEY）和配置路径——绝不引用其值。该技能拒绝写入凭证。
- 不上传任何项目内容。 所有四个文件均为本地 Markdown。不会向任何外部服务发送任何内容。证据链接为相对路径或本地运行 ID。
- 可安全提交。 如果你将状态文件提交到仓库，请将 .env 以及任何作为证据引用且包含密钥的路径加入 .gitignore。示例 .gitignore 片段见 references/host-integration.md。

中文： 不写入任何密钥、Token、凭证；状态文件只用环境变量名或相对路径引用。所有文件均为本地 Markdown，不上传任何项目内容到外部服务。

评测 / Evaluation

15 个案例，涵盖上下文清除恢复、跨厂商交接、测试失败、需求变更、中断以及人工交接——见 EVALUATION.md。

文件地图 / File map

agent-handoff-kit/
├── SKILL.md # activation rules + protocol summary
├── README.md # this file
├── LICENSE # MIT
├── EVALUATION.md # 15 evaluation cases
├── references/
│ ├── state-schemas.md # field-level schema for the 4 files
│ ├── file-templates.md # copy-paste starter templates
│ ├── workflow.md # checkpoint / resume / handoff sequences
│ └── host-integration.md # install on Claude/Cursor/Codex/Gemini
├── scripts/
│ ├── check_state.py # state validator (python3)
│ └── check_state.sh # state validator (bash fallback)
└── docs/
└── demo.svg # animated placeholder

许可证

MIT——见 LICENSE。Copyright (c) 2026 whaojie797-design