@playcraft/cli 0.0.44 → 0.0.46

package/project-templates/threejs/.claude/skills/playcraft-storyboard/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: playcraft-storyboard
+description: PlayCraft Master Composite 生成指南。5 格完整 9:16 H5 竖屏拼成一张审阅图（横排或网格均可）。Artist Phase 1 必读。
+triggers: 故事板,storyboard,4帧,四帧,体验流,experience flow,合成图,composite,master composite,Hook场景,EndCard场景,故事板生成,storyboard generation,gameplay flow visual,concept panel,5面板
+---
+
+# PlayCraft Master Composite 生成指南
+
+## 0. 核心尺寸原则（只看比例）
+
+**每一格 = 一张完整 H5 竖屏，宽高比固定 9:16**（与 `layout-spec.md` 的 1080×1920 一致）。
+
+**整张输出 = 5 张完整 H5 的拼接**——可以横排，也可以 2+3 网格等；**禁止**把 5 个竖屏塞进 1:1 / 3:2 画布导致单格变形。
+
+### 单格（H5 viewport）
+
+| 字段     | 值                         |
+| -------- | -------------------------- |
+| 宽高比   | **9:16**（宽/高 = 0.5625） |
+| 合约参考 | 1080 × 1920                |
+
+### 整图（5 格横排，默认布局）
+
+```
+┌────┬────┬────┬────┬────┐
+│9:16│9:16│9:16│9:16│9:16│   每格等宽等高，互不裁切
+└────┴────┴────┴────┴────┘
+总宽高比 = 5×9 : 16 = 45:16  （≈ 2.81，不是 10:3，不是 1:1）
+```
+
+| 档位            | 单格尺寸       | 整图尺寸（5 横排）                         |
+| --------------- | -------------- | ------------------------------------------ |
+| 推荐 2K         | **720 × 1280** | **3600 × 1280**                            |
+| 4K（长边≤4096） | **819 × 1455** | **4096 × 1455**                            |
+| 合约 1:1 缩放   | 1080 × 1920    | 5400 × 1920（超 4K 宽，需 302 或接受缩小） |
+
+> **已废弃**：720×1080（2:3）、3600×1080、`--aspect-ratio 10:3` — 单格不是 H5，会压扁/拉长。
+
+### 可选布局（仍是 5 张完整 9:16）
+
+| 布局                 | 整图宽×高（单格 W×H） | 说明                                     |
+| -------------------- | --------------------- | ---------------------------------------- |
+| **1×5 横排**（默认） | `5W × H`              | ring 3 Ring Gate 审阅最常用              |
+| 2+3 网格             | `3W × 2H`             | 上行 2 屏、下行 3 屏；prompt 须写明 grid |
+| 5×1 竖排             | `W × 5H`              | 过高，一般不推荐（易超 4096 高）         |
+
+选用非横排时，prompt 必须写清 **grid layout**，且 **each cell still 9:16 full mobile screen**。
+
+---
+
+## 1. 五格内容（Panel 1–5）
+
+> **术语**（与 `docs/team/collaboration.md` 一致）：**Panel 1 = concept panel**（Main Gameplay，含全部元素类型 + 静态文字 + 完整 UI，TA 主提取源）；**Panels 2–5 = storyboard panels**（体验流分镜，Developer 对照）。
+
+| #   | 面板                              | 用途               |
+| --- | --------------------------------- | ------------------ |
+| 1   | Main Gameplay (**concept panel**) | 完整游戏截屏       |
+| 2   | Key Hook                          | 高光 / combo       |
+| 3   | Onboarding HUD                    | 教学引导           |
+| 4   | End Card                          | 结算 + Install CTA |
+| 5   | CTA Always Visible                | 游戏中 CTA 常驻    |
+
+---
+
+## 2. Prompt 公式
+
+```
+Mobile game UI contact sheet: exactly 5 separate complete portrait mobile game screens.
+
+CRITICAL SIZE: Each of the 5 cells is a full 9:16 H5 playable viewport (same proportions as 1080x1920). Cells must NOT be stretched or squashed. Equal cell width and height.
+
+Layout: [five equal panels in one horizontal row | OR 2+3 grid as specified].
+
+Panel 1 '1. Main Gameplay': ...
+Panel 2 '2. Key Hook': ...
+Panel 3 '3. Onboarding HUD': ...
+Panel 4 '4. End Card': ...
+Panel 5 '5. CTA Always Visible': ...
+
+[STYLE_KEYWORDS]. Thin dividers between cells only. Numbered label on top of each cell.
+Total image exactly [3600] pixels wide by [1280] pixels tall (five 720x1280 cells in a row).
+```
+
+**必须约束词**：
+
+- `each cell is a full 9:16 H5 viewport` / `1080x1920 proportions`
+- `equal cell width and height` / `NOT stretched`
+- 总像素与布局一致（横排：`3600x1280` 或 `4096x1455`）
+
+---
+
+## 3. 生成命令
+
+### MC 模型白名单（强制）
+
+Master Composite **只允许**下列高质量模型（须带 **provider 前缀**，禁止裸模型名）：
+
+| 用途     | `--image-model`            | 说明                                              |
+| -------- | -------------------------- | ------------------------------------------------- |
+| **首选** | `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI；默认 Option A                |
+| **备选** | `mulerouter/nano-banana-2` | Gemini 3.1 Flash Image；Option B/C 或需不同画风时 |
+
+**禁止**用于 MC：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及 `list-image-models` 中未列入上表的模型。
+
+多方案（A/B/C）应用 **不同 prompt / 美术方向** 探索，**不得**用低档模型换方案——质量门槛对所有 MC 选项相同。
+
+```bash
+playcraft tools generate-image \
+  --prompt "<Section 2>" \
+  --output assets/images/storyboard/master_composite_option_A.png \
+  --image-model mulerouter/gpt-image-2 \
+  --aspect-ratio 45:16 \
+  --image-size 2K \
+  --width 3600 \
+  --height 1280
+```
+
+Option B 示例（仍须白名单内）：
+
+```bash
+  --image-model mulerouter/nano-banana-2 \
+```
+
+> **必须**带 `mulerouter/` 前缀。**禁止**裸 `gpt-image-2`——fallback 会先走 `iegg-litellm`，成功时只能出 **1536×1024**，五格竖屏会被压扁。CLI 会在保存后自动校验像素，不合格直接失败。
+
+**4K 档**：`--image-size 4K --width 4096 --height 1455`
+
+| 参数                   | 要求                                                                                      |
+| ---------------------- | ----------------------------------------------------------------------------------------- |
+| `--aspect-ratio`       | **`45:16`**（5 个 9:16 横排）；**禁止 `1:1`、`10:3`**                                     |
+| `--width` / `--height` | **3600×1280**（2K）或 **4096×1455**（4K）                                                 |
+| `--image-model`        | **`mulerouter/gpt-image-2`** 或 **`mulerouter/nano-banana-2`** only（强制 provider 前缀） |
+
+### 生成后验收（强制）
+
+```bash
+playcraft image info --input assets/images/storyboard/master_composite_option_A.png
+```
+
+| 检查项                | 横排 2K                | 横排 4K              |
+| --------------------- | ---------------------- | -------------------- |
+| 总尺寸                | 3600×1280（±3%）       | 4096×1455（±3%）     |
+| 总宽高比 width/height | **≈ 2.81**（45/16）    | **≈ 2.81**           |
+| 单格推算              | 宽/5 : 高 ≈ **9:16**   | 宽/5 : 高 ≈ **9:16** |
+| 视觉                  | 圆钮正圆、竖屏 UI 不扁 | 同左                 |
+
+不合格（1024×1024、1:1、总比例≈3.33 等）→ **必须重生成**。
+
+---
+
+## 4. 核查清单
+
+| #   | 项              | 标准                        |
+| --- | --------------- | --------------------------- |
+| 1   | 5 个 Panel 描述 | 完整                        |
+| 2   | 单格 9:16       | prompt + 像素双约束         |
+| 3   | CLI             | `45:16` + 成对 width/height |
+| 4   | image info      | 通过上表                    |
+| 5   | 方案数          | ≥2（artist.md）             |
+
+---
+
+## 5. 进阶
+
+> **Read `refs/artist-master-composite-recipes.md`**
+
+> **TA 从 MC 拆层/抠图**：读 `playcraft-masking` skill（`decompose-layers` 整图分层 vs `segment`/`crop` 单元素）。

package/project-templates/threejs/.claude/skills/playcraft-style-qa/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: playcraft-style-qa
+description: 可玩广告风格质量验证方法论。涵盖 Artist Phase 2 样本自检流程（4 维度）、TA 风格解读检查方法（confidence 判定标准）、TA 微批次验证评分标准（5 级附示例场景）、色彩一致性检查、ICP 提问模板。Artist 在 Phase 2 生成样本后、TA 在 Step 0c 前必读。
+triggers: 风格验证,style qa,风格一致性,style consistency,风格检查,微批次验证,micro-batch,style interpretation,confidence,TA自检,样本质量,品质验证,意图传递,ICP提问
+---
+
+# PlayCraft 风格质量验证方法论
+
+## 0. 谁在什么时候用这个 Skill
+
+| 角色            | 时机                                         | 用哪个章节                    |
+| --------------- | -------------------------------------------- | ----------------------------- |
+| **Artist**      | Phase 2 **ICP 补洞 PNG** 生成后（非 ASR 板） | §1 Artist 自检                |
+| **TA**          | Step 0c（开始任何补全工作前）读 artist-log   | §2 Style Interpretation Check |
+| **TA**          | Stage A 每类素材前 2 个补全完成后            | §3 Micro-Batch Validation     |
+| **Artist + TA** | 需要向对方提问时                             | §5 ICP 提问模板               |
+
+---
+
+## 1. Artist 自检：ICP 补洞文件（artist-handoff-v2）
+
+**不用于** ASR 双板或 MC（已在 ring 3 锁定）。仅当 ICP 要求交付**单张孤立 PNG** 时使用。
+
+对照图：`assets/images/storyboard/master_composite_option_[selectedMcOption].png`（MC concept panel）。
+
+### 自检清单
+
+```
+样本路径：[ICP target path]
+对照图：master_composite_option_[X].png
+
+[ ] 色调一致（Palette Locked hex）
+[ ] 光影方向与 MC 一致
+[ ] 边缘处理与 Style Intent Notes 一致
+[ ] 质感特征匹配
+```
+
+**通过**：记入 artist-log Per-Atom Delivery。**未通过**：重生成或注明 TA 注意事项。
+
+### 快速重生成
+
+```bash
+playcraft tools generate-image \
+  --prompt "... matching locked MC style ..." \
+  --reference-image assets/images/storyboard/master_composite_option_[X].png \
+  --reference-image assets/images/reference/element_state_sheet_[X].png \
+  --output <ICP-path>
+```
+
+---
+
+## 2. TA Style Interpretation Check（Step 0c 必做）
+
+在开始任何补全工作前，阅读 `logs/artist-log.md` 中的 Style Intent Notes，**写出你自己的理解**，并判断 confidence 等级。
+
+### 阅读 Style Intent Notes 的方法
+
+逐条阅读 artist-log 中每个样本的 Style Intent Notes，提取：
+
+1. **主色调**：具体色温描述（暖橙、冷蓝、柔粉……）
+2. **光影方向**：光源位置（左上角 45°、正面平光……）
+3. **边缘处理**：描边有无 + 粗细 + 风格（硬边/柔边）
+4. **质感特征**：材质感（卡通光泽、哑光扁平、写实粗糙……）
+
+### Confidence 判定标准
+
+写到 `logs/ta-log.md` 的 Style Interpretation 表中：
+
+| Confidence | 判定条件                                                                              | 处置方式                                                             |
+| ---------- | ------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
+| **high**   | Artist 提供了具体数值或对比词（如"饱和度约 70%，轮廓线 2px"），你的理解与描述完全一致 | 直接生成                                                             |
+| **medium** | Artist 用形容词描述（如"柔和"、"温暖"），你能理解大方向但无法确定具体参数             | 生成，但在 prompt 中加入你的理解作为约束词                           |
+| **low**    | 描述模糊（如"有点古典风"）、或不同样本的 Style Intent Notes 存在明显矛盾              | **STOP，写问题到 `docs/intent-clarifications.md`，等待 Artist 回答** |
+
+### 写入 ta-log.md 的格式
+
+```markdown
+## Style Interpretation
+
+| #   | Artist Intent（引用 artist-log 原文） | 我的理解                                            | Confidence | 处置    |
+| --- | ------------------------------------- | --------------------------------------------------- | ---------- | ------- |
+| 1   | "warm amber tones, golden highlights" | 主色为 #E8A020 附近的暖橙，高光用米白色渐变         | high       | proceed |
+| 2   | "soft edges, no harsh outlines"       | 无描边，边缘使用 2-3px 柔化过渡（anti-aliasing）    | high       | proceed |
+| 3   | "有一种古典气质"                      | 理解不明确，可能是深色系+金色装饰，也可能是水墨风格 | low        | clarify |
+```
+
+> **规则**：任何一项 confidence = low，都必须先提问，不得继续该类型的素材生成。
+
+---
+
+## 3. Micro-Batch Validation 评分标准（TA）
+
+**触发时机**：每种素材类型前 2 个补全完成后，与 **ASR crop 参考** 或 MC 概念面板并排对比评分。
+
+### 5 级评分标准
+
+| 分数  | 标准                                                                         | 示例场景                                     |
+| ----- | ---------------------------------------------------------------------------- | -------------------------------------------- |
+| **5** | 完美匹配，可以乱真——若不看文件名，看不出哪个是 Artist 原始样本               | 色调、光影、边缘、质感全部一致               |
+| **4** | 良好匹配，细看才发现微小差异——整体风格统一，不影响游戏视觉连贯性             | 高光角度略偏 5°，或饱和度差 ±5%              |
+| **3** | 可接受匹配，整体风格可识别，但有明显属性偏差——在游戏里仔细看会觉得"有点不对" | 色温偏冷了一档，或描边略粗                   |
+| **2** | 较差匹配，风格明显不一致——玩家会注意到这个元素和其他元素"不一样"             | 应该是暖色调却生成了冷色调，边缘风格完全不同 |
+| **1** | 完全不匹配，必须停止——风格完全是另一个方向                                   | 应该是卡通风却生成了写实风，色系完全对立     |
+
+### 评分流程
+
+```
+1. 并排打开 Artist 样本 + 你的第 1、2 个补全
+2. 逐维度对比（色调 / 光影 / 边缘 / 质感）
+3. 给整体打分（1–5）
+4. 写入 ta-log.md 的 Micro-Batch Validation 表
+```
+
+**判断逻辑**：
+
+- Score ≥ 3 → 继续批量生产剩余同类素材
+- Score < 3 → **立即停止此类素材**，调整生成参数（见下方）或提问 ICP
+
+### Score < 3 时的参数调整策略
+
+```bash
+# 问题：色调偏差（最常见）
+# 调整：加强 reference-image 权重（多加一张已通过自检的 Artist 样本）
+playcraft tools generate-image \
+  --reference-image assets/images/storyboard/master_composite_option_[X].png \
+  --reference-image <asr-crop-or-icp-reference>.png
+  --prompt "... [加入具体色调描述，从 Style Intent Notes 中提取]"
+
+# 问题：边缘/描边风格不对
+# 调整：在 prompt 中明确描边参数
+# 原：无描边描述
+# 改：加 "black outline 2px" 或 "no outline, smooth edges"
+
+# 问题：模型选型问题（某模型不擅长该风格）
+# 调整：换模型，保持 prompt 不变（不同模型对同类素材风格差异明显）
+playcraft tools generate-image \
+  --image-model google/gemini-3.1-flash-image-preview \  # 换模型
+  --prompt "[与之前相同]" \
+  --reference-image [同上]
+```
+
+---
+
+## 4. 色彩一致性检查
+
+### 4.1 手动快速检查（单张比较）
+
+当视觉判断不确定时，用 `playcraft image info` 提取色彩信息辅助判断：
+
+```bash
+# 提取参考图（概念图）的色彩信息
+playcraft image info assets/images/storyboard/master_composite_option_[X].png
+# 重点看：dominant colors（主色列表）
+
+# 提取你生成的素材的色彩信息
+playcraft image info assets/images/tiles/tile_001.png
+
+# 对比两张图的 dominant colors：
+# - 主色的色相（H）差异 < 15°：可接受
+# - 主色的色相（H）差异 15–30°：需要在 prompt 中加强色调描述
+# - 主色的色相（H）差异 > 30°：色调严重偏差，重新生成
+```
+
+**参考色彩提取技巧**：
+
+从 `playcraft image info` 的输出中找到 `dominant colors` 字段，记录前 3 个颜色的 Hex 值。在下一次生成时，将这些 Hex 值直接写入 prompt：
+
+```bash
+# 从概念图提取到主色 #E8A020（暖橙）+ #4A2800（深棕）+ #FFFAF0（奶白）
+playcraft tools generate-image \
+  --prompt "... color palette dominated by warm amber #E8A020, dark brown #4A2800, cream white #FFFAF0 ..."
+```
+
+---
+
+### 4.2 自动化批量检查（推荐用于 Micro-Batch Validation）
+
+当需要对一批补全素材做客观量化评估时，使用 `compare-style.template.mjs` 脚本，避免纯靠 LLM 视觉判断的主观性。
+
+**使用步骤**：
+
+```bash
+# 1. 复制脚本模板到 ta-workspace
+cp .claude/skills/playcraft-image-generation/reference/compare-style.template.mjs \
+   ta-workspace/scripts/compare-style.mjs
+
+# 2. 编辑 CONFIG 区域（约 30 秒）：
+#    referenceImage: 你的 Artist 样本路径
+#    targetDir:      你的 TA 补全素材目录
+#    excludeKeywords: 排除 Artist 样本自身（避免自比）
+
+# 3. 运行
+node ta-workspace/scripts/compare-style.mjs
+```
+
+**输出示例**：
+
+```
+📊 色彩风格一致性检查
+   参考图: assets/images/reference/element_state_sheet_[X].png (crop slot)
+
+[COMPARE] asr_crop_ref.png  vs  tile_comp_01.png
+  色相距离（加权）: 8.3°     → ✅ 优秀（< 15°）
+  明度差异:         0.06     → ✅ 优秀（< 0.10）
+  饱和度差异:       0.04     → ✅ 优秀（< 0.10）
+  综合一致性评分:   5 / 5  → ✅ 良好
+
+[COMPARE] tile_sample_1.png  vs  tile_comp_02.png
+  色相距离（加权）: 34.1°    → ❌ 严重偏差（≥ 30°）
+  明度差异:         0.22     → ❌ 严重偏差（≥ 0.20）
+  饱和度差异:       0.09     → ✅ 优秀（< 0.10）
+  综合一致性评分:   1 / 5  → ❌ 偏差过大，需停止
+
+=== 汇总 ===
+  检查文件数: 2
+  平均评分:   3.0 / 5
+  低于阈值数: 1（阈值 3.0）
+  ⚠️  建议：停止低分文件类型的批量生产，调整生成参数或向 Artist 提问 ICP
+```
+
+**评分标准（与 §3 Micro-Batch Validation 对齐）**：
+
+| 综合评分 | 色相距离 | 明度/饱和度差 | 对应 §3 评分 | 处置                       |
+| -------- | -------- | ------------- | ------------ | -------------------------- |
+| 5        | < 15°    | < 0.10        | 4–5          | 继续批量生产               |
+| 4        | < 20°    | < 0.15        | 4            | 继续批量生产               |
+| 3        | < 30°    | < 0.20        | 3            | 勉强可接受，调整参数后继续 |
+| 2        | < 45°    | < 0.30        | 2            | 停止，调整 prompt 后重试   |
+| 1        | ≥ 45°    | ≥ 0.30        | 1            | 停止，向 Artist 提问 ICP   |
+
+> **注意**：脚本基于 `playcraft image info` 的 dominant colors 做色相分析，是色彩维度的客观辅助，不能替代 §3 的整体视觉评估（边缘处理、质感特征等维度需人工判断）。
+
+---
+
+## 5. ICP 提问模板
+
+**原则**：提问必须具体，必须引用文件路径和具体 atom，不能用"风格不对"这种模糊描述。
+
+### TA → Artist 提问格式
+
+```markdown
+| #   | From | To     | Atom/Topic           | Question                                                                                                                                                                                                                      | Raised At  | Status |
+| --- | ---- | ------ | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
+| 1   | TA   | Artist | tile_atom / 边缘风格 | `logs/artist-log.md` Style Intent Notes 中 tile_sample_1.png 的描述是 "soft edges"，但 tile_sample_2.png 的 Anti-Pattern Notes 中写 "avoid blurry edges"。两者相互矛盾——请问边缘应该是柔化过渡（anti-aliasing）还是清晰硬边？ | production | open   |
+```
+
+### TA → Game Designer 提问格式（故事板与 layout-spec 冲突）
+
+```markdown
+| #   | From | To            | Atom/Topic             | Question                                                                                                                                                                                                                                      | Raised At  | Status |
+| --- | ---- | ------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | ------ |
+| 1   | TA   | Game Designer | bg_atom / EndCard 背景 | `assets/images/storyboard/storyboard_confirmed.png` EndCard 帧（右下）显示背景为深蓝色夜景，但 `docs/layout-spec.md` zones.endcard.background 注释写的是"白色/浅色背景以突出 CTA 按钮"。请裁决：以故事板色调为准还是以 layout-spec 注释为准？ | production | open   |
+```
+
+### Artist → TA 回答格式
+
+回答时直接在表格 Status 改为 `answered`，并在同行末尾加 `| Answer |`：
+
+```markdown
+| 1 | TA | Artist | ... | ... | ... | answered | tile_sample_1.png 的 "soft edges" 指 anti-aliasing（无描边）；tile_sample_2.png 的 "avoid blurry edges" 是指不要过度模糊失去形状，两者不冲突。统一结论：无描边，边缘使用 2px anti-aliasing，保持形状清晰。 |
+```
+
+### 常见可问题类型速查
+
+| 疑问类型                       | 提问 Target   | 示例提问                                                               |
+| ------------------------------ | ------------- | ---------------------------------------------------------------------- |
+| Style Intent Notes 描述矛盾    | Artist        | "XXX 样本的描述 A 和描述 B 相互矛盾，请澄清..."                        |
+| 故事板帧与 layout-spec 冲突    | Game Designer | "故事板第 N 帧显示 X，但 layout-spec 写 Y，以谁为准？"                 |
+| Micro-Batch Score < 3 无法提升 | Artist        | "尝试了 3 种参数组合，score 无法超过 3，需要新的 Style Intent 指导..." |
+| 素材类型无 Artist 样本         | Artist        | "atom-tree 中 XXX 类型缺少样本，TA 无法生成对应参考，请提供或指导..."  |

package/project-templates/threejs/.claude/skills/playcraft-text-rendering/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: playcraft-text-rendering
+description: PlayCraft 可玩广告文字渲染完整指南。涵盖全烤图策略（零字体文件）、静态文字图片规格、动态数字 Digit Sprite Strip 规格与运行时帧切割渲染模板、layout-spec textAssets 字段说明、三角色（Artist/TA/Developer）各自职责。任何涉及游戏内文字、字体、数字显示、分数、计时器的场景前必读。
+triggers: 文字,字体,font,text,数字,digit,分数,score,计时器,timer,倒计时,countdown,sprite strip,digit strip,CTA文字,游戏标题,label,艺术字,显示字体,烤图,text rendering
+---
+
+# PlayCraft 文字渲染完整指南
+
+## 0. 核心原则：零字体文件
+
+可玩广告的硬约束是**零外部请求**和**体积最小化**。因此：
+
+- **不使用任何字体文件**（不内嵌 TTF/WOFF，不引用 CDN 字体）
+- **所有可见文字都是图片资产**——和元素、背景一样走 Asset Contract
+- 静态文字烤入图片，动态数字用 Digit Sprite Strip 帧切割渲染
+
+```
+文字类型决策树：
+├── 内容固定不变？
+│   ├── 是 → 静态文字图片（Artist 烤入 Master Composite → TA 提取）
+│   └── 否 → 动态文字
+│       ├── 仅数字/符号？
+│       │   ├── 是 → Digit Sprite Strip（Artist 生成 → Developer 帧切割）
+│       │   └── 否 → 扩展 Sprite Strip 字符集（Game Designer 在 layout-spec 指定）
+```
+
+---
+
+## 1. 静态文字（Static Text）
+
+### 什么是静态文字
+
+游戏中**内容不会变化**的文字元素：
+
+| 示例                       | 典型位置      |
+| -------------------------- | ------------- |
+| 游戏标题                   | Hook 场景顶部 |
+| 关卡名 "Level 1"           | 场景过渡      |
+| "YOU WIN" / "GAME OVER"    | EndCard       |
+| CTA 按钮文字 "Install Now" | EndCard 底部  |
+| 教学引导 "Tap to match"    | Tutorial 场景 |
+
+### 生产流程
+
+1. **Game Designer**：在 `layout-spec.md` `## Text Assets > Static Text` 表中列出所有静态文字，指定资产路径
+2. **Artist**：在 Master Composite 的 concept panel 中，将所有静态文字以**艺术风格**渲染（不是随便加文字——文字本身就是美术的一部分）
+3. **TA**：从 MC concept panel **逐条**提取（`crop` 优先；`segment --text` 最后手段）→ layout-spec 路径
+4. **提取失败** → ICP → **Artist** 交付该 id 的**单张**孤立 PNG（`artist-deliverable-spec.md`）
+5. **Developer**：`loadImage(path)` per Asset Contract
+
+> Rows must appear in `artist-log` **ASR Coverage Matrix** (`Type: text`).
+
+### layout-spec 格式
+
+```markdown
+### Static Text (baked into Master Composite concept panel)
+
+| id       | text content   | asset path                    | notes                    |
+| -------- | -------------- | ----------------------------- | ------------------------ |
+| title    | "Fruit Blast"  | assets/images/ui/title.png    | TA extracts from concept |
+| cta      | "Install Now"  | assets/images/ui/cta_text.png | TA extracts from concept |
+| tutorial | "Tap to match" | assets/images/ui/tutorial.png | TA extracts from concept |
+| win      | "YOU WIN!"     | assets/images/ui/win_text.png | TA extracts from concept |
+```
+
+---
+
+## 2. Digit Sprite Strip（动态数字）
+
+### 什么是 Digit Sprite Strip
+
+一张水平排列的图片，包含所有需要动态显示的字符。每个字符占据等宽的一个 cell。运行时按字符索引切割渲染。
+
+```
+┌────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┬────┐
+│ 0  │ 1  │ 2  │ 3  │ 4  │ 5  │ 6  │ 7  │ 8  │ 9  │ :  │ ,  │ .  │
+└────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┴────┘
+ cell0 cell1 cell2 ...                                         cellN
+```
+
+### 生产流程
+
+1. **Game Designer**：在 `layout-spec.md` `## Text Assets > Digit Sprite Strip` 中定义：
+   - `characters`：字符集字符串（如 `"0123456789:,."`）
+   - `cell size`：单个字符的宽高（如 `64x80`）
+   - `asset path`：如 `assets/images/ui/digits.png`
+2. **Artist**：Phase 2 生成整条 strip 图片（见下方生成命令），确保：
+   - 字符按 `characters` 字符串顺序从左到右排列
+   - 每个字符等宽（= cellWidth），高度 = cellHeight
+   - 艺术风格与 confirmed Master Composite 一致（使用 composite 作 `--reference-image`）
+   - 总图片宽度 = `characters.length × cellWidth`
+   - **约束**：总宽度不得超过 4096px（如 `18 chars × 200px = 3600px` ✓；若超限则减小 cellWidth）
+3. **TA**：验证 strip 尺寸（见下方验证命令），不合规则 resize 修正
+4. **Developer**：运行时帧切割渲染（见下方代码模板）
+
+### Artist 生成命令
+
+```bash
+# 计算总尺寸
+# totalWidth = characters.length × cellWidth（必须 ≤ 4096）
+# totalHeight = cellHeight
+
+playcraft tools generate-image \
+  --prompt "Horizontal digit sprite strip on solid [BG_COLOR] background. Single row of characters, left-to-right in exact order: [CHAR_1], [CHAR_2], ..., [CHAR_N]. Each character occupies exactly [CELL_W]px width × [CELL_H]px height. [N] characters total, evenly spaced, no gaps. Art style: [SAME style as confirmed Master Composite]. Characters rendered in [FONT_STYLE] with [COLOR] on [BG]. No extra decoration, no borders between characters, no labels." \
+  --output assets/images/ui/digits.png \
+  --reference-image assets/images/storyboard/master_composite.png \
+  --image-size 1K \
+  --image-model gpt-image-2
+```
+
+> 若 `totalWidth × totalHeight` 小于模型最小输出（1024×1024），模型会自动适配。生成后 TA 需 resize 到精确尺寸。
+
+### TA 验证命令
+
+```bash
+# 检查尺寸是否精确匹配
+playcraft image info assets/images/ui/digits.png
+# 期望输出：width = characters.length × cellWidth, height = cellHeight
+
+# 如尺寸不匹配，resize 修正：
+playcraft image resize \
+  --input assets/images/ui/digits.png \
+  --width [characters.length × cellWidth] \
+  --height [cellHeight] \
+  --output assets/images/ui/digits.png
+```
+
+### layout-spec 格式
+
+```markdown
+### Digit Sprite Strip (for dynamic numbers)
+
+- **Characters**: `0123456789:,.`
+- **Cell size**: 64x80
+- **Asset path**: `assets/images/ui/digits.png`
+```
+
+### 常见字符集
+
+| 游戏类型      | 推荐字符集           | 说明    |
+| ------------- | -------------------- | ------- |
+| 仅分数        | `0123456789`         | 10 字符 |
+| 分数 + 计时器 | `0123456789:.`       | 12 字符 |
+| 分数 + 倍率   | `0123456789x+,.`     | 14 字符 |
+| 完整          | `0123456789:,.x+-/%` | 18 字符 |
+
+> Game Designer 根据项目实际需求在 layout-spec 中指定，不使用固定字符集。
+
+---
+
+## 3. Developer 运行时渲染
+
+### Canvas 2D 帧切割
+
+```javascript
+const DIGIT_CHARS = '0123456789:,.'; // ← from layout-spec
+const CELL_W = 64; // ← from layout-spec
+const CELL_H = 80; // ← from layout-spec
+const digitImg = await loadImage('assets/images/ui/digits.png');
+
+function drawText(ctx, text, x, y, scale = 1) {
+  const w = CELL_W * scale;
+  const h = CELL_H * scale;
+  for (let i = 0; i < text.length; i++) {
+    const charIdx = DIGIT_CHARS.indexOf(text[i]);
+    if (charIdx >= 0) {
+      ctx.drawImage(
+        digitImg,
+        charIdx * CELL_W,
+        0,
+        CELL_W,
+        CELL_H, // source rect
+        x + i * w,
+        y,
+        w,
+        h, // dest rect
+      );
+    }
+  }
+}
+
+// Usage
+drawText(ctx, '12345', 100, 50); // score
+drawText(ctx, '0:30', 300, 10, 0.75); // timer (scaled down)
+```
+
+### 对齐辅助
+
+```javascript
+function drawTextCentered(ctx, text, centerX, y, scale = 1) {
+  const totalW = text.length * CELL_W * scale;
+  drawText(ctx, text, centerX - totalW / 2, y, scale);
+}
+
+function drawTextRight(ctx, text, rightX, y, scale = 1) {
+  const totalW = text.length * CELL_W * scale;
+  drawText(ctx, text, rightX - totalW, y, scale);
+}
+```
+
+### PlayCanvas Engine (sprite frame)
+
+如果项目使用 PlayCanvas Engine，可以用 TextureAtlas 方式注册帧：
+
+```javascript
+const atlas = new pc.TextureAtlas();
+atlas.setFrame('0', { rect: new pc.Vec4(0, 0, CELL_W, CELL_H) });
+atlas.setFrame('1', { rect: new pc.Vec4(CELL_W, 0, CELL_W, CELL_H) });
+// ... register all chars
+
+const sprite = new pc.Sprite(app.graphicsDevice, {
+  atlas: atlas,
+  frameKeys: DIGIT_CHARS.split(''),
+});
+```
+
+---
+
+## 4. 角色职责速查
+
+| 角色              | 文字相关职责                                                                                       |
+| ----------------- | -------------------------------------------------------------------------------------------------- |
+| **Game Designer** | 在 layout-spec `textAssets` 中定义：静态文字列表 + digit strip 字符集/尺寸/路径                    |
+| **Artist**        | ① Master Composite concept panel 中渲染所有静态文字（艺术风格）；② Phase 2 生成 digit sprite strip |
+| **TA**            | ① 从 composite 提取静态文字图片（segment → resize）；② 验证 digit strip 尺寸合规                   |
+| **Developer**     | ① 静态文字按 Asset Contract 路径加载图片；② digit strip 帧切割渲染（上方代码模板）                 |
+
+---
+
+## 5. 注意事项
+
+1. **文字是美术的一部分**——Artist 不是"随便加文字"，而是将文字作为视觉设计元素融入 concept
+2. **digit strip 字符顺序必须与 layout-spec 一致**——Developer 按索引切割，顺序错了显示就错
+3. **不要用 CSS text-shadow / -webkit-text-stroke 模拟艺术字**——这不是 web 页面，是游戏
+4. **CTA 按钮文字也是图片**——按钮背景 + 文字都从 composite 提取，Developer 只管点击事件
+5. **多语言场景**：如需多语言，Game Designer 在 layout-spec 中为每种语言指定独立的文字资产路径，Artist 为每种语言生成对应文字