@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/agents/refs/ta-image-ops-reference.md

@@ -0,0 +1,495 @@
+> 本文件是 `playcraft image` 子命令的完整 CLI 参数速查表。生产上下文指南见 `playcraft-image-ops` skill。
+
+# PlayCraft 图形操作完整指南
+
+## 0. 命令总览
+
+所有命令均为 `playcraft image <子命令>` 格式，基于 sharp 本地处理，无需后端。
+
+| 命令        | 核心用途                      |
+| ----------- | ----------------------------- |
+| `crop`      | 精确裁切矩形区域              |
+| `overlay`   | 底图 + 叠加图合成             |
+| `pad`       | 扩展画布（加边距）            |
+| `trim`      | 自动裁掉透明/纯色边缘         |
+| `resize`    | 缩放                          |
+| `rotate`    | 旋转                          |
+| `flip`      | 水平/垂直翻转                 |
+| `blur`      | 高斯模糊                      |
+| `tint`      | 色调叠加                      |
+| `grayscale` | 灰度化                        |
+| `negate`    | 反色                          |
+| `convert`   | 格式转换（PNG/WebP/AVIF/JPG） |
+| `info`      | 查看尺寸/格式/文件大小        |
+
+---
+
+## 1. crop — 精确裁切
+
+### 基础用法
+
+```bash
+playcraft image crop \
+  --input assets/images/source.png \
+  --output assets/images/cropped.png \
+  --x 100 \      # 左边缘（像素，从左上角起）
+  --y 200 \      # 上边缘（像素）
+  --width 512 \  # 裁切宽度
+  --height 512   # 裁切高度
+```
+
+**参数说明**：`x` + `y` 是左上角起点坐标，`width` + `height` 是裁切区域大小。所有参数为像素整数。
+
+### 常用裁切模式
+
+#### 居中裁（最常用）
+
+从图片中心裁取目标尺寸：
+
+```bash
+# 从 1080×1920 图居中裁取 512×512
+# x = (1080 - 512) / 2 = 284
+# y = (1920 - 512) / 2 = 704
+playcraft image crop \
+  --input assets/images/bg/background.png \
+  --output assets/images/tiles/center_crop.png \
+  --x 284 --y 704 --width 512 --height 512
+```
+
+**居中裁公式**：
+
+- `x = (原图宽 - 目标宽) / 2`（取整）
+- `y = (原图高 - 目标高) / 2`（取整）
+
+#### 顶部裁（保留上半部分）
+
+```bash
+# 裁取图片顶部 1/3 区域
+playcraft image crop \
+  --input source.png \
+  --output top_crop.png \
+  --x 0 --y 0 --width 1080 --height 640
+```
+
+#### 提取局部区域（制作素材变体）
+
+```bash
+# 从精灵图提取单个帧（已知帧位置时用 crop，不规则布局用 sprite-split）
+playcraft image crop \
+  --input assets/images/tiles/tile_sheet.png \
+  --output assets/images/tiles/tile_001.png \
+  --x 0 --y 0 --width 128 --height 128
+
+# 提取第 2 帧（横向排列，每帧 128px）
+playcraft image crop \
+  --input assets/images/tiles/tile_sheet.png \
+  --output assets/images/tiles/tile_002.png \
+  --x 128 --y 0 --width 128 --height 128
+```
+
+### crop vs sprite-split 选型
+
+| 场景                       | 推荐                                          |
+| -------------------------- | --------------------------------------------- |
+| 精确知道帧位置（均匀网格） | `crop` 或 `sprite-split --rows N --columns N` |
+| 不规则布局 / 不知道帧位置  | `sprite-split --auto-detect`                  |
+| 只提取图片的一个局部区域   | `crop`                                        |
+
+> **注意**：`crop` 不支持在 `playcraft image batch --steps` 中使用（已知 CLI 限制，运行时报 `unsupported command "crop"`）。批量裁切请用 Node.js 脚本或 for 循环。
+
+---
+
+## 2. overlay — 合成叠图
+
+将一张图叠加在另一张图上。用于：添加阴影/光晕、叠加徽章/标签、合成多个素材层。
+
+### 基础用法
+
+```bash
+playcraft image overlay \
+  --base assets/images/bg/background.png \    # 底图（决定输出尺寸）
+  --overlay assets/images/ui/badge.png \      # 叠加图
+  --output assets/images/composite.png
+```
+
+输出尺寸 = 底图尺寸（与叠加图大小无关）。
+
+### Gravity 模式（对齐位置）
+
+不指定 `--x`/`--y` 时，用 `--gravity` 控制叠加图的对齐位置：
+
+| gravity 值       | 对齐位置 |
+| ---------------- | -------- |
+| `center`（默认） | 居中     |
+| `north`          | 顶部居中 |
+| `south`          | 底部居中 |
+| `east`           | 右侧居中 |
+| `west`           | 左侧居中 |
+| `northeast`      | 右上角   |
+| `northwest`      | 左上角   |
+| `southeast`      | 右下角   |
+| `southwest`      | 左下角   |
+
+```bash
+# 将徽章放在右上角
+playcraft image overlay \
+  --base assets/images/tiles/tile_001.png \
+  --overlay assets/images/ui/new_badge.png \
+  --output assets/images/tiles/tile_001_badge.png \
+  --gravity northeast
+
+# 将 CTA 按钮放在底部居中
+playcraft image overlay \
+  --base assets/images/bg/endcard_bg.png \
+  --overlay assets/images/ui/cta_button.png \
+  --output assets/images/endcard_composite.png \
+  --gravity south
+```
+
+### 精确定位（--x + --y）
+
+**同时提供** `--x` 和 `--y` 时，叠加图左上角放置在底图的 `(x, y)` 坐标处（忽略 gravity）：
+
+```bash
+# 精确放置：叠加图左上角在底图 (200, 150) 处
+playcraft image overlay \
+  --base assets/images/bg/background.png \
+  --overlay assets/images/ui/icon.png \
+  --output assets/images/composite.png \
+  --x 200 \
+  --y 150
+```
+
+### 典型场景配方
+
+#### 添加阴影（先生成阴影层再叠加）
+
+```bash
+# 1. 用 tint 把原图变成纯黑色版本作为阴影
+playcraft image tint \
+  --input assets/images/character.png \
+  --output /tmp/shadow.png \
+  --color "#000000"
+
+# 2. 把阴影叠加到背景，位置偏移 +4px
+playcraft image overlay \
+  --base assets/images/bg/background.png \
+  --overlay /tmp/shadow.png \
+  --output /tmp/bg_with_shadow.png \
+  --x 4 --y 4
+
+# 3. 再把原图叠到正确位置（居中）
+playcraft image overlay \
+  --base /tmp/bg_with_shadow.png \
+  --overlay assets/images/character.png \
+  --output assets/images/final_composite.png \
+  --gravity center
+```
+
+#### 给素材添加光晕边框
+
+```bash
+# 先 pad 扩大原图作为光晕层（用半透明背景），再叠回原图
+playcraft image pad \
+  --input assets/images/tiles/tile_001.png \
+  --output /tmp/glow_layer.png \
+  --all 8 \
+  --background "#FFD70088"   # 半透明金色
+
+playcraft image overlay \
+  --base /tmp/glow_layer.png \
+  --overlay assets/images/tiles/tile_001.png \
+  --output assets/images/tiles/tile_001_glow.png \
+  --gravity center
+```
+
+---
+
+## 3. pad — 扩展画布
+
+在图片四周添加边距，常用于：统一精灵图尺寸、添加安全边距、适配不同宽高比。
+
+### 基础用法
+
+```bash
+# 四边均等扩展 16px（透明填充）
+playcraft image pad \
+  --input assets/images/tiles/tile_001.png \
+  --output assets/images/tiles/tile_001_padded.png \
+  --all 16
+
+# 四边分别指定
+playcraft image pad \
+  --input assets/images/ui/button.png \
+  --output assets/images/ui/button_safe.png \
+  --top 24 \
+  --bottom 24 \
+  --left 32 \
+  --right 32 \
+  --background "#00000000"   # 透明（默认）
+```
+
+### 典型场景
+
+#### 统一精灵图尺寸（大小不一的图片变成相同画布）
+
+```bash
+# 将 96×112 的角色精灵扩展到 128×128（居中内容）
+# top = (128-112)/2 = 8, bottom = 8, left = (128-96)/2 = 16, right = 16
+playcraft image pad \
+  --input assets/images/character_sprite.png \
+  --output assets/images/character_128x128.png \
+  --top 8 --bottom 8 --left 16 --right 16
+```
+
+#### 添加安全边距（防止 UI 元素贴边）
+
+```bash
+playcraft image pad \
+  --input assets/images/ui/cta_button.png \
+  --output assets/images/ui/cta_button_safe.png \
+  --all 48 \
+  --background "#00000000"
+```
+
+#### 白色/彩色填充背景（不透明）
+
+```bash
+playcraft image pad \
+  --input assets/images/icon.png \
+  --output assets/images/icon_white_bg.png \
+  --all 20 \
+  --background "#FFFFFF"
+```
+
+---
+
+## 4. trim — 自动裁掉边缘
+
+自动检测并移除图片边缘的透明区域或纯色边缘。常用于：精灵图去白边、AI 生成图去冗余透明边。
+
+```bash
+# 移除透明边缘（默认阈值 10）
+playcraft image trim \
+  --input assets/images/tiles/tile_001.png \
+  --output assets/images/tiles/tile_001_trimmed.png
+
+# 调整阈值（0-255，越高容错越大）
+# 阈值 30：稍微偏白的背景也会被裁掉
+playcraft image trim \
+  --input assets/images/ui/icon.png \
+  --output assets/images/ui/icon_trimmed.png \
+  --threshold 30
+```
+
+**什么时候用 trim**：
+
+- AI 生成的图片四周有半透明区域
+- 精灵图合并前需要统一去掉白色/透明边距
+- `remove-background` 处理后的图片有冗余透明像素
+
+**trim 后通常接 pad**：先 trim 去掉不需要的边，再 pad 统一添加所需的安全边距。
+
+---
+
+## 5. rotate / flip — 旋转与翻转
+
+```bash
+# 旋转 90 度（顺时针），填充透明
+playcraft image rotate \
+  --input assets/images/arrow.png \
+  --output assets/images/arrow_rotated.png \
+  --angle 90
+
+# 旋转并指定填充色
+playcraft image rotate \
+  --input assets/images/bg/background.png \
+  --output assets/images/bg/background_rotated.png \
+  --angle 15 \
+  --background "#1A1A2E"
+
+# 水平翻转（左右镜像）
+playcraft image flip \
+  --input assets/images/character/run_right.png \
+  --output assets/images/character/run_left.png \
+  --direction horizontal
+
+# 垂直翻转（上下镜像）
+playcraft image flip \
+  --input assets/images/tiles/water.png \
+  --output assets/images/tiles/water_flipped.png \
+  --direction vertical
+```
+
+**典型用途**：
+
+- `rotate 90/180/270`：调整素材方向
+- `flip horizontal`：从"向右跑"生成"向左跑"，节省一半动画生成成本
+- `rotate 15` + 透明背景：制作倾斜装饰元素
+
+---
+
+## 6. 滤镜命令（blur / tint / grayscale / negate）
+
+### blur — 高斯模糊
+
+```bash
+# sigma 越大，模糊程度越高（默认 3）
+playcraft image blur \
+  --input assets/images/bg/background.png \
+  --output assets/images/bg/background_blurred.png \
+  --sigma 8
+
+# 背景虚化（大 sigma）
+playcraft image blur --input bg.png --output bg_bokeh.png --sigma 15
+```
+
+**典型用途**：背景虚化强调前景角色；制作毛玻璃效果底图；对参考图模糊处理减少 AI 参考图的细节影响。
+
+### tint — 色调叠加
+
+```bash
+# 整体染色（不影响透明通道）
+playcraft image tint \
+  --input assets/images/tiles/tile_001.png \
+  --output assets/images/tiles/tile_001_gold.png \
+  --color "#FFD700"
+
+# 制作禁用状态（灰色叠加）
+playcraft image tint \
+  --input assets/images/ui/button.png \
+  --output assets/images/ui/button_disabled.png \
+  --color "#808080"
+```
+
+**注意**：tint 是颜色混合，不是替换颜色。深色图像 tint 效果不明显，用 `overlay` + 纯色图层效果更可控。
+
+### grayscale — 灰度化
+
+```bash
+playcraft image grayscale \
+  --input assets/images/tiles/tile_001.png \
+  --output assets/images/tiles/tile_001_gray.png
+```
+
+**典型用途**：制作"锁定/未解锁"状态的灰色版本素材；从彩色图快速生成黑白版本作为蒙版参考。
+
+### negate — 反色
+
+```bash
+playcraft image negate \
+  --input assets/images/ui/icon.png \
+  --output assets/images/ui/icon_inverted.png
+
+# 仅反色 RGB，保留透明通道
+playcraft image negate \
+  --input assets/images/ui/icon.png \
+  --output assets/images/ui/icon_inverted.png \
+  --no-alpha
+```
+
+---
+
+## 7. convert — 格式转换
+
+```bash
+# 转换为 WebP（有损，质量 85）
+playcraft image convert \
+  --input assets/images/bg/background.png \
+  --output assets/images/bg/background.webp \
+  --format webp \
+  --quality 85
+
+# 转换为 WebP 无损（适合像素艺术和 UI）
+playcraft image convert \
+  --input assets/images/ui/icon.png \
+  --output assets/images/ui/icon.webp \
+  --format webp \
+  --lossless
+
+# 转换为 AVIF（更小体积，兼容性稍差）
+playcraft image convert \
+  --input assets/images/bg/background.png \
+  --output assets/images/bg/background.avif \
+  --format avif \
+  --quality 80
+```
+
+**格式选型建议**（生产阶段）：
+
+- 生产阶段统一用 **PNG**（无损，最大兼容性，方便后续处理）
+- 格式转换交给构建阶段的 `playcraft build --convert-webp` 批量处理
+
+---
+
+## 8. info — 查看图片信息
+
+```bash
+# 查看尺寸、格式、文件大小
+playcraft image info --input assets/images/bg/background.png
+
+# JSON 格式输出（方便脚本解析）
+playcraft image info --input assets/images/bg/background.png --json
+```
+
+输出包含：`width`、`height`、`format`、`channels`、`size`（字节）、`hasAlpha`。
+
+---
+
+## 9. 完整参数速查表
+
+| 命令        | 必填参数                                                 | 可选参数                                           | 默认值         |
+| ----------- | -------------------------------------------------------- | -------------------------------------------------- | -------------- |
+| `crop`      | `--input --output --x --y --width --height`              | —                                                  | —              |
+| `overlay`   | `--base --overlay --output`                              | `--x --y --gravity`                                | gravity=center |
+| `pad`       | `--input --output`                                       | `--top --bottom --left --right --all --background` | 0px / 透明     |
+| `trim`      | `--input --output`                                       | `--threshold`                                      | 10             |
+| `resize`    | `--input --output` + (`--width`/`--height` 或 `--scale`) | `--fit`                                            | fit=cover      |
+| `rotate`    | `--input --output --angle`                               | `--background`                                     | 透明           |
+| `flip`      | `--input --output`                                       | `--direction`                                      | horizontal     |
+| `blur`      | `--input --output`                                       | `--sigma`                                          | 3              |
+| `tint`      | `--input --output --color`                               | —                                                  | —              |
+| `grayscale` | `--input --output`                                       | —                                                  | —              |
+| `negate`    | `--input --output`                                       | `--no-alpha`                                       | —              |
+| `convert`   | `--input --output`                                       | `--format --quality --lossless`                    | quality=85     |
+| `info`      | `--input`                                                | `--json`                                           | —              |
+
+---
+
+## 10. 常用组合配方
+
+### 配方 A：统一精灵图尺寸
+
+```bash
+# 1. 裁掉冗余透明边
+playcraft image trim --input raw_sprite.png --output /tmp/trimmed.png
+
+# 2. 用 pad 统一到目标尺寸（128×128）
+# （trim 后获取尺寸：playcraft image info --input /tmp/trimmed.png --json）
+playcraft image pad \
+  --input /tmp/trimmed.png \
+  --output final_sprite_128x128.png \
+  --top 8 --bottom 8 --left 16 --right 16
+```
+
+### 配方 B：制作"选中高亮"效果
+
+```bash
+# 1. 生成发光边框层（pad + tint）
+playcraft image pad --input tile.png --output /tmp/glow.png --all 6 --background "#FFD70099"
+# 2. 把原图叠回
+playcraft image overlay --base /tmp/glow.png --overlay tile.png --output tile_selected.png --gravity center
+```
+
+### 配方 C：批量生成镜像动画帧
+
+```bash
+# 已有向右跑的动画帧，批量生成向左跑
+for f in assets/images/character/run_right_*.png; do
+  name=$(basename "$f" .png)
+  playcraft image flip \
+    --input "$f" \
+    --output "assets/images/character/${name/right/left}.png" \
+    --direction horizontal
+done
+```