1实现原理 · 为什么它能做到
核心是“按目标格式自动挑压缩器”：webp 优先 cwebp、其次 ImageMagick 的 convert、最后 sharp；非 webp 在 macOS 直接用 sips，否则 convert，再退 sharp。
skills/baoyu-compress-image/scripts/main.ts
if (await commandExists("cwebp")) return "cwebp";
判据是运行平台与 PATH 上的命令，而不是 npm 依赖清单——所以没有 node_modules 也能跑（只要有 cwebp/convert/sips 之一）。
可用性探测靠 which + child_process.spawn，压缩本身也是 spawn 系统 CLI 并解析退出码/stderr。
skills/baoyu-compress-image/scripts/main.ts
const proc = spawn("which", [cmd], { stdio: "pipe" });
runCmd 统一收集 stderr，非 0 退出即抛 'sips failed/cwebp failed/convert failed'，错误信息来自外部工具。
sharp 作为纯 JS 兜底，用动态 import 延迟加载（前三条路径都不命中时才付出加载成本）。
skills/baoyu-compress-image/scripts/main.ts
const sharp = (await import("sharp")).default;
三种格式分别走 pipeline.webp/png/jpeg({ quality })；sharp 是唯一会在缺失时导致运行失败的依赖。
写盘用“临时文件 + 原子改名”：先写 output + '.tmp'，成功后 rename 到目标名，避免中途失败留下半截文件。
skills/baoyu-compress-image/scripts/main.ts
renameSync(tempOutput, output);
同一函数里若未开 --keep 且输入输出不同名，会先把原图改名成 {base}_original{ext} 再落新文件，等于默认保留原图副本（只是改了名）。
默认“转换而非另存”：同目录同基名、换扩展名；开启 --keep 且扩展名相同才输出 {base}-compressed.{ext}。
skills/baoyu-compress-image/scripts/main.ts
return join(dir, `${base}-compressed${ext}`);
配合 -o/--output 可指定任意目标路径，此时不做原图改名（absInput !== output 才改名）。
目录模式按扩展名白名单递归收集，逐个处理并汇总体积；单个文件失败只打印错误不中断整批。
skills/baoyu-compress-image/scripts/main.ts
const SUPPORTED_EXTS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".tiff"];
汇总输出形如 'Processed N files: 12MB → 4.1MB (66% reduction)'，--json 时输出 files[] + summary。
偏好只在 SKILL.md 层声明（EXTEND.md 三级查找，没找到就用默认格式/质量/保留策略），脚本本身不读配置文件。
skills/baoyu-compress-image/SKILL.md
If none found, use defaults.
因此纯 CLI 使用与经 agent 使用的行为一致，差别只在 agent 会按偏好补默认参数。
2核心能力
01自动选择压缩后端（sips / cwebp / ImageMagick / sharp 四级降级）
02格式转换 webp/png/jpeg + 质量参数 (0-100，默认 80)
03单文件与目录批处理（-r 递归，扩展名白名单）
04保留原图策略（-k 走 -compressed 命名；默认把原图改名为 *_original）
05原子写盘（.tmp 中转后 rename），失败不留半成品
06体积对比汇报 + --json 结构化输出
07EXTEND.md 偏好（默认格式/质量/保留原图）与三级路径查找
3外部依赖
| Kind | Dependency / Endpoint |
|---|---|
| cli | sips（macOS 系统自带图像工具，非 webp 时的首选） |
| cli | cwebp（libwebp 官方 CLI，webp 首选） |
| cli | ImageMagick convert |
| cli | which（命令可用性探测） |
| package | sharp（动态 import 的纯 JS 兜底；skill 目录无 package.json，依赖运行环境解析） |
4管控建议与判定依据
建议配套管控措施
面向 Agent
分级或逐次授权，建议在沙箱运行
面向管理者
审批流程、可回滚、全程审计
判定依据（文件路径与关键语句摘要）
- scripts/: 执行本地脚本或命令: scripts/main.ts（bun 运行；spawn which / sips / cwebp / convert，动态 import sharp
- 本地工作目录: 文件读写与工件输出: 输出图片（同目录新扩展名或 -o 指定路径）、临时文件 <output>.tmp、未开 --keep 时把原图改名 {base}_original.{
审计说明： 。(a) 行为全部在本地：spawn 'which' 探测、调 sips/cwebp/convert 压缩、sharp 兜底，读本地图片写本地文件，零网络端点、零凭证读取、零配置文件解析（EXTEND.md 只由 agent 读取）。(b) 需要知情的是文件副作用：不开 --keep 时脚本会把原图 renameSync 为 {base}_original.{ext} 再写新文件，批量目录模式下影响面大，建议先小范围试跑或用 -o 明确输出。(c) 依赖运行环境里的 imagemagick/cwebp/sips/sharp 之一；无 CLI 且无 sharp 时会失败。对照先例：canvas-design / writing-fragments 等本地读写类为 blue。
5第二遍独立确认
- [ok] 无网络调用 / 无凭证读取 — 全文无 fetch/http/curl/API key/cookie/process.env 命中；唯一子进程是 which 与四个图像 CLI。
- [ok] “默认覆盖原图”的初判修正 — 第一遍曾疑为删除原图；逐行读后确认为 renameSync(absInput, `${base}_original${ext}`)——原图被改名保留，结论已按此更正写进 risks。
- [ok] sharp 依赖可解析性 — skill 目录无 package.json；仓库根 dependencies 含 sharp ^0.34.5。非 workspace 环境需自行安装 sharp 或依赖 cwebp/convert/sips 分支。
- [ok] 四个压缩器的参数与退出码处理 — sips 用 -s format/-s formatOptions/--out；cwebp 用 -q/-o；convert 用 [-quality]；sharp 走 pipeline.webp/png/jpeg。均检查 code!==0 并抛错。
- [ok] 批量容错与汇总 — 目录模式下 processFile 抛错被 catch 后仅 console.error 继续；--json 输出 files[] + summary(compressor/totals/ratio)。
- [ok] meta 元数据 — GitHub API：MIT、25926 stars、pushed_at 2026-09-10T15:13:43Z；本地 HEAD 与任务 pin 1567581c26ec… 一致。
6结论
适合： 适合站点/博客批量把大图转 WebP、给交付物瘦身的自动化场景，也适合塞进 agent 工作流做“生成后压缩”这一步（可被其它 baoyu skill 调用）。
不适合： 不适合需要保留 EXIF/ICC 精细控制、或需要 lossless/AVIF 等高级编码的场景；不适合对原文件名有强校验、不允许改名的流水线。
Install Agent-Ready
① Verified Mirror 2026-09-15
Option A · Direct DownloadDownload baoyu-compress-image.tar.gz
sha256:
Option B · Copy Guide for Agent5c0a427092d20497…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit 1567581c26.