@playcraft/cli 0.1.56-beta → 0.1.58-beta

package/dist/assets/client.js

@@ -120,7 +120,9 @@ export async function downloadAssetTask(client, scope, taskId, output, versionId
     const staging = await mkdtemp(join(dirname(destination), '.playcraft-asset-'));
     let createdDestination = false;
     try {
-        const files = bundle?.files ?? [{ ...entry, path: 'output', fileId: undefined }];
+        const multiple = !bundle && !versionId && Boolean(task.outputs);
+        const directory = Boolean(bundle || multiple);
+        const files = bundle?.files ?? (multiple ? task.outputs.map(file => ({ ...file, path: file.name })) : [{ ...entry, path: 'output', fileId: undefined }]);
         const paths = [];
         for (const file of files) {
             const temporary = resolve(staging, file.path);
@@ -128,11 +130,11 @@ export async function downloadAssetTask(client, scope, taskId, output, versionId
             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 client.download(assetContentRoute({ ...scope, taskId, ...(directory ? { fileId: file.fileId } : {}), ...(versionId ? { versionId } : {}) }), temporary);
             await verifyFile(temporary, file);
-            paths.push(bundle ? join(destination, file.path) : destination);
+            paths.push(directory ? join(destination, file.path) : destination);
         }
-        if (bundle) {
+        if (directory) {
             // mkdir is exclusive; an existing directory or symbolic link cannot be replaced.
             await mkdir(destination);
             createdDestination = true;

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

@@ -46,6 +46,7 @@ export function register3DCommands(tools) {
         .description('Generate a 3D model from a text prompt or input image (uses HunyuanTo3D or configured provider)')
         .option('--prompt <text>', 'Text description of the 3D model to generate')
         .option('--input <path>', 'Input image (local path or URL) for image-to-3D generation')
+        .option('--view-image <view=path>', 'Additional local reference for hy-3d-3.1: left|right|back|top|bottom|left_front|right_front; repeat for multiple views', (value, previous) => [...previous, value], [])
         .requiredOption('--output <path>', 'Output model file path')
         .option('--model <ref>', 'Model ref in provider/model-id format (e.g. tencent-cloud/hy-3d-3.1)')
         .option('--format <fmt>', 'Output format: glb|obj|stl|fbx|usdz (default: glb)', 'glb')
@@ -77,6 +78,20 @@ export function register3DCommands(tools) {
                 payload.enablePBR = true;
             if (opts.polygonType)
                 payload.polygonType = opts.polygonType;
+            if (opts.viewImage.length) {
+                const views = new Set(['left', 'right', 'back', 'top', 'bottom', 'left_front', 'right_front']);
+                const seen = new Set();
+                if (!opts.input || opts.viewImage.length > 7 || opts.model && opts.model !== 'tencent-cloud/hy-3d-3.1')
+                    throw new Error('--view-image requires --input and hy-3d-3.1 (at most 7 unique views)');
+                payload.multiViewImages = opts.viewImage.map((value) => {
+                    const separator = value.indexOf('='), view = value.slice(0, separator), imagePath = value.slice(separator + 1);
+                    if (separator < 1 || !imagePath || !views.has(view) || seen.has(view))
+                        throw new Error('--view-image expects a unique view=path, e.g. back=./back.png');
+                    seen.add(view);
+                    return { view: view,
+                        imageBase64: readFileSync(imagePath).toString('base64'), mimeType: mimeTypeForImagePath(imagePath) };
+                });
+            }
             if (opts.input) {
                 let inputImageBase64;
                 let inputImageMimeType = opts.inputMime;

package/dist/commands/tools-generation.js

@@ -6,6 +6,7 @@ import { captureGeneratedArtifact } from '../workspace-runtime/workspaces/artifa
 import { resolveImageBackgroundRequirement, validateImageDeliveryOptions } from '@playcraft/common/prefab';
 import { assertImageAssetOutputPaths, readImageAssetContext } from '../utils/image-asset-context.js';
 import { AgentApiClient } from '../utils/agent-api-client.js';
+import { isUnsafeImageRetryError } from '../utils/image-generation-retry.js';
 import { MAX_REFERENCE_IMAGES, collectReferenceImagePaths, parseImageTargetFieldPath, collectReferenceImagePayloads, sniffImageExtension, extensionForImageMime, resolveImageOutputPath, handleError, raceWithTimeout, } from './tools-utils.js';
 function isMasterCompositeStripRequest(opts) {
     if (opts.aspectRatio === '45:16')
@@ -285,7 +286,7 @@ export function registerGenerationCommands(tools) {
                     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);
+                    const cannotRetry = isUnsafeImageRetryError(e);
                     if (isTimeout || cannotRetry) {
                         console.error(`Attempt ${attempt + 1} stopped: ${msg}`);
                         break;
@@ -433,7 +434,7 @@ export function registerGenerationCommands(tools) {
     tools.command('generate-sfx')
         .description('AI 生成音效（SFX），使用 ElevenLabs Sound Effects')
         .requiredOption('--prompt <text>', '音效描述，仅英文，如 "crisp UI click, short tail, no voice"')
-        .option('--duration <seconds>', '时长（秒，0.5-30）', parseFloat)
+        .option('--duration <seconds>', '时长（秒，0.5-22；省略时由供应商自动决定）', parseFloat)
         .option('--loop', '生成可循环的音效', false)
         .requiredOption('--output <path>', '保存路径，如 ./assets/audio/click.mp3')
         .action(async (opts) => {

package/dist/commands/workspace.js

@@ -1,3 +1,6 @@
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { diagnoseWorkspaceShares, WORKSPACE_SHARED_PATHS } from '../workspace-runtime/workspaces/workspace-shares.js';
 import { workspaceClone, workspacePush } from '../workspace/transfer-client.js';
 import { workspaceMessage as message } from '../workspace/messages.js';
 import { normalizeWorkspaceTransferError, WorkspaceCliTransferError } from '../workspace/transfer-errors.js';
@@ -22,7 +25,47 @@ export function registerWorkspaceCommands(program) {
             process.exitCode = 1;
         }
     };
+    const doctor = async (options) => {
+        const root = resolve(options.dir ?? process.cwd());
+        const info = await stat(root).catch(() => undefined);
+        if (!info?.isDirectory()) {
+            if (options.json)
+                console.log(JSON.stringify({ ok: false, error: 'workspace_root_missing', root }));
+            else
+                console.error(message('doctorRootMissing'));
+            process.exitCode = 1;
+            return;
+        }
+        const drift = await diagnoseWorkspaceShares(root);
+        if (options.json) {
+            console.log(JSON.stringify({
+                ok: drift.length === 0,
+                root,
+                shared: [...WORKSPACE_SHARED_PATHS],
+                drift: drift.map((entry) => ({
+                    path: entry.path.slice(root.length + 1),
+                    missing: entry.missing,
+                    owner: entry.owner,
+                })),
+            }));
+        }
+        else if (drift.length === 0) {
+            console.log(message('doctorHealthy'));
+        }
+        else {
+            for (const entry of drift) {
+                console.log(`${entry.missing}\t${entry.owner}\t${entry.path.slice(root.length + 1)}`);
+            }
+            console.log(message('doctorSummary', { count: drift.length }));
+            console.log(message('doctorHint'));
+        }
+        process.exitCode = drift.length === 0 ? 0 : 1;
+    };
     const workspace = program.command('workspace').description(message('description'));
+    workspace.command('doctor').description(message('doctor'))
+        .option('--dir <path>', message('doctorTarget'), process.cwd())
+        .option('--json', message('json'))
+        .action(doctor);
     workspace.command('clone').description(message('clone'))
         .requiredOption('--workspace-id <id>', message('workspaceId'))
         .option('--directory <name>', message('directory'), 'basic')

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

@@ -9,8 +9,10 @@ import { homedir } from 'os';
 import { loadGlobalConfig } from '../config.js';
 import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from '../commands/login.js';
 import { AGENT_TOOL_OPERATION_PROTOCOL, AGENT_TOOL_OPERATION_HEADERS, AGENT_TOOL_OPERATION_CAPABILITIES_PATH, } from '@playcraft/common/agent-tools';
-import { beginToolOperation } from './tool-operation-journal.js';
+import { beginToolOperation, findToolOperation } from './tool-operation-journal.js';
 import { businessEndpoint } from './environment-endpoints.js';
+import { cloudRuntimeCredentialHint, isWorkspaceGenerationPath, withGenerationWorkspaceScope } from './generation-workspace-scope.js';
+import { agentGenerationProvenanceHeaders } from './agent-generation-provenance.js';
 import { redactDiagnosticText } from './error-diagnostics.js';
 import { AccountActivationError, parseErrorPayload, pendingAccountActivationError, } from '../auth/account-activation.js';
 /**
@@ -37,6 +39,7 @@ export class AgentApiClient {
     token;
     credentialFile;
     playcraftEnv;
+    cloudRuntimeCredential;
     constructor() {
         const localConfig = AgentApiClient.loadLocalConfig();
         const globalConfig = loadGlobalConfig();
@@ -59,6 +62,7 @@ export class AgentApiClient {
         this.token = token;
         this.credentialFile = localConfig.credentialFile;
         this.playcraftEnv = (process.env.PLAYCRAFT_ENV || localConfig.env || '').trim();
+        this.cloudRuntimeCredential = cloudRuntimeCredentialHint(token, token === localConfig.token ? localConfig : undefined);
     }
     /** 根据 token 类型构造鉴权 headers */
     authHeaders() {
@@ -85,12 +89,26 @@ export class AgentApiClient {
     }
     async post(path, body, options) {
         const url = this.toolsRequestUrl(path);
-        const serializedBody = JSON.stringify(body);
-        if (serializedBody === undefined)
+        const originalBody = JSON.stringify(body);
+        if (originalBody === undefined)
             throw new Error('Tool request body is required');
         const recoverId = options?.requestId ?? process.env.PLAYCRAFT_TOOL_REQUEST_ID;
+        const newRequest = options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1';
+        const originalReceipt = recoverId !== undefined && !newRequest && isWorkspaceGenerationPath(path)
+            ? findToolOperation(url.pathname, originalBody, recoverId) : undefined;
+        let serializedBody = originalReceipt ? originalBody : JSON.stringify(await withGenerationWorkspaceScope(path, body, this.cloudRuntimeCredential));
+        if (serializedBody === undefined)
+            throw new Error('Tool request body is required');
+        if (serializedBody !== originalBody && !newRequest) {
+            const previous = findToolOperation(url.pathname, originalBody, recoverId);
+            if (previous && recoverId !== undefined)
+                serializedBody = originalBody;
+            else if (previous)
+                throw new Error(`Previous unscoped tool request ${previous.requestId} is still unconfirmed. ` +
+                    `Rerun this command with PLAYCRAFT_TOOL_REQUEST_ID=${previous.requestId} to read its settled receipt before starting a workspace generation. No generation was sent.`);
+        }
         const operation = beginToolOperation(url.pathname, serializedBody, recoverId, {
-            newRequest: options?.newRequest ?? process.env.PLAYCRAFT_TOOL_NEW_REQUEST === '1',
+            newRequest,
         });
         const unknownOutcome = `Tool request ${operation.requestId}: the outcome is unknown. Rerun the same command to ` +
             `continue this request: it returns the result if the request finished, or finishes it if ` +
@@ -135,6 +153,7 @@ export class AgentApiClient {
                 headers: {
                     'Content-Type': 'application/json',
                     ...this.authHeaders(),
+                    ...await agentGenerationProvenanceHeaders(path, serializedBody, operation.requestId, this.cloudRuntimeCredential, options?.signal),
                     [AGENT_TOOL_OPERATION_HEADERS.protocol]: AGENT_TOOL_OPERATION_PROTOCOL,
                     [AGENT_TOOL_OPERATION_HEADERS.requestId]: operation.requestId,
                     ...(operation.settledOnly ? { [AGENT_TOOL_OPERATION_HEADERS.settledOnly]: 'true' } : {}),
@@ -163,11 +182,15 @@ export class AgentApiClient {
                 const pending = pendingAccountActivationError(res.status, parseErrorPayload(text));
                 if (pending)
                     throw pending;
+                if (isWorkspaceGenerationPath(path) && res.headers.get('x-playcraft-generation-outcome') === 'failed') {
+                    operation.reject();
+                    throw new ToolRequestError(`API ${res.status}: ${text}`);
+                }
                 const code = errorCode(text);
-                if (res.status === 409 && code === 'business_operation_in_progress')
+                if (res.status === 409 && (code === 'business_operation_in_progress' || code === 'asset_generation_in_progress'))
                     throw new ToolRequestError(`API 409: ${text}\nTool request ${operation.requestId} is still running. Rerun the ` +
                         'same command later to get its result.');
-                if (res.status === 409 && code === 'business_operation_requires_reconciliation')
+                if (res.status === 409 && (code === 'business_operation_requires_reconciliation' || code === 'asset_generation_outcome_unknown'))
                     throw new ToolRequestError(recoverId !== undefined
                         ? // A receipt query never runs the request, even for a tool that can be safely redone.
                             `API 409: ${text}\nTool request ${operation.requestId} has no settled result yet. ` +
@@ -331,8 +354,8 @@ function responseErrorReason(text) {
 }
 function errorCode(text) {
     try {
-        const message = JSON.parse(text).message;
-        return typeof message === 'string' ? message : undefined;
+        const payload = JSON.parse(text);
+        return typeof payload.code === 'string' ? payload.code : typeof payload.message === 'string' ? payload.message : undefined;
     }
     catch {
         return undefined;

package/dist/utils/agent-generation-provenance.js

@@ -0,0 +1,45 @@
+import { hashOperationPayload, AGENT_GENERATION_PROVENANCE_HEADER } from '@playcraft/common/cloud-workspace/runtime';
+import { isWorkspaceGenerationPath } from './generation-workspace-scope.js';
+/** Attribution is optional; only the controlled local broker can attest an execution. */
+export async function agentGenerationProvenanceHeaders(path, body, requestId, cloudRuntime, signal) {
+    if (!cloudRuntime)
+        return {};
+    const normalized = path.startsWith('/') ? path : `/${path}`;
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        return {};
+    }
+    const assetCreate = normalized === '/workspace-assets' && payload?.action === 'create';
+    if (!isWorkspaceGenerationPath(normalized) && !assetCreate)
+        return {};
+    const endpoint = process.env.PLAYCRAFT_AGENT_GENERATION_ENDPOINT;
+    const capability = process.env.PLAYCRAFT_AGENT_GENERATION_CAPABILITY;
+    if (!endpoint || !capability || capability.length > 128 || endpoint.length > 1024)
+        return {};
+    try {
+        const url = new URL(endpoint);
+        if (url.protocol !== 'http:' || url.hostname !== '127.0.0.1' || !url.port || url.username || url.password
+            || url.search || url.hash || !/\/[0-9a-f-]{36}\/[0-9a-f]{32}\/generation-provenance$/.test(url.pathname))
+            return {};
+        const response = await fetch(url, {
+            method: 'POST', redirect: 'error',
+            signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(15_000)]) : AbortSignal.timeout(15_000),
+            headers: { 'content-type': 'application/json', authorization: `Bearer ${capability}` },
+            body: JSON.stringify({ toolPath: `/agent/tools${normalized}`,
+                toolRequestId: assetCreate ? payload.clientRequestId : requestId, payloadHash: hashOperationPayload(payload) }),
+        });
+        if (!response.ok) {
+            await response.body?.cancel();
+            return {};
+        }
+        const value = await response.json();
+        return typeof value.proof === 'string' && value.proof.length > 0 && value.proof.length <= 8192
+            ? { [AGENT_GENERATION_PROVENANCE_HEADER]: value.proof } : {};
+    }
+    catch {
+        return {};
+    }
+}

package/dist/utils/generation-workspace-scope.js

@@ -0,0 +1,50 @@
+import { basename, dirname } from 'node:path';
+import { workspaceDirectoryRegistrationSchema } from '@playcraft/common/cloud-workspace/runtime';
+import { generatedWorkspace } from '../workspace-runtime/workspaces/artifact-receipts.js';
+const generationPaths = new Set([
+    '/generate-image', '/generate-sfx', '/generate-bgm', '/generate-3d',
+    '/generate-texture', '/generate-motion', '/generate-avatar',
+]);
+const workspaceScopeSchema = workspaceDirectoryRegistrationSchema.pick({ workspaceId: true, directoryName: true });
+export function isWorkspaceGenerationPath(path) {
+    return generationPaths.has(path.startsWith('/') ? path : `/${path}`);
+}
+/** Credential metadata only selects routing; the business service still authenticates and authorizes it. */
+export function cloudRuntimeCredentialHint(token, metadata) {
+    if (token.startsWith('playcraft_pat_'))
+        return false;
+    if (metadata?.kind === 'cloud-runtime-cli' || typeof metadata?.runtimeId === 'string' && metadata.runtimeId.trim())
+        return true;
+    const parts = token.split('.');
+    if (parts.length !== 3 || parts[1].length > 16 * 1024)
+        return false;
+    try {
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        return Boolean(payload && typeof payload === 'object' && 'kind' in payload && payload.kind === 'cloud-runtime-cli');
+    }
+    catch {
+        return false;
+    }
+}
+/** Add the current engineering checkout before the durable operation hashes its request. */
+export async function withGenerationWorkspaceScope(path, body, requiresWorkspace, cwd = process.cwd()) {
+    if (!isWorkspaceGenerationPath(path))
+        return body;
+    const context = await generatedWorkspace(cwd);
+    if (!context) {
+        if (requiresWorkspace)
+            throw new Error('Cloud workspace generation requires a current engineering directory; run this command from basic or a remix directory. No generation was sent.');
+        return body;
+    }
+    const parsed = workspaceScopeSchema.safeParse({ workspaceId: context.workspaceId, directoryName: basename(context.root) });
+    if (!parsed.success || basename(dirname(context.root)) !== context.workspaceId)
+        throw new Error('Cloud workspace generation requires a valid basic or remix checkout under its workspace. No generation was sent.');
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        throw new Error('Tool generation request must be an object');
+    if ('workspace' in body && body.workspace !== undefined) {
+        const explicit = workspaceScopeSchema.safeParse(body.workspace);
+        if (!explicit.success || explicit.data.workspaceId !== parsed.data.workspaceId || explicit.data.directoryName !== parsed.data.directoryName)
+            throw new Error('Tool generation workspace does not match the current engineering directory. No generation was sent.');
+    }
+    return { ...body, workspace: parsed.data };
+}

package/dist/utils/image-generation-retry.js

@@ -0,0 +1,7 @@
+/** An uncertain generation may still be billed; retrying must never create another operation. */
+export function isUnsafeImageRetryError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /source_transparency_invalid|output_transparency_invalid|transparency_unsupported|"retryable"\s*:\s*false/.test(message)
+        || /business_operation_(?:in_progress|requires_reconciliation)|asset_generation_(?:in_progress|outcome_unknown)/.test(message)
+        || /outcome is unknown|outcome remains unconfirmed|still unconfirmed|needs reconciliation|no settled result|settled result is not available/i.test(message);
+}

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

@@ -97,9 +97,40 @@ export function beginToolOperation(path, serializedBody, recoverId, options = {}
         release: () => inFlight.delete(requestId),
     };
 }
-function findUnconfirmed(directory, path, inputHash) {
+/** Read an existing identity without creating an intent or changing its receipt state. */
+export function findToolOperation(path, serializedBody, requestId) {
+    const directory = process.env.PLAYCRAFT_TOOL_REQUEST_DIR ?? join(homedir(), '.playcraft', 'tool-requests');
+    if (!isAbsolute(directory))
+        throw new Error('PLAYCRAFT_TOOL_REQUEST_DIR must be an absolute path');
+    const inputHash = createHash('sha256').update(serializedBody).digest('hex');
+    if (requestId === undefined)
+        return findUnconfirmed(directory, path, inputHash, true);
+    if (!isAgentToolRequestId(requestId))
+        return undefined;
+    try {
+        const entry = JSON.parse(readFileSync(join(directory, `${requestId.toLowerCase()}.json`), 'utf8'));
+        if (entry.version === 1 && entry.requestId === requestId.toLowerCase() && entry.path === path && entry.inputHash === inputHash
+            && ['unconfirmed', 'completed', 'rejected'].includes(entry.state))
+            return entry;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return undefined;
+}
+function findUnconfirmed(directory, path, inputHash, includeActive = false) {
     let latest;
-    for (const name of readdirSync(directory)) {
+    let files;
+    try {
+        files = readdirSync(directory);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+    for (const name of files) {
         if (!name.endsWith('.json'))
             continue;
         try {
@@ -112,8 +143,7 @@ function findUnconfirmed(directory, path, inputHash) {
                 (!latest || entry.updatedAt > latest.updatedAt) &&
                 // Still being sent, here or by another live process: that run is not interrupted.
                 // Checked last, so only this command's candidates cost a process probe.
-                !inFlight.has(entry.requestId) &&
-                !holderAlive(entry.holder))
+                (includeActive || !inFlight.has(entry.requestId) && !holderAlive(entry.holder)))
                 latest = entry;
         }
         catch {

package/dist/workspace/messages.js

@@ -31,6 +31,11 @@ const messages = {
         preflight: 'Push preflight passed: {files} files, {bytes} of content. Preparing incremental transfer.',
         upload: 'Uploading incremental transfer: {bytes}.',
         login: 'Log in to the target environment using playcraft login --url',
+        doctor: 'List shared workspace paths that lost development-group access',
+        doctorTarget: 'Workspace checkout to inspect', doctorRootMissing: 'The target directory does not exist.',
+        doctorHealthy: 'All shared workspace paths are readable and writable by the development group.',
+        doctorSummary: '{count} shared path(s) need repair.',
+        doctorHint: 'Reconnect the workspace to repair entries owned by this user; entries owned by the other identity are repaired when that identity writes again.',
     },
     zh: {
         description: '下载云工作区，并将本地提交推送回来', clone: '克隆当前工作区文件，包含尚未提交的修改',
@@ -59,6 +64,11 @@ const messages = {
         preflight: '推送预检查通过：{files} 个文件，内容共 {bytes}。正在准备增量传输。',
         upload: '正在上传增量传输包：{bytes}。',
         login: '请使用 playcraft login --url 登录目标环境',
+        doctor: '列出失去开发组访问权限的共享工作区路径',
+        doctorTarget: '要检查的工作区目录', doctorRootMissing: '目标目录不存在。',
+        doctorHealthy: '所有共享工作区路径都能被开发组读写。',
+        doctorSummary: '有 {count} 个共享路径需要修复。',
+        doctorHint: '重新连接工作区可修复属于当前用户的条目；属于另一个身份的条目会在该身份下次写入时修复。',
     },
 };
 export function workspaceMessage(key, values = {}) {