@playcraft/cli 0.1.53-beta → 0.1.55-beta

package/README.md

@@ -210,18 +210,27 @@ echo '{"token":"<sandbox-jwt>","apiUrl":"https://..."}' > .playcraft.json
 
 > 运行 `playcraft login` 后所有子命令均可直接使用。
 
-| 命令                      | 说明                | 示例                                                                  |
-| ------------------------- | ------------------- | --------------------------------------------------------------------- |
-| `tools generate-image`    | AI 生成图片         | `playcraft tools generate-image --prompt "pixel art sky"`             |
-| `tools generate-sfx`      | AI 生成音效         | `playcraft tools generate-sfx --prompt "UI click"`                    |
-| `tools generate-bgm`      | AI 生成 BGM         | `playcraft tools generate-bgm --prompt "casual game music"`           |
-| `tools list-image-models` | 列出可用生图模型    | `playcraft tools list-image-models`                                   |
-| `tools list-remixes`      | 查看 Remix 项目列表 | `playcraft tools list-remixes`                                        |
-| `tools save-to-git`       | 同步沙箱内容到 Git  | `playcraft tools save-to-git --project-id <id> --message "feat: ..."` |
-| `tools build-project`     | 在沙箱中执行构建    | `playcraft tools build-project --project-id <id>`                     |
-| `recommend similar`       | 相似 Creative 推荐  | `playcraft recommend similar --channel Applovin`                      |
-| `recommend improvements`  | Tag 改进建议        | `playcraft recommend improvements --channel Facebook`                 |
-| `recommend random`        | 随机 Tag 组合推荐   | `playcraft recommend random --channel Google`                         |
+| 命令                                                    | 说明                           | 示例                                                                          |
+| ------------------------------------------------------- | ------------------------------ | ----------------------------------------------------------------------------- |
+| `tools generate-image`                                  | AI 生成图片                    | `playcraft tools generate-image --prompt "pixel art sky"`                     |
+| `tools generate-sfx`                                    | AI 生成音效                    | `playcraft tools generate-sfx --prompt "UI click"`                            |
+| `tools generate-bgm`                                    | AI 生成 BGM                    | `playcraft tools generate-bgm --prompt "casual game music"`                   |
+| `tools list-image-models`                               | 列出可用生图模型               | `playcraft tools list-image-models`                                           |
+| `library search`                                        | 检索有权访问的素材库           | `playcraft library search "角色" --type texture --json`                       |
+| `library download`                                      | 下载单文件或完整素材包         | `playcraft library download <assetId> --output ./assets/character`            |
+| `image decompose-layers`                                | 与云工作区一致的图层分离       | `playcraft image decompose-layers --input scene.png --output-dir dist/layers` |
+| `image analyze-nine-patch`                              | 分析九宫格拉伸边距             | `playcraft image analyze-nine-patch --input panel.png --output panel.json`    |
+| `assets generate`                                       | 创建可恢复的工作区素材生成任务 | `playcraft assets generate --request request.json --client-request-id <uuid>` |
+| `assets tasks` / `get` / `wait` / `cancel` / `download` | 管理工作区生成任务和结果       | `playcraft assets download <taskId> --output ./assets/result`                 |
+| `tools list-remixes`                                    | 查看 Remix 项目列表            | `playcraft tools list-remixes`                                                |
+| `tools save-to-git`                                     | 同步沙箱内容到 Git             | `playcraft tools save-to-git --project-id <id> --message "feat: ..."`         |
+| `tools build-project`                                   | 在沙箱中执行构建               | `playcraft tools build-project --project-id <id>`                             |
+
+| `recommend similar` | 相似 Creative 推荐 | `playcraft recommend similar --channel Applovin` |
+| `recommend improvements` | Tag 改进建议 | `playcraft recommend improvements --channel Facebook` |
+| `recommend random` | 随机 Tag 组合推荐 | `playcraft recommend random --channel Google` |
+
+云工作区工具与命令行的完整对应、权限规则和请求示例见[工具覆盖说明](../../docs/cli/cloud-workspace-tool-parity.md)。
 
 ### 业务工具请求恢复
 

package/dist/assets/client.js

@@ -0,0 +1,157 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { link, lstat, mkdir, mkdtemp, open, readFile, rm } from 'node:fs/promises';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { assetGenerationTaskSchema, assetGenerationTaskListSchema, animationEditorStateSchema, workspaceSessionScopeSchema, ASSET_GENERATION_REQUEST_MAX_BYTES, } from '@playcraft/common/cloud-workspace/runtime';
+import { resolveVideoWorkspace } from '../video-replication/client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { assetMessage as t } from './messages.js';
+export async function readAssetRequest(path) {
+    const handle = await open(resolve(resolveSandboxPath(path)), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+    try {
+        const stat = await handle.stat();
+        if (!stat.isFile() || stat.size > ASSET_GENERATION_REQUEST_MAX_BYTES)
+            throw new Error(t('requestTooLarge'));
+        return JSON.parse(await handle.readFile('utf8'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+export async function resolveAssetScope(options, cwd = process.cwd()) {
+    const workspaceId = await resolveVideoWorkspace(options.workspace, cwd);
+    let inferred;
+    for (let cursor = resolve(cwd);; cursor = dirname(cursor)) {
+        try {
+            const value = JSON.parse(await readFile(join(cursor, '.playcraft/workspace-context.json'), 'utf8'));
+            if (value.workspaceId === workspaceId) {
+                // Cloud project roots are <workspaceRoot>/<workspaceId>/<engineeringDirectory>.
+                if (basename(dirname(cursor)) === workspaceId && workspaceSessionScopeSchema.safeParse(basename(cursor)).success)
+                    inferred = basename(cursor);
+                break;
+            }
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (dirname(cursor) === cursor)
+            break;
+    }
+    const parsed = workspaceSessionScopeSchema.safeParse(options.directory ?? inferred ?? 'basic');
+    if (!parsed.success || inferred && options.directory && inferred !== options.directory)
+        throw new Error(t('scopeMismatch'));
+    return { workspaceId, directoryName: parsed.data };
+}
+export function assetContentRoute(input) {
+    const query = new URLSearchParams(Object.entries(input).filter(([, value]) => value !== undefined));
+    return `/workspace-assets/content?${query}`;
+}
+export function scopedAssetTask(scope, value) {
+    const task = assetGenerationTaskSchema.parse(value);
+    if (task.workspaceId !== scope.workspaceId || task.directoryName !== scope.directoryName)
+        throw new Error(t('scopeMismatch'));
+    return task;
+}
+export async function readAssetTasks(client, scope) {
+    const value = assetGenerationTaskListSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'list' }));
+    return { tasks: value.tasks.map(task => scopedAssetTask(scope, task)) };
+}
+export async function readAssetTask(client, scope, taskId) {
+    const task = scopedAssetTask(scope, await client.get('/workspace-assets', { ...scope, action: 'get', taskId }));
+    if (task.taskId !== taskId)
+        throw new Error(t('scopeMismatch'));
+    return task;
+}
+export async function waitForAssetTask(client, scope, taskId, timeoutSeconds = 1800, intervalSeconds = 3) {
+    validateAssetWait(timeoutSeconds, intervalSeconds);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    for (;;) {
+        const task = await readAssetTask(client, scope, taskId);
+        if (!['queued', 'running', 'cancel_requested'].includes(task.status))
+            return task;
+        if (Date.now() >= deadline)
+            throw new Error(t('timeoutReached'));
+        await delay(Math.min(intervalSeconds * 1000, deadline - Date.now()));
+    }
+}
+export function validateAssetWait(timeoutSeconds, intervalSeconds) {
+    if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0 || timeoutSeconds > 86400 || !Number.isFinite(intervalSeconds)
+        || intervalSeconds < 0.1 || intervalSeconds > 60)
+        throw new Error(t('invalidRequest'));
+}
+async function verifyFile(path, file) {
+    const handle = await open(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    try {
+        if ((await handle.stat()).size !== file.size)
+            throw new Error(t('invalidContent'));
+        const hash = createHash('sha256');
+        for await (const chunk of handle.createReadStream({ autoClose: false }))
+            hash.update(chunk);
+        if (hash.digest('hex') !== file.contentHash)
+            throw new Error(t('invalidContent'));
+    }
+    finally {
+        await handle.close();
+    }
+}
+/** Stage and verify every member before publishing the new local output. */
+export async function downloadAssetTask(client, scope, taskId, output, versionId) {
+    const task = await readAssetTask(client, scope, taskId);
+    if (!['awaiting_adoption', 'saved'].includes(task.status) || !task.output)
+        throw new Error(t('outputUnavailable'));
+    let bundle = task.bundle, entry = task.output;
+    if (versionId) {
+        const editor = animationEditorStateSchema.parse(await client.get('/workspace-assets', { ...scope, action: 'animation', taskId }));
+        if (editor.taskId !== taskId)
+            throw new Error(t('scopeMismatch'));
+        const version = editor.versions.find(version => version.versionId === versionId);
+        if (!version)
+            throw new Error(t('outputUnavailable'));
+        bundle = version.bundle;
+        entry = version.output;
+    }
+    const destination = resolve(resolveSandboxPath(output));
+    if (await lstat(destination).then(() => true, error => { if (error.code === 'ENOENT')
+        return false; throw error; }))
+        throw new Error(t('outputExists'));
+    await mkdir(dirname(destination), { recursive: true });
+    const staging = await mkdtemp(join(dirname(destination), '.playcraft-asset-'));
+    let createdDestination = false;
+    try {
+        const files = bundle?.files ?? [{ ...entry, path: 'output', fileId: undefined }];
+        const paths = [];
+        for (const file of files) {
+            const temporary = resolve(staging, file.path);
+            const inside = relative(staging, temporary);
+            if (!inside || inside === '..' || inside.startsWith(`..${sep}`))
+                throw new Error(t('invalidContent'));
+            await mkdir(dirname(temporary), { recursive: true });
+            await client.download(assetContentRoute({ ...scope, taskId, ...(bundle ? { fileId: file.fileId } : {}), ...(versionId ? { versionId } : {}) }), temporary);
+            await verifyFile(temporary, file);
+            paths.push(bundle ? join(destination, file.path) : destination);
+        }
+        if (bundle) {
+            // mkdir is exclusive; an existing directory or symbolic link cannot be replaced.
+            await mkdir(destination);
+            createdDestination = true;
+            for (const file of files) {
+                const path = join(destination, file.path);
+                await mkdir(dirname(path), { recursive: true });
+                await link(join(staging, file.path), path);
+            }
+        }
+        else
+            await link(join(staging, 'output'), destination);
+        return { task, paths };
+    }
+    catch (error) {
+        if (createdDestination)
+            await rm(destination, { recursive: true, force: true });
+        throw error;
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}

package/dist/assets/messages.js

@@ -0,0 +1,48 @@
+const messages = {
+    en: {
+        topic: 'Generate workspace assets and manage the same tasks shown in the workspace',
+        estimate: 'Estimate generation cost without creating a task', generate: 'Create a durable generation task',
+        tasks: 'List generation tasks', get: 'Read a generation task', cancel: 'Request task cancellation',
+        wait: 'Wait for an existing task; never submit another generation', download: 'Download a verified result, preserving all bundle files',
+        saved: 'Confirm workspace adoption using an existing platform write receipt',
+        libraryTargets: 'List authorized destination teams', librarySave: 'Copy a generated result into the asset library',
+        librarySaves: 'List library copy jobs', libraryRetry: 'Resume a library copy job using its existing identity',
+        animation: 'Inspect and edit generated frame animations', animationGet: 'Read the animation draft and versions',
+        animationDraft: 'Update a draft using its expected revision', animationFrame: 'Upload a replacement frame',
+        animationVersion: 'Export an immutable animation version', animationSaved: 'Confirm adoption of an animation version',
+        workspace: 'Workspace identifier; inferred from the current project when omitted', directory: 'Engineering directory; inferred inside the cloud workspace, otherwise basic',
+        request: 'Path to the request document', receipt: 'Path to a platform write receipt with operationId and path',
+        clientRequest: 'Stable request identity; reuse it after an uncertain submission',
+        output: 'Destination file, or new directory for a complete sprite or animation bundle',
+        waitOption: 'Wait for generation to finish', timeout: 'Maximum wait in seconds', interval: 'Polling interval in seconds',
+        version: 'Animation version identifier', saveId: 'Existing library copy job identifier', release: 'Start this library copy without waiting for workspace adoption',
+        json: 'Print structured results', invalidRequest: 'The request document or command arguments are invalid.',
+        scopeMismatch: 'The returned result belongs to another workspace or engineering directory.',
+        outputUnavailable: 'The task has no completed output to download.', outputExists: 'The output already exists. Choose a new destination.',
+        invalidContent: 'Downloaded content does not match the task size or content digest.', failed: 'Asset operation failed',
+        timeoutReached: 'Waiting timed out. Use assets get or assets wait with the same task identifier; generation was not cancelled.',
+        requestTooLarge: 'The request document exceeds the permitted size.',
+    },
+    zh: {
+        topic: '生成工作区素材，管理工作区面板中同一批任务', estimate: '估算生成费用，不创建任务', generate: '创建可恢复的素材生成任务',
+        tasks: '列出素材生成任务', get: '读取生成任务', cancel: '请求取消任务', wait: '等待已有任务，不会重新生成',
+        download: '校验并下载结果，保留素材包全部文件', saved: '用已有平台写入回执确认素材已采纳',
+        libraryTargets: '列出允许写入的团队素材库', librarySave: '将生成结果保存到素材库', librarySaves: '列出素材库保存任务',
+        libraryRetry: '沿用已有标识恢复素材库保存任务', animation: '查看、编辑生成的帧动画', animationGet: '读取动画草稿和版本',
+        animationDraft: '按预期修订号更新动画草稿', animationFrame: '上传替换帧', animationVersion: '导出不可变的动画版本',
+        animationSaved: '确认动画版本已采纳', workspace: '工作区标识；省略时从当前工程推断', directory: '工程目录；云工作区内自动推断，其余情况默认 basic',
+        request: '请求文档路径', receipt: '平台写入回执路径，需包含 operationId 和 path',
+        clientRequest: '稳定请求标识；提交结果不确定时复用同一标识', output: '目标文件路径；精灵图或动画素材包使用新目录',
+        waitOption: '等待生成完成', timeout: '最长等待秒数', interval: '查询间隔秒数', version: '动画版本标识',
+        saveId: '已有素材库保存任务标识', release: '立即执行此素材库保存任务，不再等待工作区采纳', json: '输出结构化结果',
+        invalidRequest: '请求文档或命令参数无效。', scopeMismatch: '返回结果不属于所选工作区或工程目录。',
+        outputUnavailable: '任务尚无可供下载的完整结果。', outputExists: '目标已存在，请选择新的保存位置。',
+        invalidContent: '下载内容与任务记录的大小或内容摘要不一致。', failed: '素材操作失败',
+        timeoutReached: '等待已超时。请使用同一任务标识运行 assets get 或 assets wait，生成任务未取消。',
+        requestTooLarge: '请求文档超过允许大小。',
+    },
+};
+export function assetMessage(key) {
+    const language = process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en';
+    return messages[language.startsWith('zh') ? 'zh' : 'en'][key];
+}

package/dist/cli-root-help.js

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

package/dist/commands/assets.js

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

package/dist/commands/image-layer-messages.js

@@ -0,0 +1,37 @@
+const messages = {
+    en: {
+        decompose: 'Separate an image into a base and editable layers using the cloud workspace pipeline',
+        input: 'Input image path or image address', outputDir: 'Output directory',
+        engine: 'Layer engine: seedream (workspace) or qwen (legacy)', imageModel: 'Image model reference for workspace layer separation',
+        size: 'Workspace layer size: auto, 1K, 1.5K, 2K', prompt: 'Optional layer guidance', team: 'Team used for model configuration',
+        numLayers: 'Legacy Qwen layer count, 2–10', safety: 'Disable the legacy Qwen safety checker', format: 'Legacy Qwen output format',
+        ninePatch: 'Analyze stretchable nine-patch borders with the cloud workspace vision model',
+        output: 'Save the analysis as a file', visionModel: 'Vision model reference',
+        invalidFile: 'Input must be a regular image file of at most {maxBytes} bytes', downloadFailed: 'Image download failed ({status})',
+        tooLarge: 'Input image exceeds {maxBytes} bytes', unsupportedInput: 'Input must be a single image in a supported format',
+        unsupportedOutput: 'Unsupported output image type: {mimeType}', invalidEngine: '--engine must be seedream or qwen',
+        legacyOnly: '--num-layers, --no-safety-checker and --output-format require --engine qwen',
+        workspaceOnly: '--image-model, --size and --team-id require --engine seedream',
+        invalidSize: '--size must be auto, 1K, 1.5K or 2K', invalidCount: '--num-layers must be an integer between 2 and 10',
+        saved: 'Saved separated layers and decompose-layers-meta.json to {outputDir}', failed: 'Image command failed: {message}',
+    },
+    zh: {
+        decompose: '使用云工作区同款管线，将图片分解为底图和可编辑图层',
+        input: '输入图片路径或图片地址', outputDir: '输出目录',
+        engine: '分层引擎：seedream（云工作区）或 qwen（旧版）', imageModel: '云工作区图层分离的图像模型引用',
+        size: '云工作区分层尺寸：auto、1K、1.5K、2K', prompt: '可选图层分离提示词', team: '模型配置所属团队',
+        numLayers: '旧版 Qwen 图层数量，2–10', safety: '关闭旧版 Qwen 安全检测', format: '旧版 Qwen 输出格式',
+        ninePatch: '使用云工作区视觉模型分析点九图可拉伸边界', output: '将分析结果保存到文件', visionModel: '视觉模型引用',
+        invalidFile: '输入必须是大小不超过 {maxBytes} 字节的普通图片文件', downloadFailed: '图片下载失败（{status}）',
+        tooLarge: '输入图片超过 {maxBytes} 字节', unsupportedInput: '输入必须是支持格式的单张图片',
+        unsupportedOutput: '不支持的输出图片类型：{mimeType}', invalidEngine: '--engine 必须为 seedream 或 qwen',
+        legacyOnly: '--num-layers、--no-safety-checker 和 --output-format 需要使用 --engine qwen',
+        workspaceOnly: '--image-model、--size 和 --team-id 需要使用 --engine seedream',
+        invalidSize: '--size 必须为 auto、1K、1.5K 或 2K', invalidCount: '--num-layers 必须为 2 到 10 之间的整数',
+        saved: '已将分离图层与 decompose-layers-meta.json 保存到 {outputDir}', failed: '图片命令执行失败：{message}',
+    },
+};
+export function imageLayerMessage(key, values = {}) {
+    const language = (process.env.PLAYCRAFT_LANGUAGE || process.env.LANG || 'en').startsWith('zh') ? 'zh' : 'en';
+    return messages[language][key].replace(/\{(\w+)\}/g, (match, name) => String(values[name] ?? match));
+}

package/dist/commands/image-layer-tools.js

@@ -0,0 +1,185 @@
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import sharp from 'sharp';
+import { AgentApiClient } from '../utils/agent-api-client.js';
+import { resolveSandboxPath } from '../utils/sandbox-path.js';
+import { imageLayerMessage as t } from './image-layer-messages.js';
+import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifact-receipts.js';
+const MAX_IMAGE_BYTES = 30_000_000;
+const isRemote = (input) => /^https?:\/\//i.test(input);
+function localImageBytes(input, maxBytes) {
+    const filename = resolveSandboxPath(input);
+    const info = statSync(filename);
+    if (!info.isFile() || info.size > maxBytes) {
+        throw new Error(t('invalidFile', { maxBytes }));
+    }
+    return readFileSync(filename);
+}
+async function inputImage(input) {
+    let bytes;
+    if (isRemote(input)) {
+        const response = await fetch(input, { signal: AbortSignal.timeout(60_000) });
+        if (!response.ok || !response.body)
+            throw new Error(t('downloadFailed', { status: response.status }));
+        if (Number(response.headers.get('content-length')) > MAX_IMAGE_BYTES) {
+            await response.body.cancel();
+            throw new Error(t('tooLarge', { maxBytes: MAX_IMAGE_BYTES }));
+        }
+        const reader = response.body.getReader();
+        const chunks = [];
+        let total = 0;
+        try {
+            while (true) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                total += chunk.value.byteLength;
+                if (total > MAX_IMAGE_BYTES)
+                    throw new Error(t('tooLarge', { maxBytes: MAX_IMAGE_BYTES }));
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            await reader.cancel();
+        }
+        bytes = Buffer.concat(chunks);
+    }
+    else {
+        bytes = localImageBytes(input, MAX_IMAGE_BYTES);
+    }
+    const metadata = await sharp(bytes).metadata();
+    const inputMimeTypes = { png: 'image/png', jpeg: 'image/jpeg', webp: 'image/webp' };
+    const mimeType = inputMimeTypes[metadata.format ?? ''];
+    if (!mimeType || (metadata.pages ?? 1) > 1)
+        throw new Error(t('unsupportedInput'));
+    return { imageBase64: bytes.toString('base64'), mimeType };
+}
+function imageExtension(mimeType) {
+    const formats = { 'image/png': 'png', 'image/jpeg': 'jpg', 'image/webp': 'webp' };
+    const extension = formats[mimeType];
+    if (!extension)
+        throw new Error(t('unsupportedOutput', { mimeType }));
+    return extension;
+}
+function saveLayer(outputDir, stem, layer) {
+    const file = `${stem}.${imageExtension(layer.mimeType)}`;
+    writeFileSync(join(outputDir, file), Buffer.from(layer.imageBase64, 'base64'));
+    const { imageBase64: _bytes, ...metadata } = layer;
+    return { ...metadata, file };
+}
+function fail(error) {
+    console.error(t('failed', { message: error instanceof Error ? error.message : String(error) }));
+    process.exit(1);
+}
+export function registerImageLayerTools(image) {
+    image.command('decompose-layers')
+        .description(t('decompose'))
+        .requiredOption('--input <path>', t('input'))
+        .option('--output-dir <dir>', t('outputDir'), './decompose-layers-output')
+        .option('--engine <name>', t('engine'), 'seedream')
+        .option('--image-model <ref>', t('imageModel'))
+        .option('--size <size>', t('size'))
+        .option('--prompt <text>', t('prompt'), '')
+        .option('--team-id <id>', t('team'))
+        .option('--num-layers <n>', t('numLayers'), (value) => Number(value), 4)
+        .option('--no-safety-checker', t('safety'))
+        .option('--output-format <format>', t('format'), 'png')
+        .action(async (opts, command) => {
+        try {
+            const legacyFlags = ['numLayers', 'safetyChecker', 'outputFormat'].some(name => command.getOptionValueSource(name) === 'cli');
+            const explicitEngine = command.getOptionValueSource('engine') === 'cli';
+            const engine = legacyFlags && !explicitEngine ? 'qwen' : opts.engine;
+            if (!['seedream', 'qwen'].includes(engine))
+                throw new Error(t('invalidEngine'));
+            if (engine === 'seedream' && legacyFlags) {
+                throw new Error(t('legacyOnly'));
+            }
+            if (engine === 'qwen' && (opts.imageModel || opts.size || opts.teamId)) {
+                throw new Error(t('workspaceOnly'));
+            }
+            if (opts.size && !['auto', '1K', '1.5K', '2K'].includes(opts.size)) {
+                throw new Error(t('invalidSize'));
+            }
+            if (engine === 'qwen' && (!Number.isInteger(opts.numLayers) || opts.numLayers < 2 || opts.numLayers > 10)) {
+                throw new Error(t('invalidCount'));
+            }
+            const outputDir = resolveSandboxPath(opts.outputDir);
+            const input = opts.input;
+            const startedAt = Date.now();
+            const client = new AgentApiClient();
+            let metadata;
+            const savedImages = [];
+            if (engine === 'seedream') {
+                const result = await client.post('/image/layer-decomposition', {
+                    ...await inputImage(input),
+                    prompt: opts.prompt || undefined,
+                    size: opts.size || 'auto',
+                    imageModelRef: opts.imageModel,
+                    teamId: opts.teamId,
+                });
+                mkdirSync(outputDir, { recursive: true });
+                const base = saveLayer(outputDir, 'base', result.base);
+                const layers = result.layers.map((layer, index) => saveLayer(outputDir, `layer_${String(index).padStart(2, '0')}`, layer));
+                savedImages.push(...[base, ...layers].map(layer => join(outputDir, layer.file)));
+                metadata = { source: input, engine, base, layers, usage: result.usage };
+            }
+            else {
+                const maxBytes = Number.parseInt(process.env.PLAYCRAFT_IMAGE_MAX_INPUT_BYTES || '', 10);
+                const payload = {
+                    ...(isRemote(input) ? { imageUrl: input } : {
+                        imageBase64: localImageBytes(input, maxBytes > 0 ? maxBytes : 512 * 1024 * 1024).toString('base64'),
+                    }),
+                    numLayers: opts.numLayers,
+                    prompt: opts.prompt,
+                    enableSafetyChecker: opts.safetyChecker !== false,
+                    outputFormat: opts.outputFormat,
+                };
+                const result = await client.post('/image-layered/decompose', payload);
+                mkdirSync(outputDir, { recursive: true });
+                const layers = result.layers.map((layer) => {
+                    const file = `layer_${String(layer.index).padStart(2, '0')}.${imageExtension(layer.mimeType)}`;
+                    writeFileSync(join(outputDir, file), Buffer.from(layer.imageBase64, 'base64'));
+                    savedImages.push(join(outputDir, file));
+                    const { imageBase64: _bytes, ...details } = layer;
+                    return { ...details, file };
+                });
+                metadata = { source: input, engine, requestId: result.requestId, numLayers: result.numLayers,
+                    hasNsfwConcepts: result.hasNsfwConcepts, layers };
+            }
+            const elapsed = `${((Date.now() - startedAt) / 1000).toFixed(1)}s`;
+            writeFileSync(join(outputDir, 'decompose-layers-meta.json'), JSON.stringify({ ...metadata, elapsed }, null, 2));
+            for (const imagePath of savedImages)
+                await captureGeneratedArtifact(imagePath, 'decompose-layers');
+            console.log(t('saved', { outputDir }));
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+    image.command('analyze-nine-patch')
+        .description(t('ninePatch'))
+        .requiredOption('--input <path>', t('input'))
+        .option('--output <path>', t('output'))
+        .option('--vision-model <ref>', t('visionModel'))
+        .option('--team-id <id>', t('team'))
+        .action(async (opts) => {
+        try {
+            const input = await inputImage(opts.input);
+            const result = await new AgentApiClient().post('/image/analyze-nine-patch', {
+                imageBase64: input.imageBase64,
+                visionModelRef: opts.visionModel,
+                teamId: opts.teamId,
+            });
+            const json = JSON.stringify(result, null, 2);
+            if (opts.output) {
+                const output = resolveSandboxPath(opts.output);
+                mkdirSync(dirname(output), { recursive: true });
+                writeFileSync(output, json);
+            }
+            console.log(json);
+        }
+        catch (error) {
+            fail(error);
+        }
+    });
+}