@qmuse/qmuse-cli 1.0.3-dev.4 → 1.0.3-dev.5

package/README.md

@@ -50,7 +50,7 @@ qmuse import /path/to/react-project --space-id <spaceId>
 
 ### 更新已有应用
 
-从 QMuse 下载的项目，在项目根目录执行 `qmuse import .` 即可更新对应应用；没有关联应用时会创建新应用。普通外部项目每次导入都会创建新应用。
+没有关联应用时，首次导入会创建新应用并自动保存本地绑定。之后在同一项目目录执行 `qmuse import .`，即可更新对应应用。请保留 `.qmuse/project.json`，从 QMuse 下载且带有绑定的项目也使用相同命令更新。
 
 平台已有新版本时，终端会询问是否用本地全部源码覆盖，不会自动合并平台修改。确认覆盖可执行 `qmuse import . --force`；脚本或 `--json` 模式须显式指定该参数。覆盖会在原应用创建新版本，仍需通过正常导入校验。
 
@@ -101,7 +101,7 @@ CLI 将本地 Runtime 的 `__MUSE__.domain` 设置为实际监听地址（如 `h
 
 服务端必须先部署 `/api/appwrite/local-dev/context` 和 `/api/appwrite/local-dev/mutation-events`，再发布并安装新版 CLI；缺少接口时不会降级为模拟云服务。
 
-页面改动热更新，Schema/函数改动继续执行 `qmuse import .`。导入更新本地绑定后，连接会重新获取配置并刷新页面。切换登录账号或应用绑定需重启连接；退出 CLI 不会自动撤销浏览器已经建立的 AppBase Session。SDK 的匿名降级行为保持不变，验收必须检查实际 Session 用户，不能只看页面是否显示。
+页面改动热更新，Schema/函数改动继续执行 `qmuse import .`。CLI 启动期间设置 `QMUSE_HMR_GATE_ENABLED=false`，退出后恢复原值；项目的 `@qmuse/vite-config` 必须支持此开关，否则平台批量改码门禁仍会暂存本地修改。导入更新本地绑定后，连接会重新获取配置并刷新页面。切换登录账号或应用绑定需重启连接；退出 CLI 不会自动撤销浏览器已经建立的 AppBase Session。SDK 的匿名降级行为保持不变，验收必须检查实际 Session 用户，不能只看页面是否显示。
 
 联调验收包括 CRUD、刷新读回、文件上传/预览、函数调用和权限拒绝；浏览器 Cookie 限制需在目标浏览器验证。`.muse-tmp`、`.qmuse` 和系统临时配置不进入导入包。
 

package/dist/cli.js

@@ -17,9 +17,10 @@ import { configureAppImport, getAppOpenUrl, getImportStatusUrl, queryAppImportSt
 import { pollAppImport } from './import/poll.js';
 import { preflightImport } from './import/preflight.js';
 import { resolveUpdateBase } from './import/update.js';
-import { clearPendingImport, completeManagedImport, loadManagedProject, saveManagedProject, setPendingImport, } from './import/project.js';
-import { clearImportFailureDiagnostic, writeImportFailureDiagnostic, } from './import/diagnostic.js';
-import { checkCloudInit, CLOUD_INIT_SUCCESS_MESSAGE } from './cloud.js';
+import { clearPendingImport, completeManagedImport, createExternalProject, loadManagedProject, saveManagedProject, resolveProjectEnvironment, setPendingImport, } from './import/project.js';
+import { clearImportFailureDiagnostic, writeImportFailureDiagnostic, importRetryGuidance, } from './import/diagnostic.js';
+import { checkCloudInit, checkCloudEntitlement, CLOUD_INIT_SUCCESS_MESSAGE } from './cloud.js';
+import { configurationGuidance } from './import/guidance.js';
 import { QMUSE_CLI_VERSION } from './version.js';
 import { startUpdateNotice } from './update-notice.js';
 import { startDevelopment } from './dev/index.js';
@@ -191,11 +192,14 @@ async function pollImportWithLogs(jobId, cfg, flags) {
         process.removeListener('SIGINT', onInterrupt);
     }
 }
-async function resolveImportConfiguration(status, cfg, flags) {
+async function resolveImportConfiguration(status, cfg, flags, cloudTarget) {
     if (status.stage === 'QMUSE_CLOUD_ADAPTATION_REQUIRED')
         return undefined;
     const interactive = process.stdin.isTTY === true && flags['--json'] !== true;
     let cloudMode = parseImportCloudMode(str(flags, '--cloud-mode'));
+    if (cloudMode === 'AUTO' && ['QMUSE', 'EXTERNAL'].includes(status.cloudMode ?? '')) {
+        cloudMode = status.cloudMode;
+    }
     if (cloudMode === 'AUTO') {
         if (!interactive)
             return undefined;
@@ -235,6 +239,8 @@ async function resolveImportConfiguration(status, cfg, flags) {
         if (!acknowledgeEmptyCloudData)
             return undefined;
     }
+    if (cloudMode === 'QMUSE')
+        await checkCloudEntitlement(cloudTarget, cfg);
     const configured = await configureAppImport({
         jobId: status.jobId,
         cloudMode,
@@ -251,23 +257,34 @@ async function resolveImportConfiguration(status, cfg, flags) {
 }
 async function finishImport(status, sourceHash, cfg, flags, managedProject, rootDir) {
     if (status.status !== 'READY' || !status.appId || !status.versionId) {
+        const guidance = configurationGuidance(status, resolveProjectEnvironment(cfg, str(flags, '--env')), parseImportCloudMode(str(flags, '--cloud-mode')));
         if (flags['--json'] === true) {
-            output({ success: false, ...status }, flags);
+            output({ success: false, ...status, ...(guidance ? { configurationRequired: guidance } : {}) }, flags);
         }
         else {
             printImportStatus(status, flags);
             if (status.status === 'FAILED')
                 log.error('导入失败');
-            else
-                log.warn(`任务需要继续配置，可执行 qmuse import status ${status.jobId} --wait`);
+            else if (guidance) {
+                log.warn(guidance.message);
+                if (guidance.resumeCommand)
+                    log.warn(`继续配置：${guidance.resumeCommand}`);
+                if (guidance.waitCommand)
+                    log.warn(`配置后在原项目目录执行：${guidance.waitCommand}`);
+            }
         }
         process.exitCode = status.status === 'FAILED' ? 1 : 2;
         if (status.status === 'FAILED' && rootDir) {
-            const diagnosticPath = await writeImportFailureDiagnostic({ rootDir, status });
+            const diagnosticProject = managedProject ?? await loadManagedProject(rootDir, cfg, str(flags, '--env'));
+            const diagnosticPath = await writeImportFailureDiagnostic({ rootDir, status, project: diagnosticProject,
+                environment: resolveProjectEnvironment(cfg, str(flags, '--env')) });
             if (flags['--json'] !== true) {
                 log.warn(`诊断已写入 ${diagnosticPath}`);
                 if (status.failureDiagnostic?.fixableByModel) {
-                    log.warn(`请让当前大模型读取 ${diagnosticPath}，修复源码后执行 qmuse import .`);
+                    const retry = importRetryGuidance(status, diagnosticProject);
+                    log.warn(`请让当前大模型读取 ${diagnosticPath}，修复源码。${retry.retryAdvice}`);
+                    if (retry.retryCommand)
+                        log.warn(retry.retryCommand);
                 }
             }
         }
@@ -369,27 +386,53 @@ async function cmdImport(command, flags) {
         const mode = parseImportCloudMode(str(flags, '--cloud-mode'));
         if (mode === 'AUTO')
             fail('configure 必须指定 --cloud-mode EXTERNAL 或 QMUSE');
+        const current = await queryAppImportStatus(jobId, cfg);
+        if (!current.ok || !current.data)
+            throw new Error(`查询导入任务失败：${current.errorMessage ?? current.errorCode}`);
+        const guidance = configurationGuidance(current.data, resolveProjectEnvironment(cfg, str(flags, '--env')), mode);
+        if (mode === 'QMUSE' && guidance?.requiredFlags?.some(flag => flags[flag] !== true)) {
+            await finishImport(current.data, undefined, cfg, flags);
+            return;
+        }
+        if (mode === 'QMUSE') {
+            const project = await loadManagedProject(process.cwd(), cfg, str(flags, '--env'));
+            const pending = project?.manifest.pendingImports?.[project.environment];
+            const matchingProject = pending?.jobId === jobId ? project : undefined;
+            const appId = current.data.appId || matchingProject?.target?.appId;
+            const spaceId = pending?.jobId === jobId ? pending.spaceId : str(flags, '--space-id');
+            if (appId || spaceId)
+                await checkCloudEntitlement({ appId, spaceId: spaceId ?? '' }, cfg);
+        }
         const result = await configureAppImport({
             jobId,
             cloudMode: mode,
             ...(mode === 'EXTERNAL'
                 ? { publicConfig: readPublicConfig(str(flags, '--public-config')) }
-                : flags['--confirm-cloud-service'] === true
-                    ? { confirmCloudService: true }
-                    : { acknowledgeEmptyCloudData: flags['--acknowledge-empty-cloud-data'] === true }),
+                : {
+                    confirmCloudService: flags['--confirm-cloud-service'] === true,
+                    acknowledgeEmptyCloudData: flags['--acknowledge-empty-cloud-data'] === true,
+                }),
         }, cfg);
         if (!result.ok || !result.data) {
             fail(`提交导入配置失败：${result.errorMessage ?? result.errorCode ?? `HTTP ${result.status}`}`);
         }
-        printImportStatus(result.data, flags);
+        if (['WAITING_CLOUD_CONFIRMATION', 'NEEDS_CONFIGURATION', 'FAILED'].includes(result.data.status)) {
+            await finishImport(result.data, undefined, cfg, flags);
+        }
+        else
+            printImportStatus(result.data, flags);
         return;
     }
     const directory = subcommand;
     if (!directory)
         fail('用法: qmuse import <directory> [--space-id <id>]');
     const rootDir = path.resolve(directory);
-    await clearImportFailureDiagnostic(rootDir);
-    const managedProject = await loadManagedProject(rootDir, cfg, str(flags, '--env'));
+    const managedProject = await loadManagedProject(rootDir, cfg, str(flags, '--env')) ??
+        createExternalProject(rootDir, cfg, str(flags, '--env'));
+    const pendingImport = managedProject.manifest.pendingImports?.[managedProject.environment];
+    if (pendingImport) {
+        throw new Error(`当前目录有尚未完成的导入任务，请先执行 qmuse import status ${pendingImport.jobId} --wait --env ${managedProject.environment}，避免重复创建应用`);
+    }
     const explicitSpaceId = str(flags, '--space-id');
     const operation = managedProject?.target ? 'UPDATE' : 'CREATE';
     if (flags['--force'] === true && !managedProject?.target) {
@@ -435,6 +478,12 @@ async function cmdImport(command, flags) {
             log.success('源码没有变化，无需创建新版本');
         return;
     }
+    if (cloudMode === 'QMUSE') {
+        const quota = await checkCloudEntitlement({ appId: managedProject.target?.appId, spaceId }, cfg);
+        if (flags['--json'] !== true && quota.appLimit !== undefined) {
+            log.info(`QMuse 云服务额度：已使用 ${quota.enabledAppCount ?? 0}/${quota.appLimit}${quota.alreadyEnabled ? '（当前应用已开通）' : ''}`);
+        }
+    }
     if (flags['--json'] !== true) {
         log.success(`识别为 React 项目（${preflight.fileCount} 个文件）`);
         if (flags['--log'] === true) {
@@ -449,6 +498,7 @@ async function cmdImport(command, flags) {
     const archive = await createImportArchive(preflight);
     let sourceToken;
     try {
+        await saveManagedProject(managedProject);
         sourceToken = await uploadImportArchive({
             filePath: archive.filePath,
             spaceId,
@@ -467,7 +517,7 @@ async function cmdImport(command, flags) {
         sourceType: 'REACT_VITE',
         cloudMode,
         idempotencyKey: str(flags, '--idempotency-key'),
-        sourceScenario: managedProject ? 'QMUSE_TEMPLATE' : 'EXTERNAL_REPOSITORY',
+        sourceScenario: managedProject.manifest.projectKind,
         operation,
         ...(managedProject?.target
             ? {
@@ -495,7 +545,7 @@ async function cmdImport(command, flags) {
         log.success(`已创建导入任务 ${jobId}`);
     let polled = await pollImportWithLogs(jobId, cfg, flags);
     while (polled.reason === 'CONFIGURATION_REQUIRED' && polled.status) {
-        const configured = await resolveImportConfiguration(polled.status, cfg, flags);
+        const configured = await resolveImportConfiguration(polled.status, cfg, flags, { appId: managedProject.target?.appId, spaceId });
         if (!configured) {
             await finishImport(polled.status, preflight.sourceHash, cfg, flags, managedProject, rootDir);
             return;
@@ -769,7 +819,12 @@ async function main() {
     catch (err) {
         finishUpdateNotice();
         const msg = err instanceof Error ? err.message : String(err);
-        fail(msg);
+        if (flags['--json'] === true) {
+            output({ success: false, message: msg }, flags);
+            process.exitCode = 1;
+        }
+        else
+            fail(msg);
     }
     finally {
         finishUpdateNotice();

package/dist/cloud.js

@@ -20,6 +20,9 @@ export async function checkCloudInit(rootDir, cfg, explicitEnvironment) {
     if (!spaceId) {
         throw new Error('请先执行 qmuse space use <spaceId>，或通过 --space-id 指定目标空间');
     }
+    return checkCloudEntitlement({ appId, spaceId }, cfg);
+}
+export async function checkCloudEntitlement({ appId, spaceId }, cfg) {
     const response = appId
         ? await apiCall('POST', '/api/appwrite/entitlement/check', { appId }, cfg)
         : await apiCall('POST', '/api/appwrite/entitlement/space/check', { spaceId }, cfg);

package/dist/dev/index.js

@@ -26,6 +26,7 @@ export async function startDevelopment(options) {
     const directory = await mkdtemp(path.join(tmpdir(), 'qmuse-local-dev-'));
     const runtimePath = path.join(directory, 'runtime.json');
     const previousPath = process.env.MUSE_RUNTIME_CONFIG_PATH;
+    const previousHmrGate = process.env.QMUSE_HMR_GATE_ENABLED;
     let server;
     let closed = false;
     const manifestPath = path.join(root, '.qmuse/project.json');
@@ -58,11 +59,16 @@ export async function startDevelopment(options) {
                 delete process.env.MUSE_RUNTIME_CONFIG_PATH;
             else
                 process.env.MUSE_RUNTIME_CONFIG_PATH = previousPath;
+            if (previousHmrGate === undefined)
+                delete process.env.QMUSE_HMR_GATE_ENABLED;
+            else
+                process.env.QMUSE_HMR_GATE_ENABLED = previousHmrGate;
         }
     };
     try {
         await writeRuntime();
         process.env.MUSE_RUNTIME_CONFIG_PATH = runtimePath;
+        process.env.QMUSE_HMR_GATE_ENABLED = 'false';
         const vite = await import(pathToFileURL(vitePath).href);
         server = await vite.createServer({
             root,

package/dist/import/diagnostic.js

@@ -2,6 +2,15 @@ import { randomUUID } from 'node:crypto';
 import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 export const QMUSE_IMPORT_DIAGNOSTIC_PATH = '.qmuse/last-import-error.json';
+export function importRetryGuidance(status, project) {
+    const target = project?.target;
+    const pending = project?.manifest.pendingImports?.[project.environment];
+    const canRetryUpdate = target && status.operation !== 'CREATE' &&
+        (status.appId === target.appId || (!status.appId && pending?.jobId === status.jobId && pending.operation === 'UPDATE'));
+    return canRetryUpdate
+        ? { retryCommand: `qmuse import . --env ${project.environment}`, retryAdvice: '在当前项目目录修复源码后执行，将更新已绑定的应用。' }
+        : { retryCommand: null, retryAdvice: '当前任务没有可确认的原应用绑定。请先核对任务是否已创建应用，并恢复对应环境的项目绑定；直接重新 import 可能创建新应用。' };
+}
 export async function writeImportFailureDiagnostic(input) {
     if (input.status.status !== 'FAILED') {
         throw new Error('只能为失败的导入任务写入诊断文件');
@@ -17,10 +26,18 @@ export async function writeImportFailureDiagnostic(input) {
         message: input.status.message,
         diagnostic: input.status.diagnostic,
         failureDiagnostic: input.status.failureDiagnostic,
-        retryCommand: 'qmuse import .',
+        ...importRetryGuidance(input.status, input.project),
+        environment: input.project?.environment ?? input.environment,
         generatedAt: new Date().toISOString(),
     };
+    const historyPath = path.join(input.rootDir, '.qmuse', 'import-errors', input.project?.environment ?? input.environment ?? 'unknown', `${encodeURIComponent(input.status.jobId)}.json`);
+    await mkdir(path.dirname(historyPath), { recursive: true });
+    const historyTemporaryPath = `${historyPath}.${process.pid}.${randomUUID()}.tmp`;
     try {
+        await writeFile(historyTemporaryPath, `${JSON.stringify(payload, null, 2)}\n`, {
+            encoding: 'utf8', mode: 0o600, flag: 'wx',
+        });
+        await rename(historyTemporaryPath, historyPath);
         await writeFile(temporaryPath, `${JSON.stringify(payload, null, 2)}\n`, {
             encoding: 'utf8',
             mode: 0o600,
@@ -29,6 +46,7 @@ export async function writeImportFailureDiagnostic(input) {
         await rename(temporaryPath, filePath);
     }
     catch (error) {
+        await rm(historyTemporaryPath, { force: true });
         await rm(temporaryPath, { force: true });
         throw error;
     }

package/dist/import/guidance.js

@@ -0,0 +1,35 @@
+export function configurationGuidance(status, environment, requestedMode = 'AUTO') {
+    if (!['WAITING_CLOUD_CONFIRMATION', 'NEEDS_CONFIGURATION'].includes(status.status))
+        return undefined;
+    if (status.stage === 'QMUSE_CLOUD_ADAPTATION_REQUIRED') {
+        return { message: '请先根据诊断完成源码的 QMuse 云服务适配，再重新导入。' };
+    }
+    const mode = requestedMode === 'AUTO' ? status.cloudMode : requestedMode;
+    if (!/^[a-zA-Z0-9_-]+$/u.test(status.jobId))
+        return { message: '任务标识格式异常，请联系平台支持。' };
+    const base = `qmuse import configure ${status.jobId} --env ${environment}`;
+    const waitCommand = `qmuse import status ${status.jobId} --wait --env ${environment} --json`;
+    if (mode === 'QMUSE') {
+        const flag = status.sourceScenario === 'QMUSE_TEMPLATE'
+            ? '--confirm-cloud-service' : '--acknowledge-empty-cloud-data';
+        return {
+            message: `任务尚未完成，需要确认：模板使用 --confirm-cloud-service，外部项目使用 --acknowledge-empty-cloud-data。当前任务请使用 ${flag}。`,
+            requiredFlags: [flag],
+            resumeCommand: `${base} --cloud-mode QMUSE ${flag} --json`,
+            waitCommand,
+        };
+    }
+    if (mode === 'EXTERNAL') {
+        return {
+            message: `请提供外部云服务所需的公开配置：${(status.requiredConfigKeys ?? []).join(', ') || '请参考任务诊断'}。`,
+            requiredConfigKeys: status.requiredConfigKeys ?? [],
+            resumeCommand: `${base} --cloud-mode EXTERNAL --public-config @public-config.json --json`,
+            waitCommand,
+        };
+    }
+    return {
+        message: '请先选择 --cloud-mode QMUSE 或 EXTERNAL；QMUSE 模板需 --confirm-cloud-service，外部项目需 --acknowledge-empty-cloud-data。',
+        requiredFlags: ['--cloud-mode'],
+        waitCommand,
+    };
+}

package/dist/import/project.js

@@ -1,5 +1,5 @@
 import { randomUUID } from 'node:crypto';
-import { readFile, rename, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 export const QMUSE_PROJECT_PATH = '.qmuse/project.json';
 function isRecord(value) {
@@ -73,20 +73,21 @@ function parseManifest(value) {
     if (value.schemaVersion !== 1) {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 schemaVersion 不受支持`);
     }
-    if (value.projectKind !== 'QMUSE_TEMPLATE') {
-        throw new Error(`${QMUSE_PROJECT_PATH} 的 projectKind 必须是 QMUSE_TEMPLATE`);
+    if (value.projectKind !== 'QMUSE_TEMPLATE' && value.projectKind !== 'EXTERNAL_REPOSITORY') {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 projectKind 无效`);
     }
     if (value.appType !== 'GENERAL') {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 appType 必须是 GENERAL`);
     }
-    if (!Number.isSafeInteger(value.packageVersion) || Number(value.packageVersion) < 1) {
+    const isTemplate = value.projectKind === 'QMUSE_TEMPLATE';
+    if (isTemplate && (!Number.isSafeInteger(value.packageVersion) || Number(value.packageVersion) < 1)) {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 packageVersion 无效`);
     }
-    if (!isRecord(value.skillVersions)) {
+    if (isTemplate && !isRecord(value.skillVersions)) {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 skillVersions 必须是对象`);
     }
     const skillVersions = {};
-    for (const [name, version] of Object.entries(value.skillVersions)) {
+    for (const [name, version] of Object.entries(isTemplate ? value.skillVersions : {})) {
         skillVersions[requireNonEmptyString(name, 'skillVersions key')] = requireNonEmptyString(version, `skillVersions.${name}`);
     }
     const defaultSpaceId = value.defaultSpaceId === undefined
@@ -94,11 +95,13 @@ function parseManifest(value) {
         : requireNonEmptyString(value.defaultSpaceId, 'defaultSpaceId');
     return {
         schemaVersion: 1,
-        packageVersion: Number(value.packageVersion),
-        projectKind: 'QMUSE_TEMPLATE',
+        projectKind: value.projectKind,
         appType: 'GENERAL',
-        templateCommit: requireNonEmptyString(value.templateCommit, 'templateCommit'),
-        skillVersions,
+        ...(isTemplate ? {
+            packageVersion: Number(value.packageVersion),
+            templateCommit: requireNonEmptyString(value.templateCommit, 'templateCommit'),
+            skillVersions,
+        } : {}),
         ...(defaultSpaceId ? { defaultSpaceId } : {}),
         targets: parseEnvironmentMap(value.targets, 'targets', parseTarget),
         ...(value.pendingImports === undefined
@@ -150,6 +153,7 @@ export async function loadManagedProject(rootDir, cfg, explicitEnvironment) {
     return { manifestPath, manifest, environment, target };
 }
 export async function saveManagedProject(context) {
+    await mkdir(path.dirname(context.manifestPath), { recursive: true });
     const temporaryPath = `${context.manifestPath}.${process.pid}.${randomUUID()}.tmp`;
     const content = `${JSON.stringify(context.manifest, null, 2)}\n`;
     try {
@@ -162,6 +166,18 @@ export async function saveManagedProject(context) {
         throw error;
     }
 }
+export function createExternalProject(rootDir, cfg, explicitEnvironment) {
+    return {
+        manifestPath: path.join(rootDir, QMUSE_PROJECT_PATH),
+        environment: resolveProjectEnvironment(cfg, explicitEnvironment),
+        manifest: {
+            schemaVersion: 1,
+            projectKind: 'EXTERNAL_REPOSITORY',
+            appType: 'GENERAL',
+            targets: {},
+        },
+    };
+}
 export function setPendingImport(context, pending) {
     context.manifest.pendingImports = {
         ...context.manifest.pendingImports,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmuse/qmuse-cli",
-  "version": "1.0.3-dev.4",
+  "version": "1.0.3-dev.5",
   "description": "将本地 React 项目安全导入 QMuse 的命令行客户端",
   "type": "module",
   "bin": {