@qmuse/qmuse-cli 1.0.9-dev.4 → 1.0.10-dev.1

package/dist/cli.js

@@ -7,12 +7,13 @@ import { recordOperation, withOperationLog } from './operation-log.js';
  * 用法见 `qmuse help`。
  */
 import { loadConfig, saveConfig, deleteSession, findConfigPath } from './config.js';
-import { hasAuth } from './client.js';
+import { hasAuth, apiCall } from './client.js';
 import { log } from './logger.js';
 import * as api from './api.js';
 import * as login from './login.js';
 import { prompt, closePrompt } from './login.js';
-import { readFileSync } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { createImportArchive } from './import/archive.js';
@@ -24,16 +25,34 @@ import { resolveUpdateBase } from './import/update.js';
 import { clearPendingImport, completeManagedImport, createExternalProject, importArchitectureProtocol, loadManagedProject, saveManagedProject, resolveProjectEnvironment, setPendingImport, } from './import/project.js';
 import { clearImportFailureDiagnostic, writeImportFailureDiagnostic, importRetryGuidance, } from './import/diagnostic.js';
 import { checkCloudInit, checkCloudEntitlement, CLOUD_INIT_SUCCESS_MESSAGE, resolveCloudAppId, preflightCloudSchema, exportCloudSchema, parseCloudSecrets, setCloudSecrets } from './cloud.js';
+import { cloudEnvironmentStatus, databaseOverview, enableCloudService, localDevContext, retryCloudEnvironment, } from './app/cloud.js';
+import { createDeployTicket, lastDeployTicket, listDeployTickets, parseDeployTicketContent, waitDeployResult, } from './app/release.js';
 import { configurationGuidance } from './import/guidance.js';
-import { QMUSE_CLI_VERSION } from './version.js';
+import { benefitEntitlements, pointBalance, pointConsumeStats, pointRecords, } from './app/account.js';
+import { QMUSE_CLI_VERSION, QMUSE_CLI_NAME, QMUSE_CLI_DISTRIBUTION } from './version.js';
+import { createRecord, deleteRecord, diagnoseRecordParams, getRecord, listRecords, queryAppMetadata, queryFormAuth, syncFormAuth, updateRecord, } from './app/data.js';
+import { cancelChat, uploadAttachment, clearChatContext, continueChat, getChatState, summarizePendingInterrupts, listModels, queryChatByAppIdAndSprintId, } from './app/chat.js';
+import { fetchSourceFiles, listAppVersions } from './app/version.js';
+import { deploymentDetail, executionDetail, functionDetail, listFunctionDeployments, listFunctionExecutions, listFunctions, retryFunctionPublish, } from './app/fn.js';
+import { deleteSecret, disableSecret, enableSecret, listSecrets, retrySecretSync } from './app/secret.js';
+import { buildArtifactsStatus, ensureSandbox, previewHealth, previewInfo, querySandboxSetting, restartPreview, } from './app/sandbox.js';
+import { mkdirSync, writeFileSync, rmSync, statSync, readFileSync } from 'node:fs';
+import { createAppChat, generateCreateRequestId, normalizeAppType, } from './app/create.js';
+import { deleteApp, queryAppInfo, queryAppListBySpaceId, updateApp, } from './app/api.js';
+import { clearAppBinding, loadAppBinding, saveAppBinding, } from './app/binding.js';
 import { startUpdateNotice } from './update-notice.js';
+import { recordEvent, setTelemetryCommand, currentCommandLabel } from './telemetry.js';
+import { trackCommand } from './tracker.js';
+import { buildCliError, sanitizeMessage } from './errors.js';
+import { checkVersionGate, defaultUpgradeCommand, envPolicyProvider, registryPolicyProvider, shouldUpgrade } from './version-gate.js';
+import { installAgentSkill, skillStatus, syncInstalledSkills, defaultTargetForAgent } from './agent-skill.js';
 import { startDevelopment } from './dev/index.js';
 import { createProject } from './create.js';
 import { pullProject } from './pull.js';
 import { withProjectLock } from './project-lock.js';
 // ---------------- 参数解析 ----------------
 const BOOL_FLAGS = new Set([
-    '--help', '-h', '--version', '-V', '--json', '--status',
+    '--help', '-h', '-V', '--json', '--status',
     '--log', '--no-open', '--wait', '--force',
     '--acknowledge-empty-cloud-data',
     '--confirm-cloud-service',
@@ -112,14 +131,52 @@ function output(value, flags) {
     const json = flags['--json'] === true ? JSON.stringify(value, null, 2) : JSON.stringify(value);
     process.stdout.write(`${json}\n`);
 }
-function fail(message) {
-    throw new Error(message);
+/** 结构化 CLI 错误：fail() 可传 code/hint，供 --json 输出与排障使用。 */
+export class CliError extends Error {
+    info;
+    constructor(info) {
+        super(info.message);
+        this.info = info;
+        this.name = 'CliError';
+    }
+}
+function fail(message, options) {
+    if (options?.code) {
+        throw new CliError(buildCliError({
+            errorCode: options.code,
+            errorMessage: sanitizeMessage(message),
+            ...(options.hint ? { hint: options.hint } : {}),
+            ...(options.details ? { details: options.details } : {}),
+        }));
+    }
+    throw new CliError(buildCliError({ errorMessage: sanitizeMessage(message) }));
+}
+/** 统一的「服务端调用失败」出口：自动带 code/hint/traceId，避免 43 处手写模板。 */
+function failApi(r, prefix) {
+    const info = buildCliError({
+        errorCode: r.errorCode,
+        errorMessage: `${prefix}: ${r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`}`,
+        status: r.status,
+        ...(r.traceId ? { traceId: r.traceId } : {}),
+        ...(r.hint ? { hint: r.hint } : {}),
+        ...(r.retryAfterMs !== undefined ? { details: { retryAfterMs: r.retryAfterMs } } : {}),
+    });
+    throw new CliError(info);
 }
 function requireAuth(cfg) {
     if (!hasAuth(cfg)) {
         fail('当前环境未登录。请先运行 `qmuse login`。');
     }
 }
+/** 汇总输出中的软性小节：失败不阻断整体，仅返回 unavailable 原因。 */
+async function sectionOf(run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        return { unavailable: err instanceof Error ? err.message : String(err) };
+    }
+}
 function readPublicConfig(value) {
     if (!value)
         return {};
@@ -275,9 +332,23 @@ async function resolveImportConfiguration(status, cfg, flags, cloudTarget) {
     return configured.data;
 }
 async function finishImport(status, sourceHash, cfg, flags, managedProject, rootDir) {
+    await finishImportWithSync(status, sourceHash, cfg, flags, managedProject, rootDir, undefined);
+}
+/** C04.14：导入结果附带同步反馈（源码变化、远端版本基线与结构化诊断）。 */
+async function finishImportWithSync(status, sourceHash, cfg, flags, managedProject, rootDir, sync) {
     recordOperation('IMPORT_RESULT', { jobId: status.jobId, appId: status.appId, toVersionId: status.versionId,
         status: status.status, stage: status.stage, errorCode: status.failureDiagnostic?.code });
     if (status.status !== 'READY' || !status.appId || !status.versionId) {
+        // T01.18：非 READY 终局补 waiting/failed 事件——服务端未终态（待确认/待配置）与失败分别口径。
+        recordEvent({
+            kind: 'cli.task.state',
+            route: '/api/app-import/status',
+            stage: status.status === 'FAILED' ? 'terminal' : 'waiting',
+            operationId: status.jobId,
+            result: status.status === 'FAILED' ? 'failed' : 'waiting',
+            status: String(status.status ?? '').toLowerCase() || undefined,
+            ...(status.failureDiagnostic?.code ? { errorCode: String(status.failureDiagnostic.code) } : {}),
+        });
         const guidance = configurationGuidance(status, resolveProjectEnvironment(cfg, str(flags, '--env')), parseImportCloudMode(str(flags, '--cloud-mode')));
         if (flags['--json'] === true) {
             output({ success: false, ...status, ...(guidance ? { configurationRequired: guidance } : {}) }, flags);
@@ -335,6 +406,11 @@ async function finishImport(status, sourceHash, cfg, flags, managedProject, root
     }
     if (rootDir)
         await clearImportFailureDiagnostic(rootDir);
+    // T01.05/06：导入任务终态与上传来源（digest 为源码 sha256，不含内容）。
+    recordEvent({ kind: 'cli.transfer.result', route: '/api/app-import/source', result: 'ready',
+        ...(completedSourceHash ? { digest: completedSourceHash } : {}) });
+    recordEvent({ kind: 'cli.task.state', route: '/api/app-import/status', stage: 'READY',
+        operationId: status.jobId, result: 'ok', status: String(status.status ?? '').toLowerCase() || undefined });
     const result = {
         success: true,
         jobId: status.jobId,
@@ -345,6 +421,13 @@ async function finishImport(status, sourceHash, cfg, flags, managedProject, root
         openUrl,
         sourceHash: completedSourceHash,
         operation: status.operation || pending?.operation || (managedProject?.target ? 'UPDATE' : 'CREATE'),
+        sourceChanged: true,
+        ...(sync?.remoteChanged !== undefined ? { remoteChanged: sync.remoteChanged, baseVersionId: sync.baseVersionId } : {}),
+        ...(sync?.fileCount !== undefined ? { fileCount: sync.fileCount } : {}),
+        diagnostics: {
+            assetReport: '.qmuse/asset-preflight.json',
+            ...(status.failureDiagnostic ? { failureDiagnostic: status.failureDiagnostic } : {}),
+        },
         templateCommit: status.templateCommit,
         importerVersion: status.importerVersion,
         assetCount: status.assetCount,
@@ -524,6 +607,10 @@ async function cmdImport(command, flags) {
             appId: managedProject.target.appId,
             versionId: managedProject.target.lastVersionId,
             sourceHash: preflight.sourceHash,
+            sourceChanged: false,
+            remoteChanged: updateBase?.remoteChanged === true,
+            ...(updateBase ? { baseVersionId: updateBase.baseVersionId } : {}),
+            fileCount: preflight.fileCount,
             openUrl: getAppOpenUrl(cfg.webBaseUrl, managedProject.target.appId),
         };
         if (flags['--json'] === true)
@@ -619,7 +706,11 @@ async function cmdImport(command, flags) {
         process.exitCode = 130;
         return;
     }
-    await finishImport(polled.status, preflight.sourceHash, cfg, flags, managedProject, rootDir);
+    await finishImportWithSync(polled.status, preflight.sourceHash, cfg, flags, managedProject, rootDir, {
+        remoteChanged: updateBase?.remoteChanged,
+        baseVersionId: updateBase?.baseVersionId,
+        fileCount: preflight.fileCount,
+    });
 }
 async function cmdCloud(command, flags) {
     const subcommand = command[1];
@@ -663,8 +754,88 @@ async function cmdCloud(command, flags) {
             process.exitCode = 1;
         return;
     }
+    if (['enable', 'status', 'pull-env'].includes(subcommand ?? '') || (subcommand === 'environment' && command[2] === 'retry')) {
+        const cfg = resolveCfg(flags);
+        requireAuth(cfg);
+        const appId = await resolveCloudAppId(process.cwd(), cfg, str(flags, '--env'), str(flags, '--app-id'));
+        if (subcommand === 'enable') {
+            // C14.02：复用既有开通服务与权益判断，返回真实资源与初始化状态。
+            const [enabled, entitlement] = await Promise.all([
+                enableCloudService(appId, cfg),
+                checkCloudEntitlement({ appId, spaceId: cfg.spaceId ?? "" }, cfg).then(v => v).catch(err => ({
+                    unavailable: err instanceof Error ? err.message : String(err),
+                })),
+            ]);
+            if (!enabled.ok || !enabled.data)
+                fail(`开通云服务失败: ${enabled.errorMessage ?? enabled.errorCode ?? `HTTP ${enabled.status}`}`);
+            // T01.08：云资源开通任务来源。
+            recordEvent({ kind: 'cli.task.state', route: '/api/appwrite/cloud/storage/enable', stage: 'enabled', result: 'ok' });
+            output({ appId, activation: enabled.data, entitlement }, flags);
+            return;
+        }
+        if (subcommand === 'status') {
+            // C14.03：集中展示架构、实际云环境、初始化状态、公开资源与权益/失败原因。
+            const [status, entitlement] = await Promise.all([
+                cloudEnvironmentStatus(appId, cfg),
+                checkCloudEntitlement({ appId, spaceId: cfg.spaceId ?? "" }, cfg).then(v => v).catch(err => ({
+                    unavailable: err instanceof Error ? err.message : String(err),
+                })),
+            ]);
+            if (!status.ok || !status.data)
+                fail(`查询云状态失败: ${status.errorMessage ?? status.errorCode ?? `HTTP ${status.status}`}`);
+            const data = status.data;
+            if (data.activationStatus === 'NOT_ENABLED') {
+                output({ appId, ...data, entitlement, hint: '云服务未开通：执行 qmuse cloud enable' }, flags);
+                return;
+            }
+            output({ appId, ...data, entitlement }, flags);
+            return;
+        }
+        if (subcommand === 'environment' && command[2] === 'retry') {
+            // C14.08：复用平台既有重试动作（幂等 + 分布式锁），不以新建资源替代原任务恢复。
+            const r = await retryCloudEnvironment(appId, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `重试云环境初始化失败`);
+            let current = r.data;
+            if (flags['--wait'] === true) {
+                const deadline = Date.now() + 5 * 60 * 1000;
+                while (!['ACTIVE', 'PENDING_FIRST_PUBLISH', 'INITIALIZATION_FAILED'].includes(String(current.activationStatus))) {
+                    if (Date.now() > deadline) {
+                        current = { ...current, timedOut: true };
+                        break;
+                    }
+                    await new Promise(resolve => setTimeout(resolve, 5000));
+                    const q = await cloudEnvironmentStatus(appId, cfg);
+                    if (q.ok && q.data)
+                        current = q.data;
+                }
+            }
+            output({ appId, ...current }, flags);
+            if (['INITIALIZATION_FAILED', 'NOT_ENABLED'].includes(String(current.activationStatus)))
+                process.exitCode = 1;
+            return;
+        }
+        if (subcommand === 'pull-env') {
+            // C14.09：导出实际环境公开连接与运行配置（不含管理凭证），供本地运行上下文复用。
+            const outPath = str(flags, '--output');
+            const r = await localDevContext(appId, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `查询本地开发上下文失败`);
+            const context = r.data;
+            const resolved = outPath ? path.resolve(outPath.replace(/^\$HOME(?=\/|$)/u, homedir())) : undefined;
+            if (resolved) {
+                mkdirSync(path.dirname(resolved), { recursive: true });
+                writeFileSync(resolved, `${JSON.stringify(context, null, 2)}\n`, { mode: 0o600 });
+                output({ success: true, appId, output: resolved, context }, flags);
+            }
+            else {
+                output({ appId, context }, flags);
+            }
+            return;
+        }
+    }
     if (subcommand !== 'init') {
-        fail(`未知 cloud 子命令: ${subcommand ?? '(空)'}。可用: init、set-secret、schema preflight、schema export`);
+        fail(`未知 cloud 子命令: ${subcommand ?? '(空)'}。可用: init、enable、status、environment retry、pull-env、set-secret、schema preflight、schema export`);
     }
     if (!str(flags, '-d')?.trim()) {
         fail('用法: qmuse cloud init -d "<应用功能描述>"');
@@ -679,7 +850,216 @@ async function cmdCloud(command, flags) {
     process.stdout.write(`${CLOUD_INIT_SUCCESS_MESSAGE}\n`);
 }
 // ---------------- 命令实现 ----------------
+/** 摘要发布单关键信息（发布/预览地址、安全检查、域名发布状态）——typed 契约解析。 */
+function summarizeDeployTicket(ticket) {
+    if (!ticket)
+        return { ticket: null };
+    // query/list/last 返回带 content 字段；create 响应直接展开 content 字段。
+    const content = ticket.content !== undefined
+        ? parseDeployTicketContent(ticket)
+        : ticket;
+    const domainPublication = content.domainPublication;
+    const base = ticket;
+    return {
+        deployId: base.id,
+        appId: base.appId,
+        versionId: content.versionId,
+        status: base.status,
+        publishUrl: domainPublication?.appPath ?? domainPublication?.url ?? domainPublication?.publishedUrl,
+        previewUrl: content.preview_snapshot_url ?? content.previewThumbUrl,
+        infosecStatus: content.infosecStatus ?? undefined,
+        infosecResult: !content.infosecResult || content.infosecResult === null ? undefined : content.infosecResult,
+        mosecStatus: content.mosecScan?.status,
+        domainPublication,
+        updatedAt: ticket.updatedAt ?? ticket.gmtModified ?? undefined,
+    };
+}
+async function cmdDeploy(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    if (command.length > 1)
+        fail('用法: qmuse deploy --version <versionId> [--app-id <appId>] [--no-wait] [--json]');
+    const versionId = pickString(flags, '--version') ?? pickString(flags, '--version-id');
+    if (!versionId)
+        fail('用法: qmuse deploy --version <versionId> [--app-id <appId>] [--no-wait]');
+    const binding = loadAppBinding(process.cwd());
+    const appId = pickString(flags, '--app-id') ?? binding?.appId;
+    if (!appId)
+        fail('未指定应用：传 --app-id <appId> 或先执行 qmuse app use <appId>');
+    const created = await createDeployTicket(appId, versionId, cfg);
+    if (!created.ok || !created.data)
+        fail(`创建发布单失败: ${created.errorMessage ?? created.errorCode ?? `HTTP ${created.status}`}`);
+    const seed = created.data;
+    const deployId = String(seed['id'] ?? '');
+    // T01.08：发布受理来源（安全门禁/产物准备在服务端执行，同一 releaseId 可继续查询）。
+    recordEvent({ kind: 'cli.task.state', route: '/api/deploy/create', stage: 'accepted',
+        operationId: deployId || undefined, result: 'ok' });
+    const wait = await waitDeployResult(deployId, cfg, { noWait: flags['--no-wait'] === true });
+    const payload = {
+        success: !wait.timedOut,
+        appId,
+        versionId,
+        deployId: deployId || undefined,
+        timedOut: wait.timedOut || undefined,
+        error: wait.lastError,
+        ...summarizeDeployTicket(wait.ticket ?? seed),
+    };
+    if (flags['--json'] === true) {
+        output(payload, flags);
+    }
+    else {
+        if (wait.lastError)
+            log.error(`查询发布结果失败: ${wait.lastError}`);
+        log.info(`发布单 ${deployId}（appId=${appId} versionId=${versionId}）状态：${payload.status ?? 'UNKNOWN'}`);
+        if (payload.publishUrl)
+            log.success(`发布地址：${String(payload.publishUrl)}`);
+        if (payload.timedOut)
+            log.info('等待超时：使用 qmuse release status <releaseId> 继续查询');
+        else if (!flags['--no-wait'])
+            log.info('继续查询：qmuse release status ' + deployId);
+    }
+    if (wait.timedOut || payload.status === 'DEPLOY_FAILED' || payload.status === 'CANCEL')
+        process.exitCode = 1;
+    // T01.08：发布终态来源（receipt 由服务端任务记录，这里保留 CLI 端可观测尾部）。
+    recordEvent({ kind: 'cli.task.state', route: '/api/deploy/query', stage: 'terminal',
+        operationId: deployId || undefined, status: wait.timedOut ? 'timeout' : String(payload.status ?? 'unknown').toLowerCase(),
+        result: wait.timedOut ? 'timeout' : payload.status === 'DEPLOYED' ? 'ok' : 'failed',
+    });
+}
+async function cmdRelease(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    if (sub === 'status') {
+        const releaseId = command[2] || pickString(flags, '--release-id') || pickString(flags, '--id');
+        if (!releaseId)
+            fail('用法: qmuse release status <releaseId> [--wait] 或 qmuse release status --last --app-id <appId>');
+        const wait = await waitDeployResult(releaseId, cfg, { noWait: flags['--wait'] !== true });
+        const summary = summarizeDeployTicket(wait.ticket);
+        const lookupFailed = !wait.ticket;
+        if (flags['--json'] === true) {
+            output({ success: !wait.timedOut && !lookupFailed && summary.status !== 'DEPLOY_FAILED' && summary.status !== 'CANCEL', timedOut: wait.timedOut || undefined, error: wait.lastError, ...summary }, flags);
+            return;
+        }
+        log.info(`发布单 ${releaseId} 状态：${String(summary.status ?? 'UNKNOWN')}${wait.timedOut ? '（等待超时）' : ''}`);
+        if (summary.publishUrl)
+            log.success(`发布地址：${String(summary.publishUrl)}`);
+        process.exitCode = wait.timedOut || summary.status === 'DEPLOY_FAILED' || summary.status === 'CANCEL' ? 1 : 0;
+        return;
+    }
+    if (sub === 'list') {
+        let appId = pickString(flags, '--app-id') ?? loadAppBinding(process.cwd())?.appId;
+        if (!appId)
+            fail('用法: qmuse release list --app-id <appId>');
+        if (flags['--last'] === true) {
+            const r = await lastDeployTicket(appId, cfg);
+            if (!r.ok)
+                failApi(r, `查询最近发布失败`);
+            output(summarizeDeployTicket(r.data), flags);
+            return;
+        }
+        const r = await listDeployTickets(appId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询发布记录失败`);
+        // 防御性兼容：老网关可能返回包装对象而非数组，运行时仍做数组判定。
+        const payload = r.data;
+        const list = Array.isArray(payload)
+            ? payload.map(item => summarizeDeployTicket(item))
+            : payload;
+        output({ appId, releases: list }, flags);
+        return;
+    }
+    fail(`未知 release 子命令: ${sub ?? '(空)'}。可用: status <releaseId> [--wait]、list --app-id <appId>`);
+}
+function devStatePath() {
+    return path.join(process.cwd(), '.qmuse', 'dev.json');
+}
+function writeDevState(state, _root) {
+    mkdirSync(path.dirname(devStatePath()), { recursive: true });
+    writeFileSync(devStatePath(), JSON.stringify(state, null, 2), 'utf8');
+}
+function readDevState() {
+    try {
+        const parsed = JSON.parse(readFileSync(devStatePath(), 'utf8'));
+        return parsed?.schemaVersion === 1 && typeof parsed.ppid === 'number' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function devProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+async function cmdDevSession(sub, flags) {
+    const state = readDevState();
+    const running = state && devProcessAlive(state.ppid);
+    if (sub === 'status') {
+        if (!state) {
+            output({ running: false, reason: 'no-session-file' }, flags);
+            return;
+        }
+        if (!running) {
+            output({ running: false, reason: 'stale-session', pid: state.ppid }, flags);
+            return;
+        }
+        output({
+            running: true,
+            pid: state.ppid,
+            appId: state.appId,
+            port: state.port,
+            env: state.env,
+            startedAt: state.startedAt,
+            localUrl: `http://127.0.0.1:${state.port}/`,
+        }, flags);
+        return;
+    }
+    if (sub === 'stop') {
+        if (!state || !running) {
+            if (state)
+                rmSync(devStatePath(), { force: true });
+            if (flags['--json'] === true)
+                output({ stopped: false, reason: 'not-running' }, flags);
+            else
+                log.warn('当前目录没有运行中的 qmuse dev 会话');
+            return;
+        }
+        try {
+            process.kill(state.ppid, 'SIGTERM');
+        }
+        catch { /* 已退出 */ }
+        for (let waited = 0; waited < 8000 && devProcessAlive(state.ppid); waited += 200) {
+            await new Promise(resolve => setTimeout(resolve, 200));
+        }
+        if (devProcessAlive(state.ppid)) {
+            try {
+                process.kill(state.ppid, 'SIGKILL');
+            }
+            catch { /* 忽略 */ }
+        }
+        rmSync(devStatePath(), { force: true });
+        if (flags['--json'] === true)
+            output({ stopped: true, pid: state.ppid, appId: state.appId }, flags);
+        else
+            log.success(`开发会话已停止（pid=${state.ppid}，appId=${state.appId}）`);
+        return;
+    }
+    fail(`未知 dev 子命令: ${sub}。可用: status / stop`);
+}
 async function cmdDev(command, flags) {
+    const sub = command[1];
+    if (sub === 'status' || sub === 'stop') {
+        await cmdDevSession(sub, flags);
+        return;
+    }
+    await cmdDevRun(command, flags);
+}
+async function cmdDevRun(command, flags) {
     const cfg = resolveCfg(flags);
     requireAuth(cfg);
     if (flags['--port'] !== undefined && typeof flags['--port'] !== 'string')
@@ -704,6 +1084,14 @@ async function cmdDev(command, flags) {
             log.warn('当前为单环境应用，开发云资源可能与正式页面共用。');
         development.server.printUrls();
     }
+    writeDevState({
+        schemaVersion: 1,
+        ppid: process.pid,
+        appId: development.context.appId,
+        port,
+        env: typeof flags['--env'] === 'string' ? flags['--env'] : 'default',
+        startedAt: new Date().toISOString(),
+    }, process.cwd());
     await new Promise(resolve => {
         const stop = () => {
             process.off('SIGINT', stop);
@@ -750,7 +1138,7 @@ async function cmdWhoami(flags) {
                 log.info(`本地空间 : ${cfg.spaceId}`);
             return;
         }
-        fail(`查询当前用户失败: ${result.errorMessage ?? result.errorCode ?? `HTTP ${result.status}`}`);
+        failApi(result, '查询当前用户失败');
     }
     const currentUser = result.data;
     const tenantName = tenantDisplayName(currentUser.tenantCode, currentUser.tenantName);
@@ -804,7 +1192,7 @@ async function cmdSpace(command, flags) {
         // 空间发现接口不携带当前空间，确保账号切换后仍能列出新账号的空间。
         const r = await api.listSpaces(num(flags, '--page-index', 1), num(flags, '--page-size', 20), { ...cfg, spaceId: undefined });
         if (!r.ok || !r.data)
-            fail(`查询空间失败: ${r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`}`);
+            failApi(r, `查询空间失败`);
         if (flags['--json'] === true) {
             output(r.data, flags);
             return;
@@ -821,160 +1209,1739 @@ async function cmdSpace(command, flags) {
         const spaceId = command[2] || str(flags, '--space-id');
         if (!spaceId)
             fail('用法: qmuse space use <spaceId>');
+        // 保存前先校验该空间当前账号可访问（C02.02）：探测失败不写入默认选择。
+        const probe = { ...cfg, spaceId };
+        const access = await api.spaceInfo(probe);
+        if (!access.ok || !access.data) {
+            fail(`空间 ${spaceId} 不可用：${access.errorMessage ?? access.errorCode ?? `HTTP ${access.status}`}；默认空间选择未变更`);
+        }
+        const spaceName = access.data?.cnName;
         const next = { ...cfg, spaceId };
         saveConfig(next, true);
-        log.success(`已设为当前空间 spaceId=${spaceId}（后续请求带 x-space-id 头）`);
+        log.success(`已设为当前空间 spaceId=${spaceId}${spaceName ? `（${spaceName}）` : ''}（后续请求带 x-space-id 头）`);
         return;
     }
     if (sub === 'info') {
         const r = await api.spaceInfo(cfg);
         if (!r.ok)
-            fail(`查询当前空间失败: ${r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`}`);
+            failApi(r, `查询当前空间失败`);
         output(r.data, flags);
         return;
     }
     fail(`未知 space 子命令: ${sub ?? '(空)'}。可用: list / use <spaceId> / info`);
 }
-async function cmdLogin(flags) {
-    const cfg = resolveCfg(flags);
-    if (flags['--status'] === true) {
-        const out = await login.loginStatus(cfg);
-        if (out.success)
-            log.success(out.message ?? '会话有效');
-        else
-            log.error(out.message ?? '会话无效');
-        return;
+// ---------------- 统一创建 ----------------
+/** 读取首条创作内容：--file <路径|-> 或标准输入（管道）；TTY 下要求显式 --file。 */
+async function readCreateContent(flags) {
+    const file = str(flags, '--file');
+    if (file && file !== '-') {
+        try {
+            return readFileSync(path.resolve(file), 'utf8');
+        }
+        catch (err) {
+            throw new Error(`无法读取 --file：${err instanceof Error ? err.message : String(err)}`);
+        }
     }
-    log.info(`登录方式：browser    目标：${cfg.baseUrl}${cfg.apiPrefix || ''}`);
-    const out = await login.loginBrowser(cfg, {
-        logRequestDetails: flags['--log'] === true,
-    });
-    if (out.success) {
-        login.closePrompt();
-        log.success(`登录成功（${out.method}）`);
-        if (flags['--json'] === true)
-            output({ success: true, method: out.method }, flags);
+    if (!file && process.stdin.isTTY === true) {
+        fail('用法: qmuse app create <web|h5> --file <路径|->（--file - 从管道读取）');
     }
-    else {
-        login.closePrompt();
-        fail(out.message ?? '登录失败');
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
     }
+    return Buffer.concat(chunks).toString('utf8');
 }
-async function cmdLogout(flags) {
-    const cfg = resolveCfg(flags);
-    const hadSession = !!(cfg.sessionId || '').trim();
-    deleteSession(cfg);
-    if (hadSession) {
-        log.success('已清除当前环境的登录态和空间选择');
+/** 标题缺省时从内容首个非空行推导（去 markdown 标记，截断 40 字符）。 */
+function deriveCreateTitle(content) {
+    const line = content
+        .split('\n')
+        .map(item => item.trim())
+        .find(Boolean) ?? '';
+    const cleaned = line.replace(/^#+\s*/u, '').replace(/[*`_\[\]]/gu, '').trim();
+    const title = [...cleaned].slice(0, 40).join('');
+    return title || '未命名应用';
+}
+function createAppOpenUrl(cfg, appId) {
+    if (!appId)
+        return '';
+    try {
+        return getAppOpenUrl(cfg.webBaseUrl, appId);
     }
-    else {
-        log.info('当前未配置登录态；已清除空间选择');
+    catch {
+        return '';
     }
 }
-// ---------------- 帮助 & 入口 ----------------
-async function cmdCreate(command, flags) {
-    if (command.length !== 2)
-        fail('用法：qmuse create <directory>');
-    const result = await createProject(command[1], resolveCfg(flags));
+function printAppCreateResult(result, openUrl, flags) {
     if (flags['--json'] === true) {
-        output(result, flags);
+        const success = result.status === 'SUCCEEDED' || result.status === 'REUSED' || result.status === 'WAITING_INPUT';
+        output({
+            schemaVersion: 1,
+            success,
+            status: result.status,
+            data: {
+                ...(result.identity.appId ? { appId: result.identity.appId } : {}),
+                ...(result.identity.chatId ? { chatId: result.identity.chatId } : {}),
+                ...(result.identity.sprintId ? { sprintId: result.identity.sprintId } : {}),
+                ...(result.versionId ? { versionId: result.versionId } : {}),
+                ...(openUrl ? { openUrl } : {}),
+                reused: result.reused,
+                requestId: result.requestId,
+                messageId: result.messageId,
+                ...(result.created ? { created: result.created } : {}),
+            },
+            ...(result.errorText ? { errorText: result.errorText } : {}),
+            ...(result.errorCode ? { errorCode: result.errorCode } : {}),
+            ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
+            ...(result.traceId ? { traceId: result.traceId } : {}),
+        }, flags);
+    }
+    else {
+        switch (result.status) {
+            case 'REUSED':
+                log.success(`该请求此前已受理：appId=${result.identity.appId}，已恢复身份，未重复创建或重新生成`);
+                if (openUrl)
+                    log.raw(`${openUrl}\n`);
+                break;
+            case 'SUCCEEDED':
+                log.success('应用创建完成，首轮生成已结束');
+                if (openUrl)
+                    log.raw(`${openUrl}\n`);
+                break;
+            case 'WAITING_INPUT':
+                log.warn('首轮生成在等待输入；请打开作品页继续，或用相同 --request-id 重新查询状态');
+                if (openUrl)
+                    log.raw(`${openUrl}\n`);
+                break;
+            case 'INTERRUPTED':
+                log.warn('已停止本地等待，服务端生成仍会继续；应用身份已保留');
+                if (result.identity.appId)
+                    log.raw(`${openUrl}\n`);
+                break;
+            default:
+                log.error(`创建失败：${result.errorText ?? result.errorMessage ?? '未知错误'}`);
+                if (result.identity.appId) {
+                    log.warn(`应用已创建（${openUrl}），生成失败可认为首轮未完成，请勿将本次计为成功`);
+                }
+        }
+    }
+}
+async function cmdApp(command, flags) {
+    const sub = command[1];
+    if (sub === 'create') {
+        await cmdAppCreate(command, flags);
         return;
     }
-    log.success(`模板已下载到 ${result.directory}`);
-    log.info('进入项目目录后执行：npm install');
-    log.info(`开发完成后执行：qmuse${str(flags, '--env') ? ` --env ${str(flags, '--env')}` : ''} import .`);
+    await cmdAppManage(sub, command, flags);
 }
-const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
-
-用法:
-  qmuse [global flags] <command> [subcommand] [flags]
-
-全局 flags:
-  --env <env>           环境预设：prod / pre / local
-  --json                结果以 JSON 输出
-  --log                 打印登录请求接口和页面地址（不含登录凭证）
-
-  全局 flags 可放在命令前或命令后
-
-命令:
-  whoami                                            查看当前环境、登录和空间状态
-  login [--status] [--log] [--json]                 通过 QMuse 网页登录
-  logout                                            清除保存的登录态和空间选择
-  config [get|path]                                 查看配置
-
-  create <directory>                               下载 QMuse 模板并解压到新项目目录
-  pull [directory]                                 免费同步已导入应用的最新已保存源码（本地有改动时停止）
-
-  cloud init -d "<应用功能描述>"                    校验当前空间的 QMuse 云服务权益
-  cloud set-secret KEY1,KEY2 --stdin                从标准输入 JSON 保存密钥，不输出密钥值
-      [--app-id <id>] [--cloud-env dev|prod]
-  cloud schema preflight --candidate <schema.json>  只读校验候选与云端 READY 基线
-  cloud schema export [--app-id <id>]               输出当前开发环境的 READY schema
-  dev [directory] [--port <port>]                   连接已导入应用的开发云资源并启动本地 Vite
-
-  assets upload <file> [more-files...] --json      上传媒体到 CDN，返回引用替换清单
-  import <directory> [--space-id <id>]             导入本地 React 仓库
-      [--title <title>] [--force] [--cloud-mode AUTO|EXTERNAL|QMUSE]
-      [--public-config '<json>'|@file] [--acknowledge-empty-cloud-data]
-      [--confirm-cloud-service]
-      [--no-open] [--json] [--log]
-  import status <jobId> [--wait] [--no-open]        查询或恢复等待导入任务
-  import configure <jobId> --cloud-mode <mode>      补充云服务配置后继续任务
-
-  space list                                        我加入的空间列表
-  space use <spaceId>                               设为当前空间（后续带 x-space-id 头）
-  space info                                        当前空间信息
-
-典型流程:
-  qmuse login
-  qmuse space list
-  qmuse space use S640459450135
-  qmuse create my-app
-  qmuse import /path/to/react-vite-app
-`;
-async function main() {
-    const argv = process.argv.slice(2);
-    if (argv.length === 0) {
-        process.stdout.write(HELP);
+function printAppLine(app) {
+    log.raw(`${app.appId}  ${(app.appType ?? '').padEnd(9)} ${(app.status ?? '').padEnd(10)} ${app.title ?? ''}\n`);
+}
+async function cmdAppManage(sub, command, flags) {
+    const cfg = resolveCfg(flags);
+    const appIdArg = command[2] || str(flags, '--app-id') || '';
+    if (sub === 'list') {
+        requireAuth(cfg);
+        const spaceId = str(flags, '--space-id') || cfg.spaceId;
+        if (!spaceId)
+            fail('请先执行 qmuse space use <spaceId> 或传 --space-id');
+        const r = await queryAppListBySpaceId(spaceId, {
+            pageIndex: num(flags, '--page-index', 1),
+            pageSize: num(flags, '--page-size', 20),
+            searchKeyword: str(flags, '--keyword'),
+        }, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询应用列表失败`);
+        if (flags['--json'] === true) {
+            output(r.data, flags);
+            return;
+        }
+        log.info(`空间 ${spaceId} 共 ${r.data.total} 个应用：`);
+        for (const app of r.data.list)
+            printAppLine(app);
         return;
     }
-    const { command, flags } = parseArgs(argv);
-    if (flags['--help'] === true || flags['-h'] === true) {
-        process.stdout.write(HELP);
+    if (sub === 'info') {
+        requireAuth(cfg);
+        if (!appIdArg)
+            fail('用法: qmuse app info <appId>');
+        const r = await queryAppInfo(appIdArg, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询应用信息失败`);
+        output(r.data, flags);
         return;
     }
-    if (flags['--version'] === true || flags['-V'] === true) {
-        process.stdout.write(`qmuse ${QMUSE_CLI_VERSION}\n`);
+    if (sub === 'use') {
+        requireAuth(cfg);
+        if (!appIdArg)
+            fail('用法: qmuse app use <appId>');
+        const info = await queryAppInfo(appIdArg, cfg);
+        if (!info.ok || !info.data) {
+            fail(`应用不可用：${info.errorMessage ?? info.errorCode ?? `HTTP ${info.status}`}；本地绑定未变更`);
+        }
+        const path = saveAppBinding({
+            appId: appIdArg,
+            ...(cfg.spaceId ? { spaceId: cfg.spaceId } : {}),
+            ...(typeof info.data.title === 'string' ? { title: info.data.title } : {}),
+            apiOrigin: cfg.baseUrl,
+        });
+        log.success(`已绑定应用 ${appIdArg}${info.data.title ? `（${info.data.title}）` : ''}，绑定记录 ${path}`);
         return;
     }
-    const root = command[0];
-    const finishUpdateNotice = startUpdateNotice({
-        enabled: root === 'import' && process.stderr.isTTY === true && flags['--json'] !== true,
-        notify: message => process.stderr.write(`${message}\n`),
-    });
-    process.once('exit', finishUpdateNotice);
-    try {
-        switch (root) {
-            case 'whoami':
-                await cmdWhoami(flags);
-                return;
-            case 'login':
-                await cmdLogin(flags);
-                return;
-            case 'logout':
-                await cmdLogout(flags);
-                return;
-            case 'config':
-                await cmdConfig(command, flags);
-                return;
-            case 'create':
-                await cmdCreate(command, flags);
-                return;
-            case 'pull': {
-                if (command.length > 2 || Object.keys(flags).some(key => !['--env', '--json'].includes(key))) {
-                    throw new Error('用法：qmuse pull [directory] [--env prod|pre|local] [--json]');
-                }
-                const result = await withOperationLog({ directory: command[1] || '.', command: 'pull',
+    if (sub === 'current') {
+        const binding = loadAppBinding();
+        if (!binding) {
+            fail('当前目录没有应用绑定；使用 qmuse app use <appId> 或 qmuse import <dir> 建立');
+        }
+        if (flags['--json'] === true)
+            output(binding, flags);
+        else {
+            log.info(`当前目录绑定应用：${binding.appId}${binding.title ? `（${binding.title}）` : ''}`);
+            if (binding.spaceId)
+                log.info(`绑定空间：${binding.spaceId}`);
+            if (binding.apiOrigin)
+                log.info(`绑定环境：${binding.apiOrigin}`);
+        }
+        return;
+    }
+    if (sub === 'unlink') {
+        const removed = clearAppBinding();
+        if (!removed) {
+            log.warn('当前目录没有应用绑定，无需解除');
+            return;
+        }
+        log.success('已解除当前目录的应用绑定');
+        return;
+    }
+    if (sub === 'update') {
+        requireAuth(cfg);
+        if (!appIdArg)
+            fail('用法: qmuse app update <appId> [--title <t>] [--description <d>] [--require-login 0|1] [ --default-device <d>]');
+        const patch = {
+            ...(str(flags, '--title') ? { title: str(flags, '--title') } : {}),
+            ...(flags['--description'] !== undefined ? { description: str(flags, '--description') } : {}),
+            ...(str(flags, '--require-login') !== undefined ? { requireLogin: Number(str(flags, '--require-login')) } : {}),
+            ...(str(flags, '--default-device') ? { defaultDevice: str(flags, '--default-device') } : {}),
+        };
+        try {
+            const r = await updateApp(appIdArg, patch, cfg);
+            if (!r.ok)
+                failApi(r, `更新应用失败`);
+            if (flags['--json'] === true)
+                output({ success: true, appId: appIdArg, ...patch }, flags);
+            else
+                log.success(`应用 ${appIdArg} 信息已更新`);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+        return;
+    }
+    if (sub === 'delete') {
+        requireAuth(cfg);
+        if (!appIdArg)
+            fail('用法: qmuse app delete <appId> --yes');
+        if (flags['--yes'] !== true)
+            fail('删除应用不可恢复：请显式传入 --yes 确认');
+        const r = await deleteApp(appIdArg, cfg);
+        if (!r.ok)
+            failApi(r, `删除应用失败`);
+        if (loadAppBinding()?.appId === appIdArg)
+            clearAppBinding();
+        if (flags['--json'] === true)
+            output({ success: true, deleted: true, appId: appIdArg }, flags);
+        else
+            log.success(`应用 ${appIdArg} 已删除`);
+        return;
+    }
+    fail(`未知 app 子命令: ${sub ?? '(空)'}。可用: create / list / info / use / current / unlink / update / delete`);
+}
+async function cmdAppCreate(command, flags) {
+    const typeArg = command[2] && !command[2].startsWith('-')
+        ? command[2]
+        : str(flags, '--type');
+    const appType = normalizeAppType(typeArg);
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const spaceId = str(flags, '--space-id') || cfg.spaceId || '';
+    const content = await readCreateContent(flags);
+    const title = str(flags, '--title') || deriveCreateTitle(content);
+    const operationId = `op_${randomBytes(12).toString('hex')}`;
+    const abortController = new AbortController();
+    const onInterrupt = () => abortController.abort();
+    process.once('SIGINT', onInterrupt);
+    let announcedStream = false;
+    let announcedInterrupt = false;
+    const result = await createAppChat(cfg, {
+        requestId: str(flags, '--request-id') || generateCreateRequestId(),
+        appType,
+        spaceId,
+        title,
+        content,
+        ...(str(flags, '--model') ? { selectedModel: str(flags, '--model') } : {}),
+    }, {
+        signal: abortController.signal,
+        onEvent: ({ sequence, type }) => {
+            if (flags['--ndjson'] === true) {
+                process.stdout.write(`${JSON.stringify({
+                    schemaVersion: 1,
+                    type: 'event',
+                    sequence,
+                    operationId,
+                    eventType: type,
+                })}\n`);
+                return;
+            }
+            if (flags['--json'] === true)
+                return;
+            if (sequence === 1 && !announcedStream) {
+                announcedStream = true;
+                log.info('已连接首轮生成流...');
+            }
+            if (type.startsWith('data-graph') && !announcedInterrupt) {
+                announcedInterrupt = true;
+                log.warn('检测到等待输入的生成帧');
+            }
+        },
+    });
+    process.removeListener('SIGINT', onInterrupt);
+    if (flags['--ndjson'] === true) {
+        process.stdout.write(`${JSON.stringify({
+            schemaVersion: 1,
+            type: 'result',
+            sequence: (result.eventCount ?? 0) + 1,
+            operationId,
+            result: {
+                status: result.status,
+                appId: result.identity.appId || undefined,
+                chatId: result.identity.chatId || undefined,
+                sprintId: result.identity.sprintId || undefined,
+                versionId: result.versionId,
+                reused: result.reused,
+                requestId: result.requestId,
+                ...(result.errorText ? { errorText: result.errorText } : {}),
+            },
+        })}\n`);
+    }
+    else {
+        printAppCreateResult(result, createAppOpenUrl(cfg, result.identity.appId), flags);
+    }
+    // T01.04：创建/恢复首轮流终态来源（不重复计 reused 恢复）。
+    recordEvent({ kind: 'cli.sse.result', route: '/api/chat', result: result.status.toLowerCase(),
+        appType, operationId: result.requestId,
+        status: result.reused ? 'reused' : 'created' });
+    switch (result.status) {
+        case 'SUCCEEDED':
+        case 'REUSED':
+            return;
+        case 'WAITING_INPUT':
+            process.exitCode = 2;
+            return;
+        case 'INTERRUPTED':
+            process.exitCode = 130;
+            return;
+        default:
+            process.exitCode = 1;
+    }
+}
+// ---------------- 对话 / 版本 / 云函数 / 秘密 / 沙箱（C05/C07/C08/C15/C16） ----------------
+/** 简化后的对象探测（state 摘要用，避免内联类型断言散落）。 */
+function isRecordLike(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function pickString(flags, key) {
+    const v = flags[key];
+    return typeof v === 'string' && v.trim() ? v.trim() : undefined;
+}
+async function readBodyFile(flags, label) {
+    const raw = str(flags, '--file') ?? '';
+    if (!raw || raw === '-') {
+        if (process.stdin.isTTY === true)
+            fail(`${label} 需要 --file <路径|->`);
+        const chunks = [];
+        for await (const chunk of process.stdin)
+            chunks.push(chunk);
+        return Buffer.concat(chunks).toString('utf8');
+    }
+    return readFileSync(path.resolve(raw), 'utf8');
+}
+async function cmdChat(command, flags) {
+    const cfg = resolveCfg(flags);
+    const sub = command[1];
+    if (sub === 'history') {
+        requireAuth(cfg);
+        const appId = pickString(flags, '--app-id') ?? command[2];
+        const sprintId = pickString(flags, '--sprint-id');
+        if (!appId || !sprintId)
+            fail('用法: qmuse chat history --app-id <appId> --sprint-id <sprintId>');
+        const r = await queryChatByAppIdAndSprintId(appId, sprintId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询会话失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'state') {
+        requireAuth(cfg);
+        const chatId = command[2] || pickString(flags, '--chat-id');
+        if (!chatId)
+            fail('用法: qmuse chat state <chatId>');
+        const r = await getChatState(chatId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询会话状态失败`);
+        if (flags['--json'] === true) {
+            output(r.data, flags); // 结构化输出保持原样（零契约变更）
+            return;
+        }
+        // C05.04“断流先用已有 state 查询”：文本模式给出人读摘要 + 可复制的恢复命令。
+        const status = isRecordLike(r.data) && typeof r.data['__chatStatus'] === 'string' ? r.data['__chatStatus'] : 'UNKNOWN';
+        const messages = isRecordLike(r.data) && Array.isArray(r.data['messages']) ? r.data['messages'].length : 0;
+        log.info(`会话 ${chatId} 状态：${status}；消息 ${messages} 条`);
+        const pending = summarizePendingInterrupts(r.data, chatId);
+        if (pending.length === 0) {
+            log.info('无待恢复中断（原始结构可用 --json 查看）');
+            return;
+        }
+        log.raw(`
+`);
+        pending.forEach((item, index) => {
+            log.raw(`[待恢复 ${index + 1}] ${item.kind === 'form' ? '表单' : item.kind === 'bash-interception' ? '命令拦截' : '中断'} ${item.label}
+`);
+            item.questions.forEach(question => {
+                const meta = [question.control, question.required ? '必填' : ''].filter(Boolean).join('，');
+                log.raw(`    - ${question.questionId}（${meta}）${question.label}
+`);
+                if (question.options?.length)
+                    log.raw(`      选项：${question.options.join(' / ')}
+`);
+            });
+            log.raw(`    恢复：${item.resumeCommand}
+`);
+            log.raw(`    答案结构：${item.answerHint}
+`);
+        });
+        return;
+    }
+    if (sub === 'cancel') {
+        requireAuth(cfg);
+        const chatId = command[2] || pickString(flags, '--chat-id');
+        const appId = pickString(flags, '--app-id');
+        if (!chatId || !appId)
+            fail('用法: qmuse chat cancel <chatId> --app-id <appId>');
+        const r = await cancelChat(appId, chatId, cfg);
+        if (!r.ok)
+            failApi(r, `取消失败`);
+        if (flags['--json'] === true)
+            output({ success: true, chatId, appId }, flags);
+        else
+            log.success(`已发送停止指令（appId=${appId} chatId=${chatId}）；服务端确认状态以 getChatState 为准`);
+        return;
+    }
+    if (sub === 'resume') {
+        // C05.04：恢复用户输入与云资源中断——同一会话与 checkpoint，明确 interruptId。
+        requireAuth(cfg);
+        const chatId = command[2] || pickString(flags, '--chat-id');
+        const interruptId = pickString(flags, '--interrupt-id');
+        const appId = pickString(flags, '--app-id') ?? loadAppBinding(process.cwd())?.appId;
+        const sprintId = pickString(flags, '--sprint-id');
+        if (!chatId || !interruptId || !appId) {
+            fail('用法: qmuse chat resume <chatId> --interrupt-id <id> --file <answerFile> --app-id <appId> [--sprint-id <id>] [--ndjson]');
+        }
+        const answerRaw = (await readBodyFile(flags, 'chat resume')).trim();
+        if (!answerRaw)
+            fail('恢复回答不能为空：--file 传入 JSON（questions 答案或云资源决定）');
+        let answer;
+        try {
+            answer = JSON.parse(answerRaw);
+        }
+        catch {
+            fail('--file 内容必须是 JSON 对象（answers/data/response 之一）');
+        }
+        if (!answer || typeof answer !== 'object' || Array.isArray(answer))
+            fail('--file 内容必须是 JSON 对象（answers/data/response 之一）');
+        const answerObj = answer;
+        const interruptResponse = { ...answerObj, interruptId };
+        const operationId = `op_${randomBytes(12).toString('hex')}`;
+        const abort = new AbortController();
+        const onInterrupt = () => abort.abort();
+        process.once('SIGINT', onInterrupt);
+        const result = await continueChat(cfg, {
+            appId,
+            chatId,
+            ...(sprintId ? { sprintId } : {}),
+            interruptResponse,
+        }, {
+            signal: abort.signal,
+            onEvent: ({ sequence, type }) => {
+                if (flags['--ndjson'] === true) {
+                    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'event', sequence, operationId, eventType: type })}\n`);
+                }
+            },
+        });
+        process.off('SIGINT', onInterrupt);
+        if (flags['--ndjson'] === true) {
+            process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'result', sequence: result.eventCount + 1, operationId, result: { status: result.status, chatId: result.chatId, ...(result.errorText ? { errorText: result.errorText } : {}) } })}\n`);
+        }
+        else if (flags['--json'] === true) {
+            output({ schemaVersion: 1, success: result.status === 'SUCCEEDED' || result.status === 'WAITING_INPUT', status: result.status, interruptId, data: { chatId: result.chatId, toolConsumed: result.toolConsumed }, ...(result.errorText ? { errorText: result.errorText } : {}) }, flags);
+        }
+        else if (result.status === 'SUCCEEDED') {
+            log.success('中断恢复完成');
+        }
+        else {
+            log.error(`恢复未完成：${result.status}${result.errorText ? `，${result.errorText}` : ''}`);
+            process.exitCode = result.status === 'WAITING_INPUT' ? 2 : 1;
+        }
+        // T01.04：恢复流终态来源（同一会话 checkpoint，不重跑首轮生成）。
+        recordEvent({ kind: 'cli.sse.result', route: '/api/chat', result: result.status.toLowerCase(), operationId });
+        return;
+    }
+    if (sub === 'clear') {
+        requireAuth(cfg);
+        const chatId = command[2] || pickString(flags, '--chat-id');
+        const appId = pickString(flags, '--app-id');
+        const sprintId = pickString(flags, '--sprint-id');
+        if (!chatId || !appId || !sprintId)
+            fail('用法: qmuse chat clear <chatId> --app-id <appId> --sprint-id <sprintId>');
+        const r = await clearChatContext(appId, chatId, sprintId, cfg);
+        if (!r.ok)
+            failApi(r, `清理会话上下文失败`);
+        if (flags['--json'] === true)
+            output({ success: true, chatId }, flags);
+        else
+            log.success(`会话上下文已清理（chatId=${chatId}）`);
+        return;
+    }
+    if (sub === 'send') {
+        requireAuth(cfg);
+        const appId = pickString(flags, '--app-id');
+        const chatId = pickString(flags, '--chat-id');
+        const content = (await readBodyFile(flags, 'chat send')).trim();
+        if (!content)
+            fail('首条继续内容不能为空');
+        if (!appId || !chatId)
+            fail('用法: qmuse chat send --app-id <appId> --chat-id <chatId> --file <路径|-> [--model <m>] [--ndjson]');
+        const model = pickString(flags, '--model') ?? 'auto';
+        const skills = pickString(flags, '--skill');
+        const skillVersion = pickString(flags, '--skill-version');
+        if ((skills && !skillVersion) || (!skills && skillVersion)) {
+            fail('--skill 与 --skill-version 必须同时提供（精确版本引用）');
+        }
+        if (model !== 'auto') {
+            const models = await listModels(cfg);
+            if (!models.ok || !models.data)
+                fail(`模型列表查询失败: ${models.errorMessage ?? models.errorCode ?? `HTTP ${models.status}`}`);
+            const known = collectModelIds(models.data);
+            if (!known.includes(model)) {
+                fail(`未知模型 ${model}；可用: auto, ${known.slice(0, 8).join(', ')}${known.length > 8 ? ' …' : ''}`);
+            }
+        }
+        const extraChat = {};
+        if (skills)
+            extraChat.skills = [skills];
+        if (skillVersion)
+            extraChat.skillVersionIds = { [skills]: skillVersion };
+        const operationId = `op_${randomBytes(12).toString('hex')}`;
+        const abort = new AbortController();
+        const onInterrupt = () => abort.abort();
+        process.once('SIGINT', onInterrupt);
+        const result = await continueChat(cfg, {
+            ...pickChatSeed(flags),
+            ...extraChat,
+            appId,
+            chatId,
+            selectedModel: model,
+            message: { role: 'user', id: `mu_${randomBytes(12).toString('hex')}`, content },
+        }, {
+            signal: abort.signal,
+            onEvent: ({ sequence, type }) => {
+                if (flags['--ndjson'] === true) {
+                    process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'event', sequence, operationId, eventType: type })}\n`);
+                }
+                else if (flags['--json'] !== true && sequence === 1) {
+                    log.info('已连接生成流...');
+                }
+            },
+        });
+        process.removeListener('SIGINT', onInterrupt);
+        if (flags['--ndjson'] === true) {
+            process.stdout.write(`${JSON.stringify({ schemaVersion: 1, type: 'result', sequence: result.eventCount + 1, operationId, result: { status: result.status, chatId: result.chatId, ...(result.errorText ? { errorText: result.errorText } : {}) } })}\n`);
+        }
+        else if (flags['--json'] === true) {
+            output({ schemaVersion: 1, success: result.status === 'SUCCEEDED' || result.status === 'WAITING_INPUT', status: result.status, data: { chatId: result.chatId, toolConsumed: result.toolConsumed }, ...(result.errorText ? { errorText: result.errorText } : {}) }, flags);
+        }
+        else if (result.status === 'SUCCEEDED') {
+            log.success('本轮对话完成');
+        }
+        else {
+            log.error(`对话未完成：${result.status}${result.errorText ? `，${result.errorText}` : ''}`);
+            process.exitCode = result.status === 'WAITING_INPUT' ? 2 : 1;
+        }
+        // T01.04：已有会话 continue 流终态来源。
+        recordEvent({ kind: 'cli.sse.result', route: '/api/chat', result: result.status.toLowerCase(), operationId });
+        return;
+    }
+    if (sub === 'attachment') {
+        if (command[2] !== 'upload')
+            fail('用法: qmuse chat attachment upload <path> --app-id <appId> [--version <versionId>]');
+        requireAuth(cfg);
+        const appId = pickString(flags, '--app-id');
+        const filePath = command[3];
+        if (!appId || !filePath)
+            fail('用法: qmuse chat attachment upload <path> --app-id <appId> [--version <versionId>]');
+        let versionId = pickString(flags, '--version');
+        if (!versionId) {
+            const versions = await listAppVersions(appId, cfg);
+            if (!versions.ok || !versions.data?.list?.length) {
+                fail('未找到可上传的版本；请用 --version 指定版本 ID 或先完成首次创建/导入');
+            }
+            versionId = versions.data.list[0].id;
+            log.info(`未指定 --version，使用最新版本 ${versionId}`);
+        }
+        const stats = statSync(path.resolve(filePath));
+        const r = await uploadAttachment(cfg, path.resolve(filePath), versionId, appId);
+        if (!r.ok || !r.data)
+            failApi(r, `附件上传失败`);
+        // T01.05：上传结果来源（资源归属校验由 /api/file/upload 版本权限完成）。
+        recordEvent({ kind: 'cli.transfer.result', route: '/api/file/upload',
+            ...(Number.isFinite(stats.size) && stats.size >= 0 ? { bytes: stats.size } : {}), result: 'ok' });
+        output(r.data, flags);
+        return;
+    }
+    fail(`未知 chat 子命令: ${sub ?? '(空)'}。可用: history / state / cancel / clear / send / resume / attachment`);
+}
+/** 继续对话 base 上下文：从绑定与 --model/--biz 已知字段拼装，未提供的字段遵循服务端可选性。 */
+function collectModelIds(data) {
+    const items = Array.isArray(data) ? data : data?.list;
+    if (!Array.isArray(items))
+        return [];
+    return items.map(item => item.modelId).filter((v) => typeof v === 'string');
+}
+function pickChatSeed(flags) {
+    const biz = pickString(flags, '--biz');
+    return biz ? { bizExtInfo: JSON.parse(biz) } : {};
+}
+async function cmdModels(_command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const r = await listModels(cfg);
+    if (!r.ok || !r.data)
+        failApi(r, `查询模型列表失败`);
+    output(r.data, flags);
+}
+async function cmdVersions(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    if (sub === 'list') {
+        const appId = pickString(flags, '--app-id');
+        if (!appId)
+            fail('用法: qmuse version list --app-id <appId>');
+        const r = await listAppVersions(appId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询版本失败`);
+        if (flags['--json'] === true) {
+            output(r.data, flags);
+            return;
+        }
+        const versions = r.data.list ?? [];
+        log.info(`应用 ${appId} 共 ${r.data.total ?? versions.length} 个版本：`);
+        for (const v of versions) {
+            log.raw(`${v.id}  ${(v.status ?? '').padEnd(10)} ${v.gmtCreate ?? ''}  ${v.remark ?? ''}\n`);
+        }
+        return;
+    }
+    if (sub === 'info') {
+        const versionId = command[2];
+        const appId = pickString(flags, '--app-id');
+        if (!versionId || !appId)
+            fail('用法: qmuse version info <versionId> --app-id <appId>');
+        const r = await listAppVersions(appId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询版本失败`);
+        const version = (r.data.list ?? []).find(item => item.id === versionId);
+        if (!version)
+            fail(`应用 ${appId} 中未找到版本 ${versionId}`);
+        output(version, flags);
+        return;
+    }
+    fail(`未知 version 子命令: ${sub ?? '(空)'}。可用: list / info（diff/restore/artifact 待服务端契约开放）`);
+}
+async function cmdCodeExport(_command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const appId = pickString(flags, '--app-id');
+    const outDir = pickString(flags, '--output');
+    if (!appId || !outDir)
+        fail('用法: qmuse code export --app-id <appId> --output <dir>');
+    const r = await fetchSourceFiles(appId, cfg);
+    if (!r.ok || !r.data)
+        failApi(r, `获取源码失败`);
+    const requestedVersion = pickString(flags, '--version');
+    if (requestedVersion && r.data.versionId && requestedVersion !== r.data.versionId) {
+        fail(`服务端当前仅提供最新版源码导出：latest=${r.data.versionId}，请求=${requestedVersion}`);
+    }
+    mkdirSync(path.resolve(outDir), { recursive: true });
+    const files = Object.entries(r.data.files ?? {});
+    for (const [filePath, file] of files) {
+        const target = path.join(path.resolve(outDir), filePath);
+        mkdirSync(path.dirname(target), { recursive: true });
+        writeFileSync(target, file.value ?? '', 'utf8');
+    }
+    // T01.05：导出下载来源（资源、文件数与关联版本）。
+    recordEvent({ kind: 'cli.transfer.result', route: '/api/app/code', result: 'ok',
+        ...(r.data.versionId ? { status: 'version-synced' } : {}) });
+    if (flags['--json'] === true) {
+        output({ success: true, appId, versionId: r.data.versionId ?? null, fileCount: files.length, output: path.resolve(outDir) }, flags);
+    }
+    else {
+        log.success(`已导出 ${files.length} 个文件到 ${path.resolve(outDir)}（versionId=${r.data.versionId ?? '(无版本)'}）`);
+    }
+}
+async function cmdFn(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    const appId = pickString(flags, '--app-id');
+    const functionId = pickString(flags, '--function-id');
+    if (sub === 'list') {
+        if (!appId)
+            fail('用法: qmuse fn list --app-id <appId>');
+        const r = await listFunctions(appId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询云函数失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'info') {
+        if (!appId || !functionId)
+            fail('用法: qmuse fn info --app-id <appId> --function-id <fid>');
+        const r = await functionDetail(appId, functionId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询函数详情失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'retry') {
+        if (!appId || !functionId)
+            fail('用法: qmuse fn retry --app-id <appId> --function-id <fid>');
+        const r = await retryFunctionPublish(appId, functionId, cfg);
+        // T01.08：既有函数发布重试的受受理/结果来源事件。
+        recordEvent({ kind: 'cli.task.state', route: '/api/appwrite/functions/retry-publish',
+            stage: 'accepted', operationId: `${appId}:${functionId}`, result: r.ok ? 'ok' : 'failed' });
+        if (!r.ok)
+            failApi(r, `重试发布失败`);
+        if (flags['--json'] === true)
+            output({ success: true, appId, functionId }, flags);
+        else
+            log.success(`已重试函数 ${functionId} 发布`);
+        return;
+    }
+    const subByPath = {
+        'deployment-list': () => listFunctionDeployments(appId, functionId, pageFor(flags), cfg),
+        'deployment-info': () => deploymentDetail(appId, functionId, command[2], cfg),
+        'execution-list': () => listFunctionExecutions(appId, functionId, pageFor(flags), cfg),
+        'execution-info': () => executionDetail(appId, functionId, command[2], cfg),
+    };
+    if (sub && subByPath[sub]) {
+        if (!appId || !functionId)
+            fail(`用法: qmuse fn ${sub} --app-id <appId> --function-id <fid> [资源ID]`);
+        const r = await subByPath[sub]();
+        if (!r.ok || !r.data)
+            failApi(r, `查询失败`);
+        output(r.data, flags);
+        return;
+    }
+    fail(`未知 fn 子命令: ${sub ?? '(空)'}。可用: list / info / retry / deployment-list / deployment-info / execution-list / execution-info`);
+}
+function pageFor(flags) {
+    const limit = pickString(flags, '--limit');
+    const offset = pickString(flags, '--offset');
+    return {
+        ...(limit ? { limit: Number(limit) } : {}),
+        ...(offset ? { offset: Number(offset) } : {}),
+    };
+}
+async function cmdSecret(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    const appId = pickString(flags, '--app-id');
+    const secretId = command[2] || pickString(flags, '--secret-id');
+    if (sub === 'list') {
+        if (!appId)
+            fail('用法: qmuse secret list --app-id <appId> [--cloud-env dev|prod]');
+        const cloudEnv = pickString(flags, '--cloud-env');
+        if (cloudEnv && cloudEnv !== 'dev' && cloudEnv !== 'prod')
+            fail('--cloud-env 仅支持 dev / prod');
+        const r = await listSecrets(appId, cfg, cloudEnv);
+        if (!r.ok || !r.data)
+            failApi(r, `查询秘密失败`);
+        if (flags['--json'] === true) {
+            output(r.data, flags);
+            return;
+        }
+        const payload = r.data;
+        const items = (payload.secrets ?? payload.list ?? []);
+        log.info(`环境 ${cloudEnv ?? 'dev'}：共 ${typeof payload.total === 'number' ? payload.total : items.length} 个密钥`);
+        items.forEach(item => {
+            const state = `${String(item.status ?? '')}/${String(item.syncStatus ?? '')}${item.lastError ? `（${String(item.lastError).slice(0, 60)}）` : ''}`;
+            log.raw(`  ${String(item.key)}  [${item.id}] ${state}（更新于 ${String(item.updatedAt ?? '?')}）
+`);
+        });
+        return;
+    }
+    if (sub === 'create') {
+        if (!appId || !secretId)
+            fail('用法: qmuse secret create <KEY> --app-id <appId> --value-stdin [--description <d>]');
+        const value = (await readBodyFile(flags, 'secret create --value-stdin')).replace(/\n+$/, '');
+        if (!value)
+            fail('秘密值不能为空（--value-stdin 从管道/文件读取）');
+        const key = secretId;
+        const { createSecret } = await import('./app/secret.js');
+        const r = await createSecret(appId, key, value, cfg, pickString(flags, '--description'));
+        if (!r.ok || !r.data)
+            failApi(r, `创建秘密失败`);
+        if (flags['--json'] === true)
+            output({ success: true, appId, key }, flags);
+        else
+            log.success(`秘密 ${key} 已创建/更新并进入同步流程`);
+        return;
+    }
+    if (sub === 'enable' || sub === 'disable') {
+        // 停用（会同步删除云上变量）是删除的前置条件；启用走反向同步。
+        if (!appId || !secretId)
+            fail(`用法: qmuse secret ${sub} <secretId> --app-id <appId> [--cloud-env dev|prod]`);
+        const cloudEnv = pickString(flags, '--cloud-env');
+        if (cloudEnv && cloudEnv !== 'dev' && cloudEnv !== 'prod')
+            fail('--cloud-env 仅支持 dev / prod');
+        const r = sub === 'disable'
+            ? await disableSecret(appId, secretId, cfg, cloudEnv)
+            : await enableSecret(appId, secretId, cfg, cloudEnv);
+        if (!r.ok)
+            failApi(r, `${sub === 'disable' ? '停用' : '启用'}秘密失败`);
+        if (flags['--json'] === true)
+            output({ success: true, appId, secretId, action: sub, env: cloudEnv ?? 'dev' }, flags);
+        else
+            log.success(`已${sub === 'disable' ? '停用' : '启用'}秘密 ${secretId}（${cloudEnv ?? 'dev'}）`);
+        return;
+    }
+    if (sub === 'delete') {
+        if (!appId || !secretId)
+            fail('用法: qmuse secret delete <secretId> --app-id <appId>');
+        if (flags['--yes'] !== true)
+            fail('删除秘密不可恢复：请显式传入 --yes');
+        const cloudEnv = pickString(flags, '--cloud-env');
+        if (cloudEnv && cloudEnv !== 'dev' && cloudEnv !== 'prod')
+            fail('--cloud-env 仅支持 dev / prod');
+        const r = await deleteSecret(appId, secretId, cfg, cloudEnv);
+        if (!r.ok) {
+            const reason = r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`;
+            const hint = /系统异常|停用/i.test(String(reason))
+                ? `；服务端仅允许删除"已停用且同步完成"的密钥：请先执行 qmuse secret disable ${secretId} --app-id ${appId} 后重试`
+                : '';
+            fail(`删除秘密失败: ${reason}${hint}`);
+        }
+        if (flags['--json'] === true)
+            output({ success: true, appId, secretId, env: cloudEnv ?? 'dev' }, flags);
+        else
+            log.success(`已删除秘密 ${secretId}（${cloudEnv ?? 'dev'}）`);
+        return;
+    }
+    if (sub === 'sync') {
+        const syncSub = command[2];
+        const syncId = command[3] || pickString(flags, '--secret-id');
+        const syncEnv = pickString(flags, '--cloud-env');
+        if (syncEnv && syncEnv !== 'dev' && syncEnv !== 'prod')
+            fail('--cloud-env 仅支持 dev / prod');
+        if (!appId || !syncId)
+            fail('用法: qmuse secret sync status|retry <secretId> --app-id <appId> [--cloud-env dev|prod]');
+        if (syncSub === 'status') {
+            const r = await listSecrets(appId, cfg, syncEnv);
+            if (!r.ok || !r.data)
+                failApi(r, `查询秘密同步状态失败`);
+            const payload = r.data.secrets ?? r.data.list ?? r.data;
+            const target = Array.isArray(payload)
+                ? payload.find(item => item.secretId === syncId || item.key === syncId)
+                : undefined;
+            output(target ?? { secretId: syncId, found: false, list: payload }, flags);
+            return;
+        }
+        if (syncSub === 'retry') {
+            const r = await retrySecretSync(appId, syncId, cfg, syncEnv);
+            // T01.08：秘密同步重试的结果来源事件（成功/失败都保留）。
+            recordEvent({ kind: 'cli.task.state', route: '/api/appwrite/secrets/retry-sync',
+                stage: 'accepted', operationId: syncId, result: r.ok ? 'ok' : 'failed',
+                ...(r.errorCode ? { errorCode: r.errorCode } : {}) });
+            if (!r.ok)
+                failApi(r, `重试同步失败`);
+            if (flags['--json'] === true)
+                output({ success: true, secretId: syncId }, flags);
+            else
+                log.success(`已触发秘密 ${syncId} 重新同步`);
+            return;
+        }
+        fail('用法: qmuse secret sync status|retry <secretId> --app-id <appId>');
+        return;
+    }
+    fail(`未知 secret 子命令: ${sub ?? '(空)'}。可用: list / create / enable / disable / delete（先停用再删除） / sync status|retry`);
+}
+async function cmdSandbox(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    const appId = pickString(flags, '--app-id');
+    const sprintId = pickString(flags, '--sprint-id');
+    const chatId = pickString(flags, '--chat-id');
+    const sandboxId = pickString(flags, '--sandbox-id');
+    if (sub === 'ensure') {
+        if (!appId || !sprintId)
+            fail('用法: qmuse sandbox ensure --app-id <appId> --sprint-id <sprintId>');
+        const r = await ensureSandbox(appId, sprintId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `确保沙箱失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'restart') {
+        if (!chatId)
+            fail('用法: qmuse sandbox restart --chat-id <chatId>（服务端按会话授权）');
+        const r = await restartPreview(chatId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `重启预览失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'setting-get') {
+        if (!appId)
+            fail('用法: qmuse sandbox setting-get --app-id <appId>');
+        const r = await querySandboxSetting(appId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询沙箱配置失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'status') {
+        // C07.05：集中返回沙箱配置、预览、健康及失败原因（结果全部来自现有平台状态）。
+        if (!appId)
+            fail('用法: qmuse sandbox status --app-id <appId> [--sandbox-id <id>]');
+        const resolveApi = async (call, label) => {
+            try {
+                const r = await call;
+                if (!r.ok)
+                    return { unavailable: r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}` };
+                return r.data ?? null;
+            }
+            catch (err) {
+                return { unavailable: err instanceof Error ? err.message : String(err), section: label };
+            }
+        };
+        const settingPromise = resolveApi(querySandboxSetting(appId, cfg), 'setting');
+        let discoveredSandboxId;
+        let effectiveSandboxId = sandboxId;
+        if (!effectiveSandboxId) {
+            // 沙箱标识自动发现：previewHealth 对不匹配 id 的失败响应会暴露 actual=SBX_*（现有平台状态）；
+            // 与 setting 并行执行，随后 previewInfo/previewHealth 再并行，减少串行 RTT。
+            const probe = await Promise.all([settingPromise, previewHealth(appId, 'qmuse-cli-discovery', cfg)]).then(([, p]) => p);
+            const mismatch = /actual=(SBX_[a-z0-9]+)/iu.exec(`${probe.errorMessage ?? ''} ${JSON.stringify(probe.data ?? {})}`);
+            if (mismatch) {
+                discoveredSandboxId = mismatch[1];
+                effectiveSandboxId = discoveredSandboxId;
+            }
+        }
+        let preview = { unavailable: '缺少 --sandbox-id（活跃沙箱标识来自 dev 会话或 chat 上下文）' };
+        let health = preview;
+        if (effectiveSandboxId) {
+            const [info, healthy] = await Promise.all([
+                resolveApi(previewInfo(appId, effectiveSandboxId, cfg), 'preview'),
+                resolveApi(previewHealth(appId, effectiveSandboxId, cfg), 'health'),
+            ]);
+            preview = info;
+            health = healthy;
+        }
+        const setting = await settingPromise;
+        const data = { appId, ...(effectiveSandboxId ? { sandboxId: effectiveSandboxId } : {}),
+            ...(discoveredSandboxId ? { sandboxIdDiscovered: true } : {}),
+            setting, preview, health };
+        if (flags['--json'] === true) {
+            output(data, flags);
+            return;
+        }
+        log.info(`沙箱配置：${JSON.stringify(setting)}`);
+        log.info(`预览信息：${JSON.stringify(preview)}`);
+        log.info(`健康状态：${JSON.stringify(health)}`);
+        return;
+    }
+    if (sub === 'health') {
+        if (!appId || !sandboxId)
+            fail('sandbox health 需要 --app-id 与 --sandbox-id（活跃沙箱标识来自 dev 会话 / socketInfo）');
+        const r = await previewHealth(appId, sandboxId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询沙箱失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'logs') {
+        // C07.14：现有接口可提供的任务错误与构建日志；未取得日志必须显式标注，不解释为成功。
+        if (!appId)
+            fail('用法: qmuse sandbox logs --app-id <appId> [--sandbox-id <id>] [--version-id <id>] [--build-id <id>]');
+        const versionId = pickString(flags, '--version-id');
+        const buildId = pickString(flags, '--build-id');
+        const sources = {};
+        const artifacts = await buildArtifactsStatus(appId, {
+            ...(sprintId ? { sprintId } : {}),
+            ...(versionId ? { versionId } : {}),
+            ...(buildId ? { buildId } : {}),
+            artifactTarget: 'preview',
+        }, cfg);
+        sources.buildArtifacts = artifacts.ok
+            ? artifacts.data
+            : { unavailable: artifacts.errorMessage ?? artifacts.errorCode ?? `HTTP ${artifacts.status}` };
+        if (sandboxId) {
+            const info = await previewInfo(appId, sandboxId, cfg);
+            sources.previewInfo = info.ok ? info.data : { unavailable: info.errorMessage ?? info.errorCode ?? `HTTP ${info.status}` };
+            const health = await previewHealth(appId, sandboxId, cfg);
+            sources.previewHealth = health.ok ? health.data : { unavailable: health.errorMessage ?? health.errorCode ?? `HTTP ${health.status}` };
+        }
+        // 日志判定：仅当响应中存在非空的日志类字段（logs/buildLogs/lines/errorLogs/taskError/logsUrl 等）才算取得，
+        // 仅返回构建状态（fileCount/status）不得解释为成功（C07.14“不将未取得日志解释为成功”）。
+        const isLogKey = (key) => /^(?:[a-z]+_)*logs?$/iu.test(key) // logs / build_logs / preview_log
+            || /(?<=[a-z])[A-Z]Logs?$/.test(key) // buildLogs / taskLog（驼峰边界，排除 catalog）
+            || /^(errorLogs?|taskError|logLines?|logsUrl|logUrl)$/iu.test(key);
+        const hasLogContent = (value, depth = 0) => {
+            if (depth > 4 || value == null || typeof value !== 'object')
+                return false;
+            // 数组本身不算日志：向内寻找日志类键（避免任意非空列表误判为“取得日志”）。
+            if (Array.isArray(value))
+                return value.some(item => hasLogContent(item, depth + 1));
+            for (const [key, item] of Object.entries(value)) {
+                if (isLogKey(key)) {
+                    if (typeof item === 'string' && item.trim().length > 0)
+                        return true;
+                    if (Array.isArray(item) && item.length > 0)
+                        return true;
+                }
+                if (hasLogContent(item, depth + 1))
+                    return true;
+            }
+            return false;
+        };
+        const anyLogs = Object.values(sources).some(v => v && typeof v === 'object' && !('unavailable' in v)
+            && hasLogContent(v));
+        const data = {
+            appId,
+            ...(sandboxId ? { sandboxId } : {}),
+            ...(versionId ? { versionId } : {}),
+            sources,
+            logsAvailable: anyLogs,
+            ...(anyLogs ? {} : { logsUnavailableReason: '现有平台接口未返回日志内容；请结合 --build-id/--version-id 重试或在开发会话内查看' }),
+        };
+        output(data, flags);
+        if (!anyLogs)
+            process.exitCode = 3; // 明确非成功：未取得日志
+        return;
+    }
+    fail(`未知 sandbox 子命令: ${sub ?? '(空)'}。可用: ensure / restart / status / health / logs / setting-get`);
+}
+// ---------------- 数据域（C13） ----------------
+async function cmdDataSources(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    const appId = pickString(flags, '--app-id');
+    const sourceId = pickString(flags, '--source-id') ?? command[2];
+    if (!appId)
+        fail('用法: qmuse data-source list|info --app-id <appId>');
+    const versionId = pickString(flags, '--version')
+        ?? ((await listAppVersions(appId, cfg)).data?.list ?? [])[0]?.id;
+    if (!versionId)
+        fail('查询版本失败：无法确定 devAppVersionId');
+    const r = await queryAppMetadata(appId, versionId, cfg);
+    if (!r.ok || !r.data)
+        failApi(r, `查询应用数据元信息失败`);
+    const payload = r.data;
+    if (sub === 'list') {
+        output({ appId, devAppVersionId: versionId, tables: payload }, flags);
+        return;
+    }
+    if (sub === 'info') {
+        if (!sourceId)
+            fail('用法: qmuse data-source info <formId> --app-id <appId>');
+        const flat = [];
+        const walk = (node) => {
+            if (Array.isArray(node)) {
+                node.forEach(walk);
+                return;
+            }
+            if (node && typeof node === 'object') {
+                const record = node;
+                if (typeof record.name === 'string' && Array.isArray(record.properties))
+                    flat.push(record);
+                Object.values(record).forEach(walk);
+            }
+        };
+        walk(payload);
+        const found = flat.find(item => item.name === sourceId);
+        output(found ?? { formId: sourceId, found: false, hint: 'data-source list 查看全部表' }, flags);
+        return;
+    }
+    fail(`未知 data-source 子命令: ${sub ?? '(空)'}。可用: list / info`);
+}
+async function cmdDb(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    const appId = pickString(flags, '--app-id');
+    const formId = pickString(flags, '--form-id');
+    const env = pickString(flags, '--cloud-env') ?? 'dev';
+    if (!appId || !formId)
+        fail('用法: qmuse db <子命令> --app-id <appId> --form-id <formId>');
+    if (sub === 'tables') {
+        const r = await queryAppMetadata(appId, ((await listAppVersions(appId, cfg)).data?.list ?? [])[0]?.id ?? '', cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询数据表失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'permission' && command[2] === 'get') {
+        const r = await queryFormAuth(appId, formId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `读取表权限失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'permission' && command[2] === 'set') {
+        const file = pickString(flags, '--file');
+        if (!file)
+            fail('用法: qmuse db permission set --file <permissions.json>');
+        const permissions = JSON.parse(readFileSync(path.resolve(file), 'utf8'));
+        const r = await syncFormAuth(appId, formId, permissions, cfg);
+        if (!r.ok)
+            failApi(r, `更新表权限失败`);
+        output({ success: true, formId }, flags);
+        return;
+    }
+    if (sub === 'records') {
+        const op = command[2];
+        const conditionsFile = pickString(flags, '--conditions-file');
+        if (op === 'list') {
+            const r = await listRecords(appId, formId, {
+                env,
+                pageNumber: Number(pickString(flags, '--page-number') ?? 1),
+                pageSize: Number(pickString(flags, '--page-size') ?? 20),
+                ...(conditionsFile ? { conditions: JSON.parse(readFileSync(path.resolve(conditionsFile), 'utf8')) } : {}),
+            }, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `查询记录失败`);
+            output(r.data, flags);
+            return;
+        }
+        if (op === 'get') {
+            const code = command[3];
+            if (!code)
+                fail('用法: qmuse db records get <code> ...');
+            const r = await getRecord(appId, formId, code, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `读取记录失败`);
+            output(r.data, flags);
+            return;
+        }
+        if (op === 'create' || op === 'update') {
+            const file = pickString(flags, '--file');
+            if (!file)
+                fail(`用法: qmuse db records ${op} --file <parameters.json>`);
+            const parameters = JSON.parse(readFileSync(path.resolve(file), 'utf8'));
+            const r = op === 'create'
+                ? await createRecord(appId, formId, parameters, cfg)
+                : await updateRecord(appId, formId, parameters, cfg);
+            if (!r.ok) {
+                const reason = r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}`;
+                // 服务器对缺必填/类型问题只回“系统异常”：失败后按表元数据补字段级诊断（成功路径零开销）。
+                let hints = [];
+                try {
+                    hints = await diagnoseRecordParams(appId, formId, parameters, cfg);
+                }
+                catch { /* 诊断仅尽力而为 */ }
+                const hint = hints.length > 0 ? `；字段诊断: ${hints.join('；')}` : '';
+                fail(`${op === 'create' ? '创建' : '更新'}失败: ${reason}${hint}`);
+            }
+            output(r.data, flags);
+            return;
+        }
+        if (op === 'delete') {
+            const code = command[3];
+            if (!code || flags['--yes'] !== true)
+                fail('用法: qmuse db records delete <code> ... --yes');
+            const r = await deleteRecord(appId, formId, code, cfg);
+            if (!r.ok)
+                failApi(r, `删除失败`);
+            output({ success: true, code, deleted: r.data === true }, flags);
+            return;
+        }
+        fail('用法: qmuse db records list | get <code> | create --file | update --file | delete <code> --yes');
+        return;
+    }
+    fail(`未知 db 子命令: ${sub ?? '(空)'}。可用: tables / records / permission`);
+}
+// ---------------- 账户域（C29） ----------------
+async function cmdAccount(command, flags) {
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const sub = command[1];
+    const spaceId = pickString(flags, '--space-id') ?? cfg.spaceId;
+    if (!spaceId)
+        fail('用法: qmuse account <子命令> --space-id <spaceId>（或先用 space use）');
+    if (sub === undefined || sub === 'overview') {
+        // C29.01：同一输出汇总套餐/订阅、余额、权益、额度与可取得的消耗摘要。
+        const [bal, ent, stats] = await Promise.all([
+            pointBalance(spaceId, cfg),
+            benefitEntitlements(spaceId, cfg),
+            pointConsumeStats(spaceId, { pageIndex: '1', pageSize: '8' }, cfg),
+        ]);
+        if (!bal.ok || !bal.data)
+            fail(`查询余额失败: ${bal.errorMessage ?? bal.errorCode ?? `HTTP ${bal.status}`}`);
+        const appId = pickString(flags, '--app-id') ?? loadAppBinding(process.cwd())?.appId;
+        const [subscription, dbUsage] = await Promise.all([
+            sectionOf(async () => {
+                // 订阅状态为只读面（GET /api/order/subscription/current）；无契约时显式标注。
+                const r = await apiCall('GET', '/api/order/subscription/current', undefined, cfg);
+                if (!r.ok)
+                    return { unavailable: r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}` };
+                return r.data ?? null;
+            }),
+            appId ? sectionOf(async () => {
+                const r = await databaseOverview(appId, cfg);
+                if (!r.ok)
+                    return { unavailable: r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}` };
+                return r.data ?? null;
+            }) : { unavailable: '未绑定应用：传 --app-id 或执行 qmuse app use' },
+        ]);
+        output({
+            schemaVersion: 1,
+            spaceId,
+            balance: bal.data,
+            entitlements: ent.ok ? ent.data : { unavailable: ent.errorMessage ?? ent.errorCode ?? ent.status },
+            consumeStats: stats.ok ? stats.data : { unavailable: stats.errorMessage ?? stats.errorCode ?? stats.status },
+            subscription,
+            ...(appId ? { appId } : {}),
+            dbUsage,
+            notes: [
+                '套餐/订阅购买与计划管理在 PC 端承载；CLI 仅只读订阅状态。',
+                ...(appId ? [] : ['数据库/存储用量需绑定应用后查询（cloud status / db 亦可参考）。']),
+            ],
+        }, flags);
+        return;
+    }
+    if (sub === 'benefit') {
+        const r = await benefitEntitlements(spaceId, cfg);
+        if (!r.ok || !r.data)
+            failApi(r, `查询权益失败`);
+        output(r.data, flags);
+        return;
+    }
+    if (sub === 'points') {
+        const op = command[2] ?? 'balance';
+        if (op === 'balance') {
+            const r = await pointBalance(spaceId, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `查询余额失败`);
+            output(r.data, flags);
+            return;
+        }
+        if (op === 'records') {
+            const r = await pointRecords(spaceId, {
+                pageIndex: pickString(flags, '--page-index') ?? '1',
+                pageSize: pickString(flags, '--page-size') ?? '20',
+                ...(pickString(flags, '--flow-type') ? { flowType: pickString(flags, '--flow-type') } : {}),
+            }, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `查询消费记录失败`);
+            output(r.data, flags);
+            return;
+        }
+        if (op === 'stats') {
+            const bizCodes = pickString(flags, '--biz-codes');
+            const r = await pointConsumeStats(spaceId, {
+                pageIndex: pickString(flags, '--page-index') ?? '1',
+                pageSize: pickString(flags, '--page-size') ?? '20',
+                ...(bizCodes ? { bizCodeList: bizCodes.split(',').map(v => v.trim()).filter(Boolean) } : {}),
+                ...(pickString(flags, '--after') ? { gmtCreate: pickString(flags, '--after') } : {}),
+            }, cfg);
+            if (!r.ok || !r.data)
+                failApi(r, `查询消耗统计失败`);
+            output(r.data, flags);
+            return;
+        }
+        fail('用法: qmuse account points balance|records|stats');
+        return;
+    }
+    if (sub === 'plan' || sub === 'subscription') {
+        fail('套餐与订阅由 PC 端承载（暂无 CLI 可用服务端契约），清单该项标注平台依赖');
+    }
+    fail(`未知 account 子命令: ${sub ?? '(空)'}。可用: overview / benefit / points balance|records|stats`);
+}
+async function cmdInfo(command, flags) {
+    // C04.01 + X01.16：同一入口输出 CLI 版本、目录绑定、实际环境、运行约束、云架构与可用操作。
+    if (command.length > 1)
+        fail('用法: qmuse info [--app-id <appId>] [--json]');
+    const cfg = resolveCfg(flags);
+    const apiBaseUrl = `${cfg.baseUrl}${cfg.apiPrefix || ''}`;
+    const binding = loadAppBinding(process.cwd());
+    const managed = await (async () => {
+        try {
+            return await loadManagedProject(process.cwd(), cfg, str(flags, '--env'));
+        }
+        catch {
+            return undefined;
+        }
+    })();
+    const appId = pickString(flags, '--app-id') ?? binding?.appId ?? managed?.target?.appId;
+    const section = async (label, run) => {
+        try {
+            return await run();
+        }
+        catch (err) {
+            return { unavailable: err instanceof Error ? err.message : String(err) };
+        }
+    };
+    const session = !hasAuth(cfg)
+        ? { loggedIn: false }
+        : await section('session', async () => {
+            const r = await api.whoami({ ...cfg, spaceId: undefined });
+            if (!r.ok || !r.data?.userId)
+                return { loggedIn: false, reason: r.status === 401 ? 'session-expired-or-absent' : r.errorMessage ?? r.errorCode };
+            return { loggedIn: true, userId: r.data.userId, userName: r.data.userName, spaceId: r.data.spaceId ?? cfg.spaceId, spaceName: r.data.spaceName ?? null };
+        });
+    const appInfo = appId && hasAuth(cfg)
+        ? await section('app', async () => {
+            const r = await queryAppInfo(appId, cfg);
+            if (!r.ok || !r.data)
+                return { appId, unavailable: r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}` };
+            return { appId, title: r.data.title, appType: r.data.appType, status: r.data.status };
+        })
+        : undefined;
+    const cloud = appId && hasAuth(cfg)
+        ? await section('cloud', async () => {
+            const [ent, env] = await Promise.all([
+                checkCloudEntitlement({ appId: appId, spaceId: cfg.spaceId ?? '' }, cfg).catch(err => ({ unavailable: err instanceof Error ? err.message : String(err) })),
+                cloudEnvironmentStatus(appId, cfg).then(r => r.ok ? r.data : { unavailable: r.errorMessage ?? r.errorCode ?? `HTTP ${r.status}` }),
+            ]);
+            return { entitlement: ent, environment: env };
+        })
+        : undefined;
+    const envFlag = str(flags, '--env');
+    const platformEnv = envFlag === 'prod' || envFlag === 'pre' || envFlag === 'local' ? envFlag : (cfg.baseUrl.includes('-pre.') ? 'pre' : 'prod');
+    const info = {
+        schemaVersion: 1,
+        cli: { name: QMUSE_CLI_NAME, version: QMUSE_CLI_VERSION, distribution: QMUSE_CLI_DISTRIBUTION },
+        environment: {
+            platformEnv,
+            apiBaseUrl,
+            webBaseUrl: cfg.webBaseUrl,
+        },
+        session,
+        bindings: {
+            app: binding ? { appId: binding.appId, title: binding.title ?? null, boundAt: binding.boundAt ?? null } : null,
+            project: managed
+                ? {
+                    appId: managed.target?.appId ?? null,
+                    kind: managed.manifest?.projectKind ?? null,
+                    cloudArchitecture: managed.manifest?.cloudArchitecture ?? null,
+                    templateCommit: managed.manifest?.templateCommit ?? null,
+                    baselineVersionId: managed.target?.lastVersionId ?? null,
+                    baselineSourceHash: managed.target?.lastSourceHash ?? null,
+                }
+                : null,
+        },
+        ...(appId && appInfo ? { app: appInfo } : {}),
+        ...(cloud ? { cloud } : {}),
+        template: {
+            source: 'QMuse GENERAL 项目模板',
+            fetch: 'create/import 时通过 /api/project-template/download 下发（appType=GENERAL）',
+            constraints: [
+                'React + Vite 单页工程；导入前执行 qmuse import <dir> 预检',
+                '远端应用创建与首轮生成走 app create/qmuse chat；本地模板创建走 qmuse create <dir>',
+                '源码上传走 import；下载最新已保存源码走 pull / code export',
+            ],
+        },
+        capabilities: [
+            { domain: '身份与空间', entry: 'login/whoami/logout、space list|use|info', requires: '会话' },
+            { domain: '应用创建与管理', entry: 'app create/list/info/use/current/unlink/update/delete', requires: '会话+空间' },
+            { domain: '初始化与导入', entry: 'create <dir>、import <dir>|status|configure、pull', requires: '会话；导入需要云权益预检' },
+            { domain: '对话与恢复', entry: 'chat send|history|state|cancel|clear|resume、chat attachment upload、models', requires: '会话+应用绑定或显式 appId' },
+            { domain: '本地开发', entry: 'dev [dir]|status|stop', requires: '会话+云资源（云绑定应用）' },
+            { domain: '版本与源码', entry: 'version list|info、code export', requires: '会话+appId' },
+            { domain: '发布与结果', entry: 'deploy --version、release status|list', requires: '会话+appId；发布走平台安全门禁' },
+            { domain: '数据调试', entry: 'data-source list|info、db tables|records|permission', requires: '会话+appId（记录写操作依赖平台数据权限）' },
+            { domain: '云服务与环境', entry: 'cloud init|enable|status|environment retry|pull-env|set-secret|schema', requires: '会话+权益' },
+            { domain: '函数、秘密、沙箱', entry: 'fn …、secret list|create|delete|sync …、sandbox status|logs|health|restart|setting-get', requires: '会话+appId；沙箱写操作依赖平台沙箱通道' },
+            { domain: '官方 Skill', entry: 'agent-skill install|status（指南随 CLI 包内分发）', requires: '本地安装目标' },
+        ],
+        unsupported: [
+            { capability: '套餐与订阅（购买型）', reason: 'PC 端承载；CLI 仅读订阅状态（account overview 汇总，缺少契约时标注 unsupported）' },
+            ...(str(flags, '--env') === 'local' ? [{ capability: '预发专用链路（沙箱/发布门禁）', reason: '本地环境不包含预发后端部署的部分平台组件' }] : []),
+        ],
+    };
+    if (flags['--json'] === true) {
+        output(info, flags);
+        return;
+    }
+    log.info(`QMuse CLI ${QMUSE_CLI_VERSION}（${QMUSE_CLI_DISTRIBUTION}）`);
+    log.info(`API：${apiBaseUrl}    Web：${cfg.webBaseUrl}`);
+    log.info(`会话：${JSON.stringify(session)}`);
+    log.info(`绑定：${JSON.stringify(info.bindings)}`);
+    if (cloud)
+        log.info(`云服务：${JSON.stringify(cloud)}`);
+    log.info('能力入口见 qmuse help；约束见 qmuse info --json 的 template.constraints 与使用规则。');
+}
+/**
+ * 版本闸门执行：blocked 拒绝执行（可绕过项除外），warning 告警，notice 静默（由退出提示负责）。
+ * 策略读不到时一律放行——闸门不可用绝不锁死用户。
+ */
+async function enforceVersionGate(root, flags) {
+    if (root === undefined)
+        return;
+    const gateEnabled = process.env.QMUSE_VERSION_GATE !== 'off';
+    if (!gateEnabled)
+        return;
+    // 策略来源：显式环境变量优先（自测/内网固定策略），否则读 registry 包元数据。
+    const provider = process.env.QMUSE_VERSION_POLICY
+        ? envPolicyProvider()
+        : registryPolicyProvider({ distribution: QMUSE_CLI_DISTRIBUTION, timeoutMs: 1500 });
+    const check = await checkVersionGate({
+        command: root,
+        distribution: QMUSE_CLI_DISTRIBUTION,
+        provider,
+    });
+    const { decision } = check;
+    if (decision.level === 'blocked' && check.blocked) {
+        // 只抛结构化错误，由统一出口渲染一次（文本/JSON 皆然），避免重复输出。
+        throw new CliError(buildCliError({
+            errorCode: 'VERSION_BLOCKED',
+            errorMessage: decision.message ?? '当前 CLI 版本已停止支持，请升级后继续使用',
+            hint: `升级命令：${decision.upgradeCommand}`,
+            details: {
+                current: decision.current,
+                ...(decision.latest ? { latest: decision.latest } : {}),
+                ...(decision.minRequired ? { minRequired: decision.minRequired } : {}),
+            },
+        }));
+    }
+    if (decision.level === 'warning' && flags['--json'] !== true) {
+        log.warn(`${decision.message ?? 'CLI 版本过旧，建议尽快升级'}（当前 ${decision.current}${decision.latest ? `，最新 ${decision.latest}` : ''}）`);
+        log.info(`升级命令：${decision.upgradeCommand}`);
+    }
+}
+/** qmuse upgrade：自查最新版本并执行升级（闸门对自身放行）。 */
+async function cmdUpgrade(command, flags) {
+    if (command.length > 1)
+        fail('用法：qmuse upgrade [--json]', { code: 'INVALID_ARGUMENTS' });
+    log.info('检查最新版本…');
+    const provider = registryPolicyProvider({ distribution: QMUSE_CLI_DISTRIBUTION, timeoutMs: 5000 });
+    const snapshot = await provider();
+    if (!snapshot?.latest) {
+        fail('无法获取最新版本信息', {
+            code: 'CHECK_FAILED',
+            hint: '请检查网络连接；也可手动执行 ' + defaultUpgradeCommand(QMUSE_CLI_DISTRIBUTION),
+        });
+    }
+    const latest = snapshot.latest;
+    const current = QMUSE_CLI_VERSION;
+    const upToDate = !shouldUpgrade(current, latest);
+    if (upToDate) {
+        if (flags['--json'] === true) {
+            output({ success: true, current, latest, upToDate: true, skillSync: syncInstalledSkills() }, flags);
+            return;
+        }
+        log.success(`当前已是最新版本（${current}）`);
+        // 即使 CLI 已最新，仍顺带把已安装的官方指南对齐到当前包（不新建目标、不覆盖用户修改）。
+        reportSkillSync(syncInstalledSkills());
+        return;
+    }
+    if (flags['--json'] !== true) {
+        log.info(`当前版本：${current}`);
+        log.info(`最新版本：${latest}`);
+        log.info('正在升级…');
+    }
+    const distribution = QMUSE_CLI_DISTRIBUTION;
+    const args = distribution === 'PUBLIC'
+        ? ['install', '-g', `@qmuse/qmuse-cli@${latest}`, '--registry=https://registry.npmjs.org/']
+        : ['install', '-g', `@alipay/qmuse-cli@${latest}`];
+    const result = await new Promise((resolve) => {
+        const child = spawn('npm', args, { stdio: flags['--json'] === true ? 'pipe' : 'inherit', shell: process.platform === 'win32' });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => { stderr += chunk.toString('utf8'); });
+        child.on('close', (code) => resolve(code === 0 ? { ok: true } : { ok: false, detail: stderr.slice(-500) }));
+        child.on('error', (error) => resolve({ ok: false, detail: error.message }));
+    });
+    if (!result.ok) {
+        fail('升级失败', {
+            code: 'UPGRADE_FAILED',
+            hint: `尝试手动执行：${defaultUpgradeCommand(distribution)}`,
+            ...(result.detail ? { details: { stderr: sanitizeMessage(result.detail) } } : {}),
+        });
+    }
+    // 升级成功后顺带同步「已存在」的官方指南安装（不新建目标、不覆盖用户修改、失败不影响升级结论）。
+    const skillSync = syncInstalledSkills();
+    if (flags['--json'] === true) {
+        output({ success: true, from: current, to: latest, skillSync }, flags);
+        return;
+    }
+    log.success(`已升级到 ${latest}`);
+    reportSkillSync(skillSync);
+}
+/** 输出指南同步结果（升级前后共用）。 */
+function reportSkillSync(items) {
+    if (items.length === 0) {
+        log.info('未检测到已安装的官方指南；需要时执行 qmuse agent-skill install');
+        return;
+    }
+    for (const item of items) {
+        const label = item.agent ? `${item.agent}` : item.address;
+        if (item.outcome === 'refreshed')
+            log.success(`官方指南已同步（${label}）`);
+        else if (item.outcome === 'up-to-date')
+            log.info(`官方指南已是当前版本（${label}）`);
+        else if (item.outcome === 'skipped-user-modified')
+            log.warn(`保留你对官方指南的修改（${label}）：${item.detail ?? ''}`);
+        else
+            log.warn(`官方指南同步失败（${label}）：${item.detail ?? ''}`);
+    }
+}
+async function cmdLogin(flags) {
+    const cfg = resolveCfg(flags);
+    if (flags['--status'] === true) {
+        const out = await login.loginStatus(cfg);
+        // T01.03：会话查询结果来源（匿名请求 traceId 由 cli.http.request 记录）。
+        recordEvent({ kind: 'cli.auth.event', stage: 'status', result: out.success ? 'ok' : 'failed' });
+        if (out.success)
+            log.success(out.message ?? '会话有效');
+        else
+            log.error(out.message ?? '会话无效');
+        return;
+    }
+    log.info(`登录方式：browser    目标：${cfg.baseUrl}${cfg.apiPrefix || ''}`);
+    const out = await login.loginBrowser(cfg, {
+        logRequestDetails: flags['--log'] === true,
+    });
+    // T01.03：登录结果事件（匿名请求 traceId 已随 cli.http.request 保留；凭证仅入系统凭证库）。
+    recordEvent({ kind: 'cli.auth.event', stage: 'browser-login', result: out.success ? 'ok' : 'failed',
+        ...(out.method ? { status: out.method } : {}) });
+    if (out.success) {
+        login.closePrompt();
+        log.success(`登录成功（${out.method}）`);
+        if (flags['--json'] === true)
+            output({ success: true, method: out.method }, flags);
+    }
+    else {
+        login.closePrompt();
+        fail(out.message ?? '登录失败');
+    }
+}
+async function cmdLogout(flags) {
+    const cfg = resolveCfg(flags);
+    const hadSession = !!(cfg.sessionId || '').trim();
+    deleteSession(cfg);
+    if (hadSession) {
+        log.success('已清除当前环境的登录态和空间选择');
+    }
+    else {
+        log.info('当前未配置登录态；已清除空间选择');
+    }
+}
+// ---------------- 帮助 & 入口 ----------------
+async function cmdCreate(command, flags) {
+    if (command.length !== 2)
+        fail('用法：qmuse create <directory>');
+    const result = await createProject(command[1], resolveCfg(flags));
+    if (flags['--json'] === true) {
+        output(result, flags);
+        return;
+    }
+    log.success(`模板已下载到 ${result.directory}`);
+    log.info('进入项目目录后执行：npm install');
+    log.info(`开发完成后执行：qmuse${str(flags, '--env') ? ` --env ${str(flags, '--env')}` : ''} import .`);
+}
+const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
+
+用法:
+  qmuse [global flags] <command> [subcommand] [flags]
+
+全局 flags:
+  --env <env>           环境预设：prod / pre / local
+  --json                结果以 JSON 输出
+  --log                 打印登录请求接口和页面地址（不含登录凭证）
+
+  全局 flags 可放在命令前或命令后
+
+命令:
+  whoami                                            查看当前环境、登录和空间状态
+  login [--status] [--log] [--json]                 通过 QMuse 网页登录
+  logout                                            清除保存的登录态和空间选择
+  config [get|path]                                 查看配置
+
+  create <directory>                               下载 QMuse 模板并解压到新项目目录
+  pull [directory]                                 免费同步已导入应用的最新已保存源码（本地有改动时停止）
+
+  chat history --app-id <id> --sprint-id <id>       按应用和迭代查询会话与历史
+  chat state <chatId>                              查询会话执行状态与阶段
+  chat cancel <chatId> --app-id <id>               发送停止指令（以服务端状态为准）
+  chat clear <chatId> --app-id --sprint-id         清理会话上下文
+  chat send --app-id --chat-id --file <路径|->      已有应用继续对话（统一 continue 接口）
+      [--model <model>] [--skill <skillId> --skill-version <versionId>]
+  chat resume <chatId> --interrupt-id <id>          恢复等待输入/云资源中断（--file 回答 JSON）
+      --file <路径|-> --app-id <id> [--ndjson]
+  chat attachment upload <path> --app-id <id>      上传应用版本附件
+  models                                           查询可选模型列表
+  version list|info --app-id <id>                  查询应用版本列表/详情
+  code export --app-id <id> --output <dir>         导出应用最新已保存源码
+  deploy --version <versionId> [--no-wait]         固定版本发布（受理后退出用 --no-wait）
+      [--app-id <id>]
+  release status <releaseId> [--wait]              查询发布任务详情/检查/地址/失败原因
+  release list --app-id <id>                       查询应用发布记录（--last 查最近一次）
+  info [--app-id <id>]                             CLI 版本/环境/绑定/模板约束/云架构/能力
+  agent-skill install --agent codex                安装包内官方研发指南（--target 覆盖；--force 覆盖修改）
+  agent-skill status [--agent codex|--target <dir>] 查询指南安装状态与用户修改
+  upgrade                                          自查最新版本并升级 CLI（--json 结构化输出）
+  account overview|benefit|points …                 空间余额/权益/喵币消耗/订阅状态（--space-id）
+  data-source list|info                            应用数据源与表元数据（--app-id）
+  db tables|record|list|get|create|update|delete|permission   应用数据表与记录（--app-id --form-id）
+  fn list|info|retry|deployment-*|execution-*      云函数查询与发布重试（--app-id）
+  secret list|create|enable|disable|delete          云秘密管理（--app-id；删除需先停用且 --yes）
+      [--cloud-env dev|prod]
+  secret sync status|retry                          查询/重试秘密同步状态（--app-id）
+  sandbox status --app-id <id>                     汇总沙箱配置/预览/健康及失败原因
+      [--sandbox-id <id>] [--json]
+  sandbox logs --app-id <id>                       现有接口可提供的构建/任务诊断日志
+      [--sandbox-id <id>] [--version-id <id>] [--build-id <id>]
+  sandbox health|restart|setting-get|ensure        沙箱其余只读与显式重启入口
+  app create <web|h5> --file <路径|->               统一创建应用并开始首轮生成（预发接口）
+      [--title <title>] [--space-id <id>] [--request-id <cc_时间戳_随机hex>]
+      [--model <model>] [--no-open] [--json|--ndjson]
+  app list [--space-id <id>] [--keyword <kw>]        查询空间应用列表
+  app info <appId>                                   查询应用详情
+  app use / current / unlink                         绑定、查看、解除本地应用绑定
+  app update <appId> [--title <t>] [--description <d>] [--require-login 0|1] [ --default-device <d>]
+                                                     修改应用信息
+  app delete <appId> --yes                           删除应用（不可恢复）
+
+  cloud init -d "<应用功能描述>"                    校验当前空间的 QMuse 云服务权益
+  cloud enable [--app-id <id>]                      实际开通云服务（复用既有权益判断）
+  cloud status [--app-id <id>]                      查询架构/云环境/初始化状态与失败原因
+  cloud environment retry --app-id <id> [--wait]    重试云环境初始化（复用原任务）
+  cloud pull-env --app-id <id> --output <path>      导出实际环境公开连接与运行配置
+  cloud set-secret KEY1,KEY2 --stdin                从标准输入 JSON 保存密钥，不输出密钥值
+      [--app-id <id>] [--cloud-env dev|prod]
+  cloud schema preflight --candidate <schema.json>  只读校验候选与云端 READY 基线
+  cloud schema export [--app-id <id>]               输出当前开发环境的 READY schema
+  dev [directory] [--port <port>]                   连接已导入应用的开发云资源并启动本地 Vite
+
+  assets upload <file> [more-files...] --json      上传媒体到 CDN，返回引用替换清单
+  import <directory> [--space-id <id>]             导入本地 React 仓库
+      [--title <title>] [--force] [--cloud-mode AUTO|EXTERNAL|QMUSE]
+      [--public-config '<json>'|@file] [--acknowledge-empty-cloud-data]
+      [--confirm-cloud-service]
+      [--no-open] [--json] [--log]
+  import status <jobId> [--wait] [--no-open]        查询或恢复等待导入任务
+  import configure <jobId> --cloud-mode <mode>      补充云服务配置后继续任务
+
+  space list                                        我加入的空间列表
+  space use <spaceId>                               设为当前空间（后续带 x-space-id 头）
+  space info                                        当前空间信息
+
+典型流程:
+  qmuse login
+  qmuse space list
+  qmuse space use S640459450135
+  qmuse create my-app
+  qmuse import /path/to/react-vite-app
+`;
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0) {
+        recordCommandEvent('help', 0, Date.now());
+        process.stdout.write(HELP);
+        return;
+    }
+    const { command, flags } = parseArgs(argv);
+    if (flags['--help'] === true || flags['-h'] === true) {
+        recordCommandEvent(currentCommandLabel(command), 0, Date.now());
+        process.stdout.write(HELP);
+        return;
+    }
+    if (flags['--version'] === true || flags['-V'] === true) {
+        recordCommandEvent('version', 0, Date.now());
+        process.stdout.write(`qmuse ${QMUSE_CLI_VERSION}\n`);
+        return;
+    }
+    const root = command[0];
+    const commandLabel = currentCommandLabel(command);
+    setTelemetryCommand(commandLabel, str(flags, '--env'));
+    const commandStartedAt = Date.now();
+    recordEvent({ kind: 'cli.command.start', command: commandLabel,
+        environment: str(flags, '--env') });
+    // MAU：模拟 Tracert dwcookie 协议上报到蚂蚁采集平台
+    trackCommand(commandLabel.replace(/ /gu, '-'), resolveCfg(flags));
+    const finishUpdateNotice = startUpdateNotice({
+        enabled: root === 'import' && process.stderr.isTTY === true && flags['--json'] !== true,
+        notify: message => process.stderr.write(`${message}\n`),
+    });
+    process.once('exit', finishUpdateNotice);
+    try {
+        // 版本闸门（失败降级放行）：blocked 拒绝执行，warning 告警，notice 仅退出提示。
+        await enforceVersionGate(root, flags);
+        switch (root) {
+            case 'whoami':
+                await cmdWhoami(flags);
+                return;
+            case 'login':
+                await cmdLogin(flags);
+                return;
+            case 'logout':
+                await cmdLogout(flags);
+                return;
+            case 'config':
+                await cmdConfig(command, flags);
+                return;
+            case 'create':
+                await cmdCreate(command, flags);
+                return;
+            case 'account':
+                await cmdAccount(command, flags);
+                return;
+            case 'data-source':
+                await cmdDataSources(command, flags);
+                return;
+            case 'db':
+                await cmdDb(command, flags);
+                return;
+            case 'app':
+                await cmdApp(command, flags);
+                return;
+            case 'chat':
+                await cmdChat(command, flags);
+                return;
+            case 'models':
+                await cmdModels(command, flags);
+                return;
+            case 'version':
+                await cmdVersions(command, flags);
+                return;
+            case 'code':
+                await cmdCodeExport(command, flags);
+                return;
+            case 'fn':
+                await cmdFn(command, flags);
+                return;
+            case 'secret':
+                await cmdSecret(command, flags);
+                return;
+            case 'sandbox':
+                await cmdSandbox(command, flags);
+                return;
+            case 'pull': {
+                if (command.length > 2 || Object.keys(flags).some(key => !['--env', '--json'].includes(key))) {
+                    throw new Error('用法：qmuse pull [directory] [--env prod|pre|local] [--json]');
+                }
+                const result = await withOperationLog({ directory: command[1] || '.', command: 'pull',
                     report: summary => reportCliOperation(summary, resolveCfg(flags)) }, () => pullProject(command[1] || '.', resolveCfg(flags), str(flags, '--env')));
                 if (flags['--json'] === true)
                     output(result, flags);
@@ -985,11 +2952,30 @@ async function main() {
                     if (!result.noChanges)
                         log.info('修改完成后执行 qmuse import，更新同一应用。');
                 }
+                // T01.05：下载来源与同步基线（noChanges 显式区分，不静默覆盖本地修改）。
+                recordEvent({ kind: 'cli.transfer.result', route: '/api/app-import/pull',
+                    result: result.noChanges ? 'no-changes' : 'ok',
+                    ...(result.versionId ? { status: 'synced' } : {}) });
                 return;
             }
             case 'cloud':
                 await cmdCloud(command, flags);
                 return;
+            case 'deploy':
+                await cmdDeploy(command, flags);
+                return;
+            case 'release':
+                await cmdRelease(command, flags);
+                return;
+            case 'info':
+                await cmdInfo(command, flags);
+                return;
+            case 'agent-skill':
+                await cmdAgentSkill(command, flags);
+                return;
+            case 'upgrade':
+                await cmdUpgrade(command, flags);
+                return;
             case 'dev':
                 await cmdDev(command, flags);
                 return;
@@ -1017,17 +3003,38 @@ async function main() {
                 process.stdout.write(HELP);
                 return;
             default:
-                fail(`未知命令: ${root ?? '(空)'}。\n\n${HELP}`);
+                fail(`未知命令: ${root ?? '(空)'}`, {
+                    code: 'UNKNOWN_COMMAND',
+                    hint: '运行 qmuse help 查看全部命令与参数',
+                    details: { help: HELP },
+                });
         }
     }
     catch (err) {
         finishUpdateNotice();
-        const msg = err instanceof Error ? err.message : String(err);
+        const info = err instanceof CliError
+            ? err.info
+            : buildCliError({ errorMessage: sanitizeMessage(err instanceof Error ? err.message : String(err)) });
         if (flags['--json'] === true) {
-            output({ success: false, message: msg }, flags);
+            output({
+                success: false,
+                error: {
+                    code: info.code,
+                    message: info.message,
+                    ...(info.hint ? { hint: info.hint } : {}),
+                    ...(info.traceId ? { traceId: info.traceId } : {}),
+                    ...(info.details ? { details: info.details } : {}),
+                },
+                // 兼容：老消费者读 message
+                message: info.message,
+            }, flags);
         }
         else {
-            log.error(msg);
+            log.error(info.message);
+            if (info.hint)
+                log.info(info.hint);
+            if (info.traceId)
+                log.info(`traceId: ${info.traceId}`);
         }
         process.exitCode = 1;
     }
@@ -1035,6 +3042,70 @@ async function main() {
         closePrompt();
         finishUpdateNotice();
         process.off('exit', finishUpdateNotice);
+        // T01.01：命令结束事件（含帮助/版本/失败与 exitCode）。
+        recordEvent({ kind: 'cli.command.end', command: commandLabel, durationMs: Date.now() - commandStartedAt,
+            result: process.exitCode ? 'error' : 'ok', environment: str(flags, '--env') });
+        // T01.15：网络补报已由服务端 AOP 中间件替代——CLI 每个业务请求都在
+        // 请求头携带 x-qmuse-client/-version/-distribution/-invocation-id/-command，
+        // 服务端 cliSourceMetrics 中间件自动观测并落库（调用侧不感知，无独立端点）。
+        // 本地 JSONL 队列保留为排障用（telemetry.ts），不再向服务端发送。
+    }
+}
+/** S01：官方 CLI Skill 的离线安装与状态查询（指南随包内分发，不新增对话命令）。 */
+async function cmdAgentSkill(command, flags) {
+    const sub = command[1];
+    const agent = pickString(flags, '--agent') ?? (pickString(flags, '--target') ? undefined : 'codex');
+    const explicitTarget = pickString(flags, '--target');
+    const targetRoot = explicitTarget
+        ? explicitTarget.replace(/^\$HOME(?=\/|$)/u, homedir())
+        : agent ? defaultTargetForAgent(agent) : undefined;
+    if (sub === 'install') {
+        if (!targetRoot)
+            fail('用法: qmuse agent-skill install --agent codex [--target <dir>] [--force] [--json]');
+        const result = installAgentSkill({
+            targetRoot,
+            agent: agent ?? 'custom',
+            force: flags['--force'] === true,
+        });
+        // T01.11：安装事件（记录指南版本与目标助手类型，不记录本机私有路径）。
+        recordEvent({ kind: 'cli.skill.event', stage: 'install', result: 'ok',
+            agent: agent ?? 'custom', target: 'skill-content' });
+        if (flags['--json'] === true)
+            output({ success: true, ...result }, flags);
+        else {
+            log.success(result.replaced ? `官方指南已安装到 ${result.address}` : `官方指南已是最新（${result.manifest.cliVersion}）：${result.address}`);
+            log.info(`包含 SKILL.md、references/cloud.md、references/core-flows.md（共 ${result.installedFiles.length} 个文件）`);
+        }
+        return;
+    }
+    if (sub === 'status') {
+        if (!targetRoot)
+            fail('用法: qmuse agent-skill status [--agent codex] [--target <dir>] [--json]');
+        const report = skillStatus(targetRoot);
+        // T01.11：状态查询事件。
+        recordEvent({ kind: 'cli.skill.event', stage: 'status', result: report.installed ? 'ok' : 'not-installed' });
+        if (flags['--json'] === true) {
+            output(report, flags);
+            return;
+        }
+        log.info(`包内指南版本：${report.packagedVersion}（${report.packagedAvailable ? `${report.packagedFiles} 个文件` : '缺失，请重装 CLI'}）`);
+        if (!report.installed)
+            log.warn('当前目标未安装官方指南；执行 qmuse agent-skill install --agent codex');
+        else {
+            log.info(`已安装：${report.installed.address}`);
+            log.info(`安装版本：${report.installed.cliVersion ?? '(早期安装，无元数据)'}${report.installed.matchesPackagedVersion ? '（与 CLI 一致）' : '（与当前 CLI 不一致，建议重新安装）'}`);
+            if (report.installed.modifiedFiles.length > 0) {
+                log.warn(`用户修改保留中：${report.installed.modifiedFiles.join(', ')}（覆盖需 --force）`);
+            }
+        }
+        return;
     }
+    fail(`未知 agent-skill 子命令: ${sub ?? '(空)'}。可用: install / status（指南随 CLI 包内分发）`);
+}
+/** 帮助/版本等无命令上下文路径的结束事件（T01.01 覆盖帮助与版本输出）。 */ function recordCommandEvent(label, exitCode, startedAt) {
+    setTelemetryCommand(label);
+    recordEvent({ kind: 'cli.command.start', command: label });
+    recordEvent({ kind: 'cli.command.end', command: label, durationMs: Math.max(0, Date.now() - startedAt),
+        result: exitCode ? 'error' : 'ok' });
 }
 main();