compress

name	compress
description	上下文压缩。当 token 超限、需要压缩对话、/compress 时使用。

Compress — 上下文压缩

管理 Claude Code 会话的上下文窗口，防止 token 溢出导致的性能下降和费用飙升。

自动触发条件

条件	阈值	行为
Token 使用率	超过窗口的 75%	自动触发压缩
连续对话轮次	超过 50 轮	建议压缩
单次会话时长	超过 2 小时	建议压缩

默认窗口为 200K tokens（可在 settings.json 中调整 contextWindowSize）。

压缩策略详解

压缩不是简单截断，而是有选择地保留和丢弃：

保留（高优先级）

1. 用户偏好与约束 — 用户的显式要求、禁止事项、格式偏好
2. 关键决策与结论 — 设计决策、选型理由、最终确认的方案
3. 未完成任务 — 正在进行中的任务状态、待确认事项
4. 重要文件路径 — 被频繁引用的文件位置
5. 项目结构概要 — 核心模块、入口文件、关键配置

丢弃（低优先级）

1. 中间探索过程 — 试错、调试、已否定的方案
2. 已完成的子任务细节 — 已确认完成的步骤
3. 重复的错误信息 — 多次出现的相同报错
4. 冗长的工具输出 — 大段终端输出、日志
5. 过时的对话分支 — 已被用户否决的方向

压缩优先级

关键决策 > 当前任务上下文 > 用户偏好 > 文件引用 > 历史摘要 > 中间过程

手动触发方式

方式	命令	说明
斜杠命令	/compress	标准压缩
Agent 调度	@compress	通过 dispatch 调度
快捷命令	/compact	别名，等同 /compress
代码触发	python maestro/dispatch.py --agent compress	编程调用

压缩前后对比

压缩前自动记录：

• 当前 token 用量（输入 / 输出）
• 会话轮次
• 会话持续时间

压缩后输出：

• 压缩比（节省的 token 百分比）
• 保留的关键信息摘要
• 被丢弃的内容概要

与 PreCompact Hook 的配合

压缩前自动执行 hooks/PreCompact.sh：

1. 保存任务状态 — 当前正在执行的任务 ID 和进度
2. 记录压缩日志 — 时间戳写入 .claude/memory/.compact-log
3. 备份关键上下文 — 用户偏好和未完成决策写入 memory 目录

可在 PreCompact.sh 中添加自定义保存逻辑（见脚本注释）。

配置调优

在 .claude/settings.json 中调整：

{
  "contextWindowSize": 200000,
  "autoCompactionThreshold": 0.75,
  "compactPreserveRecentTurns": 5
}

参数	默认值	说明
contextWindowSize	200000	上下文窗口大小（tokens）
autoCompactionThreshold	0.75	自动压缩触发比例
compactPreserveRecentTurns	5	保留最近 N 轮完整对话

注意事项

• 压缩后不可逆 — 丢弃的中间过程无法恢复
• 如果压缩后关键信息丢失，可从 .claude/memory/ 中恢复备份
• 频繁压缩（每小时超过 3 次）说明对话结构需要优化 — 考虑拆分为多个子任务
• 压缩不影响已保存到文件的结果（maestro/results/、工作日志等）