Mac 图片压缩 CLI：用 Zipic 接入 AI Agent 和脚本

如果你想让 Claude Code、Codex 或脚本处理图片压缩，单纯唤起 GUI 不够。脚本要知道任务有没有完成、每个文件的处理结果、失败时该怎么分支。Zipic 1.9.5 新增的 zipic 命令就是这个入口：一个在 Mac 本机运行的 mac图片压缩cli，支持 --json、--dry-run、退出码和预设。

zipic 通过 Unix Domain Socket 连接正在运行的 Zipic.app。压缩仍由 Zipic.app 完成，CLI 只负责把请求交过去，再把结果带回来。这样既复用应用里的预设和许可状态，也保留本地处理：图片不会上传到服务器。

为什么 mac图片压缩cli 更适合 AI Agent

Zipic 也支持 URL Scheme。它适合快捷指令、启动器或一次性终端触发。但 URL Scheme 只负责触发，不会返回处理结果。AI Agent 和脚本更需要 CLI。

CLI 能补上这些信息：

Agent 需要什么	zipic CLI	URL Scheme
判断压缩是否成功	退出码	没有返回值
读取每个文件的结果	--json 单行输出	没有 stdout
执行前检查计划	--dry-run	不支持
识别 Pro 或配额限制	结构化错误字段	只有界面提示
等任务完成再继续	同步命令	触发即结束

人可以打开 Finder 看结果，脚本不能靠猜。CLI 会告诉它：这个文件压缩成功，那个文件被 Smart Skip 保留原图，这批任务碰到了 Pro 限制，或者命令参数写错了。

完整参考见 命令行工具 和 与 AI / 命令行协作。

安装并验证 zipic 命令行

zipic 需要从 Zipic 应用内安装。安装后，Zipic 会在 /usr/local/bin/zipic 创建符号链接，终端和脚本就能直接调用它。

有两种安装方式：

1. 点击 Zipic 菜单栏图标，选择 Install zipic CLI。
2. 首次启动时，在引导流程里的 Install CLI 步骤完成安装。

接入自动化之前，先确认命令可用：

command -v zipic
zipic --version
zipic --help

我在 2026 年 5 月的本机检查中看到：Zipic.app 版本是 1.9.5，zipic --version 输出 zipic 0.1.0。这两个版本号不是一回事。前者是应用版本，后者是 CLI 客户端版本。

--help 会列出主要命令：

zipic compress <files-or-dirs>...
zipic preset list
zipic preset show <name-or-id>
zipic list
zipic list clear

第一次安装后，建议运行 zipic preset list --json。能看到预设列表，就说明 CLI 已经连上 Zipic.app。

给 AI Agent 安装 Zipic Skill

如果你的重点是 AI Agent，不要只把 zipic 命令扔给它。更稳的做法是安装 Zipic Skill，让 Agent 知道 Zipic 的能力边界、常用参数和兜底方式。

官方文档里的安装命令是：

npx skills add okooo5km/Skills4U --skill zipic

安装后，你可以直接对 Claude Code、Codex 或其他支持 AI Skills 的工具说：

• “压缩 ~/Downloads/screenshots/ 里的图片。”
• “把这张 PNG 转成 WebP，用在博客里。”
• “把这些产品图缩到 1920px 宽，并保存为 AVIF。”

Skill 的价值不只是少打一段命令。它会先判断当前环境能不能运行 Zipic，处理带空格或中文的路径，根据场景选择 WebP、AVIF、HEIC 或 JPEG，也会在遇到 Pro 功能或免费配额限制时给出更准确的提示。

实际使用时，可以把它理解成两层配合：zipic CLI 负责执行和返回结果，Zipic Skill 负责把自然语言请求变成更可靠的调用。能跑 CLI 时优先用 CLI；环境不能执行二进制时，再退回 URL Scheme。

先 dry run，再用 JSON 输出压缩结果

给 Agent 使用时，建议先预演，再执行。

zipic compress ~/Downloads/screenshots \
  --format webp \
  --level 3 \
  --dry-run \
  --json

--dry-run 不会压缩文件，只返回执行计划。结果里会列出输入路径和最终参数，例如 output_format、level、location、width、height、后缀、覆盖方式和宽高比设置。

确认计划符合用户意图后，去掉 --dry-run：

zipic compress ~/Downloads/screenshots \
  --format webp \
  --level 3 \
  --json

加上 --json 后，Zipic 会按行输出结果，jq、Node、Python 或 Agent 都能解析。官方文档说明，结果状态包括 "success"（压缩成功）和 "kept_source"（Smart Skip 保留源文件）。

zipic compress ~/Downloads/screenshots --format webp --level 3 --json | \
  jq -c 'select(.state == "success") | {file: .source, saved: .saved_bytes}'

Agent 读完输出后，可以直接汇报：“5 个文件压缩成功，2 个文件已足够小，保留原图。” 它不需要靠文件修改时间猜结果。

用预设代替到处硬编码参数

一次性脚本可以直接写 flags。重复使用的流程，建议改用 Zipic 预设。压缩策略留在应用里，脚本只引用预设名称或 ID。

zipic preset list --json
zipic compress ~/Projects/site/public/images --preset WebP --json

不同图片可以用不同预设：

资产类型	预设思路	原因
博客截图	WebP，等级 2 或 3	保持界面文字清晰，同时减小 PNG 体积
营销照片	AVIF 或 WebP，等级 3	用现代格式减小网页资源体积
社交分享图	JPEG，固定宽度	兼容性更稳
文档截图	原格式，低压缩等级	避免文字边缘出现明显噪点

你也可以直接在 CLI 里创建和管理预设：

zipic preset create --name BlogWebP --format webp --level 3
zipic preset show BlogWebP --json
zipic preset set-default BlogWebP

也可以先在 Zipic 的 Workflow 设置里建好预设，再交给 CLI 调用。

更多自动化用法见 开发者图片压缩工作流 和官方 集成 Zipic 能力 文档。

处理退出码、Smart Skip 和 Pro 限制

脚本先看退出码，再决定下一步。Zipic CLI 文档列了四类退出码：

退出码	含义	Agent 应该怎么做
0	成功	解析结果，总结节省体积
1	业务或运行时错误	读取 JSON 错误字段并说明原因
64	参数错误	修正命令构造后再试
65	Zipic.app 未运行且无法自动唤起	提醒用户打开或重新安装 Zipic

CLI 的 Free / Pro 边界和 GUI 一致。免费版可以压缩基础格式；高级格式、高级输入、自定义预设数量和每日配额，按 Pro 或试用状态判断。在 JSON 模式下，Pro 和配额错误可以带上 purchase_url、blocked_format、remaining、requested 字段。

脚本可以这样分支：

zipic compress "$folder" --format avif --level 3 --json
case "$?" in
  0) echo "Compression completed";;
  1) echo "Read JSON error and offer fallback or Pro link";;
  64) echo "Fix arguments";;
  65) echo "Open Zipic.app and retry";;
esac

如果 Zipic 返回 kept_source，不要当成失败。它表示继续压缩没有收益，Zipic 保留了源文件。脚本应该把它单独计数。

CLI、URL Scheme、快捷指令和 Raycast 该怎么选

需要读取结果，用 CLI。只想触发压缩，用其他入口。

入口	最适合什么场景
zipic CLI	AI Agent、终端脚本、Mac runner、本地构建任务、需要结果的批处理
URL Scheme	只能打开 URL 的一次性触发
Apple Shortcuts / AppIntents	Finder 快速操作、分享菜单、面向用户的自动化
Raycast 扩展	从 Finder 选中文件后用键盘快速压缩
文件夹监控	文件进入指定目录后自动压缩

URL Scheme 仍然有用。如果某个工具不能执行二进制，open "zipic://compress?... 就是兜底方案。只要 Claude Code、Codex、Node 脚本、Makefile 或 Mac runner 能运行命令，优先用 CLI。

如果流水线跑在纯 Linux 环境里，不要硬接 Zipic CLI。更稳的做法是把压缩放在本机 Mac、发布前脚本，或能访问 Zipic.app 的 Mac runner 上；Linux 端只使用已经压好的产物。

下面的视频展示的是 URL Scheme 终端触发方式，可以作为背景说明。Agent 工作流优先用 CLI。

相关阅读

• Zipic URL Scheme 指南 —— zipic://compress 的完整参数参考。
• 开发者图片压缩工作流 —— 面向 Web 项目的完整自动化思路。
• AI 生成图片压缩指南 —— Midjourney、DALL-E 和 Stable Diffusion 输出图的体积优化。
• 用 Apple Shortcuts 自动压缩图片 —— AppIntents 与 Finder 快速操作。
• Raycast 图片压缩 —— 键盘驱动的一次性压缩。
• Mac 批量压缩图片教程 —— 需要手动检查结果时的批处理流程。

完整文档：命令行工具 | 与 AI / 命令行协作 | 集成 Zipic 能力

---

想让脚本读懂图片压缩结果？下载 Zipic，从应用内安装 zipic 命令行。下载即享 7 天完整 Pro 体验。Zipic Pro 解锁高级格式、自动化能力，以及超过免费每日限额的批量处理。