terse Skill 技能

技能简介

terse 是一款面向 AI Agent 的 MCP 工具输出无损压缩代理层。它以「即插即用代理」的形态运行在任何 MCP 服务器之前，在工具结果返回给模型的途中，剥离重复的结构开销（重复的键名、重复的值、重复的嵌套结构），把同样的数据以更紧凑的形式交给模型，全程不改变任何一个字段的值。

与同类工具不同，terse 的核心承诺是无条件无损：每一种变换都有精确的逆运算，项目内置往返校验门禁，断言 decompress(compress(x)) == x。它不丢行、不丢旧结果、不依赖任何 ML 模型，也不引入会过期的检索缓存。在真实 GitHub API 负载上实测节省 59.1% 的 token。

核心能力

• 无损压缩编解码器：只移除结构性开销——美化打印空白、每条记录重复的键、重复的字符串值、重复的嵌套模式树，任何字段值都不改变。
• 全表化（Tabularize）：把均匀记录列表折叠成一个表头加多行值的形式，键只写一次，并递归将嵌套的均匀字典列提升为共享表头。
• 字典编码（Dictionary）：把重复出现的字符串值与整棵重复子树折叠进内联图例（~0、~1…），仅在确实省 token 时启用，绝不反向膨胀。
• 跨调用增量（可选项）：同一工具被反复调用时，输出相对上一次结果的无损增量而非完整负载，重复调用场景可缩小约 73%。
• 跨块合并（默认开启）：当 MCP 服务器每个内容块只返回一条记录时，代理先合并成一个记录数组再压缩，让表化与增量能力覆盖整份结果。
• 实时节省台账：默认记录每次结果的体积、token 数与决策（绝不记录内容），可用 terse stats 回答「这一周到底省了多少」。
• 选择性策略：按工具粒度配置策略，压不动的内容直接透传，永远不会让结果变大。
• 便捷安装集成：terse install-mcp 一键改写客户端 MCP 配置，让服务器经由 terse 启动，可逆且对客户端透明。

安装配置

1. 环境要求：需要 Python 3.11 及以上版本。
2. 全局安装 CLI：执行 uv tool install terse-mcp（或 pipx install terse-mcp），安装后获得全局 terse 命令。
3. 虚拟环境安装：若用于库或嵌入式场景，执行 pip install terse-mcp 安装到虚拟环境。
4. Docker 方式：docker build -t terse . 构建镜像后，用 docker run -i --rm terse uvx some-mcp-server 代理真实服务器（-i 必须有，因为 MCP stdio 依赖标准输入输出）。
5. 策略文件：最小可用策略示例为 {"version":1,"defaults":{"tiers":["minify","tabularize","dictionary"]}}，写入 terse-policy.json 备用。

使用步骤

1. 包装任意 stdio MCP 服务器：运行 terse proxy -- uvx some-mcp-server --flags，你的 Agent 照常与之通信，terse 在途中无损压缩它返回的结果。
2. 查看节省效果：运行 terse stats，从真实会话中查看 terse 实际节省了多少 token。
3. 快速验证编解码器：把一段 JSON 通过管道传给 terse gate -，即可看到往返无损校验是否通过以及 cl100k token 节省比例。
4. 永久接入客户端：先写好策略文件，再运行 terse install-mcp --policy terse-policy.json，把已注册的服务器改为经 terse 启动。
5. 确认与卸载：terse mcp-status 查看当前包装了哪些服务器，terse uninstall-mcp 干净还原原始配置。
6. 生成验证报告：运行 terse verify --out reports/verify-report.md，一条命令产出无损门禁加逐工具 token 节省报告，可加 --html 输出图表版。

适用场景

• 记录型 / 数组型 JSON 输出：工具返回的对象列表，是 terse 收益最大的形态。
• 存在重复值或重复嵌套子树：同一用户对象、同一仓库对象被反复嵌入时，字典层能大幅折叠。
• 冗长的 REST 风格负载：GitHub、Jira、数据库行这类啰嗦的 API 返回。
• 被反复调用的工具：开启跨调用增量后可获得额外收益，适合轮询列表、重复读文件等循环。
• 上下文预算紧张的长会话：压缩工具输出可延缓上下文窗口被填满的速度。

适用人群

使用 Claude Code、Cursor 等 MCP 客户端、且工具输出体量大、token 成本敏感的开发者与 AI 应用团队；以及希望在不动任何业务代码的前提下削减上下文开销的 MCP 服务器维护者。

工作原理

terse 以 MCP stdio 中间件的身份运行：客户端连到 terse 而非直连服务器，terse 再连下游服务器，双向转发消息并在返回路径上压缩工具结果。压缩管线分层进行——第 0 层做压缩空白与表化，第 0.5 层做字典编码，第 0.7 层（可选）做跨调用增量（记录型走行列差异，非 JSON 结果走内容定义分块差异），第 1 层为按字段显式开启的有损模式（截断、降级为检索句柄），而「总结」类有损模式被永久关闭以守住「无 ML 依赖」的确定性承诺。转换后的字节本身就是模型的输入——它是一份更紧凑但仍可读的表示，而不是外挂式的卸载。

官方链接

• PyPI 主页：https://pypi.org/project/terse-mcp/
• GitHub 仓库：https://github.com/inth3shadows/terse