从 Pi 压缩机制到 Handoff 技能实战

使用 Agent 跑长任务，最容易碰到这两类问题：做到一半上下文爆了，任务目标开始产生偏移；换个会话，刚执行任务现场的上下文又全没了，要重新再来。

Pi 官方压缩可以适当缓解第一类问题，机制的设计本身也值得拆开看看。但是它目前只管一次会话 Session：换会话、换 Agent，压缩的摘要也无法跟着走。所以我参考 Pi 的同一套思路做了一个基本：Handoff。

会话内靠 Agent 原生压缩，会话外靠 Handoff 承接上下文。

Pi 官方压缩算法

官方核心的设计点如下：

1. 触发设计：上下文达到上限后自动压缩，也可以手动输入命令 /compact。自动压缩压缩完，同一轮次继续跑，全程不打断。
2. 切点设计：从最新的消息往回数，保留 keepRecentTokens 配置的 Token 数量原样不动，更早的收成摘要。
3. 摘要不是自由文本：字段名是官方定死的——Goal、Constraints、Progress（Done / In Progress / Blocked）、Decisions、Next Steps、Critical Context，附带上这次读过的、改过的文件清单。
4. 摘要接力：上一轮生成的摘要，下一轮继续作为输入，不是每次从零开始；再次压缩也从上次保留的边界继续，不重复压已经保住的消息。读过的、改过的文件清单也跨压缩累计，不会丢。
5. 支持换分支：用 /tree 切换分支时，会把离开的分支收成摘要带过去，官方叫 branch summarization。
6. 单轮超长处理：一次对话轮特别长且装不下时，切点会落在轮的中间，拆成两段摘要合并。

Pi Agent 管的是：压缩和保留哪些内容、摘要长什么样，把怎么总结交给大模型。

正常情况下只有左边：更早的完整轮次压成一份摘要（compaction）。只有当某一个轮自己就特别长、切点落不进任何干净的轮边界时，才会多出中间这一块：超长轮的前半段单独压成 Turn Context，后半段作为最近的现场原样保留。两段拼在一起，下次请求时作为摘要注入给模型。

Pi 官方完整的压缩示意图：

Handoff 技能

结合 Pi Agent 的摘要结构 ——Goal、Constraints、Progress、Decisions、Next Steps、Critical Context 六个字段，做成 Handoff Skill，完整 SKILL.md 如下：

---
name: handoff
description: 生成或更新工程 handoff.md，记录可验证的目标、进展、决策、下一步和接手上下文。用于暂停开发、切换会话或交接未完成工作。
---

# Handoff

使用 [HANDOFF-TEMPLATE.md](templates/HANDOFF-TEMPLATE.md) 生成或更新工程 checkpoint。优先使用用户指定路径和项目约定；都没有时，写入 `docs/handoff/{yyyyMMdd-slug}-handoff/handoff.md`。

## Workflow

1. 确定交接范围，读取用户消息、项目代码上下文、项目规则和关联文档。
2. 若已有 handoff，将其作为 previous checkpoint：保留有效信息，加入新进展，移动完成事项，删除过期现场和已解决阻塞。
3. 严格按模板生成完整 checkpoint；没有证据的事项不得写入 Done，推测必须明确标记。
4. 确保内容简洁、自包含，并能让下一 Agent 直接执行第一项 Next Steps。

对应模板也固定，不让模型自由发挥结构：

# Handoff Template

使用以下固定结构生成 `handoff.md`。删除全部占位内容；除 Progress 下的 Done、In Progress、Blocked 外，不增加其它固定标题。

```md
# {Handoff Title}

> 本文件是当前工程 checkpoint。详细需求、设计和任务状态以引用的项目文档为准。

## Goal

{简要说明当前工作的目标、范围和交付边界。}

## Constraints

- {仍然生效且后续必须遵守的要求、偏好或禁止事项。}

## Progress

### Done

- [x] {已有证据的完成结果。}

### In Progress

- [ ] {尚未收口的当前工作；没有时写 None。}

### Blocked

- {阻塞、待决策或未验证事项；没有时写 None。}

## Decisions

- **{Decision}**: {Rationale}

## Next Steps

1. {下一 Agent 可以直接执行的第一项工作。}
2. {完成当前阶段所需的后续工作。}
3. {未来阶段任务及其开始条件。}

## Context

- {接手必需的文档和代码路径。}
- {接手必需的 Git 现场和未提交文件。}
- {已执行或未执行的验证及结果。}
- {必须精确保留的错误、接口或环境信息。}
```

对照 Pi 压缩，其实就三件事：

• 留什么：Next Steps 第一项必须能直接执行，没收口的现场留在 In Progress。
• 收什么：将目标、约束、有证据的进展、决策，放进 checkpoint；过程日志不要放入进来，避免影响 Agent 的注意力。
• 怎么续：做完的挪到 Done，过期的删掉，不是每次新写一篇；等达到下一个阶段的时候，重新再开一个 handoff 文件。

详细需求、设计、任务仍放在原文档里，handoff 只负责某个阶段的上下文传递和记录。

效果展示

1）Pi Agent 在 Session 内的压缩效果：

2）跨 Session Handoff 技能效果：

最后

Handoff 技能只做一件事：判断当前 Session 是否还需要继续干，或者总结某个阶段的任务项，就可以写成一份 checkpoint，来补充上下文并追踪进度。

上下文管理是一件非常重要的事，建议会话内交给压缩，会话外留一份好的 Handoff。

推荐阅读

Pi Agent 系列

• 用 Pi Agent 打造独属于你的 AI Harness
• 使用 Pi Agent 搭建个人开发工作流实战
• Pi Agent 接入 Grok 的上下文管理实战