SuperAPI AI 工具集

use-pxpipe

编程与开发

查看项目

更新于 11-05 16:17

技能介绍

用途

use-pxpipe 用于把 Claude Code 的智能体框架接入 pxpipe 本地代理,从而降低编码会话的输入 token 消耗。pxpipe 运行在本机 127.0.0.1:47821,在请求离开本机前,把每次请求中重复发送的大量内容(系统提示、工具文档、折叠的较早历史)改写为高密度 PNG 图像块。图像按像素面积计 token,不按字符数计算,因此代码、JSON、日志等高密度文本以图像形式承载时,每 token 的字符数约为纯文本的 3 倍。真实会话端到端测得输入 token 减少约 59%–70%(一次实时 A/B 为 856k→277k)。模型返回的响应原样流回,pxpipe 只压缩请求,不压缩输出。

该技能与 use-freellmapi 是同一技术栈上的不同层级:use-freellmapi 改写应用自身的 LLM 客户端(源码中的 base_url 与 key),目标是免费试用应用;use-pxpipe 改写智能体框架(ANTHROPIC_BASE_URL 环境变量),目标是减少编码会话的输入 token,代价是旧的大块内容以有损摘要形式呈现,而最近的对话轮次仍保持文本。

主要能力

  • 将 Claude Code 的 ANTHROPIC_BASE_URL 指向 http://127.0.0.1:47821。
  • 通过 PXPIPE_MODELS 控制模型范围,默认仅 claude-fable-5;只有确认模型在允许清单内才可扩大范围。
  • 提供本地仪表盘 http://127.0.0.1:47821/,展示实时节省、透传开关(POST /api/compression)。
  • 以环境变量方式接入,unset ANTHROPIC_BASE_URL 即可完全恢复原始行为,不写入项目配置,不把 pxpipe 作为项目依赖。

使用方式

  1. 先查模型允许清单:pxpipe 把上下文转成图像后需要模型从像素中读回,不同模型对此能力差异很大。允许清单位于 model-adaptation 的「Image-proxy model allowlist」章节及其 references/model-effort-tiering.md。不得把 PXPIPE_MODELS 扩大到清单之外;对读图能力不足的模型做图像化会产生看似自信的错误答案,不会报错。若会话模型不在清单内,pxpipe 会以 unsupported_model 原因原样透传,此时接入没有意义。
  2. 确认代理在运行:可用 curl -fsS http://127.0.0.1:47821/api/stats.json 探测;若无响应,用 Node 18+ 执行 npx pxpipe-proxy 启动,它会绑定 127.0.0.1:47821 并在 / 提供仪表盘。
  3. 在启动 Claude Code 的 shell 中设置环境变量:export ANTHROPIC_BASE_URL=http://127.0.0.1:47821 开启;unset ANTHROPIC_BASE_URL 关闭。建议只对当前会话生效,不要写入项目配置;若需持久化,可在 shell 配置中放两行带注释的开关行。
  4. 验证压缩确实生效且提示缓存保持热态:检查 ~/.pxpipe/events.jsonl 或仪表盘。压缩生效表现为事件行显示应用了压缩,而非 unsupported_model 透传或门槛拒绝。缓存热态表现为 history_image_sha8 在连续轮次间稳定,且首轮之后 cache_read_tokens 明显多于 cache_create_tokens;若历史边界设置错误,会每轮重新生成 Anthropic 提示缓存,反复按 1.25 倍 cache_create 计费,历史上出现过 −250% 的「节省」回归。仪表盘报告不设下限,出现负数应关闭开关排查。
  5. 向用户交接:仪表盘地址与开关方式(unset ANTHROPIC_BASE_URL 硬关闭;仪表盘透传开关或 PXPIPE_DISABLE=1 关闭压缩但保持代理运行;PXPIPE_MODELS=off 在范围层关闭)。

字节级精确的逃生通道:需要逐字保真的工作可交给图像范围之外的子代理模型,例如 CLAUDE_CODE_SUBAGENT_MODEL=claude-sonnet-5,前提是该模型不在图像代理允许清单内,需在选择时复查清单。

安全与限制

  • 仅限回环:仪表盘无身份验证,可查看捕获的请求上下文并执行关闭开关;共享机器上不得设置 HOST=0.0.0.0,对外暴露属于上游的显式选择并会记录警告。Cloudflare Workers 部署存在但需要 PXPIPE_WORKER_SECRET,不在本技能范围内。
  • 有损风险:图像化的大块内容适合按要点导航(决策、路径、名称、状态),但不能作为任何需要字节级精确内容(密钥、哈希、精确 ID、数值账目)的唯一副本。视觉不是 OCR,误读会表现为看似合理的错误值而非报错。pxpipe 会保留最近轮次为文本,并在每张图像旁附带精确标识符的文本事实表,但这只能缓解、不能消除该风险。
  • 上游较年轻(约 8 周历史,v0.8.x),若上游损坏,一行 unset 即可恢复默认行为。

适用场景

长时间编码会话、需要压缩上下文的智能体任务、希望在不改动项目依赖的前提下削减输入 token 的开发者。

不适用场景

字节级精确关键型工作;历史太短、无法摊薄压缩收益的短会话;提示已有约 98% 走缓存、几乎没有未缓存大块可压缩的会话;对延迟敏感的单词大请求(PNG 编码会增加延迟,但长会话中可忽略)。