@playcraft/cli 0.0.40 → 0.0.42

package/project-template/.claude/skills/playcraft-image-generation/SKILL.md

@@ -0,0 +1,279 @@
+---
+name: playcraft-image-generation
+description: PlayCraft AI 图片生成核心决策指南。涵盖模型选择决策树、核心命令模板、背景处理决策树（绿幕策略）、脚本决策规则。精灵图直出/Edit 模型/错误恢复/批量实践等进阶内容见 refs/ta-image-generation-detail.md。
+triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
+---
+
+# PlayCraft AI 图片生成指南
+
+## 0. 开始前必读
+
+生图前**必须先运行模型发现命令**：
+
+```bash
+playcraft tools list-image-models
+```
+
+输出示例：
+
+```
+MODEL                                        CAPABILITY   ALPHA  PROVIDERS
+gpt-image-2                                  text+image   no     3 (iegg-litellm, mulerouter, 302)
+gemini-3.1-flash-image-preview               text+image   no     2 (google, iegg-litellm)
+hy-image-v3.0                                text+image   no     1 (tencent-cloud)
+flux-kontext-pro                             text+image   no     1 (302)
+qwen-image-edit-max                          image→image  no     1 (mulerouter)
+...
+```
+
+**列说明**：
+
+- `CAPABILITY`：`text→image` 仅文生图 / `image→image` 仅图生图 / `text+image` 两者均支持
+- `ALPHA`：`yes` = 原生透明 PNG；`no` = 需使用绿幕策略（见第 3 节）
+- `PROVIDERS`：支持该模型的 provider 数量，多个 provider 时后端按优先级自动 fallback（顺序尝试，首个成功即返回）
+
+**Prompt 套路速查**：[reference/prompt-cookbook.md](reference/prompt-cookbook.md)
+
+---
+
+## 1. 模型选择决策树
+
+```
+需要生图？
+├─ 追求最高质量（概念图、精品单图）？
+│  └─ gpt-image-2（3 个 provider 自动 fallback：iegg-litellm → mulerouter → 302）
+│
+├─ 需要 --reference-image（风格一致性批量生产）？
+│  └─ 必须选 CAPABILITY = text+image 或 image→image 的模型
+│
+├─ 同类元素批量生成（<=16 个）？
+│  └─ 精灵图直出策略（见进阶参考）
+│
+├─ 结构相似的变体集（换花色/换数字/换颜色）？
+│  └─ Edit 模型工作流（见进阶参考）
+│
+└─ 不确定？
+   └─ 先试 gpt-image-2，失败换 gemini-3.1-flash-image-preview
+```
+
+### 主要模型特性
+
+| 模型                               | 特点与优势                                                                                  | 最佳场景                                        | 速度                            | 注意事项                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
+| **gpt-image-2**                    | 细节最丰富、光影最真实、网格/布局理解力最强、中文字符准确率最高、3 provider fallback 容错高 | 概念图、精灵图直出、含文字素材、写实/半写实风格 | 慢(7-8min/张)，**不设 timeout** | 慢是正常的；只有 `API 500` / `fetch failed` 才切换下一 provider |
+| **gemini-3.1-flash-image-preview** | 速度快、色彩鲜艳、构图清晰、最稳定不易报错、reference-image 理解好                          | 快速迭代、扁平卡通、明亮休闲风、超时回退        | 快(<30s)                        | 精细细节和文字不如 gpt-image-2                                  |
+| **hy-image-v3.0**                  | 亚洲审美偏向、角色设计好、Q版/IP风格擅长                                                    | 中国风、Q版角色、IP 形象                        | 中等                            | 西方写实风格表现一般                                            |
+| **flux-kontext-pro**               | 艺术感强、风格独特、手绘质感好                                                              | 艺术插画、手绘风、独特画风探索                  | 中等                            | 网格理解弱，不适合精灵图                                        |
+| **nano-banana-2**                  | 最快、适合简单图形探索                                                                      | 简洁图标、平面设计、快速草稿                    | 极快                            | 中文字符不可靠、细节少                                          |
+| **qwen-image-edit-max**            | 图生图编辑能力强、局部修改精确                                                              | 换花色/换数字/换颜色等结构相似变体              | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
+| **wan2.6-image**                   | 风格迁移能力好                                                                              | 将参考图风格应用到新内容                        | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
+
+### 选型口诀
+
+- 追求质量 / 含文字 / 网格图 → `gpt-image-2`
+- 快速迭代 / 扁平风格 / 回退备选 → `gemini-3.1-flash-image-preview`
+- 中国风 / Q版 / 亚洲审美 → `hy-image-v3.0`
+- 艺术/手绘探索 → `flux-kontext-pro`
+- 纯 edit 变体 → `qwen-image-edit-max`
+- 一切都失败 → `gemini-3.1-flash-image-preview`（最稳定）
+
+### 为什么精灵图直出是首选批量策略？
+
+精灵图直出（一次 API 调用生成一张包含 N 个元素的网格图，再 sprite-split 切分）优于逐个生成，原因有三：
+
+1. **成本**：一次 API 调用可包含 4-16 个元素，而逐个生成 N 个元素需要 N 次调用，成本和耗时线性增长。
+2. **风格一致性**：同一张图中的所有元素共享相同的生成上下文，天然保证色调、线条、阴影风格统一，避免逐个生成时每张图风格漂移的问题。
+3. **无逐元素偏差**：逐个生成时即使用相同 prompt，模型每次采样结果都不同，元素之间会出现肉眼可见的不一致；精灵图在一次推理中完成，消除了这种 per-element drift。
+
+详细策略与代码示例见进阶参考。
+
+---
+
+## 2. 核心命令
+
+### 文生图（text-to-image）
+
+```bash
+playcraft tools generate-image \
+  --prompt "A golden sword icon, flat 2D vector style, centered composition" \
+  --output assets/images/sword.png \
+  --aspect-ratio 1:1 \
+  --image-size 4K \
+  --image-model gpt-image-2
+```
+
+### 图生图（image-to-image / reference-image）
+
+```bash
+playcraft tools generate-image \
+  --prompt "A similar style silver shield icon, same art direction" \
+  --output assets/images/shield.png \
+  --reference-image assets/images/sword.png \
+  --aspect-ratio 1:1 \
+  --image-size 4K \
+  --image-model gpt-image-2
+```
+
+### 参数说明
+
+| 参数                   | 值                                        | 说明                                                    |
+| ---------------------- | ----------------------------------------- | ------------------------------------------------------- |
+| `--aspect-ratio`       | `1:1` / **`45:16`** / `16:9` / `9:16` / … | **Master Composite（5×9:16 横排）用 `45:16`**           |
+| `--width` / `--height` | 像素整数（成对）                          | MC 推荐 **`3600×1280`** 或 **`4096×1455`**              |
+| `--image-size`         | `1K` / `2K` / `4K`                        | 控制分辨率级别。实际像素取决于模型+比例的组合（见下表） |
+
+**`--image-size` 对 gpt-image-2 的落盘尺寸**（MuleRouter 请求 `size=auto`，由后端 letterbox 到目标像素）：
+
+| aspectRatio                   | 1K        | 2K            | 4K            |
+| ----------------------------- | --------- | ------------- | ------------- |
+| 1:1                           | 1024x1024 | 2048x2048     | 2048x2048     |
+| **45:16** (5×9:16 故事板横排) | 2048x728  | **3600x1280** | **4096x1455** |
+| 16:9                          | 2048x1152 | 2048x1152     | 3840x2160     |
+| 9:16                          | 2160x3840 | 2160x3840     | 2160x3840     |
+| 3:2 / 4:3                     | 1536x1024 | 1536x1024     | 1536x1024     |
+| 21:9                          | 2048x1152 | 3840x2160     | 3840x2160     |
+
+> **IEGG LiteLLM** 在 fallback 链中排第一，但 Azure gpt-image 最大约 1536px 宽 — 达不到 5×9:16 横排。故事板请用 **`mulerouter/gpt-image-2`**（跳过 litellm）+ `--width 3600 --height 1280`（或 4096×1455）。
+
+### Master Composite（MC）模型白名单
+
+Designer 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux / hy-image 等——MC 只允许：
+
+| 允许                       | 禁止（MC）                                          |
+| -------------------------- | --------------------------------------------------- |
+| `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
+| `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
+
+完整 prompt / 尺寸规范见 **`playcraft-storyboard`** skill。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+
+**Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
+**Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
+
+### --reference-image 路径支持
+
+- 本地绝对路径：`/path/to/ref.png`
+- 相对路径（相对 CWD）：`assets/images/ref.png`
+- HTTP(S) URL（CLI 自动下载）：`"https://images.unsplash.com/photo-xxx"`
+- 多张参考图（重复选项，最多 8 张）
+- 混合本地文件 + URL
+- `search-image` 返回的 `downloadUrl` 可直接使用
+
+### 常用辅助命令
+
+```bash
+# 去背景（绿幕建议 tolerance=25；默认白背景可用 15）
+playcraft image remove-background --input in.png --output out.png --tolerance 25
+
+# 缩放
+playcraft image resize --input in.png --output out.png --width 128 --height 128
+
+# 精灵图切分
+playcraft image sprite-split \
+  --input sheet.png --output-dir frames/ \
+  --rows 2 --columns 4 \
+  --frame-width <总宽/4> --frame-height <总高/2>
+
+# 合并精灵图
+playcraft image sprite-sheet \
+  --input-dir processed/ --output bundle \
+  --columns 8 --background white
+```
+
+---
+
+## 3. 背景处理决策树
+
+> **核心原则**：先确定素材类型，再决定是否需要去背景，再按素材主色调选择色幕颜色，最后做去背景 + 深色背景验证。
+
+```
+生成的素材需要做什么？
+│
+├─ 需要透明背景的独立元素（角色、道具、图标、文字图片、HUD、VFX）？
+│   ├─ 检查模型 ALPHA 列（playcraft tools list-image-models）
+│   ├─ ALPHA = yes → prompt 加 "transparent background, PNG with alpha"
+│   └─ ALPHA = no  → 色幕策略（按素材主色调选择）：
+│       ├─ 素材为金色/黄色/橙色/绿色 → 蓝幕 #0000FF
+│       │   ├─ prompt 末尾加 "on solid bright blue #0000FF background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       ├─ 素材为蓝色/紫色/靛蓝 → 绿幕 #00FF00
+│       │   ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│       │   └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│       └─ 其他颜色 → 绿幕 #00FF00（默认）
+│           ├─ prompt 末尾加 "on solid bright green #00FF00 background, isolated, centered"
+│           └─ 后处理：remove-background（tolerance 25）→ 深色背景验证
+│
+├─ 卡牌/棋盘格子/UI 面板（本身就是矩形有边框）？
+│   ├─ 不要去背景！白色牌面就是牌的一部分
+│   ├─ prompt 加 "flat 2D, no drop shadow, no 3D effect, clean edges"
+│   └─ 后处理：直接 resize（skipRemoveBg = true）
+│
+└─ 场景背景（天空、地面、全屏图）？
+    ├─ 不做背景处理，直接 resize
+    └─ ⚠️ prompt 必须加 "full bleed, edge to edge, no vignette, no fade"
+       → 后处理验证：四角四边颜色一致，无褪色/白色
+```
+
+### 为什么需要色幕策略？
+
+**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
+
+### 色幕选型矩阵（Color Conflict Avoidance）
+
+> ⚠️ **不要默认全用绿幕！** 金色素材 + 绿幕 = 绿色与金色色相接近，floodfill 会在边缘残留绿色，或误删金色像素。
+
+| 素材主色调            | ❌ 禁用 | ✅ 推荐          | 原因                                       |
+| --------------------- | ------- | ---------------- | ------------------------------------------ |
+| 金色/黄色/橙色/琥珀色 | 绿幕    | **蓝幕 #0000FF** | 金色与绿色色相接近（黄绿区），边缘残留绿色 |
+| 绿色/翠绿/青色        | 绿幕    | **蓝幕 #0000FF** | 同色系，无法区分边界                       |
+| 蓝色/靛蓝/紫色        | 蓝幕    | **绿幕 #00FF00** | 同色系冲突                                 |
+| 红色/粉色/白色/黑色   | —       | 绿幕或蓝幕均可   | 与两者色相距离都大                         |
+| 多色/彩虹             | —       | **品红 #FF00FF** | 品红在自然素材中最少出现（最后手段）       |
+
+### Prompt 后缀速查表
+
+| 素材类型                   | prompt 建议后缀                                                     | 后处理                                      | skipRemoveBg |
+| -------------------------- | ------------------------------------------------------------------- | ------------------------------------------- | ------------ |
+| 独立元素（需透明，非金色） | `"on solid bright green #00FF00 background, isolated, centered"`    | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（金/黄/橙/绿色）  | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 深色验证 | `false`      |
+| 独立元素（多色/彩虹）      | `"on solid bright magenta #FF00FF background, isolated, centered"`  | remove-background (tolerance 20) → 深色验证 | `false`      |
+| VFX 特效（发光/粒子）      | `"on solid bright blue #0000FF background, isolated, centered"`     | remove-background (tolerance 25) → 逐帧验证 | `false`      |
+| 卡牌/棋子（矩形本体）      | `"flat 2D, no shadow, no 3D effect, clean edges, white background"` | 只做 resize                                 | `true`       |
+| UI 按钮/面板               | `"flat UI element, no shadow, clean edges"`                         | trim + resize                               | `true`       |
+| 场景背景                   | `"full scene, full bleed, edge to edge, no vignette, no fade"`      | resize → 四角全覆盖检查                     | `true`       |
+
+### 去背景后必做：深色背景渲证
+
+> 每个需要透明的资产，去背景后**必须**在深色背景上叠合验证。这一步是防止白底/色幕残留/黑块的最后防线。
+
+```bash
+playcraft image overlay \
+  --base ta-workspace/tmp/dark_verify_bg.png \
+  --overlay <processed>.png \
+  --output ta-workspace/tmp/verify_<name>.png \
+  --gravity center
+# 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
+```
+
+**不通过时的修复**：见 `ta-pipeline-cookbook.md` Step 0e §3 及 Compliance Gate 失败修复表。
+
+---
+
+## 4. 脚本决策
+
+- **<=5 个文件** → 直接使用 CLI 命令
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
+
+---
+
+## 5. 进阶参考
+
+需要以下进阶内容时，查阅 [`refs/ta-image-generation-detail.md`](../../agents/refs/ta-image-generation-detail.md)：
+
+| 主题                  | 说明                                                                |
+| --------------------- | ------------------------------------------------------------------- |
+| 精灵图直出策略        | gpt-image-2 网格图生成 + sprite-split 切分，白底/绿幕示例，分批策略 |
+| Edit 模型工作流       | 基图 → edit 变体（换花色/换数字/换颜色），prompt 写法               |
+| 错误恢复表            | 各类错误现象、原因、立即行动；模型回退顺序                          |
+| Provider 回退链       | gpt-image-2 三 provider 互为回退 + 非 gpt-image-2 稳定回退          |
+| 批量生成最佳实践      | 单张验证、Node.js 脚本推荐、脚本模板使用                            |
+| ta-workspace 脚本驱动 | 为什么用 Node.js、目录约定、脚本模板一览表                          |

package/project-template/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs

@@ -0,0 +1,123 @@
+// ============================================================
+// build-sprite-sheet.template.mjs — 精灵图合并 + 验证脚本模板
+// 用途：将处理好的图片目录合并为精灵图（PNG + JSON 元数据）
+//
+// 使用方式：
+//   1. cp .claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs ta-workspace/scripts/build-<name>-atlas.mjs
+//   2. 修改下方 CONFIG 区域
+//   3. 如需控制帧顺序，填写 ORDERED_NAMES 数组（留空则按文件名排序）
+//   4. node ta-workspace/scripts/build-<name>-atlas.mjs
+// ============================================================
+
+import { execSync } from 'child_process';
+import { existsSync, readFileSync, readdirSync, mkdirSync, appendFileSync } from 'fs';
+import { join, extname } from 'path';
+
+// ============ CONFIG — 修改这里 ============
+const CONFIG = {
+  /** 处理好的图片目录（process-batch 的输出目录） */
+  processedDir: 'assets/images/processed',
+  /** 输出文件路径（不含扩展名，会生成 .png 和 .json 两个文件） */
+  outputBase: 'assets/bundles/atlas',
+  /** 每行帧数 */
+  columns: 8,
+  /** 帧间距（像素） */
+  padding: 2,
+  /**
+   * 精灵图背景色
+   * - 'transparent'（默认）：透明背景
+   * - 'white' / 'black' / '#RRGGBB'：固定背景色
+   *   某些引擎（如 PlayCanvas）处理透明精灵图时可能显示为黑色，此时用 'white' 更安全
+   */
+  background: 'transparent',
+  /** 文件名排序方式：'name'（字母序）或 'custom'（使用 ORDERED_NAMES） */
+  sort: 'name',
+};
+
+/**
+ * 自定义帧顺序（CONFIG.sort = 'custom' 时生效）
+ * 填写不含扩展名的文件名，按期望顺序排列
+ * 示例（扑克牌）：['spades_A', 'spades_2', 'spades_3', ...]
+ */
+const ORDERED_NAMES = [
+  // 填写文件名（不含扩展名）...
+];
+// ============ LOGIC — 通常不需要修改 ============
+
+const LOG_FILE = 'ta-workspace/logs/build-sprite-sheet.log';
+mkdirSync('ta-workspace/logs', { recursive: true });
+
+function log(msg) {
+  const line = `[${new Date().toISOString()}] ${msg}`;
+  console.log(line);
+  appendFileSync(LOG_FILE, line + '\n');
+}
+
+// 收集输入文件
+let inputFiles;
+if (CONFIG.sort === 'custom' && ORDERED_NAMES.length > 0) {
+  // 自定义顺序：按 ORDERED_NAMES 排列，找不到的文件跳过并警告
+  inputFiles = [];
+  for (const name of ORDERED_NAMES) {
+    const candidates = ['.png', '.jpg', '.webp'].map(ext => join(CONFIG.processedDir, `${name}${ext}`));
+    const found = candidates.find(p => existsSync(p));
+    if (found) {
+      inputFiles.push(found);
+    } else {
+      log(`[WARN] Ordered file not found: ${name} (skipping)`);
+    }
+  }
+} else {
+  // 文件名排序
+  inputFiles = readdirSync(CONFIG.processedDir)
+    .filter(f => ['.png', '.jpg', '.webp'].includes(extname(f).toLowerCase()))
+    .sort()
+    .map(f => join(CONFIG.processedDir, f));
+}
+
+if (inputFiles.length === 0) {
+  log('ERROR: No input files found in ' + CONFIG.processedDir);
+  process.exit(1);
+}
+
+log(`=== Build Sprite Sheet Start ===`);
+log(`Frames: ${inputFiles.length} | Columns: ${CONFIG.columns} | Padding: ${CONFIG.padding} | BG: ${CONFIG.background}`);
+
+// 构建 --inputs 参数列表
+const inputsArg = inputFiles.map(p => `"${p}"`).join(' ');
+
+const cmd =
+  `playcraft image sprite-sheet` +
+  ` --inputs ${inputsArg}` +
+  ` --output "${CONFIG.outputBase}"` +
+  ` --columns ${CONFIG.columns}` +
+  ` --padding ${CONFIG.padding}` +
+  (CONFIG.background !== 'transparent' ? ` --background "${CONFIG.background}"` : '');
+
+log(`Running: playcraft image sprite-sheet ... --output ${CONFIG.outputBase}`);
+
+try {
+  execSync(cmd, { stdio: 'inherit' });
+} catch (e) {
+  log(`ERROR: sprite-sheet command failed: ${e.message}`);
+  process.exit(1);
+}
+
+// 验证输出
+const pngPath  = `${CONFIG.outputBase}.png`;
+const jsonPath = `${CONFIG.outputBase}.json`;
+
+if (!existsSync(pngPath) || !existsSync(jsonPath)) {
+  log('ERROR: Output files missing! Expected ' + pngPath + ' and ' + jsonPath);
+  process.exit(1);
+}
+
+const meta = JSON.parse(readFileSync(jsonPath, 'utf-8'));
+const frameCount = Object.keys(meta.frames ?? {}).length;
+
+log(`\n=== Sprite Sheet Built ===`);
+log(`  Frames  : ${frameCount}`);
+log(`  PNG     : ${pngPath}`);
+log(`  JSON    : ${jsonPath}`);
+log(`  Columns : ${CONFIG.columns}`);
+log(`  Rows    : ${Math.ceil(frameCount / CONFIG.columns)}`);

package/project-template/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs

@@ -0,0 +1,254 @@
+/**
+ * compare-style.template.mjs
+ *
+ * 色彩风格一致性定量检查脚本。
+ * 用途：TA Micro-Batch Validation 辅助工具，对 AI 补全素材与 Designer 样本做客观色彩比较。
+ *
+ * 使用方法：
+ *   cp .claude/skills/playcraft-image-generation/reference/compare-style.template.mjs \
+ *      ta-workspace/scripts/compare-style.mjs
+ *   # 修改下方 CONFIG 区域后运行：
+ *   node ta-workspace/scripts/compare-style.mjs
+ *
+ * 输出示例：
+ *   [COMPARE] tile_sample_1.png  vs  tile_comp_01.png
+ *     色相距离（加权）: 8.3°     → ✅ 优秀（< 15°）
+ *     明度差异:         0.06     → ✅ 优秀（< 0.10）
+ *     饱和度差异:       0.04     → ✅ 优秀（< 0.10）
+ *     综合一致性评分:   4.7 / 5  → ✅ 通过（≥ 3.0）
+ *
+ * 依赖：@gltf-transform/core（CLI 已内置）、sharp（CLI 已内置）
+ * 若 sharp 未全局可用，运行前：npm install sharp --no-save
+ */
+
+import { execSync } from 'child_process';
+import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import path from 'path';
+
+// ─── CONFIG ───────────────────────────────────────────────────────────────────
+
+const CONFIG = {
+  /** Designer 样本图（风格基准） */
+  referenceImage: 'assets/images/tiles/tile_sample_1.png',
+
+  /** 要检查的 TA 补全素材目录或文件列表 */
+  targetDir: 'assets/images/tiles',
+
+  /** 只检查该目录下的哪些文件（glob 后缀匹配） */
+  targetGlob: '.png',
+
+  /** 排除文件名包含这些关键词的文件（Designer 样本自身） */
+  excludeKeywords: ['sample', 'concept', 'selected', 'storyboard'],
+
+  /** 日志输出路径 */
+  logFile: 'ta-workspace/logs/style-compare.log',
+
+  /** 评分阈值（低于此值输出警告） */
+  warnThreshold: 3.0,
+};
+
+// ─── HELPERS ──────────────────────────────────────────────────────────────────
+
+/**
+ * 用 playcraft image info 提取图片的 dominant colors（HSL 列表）
+ * 返回格式：[{ h, s, l, weight }]（weight 为面积占比估算）
+ */
+function extractDominantColors(imagePath) {
+  try {
+    const raw = execSync(
+      `playcraft image info --input "${imagePath}" --json`,
+      { encoding: 'utf-8', stdio: ['pipe', 'pipe', 'pipe'] }
+    );
+    const info = JSON.parse(raw);
+
+    // playcraft image info 返回 dominantColors 数组：[{ r, g, b, hex, percent }]
+    const colors = (info.dominantColors || []).slice(0, 5);
+    return colors.map(c => {
+      const hsl = rgbToHsl(c.r, c.g, c.b);
+      return { ...hsl, weight: (c.percent || 20) / 100 };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function rgbToHsl(r, g, b) {
+  r /= 255; g /= 255; b /= 255;
+  const max = Math.max(r, g, b), min = Math.min(r, g, b);
+  const l = (max + min) / 2;
+  if (max === min) return { h: 0, s: 0, l };
+  const d = max - min;
+  const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+  let h;
+  switch (max) {
+    case r: h = ((g - b) / d + (g < b ? 6 : 0)) / 6; break;
+    case g: h = ((b - r) / d + 2) / 6; break;
+    default: h = ((r - g) / d + 4) / 6;
+  }
+  return { h: h * 360, s, l };
+}
+
+/**
+ * 计算两组 dominant colors 之间的加权色相距离（°）
+ * 色相距离取最短弧（0–180°）
+ */
+function weightedHueDist(colorsA, colorsB) {
+  if (!colorsA.length || !colorsB.length) return 999;
+  let totalDist = 0, totalWeight = 0;
+  for (const a of colorsA) {
+    // 找 B 中色相最近的颜色
+    let minDist = Infinity;
+    for (const b of colorsB) {
+      const raw = Math.abs(a.h - b.h);
+      const dist = raw > 180 ? 360 - raw : raw;
+      if (dist < minDist) minDist = dist;
+    }
+    totalDist += minDist * a.weight;
+    totalWeight += a.weight;
+  }
+  return totalWeight > 0 ? totalDist / totalWeight : 999;
+}
+
+/**
+ * 计算明度 / 饱和度的加权平均差异（0–1）
+ */
+function weightedChannelDiff(colorsA, colorsB, channel) {
+  if (!colorsA.length || !colorsB.length) return 1;
+  const avgA = colorsA.reduce((s, c) => s + c[channel] * c.weight, 0) /
+               colorsA.reduce((s, c) => s + c.weight, 0);
+  const avgB = colorsB.reduce((s, c) => s + c[channel] * c.weight, 0) /
+               colorsB.reduce((s, c) => s + c.weight, 0);
+  return Math.abs(avgA - avgB);
+}
+
+/**
+ * 综合一致性评分 1–5
+ *
+ * 评分规则（与 playcraft-style-qa Micro-Batch 标准对齐）：
+ *   色相距离 < 15°  且 明度/饱和度差 < 0.10  → 5 分
+ *   色相距离 < 20°  且 明度/饱和度差 < 0.15  → 4 分
+ *   色相距离 < 30°  且 明度/饱和度差 < 0.20  → 3 分（勉强可接受）
+ *   色相距离 < 45°  且 明度/饱和度差 < 0.30  → 2 分（需调整）
+ *   其他                                       → 1 分（停止，提问 Designer）
+ */
+function calcScore(hueDist, lightDiff, satDiff) {
+  const channelOk = Math.max(lightDiff, satDiff);
+  if (hueDist < 15 && channelOk < 0.10) return 5;
+  if (hueDist < 20 && channelOk < 0.15) return 4;
+  if (hueDist < 30 && channelOk < 0.20) return 3;
+  if (hueDist < 45 && channelOk < 0.30) return 2;
+  return 1;
+}
+
+function scoreLabel(score) {
+  if (score >= 4) return '✅ 良好';
+  if (score >= 3) return '⚠️  可接受';
+  return '❌ 偏差过大，需停止';
+}
+
+function hueLabel(dist) {
+  if (dist < 15) return '✅ 优秀（< 15°）';
+  if (dist < 30) return '⚠️  偏差（< 30°）';
+  return '❌ 严重偏差（≥ 30°）';
+}
+
+function channelLabel(diff) {
+  if (diff < 0.10) return '✅ 优秀（< 0.10）';
+  if (diff < 0.20) return '⚠️  偏差（< 0.20）';
+  return '❌ 严重偏差（≥ 0.20）';
+}
+
+// ─── MAIN ─────────────────────────────────────────────────────────────────────
+
+async function main() {
+  const logDir = path.dirname(CONFIG.logFile);
+  if (!existsSync(logDir)) mkdirSync(logDir, { recursive: true });
+
+  const refPath = CONFIG.referenceImage;
+  if (!existsSync(refPath)) {
+    console.error(`[ERROR] 参考图不存在: ${refPath}`);
+    process.exit(1);
+  }
+
+  console.log(`\n📊 色彩风格一致性检查`);
+  console.log(`   参考图: ${refPath}\n`);
+
+  const refColors = extractDominantColors(refPath);
+  if (!refColors.length) {
+    console.error('[ERROR] 无法从参考图提取颜色，请确认 playcraft image info 可用');
+    process.exit(1);
+  }
+
+  // 收集目标文件
+  let targets = [];
+  try {
+    const { readdirSync } = await import('fs');
+    targets = readdirSync(CONFIG.targetDir)
+      .filter(f => f.endsWith(CONFIG.targetGlob))
+      .filter(f => !CONFIG.excludeKeywords.some(kw => f.includes(kw)))
+      .map(f => path.join(CONFIG.targetDir, f));
+  } catch {
+    console.error(`[ERROR] 无法读取目录: ${CONFIG.targetDir}`);
+    process.exit(1);
+  }
+
+  if (!targets.length) {
+    console.log('  未找到需要检查的目标文件');
+    return;
+  }
+
+  const results = [];
+  let failCount = 0;
+
+  for (const target of targets) {
+    const targetColors = extractDominantColors(target);
+    if (!targetColors.length) {
+      console.log(`  [SKIP] ${path.basename(target)} — 无法提取颜色`);
+      continue;
+    }
+
+    const hueDist  = weightedHueDist(refColors, targetColors);
+    const lightDiff = weightedChannelDiff(refColors, targetColors, 'l');
+    const satDiff   = weightedChannelDiff(refColors, targetColors, 's');
+    const score     = calcScore(hueDist, lightDiff, satDiff);
+
+    if (score < CONFIG.warnThreshold) failCount++;
+
+    const line = [
+      `[COMPARE] ${path.basename(refPath)}  vs  ${path.basename(target)}`,
+      `  色相距离（加权）: ${hueDist.toFixed(1)}°     → ${hueLabel(hueDist)}`,
+      `  明度差异:         ${lightDiff.toFixed(2)}     → ${channelLabel(lightDiff)}`,
+      `  饱和度差异:       ${satDiff.toFixed(2)}     → ${channelLabel(satDiff)}`,
+      `  综合一致性评分:   ${score} / 5  → ${scoreLabel(score)}`,
+      '',
+    ].join('\n');
+
+    console.log(line);
+    results.push({ file: path.basename(target), score, hueDist, lightDiff, satDiff });
+  }
+
+  // 汇总
+  const avgScore = results.reduce((s, r) => s + r.score, 0) / (results.length || 1);
+  const summary = [
+    `=== 汇总 ===`,
+    `  检查文件数: ${results.length}`,
+    `  平均评分:   ${avgScore.toFixed(1)} / 5`,
+    `  低于阈值数: ${failCount}（阈值 ${CONFIG.warnThreshold}）`,
+    failCount > 0
+      ? `  ⚠️  建议：停止低分文件类型的批量生产，调整生成参数或向 Designer 提问 ICP`
+      : `  ✅  全部通过，可继续批量生产`,
+    '',
+  ].join('\n');
+
+  console.log(summary);
+
+  // 写日志
+  const timestamp = new Date().toISOString();
+  appendFileSync(CONFIG.logFile, `\n[${timestamp}]\n${results.map(r =>
+    `${r.file}: score=${r.score} hue=${r.hueDist.toFixed(1)}° L=${r.lightDiff.toFixed(2)} S=${r.satDiff.toFixed(2)}`
+  ).join('\n')}\n${summary}`);
+
+  if (failCount > 0) process.exit(1);
+}
+
+main().catch(e => { console.error(e); process.exit(1); });