上下文压缩
不要让你的AI代理淹没在shell输出中。 在工具输出到达上下文窗口之前对其进行压缩——通过MCP服务器、插入式CLI或两者兼而有之。
 ](https://www.npmjs.com/package/context-compress) ](https://nodejs.org)   
快速入门 · 压缩模式 · 与RTK · 运作原理 · 配置 · 命令行界面 · 更新日志
93%
代币减少
激进模式
+10.5页
通过RTK
相同的命令
4种模式
包括LLM评审
自动•激进•平衡•保守
8个MCP工具
+独立CLI
RTK兼容包装
______________________________________________________________________
快速入门
# 1. Install
npm install -g context-compress
# 2. One-line setup — registers the MCP server, installs the hook,
# enables transparent Bash compression
context-compress setup --auto
# 3. (optional) Pick a mode for the session
export CONTEXT_COMPRESS_MODE=balanced # or: aggressive, conservative, auto就是这样。重新启动Claude Code，shell输出现在在进入上下文之前被压缩。
Quickstart for AI agents — paste this prompt and your agent will install it
Install context-compress — an MCP server that compresses tool output for Claude Code.
Raw data stays in sandboxed subprocesses, only concise summaries enter your context window.
Saves ~99% of tokens on large outputs while keeping everything searchable via FTS5.
npm install -g context-compress
context-compress setup --auto
context-compress doctor
More info: https://github.com/Open330/context-compress______________________________________________________________________
为什么？
进入Claude Code上下文窗口的工具输出的每个字节 降低质量和速度. 一个 git log 或 npm test 可以将50KB+的数据转储到上下文中——大约12000个令牌已经消失了。
上下文压缩 拦截这些工具，在沙箱中处理输出，只返回重要的内容：
Before: git log --oneline -100 → 8.2KB into context
After: execute("git log ...") → 0.3KB summary + full data searchable in FTS5它以两种自由组合的模式工作：
- MCP服务器 --使用8个工具注册为Claude Code MCP服务器(
execute,search,batch_execute,fetch_and_index,index,execute_file,stats,discover).当输出较大时，代理会直接调用它们。 - 独立CLI —
context-compress wrap ""运行任何shell命令，并通过相同的压缩管道传输输出。请光临 实时动态测量 和朋友。PreToolUse挂钩可以布线Bash在以下情况下透明地调用它CONTEXT_COMPRESS_FILTER_BASH=1.
基于 上下文模式 Mert Koseoğlu——用TypeScript重写，具有安全强化、架构改进和更好的DX。
______________________________________________________________________
入门指南
安装
npm install -g context-compress单线设置
context-compress setup --auto写 ~/.claude/settings.json 为您：注册MCP服务器，安装PreToolUse钩子，启用透明的Bash压缩。Idempotent——使用相同的路径重新运行不会产生任何变化。保留任何无关的用户设置。
手动设置
claude mcp add context-compress -- node $(which context-compress)或添加到您的项目 .mcp.json:
{
"mcpServers": {
"context-compress": {
"command": "node",
"args": ["/path/to/context-compress/dist/index.js"]
}
}
}验证
context-compress doctor______________________________________________________________________
运作原理
┌─────────────────────────────────────────────────────────┐
│ Claude Code │
│ │
│ "Run tests" ──→ PreToolUse Hook intercepts │
│ │ │
│ ▼ │
│ ┌──────────────────┐ │
│ │ context-compress │ │
│ │ MCP Server │ │
│ └────────┬─────────┘ │
│ │ │
│ ┌───────────┼───────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Executor │ │ Store │ │ Stats │ │
│ │ (11 lang)│ │ (FTS5) │ │ Tracker │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │ │ │
│ ▼ ▼ │
│ Raw output Indexed & Only summary │
│ stays here searchable enters context │
└─────────────────────────────────────────────────────────┘8个MCP工具
| 工具 | 它做什么 |
|---|---|
execute | 用11种语言运行代码。只有stdout进入上下文。 |
execute_file | 通过以下方式处理文件 FILE_CONTENT 变量——文件从不进入上下文。 |
index | 将标记/文本分块到FTS5知识库中进行搜索。 |
search | BM25搜索带有波特词干→ 三元组→ 模糊回退。 |
fetch_and_index | 获取URL→ HTML标记→ 自动索引。仅在上下文中预览。 |
batch_execute | 在一次通话中运行N个命令+搜索。替换30多个工具调用。 |
stats | 会话+累积统计：节省的字节数、避免的令牌、节省率。 |
discover | 列出索引源、可搜索的顶级术语，并建议下一步行动。 |
支持的语言
javascript · typescript · python · shell · ruby · go · rust · php · perl · r · elixir
自动检测到Bun，JS/TS执行速度提高3-5倍。
______________________________________________________________________
压缩模式
上下文压缩提供了四种压缩模式，以保真度换取紧凑性。通过 --mode 到CLI，设置 CONTEXT_COMPRESS_MODE 在您的环境中，或让默认值(balanced)只是工作。
|模式|策略|使用时| |:--|:--|:--| | conservative |仅ANSI条带--保留有意义内容的每个字节|您需要完全保真度、调试输出、归档日志| | balanced *（默认）* |去除噪音（进度条、弃用警告、提示行）——保留元数据（提交正文、文件日期、完整测试失败）|日常代理工作，可能会重新读取上下文| | aggressive |也删除元数据--git日志→ 洛杉矶一号线→ 名称+大小，找到较低的阈值，grep分组|最大令牌节省；代理人很少需要遗漏的细节| | auto |LLM（无烟煤API或 claude -p)根据输出的500字节样本，为每个命令选择上述之一。缓存24小时的决策|你不想去想它——让模型根据输出进行判断|
# CLI flag (per-call override)
context-compress wrap --mode aggressive "git log -50"
# Env var (set once for the session)
export CONTEXT_COMPRESS_MODE=aggressivePreToolUse挂钩也向前 CONTEXT_COMPRESS_MODE 在包装Bash命令时自动执行，因此代理可以透明地获取您配置的任何模式。
与 实时动态测量
本地复制：
git clone https://github.com/rtk-ai/rtk /tmp/rtk && (cd /tmp/rtk && cargo build --release)
RTK_BIN=/tmp/rtk/target/release/rtk tsx scripts/benchmark-vs-rtk.ts此存储库上的结果（RTK 0.39.0 vs上下文压缩2026.5.0）：
|命令|原始|RTK|CC conservative |CC balanced |CC aggressive |CC auto LLM |:--|--:|--:|--:|--:|--:|--:| | git status |577 B | 241 B（58%）| 577 B（0%）| 375 B（35%）| 187 B（68%） |平衡（35%）| | git log -10 （完整）|21.3 KB |3.2 KB（85%）|21.3KB（0%）|4.6 KB（79%）| 947b（96%） |平衡（79%）| | git log -50 （完整）|36.9 KB |10.1 KB（73%）|36.9KB（0%）|12.3 KB（67%）| 3.2 KB（91%） |平衡（67%）| | git diff --stat |425 B | 424 B（0%）| 425 B（0%| | ls src/ |149 B | 229 B（-54%）| 149 B（0%）| 149 A（0%）| | ls -laR src/ |3.8 KB| 229 B（94%） |3.8 KB（0%）|3.1 KB（19%）|877 B（78%）|攻击性（78%）| | find *.ts |1.0 KB | 589 B（44%）| 1.0 KB（0%）| 183 B（83%） | 183 B（83%） |攻击性（83%）| | npm test |21.8 KB |114 B（99%）|16.7 KB（24%）| 120 B（99%） | 120 B（99%） |平衡（99%）| | 总体 （字节加权）| 85.9 KB |15.0 KB（82.5%）|80.8 KB（6.0%）|21.2 KB（75.4%）| 6.0 KB（93.0%） |19.0 KB（77.9%）|
从这张桌子上可以学到三件事：
balanced它本身就具有竞争力。 默认模式在不删除任何元数据的情况下减少了约75%——代理可以获得完整的提交头、文件权限/日期和完整的测试失败详细信息。仅落后RTK 7pp，同时进行了不同的保真度权衡。aggressive在原始压缩方面取得决定性胜利 --93.0%，比RTK高出10.5个百分点。当您希望最大限度地节省令牌时，选择此选项，代理很少会重新读取删除的详细信息。auto让模型来挑选。 根据命令，LLM的总体判断率为77.9%，介于平衡和攻击之间。有趣的结果是 *什么* 它选择：balanced对于git/test输出（其中提交体和失败细节很重要），aggressive为了ls -laR和find（问题是“那里有什么？”，而不是“给我看一切”），conservative对于压缩毫无意义的微小输出。
攻击模式覆盖的命令面比上表提示的更广——它还处理 df （删除伪文件系统）， du （按大小排名前N）， ps aux （仅PID/%CPU/%MEM/CMD，删除内核线程）， npm ls （条形树绘图字符+ deduped/extraneous 标记），以及 grep/rg （按文件分组，截断长线）。
现在平衡的做法（过于保守）：
ls -l*滴total N,./..条目（通用噪声），但保留perms/dategit log每次提交保留头文件+前3行正文，其余部分替换为[+N lines omitted]find/ls -R一旦输出超过20个条目，则对每个目录进行汇总- 通用数据消除/进度/组以5KB而不是10KB的速度运行
RTK具有单一的固定压缩策略，与上下文压缩相当aggressive.context compress允许代理选择：aggressive当问题是“发生了什么变化”时，balanced当问题是“解释为什么”时。
______________________________________________________________________
代币减少
上下文压缩实现 代币减少99.2% 在典型的12操作编码会话中。
|操作|之前|之后|减少| |:--|--:|--:|--:| |读取捆绑文件（776KB）|194076tok|105tok|99.9%| |剧作家快照（56KB）|14000托|75托|99.5%| |读取CSV/JSON数据（100KB）|25000托|125托|99.5%| |读取源文件（21KB）|5250托|88托|98.3%| |npm安装日志（15KB）|3750tok|50tok|98.7%| |curl API响应（12KB）| 3000 tok | 88 tok | 97.1%| |npm测试（42个测试）|935 tok|45 tok|95.2%| |批处理执行器（5厘米）|6250托|375托|94.0%| |fetch_and_index（45KB页面）|1125托|750托|93.3%| |grep（小产量）| 361托| 361托|0%| | 会话总数 | 267121托克 | 2223托 | 99.2% |
如果没有上下文压缩，12个操作将消耗 20万上下文窗口的133% --完全溢出。使用上下文压缩，相同的操作使用 1.1%，让98.9%的人可以自由地进行实际对话。
数据不会被删除——它在FTS5中被编入索引，可以按需搜索。小输出（\server.ts现在很薄（132行）——它构建deps，构建一个ToolContext，注册8个工具模块，并关闭电线。所有工具处理程序都位于src/tools/，下的所有可重用助手src/util/.
______________________________________________________________________
安全
| 威胁 | 缓解 |
|---|---|
| 凭证泄漏 | passthroughEnvVars 默认为 [] --除非选择加入，否则传递给子进程的环境变量为零 |
| 壳体注射 | execFileSync 整个过程中都有数组参数——没有字符串插值到shell中 |
| SSRF/私有IP获取 | fetch_and_index 块RFC1918、链路本地、环回、IPv4映射IPv6（包括十六进制形式 ::ffff:HHHH:HHHH)，cgnat |
| DNS重新绑定（TOCTU） | resolveAndValidate +URL固定到解析的IP地址 Host 保留标题 |
| 路径遍历 | isWithinProject 用途 realpathSync 击败符号链接逃逸；对于尚未存在的路径，回退到字符串前缀 |
| 钩子自修改 | 钩子是只读的--否 fs.writeFileSync 在 src/hooks/.钩子完整性SHA-256由验证 doctor |
| 任意代码执行 | 否 upgrade 命令--否 git clone 或 npm install 在运行时。安装程序仅写入 ~/.claude/settings.json |
| 无声的失败 | CONTEXT_COMPRESS_DEBUG=1 所有曲面都将块错误捕获到stderr |
| 子进程沙盒 | 操作系统级沙盒未强制执行（根据MCP信任模型的设计）。看 安全.md 对于完全信任模型。 |
______________________________________________________________________
贡献
git clone https://github.com/Open330/context-compress
cd context-compress
npm install
npm run typecheck # Strict TS
npm run lint # Biome
npm test # All tests (unit + integration)
npm run test:unit # Unit tests only
npm run build # Compile + bundle MCP server + CLI
npm run build:hooks # Bundle the PreToolUse hook (with SHA-256)
npm run build:bin # Cross-compile single binaries via Bun (4 targets)重现基准
# Synthetic — fast, reproducible, includes RTK-style commands
tsx scripts/benchmark.ts
# Real-world — runs actual commands in your repo
tsx scripts/benchmark-real.ts # full
tsx scripts/benchmark-real.ts --quick # skip npm test
# Head-to-head with RTK (build it first)
git clone https://github.com/rtk-ai/rtk /tmp/rtk
(cd /tmp/rtk && cargo build --release)
RTK_BIN=/tmp/rtk/target/release/rtk tsx scripts/benchmark-vs-rtk.ts
RTK_BIN=... tsx scripts/benchmark-vs-rtk.ts --auto # also run LLM-judged auto mode
RTK_BIN=... tsx scripts/benchmark-vs-rtk.ts --json # machine-readable______________________________________________________________________
许可证
灵感来自 实时动态测量 用于命令感知过滤策略。LLM判断，上下文压缩基于多模式权衡的相同理念 auto 模式、MCP集成、沙盒执行和可搜索的知识库。