@playcraft/cli 0.0.51 → 0.0.53

package/REMIX.md

@@ -486,11 +486,14 @@ playcraft remix run
 交互顺序：
 
 1. 选择团队。
-2. 选择模板。
-3. 输入 Remix 名称。
-4. 创建真实 Remix 分支。
-5. 输入需求描述。
-6. 有需求时启动沙箱并运行 Agent；直接回车或输入 `exit` 时只创建 Remix。
+2. 加载模板来源：有模板页权限时显示团队模板和当前团队的系统推荐；无权限时只显示当前团队的系统推荐。系统推荐与 Remix 画廊一致，由推荐 Prompt 模板和推荐 Remix 两部分组成。
+3. 选择模板；输入 `back` 可返回团队列表。
+4. 选择团队模板后加载它的分支，可选择 `main` 或已有 Remix；选择系统推荐时直接使用该推荐配置的基础模板和分支。输入 `back` 可返回模板列表。
+5. CLI 按平台规则自动生成 Remix 名称并创建真实 Remix 分支。
+6. 输入需求描述。
+7. 有需求时启动沙箱并运行 Agent；直接回车或输入 `exit` 时只创建 Remix。
+
+模板权限与网页 `/projects` 保持一致，仅系统管理员可以读取团队模板项目。CLI 只在服务端明确返回 `403 Forbidden` 时降级为仅系统推荐；网络错误或服务端异常会原样报错，不会误判成权限不足。
 
 创建后留空 Prompt 的输出：
 

package/dist/commands/remix.js

@@ -1,15 +1,99 @@
 import inquirer from 'inquirer';
+import autocomplete from 'inquirer-autocomplete-prompt';
 import { exec } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { PlayCraftApiError, PlayCraftHttpClient, isPlayCraftApiError } from '../utils/playcraft-http-client.js';
 import { IMAGE_OPTION_HELP, buildReferenceImagesPrompt, readImageAttachments, uploadImageAttachments, } from '../utils/remix-image-attachments.js';
 import { initTemplateCommand } from '../remix/init-template.js';
+// Register autocomplete prompt
+inquirer.registerPrompt('autocomplete', autocomplete);
 const JSON_OUTPUT_HELP = '输出一条 JSON (JavaScript Object Notation, JavaScript 对象表示法) 结果';
 const SERVICE_ADDRESS_HELP = 'PlayCraft 服务地址';
 const PAT_HELP = 'PAT (Personal Access Token, 个人访问令牌)';
+const BACK_TO_TEAMS = '__back_to_teams__';
+const BACK_TO_TEMPLATES = '__back_to_templates__';
+const NO_MATCH = '__no_match__';
 function emitProgress(options, message) {
     (options.json ? process.stderr : process.stdout).write(`${message}\n`);
 }
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_./:@%+=,-]+$/.test(value))
+        return value;
+    return `"${value.replace(/"/g, '\\"')}"`;
+}
+function buildOneLineRetryCommand(command, options) {
+    const parts = ['playcraft'];
+    if (command === 'remix.start')
+        parts.push('remix', 'start');
+    else if (command === 'remix.prompt')
+        parts.push('remix', 'prompt');
+    else if (command === 'remix.run')
+        parts.push('remix', 'run');
+    else if (command === 'remix.create')
+        parts.push('remix', 'create');
+    else
+        return undefined;
+    const projectId = options.projectId != null ? String(options.projectId) : '';
+    const branch = options.branch != null ? String(options.branch) : '';
+    if (projectId)
+        parts.push('--project-id', shellQuote(projectId));
+    if (branch)
+        parts.push('--branch', shellQuote(branch));
+    if (options.sourceBranch)
+        parts.push('--source-branch', shellQuote(String(options.sourceBranch)));
+    if (options.teamId)
+        parts.push('--team-id', shellQuote(String(options.teamId)));
+    if (options.templateId)
+        parts.push('--template-id', shellQuote(String(options.templateId)));
+    if (options.name)
+        parts.push('--name', shellQuote(String(options.name)));
+    if (options.prompt)
+        parts.push('--prompt', shellQuote(String(options.prompt)));
+    if (options.promptFile)
+        parts.push('--prompt-file', shellQuote(String(options.promptFile)));
+    if (options.evictSlotId)
+        parts.push('--evict-slot-id', shellQuote(String(options.evictSlotId)));
+    if (options.evictConfirmed)
+        parts.push('--evict-confirmed');
+    if (options.open)
+        parts.push('--open');
+    if (options.wait === false)
+        parts.push('--no-wait');
+    if (options.url)
+        parts.push('--url', shellQuote(String(options.url)));
+    if (Array.isArray(options.images) && options.images.length) {
+        parts.push('--image', ...options.images.map((image) => shellQuote(String(image))));
+    }
+    return parts.join(' ');
+}
+function isNetworkLikeError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return /网络请求失败|fetch failed|ECONNRESET|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|socket hang up/i.test(message);
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function fetchWithRetry(input, init, options = {}) {
+    const attempts = options.attempts ?? 3;
+    const delays = [1000, 2000, 4000];
+    let lastError;
+    for (let attempt = 0; attempt < attempts; attempt++) {
+        try {
+            return await fetch(input, init);
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === attempts - 1)
+                break;
+            await sleep(delays[attempt] ?? 4000);
+        }
+    }
+    throw new PlayCraftApiError({
+        code: 'AGENT_REQUEST_FAILED',
+        message: `网络请求失败（${lastError instanceof Error ? lastError.message : String(lastError)}）。请稍后重试。`,
+        retryable: true,
+    });
+}
 function formatIdleSec(idleSec) {
     if (!idleSec || idleSec <= 0)
         return '0s';
@@ -243,6 +327,97 @@ function parseProjectTemplates(payload) {
         sourceBranch: project.settings?.git?.branch || 'main',
     }));
 }
+export function parseRecommendedPromptTemplates(payload) {
+    const items = payload && typeof payload === 'object' && Array.isArray(payload.items)
+        ? payload.items
+        : [];
+    return items.flatMap((item) => {
+        const projectId = item.baseProject?.numericId ?? item.baseProject?.id ?? item.baseProjectId;
+        const name = item.name?.trim();
+        if (!projectId || !name)
+            return [];
+        return [{
+                id: String(projectId),
+                uuid: item.baseProject?.id,
+                choiceValue: `recommended-prompt:${item.id ?? name}:${projectId}`,
+                name,
+                baseProjectName: item.baseProject?.name,
+                projectType: item.baseProject?.projectType,
+                thumbnailUrl: item.coverImageUrl ?? item.baseProject?.thumbnailUrl,
+                sourceBranch: 'main',
+                useExactSourceBranch: true,
+                source: 'system',
+            }];
+    });
+}
+export function parseGalleryTemplates(payload) {
+    const items = payload && typeof payload === 'object' && Array.isArray(payload.items)
+        ? payload.items
+        : [];
+    return items.flatMap((item) => {
+        const projectId = item.projectId ?? item.template?.id;
+        const name = item.displayName?.trim() || item.template?.name?.trim();
+        if (projectId === undefined || !name)
+            return [];
+        const sourceBranch = item.isMain ? 'main' : item.branchName?.trim() || 'main';
+        return [{
+                id: String(projectId),
+                uuid: item.projectUuid,
+                choiceValue: `recommended-remix:${item.id ?? `${projectId}/${sourceBranch}`}`,
+                name,
+                baseProjectName: item.template?.name,
+                projectType: item.projectType,
+                thumbnailUrl: item.thumbnailUrl,
+                sourceBranch,
+                useExactSourceBranch: true,
+                source: 'system',
+            }];
+    });
+}
+export function buildTemplateChoices(templates) {
+    return templates.map((template) => {
+        const sourceLabel = template.source === 'system' ? '[系统推荐]' : '[团队模板]';
+        const baseLabel = template.baseProjectName && template.baseProjectName !== template.name
+            ? ` (模板: ${template.baseProjectName}, ID: ${template.id})`
+            : ` (ID: ${template.id})`;
+        return {
+            name: `${sourceLabel} ${template.name}${baseLabel}`,
+            value: template.choiceValue ?? template.id,
+        };
+    });
+}
+export function isTemplateProjectAccessDenied(error) {
+    return isPlayCraftApiError(error) && (error.status === 403 || error.code === 'FORBIDDEN');
+}
+export function buildRemixBranchChoices(payload, mainBranch) {
+    const seen = new Set([mainBranch]);
+    const remixChoices = parseList(payload).flatMap((branch) => {
+        const branchName = branch.id?.trim();
+        if (!branchName || seen.has(branchName) || branchName === 'main' || branchName === 'master') {
+            return [];
+        }
+        seen.add(branchName);
+        return [{
+                name: `[Remix] ${branch.name?.trim() || branchName} (${branchName})`,
+                value: branchName,
+            }];
+    });
+    return [
+        { name: '[返回] 重新选择模板（输入 back 快速定位）', value: BACK_TO_TEMPLATES },
+        { name: `${mainBranch} (从模板主分支创建新 Remix)`, value: mainBranch },
+        ...remixChoices,
+    ];
+}
+function filterPromptChoices(choices, input) {
+    const rawQuery = input?.trim().toLowerCase() || '';
+    const query = rawQuery === 'back' ? '返回' : rawQuery;
+    if (!query)
+        return choices;
+    const filtered = choices.filter((choice) => choice.name.toLowerCase().includes(query) || choice.value.toLowerCase().includes(query));
+    return filtered.length
+        ? filtered
+        : [{ name: '[无匹配] 请按 Backspace 删除关键词，或输入 back 返回', value: NO_MATCH }];
+}
 function readPrompt(options) {
     if (options.prompt && options.promptFile) {
         throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: '--prompt 和 --prompt-file 只能使用一个。' });
@@ -293,12 +468,27 @@ function handleCommandError(command, options, client, error) {
     }
     else {
         const code = isPlayCraftApiError(error) ? error.code : undefined;
-        const message = code === 'AUTH_REQUIRED'
+        let message = code === 'AUTH_REQUIRED'
             ? '需要登录。请先运行 `playcraft login`，或提供 PLAYCRAFT_TOKEN。'
             : code === 'AUTH_EXPIRED'
                 ? '登录已过期，请重新运行 `playcraft login`。'
                 : error instanceof Error ? error.message : String(error);
-        console.error(`错误：${message}`);
+        // 把裸的 fetch failed 转成可操作的中文提示
+        if (message === 'fetch failed' || /^TypeError: fetch failed$/i.test(message)) {
+            message = '网络请求失败（fetch failed）。请稍后重试。';
+        }
+        const retryable = isPlayCraftApiError(error) ? error.retryable : isNetworkLikeError(error);
+        const retryCommand = (retryable || isNetworkLikeError(error))
+            ? buildOneLineRetryCommand(command, options)
+            : undefined;
+        if (retryCommand) {
+            console.error(`错误：${message}`);
+            console.error('请重试：');
+            console.error(retryCommand);
+        }
+        else {
+            console.error(`错误：${message}`);
+        }
     }
     process.exitCode = exitCodeForError(error);
 }
@@ -332,7 +522,7 @@ async function remixTemplates(options) {
         if (!options.teamId)
             throw new PlayCraftApiError({ code: 'TEAM_NOT_FOUND', message: '必须提供 --team-id。' });
         client = createRemixClient(options);
-        const templates = parseProjectTemplates(await client.get('/projects', {
+        const templates = parseProjectTemplates(await client.get('/projects/templates', {
             teamId: options.teamId,
             limit: '100',
             skip: '0',
@@ -394,9 +584,9 @@ async function remixEnsureStream(options) {
     if (options.evictSlotId)
         endpoint.searchParams.set('evictSlotId', options.evictSlotId);
     emitProgress(options, '[连接中] 正在连接沙箱服务...');
-    const response = await fetch(endpoint, {
+    const response = await fetchWithRetry(endpoint, {
         headers: { Authorization: `Bearer ${client.token}`, Accept: 'text/event-stream' },
-    });
+    }, { label: 'ensure-stream' });
     if (!response.ok || !response.body) {
         throw new PlayCraftApiError({ code: response.status === 401 ? 'AUTH_EXPIRED' : 'AGENT_REQUEST_FAILED', message: `启动沙箱失败，状态码：${response.status}`, status: response.status, retryable: response.status >= 500 });
     }
@@ -519,7 +709,7 @@ async function waitForAgentIdle(client, ready, timeoutMs, options, handledQuesti
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     try {
-        const response = await fetch(client.url(path), { headers: { Authorization: `Bearer ${client.token}`, Accept: 'text/event-stream' }, signal: controller.signal });
+        const response = await fetchWithRetry(client.url(path), { headers: { Authorization: `Bearer ${client.token}`, Accept: 'text/event-stream' }, signal: controller.signal }, { label: 'agent-event-stream' });
         if (!response.ok || !response.body)
             throw new Error(`Agent 事件流连接失败，状态码：${response.status}`);
         const reader = response.body.getReader();
@@ -717,37 +907,144 @@ async function remixRun(options) {
             throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: '已有 Remix 模式的 --project-id/--branch 不能与 --team-id、--template-id 或 --name 同时使用。' });
         }
         if (!options.projectId) {
-            if (!teamId) {
-                if (!interactive)
-                    throw new PlayCraftApiError({ code: 'TEAM_NOT_FOUND', message: '非交互模式必须提供 --team-id。' });
-                const teams = parseList(await client.get('/teams'));
-                if (!teams.length)
-                    throw new PlayCraftApiError({ code: 'TEAM_NOT_FOUND', message: '当前登录账号没有可用团队。' });
-                teamId = (await inquirer.prompt([{ type: 'list', name: 'teamId', message: '请选择团队：', choices: teams.map((team) => ({ name: team.name, value: team.id })) }])).teamId;
+            let sourceBranch;
+            let teams;
+            while (!selectedTemplate || !sourceBranch) {
+                if (!teamId) {
+                    if (!interactive)
+                        throw new PlayCraftApiError({ code: 'TEAM_NOT_FOUND', message: '非交互模式必须提供 --team-id。' });
+                    teams ??= parseList(await client.get('/teams'));
+                    if (!teams.length)
+                        throw new PlayCraftApiError({ code: 'TEAM_NOT_FOUND', message: '当前登录账号没有可用团队。' });
+                    teamId = (await inquirer.prompt([{
+                            type: 'list',
+                            name: 'teamId',
+                            message: '请选择团队：',
+                            choices: teams.map((team) => ({ name: team.name, value: team.id })),
+                        }])).teamId;
+                }
+                let projectTemplates = [];
+                let recommendedPromptTemplates = [];
+                let galleryTemplates = [];
+                try {
+                    const projectData = await client.get('/projects/templates', {
+                        teamId,
+                        limit: '100',
+                        skip: '0',
+                    });
+                    projectTemplates = parseProjectTemplates(projectData)
+                        .map((template) => ({ ...template, source: 'team' }));
+                }
+                catch (error) {
+                    if (!isTemplateProjectAccessDenied(error))
+                        throw error;
+                }
+                const [promptResult, remixResult] = await Promise.allSettled([
+                    client.get('/recommended-prompts', { teamId, limit: '100' }),
+                    client.get('/remixes', {
+                        scope: 'gallery',
+                        recommended: 'true',
+                        teamId,
+                        limit: '100',
+                    }),
+                ]);
+                if (promptResult.status === 'fulfilled') {
+                    recommendedPromptTemplates = parseRecommendedPromptTemplates(promptResult.value);
+                }
+                else if (!options.json) {
+                    emitProgress(options, '[警告] 获取系统推荐 Prompt 模板失败');
+                }
+                if (remixResult.status === 'fulfilled') {
+                    galleryTemplates = parseGalleryTemplates(remixResult.value);
+                }
+                else if (!options.json) {
+                    emitProgress(options, '[警告] 获取系统推荐 Remix 失败');
+                }
+                const templates = [
+                    ...projectTemplates,
+                    ...recommendedPromptTemplates,
+                    ...galleryTemplates,
+                ];
+                if (!templates.length) {
+                    throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: '当前没有可用的模板项目。请联系管理员开通权限或检查系统推荐模板配置。' });
+                }
+                if (!templateId) {
+                    if (!interactive)
+                        throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: '非交互模式必须提供 --template-id。' });
+                    const templateChoices = buildTemplateChoices(templates);
+                    if (!options.teamId) {
+                        templateChoices.unshift({
+                            name: '[返回] 重新选择团队（输入 back 快速定位）',
+                            value: BACK_TO_TEAMS,
+                        });
+                    }
+                    let answer = NO_MATCH;
+                    while (answer === NO_MATCH) {
+                        answer = (await inquirer.prompt([{
+                                type: 'autocomplete',
+                                name: 'templateId',
+                                message: '请选择模板（可输入关键词搜索，输入 back 返回）：',
+                                source: async (_answersSoFar, input) => filterPromptChoices(templateChoices, input),
+                            }])).templateId;
+                    }
+                    if (answer === BACK_TO_TEAMS) {
+                        teamId = undefined;
+                        templateId = undefined;
+                        selectedTemplate = undefined;
+                        continue;
+                    }
+                    templateId = answer;
+                }
+                selectedTemplate = templates.find((template) => template.choiceValue === templateId || template.id === templateId);
+                if (!selectedTemplate) {
+                    throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: `模板 ${templateId} 不存在或对所选团队不可见。` });
+                }
+                templateId = selectedTemplate.id;
+                if (selectedTemplate.useExactSourceBranch) {
+                    sourceBranch = selectedTemplate.sourceBranch || 'main';
+                    continue;
+                }
+                if (!options.json)
+                    emitProgress(options, '[加载中] 获取模板的 Remix 分支列表...');
+                const branchData = await client.get(`/projects/${encodeURIComponent(selectedTemplate.id)}/branches`, {
+                    includeAll: 'true',
+                    teamId,
+                });
+                const mainBranch = selectedTemplate.sourceBranch || options.sourceBranch || 'main';
+                const branchChoices = buildRemixBranchChoices(branchData, mainBranch);
+                let branchAnswer = NO_MATCH;
+                while (branchAnswer === NO_MATCH) {
+                    branchAnswer = (await inquirer.prompt([{
+                            type: 'autocomplete',
+                            name: 'branch',
+                            message: '请选择基础分支（输入 back 返回模板列表）：',
+                            source: async (_answersSoFar, input) => filterPromptChoices(branchChoices, input),
+                        }])).branch;
+                }
+                if (branchAnswer === BACK_TO_TEMPLATES) {
+                    templateId = undefined;
+                    selectedTemplate = undefined;
+                    continue;
+                }
+                sourceBranch = branchAnswer;
             }
-            const templates = parseProjectTemplates(await client.get('/projects', {
-                teamId,
-                limit: '100',
-                skip: '0',
-            }));
-            if (!templates.length)
-                throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: '所选团队当前没有可见项目。' });
-            if (!templateId) {
-                if (!interactive)
-                    throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: '非交互模式必须提供 --template-id。' });
-                templateId = (await inquirer.prompt([{ type: 'list', name: 'templateId', message: '请选择模板：', choices: templates.map((template) => ({ name: template.name, value: template.id })) }])).templateId;
+            if (!selectedTemplate || !sourceBranch) {
+                throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: '未选择有效的模板或基础分支。' });
             }
-            selectedTemplate = templates.find((template) => template.id === templateId);
-            if (!selectedTemplate)
-                throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: `模板 ${templateId} 不存在或对所选团队不可见。` });
-            if (!options.name && !interactive)
-                throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: '非交互模式必须提供 --name。' });
-            const name = (options.name || (await inquirer.prompt([{ type: 'input', name: 'name', message: '请输入 Remix 名称：', validate: (value) => Boolean(value.trim()) || 'Remix 名称不能为空。' }])).name).trim();
+            if (!options.json)
+                emitProgress(options, `[已选择] 基于分支: ${sourceBranch}`);
+            // Auto-generate remix name following platform naming convention
+            const timestamp = Date.now();
+            const randomSuffix = Math.random().toString(36).substring(2, 10);
+            const baseName = selectedTemplate.name.replace(/[^a-zA-Z0-9-]/g, '-').toLowerCase();
+            const name = options.name || `remix-${baseName}-${timestamp}-${randomSuffix}`;
+            if (!options.json)
+                emitProgress(options, `[自动生成] Remix 名称: ${name}`);
             const createdRemix = await remixCreate({
                 ...options,
                 projectId: selectedTemplate.id,
                 name,
-                sourceBranch: selectedTemplate.sourceBranch || options.sourceBranch,
+                sourceBranch, // Use the sourceBranch determined above
                 teamId,
                 editorProjectId: selectedTemplate.projectType === 'external' && selectedTemplate.uuid
                     ? selectedTemplate.uuid
@@ -888,14 +1185,44 @@ export function registerRemixCommands(program) {
         .action(async (opts) => {
         let client;
         try {
-            client = createRemixClient(opts);
-            const ready = await remixEnsureStream({ ...opts, projectId: String(opts.projectId), branch: String(opts.branch), interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY && !opts.json) });
-            const editorProjectId = await resolveEditorProjectIdBestEffort(client, String(opts.projectId), opts);
-            const data = { projectId: String(opts.projectId), branch: String(opts.branch), urls: { editor: editorUrl(client, editorProjectId, String(opts.branch)), ...(ready.previewUrl ? { preview: ready.previewUrl } : {}) }, sandbox: { id: ready.sandboxId, slotId: ready.slotId, status: ready.status || 'ready' }, agent: { slug: ready.codeAgentSlug, sessionId: ready.agentSessionId } };
+            const options = {
+                ...opts,
+                projectId: String(opts.projectId),
+                branch: String(opts.branch),
+                interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY && !opts.json),
+            };
+            client = createRemixClient(options);
+            const sandbox = await remixEnsureStream(options);
+            const ready = await ensureAgentSession(client, sandbox, options);
+            const editorProjectId = await resolveEditorProjectIdBestEffort(client, options.projectId, options);
+            const pendingQuestions = await listPendingAgentQuestions(client, ready);
+            const handledQuestionIds = new Set();
+            if (pendingQuestions.length) {
+                emitProgress(options, `[恢复中] 检测到 ${pendingQuestions.length} 个待回答问题，Agent 正在等待你的选择。`);
+                for (const request of pendingQuestions) {
+                    await replyToAgentQuestion(client, ready, options, request, handledQuestionIds);
+                }
+            }
+            const data = {
+                projectId: options.projectId,
+                branch: options.branch,
+                urls: {
+                    editor: editorUrl(client, editorProjectId, options.branch),
+                    ...(ready.previewUrl ? { preview: ready.previewUrl } : {}),
+                },
+                sandbox: { id: ready.sandboxId, slotId: ready.slotId, status: ready.status || 'ready' },
+                agent: {
+                    slug: ready.codeAgentSlug,
+                    sessionId: ready.agentSessionId,
+                    pendingQuestions: pendingQuestions.length,
+                },
+            };
             if (opts.open)
                 openBrowser(data.urls.editor);
             if (opts.json)
                 console.log(JSON.stringify(resultEnvelope('remix.start', client, data)));
+            else if (pendingQuestions.length)
+                console.log(`待回答问题已处理，沙箱已就绪：${data.urls.editor}`);
             else
                 console.log(`沙箱已就绪：${data.urls.editor}`);
         }

package/dist/utils/playcraft-http-client.js

@@ -36,6 +36,15 @@ function resolveToken(token) {
     }
     return resolved;
 }
+function humanizeNetworkError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    if (raw.includes('网络请求失败'))
+        return raw;
+    if (/fetch failed|ECONNRESET|ETIMEDOUT|ENOTFOUND|ECONNREFUSED|socket hang up|UND_ERR/i.test(raw)) {
+        return `网络请求失败（${raw}）。请稍后重试。`;
+    }
+    return raw;
+}
 function statusCode(status) {
     if (status === 401)
         return 'AUTH_EXPIRED';
@@ -67,49 +76,80 @@ export class PlayCraftHttpClient {
         headers.set('X-Request-Id', this.requestId);
         if (init.body && !headers.has('Content-Type'))
             headers.set('Content-Type', 'application/json');
-        let response;
-        try {
-            response = await fetch(this.url(path), { ...init, headers });
-        }
-        catch (error) {
-            throw new PlayCraftApiError({
-                code: 'AGENT_REQUEST_FAILED',
-                message: error instanceof Error ? error.message : String(error),
-                retryable: true,
-            });
-        }
-        const contentType = response.headers.get('content-type') || '';
-        const raw = await response.text();
-        let payload = undefined;
-        if (raw) {
+        const maxRetries = 3;
+        const retryDelays = [1000, 2000, 4000]; // 指数退避：1s, 2s, 4s
+        let lastError;
+        for (let attempt = 0; attempt < maxRetries; attempt++) {
             try {
-                payload = contentType.includes('json') ? JSON.parse(raw) : raw;
+                const response = await fetch(this.url(path), { ...init, headers });
+                const contentType = response.headers.get('content-type') || '';
+                const raw = await response.text();
+                let payload = undefined;
+                if (raw) {
+                    try {
+                        payload = contentType.includes('json') ? JSON.parse(raw) : raw;
+                    }
+                    catch {
+                        payload = raw;
+                    }
+                }
+                if (!response.ok) {
+                    const error = payload?.error;
+                    const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
+                    const message = typeof error?.message === 'string'
+                        ? error.message
+                        : typeof payload?.message === 'string'
+                            ? payload.message
+                            : typeof payload === 'string'
+                                ? payload
+                                : response.statusText || 'PlayCraft request failed';
+                    throw new PlayCraftApiError({
+                        code,
+                        message,
+                        status: response.status,
+                        details: error?.details ?? payload,
+                        retryable: response.status >= 500,
+                    });
+                }
+                if (!raw)
+                    return undefined;
+                return payload;
             }
-            catch {
-                payload = raw;
+            catch (error) {
+                lastError = isPlayCraftApiError(error)
+                    ? error
+                    : new PlayCraftApiError({
+                        code: 'AGENT_REQUEST_FAILED',
+                        message: humanizeNetworkError(error),
+                        retryable: true,
+                    });
+                // 如果是客户端错误（4xx）或不可重试的错误，立即抛出
+                if (isPlayCraftApiError(error) && !error.retryable) {
+                    throw error;
+                }
+                // 最后一次尝试失败，抛出错误
+                if (attempt === maxRetries - 1) {
+                    break;
+                }
+                // 等待后重试
+                await new Promise(resolve => setTimeout(resolve, retryDelays[attempt]));
             }
         }
-        if (!response.ok) {
-            const error = payload?.error;
-            const code = typeof error?.code === 'string' ? error.code : statusCode(response.status);
-            const message = typeof error?.message === 'string'
-                ? error.message
-                : typeof payload?.message === 'string'
-                    ? payload.message
-                    : typeof payload === 'string'
-                        ? payload
-                        : response.statusText || 'PlayCraft request failed';
+        // 所有重试都失败了
+        if (isPlayCraftApiError(lastError)) {
             throw new PlayCraftApiError({
-                code,
-                message,
-                status: response.status,
-                details: error?.details ?? payload,
-                retryable: response.status >= 500,
+                code: lastError.code,
+                message: humanizeNetworkError(lastError),
+                status: lastError.status,
+                details: lastError.details,
+                retryable: true,
             });
         }
-        if (!raw)
-            return undefined;
-        return payload;
+        throw new PlayCraftApiError({
+            code: 'AGENT_REQUEST_FAILED',
+            message: humanizeNetworkError(lastError),
+            retryable: true,
+        });
     }
     get(path, params, init = {}) {
         const url = new URL(this.url(path));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@playcraft/cli",
-  "version": "0.0.51",
+  "version": "0.0.53",
   "private": false,
   "type": "module",
   "engines": {
@@ -45,8 +45,8 @@
     "@gltf-transform/core": "^4.3.0",
     "@gltf-transform/extensions": "^4.3.0",
     "@gltf-transform/functions": "^4.3.0",
-    "@playcraft/build": "^0.0.51",
-    "@playcraft/common": "^0.0.51",
+    "@playcraft/build": "^0.0.53",
+    "@playcraft/common": "^0.0.53",
     "chokidar": "^4.0.3",
     "commander": "^13.1.0",
     "cors": "^2.8.6",
@@ -57,6 +57,7 @@
     "express": "^5.2.1",
     "fluent-ffmpeg": "^2.1.3",
     "inquirer": "^9.3.8",
+    "inquirer-autocomplete-prompt": "^3.0.1",
     "js-yaml": "^4.1.1",
     "json5": "^2.2.3",
     "latest-version": "^7.0.0",