tamaratran/fast-jev-compaction
已整理这个项目用于在 Claude Code 压缩会话上下文时,尽量删除不再需要的工具调用和结果,而不是把历史内容改写成摘要。它适合希望减少上下文占用、同时保留原始对话和关键工具输出的 Claude Code 用户或需要在代码中处理会话压缩的开发者。
项目简介
这个项目用于在 Claude Code 压缩会话上下文时,尽量删除不再需要的工具调用和结果,而不是把历史内容改写成摘要。它适合希望减少上下文占用、同时保留原始对话和关键工具输出的 Claude Code 用户或需要在代码中处理会话压缩的开发者。
官方仓库资料
- 主要语言
- TypeScript
- 许可证
- MIT
- 默认分支
- main
- Stars
- 6461
- Forks
- 370
- Open Issues
- 75
- 仓库状态
- 正常运行
- 派生仓库
- 非 Fork
- 数据采样
- 2026/9/23 19:04:11
- 资料抓取
- 2026/9/23 19:04:11
- 首次收录
- 2026/9/23 19:04:11
Topics:仓库未提供
AI 整理 · 基于已抓取的官方资料
核心功能
- 替代 Claude Code 内置的压缩摘要流程,用 Jev 判断旧的工具调用和结果是否仍然需要保留。
- 只处理 tool_use 和 tool_result;用户与助手的文本内容在输出中保持原文和顺序。
- 将每个工具调用与对应结果按 tool_use_id 配对,避免出现没有调用的结果。
- 支持保留最近若干条消息和第一条消息,避免压缩关键上下文。
- 对工具调用和工具结果分别提问并评分,根据阈值决定保留完整结果、仅保留调用并截断结果,或删除调用与结果。
- 当状态或请求过大时,会分阶段压缩发送给 Jev 的状态,包括截断工具输入、折叠旧消息、简化旧工具调用等。
- 支持并发拆分请求,以适配请求 token 上限。
- 导出 compactMessages、compact、reductionRatio 以及 collectToolCalls、fitState、batchCalls、decideCall、applyDecisions 等构建模块。
- 支持自定义 JevAsker,也提供 buildJevRequest 和 parseJevResponse 用于自带传输层。
- Claude Code 插件模式下可接管 /compact 和自动压缩;出错或压缩不足时回退到 Claude Code 内置摘要。
适用场景
- 在 Claude Code 中替换 /compact 的内置摘要,保留原始消息并删除过时的工具调用结果。
- 在较长的编码会话中减少上下文占用,同时避免摘要丢失文件路径、错误信息、约束或命令等细节。
- 作为 npm 库对 Claude Code 会话 transcript 进行工具调用级别的压缩。
- 接入自定义 Jev 传输层,对消息历史进行保留或删除决策。
- 在自动压缩场景中尝试用 Jev 裁剪历史,并在失败或收益不足时回退到内置摘要。
使用方式
install_library: - npm install fast-jev-compaction
- export TYPESAFE_API_KEY=... library_example: import { compactMessages, reductionRatio, type Message } from 'fast-jev-compaction';
const result = await compactMessages(transcript, { preserveRecentMessages: 4 }); console.log(result.messages, result.decisions, result.stats); if (reductionRatio(result) < 0.25) { // keep the original transcript, or summarize instead } api_key: apiKey 默认读取 process.env.TYPESAFE_API_KEY。README 明确提示不要提交密钥,也不要把密钥放进源文件。 claude_code_plugin_install: - 在 Claude Code 运行环境中启用函数 hook,例如在 ~/.claude/settings.json 中设置 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1,并设置 TYPESAFE_API_KEY。
- claude plugin marketplace add tamaratran/fast-jev-compaction
- claude plugin install fast-jev-compaction@fast-jev-compaction
- 重启 Claude Code 或运行 /reload-plugins。 local_plugin_run: CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 claude --plugin-dir . development_commands: - npm install
- npm run typecheck
- npm test
- npm run build
- npm run validate:plugin
- TYPESAFE_API_KEY="$(cat ~/.typesafe_key)" npm run demo demo: README 提到 demo/JevDemo 是一个 macOS SwiftUI 动画演示应用,不调用 API,用于展示压缩流程;可运行 demo/JevDemo/build.sh 构建并启动。
技术特点
- 仓库语言为 TypeScript。
- 项目既包含 npm 包部分,也包含 Claude Code 插件部分。
- Message 是 Claude Code SessionMessage 的一个子集,因此 session transcript 可以直接传入。
- 默认模型为 jev-latest。
- 默认接口地址为 https://api.typesafe.ai/v1/systemone。
- 默认 preserveRecentMessages 为 6,第一条消息始终保留。
- 默认 keepThreshold 为 0.5。
- 默认 maxStateTokens 为 25000。
- 默认 maxRequestTokens 为 30000。
- 默认 truncateHeadChars 为 300。
- 默认 goal 为最近 3 个用户提示。
- 状态中会包含到目前为止的完整对话顺序,但工具结果会被替换为简短说明;工具输入和文本会包含在状态中。
- 工具调用在第一条消息或最新 preserveRecentMessages 条消息中时会被固定保留。
- Jev 对每个非固定调用提出两个问题:调用本身是否仍然重要,以及结果是否需要逐字保留。
- 结果保留规则为:结果分数达到阈值时保留调用和结果;否则调用分数达到阈值时保留调用并截断结果;否则删除调用和结果。
- Jev 失败、答案格式错误、缺少 key,或历史无法放入限制时会抛错;调用方或 Claude Code hook 决定如何回退。
- result.stats 会报告压缩前后的消息和字符数量、按原因统计的决策数量、状态估算 token 数、所需 fitting 阶段和请求数量。
- 单元测试使用假的 Jev,不会访问 TypeSafe;demo 是实时网络检查。
限制与边界
- 只有工具调用和工具结果会作为候选项;输出中的文本消息不会被删除或缩短。
- 发送给 Jev 的状态中,文本可能会被 abridge,但输出中的文本保持不变。
- token 大小来自字符计数估算,不使用 tokenizer。
- 概率不是结果可以安全删除的证明;助手仍可能需要重新运行工具。
- 每个请求都会重复发送完整状态,因此接近状态上限的历史可能需要为少量问题发送一个请求。
- 如果 Jev 失败、响应格式异常、缺少 key,或历史无法适配限制,会抛出错误。
- Claude Code 函数 hook 是早期访问功能,README 标注需要 Claude Code 2.1.274+ 并启用 CLAUDE_CODE_ENABLE_FUNCTION_HOOKS。
README
README 介绍了 fast-jev-compaction 的目标:避免用摘要改写旧上下文,而是让 Jev 判断工具调用和工具结果是否仍需保留,从而删除或截断不必要的工具信息,保留的内容则保持逐字不变。文档说明了配对工具调用、构造 Jev 状态、按 token 限制分阶段适配、批量提问、按阈值应用决策和重建消息列表的流程;同时提供了 npm 安装与代码调用示例、可配置选项、限制说明、Claude Code 插件安装方式、开发命令以及 macOS 动画演示信息。
关联 Wiki 词条
暂无已建立的词条关联。