@playcraft/cli 0.0.44 → 0.0.47

package/project-templates/phaser/skills/_shared/agent-prep.md

@@ -0,0 +1,136 @@
+# Agent 自举协议（用户不跑命令）
+
+> **用户怎么说**：「用 `playable-xxx` 技能优化当前 playable / 当前页面」  
+> **Agent 怎么做**：先读本文件完成 **Phase 0 自举**，再读目标 skill 的 **Agent 入口**，全程 **Agent 自己执行 shell**，不要把命令列表丢给用户。
+
+---
+
+## Phase 0 — create 后默认已完成
+
+`playcraft create` 会自动执行 `ensure-project --no-install`，新项目创建后已经具备 `docs/project-state.md`、`logs/`、`workflow:doctor` 等工作流骨架。
+
+Agent 每次开始时优先执行：
+
+```bash
+npm run workflow:doctor
+```
+
+只有当 doctor 提示缺 workflow 文件、项目是旧模板、或用户是在现有目录手动接入 playable pipeline 时，才在 **playable 工程根**（含 `index.html` 或 `game/index.html` 与 `skills/` 的目录）执行：
+
+```bash
+npm run ensure:project -- --no-install
+```
+
+或：
+
+```bash
+node skills/_shared/scripts/ensure-project.mjs --root=. --no-install
+```
+
+（monorepo 里 `testN/` 若 skills 在同级 `../skills/`，ensure-project 会自动写对路径。）
+
+脚本会自动（缺什么补什么）：
+
+| 检查                       | 动作                                   |
+| -------------------------- | -------------------------------------- |
+| `playable.ui.profile.yaml` | 从 skill 模板复制                      |
+| `playground/registry.json` | bootstrap focus-lab + catalog          |
+| `focus-lab/` harness       | bootstrap（不覆盖已有）                |
+| `package.json` scripts     | 合并指向 `skills/` 的标准 npm 脚本     |
+| `node_modules`             | 无则 `npm install`                     |
+| Playwright Chromium        | 无则 `npx playwright install chromium` |
+| `recordings/`              | 创建目录                               |
+
+输出 JSON：`projectRoot`、`skillsRoot`、`relSkills`、`ready`、`warnings`。
+
+**`ready: false` 时**：Agent 修 blocker（缺 game、缺 skills）后再跑 ensure；**不要**让用户手工 bootstrap。
+
+---
+
+## Phase 0.5 — 定位「当前页面 / 优化目标」
+
+用户说「当前页面」时，Agent 推断 **Focus Zone**（不要问用户要命令）：
+
+| 用户意图关键词               | Zone          | 优先 skill                               | L 步 playground id              |
+| ---------------------------- | ------------- | ---------------------------------------- | ------------------------------- |
+| 整片 / 录屏 / 交付           | FLOW          | `playable-validate`                      | `flow:full`                     |
+| ENDCARD / 结算 / CTA         | PHASE:endcard | loop + animation                         | `integration:PHASE:endcard-win` |
+| 消牌 / 碎裂 / match          | EVENT:match   | `playable-fx-decompose` + peak           | `integration:EVENT:match-once`  |
+| 帧动画 / burst / ring / ray  | FX:frame      | `playable-fx-peak`                       | `clean:frame:<spec>`            |
+| 粒子 / 破碎素材              | FX:particle   | `playable-fx-decompose`                  | `clean:particle:<spec>`         |
+| 美术 / atlas / 正式 GPT 美术 | ART           | `playable-art`                           | —                               |
+| 占位图 / 占位音频 / 补齐合约 | PLACEHOLDER   | `playable-placeholder`                   | —                               |
+| UI 布局 / HUD                | UI            | `playable-verify-ui`                     | verify:ui                       |
+| 卡顿 / 点不动                | PERF          | `playable-validate` + `playable-animate` | 录屏 + verify:ui                |
+
+不确定时：**先 `flow:full` 录屏 → validate → 再收窄到 L 步**。
+
+---
+
+## Phase 1 — 调用目标 skill
+
+读取 `skills/<skill-name>/SKILL.md` 的 **Agent 入口** 节，按九步子集执行。
+
+通用 Gate（详见 [validation-rules.md](../playable-validate/validation-rules.md)）：
+
+```
+改代码/素材 → workflow:doctor（状态异常时再 ensure-project）
+           → verify:ui（改 manifest/PNG 后）
+           → 一键通关可达（⑤）
+           → 录屏 / playground record（⑥⑧）
+           → 写 validate 报告（⑨）
+```
+
+---
+
+## Phase 2 — 交付给用户什么
+
+用户只需要看到：
+
+1. **结论**：通过 / 有条件通过 / 未通过
+2. **证据**：最新 MP4 或 focus 录屏路径
+3. **相对上一版**：改善 / 仍存 / 回归（1–3 条）
+4. **报告**：`validate/PLAYABLE-*.md` 或 focus 报告路径
+
+不要贴长串 shell 命令 unless 用户明确要求看命令。
+
+---
+
+## 标准 npm 脚本（ensure-project 会合并）
+
+自包含 starter（`skills/` 在项目内）示例：
+
+```json
+{
+  "verify:ui": "python3 skills/playable-verify-ui/scripts/run_all.py",
+  "ensure:project": "node skills/_shared/scripts/ensure-project.mjs --root=.",
+  "record:mp4": "node skills/playable-record/scripts/record-playable.mjs --root=.",
+  "playground": "node skills/playable-focus/scripts/playground.mjs --root=."
+}
+```
+
+Agent 优先 `npm run <script>`；无 script 时用 `node skills/...` 或 ensure 输出的 `relSkills` 路径。
+
+---
+
+## 目录约定
+
+**自包含 starter（推荐分发）**
+
+```
+my-playable/
+├── Agent.md
+├── skills/              ← 工具链（template 已内置）
+├── game/index.html
+└── package.json
+```
+
+**monorepo（本仓库 testN/）**
+
+```
+workspace/
+├── skills/              ← 共享工具链
+└── testN/               ← 工程根，scripts 指向 ../skills/
+```
+
+在 Cursor 中应打开 **工程根**（含 `Agent.md` 与 `game/` 的那一层）。

package/project-templates/phaser/skills/_shared/requirements.txt

@@ -0,0 +1 @@
+Pillow>=10.0

package/project-templates/phaser/skills/_shared/scripts/build-evidence-gate.mjs

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+/**
+ * Knife 12C — ring:gate build/VLM evidence aggregation (read artifacts only).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { isSliceResolved, normalizeSliceState } from './state-store.mjs';
+import { readBuildArtifact, validateBuildArtifactForSlice } from '../../playable-record/scripts/lib/build-artifact.mjs';
+
+/**
+ * When sliceState is non-empty, ring gate aggregates per-slice build artifacts
+ * instead of re-running verify:* scripts (unless PLAYCRAFT_GATE_RERUN=1).
+ */
+export function evaluateBuildEvidenceForRingGate(projectDir, iteration, sliceState) {
+  const ss = normalizeSliceState(sliceState || {});
+  if (!ss.slices.length) {
+    return {
+      applicable: false,
+      ok: true,
+      blockingIssues: [],
+      routeTo: 'none',
+      nextAction: 'No slice queue — build evidence gate N/A',
+      summary: null,
+    };
+  }
+
+  const blockingIssues = [];
+  const devSlices = ss.slices.filter((s) => s.role === 'developer');
+
+  for (const slice of devSlices) {
+    if (!isSliceResolved(slice)) {
+      blockingIssues.push(`developer slice "${slice.sliceId}" is ${slice.status} — queue not terminal`);
+      continue;
+    }
+    if (slice.status === 'verified') {
+      blockingIssues.push(...validateBuildArtifactForSlice(projectDir, slice));
+    }
+  }
+
+  const vlmSlices = devSlices.filter((s) => s.evidenceTier === 'video-vlm');
+  if (vlmSlices.length > 0) {
+    const verifiedVlm = vlmSlices.filter((s) => s.status === 'verified');
+    if (verifiedVlm.length === 0) {
+      blockingIssues.push(
+        `Ring ${iteration} requires at least one verified video-vlm spine/periphery slice with build + MP4 + VLM evidence`,
+      );
+    }
+  }
+
+  const ring = Math.min(Math.max(Number(iteration) || 1, 1), 4);
+  const vlmPath = path.join(projectDir, `validate/ring${ring}/vlm-video.json`);
+  if (fs.existsSync(vlmPath)) {
+    try {
+      const vlm = JSON.parse(fs.readFileSync(vlmPath, 'utf8'));
+      const failed = (vlm.findings || []).filter((f) => f.status === 'fail' || f.severity === 'P0');
+      if (vlm.ok === false || failed.length > 0) {
+        blockingIssues.push(
+          `validate/ring${ring}/vlm-video.json has ${failed.length} failing finding(s)`,
+        );
+      }
+    } catch {
+      blockingIssues.push(`validate/ring${ring}/vlm-video.json is invalid JSON`);
+    }
+  }
+
+  const firstPending = devSlices.find((s) => s.status === 'pending' || s.status === 'in_progress');
+  return {
+    applicable: true,
+    ok: blockingIssues.length === 0,
+    blockingIssues,
+    routeTo: firstPending?.role || 'developer',
+    nextAction: blockingIssues.length
+      ? `Fix build/VLM evidence: ${blockingIssues[0]}`
+      : 'Build evidence aggregation passed',
+    summary: {
+      devSlices: devSlices.length,
+      verified: devSlices.filter((s) => s.status === 'verified').length,
+      videoVlm: vlmSlices.length,
+    },
+  };
+}
+
+export function shouldAggregateGateEvidence(sliceState) {
+  if (process.env.PLAYCRAFT_GATE_RERUN === '1') return false;
+  const ss = normalizeSliceState(sliceState || {});
+  return ss.slices.length > 0;
+}

package/project-templates/phaser/skills/_shared/scripts/context-budget.mjs

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+/**
+ * Context budget meter — makes each agent role's "always-loaded" context cost
+ * visible, and audits the on-demand refs/skills pool so the layered design
+ * (L1 card = ownership only; refs read on demand) keeps paying off.
+ *
+ * Token cost is estimated from bytes (~4 chars/token). A file may override the
+ * estimate with `tokenCost:` frontmatter (`~5k` or `5000`); `readWhen:` is
+ * surfaced for display. Nothing needs annotating — measurement is automatic.
+ *
+ * Advisory by default (exit 0). With --strict, exits 2 if any budget is blown.
+ *
+ * Usage:
+ *   node skills/_shared/scripts/context-budget.mjs --root=.
+ *   node skills/_shared/scripts/context-budget.mjs --root=. --json
+ *   node skills/_shared/scripts/context-budget.mjs --root=. --strict --base-budget=30000
+ */
+
+import { readFileSync, existsSync, readdirSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROLES = [
+  'game-designer',
+  'artist',
+  'technical-artist',
+  'developer',
+  'reviewer',
+];
+
+// Every sub-agent's First Step routes through these contract docs; count them
+// as part of each role's always-loaded base context.
+const SHARED_BASE_DOCS = ['docs/team/agent-conduct.md', 'docs/team/collaboration.md'];
+
+const DEFAULTS = { baseBudget: 30000, fileBudget: 8000 };
+
+function parseArgs(argv) {
+  const opts = { root: process.cwd(), json: false, strict: false, ...DEFAULTS };
+  for (const arg of argv) {
+    if (arg.startsWith('--root=')) {
+      const v = arg.slice('--root='.length);
+      opts.root = v.startsWith('/') ? v : resolve(process.cwd(), v);
+    } else if (arg === '--json') opts.json = true;
+    else if (arg === '--strict') opts.strict = true;
+    else if (arg.startsWith('--base-budget=')) opts.baseBudget = Number(arg.split('=')[1]) || DEFAULTS.baseBudget;
+    else if (arg.startsWith('--file-budget=')) opts.fileBudget = Number(arg.split('=')[1]) || DEFAULTS.fileBudget;
+  }
+  return opts;
+}
+
+/** Rough token estimate: ~4 characters per token. */
+export function estimateTokens(text) {
+  return Math.ceil(text.length / 4);
+}
+
+function frontmatter(text) {
+  const m = text.match(/^---\n([\s\S]*?)\n---/);
+  return m ? m[1] : '';
+}
+
+/** Parse an explicit `tokenCost:` override (`~5k` / `5000`) from frontmatter, if any. */
+function declaredTokenCost(fmText) {
+  const m = fmText.match(/tokenCost:\s*~?\s*([0-9.]+)\s*([kK])?/);
+  if (!m) return null;
+  const n = parseFloat(m[1]);
+  return Math.round(/k/i.test(m[2] || '') ? n * 1000 : n);
+}
+
+function declaredReadWhen(fmText) {
+  const m = fmText.match(/readWhen:\s*(.+)/);
+  return m ? m[1].trim().replace(/^['"]|['"]$/g, '') : null;
+}
+
+/** @returns {{ path: string, tokens: number, estimated: boolean, readWhen: string|null } | null} */
+function measure(root, rel) {
+  const abs = join(root, rel);
+  if (!existsSync(abs)) return null;
+  const text = readFileSync(abs, 'utf8');
+  const fm = frontmatter(text);
+  const declared = declaredTokenCost(fm);
+  return {
+    path: rel,
+    tokens: declared ?? estimateTokens(text),
+    estimated: declared == null,
+    readWhen: declaredReadWhen(fm),
+  };
+}
+
+function listMarkdown(root, relDir) {
+  const abs = join(root, relDir);
+  if (!existsSync(abs)) return [];
+  return readdirSync(abs)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => `${relDir}/${f}`)
+    .sort();
+}
+
+function listSkills(root) {
+  const abs = join(root, '.claude/skills');
+  if (!existsSync(abs)) return [];
+  const out = [];
+  for (const entry of readdirSync(abs, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const rel = `.claude/skills/${entry.name}/SKILL.md`;
+    if (existsSync(join(root, rel))) out.push(rel);
+  }
+  return out.sort();
+}
+
+/**
+ * @param {string} projectRoot
+ * @param {{ baseBudget?: number, fileBudget?: number }} [opts]
+ */
+export function analyzeBudget(projectRoot, opts = {}) {
+  const root = resolve(projectRoot);
+  const baseBudget = opts.baseBudget ?? DEFAULTS.baseBudget;
+  const fileBudget = opts.fileBudget ?? DEFAULTS.fileBudget;
+
+  const sharedDocs = SHARED_BASE_DOCS.map((d) => measure(root, d)).filter(Boolean);
+  const sharedTokens = sharedDocs.reduce((s, d) => s + d.tokens, 0);
+
+  const roles = [];
+  for (const role of ROLES) {
+    const card = measure(root, `.claude/agents/${role}.md`);
+    if (!card) continue;
+    const base = card.tokens + sharedTokens;
+    roles.push({
+      role,
+      cardTokens: card.tokens,
+      sharedTokens,
+      baseTokens: base,
+      overBudget: base > baseBudget,
+    });
+  }
+
+  const refs = listMarkdown(root, '.claude/agents/refs')
+    .map((rel) => measure(root, rel))
+    .filter(Boolean)
+    .filter((f) => basename(f.path) !== 'README.md');
+  const skills = listSkills(root)
+    .map((rel) => measure(root, rel))
+    .filter(Boolean);
+
+  const onDemand = [...refs, ...skills].sort((a, b) => b.tokens - a.tokens);
+  const onDemandTotal = onDemand.reduce((s, f) => s + f.tokens, 0);
+  const heavy = onDemand.filter((f) => f.tokens > fileBudget);
+  const unscopedHeavy = heavy.filter((f) => !f.readWhen);
+
+  const warnings = [];
+  for (const r of roles) {
+    if (r.overBudget) {
+      warnings.push(
+        `role "${r.role}" base context ≈ ${r.baseTokens} tokens (> ${baseBudget} budget)`,
+      );
+    }
+  }
+  for (const f of unscopedHeavy) {
+    warnings.push(`heavy on-demand file: ${f.path} ≈ ${f.tokens} tokens (> ${fileBudget}) — consider splitting`);
+  }
+
+  return {
+    ok: warnings.length === 0,
+    root,
+    baseBudget,
+    fileBudget,
+    sharedTokens,
+    roles,
+    onDemand,
+    onDemandTotal,
+    heavy,
+    warnings,
+  };
+}
+
+function printHuman(result) {
+  console.log(`[context:budget] base-budget=${result.baseBudget} file-budget=${result.fileBudget} tokens`);
+  console.log(`shared base docs ≈ ${result.sharedTokens} tokens (loaded by every role)`);
+  console.log('\nPer-role always-loaded base context:');
+  for (const r of result.roles) {
+    const mark = r.overBudget ? '!' : ' ';
+    console.log(`  [${mark}] ${r.role.padEnd(18)} ≈ ${r.baseTokens} tokens (card ${r.cardTokens} + shared ${r.sharedTokens})`);
+  }
+  console.log(`\nOn-demand pool: ${result.onDemand.length} files ≈ ${result.onDemandTotal} tokens total`);
+  const top = result.onDemand.slice(0, 5);
+  for (const f of top) {
+    console.log(`  - ${f.path} ≈ ${f.tokens} tokens${f.estimated ? '' : ' (declared)'}`);
+  }
+  if (result.warnings.length) {
+    console.log('\nWarnings:');
+    for (const w of result.warnings) console.log(`  - ${w}`);
+  } else {
+    console.log('\nAll roles within budget.');
+  }
+}
+
+function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  const result = analyzeBudget(opts.root, opts);
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    printHuman(result);
+  }
+  process.exit(opts.strict && !result.ok ? 2 : 0);
+}
+
+const isMain = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isMain) {
+  try {
+    main();
+  } catch (err) {
+    console.error(`[context:budget] ${err.message}`);
+    process.exit(1);
+  }
+}

package/project-templates/phaser/skills/_shared/scripts/create-playable.mjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * Copy template/ to a new playable project and run ensure-project.
+ *
+ * Usage (from workspace root):
+ *   node skills/_shared/scripts/create-playable.mjs --name=my-game
+ *   node skills/_shared/scripts/create-playable.mjs --name=my-game --no-ensure
+ */
+
+import { access, cp, mkdir, readFile, writeFile } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SKILLS_ROOT = resolve(__dirname, '../..');
+const REPO_ROOT = resolve(SKILLS_ROOT, '..');
+const TEMPLATE_ROOT = REPO_ROOT;
+const DEST_PARENT = dirname(REPO_ROOT);
+const COPY_EXCLUDES = new Set([
+  '.DS_Store',
+  '.git',
+  'node_modules',
+  'dist',
+  'package-lock.json',
+  'playable.ui.profile.yaml',
+  'playground',
+  'recordings',
+  'validate',
+]);
+
+function shouldCopy(src) {
+  const name = basename(src);
+  if (COPY_EXCLUDES.has(name)) return false;
+  if (src.includes(`${join('ta-workspace', 'logs')}`)) return name === '.gitkeep';
+  if (src.includes(`${join('ta-workspace', 'tmp')}`)) return name === '.gitkeep';
+  if (src.includes(`${join('focus-lab')}`)) return name === 'focus-lab' || name === '.gitkeep';
+  return true;
+}
+
+function parseArgs(argv) {
+  const opts = { name: null, ensure: true, json: false };
+  for (const arg of argv) {
+    if (arg.startsWith('--name=')) opts.name = arg.slice(7).trim();
+    else if (arg === '--no-ensure') opts.ensure = false;
+    else if (arg === '--json') opts.json = true;
+  }
+  return opts;
+}
+
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function patchPackageJson(destRoot, name) {
+  const pkgPath = join(destRoot, 'package.json');
+  const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  pkg.name = name;
+  pkg.description = `${name} — playable project`;
+  await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8');
+}
+
+async function patchProfile(destRoot, name) {
+  const profilePath = join(destRoot, 'playable.ui.profile.yaml');
+  if (!(await exists(profilePath))) return;
+  let text = await readFile(profilePath, 'utf8');
+  text = text.replace(/name: playable-template/, `name: ${name}`);
+  await writeFile(profilePath, text, 'utf8');
+}
+
+async function main() {
+  const opts = parseArgs(process.argv.slice(2));
+  if (!opts.name) {
+    console.error('Usage: create-playable.mjs --name=<project-dir-name>');
+    process.exit(1);
+  }
+
+  if (!(await exists(TEMPLATE_ROOT))) {
+    console.error(`Template not found: ${TEMPLATE_ROOT}`);
+    process.exit(1);
+  }
+
+  const destRoot = resolve(DEST_PARENT, opts.name);
+  if (await exists(destRoot)) {
+    console.error(`Target already exists: ${destRoot}`);
+    process.exit(1);
+  }
+
+  await cp(TEMPLATE_ROOT, destRoot, {
+    recursive: true,
+    filter: (src) => shouldCopy(src),
+  });
+  await patchPackageJson(destRoot, opts.name);
+  await patchProfile(destRoot, opts.name);
+
+  let ensureResult = null;
+  if (opts.ensure) {
+    const ensureScript = join(SKILLS_ROOT, '_shared/scripts/ensure-project.mjs');
+    const r = spawnSync('node', [ensureScript, `--root=${destRoot}`], {
+      cwd: destRoot,
+      encoding: 'utf8',
+    });
+    ensureResult = { status: r.status, stdout: r.stdout, stderr: r.stderr };
+  }
+
+  const result = {
+    ok: true,
+    projectRoot: destRoot,
+    templateRoot: TEMPLATE_ROOT,
+    skillsRoot: SKILLS_ROOT,
+    ensure: ensureResult,
+    next: [
+      `cd ${opts.name}`,
+      'npm run dev',
+      '对 Agent：用 playable-validate 优化当前 playable',
+    ],
+  };
+
+  if (opts.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    console.log(`[create-playable] created ${destRoot}`);
+    if (ensureResult?.status === 0) {
+      console.log('[create-playable] ensure-project OK');
+    } else if (opts.ensure) {
+      console.warn('[create-playable] ensure-project had issues — run npm run ensure:project');
+    }
+    for (const step of result.next) console.log(`  → ${step}`);
+  }
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});