@playcraft/cli 0.1.29 → 0.1.30

package/dist/commands/tools-generation.js

@@ -1,8 +1,7 @@
 import { writeFileSync, mkdirSync } from 'fs';
 import { dirname, parse, join } from 'path';
 import sharp from 'sharp';
-import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
-import { readImageAssetContext } from '../utils/image-asset-context.js';
+import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
 function isMasterCompositeStripRequest(opts) {
@@ -152,120 +151,86 @@ export function registerGenerationCommands(tools) {
         .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')
         .requiredOption('--output <path>', '保存路径（--count>1 时自动追加 _1/_2 等后缀）')
-        .option('--target-asset <path>', 'Existing asset to replace; read its schema references and delivery constraints')
-        .option('--no-target-reference', 'Generate without the existing asset reference only when explicitly requested')
-        .option('--output-format <format>', 'Final format: png, webp or jpeg')
-        .option('--fit-mode <mode>', 'Canvas fitting: contain, cover or fill')
-        .option('--padding-color <color>', 'Canvas padding color (transparent by default)')
-        .option('--remove-background', 'Require a verified transparent image')
-        .option('--no-remove-background', 'Keep the generated background')
         .option('--image-size <size>', '图片尺寸 (1K|2K|4K)')
         .option('--width <n>', '精确宽度（像素；MC 横排 5×9:16 推荐 3600 或 4096）', (v) => parseInt(v, 10))
         .option('--height <n>', '精确高度（像素；MC 推荐 1280 或 1455）', (v) => parseInt(v, 10))
         .option('--reference-image <path>', '参考图路径（可重复多次，最多 8 张），支持 PNG/JPG/WEBP', collectReferenceImagePaths, [])
         .option('--image-model <model>', '模型名（如 gpt-image-2）或 provider/model（如 mulerouter/gpt-image-2）。传模型名时后端按优先级自动 fallback；传 provider/model 则直连指定 provider')
-        .option('--retry <n>', '额外重试轮数（默认 0；后端统一限制尝试，透明验证失败和超时不重试）', (v) => parseInt(v, 10), 0)
+        .option('--retry <n>', '全部 provider 都失败时的重试轮数（默认 1；超时不计为可重试错误）', (v) => parseInt(v, 10), 1)
         .option('--timeout <seconds>', '请求超时秒数（默认 1800，即 30 分钟；异步生图模型耗时较长，仅在后端明确报错时提前终止）', (v) => parseInt(v, 10), 1800)
         .option('--count <n>', '一次 API 调用生成多少张图片（默认 1，最多 10；仅 gpt-image-2 实际支持批量）', (v) => parseInt(v, 10), 1)
         .action(async (opts) => {
-        try {
-            const assetContext = opts.targetAsset ? await readImageAssetContext(opts.targetAsset, process.cwd(), {
-                referenceImagePaths: opts.referenceImage, useTargetReference: opts.targetReference,
-                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?.outputFormat ?? opts.outputFormat,
-                fitMode: assetContext?.fitMode ?? opts.fitMode,
-                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 ?? [];
-            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);
-                return;
+        const paths = opts.referenceImage ?? [];
+        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);
+            return;
+        }
+        const hasReferenceImages = paths.length > 0;
+        const attemptGenerate = async (modelRef, attempt) => {
+            const label = modelRef ? `[${modelRef}]` : '[default model]';
+            if (attempt > 0) {
+                console.log(`Retry ${attempt}/${opts.retry} ${label}...`);
             }
-            const hasReferenceImages = paths.length > 0;
-            const attemptGenerate = async (modelRef, attempt) => {
-                const label = modelRef ? `[${modelRef}]` : '[default model]';
-                if (attempt > 0) {
-                    console.log(`Retry ${attempt}/${opts.retry} ${label}...`);
-                }
-                else {
-                    console.log(`Generating image ${label}...`);
-                }
-                const referenceImages = await collectReferenceImagePayloads(paths);
-                const client = new AgentApiClient();
-                const imageCount = Math.min(Math.max(1, opts.count ?? 1), 10);
-                const requestPromise = client.post('/generate-image', {
-                    prompt: opts.prompt,
-                    aspectRatio: assetContext?.aspectRatio ?? opts.aspectRatio,
-                    imageSize: opts.imageSize,
-                    width: assetContext?.width ?? opts.width,
-                    height: assetContext?.height ?? opts.height,
-                    outputFormat: assetContext?.outputFormat ?? opts.outputFormat,
-                    fitMode: assetContext?.fitMode ?? opts.fitMode,
-                    paddingColor: assetContext?.paddingColor ?? opts.paddingColor,
-                    removeBackground: opts.removeBackground,
-                    referenceImages,
-                    ...(modelRef ? { imageModelRef: modelRef } : {}),
-                    ...(imageCount > 1 ? { imageCount } : {}),
-                });
-                return raceWithTimeout(requestPromise, opts.timeout * 1000, `Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`);
-            };
-            const enrichError = (err, modelRef) => {
-                const msg = err instanceof Error ? err.message : String(err);
-                const lines = [`Error: ${msg}`];
-                if (/source_transparency_invalid|output_transparency_invalid|transparency_unsupported/.test(msg)) {
-                    lines.push('Hint: Transparent output was not delivered. Preserve the requested transparency, references and model; use the request id and stage to investigate.');
-                }
-                else if (/API 500\b|Internal server error/.test(msg)) {
-                    lines.push('');
-                    lines.push('Hint: API 500 error — the model may be temporarily unavailable.');
-                    lines.push('  → Inspect the request id and backend diagnostics before another generation attempt.');
-                    if (modelRef?.includes('/') && opts.removeBackground !== true) {
-                        lines.push('  → Or try without provider prefix to auto-fallback providers: --image-model gpt-image-2');
-                    }
-                }
-                else if (msg.includes('timed out')) {
-                    lines.push('');
-                    lines.push('Hint: Request timed out. The backend task may still be running — retries were skipped to avoid creating duplicate tasks.');
-                    lines.push('  → Check the backend/admin panel for task status before re-running');
-                    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'))) {
-                    lines.push('');
-                    lines.push('Hint: Reference image error — the selected model may not support --reference-image.');
-                    lines.push('  → Run: playcraft tools list-image-models');
-                    lines.push('  → Models with CAPABILITY=text+image support --reference-image');
+            else {
+                console.log(`Generating image ${label}...`);
+            }
+            const referenceImages = await collectReferenceImagePayloads(paths);
+            const client = new AgentApiClient();
+            const imageCount = Math.min(Math.max(1, opts.count ?? 1), 10);
+            const requestPromise = client.post('/generate-image', {
+                prompt: opts.prompt,
+                aspectRatio: opts.aspectRatio,
+                imageSize: opts.imageSize,
+                ...(opts.width && opts.height ? { width: opts.width, height: opts.height } : {}),
+                referenceImages,
+                ...(modelRef ? { imageModelRef: modelRef } : {}),
+                ...(imageCount > 1 ? { imageCount } : {}),
+            });
+            return raceWithTimeout(requestPromise, opts.timeout * 1000, `Request timed out after ${opts.timeout}s. The backend task may still be running — check admin panel before re-running.`);
+        };
+        const enrichError = (err, modelRef) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            const lines = [`Error: ${msg}`];
+            if (msg.includes('500') || msg.includes('Internal server error')) {
+                lines.push('');
+                lines.push('Hint: API 500 error — the model may be temporarily unavailable.');
+                lines.push('  → If using a bare model name (e.g. gpt-image-2), all providers failed — try a different model');
+                if (modelRef?.includes('/')) {
+                    lines.push('  → Or try without provider prefix to auto-fallback providers: --image-model gpt-image-2');
                 }
-                return lines.join('\n');
-            };
+            }
+            else if (msg.includes('timed out')) {
+                lines.push('');
+                lines.push('Hint: Request timed out. The backend task may still be running — retries were skipped to avoid creating duplicate tasks.');
+                lines.push('  → Check the backend/admin panel for task status before re-running');
+                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'))) {
+                lines.push('');
+                lines.push('Hint: Reference image error — the selected model may not support --reference-image.');
+                lines.push('  → Run: playcraft tools list-image-models');
+                lines.push('  → Models with CAPABILITY=text+image support --reference-image');
+            }
+            return lines.join('\n');
+        };
+        try {
             let result = null;
             let lastError = null;
             // 重试逻辑：超时不重试（后端任务可能仍在运行，重试会导致重复提交）
-            const maxAttempts = 1 + (opts.retry ?? 0);
+            const maxAttempts = 1 + (opts.retry ?? 1);
             for (let attempt = 0; attempt < maxAttempts; attempt++) {
                 try {
-                    result = await attemptGenerate(opts.imageModel || assetContext?.imageModelRef, attempt);
+                    result = await attemptGenerate(opts.imageModel, attempt);
                     break;
                 }
                 catch (e) {
                     lastError = e;
                     const msg = e instanceof Error ? e.message : String(e);
                     const isTimeout = msg.includes('timed out');
-                    const cannotRetry = /source_transparency_invalid|output_transparency_invalid|transparency_unsupported|"retryable"\s*:\s*false/.test(msg);
-                    if (isTimeout || cannotRetry) {
-                        console.error(`Attempt ${attempt + 1} stopped: ${msg}`);
+                    if (isTimeout) {
+                        console.error(`Attempt ${attempt + 1} timed out — not retrying (backend task may still be running).`);
                         break;
                     }
                     if (attempt < maxAttempts - 1) {
@@ -294,14 +259,12 @@ export function registerGenerationCommands(tools) {
                 ...(result.additionalImages ?? []),
             ];
             const isBatch = allImages.length > 1;
-            const modelPart = result.model ? `model: ${result.model}` : '';
+            const modelPart = opts.imageModel ? `model: ${opts.imageModel}` : '';
             const providerPart = result.provider ? `provider: ${result.provider}` : '';
             const labelParts = [modelPart, providerPart].filter(Boolean);
             const modelLabel = labelParts.length > 0 ? ` (${labelParts.join(', ')})` : '';
             const savedPaths = [];
-            if (result.transparencySource)
-                console.log(`Transparency source: ${result.transparencySource}`);
-            const stripTarget = opts.targetAsset || result.transparentBackground ? null : resolveStripTargetDimensions({
+            const stripTarget = resolveStripTargetDimensions({
                 aspectRatio: opts.aspectRatio,
                 width: opts.width,
                 height: opts.height,
@@ -349,17 +312,8 @@ export function registerGenerationCommands(tools) {
                 savedPaths.push(resolvedPath);
                 const sidecar = {
                     prompt: opts.prompt,
-                    model: result.model ?? null,
-                    requestedModel: opts.imageModel ?? null,
+                    model: opts.imageModel ?? 'default',
                     provider: result.provider ?? null,
-                    transparentBackground: result.transparentBackground ?? null,
-                    transparencySource: result.transparencySource ?? null,
-                    requestId: result.requestId ?? null,
-                    attempts: result.attempts ?? null,
-                    targetAssetPath: assetContext?.targetAssetPath ?? null,
-                    outputFormat: opts.outputFormat ?? null,
-                    fitMode: opts.fitMode ?? null,
-                    paddingColor: opts.paddingColor ?? null,
                     aspectRatio: opts.aspectRatio,
                     imageSize: opts.imageSize ?? null,
                     requestedWidth: opts.width ?? stripTarget?.width ?? null,
@@ -377,6 +331,9 @@ export function registerGenerationCommands(tools) {
                 };
                 const sidecarPath = resolvedPath.replace(/\.[^.]+$/, '.json');
                 writeFileSync(sidecarPath, JSON.stringify(sidecar, null, 2));
+                await captureGeneratedArtifact(resolvedPath, 'generate-image', {
+                    ...(actualWidth ? { width: actualWidth } : {}), ...(actualHeight ? { height: actualHeight } : {}),
+                });
                 console.log(`  └─ Generation metadata: ${sidecarPath}`);
             }
             if (!isBatch && opts.output !== savedPaths[0] && savedPaths[0]) {
@@ -424,6 +381,7 @@ export function registerGenerationCommands(tools) {
                 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 });
             console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
         }
         catch (e) {
@@ -456,6 +414,7 @@ export function registerGenerationCommands(tools) {
                 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 });
             console.log(`  └─ Generation metadata: ${opts.output.replace(/\.[^.]+$/, '.json')}`);
         }
         catch (e) {

package/dist/commands/tools.js

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

package/dist/commands/video.js

@@ -0,0 +1,111 @@
+import { videoAnalysisRunSchema, videoModelCatalogSchema } from '@playcraft/common/agent-tools';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { executeVideoUnderstanding, readVideoRun, requireVideoId, resolveVideoWorkspace, videoTimeout, } from '../video-replication/client.js';
+import { materializeVideoEvidence } from '../video-replication/evidence.js';
+import { probeVideo } from '../video-replication/media.js';
+import { VideoCliError, videoMessage as t } from '../video-replication/messages.js';
+import { comparisonMessage as c } from '../video-replication/comparison-messages.js';
+import { executeVideoComparison, readComparisonRun, comparisonRunResult } from '../video-replication/comparison.js';
+import { materializeComparisonEvidence } from '../video-replication/comparison-evidence.js';
+/** One final structured stdout record; progress and diagnostics stay on stderr. */
+export async function runVideoCliAction(command, options, action) {
+    const interrupt = new AbortController();
+    const onInterrupt = () => interrupt.abort(new DOMException('Interrupted', 'AbortError'));
+    process.once('SIGINT', onInterrupt);
+    let timer;
+    const deadline = new AbortController();
+    try {
+        timer = setTimeout(() => deadline.abort(new DOMException('Timed out', 'TimeoutError')), videoTimeout(options));
+        const result = await action(AbortSignal.any([interrupt.signal, deadline.signal]));
+        process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
+        process.exitCode = result.exitCode;
+    }
+    catch (error) {
+        const key = error instanceof VideoCliError ? error.code : interrupt.signal.aborted ? 'interrupted' : deadline.signal.aborted ? 'timeoutReached' : 'failed';
+        const envelope = {
+            schemaVersion: 'playcraft.video-cli.v1', command, state: interrupt.signal.aborted || deadline.signal.aborted ? 'uncertain' : 'failed', ok: false,
+            error: { code: key, message: t(key) },
+        };
+        process.stdout.write(`${JSON.stringify(envelope)}\n`);
+        process.exitCode = error instanceof VideoCliError ? error.exitCode : interrupt.signal.aborted ? 130 : deadline.signal.aborted ? 75 : 4;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        process.removeListener('SIGINT', onInterrupt);
+    }
+}
+function shared(command) {
+    return command.option('--workspace <id>', t('workspace')).option('--timeout <seconds>', t('timeout'));
+}
+export function registerVideoCommands(program) {
+    const video = program.command('video').description(t('topic'));
+    shared(video.command('models').description(t('models')))
+        .option('--json', t('json'))
+        .action((options) => runVideoCliAction('video models', options, async (signal) => {
+        const workspaceId = await resolveVideoWorkspace(options.workspace);
+        const catalog = videoModelCatalogSchema.parse(await new AgentApiClient().get('/video-models', { workspaceId }, { signal }));
+        return { exitCode: 0, envelope: { schemaVersion: 'playcraft.video-cli.v1', command: 'video models', state: 'completed', ok: true, result: catalog } };
+    }));
+    shared(video.command('understand').description(t('understand')))
+        .option('--video <path>', t('video')).option('--question <text>', t('question'))
+        .option('--context <path>', t('context')).option('--processing <mode>', t('processing'))
+        .option('--fps <number>', t('fps')).option('--clip <start:end>', t('clip'))
+        .option('--model-config <id>', t('model')).option('--out <directory>', t('out'))
+        .option('--resume <runId>', t('resume'))
+        .action((options) => runVideoCliAction('video understand', options, signal => executeVideoUnderstanding(options, signal, {
+        client: new AgentApiClient(), probe: probeVideo, materialize: materializeVideoEvidence,
+        progress: key => process.stderr.write(`[video] ${t(key)}\n`),
+    })));
+    shared(video.command('compare').description(c('compare')))
+        .option('--reference <path>', c('reference')).option('--analysis <path>', c('analysis'))
+        .option('--candidate <path>', c('candidate')).option('--recording <path>', c('recording'))
+        .option('--policy <path>', c('policy')).option('--processing <mode>', c('processing'))
+        .option('--fps <number>', t('fps')).option('--model-config <id>', t('model'))
+        .option('--out <directory>', t('out')).option('--resume <runId>', t('resume'))
+        .action((options) => runVideoCliAction('video compare', options, signal => executeVideoComparison(options, signal, {
+        client: new AgentApiClient(), probe: probeVideo, materialize: materializeComparisonEvidence,
+        progress: key => process.stderr.write(`[video] ${t(key)}\n`),
+    })));
+    const jobs = video.command('jobs').description(t('jobs'));
+    shared(jobs.command('get <runId>').description(t('get')))
+        .option('--kind <kind>', c('kind'))
+        .action((runId, options) => runVideoCliAction('video jobs get', options, async (signal) => {
+        const workspaceId = await resolveVideoWorkspace(options.workspace);
+        if (options.kind !== undefined && !['understanding', 'comparison'].includes(options.kind))
+            throw new VideoCliError('invalidArguments', 64);
+        if (options.kind === 'comparison') {
+            const run = await readComparisonRun(new AgentApiClient(), requireVideoId(runId), workspaceId, signal);
+            return comparisonRunResult('video jobs get', run);
+        }
+        const run = await readVideoRun(new AgentApiClient(), requireVideoId(runId), workspaceId, signal);
+        return { exitCode: run.state === 'uncertain' ? 75 : run.state === 'failed' || run.state === 'cancelled' ? 4 : 0, envelope: {
+                schemaVersion: 'playcraft.video-cli.v1', command: 'video jobs get', runId: run.runId, state: run.state,
+                ok: !['failed', 'uncertain', 'cancelled'].includes(run.state), result: run,
+            } };
+    }));
+    shared(jobs.command('cancel <runId>').description(t('cancel')))
+        .option('--kind <kind>', c('kind'))
+        .action((identifier, options) => runVideoCliAction('video jobs cancel', options, async (signal) => {
+        const workspaceId = await resolveVideoWorkspace(options.workspace);
+        const runId = requireVideoId(identifier);
+        if (options.kind !== undefined && !['understanding', 'comparison'].includes(options.kind))
+            throw new VideoCliError('invalidArguments', 64);
+        if (options.kind === 'comparison') {
+            const run = await readComparisonRun(new AgentApiClient(), runId, workspaceId, signal, true);
+            const confirmed = run.state === 'cancelled';
+            return { exitCode: confirmed ? 0 : 75, envelope: {
+                    schemaVersion: 'playcraft.video-cli.v1', command: 'video jobs cancel', runId, state: run.state,
+                    ok: confirmed, result: { ...run, cancellationConfirmed: confirmed },
+                } };
+        }
+        const run = videoAnalysisRunSchema.parse(await new AgentApiClient().post(`/video-analysis/${runId}/cancel`, { workspaceId, runId }, { signal }));
+        if (run.runId !== runId || run.workspaceId !== workspaceId)
+            throw new VideoCliError('invalidResult');
+        const confirmed = run.state === 'cancelled';
+        return { exitCode: confirmed ? 0 : 75, envelope: {
+                schemaVersion: 'playcraft.video-cli.v1', command: 'video jobs cancel', runId, state: run.state,
+                ok: confirmed, result: { ...run, cancellationConfirmed: confirmed },
+            } };
+    }));
+}

package/dist/commands/workspace-runtime.js

@@ -0,0 +1,54 @@
+import { readFile } from 'node:fs/promises';
+import { INCOMPATIBLE_EXIT_CODE, parseSandboxRuntimeConfig, } from '@playcraft/common/cloud-workspace/runtime';
+import { startWorkspaceRuntime } from '../workspace-runtime/serve.js';
+export async function runWorkspaceRuntimeServe(configPath) {
+    process.env.PLAYCRAFT_SKIP_UPDATE_CHECK = '1';
+    let config;
+    try {
+        config = parseSandboxRuntimeConfig(JSON.parse(await readFile(configPath, 'utf8')));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        console.error(`workspace-runtime config invalid: ${message}`);
+        process.exitCode = INCOMPATIBLE_EXIT_CODE;
+        return;
+    }
+    try {
+        const runtime = await startWorkspaceRuntime(config, { configPath });
+        console.log(JSON.stringify({
+            status: 'listening',
+            url: runtime.url,
+            phase: 'awaiting_native',
+            protocolMajor: runtime.config.protocolMajor,
+            protocolMinor: runtime.config.protocolMinor,
+        }));
+        await new Promise((resolve) => {
+            const stop = () => {
+                void runtime.close().finally(resolve);
+            };
+            process.once('SIGINT', stop);
+            process.once('SIGTERM', stop);
+        });
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'protocol_incompatible' || code === 'duplicate_instance') {
+            console.error(error instanceof Error ? error.message : code);
+            process.exitCode = INCOMPATIBLE_EXIT_CODE;
+            return;
+        }
+        throw error;
+    }
+}
+export function registerWorkspaceRuntimeCommands(program) {
+    const workspaceRuntime = program
+        .command('workspace-runtime')
+        .description('沙箱内 Sandbox Agent Server（Cloud Workspace 常驻运行入口）');
+    workspaceRuntime
+        .command('serve')
+        .description('前台常驻：读取 Runtime Server 下发的配置，不启动本地 backend 或旧同步')
+        .requiredOption('--config <path>', 'Runtime 引导配置 JSON')
+        .action(async (options) => {
+        await runWorkspaceRuntimeServe(options.config);
+    });
+}

package/dist/config.js

@@ -2,7 +2,8 @@ import { cosmiconfig } from 'cosmiconfig';
 import { z } from 'zod';
 import path from 'path';
 import { homedir } from 'os';
-import { mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { chmodSync, mkdirSync, renameSync, rmSync, writeFileSync, readFileSync } from 'fs';
+import { randomUUID } from 'node:crypto';
 import 'dotenv/config';
 export const ConfigSchema = z.object({
     projectId: z.string().optional(),
@@ -18,6 +19,33 @@ const explorer = cosmiconfig('playcraft', {
 });
 const GLOBAL_CONFIG_DIR = path.join(homedir(), '.playcraft');
 const GLOBAL_CONFIG_FILE = path.join(GLOBAL_CONFIG_DIR, 'config.json');
+export function normalizeEnvironmentBaseUrl(raw) {
+    try {
+        const url = new URL(raw);
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password)
+            return undefined;
+        url.hash = '';
+        url.search = '';
+        url.pathname = url.pathname.replace(/\/+$/, '').replace(/\/api$/, '');
+        return url.toString().replace(/\/+$/, '');
+    }
+    catch {
+        return undefined;
+    }
+}
+export function readEnvironmentProfile(config, baseUrl) {
+    const key = normalizeEnvironmentBaseUrl(baseUrl);
+    const profiles = config.environmentProfiles;
+    if (!key || !profiles || typeof profiles !== 'object' || Array.isArray(profiles))
+        return undefined;
+    const profile = profiles[key];
+    if (!profile || typeof profile !== 'object' || Array.isArray(profile))
+        return undefined;
+    const value = profile;
+    if (typeof value.token !== 'string' || !value.token || normalizeEnvironmentBaseUrl(value.backendUrl) !== key)
+        return undefined;
+    return value;
+}
 export function loadGlobalConfig() {
     try {
         const content = readFileSync(GLOBAL_CONFIG_FILE, 'utf-8');
@@ -28,7 +56,8 @@ export function loadGlobalConfig() {
     }
 }
 export function saveGlobalConfig(partial) {
-    mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true });
+    mkdirSync(GLOBAL_CONFIG_DIR, { recursive: true, mode: 0o700 });
+    chmodSync(GLOBAL_CONFIG_DIR, 0o700);
     let existing = {};
     try {
         existing = JSON.parse(readFileSync(GLOBAL_CONFIG_FILE, 'utf-8'));
@@ -37,7 +66,25 @@ export function saveGlobalConfig(partial) {
         // ignore
     }
     const merged = { ...existing, ...partial };
-    writeFileSync(GLOBAL_CONFIG_FILE, JSON.stringify(merged, null, 2), 'utf-8');
+    const temporary = path.join(GLOBAL_CONFIG_DIR, `.config-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, JSON.stringify(merged, null, 2), { encoding: 'utf-8', flag: 'wx', mode: 0o600 });
+        renameSync(temporary, GLOBAL_CONFIG_FILE);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+export function saveEnvironmentProfile(baseUrl, profile) {
+    const key = normalizeEnvironmentBaseUrl(baseUrl);
+    if (!key)
+        throw new Error('Invalid environment address');
+    const current = loadGlobalConfig();
+    const profiles = current.environmentProfiles && typeof current.environmentProfiles === 'object'
+        && !Array.isArray(current.environmentProfiles) ? current.environmentProfiles : {};
+    saveGlobalConfig({ environmentProfiles: { ...profiles,
+            [key]: { ...profile, backendUrl: key, updatedAt: new Date().toISOString() } },
+        token: profile.token, url: key, backendUrl: key });
 }
 export async function loadConfig(cliOptions) {
     const result = await explorer.search(cliOptions.dir || process.cwd());
@@ -46,12 +93,20 @@ export async function loadConfig(cliOptions) {
         ? (fileConfig.agent || {})
         : fileConfig;
     const globalConfig = loadGlobalConfig();
+    const explicitTarget = cliOptions.url || process.env.PLAYCRAFT_URL || agentConfig.url;
+    const targetUrl = explicitTarget || globalConfig.url;
+    const profile = typeof targetUrl === 'string' ? readEnvironmentProfile(globalConfig, targetUrl) : undefined;
+    const legacyTarget = typeof globalConfig.backendUrl === 'string' ? globalConfig.backendUrl
+        : typeof globalConfig.url === 'string' ? globalConfig.url : undefined;
+    const legacyToken = !explicitTarget || (legacyTarget && normalizeEnvironmentBaseUrl(String(targetUrl)) === normalizeEnvironmentBaseUrl(legacyTarget))
+        ? globalConfig.token : undefined;
     const config = ConfigSchema.parse({
         ...globalConfig,
         ...agentConfig,
         ...cliOptions,
         projectId: cliOptions.projectId || process.env.PLAYCRAFT_PROJECT_ID || agentConfig.projectId || globalConfig.projectId,
-        token: cliOptions.token || process.env.PLAYCRAFT_TOKEN || agentConfig.token || globalConfig.token,
+        url: targetUrl,
+        token: cliOptions.token || process.env.PLAYCRAFT_TOKEN || agentConfig.token || profile?.token || legacyToken,
         port: cliOptions.port || (process.env.PLAYCRAFT_PORT ? parseInt(process.env.PLAYCRAFT_PORT) : undefined) || agentConfig.port || globalConfig.port,
         mode: cliOptions.mode || process.env.PLAYCRAFT_MODE || agentConfig.mode || globalConfig.mode,
         skillsDir: cliOptions.skillsDir || process.env.AGENT_SKILLS_DIR || agentConfig.skillsDir || globalConfig.skillsDir,

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { Command } from 'commander';
+import { Command, CommanderError } from 'commander';
+import { accountActivationMessage } from './auth/messages.js';
 import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
@@ -27,16 +28,23 @@ import { registerLevelsCommands } from './commands/levels.js';
 import { registerPatternsCommands } from './commands/patterns.js';
 import { registerPradCommands } from './commands/prad.js';
 import { register3DCommands } from './commands/3d.js';
+import { registerWorkspaceRuntimeCommands } from './commands/workspace-runtime.js';
+import { registerVideoCommands } from './commands/video.js';
+import { registerPlayableCommands } from './commands/playable.js';
+import { videoMessage } from './video-replication/messages.js';
 import { CLI_ROOT_DESCRIPTION, getCliTopicsHelpText, registerRootProgramHelp, } from './cli-root-help.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJson = JSON.parse(readFileSync(join(__dirname, '..', 'package.json'), 'utf-8'));
 const program = new Command();
+const structuredVideoTopic = ['video', 'playable'].includes(process.argv[2] ?? '');
+if (structuredVideoTopic)
+    program.exitOverride();
 program.name('playcraft').description(CLI_ROOT_DESCRIPTION).version(packageJson.version);
 registerRootProgramHelp(program);
 // 版本检查（非阻塞，后台执行）
 // 只在非 upgrade 命令时检查，避免重复提示
-if (!process.argv.includes('upgrade')) {
+if (!structuredVideoTopic && !process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
     checkForUpdates(packageJson);
 }
 // create 命令
@@ -65,6 +73,8 @@ program
     .command('login')
     .description('登录 PlayCraft 账号并获取 CLI token')
     .option('--url <url>', 'Portal / API 基址（默认 https://playcraft.aix.intlgame.com，可用环境变量 PLAYCRAFT_URL 覆盖）')
+    .option('--activate', accountActivationMessage('activateOption'))
+    .option('--token <token>', accountActivationMessage('tokenOption'))
     .action(async (options) => {
     const { loginCommand } = await import('./commands/login.js');
     await loginCommand(options);
@@ -368,4 +378,25 @@ registerPatternsCommands(program);
 registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
-program.parse(process.argv);
+registerWorkspaceRuntimeCommands(program);
+registerVideoCommands(program);
+registerPlayableCommands(program);
+if (structuredVideoTopic) {
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        if (!(error instanceof CommanderError))
+            throw error;
+        if (error.exitCode === 0)
+            process.exitCode = 0;
+        else {
+            const command = [process.argv[2], process.argv[3]?.startsWith('-') ? undefined : process.argv[3]].filter(Boolean).join(' ');
+            process.stdout.write(`${JSON.stringify({ schemaVersion: 'playcraft.video-cli.v1', command, state: 'failed', ok: false,
+                error: { code: 'invalidArguments', message: videoMessage('invalidArguments') } })}\n`);
+            process.exitCode = 64;
+        }
+    }
+}
+else
+    program.parse(process.argv);