@playcraft/cli 0.1.54 → 0.1.55-beta

package/dist/auth/account-activation.js

@@ -0,0 +1,157 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { loadGlobalConfig } from '../config.js';
+import { accountActivationMessage } from './messages.js';
+export const ACCOUNT_PENDING_ACTIVATION = 'account_pending_activation';
+export class AccountActivationError extends Error {
+    code;
+    status;
+    retryable = false;
+    constructor(code, message, status) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.name = 'AccountActivationError';
+    }
+}
+export function responseErrorCode(payload) {
+    if (!payload || typeof payload !== 'object')
+        return undefined;
+    const { error, code } = payload;
+    return typeof error?.code === 'string' ? error.code : typeof code === 'string' ? code : undefined;
+}
+export function pendingAccountActivationError(status, payload) {
+    return status === 403 && responseErrorCode(payload) === ACCOUNT_PENDING_ACTIVATION
+        ? new AccountActivationError(ACCOUNT_PENDING_ACTIVATION, `${ACCOUNT_PENDING_ACTIVATION}: ${accountActivationMessage('pending')}`, status)
+        : undefined;
+}
+export function parseErrorPayload(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function localActivationConfig() {
+    for (const path of [
+        join(process.cwd(), '.playcraft.json'),
+        '/project/.playcraft.json',
+        join(homedir(), '.playcraft.json'),
+    ]) {
+        if (!existsSync(path))
+            continue;
+        try {
+            const config = JSON.parse(readFileSync(path, 'utf8'));
+            if (config && typeof config === 'object' && !Array.isArray(config))
+                return config;
+        }
+        catch {
+            // Follow the existing local credential lookup when a file is unreadable.
+        }
+    }
+    return {};
+}
+function stringValue(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+function activationBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol) ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash)
+            throw new Error();
+        url.pathname = url.pathname.replace(/\/+$/, '').replace(/\/api$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        throw new AccountActivationError('INVALID_ACTIVATION_TARGET', accountActivationMessage('invalidTarget'));
+    }
+}
+function savedTokenForTarget(config, rawUrl, target, environment) {
+    if (!rawUrl || (stringValue(config.env)?.trim() || '') !== environment)
+        return undefined;
+    try {
+        return activationBaseUrl(rawUrl) === target ? stringValue(config.token) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function normalizedSavedUrl(raw) {
+    try {
+        return raw ? activationBaseUrl(raw) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function activateAccount(options, defaultBaseUrl) {
+    const local = localActivationConfig();
+    const global = loadGlobalConfig();
+    const localUrl = stringValue(local.apiUrl);
+    const globalUrl = stringValue(global.backendUrl) || stringValue(global.url);
+    const explicitUrl = options.url || process.env.PLAYCRAFT_API_URL || process.env.PLAYCRAFT_URL;
+    const target = activationBaseUrl(explicitUrl || localUrl || globalUrl || defaultBaseUrl);
+    const explicitToken = options.token || process.env.PLAYCRAFT_TOKEN || process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const savedUrls = [normalizedSavedUrl(localUrl), normalizedSavedUrl(globalUrl)].filter(Boolean);
+    const savedTokens = [stringValue(local.token), stringValue(global.token)].filter(Boolean);
+    const environmentsConflict = savedUrls.length === 2 &&
+        savedUrls[0] === savedUrls[1] &&
+        (stringValue(local.env)?.trim() || '') !== (stringValue(global.env)?.trim() || '');
+    const environmentTokensConflict = process.env.PLAYCRAFT_TOKEN &&
+        process.env.PLAYCRAFT_SANDBOX_TOKEN &&
+        process.env.PLAYCRAFT_TOKEN !== process.env.PLAYCRAFT_SANDBOX_TOKEN;
+    const environmentUrlsConflict = process.env.PLAYCRAFT_API_URL &&
+        process.env.PLAYCRAFT_URL &&
+        normalizedSavedUrl(process.env.PLAYCRAFT_API_URL) !==
+            normalizedSavedUrl(process.env.PLAYCRAFT_URL);
+    if ((!explicitUrl && new Set(savedUrls).size > 1) ||
+        (!explicitToken && new Set(savedTokens).size > 1) ||
+        (environmentsConflict && !process.env.PLAYCRAFT_ENV) ||
+        (environmentTokensConflict && !options.token) ||
+        (environmentUrlsConflict && !options.url)) {
+        throw new AccountActivationError('AMBIGUOUS_ACTIVATION_TARGET', accountActivationMessage('ambiguous'));
+    }
+    const environment = (process.env.PLAYCRAFT_ENV ||
+        (!explicitUrl ? (localUrl ? stringValue(local.env) : stringValue(global.env)) : '') ||
+        '').trim();
+    const token = explicitToken ||
+        savedTokenForTarget(local, localUrl, target, environment) ||
+        savedTokenForTarget(global, globalUrl, target, environment);
+    if (!token)
+        throw new AccountActivationError('AUTH_REQUIRED', accountActivationMessage('missingToken'));
+    if (!/^playcraft_pat_[A-Za-z0-9_-]{32}$/.test(token)) {
+        throw new AccountActivationError('INVALID_ACTIVATION_TOKEN', accountActivationMessage('invalidToken'));
+    }
+    let response;
+    try {
+        response = await fetch(`${target}/api/settings/personal-access-tokens/activate`, {
+            method: 'POST',
+            redirect: 'error',
+            signal: AbortSignal.timeout(30_000),
+            headers: {
+                Authorization: `Bearer ${token}`,
+                ...(environment ? { 'playcraft-env': environment } : {}),
+            },
+        });
+    }
+    catch {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'));
+    }
+    if (!response.ok) {
+        await response.body?.cancel().catch(() => { });
+        throw new AccountActivationError('ACTIVATION_FAILED', accountActivationMessage('failed'), response.status);
+    }
+    const result = await response.json().catch(() => undefined);
+    if (!result ||
+        typeof result !== 'object' ||
+        result.accountStatus !== 'active') {
+        throw new AccountActivationError('ACTIVATION_UNCONFIRMED', accountActivationMessage('unavailable'), response.status);
+    }
+    console.log(accountActivationMessage('success'));
+}

package/dist/auth/messages.js

@@ -0,0 +1,30 @@
+const messages = {
+    en: {
+        activateOption: 'Explicitly activate the account using the current personal access token',
+        tokenOption: 'Personal access token for --activate (or use PLAYCRAFT_TOKEN)',
+        pending: 'Account activation is required. Run `playcraft login --activate` with the same token and target environment, then rerun your command.',
+        success: 'Account activated. Rerun your original command to continue.',
+        missingToken: 'No personal access token matches this target environment. Provide PLAYCRAFT_TOKEN or log in to this environment first.',
+        invalidToken: 'Account activation requires a personal access token. A sandbox token cannot activate an account.',
+        ambiguous: 'Activation credentials or target environments conflict. Specify --url, PLAYCRAFT_ENV when needed, and an explicit personal access token using --token or PLAYCRAFT_TOKEN.',
+        invalidTarget: 'Use a web service base address (http:// or https://) without credentials, a query, or a fragment.',
+        failed: 'Account activation failed. Check the target environment and token before trying again.',
+        unavailable: 'Account activation could not be confirmed. Check your account status before explicitly trying again.',
+    },
+    zh: {
+        activateOption: '明确使用当前个人访问令牌激活账号',
+        tokenOption: '用于 --activate 的个人访问令牌（也可使用 PLAYCRAFT_TOKEN）',
+        pending: '账号需要激活。请使用同一令牌和目标环境主动运行 `playcraft login --activate`，然后重新执行原命令。',
+        success: '账号已激活，请重新执行原命令继续。',
+        missingToken: '没有与目标环境匹配的个人访问令牌。请提供 PLAYCRAFT_TOKEN，或先登录此环境。',
+        invalidToken: '激活账号需要个人访问令牌，沙箱令牌不能用于激活账号。',
+        ambiguous: '激活凭据或目标环境存在冲突。请明确指定 --url、所需的 PLAYCRAFT_ENV，并通过 --token 或 PLAYCRAFT_TOKEN 提供个人访问令牌。',
+        invalidTarget: '激活目标必须是网页服务基址（http:// 或 https://），不能包含凭据、查询参数或片段。',
+        failed: '账号激活失败，请检查目标环境和令牌后再尝试。',
+        unavailable: '无法确认账号是否已激活。请先检查账号状态，再主动决定是否重试。',
+    },
+};
+export function accountActivationMessage(key) {
+    const locale = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[locale.startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/cli-root-help.js

@@ -5,8 +5,12 @@ export function getCliTopicsHelpText() {
         '',
         '  本地开发   create, init, start, stop, status, logs, config, sync, fix-ids',
         '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>  |  prefab <子命令>',
+        '  素材库     library list/search/facets/get/files/download',
+        '  生成任务   assets estimate/generate/tasks/get/wait/cancel/download | assets animation',
+        '  视频理解   video models | video understand | video jobs get/cancel',
         '  平台       build, build-base, build-playable, build-all, analyze, inspect, upgrade',
         '             tools 除 generate-* 外（Git / 沙箱构建 / 发布 / 列表 / Prefab 等，需后端 API）',
+        '  沙箱常驻   workspace-runtime serve（Cloud Workspace，由 Runtime 引导配置启动）',
         '',
         '也可运行: playcraft topics',
         '',

package/dist/commands/assets.js

@@ -0,0 +1,123 @@
+import { assetGenerationRequestSchema, assetGenerationEstimateInput, assetGenerationEstimateInputSchema, assetGenerationEstimateSchema, assetGenerationTaskSavedSchema, assetLibrarySaveRequestSchema, assetLibrarySaveJobSchema, assetLibrarySaveListSchema, assetLibrarySaveTargetsSchema, animationEditorStateSchema, animationEditorDraftUpdateSchema, animationEditorFrameUploadSchema, animationEditorFrameUploadResultSchema, animationEditorVersionCreateSchema, animationEditorVersionResultSchema, workspaceAssetToolWriteSchema, } from '@playcraft/common/cloud-workspace/runtime';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveAssetScope, readAssetRequest, readAssetTask, readAssetTasks, scopedAssetTask, waitForAssetTask, downloadAssetTask } from '../assets/client.js';
+import { validateAssetWait } from '../assets/client.js';
+import { assetMessage as t } from '../assets/messages.js';
+function shared(command) {
+    return command.option('--workspace <id>', t('workspace')).option('--directory <name>', t('directory')).option('--json', t('json'));
+}
+function polling(command) {
+    return command.option('--timeout <seconds>', t('timeout'), '1800').option('--interval <seconds>', t('interval'), '3');
+}
+function identifier(value) {
+    if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value))
+        throw new Error(t('invalidRequest'));
+    return value.toLowerCase();
+}
+async function document(path) { if (!path)
+    throw new Error(t('invalidRequest')); return readAssetRequest(path); }
+async function run(command, options, action) {
+    try {
+        const scope = await resolveAssetScope(options);
+        const result = await action({ scope, client: new AgentApiClient() });
+        const record = result && typeof result === 'object' ? result : {};
+        const failed = ['failed', 'interrupted', ...(command === 'assets cancel' ? [] : ['cancelled'])];
+        const ok = !failed.includes(record.status ?? '');
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 'playcraft.assets-cli.v1', command, ok, result })}\n`);
+        if (!ok)
+            process.exitCode = 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const timeout = message === t('timeoutReached');
+        process.stderr.write(`${t('failed')}: ${message}\n`);
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 'playcraft.assets-cli.v1', command, ok: false,
+            error: { code: timeout ? 'asset_generation_wait_timeout' : 'asset_operation_failed', message } })}\n`);
+        process.exitCode = timeout ? 75 : 1;
+    }
+}
+function write(client, body) {
+    return client.post(body.action === 'animation-draft' ? '/workspace-assets/animation-draft' : '/workspace-assets', workspaceAssetToolWriteSchema.parse(body));
+}
+export function registerWorkspaceAssetCommands(program) {
+    const assets = program.command('assets').description(t('topic'));
+    shared(assets.command('estimate').description(t('estimate')))
+        .requiredOption('--request <path>', t('request'))
+        .action((options) => run('assets estimate', options, async ({ client, scope }) => {
+        const input = await document(options.request), full = assetGenerationRequestSchema.safeParse(input);
+        const request = full.success ? assetGenerationEstimateInput(full.data) : assetGenerationEstimateInputSchema.parse(input);
+        return assetGenerationEstimateSchema.parse(await write(client, { ...scope, action: 'estimate', request }));
+    }));
+    polling(shared(assets.command('generate').description(t('generate'))))
+        .requiredOption('--request <path>', t('request')).requiredOption('--client-request-id <id>', t('clientRequest'))
+        .option('--wait', t('waitOption')).option('--output <path>', t('output'))
+        .action((options) => run('assets generate', options, async ({ client, scope }) => {
+        if (options.output && !options.wait)
+            throw new Error(t('invalidRequest'));
+        if (options.wait)
+            validateAssetWait(Number(options.timeout), Number(options.interval));
+        const clientRequestId = options.clientRequestId.trim();
+        if (!clientRequestId)
+            throw new Error(t('invalidRequest'));
+        const request = assetGenerationRequestSchema.parse(await document(options.request));
+        let task = scopedAssetTask(scope, await write(client, { ...scope, action: 'create', clientRequestId, request }));
+        if (task.clientRequestId !== clientRequestId)
+            throw new Error(t('scopeMismatch'));
+        // The identity is printed before polling so a disconnected caller can recover without creating a task.
+        if (options.wait) {
+            process.stderr.write(`${JSON.stringify({ taskId: task.taskId, clientRequestId: task.clientRequestId, status: task.status })}\n`);
+            task = await waitForAssetTask(client, scope, task.taskId, Number(options.timeout), Number(options.interval));
+        }
+        if (options.output && ['awaiting_adoption', 'saved'].includes(task.status))
+            return downloadAssetTask(client, scope, task.taskId, options.output);
+        return task;
+    }));
+    shared(assets.command('tasks').description(t('tasks')))
+        .action((options) => run('assets tasks', options, ({ client, scope }) => readAssetTasks(client, scope)));
+    shared(assets.command('get <task-id>').description(t('get')))
+        .action((taskId, options) => run('assets get', options, ({ client, scope }) => readAssetTask(client, scope, identifier(taskId))));
+    shared(assets.command('cancel <task-id>').description(t('cancel')))
+        .action((taskId, options) => run('assets cancel', options, async ({ client, scope }) => scopedAssetTask(scope, await write(client, { ...scope, action: 'cancel', taskId: identifier(taskId) }))));
+    polling(shared(assets.command('wait <task-id>').description(t('wait'))))
+        .action((taskId, options) => run('assets wait', options, ({ client, scope }) => waitForAssetTask(client, scope, identifier(taskId), Number(options.timeout), Number(options.interval))));
+    shared(assets.command('download <task-id>').description(t('download')))
+        .requiredOption('--output <path>', t('output')).option('--version <id>', t('version'))
+        .action((taskId, options) => run('assets download', options, ({ client, scope }) => downloadAssetTask(client, scope, identifier(taskId), options.output, options.version ? identifier(options.version) : undefined)));
+    shared(assets.command('saved <task-id>').description(t('saved')))
+        .requiredOption('--receipt <path>', t('receipt'))
+        .action((taskId, options) => run('assets saved', options, async ({ client, scope }) => scopedAssetTask(scope, await write(client, { ...scope, action: 'saved', taskId: identifier(taskId), proof: assetGenerationTaskSavedSchema.parse(await document(options.receipt)) }))));
+    shared(assets.command('library-targets').description(t('libraryTargets')))
+        .action((options) => run('assets library-targets', options, async ({ client, scope }) => assetLibrarySaveTargetsSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'library-targets' }))));
+    shared(assets.command('library-saves <task-id>').description(t('librarySaves')))
+        .action((taskId, options) => run('assets library-saves', options, async ({ client, scope }) => assetLibrarySaveListSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'library-saves', taskId: identifier(taskId) }))));
+    shared(assets.command('library-save <task-id>').description(t('librarySave')))
+        .requiredOption('--request <path>', t('request'))
+        .action((taskId, options) => run('assets library-save', options, async ({ client, scope }) => assetLibrarySaveJobSchema.parse(await write(client, { ...scope, action: 'library-save', taskId: identifier(taskId), request: assetLibrarySaveRequestSchema.parse(await document(options.request)) }))));
+    shared(assets.command('library-retry <task-id>').description(t('libraryRetry')))
+        .requiredOption('--save-id <id>', t('saveId')).option('--start-without-workspace', t('release'))
+        .action((taskId, options) => run('assets library-retry', options, async ({ client, scope }) => assetLibrarySaveJobSchema.parse(await write(client, { ...scope, action: 'library-retry', taskId: identifier(taskId), saveId: identifier(options.saveId),
+        ...(options.startWithoutWorkspace ? { startWithoutWorkspace: true } : {}) }))));
+    const animation = assets.command('animation').description(t('animation'));
+    shared(animation.command('get <task-id>').description(t('animationGet')))
+        .action((taskId, options) => run('assets animation get', options, async ({ client, scope }) => {
+        const result = animationEditorStateSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'animation', taskId: identifier(taskId) }));
+        if (result.taskId !== identifier(taskId))
+            throw new Error(t('scopeMismatch'));
+        return result;
+    }));
+    for (const [name, action, description, schema, response] of [
+        ['draft', 'animation-draft', 'animationDraft', animationEditorDraftUpdateSchema, animationEditorStateSchema],
+        ['upload-frame', 'animation-frame', 'animationFrame', animationEditorFrameUploadSchema, animationEditorFrameUploadResultSchema],
+        ['version', 'animation-version', 'animationVersion', animationEditorVersionCreateSchema, animationEditorVersionResultSchema],
+    ]) {
+        shared(animation.command(`${name} <task-id>`).description(t(description))).requiredOption('--request <path>', t('request'))
+            .action((taskId, options) => run(`assets animation ${name}`, options, async ({ client, scope }) => {
+            const body = workspaceAssetToolWriteSchema.parse({ ...scope, action, taskId: identifier(taskId), request: schema.parse(await document(options.request)) });
+            return response.parse(await write(client, body));
+        }));
+    }
+    shared(animation.command('saved <task-id>').description(t('animationSaved')))
+        .requiredOption('--version <id>', t('version')).requiredOption('--receipt <path>', t('receipt'))
+        .action((taskId, options) => run('assets animation saved', options, async ({ client, scope }) => animationEditorVersionResultSchema.parse(await write(client, { ...scope, action: 'animation-saved', taskId: identifier(taskId), versionId: identifier(options.version),
+        proof: assetGenerationTaskSavedSchema.parse(await document(options.receipt)) }))));
+}

package/dist/commands/build-all.js

@@ -4,6 +4,7 @@ import pc from 'picocolors';
 import ora from 'ora';
 import { BaseBuilder, ViteBuilder, PlayableBuilder, EngineDetector, detectAmmoUsage, } from '@playcraft/build';
 import { loadBuildConfig } from '../build-config.js';
+import { cleanupBuildTempDirectory, createBuildTempDirectory } from './build-temp.js';
 import inquirer from 'inquirer';
 /**
  * 所有可用的渠道平台
@@ -141,6 +142,7 @@ export async function buildAllCommand(projectPath, options) {
     const spinner = ora(pc.cyan('🚀 批量打渠道包...')).start();
     let isBaseBuild = false;
     let baseBuildDir;
+    let tempBuildDir;
     try {
         // 1. 确定要构建的平台列表
         let targetPlatforms;
@@ -415,9 +417,9 @@ export async function buildAllCommand(projectPath, options) {
         }
         else {
             spinner.text = pc.cyan('执行阶段1: 基础构建（仅一次）...');
-            const tempDir = path.join(resolvedProjectPath, '.playcraft-temp', `base-build-${Date.now()}`);
+            tempBuildDir = await createBuildTempDirectory(resolvedProjectPath);
             const baseBuilder = new BaseBuilder(resolvedProjectPath, {
-                outputDir: tempDir,
+                outputDir: tempBuildDir,
                 selectedScenes,
                 analyze: options.analyze,
             });
@@ -593,6 +595,7 @@ export async function buildAllCommand(projectPath, options) {
         if (failCount > 0) {
             process.exit(1);
         }
+        await cleanupBuildTempDirectory(tempBuildDir);
     }
     catch (error) {
         spinner.fail(pc.red('批量构建失败'));
@@ -602,21 +605,4 @@ export async function buildAllCommand(projectPath, options) {
         }
         process.exit(1);
     }
-    finally {
-        // 清理临时目录，避免磁盘空间浪费
-        if (!isBaseBuild && baseBuildDir && baseBuildDir.includes('.playcraft-temp')) {
-            try {
-                await fs.rm(baseBuildDir, { recursive: true, force: true });
-                // 如果 .playcraft-temp 父目录为空，也一并清理
-                const tempParent = path.dirname(baseBuildDir);
-                const remaining = await fs.readdir(tempParent);
-                if (remaining.length === 0) {
-                    await fs.rm(tempParent, { recursive: true, force: true });
-                }
-            }
-            catch {
-                // 清理失败不影响构建结果
-            }
-        }
-    }
 }

package/dist/commands/build-temp.js

@@ -0,0 +1,26 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+export async function createBuildTempDirectory(projectPath) {
+    const parent = path.join(projectPath, '.playcraft-temp');
+    await mkdir(parent, { recursive: true });
+    const directory = path.join(parent, `base-build-${randomUUID()}`);
+    // mkdir 继承工程的共享组和权限掩码；mkdtemp 固定使用 0700。
+    await mkdir(directory);
+    return directory;
+}
+export async function cleanupBuildTempDirectory(directory) {
+    if (!directory)
+        return;
+    if (process.env.PLAYCRAFT_KEEP_BUILD_TEMP === '1') {
+        console.log(`构建临时目录保留在: ${directory}`);
+        return;
+    }
+    try {
+        // 只删除本次创建的目录，保留并发构建与用户输入；父目录不做递归清理。
+        await rm(directory, { recursive: true, force: true });
+    }
+    catch (error) {
+        console.warn(`清理构建临时目录失败: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}

package/dist/commands/build.js

@@ -4,6 +4,7 @@ import pc from 'picocolors';
 import ora from 'ora';
 import { BaseBuilder, ViteBuilder, PlayableBuilder, PlayableAnalyzer, EngineDetector, detectAmmoUsage } from '@playcraft/build';
 import { loadBuildConfig } from '../build-config.js';
+import { cleanupBuildTempDirectory, createBuildTempDirectory } from './build-temp.js';
 import inquirer from 'inquirer';
 /**
  * 类型守卫：检查对象是否符合 PlayableScriptsConfig 类型
@@ -250,6 +251,7 @@ export async function buildCommand(projectPath, options) {
     const spinner = ora(pc.cyan('🔨 开始打包 Playable Ad...')).start();
     // 清理选项（默认为 false，使用覆盖模式）
     const shouldClean = options.clean === true;
+    let tempBuildDir;
     try {
         // ====== 引擎 + 构建工具检测 ======
         spinner.text = pc.cyan('检测项目引擎类型...');
@@ -450,6 +452,7 @@ export async function buildCommand(projectPath, options) {
         const shouldRunPlayableOnly = options.mode === 'playable';
         // 验证平台
         const validPlatforms = [
+            'playcraft',
             'facebook',
             'snapchat',
             'ironsource',
@@ -473,6 +476,7 @@ export async function buildCommand(projectPath, options) {
         // 注：Facebook 在 Phaser（playable-scripts devkit）下的产物格式由其 devkit 输入配置决定（恒为 ZIP），
         //     平台侧不在此处做引擎判断。
         const platformFormatConfig = {
+            playcraft: { formats: ['html'], default: 'html' },
             facebook: { formats: ['html', 'zip'], default: 'html' },
             applovin: { formats: ['html'], default: 'html' },
             ironsource: { formats: ['html'], default: 'html' },
@@ -584,8 +588,11 @@ export async function buildCommand(projectPath, options) {
                     console.log(pc.dim('   无主题目录，跳过主题选择'));
                 }
             }
-            // 输入商店跳转地址（CTA）- 如果配置文件中没有则必填
-            if (!options.storeUrls) {
+            // 输入商店跳转地址（CTA）- 如果配置文件中没有则必填；通用预览（playcraft）不面向渠道，可不填
+            if (selectedPlatform === 'playcraft' && !options.storeUrls) {
+                console.log(pc.dim('\nℹ️  通用预览不需要商店地址'));
+            }
+            else if (!options.storeUrls) {
                 console.log(pc.cyan('\n🔗 商店跳转地址（CTA 按钮目标）'));
                 console.log(pc.dim('   iOS 和 Android 地址均为必填'));
                 const storeUrlAnswer = await inquirer.prompt([
@@ -636,8 +643,8 @@ export async function buildCommand(projectPath, options) {
                 // 未指定格式，使用默认值
                 options.format = formatConfig.default;
             }
-            // 如果命令行未传入 storeUrls，交互式输入（必填）
-            if (!options.storeUrls) {
+            // 如果命令行未传入 storeUrls，交互式输入（必填）；通用预览（playcraft）不面向渠道，可不填
+            if (!options.storeUrls && options.platform !== 'playcraft') {
                 spinner.stop();
                 console.log(pc.cyan('\n🔗 商店跳转地址（CTA 按钮目标）'));
                 console.log(pc.dim('   iOS 和 Android 地址均为必填'));
@@ -742,7 +749,7 @@ export async function buildCommand(projectPath, options) {
             // 输入是源代码或官方构建，先执行阶段1
             spinner.text = pc.cyan('执行阶段1: 基础构建...');
             // 将临时目录放在项目所在目录下，避免跨盘符路径问题（Windows 上 C:\Temp 和 D:\project 会导致 Vite 路径计算错误）
-            const tempDir = path.join(resolvedProjectPath, '.playcraft-temp', `base-build-${Date.now()}`);
+            tempBuildDir = await createBuildTempDirectory(resolvedProjectPath);
             // 构建 playableScriptsConfig，合并 CLI 选择的参数
             const playableScriptsConfig = buildPlayableScriptsConfig(fileConfig?.playableScripts, {
                 platform: options.platform,
@@ -750,7 +757,7 @@ export async function buildCommand(projectPath, options) {
                 selectedThemes,
             });
             const baseBuilder = new BaseBuilder(resolvedProjectPath, {
-                outputDir: tempDir,
+                outputDir: tempBuildDir,
                 selectedScenes,
                 analyze: buildOptions.analyze,
                 analyzeReportPath: buildOptions.analyze ? 'base-bundle-report.html' : undefined,
@@ -795,16 +802,7 @@ export async function buildCommand(projectPath, options) {
                 }
                 console.log('\n' + pc.green(`输出目录: ${finalOutputDir}`));
                 console.log(pc.dim('💡 产物已包含渠道适配、MRAID 注入、代码混淆和 fflate 压缩'));
-                // 清理临时目录
-                try {
-                    const tempBaseDir = path.join(resolvedProjectPath, '.playcraft-temp');
-                    await fs.rm(tempBaseDir, { recursive: true, force: true });
-                    console.log(pc.dim(`\n🗑️  已清理临时目录`));
-                }
-                catch (error) {
-                    // 记录清理错误信息
-                    console.log(pc.dim(`\n⚠️  清理临时目录失败: ${error instanceof Error ? error.message : String(error)}`));
-                }
+                await cleanupBuildTempDirectory(tempBuildDir);
                 return;
             }
             spinner.text = pc.cyan('✅ 阶段1完成，开始阶段2...');
@@ -976,18 +974,7 @@ export async function buildCommand(projectPath, options) {
                 console.log(pc.yellow(`\n⚠️  检测到 Ammo.js，建议替换为 ${analysis.suggestedEngine}`));
             }
         }
-        // 清理临时目录（调试时注释掉）
-        if (!isBaseBuild && baseBuildDir.includes('.playcraft-temp')) {
-            // 调试：暂时保留临时目录
-            console.log(pc.yellow(`[DEBUG] 临时目录保留在: ${baseBuildDir}`));
-            // try {
-            //   // 清理整个 .playcraft-temp 目录
-            //   const tempBaseDir = path.join(resolvedProjectPath, '.playcraft-temp');
-            //   await fs.rm(tempBaseDir, { recursive: true, force: true });
-            // } catch (error) {
-            //   // 忽略清理错误
-            // }
-        }
+        await cleanupBuildTempDirectory(tempBuildDir);
     }
     catch (error) {
         spinner.fail(pc.red('打包失败'));

package/dist/commands/create.js

@@ -1,3 +1,4 @@
+import { prepareLocalSkillLifecycle } from '../project-skills/lifecycle.js';
 import { execFileSync, execSync } from 'child_process';
 import inquirer from 'inquirer';
 import fs from 'fs/promises';
@@ -6,8 +7,11 @@ import { fileURLToPath } from 'url';
 import pc from 'picocolors';
 import ora from 'ora';
 import { resolveCreateTemplate, resolveCreateTemplateDir, } from '../scaffold/templates.js';
+import { PLATFORM_SKILL_DIRS } from './platform-skills.generated.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
+/** `@playcraft/skills` 包内 Platform Skill 的目录名（与 Atom Skill 的 `skills/` 区分）。 */
+const PLATFORM_SKILLS_DIRNAME = 'playcraft-skills';
 /** 生成一个本地占位 Project ID（99xxxxxx），后续可通过 playcraft config set 更新为真实 ID */
 function generateMockProjectId() {
     const suffix = Math.floor(Math.random() * 90_000_000) + 10_000_000;
@@ -849,7 +853,7 @@ function extractSkillBodyForCursor(content) {
  * @param cliCommandsDir CLI 命令所在目录（用于解析 skills 包位置）
  * @param configDir 配置目录名（如 '.claude' 或 '.codebuddy'）
  */
-async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir) {
+export async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir) {
     const skillsLinkDir = path.join(targetDir, configDir, 'skills');
     await fs.mkdir(skillsLinkDir, { recursive: true });
     // 以下 Skill 在项目模板中以静态目录形式存在，不创建软连接覆盖它们。
@@ -868,11 +872,12 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
         'playcraft-image-generation',
         'playcraft-audio-generation',
     ]);
-    // 尝试从 CLI 安装包的位置定位 @playcraft/skills/skills 目录
+    // Platform Skill 住在 playcraft-skills/，与 Atom Skill 的 skills/ 是两个目录。
+    // 尝试从 CLI 安装包的位置定位它（monorepo 内或与 CLI 平级安装时可解析）。
     const candidateDirs = [
-        path.resolve(cliCommandsDir, '..', '..', '..', '..', 'skills', 'skills'),
-        path.resolve(cliCommandsDir, '..', '..', '..', 'skills', 'skills'),
-        path.resolve(cliCommandsDir, '..', '..', 'skills', 'skills'),
+        path.resolve(cliCommandsDir, '..', '..', '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
+        path.resolve(cliCommandsDir, '..', '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
+        path.resolve(cliCommandsDir, '..', '..', 'skills', PLATFORM_SKILLS_DIRNAME),
     ];
     let resolvedSkillsDir = null;
     for (const dir of candidateDirs) {
@@ -885,18 +890,24 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
             // 继续下一个候选
         }
     }
-    // 相对路径（指向 npm install 后的 node_modules）始终创建，作为安装后激活的备用
-    const relativeSkillsBase = path.join('..', '..', 'node_modules', '@playcraft', 'skills', 'skills');
+    // 相对路径（指向 npm install 后的 node_modules）作为安装后激活的备用
+    const relativeSkillsBase = path.join('..', '..', 'node_modules', '@playcraft', 'skills', PLATFORM_SKILLS_DIRNAME);
     if (resolvedSkillsDir) {
-        // 能立即解析 → 创建指向绝对路径的软连接，当下即可使用
+        // 能立即解析 → 以真实目录为准创建绝对路径软连接，当下即可使用。
+        // 按「是否含 SKILL.md」判定而非 playcraft- 前缀：sound-effects 无前缀但同样是平台技能。
         const entries = await fs.readdir(resolvedSkillsDir, { withFileTypes: true });
         for (const entry of entries) {
-            if (!entry.name.startsWith('playcraft-') || staticSkills.has(entry.name))
+            if (!entry.isDirectory() || staticSkills.has(entry.name))
                 continue;
-            const linkPath = path.join(skillsLinkDir, entry.name);
             const targetPath = path.join(resolvedSkillsDir, entry.name);
             try {
-                await fs.symlink(targetPath, linkPath, 'dir');
+                await fs.access(path.join(targetPath, 'SKILL.md'));
+            }
+            catch {
+                continue;
+            }
+            try {
+                await fs.symlink(targetPath, path.join(skillsLinkDir, entry.name), 'dir');
             }
             catch {
                 // 已存在则跳过
@@ -904,28 +915,9 @@ async function setupPlatformSkillLinksInner(targetDir, cliCommandsDir, configDir
         }
     }
     else {
-        // 无法立即解析 → 创建指向 node_modules 的相对路径软连接，npm install 后自动激活
-        const knownPlatformTools = [
-            'playcraft-asset-management',
-            'playcraft-audio-generation',
-            'playcraft-build',
-            'playcraft-code-editor',
-            'playcraft-create-remix',
-            'playcraft-deploy',
-            'playcraft-image-generation',
-            'playcraft-image-processing',
-            'playcraft-platform-intro',
-            'playcraft-prefab',
-            'playcraft-project-management',
-            'playcraft-remix-workflow',
-            'playcraft-save',
-            'playcraft-skill-recommender',
-            'playcraft-sprite-generation',
-            'playcraft-sprite-remix',
-            'playcraft-sprite-sheet',
-            'playcraft-3d-flip-sprite',
-        ];
-        for (const name of knownPlatformTools) {
+        // 无法立即解析 → 指向 node_modules 的相对路径软连接，npm install 后自动激活。
+        // 清单由 scripts/generate-platform-skills.mjs 从真实目录生成并由 CI 校验，不要手写。
+        for (const name of PLATFORM_SKILL_DIRS) {
             if (staticSkills.has(name))
                 continue;
             const linkPath = path.join(skillsLinkDir, name);
@@ -1289,6 +1281,7 @@ export async function createCommand(projectName, options) {
                 smokeSpinner.warn(`Harness 自检跳过: ${message}`);
             }
         }
+        await prepareLocalSkillLifecycle(targetDir, 'create');
         const gitSpinner = ora(isWorktreeMode ? '提交项目分支...' : '初始化 Git 仓库...').start();
         try {
             if (isWorktreeMode) {