teamchong/pxpipe · 上手攻略

  • 仓库：teamchong/pxpipe
  • 链接：https://github.com/teamchong/pxpipe
  • 分类：ai · llm-infra · tool
  • 作者：Tom
  • 更新：2026-07-07

它是什么

pxpipe 是一个本地请求代理，专门用来降低 Claude Code（以及其他基于 Anthropic API 的 Agent）的 token 消耗。它通过将大量文本内容（系统提示词、工具文档、历史记录）渲染为图片，再通过视觉通道传输，从而大幅压缩输入 token 数量。

核心逻辑：一张图片的 token 成本由像素尺寸决定，而不是内容长度。实测 dense 内容（代码、JSON、工具输出）约 3.1 chars/token，而文本模式约 1 char/token。按 Fable 5 当前 list price 计算，可节省 59-70% 的终端账单（注意：具体节省比例取决于实际 workload）。

pxpipe 压缩的是请求（input），不压缩响应（output），模型回复正常返回。

解决什么问题

Claude Code 类 Agent 在处理复杂项目时，单次请求的 input token 可能非常大（系统提示词 + 工具文档 + 历史上下文），导致： - 快速达到上下文上限，频繁截断历史 - token 费用高昂（长会话账单吓人） - 长上下文下模型推理速度下降

pxpipe 通过把大段文本"变成图片"来绕过 token 计量——图片的视觉 token 远少于等效文本 token（≈92,000 chars → ≈4,761 vision tokens）。

快速安装

方式一：一条命令启动（最简）

npx pxpipe-proxy                                  # 在 127.0.0.1:47821 启动代理
ANTHROPIC_BASE_URL=http://127.0.0.1:47821 claude  # 另起终端，让 Claude Code 指向代理

Dashboard 在 http://127.0.0.1:47821/ 可查看节省了多少 token、每个文本→图片转换的对比、kill switch 和实时模型信息。

方式二：库集成（开发者用）

npm install pxpipe-proxy

TypeScript / JavaScript 调用：

import { renderTextToImages, transformAnthropicMessages } from "pxpipe-proxy";

// 将文本渲染为图片
const { pages } = await renderTextToImages(toolResultText);
// pages[i].png: Uint8Array

// 转换请求体
const { body, applied, info } = await transformAnthropicMessages({
  body: requestBytes,
  model: "claude-fable-5",
});

保留特定块为原文（不转图片）：

options.keepSharp(block)  // 精确匹配 block

获取被图片化的原始内容（用于调试）：

options.emitRecoverable  // 返回被转换的原始块

核心用法

基础使用

# 1. 启动代理（默认 127.0.0.1:47821）
npx pxpipe-proxy

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

# 3. Dashboard 查看效果
# 浏览器打开 http://127.0.0.1:47821/

模型配置

默认只对 claude-fable-5 和 gpt-5.6 启用图片化。其他模型手动指定：

PXPIPE_MODELS=claude-fable-5,claude-opus-4-8,gpt-5.6 npx pxpipe-proxy

完全关闭：

PXPIPE_MODELS=off npx pxpipe-proxy

子 Agent 路由（避免精确值丢失）

对需要精确字符（如 hex、ID、hash）的任务，让子 Agent 走非允许列表模型：

CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-4-6 claude
# 或在 agent frontmatter 中：
# model: sonnet

日志文件

每次请求记录到 ~/.pxpipe/events.jsonl，包含 token 节省的详细数据，可自行复现计算节省比例：

cat ~/.pxpipe/events.jsonl

技术细节

工作原理

tool_result string ──► wrap at 1928px-wide columns ──► pack ~92,000 chars/page ──► PNG[]

代理拦截 /v1/messages，将符合条件的 bulk 内容重写为图片块，拼接回去后转发。1928×1928 图片 ≈ 4,761 vision tokens，可容纳约 92,000 chars。文字只在超过约 19 chars/token 的稀疏场景才更划算，而 Claude Code 实际流量约 1.91 chars/token（dense）。

pxpipe 有内置 profitability gate，根据每次请求的内容密度决定是否启用图片化，稀疏文本（如普通对话）不会浪费转换。

静态前缀保留 & 提示缓存

文本→图片转换时，静态前缀（如系统提示词）保留原文，可继续享受 Anthropic 的 cache_control 提示缓存，不影响现有缓存策略。

模型兼容性

模型 默认状态 说明
claude-fable-5 ✅ 启用 100/100 阅读准确率，推荐
claude-opus-4-8 ❌ opt-in 约 7% 渲染内容误读率
gpt-5.6 ✅ 启用
gpt-5.5 ❌ opt-in 图片上下文下有降级

典型适用场景

  1. SWE-bench 类任务：大幅压缩请求上下文，在 1M token 上限内处理更大 codebase
  2. 长会话开发：日常开发中避免上下文截断，保持历史连贯
  3. Token 账单优化：重度使用 Claude Code 的个人开发者或团队
  4. 代码库很大但只改一点：大段参考代码、图片化后不影响对局部代码的操作

坑与注意

  1. 信息丢失（关键）：pxpipe 是有损压缩。Fable 5 对 dense 图片中 12-char hex 字符串的精确回忆率约 13/15（86.7%），Opus 4.8 为 0/15。误读是静默的虚构（silent confabulation），不是报错。 - 字节精确值（IDs、hash、密钥）必须保留原文，不要依赖图片化内容。配置 keepSharp() 或让子 Agent 走 sonnet 模型。
  2. Opus 4.7/4.8 默认不开启：约 7% 的渲染内容误读率，实测不满足精确工作需求。
  3. 图片化内容不享受提示缓存：被转为图片的部分不参与 cache_control 计算（虽然静态前缀仍可缓存）。
  4. 稀疏文本反而多花钱：纯对话（~3.5 chars/token）走图片化反而更贵，pxpipe 的 profitability gate 应会自动跳过。
  5. 依赖视觉通道：Agent 必须支持视觉输入（如 Claude Code 自带），纯文本接口无法使用。
  6. Fable 5 是默认模型：如果你用的是 Opus 或 Sonnet，需要手动加入 PXPIPE_MODELS。

与同类对比

工具 原理 节省幅度 精度 接入复杂度
pxpipe 文本→图片（视觉通道） ~59-70%（Fable 5） 中等（有损） 低（代理模式开箱即用）
prompt caching（Anthropic） 提示词缓存 取决于缓存命中率 无损 无需工具，API 层面开启
上下文压缩（第三方） LLM 摘要压缩 视压缩比 有损 需集成
只传相关代码块 截取局部上下文 取决于工具 无损 需工作流改造

pxpipe 独特之处：不需要改工作流，不需要改 Agent 代码，作为透明代理运行，适合不想折腾的 Claude Code 重度用户。

一句话推荐

如果你重度使用 Claude Code（Fable 5），跑一个本地透明代理即可节省约 60% 的 token 账单，但注意不要把需要精确字符（ID、hash）的任务交给它——图片里的信息是有损的。