fast-jev-compaction

fast-jev-compaction 快速入门

fast-jev-compaction（tamaratran/fast-jev-compaction）是一个 Claude Code 插件（同时可作 npm 库使用），用来替换 Claude Code 内置的 compaction summary（有损上下文压缩）。内置压缩让 LLM 把旧对话「摘要」成一段文字——文件路径、确切报错、约束条件、命令都可能消失。本库不重写任何内容：它把整个会话展示给 Jev 决策模型，在一次快请求里给每个 tool call / tool result 打分，只删除判定过时的条目或做截断；用户与助手文本逐字保留、顺序不变。2026-10-01 核验（GitHub API + README）：7,251★ / 469 fork，最近 push 2026-09-18，MIT + TypeScript。

这是什么？适合谁？

Claude Code 长会话接近上下文上限时会触发内置 compaction：让 LLM 总结旧对话并丢弃原文。这个摘要是有损的——一个文件路径、一条关键报错、一个你早前定下的约束没了，后面的工作就可能跑偏。fast-jev-compaction 的做法完全不同：不总结，只删除。它让 Jev 模型看着整个对话给每个 tool call / tool result 打分（一次快速请求完成），过时的条目删除或截断，保留的内容逐字不动、顺序不乱。

工作原理（README 核验）：

1. 每个 tool_use 通过 tool_use_id 与对应 tool_result 配对；首条消息和最近 preserveRecentMessages 条消息里的调用被固定（pinned）永不触碰。
2. 发给 Jev 的状态是完整对话（旧→新），tool result 替换为短注（ok, 4213 chars (omitted)），tool 输入与文本全部保留——不做摘要。
3. 状态按阶段压缩进 maxStateTokens（默认 25k）：tool 输入截到 1000 → 200 → 60 字符；长文本头尾保留；最旧非固定消息逐级折叠成省略注。仍放不下则 compaction 抛错（而不是静默丢内容）。
4. 仓库同时是 npm 包（src/）和 Claude Code 插件（hooks/ + .claude-plugin/），插件用该包替换内置压缩。

适合人群：长会话 Claude Code 重度用户（大重构、跨天任务），曾被「压缩后 Agent 忘了早前的报错/路径/约束」坑过的开发者；想在自有工具链里做无损上下文管理的工程师（npm 库形态）。

不适合谁：短会话用户（很少触发 compaction，无感）；必须严格控制在单一厂商生态内、不想引入额外模型调用的团队；需要「摘要」而非「删除」语义的场景（它明确不做摘要）。

准备工作

1. Claude Code 环境 + 一个 Jev 决策模型的访问方式（README 演示用 TYPESAFE_API_KEY，即 TypeSafe 的 Jev 模型 API）
2. Node.js / npm（既是 npm 库也是插件）
3. 时间预算：安装启用 10 分钟；调 preserveRecentMessages / maxStateTokens 参数半小时内
4. 成本：库 MIT 免费；Jev 打分是一次「快请求」（状态压缩到 25k token 级别），单次压缩成本远低于重跑丢上下文后的返工

核心用法：三步上手

第 1 步：作为 Claude Code 插件安装

按 .claude-plugin/ 目录的插件说明安装启用（Claude Code 插件机制），它会 hook 内置 compaction 流程。

第 2 步：配置模型 key

设置 Jev 模型的 API key（README 演示环境变量 TYPESAFE_API_KEY）。首次触发 compaction 时观察日志：应看到打分请求与逐条删除决策，而不是一段摘要。

第 3 步：验证无损行为

开一个长会话（读多个文件、跑多次命令）触发压缩，检查：文件路径与关键报错仍在上下文中、消息顺序未变、被删的只是过时 tool 调用。可跑 npm test（单测用假 Jev，不联网）确认本地构建。

常见踩坑

1. 症状：compaction 抛错「state 放不下」。 根因：会话里有大量超长 tool 输出，压到最低阶段仍超 maxStateTokens。解决：调大 maxStateTokens（默认 25k），或减少单次会话中巨型输出的产生量；这是官方设计的「宁可失败也不静默丢内容」保护。
2. 症状：删除后丢了还需要的调用。 根因：Jev 判定「过时」但该调用实际后文要用。解决：调大 preserveRecentMessages（近区固定不删）；关键约束尽量写进用户消息文本——文本永不被删。
3. 症状：插件没生效、仍是内置摘要。 根因：插件 hook 未正确安装或版本不匹配。解决：跑 npm run validate:plugin 验证插件结构；确认 Claude Code 版本支持该 hook 机制。
4. 症状：打分请求变慢或失败。 根因：Jev API 延迟/配额问题。解决：这是单次快请求（状态已压缩到 25k 级），正常应很快；持续失败先查 key 与配额，必要时回退内置压缩排查。
5. 症状：单测想跑但怕烧 API。 根因：以为测试需要真实模型。解决：npm test 使用假 Jev，从不联网；只有 npm run demo 是真实网络检查。

常见问题 FAQ

Q1: 它和 Claude Code 内置 compaction 的本质区别是什么？

A: 内置是「摘要替换原文」（有损、不可控）；本库是「评分删除」（保留内容逐字不动、顺序不变，只删判定过时的 tool 条目）。摘要里消失的路径/报错/约束在这里不会消失。

Q2: Jev 是什么？为什么不用别的模型？

A: Jev 是一个轻量决策模型，适合「看全局、给每条打分」这类一次快请求的判断任务；项目即为该决策模式设计（tool 输入截断、状态分阶段压缩等都是为单次快请求优化）。

Q3: 用户和助手的文本会被改吗？

A: 不会。README 明确：用户与助手文本逐字保留、顺序不变；只有 tool call / tool result 会被删除或截断，且首条消息与最近 preserveRecentMessages 条消息固定不动。

Q4: 能在 Claude Code 之外用吗？

A: 能。仓库同时是 npm 包（src/），可集成进任何需要上下文压缩的自有工具链；Claude Code 插件（hooks/）只是它的一个封装形态。

Q5: token 成本怎么算？

A: 压缩时发一次 Jev 请求，状态控制在 maxStateTokens（默认 25k）内；相比「压缩丢信息 → 后续返工重读文件重跑命令」的隐性成本，通常净省。

参考链接

• 官方仓库 tamaratran/fast-jev-compaction
• npm 包
• GitHub Releases

本文章基于公开资料整理，AI 辅助生成，独立实测与数据核验日期 2026-10-01（GitHub API 实时抓取 stars/fork/push/license；README 全文核验；未在本机做插件安装实测）。