@playcraft/cli 0.1.23 → 0.1.25

package/dist/cli-root-help.js

@@ -5,6 +5,7 @@ export function getCliTopicsHelpText() {
         '',
         '  本地开发   create, init, start, stop, status, logs, config, sync, fix-ids',
         '  素材       tools generate-*  |  image <子命令>  |  audio <子命令>  |  prefab <子命令>',
+        '  视频理解   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 引导配置启动）',

package/dist/commands/playable.js

@@ -0,0 +1,53 @@
+import { recordPlayable } from '../recording/recorder.js';
+import { RecordingError, recordingMessage as t } from '../recording/messages.js';
+import { dirname, join } from 'node:path';
+import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
+export async function runPlayableRecord(options) {
+    const interrupted = new AbortController();
+    const deadline = new AbortController();
+    const onInterrupt = () => interrupted.abort(new DOMException('Interrupted', 'AbortError'));
+    process.once('SIGINT', onInterrupt);
+    let timer;
+    try {
+        const seconds = options.timeout === undefined ? 1200 : Number(options.timeout);
+        if (!Number.isFinite(seconds) || seconds <= 0 || seconds > 1800)
+            throw new RecordingError('invalidArguments', 64);
+        timer = setTimeout(() => deadline.abort(new DOMException('Timed out', 'TimeoutError')), seconds * 1000);
+        const result = await recordPlayable(options, AbortSignal.any([interrupted.signal, deadline.signal]));
+        const metadata = result.envelope.result;
+        const output = result.envelope.artifacts;
+        if (result.envelope.ok && metadata && output?.candidate) {
+            const artifacts = [metadata.candidate, ...metadata.controls];
+            const paths = [output.candidate, ...(output.controls ?? [])];
+            for (let index = 0; index < artifacts.length; index++) {
+                const artifact = artifacts[index], path = paths[index];
+                if (!path)
+                    continue;
+                const thumbnail = artifact.screenshots?.[0]?.path;
+                await captureGeneratedArtifact(path, 'playable record', {
+                    width: artifact.video.source.width, height: artifact.video.source.height,
+                    duration: artifact.video.source.durationMs / 1000,
+                    ...(thumbnail ? { thumbnailPath: join(dirname(output.metadata), thumbnail) } : {}),
+                });
+            }
+        }
+        process.stdout.write(`${JSON.stringify(result.envelope)}\n`);
+        process.exitCode = result.exitCode;
+    }
+    catch (error) {
+        const code = error instanceof RecordingError ? error.code : 'recordingFailed';
+        process.stdout.write(`${JSON.stringify({ schemaVersion: 'playcraft.video-cli.v1', command: 'playable record', state: 'failed', ok: false, error: { code, message: t(code) } })}\n`);
+        process.exitCode = error instanceof RecordingError ? error.exitCode : 4;
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        process.removeListener('SIGINT', onInterrupt);
+    }
+}
+export function registerPlayableCommands(program) {
+    program.command('playable').description(t('topic')).command('record').description(t('record'))
+        .option('--url <url>', t('url')).option('--scenario <file>', t('scenario')).option('--out <directory>', t('out'))
+        .option('--browser-path <path>', t('browser')).option('--timeout <seconds>', t('timeout'))
+        .action(runPlayableRecord);
+}

package/dist/commands/tools-3d.js

@@ -2,6 +2,7 @@ import { writeFileSync, mkdirSync, readFileSync } from 'fs';
 import { dirname } from 'path';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { mimeTypeForImagePath, handleError } from './tools-utils.js';
+import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
 const AVATAR_TEMPLATES = [
     'basketball', 'badminton', 'pingpong', 'gymnastics', 'pilidance',
     'tennis', 'athletics', 'footballboykicking1', 'footballboykicking2',
@@ -148,6 +149,9 @@ export function register3DCommands(tools) {
                 writeFileSync(opts.savePreview, previewBuf);
                 console.log(`  Preview saved: ${opts.savePreview}`);
             }
+            await captureGeneratedArtifact(opts.output, 'generate-3d', {
+                ...(opts.savePreview && result.previewImageBase64 ? { thumbnailPath: opts.savePreview } : {}),
+            });
             console.log(`\nNext steps:`);
             console.log(`  Inspect:        playcraft 3d info ${opts.output}`);
             console.log(`  Apply texture:  playcraft tools generate-texture --model-url <url> --reference-image <img> --output out.glb`);
@@ -209,6 +213,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'generate-texture');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nTextured model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
             if (result.resultUrl)
@@ -253,6 +258,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'retopology');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nRetopologized model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -289,6 +295,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'uv-unwrap');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nUV-unwrapped model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -324,6 +331,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'convert-3d');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nConverted model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
             console.log(`  Format: ${result.format.toUpperCase()}`);
@@ -359,6 +367,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'generate-3d-parts');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\n3D parts model saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -402,6 +411,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'generate-motion');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\nMotion FBX saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }
@@ -463,6 +473,7 @@ export function register3DCommands(tools) {
             const outDir = dirname(opts.output);
             mkdirSync(outDir, { recursive: true });
             writeFileSync(opts.output, buf);
+            await captureGeneratedArtifact(opts.output, 'generate-avatar');
             const sizeMB = (buf.length / 1024 / 1024).toFixed(2);
             console.log(`\n3D avatar saved: ${opts.output} (${sizeMB}MB, ${elapsed}s)`);
         }

package/dist/commands/tools-batch.js

@@ -1,25 +1,35 @@
 import { readFile } from 'node:fs/promises';
-import { batchCreateSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { batchCreateSchema, batchPromptCreateSchema } from '@playcraft/common/cloud-workspace/runtime';
 import { AgentApiClient } from '../utils/agent-api-client.js';
 import { handleError } from './tools-utils.js';
 const messages = {
     en: {
-        create: 'Create a batch draft; confirm the whole batch in the browser',
+        create: 'Create and automatically run independent Remix variants from one prompt',
         input: 'Path to the batch draft JSON (JavaScript Object Notation, 数据交换格式) file',
-        status: 'Read a batch draft and its generation status',
+        status: 'Read a batch and its generation status',
         id: 'Batch identifier',
-        created: 'Batch draft created',
-        help: '\nDraft shape: { clientRequestId, title, commonGoal, sourceWorkspaceId, engine, variants: [{ variantId, name, changes, preserves }] }\nUse the current workspace identifier as sourceWorkspaceId and a stable clientRequestId for retries. Maximum 10 variants. Confirm the batch in the browser.\n',
-        confirmation: 'Review the baseline and differences, then approve the whole batch in the browser.',
+        created: 'Batch created',
+        prompt: 'The complete batch generation request', workspace: 'Source workspace identifier',
+        directory: 'Source engineering directory; defaults to basic', request: 'Stable batch creation identity for retries',
+        team: 'Team identifier for a standalone workspace', invalidMode: 'Provide either --prompt with --workspace-id or --input, exclusively.',
+        requestRequired: 'Prompt creation requires a stable --client-request-id; reuse it when retrying the same request.',
+        help: '\nUse --prompt with --workspace-id and a stable --client-request-id. The platform plans and generates independent Remix directories while preserving the source. An omitted count defaults to 3; maximum 10. --input also accepts existing structured drafts.\n',
+        confirmation: 'Generation is queued. Read the batch status to track its results.',
+        review: 'This existing draft requires baseline approval in the browser.',
     },
     zh: {
-        create: '创建批次草案；整批确认须在浏览器完成',
+        create: '用一个 prompt 创建并自动生成独立 Remix 变体',
         input: '批次草案 JSON (JavaScript Object Notation, 数据交换格式) 文件路径',
-        status: '查询批次草案及生成状态',
+        status: '查询批次及生成状态',
         id: '批次标识',
-        created: '批次草案已创建',
-        help: '\n草案格式：{ clientRequestId, title, commonGoal, sourceWorkspaceId, engine, variants: [{ variantId, name, changes, preserves }] }\nsourceWorkspaceId 填当前 workspace 标识，重试使用稳定的 clientRequestId。最多 10 个变体，整批在浏览器确认。\n',
-        confirmation: '请在浏览器查看基准和差异清单，然后确认整批。',
+        created: '批次已创建',
+        prompt: '完整的批量生成需求', workspace: '来源 workspace 标识',
+        directory: '来源工程目录，默认 basic', request: '用于重试的稳定批次创建标识',
+        team: '独立工作区所属团队标识', invalidMode: '请选择 --prompt 配合 --workspace-id，或 --input，两种方式不能同时使用。',
+        requestRequired: '使用 prompt 创建时必须提供稳定的 --client-request-id，重试同一请求时复用该标识。',
+        help: '\n使用 --prompt、--workspace-id 和稳定的 --client-request-id。平台自动规划，在副本中生成独立 Remix，保持来源不变。未指定数量默认 3 个，最多 10 个。--input 也兼容现有结构化草案。\n',
+        confirmation: '生成已排队，可查询批次状态追踪各项成果。',
+        review: '此历史草案需要在浏览器确认基准。',
     },
 };
 const language = () => /^zh/i.test(process.env.PLAYCRAFT_LANG ?? process.env.LANG ?? '') ? messages.zh : messages.en;
@@ -27,17 +37,35 @@ export async function createBatchDraft(path, client = new AgentApiClient()) {
     const draft = batchCreateSchema.parse(JSON.parse(await readFile(path, 'utf8')));
     return client.post('/create-batch', draft);
 }
+export async function createPromptBatch(input, client = new AgentApiClient()) {
+    return client.post('/create-batch', batchPromptCreateSchema.parse(input));
+}
 export function registerBatchCommands(tools) {
     const t = language();
     tools.command('create-batch')
         .description(t.create)
-        .requiredOption('--input <path>', t.input)
+        .option('--input <path>', t.input)
+        .option('--prompt <text>', t.prompt)
+        .option('--workspace-id <id>', t.workspace)
+        .option('--source-directory <name>', t.directory, 'basic')
+        .option('--client-request-id <id>', t.request)
+        .option('--team-id <id>', t.team)
         .option('--json', 'JSON (JavaScript Object Notation, 数据交换格式)')
         .addHelpText('after', t.help)
         .action(async (opts) => {
         try {
-            const result = await createBatchDraft(opts.input);
-            console.log(opts.json ? JSON.stringify(result, null, 2) : `${t.created}: ${result.batchId}\n${t.confirmation}`);
+            if (Boolean(opts.input) === Boolean(opts.prompt))
+                throw new Error(t.invalidMode);
+            if (opts.prompt && !opts.workspaceId)
+                throw new Error(t.invalidMode);
+            if (opts.prompt && !opts.clientRequestId)
+                throw new Error(t.requestRequired);
+            const result = opts.input ? await createBatchDraft(opts.input) : await createPromptBatch({
+                clientRequestId: opts.clientRequestId, prompt: opts.prompt,
+                sourceWorkspaceId: opts.workspaceId, sourceDirectoryName: opts.sourceDirectory,
+                ...(opts.teamId ? { teamId: opts.teamId } : {}),
+            });
+            console.log(opts.json ? JSON.stringify(result, null, 2) : `${t.created}: ${result.batchId}\n${result.manifest.autoStart ? t.confirmation : t.review}`);
         }
         catch (error) {
             handleError(error);

package/dist/commands/tools-generation.js

@@ -1,6 +1,7 @@
 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 { 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) {
@@ -330,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]) {
@@ -377,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) {
@@ -409,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/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/index.js

@@ -1,5 +1,5 @@
 #!/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';
@@ -29,16 +29,22 @@ 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') && !process.argv.includes('workspace-runtime')) {
+if (!structuredVideoTopic && !process.argv.includes('upgrade') && !process.argv.includes('workspace-runtime')) {
     checkForUpdates(packageJson);
 }
 // create 命令
@@ -373,4 +379,24 @@ registerPradCommands(program);
 // 3D model utilities (playcraft 3d <command>)
 register3DCommands(program);
 registerWorkspaceRuntimeCommands(program);
-program.parse(process.argv);
+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);