tamaratran/fast-jev-compaction

fast-jev-compaction – 一個 Claude Code 插件與 npm 套件

它做什麼

• 當你使用 Claude Code 時，會話歷史可能會變得非常龐大，因為每次 工具使用（例如 Read、Write）及其結果都會完整儲存。
• 內建的「壓縮」功能通常會要求 LLM 對舊的對話回合進行 總結，這可能導致遺失重要細節，例如檔案路徑或精確的錯誤訊息。
• fast-jev-compaction 以一種 選擇性修剪 過程取代此總結：它將 Jev 模型（一個 Typesafe LLM）用於判斷每個工具呼叫與每個工具結果是否仍需保留。被判定為不必要的內容將被刪除，其餘內容則完全保留原樣。

它是如何運作的

1. 透過 tool_use_id 將每個 tool_use 與其 tool_result 配對。第一則訊息與最新的 N 則訊息（可設定）被「固定」且永不修改。
2. 建立一個包含整個對話（依時間順序由最早開始）的 狀態，但將每個結果替換為類似 ok, 4213 chars (omitted) 的簡短占位符。不會對文字訊息進行任何總結。
3. 透過逐步截斷工具輸入、縮寫長文字、合併舊訊息等方式，將狀態調整至 maxStateTokens（預設 25k）的令牌預算內。
4. 對每個非固定工具呼叫，向 Jev 發送兩個是/否問題：保留該呼叫？ 與 保留結果原文？。
5. 將問題批量處理為盡可能多的請求，同時保持在 maxRequestTokens（預設 30k）以內。請求並行執行，結果合併。
6. 應用閾值（keepThreshold，預設 0.5）：
   • 如果結果保留機率 ≥ 閾值 → 保留呼叫與結果。
   • 否則如果呼叫保留機率 ≥ 閾值 → 保留呼叫，將結果截斷為 truncateHeadChars（預設 300）字元加上註解。
   • 否則 → 兩者皆刪除。
7. 重新組合訊息列表，移除任何變為空的訊息。輸出中永遠不會出現沒有對應呼叫的結果。

安裝

npm install fast-jev-compaction
export TYPESAFE_API_KEY=…   # 你的 Typesafe (Jev) 金鑰

基本用法（TypeScript）

import { compactMessages, reductionRatio, type Message } from 'fast-jev-compaction';

const transcript: Message[] = [
  { role: 'user', text: '修復失敗的測試。不要編輯 src/generated。', toolUses: [] },
  {
    role: 'assistant',
    text: '',
    toolUses: [{ tool_use_id: 'toolu_1', tool: 'Read', input: { file_path: 'src/a.ts' } }],
  },
  { role: 'user', text: '', toolUses: [], toolResults: [{ tool_use_id: 'toolu_1', text: '…file…' }] },
];

const result = await compactMessages(transcript, { preserveRecentMessages: 4 });
console.log(result.messages, result.decisions, result.stats);
if (reductionRatio(result) < 0.25) {
  // 壓縮不足 – 回退到一般總結
}

• compactMessages 回傳修剪後的訊息列表、每項呼叫的決策與統計資訊。
• 高階用法：實作你自己的 JevAsker（提供 ask(state, questions) 方法），並呼叫底層的 compact(messages, asker, options)。

設定選項（預設值顯示）

選項	預設值	含義
apiKey	process.env.TYPESAFE_API_KEY	你的 Typesafe (Jev) API 金鑰
model	jev-latest	要查詢的 Jev 模型
baseUrl	https://api.typesafe.ai/v1/systemone	API 端點
goal	最近的 3 個使用者提示	包含在狀態中的任務描述
keepThreshold	0.5	保留呼叫/結果的機率閾值
preserveRecentMessages	6	最新訊息永不修剪（第一則訊息始終保留）
maxStateTokens	25000	發送給 Jev 的狀態的令牌預算
maxRequestTokens	30000	每個請求的令牌預算（狀態 + 問題）
truncateHeadChars	300	被刪除結果中保留的字元數

限制

• 只有 工具 呼叫/結果可能被刪除；使用者/助理的純文字在最終輸出中從不縮短。
• 令牌計數是基於字元長度的粗略估計，而非真實分詞器。
• 模型的機率分數不是保證；助手可隨時重新執行被刪除的工具。
• 每次批量請求都會重新發送完整狀態，因此非常長的歷史可能產生大量 API 呼叫。

Claude Code 插件

• 倉儲包含一個插件（hooks/fast-jev.ts），可自動在 Claude Code 會話中執行此壓縮。
• 透過 Claude Code 的市場安裝：

  claude plugin marketplace add tamaratran/fast-jev-compaction
  claude plugin install fast-jev-compaction@fast-jev-compaction
  

• 安裝後，/compact 命令（和自動壓縮）將使用 Jev；彈出提示將顯示修剪是否成功或回退到內建總結。

開發與示範

• npm test 使用假的 Jev 客戶端執行單元測試（無網路）。
• demo/JevDemo 是一個小型 SwiftUI macOS 應用，用於可視化修剪流程；它不呼叫真實 API，專為螢幕錄製設計。

總結 fast-jev-compaction 為開發者提供了一種在保留所有重要工具互動的同時，丟棄真正不必要的歷史記錄的方法，避免了 Claude Code 通常執行的有損總結。它既可以作為一般 npm 套件使用，也可以作為第一流的 Claude Code 插件使用。