Sqz: AI编程智能体上下文压缩
面向AI智能体的注入前压缩: 平均省24.7% token, 重复内容省92%。Rust, 离线, 零LLM调用。
AI编程智能体不是把 token 烧在推理上,而是烧在 cargo test 输出、git status 刷屏、同一个文件读五遍上。
这正是 sqz ↗ 解决的问题。单个 Rust 二进制,在工具输出进入模型 context 之前压缩。零 LLM 调用、完全离线、sqz expand 字节精确还原。
真实会话数据: 3,003 次压缩、节省 178,442 token、平均降低 24.7%,模型已有输出最高 92-96%。
为什么重要#
每个 agent turn 都会重发历史。1,200 token 的测试日志不是付一次——到 compaction 之前每个 turn 都要付。加上 prompt caching,账更微妙,但方向明确: 噪声输出缩短会话、推高成本、挤掉有用推理。
[!NOTE] token 减少 ≠ 账单 1:1 减少。prompt caching 下重复 context 约打 1 折。
sqz stats --cost对此诚实建模。
ELI5(讲给10岁听): 智能体每次出行都要装行李箱(context window)。现在它把脏衣服全塞进去——全量通过测试、不变的 git status、重复读文件。sqz 是帮你叠好、去重、贴纸条的朋友:“蓝衬衫已在箱内, 见3号口袋”。
压什么, 不压什么#
压缩:
- Shell 输出 — 12 生态 45+ formatter: git、cargo、npm/pnpm/yarn/bun、pytest、ruff、mypy、go test(含
-json流)、docker/podman、kubectl、aws、terraform、gcloud、gradle、maven、xcodebuild、adb logcat、dotnet、gh、grep/rg、tree、curl 等 - JSON — 去 null、删 debug 字段、flatten、合并数组、TOON 编码
- 日志 — 合并重复行(默认
max_repeated_lines = 3) - 测试输出 — Rust、Go、Python、JS、JVM 状态机解析器, 只留失败
绝不碰:
- 源码、堆栈、报错、secret → 安全模式, 0% 压缩
- 你的 prompt 和模型回复 → 归框架管, sqz 不碰
[!TIP] 所有压缩结果都可字节精确恢复:
sqz expand <ref>。
数据#
单命令压缩(cargo test -p sqz-engine benchmarks):
| 内容 | 前 | 后 | 节省 |
|---|---|---|---|
| 重复日志行 | 148 | 62 | 58% |
| 大 JSON 数组 | 259 | 142 | 45% |
| JSON API 响应 | 64 | 53 | 17% |
| Git diff | 61 | 54 | 12% |
| 文章/docs | 124 | 121 | 2% |
| 堆栈(安全模式) | 82 | 82 | 0% |
会话级加 dedup(sqz 真正发力):
| 重复 | 无 sqz | 有 sqz | 节省 |
|---|---|---|---|
不变 git status 重跑 | 155 | 13 | 92% |
| 200 行文件重读 41-80 行 | 305 | 16 | 95% |
同样 cargo test | 303 | 13 | 96% |
README 示例:
cat auth.py (500 行): 4,000 token 4,000 token (源码全文保留)
cargo test (1 失败): 1,200 token 120 token (失败+断言+file:line)
sed -n '40,80p' auth.py: 330 token 18 token (§ref:…:L40-80§)
git status 不变: 160 token 13 token (§ref:…§)
───────────────────────────────────── ─────────────
合计: 5,690 token 4,151 token (省 27%, 零丢失)text作者提醒的 нюанс: 整文件重读比传说少(某用户 92 会话 542 读中仅 1 次)。真实重复是不变命令输出、行范围、小改后重读——每种有专属引用类型。
2 分钟安装#
# macOS / Linux (预编译, 无需编译器)
curl -fsSL https://raw.githubusercontent.com/ojuschugh1/sqz/main/install.sh | sh
# npm 全平台
npm install -g sqz-cli
# Homebrew
brew tap ojuschugh1/sqz
brew install sqz
# 源码
cargo install sqz-cli sqz-mcpbash然后:
sqz init --global # 全机项目 (~/.claude/settings.json 合并)
# 或
sqz init # 仅当前项目
sqz init --only opencode,codex
sqz init --skip cursor,windsurf
sqz doctor # 校验: 二进制, DB, hook, 最近压缩bash[!WARNING]
sqz init经 JSON 解析重写opencode.jsonc会丢注释。想保留注释请手动:sqz print-opencode-plugin > ~/.config/opencode/plugins/sqz.ts, 再手加sqz-mcp条目。
先试后装: 反事实重放#
已用 Claude Code 或 Kiro? 本地重放已有 transcript, 不上传:
sqz discover --replay
# Sessions replayed: 24
# Tool outputs: 43
# Tokens (original): 116,598 → compressed: 92,560
# Estimated avoidable: 24,038 tokens (20.6%)bash每会话用一次性空白缓存重放, 跨会话 dedup 绝不虚增数字。
CLI 速查#
sqz compress "text" # 或 stdin 管道
sqz compress --no-cache # 跳过 dedup, 全量输出
sqz expand a1b2c3d4 # 前缀匹配, 或粘完整 §ref:…§
sqz gain # 日粒度柱状图, 近 7 天
sqz gain --days 30 --project . # 30 天, 当前项目
sqz stats # 累计 + regret 信号
sqz stats --cost # prompt-cached 计费下 $
sqz stats --breakdown # 各命令 token 消耗排行
sqz recall "connection refused" # 全文 FTS5 检索压缩过的一切
sqz resume # compaction 后回注 context
sqz compact # 主动驱逐: --strategy keep_recent|keep_relevant|keep_errors
sqz vizit # htop 式实时面板
sqz discover # 压缩最差的命令bashdedup 逃生(个别模型如 GLM 5.1 解析 §ref§ 会循环):
echo "..." | sqz compress --no-cache
export SQZ_NO_DEDUP=1 # 全局关
export SQZ_REF_TTL_SECS=300 # 缩短 ref 窗口 (默认 1800, 0=关)bash压缩原理: 6 级#
- 单命令 formatter —
cargo test只留失败用例+断言+file:line。git status变精简摘要。未知命令走通用管线——无一遗漏。 - 表格压缩 —
ps aux等对齐空白压成双空格分隔。严格检测: 缩进行、代码、YAML、JSON 永不命中。 - 结构摘要 — 代码→import+签名+调用图(约减 70%)。模型看架构, 不看实现噪声。
- dedup 缓存 — SHA-256, SQLite 持久。字节相同→13 token
§ref:HASH§。已知文件行范围→§ref:HASH:L40-80§。小改后重读→仅差异行。ref 存活 30 分钟(SQZ_REF_TTL_SECS), compaction 重置。 - JSON 管线 — 去 null→删 debug→flatten→合并数组→TOON(无损紧凑格式)。
- 安全模式 — 熵分析识别堆栈、secret、migration→0% 压缩直通。
延迟亚毫秒(100KB 内 p99 < 5ms), SQLite 查询约 0.1ms。相对 LLM 推理可忽略。
支持工具#
| 工具 | 集成 | 安装 |
|---|---|---|
| Claude Code / Cursor / Windsurf / Cline | PreToolUse hook (透明) | sqz init |
| Gemini CLI | BeforeTool hook | sqz init |
| Kiro | Steering + MCP | sqz init |
| OpenCode | TypeScript plugin | sqz init |
| Codex / Zed | AGENTS.md + MCP | sqz init |
| Copilot CLI | preToolUse hook | sqz init |
| Copilot coding agent (CI) | 仓库 hook, 云端自举 | sqz init --ci + commit |
| 任意 MCP server | sqz-mcp proxy -- <server> | 压结果+tools/list |
| VS Code / JetBrains / Chrome / Firefox | 扩展 | 应用市场 |
MCP proxy 示例, 包任意 stdio server:
{
"mcpServers": {
"github": {
"command": "sqz-mcp",
"args": ["proxy", "--", "npx", "-y", "@modelcontextprotocol/server-github"]
}
}
}json--lazy-tools(一句简介+sqz_tool_help 按需取全文——有的 server 光 tools/list 就烧 10-40k token)、--no-desc、--no-cache。proxy 注入 sqz_expand 供 agent 还原原文。
诚实记账: cost 与 regret#
别家常忽略的两信号:
sqz stats --cost— prompt-cached 计费下 $(写×1.25 一次, 读×0.10 每轮)。假设全打印,--price-in等可覆盖。保守设计。- regret 信号 — 快速重跑(2 分钟内字节相同重现=白重复)与 ref expand(
§ref§被还原=模型要全文)。某命令常上榜说明 formatter 待修——去提 issue。
设计规避 arXiv:2607.12161 ↗ 实测坑: 确定性+查询无关(不使 provider prompt cache 失效)、只碰新工具输出(历史不重写)、管道/重定向不拦截、16 token 净胜门槛跳过不划算压缩。
实战: 接入会话#
# 1. 看本可省多少
sqz discover --replay
# 2. 全局安装
sqz init --global
sqz doctor
# 3. 正常干活, 再量
sqz gain
sqz stats --breakdown
# 4. recall 比重跑快
sqz recall "Failed to connect"
sqz expand 3f9a1c05e2d84b17bashdirenv 按项目隔离 DB:
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"bash全链路遵守: shell hook、stats/gain/expand、MCP server(MCP 配置 env)。父目录自动建 mode 0700。
配置#
[preset]
name = "default"
version = "1.0"
[compression.condense]
enabled = true
max_repeated_lines = 3
[compression.strip_nulls]
enabled = true
[budget]
warning_threshold = 0.70
default_window_size = 200000toml隐私#
零遥测、无崩溃上报、完全离线、可气隙运行。统计在 ~/.sqz/sessions.db(SQLite FTS5)。不出本机。
何时不用 sqz#
- 审计要逐字日志——用
--no-cache或安全通道, 事后expand。 - 模型解析不了
§ref§——关 dedup(SQZ_NO_DEDUP=1)。 - 微小输出低于净胜门槛——sqz 已自动跳过(16 token 阈值)。
结论#
sqz 站在正确边界: 工具执行时。不是改写 prompt, 不是模型专属适配。一次 sqz init 覆盖全框架, Rust 确定性核心 p99 5ms 内, dedup 把重复变 13 token 引用。
先跑 sqz discover --replay——自己 transcript 显示 20%+ 可省, 再装 hook。