@playcraft/cli 0.1.84-beta → 0.1.86

package/dist/commands/tools-generation.js

@@ -3,8 +3,8 @@ import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
 import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
-import { resolveImageBackgroundRequirement, validateImageDeliveryOptions, } from '@playcraft/common/prefab';
-import { assertImageAssetOutputPaths, readImageAssetContext, } from '../utils/image-asset-context.js';
+import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
+import { assertImageAssetOutputPaths, readImageAssetContext } from '../utils/image-asset-context.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { isUnsafeImageRetryError } from '../utils/image-generation-retry.js';
 import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, parseImageTargetFieldPath, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
@@ -73,8 +73,7 @@ async function verifyMasterCompositeStripSize(imgBuf, target) {
 }
 export function registerGenerationCommands(tools) {
     // ─── Image Models ────────────────────────────────────────────
-    tools
-        .command('list-image-models')
+    tools.command('list-image-models')
         .description('列出后端已配置的可用生图模型，按模型名分组展示所有 provider（多个 provider 时按优先级自动 fallback）')
         .option('--json', '以 JSON 格式输出（默认为人类可读表格）')
         .action(async (opts) => {
@@ -151,8 +150,7 @@ export function registerGenerationCommands(tools) {
         }
     });
     // ─── Generation ─────────────────────────────────────────────
-    tools
-        .command('generate-image')
+    tools.command('generate-image')
         .description('AI 生成图片（支持多张参考图图生图；gpt-image-2 支持 --count N 批量出图）')
         .requiredOption('--prompt <text>', '图片描述')
         .option('--aspect-ratio <ratio>', '宽高比 (1:1|45:16|16:9|9:16|3:4|4:3|2:3|3:2|21:9)', '1:1')
@@ -176,12 +174,8 @@ export function registerGenerationCommands(tools) {
         .option('--count <n>', '一次 API 调用生成多少张图片（默认 1，最多 10；仅 gpt-image-2 实际支持批量）', (v) => parseInt(v, 10), 1)
         .action(async (opts) => {
         try {
-            const explicitBackground = opts.background === undefined
-                ? opts.removeBackground
-                : opts.background === 'transparent';
-            if (opts.background !== undefined &&
-                opts.removeBackground !== undefined &&
-                opts.removeBackground !== explicitBackground) {
+            const explicitBackground = opts.background === undefined ? opts.removeBackground : opts.background === 'transparent';
+            if (opts.background !== undefined && opts.removeBackground !== undefined && opts.removeBackground !== explicitBackground) {
                 throw new Error('Conflicting background options. Use --background transparent or --background opaque; no image request was sent.');
             }
             opts = { ...opts, removeBackground: explicitBackground };
@@ -190,46 +184,28 @@ export function registerGenerationCommands(tools) {
             }
             const explicitOutputFormat = opts.outputFormat;
             const { dir: outputDir, name: outputName, ext: outputExt } = parse(opts.output);
-            const outputCandidates = [
-                opts.output,
-                ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`)),
-            ];
-            const assetContext = opts.targetAsset
-                ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
-                    referenceImagePaths: opts.referenceImage,
-                    useTargetReference: opts.targetReference,
-                    ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
-                    outputPaths: outputCandidates,
-                    prompt: opts.prompt,
-                    removeBackground: opts.removeBackground,
-                })
-                : undefined;
-            opts = {
-                ...opts,
+            const outputCandidates = [opts.output, ...Array.from({ length: opts.count > 1 ? Math.min(opts.count, 10) : 0 }, (_, i) => join(outputDir, `${outputName}_${i + 1}${outputExt}`))];
+            const assetContext = opts.targetAsset ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
+                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
+                ...(opts.targetFieldPath ? { targetFieldPath: opts.targetFieldPath } : {}),
+                outputPaths: outputCandidates,
+                prompt: opts.prompt, removeBackground: opts.removeBackground,
+            }) : undefined;
+            opts = { ...opts,
                 aspectRatio: assetContext?.aspectRatio ?? opts.aspectRatio,
-                width: assetContext?.width ?? opts.width,
-                height: assetContext?.height ?? opts.height,
-                outputFormat: assetContext?.outputFormatFromSchema
-                    ? assetContext.outputFormat
-                    : (opts.outputFormat ?? assetContext?.outputFormat),
+                width: assetContext?.width ?? opts.width, height: assetContext?.height ?? opts.height,
+                outputFormat: assetContext?.outputFormatFromSchema ? assetContext.outputFormat : opts.outputFormat ?? assetContext?.outputFormat,
                 fitMode: assetContext?.fitMode ?? opts.fitMode,
-                removeBackground: resolveImageBackgroundRequirement({
-                    prompt: opts.prompt,
-                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema
-                        ? assetContext.removeBackground
-                        : undefined,
-                    removeBackground: opts.removeBackground,
-                    fallbackRemoveBackground: assetContext?.removeBackground,
-                }),
+                removeBackground: resolveImageBackgroundRequirement({ prompt: opts.prompt,
+                    schemaRemoveBackground: assetContext?.removeBackgroundFromSchema ? assetContext.removeBackground : undefined,
+                    removeBackground: opts.removeBackground, fallbackRemoveBackground: assetContext?.removeBackground }),
                 paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
                 imageModel: opts.imageModel || assetContext?.imageModelRef,
             };
             const invalidDelivery = validateImageDeliveryOptions(opts);
             if (invalidDelivery)
                 throw new Error(invalidDelivery);
-            const paths = opts.referenceImage?.length
-                ? opts.referenceImage
-                : (assetContext?.referenceImagePaths ?? []);
+            const paths = opts.referenceImage?.length ? opts.referenceImage : assetContext?.referenceImagePaths ?? [];
             if (paths.length > MAX_REFERENCE_IMAGES) {
                 console.error(`Error: Too many reference images: ${paths.length} paths given; maximum is ${MAX_REFERENCE_IMAGES}.`);
                 process.exit(1);
@@ -254,26 +230,14 @@ export function registerGenerationCommands(tools) {
                     width: assetContext?.width ?? opts.width,
                     height: assetContext?.height ?? opts.height,
                     outputFormat: opts.outputFormat,
-                    outputFormatSource: assetContext?.outputFormatFromSchema
-                        ? 'schema'
-                        : explicitOutputFormat
-                            ? 'explicit'
-                            : assetContext
-                                ? 'inferred'
-                                : undefined,
+                    outputFormatSource: assetContext?.outputFormatFromSchema ? 'schema'
+                        : explicitOutputFormat ? 'explicit' : assetContext ? 'inferred' : undefined,
                     fitMode: assetContext?.fitMode ?? opts.fitMode,
                     paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
-                    background: opts.background === undefined
-                        ? undefined
-                        : opts.removeBackground
-                            ? 'transparent'
-                            : 'opaque',
+                    background: opts.background === undefined ? undefined : opts.removeBackground ? 'transparent' : 'opaque',
                     removeBackground: opts.removeBackground,
-                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema
-                        ? 'schema'
-                        : explicitBackground !== undefined
-                            ? 'explicit'
-                            : 'inferred',
+                    backgroundRequirementSource: assetContext?.removeBackgroundFromSchema ? 'schema'
+                        : explicitBackground !== undefined ? 'explicit' : 'inferred',
                     referenceImages,
                     ...(modelRef ? { imageModelRef: modelRef } : {}),
                     ...(imageCount > 1 ? { imageCount } : {}),
@@ -301,8 +265,7 @@ export function registerGenerationCommands(tools) {
                     lines.push('  → Try --image-size 1K to reduce generation time');
                     lines.push('  → Or increase timeout with --timeout <seconds> (current default: 1800s)');
                 }
-                else if (hasReferenceImages &&
-                    (msg.includes('reference') || msg.includes('image input'))) {
+                else if (hasReferenceImages && (msg.includes('reference') || msg.includes('image input'))) {
                     lines.push('');
                     lines.push('Hint: Reference image error — the selected model may not support --reference-image.');
                     lines.push('  → Run: playcraft tools list-image-models');
@@ -350,11 +313,7 @@ export function registerGenerationCommands(tools) {
             }
             // 收集所有待保存图片（第 1 张 + 批量额外图）
             const allImages = [
-                {
-                    imageBase64: result.imageBase64,
-                    mimeType: result.mimeType,
-                    previewUrl: result.previewUrl,
-                },
+                { imageBase64: result.imageBase64, mimeType: result.mimeType, previewUrl: result.previewUrl },
                 ...(result.additionalImages ?? []),
             ];
             const isBatch = allImages.length > 1;
@@ -365,14 +324,12 @@ export function registerGenerationCommands(tools) {
             const savedPaths = [];
             if (result.transparencySource)
                 console.log(`Transparency source: ${result.transparencySource}`);
-            const stripTarget = opts.targetAsset || result.transparentBackground
-                ? null
-                : resolveStripTargetDimensions({
-                    aspectRatio: opts.aspectRatio,
-                    width: opts.width,
-                    height: opts.height,
-                    imageSize: opts.imageSize,
-                });
+            const stripTarget = opts.targetAsset || result.transparentBackground ? null : resolveStripTargetDimensions({
+                aspectRatio: opts.aspectRatio,
+                width: opts.width,
+                height: opts.height,
+                imageSize: opts.imageSize,
+            });
             for (let i = 0; i < allImages.length; i++) {
                 const img = allImages[i];
                 let imgBuf = Buffer.from(img.imageBase64, 'base64');
@@ -390,7 +347,8 @@ export function registerGenerationCommands(tools) {
                     generatedHeight = metaBefore.height;
                     if (metaBefore.width != null &&
                         metaBefore.height != null &&
-                        (metaBefore.width !== stripTarget.width || metaBefore.height !== stripTarget.height)) {
+                        (metaBefore.width !== stripTarget.width ||
+                            metaBefore.height !== stripTarget.height)) {
                         imgBuf = Buffer.from(await letterboxToTarget(imgBuf, stripTarget.width, stripTarget.height));
                         console.log(`↑ Letterbox ${generatedWidth}×${generatedHeight} → ${stripTarget.width}×${stripTarget.height}（等比 + 白边，不拉伸）`);
                     }
@@ -446,11 +404,10 @@ export function registerGenerationCommands(tools) {
                     referenceImageStatus: result.referenceImageStatus ?? null,
                     generatedAt: new Date().toISOString(),
                 };
-                const sidecarPath = `${resolvedPath}.generation.json`;
+                const sidecarPath = resolvedPath.replace(/\.[^.]+$/, '.json');
                 writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
                 await captureGeneratedArtifact(resolvedPath, 'generate-image', {
-                    ...(actualWidth ? { width: actualWidth } : {}),
-                    ...(actualHeight ? { height: actualHeight } : {}),
+                    ...(actualWidth ? { width: actualWidth } : {}), ...(actualHeight ? { height: actualHeight } : {}),
                 });
                 console.log(`  └─ Generation metadata: ${sidecarPath}`);
             }
@@ -474,8 +431,7 @@ export function registerGenerationCommands(tools) {
             handleError(e);
         }
     });
-    tools
-        .command('generate-sfx')
+    tools.command('generate-sfx')
         .description('AI 生成音效（SFX），使用 ElevenLabs Sound Effects')
         .requiredOption('--prompt <text>', '音效描述，仅英文，如 "crisp UI click, short tail, no voice"')
         .option('--duration <seconds>', '时长（秒，0.5-22；省略时由供应商自动决定）', parseFloat)
@@ -495,14 +451,9 @@ export function registerGenerationCommands(tools) {
             const sizeKB = Math.round(buf.length / 1024);
             console.log(`SFX saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
             const sfxSidecar = {
-                type: 'sfx',
-                prompt: opts.prompt,
-                duration: opts.duration ?? null,
-                loop: opts.loop ?? false,
-                provider: result.provider,
-                actualDuration: result.duration,
-                output: opts.output,
-                generatedAt: new Date().toISOString(),
+                type: 'sfx', prompt: opts.prompt, duration: opts.duration ?? null,
+                loop: opts.loop ?? false, provider: result.provider, actualDuration: result.duration,
+                output: opts.output, generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(sfxSidecar, null, 2));
             await captureGeneratedArtifact(opts.output, 'generate-sfx', { duration: result.duration });
@@ -512,8 +463,7 @@ export function registerGenerationCommands(tools) {
             handleError(e);
         }
     });
-    tools
-        .command('generate-bgm')
+    tools.command('generate-bgm')
         .description('AI 生成 BGM（30s 循环），使用 Google Lyria 3')
         .requiredOption('--prompt <text>', 'BGM 描述，如 "轻快休闲游戏配乐"')
         .option('--style <style>', '音乐风格，如 casual / epic / sci-fi / retro')
@@ -534,14 +484,9 @@ export function registerGenerationCommands(tools) {
             const sizeKB = Math.round(buf.length / 1024);
             console.log(`BGM saved to ${opts.output} (${sizeKB}KB, ${result.duration.toFixed(2)}s, provider=${result.provider})`);
             const bgmSidecar = {
-                type: 'bgm',
-                prompt: opts.prompt,
-                style: opts.style ?? null,
-                bpm: opts.bpm ?? null,
-                provider: result.provider,
-                actualDuration: result.duration,
-                output: opts.output,
-                generatedAt: new Date().toISOString(),
+                type: 'bgm', prompt: opts.prompt, style: opts.style ?? null,
+                bpm: opts.bpm ?? null, provider: result.provider, actualDuration: result.duration,
+                output: opts.output, generatedAt: new Date().toISOString(),
             };
             writeFileSync(opts.output.replace(/\.[^.]+$/, '.json'), JSON.stringify(bgmSidecar, null, 2));
             await captureGeneratedArtifact(opts.output, 'generate-bgm', { duration: result.duration });
@@ -572,8 +517,7 @@ export function registerGenerationCommands(tools) {
         }
     });
     // ─── Search Image ──────────────────────────────────────────
-    tools
-        .command('search-image')
+    tools.command('search-image')
         .description('搜索参考图片（Unsplash / Pexels），结果 URL 可直接用于 --reference-image')
         .requiredOption('--query <query>', '搜索关键词（建议英文）')
         .option('--source <source>', '图源：unsplash | pexels | auto（默认 auto）', 'auto')

package/dist/commands/tools-request.js

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+export async function toolRequestCommand(operation, serializedBody) {
+    if (!['generate-image', 'generate-bgm', 'generate-sfx'].includes(operation))
+        throw new Error('Unsupported generation operation');
+    const body = JSON.parse(serializedBody);
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        throw new Error('Generation request must be a JSON object');
+    return new AgentApiClient({
+        configFile: process.env.PLAYCRAFT_SANDBOX_CONFIG_PATH || join(process.cwd(), '.playcraft.json'),
+        operationNamespace: 'opencode',
+    }).post(`/${operation}`, body);
+}
+/** Static sandbox plugins cannot import command-line modules; use this client for transport. */
+export function registerToolRequestCommand(tools) {
+    tools
+        .command('request <operation>', { hidden: true })
+        .description('Send a generation request from JSON on stdin and print its durable result as JSON')
+        .action(async (operation) => {
+        const result = await toolRequestCommand(operation, readFileSync(0, 'utf8'));
+        process.stdout.write(`${JSON.stringify(result)}\n`);
+    });
+}

package/dist/commands/tools-utils.js

@@ -1,5 +1,5 @@
 import { writeFileSync, mkdirSync, readFileSync } from 'fs';
-import { join, parse, resolve } from 'path';
+import { join, parse } from 'path';
 import { tmpdir } from 'os';
 import { InvalidArgumentError } from 'commander';
 export const TMP_DIR = join(tmpdir(), 'playcraft');
@@ -9,12 +9,8 @@ export function parseImageTargetFieldPath(value) {
     try {
         parsed = JSON.parse(value);
     }
-    catch {
-        /* Report the expected shape below. */
-    }
-    if (!Array.isArray(parsed) ||
-        !parsed.length ||
-        parsed.some((key) => typeof key !== 'string' || !key.length)) {
+    catch { /* Report the expected shape below. */ }
+    if (!Array.isArray(parsed) || !parsed.length || parsed.some(key => typeof key !== 'string' || !key.length)) {
         throw new InvalidArgumentError('Expected an array of field names, e.g. ["endUI","playButton"].');
     }
     return parsed;
@@ -78,7 +74,11 @@ export function extensionForImageMime(mimeType) {
  * Detect container from decoded bytes (magic). Prefer this over MIME alone.
  */
 export function sniffImageExtension(buf) {
-    if (buf.length >= 8 && buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) {
+    if (buf.length >= 8 &&
+        buf[0] === 0x89 &&
+        buf[1] === 0x50 &&
+        buf[2] === 0x4e &&
+        buf[3] === 0x47) {
         return '.png';
     }
     if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
@@ -133,14 +133,12 @@ export function mimeTypeForImagePath(filePath) {
         return 'image/png';
     if (ext === 'webp')
         return 'image/webp';
-    if (ext === 'gif')
-        return 'image/gif';
     if (ext === 'jpg' || ext === 'jpeg')
         return 'image/jpeg';
     if (ext === undefined || ext === '') {
         throw new Error(`Reference image path has no file extension: ${filePath}. Use .png, .webp, .jpg, or .jpeg.`);
     }
-    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, jpeg, and gif are allowed.`);
+    throw new Error(`Unsupported reference image extension ".${ext}" in ${filePath}. Only png, webp, jpg, and jpeg are allowed.`);
 }
 async function downloadImageFromUrl(url) {
     let res;
@@ -157,8 +155,7 @@ async function downloadImageFromUrl(url) {
     const contentType = res.headers.get('content-type') ?? '';
     const mimeType = contentType.split(';')[0].trim() || 'image/png';
     const allowed = ['image/png', 'image/jpeg', 'image/webp', 'image/gif'];
-    if (!allowed.some((t) => mimeType.startsWith(t.split('/')[0]) && mimeType.includes('/')) ||
-        !mimeType.startsWith('image/')) {
+    if (!allowed.some((t) => mimeType.startsWith(t.split('/')[0]) && mimeType.includes('/')) || !mimeType.startsWith('image/')) {
         throw new Error(`参考图 URL 返回的 Content-Type 不是图片（${mimeType}）：${url}\n  只支持 PNG / JPG / WEBP / GIF。`);
     }
     const buf = await res.arrayBuffer();
@@ -181,13 +178,18 @@ export async function collectReferenceImagePayloads(paths) {
             }
             else {
                 const mimeType = mimeTypeForImagePath(p);
-                out.push({ base64: readFileSync(resolve(process.cwd(), p)).toString('base64'), mimeType });
+                out.push({ base64: readFileSync(p).toString('base64'), mimeType });
             }
         }
         catch (e) {
             const detail = e instanceof Error ? e.message : String(e);
-            throw new Error(`Could not load reference image "${p}": ${detail}. No image request was sent.`);
+            const code = !isUrl && e && typeof e === 'object' && 'code' in e ? String(e.code) : '';
+            const hint = code ? ` (${code})` : '';
+            console.warn(`Skipping reference image (load failed): ${p}${hint}\n  ${detail}`);
         }
     }
+    if (paths.length > 0 && out.length === 0) {
+        console.warn('All reference images failed to load; continuing with text-only generation.');
+    }
     return out.length > 0 ? out : undefined;
 }

package/dist/commands/tools.js

@@ -6,11 +6,13 @@ import { registerDetectCommand } from './tools-detect.js';
 import { registerVideoReviewCommand } from './tools-video-review.js';
 import { registerImageContextCommand } from './tools-image-context.js';
 import { registerContextCommands } from './tools-context.js';
+import { registerToolRequestCommand } from './tools-request.js';
 export function registerToolsCommands(program) {
     const tools = program
         .command('tools')
         .description('后端 /api/agent/tools；运行 playcraft login 后即可直接使用，也支持 .playcraft.json 或 PLAYCRAFT_SANDBOX_TOKEN 环境变量');
     registerGenerationCommands(tools);
+    registerToolRequestCommand(tools);
     registerImageContextCommand(tools);
     registerProjectCommands(tools);
     registerBatchCommands(tools);

package/dist/utils/agent-api-client.js

@@ -1,10 +1,10 @@
 import { readFileSync, existsSync } from 'fs';
 import { createWriteStream } from 'node:fs';
 import { link, mkdir, stat, unlink } from 'node:fs/promises';
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
-import { dirname, join } from 'path';
+import { dirname, join, resolve } from 'path';
 import { homedir } from 'os';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
@@ -41,20 +41,28 @@ export class AgentApiClient {
     credentialFile;
     playcraftEnv;
     cloudRuntimeCredential;
-    constructor() {
-        const localConfig = AgentApiClient.loadLocalConfig();
-        const globalConfig = loadGlobalConfig();
+    explicitConfig;
+    operationDirectory;
+    constructor(options = {}) {
+        const localConfig = options.configFile
+            ? AgentApiClient.requireLocalConfig(options.configFile)
+            : AgentApiClient.loadLocalConfig();
+        const globalConfig = options.configFile ? {} : loadGlobalConfig();
         // URL: 环境变量 → 本地 .playcraft.json → 全局 login 配置 → 公有云默认地址
-        const apiUrl = (process.env.PLAYCRAFT_API_URL ||
-            localConfig.apiUrl ||
-            globalConfig.backendUrl ||
-            globalConfig.url ||
-            DEFAULT_PLAYCRAFT_CLOUD_BASE).replace(/\/+$/, '');
+        const apiUrl = (options.configFile
+            ? localConfig.apiUrl
+            : process.env.PLAYCRAFT_API_URL ||
+                localConfig.apiUrl ||
+                globalConfig.backendUrl ||
+                globalConfig.url ||
+                DEFAULT_PLAYCRAFT_CLOUD_BASE).replace(/\/+$/, '');
         // Token: 环境变量 → 沙箱全局配置 → 项目配置 → 用户登录配置
-        const token = process.env.PLAYCRAFT_SANDBOX_TOKEN ||
-            localConfig.token ||
-            globalConfig.token ||
-            '';
+        const token = options.configFile
+            ? localConfig.token
+            : process.env.PLAYCRAFT_SANDBOX_TOKEN ||
+                localConfig.token ||
+                globalConfig.token ||
+                '';
         if (!token) {
             throw new Error('Missing PlayCraft API credentials. ' +
                 'Run `playcraft login` to authenticate, or set PLAYCRAFT_SANDBOX_TOKEN / create a .playcraft.json file.');
@@ -62,14 +70,29 @@ export class AgentApiClient {
         this.apiUrl = apiUrl;
         this.token = token;
         this.credentialFile = localConfig.credentialFile;
-        this.playcraftEnv = (process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
+        this.explicitConfig = Boolean(options.configFile);
+        this.playcraftEnv = (options.configFile
+            ? localConfig.env || process.env.PLAYCRAFT_ENV || ''
+            : process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
         this.cloudRuntimeCredential = cloudRuntimeCredentialHint(token, token === localConfig.token ? localConfig : undefined);
+        if (options.operationNamespace) {
+            if (!options.configFile)
+                throw new Error('Operation namespace requires an explicit sandbox configuration');
+            const scope = JSON.stringify([
+                resolve(options.configFile),
+                apiUrl,
+                this.playcraftEnv,
+                localConfig.projectId,
+                localConfig.branch,
+            ]);
+            this.operationDirectory = join(process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests'), options.operationNamespace, createHash('sha256').update(scope).digest('hex'));
+        }
     }
     /** 根据 token 类型构造鉴权 headers */
     authHeaders() {
         let token = this.token;
         // Polling commands can outlive a credential: read the atomically refreshed file per request.
-        if (this.credentialFile && !process.env.PLAYCRAFT_SANDBOX_TOKEN) {
+        if (this.credentialFile && (this.explicitConfig || !process.env.PLAYCRAFT_SANDBOX_TOKEN)) {
             try {
                 token = JSON.parse(readFileSync(this.credentialFile, 'utf8')).token || token;
             }
@@ -96,12 +119,12 @@ export class AgentApiClient {
         const recoverId = options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID;
         const newRequest = options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1';
         const originalReceipt = recoverId !== undefined && !newRequest && isWorkspaceGenerationPath(path)
-            ? findToolOperation(url.pathname, originalBody, recoverId) : undefined;
+            ? findToolOperation(url.pathname, originalBody, recoverId, this.operationDirectory) : undefined;
         let serializedBody = originalReceipt ? originalBody : JSON.stringify(await withGenerationWorkspaceScope(path, body, this.cloudRuntimeCredential));
         if (serializedBody === undefined)
             throw new Error('Tool request body is required');
         if (serializedBody !== originalBody && !newRequest) {
-            const previous = findToolOperation(url.pathname, originalBody, recoverId);
+            const previous = findToolOperation(url.pathname, originalBody, recoverId, this.operationDirectory);
             if (previous && recoverId !== undefined)
                 serializedBody = originalBody;
             else if (previous)
@@ -110,6 +133,7 @@ export class AgentApiClient {
         }
         const operation = beginToolOperation(url.pathname, serializedBody, recoverId, {
             newRequest,
+            directory: this.operationDirectory,
         });
         const unknownOutcome = `Tool request ${operation.requestId}: the outcome is unknown. Rerun the same command to ` +
             `continue this request: it returns the result if the request finished, or finishes it if ` +
@@ -384,6 +408,21 @@ export class AgentApiClient {
         }
         return { apiUrl: '', token: '' };
     }
+    /** A static plugin's slot must never fall back to another workspace or a global login. */
+    static requireLocalConfig(file) {
+        try {
+            const config = JSON.parse(readFileSync(file, 'utf8'));
+            if (typeof config?.apiUrl !== 'string' ||
+                !config.apiUrl.trim() ||
+                typeof config.token !== 'string' ||
+                !config.token.trim())
+                throw new Error('invalid');
+            return { ...config, credentialFile: file };
+        }
+        catch {
+            throw new Error('A valid project .playcraft.json with apiUrl and token is required; no generation request was sent');
+        }
+    }
 }
 /** A failure whose meaning is settled; no recovery hint applies. */
 class ToolRequestError extends Error {

package/dist/utils/image-asset-context.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import JSON5 from 'json5';
 import sharp from 'sharp';
-import { extractAssetFields, getByPath, parseThemeIndexImportPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_INDEX_PATH, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
+import { extractAssetFields, getByPath, resolveAiImageTargetConstraints, resolveImageBackgroundRequirement, THEME_SCHEMA_PATH, themeDataPath, } from '@playcraft/common/prefab';
 function isWithinDirectory(root, file) {
     const relative = path.relative(root, file);
     return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
@@ -38,29 +38,20 @@ export function assertImageAssetOutputPaths(context, outputPaths, projectDir = p
     const root = path.resolve(projectDir);
     const target = canonicalProjectPath(root, context.targetAssetPath);
     const targetStat = statSync(target);
-    const outputRoots = [
-        root,
-        ...allowedOutputRoots.map((outputRoot) => path.resolve(root, outputRoot)),
-    ];
+    const outputRoots = [root, ...allowedOutputRoots.map(outputRoot => path.resolve(root, outputRoot))];
     for (const output of outputPaths) {
         const mapped = output.startsWith('/project/') ? output.slice('/project/'.length) : output;
         const { dir, name } = path.parse(mapped);
         // The response encoding can change the requested extension.
-        const candidates = [
-            mapped,
-            ...['.png', '.webp', '.jpg', '.gif', '.bmp'].map((ext) => path.join(dir, `${name}${ext}`)),
-        ];
+        const candidates = [mapped, ...['.png', '.webp', '.jpg', '.gif', '.bmp'].map(ext => path.join(dir, `${name}${ext}`))];
         for (const candidate of candidates) {
             const candidatePath = path.resolve(root, candidate);
-            const outputRoot = outputRoots.find((allowed) => isWithinDirectory(allowed, candidatePath));
+            const outputRoot = outputRoots.find(allowed => isWithinDirectory(allowed, candidatePath));
             if (!outputRoot)
                 throw new Error(`Image output path is outside the project and allowed output roots: ${output}`);
             const file = canonicalProjectPath(outputRoot, candidatePath);
             const fileStat = existsSync(file) ? statSync(file) : undefined;
-            if (!path.relative(target, file) ||
-                (targetStat.ino !== 0 &&
-                    fileStat?.ino === targetStat.ino &&
-                    fileStat.dev === targetStat.dev)) {
+            if (!path.relative(target, file) || (targetStat.ino !== 0 && fileStat?.ino === targetStat.ino && fileStat.dev === targetStat.dev)) {
                 throw new Error(`Cannot overwrite shared image asset ${context.targetAssetPath}: other fields have different requirements. Use a separate outputPath, then explicitly update the selected field reference; no shared asset was changed.`);
             }
         }
@@ -80,10 +71,8 @@ function projectFile(root, input) {
 /** Read the same per-field constraints used by the asset image dialog. */
 export async function readImageAssetContext(assetPath, projectDir = process.cwd(), options = {}) {
     const targetFieldPath = options.targetFieldPath;
-    if (targetFieldPath !== undefined &&
-        (!Array.isArray(targetFieldPath) ||
-            !targetFieldPath.length ||
-            targetFieldPath.some((key) => typeof key !== 'string' || !key.length))) {
+    if (targetFieldPath !== undefined && (!Array.isArray(targetFieldPath)
+        || !targetFieldPath.length || targetFieldPath.some(key => typeof key !== 'string' || !key.length))) {
         throw new Error('targetFieldPath must be a non-empty array of non-empty field names.');
     }
     const root = path.resolve(projectDir);
@@ -92,36 +81,24 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
     const targetStat = statSync(target);
     const relativeTarget = path.relative(root, target).replace(/\\/g, '/');
     const themeMatch = relativeTarget.match(/^src\/theme\/([^/]+)\/assets\//);
-    const indexFile = path.join(root, THEME_INDEX_PATH);
-    const themeId = themeMatch?.[1] ??
-        (existsSync(indexFile)
-            ? parseThemeIndexImportPath(readFileSync(projectFile(root, THEME_INDEX_PATH), 'utf8'))
-            : null);
     let fields = [];
     const schemaFile = path.join(root, THEME_SCHEMA_PATH);
-    if (themeId && existsSync(schemaFile)) {
+    if (themeMatch && existsSync(schemaFile)) {
         const schema = JSON5.parse(readFileSync(projectFile(root, THEME_SCHEMA_PATH), 'utf8'));
-        const dataPath = themeDataPath(themeId);
+        const dataPath = themeDataPath(themeMatch[1]);
         const data = existsSync(path.join(root, dataPath))
-            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8'))
-            : {};
+            ? JSON5.parse(readFileSync(projectFile(root, dataPath), 'utf8')) : {};
         const themeRoot = path.dirname(path.join(root, dataPath));
-        const matches = extractAssetFields(schema, data).filter((candidate) => {
+        const matches = extractAssetFields(schema, data).filter(candidate => {
             let configured = getByPath(data, candidate.path);
             if (configured === undefined && ['gameplay', 'gamePlay'].includes(candidate.path[0])) {
-                configured = getByPath(data, [
-                    candidate.path[0] === 'gameplay' ? 'gamePlay' : 'gameplay',
-                    ...candidate.path.slice(1),
-                ]);
+                configured = getByPath(data, [candidate.path[0] === 'gameplay' ? 'gamePlay' : 'gameplay', ...candidate.path.slice(1)]);
             }
             const value = typeof configured === 'string' ? configured : candidate.schema.default;
             if (typeof value !== 'string' || /^https?:\/\//i.test(value))
                 return false;
-            const configuredPath = value.startsWith('/project/')
-                ? path.resolve(root, value.slice('/project/'.length))
-                : /^\/?src\//.test(value)
-                    ? path.resolve(root, value.replace(/^\//, ''))
-                    : path.resolve(themeRoot, value);
+            const configuredPath = value.startsWith('/project/') ? path.resolve(root, value.slice('/project/'.length))
+                : path.resolve(themeRoot, value);
             if (configuredPath === target)
                 return true;
             try {
@@ -129,22 +106,19 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
                 if (!path.relative(realTarget, realpathSync(candidateFile)))
                     return true;
                 const candidateStat = statSync(candidateFile);
-                return (targetStat.ino !== 0 &&
-                    candidateStat.ino === targetStat.ino &&
-                    candidateStat.dev === targetStat.dev);
+                return targetStat.ino !== 0 && candidateStat.ino === targetStat.ino && candidateStat.dev === targetStat.dev;
             }
             catch {
                 // Other fields may reference missing files or paths outside this project.
                 return false;
             }
         });
-        if (!matches.length && (themeMatch || targetFieldPath))
+        if (!matches.length)
             throw new Error(`No image schema field matches ${relativeTarget}; check theme.data.json5 before generating.`);
         fields = matches;
-        if (targetFieldPath &&
-            !fields.some((candidate) => candidate.path.length === targetFieldPath.length &&
-                candidate.path.every((key, index) => key === targetFieldPath[index]))) {
-            throw new Error(`targetFieldPath ${JSON.stringify(targetFieldPath)} does not reference ${relativeTarget}. Matching fields: ${matches.map((candidate) => JSON.stringify(candidate.path)).join(', ')}.`);
+        if (targetFieldPath && !fields.some(candidate => candidate.path.length === targetFieldPath.length
+            && candidate.path.every((key, index) => key === targetFieldPath[index]))) {
+            throw new Error(`targetFieldPath ${JSON.stringify(targetFieldPath)} does not reference ${relativeTarget}. Matching fields: ${matches.map(candidate => JSON.stringify(candidate.path)).join(', ')}.`);
         }
     }
     else if (targetFieldPath) {
@@ -157,35 +131,22 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
         const ext = xp?.ext;
         // Schema references follow the dialog's root/theme conventions; explicit tool paths do not change.
         const schemaReferences = Array.isArray(ext?.reference_image)
-            ? ext.reference_image
-                .filter((ref) => typeof ref === 'string' && ref.trim())
-                .map((ref) => {
+            ? ext.reference_image.filter(ref => typeof ref === 'string' && ref.trim()).map(ref => {
                 const raw = ref.trim().replace(/\\/g, '/');
-                const normalized = raw
-                    .replace(/^\.\/+/, '')
-                    .replace(/^\/+/, '')
-                    .replace(/\/{2,}/g, '/');
+                const normalized = raw.replace(/^\.\/+/, '').replace(/^\/+/, '').replace(/\/{2,}/g, '/');
                 if (/^\/?(?:assets|src|public)\//.test(raw) || normalized.startsWith('src/'))
                     return normalized;
-                if (!themeId || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
+                if (!themeMatch || path.isAbsolute(raw) || /^https?:\/\//i.test(raw))
                     return raw;
-                return path.posix.join('src/theme', themeId, normalized);
-            })
-            : [];
-        const references = options.referenceImagePaths?.length
-            ? options.referenceImagePaths
-            : options.useTargetReference === false
-                ? []
-                : schemaReferences.length
-                    ? schemaReferences
-                    : [relativeTarget];
-        const referenceImagePaths = references.map((ref) => /^https?:\/\//i.test(ref)
-            ? ref
+                return path.posix.join('src/theme', themeMatch[1], normalized);
+            }) : [];
+        const references = options.referenceImagePaths?.length ? options.referenceImagePaths
+            : options.useTargetReference === false ? [] : schemaReferences.length ? schemaReferences : [relativeTarget];
+        const referenceImagePaths = references.map(ref => /^https?:\/\//i.test(ref) ? ref
             : path.relative(realpathSync(root), canonicalProjectPath(root, ref)).replace(/\\/g, '/'));
         const hasSchemaBackground = typeof ext?.remove_background === 'boolean';
         if (!hasSchemaBackground && targetHasTransparency === undefined) {
-            targetHasTransparency =
-                !!targetMeta.hasAlpha && (await sharp(target).stats()).channels.at(-1).min < 250;
+            targetHasTransparency = !!targetMeta.hasAlpha && (await sharp(target).stats()).channels.at(-1).min < 250;
         }
         const removeBackground = resolveImageBackgroundRequirement({
             prompt: options.prompt ?? '',
@@ -210,16 +171,12 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
             targetAssetPath: relativeTarget,
             fieldPath: field?.path,
             referenceImagePaths,
-            width: delivery.width,
-            height: delivery.height,
+            width: delivery.width, height: delivery.height,
             aspectRatio: typeof ext?.ratio === 'string' ? ext.ratio : `${delivery.width}:${delivery.height}`,
             outputFormat: (removeBackground && delivery.format === 'jpeg' && !delivery.fromSchemaMimeType
-                ? 'png'
-                : delivery.format),
+                ? 'png' : delivery.format),
             outputFormatFromSchema: delivery.fromSchemaMimeType,
-            fitMode: delivery.fitMode,
-            removeBackground: delivery.removeBackground,
-            paddingColor: delivery.paddingColor,
+            fitMode: delivery.fitMode, removeBackground: delivery.removeBackground, paddingColor: delivery.paddingColor,
             removeBackgroundFromSchema: hasSchemaBackground,
             imageModelRef: typeof ext?.imageModelRef === 'string' ? ext.imageModelRef : undefined,
         };
@@ -231,40 +188,33 @@ export async function readImageAssetContext(assetPath, projectDir = process.cwd(
             contexts.push(await contextForField(field));
         }
         catch (error) {
-            const selected = field?.path.length === targetFieldPath?.length &&
-                field?.path.every((key, index) => key === targetFieldPath?.[index]);
+            const selected = field?.path.length === targetFieldPath?.length
+                && field?.path.every((key, index) => key === targetFieldPath?.[index]);
             if (!targetFieldPath || selected)
                 throw error;
             // Invalid sibling requirements still protect the original shared file.
             unresolvedSharedField = true;
         }
     }
-    const context = targetFieldPath
-        ? contexts.find((candidate) => candidate.fieldPath?.length === targetFieldPath.length &&
-            candidate.fieldPath.every((key, index) => key === targetFieldPath[index]))
-        : contexts[0];
+    const context = targetFieldPath ? contexts.find(candidate => candidate.fieldPath?.length === targetFieldPath.length
+        && candidate.fieldPath.every((key, index) => key === targetFieldPath[index])) : contexts[0];
     const deliveryKey = ({ fieldPath: _fieldPath, outputFormatFromSchema: _formatSource, removeBackgroundFromSchema: _backgroundSource, aspectRatio, ...delivery }) => {
         const ratio = aspectRatio.match(/^\s*(\d+(?:\.\d+)?)\s*:\s*(\d+(?:\.\d+)?)\s*$/);
-        return JSON.stringify({
-            ...delivery,
-            aspectRatio: ratio && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : aspectRatio,
-        });
+        return JSON.stringify({ ...delivery, aspectRatio: ratio && Number(ratio[2]) > 0 ? Number(ratio[1]) / Number(ratio[2]) : aspectRatio });
     };
-    const conflicting = unresolvedSharedField ||
-        contexts.some((candidate) => deliveryKey(candidate) !== deliveryKey(context));
+    const conflicting = unresolvedSharedField || contexts.some(candidate => deliveryKey(candidate) !== deliveryKey(context));
     if (conflicting && !targetFieldPath) {
-        throw new Error(`Multiple image fields use ${relativeTarget} with different references or delivery constraints. Set targetFieldPath (or --target-field-path) to one of: ${fields.map((field) => JSON.stringify(field.path)).join(', ')}.`);
+        throw new Error(`Multiple image fields use ${relativeTarget} with different references or delivery constraints. Set targetFieldPath (or --target-field-path) to one of: ${fields.map(field => JSON.stringify(field.path)).join(', ')}.`);
     }
     if (targetFieldPath) {
         // A separate output retains exactly the selected field's requirements.
-        if (conflicting ||
-            contexts.some((candidate) => (candidate.outputFormatFromSchema && !context.outputFormatFromSchema) ||
-                (candidate.removeBackgroundFromSchema && !context.removeBackgroundFromSchema)))
+        if (conflicting || contexts.some(candidate => (candidate.outputFormatFromSchema && !context.outputFormatFromSchema)
+            || (candidate.removeBackgroundFromSchema && !context.removeBackgroundFromSchema)))
             context.requiresSeparateOutput = true;
     }
     else {
-        context.outputFormatFromSchema = contexts.some((candidate) => candidate.outputFormatFromSchema);
-        context.removeBackgroundFromSchema = contexts.some((candidate) => candidate.removeBackgroundFromSchema);
+        context.outputFormatFromSchema = contexts.some(candidate => candidate.outputFormatFromSchema);
+        context.removeBackgroundFromSchema = contexts.some(candidate => candidate.removeBackgroundFromSchema);
     }
     assertImageAssetOutputPaths(context, options.outputPaths ?? [], root, options.allowedOutputRoots);
     if (context.referenceImagePaths.length > 8)

package/dist/utils/tool-operation-journal.js

@@ -29,7 +29,7 @@ function holderAlive(holder) {
 }
 /** Persist an identity before sending. Store neither credentials nor request/response bodies. */
 export function beginToolOperation(path, serializedBody, recoverId, options = {}) {
-    const directory = process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
+    const directory = options.directory ?? process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
     if (!isAbsolute(directory))
         throw new Error('PLAYCRAFT_TOOL_REQUEST_DIR must be an absolute path');
     mkdirSync(directory, { recursive: true, mode: 0o700 });
@@ -98,8 +98,8 @@ export function beginToolOperation(path, serializedBody, recoverId, options = {}
     };
 }
 /** Read an existing identity without creating an intent or changing its receipt state. */
-export function findToolOperation(path, serializedBody, requestId) {
-    const directory = process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
+export function findToolOperation(path, serializedBody, requestId, directoryOverride) {
+    const directory = directoryOverride ?? process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
     if (!isAbsolute(directory))
         throw new Error('PLAYCRAFT_TOOL_REQUEST_DIR must be an absolute path');
     const inputHash = createHash('sha256').update(serializedBody).digest('hex');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.1.84-beta",
+  "version": "0.1.86",
   "private": false,
   "type": "module",
   "engines": {
@@ -57,8 +57,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "0.1.84-beta",
-    "@playcraft/common": "0.1.84-beta",
+    "@playcraft/build": "0.1.86",
+    "@playcraft/common": "0.1.86",
     "better-sqlite3-pinned": "npm:better-sqlite3@13.0.3",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",