W
AI-Wiki
← 开源项目

tamaratran/fast-jev-compaction

已整理
https://github.com/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 词条

暂无已建立的词条关联。