vision-squeezer

VisionSqueezer

在图像到达模型之前，将其调整到视觉大模型的 token 预算范围内。提供库、命令行工具和 MCP 服务，适用于代码、Agent 和流水线。

它做不到什么。 VisionSqueezer 无法缩小你粘贴、拖入或通过 @ 附加到聊天窗口（Claude Code、Cursor、ChatGPT 等）的图像。客户端会在任何工具或钩子运行之前附加图像，因此这些图像仍按完整大小计费。

它能节省 token 的场景：

• 你的代码发送到模型 API 的图像：Rust crate、Python 绑定和命令行工具。
• Agent 从文件中读取或通过工具获取的图像（屏幕截图、爬虫、浏览器自动化）：MCP 服务，或用于处理项目内文件的 Claude Code 图像读取钩子。

确切场景请参阅节省 token 的场景。

MCP 服务可在任何 MCP 客户端（Claude Code、Cursor、Codex、Gemini CLI 等）中运行，但只能看到 Agent 传给它的图像。

安装

每个客户端只需一条命令（推荐）

npx vision-squeezer install                       # asks for the client and scope
npx vision-squeezer install --client claude --scope user --yes
npx vision-squeezer install --client cursor --yes

每种客户端都只有一种安装方式，安装程序会自动选择：

JSON 文件只会合并，不会替换：其他服务和钩子都会保留；无法解析的文件不会被修改；重新运行时会替换我们自己的条目，而不是重复添加。

仅当客户端支持多种作用域（user、local、project）时，才会询问选择哪种作用域。旧版本中的 --method 参数仍可接受，但会被忽略。

下方的手动命令为简洁起见使用 npx -y vision-squeezer。请固定版本，如 vision-squeezer@<version>（安装程序会为你处理）：不指定版本的 npx 会继续使用它最初缓存的版本，即使已有新版本发布也是如此。

Claude Code

npx vision-squeezer install --client claude --scope user --yes

此命令会替你运行下面的两条命令（并首先移除旧版 claude mcp add 注册和 settings.json 钩子）。如需手动操作：

claude plugin marketplace add eralpozcan/vision-squeezer
claude plugin install vision-squeezer-mcp@vision-squeezer --scope user

重启 Claude Code，或运行 /reload-plugins，以加载 MCP 服务、技能和钩子。只想安装 MCP 服务，不需要技能和钩子？运行 claude mcp add --scope user vision-squeezer -- npx -y vision-squeezer。

Claude Desktop

npx vision-squeezer install --client claude-desktop --yes

也可以将配置添加到 claude_desktop_config.json（macOS：~/Library/Application Support/Claude/，Windows：%APPDATA%\\Claude\\）：

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

Cursor

npx vision-squeezer install --client cursor --yes

或者添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

code --add-mcp '{"name":"vision-squeezer","command":"npx","args":["-y","vision-squeezer"]}'

{
  "servers": {
    "vision-squeezer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

{
  "servers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

npx vision-squeezer install --client windsurf --yes

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

gemini mcp add --scope user vision-squeezer -- npx -y vision-squeezer

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

codex mcp add vision-squeezer -- npx -y vision-squeezer

[mcp_servers.vision-squeezer]
command = "npx"
args = ["-y", "vision-squeezer"]

qwen mcp add vision-squeezer -- npx -y vision-squeezer

{
  "mcp": {
    "vision-squeezer": {
      "type": "local",
      "command": ["npx", "-y", "vision-squeezer"],
      "enabled": true
    }
  }
}

kimi mcp add vision-squeezer -- npx -y vision-squeezer

{
  "context_servers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

{
  "mcpServers": {
    "vision-squeezer": {
      "command": "npx",
      "args": ["-y", "vision-squeezer"]
    }
  }
}

手动安装（Rust 二进制文件）

# From crates.io
cargo install vision-squeezer

# Or from source
git clone https://github.com/eralpozcan/vision-squeezer && cd vision-squeezer
make install   # builds → ~/.local/bin/

然后在上述任意配置中直接使用二进制文件路径，替代 npx：

{ "command": "vision-squeezer-mcp" }

**提示：**运行 npx -y vision-squeezer --setup 可打印包含自动检测路径的即用配置。

CLI 用法

vision-squeezer path/to/image.jpg \
  --mode auto|ocr|standard \      # default: auto (= standard, keeps colour; ocr is opt-in)
  --format jpeg|webp|avif \       # default: jpeg
  --quality 85 \                  # output quality 1-100 (default: 75)
  --tile-size 256 \               # patch size in px (default: 512)
  --no-crop \                     # disable padding removal
  --smart-crop \                  # edge-energy crop (vs corner-tolerance)
  --auto-quality 0.95 \           # binary-search quality to hit SSIM target
  --bg-tolerance 25 \             # background detection 0-255 (default: 15)
  --model <provider-alias> \ # model-aware resizing; see the model catalog
  --max-tokens 1600 \            # token budget: downscale until the output fits (0 = off; MCP default 1600)
  --max-tiles 20 \                # hard cap on tile count (model-specific unit)
  --json \                        # machine-readable JSON output
  --dry-run                       # run pipeline, skip disk write

批处理模式

传入目录而非文件：

vision-squeezer ./screenshots --recursive --output-dir ./optimized
vision-squeezer ./screenshots --recursive --json > report.json

HTTP API（n8n、Make、Zapier）

vision-squeezer serve 会运行一个小型 HTTP 服务，因此任何工作流工具都可以通过普通 HTTP 请求，在两个步骤之间压缩图像。无需自定义节点。

vision-squeezer serve                    # 127.0.0.1:8080
docker build -t vision-squeezer .        # or run it in a container
docker run -p 8080:8080 vision-squeezer

将图像字节作为 POST /optimize 的请求体发送。选项通过查询字符串传递：

curl --data-binary @screenshot.png "http://localhost:8080/optimize?max_tokens=1600" -o out.jpg -D -
# X-Tokens-Before: 4674
# X-Tokens-After: 1584
# X-Input-Size: 2400x1670
# X-Output-Size: 1344x924

GET /health 会返回 ok。超过 25 MB 的请求体会返回 413，无效输入会返回 400 和一行错误原因。此服务没有身份验证：默认监听 127.0.0.1，Docker 镜像则在容器内监听所有接口，因此仅应在可信网络上发布其端口。

**n8n。**在获取图像的步骤和视觉模型之间添加一个 HTTP Request 节点：

• 方法 POST，URL 为 http://vision-squeezer:8080/optimize?max_tokens=1600（如果两者运行在同一 Docker 网络中，则使用容器名称；否则使用 localhost）。
• 开启 Send Body，Body Content Type 选择 n8n Binary File，Input Data Field Name 设为 data。
• 在 Options → Response 中将 Response Format 设为 File，这样下一个节点就会获得优化后的二进制图像。开启 Include Response Headers and Status，以读取 X-Tokens-* 值。

这些设置参考了 n8n 文档，但尚未在 n8n 本身中测试。

Pipeline

Input image
  → crop_padding               remove solid-color borders
  → calculate_optimal_dims     snap to tile boundary (always down)
  → [enforce_max_tokens]       token budget (MCP default 1600) / optional tile cap
  → resize_exact               Lanczos3
  → [binarize]                 OCR mode only: Otsu threshold
  → JPEG/WebP encode           configurable quality & format

🦀 为什么选择 Rust？

VisionSqueezer 是对性能要求极高的中间件。我们选择 Rust 有三个不容妥协的理由：

• 延迟低到无感： 图像处理绝不应成为瓶颈。Rust 可确保图像对齐、裁剪和编码在毫秒内完成，让开发者在工作流中几乎感受不到优化层的存在。
• 占用空间极小： VisionSqueezer 作为运行在 IDE 后台的 MCP 服务，专为超轻量设计，在空闲时几乎不占用 CPU 和 RAM。
• 支持 Wasm： Rust 对 WebAssembly 的一流支持，让我们能将同样的高性能优化带到浏览器和边缘环境（Cloudflare Workers），在图像发送到网络之前，就能在客户端进行压缩。

基准测试快照

在 data/ 中的示例图像上，使用 vision-squeezer <image> [flags] --dry-run --json 捕获。目标是减少 token，而不是减少兆字节：服务商按像素尺寸计费，因此文件大小只影响上传和延迟。未设置预算时，流水线会对齐到网格并裁剪留白；对于大型照片，节省有限，因为服务商本身就会缩小过大的图像。token 预算（--max-tokens，MCP 服务中的默认值为 1600）才能带来实际节省。

案例研究 1：标准图像（istanbul.jpg）

2400×1670，0.5 MB。

vision-squeezer data/istanbul.jpg --max-tokens 1600

Input:  2400×1670  (0.5 MB)
Output: 1344×924  (0.2 MB, JPG q75)
File:   67.5% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude 4.7+      4674     1584     3090 (66.1%)
GPT-6            2903     1462     1441 (49.6%)
GPT-4o           1105     1105        0 (0.0%)
GPT-5             910      910        0 (0.0%)
Gemini           3096     1032     2064 (66.7%)
────────────────────────────────────────────────────────────

案例研究 2：1200 万像素图像（istanbul2.jpg）

4096×3072，2.2 MB。

vision-squeezer data/istanbul2.jpg --max-tokens 1600

Input:  4096×3072  (2.2 MB)
Output: 1288×952  (0.3 MB, JPG q75)
File:   87.9% smaller

── Token Estimates ─────────────────────────────────────────
Model          Before    After      Saved
------------------------------------------
Claude 4.7+      4661     1564     3097 (66.4%)
GPT-6            2942     1476     1466 (49.8%)
GPT-4o            765     1105        0 (0.0%)
GPT-5             630      910        0 (0.0%)
Gemini           6192     1032     5160 (83.3%)
────────────────────────────────────────────────────────────

如何解读这些数字

• 关闭预算，token 几乎没有变化。 Claude 4.7+ 已将图像上限设为 4,784 tokens，因此原图为 4,661 tokens 时，处理后可能反而达到 4,698。压缩后的文件更小了，但费用没有减少。
• 两张照片使用 --max-tokens 1600，Claude tokens 减少约 66%，GPT-6 减少约 50%，同时保留构图、色彩和大号文字。最先损失的是精细细节（远处的窗户、小标牌）。
• 预算按目标模型衡量，未指定时使用 Claude。使用相同的 1600 并指定 --model gemini，结果会落在 Gemini 的 768px 瓦片网格上（1,032 tokens），文件大小列也会相应变化。
• 根据内容选择预算。 1600 和 1000 能让视网膜屏幕代码截图中的正文保持清晰可读；600 则不行。在命令行中传入 --max-tokens 0（或省略该参数）即可关闭上限。
• 颜色不会被移除。 auto 模式的表现与 standard 相同；只有显式指定 --mode ocr 时才会输出黑白图像。

当前模型合理性检查

MCP 工具：optimize_image

**响应：**一个包含优化后图像的 MCP image 块，随后是一个简短报告文本块。图像绝不会以 base64 的形式出现在文本中：模型会将其读取为文本 token，成本会高于它所替代的图像。

{
  "width": 1344,
  "height": 924,
  "output_path": "/tmp/vision-squeezer/shot-1a2b3c4d.jpg",
  "tokens_before": 4674,
  "tokens_after": 1584,
  "savings_report": {
    "tiles_before": 4674,
    "tiles_after": 1584,
    "tiles_saved": 3090,
    "token_reduction_pct": "66.1",
    "size_reduction_pct": "67.5"
  }
}

如果输入为 image_path，则会设置 output_path。

节省 Token 的场景

只有更小的图像实际传到模型时，这项优化才有用。具体来说：

基准情况很重要。 Claude Code 在发送大图之前已经会缩小图像：在我们的测试中，一个 2400×1670 的文件传到模型时变成了 1999×1392。在此基础上，1600 Token 的预算在 istanbul.jpg 上节省约 56%，而不是与原始文件相比测得的 66%。

本 README 中的 Token 数量是根据各提供商公布的规则估算得出的。对于 Claude，我们使用 Anthropic 的 count_tokens 端点（claude-sonnet-5-5，仅图像 Token）进行了验证：

与 Claude Code 发送的图像相比，实际节省量为 3,603 → 1,587（−56%）；与原始图像相比，则为 4,759 → 1,587（−67%）。GPT 和 Gemini 的估算值尚未通过其 API 验证。

“仅 MCP 工具”表示 Agent 必须自行使用 image_path 调用 optimize_image；请在 AGENTS.md 中告知它这样做。Cursor、Gemini CLI 和 OpenCode 的钩子会将副本保存在项目内自动忽略的 .vision-squeezer/ 文件夹中，因为这些客户端限制只能读取工作区内的文件。

将截图保存到项目中（例如 screenshots/），并通过路径引用，即可节省 Token。钩子只会重写项目内的文件：它会返回允许决定，因此不得打开普通 Read 原本会询问是否允许访问的文件。

配置参考

支持的模型

平台支持

预编译的 MCP 二进制文件支持 Linux x86_64/ARM64、macOS Apple Silicon/Intel 和 Windows x86_64/ARM64。Python wheel 支持 Linux x86_64/ARM64、macOS Apple Silicon/Intel 和 Windows x86_64。不受支持的 Python 架构可通过 pip install --no-binary vision-squeezer vision-squeezer 从源代码安装。

高级功能

持久化与分析

VisionSqueezer 会在本地跟踪每次优化，并存储到 ~/.vision-squeezer/stats.db。

vision-squeezer stats

── VisionSqueezer Analytics ────────────────────────────────
Total Optimizations: 42
Total Tokens Saved:  842,500
Total Bytes Saved:   156.40 MB
Estimated USD Saved: $2.11
────────────────────────────────────────────────────────────

Shell 钩子与 Claude Code Skills

添加到 .zshrc / .bashrc：

eval "$(vision-squeezer setup-hook)"

这会一次性安装两项内容：

• squeeze 别名 — 一步完成优化并捕获输出路径：

  img_path=$(squeeze data/logo.png --model gemini)
  

• Claude Code Skills — 首次运行时自动写入 ~/.claude/skills/

可用 Skills

输出示例：

/vision-stats
── VisionSqueezer Analytics ────────────────────────────────
Total Optimizations: 42
Total Tokens Saved:  842,500
Total Bytes Saved:   156.40 MB
Estimated USD Saved: $2.11
────────────────────────────────────────────────────────────

/vision-doctor
## VisionSqueezer Doctor
- [x] Binary found: /usr/local/bin/vision-squeezer
- [x] Installed version: 0.1.8
- [x] Latest version (npm): 0.1.8
- [x] Status: Up to date

Marketplace 安装（setup-hook 的替代方式）： 添加到 ~/.claude/settings.json：

{
  "extraKnownMarketplaces": {
    "vision-squeezer": {
      "source": { "source": "github", "repo": "eralpozcan/vision-squeezer" }
    }
  }
}

然后在 Claude Code 中运行 /plugins add vision-stats@vision-squeezer、/plugins add vision-doctor@vision-squeezer 或 /plugins add vision-upgrade@vision-squeezer。

沙盒模式：“用代码思考”

在图像到达大模型之前，先在本地执行原子操作。Agent 决定如何处理图像；中间步骤不消耗任何 token。

CLI：

vision-squeezer screenshot.png --ops '[{"op":"crop","x":10,"y":20,"width":500,"height":500},{"op":"binarize"}]'

MCP 工具 — sandbox_execute：

支持的操作：crop、grayscale、binarize、resize、contrast、brightness。

爬虫集成

可在任何 Playwright/Puppeteer 抓取工作流中即时优化图像 — 原始截图不会浪费 API token。

await page.route('**/*.{png,jpg}', async (route) => {
  const response = await route.fetch();
  const body = await response.body();
  const optimized = await squeeze(body); // pipe through vision-squeezer
  route.fulfill({ body: optimized });
});

参与贡献

欢迎提交 PR。设置说明和指南请参阅 CONTRIBUTING.md。 请遵守我们的 行为准则。

许可证

Elastic License 2.0（ELv2）— 详情请参阅 LICENSE。