compact

# 策略性压缩技能

本技能用于在合适的时机建议上下文压缩，优化会话效率。

> ⚠️ **重要提示**：Claude Code 官方的 auto-compact 有已知 bug（见下文），建议主动在 **70%** 时手动压缩。

## 官方 Auto-Compact Bug

Claude Code 官方的自动压缩功能存在已知问题：

| Issue                                                            | 版本     | 状态     | 问题描述                            |
| ---------------------------------------------------------------- | -------- | -------- | ----------------------------------- |
| [#18211](https://github.com/anthropics/claude-code/issues/18211) | v2.1.7+  | 已关闭   | `/cc-best:compact` 和 auto-compact 同时损坏 |
| [#21853](https://github.com/anthropics/claude-code/issues/21853) | v2.1.23+ | **开放** | `/cc-best:compact` 始终失败（回归 bug）     |
| [#16349](https://github.com/anthropics/claude-code/issues/16349) | -        | -        | 警告和错误阈值相同，无预警          |

**问题根因**：

- 官方 auto-compact 设计在 **95%** 时触发，但压缩本身需要空间
- 当上下文超过 **~85%** 时，压缩可能因空间不足而失败
- 警告阈值和错误阈值相同，用户无预警就触发硬限制

**本插件的 Workaround**：

- 默认启用 `suggest-compact.js` 钩子
- 每 40 次工具调用提醒一次
- 建议在 **70%** 时主动压缩

## 触发条件

- 工具调用次数达到阈值（默认 40 次）
- 从研究/探索阶段转向实现阶段
- 完成一个里程碑后
- 计划已最终确定
- **上下文使用率 > 60%**（建议主动压缩）

## 为什么需要策略性压缩

### 自动压缩的问题

- 发生在任意点，经常在任务中途
- 可能丢失重要上下文
- 打断思维连贯性
- **官方有 bug，可能失败**

### 策略性压缩的优势

- 在逻辑阶段边界压缩
- 保留关键决策和上下文
- 探索后、执行前压缩
- 里程碑完成后压缩
- **避免触发官方 bug**

## 压缩时机

### 适合压缩的时机

```
1. 探索/研究完成，准备开始实现
2. 计划已确定，准备执行
3. 完成一个功能模块
4. 解决一个复杂问题后
5. 代码审查反馈处理完
6. 上下文使用率 > 70%
```

### 不适合压缩的时机

```
1. 调试进行中
2. 多文件修改未完成
3. 测试失败修复中
4. 重要决策讨论中
5. 复杂逻辑实现中途
```

## 压缩前检查清单

```markdown
## 压缩前确认

- [ ] 当前任务状态已记录到 progress.md
- [ ] 重要决策已记录
- [ ] 待确认假设已标注
- [ ] 未完成的代码变更已保存
- [ ] 下一步明确

## 压缩内容

- 当前进度
- 关键决策及原因
- 待处理项
- 下一步任务
```

## 使用方式

### 手动触发

```
/cc-best:compact
```

### 自动建议

当达到以下条件时，系统会提示考虑压缩：

1. **工具调用数达到阈值**（默认 40 次）
2. **每隔一定间隔**（默认每 20 次工具调用后提醒）

## 配置

### 阈值配置

```bash
# 环境变量
export COMPACT_THRESHOLD=40  # 首次提醒的工具调用数
export COMPACT_INTERVAL=20   # 后续提醒间隔
```

### Hook 配置

已在 `hooks/hooks.json` 中默认启用：

```json
{
  "matcher": ".*",
  "hooks": [
    {
      "type": "command",