leikegeek/context-compaction

战略性上下文压缩

技能目标

在流水线阶段切换时，将当前上下文中的关键信息结构化保存为「上下文快照」，然后执行压缩（compact），再通过恢复检查确认信息无损。整个过程分三步：快照 → 压缩 → 验证。

核心原则

1. 先快照后压缩：没有快照就没有压缩。快照是压缩的前提，不是可选步骤。
2. 结构化优于自然语言：快照使用固定模板，确保关键字段不遗漏，便于压缩后快速恢复。
3. 持久化文件是锚点：技术方案、变更清单、实施计划等文件已持久化在磁盘上，快照只需记录路径，无需复制内容。
4. 用户确认是门禁：压缩前必须向用户展示快照摘要并获得确认。

执行流程

第一步：判断时机

检查 context-compaction 规则中的时机表：

• 当前是否处于「必须建议压缩」的节点？→ 主动建议
• 当前是否处于「禁止压缩」的场景？→ 明确拒绝，即使用户要求也应说明原因
• 均不符合但 token 消耗已明显偏高？→ 可建议，但标注为非标准时机

第二步：生成上下文快照

按以下模板输出快照。所有字段必填，无对应内容时填写「无」。

# 上下文快照

> 生成时间：{当前时间}
> 触发节点：{如 B1→B2 切换}

## 任务标识

- 需求编号：{SV-xxxxx}
- 当前阶段：{如 B1 实施准备完成}
- 下一阶段：{如 B2 编码实施}
- 当前模式：{设计模式 / 编码模式}

## 任务契约摘要

- 目标：{一句话概括}
- 范围：{受影响的模块/层级}
- 允许写入路径：{路径列表}
- 禁止项：{约束列表}
- 验收标准：{关键验收条件}

## 关键决策记录

{列出本阶段做出的重要决策，包括方案选型、已确认的疑问答案、取舍理由}

1. {决策1}
2. {决策2}
3. ...

## 任务进度

### 已完成
- [ ] {已完成的任务项，含任务ID}

### 未完成
- [ ] {未完成的任务项，含任务ID和依赖关系}

## 待恢复文件

{压缩后如需回溯细节，应读取以下文件}

| 文件 | 用途 |
|------|------|
| docs/design/SV-xxxxx-tech-design.md | 技术方案（含架构设计、接口定义） |
| docs/delivery/SV-xxxxx-changelist.md | 变更清单（编码阶段增量记录） |
| AGENTS.md | 项目画像（技术栈、架构模式） |
| {其他相关文件} | {用途说明} |

## 下一步行动

{进入下一阶段后的第一个动作}

第三步：请求用户确认

向用户展示快照摘要（不必展示完整模板，突出关键信息），并询问：

即将执行上下文压缩。以上快照包含了当前阶段的关键信息，压缩后将以此快照为恢复基础。

• 是否有需要补充的信息？
• 确认后将执行压缩。

第四步：执行压缩

用户确认后，使用 Cursor 的 compact 机制压缩对话上下文。压缩时将快照内容作为保留摘要的核心输入。

第五步：恢复验证

压缩完成后，立即执行以下自检：

必检项（全部通过才算压缩成功）

| 检查项 | 验证方式 | |--------|----------| | 需求编号 | 能正确说出当前 SV-ID | | 当前阶段 | 能正确说出当前处于哪个阶段 | | 当前模式 | 能正确说出当前工作模式和写入边界 | | 任务契约 | 能复述目标、范围、禁止项 | | 未完成任务 | 能列出所有未完成的任务清单 | | 关键文件路径 | 能说出技术方案和变更清单的文件路径 |

检查失败的处理

若任何必检项无法回答：

1. 从快照中的「待恢复文件」列表读取对应文件
2. 恢复缺失信息
3. 重新自检直到全部通过
4. 向用户报告恢复情况

输出格式

压缩完成后，向用户输出简要确认：

✅ 上下文压缩完成
- 需求编号：SV-xxxxx
- 当前阶段：{阶段}（{模式}）
- 未完成任务：{N} 项
- 恢复验证：全部通过

特殊场景

用户主动要求压缩

当用户在非标准时机主动要求压缩时：

1. 检查是否处于禁止压缩的场景，如果是则向用户说明原因并建议等待
2. 如果不在禁止时机，按正常流程执行，但在快照中标注「非标准时机：用户主动触发」

从流水线 A 断开后重新进入

通过 /code SV-ID 独立进入流水线 B 时，不存在需要压缩的历史上下文，跳过压缩直接执行 B0。

连续多次压缩

若短时间内（如 B0→B1→B2 连续切换）多次触发压缩建议，可合并为一次压缩，在到达最近的高优先级压缩点时统一执行。

与其他技能的关系

• coding：压缩时机避开 TDD 循环；编码子代理默认组间串行的派发/验收过程也不触发压缩。若用户显式确认「允许并行」、且存在多组同时执行，此并发窗口同样不触发压缩。
• implementation-planning：B1 实施准备完成后是关键压缩点，快照中的「未完成任务」直接对应实施计划的任务清单。
• delivery：B3→B4 的可选压缩不影响交付物完整性，因为交付物已持久化在文件中。