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

package/README.md

@@ -49,6 +49,19 @@ npm install
 
 支持 `qmuse --env pre create my-app` 下载预发模板，以及 `--json` 输出项目目录和模板 commit。后续导入使用相同的 `--env`。
 
+### 大资源上传与发布体积检查
+
+```bash
+qmuse assets upload public/photo.png public/audio/clip.wav --json
+# 文件路径相对于项目；可加 --project /path/to/project、--space-id <id>、--env pre
+```
+
+返回本地路径、SHA-256、大小、文件 ID、稳定 CDN 地址及修复步骤。映射保存在 `.qmuse/assets/`，按 API 环境和空间隔离；失败重试复用已上传文件，重新完成登记和内容检查。旧服务端会在上传前提示升级。
+
+让本地模型根据映射替换全部引用，尤其是动态路径、JSON 音频清单和 Three.js 加载器；验证构建及页面的图片、纹理、音频播放后，再删除本地副本并重新 `qmuse import .`。上传命令不会自动改代码或删除资源。支持常用图片、音视频，单文件最多 100 MiB、单次 200 个；SVG、字体及模型关联文件暂不支持。
+
+导入时会生成 `.qmuse/asset-preflight.json`。源码资源总大小仅用于预警；服务端在 READY 前用 APC dry-run 检查实际压缩发布包。初始预算为 10,000,000 字节减去 65,536 字节预留量，超限返回可供模型修复的 `publishBudget` 诊断。此预算不等于已经证实的网关限制，也不代表未来代码或运行配置变更后的发布保证。
+
 ### 导入本地代码
 
 ```bash

package/dist/cli.js

@@ -16,6 +16,7 @@ import { homedir } from 'node:os';
 import { createImportArchive } from './import/archive.js';
 import { configureAppImport, assertTemplateProtocolSupported, getAppOpenUrl, getImportStatusUrl, queryAppImportStatus, startAppImport, uploadImportArchive, } from './import/api.js';
 import { pollAppImport } from './import/poll.js';
+import { uploadLocalAssets, writeAssetPreflightReport } from './import/assets.js';
 import { preflightImport } from './import/preflight.js';
 import { resolveUpdateBase } from './import/update.js';
 import { clearPendingImport, completeManagedImport, createExternalProject, importArchitectureProtocol, loadManagedProject, saveManagedProject, resolveProjectEnvironment, setPendingImport, } from './import/project.js';
@@ -358,6 +359,19 @@ async function finishImport(status, sourceHash, cfg, flags, managedProject, root
             log.warn('无法自动打开浏览器');
     }
 }
+async function cmdAssets(command, flags) {
+    if (command[1] !== 'upload' || command.length < 3)
+        fail('用法: qmuse assets upload <relative-file> [more-files...] [--project <dir>] [--space-id <id>] [--json]');
+    const cfg = resolveCfg(flags);
+    requireAuth(cfg);
+    const rootDir = path.resolve(str(flags, '--project') || '.');
+    const project = await loadManagedProject(rootDir, cfg, str(flags, '--env'));
+    const spaceId = str(flags, '--space-id') || project?.target?.spaceId || project?.manifest.defaultSpaceId || cfg.spaceId;
+    if (!spaceId)
+        fail('请指定资源所属空间 --space-id');
+    const result = await uploadLocalAssets({ rootDir, files: command.slice(2), cfg, spaceId });
+    output({ success: true, ...result }, flags);
+}
 async function cmdImport(command, flags) {
     const cfg = resolveCfg(flags);
     requireAuth(cfg);
@@ -468,6 +482,10 @@ async function cmdImport(command, flags) {
     if (flags['--json'] !== true)
         log.info('正在只读预检本地仓库...');
     const preflight = await preflightImport(directory);
+    const assetReportPath = await writeAssetPreflightReport(preflight);
+    if (preflight.assets.reduce((sum, asset) => sum + asset.sizeBytes, 0) >= 10_000_000 && flags['--json'] !== true) {
+        log.warn(`本地静态资源较大，可能超过发布预算。清单：${assetReportPath}；可先执行 qmuse assets upload <资源路径> --json。最终以服务端 APC 压缩包检查为准。`);
+    }
     const updateBase = managedProject?.target
         ? await resolveUpdateBase({
             target: managedProject.target,
@@ -870,6 +888,7 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   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]
@@ -933,6 +952,9 @@ async function main() {
             case 'dev':
                 await cmdDev(command, flags);
                 return;
+            case 'assets':
+                await cmdAssets(command, flags);
+                break;
             case 'import':
                 await cmdImport(command, flags);
                 return;

package/dist/import/assets.js

@@ -0,0 +1,165 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { lstat, mkdir, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { apiCall, hasAuth } from '../client.js';
+import { resolveProjectEnvironment } from './project.js';
+const MEDIA = {
+    '.png': { mimeType: 'image/png', materialType: 'image' },
+    '.jpg': { mimeType: 'image/jpeg', materialType: 'image' },
+    '.jpeg': { mimeType: 'image/jpeg', materialType: 'image' },
+    '.gif': { mimeType: 'image/gif', materialType: 'image' },
+    '.webp': { mimeType: 'image/webp', materialType: 'image' },
+    '.avif': { mimeType: 'image/avif', materialType: 'image' },
+    '.mp3': { mimeType: 'audio/mpeg', materialType: 'audio' },
+    '.wav': { mimeType: 'audio/wav', materialType: 'audio' },
+    '.ogg': { mimeType: 'audio/ogg', materialType: 'audio' },
+    '.mp4': { mimeType: 'video/mp4', materialType: 'video' },
+    '.webm': { mimeType: 'video/webm', materialType: 'video' },
+};
+const MAX_ASSET_BYTES = 100 * 1024 * 1024;
+export const ASSET_REPAIR_STEPS = [
+    '按 sourcePath、sha256 和 stableUrl 替换全部资源引用，包括动态拼接、JSON 清单、CSS、HTML 和 Three.js 加载器。',
+    '保留 URL 的运行时语义；fetch、纹理、音频须验证 CORS、解码和播放，模型资源须检查关联文件及相对路径。',
+    '运行构建和相关页面检查，确认没有旧引用后，再删除已迁移资源的本地副本。不要仅凭上传成功删除文件。',
+    '重新执行 qmuse import .；服务端会重新构建并检查 APC 压缩发布包，单纯上传 CDN 不会减少发布体积。',
+];
+async function writeJson(file, value) {
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+/** Source bytes are an early warning only; they are not APC compressed package bytes. */
+export async function writeAssetPreflightReport(preflight) {
+    const directory = path.join(preflight.rootDir, '.qmuse');
+    await mkdir(directory, { recursive: true });
+    const file = path.join(directory, 'asset-preflight.json');
+    await writeJson(file, {
+        schemaVersion: 1, metric: 'SOURCE_ASSET_BYTES',
+        totalAssetBytes: preflight.assets.reduce((sum, asset) => sum + asset.sizeBytes, 0),
+        finalPublishSizeCheck: 'SERVER_APC_DRY_RUN_BEFORE_READY',
+        assets: preflight.assets.map(asset => ({ ...asset,
+            sha256: preflight.files.find(file => file.relativePath === asset.sourcePath)?.sha256,
+            uploadSupported: Boolean(MEDIA[path.extname(asset.sourcePath).toLowerCase()]),
+        })).sort((a, b) => b.sizeBytes - a.sizeBytes),
+        uploadCommand: 'qmuse assets upload <relative-file> [more-files...] --json',
+        repairSteps: ASSET_REPAIR_STEPS,
+    });
+    return file;
+}
+function requireStableUrl(value) {
+    const url = new URL(value);
+    if (url.protocol !== 'https:' || url.username || url.password ||
+        [...url.searchParams.keys()].some(key => /^(?:expires|signature|x-oss-signature|x-oss-expires)$/iu.test(key))) {
+        throw new Error('CDN 未返回稳定 HTTPS 地址');
+    }
+    return url.toString();
+}
+export async function uploadLocalAssets(input) {
+    if (!hasAuth(input.cfg))
+        throw new Error('请先登录 QMuse');
+    if (!input.spaceId)
+        throw new Error('请指定资源所属空间 --space-id');
+    if (!input.files.length || input.files.length > 200)
+        throw new Error('每次上传需指定 1 到 200 个资源文件');
+    const root = await realpath(input.rootDir);
+    const cfg = { ...input.cfg, spaceId: input.spaceId };
+    const scope = createHash('sha256').update(`${cfg.baseUrl}\n${input.spaceId}`).digest('hex').slice(0, 24);
+    const directory = path.join(root, '.qmuse', 'assets');
+    await mkdir(directory, { recursive: true });
+    const manifestPath = path.join(directory, `${scope}.json`);
+    const lock = `${manifestPath}.lock`;
+    try {
+        await mkdir(lock);
+    }
+    catch {
+        throw new Error(`资源上传正在运行；若进程已退出，请检查并删除锁目录 ${lock}`);
+    }
+    try {
+        const protocol = await apiCall('GET', '/api/app-import/protocol', undefined, { cfg, redirect: 'error', signal: AbortSignal.timeout(30_000) });
+        if (!protocol.ok || protocol.data?.localAssetUpload !== true)
+            throw new Error('当前服务端尚不支持 CLI 资源上传，请先升级服务端后重试');
+        let cached = [];
+        try {
+            const manifest = JSON.parse(await readFile(manifestPath, 'utf8'));
+            if (manifest.apiBaseUrl === cfg.baseUrl && manifest.spaceId === input.spaceId && Array.isArray(manifest.mappings))
+                cached = manifest.mappings;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const save = () => writeJson(manifestPath, { schemaVersion: 1, apiBaseUrl: cfg.baseUrl, spaceId: input.spaceId, mappings: cached });
+        const mappings = [];
+        for (const file of [...new Set(input.files)]) {
+            const absolute = path.resolve(root, file);
+            const sourcePath = path.relative(root, absolute).split(path.sep).join('/');
+            if (!sourcePath || sourcePath.startsWith('../') || path.isAbsolute(sourcePath))
+                throw new Error(`资源不能位于项目外：${file}`);
+            // Reject symbolic links, including links in parent directories.
+            let current = root;
+            for (const segment of sourcePath.split('/')) {
+                current = path.join(current, segment);
+                if ((await lstat(current)).isSymbolicLink())
+                    throw new Error(`不支持符号链接：${sourcePath}`);
+            }
+            const extension = path.extname(sourcePath).toLowerCase();
+            const media = MEDIA[extension];
+            if (!media)
+                throw new Error(`暂不支持上传该类型：${sourcePath}；SVG、字体和含关联文件的模型资源需保留并单独处理`);
+            const stat = await lstat(absolute);
+            if (!stat.isFile() || stat.size <= 0 || stat.size > MAX_ASSET_BYTES)
+                throw new Error(`资源必须是 1 字节至 100 MiB 的普通文件：${sourcePath}`);
+            const bytes = await readFile(absolute);
+            if (bytes.length <= 0 || bytes.length > MAX_ASSET_BYTES)
+                throw new Error(`读取期间资源大小改变：${sourcePath}`);
+            const sha256 = createHash('sha256').update(bytes).digest('hex');
+            let mapping = cached.find(item => item.sourcePath === sourcePath && item.sha256 === sha256 && item.sizeBytes === bytes.length && item.mimeType === media.mimeType && typeof item.fileId === 'string');
+            if (!mapping) {
+                const grant = await apiCall('GET', `/api/file/upload-url?spaceId=${encodeURIComponent(input.spaceId)}`, undefined, { cfg, redirect: 'error', signal: AbortSignal.timeout(30_000) });
+                if (!grant.ok || !grant.data?.uploadUrl)
+                    throw new Error(`获取上传地址失败：${grant.errorMessage ?? grant.errorCode ?? grant.status}`);
+                const url = new URL(grant.data.uploadUrl);
+                if (url.protocol !== 'https:' || url.username || url.password)
+                    throw new Error('上传地址必须是 HTTPS');
+                url.searchParams.set('public', 'true');
+                const form = new FormData();
+                form.append('file', new Blob([bytes], { type: media.mimeType }), path.basename(sourcePath));
+                // No session, cookie or QMuse credentials are forwarded to the CDN.
+                const response = await fetch(url, { method: 'POST', redirect: 'error', body: form,
+                    headers: { 'x-mass-ext-name': extension, 'x-afts-text-encoding': 'utf-8' }, signal: AbortSignal.timeout(300_000) });
+                if (!response.ok)
+                    throw new Error(`CDN 上传失败：HTTP ${response.status}`);
+                const result = await response.json();
+                const uploaded = Array.isArray(result.data) ? result.data[0] : result.data;
+                if (result.code !== 0 || typeof uploaded?.id !== 'string' || !uploaded.id.trim())
+                    throw new Error('CDN 上传未返回有效文件 ID');
+                mapping = { sourcePath, sha256, sizeBytes: bytes.length, mimeType: media.mimeType, fileId: uploaded.id };
+                cached = cached.filter(item => item.sourcePath !== sourcePath);
+                cached.push(mapping);
+                await save(); // Keep completed uploads even if registration/review or a later file fails.
+            }
+            delete mapping.stableUrl;
+            await save();
+            const registered = await apiCall('POST', '/api/app-import/assets/register', {
+                spaceId: input.spaceId, fileId: mapping.fileId, name: path.basename(sourcePath), materialType: media.materialType,
+            }, { cfg, redirect: 'error', signal: AbortSignal.timeout(60_000) });
+            if (!registered.ok || !registered.data)
+                throw new Error(`资源登记或内容检查未通过：${registered.errorMessage ?? registered.errorCode ?? registered.status}；已上传文件保存在 ${manifestPath}，重试将复用`);
+            if (registered.data.fileId !== mapping.fileId || registered.data.sizeBytes !== mapping.sizeBytes)
+                throw new Error(`CDN 资源大小或身份不一致：${sourcePath}`);
+            mapping.stableUrl = requireStableUrl(registered.data.stableUrl);
+            await save();
+            mappings.push({ ...mapping });
+        }
+        const environment = resolveProjectEnvironment(cfg);
+        return { mappings, manifestPath, repairSteps: ASSET_REPAIR_STEPS.map(step => step.replace('qmuse import .', `qmuse import . --env ${environment}`)) };
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true });
+    }
+}

package/dist/import/diagnostic.js

@@ -1,3 +1,4 @@
+import { ASSET_REPAIR_STEPS } from './assets.js';
 import { randomUUID } from 'node:crypto';
 import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -26,6 +27,13 @@ export async function writeImportFailureDiagnostic(input) {
         message: input.status.message,
         diagnostic: input.status.diagnostic,
         failureDiagnostic: input.status.failureDiagnostic,
+        ...(input.status.failureDiagnostic?.code?.startsWith('APP_PUBLISH_') ? {
+            assetRepair: {
+                preflightReport: '.qmuse/asset-preflight.json',
+                uploadCommand: `qmuse assets upload <relative-file> [more-files...] --env ${input.project?.environment ?? input.environment ?? 'prod'} --json`,
+                steps: ASSET_REPAIR_STEPS.map(step => step.replace('qmuse import .', `qmuse import . --env ${input.project?.environment ?? input.environment ?? 'prod'}`)),
+            },
+        } : {}),
         ...importRetryGuidance(input.status, input.project),
         environment: input.project?.environment ?? input.environment,
         generatedAt: new Date().toISOString(),

package/package.json

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