context-compression

上下文压缩 — 长会话管理

压缩已完成的工作，同时保留关键决策，让会话保持高效。

概述

长会话（30 轮以上）会导致上下文退化——AI 会忘记之前的工作、重复内容或遗忘决策。上下文压缩会主动总结已完成的阶段，让上下文窗口始终聚焦于当前工作。

Token 影响： 在长会话中，用语义摘要替换冗长的工具输出，可释放 5,000-15,000 个 token。

---

何时压缩

信号	操作
会话达到 20 轮以上	考虑主动压缩
Agent 重复之前的建议	上下文已饱和——立即压缩
用户说“我们已经讨论过这个”	立即压缩
切换到新的工作阶段	压缩已完成的阶段
工具输出很长（500 行以上）	对输出进行微压缩

---

压缩级别

级别 1：微压缩（工具输出）

在保留语义内容的同时压缩单个工具输出：

❌ Before (raw grep output — 200 lines, ~4,000 tokens):
src/auth/jwt.ts:15: import { verify } from 'jsonwebtoken'
src/auth/jwt.ts:23: export function validateToken(token: string) {
src/auth/jwt.ts:24:   try {
src/auth/jwt.ts:25:     const decoded = verify(token, SECRET)
... (195 more lines)

✅ After (micro-compact — 5 lines, ~100 tokens):
Grep results for "jwt": Found 8 files, 42 matches.
Key files: src/auth/jwt.ts (main JWT logic), src/middleware/auth.ts (middleware),
src/api/login.ts (token creation). Token validation at jwt.ts:23-40.
Error handling at jwt.ts:42-55. Secret loaded from env at jwt.ts:8.

级别 2：阶段摘要

将已完成的工作阶段替换为摘要：

❌ Before (full research transcript — ~3,000 tokens):
[turn 1] Read package.json...
[turn 2] Read src/index.ts...
[turn 3] Grep for "auth"...
[turn 4] Found 8 files related to auth...
[turn 5] Read src/auth/jwt.ts...
... (10 more turns of exploration)

✅ After (phase summary — ~200 tokens):
## Research Phase Complete
- Project: Next.js 15 app with JWT auth
- Auth files: 8 files in src/auth/, src/middleware/, src/api/
- Token flow: login → create JWT → store in httpOnly cookie → validate in middleware
- Bug location: src/auth/jwt.ts:45 — expiry check uses `<` instead of `<=`
- Decision: Fix the comparison operator, add edge case test

级别 3：会话检查点

为长时间运行的工作提供完整的会话摘要：

## Session Checkpoint (Turn 35)

### Completed
- [x] Researched auth system (8 files, JWT flow mapped)
- [x] Fixed token expiry bug in jwt.ts:45
- [x] Added edge case test in jwt.test.ts
- [x] Verified: all 42 tests passing

### In Progress
- [ ] Update API documentation
- [ ] Review related middleware

### Key Decisions
1. Keep httpOnly cookies (not localStorage) for token storage
2. Use `<=` for expiry check to include exact-moment expiry
3. Add 5-minute grace period for clock skew

### Files Modified
- src/auth/jwt.ts (line 45: comparison fix)
- tests/auth/jwt.test.ts (added 3 edge case tests)

---

压缩流程

步骤 1：识别已完成的阶段

What work is DONE and won't be revisited?
→ Research findings already synthesized
→ Implementation already verified
→ Decisions already made and applied

步骤 2：提取关键信息

From the completed phase, preserve:
✅ Decisions made and WHY
✅ File paths and line numbers of changes
✅ Key findings that inform ongoing work
✅ Error messages or test results (summarized)

Discard:
❌ Step-by-step tool invocation details
❌ Full file contents that were read
❌ Exploratory dead-ends that didn't lead anywhere
❌ Verbose error stack traces (keep the message only)

步骤 3：撰写摘要

Use the Phase Summary format above.
Keep to 100-300 tokens per completed phase.
Include enough detail to resume work without re-reading.

---

最佳实践

1. 压缩阶段，而非事实 — 保留单项决策，舍弃完整对话记录
2. 优先保留“原因”，而非“内容” — 决策的原因比实际运行的命令更重要
3. 绝不自动压缩 — 始终告知用户：“我正在总结已完成的研究阶段，以便让上下文保持聚焦”
4. 保留文件引用 — 始终在摘要中保留文件路径和行号
5. 在阶段转换时设置检查点 — 从研究切换到实现时，是自然的压缩时机