@qmuse/qmuse-cli 1.0.7 → 1.0.8-dev.1

package/README.md

@@ -36,6 +36,21 @@ qmuse space info
 
 ## 导入
 
+### 从模板开始
+
+```bash
+qmuse login
+qmuse create my-app
+cd my-app
+npm install
+```
+
+`create` 从 QMuse 模板下载接口获取代码并直接解压，包含 `AGENTS.md`、云服务 Skill 和 `.qmuse/project.json`。只需登录，无需先选择空间；目标目录必须不存在。命令不会自动安装依赖。开发完成后选择空间并执行 `qmuse import .`。
+
+支持 `qmuse --env pre create my-app` 下载预发模板，以及 `--json` 输出项目目录和模板 commit。后续导入使用相同的 `--env`。
+
+### 导入本地代码
+
 ```bash
 qmuse import /path/to/react-project --space-id <spaceId>
 ```

package/dist/cli.js

@@ -14,17 +14,18 @@ import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { createImportArchive } from './import/archive.js';
-import { configureAppImport, getAppOpenUrl, getImportStatusUrl, queryAppImportStatus, startAppImport, uploadImportArchive, } from './import/api.js';
+import { configureAppImport, assertTemplateProtocolSupported, getAppOpenUrl, getImportStatusUrl, queryAppImportStatus, startAppImport, uploadImportArchive, } from './import/api.js';
 import { pollAppImport } from './import/poll.js';
 import { preflightImport } from './import/preflight.js';
 import { resolveUpdateBase } from './import/update.js';
-import { clearPendingImport, completeManagedImport, createExternalProject, loadManagedProject, saveManagedProject, resolveProjectEnvironment, setPendingImport, } from './import/project.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 { configurationGuidance } from './import/guidance.js';
 import { QMUSE_CLI_VERSION } from './version.js';
 import { startUpdateNotice } from './update-notice.js';
 import { startDevelopment } from './dev/index.js';
+import { createProject } from './create.js';
 // ---------------- 参数解析 ----------------
 const BOOL_FLAGS = new Set([
     '--help', '-h', '--version', '-V', '--json', '--status',
@@ -441,6 +442,8 @@ async function cmdImport(command, flags) {
     const rootDir = path.resolve(directory);
     const managedProject = await loadManagedProject(rootDir, cfg, str(flags, '--env')) ??
         createExternalProject(rootDir, cfg, str(flags, '--env'));
+    if (managedProject.manifest.schemaVersion === 2)
+        await assertTemplateProtocolSupported(cfg);
     const pendingImport = managedProject.manifest.pendingImports?.[managedProject.environment];
     if (pendingImport) {
         throw new Error(`当前目录有尚未完成的导入任务，请先执行 qmuse import status ${pendingImport.jobId} --wait --env ${managedProject.environment}，避免重复创建应用`);
@@ -522,6 +525,7 @@ async function cmdImport(command, flags) {
     if (flags['--json'] !== true)
         log.success('源代码上传完成');
     const started = await startAppImport({
+        ...importArchitectureProtocol(managedProject.manifest),
         sourceToken,
         spaceId,
         title: str(flags, '--title')?.trim() || undefined,
@@ -827,6 +831,18 @@ async function cmdLogout(flags) {
     }
 }
 // ---------------- 帮助 & 入口 ----------------
+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
 
 用法:
@@ -845,6 +861,8 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   logout                                            清除保存的登录态和空间选择
   config [get|path]                                 查看配置
 
+  create <directory>                               下载 QMuse 模板并解压到新项目目录
+
   cloud init -d "<应用功能描述>"                    校验当前空间的 QMuse 云服务权益
   cloud set-secret KEY1,KEY2 --stdin                从标准输入 JSON 保存密钥，不输出密钥值
       [--app-id <id>] [--cloud-env dev|prod]
@@ -868,6 +886,7 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   qmuse login
   qmuse space list
   qmuse space use S640459450135
+  qmuse create my-app
   qmuse import /path/to/react-vite-app
 `;
 async function main() {
@@ -905,6 +924,9 @@ async function main() {
             case 'config':
                 await cmdConfig(command, flags);
                 return;
+            case 'create':
+                await cmdCreate(command, flags);
+                return;
             case 'cloud':
                 await cmdCloud(command, flags);
                 return;

package/dist/create.js

@@ -0,0 +1,151 @@
+import { createWriteStream } from 'node:fs';
+import { lstat, mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { fromBufferPromise } from 'yauzl';
+import { authHeaders, buildUrl, hasAuth } from './client.js';
+import { loadManagedProject } from './import/project.js';
+const MAX_ARCHIVE_BYTES = 100 * 1024 * 1024;
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+const MAX_FILES = 20_000;
+async function readResponse(response, limit) {
+    if (!response.body)
+        throw new Error('模板下载响应为空');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        if (Number(response.headers.get('content-length')) > limit) {
+            throw new Error('模板下载响应超过大小限制');
+        }
+        while (true) {
+            const { value, done } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > limit)
+                throw new Error('模板下载响应超过大小限制');
+            chunks.push(Buffer.from(value));
+        }
+        return Buffer.concat(chunks, size);
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+}
+async function downloadTemplate(projectName, cfg) {
+    const params = new URLSearchParams({ appType: 'GENERAL', projectName });
+    // 模板下载无需空间；不继承当前空间，避免触发无关的空间权限校验。
+    const headers = authHeaders({ ...cfg, spaceId: '' });
+    headers.Accept = 'application/zip';
+    delete headers['Content-Type'];
+    const response = await fetch(buildUrl(cfg, `/api/project-template/download?${params}`), {
+        headers,
+        redirect: 'error',
+        signal: AbortSignal.timeout(120_000),
+    });
+    if (!response.ok || response.headers.get('content-type')?.split(';')[0].trim().toLowerCase() !== 'application/zip') {
+        const body = await readResponse(response, 64 * 1024);
+        let message = '';
+        try {
+            const error = JSON.parse(body.toString('utf8'));
+            if (typeof error.errorMessage === 'string')
+                message = error.errorMessage;
+            else if (typeof error.message === 'string')
+                message = error.message;
+        }
+        catch { /* HTML 登录页或代理错误页不作为模板落盘。 */ }
+        if (response.status === 401)
+            throw new Error('登录已失效，请先运行 `qmuse login`');
+        throw new Error(`模板下载失败（HTTP ${response.status}）${message ? `：${message}` : '：服务端未返回 ZIP 模板'}`);
+    }
+    return readResponse(response, MAX_ARCHIVE_BYTES);
+}
+async function extractTemplate(archive, directory, projectName) {
+    const zip = await fromBufferPromise(archive, {
+        lazyEntries: true, strictFileNames: true, validateEntrySizes: true,
+    });
+    const seen = new Set();
+    let totalBytes = 0;
+    let count = 0;
+    try {
+        if (zip.entryCount > MAX_FILES)
+            throw new Error('模板文件数超过限制');
+        for await (const entry of zip.eachEntry()) {
+            if (++count > MAX_FILES)
+                throw new Error('模板文件数超过限制');
+            const name = entry.fileName;
+            const isDirectory = name.endsWith('/');
+            const parts = name.replace(/\/$/u, '').split('/');
+            if (parts[0] !== projectName || parts.some(part => !part || part === '.' || part === '..' || /[\\:\x00-\x1f]/u.test(part)))
+                throw new Error(`模板包含不安全路径：${name}`);
+            const fileType = (entry.externalFileAttributes >>> 16) & 0o170000;
+            if (fileType && fileType !== (isDirectory ? 0o040000 : 0o100000)) {
+                throw new Error(`模板包含符号链接或特殊文件：${name}`);
+            }
+            const relative = parts.slice(1).join('/');
+            if (!relative) {
+                if (!isDirectory)
+                    throw new Error(`模板路径不是项目文件：${name}`);
+                continue;
+            }
+            if (seen.has(relative))
+                throw new Error(`模板包含重复路径：${name}`);
+            seen.add(relative);
+            if (entry.uncompressedSize > MAX_FILE_BYTES)
+                throw new Error(`模板文件过大：${name}`);
+            totalBytes += entry.uncompressedSize;
+            if (totalBytes > MAX_ARCHIVE_BYTES)
+                throw new Error('模板解压大小超过限制');
+            const destination = path.join(directory, relative);
+            if (isDirectory) {
+                await mkdir(destination, { recursive: true });
+            }
+            else {
+                await mkdir(path.dirname(destination), { recursive: true });
+                const stream = await zip.openReadStreamPromise(entry);
+                await pipeline(stream, createWriteStream(destination, { flags: 'wx', mode: 0o644 }));
+            }
+        }
+    }
+    finally {
+        zip.close();
+    }
+}
+export async function createProject(directory, cfg) {
+    const rootDir = path.resolve(directory);
+    const projectName = path.basename(rootDir);
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(projectName)) {
+        throw new Error('项目目录名称需以字母或数字开头，仅支持字母、数字、点、下划线和短横线，最多 64 个字符');
+    }
+    try {
+        await lstat(rootDir);
+        throw new Error(`目标目录已存在，请使用新目录：${rootDir}`);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (!hasAuth(cfg))
+        throw new Error('当前环境未登录。请先运行 `qmuse login`。');
+    const archive = await downloadTemplate(projectName, cfg);
+    // mkdir 不覆盖已有目录，下载期间出现的同名目录也保留原样。
+    await mkdir(rootDir);
+    try {
+        await extractTemplate(archive, rootDir, projectName);
+        const project = await loadManagedProject(rootDir, cfg);
+        if (!project || project.manifest.projectKind !== 'QMUSE_TEMPLATE') {
+            throw new Error('模板缺少有效的 .qmuse/project.json');
+        }
+        for (const name of ['package.json', 'AGENTS.md', '.agents/skills/qmuse-cloud/SKILL.md']) {
+            if (!(await lstat(path.join(rootDir, name))).isFile())
+                throw new Error(`模板缺少文件：${name}`);
+        }
+        return { success: true, directory: rootDir, templateCommit: project.manifest.templateCommit };
+    }
+    catch (error) {
+        await rm(rootDir, { recursive: true, force: true });
+        throw error;
+    }
+}

package/dist/import/api.js

@@ -1,6 +1,12 @@
 import { openAsBlob } from 'node:fs';
 import { apiCall, authHeaders, buildUrl, requestSourceHeaders, } from '../client.js';
 import { assertImportArchiveSize } from './limits.js';
+export async function assertTemplateProtocolSupported(cfg) {
+    const result = await apiCall('GET', '/api/app-import/protocol', undefined, cfg);
+    if (!result.ok || !result.data?.templateProtocolVersions?.includes(2)) {
+        throw new Error('当前平台尚不支持新模板架构协议，请等待服务端升级；未提交导入，不会降级为旧架构');
+    }
+}
 export async function uploadImportArchive(input, cfg) {
     const archive = await openAsBlob(input.filePath, { type: 'application/zip' });
     assertImportArchiveSize(archive.size);

package/dist/import/project.js

@@ -70,8 +70,8 @@ function parseEnvironmentMap(value, field, parse) {
 function parseManifest(value) {
     if (!isRecord(value))
         throw new Error(`${QMUSE_PROJECT_PATH} 必须是 JSON 对象`);
-    if (value.schemaVersion !== 1) {
-        throw new Error(`${QMUSE_PROJECT_PATH} 的 schemaVersion 不受支持`);
+    if (value.schemaVersion !== 1 && value.schemaVersion !== 2) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 schemaVersion 不受支持，请升级 QMuse CLI`);
     }
     if (value.projectKind !== 'QMUSE_TEMPLATE' && value.projectKind !== 'EXTERNAL_REPOSITORY') {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 projectKind 无效`);
@@ -80,6 +80,14 @@ function parseManifest(value) {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 appType 必须是 GENERAL`);
     }
     const isTemplate = value.projectKind === 'QMUSE_TEMPLATE';
+    if (value.schemaVersion === 2) {
+        if (!isTemplate || !['LEGACY_DIRECT_V1', 'HONO_BACKEND_V1'].includes(String(value.cloudArchitecture))) {
+            throw new Error(`${QMUSE_PROJECT_PATH} 的新模板协议必须声明有效的 cloudArchitecture`);
+        }
+    }
+    else if (value.cloudArchitecture !== undefined) {
+        throw new Error(`${QMUSE_PROJECT_PATH} 的 cloudArchitecture 需要 schemaVersion 2，请使用新版模板`);
+    }
     if (isTemplate && (!Number.isSafeInteger(value.packageVersion) || Number(value.packageVersion) < 1)) {
         throw new Error(`${QMUSE_PROJECT_PATH} 的 packageVersion 无效`);
     }
@@ -94,7 +102,8 @@ function parseManifest(value) {
         ? undefined
         : requireNonEmptyString(value.defaultSpaceId, 'defaultSpaceId');
     return {
-        schemaVersion: 1,
+        schemaVersion: value.schemaVersion,
+        ...(value.schemaVersion === 2 ? { cloudArchitecture: value.cloudArchitecture } : {}),
         projectKind: value.projectKind,
         appType: 'GENERAL',
         ...(isTemplate ? {
@@ -109,6 +118,14 @@ function parseManifest(value) {
             : { pendingImports: parseEnvironmentMap(value.pendingImports, 'pendingImports', parsePendingImport) }),
     };
 }
+/** Keep v1 requests byte-compatible; never infer architecture from installed dependencies. */
+export function importArchitectureProtocol(manifest) {
+    if (manifest.schemaVersion === 1)
+        return {};
+    if (!manifest.cloudArchitecture)
+        throw new Error('新模板协议缺少 cloudArchitecture');
+    return { templateProtocolVersion: 2, cloudArchitecture: manifest.cloudArchitecture };
+}
 export function resolveProjectEnvironment(cfg, explicitEnvironment) {
     if (explicitEnvironment)
         return explicitEnvironment;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qmuse/qmuse-cli",
-  "version": "1.0.7",
+  "version": "1.0.8-dev.1",
   "description": "将本地 React 项目安全导入 QMuse 的命令行客户端",
   "type": "module",
   "bin": {
@@ -24,6 +24,7 @@
     "open": "^11.0.4",
     "semver": "7.7.4",
     "typescript": "^5.9.3",
+    "yauzl": "^3.4.0",
     "yazl": "^3.3.1"
   },
   "files": [
@@ -37,6 +38,7 @@
     "@playwright/test": "1.63.0",
     "@types/node": "^22.10.0",
     "@types/semver": "7.7.1",
+    "@types/yauzl": "^3.4.0",
     "@types/yazl": "^3.3.1",
     "tsx": "^4.19.2",
     "vite": "7.3.6"