@playcraft/cli 0.0.57 → 0.0.58

package/project-template-v2/skills/playable-debug/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: playable-debug
+description: >-
+  Step ⑤ auto-clear for playables. Agent checks game-config before record:mp4
+  in video-validate-loop. Use when record fails to reach ENDCARD or user mentions
+  一键通关. Usually invoked by other skills, not directly by user.
+---
+
+# Playable Debug Playback
+
+> **通常由 video-validate-loop / record-playback 在录屏前调用**，用户不单独跑。
+
+---
+
+## Agent 入口（录屏前 checklist）
+
+### 1. 开发态录屏配置
+
+`game/config/game-config.ts`（或 legacy `.js`）：
+
+| Key                 | 录屏优化时  |
+| ------------------- | ----------- |
+| `SHOW_DEBUG_BUTTON` | **`true`**  |
+| `SKIP_TRANSITIONS`  | **`false`** |
+
+### 2. 验证可达 ENDCARD
+
+**Pass 标准**：`window.__playable.autoPlay()` + `getState().currentPhase === 'ENDCARD'`（见 `npm run verify:contract`）。
+
+Legacy 链路：`DebugButton` → `_onDebugAutoPlay()` → `autoPlayToWin()` → ENDCARD（仍可用，2026-Q3 移除）。
+
+录屏脚本优先调用 `__playable.autoPlay()`；legacy 项目走 `evaluate _onDebugAutoPlay()`。
+
+### 3. 发布前（build:html 前）
+
+反向：`SHOW_DEBUG_BUTTON: false`，写进 validate 报告「发布配置已关 debug」。
+
+---
+
+## When to Apply
+
+- 「一键通关」按钮不见了
+- 需要快速跑完整局验证 end card / CTA / 动画
+- 发布前检查调试项是否关闭
+- 自动玩卡住、与教程/guide 冲突
+
+## Config Switches (`game-config.js`)
+
+| Key                 | 开发             | 发布        |
+| ------------------- | ---------------- | ----------- |
+| `SHOW_DEBUG_BUTTON` | `true`           | **`false`** |
+| `SKIP_TRANSITIONS`  | 可选 `true` 加速 | `false`     |
+| `IS_EASY_MODE`      | 按需             | 按产品      |
+
+`SHOW_DEBUG_BUTTON: false` 时 **不会创建** `DebugButton`（不是隐藏，是 `null`）。
+
+## 一键通关链路
+
+```
+publishPlayableRuntime()  →  window.__playable.autoPlay()  →  ENDCARD   ← pass 标准
+       ↓ (legacy warn)
+game-config.ts  SHOW_DEBUG_BUTTON
+       ↓
+main-scene.js   DebugButton → _onDebugAutoPlay()
+       ↓
+match-system.js autoPlayToWin()
+       ↓
+sceneManager    通关 → ENDCARD
+```
+
+**按钮位置**：`GAME_CONFIG.DEBUG`（由 `applySafeLayout` 写在 CTA 上方左侧）。
+
+**相关文件**
+
+- `game/gameplay/debug-tools.js` — `DebugButton` UI
+- `game/scenes/main-scene.js` — `_onDebugAutoPlay`, `_prepareDebugAutoPlay`
+- `game/gameplay/match-system.js` — `autoPlayToWin`
+
+## 恢复一键通关
+
+1. 确认 `SHOW_DEBUG_BUTTON: true`
+2. 确认 `index.html` 已加载 `debug-tools.js`（在 `main-scene.js` 之前）
+3. 刷新页面；按钮在左下、CTA 上方
+4. 若仍无：检查是否已进入 `ENDCARD`（`setEnabled(false)` 会隐藏）
+
+## 自动玩行为
+
+`autoPlayToWin`：
+
+1. 跳过教程 / `disableTutorialMode`
+2. 循环 `findMatchablePair` 正常消除
+3. 死局后静默扫尾
+4. `board.isAllMatched()` 后结束
+
+`setBusy(true)` 期间按钮文案为「自动玩…」，结束后恢复。
+
+## 发布前检查
+
+```bash
+rg "SHOW_DEBUG_BUTTON:\s*true" game/config/game-config.js && echo "WARN: disable debug"
+```
+
+必做：
+
+- [ ] `SHOW_DEBUG_BUTTON: false`
+- [ ] `SKIP_TRANSITIONS: false`（除非产品要求）
+- [ ] 浏览器目视无绿色调试按钮
+
+## Related Skills
+
+- [playable-record](../playable-record/SKILL.md) — `verify:contract`, `verify:firstwin`, `record:mp4`
+- [playable-validate](../playable-validate/SKILL.md) — 当前最小 video validation loop
+
+## References
+
+- 配置与接入：[references/debug-config.md](references/debug-config.md)

package/project-template-v2/skills/playable-debug/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: 'Playable Debug Playback'
+  short_description: 'Restore and manage playable debug auto-play.'
+  default_prompt: 'Restore or configure playable debug controls including one-click auto-clear and pre-ship flag checks.'

package/project-template-v2/skills/playable-debug/references/debug-config.md

@@ -0,0 +1,40 @@
+# Debug Config Reference
+
+## MainScene 接入
+
+```js
+this.debugButton = GAME_CONFIG.SHOW_DEBUG_BUTTON
+  ? new DebugButton(this, () => this._onDebugAutoPlay())
+  : null;
+```
+
+ENDCARD 时禁用：
+
+```js
+if (this.debugButton) this.debugButton.setEnabled(false);
+```
+
+点击穿透：board 点击前先判断 `debugButton.contains(x, y)`。
+
+## DEBUG 布局块
+
+```js
+DEBUG: { W: 120, H: 40, X: 0, Y: 0 }  // X/Y 由 applySafeLayout 写入
+```
+
+默认位置：安全区左侧，连击条上方。
+
+## \_prepareDebugAutoPlay 要点
+
+- `pairGuide.skip()` 若教程激活
+- `matchSystem.disableTutorialMode()`
+- 显示 HUD / 启动 countdown（若尚未开始）
+
+## 扩展调试能力
+
+新增调试按钮时：
+
+1. 增加 `SHOW_*` 开关，默认 `false`
+2. 在 `applySafeLayout` 派生坐标，勿硬编码 Y
+3. 发布检查脚本加入 `rg` 规则
+4. depth ≥ 500，避免被 board 遮挡

package/project-template-v2/skills/playable-record/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: playable-record
+description: >-
+  Minimal runtime contract check and headed 60fps MP4 recording for playables.
+  Use when iteration 1 optimize needs `verify:contract` or delivery evidence MP4.
+---
+
+# Playable Record Playback (MP4)
+
+> 当前 template-v2 迁移只接入最小运行时验证与录屏路径。
+
+---
+
+## Agent 入口
+
+### 0. 前置（record 前必做）
+
+```bash
+npm run verify:contract    # 快速断言 window.__playable 已接线
+npm run verify:lifecycle   # 确认 phasePath: HOOK→…→ENDCARD 完整（iter2 DoD 必须项）
+```
+
+**verify:lifecycle 检查**：phasePath 必须从 HOOK 出发，经过 TUTORIAL 和 GAMEPLAY，到达 ENDCARD，中间无跳跃。失败时输出缺失的 phase，路由回 generate 修复状态机骨架。
+
+**Harness 契约（pass 标准）** — 游戏须通过 `publishPlayableRuntime()` 暴露：
+
+```js
+window.__playable.autoPlay();
+window.__playable.getState(); // { currentPhase, isGameOver }
+window.__playable.getCanvas?.(); // 可选，录屏取 canvas
+window.__playable.hideDebugUi?.(); // 可选，录屏前隐藏 debug UI
+```
+
+Legacy：`MainScene._onDebugAutoPlay()` 仍可通过但会 warn。
+
+### 1. 录屏
+
+```bash
+npm run record:mp4 -- --headed --fps=60
+```
+
+### 2. 验收 spec
+
+```bash
+ffprobe -v error -select_streams v:0 \
+  -show_entries stream=width,height,r_frame_rate,duration \
+  -of default=noprint_wrappers=1 recordings/*.mp4
+```
+
+要求：1080×1920，`60/1`，完整局 ~25s。禁止 Playwright 25fps `recordVideo`。
+
+### 3. 产出
+
+`recordings/playable-YYYYMMDD-HHmmss.mp4`
+
+## When to Apply
+
+- 需要自动跑完一局并导出视频（HOOK → 一键通关 → ENDCARD）
+- 成片需要 BGM / 消牌音效 / 胜利 jingle
+- 不想改游戏源码或打进发布包
+
+## Quick Start
+
+```bash
+brew install ffmpeg          # 若未安装
+cd testN
+npm install
+npm run record:mp4:install   # 安装 Chromium
+npm run record:mp4 -- --headed --fps=60
+# 或直接：
+node ../skills/playable-record/scripts/record-playable.mjs --root=. --headed --fps=60
+```
+
+输出：`recordings/playable-YYYYMMDD-HHmmss.mp4`
+
+命令成功只代表 MP4 文件写出来了，不代表画面质量已经通过后期评审。
+
+## 流程
+
+```
+game/index.html 加载
+  → 等待 window.__playable（或 legacy MainScene HOOK）
+  → canvas.captureStream(60) + masterGain 单路 MediaRecorder
+  → hook-delay 录入场动画（无声）
+  → __playable.autoPlay()（或 legacy evaluate _onDebugAutoPlay()）
+  → 等待 ENDCARD + tail-delay
+  → 停止录制 → ffmpeg 转 MP4
+```
+
+## CLI 参数
+
+| 参数                  | 默认        | 说明                    |
+| --------------------- | ----------- | ----------------------- |
+| `--port=8080`         | 8080        | http-server 端口        |
+| `--out=recordings/`   | recordings/ | MP4 输出目录            |
+| `--fps=60`            | 60          | Canvas 采集帧率         |
+| `--hook-delay=1200`   | 1200        | HOOK 后等待 ms 再自动玩 |
+| `--tail-delay=2500`   | 2500        | ENDCARD 尾帧停留 ms     |
+| `--timeout=180000`    | 180000      | 整局超时 ms             |
+| `--keep-intermediate` | off         | 保留 capture.webm       |
+| `--headed`            | off         | 有界面浏览器（排查用）  |
+
+## 音频原理
+
+Playwright `screencast` / `recordVideo` **不含音频且固定 25fps**，不适合游戏录屏。
+
+改用浏览器内 **`canvas.captureStream(60)` + `MediaRecorder`**，单路同时采集画面与 Web Audio：
+
+```
+game.canvas.captureStream(60) ──┐
+                                ├→ MediaRecorder → capture.webm → ffmpeg → MP4
+masterGain → MediaStreamDest ───┘
+```
+
+[`scripts/lib/record-audio-bridge.js`](../../scripts/lib/record-audio-bridge.js) 在 HOOK 阶段注入 `startAvCapture(fps)`，音画同轨，无需手动对轨。
+
+默认 **60fps**；可通过 `--fps=30` 降低体积。
+
+## 故障排查
+
+| 现象          | 处理                                                                        |
+| ------------- | --------------------------------------------------------------------------- |
+| contract 失败 | 先 `npm run verify:contract` — 缺 `window.__playable` 时修 `game/contract/` |
+| MP4 无音轨    | 确认 runtime 已 boot；bridge 会 `audioContext.resume()`                     |
+| 全程静音      | 检查 `__playable.autoPlay()` 或 legacy `_onDebugAutoPlay`                   |
+| 音画漂移      | 确保 screencast 与 MediaRecorder 同时 start/stop                            |
+| WebGL 异常    | 加 `--headed`                                                               |
+| ffmpeg 找不到 | `brew install ffmpeg`                                                       |
+
+## 已知限制
+
+- 音效为 Web Audio 振荡器合成 tone，与游戏内一致，非 MP3 素材
+- 默认不含 Boot loading（screencast 从 HOOK 开始）
+- 仅 dev 页 `game/index.html`
+- 跳过教程（与一键通关相同）
+
+## Files
+
+- `scripts/record-playable.mjs` — 主脚本
+- `scripts/lib/record-audio-bridge.js` — 浏览器端音频桥

package/project-template-v2/skills/playable-record/scripts/lib/dev-server.mjs

@@ -0,0 +1,104 @@
+/**
+ * Shared dev-server helpers for verify / record / dev:start scripts.
+ *
+ * Single source of truth for how the harness boots a server and discovers the
+ * real listening URL. Previously these were copy-pasted into verify-contract,
+ * verify-firstwin and record-playable, which let the port-detection logic drift.
+ *
+ * Vite runs with strictPort:false, so when the preferred port (3000) is taken it
+ * auto-increments. `detectDevUrl` parses Vite's `Local:` stdout line to recover
+ * the actual port instead of guessing — this is what keeps devUrl correct under
+ * port drift (see docs/harness/experiment-lessons.md §9.2).
+ */
+
+import { spawn } from 'node:child_process';
+
+const LOCAL_URL_RE = /Local:\s+(http:\/\/(?:localhost|127\.0\.0\.1):\d+\/)/;
+
+/** Poll a URL with HEAD until it responds or the timeout elapses. */
+export async function waitForHttp(url, timeoutMs = 30000) {
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(url, { method: 'HEAD' });
+      if (res.ok) return;
+    } catch {
+      /* retry */
+    }
+    await new Promise((r) => setTimeout(r, 250));
+  }
+  throw new Error(`Server not ready: ${url}`);
+}
+
+/** Spawn `npm run dev` (Vite) bound to 127.0.0.1 with piped stdio for URL detection. */
+export function startDevServer(cwd) {
+  return spawn('npm', ['run', 'dev', '--', '--host', '127.0.0.1'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/** Spawn a static http-server for the non-dev probe path. */
+export function startHttpServer(port, cwd) {
+  return spawn('npx', ['http-server', '.', '-p', String(port), '-c-1', '--cors'], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+}
+
+/**
+ * Parse a chunk of dev-server output for Vite's `Local: http://…:PORT/` line.
+ * Exposed for unit testing the port-drift case.
+ * @param {string} text
+ * @returns {string | null}
+ */
+export function parseLocalUrl(text) {
+  const m = String(text).match(LOCAL_URL_RE);
+  return m ? m[1] : null;
+}
+
+/**
+ * Resolve the actual dev-server URL by watching stdout/stderr for Vite's
+ * `Local:` line. Falls back to `preferredUrl` if nothing is parsed in time.
+ * @param {import('node:child_process').ChildProcess} child
+ * @param {string} preferredUrl
+ * @param {number} [timeoutMs]
+ * @returns {Promise<string>}
+ */
+export function detectDevUrl(child, preferredUrl, timeoutMs = 30000) {
+  return new Promise((res) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      res(preferredUrl);
+    }, timeoutMs);
+    const onData = (data) => {
+      const url = parseLocalUrl(data);
+      if (url) {
+        clearTimeout(timer);
+        cleanup();
+        res(url);
+      }
+    };
+    const cleanup = () => {
+      child.stdout?.off('data', onData);
+      child.stderr?.off('data', onData);
+    };
+    child.stdout?.on('data', onData);
+    child.stderr?.on('data', onData);
+  });
+}
+
+/** Pick a free port starting at `preferred`; skips ports already serving `pathToProbe`. */
+export async function pickServerPort(preferred, pathToProbe = '/game/index.html') {
+  for (let i = 0; i < 20; i += 1) {
+    const port = preferred + i;
+    try {
+      await waitForHttp(`http://127.0.0.1:${port}${pathToProbe}`, 400);
+      // Something already serves here — try the next port.
+      continue;
+    } catch {
+      return port;
+    }
+  }
+  return preferred + 20;
+}

package/project-template-v2/skills/playable-record/scripts/lib/record-audio-bridge.js

@@ -0,0 +1,141 @@
+function pickAvMimeType() {
+  const candidates = [
+    'video/webm;codecs=vp8',
+    'video/webm;codecs=vp9',
+    'video/webm'
+  ];
+  return candidates.find((mime) => MediaRecorder.isTypeSupported(mime)) || 'video/webm';
+}
+
+function resolveCaptureSurface(fps) {
+  const playable = window.__playable;
+  const game = window.__game;
+
+  let canvas = null;
+  let targetFps = fps;
+
+  if (playable && typeof playable.getCanvas === 'function') {
+    canvas = playable.getCanvas();
+  }
+  if (!canvas && game?.canvas) {
+    canvas = game.canvas;
+  }
+  if (playable && typeof playable.getCaptureFps === 'function') {
+    targetFps = playable.getCaptureFps() || targetFps;
+  } else if (game?.loop) {
+    game.loop.targetFps = targetFps;
+    game.loop.forceSetTimeOut = false;
+  }
+
+  return { canvas, targetFps, hasGame: !!game, hasPlayable: !!playable };
+}
+
+function startAvCapture(fps) {
+  try {
+    const { canvas, targetFps, hasGame, hasPlayable } = resolveCaptureSurface(fps);
+
+    window.__avCaptureDebug = {
+      hasGame,
+      hasPlayable,
+      hasCanvas: !!canvas,
+      canvasType: canvas?.constructor?.name,
+      captureStreamType: typeof canvas?.captureStream,
+      mimeType: null,
+      recorderState: null,
+      error: null,
+      chunks: 0
+    };
+
+    if (!canvas) {
+      throw new Error('Capture canvas not ready — implement window.__playable.getCanvas() or expose Phaser game.canvas');
+    }
+
+    const videoStream = canvas.captureStream(targetFps);
+    const audioCtx = new (window.AudioContext || window.webkitAudioContext)({ sampleRate: 48000 });
+    const dest = audioCtx.createMediaStreamDestination();
+    const silence = audioCtx.createOscillator();
+    silence.frequency.value = 0;
+    const gain = audioCtx.createGain();
+    gain.gain.value = 0.0001;
+    silence.connect(gain);
+    gain.connect(dest);
+    silence.start();
+    const combined = new MediaStream([
+      ...videoStream.getVideoTracks(),
+      ...dest.stream.getAudioTracks()
+    ]);
+    const mimeType = pickAvMimeType();
+    window.__avCaptureDebug.mimeType = mimeType;
+
+    const recorder = new MediaRecorder(combined, {
+      mimeType,
+      videoBitsPerSecond: 8_000_000
+    });
+
+    window.__recordAv = {
+      chunks: [],
+      recorder,
+      videoStream: combined,
+      audioCtx,
+      silence,
+      mimeType,
+      fps
+    };
+
+    recorder.ondataavailable = (e) => {
+      if (e.data.size) window.__recordAv.chunks.push(e.data);
+    };
+    recorder.start(100);
+    window.__avCaptureDebug.recorderState = recorder.state;
+  } catch (err) {
+    if (window.__avCaptureDebug) window.__avCaptureDebug.error = err.message;
+    else window.__avCaptureDebug = { error: err.message };
+    throw err;
+  }
+}
+
+function stopAvCapture() {
+  const state = window.__recordAv;
+  if (!state?.recorder) {
+    throw new Error('AV capture was not started');
+  }
+
+  const { recorder, chunks, videoStream } = state;
+
+  if (window.__avCaptureDebug) {
+    window.__avCaptureDebug.chunks = chunks.length;
+    window.__avCaptureDebug.totalBytes = chunks.reduce((a, c) => a + c.size, 0);
+  }
+
+  return new Promise((resolve, reject) => {
+    recorder.onstop = async () => {
+      try {
+        const blob = new Blob(chunks, { type: state.mimeType || 'video/webm' });
+        videoStream.getTracks().forEach((track) => track.stop());
+        if (state.audioCtx) { try { state.audioCtx.close(); } catch {} }
+        if (state.silence) { try { state.silence.stop(); } catch {} }
+        window.__recordAv = null;
+        const buf = await blob.arrayBuffer();
+        resolve(Array.from(new Uint8Array(buf)));
+      } catch (err) {
+        reject(err);
+      }
+    };
+    recorder.onerror = () => reject(new Error('MediaRecorder failed'));
+    if (recorder.state === 'inactive') {
+      reject(new Error('MediaRecorder already stopped'));
+      return;
+    }
+    recorder.stop();
+  });
+}
+
+/** @deprecated use startAvCapture */
+function startAudioCapture() {
+  startAvCapture(25);
+}
+
+/** @deprecated use stopAvCapture */
+function stopAudioCapture() {
+  return stopAvCapture();
+}