@playcraft/cli 0.1.53-beta → 0.1.54

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

@@ -1,495 +0,0 @@
-> 本文件是 `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
-```