战略压缩技能
在您工作流中的战略性节点建议手动执行 /compact，而不是依赖任意的自动压缩。
何时激活
- 运行长时间会话，接近上下文限制（200K+ tokens）
- 处理多阶段任务（研究 → 规划 → 实施 → 测试）
- 在同一会话中切换不相关的任务
- 完成一个主要里程碑并开始新工作后
- 当回复变慢或变得不连贯时（上下文压力）
为什么是战略压缩？
自动压缩在任意点触发：
- 通常在任务中途触发，丢失重要上下文
- 不了解逻辑任务边界
- 会中断复杂的多步骤操作
在逻辑边界进行战略压缩：
- 探索之后，执行之前 — 压缩研究上下文，保留实施计划
- 完成一个里程碑后 — 为下一阶段全新开始
- 重大上下文切换之前 — 在进行不同任务前清除探索上下文
工作原理
scripts/suggest-compact.js 脚本在 PreToolUse（编辑/写入）上运行，并结合了两个信号：
- 上下文大小（主要） — 从会话记录（钩子载荷中的
transcript_path）读取最新的usage记录，并求和input_tokens + cache_read_input_tokens + cache_creation_input_tokens（该轮次的真实上下文大小）。在窗口缩放阈值下建议/compact— 200K 窗口为 160k tokens，1M 窗口为 250k tokens（从[1m]模型标记检测，或在观察到 tokens 已超过 200k 时推断）— 并在上下文每增长 60k tokens 后再次提醒 - 工具调用次数（次要） — 统计会话中的工具调用次数；在可配置的阈值（默认：50 次调用）下建议，之后每 25 次调用再次提醒
仅工具调用次数作为窗口压力的代理指标存在缺陷：几次大文件读取或 MCP 响应就可以在很少的调用次数内填满窗口，而许多小调用可能在窗口几乎为空时就超过 50 次。上下文大小信号在真正重要时触发。
钩子设置
作为插件安装？ 无需设置。插件的 hooks/hooks.json 已经注册了 suggest-compact.js（钩子 id pre:edit-write:suggest-compact，在 standard 和 strict 钩子配置文件中激活）。请勿将下面的代码块复制到 ~/.claude/settings.json 中 — ~/.claude/scripts/ 在插件安装时不存在，且重复插件钩子会导致双重执行。
如果手动安装 (./install.sh)，请添加到您的 ~/.claude/settings.json：
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit",
"hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
},
{
"matcher": "Write",
"hooks": [{ "type": "command", "command": "node ~/.claude/scripts/hooks/suggest-compact.js" }]
}
]
}
}
配置
环境变量：
COMPACT_THRESHOLD— 首次建议前的工具调用次数（默认：50）COMPACT_CONTEXT_THRESHOLD— 上下文大小建议前的上下文 tokens 数（默认：200K 窗口为 160000，1M 窗口为 250000；0禁用上下文信号）COMPACT_CONTEXT_INTERVAL— 建议重复前的额外上下文 tokens 数（默认：60000）COMPACT_STATE_TTL_DAYS— 临时目录中过时会话状态文件的过期天数（默认：14）ECC_CONTEXT_WINDOW_TOKENS— 显式上下文窗口大小（以 tokens 计），覆盖自动检测。为那些报告 id 缺少[1m]标记的大窗口模型设置此值（例如 400K Opus 4.x 或新的 1M 窗口模型系列），以便阈值能缩放到真实窗口，而不是默认使用 200K 从而高估上下文使用量。CLAUDE_CODE_AUTO_COMPACT_WINDOW— Claude Code 的原生窗口大小覆盖值（以 tokens 计）；当ECC_CONTEXT_WINDOW_TOKENS未设置时，作为备用方案被采纳。
上下文窗口否则会从
[1m]模型标记自动检测，或在观察到 tokens 已超过 200k 时推断。对于携带这两种信号的大窗口模型，请设置上述覆盖之一，以便/compact建议在正确点触发。
压缩决策指南
使用此表格决定何时压缩：
| 阶段转换 | 压缩？ | 原因 |
|---|---|---|
| 研究 → 规划 | 是 | 研究上下文庞大；计划是提炼后的输出 |
| 规划 → 实施 | 是 | 计划已写入（文件或任务列表，如果有的话）；为代码释放上下文 |
| 实施 → 测试 | 可能 | 如果测试引用近期代码则保留；如果切换关注点则压缩 |
| 调试 → 下一个功能 | 是 | 调试痕迹会污染不相关工作的上下文 |
| 实施过程中 | 否 | 丢失变量名、文件路径和部分状态代价高昂 |
| 失败方法后 | 是 | 在尝试新方法前清除死胡同推理 |
压缩后保留的内容
了解哪些内容会持久化有助于您放心压缩：
| 保留 | 丢失 |
|---|---|
| CLAUDE.md 指令 | 中间推理和分析 |
| 磁盘上的文件 | 您之前读取的文件内容 |
内存文件 (~/.claude/memory/) | 多步骤对话上下文 |
| Git 状态（提交，分支） | 工具调用历史和计数 |
| 任务列表 — 仅当您有待办工具（见下文） | 口头表述的细微用户偏好 |
不要依赖任务列表存续 — 它可能不存在
Claude Code 2.1.233 在 Opus 4.8、Sonnet 5、Fable 5、Mythos 5 及更新模型上默认移除了待办/任务工具（
TodoWrite、TaskCreate/Get/Update/List）。CLAUDE_CODE_ENABLE_TODO_TOOLS=1可以恢复它们，但这是一个每台机器的环境设置 — 它不随此技能传递，因此您无法假设读者拥有它。这很重要，因为“我的待办列表会在压缩后存续”是人们选择压缩 而不是 将状态写入文件的一个原因。如果这些工具不存在，就没有列表可以存续，计划就直接消失了。在压缩前将计划写入文件 — 文件在每个版本和每个模型上都持久存在。将任务列表视为可能缺失的便利工具，绝不要将其视为您的持久记录。
最佳实践
- 规划完成后压缩 — 一旦计划最终确定并写入文件，压缩以全新开始
- 调试完成后压缩 — 在继续之前清除错误解析上下文
- 不要在实施过程中压缩 — 保留相关更改的上下文
- 阅读建议 — 钩子告诉您何时，您决定是否
- 在压缩前写入 — 在压缩前将重要上下文保存到文件或内存中
- 使用带摘要的
/compact— 添加自定义消息：/compact 接下来专注于实现身份验证中间件
Token 优化模式
触发器表延迟加载
不要在会话开始时加载完整的技能内容，而是使用一个将关键词映射到技能路径的触发器表。技能仅在触发时加载，将基线上下文减少 50% 以上：
| 触发器 | 技能 | 何时加载 |
|---|---|---|
| "test"、"tdd"、"coverage" | tdd-workflow | 用户提到测试 |
| "security"、"auth"、"xss" | security-review | 安全相关工作 |
| "deploy"、"ci/cd" | deployment-patterns | 部署上下文 |
上下文构成感知
监控哪些内容在消耗您的上下文窗口：
- CLAUDE.md 文件 — 始终加载，保持精简
- 已加载的技能 — 每个技能增加 1-5K tokens
- 对话历史 — 随每次交换增长
- 工具结果 — 文件读取、搜索结果增加体积
重复指令检测
常见重复上下文来源：
~/.claude/rules/和项目.claude/rules/中存在相同规则- 重复 CLAUDE.md 指令的技能
- 覆盖重叠领域的多个技能
上下文优化工具
token-optimizerMCP — 通过内容去重实现自动化 95%+ 的 token 缩减context-mode— 上下文虚拟化（已展示从 315KB 到 5.4KB 的压缩）
相关
- 长篇指南 — Token 优化部分
- 内存持久化钩子 — 用于在压缩后仍存续的状态
continuous-learning技能 — 在会话结束前提取模式