策略性壓縮 (Strategic Compact)

策略性壓縮技能

在工作流程中的策略性節點建議手動 /compact，而非依賴任意的自動壓縮。

啟動時機

• 執行長時間工作階段，接近上下文限制（200K+ token）
• 處理多階段任務（研究 → 規劃 → 實作 → 測試）
• 在同一工作階段中切換不相關的任務
• 完成一個主要里程碑並開始新工作後
• 當回應速度變慢或連貫性變差時（上下文壓力）

為何策略性壓縮？

自動壓縮在任意時間點觸發：

• 經常在任務中途觸發，遺失重要上下文
• 不了解邏輯任務邊界
• 可能會中斷複雜的多步驟操作

在邏輯邊界進行策略性壓縮：

• 探索之後、執行之前 — 壓縮研究上下文，保留實作計劃
• 完成一個里程碑之後 — 為下一階段提供全新開始
• 在重大上下文轉換之前 — 在執行不同任務前，清除探索上下文

運作方式

suggest-compact.js 腳本在 PreToolUse（Edit/Write）時執行，並結合兩種訊號：

1. 上下文大小（主要訊號） — 從工作階段記錄（掛鉤 payload 中的 transcript_path）讀取最新的 usage 記錄，並加總 input_tokens + cache_read_input_tokens + cache_creation_input_tokens（該次交談的真實上下文大小）。根據視窗縮放後的閾值建議 /compact — 在 200K 視窗中為 160K token，在 1M 視窗中為 250K token（從模型標記 [1m] 偵測，或當觀察到的 token 已超過 200K 時推斷）— 並且在每次上下文增加額外 60K token 後重新提醒。
2. 工具呼叫次數（次要訊號） — 計算工作階段中的工具調用次數；在可設定的閾值（預設：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 — 觸發上下文大小建議前的上下文 token 數（預設：200K 視窗為 160000，1M 視窗為 250000；設為 0 可停用上下文訊號）
• COMPACT_CONTEXT_INTERVAL — 建議重複觸發前的額外上下文 token 數（預設：60000）
• COMPACT_STATE_TTL_DAYS — 清除暫存目錄中過期的每個工作階段狀態檔案的天數（預設：14）
• ECC_CONTEXT_WINDOW_TOKENS — 明確的上下文視窗大小（以 token 為單位），會覆蓋自動偵測。對於其報告的 ID 缺少 [1m] 標記的大型視窗模型（例如 400K Opus 4.x，或新的 1M 視窗模型系列）請設定此變數，以便閾值能根據真實視窗進行縮放，而不是預設為 200K 並高估上下文使用量。
• CLAUDE_CODE_AUTO_COMPACT_WINDOW — Claude Code 的原生視窗大小覆寫值（以 token 為單位）；當 ECC_CONTEXT_WINDOW_TOKENS 未設定時，以此作為備用。

上下文視窗會透過 [1m] 模型標記自動偵測，或在觀察到的 token 已超過 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 可以將其恢復，但這是每台機器的環境設定 — 它不會隨此技能一同傳遞，因此您不能假設使用者有此設定。

這很重要，因為「我的待辦事項清單會在壓縮後保留」是人們選擇壓縮而不是將狀態寫下的原因。如果這些工具不存在，就沒有可供保留的清單，計劃也就完全消失了。在壓縮之前，先將計劃寫入檔案 — 檔案在所有版本和所有模型上都會保留。請將任務清單視為可能缺失的便利功能，切勿將其當作您的持久記錄。

最佳實踐

1. 在規劃完成後壓縮 — 一旦計劃完成並寫入檔案，即可進行壓縮以重新開始
2. 在除錯後壓縮 — 在繼續之前清除錯誤解決上下文的痕跡
3. 不要在實作中途壓縮 — 保留相關變更的上下文
4. 閱讀建議 — 掛鉤告訴您何時壓縮，而由您決定是否壓縮
5. 在壓縮前先寫入 — 在壓縮前將重要上下文儲存到檔案或記憶體中
6. 使用帶有摘要的 /compact — 新增自訂訊息：/compact 接下來專注於實作認證中介軟體

Token 優化模式

觸發表延遲加載

與其在工作階段開始時載入完整的技能內容，不如使用一個將關鍵字對應到技能路徑的觸發表。技能僅在觸發時載入，可將基礎上下文減少 50% 以上：

觸發詞	技能	載入時機
"test", "tdd", "coverage"	tdd-workflow	使用者提及測試
"security", "auth", "xss"	security-review	與安全相關的工作
"deploy", "ci/cd"	deployment-patterns	部署上下文

上下文組成感知

監控哪些內容消耗了您的上下文視窗：

• CLAUDE.md 檔案 — 始終載入，請保持精簡
• 已載入的技能 — 每個技能增加 1-5K token
• 對話歷史 — 隨著每次交流而增長
• 工具結果 — 檔案讀取、搜尋結果會增加內容量

重複指令偵測

常見的重複上下文來源：

• 在 ~/.claude/rules/ 和專案 .claude/rules/ 中存在相同的規則
• 重複 CLAUDE.md 指令的技能
• 涵蓋重疊領域的多個技能

上下文優化工具

• token-optimizer MCP — 透過內容去重實現自動化 95%+ 的 token 減量
• context-mode — 上下文虛擬化（已展示從 315KB 降至 5.4KB）

相關資源

• 長篇指南 — Token 優化章節
• 記憶體持久化掛鉤 — 用於在壓縮後保留狀態
• continuous-learning 技能 — 在工作階段結束前提取模式