Image Compress Skill

基于 sharp 的高效图片压缩技能，跨平台支持 (macOS/Windows/Linux)，平均节省 60-80% 体积。

何时使用

立即使用此技能当用户提到：

压缩体积 — "图片太大"、"压缩一下"、"缩小文件"、"发不了微信"
格式转换 — "转成 JPG"、"PNG 转 WebP"、"HEIC 转 JPG"、"转换格式"
批量处理 — "批量压缩"、"处理这个文件夹"、"所有图片"
尺寸调整 — "宽度太大"、"缩小到 1920px"、"用于网页展示"
场景优化 — "用于邮件附件"、"上传网站"、"电商展示"、"微信发送"

典型触发语句：

"帮我压缩这张图片，文件太大了发不了微信"
"把这个 PNG 转成 JPG 格式"
"这些照片是 iPhone 拍的 HEIC 格式，帮我转成 JPG"
"批量压缩这个文件夹里的所有图片，用于上传网站"
"图片宽度太大了，帮我缩小到 1920px 以内"
"把这些设计稿都转成 WebP 格式"
"压缩一下这张图用于邮件附件，控制在 500KB 以内"
"Screenshot.png 这个文件 10MB 太大了，怎么变小一点？"

不应触发的情况：

图片编辑（旋转、裁剪、拼接、添加水印）
图片分析（识别内容、读取 EXIF）
文件管理（上传云盘、设置为壁纸、删除、重命名、移动）
文档操作（添加到 PDF）

快速开始

基础命令

/compress <图片路径>

首次运行自动：

✅ 检测 Node.js 环境
✅ 安装 sharp 依赖
✅ 配置输出目录

常用场景

场景	命令
压缩单图	`/compress ~/Desktop/screenshot.png`
格式转换	`/compress image.png --format jpg`
调整画质	`/compress photo.jpg --quality 0.6`
限制尺寸	`/compress photo.jpg --maxWidth 1920`
批量压缩	`/compress ~/Photos/ --recursive`
使用预设	`/compress photo.jpg --preset web`
组合使用	`/compress ./pics/ --preset wechat --recursive`

压缩预设

快速选择适合场景的画质：

预设	画质	用途	节省
`web`	75%	网页展示	60-70%
`wechat`	65%	微信发送	70-80%
`email`	55%	邮件附件	80-90%
`quality`	95%	高质量存档	30-40%

示例：

# 网页优化
/compress photo.jpg --preset web

# 微信发送（体积优先）
/compress photo.jpg --preset wechat

# 邮件附件（最小体积）
/compress photo.jpg --preset email

# 高质量存档
/compress photo.jpg --preset quality

核心参数

压缩选项

参数	短参数	类型	默认值	说明
`--format`	`-f`	string	`original`	输出格式：`jpg`, `png`, `webp`, `avif`
`--quality`	`-q`	number	`0.85`	画质 (0.1-1.0)，越低体积越小
`--maxWidth`	`-w`	number	`null`	最大宽度（等比缩放）
`--maxHeight`	`-h`	number	`null`	最大高度（等比缩放）
`--recursive`	`-r`	boolean	`false`	递归处理子文件夹
`--outputDir`	`-o`	string	默认目录	自定义输出目录
`--preset`	`-p`	string	`无`	压缩预设：`web`, `wechat`, `email`, `quality`
`--no-confirm`		boolean	`false`	跳过确认提示

画质建议

使用预设更简单：

预设	画质	体积节省	用途
`web`	75%	60-70%	网页展示、博客文章
`wechat`	65%	70-80%	微信发送、社交媒体
`email`	55%	80-90%	邮件附件、快速传输
`quality`	95%	30-40%	高质量存档、打印

手动设置画质参考：

用途	推荐值	体积节省
网页展示	0.7-0.8	60-70%
微信发送	0.6-0.7	70-80%
邮件附件	0.5-0.6	80-90%
高质量存档	0.9-0.95	30-40%

输出规则

目录结构

~/Downloads/compressed-images/
├── 2026-03-11/
│   ├── photo.png           # 保持原名
│   ├── photo_001.png       # 同名自动编号
│   └── trip/image001.jpg   # 保持原目录结构
└── 2026-03-12/
    └── ...

安全保护

⚠️ 永不覆盖原图 — 输出到独立目录
⚠️ 永不覆盖输出 — 同名文件自动添加 _001, _002 后缀
⚠️ 大文件警告 — 单张超过 50MB 时先确认
⚠️ 进度显示 — 批量压缩时显示进度条

格式转换规则

转换	处理方式
PNG → JPG	透明通道用白色填充
JPG → PNG	直接转换
任意 → WebP	有损压缩（可指定 quality）
任意 → AVIF	高效压缩（可指定 quality）

脚本说明

环境检测

node scripts/detect-env.js

检测 Node.js/npm，缺失时给出安装建议。

依赖安装

node scripts/install.js

自动执行 npm install 安装 sharp。

核心压缩

# 单图
node scripts/compress.js ~/Pictures/photo.png --quality 0.8

# 批量
node scripts/compress.js ~/Pictures/ --recursive --format webp

编程调用：

import { compress } from './scripts/compress.js';

const result = await compress('/path/to/image.png', {
  quality: 0.85,
  format: 'webp',
  maxWidth: 1920
});

console.log(`压缩完成：${result.originalSize}KB → ${result.compressedSize}KB`);

详细 API 参考：references/technical.md

故障排查

sharp 安装失败

# 清理缓存
npm cache clean --force

# 重新安装
cd ~/.openclaw/workspace/skills/image-compress
npm install

权限问题

# macOS/Linux
chmod -R 755 ~/.openclaw/workspace/skills/image-compress

输出目录不可写

修改配置文件 ~/.openclaw/workspace/skills/image-compress/config.json 中的 outputDir。

支持格式

输入： JPG, JPEG, PNG, WebP, GIF, BMP, HEIC, HEIF

输出： JPG, PNG, WebP, AVIF

详细格式规格：references/technical.md

配置管理

配置文件：~/.openclaw/workspace/skills/image-compress/config.json

{
  "outputDir": "~/Downloads/compressed-images",
  "defaultQuality": 0.85,
  "defaultFormat": "original"
}

skill-image-compress