fast-jev-compaction

fast-jev-compaction 是一款专为 Claude Code 设计的上下文压缩工具，通过 TypeSafe Jev 的快速决策能力替代传统 LLM 摘要机制。其核心原则是永不重写内容：仅删除 Jev 判定为过时的工具调用与结果，所有保留的用户/助手文本及工具输出均保持逐字不变。这解决了传统摘要导致关键信息（文件路径、错误详情、约束条件）丢失的工程痛点，同时利用 Jev 的毫秒级响应避免压缩过程本身成为性能瓶颈。

该项目既可作为 npm 库集成到自定义工作流，也可作为 Claude Code 函数钩子插件直接替换内置 /compact 行为。当 Jev 无法有效缩减历史或发生错误时，自动回退至 Claude Code 原生摘要，确保会话连续性。

技术机制：无损裁剪与状态适配

决策逻辑

每个 tool_use 与其 tool_result 通过 tool_use_id 配对评估。Jev 接收完整对话历史（工具结果替换为简短说明如 ok, 4213 chars (omitted)），并对每个非固定调用提出两个 Noul 问题：

1. keepCall：该调用本身是否仍重要（已知执行过、带输入）？
2. keepResult：结果内容是否仍需逐字保留（重跑工具不可替代）？

决策阈值（默认 0.5）决定处理方式：

• keepResult ≥ threshold → 完整保留调用+结果
• keepCall ≥ threshold 但 keepResult < threshold → 保留调用，结果截断为前 truncateHeadChars（默认 300）字符 + 说明
• 两者均低于阈值 → 移除调用及结果

首条消息与最近 preserveRecentMessages（默认 6）条消息被固定，永不触碰。

状态适配策略

为将历史压缩至 maxStateTokens（默认 25k），按优先级分阶段应用：

1. 工具输入截断：1000 → 200 → 60 字符
2. 长文本缩略：头+尾模式，优先处理最旧非固定消息
3. 旧消息折叠：[… N chars omitted …]
4. 旧工具调用简化：每行一条摘要（t12 Read file_path=src/a.ts → ok 480ch）
5. 无可调用消息省略
6. 连续仅调用消息合并

若所有阶段后仍超限，抛出错误触发回退。Token 估算采用启发式规则（6 字母≈1 token，数字≈0.5 token），校准为略高于 Jev 实际计数。

请求批处理

问题按 maxRequestTokens（默认 30k）分批，每批携带完整状态并发发送。答案合并后统一应用决策，重建消息列表时确保结果不脱离调用、空消息被清除。

集成方式：库与插件双路径

作为 npm 库

npm install fast-jev-compaction
export TYPESAFE_API_KEY=...

import { compactMessages, reductionRatio } from 'fast-jev-compaction';
const result = await compactMessages(transcript, { preserveRecentMessages: 4 });
if (reductionRatio(result) < 0.25) {
  // 压缩收益不足，保留原始或改用摘要
}

支持自定义传输（实现 JevAsker 接口）、注入 fetch、调整阈值等。构建块（collectToolCalls, fitState, batchCalls 等）亦可单独导入。

作为 Claude Code 插件

1. 启用函数钩子（需 Claude Code ≥2.1.274）：

   // ~/.claude/settings.json
   { "env": { "CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1", "TYPESAFE_API_KEY": "<key>" } }
   

2. 安装插件：

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

3. 重启或 /reload-plugins 后，/compact 及自动压缩均经 Jev 处理。成功时 toast 显示 kept N/M messages, no summary；失败或收益不足时自动回退内置摘要。

本地开发可直接 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir . 运行，无需发布。

配置选项与监控

result.stats 提供压缩前后消息/字符数、决策分类统计、状态大小、适配阶段及请求批次，便于调优与故障诊断。

限制与注意事项

• 仅处理工具交互：用户/助手文本永不删除或缩短（仅在 Jev 视图中缩略）
• Token 估算非精确：基于字符启发式，可能与实际计费有偏差
• 概率非安全证明：低保留概率不等于“可安全删除”，助手仍可重跑工具
• 状态重复开销：每批请求携带完整状态，接近上限时成本线性增长
• API Key 安全：切勿硬编码或提交密钥，始终通过环境变量注入
• 早期访问依赖：函数钩子为 Claude Code 实验性功能，版本兼容性需持续关注