@playcraft/cli 0.0.41 → 0.0.42

package/dist/commands/tools-generation.js

@@ -2,7 +2,7 @@ import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
 import { AgentApiClient } from '../utils/agent-api-client.js';
-import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, } from './tools-utils.js';
+import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
 function isMasterCompositeStripRequest(opts) {
     if (opts.aspectRatio === '45:16')
         return true;
@@ -176,8 +176,6 @@ export function registerGenerationCommands(tools) {
             }
             const referenceImages = await collectReferenceImagePayloads(paths);
             const client = new AgentApiClient();
-            const timeoutMs = opts.timeout * 1000;
-            const timeoutPromise = new Promise((_, reject) => setTimeout(() => reject(new Error(`Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`)), timeoutMs));
             const imageCount = Math.min(Math.max(1, opts.count ?? 1), 10);
             const requestPromise = client.post('/generate-image', {
                 prompt: opts.prompt,
@@ -188,7 +186,7 @@ export function registerGenerationCommands(tools) {
                 ...(modelRef ? { imageModelRef: modelRef } : {}),
                 ...(imageCount > 1 ? { imageCount } : {}),
             });
-            return Promise.race([requestPromise, timeoutPromise]);
+            return raceWithTimeout(requestPromise, opts.timeout * 1000, `Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`);
         };
         const enrichError = (err, modelRef) => {
             const msg = err instanceof Error ? err.message : String(err);

package/dist/commands/tools-utils.js

@@ -20,6 +20,25 @@ export function handleError(err) {
     console.error(`Error: ${msg}`);
     process.exit(1);
 }
+/**
+ * Race a promise against a timeout. Clears the timer when the promise settles so
+ * short-lived CLI processes exit immediately (uncleared timers keep Node alive).
+ */
+export async function raceWithTimeout(promise, timeoutMs, timeoutMessage) {
+    if (timeoutMs <= 0)
+        return promise;
+    let timeoutId;
+    const timeoutPromise = new Promise((_, reject) => {
+        timeoutId = setTimeout(() => reject(new Error(timeoutMessage)), timeoutMs);
+    });
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutId !== undefined)
+            clearTimeout(timeoutId);
+    }
+}
 /** Fallback extension from API mime when magic-byte sniff fails. */
 export function extensionForImageMime(mimeType) {
     const base = mimeType.toLowerCase().split(';')[0]?.trim() ?? '';

package/dist/utils/version-checker.js

@@ -6,7 +6,6 @@ import updateNotifier from 'update-notifier';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
-import { promptForUpdate } from './updater.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 let packageJson;
@@ -20,11 +19,14 @@ function getPackageJson() {
     return packageJson;
 }
 /**
- * 检查版本更新（非阻塞）
- * 使用 update-notifier 进行后台检查，24小时内最多检查一次
- * @param pkg 可选的 package.json 对象，如果不提供则自动读取
+ * 检查版本更新（非阻塞、非交互）
+ * 使用 update-notifier 打印一行提示；交互式更新请用 `playcraft upgrade`。
+ * 避免在普通 one-shot 命令结束后仍阻塞 stdin（inquirer 会导致进程不退出）。
  */
 export function checkForUpdates(pkg) {
+    if (process.env.PLAYCRAFT_SKIP_UPDATE_CHECK === '1') {
+        return;
+    }
     const packageData = pkg || getPackageJson();
     // 只在 TTY 环境中检查（避免在 CI/CD 中显示提示）
     if (!process.stdout.isTTY) {
@@ -35,17 +37,12 @@ export function checkForUpdates(pkg) {
             pkg: packageData,
             updateCheckInterval: 1000 * 60 * 60 * 24, // 24 小时
         });
-        // 如果有更新可用，触发交互式提示
         if (notifier.update) {
-            // 延迟显示，避免影响命令执行
-            setImmediate(() => {
-                promptForUpdate(notifier.update, packageData.version);
-            });
+            notifier.notify({ defer: false, isGlobal: true });
         }
     }
-    catch (error) {
+    catch {
         // 静默失败，不影响 CLI 正常使用
-        // 网络错误或其他问题不应该阻止用户使用 CLI
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.41",
+  "version": "0.0.42",
   "private": false,
   "type": "module",
   "bin": {
@@ -27,8 +27,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.42",
-    "@playcraft/common": "^0.0.30",
+    "@playcraft/build": "^0.0.43",
+    "@playcraft/common": "^0.0.31",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",

package/project-template/.claude/agents/designer.md

@@ -38,13 +38,13 @@ allowedTools:
 2. If `subagent_stop: true` and `subagent: designer` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**; no duplicate MC/ASR.
 3. Branch:
 
-| Condition                                              | This round only                                                                                                                                      | On STOP                                                                                    |
-| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `stage: style_exploration`, `#2a` not passed           | Phase 1 Skill Discovery (art-style-guide + ad-psychology + storyboard) → `refs/designer-style-exploration-flow.md` Steps 2–5 → `gates.#2a = pending` | `gate_pending: "2a"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2a"` |
-| `#2a` passed, `selectedMcOption` set, `#2b` not passed | **ASR 双板** (UI + element state sheets) + style-exploration + designer-log — do **not** regenerate MC options                                       | `gate_pending: "2b"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2b"` |
-| `stage: production`, Gate #2b passed                   | Ph.2: audio + digit strip + VisualAtom status (ASR-covered → `done`; ICP gaps only)                                                                  | `waiting_for: orchestrator`, `next_orchestrator_action: "Invoke @technical-artist"`        |
-| `stage: rework`, routeTo Designer                      | Fix paths in review-report / ICP only                                                                                                                | `waiting_for: orchestrator`, `next_orchestrator_action: "Resume developer integration"`    |
-| `devStatus: blocked_upstream`, routeTo Designer        | Upstream blocker fixes per developer-log                                                                                                             | Same as rework scoped fix                                                                  |
+| Condition                                              | This round only                                                                                                                                      | On STOP                                                                                         |
+| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| `stage: style_exploration`, `#2a` not passed           | Phase 1 Skill Discovery (art-style-guide + ad-psychology + storyboard) → `refs/designer-style-exploration-flow.md` Steps 2–5 → `gates.#2a = pending` | `gate_pending: "2a"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2a"`      |
+| `#2a` passed, `selectedMcOption` set, `#2b` not passed | **ASR 双板** (UI + element state sheets) + style-exploration + designer-log — do **not** regenerate MC options                                       | `gate_pending: "2b"`, `waiting_for: user_gate`, `next_orchestrator_action: "Run Gate #2b"`      |
+| `stage: production`, Gate #2b passed                   | Ph.2: audio + digit strip + VisualAtom status (ASR-covered → `done`; ICP gaps only)                                                                  | `waiting_for: orchestrator`, `next_orchestrator_action: "Invoke @technical-artist"`             |
+| `stage: ui_rework`, routeTo Designer                   | Fix paths in UI Diff report / ICP only                                                                                                               | `waiting_for: orchestrator`, `next_orchestrator_action: "Re-invoke @developer after ui_rework"` |
+| `devStatus: blocked_upstream`, routeTo Designer        | Upstream blocker fixes per developer-log                                                                                                             | Same as rework scoped fix                                                                       |
 
 4. Append `--- PLAYCRAFT_STOP ---` with `role: designer` and current `gate_pending` / `waiting_for`.
 
@@ -93,7 +93,7 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 
 ## Tools
 
-> **All CLI surfaces + deliverable tables**: read **`refs/designer-deliverable-spec.md`**. Before any image generation, invoke **`playcraft-image-generation`** (model / reference / background). Phase 1: `playcraft-storyboard` (MC) + `playcraft-asset-state-sheet` (ASR 双板).
+> **All CLI surfaces + deliverable tables**: read **`refs/designer-deliverable-spec.md`**. Before any image generation, invoke **`playcraft-image-generation`** (model / reference / background). Phase 1: `playcraft-storyboard` (MC — **only** `mulerouter/gpt-image-2` or `mulerouter/nano-banana-2`) + `playcraft-asset-state-sheet` (ASR 双板，模型与 MC 一致).
 
 ### Phase 1 — Style exploration
 
@@ -110,7 +110,11 @@ Full element sets & TA pipelines; single MC before Gate #2; audio before style l
 2. MC concept panel = **real game**, not sketch — all key element types visible; storyboards mandatory for Gate #2 narrative lock.
 3. **≥2 MC options** before #2a unless user pre-locked reference; **ASR only after** `selectedMcOption`.
 4. MC = **5×完整 9:16 H5** (e.g. 3600×1280 or 4096×1455); never `1:1` / `10:3`; verify with `playcraft image info`.
+   4b. **MC models whitelist only** — `mulerouter/gpt-image-2` or `mulerouter/nano-banana-2` (provider prefix required); **never** gemini/flux/hy-image/wan/qwen or bare `gpt-image-2` for MC (see `playcraft-storyboard` §3).
 5. **ASR: zero overlap** — UI 板与元素板各自网格无接触；有重叠则重生成。
 6. **No audio** until style confirmed (#2b).
 7. **Layout Spec** binding — paths, palette, naming; Palette Locked documents MC vs spec delta.
 8. **English prompts**; **size gate** after every generation; **no VisualAtom `done` without ASR Coverage Matrix row**.
+9. **mediaGroups first for audio** — read `atom-plan.json` → `skillsMatch.mediaGroups` for AudioAtom matches (BGM/SFX); if a pre-matched audio exists, link it directly (`playcraft skills link`) instead of generating from scratch. Skip only when quality/mood mismatch (document reason in `dagRevisions`).
+10. **Skill Preflight before Phase 2** — before generating audio or digit strips, read relevant Skills: `playcraft-audio-generation`, `playcraft-text-rendering`, `playcraft-image-generation` (§ background). Fill `designer-log.md` § Skill Preflight table. Do not "freelance" — follow platform patterns.
+11. **Update atom status on completion** — after each atom is done: update `atom-plan.json` → `atoms[].status = "done"` + `atoms[].actualOutput = "<path>"` (or `"ASR:<sheet>:<region>"`). Write `atom-plan.md` § Asset Skill Context. **Never** leave atoms at `pending` after delivery.

package/project-template/.claude/agents/developer.md

@@ -1,5 +1,5 @@
 ---
-description: "Developer: final owner of Dev preview — npm run dev self-check; UI+gameplay+assets; route TA/Designer rework via ICP. No playcraft build for done."
+description: "Developer: ui_pass (UI shell) + gameplay_pass (core logic) — npm run dev; devStatus ui_ready then ready. No playcraft build for done."
 allowedTools:
   - "Read"
   - "Grep"
@@ -24,26 +24,29 @@ allowedTools:
 
 ## Agent Conduct
 
-> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; own devUrl; handoff `Invoke @reviewer` — do not set `stage: review`.
+> Full: [docs/team/agent-conduct.md](../../docs/team/agent-conduct.md). **On invoke, follow ## Runtime**; own devUrl; handoff `Invoke @reviewer ui_diff` or `load_check` — do not set mainline `stage`.
 
 ## Runtime (on invoke)
 
-1. Read `docs/project-state.md` → parse `## Agent handoff` YAML.
+1. Read `docs/project-state.md` → parse `## Agent handoff` YAML + current `stage`.
 2. If `subagent_stop: true` and `subagent: developer` and `waiting_for: orchestrator` → **Already STOPPED — waiting for orchestrator**.
 3. Branch:
 
-| Condition            | This round only                                                                                                                                                                 | On STOP                                                                                                                                                     |
-| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `stage: integration` | **Upstream Intake** (`developer-log`) → Spec Quick-Check (30s) → **Skill Preflight** → scaffold → PGS + scenes + `index.html` → bind **real** assets → `npm run dev` self-check | `blocked_upstream` → STOP with blockers; else `devStatus: ready` + devUrl → `next_orchestrator_action: "Invoke @reviewer"` (**do not** set `stage: review`) |
-| `stage: rework`      | Only Action Items with `routeTo: Developer`                                                                                                                                     | Re-integrate → `devStatus: ready` → `next_orchestrator_action: "Invoke @reviewer"`                                                                          |
+| Condition              | This round only                                                                                                                                                                                                  | On STOP                                                                                                                               |
+| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| `stage: ui_pass`       | Upstream Intake → Spec Quick-Check → Skill Preflight → scaffold → **UI Pass Plan** → scenes + `index.html` + asset bind → scene navigation + simple states → **`npm run dev`** self-check (**no core gameplay**) | `blocked_upstream` → STOP with blockers; else `devStatus: ui_ready` + devUrl → `next_orchestrator_action: "Invoke @reviewer ui_diff"` |
+| `stage: ui_rework`     | Only UI Diff Action Items with `routeTo: Developer`                                                                                                                                                              | Re-fix UI → `devStatus: ui_ready` → `next_orchestrator_action: "Invoke @reviewer ui_diff"`                                            |
+| `stage: gameplay_pass` | **Gameplay Pass Plan** → PGS + core rules + first level success + CTA on existing UI shell → `npm run dev` self-check                                                                                            | `devStatus: ready` + devUrl → `next_orchestrator_action: "Invoke @reviewer load_check"` (**do not** set `stage` or Gate #3)           |
 
 4. Append `--- PLAYCRAFT_STOP ---` (`role: developer`).
 
-**Track done:** All `assignTo: Developer` atoms `done`; `devStatus: ready`, no open `devBlockers`; handoff `Invoke @reviewer` (orchestrator sets `stage: review`). Bind visuals per **`layout-spec`**: contract paths, zones, **`atlasPath` + `frameId`** (+ WebP atlas + JSON sidecar) as in [`refs/developer-impl-cookbook.md`](refs/developer-impl-cookbook.md).
+**Track done (`ui_pass`):** § UI Pass Plan complete (Scene-Asset Binding + scene navigation + Risk all `[x]`); real assets bound; scene switch works for MC panels; `devStatus: ui_ready`, no open `devBlockers`; handoff `Invoke @reviewer ui_diff`.
 
-**Prerequisites:** Production Pipeline Wave 1 + Wave 2 `done`; TA Compliance green; contract asset files exist on disk.
+**Track done (`gameplay_pass`):** § Gameplay Pass Plan complete; PGS + first level guaranteed success; CTA works; `devStatus: ready`; handoff `Invoke @reviewer load_check`.
 
-**Execute (L2):** [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md) (**Step 0** intake → Steps 1–8) + [`refs/developer-impl-cookbook.md`](refs/developer-impl-cookbook.md) + [`refs/developer-dev-handoff.md`](refs/developer-dev-handoff.md) (dev ready gate).
+**Prerequisites:** Production Pipeline Wave 1 + Wave 2 `done`; TA path compliance green; contract asset files exist on disk.
+
+**Execute (L2):** [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md) (ui_pass Steps 0–N + gameplay_pass Steps 0–N) + [`refs/developer-impl-cookbook.md`](refs/developer-impl-cookbook.md) + [`refs/developer-dev-handoff.md`](refs/developer-dev-handoff.md).
 
 ## Mission
 
@@ -52,47 +55,51 @@ allowedTools:
 ## Goals
 
 **Core responsibilities (priority #1 > #2 > #3):**
-(1) **UI** matches `layout-spec` + MC / style-exploration Visual Intent.
-(2) **Gameplay** matches `design-brief` + `atom-plan` / PGS; **first level guaranteed success**.
-(3) **Dev preview** — `npm run dev` clean; assets load; CTA / audio / state machine work; **you own what appears at devUrl** before Reviewer and the user.
+(1) **UI shell** matches `layout-spec` + MC / style-exploration Visual Intent (`ui_pass`).
+(2) **Gameplay** matches `design-brief` + `atom-plan` / PGS; **first level guaranteed success** (`gameplay_pass`).
+(3) **Dev preview** — `npm run dev` clean; assets load; **you own what appears at devUrl** before Reviewer and the user.
+
+| Phase               | You succeed when                                                                                                                                                                                               |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`ui_pass`**       | § UI Pass Plan complete; Skill Preflight + scaffold; scenes + `index.html` with **real** assets; scene switching for Hook/Tutorial/EndCard/CTA; **no core gameplay rules**; `devStatus: ui_ready` + **devUrl** |
+| **`gameplay_pass`** | § Gameplay Pass Plan complete; PGS + state machine + first level success + CTA on verified UI; `devStatus: ready` + **devUrl**                                                                                 |
 
-| Phase             | You succeed when                                                                                                                                                                                                                                 |
-| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`integration`** | Skill Preflight + PGS + scenes + `index.html` with **real** assets; Experience Flow → Code Mapping; first level guaranteed success; **Dev self-check** (UI + gameplay + browser); **no open upstream blockers**; `devStatus: ready` + **devUrl** |
+**`ui_pass` scope (allowed):** scene switching, element placement, simple state display (e.g. button hover/active), asset binding, layout zones.
 
-**Deprioritized:** `playcraft build` (not required for ready/done); asking the **user** to run dev (orchestrator shares devUrl at Gate #3); placeholder art; `devStatus: ready` with open `devBlockers`; any work during `stage: production`.
+**`ui_pass` scope (forbidden):** core gameplay rules — scoring, elimination, match logic, level win/lose, Near-Win mechanics, difficulty tuning.
 
-**Optimize for:** UI + gameplay fidelity + Hook→Tutorial→Gameplay→End Card. **Non-goals:** inventing art; coding before TA wave done; skipping `blocked` atoms; bundle-size tradeoffs over fidelity.
+**Deprioritized:** `playcraft build`; asking the **user** to run dev; placeholder art; `devStatus: ui_ready`/`ready` with open `devBlockers`; any work during `stage: production`.
 
 ## Identity
 
 - **Final owner of Dev preview** — acceptance bar for devUrl
 - Implements design docs; does not improvise them
-- `integration`: logic + scenes + real asset bindings + dev iteration; drive TA/Designer rework when gaps surface
+- Two-phase delivery: UI convergence first, gameplay second
 
 ## File Access
 
 ### Read before starting
 
-| File                        | Purpose                                                                     |
-| --------------------------- | --------------------------------------------------------------------------- |
-| `docs/project-state.md`     | Stage: `integration` (or `rework`) — verify Production Pipeline Wave 2 done |
-| `docs/design-brief.md`      | Flow, levels, style direction                                               |
-| `docs/layout-spec.md`       | Board, element IDs, zones, `assetMapping`, **`atlasPath` / `frameId`**      |
-| `docs/atom-plan.json`       | Developer atoms, `skillRef`, `dependsOn`（机器源）                          |
-| `docs/atom-plan.md`         | Acceptance criteria + Impl/Asset/TA Context                                 |
-| `docs/style-exploration.md` | Confirmed style / MC context                                                |
-| `logs/ta-log.md`            | TA manifest + compliance (required before integration)                      |
+| File                        | Purpose                                                                |
+| --------------------------- | ---------------------------------------------------------------------- |
+| `docs/project-state.md`     | Stage: `ui_pass` / `ui_rework` / `gameplay_pass`                       |
+| `docs/design-brief.md`      | Flow, levels, style direction (gameplay_pass)                          |
+| `docs/layout-spec.md`       | Board, element IDs, zones, `assetMapping`, **`atlasPath` / `frameId`** |
+| `docs/atom-plan.json`       | Developer atoms, `skillRef`, `dependsOn`                               |
+| `docs/atom-plan.md`         | Acceptance criteria + Impl/Asset/TA Context                            |
+| `docs/style-exploration.md` | Confirmed style / MC context                                           |
+| `logs/ta-log.md`            | TA manifest + compliance (required before ui_pass)                     |
+| `logs/review-report.md`     | UI Diff Report (ui_rework only)                                        |
 
 ### Write during work
 
-| Target                                                              | Use                                                     |
-| ------------------------------------------------------------------- | ------------------------------------------------------- |
-| `logs/developer-log.md`                                             | From `templates/developer-log.template.md`              |
-| `docs/atom-plan.json`                                               | `atoms[].status`                                        |
-| `docs/atom-plan.md`                                                 | Impl Skill Context, DAG Revisions                       |
-| `docs/project-state.md`                                             | Stage / dev fields (orchestrator owns some transitions) |
-| `game/gameplay/`, `game/config/`, `game/scenes/`, `game/index.html` | Implementation                                          |
+| Target                                                              | Use                                        |
+| ------------------------------------------------------------------- | ------------------------------------------ |
+| `logs/developer-log.md`                                             | From `templates/developer-log.template.md` |
+| `docs/atom-plan.json`                                               | `atoms[].status`                           |
+| `docs/atom-plan.md`                                                 | Impl Skill Context, DAG Revisions          |
+| `docs/project-state.md`                                             | dev fields (orchestrator owns `stage`)     |
+| `game/gameplay/`, `game/config/`, `game/scenes/`, `game/index.html` | Implementation                             |
 
 ## Tools
 
@@ -101,33 +108,17 @@ allowedTools:
 | `npm run dev`                                  | **Primary** — local preview (`package.json` `scripts.dev`) |
 | `playcraft skills list \| match \| read`       | Skill discovery / recipes                                  |
 | `playcraft image info`, `playcraft audio info` | Static asset verify                                        |
-| `playcraft tools research --focus code`        | Algorithm research                                         |
-
-> **Integration:** Read [`refs/developer-dev-handoff.md`](refs/developer-dev-handoff.md) before `devStatus: ready`.
-
-## Error Escalation
-
-| Situation                           | Action                                         |
-| ----------------------------------- | ---------------------------------------------- |
-| Missing / bad upstream asset in Dev | Upstream rework; `devStatus: blocked_upstream` |
-| Wrong dimensions                    | routeTo **TA** via ICP                         |
-| PGS skill missing                   | Closest skill + implement                      |
-| Layout contradictions               | **PM** in `intent-clarifications.md`           |
-| Dev server fails                    | `devStatus: failed`; log in project-state      |
-
-**NEVER** skip blockers, invent placeholders, or mark `devStatus: ready` with open upstream issues.
-
-## DAG Modification Protocol
-
-- Missing atom → add row; unnecessary → `skipped`; spec edits → update row + log
-- **Always append DAG Revisions; direction changes → STOP and report**
+| `playcraft tools research --focus code`        | Algorithm research (gameplay_pass)                         |
 
 ## Important Rules
 
-1. **Runtime + handoff** govern STOP — do not self-advance `stage` to `review`.
-2. **Dev preview owner** — `npm run dev`; `devStatus: ready` only when UI + gameplay + assets pass and blockers closed.
-3. **`integration`** — load **real** files at Asset Contract paths; **WebP atlas + JSON sidecar** per `layout-spec` / cookbook; no placeholders for missing upstream — ICP + `blocked_upstream`.
-4. **No `playcraft build` for done** — layout-spec + storyboard = UI truth; design-brief + PGS = gameplay truth.
-5. **Test-first PGS** — write testCases before rules; first level guaranteed success.
-6. **Atlas binding** — `frameId` 来自 WebP atlas 配对的 JSON sidecar（`layout-spec` / cookbook），不猜裁；零字体文件（image text + digit strip）。
-7. **Skill Preflight** — 见 [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md) Step 3；优先 `.claude/skills/<skillRef>/`（PM 已 `skills link`），断链才 `playcraft skills read`；必须 `scaffold` 后再写 `game/`。
+1. **Runtime + handoff** govern STOP — do not self-advance mainline `stage`.
+2. **UI Pass Plan before UI code** — hook enforces on `ui_pass` STOP.
+3. **Gameplay Pass Plan before PGS logic** — hook enforces on `gameplay_pass` STOP.
+4. **`ui_pass` → `devStatus: ui_ready`**; **`gameplay_pass` → `devStatus: ready`** — never swap.
+5. **No core gameplay in `ui_pass`** — Reviewer `ui_diff` compares UI to MC only.
+6. **Do not rewrite UI in `gameplay_pass`** unless open UI Diff items remain.
+7. **Real assets at contract paths** — WebP atlas + JSON sidecar per cookbook; no placeholders.
+8. **Skill Preflight** — see [`refs/developer-phase1-flow.md`](refs/developer-phase1-flow.md); scaffold before `game/` edits.
+9. **Update atom status on completion** — `atom-plan.json` + Impl Skill Context after each atom.
+10. **No `playcraft build` for done** — endpoint is user devUrl acceptance at Gate #3.

package/project-template/.claude/agents/refs/README.md

@@ -32,9 +32,10 @@
 | `skills/playcraft-asset-state-sheet`   | `agents/designer.md`, `designer-deliverable-spec.md`           | ASR 双板规范                                                            |
 | `designer-style-exploration-flow.md`   | `agents/designer.md`                                           | Phase 1 Step 2–5：MC 生成、#2a 包、ASR 双板、#2b 收尾与 STOP            |
 | `developer-impl-cookbook.md`           | `agents/developer.md`, `refs/developer-phase1-flow.md`         | index.html 骨架 + Atlas/WebP+JSON 绑定 + CTA handler                    |
-| `developer-phase1-flow.md`             | `agents/developer.md`                                          | `integration` 全流程（Spec/DAG/Scaffold/资产绑定/Completion）           |
-| `developer-dev-handoff.md`             | `agents/developer.md`, `refs/developer-impl-cookbook.md`       | Dev 迭代节奏 + UI/玩法勾选 + upstream blockers + devStatus ready        |
-| `reviewer-six-dimension-eval.md`       | `agents/reviewer.md`                                           | Dev 走查 + 全流程 Phase 1–5 + 六维细则/评分/veto + Rework 机制          |
+| `developer-phase1-flow.md`             | `agents/developer.md`                                          | `ui_pass` + `gameplay_pass` + `ui_rework` 全流程                        |
+| `developer-dev-handoff.md`             | `agents/developer.md`, `refs/developer-impl-cookbook.md`       | Dev 迭代节奏 + ui_ready/ready + upstream blockers                       |
+| `reviewer-convergence-eval.md`         | `agents/reviewer.md`                                           | design_check + ui_diff + load_check 流程                                |
+| `reviewer-six-dimension-eval.md`       | _(deprecated)_                                                 | 指向 `reviewer-convergence-eval.md`                                     |
 | `ta-tools-reference.md`                | `agents/technical-artist.md`                                   | 全工具命令表（AI 生成/3D/精灵图/图像/音频）                             |
 | `ta-pipeline-cookbook.md`              | `agents/technical-artist.md`                                   | **Step 0–2** 脚本 + TA Step 0–D pipeline + Compliance 全表 + 引用图规则 |
 | `ta-atlas-deliverable-standard.md`     | `agents/technical-artist.md`, `refs/ta-pipeline-cookbook.md`   | WebP 运行时默认、atlas `.webp`+`.json`、分组与合规、转码示例            |
@@ -46,18 +47,23 @@
 
 ## 按 invoke 场景反查
 
-| Stage / 触发                     | Sub-agent        | 应该读的 refs（按顺序）                                                                                                |
-| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| `pm` 首次 invoke                 | PM               | `pm-workflow-detail.md` (Steps 1–8)                                                                                    |
-| `style_exploration`, Gate #2a 前 | Designer         | `designer-style-exploration-flow.md` (Steps 2–3) + `designer-deliverable-spec.md` § MC                                 |
-| `style_exploration`, Gate #2b 前 | Designer         | `designer-style-exploration-flow.md` (4–5) + `designer-handoff-v2-checklist.md` + `designer-deliverable-spec.md`       |
-| `production`, Wave 1             | Designer         | `designer-deliverable-spec.md` § Phase 2 + audio skills                                                                |
-| `production`, Wave 2 (TA)        | Technical Artist | `ta-pipeline-cookbook.md` (**Step 0a** intake → Step 0 → 2) → `ta-atlas-deliverable-standard.md`                       |
-| `integration`, Developer         | Developer        | `developer-phase1-flow.md` (**Step 0** intake → Steps 1–8) → `developer-impl-cookbook.md` → `developer-dev-handoff.md` |
-| `review`                         | Reviewer         | `reviewer-six-dimension-eval.md` (Step 0 → Phases 1–5)                                                                 |
-| `rework`, routeTo TA             | Technical Artist | `ta-pipeline-cookbook.md` (scoped fixes) + `ta-atlas-deliverable-standard.md`                                          |
-| `rework`, routeTo Designer       | Designer         | `designer-deliverable-spec.md` + `designer-handoff-v2-checklist.md` + `designer-color-audio-recipes.md`                |
-| spec-gap (any)                   | PM               | `pm-workflow-detail.md` § Atlas grouping + layout/atom patch                                                           |
+| Stage / 触发                     | Sub-agent        | 应该读的 refs（按顺序）                                                                                          |
+| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `pm` 首次 invoke                 | PM               | `pm-workflow-detail.md` (Steps 1–8)                                                                              |
+| `style_exploration`, Gate #2a 前 | Designer         | `designer-style-exploration-flow.md` (Steps 2–3) + `designer-deliverable-spec.md` § MC                           |
+| `style_exploration`, Gate #2b 前 | Designer         | `designer-style-exploration-flow.md` (4–5) + `designer-handoff-v2-checklist.md` + `designer-deliverable-spec.md` |
+| `production`, Wave 1             | Designer         | `designer-deliverable-spec.md` § Phase 2 + audio skills                                                          |
+| `production`, Wave 2 (TA)        | Technical Artist | `ta-pipeline-cookbook.md` (**Step 0a** intake → Step 0 → 2) → `ta-atlas-deliverable-standard.md`                 |
+| `pm` STOP, Gate #1 pending       | Reviewer         | `reviewer-convergence-eval.md` § design_check Gate #1                                                            |
+| `style_exploration`, Gate #2b 前 | Reviewer         | `reviewer-convergence-eval.md` § design_check Gate #2b                                                           |
+| `ui_pass`, Developer             | Developer        | `developer-phase1-flow.md` Part A → `developer-impl-cookbook.md` → `developer-dev-handoff.md`                    |
+| `ui_review`                      | Reviewer         | `reviewer-convergence-eval.md` § ui_diff + `playwright-cli` skill                                                |
+| `ui_rework`, Developer           | Developer        | `developer-phase1-flow.md` Part B + UI Diff Report                                                               |
+| `gameplay_pass`, Developer       | Developer        | `developer-phase1-flow.md` Part C → `developer-impl-cookbook.md`                                                 |
+| `gameplay_pass`, load_check      | Reviewer         | `reviewer-convergence-eval.md` § load_check + `playwright-cli` skill                                             |
+| `ui_rework`, routeTo TA          | Technical Artist | `ta-pipeline-cookbook.md` (scoped fixes) + `ta-atlas-deliverable-standard.md`                                    |
+| `ui_rework`, routeTo Designer    | Designer         | `designer-deliverable-spec.md` + `designer-handoff-v2-checklist.md` + `designer-color-audio-recipes.md`          |
+| spec-gap (any)                   | PM               | `pm-workflow-detail.md` § Atlas grouping + layout/atom patch                                                     |
 
 ## 维护规则
 

package/project-template/.claude/agents/refs/designer-deliverable-spec.md

@@ -129,6 +129,30 @@ When `design-brief` dimension = True 3D, Designer also delivers (Phase 1, same G
 
 **Designer does not batch-export visual samples at `assetMapping` paths in v2.** Visual baseline = Phase 1 MC + ASR.
 
+### Phase 2 Skill Preflight (mandatory, before production)
+
+Before generating any audio or digit strip, read relevant Skills:
+
+```bash
+cat .claude/skills/playcraft-audio-generation/SKILL.md   # BGM/SFX generation patterns
+cat .claude/skills/playcraft-text-rendering/SKILL.md     # Digit strip green/blue screen strategy
+cat .claude/skills/playcraft-image-generation/SKILL.md   # §3 background decision tree (for digit)
+```
+
+**mediaGroups check** (mandatory): Read `atom-plan.json` → `skillsMatch.mediaGroups` for any `.aiaudio` matches. If matched → `playcraft skills link --atom <atomId>` → verify quality/mood → mark `status: done`. Skip only when mood/style mismatch (document in `dagRevisions`).
+
+Record in `logs/designer-log.md` § Skill Preflight:
+
+```markdown
+## Skill Preflight
+
+| Skill                      | 已读 | 关键决策摘要                                         |
+| -------------------------- | ---- | ---------------------------------------------------- |
+| playcraft-audio-generation | ✅   | BGM=ambient lo-fi; SFX 用 prompt 模板                |
+| playcraft-text-rendering   | ✅   | 数字用蓝幕；描边保护                                 |
+| mediaGroups (audio)        | ✅   | bg_music.aiaudio linked; click_sfx 需重做 (风格不符) |
+```
+
 | #   | Deliverable            | Format | Spec                                  |
 | --- | ---------------------- | ------ | ------------------------------------- |
 | 1   | **BGM**                | MP3    | Mood matches locked MC                |

package/project-template/.claude/agents/refs/designer-master-composite-recipes.md

@@ -2,35 +2,27 @@
 
 > 本文件供 Designer 在生成 Master Composite 时按需查阅。核心规则见 `playcraft-storyboard` skill。
 
-## 模型多样性策略
+## 模型策略（MC 专用 — 仅高质量模型）
 
-每个风格方案使用**不同的图片模型**，探索不同视觉可能性。先运行：
+Master Composite **禁止**使用低档或实验性模型。生成前可运行 `playcraft tools list-image-models` 核对 capability，但 **MC 只允许下表**：
 
-```bash
-playcraft tools list-image-models
-```
-
-### 推荐分配策略
+| 允许 `--image-model`           | 典型分配                                        |
+| ------------------------------ | ----------------------------------------------- |
+| **`mulerouter/gpt-image-2`**   | Option A（主推）；Option C 可复用 + 不同 prompt |
+| **`mulerouter/nano-banana-2`** | Option B；或 A/B 各用一模型做画风对比           |
 
-| 方案                   | 推荐模型类型                                        | 原因                               |
-| ---------------------- | --------------------------------------------------- | ---------------------------------- |
-| Option A（最精细方案） | `gpt-image-2`                                       | 最高质量，细节最丰富，适合主推方案 |
-| Option B（风格化方案） | `gemini-3.1-flash-image-preview` 或 `hy-image-v3.0` | 风格更鲜明、艺术感更强             |
-| Option C（探索方案）   | `flux-kontext-pro` 或 `nano-banana-2`               | 不同画风，提供对比参考             |
+**禁止用于 MC**：`gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*`、裸 `gpt-image-2`、以及上表以外的任何模型。
 
-> 若只有 1-2 个方案，仍建议用不同模型生成同一方案，对比后选最佳。
+> 多方案差异应来自 **prompt / 配色 / 构图**，不是换弱模型。ASR 双板 `--image-model` 须与已选 MC **完全一致**（见 `playcraft-asset-state-sheet` skill）。
 
-### 模型特性速查
+### 模型特性速查（仅白名单内）
 
-| 模型                             | 特点                                     | 适合风格               |
-| -------------------------------- | ---------------------------------------- | ---------------------- |
-| `gpt-image-2`                    | 细节丰富、光影真实、多 provider fallback | 写实、半写实、精细卡通 |
-| `gemini-3.1-flash-image-preview` | 色彩鲜艳、构图清晰、速度快               | 明亮卡通、休闲风       |
-| `hy-image-v3.0`                  | 亚洲审美偏向、角色设计好                 | IP 风格、Q 版角色      |
-| `flux-kontext-pro`               | 艺术感强、风格独特                       | 手绘风、艺术插画       |
-| `nano-banana-2`                  | 快速、适合探索                           | 简洁图形、平面设计风   |
+| 模型                       | 特点                          | 适合                                |
+| -------------------------- | ----------------------------- | ----------------------------------- |
+| `mulerouter/gpt-image-2`   | 细节、光影、复杂 UI、中文元素 | 写实、半写实、精细卡通、麻将/汉字类 |
+| `mulerouter/nano-banana-2` | 色彩、构图、速度快            | 明亮卡通、简洁 UI、快速迭代第二方案 |
 
-> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型，先用 `list-image-models` 确认。
+> `--reference-image` 只能用于 CAPABILITY 为 `text+image` 或 `image→image` 的模型；白名单内两模型均支持图生图。
 
 ---
 
@@ -56,7 +48,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot showing normal gameplay in
 
 [STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI (HUD bar, score display, buttons). Consistent art style across all panels. Thin vertical dividers between panels. Each panel has its numbered label at the top." \
   --output assets/images/storyboard/master_composite_option_A.png \
-  --image-model [MODEL] \
+  --image-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -80,7 +72,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot with character dodging obst
 
 [STYLE_KEYWORDS]. All 5 panels are portrait-oriented mobile screenshots arranged left-to-right. Every panel has complete game UI. Consistent art style across all panels. Thin vertical dividers. Numbered labels at top." \
   --output assets/images/storyboard/master_composite_option_A.png \
-  --image-model [MODEL] \
+  --image-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -104,7 +96,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot showing active gameplay wit
 
 Premium casual style, warm amber lighting, traditional Chinese aesthetic with modern UI, glossy tile surfaces. All 5 panels portrait-oriented, left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels." \
   --output assets/images/storyboard/master_composite_option_A.png \
-  --image-model [MODEL] \
+  --image-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -128,7 +120,7 @@ Panel 5 '5. CTA Always Visible': Mid-game screenshot with active combat, 'Play N
 
 [STYLE_KEYWORDS]. All 5 panels portrait-oriented left-to-right. Every panel has complete game UI. Consistent art style. Thin vertical dividers. Numbered labels at top." \
   --output assets/images/storyboard/master_composite_option_A.png \
-  --image-model [MODEL] \
+  --image-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -184,7 +176,7 @@ Master Composite 是 Phase 1 的**第一张生成图**，通常无前序图可
 playcraft tools generate-image \
   --prompt "<5-panel prompt>" \
   --output assets/images/storyboard/master_composite_option_A.png \
-  --image-model gpt-image-2 \
+  --image-model mulerouter/gpt-image-2 \
   --image-size 4K
 ```
 
@@ -197,7 +189,7 @@ playcraft tools generate-image \
   --prompt "<方案 B prompt>" \
   --output assets/images/storyboard/master_composite_option_B.png \
   --reference-image assets/images/storyboard/master_composite_option_A.png \
-  --image-model [不同模型] \
+  --image-model mulerouter/nano-banana-2 \
   --image-size 4K
 ```