baoyu-compress-image

# baoyu-compress-image

## 简介

基于系统中**可用性最高**的图像处理工具链进行压缩：
`sips`（macOS 原生）→ `cwebp`（WebP 官方编码器）→ `ImageMagick` → `Sharp`（Node.js 高性能库）。

---

## 脚本目录

主脚本位于 `scripts/main.ts`，为 TypeScript 编写的 CLI 入口。

- `{baseDir}` 表示当前技能文档（如 `SKILL.md`）所在目录路径；
- `${BUN_X}` 为运行时解析的执行命令：
  - 若已安装 `bun` → 使用 `bun`；
  - 否则若 `npx` 可用 → 使用 `npx -y bun`；
  - 否则提示用户安装 [Bun](https://bun.sh)。

> ✅ 实际使用时，请将 `{baseDir}` 和 `${BUN_X}` 替换为真实路径与命令。

| 脚本 | 用途 |
|------|------|
| `scripts/main.ts` | 图像压缩命令行接口（CLI） |

---

## 配置文件（EXTEND.md）

工具支持多级配置，按以下优先级查找 `EXTEND.md`：

### Unix-like 系统（macOS / Linux / WSL / Git Bash）
```sh
test -f .baoyu-skills/baoyu-compress-image/EXTEND.md && echo "project"
test -f "${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-compress-image/EXTEND.md" && echo "xdg"
test -f "$HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md" && echo "user"
```

### Windows（PowerShell）
```powershell
if (Test-Path .baoyu-skills/baoyu-compress-image/EXTEND.md) { "project" }
$xdg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$HOME/.config" }
if (Test-Path "$xdg/baoyu-skills/baoyu-compress-image/EXTEND.md") { "xdg" }
if (Test-Path "$HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md") { "user" }
```

### 配置路径说明

| 路径 | 位置 |
|------|------|
| `.baoyu-skills/baoyu-compress-image/EXTEND.md` | 当前项目目录 |
| `$HOME/.baoyu-skills/baoyu-compress-image/EXTEND.md` | 用户主目录 |
| `${XDG_CONFIG_HOME:-$HOME/.config}/baoyu-skills/baoyu-compress-image/EXTEND.md` | XDG 标准配置目录 |

### 查找结果行为

| 结果 | 行为 |
|------|------|
| 找到 | 解析并应用其中的配置项 |
| 未找到 | 使用内置默认值 |

✅ `EXTEND.md` 支持配置：
- 默认输出格式（`format`）
- 默认质量（`quality`）
- 是否保留原图（`keepOriginal`）

---

## 使用方法

```bash
${BUN_X} {baseDir}/scripts/main.ts [选项]
```

---

## 选项说明

| 选项 | 简写 | 描述 | 默认值 |
|------|------|------|--------|
| `<input>` | — | 输入文件或目录（必需） | — |
| `--output`, `-o` | `-o` | 输出路径（若为目录则保持结构） | 同名新扩展名（如 `img.png` → `img.webp`） |
| `--format`, `-f` | `-f` | 输出格式：`webp` / `png` / `jpeg` | `webp` |
| `--quality`, `-q` | `-q` | 压缩质量（0–100） | `80` |
| `--keep`, `-k` | `-k` | 保留原始文件 | `false` |
| `--recursive`, `-r` | `-r` | 递归处理子目录 | `false` |
| `--json` | — | 以 JSON 格式输出结果 | `false` |

---

## 示例

```bash
# 单图转 WebP（覆盖原图）
${BUN_X} {baseDir}/scripts/main.ts image.png

# 保持 PNG 格式并保留原图
${BUN_X} {baseDir}/scripts/main.ts image.png -f png --keep

# 递归压缩整个目录，质量设为 75
${BUN_X} {baseDir}/scripts/main.ts ./images/ -r -q 75

# JSON 格式输出（便于脚本集成）
${BUN_X} {baseDir}/scripts/main.ts image.png --json
```

✅ 标准输出示例：
```
image.png → image.webp (245KB → 89KB, 64% reduction)
```

---

## 扩展支持

通过 `EXTEND.md` 可自定义全局偏好。详见「配置文件（EXTEND.md）」章节。