@playcraft/cli 0.0.48 → 0.0.51

package/dist/commands/remix.js

@@ -1,97 +1,414 @@
 import inquirer from 'inquirer';
-import { exec } from 'child_process';
-import { loadGlobalConfig } from '../config.js';
-import { DEFAULT_PLAYCRAFT_CLOUD_BASE } from './login.js';
+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;
-}
-function openBrowser(url) {
-    const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
-    exec(`${cmd} "${url}"`, () => undefined);
+const JSON_OUTPUT_HELP = '输出一条 JSON (JavaScript Object Notation, JavaScript 对象表示法) 结果';
+const SERVICE_ADDRESS_HELP = 'PlayCraft 服务地址';
+const PAT_HELP = 'PAT (Personal Access Token, 个人访问令牌)';
+function emitProgress(options, message) {
+    (options.json ? process.stderr : process.stdout).write(`${message}\n`);
 }
 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,
+            }];
     });
-    if (!res.ok) {
-        const text = await res.text();
-        throw new Error(`创建 remix 失败: ${res.status} ${text}`);
+}
+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;
     }
-    const data = (await res.json());
-    console.log(`Remix 创建成功: ${data.displayName || data.name}`);
-    console.log(`分支: ${data.name}`);
+    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',
+    }));
+}
+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, 千二进制字节) 限制。' });
+    }
+    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;
+        const message = code === 'AUTH_REQUIRED'
+            ? '需要登录。请先运行 `playcraft login`，或提供 PLAYCRAFT_TOKEN。'
+            : code === 'AUTH_EXPIRED'
+                ? '登录已过期，请重新运行 `playcraft login`。'
+                : error instanceof Error ? error.message : String(error);
+        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', {
+            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 (options.evictSlotId)
+        endpoint.searchParams.set('evictSlotId', options.evictSlotId);
+    emitProgress(options, '[连接中] 正在连接沙箱服务...');
+    const response = await fetch(endpoint, {
+        headers: { Authorization: `Bearer ${client.token}`, Accept: 'text/event-stream' },
     });
-    if (!res.ok || !res.body) {
-        const text = await res.text();
-        throw new Error(`ensure-stream 失败: ${res.status} ${text}`);
+    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 +419,524 @@ 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})，但服务端未返回可驱逐候选`);
+                if (!options.interactive) {
+                    throw new PlayCraftApiError({ code: 'SANDBOX_CAPACITY_EXCEEDED', message: `沙箱容量已满（${event.current}/${event.max}），请传入 --evict-slot-id 和 --evict-confirmed。`, details: { candidates: event.candidates } });
                 }
-                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('用户取消操作');
-                }
-                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 fetch(client.url(path), { headers: { Authorization: `Bearer ${client.token}`, Accept: 'text/event-stream' }, signal: controller.signal });
+        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) {
+            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;
+            }
+            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;
+            }
+            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();
+            const createdRemix = await remixCreate({
+                ...options,
+                projectId: selectedTemplate.id,
+                name,
+                sourceBranch: selectedTemplate.sourceBranch || options.sourceBranch,
+                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 {
+            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 } };
+            if (opts.open)
+                openBrowser(data.urls.editor);
+            if (opts.json)
+                console.log(JSON.stringify(resultEnvelope('remix.start', client, data)));
+            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) }));
 }