---
name: "tuxu-image-tools"
display_name: "图序图片工具"
display_name_en: "Tuxu Image Tools"
description: "在用户电脑本机批量处理图片（图片不上传）：压缩图片、压到指定KB、批量压缩、格式转换、转WebP、转JPG、转PNG、改尺寸、证件照尺寸、改分辨率、裁剪、加水印、文字水印、加边框、画布留白、旋转、翻转、批量处理图片、批量改尺寸。用户提到处理图片/照片的任何上述需求时使用本技能。"
description_zh: "图序图片工具：在本机批量压缩图片（可压到指定KB）、JPG/PNG/WebP互转、改尺寸与证件照尺寸、按比例裁剪、加文字水印、加边框、画布留白、旋转翻转。图片全程留在用户电脑，不上传任何服务器。"
description_en: "Tuxu Image Tools: batch-process images locally on the user's machine (images never uploaded) — compress to a target size in KB, convert between JPG/PNG/WebP, resize with presets (e-commerce, social media, ID photos), crop by ratio, add text watermarks, borders, pad canvas to a ratio, rotate and flip."
version: "1.0.1"
slug: tuxu-image-tools
displayName: 图序图片工具
summary: 在本机批量压缩、转格式、改尺寸、加水印处理图片，图片全程留在本机、不上传
license: MIT
author: "kaiw800"
allowed-tools: "Bash"
---

# 图序图片工具（tuxu-image-tools）

在用户电脑**本机**处理图片的命令行工具集。图片全程不出用户电脑：脚本除首次安装依赖（npm 安装 sharp）外不联网、不采集、不上传任何数据。

## 第一步（必须先做）

**每次会话第一次使用本技能时，先运行环境自检，再处理图片：**

```bash
node scripts/env-check.mjs
```

- 输出 `"ok": true` → 环境就绪，直接继续。
- 输出 `"ok": false` → 会尝试自动安装依赖；仍失败时，把 JSON 里 `error.hint` 的安装指引**原文**转告用户，不要自己编步骤。
- 若某个功能脚本报 `ENV_MISSING`（exit 3），同样先运行上面的自检。

## 调用约定

- 输入：`--input` 接**单个文件**或**文件夹**（文件夹 = 批量，最多 200 张，不递归子文件夹）。路径含空格或中文**必须用引号包裹**。也可以把路径作为第一个位置参数。
- 输出：**默认写入新目录 `<输入位置>/tuxu-output/<子命令>/`（按子命令分目录，多步处理的结果互不覆盖），绝不覆盖原图**。可用 `--output` 指定其他目录。
- 结果：stdout 输出一份 JSON（`summary` 一行摘要 + `files` 每个文件成败与输入/输出路径）。stderr 是过程日志，可忽略。
- 退出码：`0` 全部成功；`1` 参数错误；`2` 文件/格式错误（含部分文件失败）；`3` 环境依赖缺失。
- 所有脚本都支持 `--help` 查看参数。
- 输出文件名与原图同名（转换格式时换扩展名）。

## 能力与子命令

### 1. compress — 压缩图片

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--input` | 路径 | 是 | - | 文件或文件夹 |
| `--target-size` | 如 `200KB`、`1.5MB` | 与quality二选一 | - | 压到指定体积（不超过为目标） |
| `--quality` | 1-100 整数 | 与target-size二选一 | 80 | 按质量压缩 |
| `--format` | jpg/png/webp | 否 | 保持原格式 | |
| `--output` | 目录 | 否 | `tuxu-output/` | |

```bash
node scripts/compress.mjs --input "D:/照片/旅游照" --target-size 200KB
```
结果示例（所有子命令的 JSON 结构相同）：
```json
{
  "ok": true,
  "partial": false,
  "command": "compress",
  "summary": "处理完成：成功 3 张，失败 0 张",
  "outputDir": "D:/照片/旅游照/tuxu-output/compress",
  "files": [
    { "input": "D:/照片/旅游照/a.jpg", "output": "D:/照片/旅游照/tuxu-output/compress/a.jpg",
      "ok": true, "format": "jpeg", "width": 1200, "height": 1600,
      "sizeBefore": 1818700, "sizeAfter": 203186, "quality": 23 }
  ]
}
```
说明：PNG 压到指定体积时使用调色板量化（`quality` 字段为色板色数）；若最低质量仍压不到目标，会输出尽力结果并在 `warning` 里如实说明。

### 2. convert — 格式转换

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--format` | jpg/png/webp | **是** | - | 目标格式 |
| `--quality` | 1-100 | 否 | 80 | JPG/WebP 有效 |
| `--input` / `--output` | | 是/否 | | 同上 |

```bash
node scripts/convert.mjs --input "D:/截图" --format webp
```
说明：含透明通道的图转 JPG 时自动铺白底。

### 3. resize — 调整尺寸

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--preset` | 预设名或 `800x800` | 三选一 | - | 商品主图/详情页/公众号封面/小红书竖图/视频封面/一寸/二寸（详见 references/presets.md） |
| `--percent` | 1-1000 | 三选一 | - | 百分比缩放，如 `50` |
| `--width` / `--height` | 像素 | 三选一 | - | 只给其一则等比缩放 |
| `--fit` | cover/contain/stretch | 否 | cover | 两维都给时：cover 裁满、contain 完整留白、stretch 拉伸 |
| `--background` | 颜色 | 否 | JPG白/PNG与WebP透明 | contain 的留白底色 |
| `--no-upscale` | 旗标 | 否 | - | 不放大 |

```bash
node scripts/resize.mjs --input "D:/图" --preset 小红书竖图
node scripts/resize.mjs --input photo.jpg --width 800
```

### 4. crop — 裁剪

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--ratio` | 如 `1:1`、`3:4` | 三选一 | - | 按比例取最大裁剪 |
| `--width` + `--height` | 像素 | 三选一 | - | 裁指定大小（居中/锚点） |
| `--region` | `x,y,宽,高` | 三选一 | - | 按坐标精确裁剪 |
| `--anchor` | 九宫格位置 | 否 | center | top-left…bottom-right |

```bash
node scripts/crop.mjs --input "D:/图" --ratio 1:1
```

### 5. rotate — 旋转与翻转

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--angle` | 90/180/270 | 否 | - | 顺时针旋转 |
| `--flip-horizontal` / `--flip-vertical` | 旗标 | 否 | - | 水平/垂直翻转 |
| 三个都不给 | | - | - | 仅按 EXIF 自动摆正（手机照片横竖不对时用） |

```bash
node scripts/rotate.mjs --input "D:/手机照片"
```
说明：所有脚本读图时都会自动按 EXIF 摆正方向。

### 6. watermark — 文字水印（图片 Logo 水印在二期）

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--text` | 文字 | **是** | - | 水印内容 |
| `--position` | 九宫格位置 | 否 | bottom-right | |
| `--tile` | 旗标 | 否 | - | -30° 平铺整图 |
| `--font-size` | 像素 | 否 | 短边6% | |
| `--color` | 如 `#ffffff` | 否 | 白 | 支持 #RRGGBB(AA) |
| `--opacity` | 0.01-1 | 否 | 0.7 | |
| `--offset-x` / `--offset-y` | 像素 | 否 | 0 | |

```bash
node scripts/watermark.mjs --input "D:/样图" --text "仅供演示"
```

### 7. border — 边框

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--width` | 像素 | 至少其一 | 0 | 边框宽度（向外扩展） |
| `--padding` | 像素 | 至少其一 | 0 | 图片与边框间的内边距留白 |
| `--color` | 颜色 | 否 | #000000 | 边框颜色 |
| `--padding-color` | 颜色 | 否 | #ffffff | 内边距颜色 |

```bash
node scripts/border.mjs --input photo.jpg --width 16 --padding 24 --padding-color "#f5f5f5"
```

### 8. pad — 画布留白

| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
| `--ratio` | 如 `1:1` | 三选一 | - | 留白到目标宽高比（图片不缩放只补边） |
| `--preset` | 预设名 | 三选一 | - | 留白到预设尺寸 |
| `--width` + `--height` | 像素 | 三选一 | - | 精确画布尺寸（图片偏大时等比缩小放入） |
| `--background` | 颜色或 transparent | 否 | #ffffff | 留白底色 |
| `--anchor` | 九宫格位置 | 否 | center | |

```bash
node scripts/pad.mjs --input "D:/商品图" --preset 商品主图 --background "#ffffff"
```

## 不支持（请勿调用本技能，直接告知用户暂不支持）

- **抠图 / 去背景 / 换底色**
- **色彩调整**（亮度 / 对比度 / 饱和度 / 滤镜 / 灰度）
- **HEIC / AVIF / GIF 动图** 的输入或转换（含「iPhone 的 HEIC 转 JPG」）
- **PDF**（图片转 PDF、PDF 转图片）
- **证件照成套出图**（人像排版、换底、美颜；只支持把已有照片改成 1 寸/2 寸的**尺寸**）
- **图片 Logo / 印章水印**（目前仅文字水印）
- 任意角度旋转（仅 90/180/270）

用户提出以上需求时，明确说明本技能暂不支持，不要尝试用本技能变通处理。

## 批量处理

- 把 `--input` 指向文件夹即为批量（不递归，最多 200 张）；每张图的成败在结果 JSON 的 `files` 数组里。
- 不受支持的文件会被跳过并在 stderr 提示，不会中断整批。
- 部分文件失败时整体退出码为 2，但成功的文件已正常输出，把失败清单转告用户即可。

## 破坏性操作规则（红线）

1. **默认绝不覆盖原图**：输出固定写入新的 `tuxu-output/<子命令>/` 目录（按子命令分目录）；脚本还会拒绝「输出路径与原图相同」的操作。
2. 只有当**用户明确要求覆盖原图**时才考虑 `--output` 指向原目录，且**必须先向用户确认**「会覆盖原图，确定吗？」得到肯定答复后再执行。
3. 除此之外任何会改动用户文件的操作（删除、移动、改名）都不属于本技能范围。

## 错误处理

- 脚本失败时，把 JSON 中 `error.message`（以及 `error.hint`）**原文**转述给用户；**不要猜测或编造原因**，不要把堆栈原文丢给用户。
- 退出码含义：`1` 参数错误（检查命令参数）、`2` 文件/格式问题（见 references/presets.md 的「常见错误与恢复指引」）、`3` 环境问题（回到第一步运行 env-check）。
- 提示用户某个具体文件失败时，引用该文件在 `files` 里的 `error` 字段。
- 预设名、调用写法、错误恢复顺序的完整说明在 [references/presets.md](references/presets.md)。