@playcraft/cli 0.1.38-beta → 0.1.39-prod

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

@@ -1,116 +0,0 @@
----
-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

@@ -1,4 +0,0 @@
-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

@@ -1,40 +0,0 @@
-# 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

@@ -1,140 +0,0 @@
----
-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

@@ -1,104 +0,0 @@
-/**
- * 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

@@ -1,141 +0,0 @@
-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();
-}