内容
# 令牌优化器
<!-- mcp-name: io.github.omkar9854/token_optimizer -->
[](https://github.com/omkar9854/token_optimizer/actions/workflows/ci.yml)
[](https://pypi.org/project/slimctx/)
[](https://registry.modelcontextprotocol.io/?search=token_optimizer)
[](LICENSE)
[](pyproject.toml)
[](pyproject.toml)
**零依赖、完全可逆的上下文压缩，用于AI代理。**
令牌优化器压缩您的代理读取的内容 - 工具输出、日志、JSON、源文件、文本 - 在它们到达LLM之前。相同的答案，少量的令牌。纯Python标准库：无ML模型，无下载，无网络调用，始终如此。可审计的端到端压缩，约1,600行代码。
<p align="center">
<img src="demo.gif" alt="令牌优化器演示：61,700令牌压缩为298，29毫秒内完成，FATAL行保留，字节精确检索" width="820">
<br><sub><code>python3 benchmarks/demo.py</code> 的实时输出 — 自己运行它，没有任何预设。</sub>
</p>
```python
from slimctx import Pipeline, Config
pipe = Pipeline(Config(target_tokens=32_000))
result = pipe.compress(messages) # OpenAI/Anthropic-style 字典
print(result.savings_ratio) # 例如 0.82
original = pipe.retrieve("a1b2c3d4...") # 字节精确的原始内容，任何时候
```
## 结果（基于真实代理流量的合成工作负载）
| 工作负载 | 之前 | 之后 | 节省 | 保留的关键事实 |
|----------------------------|-------:|-------:|--------:|:--------------:|
| 代码搜索（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` 重现结果。
## 工作原理
```
消息 ──► 内容路由器 ──► 以下之一：
├─ JSON : 无损表格化（重复键 → 表头，常量列 → 图例），然后仅在仍超出预算时进行相关性排名的行选择
├─ 日志 : Drain-style 模板挖掘 — 重复行折叠为 `pattern [x1432]`；错误原样
├─ 代码 : 抽象语法树骨架 — 签名 + 文档字符串保留，正文省略（除非与查询相关）
└─ 文本 : 提取句子选择（BM25 + 显著性 + 位置），原样，绝不改述
```
### 四大保证
1. **普遍可逆性。** 在任何有损转换之前，原始内容进入内容寻址存储（内存 / SQLite / 自带加密），输出携带 `[slimctx-ref <hash> ...]` 标记。模型或您始终可以取回字节精确的原始内容。
2. **错误从不被丢弃。** 每个压缩器都固定错误/警告内容：日志错误原样通过，JSON中显著的行被保留，显著的句子优先于填充内容。
3. **确定性输出。** 相同的输入 → 字节相同的输出，跨运行和进程。压缩的前缀保持稳定，因此提供商的提示缓存（Anthropic/OpenAI）继续生效。
4. **净收益或无操作。** 如果转换节省的令牌不足以支付其标记，则原始内容保持不变。活动区域（系统提示 + 最后N条消息）永远不会被修改。
## 为什么不使用Headroom？
[Headroom](https://github.com/headroomlabs-ai/headroom) 是该领域的成熟项目，目前功能更丰富（提供商代理与SSE流式传输、代理包装、跨代理内存、ML压缩模型）。令牌优化器采取了一套不同的权衡，针对锁定/客户端部署进行了优化：
| | Headroom | 令牌优化器 |
|---|---|---|
| 可逆性 | JSON仅限（CCR）；丢弃的文本无法恢复 | **每个**有损转换 |
| 日志处理 | 通用文本评分 | **模板挖掘** (`[x1432]` 折叠) |
| 代码处理 | 抽象语法树骨架 | 抽象语法树骨架 **+ 查询相关的正文保留** |
| 依赖项 | Rust核心，ONNX运行时，261MB HF模型 | **仅限标准库** |
| 网络出口 | 首次运行时HuggingFace拉取 | **从不，从不** |
| 存储加密 | 无（明文SQLite） | **加密钩子**（自带加密） |
| 确定性 | 缓存对齐组件 | **通过构造**（纯函数 + 记忆化） |
| 审计表面 | ~10s的KLOC跨3种语言 | **~1,200行Python代码** |
如果您需要代理/包装生态系统，请使用Headroom。如果您需要可以在下午阅读、空气隔离并为客户端环境认证的东西，请使用令牌优化器。
## 安装 / 测试
```bash
pip install slimctx # 从PyPI — 或将slimctx/目录作为依赖
python -m pytest tests/ -q # 26个测试：不变式，而非示例
python3 benchmarks/bench.py # 重现上述结果
```
## 集成草图
**作为库（任何框架）：** 在调用提供商SDK之前调用 `pipe.compress(messages)`；将 `pipe.retrieve` 暴露为名为 `retrieve` 的工具，以便模型可以拉取原始内容。
**作为MCP服务器（GitHub Copilot，Claude Code，Cursor，...）：** 内置，仅限标准库：
```bash
python3 -m slimctx.mcp_server --db ~/.slimctx/store.db
```
参见 [USAGE.md](USAGE.md) 了解 GitHub Copilot (`.vscode/mcp.json`) 设置和安全部署检查清单。
**加密存储：**
```python
from cryptography.fernet import Fernet # 可选，您选择
f = Fernet(key)
store = SqliteStore("ccr.db", cipher=(f.encrypt, f.decrypt))
pipe = Pipeline(store=store)
```
## 许可证
Apache-2.0。原始实现 — 没有从Headroom派生的代码。
