blog.dopana

返回

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号口袋”。

git, cargo, pytest, docker...未知有, 还在 context无是否智能体调工具: git status, cargotest, cat 文件sqz PreToolUse hook有专用 formatter?保留失败, 断言, file:line. 去噪声通用管线: 合并重复, 压缩表格见过? 查 SHA-256返回 13 token §ref:HASH§堆栈 / secret / migration?安全模式: 0% 压缩, 直通压缩输出给模型

压什么, 不压什么#

压缩:

  • 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):

内容前后节省
重复日志行1486258%
大 JSON 数组25914245%
JSON API 响应645317%
Git diff615412%
文章/docs1241212%
堆栈(安全模式)82820%

会话级加 dedup(sqz 真正发力):

重复无 sqz有 sqz节省
不变 git status 重跑1551392%
200 行文件重读 41-80 行3051695%
同样 cargo test3031396%

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 分钟安装#

install.sh
# 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-mcp
bash

然后:

init
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, 不上传:

discover
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 速查#

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                   # 压缩最差的命令
bash

dedup 逃生(个别模型如 GLM 5.1 解析 §ref§ 会循环):

dedup-off
echo "..." | sqz compress --no-cache
export SQZ_NO_DEDUP=1          # 全局关
export SQZ_REF_TTL_SECS=300    # 缩短 ref 窗口 (默认 1800, 0=关)
bash

压缩原理: 6 级#

  1. 单命令 formatter — cargo test 只留失败用例+断言+file:line。git status 变精简摘要。未知命令走通用管线——无一遗漏。
  2. 表格压缩 — ps aux 等对齐空白压成双空格分隔。严格检测: 缩进行、代码、YAML、JSON 永不命中。
  3. 结构摘要 — 代码→import+签名+调用图(约减 70%)。模型看架构, 不看实现噪声。
  4. dedup 缓存 — SHA-256, SQLite 持久。字节相同→13 token §ref:HASH§。已知文件行范围→§ref:HASH:L40-80§。小改后重读→仅差异行。ref 存活 30 分钟(SQZ_REF_TTL_SECS), compaction 重置。
  5. JSON 管线 — 去 null→删 debug→flatten→合并数组→TOON(无损紧凑格式)。
  6. 安全模式 — 熵分析识别堆栈、secret、migration→0% 压缩直通。

延迟亚毫秒(100KB 内 p99 < 5ms), SQLite 查询约 0.1ms。相对 LLM 推理可忽略。

支持工具#

工具集成安装
Claude Code / Cursor / Windsurf / ClinePreToolUse hook (透明)sqz init
Gemini CLIBeforeTool hooksqz init
KiroSteering + MCPsqz init
OpenCodeTypeScript pluginsqz init
Codex / ZedAGENTS.md + MCPsqz init
Copilot CLIpreToolUse hooksqz init
Copilot coding agent (CI)仓库 hook, 云端自举sqz init --ci + commit
任意 MCP serversqz-mcp proxy -- <server>压结果+tools/list
VS Code / JetBrains / Chrome / Firefox扩展应用市场

MCP proxy 示例, 包任意 stdio server:

mcp.json
{
  "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 净胜门槛跳过不划算压缩。

实战: 接入会话#

session
# 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 3f9a1c05e2d84b17
bash

direnv 按项目隔离 DB:

.envrc
export SQZ_DB_PATH="$PWD/.sqz/sessions.db"
bash

全链路遵守: shell hook、stats/gain/expand、MCP server(MCP 配置 env)。父目录自动建 mode 0700。

配置#

~/.sqz/presets/default.toml
[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 = 200000
toml

隐私#

零遥测、无崩溃上报、完全离线、可气隙运行。统计在 ~/.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。

参考资料#