@playcraft/cli 0.0.44 → 0.0.47

package/project-template/skills/playable-verify-ui/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: playable-verify-ui
+description: >-
+  Image Validator (step ③): profile-driven verify:ui for playables. Agent MUST
+  run ensure-project first; if new profile template, fill paths/assets then
+  npm run verify:ui. Use when user asks to fix HUD layout, atlas budget, missing
+  assets, or before/after any PNG manifest change. User never runs verify manually.
+---
+
+# Playable UI Optimization
+
+> **用户**：「用 ui optimization 检查/修当前 UI」  
+> **Agent**：ensure-project → 补 profile（若新建）→ verify:ui → 按 FAIL 项最小 fix。
+
+---
+
+## Agent 入口
+
+### 0. 自举
+
+```bash
+npm run ensure:project
+```
+
+若刚生成 `playable.ui.profile.yaml`：编辑 `meta` / `paths` / `assets` / `layout` 对齐本工程（参照同 repo 其他 testN 或 `examples/mahjong-match.profile.yaml`）。
+
+### 1. Image Validator
+
+```bash
+npm run verify:ui
+npm run verify:ui:assets   # 仅资源
+npm run verify:ui:layout   # 仅布局
+```
+
+### 2. FAIL → fix 映射
+
+| 检查             | Agent 动作                   |
+| ---------------- | ---------------------------- |
+| assets_present   | 补 PNG 或改 manifest         |
+| atlas_budget     | 压缩 atlas / 文档化 P2       |
+| layout_regions   | 改 layout 走 profile，删魔数 |
+| hardcoded_layout | 改用 `applySafeLayout`       |
+
+### 2b. Alpha / Matte Routing
+
+`verify:ui` 是静态 Image Validator：它能拦资源、尺寸、预算、layout、透明度风险，但不能证明合成后的画面好看。任何透明资产相关 FAIL / WARN 必须给出推荐 skill 和 `alphaStrategy`：
+
+| 静态现象                | 返回意见必须包含                                                                 |
+| ----------------------- | -------------------------------------------------------------------------------- | ---------------- | ------------- |
+| 缺 alpha / 全不透明     | `recommendedSkill=playable-art`, `alphaStrategy=chroma                           | rgb-alpha-split  | dual-bg-diff` |
+| 绿/蓝/品红边            | `recommendedSkill=playable-art`, `alphaStrategy=rgb-alpha-split` 或换 chroma key |
+| 白边 / 抗锯齿脏         | `recommendedSkill=playable-art`, `alphaStrategy=dual-bg-diff                     | rgb-alpha-split` |
+| 黑块 / glow 被吃掉      | `recommendedSkill=playable-fx-peak`, `alphaStrategy=black-add`                   |
+| wrong tile face overlay | `recommendedSkill=playable-fx-decompose`, `alphaStrategy=rgb-alpha-split         | overlay-diff`    |
+
+建议命令：
+
+```bash
+python3 skills/playable-art/scripts/verify-alpha-clean.py assets/images/ui/<asset>.png --json
+```
+
+### 2c. Vision Evidence（程序化标注环节）
+
+`verify:ui` 默认会在 validator 之后运行 `verify:vision`，把 validator 输出的 `issues[]` 程序化渲染成标注证据图。是否标注由脚本参数决定，不由 LLM 决定；LLM 只读取报告和证据图辅助修复。
+
+`verify:vision` 是 **CV (Computer Vision, 计算机视觉) 标注证据层**（本地 Pillow 薄渲染，无 supervision/opencv 重依赖）。它不单独决定质量 gate，也**不能替代** Reviewer 目视 PASS。
+
+| 命令            | 角色                                                | 何时跑                             |
+| --------------- | --------------------------------------------------- | ---------------------------------- |
+| `verify:visual` | **客观门**（SSIM/直方图 vs ASR）                    | Ring 4 verify DoD                  |
+| `verify:vision` | **程序化证据**（标注 issue 供 Reviewer/Agent 复核） | `verify:ui` 默认阶段，也可单独运行 |
+
+```bash
+npm run verify:vision
+npm run verify:vision -- --detections validate/vision/detections.json
+npm run verify:ui -- --no-annotations
+```
+
+**Issues / detections 来源（零 LLM 配置）**：
+
+1. **默认 pipeline**：`verify:ui` 收集 `verify:bg-clean` / `verify:tile-consistency` / `verify:text-overlap` 的 `issues[]`，再传给 `verify:vision` 标注。
+2. **单独运行**：`verify:vision` 会自动运行本地视觉 validator 收集 `issues[]`。
+3. **可选增强**：`playcraft tools detect --image … --output validate/vision/detections.json`（backend SAM3/VLM，见 CLI 文档），再 `--detections` 传入。
+
+输出：`validate/vision/validator-issues.json`、`validate/vision/vision-evidence.json` + `*-vision.png` 标注图。依赖 Pillow（`ensure:project` 会安装 `requirements.txt`）。
+
+**关闭标注**：`npm run verify:ui -- --no-annotations` 只关闭证据图生成，不跳过 validator，也不改变 fail/warn gate。
+
+**禁止**：仅凭 vision evidence 判定 ui_diff PASS；最终仍必须由 Reviewer 读截图/MP4。
+
+### 3. Exit
+
+PASS 后通知 orchestrating skill（video-validate-loop）可进入录屏。WARN 写入 validate 报告。
+
+---
+
+## When to Apply
+
+- 任何 Phaser 1080×1920（或可配置分辨率）可玩广告的 UI / 占位图 / 布局问题
+- HUD 顶天/贴底、连击条压 CTA、调试按钮位置不对
+- atlas 帧尺寸与文档/profile 漂移
+- 硬编码布局魔数（未走 `applySafeLayout`）
+- 新可玩项目接入：复制模板 profile → 填 paths/assets/layout → 跑检测
+
+## Quick Start
+
+```bash
+# 1. 复制模板到项目根（testN/ 或仓库根）
+cp ../skills/playable-verify-ui/profiles/template.profile.yaml playable.ui.profile.yaml
+
+# 2. 填写 meta / paths / assets / layout / thresholds
+
+# 3. 跑检测（本仓库已集成）
+npm run verify:ui
+npm run verify:ui:assets   # 仅资源层
+npm run verify:ui:layout   # 仅布局层
+```
+
+**验收顺序**：先 `npm run verify:ui`，再由 Reviewer 读取真实截图做 `ui_diff`。静态 PASS 不能替代模型目视真实渲染图。
+
+---
+
+## Profile 驱动架构
+
+```
+playable.ui.profile.yaml          ← 项目自描述（单一事实来源）
+        │
+        ├─ schema/playable-ui-profile.schema.json   ← JSON Schema 校验
+        ├─ scripts/run_all.py                     ← 编排器
+        ├─ Python 资源检测 (7)
+        └─ Node 布局检测 (4)
+```
+
+| 路径                                                                         | 用途                |
+| ---------------------------------------------------------------------------- | ------------------- |
+| [`schema/`](schema/)                                                         | Profile JSON Schema |
+| [`profiles/template.profile.yaml`](profiles/template.profile.yaml)           | 空白模板            |
+| [`examples/mahjong-match.profile.yaml`](examples/mahjong-match.profile.yaml) | 本仓库麻将示例      |
+| [`scripts/`](scripts/)                                                       | 全部检测脚本        |
+
+**禁止**：未更新 profile 就改 `EXPECTED_FRAME_SIZES`、硬编码布局 Y 值、或在 fetch 脚本中对 UI/rewards 使用 placehold.co。
+
+---
+
+## Optimization Layers
+
+按顺序处理，不要跳过 layout 直接调组件坐标：
+
+```
+1. Layout metrics   → game-config applySafeLayout（profile.layout.configKeys）
+2. Board bounds     → module: boardBounds（可选，麻将示例用 centerInPlayBand）
+3. HUD chrome       → module: hudChrome
+4. Asset placeholders → profile.assets + build-atlas
+5. Match VFX        → module: matchShatter（可选）
+6. Verify           → npm run verify:ui && browser
+```
+
+`modules` 字段仅作文档标签，不强制实现。
+
+---
+
+## 1. Safe Layout System
+
+垂直 UI 应从 `SAFE_TOP` / `SAFE_BOTTOM` / `SAFE_SIDE` 推导，在 `applySafeLayout()` 中一次性写入 `PLAY_AREA_*`、`CTA_Y`、`COMBO_HUD_Y` 等。
+
+在 profile 中声明：
+
+```yaml
+layout:
+  configKeys: [SAFE_TOP, PLAY_AREA_TOP, CTA_Y, CTA_H, ...]
+  regions:
+    hud: { y0: 'HUD.BAR_Y', y1: 'HUD.BAR_Y + HUD.BAR_H' }
+    combo: { cy: 'COMBO_HUD_Y', h: 'COMBO_HUD_H' }
+    cta: { y0: 'CTA_Y', y1: 'CTA_Y + CTA_H' }
+    playArea: { y0: 'PLAY_AREA_TOP', y1: 'PLAY_AREA_BOTTOM' }
+  rules:
+    - { type: safe_top, region: hud, min: 'safeArea.minTop' }
+    - { type: min_gap, a: combo, b: cta, min: 40 }
+    - { type: inside_band, region: combo, band: playArea }
+    - { type: ordered, first: playArea, second: cta }
+```
+
+表达式仅允许 `GAME_CONFIG` 数字字段、`safeArea.*` 与 `+ - * / ()`。
+
+---
+
+## 2. Asset Pipeline
+
+Profile `assets` 段声明 standalone PNG 与各 atlas 帧（名称、源路径、宽高）。检测脚本会验证：
+
+- 文件存在、PNG 尺寸、atlas JSON 帧名/尺寸
+- 包体预算（`thresholds.maxAtlasSheetKb` 等）
+- （warn）`assetNamingDoc` 与 profile 尺寸漂移
+- （warn）fetch/build 脚本中的 placehold.co 引用
+- 透明资产若出现边缘残留，反馈必须路由到 `playable-art` alpha postprocess 或 FX skill
+
+```bash
+npm run generate-ui      # 本地占位图（若项目有）
+npm run build-atlas      # 打包 atlas
+npm run verify:ui:assets
+```
+
+---
+
+## 3. Layout & Script Checks
+
+Node 脚本通过 `vm` 加载 `paths.gameConfig`，执行 profile 中的 `layout.rules` 与 `antipatterns` grep，并校验 `index.html` 中 `scripts.loadOrder` 子序列。
+
+```bash
+npm run verify:ui:layout
+```
+
+---
+
+## 4. New Project Onboarding
+
+1. 复制 [`profiles/template.profile.yaml`](profiles/template.profile.yaml) → `playable.ui.profile.yaml`
+2. 填写 `paths`（gameConfig、indexHtml、assetsRoot、atlasRoot）
+3. 列出 `assets.standalone` 与 `assets.atlases[].frames`
+4. 定义 `layout.regions` + `layout.rules`
+5. 在 `package.json` 添加：
+
+```json
+"verify:ui": "python3 ../skills/playable-verify-ui/scripts/run_all.py"
+```
+
+6. 依赖：`pip install pyyaml jsonschema pillow`（Python 3）；Node 18+ 无额外 npm 包
+
+---
+
+## 5. Verification Checklist
+
+- [ ] `npm run verify:ui` 全 pass（或仅预期 warn）
+- [ ] 每条透明度相关 FAIL/WARN 都写了 `recommendedSkill` + `alphaStrategy`
+- [ ] Reviewer 已读取实际渲染截图，而不是只引用静态脚本结果
+- [ ] 硬刷新后 HUD 有顶边距、连击条不压 CTA
+- [ ] 棋盘框贴合牌堆（若启用 boardBounds 模块）
+- [ ] 匹配动效符合预期（若启用 matchShatter 模块）
+- [ ] profile / asset-naming.md / build-atlas 三处规格一致
+
+故意改坏一项（如 `SAFE_TOP: 8`）应被 `verify_layout_regions` 的 `safe_top` 规则捕获。
+
+---
+
+## Scope Discipline
+
+- **In scope:** profile 维护、layout 推导、占位管线、检测脚本扩展、VFX 时序
+- **Out of scope unless asked:** 最终美术替换、玩法规则改动、CDP 截图回归
+
+用户报「布局有问题」时，先查 profile 规则与 `applySafeLayout` 输出，再调单个组件。
+
+---
+
+## Frame + Text Layout（图+字）
+
+> 原 `playable-frame-text-layout` 已并入本节。
+
+HUD / CTA / toast 等 **装饰底图 + 动态文字** 三类问题：框变形、字不居中、内边距不足。
+
+| 症状        | 根因                    | 修复                            |
+| ----------- | ----------------------- | ------------------------------- |
+| 端饰变椭圆  | 非等比 `setDisplaySize` | **等比** `setScale(s)`          |
+| 字偏上/偏下 | 按外框居中未扣金边      | `CONTENT` inset + `getBounds()` |
+| 整体太宽    | 素材宽扁                | 等比缩小或重出素材              |
+
+**缩放规则**：带祥云耳/圆端 → 整图等比；仅中间平铺条 → NineSlice；**禁止** atlas 三段 `setCrop` 拼 CTA。
+
+**Content zone**（写入 `GAME_CONFIG` + `applySafeLayout`）：
+
+```js
+CTA_TEXT_Y_RATIO: 81.5 / 190; // 红区垂直中心 / 原图高（实测）
+```
+
+实测 inset（改前不要猜）：
+
+```bash
+python3 skills/playable-verify-ui/scripts/measure_frame_content.py \
+  assets/atlas/ui.png assets/atlas/ui.json ui_cta_btn
+```
+
+详见 [references/scaling-decision-tree.md](references/scaling-decision-tree.md)、[references/phaser-patterns.md](references/phaser-patterns.md)。
+
+---
+
+## Related Skills
+
+| Skill                                              | 分工                                                                        |
+| -------------------------------------------------- | --------------------------------------------------------------------------- |
+| [playable-validate](../playable-validate/SKILL.md) | 录屏 validate、[validation-rules](../playable-validate/validation-rules.md) |
+| [playable-debug](../playable-debug/SKILL.md)       | 一键通关 / 调试开关                                                         |
+| [playable-art](../playable-art/SKILL.md)           | 素材导入与 CTA 出图规范                                                     |
+
+## Additional Reference
+
+Schema 字段、规则类型、故障对照表：[`reference.md`](reference.md)

package/project-template/skills/playable-verify-ui/examples/asset-manifest.example.json

@@ -0,0 +1,36 @@
+{
+  "version": 1,
+  "assets": {
+    "10000001": {
+      "path": "assets/images/bg/bg_game.webp",
+      "role": "background",
+      "usage": "runtime",
+      "roi": { "board": [0.08, 0.22, 0.92, 0.72] }
+    },
+    "10000010": {
+      "path": "assets/images/tiles/tile_blue.webp",
+      "role": "tile",
+      "usage": "runtime"
+    },
+    "10000011": { "path": "assets/images/tiles/tile_red.webp", "role": "tile", "usage": "runtime" },
+    "10000012": {
+      "path": "assets/images/tiles/tile_yellow.webp",
+      "role": "tile",
+      "usage": "runtime"
+    },
+    "10000020": {
+      "path": "assets/images/cta/btn_install.webp",
+      "role": "cta",
+      "usage": "runtime",
+      "allowedText": ["INSTALL", "立即下载"]
+    },
+    "10000030": {
+      "path": "assets/images/storyboard/master_composite_option_A.png",
+      "role": "reference",
+      "usage": "reference-only"
+    }
+  },
+  "screen": {
+    "allowedText": ["INSTALL", "立即下载", "PLAY"]
+  }
+}

package/project-template/skills/playable-verify-ui/examples/mahjong-match.profile.yaml

@@ -0,0 +1,334 @@
+meta:
+  engine: phaser3
+  name: mahjong-match
+  design:
+    width: 1080
+    height: 1920
+paths:
+  gameConfig: game/config/game-config.js
+  indexHtml: game/index.html
+  assetsRoot: assets/images
+  atlasRoot: assets/atlas
+  assetNamingDoc: docs/asset-naming.md
+  buildAtlasScript: scripts/build-atlas.py
+  fetchAssetsScript: scripts/fetch-assets.sh
+safeArea:
+  minTop: 48
+  minBottom: 48
+  minSide: 16
+assets:
+  standalone:
+    - key: bg
+      path: bg.png
+      width: 1080
+      height: 1920
+  atlases:
+    - name: tiles
+      json: tiles.json
+      png: tiles.png
+      frames:
+        - name: wan_1
+          source: tiles/wan_1.png
+          width: 176
+          height: 216
+        - name: wan_2
+          source: tiles/wan_2.png
+          width: 176
+          height: 216
+        - name: wan_3
+          source: tiles/wan_3.png
+          width: 176
+          height: 216
+        - name: tong_1
+          source: tiles/tong_1.png
+          width: 176
+          height: 216
+        - name: tong_2
+          source: tiles/tong_2.png
+          width: 176
+          height: 216
+        - name: tong_3
+          source: tiles/tong_3.png
+          width: 176
+          height: 216
+        - name: tiao_1
+          source: tiles/tiao_1.png
+          width: 176
+          height: 216
+        - name: tiao_2
+          source: tiles/tiao_2.png
+          width: 176
+          height: 216
+        - name: tiao_3
+          source: tiles/tiao_3.png
+          width: 176
+          height: 216
+        - name: gold
+          source: tiles/gold.png
+          width: 176
+          height: 216
+        - name: back
+          source: tiles/back.png
+          width: 176
+          height: 216
+    - name: digits
+      json: digits.json
+      png: digits.png
+      frames:
+        - name: digit_0
+          source: digits/0.png
+          width: 48
+          height: 64
+        - name: digit_1
+          source: digits/1.png
+          width: 48
+          height: 64
+        - name: digit_2
+          source: digits/2.png
+          width: 48
+          height: 64
+        - name: digit_3
+          source: digits/3.png
+          width: 48
+          height: 64
+        - name: digit_4
+          source: digits/4.png
+          width: 48
+          height: 64
+        - name: digit_5
+          source: digits/5.png
+          width: 48
+          height: 64
+        - name: digit_6
+          source: digits/6.png
+          width: 48
+          height: 64
+        - name: digit_7
+          source: digits/7.png
+          width: 48
+          height: 64
+        - name: digit_8
+          source: digits/8.png
+          width: 48
+          height: 64
+        - name: digit_9
+          source: digits/9.png
+          width: 48
+          height: 64
+        - name: digit_0_glow
+          source: digits/0_glow.png
+          width: 48
+          height: 64
+        - name: digit_1_glow
+          source: digits/1_glow.png
+          width: 48
+          height: 64
+        - name: digit_2_glow
+          source: digits/2_glow.png
+          width: 48
+          height: 64
+        - name: digit_3_glow
+          source: digits/3_glow.png
+          width: 48
+          height: 64
+        - name: digit_4_glow
+          source: digits/4_glow.png
+          width: 48
+          height: 64
+        - name: digit_5_glow
+          source: digits/5_glow.png
+          width: 48
+          height: 64
+        - name: digit_6_glow
+          source: digits/6_glow.png
+          width: 48
+          height: 64
+        - name: digit_7_glow
+          source: digits/7_glow.png
+          width: 48
+          height: 64
+        - name: digit_8_glow
+          source: digits/8_glow.png
+          width: 48
+          height: 64
+        - name: digit_9_glow
+          source: digits/9_glow.png
+          width: 48
+          height: 64
+        - name: digit_x
+          source: digits/x.png
+          width: 48
+          height: 64
+        - name: digit_colon
+          source: digits/colon.png
+          width: 48
+          height: 64
+        - name: digit_slash
+          source: digits/slash.png
+          width: 48
+          height: 64
+    - name: ui
+      json: ui.json
+      png: ui.png
+      frames:
+        - name: ui_cta_btn
+          source: ui/cta_btn.png
+          width: 500
+          height: 80
+        - name: ui_finger
+          source: ui/finger.png
+          width: 60
+          height: 90
+        - name: ui_highlight
+          source: ui/highlight.png
+          width: 80
+          height: 80
+        - name: ui_panel_win
+          source: ui/panel_win.png
+          width: 600
+          height: 360
+        - name: ui_panel_lose
+          source: ui/panel_lose.png
+          width: 600
+          height: 360
+        - name: ui_boot_title
+          source: ui/boot_title.png
+          width: 480
+          height: 80
+        - name: ui_boot_loading
+          source: ui/boot_loading.png
+          width: 280
+          height: 48
+    - name: rewards
+      json: rewards.json
+      png: rewards.png
+      frames:
+        - name: reward_combo_bg
+          source: rewards/combo_bg.png
+          width: 300
+          height: 68
+        - name: reward_gift
+          source: rewards/gift.png
+          width: 128
+          height: 128
+        - name: reward_toast_1
+          source: rewards/toast_1.png
+          width: 600
+          height: 120
+        - name: reward_toast_2
+          source: rewards/toast_2.png
+          width: 600
+          height: 120
+        - name: reward_toast_3
+          source: rewards/toast_3.png
+          width: 600
+          height: 120
+        - name: reward_bonus_1
+          source: rewards/bonus_1.png
+          width: 640
+          height: 400
+        - name: reward_bonus_2
+          source: rewards/bonus_2.png
+          width: 640
+          height: 400
+        - name: reward_bonus_3
+          source: rewards/bonus_3.png
+          width: 640
+          height: 400
+    - name: fx
+      json: fx.json
+      png: fx.png
+      procedural: true
+      frames:
+        - name: particle_gold
+          width: 32
+          height: 32
+          procedural: true
+        - name: particle_spark
+          width: 10
+          height: 36
+          procedural: true
+        - name: particle_shard_lg
+          width: 28
+          height: 36
+          procedural: true
+        - name: particle_shard_md
+          width: 20
+          height: 26
+          procedural: true
+        - name: particle_shard_sm
+          width: 14
+          height: 18
+          procedural: true
+        - name: tile_glow
+          width: 188
+          height: 228
+          procedural: true
+layout:
+  configKeys:
+    - SAFE_TOP
+    - SAFE_BOTTOM
+    - SAFE_SIDE
+    - PLAY_AREA_TOP
+    - PLAY_AREA_BOTTOM
+    - COMBO_HUD_Y
+    - COMBO_HUD_H
+    - COMBO_GAP_ABOVE_CTA
+    - CTA_Y
+    - CTA_H
+    - DESIGN_HEIGHT
+  regions:
+    hud:
+      y0: HUD.BAR_Y
+      y1: HUD.BAR_Y + HUD.BAR_H
+    combo:
+      cy: COMBO_HUD_Y
+      h: COMBO_HUD_H
+    cta:
+      y0: CTA_Y
+      y1: CTA_Y + CTA_H
+    playArea:
+      y0: PLAY_AREA_TOP
+      y1: PLAY_AREA_BOTTOM
+  rules:
+    - type: safe_top
+      region: hud
+      min: safeArea.minTop
+    - type: min_gap
+      a: combo
+      b: cta
+      min: 40
+    - type: inside_band
+      region: combo
+      band: playArea
+    - type: ordered
+      first: playArea
+      second: cta
+antipatterns:
+  - id: hardcoded_cta_y
+    grep: CTA_Y:\s*1[56]\d{2}
+    paths:
+      - game/**/*.js
+    exclude:
+      - game/config/game-config.js
+    severity: warn
+  - id: hardcoded_hud_top
+    grep: BAR_Y:\s*[0-9]{1,2}\b
+    paths:
+      - game/**/*.js
+    exclude:
+      - game/config/game-config.js
+    severity: warn
+scripts:
+  loadOrder:
+    - config/game-config.js
+    - gameplay/match-fx.js
+    - gameplay/match-system.js
+thresholds:
+  maxAtlasSheetKb: 1024
+  maxStandaloneKb: 512
+  maxTotalAssetsMb: 12
+modules:
+  boardBounds: true
+  matchShatter: true
+  hudChrome: true