深入sqz压缩管线原理：按命令格式化器、TOON编码、日志折叠与安全模式全解析

sqz 是一个专为 AI 编程代理（Claude Code、Cursor、Codex、Kiro、Zed 及任意 MCP 客户端）设计的上下文压缩工具：它在工具输出进入模型上下文之前完成压缩，把重复内容折叠成 13-token 的引用，全程 Rust 实现、确定性执行、零 LLM 调用。本文带你深入 sqz 压缩管线的四大核心机制——按命令格式化器、TOON 编码、日志折叠与安全模式——看看它如何在平均节省 24.7% token 的同时，保证 100% 的关键事实不丢失。

一、压缩管线整体流程：一次输出要过几道关？

每条工具输出（命令结果、文件读取、JSON 响应）进入模型前，都会流经 sqz 的统一管线。你可以把它想象成一条"流水线安检"：

1. 按命令格式化器：已知命令（git、cargo、npm、pytest、docker……）优先走专用格式化器
2. JSON 管线：去 null、扁平化嵌套、折叠数组、TOON 编码
3. 日志折叠：重复行压缩、表格对齐压缩、diff 上下文折叠
4. 安全模式路由：栈追踪、密钥、数据库迁移等高风险内容直接原样放行
5. 去重缓存：模型已经见过的内容，用 §ref:HASH§ 引用替代

核心代码在 pipeline.rs，各压缩阶段按优先级排序执行（stages.rs）。一个重要的设计细节：源码文件走的是无损路径（compress_lossless）——agent cat 一个文件通常接下来就要编辑它，所以管线检测出代码后会跳过所有"丢行"阶段，省 token 靠的是后续重复读取时的去重引用，而不是截断。

二、按命令格式化器：为每类命令"定制"摘要

sqz 的第一个优化思路很朴素：不同命令的输出结构是固定的，那就为每类命令写一个专门的摘要器。调度逻辑在 cmd_formatters/mod.rs，它按命令名分发到对应的格式化器：

命令族	格式化策略	实测压缩率
npm install（200 个包）	只保留摘要行	99%
cargo test（15 通过 / 3 套件）	跳过通过项，只留失败	95%
cargo build（成功，30 crates）	跳过 Compiling 噪音	90%
terraform plan	丢弃刷新与进度行	63%
git status	分支行 + 紧凑变更列表	45%
grep（100 条匹配）	ripgrep 头部布局，路径只出现一次	32%

覆盖的命令包括 git、cargo、npm/pnpm/yarn/bun、tsc、eslint、pytest、ruff、mypy、go、gradle、maven、xcodebuild、adb logcat、dotnet、rspec、docker、kubectl、terraform、grep/rg、tree、curl 等。其他命令则落到通用管线处理。

这套机制还有两道"保险丝"，值得新手注意：

• 错误行守卫：如果格式化器把任何报错行丢了，这个格式化结果直接作废，退回原样输出。Build FAILED. 这类复述行可以省，但真正的 error: xxx 必须保留
• 保护行守卫：栈追踪、密钥所在段落，只要格式化器没有逐行原样保留，同样作废

换句话说，格式化器"可以偷懒，但不能撒谎"——它可能把成功日志总结成一行，但绝不能吞掉失败信息。

三、TOON 编码：让 JSON 少花 30–60% 的 token

结构化数据是工具输出的大头（API 响应、kubectl -o json、CI 结果）。sqz 用 TOON（Token-Optimized Object Notation，token 优化对象记法） 对 JSON 做无损紧凑编码，实现见 toon.rs：

• 对象：简单键名去掉引号、分隔符最小化 → {k:v,k:v}
• 数组：去掉空格 → [v,v,v]
• 对象数组：改写成"表头 + 每行一个对象"的表格形式，空单元格表示字段缺失
• 数字/布尔/null：原样紧凑输出

编码是可逆的：TOON: 前缀标识字符串，解码器能还原出完全一致的 JSON。

一个真实例子（来自 BENCHMARKS.md）：

输入（64 tokens）：
{"id":42,"name":"Alice","metadata":{"plan":"pro","internal_id":null,...}}

TOON 编码后（53 tokens，省 17.2%）：
TOON:{created_at:"...",email:"...",id:42,metadata.plan:"pro",...}

配合管线里的 JSON 预处理阶段效果更佳：先剥离 null 字段和空值、扁平化嵌套（metadata.plan 代替一层对象）、丢弃 __v/etag/请求 ID 这类记账字段、截断超过 500 字符的长字符串，最后再 TOON 编码。一个 20 项的大 JSON 数组可以省 57.1%，aws ec2 describe-instances 的 40 台实例输出能省 69.9%。

四、日志折叠：把"刷屏"变回"一句话"

真实日志里最费 token 的不是错误，而是重复。sqz 的日志折叠由几个阶段协作完成（均在 pipeline.rs 中调度）：

1. condense：把连续相同的行先砍到 3 行以内
2. rle 游程折叠：再折成一行并标注次数 → [×10]
3. log_template：处理"只差时间戳"的伪重复行（精确 RLE 抓不到的那种）
4. sliding_window_dedup：捕获跨行重复的子串
5. table_compact：压缩 docker ps、ps aux 这类表格输出的对齐空格
6. git_diff_fold：diff 只保留 hunk 头、改动行及上下各 2 行上下文，其余折成 [N unchanged lines]

看一组实测数据（148 tokens → 39 tokens，省 73.6%）：

2024-01-01 09:59:59 [INFO] Server started
2024-01-01 10:00:00 [INFO] Connected to database [×10]
2024-01-01 10:00:11 [ERROR] Connection timeout after 30s

注意第 3 行：ERROR 行逐字保留。折叠前每个阶段都会做安全检查——如果原文里有 ERROR 标记，压缩结果里必须有，否则该阶段结果作废。

五、安全模式：压缩的"免检通道"

压缩最大的风险是压丢了关键信息。sqz 的解法是模式路由（confidence_router.rs）：

• Safe（安全模式）：栈追踪、SQL 建表/改表语句、PEM 私钥块、password: xxx 这类凭据行——识别后原样放行、任何尺寸都压缩 0%，而且永远不写入缓存（凭据不能落盘）
• Default（默认）：普通内容，平衡压缩
• Aggressive（激进）：低熵、高度重复的样板内容，最大力度压缩

判断不是简单关键词匹配，而是看结构：commit message 里写 "fix: password reset" 不算密钥，password: abc123 才算；Traceback (most recent call last): 后跟 File "..." 行才算真正的 Python 栈追踪。

即便过了模式路由，还有最后的兜底——验证器（verifier.rs）：每次压缩后跑 7 项检查（错误行是否保留、文件路径是否保留、JSON 键是否保真、diff hunk 头是否保留……），算出置信度分数；低于 0.6 就自动用安全预设重压。这套"先压缩、后验证、不行再降级"的闭环，让基准测试里 359 个关键事实做到了 100% 召回（见 quality-benchmark.md）。

六、如何亲手验证这些机制？

sqz 是确定性、可离线运行的，你可以直接复现本文所有数字：

cargo install sqz-cli     # 或 brew / npm / pipx
sqz compress --mode default --verify   # 查看压缩率 + 置信度
sqz stats --breakdown                # 按命令查看 token 节省分布
cargo test -p sqz-engine benchmarks -- --nocapture   # 跑完整基准

用 sqz compress 把一段重复日志、一个 JSON API 响应或一份 git diff 管道进去，你会直观看到日志折叠、TOON 编码和安全模式分别在什么场景下生效；sqz expand <ref> 还能把去重引用按字节精确还原。更多集成方式（Claude Code hook、MCP proxy 包装任意 server）可参考 mcp-context-compression.md 与 README.md 的 How It Works 章节。

总结：sqz 管线的四条设计原则

• 结构化优先：已知命令走定制格式化器，未知输出走通用折叠，源码原样放行
• 无损优先：TOON 可逆、sqz expand 按字节还原，节省靠"少发"而非"发坏"
• 安全优先：高风险内容免检直通、永不缓存，格式化器丢错即作废
• 验证闭环：置信度 < 0.6 自动降级安全预设，过度压缩在基准测试里就是 CI 失败

对新手而言，理解这四点就抓住了 sqz 压缩管线的全部精髓：它不是把内容压小，而是让模型只收到它"接下来要行动"的那部分信息。