# project-handoff 使用指南：换 agent 不用从头再讲一遍

**Published:** November 9, 2026

*上午 Codex 开的会话，下午换 ZCode 接着干，新会话对项目一无所知？project-handoff-skill 把交接变成项目里的一组文件：新会话开工前先看交接状态再动手，跨客户端通用。本文按五个场景介绍它，附安装方法、触发话术与服务命令。*

---
先还原一个你大概率经历过的下午：上午用 [Codex](https://openai.com/codex) 推进某个功能，聊透了架构取舍、踩平了一个依赖的坑、否掉了一个方案。下午你换了另一个客户端接着干——新会话对项目一无所知。目标是什么？干到哪了？哪些决定不能翻？上次的坑在哪？你要么从头复述一遍，要么眼睁睁看它把上午刚否掉的方案兴冲冲重做一遍，把上午刚踩过的坑原样再踩一次。

[project-handoff-skill](https://github.com/kelegele/project-handoff-skill) 把交接变成项目里的一组文件：新会话开工前先看交接状态再动手。它不绑定任何一家客户端——只依赖所有 agent 都认的 [AGENTS.md](https://agents.md/) 开放约定，谁接手都一样。

这个 skill 来自我的日常：五六个 agent 客户端来回切，每次交接都靠人肉复述。试过让 agent 自己写交接笔记，问题是没人管得住它的形状——有的越写越肥把上下文吃光，有的写完就忘没人接着看。于是把交接本身固化成 skill：开关一次问清、记录自动落盘、体积有硬预算。

## 五个该装它的场景

### 场景一：你在多个客户端之间来回切

上午 Codex、下午 ZCode、晚上 Kimi Code CLI——换客户端不想重新交代背景。装好后对 AI 说一句「用 project-handoff 给这个项目配置交接模式」，它完成用户级安装并在项目根放一个开关文件。之后每个新会话 AI 自动检查：没配置过，问一次「要不要开启交接」；配置过，静默沿用，绝不再问。

### 场景二：项目跨天跨周，会话开了又关

每次回来想直接续上，而不是翻聊天记录拼凑进度。开启交接后，项目里有一份 `HANDOVER.md`——目标、进度、红线决定、踩坑记录都在里面，新会话开工前先读它。写到哪、接下来干什么、哪些地方不能动，一眼看到。

### 场景三：被迫中途换工具

配额用尽、上下文塞满、某家模型当天不可用——你不得不换，而新工具必须立刻知道干到哪、哪些不能碰。这正是交接文件的主场：它不依赖任何特定客户端的会话记忆，文件在项目里，谁来都能读。

### 场景四：你吃过「漏讲一句」的亏

忘了说上次否掉了 A 方案，agent 重做一遍；忘了说那个依赖有坑，它原样再踩一次。交接记录把这些「负知识」钉在明面上——否掉的决定、绕开的路径、复现过的坑——新会话开工前就看到，而不是撞上之后再听你复盘。

### 场景五：一个项目多个人（或多个 agent）接力

你下班了，接手的人和它的 agent 需要同一份「干到哪了」。交接文件就在仓库里，人读得懂，agent 也读得懂——接力双方看的是同一份事实。

## 这些情况别装

安利文的诚意包括告诉你什么时候不该用：只用一个客户端从不切换的，单客户端自己的会话记忆就够，交接文件纯属开销；一次性脚本仓库没有「下一次会话」，交接无从谈起；如果你完全不理解 agent 为何物、工具全由别人代管，多出来的文件和询问只会添乱。

## 它凭什么管得住自己

agent 自己写交接笔记最常见的三种失控——越写越肥、写完没人看、不知道该不该写——这个 skill 各有一道闸：

- **占用有界**：交接记录超 8KB / 300 行自动瘦身，只留最近三节，其余进归档；运行记录每个 agent 保留 20 条，更旧的压成归档索引。agent 平时只读小文件。
- **足迹自解释**：一条「帮我体检交接配置」让 agent 跑 `--status`——这是什么、开还是关、哪些文件属于它、怎么关怎么删，一条命令答全。
- **心跳锁判孤儿**：会话半路死掉没人收尾，超时自动标记「已中断，待接手」，下一个 agent 一眼看到。
- **隐私红线**：钩子只记录事件名、时间、会话编号，从不记录提示词、回复、命令内容——仓库里有测试专门钉住这条承诺，45 个回放用例跑在 macOS + Linux 的 CI 上。

## 安装与使用

```bash
# 方式一：skills CLI（推荐）
npx skills add kelegele/project-handoff-skill

# 方式二：手动放进技能目录（目录名须为 project-handoff）
# 跨 agent 通用: ~/.agents/skills/   ZCode: ~/.zcode/skills/   Codex: ~/.codex/skills/

# 更新
npx skills update project-handoff
```

装好后触发只需要两句话术：

> 用 project-handoff 给这个项目配置交接模式

> 帮我体检交接配置

不想装任何东西？把仓库地址发给你的 agent：「帮我安装这个 skill：https://github.com/kelegele/project-handoff-skill」。

日常服务命令（都对 AI 说人话即可，agent 会去跑脚本）：

| 你说 | 它跑 | 干什么 |
|---|---|---|
| 开启/关闭交接 | `--enable` / `--disable` | 幂等开关；关闭只翻开关，保留全部记录 |
| 体检交接配置 | `--doctor` | 配置 / 钩子接线 / 权限 / 时区逐项体检，PASS/FAIL/WARN 分级 |
| 交接什么状态 | `--status` | 模式、文件所有权、最近运行、占用、卸载方法 |
| 清理交接记录 | `--gc` | 运行记录轮转 + 交接记录瘦身 |

## 三个高频疑问

**换一个它不认识的 agent 还能用吗？** 能。共享工件只依赖 AGENTS.md 通用约定，任何兼容客户端读同一份文件交接；自动记录是加分项，某家接不上不影响交接本身。

**会反复问我开不开吗？** 不会。首次问一次，之后有效配置静默沿用；配置坏了会点名具体问题，不会装作没配置过。

**怎么彻底卸载？** `--status` 给出完整清单：删项目里的开关文件与 `docs/execution/`，去掉 AGENTS.md 交接段，删技能目录里的 `project-handoff/`，全程无残留依赖。

## 现在就开始

最小成本的试用：挑一个你确实在多工具间切换的项目，装上，开启交接，然后正常干半天活、换一个客户端续一次。你会立刻看出交接文件替你省掉了多少复述。

仓库在 [GitHub](https://github.com/kelegele/project-handoff-skill)，问题与想法欢迎提 [Issues](https://github.com/kelegele/project-handoff-skill/issues)。它和 [agentsmd-skill](https://github.com/kelegele/agentsmd-skill) 是同一套思路的两块拼图：agentsmd 管「教训沉淀成规则」（用法见[场景指南](/blog/agentsmd-scene-guide)，设计见[设计哲学篇](/blog/agents-md-lessons-without-bloat)），project-handoff 管「进度交接给下一个会话」——一个让 AI 记住怎么干，一个让 AI 知道干到哪。