@playcraft/cli 0.1.24 → 0.1.26

package/dist/workspace-runtime/workspaces/skills.js

@@ -0,0 +1,189 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { cp, lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { basename, dirname, join } from 'node:path';
+import { load } from 'js-yaml';
+import { canonicalProjectSkillsJson, createCanonicalBundleArchive, effectiveProjectSkills, extractBundleArchive, inspectProjectSkills, readProjectSkillSource, readProjectSkillsLockFile, sourceTreeDigest, validateProjectSkillsSnapshot, } from '@playcraft/common/project-skills';
+import { initializeLocalProjectSkills } from '../../project-skills/local-store.js';
+import { resolveCliPackageRoot } from '../../scaffold/compose.js';
+import { selectPlatformSkillSnapshot } from '../../project-skills/builtin-import.js';
+import { EMPTY_WORKSPACE_REPOSITORY_SKILLS, EMPTY_WORKSPACE_PLATFORM_SKILLS } from './empty-template.js';
+import { excludeFromGit } from './dependencies.js';
+/** Runtime availability is determined by the locked metadata, independent of unsynced source edits. */
+export async function readWorkspaceSkillSnapshot(root) {
+    const management = await lstat(join(root, '.playcraft'));
+    const declaration = join(root, '.playcraft/skills.json');
+    const stat = await lstat(declaration);
+    if (!management.isDirectory() || management.isSymbolicLink() || !stat.isFile() || stat.isSymbolicLink() || stat.size > 1024 * 1024)
+        throw new Error('workspace_skills_invalid');
+    return validateProjectSkillsSnapshot(await readFile(declaration, 'utf8'), await readProjectSkillsLockFile(root));
+}
+/** Existing managed projects keep their exact selection. Legacy source folders are adopted once. */
+export async function ensureWorkspaceSkills(root, cache, access) {
+    await excludeFromGit(root, '/.playcraft/skills/');
+    await excludeFromGit(root, '/.playcraft/skill-artifacts/');
+    const raw = await readProjectSkillsLockFile(root);
+    if (raw !== null) {
+        await readWorkspaceSkillSnapshot(root);
+        return;
+    }
+    const inventory = await inspectProjectSkills(root);
+    if (inventory.issues.length)
+        throw new Error('workspace_skills_invalid');
+    const names = new Set(inventory.discovered.map(entry => basename(entry.root)));
+    const platformNames = EMPTY_WORKSPACE_PLATFORM_SKILLS.filter(name => !names.has(name));
+    const selected = platformNames.length ? await selectPlatformSkillSnapshot(platformNames, access) : undefined;
+    const added = new Set();
+    await initializeLocalProjectSkills(root, cache, { enabledRoots: added, platform: selected,
+        prepareSources: async () => {
+            for (const name of EMPTY_WORKSPACE_REPOSITORY_SKILLS) {
+                if (names.has(name))
+                    continue;
+                await safeDirectory(root, '.agents/skills');
+                const source = `.agents/skills/${name}`;
+                await mkdir(join(root, source), { mode: 0o755 });
+                added.add(source);
+                const template = join(resolveCliPackageRoot(), 'project-template/.claude/skills', name);
+                for (const child of await readdir(template))
+                    await cp(join(template, child), join(root, source, child), {
+                        recursive: true, force: false, errorOnExist: true,
+                    });
+            }
+        },
+        rollbackSources: async () => {
+            for (const source of added)
+                await rm(join(root, source), { recursive: true, force: true });
+        },
+    });
+}
+async function safeDirectory(root, path) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        current = join(current, segment);
+        await mkdir(current, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(current);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('workspace_skills_invalid');
+    }
+    return current;
+}
+/** Cache misses may reconstruct only the exact locked repository bytes, never a newer source. */
+async function lockedFiles(root, cache, entry, view, loadArtifact) {
+    const persistent = await safeDirectory(root, '.playcraft/skill-artifacts');
+    const saved = join(persistent, `${entry.revision.artifactHash}.tar.gz`);
+    const path = join(cache, `${entry.revision.artifactHash}.tar.gz`);
+    let archive;
+    try {
+        const stat = await lstat(saved);
+        if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
+            throw new Error('workspace_skills_invalid_bundle');
+        archive = await readFile(saved);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        try {
+            archive = await readFile(path);
+        }
+        catch (cacheError) {
+            if (cacheError.code !== 'ENOENT')
+                throw cacheError;
+            const declaration = view.declaration.entries.find(item => item.entryKey === entry.entryKey);
+            if (entry.revision.kind === 'source' && declaration.source.kind === 'repository') {
+                const source = await readProjectSkillSource(root, declaration);
+                if (source.sourceTreeHash !== entry.sourceTreeHash)
+                    throw new Error('workspace_skills_source_changed');
+                archive = createCanonicalBundleArchive(source.files.map(file => ({ path: file.path, data: Buffer.from(file.content) })));
+            }
+            else {
+                if (!loadArtifact)
+                    throw new Error('workspace_skills_artifact_unavailable');
+                archive = await loadArtifact(entry);
+            }
+        }
+    }
+    if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    const extracted = extractBundleArchive(archive);
+    if (extracted.issues.length)
+        throw new Error('workspace_skills_invalid_bundle');
+    if (entry.revision.kind === 'source' && sourceTreeDigest(extracted.files.map(file => ({ path: file.path, content: file.data }))) !== entry.sourceTreeHash)
+        throw new Error('workspace_skills_digest_mismatch');
+    const temporary = `${saved}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, archive, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, saved);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+    return extracted.files;
+}
+function metadata(entryKey, content) {
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/.exec(content);
+    const parsed = frontmatter ? load(frontmatter[1]) : {};
+    const data = parsed && typeof parsed === 'object' ? parsed : {};
+    return { entryKey, name: typeof data.name === 'string' ? data.name : entryKey,
+        description: typeof data.description === 'string' ? data.description : '', content };
+}
+export async function readWorkspaceSkills(root, cache, loadArtifact) {
+    const snapshot = await readWorkspaceSkillSnapshot(root);
+    const skills = await Promise.all(snapshot.lock.entries.map(async (entry) => {
+        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
+        const body = files.find(file => file.path === 'SKILL.md');
+        if (!body)
+            throw new Error('workspace_skills_body_missing');
+        return metadata(entry.entryKey, body.data.toString('utf8'));
+    }));
+    return { ...snapshot, lockHash: createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex'), skills };
+}
+/** Read-only task generation lives outside source discovery and is omitted from Git/snapshots. */
+export async function freezeWorkspaceSkills(root, cache, loadArtifact) {
+    const snapshot = await readWorkspaceSkillSnapshot(root);
+    const entries = effectiveProjectSkills(snapshot.declaration, snapshot.lock, 'sandbox-agent');
+    const base = await safeDirectory(root, '.playcraft/skills');
+    const lockHash = createHash('sha256').update(canonicalProjectSkillsJson(snapshot.lock)).digest('hex');
+    const generation = await safeDirectory(base, lockHash);
+    const skills = [];
+    const expectedFiles = new Set();
+    for (const entry of entries) {
+        const files = await lockedFiles(root, cache, entry, snapshot, loadArtifact);
+        for (const file of files) {
+            const target = join(generation, entry.entryKey, file.path);
+            const relative = join(entry.entryKey, file.path);
+            expectedFiles.add(relative);
+            await safeDirectory(generation, dirname(relative));
+            await writeFile(target, file.data, { flag: 'wx', mode: 0o444 }).catch(async (error) => {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const stat = await lstat(target);
+                if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1 || !file.data.equals(await readFile(target)))
+                    throw new Error('workspace_skills_digest_mismatch');
+            });
+        }
+        const body = files.find(file => file.path === 'SKILL.md');
+        if (!body)
+            throw new Error('workspace_skills_body_missing');
+        const info = metadata(entry.entryKey, body.data.toString('utf8'));
+        skills.push({ name: info.name, description: info.description, skillRef: entry.revision.skillRef,
+            revision: entry.revision.kind === 'source' ? entry.revision.sourceRevision : entry.revision.version,
+            path: join(generation, entry.entryKey, 'SKILL.md') });
+    }
+    const verifyTree = async (directory, relative = '') => {
+        for (const item of await readdir(directory, { withFileTypes: true })) {
+            const path = join(relative, item.name);
+            if (item.isSymbolicLink())
+                throw new Error('workspace_skills_invalid_bundle');
+            if (item.isDirectory()) {
+                if (![...expectedFiles].some(file => file.startsWith(`${path}/`)))
+                    throw new Error('workspace_skills_invalid_bundle');
+                await verifyTree(join(directory, item.name), path);
+            }
+            else if (!item.isFile() || !expectedFiles.has(path))
+                throw new Error('workspace_skills_invalid_bundle');
+        }
+    };
+    await verifyTree(generation);
+    return { declarationHash: snapshot.lock.declarationHash,
+        lockHash, skills };
+}

package/dist/workspace-runtime/workspaces/video-attachments.js

@@ -0,0 +1,49 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { WORKSPACE_VIDEO_ATTACHMENT_MAX_DURATION_MS, WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES } from '@playcraft/common/cloud-workspace/runtime';
+/** Probe the opened descriptor so replacing a pathname cannot redirect the media reader. */
+export async function probeAttachmentVideo(handle) {
+    const output = await new Promise((resolve, reject) => {
+        const child = spawn(process.env.PLAYCRAFT_FFPROBE_PATH ?? 'ffprobe', [
+            '-v', 'error', '-protocol_whitelist', 'file,pipe', '-show_entries',
+            'format=format_name,duration:stream=codec_type,width,height', '-of', 'json',
+            process.platform === 'linux' ? '/proc/self/fd/3' : '/dev/fd/3',
+        ], { stdio: ['ignore', 'pipe', 'ignore', handle.fd] });
+        let text = '';
+        const timer = setTimeout(() => { child.kill('SIGKILL'); reject(new Error('invalid_attachment')); }, 15_000);
+        timer.unref();
+        child.stdout.on('data', (chunk) => {
+            text += chunk.toString('utf8');
+            if (text.length > 64 * 1024) {
+                child.kill('SIGKILL');
+                reject(new Error('invalid_attachment'));
+            }
+        });
+        child.once('error', () => { clearTimeout(timer); reject(new Error('video_probe_unavailable')); });
+        child.once('close', code => { clearTimeout(timer); code === 0 ? resolve(text) : reject(new Error('invalid_attachment')); });
+    });
+    const result = JSON.parse(output);
+    const stream = result.streams?.find(item => item.codec_type === 'video');
+    const durationMs = Math.round(Number(result.format?.duration) * 1000);
+    const formats = result.format?.format_name?.split(',') ?? [];
+    const mimeType = formats.includes('webm') ? 'video/webm' : formats.includes('mp4') ? 'video/mp4' : formats.includes('mov') ? 'video/quicktime' : undefined;
+    if (!stream || !mimeType || !Number.isFinite(durationMs) || durationMs <= 0 || durationMs > WORKSPACE_VIDEO_ATTACHMENT_MAX_DURATION_MS
+        || !Number.isSafeInteger(stream.width) || !Number.isSafeInteger(stream.height) || stream.width <= 0 || stream.height <= 0
+        || stream.width > 16384 || stream.height > 16384)
+        throw new Error('invalid_attachment');
+    return { mimeType, durationMs, width: stream.width, height: stream.height };
+}
+export async function hashAttachment(handle) {
+    const digest = createHash('sha256');
+    const chunk = Buffer.allocUnsafe(64 * 1024);
+    let position = 0;
+    for (;;) {
+        const { bytesRead } = await handle.read(chunk, 0, chunk.length, position);
+        if (!bytesRead)
+            return digest.digest('hex');
+        digest.update(chunk.subarray(0, bytesRead));
+        position += bytesRead;
+        if (position > WORKSPACE_VIDEO_ATTACHMENT_MAX_BYTES)
+            throw new Error('invalid_attachment');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "private": false,
   "type": "module",
   "engines": {
@@ -14,6 +14,7 @@
     "dist",
     "templates",
     "project-template",
+    "project-template-v2",
     "engine-packs",
     "project-templates",
     "REMIX.md",
@@ -21,9 +22,9 @@
   ],
   "scripts": {
     "dev": "tsc -w",
-    "build": "tsc",
+    "build": "node scripts/generate-video-skills.mjs && tsc",
     "start": "node dist/index.js",
-    "test": "vitest run",
+    "test": "pnpm build && vitest run",
     "test:agent": "node scripts/run-agent-tests.mjs --list",
     "test:agent:designer": "node scripts/run-agent-tests.mjs game-designer",
     "test:agent:developer": "node scripts/run-agent-tests.mjs developer",
@@ -35,6 +36,10 @@
     "test:agent:gate": "node scripts/run-agent-tests.mjs gate",
     "test:agent:vlm": "node scripts/run-agent-tests.mjs vlm",
     "test:agent:stop": "node scripts/run-agent-tests.mjs stop",
+    "generate:platform-skills": "node scripts/generate-platform-skills.mjs",
+    "verify:platform-skills": "node scripts/generate-platform-skills.mjs --check",
+    "generate:video-skills": "node scripts/generate-video-skills.mjs",
+    "verify:video-skills": "node scripts/generate-video-skills.mjs --check && node --test scripts/generate-video-skills.test.mjs",
     "verify:agent-stop": "node scripts/verify-agent-stop.mjs",
     "verify-sprite-overlay": "node scripts/verify-sprite-overlay.mjs",
     "link": "node scripts/bump-local.js && pnpm build && npm link",
@@ -45,8 +50,9 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.23",
-    "@playcraft/common": "^0.1.23",
+    "@playcraft/build": "^0.1.26",
+    "@playcraft/common": "^0.1.26",
+    "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",
@@ -62,8 +68,10 @@
     "json5": "^2.2.3",
     "latest-version": "^7.0.0",
     "music-metadata": "^11.12.3",
+    "node-pty": "1.0.0",
     "ora": "^8.2.0",
     "picocolors": "^1.1.1",
+    "playwright-core": "1.52.0",
     "sharp": "^0.34.5",
     "update-notifier": "^7.3.1",
     "ws": "^8.19.0",
@@ -79,6 +87,7 @@
     "@types/sharp": "^0.32.0",
     "@types/update-notifier": "^6.0.8",
     "@types/ws": "^8.18.1",
+    "esbuild": "^0.28.1",
     "typescript": "^5.9.3",
     "vitest": "^3.2.4"
   }

package/project-template/.claude/skills/playcraft-image-generation/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: playcraft-image-generation
-description: PlayCraft AI (Artificial Intelligence, 人工智能) 图片生成与素材替换指南。默认使用可用的 Image 2.5，显式传入参考图，验证透明背景、目标尺寸和最终文件；覆盖文生图、图生图与批量素材生产。
+description: PlayCraft AI 图片生成核心决策指南。涵盖模型选择决策树、核心命令模板、背景处理决策树（绿幕策略）、脚本决策规则。精灵图直出/Edit 模型/错误恢复/批量实践等进阶内容见 refs/ta-image-generation-detail.md。
 triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
 ---
 
@@ -8,13 +8,7 @@ triggers: 生成图片,generate image,选模型,model selection,reference image,
 
 ## 0. 开始前必读
 
-先读取目标字段的 schema 配置（resolution、ratio、prompt、remove_background、reference_image）及当前素材。尺寸、格式和输出路径以项目实际配置为准，不假定所有素材都是透明 PNG (Portable Network Graphics, 便携式网络图形)。
-
-项目没有素材 schema 时，从实际资源引用、当前图片的尺寸和用户需求确定这些参数；不要套用其他游戏的字段、路径或尺寸。
-
-替换素材时优先使用字段配置的 reference_image，没有配置时使用当前素材。查看图片或在对话中选中素材不等于把它传给生图模型：必须设置 referenceImagePath 或 --reference-image，并确认文件可读。仅调整风格时保留原有文字、构图和用途；用户要求重新命名或重做构图时再改变。
-
-生图前运行模型发现命令，核实当前账号可用的模型与透明输出能力：
+生图前**必须先运行模型发现命令**：
 
 ```bash
 playcraft tools list-image-models
@@ -24,8 +18,7 @@ playcraft tools list-image-models
 
 ```
 MODEL                                        CAPABILITY   ALPHA  PROVIDERS
-gpt-image-2.5-sunburst                        text+image   yes    iegg-litellm
-gpt-image-2.5-flare                           text+image   yes    iegg-litellm
+gpt-image-2                                  text+image   no     3 (iegg-litellm, mulerouter, 302)
 gemini-3.1-flash-image-preview               text+image   no     2 (google, iegg-litellm)
 hy-image-v3.0                                text+image   no     1 (tencent-cloud)
 flux-kontext-pro                             text+image   no     1 (302)
@@ -36,7 +29,7 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 **列说明**：
 
 - `CAPABILITY`：`text→image` 仅文生图 / `image→image` 仅图生图 / `text+image` 两者均支持
-- `ALPHA`：`yes` = 支持原生透明输出；`no` = 透明素材才需要另行去背（见第 3 节）
+- `ALPHA`：`yes` = 原生透明 PNG；`no` = 需使用绿幕策略（见第 3 节）
 - `PROVIDERS`：支持该模型的 provider 数量，多个 provider 时后端按优先级自动 fallback（顺序尝试，首个成功即返回）
 
 **Prompt 套路速查**：[reference/prompt-cookbook.md](reference/prompt-cookbook.md)
@@ -47,11 +40,8 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ```
 需要生图？
-├─ 用户指定了模型，或制作流程已锁定模型？
-│  └─ 使用指定模型；失败时报告原因，不静默更换
-│
-├─ 普通图片生成 / 现有素材替换 / 含文字 Logo？
-│  └─ 优先 iegg-litellm/gpt-image-2.5-sunburst；不可用时选择清单中的 Image 2.5 并报告实际模型
+├─ 追求最高质量（概念图、精品单图）？
+│  └─ gpt-image-2（3 个 provider 自动 fallback：iegg-litellm → mulerouter → 302）
 │
 ├─ 需要 --reference-image（风格一致性批量生产）？
 │  └─ 必须选 CAPABILITY = text+image 或 image→image 的模型
@@ -63,30 +53,29 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 │  └─ Edit 模型工作流（见进阶参考）
 │
 └─ 不确定？
-   └─ 使用平台默认模型；透明素材优先清单中 ALPHA=yes 的模型
+   └─ 先试 gpt-image-2，失败换 gemini-3.1-flash-image-preview
 ```
 
 ### 主要模型特性
 
-| 模型                               | 特点与优势                                                         | 最佳场景                                 | 速度           | 注意事项                                                          |
-| ---------------------------------- | ------------------------------------------------------------------ | ---------------------------------------- | -------------- | ----------------------------------------------------------------- |
-| **gpt-image-2.5-sunburst / flare** | 当前普通生图与素材替换的优先模型，支持参考图及原生透明输出         | Logo、角色、图标、透明素材替换           | 以实际调用为准 | 使用模型清单中的 provider/model；检查返回的实际模型和透明验证结果 |
-| **gpt-image-2**                    | 兼容已有项目和明确指定 provider 的制作流程                         | 已锁定模型的概念图、故事板、精灵图       | 以实际调用为准 | 普通素材默认优先 Image 2.5；能力和可用 provider 以模型清单为准    |
-| **gemini-3.1-flash-image-preview** | 速度快、色彩鲜艳、构图清晰、最稳定不易报错、reference-image 理解好 | 快速迭代、扁平卡通、明亮休闲风、超时回退 | 快(<30s)       | 精细细节和文字不如 gpt-image-2                                    |
-| **hy-image-v3.0**                  | 亚洲审美偏向、角色设计好、Q版/IP风格擅长                           | 中国风、Q版角色、IP 形象                 | 中等           | 西方写实风格表现一般                                              |
-| **flux-kontext-pro**               | 艺术感强、风格独特、手绘质感好                                     | 艺术插画、手绘风、独特画风探索           | 中等           | 网格理解弱，不适合精灵图                                          |
-| **nano-banana-2**                  | 最快、适合简单图形探索                                             | 简洁图标、平面设计、快速草稿             | 极快           | 中文字符不可靠、细节少                                            |
-| **qwen-image-edit-max**            | 图生图编辑能力强、局部修改精确                                     | 换花色/换数字/换颜色等结构相似变体       | 中等           | CAPABILITY=image→image，必须传 reference-image                    |
-| **wan2.6-image**                   | 风格迁移能力好                                                     | 将参考图风格应用到新内容                 | 中等           | CAPABILITY=image→image，必须传 reference-image                    |
+| 模型                               | 特点与优势                                                                                  | 最佳场景                                        | 速度                            | 注意事项                                                        |
+| ---------------------------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------- | --------------------------------------------------------------- |
+| **gpt-image-2**                    | 细节最丰富、光影最真实、网格/布局理解力最强、中文字符准确率最高、3 provider fallback 容错高 | 概念图、精灵图直出、含文字素材、写实/半写实风格 | 慢(7-8min/张)，**不设 timeout** | 慢是正常的；只有 `API 500` / `fetch failed` 才切换下一 provider |
+| **gemini-3.1-flash-image-preview** | 速度快、色彩鲜艳、构图清晰、最稳定不易报错、reference-image 理解好                          | 快速迭代、扁平卡通、明亮休闲风、超时回退        | 快(<30s)                        | 精细细节和文字不如 gpt-image-2                                  |
+| **hy-image-v3.0**                  | 亚洲审美偏向、角色设计好、Q版/IP风格擅长                                                    | 中国风、Q版角色、IP 形象                        | 中等                            | 西方写实风格表现一般                                            |
+| **flux-kontext-pro**               | 艺术感强、风格独特、手绘质感好                                                              | 艺术插画、手绘风、独特画风探索                  | 中等                            | 网格理解弱，不适合精灵图                                        |
+| **nano-banana-2**                  | 最快、适合简单图形探索                                                                      | 简洁图标、平面设计、快速草稿                    | 极快                            | 中文字符不可靠、细节少                                          |
+| **qwen-image-edit-max**            | 图生图编辑能力强、局部修改精确                                                              | 换花色/换数字/换颜色等结构相似变体              | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
+| **wan2.6-image**                   | 风格迁移能力好                                                                              | 将参考图风格应用到新内容                        | 中等                            | CAPABILITY=image→image，必须传 reference-image                  |
 
 ### 选型口诀
 
-- 普通素材 / 含文字 / 透明元素 → 可用的 `gpt-image-2.5-sunburst`，其次 Image 2.5 系列
-- 已锁定的故事板或制作流程 → 沿用该流程指定模型，见下方 MC 专用规则
+- 追求质量 / 含文字 / 网格图 → `gpt-image-2`
+- 快速迭代 / 扁平风格 / 回退备选 → `gemini-3.1-flash-image-preview`
 - 中国风 / Q版 / 亚洲审美 → `hy-image-v3.0`
 - 艺术/手绘探索 → `flux-kontext-pro`
 - 纯 edit 变体 → `qwen-image-edit-max`
-- 模型失败 → 先检查返回错误；不要把原生透明失败自动改成 Gemini 白底生成
+- 一切都失败 → `gemini-3.1-flash-image-preview`（最稳定）
 
 ### 为什么精灵图直出是首选批量策略？
 
@@ -102,26 +91,6 @@ qwen-image-edit-max                          image→image  no     1 (mulerouter
 
 ## 2. 核心命令
 
-### 沙箱对话中的直接工具
-
-当前对话注册了 `playcraft-generate-image` 时，直接调用它。根据本次目标素材填写参数，不固定游戏名、素材类别、参考路径、尺寸或比例：
-
-| 参数                            | 本次取值                                                                                                 |
-| ------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `prompt`                        | 目标字段的生成说明与用户需求；按素材用途明确背景、文字、构图或状态要求                                   |
-| `imageModelRef`                 | 当前清单中可用的模型，普通生图优先 `iegg-litellm/gpt-image-2.5-sunburst`；遵守用户或已锁定流程的模型选择 |
-| `referenceImagePath`            | 已确认可读的项目相对参考路径；优先字段 `reference_image`，其次当前素材，新素材无参考时可省略             |
-| `additionalReferenceImagePaths` | 确有多个参考时传入其他可读路径，顺序与用途明确                                                           |
-| `aspectRatio`                   | 字段比例或目标尺寸推导的比例；直接工具仅支持部分比例，生成后再按目标 resolution 精确处理                 |
-| `removeBackground`              | 按字段配置与素材用途决定；透明前景为 `true`，完整背景或不透明面板为 `false`                              |
-| `outputPath`                    | 本次素材的中间文件路径，沿用项目工作目录约定，验证后写回实际主题引用                                     |
-
-背景、角色、道具、按钮、文字、发光状态、序列帧等各自遵守项目字段配置。成组状态或动画帧还需保持对象、风格、锚点与尺寸一致，不把单张静态图当成完整序列帧替换。
-
-`removeBackground: true` 表示需要通过验证的透明素材，不表示必须执行一次本地去背。保存工具结果中的实际 provider/model、参考图数量与透明验证结论；模型清单里的默认星号不能证明本次实际用了哪个模型。
-
-未注册直接工具时使用下方 CLI (Command-Line Interface, 命令行工具) 入口。若返回 `Business tool protocol unavailable (501); no operation was sent`，本次没有发出生图请求：修复入口或使用已注册的直接工具，不要通过换模型反复重试。
-
 ### 文生图（text-to-image）
 
 ```bash
@@ -130,7 +99,7 @@ playcraft tools generate-image \
   --output assets/images/sword.png \
   --aspect-ratio 1:1 \
   --image-size 4K \
-  --image-model iegg-litellm/gpt-image-2.5-sunburst
+  --image-model gpt-image-2
 ```
 
 ### 图生图（image-to-image / reference-image）
@@ -142,7 +111,7 @@ playcraft tools generate-image \
   --reference-image assets/images/sword.png \
   --aspect-ratio 1:1 \
   --image-size 4K \
-  --image-model iegg-litellm/gpt-image-2.5-sunburst
+  --image-model gpt-image-2
 ```
 
 ### 参数说明
@@ -246,14 +215,7 @@ playcraft image sprite-sheet \
 
 ### 为什么需要色幕策略？
 
-只有选用不支持原生透明的模型且需要透明素材时才使用色幕。原生透明图验证通过后直接处理尺寸，不再重复去背；发光、半透明边缘和白色前景应保留。白色背景与白色物体会让 floodfill 混淆边界。`playcraft image remove-background` 默认使用本地 floodfill，不应描述为必然调用后端去背模型。
-
-### 最终文件验证
-
-- 按字段 resolution 处理尺寸，透明前景用 `--fit contain`，确认执行的工具使用透明补边；旧版工具可能补入不透明黑色。验证不通过时更新工具或显式使用透明背景缩放。
-- 按实际资源扩展名编码，不把 PNG 内容写进其他格式的文件，也不擅自改变主题引用。
-- 去背、缩放、转格式后都检查透明通道与边缘，并分别在深色和浅色背景上预览。允许素材自身的黑色描边，拒绝额外黑色矩形补边或误删的发光效果。
-- 达到项目的文件大小限制后再覆盖目标文件。同一 Logo 的多个尺寸从同一张母图导出，避免重复生成导致风格漂移。
+**当前所有已接入模型均不支持原生透明 PNG（ALPHA = no）**。白色背景 + 白色物体 = floodfill 无法区分边界。纯色背景 + 非撞色游戏素材 = 抠图几乎完美。与影视 chroma-key 原理相同。
 
 ### 色幕选型矩阵（Color Conflict Avoidance）
 
@@ -318,7 +280,7 @@ playcraft image overlay \
 ## 4. 脚本决策
 
 - **<=5 个文件** → 直接使用 CLI 命令
-- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
+- **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录。
 
 ---
 

package/project-template/.claude/skills/playcraft-replica-validation/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: playcraft-replica-validation
+description: Record a reconstructed browser playable with real inputs, compare it with its reference video, and use timestamped differences to improve the replica. Use after implementation or fixes; use video understanding first when the reference has not been analyzed.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Replica validation
+
+Use the PlayCraft CLI (Command-Line Interface，命令行接口) to record the running implementation and compare real video evidence. Codex chooses the scenario, reads the evidence, edits the playable, and repeats the checks. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and evidence contracts](references/contracts.md) before the first recording or comparison. Check `playcraft playable record --help`, `playcraft video compare --help`, and `playcraft video models --json`. If a required command is unavailable, report that the workspace CLI needs upgrading. Provider credentials and model requests belong to Model Proxy; do not call Gemini directly or copy a key into the project.
+
+Use a completed reference `analysis.json` from `playcraft-video-understanding`. Inspect its original keyframes and distinguish observed actions from inferred controls. Run from the project root. Write an explicit, versioned scenario for the current implementation, using real browser coordinates and inputs. Include the initial view, first action and result, principal feedback, and ending when demonstrated. Keep hidden rules and unshown branches unknown. Start or restart the current project using its own development command; do not depend on internal auto-play hooks. Confirm that the supplied development address belongs to this process and serves this round's version. If that cannot be confirmed, do not claim validation of the current version. The project digest proves the recorded checkout stayed unchanged, but does not attest which source version an already-running server serves.
+
+Record into a fresh directory under `.playcraft/video-replication/`. Keep the original recording, its input logs, scenario, control recordings, and project snapshot together. Do not edit the video or its manifest to repair a failing check. Match the reference viewport when practical and record enough time for every expected result. A completed recording proves capture succeeded; it does not prove the interaction worked.
+
+Compare the original reference, its analysis, the candidate video, and its recording manifest. Inspect `comparison.md`, `comparison.json`, paired keyframes, contact sheets, input logs, and controls using available image and file-reading tools. Review event alignment before judging motion or feedback timing. The model can suggest differences; the CLI derives the final status from validated evidence and the comparison policy. A single similarity score is insufficient. Keep the default full comparison policy for delivery; an explicitly limited diagnostic must be reported as partial coverage. Do not loosen thresholds just to obtain a passing result.
+
+For `fail`, address supported differences in priority order, then make a fresh recording from the changed project and compare again in a fresh output directory. For `inconclusive`, resolve missing controls, insufficient duration, unpaired required events, low confidence, or unknown input intent before declaring completion. Preserve valid differences even when other dimensions lack evidence. Report the tested path, unsupported branches, and unevaluated audio explicitly.
+
+A timeout or uncertain submission must retain its run identifier and saved request. Resume the same comparison with `playcraft video compare --resume <runId> --out <same-directory>`; recovery reads the existing task and never creates another paid request. Explicit cancellation is separate from ending the local wait. Do not resubmit because the command exited early. Treat malformed model output, stale recordings, changed hashes, or missing frames as errors, never as a passing comparison.
+
+Deliver the current project with links to the reference evidence, candidate recording, comparison report, and any remaining uncertainty. Keep validation evidence in workspace checkpoints and out of Git and deliverable builds.

package/project-template/.claude/skills/playcraft-replica-validation/references/contracts.md

@@ -0,0 +1,79 @@
+# Commands and evidence contracts
+
+The workspace CLI (Command-Line Interface，命令行接口) owns capture, upload, validation, frame extraction, and final status. The Skill supplies guidance only. Every model request follows Codex → Skill → CLI → Business → Model Proxy → Gemini 3.8 Flash.
+
+```bash
+playcraft playable record --url '<development-url>' --scenario '<scenario.json>' \
+  --out .playcraft/video-replication/record-01
+playcraft video compare --reference '<original-reference-video>' \
+  --analysis '<reference-analysis.json>' \
+  --candidate '.playcraft/video-replication/record-01/candidate.mp4' \
+  --recording '.playcraft/video-replication/record-01/metadata.json' \
+  --out .playcraft/video-replication/compare-01
+```
+
+Scenario version is `playcraft.replica-scenario.v1`; positions are normalized to the declared `contentRect`. Replace event identifiers with actual IDs from `analysis.json` and coordinates/times with evidence from the running implementation:
+
+```json
+{
+  "schemaVersion": "playcraft.replica-scenario.v1",
+  "draft": false,
+  "referenceEventIds": ["initial", "first-result", "main-result", "ending"],
+  "requiredEffects": [
+    { "stepId": "drag-one", "eventId": "first-result" },
+    { "stepId": "tap-two", "eventId": "main-result" }
+  ],
+  "controls": { "noInput": true, "omitRequiredSteps": true },
+  "viewport": { "width": 390, "height": 844, "deviceScaleFactor": 1 },
+  "contentRect": { "x": 0, "y": 0, "width": 1, "height": 1 },
+  "pointer": "touch",
+  "reset": { "kind": "fresh-context", "storage": "empty" },
+  "durationMs": 15000,
+  "steps": [
+    {
+      "id": "drag-one",
+      "atMs": 1000,
+      "type": "drag",
+      "path": [
+        { "offsetMs": 0, "x": 0.3, "y": 0.6 },
+        { "offsetMs": 600, "x": 0.7, "y": 0.6 }
+      ]
+    },
+    { "id": "tap-two", "atMs": 4000, "type": "tap", "x": 0.5, "y": 0.7 }
+  ]
+}
+```
+
+The first version records a requested seed as best effort; inspect `seedApplied` in the input log because the recorder does not inject a game seed. Fresh browser storage does not guarantee reset of server-side state.
+
+Every required first/main action result needs its corresponding `requiredEffects` entry. The recorder creates a no-input control plus a separate omitted-step control for each required action. Maximum three distinct required steps yield at most four controls. Disabling controls leaves interaction acceptance inconclusive.
+
+Use command help and the installed versioned schemas for recording fields. Do not guess manifest fields or synthesize a successful recording. Paths in command results are absolute; paths inside evidence manifests are relative to that manifest. Model output cannot provide artifact paths.
+
+`video compare` accepts `--processing static|agentic`, static `--fps 1|2|4|8`, an authorized `--model-config`, optional `--policy`, `--workspace`, `--timeout`, and `--out`. Static sampling is the default. Agentic execution cannot be combined with fixed sampling. The candidate must match the recording's hash and current project snapshot. The reference hash must match the completed analysis. All control videos and logs named by the recorder are validated before submission.
+
+The recording manifest version is `playcraft.replica-recording.v1`; the comparison result is `playcraft.replica-validation.v1`, and its evidence manifest is `playcraft.replica-evidence.v1`.
+
+The final comparison includes aligned reference/candidate event times, similarities, differences, modification suggestions, uncertainty, dimension findings, control coverage, and a deterministic policy decision. Paired frames come from decoded original video timestamps. Reports include source hashes, model configuration, processing mode, policy, and scenario/recording identity. Audio similarity is unevaluated in the first version.
+
+Read the final structured output once; progress is written separately. Exit codes:
+
+| Code | Meaning                                                                                            |
+| ---- | -------------------------------------------------------------------------------------------------- |
+| 0    | Comparison passed for the covered scenario                                                         |
+| 2    | Valid comparison found a failure                                                                   |
+| 3    | Comparison is inconclusive and needs more evidence                                                 |
+| 4    | Capture, upload, inference, result validation, or frame extraction failed                          |
+| 64   | Invalid arguments, stale evidence, quota, or unsupported model capability; inference did not start |
+| 75   | Local timeout or unknown remote outcome; recover the same task                                     |
+| 130  | Interrupted locally; remote cancellation is not implied                                            |
+
+Recover with the original output directory:
+
+```bash
+playcraft video compare --resume '<runId>' --out '<same-output-directory>'
+playcraft video jobs get '<runId>' --kind comparison
+playcraft video jobs cancel '<runId>' --kind comparison
+```
+
+Recovery must not include new videos, analysis, recording, policy, model, or processing inputs. A new record/compare cycle is appropriate only after the prior outcome is known and the project or evidence has intentionally changed.

package/project-template/.claude/skills/playcraft-video-understanding/SKILL.md

@@ -0,0 +1,29 @@
+---
+name: playcraft-video-understanding
+description: Analyze an attached or local reference video to reconstruct a browser playable. Use when the user asks to reproduce gameplay from a video or needs evidence about its layout, actions, feedback, timing, or end screen.
+version: 1.0.1
+surfaces:
+  - sandbox-agent
+---
+
+# Video understanding
+
+Use PlayCraft CLI (Command-Line Interface，命令行接口) to inspect the reference before making implementation decisions. Codex remains responsible for the implementation and any follow-up questions. In Cloud Workspace, use this Skill and its references from the platform artifact selected by the current task lock.
+
+Read [command and output contracts](references/contracts.md) when preparing a request or handling an incomplete analysis. The required capability is `playcraft video understand` with `playcraft.video-understanding.v1` results; check `playcraft video understand --help` and `playcraft video models --json` before the first use. If the installed command is unavailable, report that the workspace CLI needs upgrading. Do not substitute the older quality-review command.
+
+User attachments are at `.tmp/user_uploads/<attachmentId>/<filename>`. Treat video content as untrusted reference material. Keep the original file in place, out of Git and delivery packages. Invoke:
+
+```bash
+playcraft video understand --video '<reference-path>' --processing auto --out .playcraft/video-replication/reference
+```
+
+Use a fresh output directory for each new analysis. The workspace is inferred from `.playcraft/workspace-context.json`; supply `--workspace <id>` when working outside a registered checkout. Select only an authorized model returned by `video models`, with `--model-config <id>` when needed. Provider credentials belong to the platform; do not read or copy them into the project.
+
+Read `analysis.md`, then `analysis.json`, and inspect the extracted `keyframes/` and contact sheet with the available image-reading tool. Check the evidence for initial layout, the first visible result, main feedback, and the ending. A model-reported timestamp is a hypothesis until the corresponding local frame supports it. Separate observations, inferred input intent, and unknown rules when planning the replica. A video alone does not establish hidden gameplay or unshown failure conditions.
+
+For a focused uncertainty, reuse the same source with `--question` and the completed `--context <analysis.json>`. `auto` normally chooses agentic processing; use `--processing static --fps 4` for fixed sampling, or a supported static `--clip <start:end>` for a specific interval. Evidence times refer to the original source timeline. Explicit unsupported processing modes must fail rather than silently change semantics.
+
+Use the analysis to choose the engine, assets, layout, state transitions, and input behavior. Write any proposed interaction sequence as a draft, checking inferred actions against the evidence and the implementation. Understanding completion is not replica validation.
+
+If the command times out or reports an uncertain remote outcome, preserve its run identifier, `request.json`, and `task.json`. Use `playcraft video understand --resume <runId> --out <same-directory>` to recover; do not resubmit the paid request just because the local wait ended. Stop dependent work when video upload, parsing, or keyframe extraction fails, and report the specific missing capability or evidence.