@playcraft/cli 0.0.49 → 0.0.52

package/dist/commands/remix.js

@@ -1,97 +1,604 @@
 import inquirer from 'inquirer';
-import { exec } from 'child_process';
-import { loadGlobalConfig } from '../config.js';
-import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from './login.js';
+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';
-function resolveBackendBaseUrl(options) {
-    const globalConfig = loadGlobalConfig();
-    const raw = options.url ||
-        process.env.PLAYCRAFT_URL ||
-        globalConfig.url ||
-        globalConfig.backendUrl ||
-        DEFAULT_PLAYCRAFT_CLOUD_BASE;
-    return raw.replace(/\/+$/, '');
-}
-function resolveJwtToken(options) {
-    const globalConfig = loadGlobalConfig();
-    const token = options.token || process.env.PLAYCRAFT_TOKEN || globalConfig.token;
-    if (!token) {
-        throw new Error('缺少 JWT token。请先执行 `playcraft login`，或传入 --token / PLAYCRAFT_TOKEN。');
-    }
-    return token;
+// 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 openBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    exec(`${cmd} "${url}"`, () => undefined);
+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';
     if (idleSec < 60)
         return `${idleSec}s`;
-    const m = Math.floor(idleSec / 60);
-    const s = idleSec % 60;
-    return `${m}m${s}s`;
+    return `${Math.floor(idleSec / 60)}m${idleSec % 60}s`;
 }
-function getTtydUrl(agentBaseUrl) {
-    if (!agentBaseUrl || !agentBaseUrl.includes('/agent/'))
-        return undefined;
-    return agentBaseUrl.replace('/agent/', '/ttyd/');
+function parseAgentQuestions(input) {
+    let raw = input;
+    if (raw && typeof raw === 'object' && !Array.isArray(raw)) {
+        raw = raw.questions ?? [raw];
+    }
+    if (typeof raw === 'string') {
+        try {
+            raw = JSON.parse(raw);
+        }
+        catch {
+            return [];
+        }
+    }
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((value) => {
+        if (!value || typeof value !== 'object')
+            return [];
+        const question = value;
+        const text = [question.question, question.prompt, question.text]
+            .find((candidate) => typeof candidate === 'string' && candidate.trim().length > 0);
+        if (!text)
+            return [];
+        const options = (Array.isArray(question.options) ? question.options : []).flatMap((option) => {
+            if (typeof option === 'string' && option.trim())
+                return [{ label: option.trim() }];
+            if (!option || typeof option !== 'object')
+                return [];
+            const item = option;
+            const label = [item.label, item.text, item.value, item.description]
+                .find((candidate) => typeof candidate === 'string' && candidate.trim().length > 0);
+            if (!label)
+                return [];
+            return [{
+                    label: label.trim(),
+                    ...(typeof item.description === 'string' && item.description.trim()
+                        ? { description: item.description.trim() }
+                        : {}),
+                }];
+        });
+        const custom = question.custom !== false;
+        if (!options.length && !custom)
+            return [];
+        return [{
+                question: text.trim(),
+                ...(typeof question.header === 'string' && question.header.trim()
+                    ? { header: question.header.trim() }
+                    : {}),
+                options,
+                multiple: question.multiple === true,
+                custom,
+            }];
+    });
 }
-async function remixCreate(options) {
-    const baseUrl = resolveBackendBaseUrl(options);
-    const token = resolveJwtToken(options);
-    const endpoint = `${baseUrl}/api/projects/${encodeURIComponent(options.projectId)}/branches`;
-    const res = await fetch(endpoint, {
-        method: 'POST',
-        headers: {
-            Authorization: `Bearer ${token}`,
-            'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-            name: options.name,
-            ref: options.sourceBranch,
-        }),
+async function promptForAgentAnswers(questions) {
+    const answers = [];
+    for (let index = 0; index < questions.length; index += 1) {
+        const question = questions[index];
+        const message = `${question.header ? `${question.header}：` : ''}${question.question}`;
+        const choices = question.options.map((option, optionIndex) => ({
+            name: option.description && option.description !== option.label
+                ? `${option.label} — ${option.description}`
+                : option.label,
+            value: optionIndex,
+        }));
+        const customValue = -1;
+        if (question.custom)
+            choices.push({ name: '其他（手动输入）', value: customValue });
+        let selectedIndexes;
+        if (!question.options.length && question.custom) {
+            selectedIndexes = [customValue];
+        }
+        else if (question.multiple) {
+            const selected = await inquirer.prompt([{
+                    type: 'checkbox',
+                    name: 'values',
+                    message: `${message}（可多选）`,
+                    choices,
+                    validate: (values) => values.length > 0 || '请至少选择一项。',
+                }]);
+            selectedIndexes = selected.values;
+        }
+        else {
+            const selected = await inquirer.prompt([{
+                    type: 'list',
+                    name: 'value',
+                    message,
+                    choices,
+                }]);
+            selectedIndexes = [selected.value];
+        }
+        const answer = selectedIndexes
+            .filter((selected) => selected !== customValue)
+            .map((selected) => question.options[selected]?.label)
+            .filter((label) => Boolean(label));
+        if (selectedIndexes.includes(customValue)) {
+            const custom = await inquirer.prompt([{
+                    type: 'input',
+                    name: 'text',
+                    message: `${question.header || `问题 ${index + 1}`}，请输入自定义答案：`,
+                    validate: (value) => Boolean(value.trim()) || '答案不能为空。',
+                }]);
+            answer.push(custom.text.trim());
+        }
+        answers.push(answer);
+    }
+    return answers;
+}
+function parseAgentQuestionRequests(input) {
+    const values = Array.isArray(input) ? input : input && typeof input === 'object' ? [input] : [];
+    return values.flatMap((value) => {
+        if (!value || typeof value !== 'object')
+            return [];
+        const payload = value;
+        const id = [payload.id, payload.requestID, payload.requestId]
+            .find((candidate) => typeof candidate === 'string' && candidate.length > 0);
+        if (!id)
+            return [];
+        const sessionId = [payload.sessionID, payload.sessionId, payload.session_id]
+            .find((candidate) => typeof candidate === 'string' && candidate.length > 0);
+        return [{
+                id,
+                ...(sessionId ? { sessionId } : {}),
+                questions: parseAgentQuestions(payload.questions ?? payload),
+                raw: value,
+            }];
+    });
+}
+async function replyToAgentQuestion(client, ready, options, request, handledQuestionIds) {
+    if (request.sessionId && request.sessionId !== ready.agentSessionId)
+        return;
+    if (handledQuestionIds.has(request.id))
+        return;
+    handledQuestionIds.add(request.id);
+    if (!request.questions.length) {
+        throw new PlayCraftApiError({
+            code: 'AGENT_REQUEST_FAILED',
+            message: 'Agent 请求用户选择，但返回的问题格式无法识别。请打开 Remix 编辑器回答。',
+            details: request.raw,
+        });
+    }
+    if (!options.interactive) {
+        throw new PlayCraftApiError({
+            code: 'AGENT_REQUEST_FAILED',
+            message: 'Agent 正在等待用户选择。请在交互式终端运行命令，或打开 Remix 编辑器回答。',
+            details: { requestId: request.id, questions: request.questions },
+        });
+    }
+    emitProgress(options, `[等待选择] Agent 提出了 ${request.questions.length} 个问题：`);
+    const answers = await promptForAgentAnswers(request.questions);
+    await client.post(`${ready.agentEndpoint}/question/${encodeURIComponent(request.id)}/reply`, { answers });
+    emitProgress(options, '[已回复] 选择已发送，Agent 继续执行...');
+}
+function openBrowser(url) {
+    const command = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
+    exec(`${command} "${url}"`, () => undefined);
+}
+function localServiceUrl(baseUrl, fromPort, toPort) {
+    const url = new URL(baseUrl);
+    const isLocal = ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname);
+    if (isLocal && url.port === fromPort)
+        url.port = toPort;
+    return url.toString().replace(/\/+$/, '');
+}
+function createRemixClient(options) {
+    const configured = new PlayCraftHttpClient(options);
+    const apiBaseUrl = localServiceUrl(configured.baseUrl, '3000', '3001');
+    if (apiBaseUrl === configured.baseUrl)
+        return configured;
+    return new PlayCraftHttpClient({
+        url: apiBaseUrl,
+        token: configured.token,
+        requestId: configured.requestId,
+    });
+}
+function editorUrl(client, projectId, branch) {
+    const configured = process.env.PLAYCRAFT_FRONTEND_URL || process.env.FRONTEND_URL;
+    const base = configured || localServiceUrl(client.baseUrl, '3001', '3000');
+    return `${base.replace(/\/+$/, '')}/editor/remix/${encodeURIComponent(projectId)}?branch=${encodeURIComponent(branch)}`;
+}
+function remixDetailUrl(client, projectId, branch) {
+    const configured = process.env.PLAYCRAFT_FRONTEND_URL || process.env.FRONTEND_URL;
+    const base = configured || localServiceUrl(client.baseUrl, '3001', '3000');
+    return `${base.replace(/\/+$/, '')}/projects/${encodeURIComponent(projectId)}/remixes/${encodeURIComponent(branch)}`;
+}
+function isAgentPromptExit(value) {
+    return ['', 'q', 'quit', 'exit', '退出'].includes(value.trim().toLowerCase());
+}
+async function resolveEditorProjectId(client, projectId) {
+    const project = await client.get(`/projects/${encodeURIComponent(projectId)}`);
+    if (project?.projectType === 'external' && typeof project.uuid === 'string' && project.uuid) {
+        return project.uuid;
+    }
+    if (project?.id !== undefined && project?.id !== null)
+        return String(project.id);
+    return projectId;
+}
+async function resolveEditorProjectIdBestEffort(client, projectId, options, fallbackProjectId = projectId) {
+    try {
+        return await resolveEditorProjectId(client, projectId);
+    }
+    catch {
+        emitProgress(options, `[提示] 项目操作已成功，但暂时无法解析编辑器项目标识，链接临时使用项目 ID：${fallbackProjectId}`);
+        return fallbackProjectId;
+    }
+}
+function parseList(payload) {
+    if (Array.isArray(payload))
+        return payload;
+    if (payload && typeof payload === 'object' && Array.isArray(payload.result)) {
+        return payload.result;
+    }
+    return [];
+}
+function parseProjectTemplates(payload) {
+    return parseList(payload).map((project) => ({
+        id: String(project.id),
+        uuid: project.uuid,
+        name: project.name,
+        projectType: project.projectType,
+        description: project.description,
+        tags: project.tags,
+        thumbnailUrl: project.thumbnailUrl,
+        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,
+            }];
     });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`创建 remix 失败: ${res.status} ${text}`);
+    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 只能使用一个。' });
+    }
+    const prompt = options.promptFile ? readFileSync(options.promptFile, 'utf8') : options.prompt || '';
+    const trimmed = prompt.trim();
+    if (!trimmed) {
+        throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: '需求描述不能为空。' });
+    }
+    if (Buffer.byteLength(trimmed, 'utf8') > 256 * 1024) {
+        throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: '需求描述超过 256 KiB (Kibibyte, 千二进制字节) 限制。' });
     }
-    const data = (await res.json());
-    console.log(`Remix 创建成功: ${data.displayName || data.name}`);
-    console.log(`分支: ${data.name}`);
+    return trimmed;
+}
+function resultEnvelope(command, client, data) {
+    return { schemaVersion: '1.0', ok: true, command, requestId: client.requestId, data };
+}
+function errorEnvelope(command, client, error) {
+    const apiError = isPlayCraftApiError(error)
+        ? error
+        : new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: error instanceof Error ? error.message : String(error) });
+    return {
+        schemaVersion: '1.0',
+        ok: false,
+        command,
+        ...(client ? { requestId: client.requestId } : {}),
+        error: {
+            code: apiError.code,
+            message: apiError.message,
+            retryable: apiError.retryable,
+            ...(apiError.details === undefined ? {} : { details: apiError.details }),
+        },
+    };
+}
+function exitCodeForError(error) {
+    const code = isPlayCraftApiError(error) ? error.code : '';
+    if (code === 'AUTH_REQUIRED' || code === 'AUTH_EXPIRED')
+        return 3;
+    if (code === 'FORBIDDEN' || code === 'TEAM_FORBIDDEN' || code === 'TEAM_NOT_FOUND' || code === 'TEMPLATE_NOT_FOUND')
+        return 4;
+    if (code === 'AGENT_TIMEOUT' || code === 'AGENT_REQUEST_FAILED' || code === 'AGENT_UNAVAILABLE')
+        return 5;
+    return 2;
+}
+function handleCommandError(command, options, client, error) {
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(errorEnvelope(command, client, error))}\n`);
+    }
+    else {
+        const code = isPlayCraftApiError(error) ? error.code : undefined;
+        let message = code === 'AUTH_REQUIRED'
+            ? '需要登录。请先运行 `playcraft login`，或提供 PLAYCRAFT_TOKEN。'
+            : code === 'AUTH_EXPIRED'
+                ? '登录已过期，请重新运行 `playcraft login`。'
+                : error instanceof Error ? error.message : String(error);
+        // 把裸的 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);
+}
+async function remixTeams(options) {
+    let client;
+    try {
+        client = createRemixClient(options);
+        const teams = parseList(await client.get('/teams'));
+        const data = { items: teams, page: 1, limit: teams.length, total: teams.length, hasMore: false };
+        if (options.json) {
+            console.log(JSON.stringify(resultEnvelope('remix.teams', client, data)));
+        }
+        else {
+            if (!teams.length)
+                console.log('当前账号没有可用团队。');
+            else
+                teams.forEach((team) => console.log(`${team.id}\t${team.name}`));
+            console.log('\n下一步：');
+            console.log('  playcraft remix templates --team-id <团队ID>');
+            console.log('\n或直接运行完整交互流程：');
+            console.log('  playcraft remix run');
+        }
+    }
+    catch (error) {
+        handleCommandError('remix.teams', options, client, error);
+    }
+}
+async function remixTemplates(options) {
+    let client;
+    try {
+        if (!options.teamId)
+            throw new PlayCraftApiError({ code: 'TEAM_NOT_FOUND', message: '必须提供 --team-id。' });
+        client = createRemixClient(options);
+        const templates = parseProjectTemplates(await client.get('/projects/templates', {
+            teamId: options.teamId,
+            limit: '100',
+            skip: '0',
+        }));
+        const filtered = options.tag
+            ? templates.filter((template) => Object.values(template.tags || {})
+                .flatMap((tags) => Array.isArray(tags) ? tags : [])
+                .some((tag) => typeof tag === 'string' && tag.toLowerCase().includes(options.tag.toLowerCase())))
+            : templates;
+        const data = { items: filtered, page: 1, limit: filtered.length, total: filtered.length, hasMore: false };
+        if (options.json) {
+            console.log(JSON.stringify(resultEnvelope('remix.templates', client, data)));
+        }
+        else {
+            if (!filtered.length)
+                console.log('所选团队当前没有可见项目。');
+            else
+                filtered.forEach((template) => console.log(`${template.id}\t${template.name}`));
+            console.log('\n下一步：');
+            console.log(`  playcraft remix run --team-id ${options.teamId} --template-id <模板ID>`);
+        }
+    }
+    catch (error) {
+        handleCommandError('remix.templates', options, client, error);
+    }
+}
+async function remixCreate(options) {
+    const client = createRemixClient(options);
+    const branch = await client.post(`/projects/${encodeURIComponent(options.projectId)}/branches`, {
+        name: options.name,
+        ref: options.sourceBranch,
+        ...(options.teamId ? { teamId: options.teamId } : {}),
+    });
+    const branchName = branch.name;
+    const editorProjectId = options.editorProjectId || await resolveEditorProjectIdBestEffort(client, options.projectId, options);
+    return {
+        projectId: options.projectId,
+        branch: branchName,
+        displayName: branch.displayName,
+        editorUrl: editorUrl(client, editorProjectId, branchName),
+    };
+}
+function resolveEnsureStreamUrl(client, projectId) {
+    const endpoint = new URL(client.url(`/projects/${encodeURIComponent(projectId)}/sandbox/ensure-stream`));
+    const isLocalFrontend = ['localhost', '127.0.0.1', '[::1]'].includes(endpoint.hostname)
+        && endpoint.port === '3000';
+    if (isLocalFrontend)
+        endpoint.port = '3001';
+    return endpoint;
 }
 async function remixEnsureStream(options) {
-    const baseUrl = resolveBackendBaseUrl(options);
-    const token = resolveJwtToken(options);
-    const endpoint = new URL(`${baseUrl}/api/projects/${encodeURIComponent(options.projectId)}/sandbox/ensure-stream`);
+    const client = createRemixClient(options);
+    const endpoint = resolveEnsureStreamUrl(client, options.projectId);
     endpoint.searchParams.set('branch', options.branch);
+    if (options.sourceBranch)
+        endpoint.searchParams.set('sourceBranch', options.sourceBranch);
     if (options.evictConfirmed)
         endpoint.searchParams.set('evictConfirmed', 'true');
-    const res = await fetch(endpoint.toString(), {
-        method: 'GET',
-        headers: {
-            Authorization: `Bearer ${token}`,
-            Accept: 'text/event-stream',
-        },
-    });
-    if (!res.ok || !res.body) {
-        const text = await res.text();
-        throw new Error(`ensure-stream 失败: ${res.status} ${text}`);
+    if (options.evictSlotId)
+        endpoint.searchParams.set('evictSlotId', options.evictSlotId);
+    emitProgress(options, '[连接中] 正在连接沙箱服务...');
+    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 });
     }
-    const reader = res.body.getReader();
+    const reader = response.body.getReader();
     const decoder = new TextDecoder();
     let buffer = '';
-    const parseBlock = (block) => {
-        const payload = block
-            .split('\n')
-            .filter((line) => line.startsWith('data:'))
-            .map((line) => line.slice(5).trim())
-            .join('\n');
-        if (!payload)
+    const parseEvent = (block) => {
+        const data = block.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim()).join('\n');
+        if (!data)
             return null;
         try {
-            return JSON.parse(payload);
+            return JSON.parse(data);
         }
         catch {
             return null;
@@ -102,134 +609,661 @@ async function remixEnsureStream(options) {
         if (done)
             break;
         buffer += decoder.decode(value, { stream: true });
-        let sepIdx = buffer.indexOf('\n\n');
-        while (sepIdx >= 0) {
-            const block = buffer.slice(0, sepIdx);
-            buffer = buffer.slice(sepIdx + 2);
-            const event = parseBlock(block);
-            if (!event) {
-                sepIdx = buffer.indexOf('\n\n');
+        const frames = buffer.split(/\r?\n\r?\n/);
+        buffer = frames.pop() || '';
+        for (const frame of frames) {
+            const event = parseEvent(frame);
+            if (!event)
                 continue;
-            }
-            if (event.type === 'phase') {
-                console.log(`[${event.phase}]${event.detail ? ` ${event.detail}` : ''}`);
-            }
-            else if (event.type === 'log') {
-                console.log(event.message);
-            }
-            else if (event.type === 'error') {
-                throw new Error(event.message || 'ensure-stream 返回 error 事件');
-            }
+            if (event.type === 'phase')
+                emitProgress(options, `[${event.phase}]${event.detail ? ` ${event.detail}` : ''}`);
+            else if (event.type === 'log')
+                emitProgress(options, event.message);
+            else if (event.type === 'error')
+                throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: event.message });
             else if (event.type === 'capacity_exceeded') {
-                const selectableCandidates = event.candidates.filter((c) => c.evictable !== false);
-                if (!selectableCandidates.length) {
-                    throw new Error(`容量已满 (${event.current}/${event.max})，但服务端未返回可驱逐候选`);
-                }
-                const selected = await inquirer.prompt([
-                    {
-                        type: 'list',
-                        name: 'slotId',
-                        message: `沙箱容量已满 (${event.current}/${event.max})，请选择一个候选项继续驱逐:`,
-                        choices: event.candidates.map((c) => ({
-                            name: `${c.slotId} (${c.projectId}/${c.branchName}) status=${c.agentStatus ?? 'unknown'} idle=${formatIdleSec(c.idleSec)}${c.hasUnpushedChanges ? ' [unpushed]' : ''}`,
-                            value: c.slotId,
-                            disabled: c.evictable === false ? (c.disabledReason ?? 'not evictable') : false,
-                        })),
-                    },
-                ]);
-                const confirmed = await inquirer.prompt([
-                    {
-                        type: 'confirm',
-                        name: 'ok',
-                        message: `确认继续驱逐并重试？ selected=${selected.slotId}`,
-                        default: false,
-                    },
-                ]);
-                if (!confirmed.ok) {
-                    throw new Error('用户取消操作');
+                if (!options.interactive) {
+                    throw new PlayCraftApiError({ code: 'SANDBOX_CAPACITY_EXCEEDED', message: `沙箱容量已满（${event.current}/${event.max}），请传入 --evict-slot-id 和 --evict-confirmed。`, details: { candidates: event.candidates } });
                 }
-                return remixEnsureStream({ ...options, evictConfirmed: true });
+                const candidates = event.candidates.filter((candidate) => candidate.evictable !== false);
+                if (!candidates.length)
+                    throw new PlayCraftApiError({ code: 'SANDBOX_CAPACITY_EXCEEDED', message: `沙箱容量已满（${event.current}/${event.max}），没有可释放的槽位。` });
+                const selected = await inquirer.prompt([{ type: 'list', name: 'slotId', message: `沙箱容量已满（${event.current}/${event.max}），请选择要释放的槽位：`, choices: event.candidates.map((candidate) => ({ name: `${candidate.slotId}（${candidate.projectId}/${candidate.branchName}）状态=${candidate.agentStatus ?? '未知'} 空闲=${formatIdleSec(candidate.idleSec)}`, value: candidate.slotId, disabled: candidate.evictable === false ? candidate.disabledReason || '不可释放' : false })) }]);
+                const confirmed = await inquirer.prompt([{ type: 'confirm', name: 'ok', message: `确定释放槽位 ${selected.slotId} 并重试吗？`, default: false }]);
+                if (!confirmed.ok)
+                    throw new PlayCraftApiError({ code: 'SANDBOX_CAPACITY_EXCEEDED', message: '操作已取消。' });
+                return remixEnsureStream({ ...options, evictConfirmed: true, evictSlotId: selected.slotId });
             }
             else if (event.type === 'done') {
                 return {
                     sandboxId: event.sandboxId,
                     previewUrl: event.previewUrl,
                     agentBaseUrl: event.agentBaseUrl,
+                    agentEndpoint: event.agentEndpoint,
+                    agentSessionId: event.agentSessionId,
+                    codeAgentSlug: event.codeAgentSlug,
+                    slotId: event.slotId,
+                    status: event.status,
+                };
+            }
+        }
+    }
+    throw new PlayCraftApiError({ code: 'AGENT_UNAVAILABLE', message: '沙箱启动连接已结束，但沙箱尚未就绪。' });
+}
+function sessionPath(ready) {
+    if (!ready.agentEndpoint || !ready.agentSessionId) {
+        throw new PlayCraftApiError({ code: 'AGENT_UNAVAILABLE', message: '沙箱未返回 Agent 服务地址或当前会话。' });
+    }
+    return `${ready.agentEndpoint}/session/${encodeURIComponent(ready.agentSessionId)}`;
+}
+async function ensureAgentSession(client, ready, options) {
+    if (!ready.agentEndpoint) {
+        throw new PlayCraftApiError({ code: 'AGENT_UNAVAILABLE', message: '沙箱未返回 Agent 服务地址。' });
+    }
+    if (ready.agentSessionId)
+        return ready;
+    const findLatestSession = async () => {
+        const sessions = await client.get(`${ready.agentEndpoint}/session`);
+        return [...(Array.isArray(sessions) ? sessions : [])]
+            .filter((session) => typeof session.id === 'string' && session.id.length > 0)
+            .sort((a, b) => (b.time?.created ?? 0) - (a.time?.created ?? 0))[0];
+    };
+    const latest = await findLatestSession();
+    if (latest?.id)
+        return { ...ready, agentSessionId: latest.id };
+    emitProgress(options, '[会话中] 正在创建 Agent 会话...');
+    let created;
+    try {
+        created = await client.post(`${ready.agentEndpoint}/session`, {}, {
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (error) {
+        emitProgress(options, '[会话中] 创建响应未返回，正在查询已创建的会话...');
+        const recovered = await findLatestSession();
+        if (recovered?.id)
+            return { ...ready, agentSessionId: recovered.id };
+        throw error;
+    }
+    if (!created?.id) {
+        throw new PlayCraftApiError({ code: 'AGENT_UNAVAILABLE', message: 'Agent 会话创建成功，但未返回会话 ID。' });
+    }
+    return { ...ready, agentSessionId: created.id };
+}
+async function listPendingAgentQuestions(client, ready) {
+    if (!ready.agentEndpoint)
+        return [];
+    try {
+        const payload = await client.get(`${ready.agentEndpoint}/question`);
+        return parseAgentQuestionRequests(payload)
+            .filter((request) => !request.sessionId || request.sessionId === ready.agentSessionId);
+    }
+    catch (error) {
+        if (isPlayCraftApiError(error) && error.status === 404)
+            return [];
+        throw error;
+    }
+}
+async function waitForAgentIdle(client, ready, timeoutMs, options, handledQuestionIds, baselineAssistantState) {
+    const path = `${sessionPath(ready).replace(/\/session\/[^/]+$/, '')}/event`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        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();
+        const decoder = new TextDecoder();
+        let buffer = '';
+        const pendingQuestions = await listPendingAgentQuestions(client, ready);
+        for (const request of pendingQuestions) {
+            await replyToAgentQuestion(client, ready, options, request, handledQuestionIds);
+        }
+        if (await hasAgentTurnCompleted(client, ready, baselineAssistantState, true))
+            return;
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            const frames = buffer.split(/\r?\n\r?\n/);
+            buffer = frames.pop() || '';
+            for (const frame of frames) {
+                const data = frame.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trim()).join('\n');
+                if (!data)
+                    continue;
+                let event;
+                try {
+                    event = JSON.parse(data);
+                }
+                catch {
+                    continue;
+                }
+                const properties = event?.properties || {};
+                const eventSessionId = properties.sessionID || properties.sessionId || properties.session_id;
+                if (event?.type === 'question.asked') {
+                    const questionPayload = Object.keys(properties).length > 0 ? properties : event;
+                    const [request] = parseAgentQuestionRequests(questionPayload);
+                    if (request) {
+                        await replyToAgentQuestion(client, ready, options, request, handledQuestionIds);
+                    }
+                    continue;
+                }
+                const idle = event?.type === 'session.idle' || (event?.type === 'session.status' && properties.status?.type === 'idle');
+                if (idle
+                    && (!eventSessionId || eventSessionId === ready.agentSessionId)
+                    && await hasAgentTurnCompleted(client, ready, baselineAssistantState, false))
+                    return;
+                if (event?.type === 'session.error' && (!eventSessionId || eventSessionId === ready.agentSessionId)) {
+                    throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: properties.message || 'Agent 会话执行失败。' });
+                }
+            }
+        }
+        throw new Error('Agent 事件流已结束，但会话尚未进入空闲状态。');
+    }
+    catch (error) {
+        if (controller.signal.aborted) {
+            throw new PlayCraftApiError({ code: 'AGENT_TIMEOUT', message: `Agent 在 ${Math.ceil(timeoutMs / 1000)} 秒内未完成任务。`, retryable: true });
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+        if (!controller.signal.aborted)
+            controller.abort();
+    }
+}
+async function listAgentMessages(client, ready) {
+    const messages = await client.get(`${sessionPath(ready)}/message`);
+    return Array.isArray(messages) ? messages : [];
+}
+function assistantState(messages) {
+    return JSON.stringify(messages.filter((message) => (message.info?.role || message.role) === 'assistant'));
+}
+async function currentAgentSessionStatus(client, ready) {
+    if (!ready.agentEndpoint || !ready.agentSessionId)
+        return undefined;
+    try {
+        const payload = await client.get(`${ready.agentEndpoint}/session/status`);
+        const record = payload && typeof payload === 'object' && !Array.isArray(payload)
+            ? payload
+            : undefined;
+        const direct = record?.[ready.agentSessionId];
+        if (record && direct === undefined)
+            return 'idle';
+        const value = direct?.status ?? direct;
+        return typeof value?.type === 'string' ? value.type : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+async function hasAgentTurnCompleted(client, ready, baselineAssistantState, requireKnownIdle) {
+    const messages = await listAgentMessages(client, ready);
+    if (assistantState(messages) === baselineAssistantState)
+        return false;
+    const status = await currentAgentSessionStatus(client, ready);
+    return status === 'idle' || (!requireKnownIdle && status === undefined);
+}
+async function lastAssistantText(client, ready) {
+    const messages = await listAgentMessages(client, ready);
+    const assistants = messages.filter((message) => (message.info?.role || message.role) === 'assistant');
+    const last = assistants[assistants.length - 1];
+    const text = (last?.parts || []).filter((part) => part.type === 'text' && part.text).map((part) => part.text).join('').trim();
+    return text || undefined;
+}
+async function remixPrompt(options) {
+    const commandName = options.commandName || 'remix.prompt';
+    let client;
+    try {
+        const prompt = readPrompt(options);
+        const imageAttachments = readImageAttachments(options.images);
+        client = createRemixClient(options);
+        const sandbox = await remixEnsureStream({ ...options, interactive: options.interactive ?? false });
+        const ready = await ensureAgentSession(client, sandbox, options);
+        const session = sessionPath(ready);
+        const editorProjectId = await resolveEditorProjectIdBestEffort(client, options.projectId, options);
+        const urls = {
+            editor: editorUrl(client, editorProjectId, options.branch),
+            ...(ready.previewUrl ? { preview: ready.previewUrl } : {}),
+        };
+        emitProgress(options, `[已就绪] Remix 编辑器地址：${urls.editor}`);
+        const pendingQuestions = await listPendingAgentQuestions(client, ready);
+        const handledQuestionIds = new Set();
+        if (pendingQuestions.length) {
+            emitProgress(options, `[恢复中] 检测到 ${pendingQuestions.length} 个待回答问题，不会重复发送原需求。`);
+        }
+        const wait = options.wait !== false;
+        const baselineAssistantState = wait
+            ? assistantState(await listAgentMessages(client, ready))
+            : undefined;
+        let uploadedImageAttachments = [];
+        if (pendingQuestions.length) {
+            if (imageAttachments.length > 0) {
+                emitProgress(options, `[提示] 当前会话有待回答问题，本次 ${imageAttachments.length} 张图片未上传，也不会重复发送原需求。`);
+            }
+            for (const request of pendingQuestions) {
+                await replyToAgentQuestion(client, ready, options, request, handledQuestionIds);
+            }
+        }
+        else {
+            if (imageAttachments.length > 0) {
+                uploadedImageAttachments = await uploadImageAttachments(client, options.projectId, options.branch, imageAttachments);
+            }
+            const promptToSend = buildReferenceImagesPrompt(prompt, uploadedImageAttachments);
+            await client.post(`${session}/prompt_async`, { parts: [{ type: 'text', text: promptToSend }] });
+        }
+        if (baselineAssistantState !== undefined) {
+            await waitForAgentIdle(client, ready, options.timeout * 1000, options, handledQuestionIds, baselineAssistantState);
+        }
+        const assistantText = wait ? await lastAssistantText(client, ready) : undefined;
+        const data = {
+            projectId: options.projectId,
+            branch: options.branch,
+            created: options.created ?? false,
+            ...(options.teamId ? { teamId: options.teamId } : {}),
+            ...(options.templateId ? { templateId: options.templateId } : {}),
+            urls,
+            ...(uploadedImageAttachments.length > 0
+                ? {
+                    attachments: {
+                        images: uploadedImageAttachments.map(({ fileName, sandboxPath }) => ({ fileName, sandboxPath })),
+                    },
+                }
+                : imageAttachments.length > 0 && pendingQuestions.length > 0
+                    ? { attachments: { requestedImages: imageAttachments.length, sentImages: 0, status: 'not_sent_pending_question' } }
+                    : {}),
+            sandbox: { id: ready.sandboxId, slotId: ready.slotId, status: ready.status || 'ready' },
+            agent: { slug: ready.codeAgentSlug, sessionId: ready.agentSessionId, status: wait ? 'completed' : 'running', ...(assistantText ? { lastAssistantText: assistantText } : {}) },
+        };
+        if (options.open)
+            openBrowser(data.urls.editor);
+        if (options.json)
+            console.log(JSON.stringify(resultEnvelope(commandName, client, data)));
+        else
+            console.log(`需求已${wait ? '完成' : '接收'}：${data.urls.editor}`);
+    }
+    catch (error) {
+        handleCommandError(commandName, options, client, error);
+    }
+}
+async function remixRun(options) {
+    let client;
+    try {
+        const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY && !options.json);
+        const requestedImageCount = options.images?.length ?? 0;
+        if (requestedImageCount > 0 && !options.prompt && !options.promptFile && !interactive) {
+            throw new PlayCraftApiError({
+                code: 'ATTACHMENT_PROMPT_REQUIRED',
+                message: '非交互模式使用 --image 时必须同时提供 --prompt 或 --prompt-file。',
+            });
+        }
+        client = createRemixClient(options);
+        let teamId = options.teamId;
+        let templateId = options.templateId;
+        let selectedTemplate;
+        let created = false;
+        if (options.projectId && (options.templateId || options.name || options.teamId)) {
+            throw new PlayCraftApiError({ code: 'AGENT_REQUEST_FAILED', message: '已有 Remix 模式的 --project-id/--branch 不能与 --team-id、--template-id 或 --name 同时使用。' });
+        }
+        if (!options.projectId) {
+            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;
+            }
+            if (!selectedTemplate || !sourceBranch) {
+                throw new PlayCraftApiError({ code: 'TEMPLATE_NOT_FOUND', message: '未选择有效的模板或基础分支。' });
+            }
+            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, // Use the sourceBranch determined above
+                teamId,
+                editorProjectId: selectedTemplate.projectType === 'external' && selectedTemplate.uuid
+                    ? selectedTemplate.uuid
+                    : selectedTemplate.id,
+            });
+            options.projectId = createdRemix.projectId;
+            options.branch = createdRemix.branch;
+            created = true;
+            const createdRemixDetailUrl = remixDetailUrl(client, createdRemix.projectId, createdRemix.branch);
+            if (!options.json) {
+                emitProgress(options, `✓ Remix 创建完成：${createdRemix.displayName || name}`);
+                emitProgress(options, `Remix 详情地址：${createdRemixDetailUrl}`);
+            }
+            let prompt;
+            if (options.prompt || options.promptFile) {
+                prompt = readPrompt(options);
+            }
+            else if (interactive) {
+                const answer = await inquirer.prompt([{
+                        type: 'input',
+                        name: 'prompt',
+                        message: '请输入需求描述（如不需要使用 Agent 生成，请直接回车或输入 exit 退出）：',
+                    }]);
+                if (!isAgentPromptExit(answer.prompt))
+                    prompt = answer.prompt.trim();
+            }
+            if (!prompt) {
+                const data = {
+                    projectId: createdRemix.projectId,
+                    branch: createdRemix.branch,
+                    created: true,
+                    teamId,
+                    templateId,
+                    urls: {
+                        remix: createdRemixDetailUrl,
+                        editor: createdRemix.editorUrl,
+                    },
+                    ...(requestedImageCount > 0
+                        ? { attachments: { requestedImages: requestedImageCount, sentImages: 0, status: 'not_sent' } }
+                        : {}),
+                    agent: { started: false },
                 };
+                if (options.json)
+                    console.log(JSON.stringify(resultEnvelope('remix.run', client, data)));
+                else
+                    emitProgress(options, requestedImageCount > 0
+                        ? '已结束：Remix 已创建，未启动 Agent；所选图片未上传。'
+                        : '已结束：Remix 已创建，未启动 Agent。');
+                return;
             }
-            sepIdx = buffer.indexOf('\n\n');
+            await remixPrompt({ ...options, promptFile: undefined, projectId: options.projectId, branch: options.branch, prompt, wait: options.wait, timeout: options.timeout, open: options.open, commandName: 'remix.run', created, teamId, templateId, interactive });
+            return;
         }
+        if (!options.branch)
+            throw new PlayCraftApiError({ code: 'REMIX_NOT_FOUND', message: '已有 Remix 模式必须同时提供 --project-id 和 --branch。' });
+        const prompt = options.prompt || options.promptFile
+            ? readPrompt(options)
+            : interactive
+                ? (await inquirer.prompt([{ type: 'input', name: 'prompt', message: '请输入需求描述：', validate: (value) => Boolean(value.trim()) || '需求描述不能为空。' }])).prompt.trim()
+                : readPrompt(options);
+        await remixPrompt({ ...options, promptFile: undefined, projectId: options.projectId, branch: options.branch, prompt, wait: options.wait, timeout: options.timeout, open: options.open, commandName: 'remix.run', created, teamId, templateId, interactive });
+    }
+    catch (error) {
+        handleCommandError('remix.run', options, client, error);
     }
-    throw new Error('ensure-stream 结束但未收到 done 事件');
 }
 export function registerRemixCommands(program) {
+    const helpTitles = {
+        'Usage:': '用法：',
+        'Arguments:': '参数：',
+        'Options:': '选项：',
+        'Global Options:': '全局选项：',
+        'Commands:': '命令：',
+    };
     const remix = program
         .command('remix')
-        .description('Remix 工作流命令（JWT 鉴权，调用用户态 API）');
-    remix
-        .command('init-template')
-        .description('Apply engine scaffold (phaser|threejs) to project or bake full templates (maintainer)')
-        .option('--engine <name>', 'Engine adapter: phaser | threejs')
-        .option('--from-atom-tree', 'Read adapter from docs/atom-tree.json meta.engineDecision')
-        .option('--project-dir <path>', 'Project root', process.cwd())
-        .option('--force', 'Replace game/ even when adapter mismatch')
-        .option('--bake', 'Maintainer: write packages/cli/project-templates/{engine}/')
-        .option('--all-engines', 'With --bake: bake phaser and threejs')
-        .action(async (opts) => {
-        await initTemplateCommand({
-            engine: opts.engine,
-            fromAtomTree: Boolean(opts.fromAtomTree),
-            projectDir: String(opts.projectDir || process.cwd()),
-            force: Boolean(opts.force),
-            bake: Boolean(opts.bake),
-            allEngines: Boolean(opts.allEngines),
-        });
-    });
-    remix
-        .command('create')
-        .description('创建 remix 分支（POST /api/projects/:id/branches）')
+        .description('Remix 工作流命令')
+        .helpOption('-h, --help', '显示帮助信息')
+        .helpCommand('help [command]', '显示指定命令的帮助信息')
+        .configureHelp({ styleTitle: (title) => helpTitles[title] || title });
+    remix.command('init-template')
+        .description('应用引擎脚手架或烘焙模板')
+        .option('--engine <name>', '引擎适配器：phaser | threejs')
+        .option('--from-atom-tree', '从 docs/atom-tree.json 读取引擎配置')
+        .option('--project-dir <path>', '项目根目录', process.cwd())
+        .option('--force', '引擎适配器不一致时仍替换 game/ 目录')
+        .option('--bake', '烘焙维护中的项目模板')
+        .option('--all-engines', '烘焙所有引擎模板')
+        .action(async (opts) => initTemplateCommand({ engine: opts.engine, fromAtomTree: Boolean(opts.fromAtomTree), projectDir: String(opts.projectDir || process.cwd()), force: Boolean(opts.force), bake: Boolean(opts.bake), allEngines: Boolean(opts.allEngines) }));
+    remix.command('teams')
+        .description('列出当前登录账号可用的团队')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action((opts) => remixTeams(opts));
+    remix.command('templates')
+        .description('列出项目页中指定团队可见的项目模板')
+        .requiredOption('--team-id <id>', '团队 ID (Identifier, 标识符)')
+        .option('--tag <filter>', '按标签筛选')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action((opts) => remixTemplates(opts));
+    remix.command('create')
+        .description('创建真实的 Remix 分支')
         .requiredOption('--project-id <id>', '项目 ID')
-        .requiredOption('--name <name>', 'remix 分支名（或展示名）')
+        .requiredOption('--name <name>', 'Remix 展示名称')
+        .option('--team-id <id>', '所选团队 ID')
         .option('--source-branch <branch>', '源分支', 'main')
-        .option('--url <url>', '后端基址（默认取登录配置 / PLAYCRAFT_URL）')
-        .option('--token <jwt>', 'JWT token（默认取登录配置 / PLAYCRAFT_TOKEN）')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
         .action(async (opts) => {
-        await remixCreate({
-            projectId: String(opts.projectId),
-            name: String(opts.name),
-            sourceBranch: String(opts.sourceBranch || 'main'),
-            url: opts.url,
-            token: opts.token,
-        });
+        let client;
+        try {
+            client = createRemixClient(opts);
+            const data = await remixCreate({ ...opts, projectId: String(opts.projectId), name: String(opts.name), sourceBranch: String(opts.sourceBranch || 'main') });
+            if (opts.json)
+                console.log(JSON.stringify(resultEnvelope('remix.create', client, data)));
+            else
+                console.log(`Remix 创建成功：${data.editorUrl}`);
+        }
+        catch (error) {
+            handleCommandError('remix.create', opts, client, error);
+        }
     });
-    remix
-        .command('start')
-        .description('启动/复用 remix 沙箱（GET ensure-stream SSE）')
+    remix.command('start')
+        .description('启动或复用 Remix 沙箱')
         .requiredOption('--project-id <id>', '项目 ID')
-        .requiredOption('--branch <name>', '分支名（如 remix/my-branch）')
-        .option('--evict-confirmed', '携带 evictConfirmed=true 重试')
-        .option('--open', 'ready 后自动打开预览地址')
-        .option('--url <url>', '后端基址（默认取登录配置 / PLAYCRAFT_URL）')
-        .option('--token <jwt>', 'JWT token（默认取登录配置 / PLAYCRAFT_TOKEN）')
+        .requiredOption('--branch <name>', 'Remix 分支')
+        .option('--source-branch <branch>', '分支不存在时使用的源分支')
+        .option('--evict-slot-id <id>', '容量已满时要释放的槽位 ID')
+        .option('--evict-confirmed', '确认释放指定槽位')
+        .option('--open', '沙箱就绪后打开编辑器地址')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
         .action(async (opts) => {
-        const ready = await remixEnsureStream({
-            projectId: String(opts.projectId),
-            branch: String(opts.branch),
-            evictConfirmed: Boolean(opts.evictConfirmed),
-            url: opts.url,
-            token: opts.token,
-        });
-        const ttydUrl = getTtydUrl(ready.agentBaseUrl);
-        console.log('Sandbox ready:');
-        console.log(`- sandboxId: ${ready.sandboxId}`);
-        if (ready.previewUrl)
-            console.log(`- previewUrl: ${ready.previewUrl}`);
-        if (ready.agentBaseUrl)
-            console.log(`- agentBaseUrl: ${ready.agentBaseUrl}`);
-        if (ttydUrl)
-            console.log(`- ttydUrl: ${ttydUrl}`);
-        if (opts.open && ready.previewUrl) {
-            openBrowser(ready.previewUrl);
+        let client;
+        try {
+            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}`);
+        }
+        catch (error) {
+            handleCommandError('remix.start', opts, client, error);
         }
     });
+    remix.command('prompt')
+        .description('向当前 Remix 沙箱会话发送需求和参考图片')
+        .requiredOption('--project-id <id>', '项目 ID')
+        .requiredOption('--branch <name>', 'Remix 分支')
+        .option('--prompt <text>', '直接传入需求描述')
+        .option('--prompt-file <path>', '包含需求描述的 UTF-8 (Unicode Transformation Format 8-bit, Unicode 八位转换格式) 文件')
+        .option('--image <path...>', IMAGE_OPTION_HELP)
+        .option('--wait', '等待会话执行完成（默认）')
+        .option('--no-wait', '需求被接收后立即返回')
+        .option('--timeout <seconds>', '等待超时秒数', '1800')
+        .option('--evict-slot-id <id>', '容量已满时要释放的槽位 ID')
+        .option('--evict-confirmed', '确认释放指定槽位')
+        .option('--open', '执行完成后打开编辑器地址')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action((opts) => remixPrompt({ ...opts, images: opts.image, projectId: String(opts.projectId), branch: String(opts.branch), timeout: Math.max(1, Number(opts.timeout) || 1800), interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY && !opts.json) }));
+    remix.command('run')
+        .description('选择模板并创建 Remix，可选向 Agent 发送需求和参考图片')
+        .option('--team-id <id>', '所选团队 ID')
+        .option('--template-id <id>', '项目模板 ID')
+        .option('--project-id <id>', '已有 Remix 的项目 ID')
+        .option('--branch <name>', '已有 Remix 的分支')
+        .option('--name <name>', '新 Remix 的展示名称')
+        .option('--source-branch <branch>', '项目未配置默认分支时使用的源分支', 'main')
+        .option('--prompt <text>', '直接传入需求描述')
+        .option('--prompt-file <path>', '包含需求描述的 UTF-8 (Unicode Transformation Format 8-bit, Unicode 八位转换格式) 文件')
+        .option('--image <path...>', IMAGE_OPTION_HELP)
+        .option('--wait', '等待会话执行完成（默认）')
+        .option('--no-wait', '需求被接收后立即返回')
+        .option('--timeout <seconds>', '等待超时秒数', '1800')
+        .option('--open', '执行完成后打开编辑器地址')
+        .option('--url <url>', SERVICE_ADDRESS_HELP)
+        .option('--token <token>', PAT_HELP)
+        .option('--json', JSON_OUTPUT_HELP)
+        .action((opts) => remixRun({ ...opts, images: opts.image, timeout: Math.max(1, Number(opts.timeout) || 1800) }));
 }