baoyu-compress-image实战：批量压缩图片并安全接入内容发布流程

返回总教程

图片压缩看似只是“把文件变小”，实际还涉及格式兼容、原图保护、批量目录、质量取舍，以及后续公众号、微博或网页是否能正确读取。baoyu-compress-image 把这些步骤收束成一个 Agent 可执行的图片处理环节：输入单个文件或目录，自动选择可用压缩器，输出新的图片并报告大小变化。本文基于固定 commit 的源码核对，案例是操作示例，不代表付费服务、账号或本机实测；不会在本文写作过程中实际安装、运行或上传图片。

适用场景与边界

适合在发布文章前压缩 PNG、JPG、JPEG、WebP、GIF、TIFF，尤其适合把截图、配图和文章内嵌图片转成更适合网页传输的 WebP；也适合对一个目录做递归处理，并用 JSON 结果交给后续自动化。脚本默认输出 WebP、质量 80。输入目录只有在明确传入 --recursive 时才会进入子目录，否则只处理当前目录中的支持格式。

它不是无损备份工具，也不是按目标文件大小反复搜索质量的编码器。质量数值是 0 到 100 的通用质量参数，较低通常更小但可能出现文字边缘、渐变和细线失真。GIF、TIFF 等输入虽然在扩展名列表内，但不能由此保证动画、多页或元信息完整保留。没有 --keep 时，仅当输入输出路径不同时，脚本才把原图改名为 _original；若输出与输入同路径，会替换原文件。处理前应另做备份，并确认写权限和空间。

前置依赖与按需安装

源码元数据要求 bun 或 npx，脚本本身是 Bun TypeScript。优先使用已安装的 Bun；若环境没有 Bun，可让 Agent 使用 npx -y bun 作为运行时，或者按项目规范安装 Bun。源码还会按格式自动选择压缩器：WebP 优先 cwebp，其次 ImageMagick 的 convert，再回退到 Sharp；PNG/JPEG 在 macOS 优先使用 sips，其他情况优先 convert，最后使用 Sharp。也就是说，不必为了第一次压缩预装全部工具，但需要确保最终选择的路径能解析 Sharp 依赖。

先按需安装技能本身。以下 --skill 与 --agent 是 skills 安装器的参数，不是压缩脚本参数；Claude Code 用户把 --agent codex 替换为 --agent claude-code：

1	npx skills add jimliu/baoyu-skills --skill baoyu-compress-image --agent codex

该命令的筛选参数已对照 skills 安装器说明核实。它通常获取仓库当前版本，不保证锁定本文 commit；严格复现时对照文末固定来源。运行时安装是另一件事，仅在确实缺少 Bun 时考虑：

1	npm install -g bun

若只是临时调用，不想全局安装，可把下面命令中的 ${BUN_X} 替换为 npx -y bun。正式运行命令还需要把 {baseDir} 替换成技能目录，例如统一源码目录下的 skills/baoyu-compress-image；不要把占位符原样交给 shell。

输入、输出与已核实参数

完整用法是：

1	${BUN_X} {baseDir}/scripts/main.ts <input> [options]

<input> 必填，可以是图片文件或目录。已核实参数如下：

--output 或 -o：指定输出路径。单文件时有效；目录批处理时脚本内部会为每个文件生成对应输出。
--format 或 -f：webp、png、jpeg，默认 webp，输入 jpg 作为格式值时会规范到 JPEG。
--quality 或 -q：0 到 100，默认 80。
--keep 或 -k：保留原文件；若输入扩展名与目标相同，输出名会添加 -compressed，避免同名冲突。
--recursive 或 -r：目录递归处理子目录。
--json：输出结构化结果。

单文件默认生成同目录同名的新扩展名。没有 --keep 且输入输出路径不同时，原文件会被改名为 _original；路径相同时则会被新输出替换。普通输出报告大小及节省百分比。JSON 包含 input、output、inputSize、outputSize、ratio、compressor，目录结果另有 files 和 summary。这里 ratio = outputSize / inputSize，不是节省百分比；节省百分比为 (1 - ratio) × 100%。例如 ratio 为 0.6 表示输出是输入的六成、节省四成，这只是计算示例。

可复制的自然语言 Agent 请求

请使用 baoyu-compress-image 处理 ./assets 目录中的 PNG、JPG 和 WebP 图片。先说明输入范围和预计输出目录，不要上传或发布。使用 WebP、质量 78、递归处理并保留原图；完成后给我每个文件的输入大小、输出大小、压缩比例和实际使用的压缩器。如果发现有不支持的文件或无法写入，请停止并说明原因。

如果只想先确认路径而不改动，可以这样请求：

1	请先检查 baoyu-compress-image 的输入文件是否存在、目录里有哪些支持的图片以及当前环境可能选择的压缩器，只做预检，不要执行压缩。

操作案例：文章配图批处理

假设工作目录有 posts/ai-guide/images/，其中有多张截图，目标是生成网页用 WebP，同时留存源图。公众号、微博等平台是否接受 WebP 需单独验证，不应因浏览器能显示就保证上传兼容；贴图工作流可能只扫描 PNG/JPG。先让 Agent 确认目标目录和原图数量，再执行：

1	${BUN_X} {baseDir}/scripts/main.ts ./posts/ai-guide/images -r -q 78 -k --json

这个案例的输入是目录，输出是各图片同目录的 WebP，-k 让 PNG/JPG 原文件保持不变，-r 让子目录也被扫描，--json 便于记录到构建日志。Agent 应将 JSON 中成功的 files 数量与预先枚举的输入数量核对，并按 1 - ratio 计算节省比例；ratio 是输出/输入之比，不是直接的节省率。某些已经高度压缩的 WebP 可能不会明显变小。若团队要求统一输出到另一处，可在单文件场景使用 --output，不要想当然地把目录批处理的输出语义当成“镜像整个目录”。

对于一个需要保持 PNG 的透明 Logo，可以明确指定：

1	${BUN_X} {baseDir}/scripts/main.ts ./brand/logo.png -f png -q 90 -k

质量不是越高越好，而应以小尺寸预览和文字清晰度共同验收。照片可从 75 到 85 试起，UI 截图、代码截图和透明图标则应先目测细线与透明边缘。

配置与偏好

技能支持可选 EXTEND.md，按以下优先级取第一个存在的文件：项目 .baoyu-skills/baoyu-compress-image/EXTEND.md，XDG 配置目录下同名路径，或用户目录 $HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md。源码说明它可配置默认格式、默认质量和是否保留原图。由于源码正文只规定了支持范围，没有为键名提供命令行替代参数，配置文件应按实际版本的扩展说明填写，不要自行编造键名后声称已生效；若没有配置，使用 webp、80、默认不保留的行为。

建议把项目级配置仅用于项目固定规范，例如文档站统一 WebP、质量 78、保留原图；不要把含路径或个人偏好的配置提交到不应共享的仓库。这些偏好属于 Agent 工作流：main.ts 本身没有读取 EXTEND.md。Agent 应把偏好转换成显式命令行参数并报告，直接执行脚本不会自动套用偏好。保留原图只能避免本次输入被重命名或替换，不会自动保护此前同名输出；再次处理前仍要检查冲突。

验收清单

输入文件或目录存在，扩展名在源码支持列表内。
单文件或递归范围与请求一致，未误处理其他目录。
输出格式、质量值和 --keep 状态与请求一致。
已另做源文件备份；跨格式且未保留时检查 _original，同路径输出不能假定有备份。
输出文件可读取，尺寸确实下降或有合理解释。
透明图、文字边缘、细线、渐变和 EXIF 相关需求已人工检查。
JSON 中处理数量、路径和压缩器记录完整。
未发生上传、发布或覆盖用户未授权的其他文件。

排错思路

提示找不到输入：检查绝对或相对路径、大小写和当前工作目录，先让 Agent 做预检。没有支持的图片：目录可能只有未列入源码数组的扩展名，或需要加 --recursive 才能看到子目录。压缩器失败：确认 cwebp、convert、macOS sips 或 Sharp 回退依赖可用；不要把未核实的包名和参数直接追加到命令。输出已存在或重命名异常：先选择新输出目录，或使用 --keep 避免同扩展名冲突。图片变大：源图可能已压缩，调整质量或选择适合内容的格式，并以视觉质量为准。批处理部分失败：目录分支会捕获单文件错误后继续，JSON 模式还不输出这些单文件错误，所以进程退出成功和 summary.totalFiles 都不能证明全部输入成功。必须对比原始清单与结果清单，必要时对失败文件单独诊断。Windows 工具检测异常：源码使用 which 而非原生 where，而 convert 也可能与系统命令重名；确认实际调用的是 ImageMagick。ImageMagick 无法判断输出格式：脚本用 .tmp 作为临时输出后缀，不能仅按安装成功推断转码成功；保留错误信息，不要自行改原图绕过。