teamchong/pxpipe

pxpipe – 用于 Claude Code 和其他 LLM 的令牌节省代理

它是什么 – pxpipe 是一个本地代理，在请求到达模型之前，将 LLM 请求中体积庞大的部分（系统提示词、工具定义、长聊天历史、文件差异等）改写为 PNG 图像。由于支持视觉的模型按图像令牌收费（取决于像素数，而不是图像内部的文本量），一个密集的代码或 JSON 块可以用比相同文本少得多的令牌来表示。该代理适用于 Anthropic 的 Claude Code、Google Gemini 以及任何接受视觉输入的 OpenAI 兼容端点。

关键概念

概念	工作原理
令牌密度提升	312×728 像素的图像（Claude-Fable-5 配置文件）大约包含每个图像令牌 3.1 个字符，而 Claude Code 中每个文本令牌约 1 个字符。这意味着在 1M 令牌窗口中可容纳的字符数增加了 ~4.7-5 倍。
选择性压缩	只有符合条件的批量上下文才会被转换为图像（系统提示词、工具文档、已关闭的工具调用轮次、较旧的历史记录）。最近的轮次和任何字节关键数据（ID、哈希、机密）保持为纯文本。
有损但有保护	图像转换可能会误读精确的十六进制字符串（例如，Fable-5 上 15 个中正确 13 个）。附加到每个请求的“事实表”保留最多 96 个高精度令牌；其余为尽力而为。
盈利性门控	pxpipe 对原始请求运行廉价的令牌计数探测（`count_tokens`），并且仅在预期成本节省超过阈值（密集工作负载约为 60-70%）时应用图像转换。
特定于模型的渲染配置文件	不同的模型使用不同的字体、单元格大小和页面尺寸（例如，Claude-Fable-5 使用 5×8 Spleen 字体，Grok 使用 JetBrains Mono 14px）。代理根据模型 ID 选择正确的配置文件。

如何试用（快速入门）

# 启动本地代理（监听 127.0.0.1:47821）
npx pxpipe-proxy

# 将 Claude Code 指向代理
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude

http://127.0.0.1:47821/ 上的仪表板显示实时令牌节省、文本与图像渲染的并排比较以及一个终止开关。

或者，使用自动注入代理的 warp 包装器：

pxpipe warp -- claude   # 无需设置 ANTHROPIC_BASE_URL

您还可以在无需运行代理的情况下将任何文本或 git 仓库导出为 PNG 页面：

npx pxpipe-proxy export src/          # 渲染 src/ 中的文件
cat prompt.txt | npx pxpipe-proxy export --stdin
npx pxpipe-proxy export --git          # 渲染当前仓库历史

导出会创建一个包含 page-*.png、factsheet.txt、manifest.json 和原始 prompt.txt 的文件夹。

实际影响（仓库中报告）

指标	报告结果
端到端成本降低	生产工作负载的账单降低 ~59-70%（例如，演示中 $6.06 vs $42.21）。
令牌减少	48k 字符系统提示词的 25k 文本令牌 → 约 2.7k 图像令牌。
基准质量	Claude-Fable-5 上算术 100/100，要点约 98/98，状态 18/18；十六进制字符串召回率略有下降（15 个中 13 个）。
SWE-bench	“Lite”套件上请求大小减少 ‑65%，“Pro”套件上 ‑60%，精度相同。

限制与注意事项

有损转换 – 精确标识符（12 字符十六进制、机密）可能被误读；此类令牌在可能的情况下会特意保留为文本。
模型依赖性 – 对于接受视觉输入且具有大上下文窗口的模型，节省效果显著；稀疏的散文实际上可能会增加成本。
仅请求侧压缩 – 模型输出永远不会转换为图像，因此输出令牌成本不变。
盈利性门控是启发式的 – 内置阈值适用于作者的生产数据（约 391 行），但可能需要针对不同的工作负载进行调整。
支持的模型 – 默认：Claude-Fable-5、Claude-Opus-5-5、Gemini-Flash。其他模型（Grok、Sol、GPT-5.6-Sol 等）可通过 PXPIPE_MODELS 选择加入。

谁可能使用它？

构建 代理工具（例如，代码助手、使用工具机器人）的开发人员，这些工具向 Claude Code 或 Gemini 发送大型系统提示词或长文件差异。
当工作负载是令牌密集型时，希望 减少 LLM API 支出 的团队。
对 视觉增强提示 和衡量令牌压缩权衡感兴趣的研究人员。

快速参考备忘单

命令	用途
`npx pxpipe-proxy`	启动代理服务器（默认端口 47821）。
`pxpipe warp -- <cmd>`	运行命令（例如 `claude`），自动注入代理。
`pxpipe warp --route '<src>=<dst>' <cmd>`	为 Anthropic 以外的端点添加自定义路由规则。
`pxpipe-proxy export <path>`	在无需运行代理的情况下，将文件或标准输入渲染为 PNG 页面。
`pxpipe stats`	从事件日志（`~/.pxpipe/events.jsonl`）汇总节省的令牌/成本。

结论 – pxpipe 是一个实用的开源工具，利用视觉令牌定价将大型文本上下文压缩为图像，为令牌密集的 LLM 工作流提供可衡量的成本节省，同时保持集成表面简单（只需一个本地 HTTP 代理）。