@playcraft/cli 0.1.54 → 0.1.55-beta

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

@@ -0,0 +1,74 @@
+import { constants } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, open, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join, relative } from 'node:path';
+import { attachmentIdsSchema, WORKSPACE_USER_UPLOADS_DIRECTORY } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveWorkspaceAttachments } from './attachments.js';
+import { excludeFromGit } from './dependencies.js';
+async function safeParents(root, path, create = false) {
+    let current = root;
+    for (const segment of path.split('/')) {
+        if (!segment || segment === '.' || segment === '..')
+            throw new Error('workspace_worktree_attachment_unavailable');
+        current = join(current, segment);
+        if (create)
+            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_worktree_attachment_unavailable');
+    }
+}
+async function readSafe(root, path, max) {
+    await safeParents(root, dirname(path));
+    const handle = await open(join(root, path), constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.nlink !== 1 || stat.size > max)
+            throw new Error('workspace_worktree_attachment_unavailable');
+        return await handle.readFile();
+    }
+    finally {
+        await handle.close();
+    }
+}
+async function copyExact(source, target, path, limit) {
+    const body = await readSafe(source, path, limit);
+    await safeParents(target, dirname(path), true);
+    const existing = await lstat(join(target, path)).catch(() => undefined);
+    if (existing) {
+        const previous = await readSafe(target, path, limit);
+        if (!createHash('sha256').update(previous).digest().equals(createHash('sha256').update(body).digest()))
+            throw new Error('workspace_worktree_attachment_conflict');
+        return;
+    }
+    const temporary = `${join(target, path)}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, body, { flag: 'wx', mode: 0o644 });
+        await rename(temporary, join(target, path));
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Copy only the selected, fully validated attachment files; retries never replace different content. */
+export async function copyWorktreeAttachments(source, target, input) {
+    const ids = [...new Set(attachmentIdsSchema.parse(input ?? []))];
+    if (!ids.length)
+        return;
+    const attachments = await resolveWorkspaceAttachments(source, ids);
+    await excludeFromGit(target, `/${WORKSPACE_USER_UPLOADS_DIRECTORY}/`);
+    for (const attachment of attachments) {
+        const prefix = `${WORKSPACE_USER_UPLOADS_DIRECTORY}/${attachment.id}/`;
+        const files = attachment.files
+            ? attachment.files.map(file => ({ path: `${prefix}${attachment.kind === 'directory' ? `${attachment.name}/` : ''}${file.path}`, size: file.size }))
+            : [{ path: relative(source, attachment.path), size: attachment.size }];
+        for (const file of files) {
+            if (!file.path.startsWith(prefix) || file.path.split('/').some(segment => segment === '..' || !segment))
+                throw new Error('workspace_worktree_attachment_unavailable');
+            await copyExact(source, target, file.path, file.size);
+        }
+        await copyExact(source, target, `${WORKSPACE_USER_UPLOADS_DIRECTORY}/.metadata/${attachment.id}.json`, 1024 * 1024);
+    }
+    await resolveWorkspaceAttachments(target, ids);
+}

package/dist/workspace-runtime/workspaces/worktree-checkout.js

@@ -0,0 +1,67 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, realpath, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { validateProjectSkillsSnapshot } from '@playcraft/common/project-skills';
+import { readWorkspaceSkills } from './skills.js';
+const execute = promisify(execFile);
+async function archiveDirectory(root) {
+    let directory = root;
+    for (const segment of ['.playcraft', 'skill-artifacts']) {
+        directory = join(directory, segment);
+        await mkdir(directory, { mode: 0o755 }).catch(error => { if (error.code !== 'EEXIST')
+            throw error; });
+        const stat = await lstat(directory);
+        if (!stat.isDirectory() || stat.isSymbolicLink())
+            throw new Error('workspace_worktree_skill_archive_unavailable');
+    }
+}
+/** Clone the saved commit and its exact skill archives, without copying unsaved files or credentials. */
+export async function checkoutChatWorktree(source, destination, commit, stateDir) {
+    const options = { timeout: 90_000, maxBuffer: 8 * 1024 * 1024,
+        env: { PATH: process.env.PATH, HOME: stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' } };
+    const git = async (root, ...args) => (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], options)).stdout;
+    await execute('git', ['-c', 'core.hooksPath=/dev/null', 'clone', '--local', '--no-hardlinks', '--no-checkout', '--', source, destination], options);
+    await git(destination, 'checkout', '--detach', commit);
+    const management = await lstat(join(destination, '.playcraft')).catch(() => undefined);
+    if (management && (!management.isDirectory() || management.isSymbolicLink()))
+        throw new Error('workspace_worktree_skill_archive_unavailable');
+    const lock = await lstat(join(destination, '.playcraft/skills.lock.json')).catch(() => undefined);
+    if (!lock)
+        return;
+    const snapshot = validateProjectSkillsSnapshot(await git(destination, 'show', `${commit}:.playcraft/skills.json`), await git(destination, 'show', `${commit}:.playcraft/skills.lock.json`));
+    const copied = new Set();
+    for (const entry of snapshot.lock.entries) {
+        const path = `.playcraft/skill-artifacts/${entry.revision.artifactHash}.tar.gz`;
+        if (copied.has(path))
+            continue;
+        copied.add(path);
+        const saved = join(destination, path);
+        if (await lstat(saved).catch(() => undefined))
+            throw new Error('workspace_worktree_skill_archive_tracked');
+        const original = join(source, path);
+        if (!await lstat(original).catch(() => undefined))
+            continue;
+        if (await realpath(dirname(original)).catch(() => '') !== join(source, '.playcraft/skill-artifacts'))
+            throw new Error('workspace_worktree_skill_archive_unavailable');
+        const handle = await open(original, constants.O_RDONLY | constants.O_NOFOLLOW);
+        let archive;
+        try {
+            const stat = await handle.stat();
+            if (!stat.isFile() || stat.nlink !== 1 || stat.size > 80 * 1024 * 1024)
+                throw new Error('workspace_worktree_skill_archive_unavailable');
+            archive = await handle.readFile();
+        }
+        finally {
+            await handle.close();
+        }
+        if (createHash('sha256').update(archive).digest('hex') !== entry.revision.artifactHash)
+            throw new Error('workspace_worktree_skill_archive_unavailable');
+        await archiveDirectory(destination);
+        await writeFile(saved, archive, { flag: 'wx', mode: 0o644 });
+    }
+    // Existing locked repository bytes and the exact runtime cache can fill missing archives.
+    await readWorkspaceSkills(destination, join(stateDir, 'skill-artifacts'));
+}

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

@@ -0,0 +1,73 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { workspaceDirectoryNameSchema, workspaceDirectoryRegistrationSchema, workspaceWorktreeSourceSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { workspaceDirectoryOccupied } from './directory-maintenance.js';
+import { registerWorkspaceDirectory } from './directories.js';
+import { copyWorktreeAttachments } from './worktree-attachments.js';
+import { revisionScope, workspaceRoot, WorkspaceContextError } from './registry.js';
+import { scheduleDependencyInstall } from './dependencies.js';
+const execute = promisify(execFile);
+async function git(state, root, ...args) {
+    return (await execute('git', ['-c', 'core.hooksPath=/dev/null', '-c', 'core.fsmonitor=false', '-C', root, ...args], {
+        timeout: 30_000, maxBuffer: 1024 * 1024,
+        env: { PATH: process.env.PATH, HOME: state.config.stateDir, GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0', GIT_OPTIONAL_LOCKS: '0' },
+    })).stdout.trim();
+}
+function assertLease(state, leaseFence) {
+    if (state.config.workspaceMode !== 'multi')
+        throw new WorkspaceContextError('multi_workspace_unavailable');
+    if (state.journal.destroyed())
+        throw new WorkspaceContextError('runtime_destroyed');
+    if (!Number.isSafeInteger(leaseFence) || leaseFence < state.acceptedLeaseFence)
+        throw new WorkspaceContextError('stale_lease');
+}
+async function sourceRoot(state, workspaceId, sourceDirectoryName, branchName) {
+    workspaceDirectoryNameSchema.parse(sourceDirectoryName);
+    const binding = state.journal.getWorkspace(workspaceId);
+    if (!binding || binding.targetKind === 'standalone')
+        throw new WorkspaceContextError('workspace_not_registered');
+    const directory = binding.directories?.find(item => item.directoryName === sourceDirectoryName);
+    if (directory?.status && directory.status !== 'ready')
+        throw new WorkspaceContextError('workspace_not_prepared');
+    if (await workspaceDirectoryOccupied(state, workspaceId, sourceDirectoryName))
+        throw new WorkspaceContextError('directory_busy');
+    const root = await workspaceRoot(state, workspaceId, sourceDirectoryName);
+    const expected = sourceDirectoryName === 'basic' ? binding.branchName : directory?.branchName;
+    const current = await git(state, root, 'symbolic-ref', '--quiet', '--short', 'HEAD').catch(() => '');
+    if (!expected || current !== expected || (branchName !== undefined && branchName !== expected)
+        || await git(state, root, 'config', '--get', 'remote.origin.url').catch(() => '') !== binding.repositoryUrl)
+        throw new WorkspaceContextError('workspace_checkout_mismatch');
+    if (await git(state, root, 'status', '--porcelain', '--untracked-files=all', '--', '.playcraft/skills.json', '.playcraft/skills.lock.json'))
+        throw new WorkspaceContextError('workspace_worktree_skills_uncommitted');
+    return { root, branchName: current };
+}
+/** Capture the selected checkout's saved commit without changing its branch, index or files. */
+export async function readWorktreeSource(state, workspaceId, sourceDirectoryName, leaseFence, branchName) {
+    assertLease(state, leaseFence);
+    return state.journal.exclusive(`directory:${workspaceId}:${sourceDirectoryName}`, async () => {
+        const source = await sourceRoot(state, workspaceId, sourceDirectoryName, branchName);
+        const sourceCommit = await git(state, source.root, 'rev-parse', '--verify', 'HEAD^{commit}');
+        assertLease(state, leaseFence);
+        return workspaceWorktreeSourceSchema.parse({ workspaceId, sourceDirectoryName, branchName: source.branchName, sourceCommit });
+    });
+}
+/** Materialize only the trusted identity and fixed commit. The regular session path binds the chat later. */
+export async function registerChatWorktree(state, input, leaseFence, sourceDirectoryName, branchName, attachmentIds) {
+    const directory = workspaceDirectoryRegistrationSchema.parse(input);
+    assertLease(state, leaseFence);
+    if (directory.directoryName === sourceDirectoryName || directory.directoryName === 'basic' || !directory.remixId || !directory.sourceCommit)
+        throw new WorkspaceContextError('workspace_directory_binding_conflict');
+    return state.journal.exclusive(`directory:${directory.workspaceId}:${sourceDirectoryName}`, async () => {
+        const source = await sourceRoot(state, directory.workspaceId, sourceDirectoryName, branchName);
+        if (await workspaceDirectoryOccupied(state, directory.workspaceId, directory.directoryName))
+            throw new WorkspaceContextError('directory_busy');
+        await git(state, source.root, 'check-ref-format', '--branch', directory.branchName);
+        await git(state, source.root, 'cat-file', '-e', `${directory.sourceCommit}^{commit}`);
+        const result = await registerWorkspaceDirectory(state, directory, leaseFence, sourceDirectoryName, true);
+        const target = await workspaceRoot(state, directory.workspaceId, directory.directoryName);
+        await copyWorktreeAttachments(source.root, target, attachmentIds);
+        assertLease(state, leaseFence);
+        void scheduleDependencyInstall(state, revisionScope(state, directory.workspaceId, directory.directoryName), target);
+        return { ...result, status: 'ready' };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.54",
+  "version": "0.1.55-beta",
   "private": false,
   "type": "module",
   "engines": {
@@ -14,16 +14,18 @@
     "dist",
     "templates",
     "project-template",
+    "project-template-v2",
     "engine-packs",
     "project-templates",
     "REMIX.md",
+    "SKILLS_REGISTRY.md",
     "README.md"
   ],
   "scripts": {
     "dev": "tsc -w",
-    "build": "tsc",
+    "build": "node scripts/generate-asset-skills.mjs && node scripts/generate-video-skills.mjs && node scripts/generate-preview-runtime.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 +37,11 @@
     "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:asset-skills": "node scripts/generate-asset-skills.mjs --check && node --test scripts/generate-asset-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 +52,9 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.1.54",
-    "@playcraft/common": "^0.1.54",
+    "@playcraft/build": "0.1.55-beta",
+    "@playcraft/common": "0.1.55-beta",
+    "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",
@@ -62,8 +70,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 +89,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-audio-generation/SKILL.md

@@ -1,13 +1,40 @@
 ---
 name: playcraft-audio-generation
-description: PlayCraft AI 音频生成完整指南。涵盖 SFX 音效生成、BGM 背景音乐生成（prompt 套路、时长、风格参数）、本地音频后处理（compress/fade/loop/normalize/mix），以及完整的音频管线。Artist 和 TA 在生成音频资产前必读。
+description: Use when generating or replacing playable audio, reusing library audio, managing durable audio tasks, or locally compressing, trimming, looping, normalizing, and mixing sound.
 triggers: 生成音效,生成bgm,生成背景音乐,generate sfx,generate bgm,generate audio,音频,音效,背景音乐,sfx,bgm,loop音频,音频压缩,音频处理,audio,compress audio,fade,normalize,音频后处理,音频管线
+compatibility: agent,opencode
+version: 1.1.1
+surfaces:
+  - sandbox-agent
 ---
 
 # PlayCraft AI 音频生成指南
 
 ## 0. 开始前必读
 
+AI (Artificial Intelligence, 人工智能) 音频包含 SFX (Sound Effects, 音效) 与 BGM (Background Music, 背景音乐)。工作素材写入当前工程的 `assets/audio/` 或当前主题素材目录；最终交付导出到工程根目录 `dist/`。请求文件和工作记录保存在 `dist/` 外。
+
+### 复用素材与持久化音频任务
+
+```bash
+# 共享素材按名称、路径与标签检索；保留返回的素材编号
+playcraft library search "reward" --type audio --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/audio/reward.mp3
+
+# 需要任务记录和断线恢复时使用工作区任务
+playcraft assets estimate --request audio-request.json
+playcraft assets generate --request audio-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/audio/generated-reward.mp3
+```
+
+`audio-request.json` 使用 JSON (JavaScript Object Notation, 数据交换格式)，例如 `{"kind":"audio","category":"sfx","description":"A short bright reward chime","duration":1}`；背景音乐改用 `category: "bgm"`，可带 `style` 与 `bpm`。持久化任务请求使用 `description`，直接生成命令使用 `--prompt`，不要混用两条入口的参数。
+
+任务命令自动读取 `.playcraft/workspace-context.json`；工程外需指定 `--workspace <workspaceId> --directory basic` 或实际变体目录。一次提交复用同一 `--client-request-id` 与原请求；拿到任务编号后用 `get` / `wait` 恢复。等待超时返回状态码 75，任务仍可查询。下载目标必须尚不存在；素材包使用新目录并保留相对路径。下载只保存文件，平台采纳状态仍由有效写入回执确认。任务取消、保存到素材库和恢复保存任务见当前可用的 `playcraft-workspace-assets` 技能。
+
 音频资产分两类，使用不同工具：
 
 | 类型               | 工具                           | 是否需要后端 |
@@ -37,7 +64,7 @@ playcraft tools generate-sfx \
 | ------------ | --------------------------- | -------------------------- |
 | `--prompt`   | 音效描述（**必须英文**）    | 见下方 prompt 套路         |
 | `--output`   | 保存路径（`.mp3` / `.wav`） | —                          |
-| `--duration` | 时长（秒）                  | SFX：0.3–3.0；环境音：3–10 |
+| `--duration` | 时长（秒）                  | SFX：0.5–3.0；环境音：3–10 |
 | `--loop`     | 是否循环友好                | 环境音、引擎声用 `--loop`  |
 
 ### SFX Prompt 套路
@@ -80,7 +107,7 @@ const SFX_LIST = [
   {
     name: 'click',
     prompt: 'button click, game UI, soft satisfying, short',
-    duration: 0.3,
+    duration: 0.5,
   },
   {
     name: 'win',
@@ -95,7 +122,7 @@ const SFX_LIST = [
   {
     name: 'jump',
     prompt: 'jump sound, platform game, light spring bounce',
-    duration: 0.4,
+    duration: 0.5,
   },
 ];
 

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

@@ -1,13 +1,42 @@
 ---
 name: playcraft-image-generation
-description: PlayCraft AI (Artificial Intelligence, 人工智能) 图片生成与素材替换指南。默认使用可用的 Image 2.5；替换素材时读取参考图，全新素材可无参考文生图；验证背景要求、目标尺寸和最终文件。
+description: Use when generating or replacing playable images, reusing shared visual assets, or managing durable image tasks. AI (Artificial Intelligence, 人工智能) 图片生成与替换指南，保持参考图、背景要求、目标尺寸和交付文件一致。
 triggers: 生成图片,generate image,选模型,model selection,reference image,参考图,风格一致,图生图,文生图,AI生图,图片质量,模型选择,500错误,模型失败,generate-image,list-image-models,ta-workspace,batch,批量,脚本,nodejs,edit模型,变体,绿幕,去背景,透明PNG,prompt,提示词,prompt套路,提示词技巧
+compatibility: agent,opencode
+version: 1.1.2
+surfaces:
+  - sandbox-agent
 ---
 
 # PlayCraft AI 图片生成指南
 
 ## 0. 开始前必读
 
+工作素材和脚本保存在当前工程，素材通常写 `assets/` 或当前主题目录；最终交付导出到工程根目录 `dist/`。云工作区的素材检索和持久化任务使用下列入口；任务请求文件和回执保存在 `dist/` 外。
+
+### 素材复用与可恢复生成
+
+```bash
+# 需要复用已有图片时，按名称、路径和标签查找共享素材
+playcraft library search "角色" --type texture --json
+playcraft library get <assetId> --json
+playcraft library files <assetId> --json
+playcraft library download <assetId> --output ./assets/library-character
+
+# 需要持久任务、精灵图或帧动画时，提交工作区任务
+playcraft assets estimate --request image-request.json
+playcraft assets generate --request image-request.json --client-request-id <stable-request-id>
+playcraft assets get <taskId>
+playcraft assets wait <taskId> --timeout 1800
+playcraft assets download <taskId> --output ./assets/generated-character
+```
+
+`image-request.json` 使用 JSON (JavaScript Object Notation, 数据交换格式)，例如 `{"kind":"image","prompt":"A cheerful game character","removeBackground":true}`。请求中的透明背景开关由下文交付约束决定；素材替换需要读取字段参考图和规格时，继续使用下文的 `tools image-context` 与 `tools generate-image`。这两条入口没有可互换的参数表。
+
+任务命令从 `.playcraft/workspace-context.json` 推断当前工作区和工程目录；在工程外运行时传 `--workspace <workspaceId> --directory basic`，或实际变体目录。提交结果不确定时复用同一个 `--client-request-id` 与原请求；已有任务编号后通过 `get` / `wait` 恢复。等待超时以状态码 75 退出，任务仍可查询。精灵图和动画必须下载完整包并保留相对路径；`download` 保存文件不代表平台已确认采纳。
+
+普通单图生成和替换使用本技能下方的直接工具与命令；素材库检索、生成任务保存到素材库、动画草稿及版本的详细流程见当前可用的 `playcraft-workspace-assets` 技能。下载目标必须尚不存在。
+
 替换现有素材时先读取目标字段的 schema 配置（resolution、ratio、prompt、remove_background、reference_image）及当前素材。全新素材按用户需求确定尺寸、格式和输出路径，不假定所有素材都是透明 PNG (Portable Network Graphics, 便携式网络图形)。
 
 项目没有素材 schema 时，从目标素材的尺寸、格式和用户需求确定交付规格；参考图只提供内容和风格，不改变目标画布。不要套用其他游戏的字段、路径或尺寸。
@@ -214,7 +243,7 @@ Artist 生成 MC 时**不得**套用上方通用决策树里的 gemini / flux /
 | `mulerouter/gpt-image-2`   | `gemini-*`、`flux-*`、`hy-image-*`、`wan*`、`qwen*` |
 | `mulerouter/nano-banana-2` | 裸 `gpt-image-2`（会走 iegg-litellm 压扁五格）      |
 
-完整 prompt / 尺寸规范见 **`playcraft-storyboard`** skill。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
+故事板的提示词与尺寸依据本节规格和当前工程的制作要求。ASR 双板 `--image-model` 须与已选 MC **完全一致**。
 
 **Phase 1（概念图）**：纯文生图，`--image-size 4K` + MC 白名单内模型。
 **Phase 2（批量生产）**：必须带 `--reference-image` 指向 Phase 1 确认的概念图，同一批次使用**相同模型 + 相同 reference image + 相同 image-size**。
@@ -325,13 +354,13 @@ playcraft image overlay \
 # 目视检查：无白边、无色幕残留色、无黑色不透明块、边缘干净
 ```
 
-**不通过时的修复**：见 `ta-pipeline-cookbook.md` Step 0e §3 及 Compliance Gate 失败修复表。
+**不通过时的修复**：检查实际模型、源图背景和去背参数，保留原始图与失败回执；按下方进阶参考的错误恢复策略处理。透明验收仍失败时报告具体阶段并停止，不交付未通过的文件。
 
 ---
 
 ## 3.1 ASR 专用分支（Artist · ring 3 build）
 
-> **Read `playcraft-asset-state-sheet` Skill first.** ASR 是制作期参考板，不是 runtime 透明资产。
+> 先核对当前工程素材状态表中的槽位、状态和交付尺寸。ASR 是制作期参考板，不是 runtime 透明资产。
 
 | 阶段              | Artist                                | TA                            |
 | ----------------- | ------------------------------------- | ----------------------------- |
@@ -354,11 +383,13 @@ playcraft image overlay \
 - **<=5 个文件** → 直接使用 CLI 命令
 - **>5 个文件** → 编写 Node.js 脚本放入 `ta-workspace/scripts/`。脚本模板见 `reference/` 目录；使用本次选定的模型与参考图，不直接沿用脚本中旧的默认模型。
 
+复制模板时，`SKILL_DIR` 表示本次实际加载的 `SKILL.md` 所在目录，由技能加载回执确定。将示例中的该变量设为真实目录后再运行；项目安装与冻结安装的目录可能不同。
+
 ---
 
 ## 5. 进阶参考
 
-需要以下进阶内容时，查阅 [`refs/ta-image-generation-detail.md`](../../agents/refs/ta-image-generation-detail.md)：
+需要以下进阶内容时，查阅 [`reference/ta-image-generation-detail.md`](reference/ta-image-generation-detail.md)：
 
 | 主题                  | 说明                                                             |
 | --------------------- | ---------------------------------------------------------------- |

package/project-template/.claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs

@@ -3,7 +3,7 @@
 // 用途：将处理好的图片目录合并为精灵图（PNG + JSON 元数据）
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/build-sprite-sheet.template.mjs ta-workspace/scripts/build-<name>-atlas.mjs
+//   1. cp "$SKILL_DIR/reference/build-sprite-sheet.template.mjs" ta-workspace/scripts/build-<name>-atlas.mjs
 //   2. 修改下方 CONFIG 区域
 //   3. 如需控制帧顺序，填写 ORDERED_NAMES 数组（留空则按文件名排序）
 //   4. node ta-workspace/scripts/build-<name>-atlas.mjs

package/project-template/.claude/skills/playcraft-image-generation/reference/compare-style.template.mjs

@@ -5,7 +5,7 @@
  * 用途：TA Micro-Batch Validation 辅助工具，对 AI 补全素材与 Artist 样本做客观色彩比较。
  *
  * 使用方法：
- *   cp .claude/skills/playcraft-image-generation/reference/compare-style.template.mjs \
+ *   cp "$SKILL_DIR/reference/compare-style.template.mjs" \
  *      ta-workspace/scripts/compare-style.mjs
  *   # 修改下方 CONFIG 区域后运行：
  *   node ta-workspace/scripts/compare-style.mjs

package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs

@@ -10,7 +10,7 @@
 //   - 数字/字母贴图：一批 ≤16 个
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/gen-batch-sprite.template.mjs ta-workspace/scripts/gen-<name>-sprite.mjs
+//   1. cp "$SKILL_DIR/reference/gen-batch-sprite.template.mjs" ta-workspace/scripts/gen-<name>-sprite.mjs
 //   2. 修改下方 CONFIG 和 BATCHES 区域
 //   3. node ta-workspace/scripts/gen-<name>-sprite.mjs
 // ============================================================

package/project-template/.claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs

@@ -3,7 +3,7 @@
 // 用途：从零批量生成一组风格一致的素材（reference-image 模式）
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/gen-batch.template.mjs ta-workspace/scripts/gen-<name>.mjs
+//   1. cp "$SKILL_DIR/reference/gen-batch.template.mjs" ta-workspace/scripts/gen-<name>.mjs
 //   2. 修改下方 CONFIG 和 ITEMS 区域
 //   3. node ta-workspace/scripts/gen-<name>.mjs
 // ============================================================

package/project-template/.claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs

@@ -8,7 +8,7 @@
 //   - 图标集（换内容符号）
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/gen-edit-variants.template.mjs ta-workspace/scripts/gen-<name>-variants.mjs
+//   1. cp "$SKILL_DIR/reference/gen-edit-variants.template.mjs" ta-workspace/scripts/gen-<name>-variants.mjs
 //   2. Phase 1：先手动生成基图（见下方说明），存为 CONFIG.baseImage 路径
 //   3. 填写 CONFIG 和 VARIANTS，然后 node ta-workspace/scripts/gen-<name>-variants.mjs
 //

package/project-template/.claude/skills/playcraft-image-generation/reference/process-batch.template.mjs

@@ -3,7 +3,7 @@
 // 用途：对一批图片执行去背景 / trim + resize + 验证
 //
 // 使用方式：
-//   1. cp .claude/skills/playcraft-image-generation/reference/process-batch.template.mjs ta-workspace/scripts/process-<name>.mjs
+//   1. cp "$SKILL_DIR/reference/process-batch.template.mjs" ta-workspace/scripts/process-<name>.mjs
 //   2. 修改下方 CONFIG 区域（特别是 SKIP_REMOVE_BG 选项）
 //   3. node ta-workspace/scripts/process-<name>.mjs
 //