token_optimizer

slimctx — AI Agent 的令牌优化器

零依赖、完全可逆的 AI Agent 上下文压缩工具。

slimctx 会在内容到达大模型之前，压缩 Agent 读取的内容——工具输出、日志、JSON、源文件、散文。答案不变，令牌用量仅为原来的零头。纯 Python 标准库实现：无需 ML 模型、无需下载、永不发起网络调用。全程可审计，代码约 1,600 行。

_{python3 benchmarks/demo.py 的实时输出——你可以亲自运行，没有任何预先布置。}

from slimctx import Pipeline, Config

pipe = Pipeline(Config(target_tokens=32_000))
result = pipe.compress(messages)        # OpenAI/Anthropic-style dicts
print(result.savings_ratio)             # e.g. 0.82

original = pipe.retrieve("a1b2c3d4...")  # byte-exact original, any time

结果（基于真实 Agent 流量建模的合成工作负载）

工作负载	压缩前	压缩后	节省比例	保留的关键信息
代码搜索（100 条结果）	5,557	916	84%	✓
SRE 事件调试	61,699	298	100%	✓
GitHub 问题分诊	12,836	975	92%	✓
代码库探索	5,734	2,760	52%	✓

每次运行还会验证每个预先埋入的“关键线索”（FIXME、OOMKill、异常值）都能在压缩后保留，并确保每种有损转换都能逐字节精确还原。运行 python3 benchmarks/bench.py 即可复现。

工作原理

messages ──► ContentRouter ──► one of:
                ├─ JSON  : lossless tabularization (repeated keys → header,
                │          constant columns → legend), then relevance-ranked
                │          row selection only if still over budget
                ├─ LOG   : Drain-style template mining — repeated lines
                │          collapse to `pattern [x1432]`; errors verbatim
                ├─ CODE  : AST skeleton — signatures + docstrings kept,
                │          bodies elided EXCEPT those relevant to the query
                └─ TEXT  : extractive sentence selection (BM25 + salience
                           + position), verbatim, never paraphrased

四项保证

1. 普遍可逆。 在进行任何有损转换之前，原始内容都会存入内容寻址存储（内存 / SQLite / 自带加密方案），输出中则会带有 [slimctx-ref <hash> ...] 标记。模型或你自己随时都能取回逐字节精确的原始内容。
2. 绝不丢弃错误。 每种压缩器都会保留错误和警告内容：日志错误原样通过，重要的 JSON 行会被保留，重要句子的优先级高于填充内容。
3. 输出具有确定性。 相同输入 → 不同运行和进程都会得到逐字节相同的输出。压缩后的前缀保持稳定，因此提供商的提示词缓存（Anthropic/OpenAI）可以持续命中。
4. 有收益才压缩，否则不处理。 如果某种转换节省的令牌不足以抵消其标记开销，就会原样保留原内容。实时区域（系统提示词 + 最近 N 条消息）完全不会被修改。

为什么不直接使用 Headroom？

Headroom 是该领域成熟的项目，目前功能也更丰富（支持 SSE 流式传输的提供商代理、Agent 封装、跨 Agent 记忆、ML 压缩模型）。slimctx 的取舍有所不同，面向受限环境／客户现场部署：

	Headroom	slimctx
可逆性	仅支持 JSON（CCR）；丢弃的文本无法恢复	每一种有损转换
日志处理	通用文本评分	模板挖掘（折叠 [x1432]）
代码处理	AST 骨架	AST 骨架 + 保留与查询相关的代码体
依赖项	Rust 核心、ONNX 运行时、261MB HF 模型	仅使用标准库
网络出站	首次运行时从 HuggingFace 拉取	始终没有
存储加密	无（SQLite 明文存储）	加密钩子（自行提供）
确定性	cache-aligner 组件	由设计保证（纯函数 + 记忆化）
审计范围	3 种语言，约 10K 行代码	约 1,200 行 Python

如果你需要代理／封装生态，请使用 Headroom。如果你需要一个能在一下午读完、可在气隙环境中运行，并能通过客户环境认证的项目，请使用 slimctx。

安装／测试

pip install slimctx           # from PyPI — or vendor the slimctx/ directory
python -m pytest tests/ -q    # 26 tests: invariants, not examples
python3 benchmarks/bench.py   # reproduce the numbers above

集成示例

作为库使用（任意框架）： 在调用提供商 SDK 前直接调用 pipe.compress(messages)；将 pipe.retrieve 作为名为 retrieve 的工具公开，以便模型获取原始内容。

作为 MCP 服务使用（GitHub Copilot、Claude Code、Cursor，……）： 内置支持，仅使用标准库：

python3 -m slimctx.mcp_server --db ~/.slimctx/store.db

请参阅 USAGE.md，了解 GitHub Copilot（.vscode/mcp.json）配置和安全部署检查清单。

加密存储：

from cryptography.fernet import Fernet          # optional, your choice
f = Fernet(key)
store = SqliteStore("ccr.db", cipher=(f.encrypt, f.decrypt))
pipe = Pipeline(store=store)

许可证

Apache-2.0。原创实现——未使用任何源自 Headroom 的代码。