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 插件使用。