来源：GitHub (★594)
URL: https://github.com/ojuschugh1/sqz
精读日期：2026-08-16
模型：DeepSeek V4 Flash（AI 生成，人工未审校）
正文获取：全文

一、核心论点/事实

  • sqz 是一个用 Rust 编写的单二进制工具，用于在命令输出到达 LLM 之前进行压缩，目标是节省 token 和降低成本，零配置。
  • 核心机制是去重（dedup）：同一文件在一次会话中被读取 5 次时，首次发送压缩内容（约 800 tokens），后续重复读取仅返回 13-token 的引用。
  • 实测数据：一次开发者一周的真实使用中，3,003 次压缩共节省 178,442 tokens，平均缩减 24.7%；单命令压缩率在 2–58% 之间，取决于内容类型。
  • 典型场景对比：无 sqz 时 3 次文件读取共 6,000 tokens；有 sqz 时仅约 826 tokens，节省 86%。
  • 安装方式支持 curl（Unix）和 PowerShell（Windows），无需编译器；Windows 需 Visual Studio Build Tools（C++ 桌面开发工作负载）。
  • 支持 40+ 命令格式化器（git、cargo、npm/pnpm/yarn、pytest、ruff、go test、docker、kubectl、aws、terraform、gradle、gh、grep/rg、tree、curl 等）。
  • 安全机制：堆栈跟踪、错误消息、密钥等敏感内容路由到安全模式（0% 压缩），避免信息丢失或泄露。

二、方法/架构拆解

  • 实现方式：sqz 安装一个 PreToolUse 钩子，在 AI 工具（如 Claude Code）执行 bash 命令之前拦截，透明地压缩命令输出，AI 工具无感知。
  • 压缩管线：包含 40+ 按命令类型定制的格式化器（如 git status、cargo build 等），剥离空字符、紧凑编码，输出为 TOON 格式。
  • 去重机制：会话内缓存已发送的文件内容，重复读取时返回 13-token 的引用，而非重新发送完整内容。
  • 状态机解析器：针对 Rust、Go、Python、JS、JVM 等语言实现状态机解析器，仅展示失败信息（如测试失败、编译错误），过滤成功输出。
  • 安全路由：堆栈跟踪、错误消息、密钥等敏感内容自动路由到安全模式，压缩率为 0%，确保关键信息不被破坏。
  • 安装与配置：
  • 支持全局安装（作用于机器上所有项目）和项目级安装（仅当前项目，通过 .claude/settings.local.json）。
  • 自动安装会通过 JSON 解析器合并配置条目，可能丢失注释；手动安装可保留注释（适用于 Claude Code、Cursor、Windsurf、Cline、Gemini CLI、Codex 等使用纯 JSON 配置的工具）。
  • OpenCode 支持带注释的 JSON 文件，自动安装对其非破坏性。
  • 适用范围：仅压缩命令输出（bash 命令的 stdout），不干预用户提示词和 AI 响应（由 AI 工具控制）；不适用于 ChatGPT、Claude.ai、Gemini、Grok、Perplexity 等聊天界面。

三、值得注意的局限/争议

作者承认的局限：

  • 压缩率因内容而异（2–58%），高度依赖工具调用的重复性；agentic 会话中大量文件重读时收益最大，否则收益有限。
  • 自动安装会通过 JSON 解析器重写配置文件，可能丢失用户精心编写的注释；需手动安装才能保留。
  • Windows 平台需要额外安装 Visual Studio Build Tools，并非完全零依赖。

AI 判断的局限/争议：

  • 去重机制依赖会话内缓存，若会话跨多个项目或长时间运行，缓存管理策略（如 LRU、过期时间）未说明，可能存在内存或准确性风险。
  • 13-token 引用机制要求 AI 工具在后续调用中能正确解析引用，若 AI 工具不理解该格式，可能导致上下文断裂或错误解读。
  • 安全模式（0% 压缩）虽然保护敏感信息，但意味着这些内容仍以原始大小发送，token 节省效果在这些场景下为零。
  • 仅支持命令行工具的输出压缩，对非 bash 命令（如 GUI 操作、API 调用）无效，适用范围有限。
  • 依赖 PreToolUse 钩子机制，仅适用于支持该钩子的 AI 工具（如 Claude Code），对其他工具（如 ChatGPT 桌面版）不生效。

四、与 RRLab 研究的关联

  • Harness 工程：sqz 的 PreToolUse 钩子拦截机制为 RRLab 的 Harness 设计提供了参考——在工具调用链中插入透明中间层，不改变 AI 工具行为即可优化 token 消耗，可借鉴其"零侵入"的架构思路。
  • 多模型协同：去重缓存（13-token 引用）机制可应用于多模型协同场景——当多个模型共享同一上下文时，通过引用而非复制减少跨模型通信开销，提升协同效率。
  • 模型评测：sqz 的 3,003 次真实压缩数据（24.7% 平均缩减）为 RRLab 的评测体系提供了 token 成本维度的量化基准，可纳入评测指标（如 token 效率、成本节省率）。
  • Agent 落地：sqz 针对 agentic 会话（大量文件重读）的优化策略，直接适用于 RRLab 的 Agent 落地实践——通过压缩和去重降低长会话的 token 成本，提升 Agent 的可持续运行能力。
  • AI 原生产品：sqz 的"透明压缩"理念（AI 工具无感知）可作为 AI 原生产品的设计原则——在用户无感的情况下优化资源消耗，提升产品性价比和用户体验。

本笔记由 DeepSeek V4 Flash 自动生成，未经人工审校。原文链接：https://github.com/ojuschugh1/sqz