1实现原理 · 为什么它能做到

核心是“按目标格式自动挑压缩器”：webp 优先 cwebp、其次 ImageMagick 的 convert、最后 sharp；非 webp 在 macOS 用 sips，否则 convert，再退 sharp。

skills/canghe-compress-image/scripts/main.ts

if (await commandExists("cwebp")) return "cwebp";

这里在做什么：detectCompressor 的判据是运行平台与 PATH 上的命令，而不是 npm 依赖清单——只要有 cwebp/convert/sips 之一，没有 node_modules 也能跑。

可用性探测靠 which + child_process.spawn，压缩本身也是 spawn 系统 CLI 并解析退出码/stderr。

skills/canghe-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/canghe-compress-image/scripts/main.ts

const sharp = (await import("sharp")).default;

这里在做什么：三种格式分别走 pipeline.webp/png/jpeg({ quality })；sharp 是唯一会在缺失时导致运行失败的依赖。

写盘用“临时文件 + 原子改名”：先写 output + '.tmp'，成功后 rename 到目标名。

skills/canghe-compress-image/scripts/main.ts

renameSync(tempOutput, output);

这里在做什么：避免中途失败留下半截文件；同一函数里若未开 --keep 且输入输出不同名，会先把原图改名成 *_original 再落新文件。

默认“转换而非另存”：同目录同基名、换扩展名；开启 --keep 且扩展名相同才输出 {base}-compressed.{ext}。

skills/canghe-compress-image/scripts/main.ts

return join(dir, `${base}-compressed${ext}`);

这里在做什么：getOutputPath 配合 -o/--output 可指定任意目标路径，此时不做原图改名。

未开 --keep 时把原图改名保留为 {base}_original.{ext}。

skills/canghe-compress-image/scripts/main.ts

renameSync(absInput, `${base}_original${ext}`);

这里在做什么：默认不删除原图（只是改名），但文件名变了，脚本类消费方需注意。

目录模式按扩展名白名单递归收集，逐个处理并汇总体积。

skills/canghe-compress-image/scripts/main.ts

const SUPPORTED_EXTS = [".png", ".jpg", ".jpeg", ".webp", ".gif", ".tiff"];

这里在做什么：collectFiles 仅在 -r 时递归；单文件失败只打印错误不中断整批，最后汇总输出总降幅。

偏好只在 SKILL.md 层声明（EXTEND.md 三级查找，命中则读取应用），脚本本身不读配置文件。

skills/canghe-compress-image/SKILL.md

Read, parse, apply settings

这里在做什么：EXTEND.md 支持默认格式/质量/保留原图；纯 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 时会失败。对照先例：baoyu-compress-image 等本地读写类为 blue。

5第二遍独立确认

[ok] 自带脚本只有 scripts/main.ts，且仅本地行为 — 扫描“网络请求”0 命中；唯一执行面是 spawn which/sips/cwebp/convert 与动态 import sharp；无 fetch/http 调用。
[ok] 原图改名副作用 — processFile 中当 !keep 且 absInput !== output 时 renameSync 原图为 *_original.{ext}；已在 risks 提示，批量前建议试跑或 -o。
[ok] sharp 依赖来源（无自带 package.json） — skill 目录确无 package.json；sharp 靠运行环境解析，缺失时仅在前几条 CLI 路径都不命中才会失败。
[ok] 选项表与脚本参数一致 — SKILL.md 的 7 个 option 与 parseArgs 处理的分支完全对应，默认值 format=webp、quality=80、keep/recursive/json=false。
[ok] 安全面与档位 — 零网络、零凭证、零配置解析；仅本地文件读写与系统 CLI 调用，判 blue 与前例一致。
[ok] meta 元数据 — commit dd0bf355…、path skills/canghe-compress-image、license MIT 与 bundle §0 核定值一致。

6结论

零 npm 强依赖，装了哪个系统工具就用哪个，跨平台可用性高。

原子写盘 + 批处理容错，批量化压缩不会因单个文件失败而中断。

参数面小且文档与实现高度一致，行为可预期。

安全面干净：纯本地、零网络、零凭证。

适合： 适合需要把图片批量转 WebP/压缩以减小体积、且希望零依赖快速上手的写作者或前端/内容工程。

不适合： 不适合需要无损或有损质量精细控制（如自定义编码参数）的专业图像管线；不适合想保留原文件名的自动化脚本（默认会改名）。

Install Agent-Ready

① Verified Mirror 2026-10-10

Option A · Direct DownloadDownload canghe-compress-image.tar.gz

sha256: 346c02cfdb2597bb…

Option B · Copy Guide for Agent

install.json

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit dd0bf35595.