用 PiPic Skill 给编程 Agent 配一个图片压缩器

你的编程 Agent 能跑构建、改组件，也能修失败的测试。可你让它压缩一整个图片文件夹时， 它经常会临时写一段脚本，或者挑一个自己都无法稳定解读输出的工具。PiPic 给了它另一条路： 真正的 CLI 负责处理图片，一份简短的 Skill 教 Agent 怎样安全地调用这个 CLI。

PiPic 不是 AI 压缩模型。Agent 负责选择并操作工具；PiPic Agent CLI 把 PNG、 JPEG、WebP 或 AVIF 文件发送到 HTTP API 使用的同一套托管压缩服务。PiPic Skill 是连接 自然语言请求与 CLI 命令的指令层。

CLI 和 Skill 只需安装一次

初始设置由这台机器的使用者完成。安装 CLI，批准一次登录，再把开源 Skill 安装到你使用 的 Agent 里：

npm i -g @pipic/cli
pipic login

npx skills add PiPic-cc/pipic-cli -g \
  -a claude-code \
  -a codex \
  -a cursor \
  -y

更短的 npx skills add PiPic-cc/pipic-cli -g 会询问要把 Skill 安装到哪些受支持的 Agent。之后可以用 npx skills update -g 检查全局安装的 Skill 是否有更新。 Skill 源文件 和 CLI 一起公开，操作规则不是藏在某个提示词服务里的黑盒。

完成这些设置后，请求里不用出现产品名，也不用记任何参数：

Compress the images in ./assets in place.

Skill 的描述能匹配压缩、缩小或优化图片的请求。被选中后，它先检查 pipic 是否已经 安装，再检查当前机器是否已经登录。随后它把 “in place” 映射成 --replace，并让 CLI 输出机器可读的结果：

pipic ./assets --replace --json

如果用户要求保留原文件，Agent 就改用 -o <dir>。PiPic 强制要求二选一；两者都没 给时，命令会在发送任何文件之前直接拒绝执行。

Skill 固定了 Agent 猜不到的规则

README 可以说明一条命令，但 Agent 仍要判断什么算成功、什么时候重试、什么时候必须 停下来。这些决定会影响文件和月度配额，所以 PiPic Skill 把它们写成了明确规则。

Skill 要求 Agent 始终带上 --json。CLI 会为每个输入文件输出一行 NDJSON，固定包含 六个字段：file、status、before、after、saved，以及只出现在跳过或 失败记录里的 error。status 只有 ok、skipped 和 error 三种值。

skipped 不是失败。最常见的一种跳过，是压缩结果反而更大，因此 PiPic 保留了原文件。 Skill 能防止 Agent 把这种情况汇报成任务失败，也不会让更大的文件覆盖原文件。

退出码决定下一步动作：

退出码 1 的规则很重要。两个文件失败后整目录重跑，会把已经成功的文件全部再上传一次， 配额也会重复消耗。Skill 会把重试范围缩到失败文件。

Skill 还为版本漂移留了退路。如果已安装 CLI 的行为和 Skill 描述不一致，Agent 会运行 pipic --help，以当前安装的程序为准。Skill 可以单独更新，运行时的最终依据仍是可执行 程序。

真正处理图片的是 CLI

Skill 不包含编码器，不上传图片字节，自己也不会压缩任何东西。它教 Agent 调用 CLI。 CLI 负责解析路径、检查输出位置、调用托管服务、以原子方式写入更小的结果，并输出 Agent 能够读取的记录。

我们公开的 2026 年第三季度 Benchmark 中，有一条记录使用 PiPic Agent CLI 1.0.6 处理 landscape.png。该文件压缩前是 2,316,198 字节，压缩后 是 723,577 字节，节省 1,592,621 字节。这只是一个有公开许可证的测试文件和一次真实 记录，不代表每个 PNG 都会得到同样结果。Benchmark 同时公开了输入、精确命令、全部 72 条原始记录和局限性。

对于普通 Agent 任务，更有价值的是这个数字周围的契约。Agent 能知道哪个文件被改写、 节省了多少字节、哪些文件保持原样，以及是否有路径需要处理。它不用猜进度动画，也不用 解析写给人看的描述句子。

远程 MCP 与这条执行路径彼此独立。MCP 是只读的集成指南，帮助 Agent 发现 CLI 和 HTTP API。图片字节通过 CLI 或直接 HTTP 请求传输，不经过 JSON-RPC。

把人的边界写清楚

Agent 不会擅自安装全局包，也不会自己运行 pipic login。全局安装会改变用户环境；登录 会打开浏览器，或者等待只有用户才能批准的设备码。如果 pipic whoami 以退出码 3 结束， 正确做法是停下来，请用户完成批准。

同一台机器上，pipic login 保存的凭证可以供之后的 Agent 任务使用。容器、CI 或沙箱 可能看不到用户的 ~/.config，这些环境应当改用用户在账号页创建并设置的 PIPIC_TOKEN。

PiPic CLI 和 API 使用独立的月度配额：Free 每月 100 张，Pro 每月 5,000 张。网页版压缩 仍然免费、不限量，也不需要账号。CLI 图片会离开本机接受处理，并在压缩结束后立即从服务 器删除；完整处理方式见隐私页面。

这套分工很明确。人负责安装并授权工具，Skill 提供操作规则，Agent 判断何时调用，CLI 用一份 Agent 真能遵循的输出契约完成实际工作。