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

package/README.md

@@ -49,6 +49,21 @@ 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` 诊断。此预算不等于已经证实的网关限制，也不代表未来代码或运行配置变更后的发布保证。
+
+超限后的 `.qmuse/last-import-error.json` 按媒体、数据、代码及关联资源分类给出建议：JSON 数据需精简或设计外置加载，JS/CSS 需优化依赖及构建产物，SVG、字体和模型需单独处理。服务端大文件清单使用构建产物路径；CLI 重新检查本地项目后列出的媒体候选与之没有自动映射，须确认源文件后再上传。缺少清单或可确认的本地媒体时不生成上传命令；修复后按诊断中的应用绑定与重试建议操作，避免重复创建应用。
+
 ### 导入本地代码
 
 ```bash
@@ -71,6 +86,24 @@ qmuse import /path/to/react-project --space-id <spaceId>
 
 平台已有新版本时，终端会询问是否用本地全部源码覆盖，不会自动合并平台修改。确认覆盖可执行 `qmuse import . --force`；脚本或 `--json` 模式须显式指定该参数。覆盖会在原应用创建新版本，仍需通过正常导入校验。
 
+### 拉取平台对话更新
+
+```bash
+qmuse pull .                 # 拉取当前绑定应用最新已保存的源码
+# 本地修改、运行和验证
+qmuse import .               # 更新同一应用
+```
+
+`pull` 支持 `--env prod|pre|local` 和 `--json`。需要 MusePub 部署 `/api/app-import/pull`；服务端校验应用编辑权限、空间和历史导入版本。已绑定的导入应用免费同步，不扣下载积分，不改变普通源码下载的套餐规则。旧的 `.qmuse/project.json` 可直接使用；成功拉取后会保留导入版本凭据，支持后续多次拉取。
+
+本地源码与上次成功导入或拉取的基线不一致时，命令直接停止，包括新增、修改和删除文件。请先备份并处理本地改动；仅执行 Git 提交不会清除 QMuse 检测到的差异。首版不自动合并，也不支持强制拉取覆盖。
+
+拉取的是平台已保存版本的完整工程结构，可能与最初上传的项目结构不同。成功后会删除平台已移除的源码，并更新本地版本、源码哈希和模板标识，使后续导入沿用平台工程处理方式。平台在拉取期间再次更新时，下次导入仍会检测版本冲突。尚未保存的对话工作区改动不会被拉取。
+
+`.git`、`.qmuse`、`.agents`、`AGENTS.md`、`.env*`、依赖目录、构建产物和本地忽略文件按本地保留规则处理，不自动执行脚本或安装依赖。远端文件与本地保留文件冲突时停止。源码上限为 20000 个文件、100 MiB。
+
+每次更新前，原源码和绑定保存在终端返回的 `.qmuse/pull-backups/pull-*/`，其中 `original/` 是原源码，`project.json` 是原绑定，`transaction.json` 是文件清单。普通失败自动回滚；进程异常退出时保留 `.qmuse/pull-recovery.json` 和锁，后续导入/拉取会停止。恢复时先确认原进程已退出，备份当前目录，再按清单清理本次新增文件、恢复 `original/` 和原绑定，核对后移除恢复标记和 `.qmuse/sync.lock`。备份包含完整源码，请确认无需恢复后自行清理。
+
 ### 外部云服务
 
 ```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';
@@ -26,6 +27,8 @@ import { QMUSE_CLI_VERSION } from './version.js';
 import { startUpdateNotice } from './update-notice.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',
@@ -358,6 +361,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 +484,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,
@@ -862,6 +882,7 @@ const HELP = `QMuse CLI —— 将本地 React 项目导入 QMuse
   config [get|path]                                 查看配置
 
   create <directory>                               下载 QMuse 模板并解压到新项目目录
+  pull [directory]                                 免费同步已导入应用的最新已保存源码（本地有改动时停止）
 
   cloud init -d "<应用功能描述>"                    校验当前空间的 QMuse 云服务权益
   cloud set-secret KEY1,KEY2 --stdin                从标准输入 JSON 保存密钥，不输出密钥值
@@ -870,6 +891,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]
@@ -927,14 +949,37 @@ async function main() {
             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 pullProject(command[1] || '.', resolveCfg(flags), str(flags, '--env'));
+                if (flags['--json'] === true)
+                    output(result, flags);
+                else {
+                    log.success(result.noChanges ? '本地已是平台最新版本' : `已拉取平台版本 ${result.versionId}`);
+                    if (result.backupDirectory)
+                        log.info(`原源码备份：${result.backupDirectory}`);
+                    if (!result.noChanges)
+                        log.info('修改完成后执行 qmuse import，更新同一应用。');
+                }
+                return;
+            }
             case 'cloud':
                 await cmdCloud(command, flags);
                 return;
             case 'dev':
                 await cmdDev(command, flags);
                 return;
+            case 'assets':
+                await cmdAssets(command, flags);
+                break;
             case 'import':
-                await cmdImport(command, flags);
+                if (command[1] && !['status', 'configure'].includes(command[1])) {
+                    await withProjectLock(command[1], () => cmdImport(command, flags));
+                }
+                else
+                    await cmdImport(command, flags);
                 return;
             case 'space':
                 await cmdSpace(command, flags);

package/dist/import/assets.js

@@ -0,0 +1,173 @@
+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 function supportsAssetUpload(sourcePath, sizeBytes) {
+    return Boolean(MEDIA[path.extname(sourcePath).toLowerCase()]) &&
+        Number.isSafeInteger(sizeBytes) && sizeBytes > 0 && sizeBytes <= MAX_ASSET_BYTES;
+}
+export const ASSET_REPAIR_STEPS = [
+    '按 sourcePath、sha256 和 stableUrl 替换全部资源引用，包括动态拼接、JSON 清单、CSS、HTML 和 Three.js 加载器。',
+    '保留 URL 的运行时语义；fetch、纹理、音频须验证 CORS、解码和播放，模型资源须检查关联文件及相对路径。',
+    '检查 assetRoot + clip.url 等拼接：完整 CDN 地址不能再拼接本地目录；JSON 清单和读取清单的代码需要一起验证。',
+    '运行构建和相关页面检查，确认没有旧引用后，再删除已迁移资源的本地副本。不要仅凭上传成功删除文件。',
+    '确认当前环境的应用绑定后，重新执行 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');
+    const hasUploadCandidates = preflight.assets.some(asset => supportsAssetUpload(asset.sourcePath, asset.sizeBytes));
+    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: supportsAssetUpload(asset.sourcePath, asset.sizeBytes),
+        })).sort((a, b) => b.sizeBytes - a.sizeBytes),
+        uploadCommand: hasUploadCandidates ? 'qmuse assets upload <relative-file> [more-files...] --json' : null,
+        repairSteps: hasUploadCandidates ? ASSET_REPAIR_STEPS : [
+            '本地预检没有发现受支持的媒体上传候选。结合服务端发布包诊断检查数据、代码及其他构建产物；不要把 JSON、JS/CSS、SVG、字体或模型文件直接传给 assets upload。',
+        ],
+    });
+    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 { buildPublishRepairGuidance } from './publish-repair.js';
 import { randomUUID } from 'node:crypto';
 import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
@@ -26,6 +27,14 @@ export async function writeImportFailureDiagnostic(input) {
         message: input.status.message,
         diagnostic: input.status.diagnostic,
         failureDiagnostic: input.status.failureDiagnostic,
+        ...(input.status.failureDiagnostic &&
+            ['APP_PUBLISH_PACKAGE_TOO_LARGE', 'APP_PUBLISH_FILE_TOO_LARGE'].includes(input.status.failureDiagnostic.code ?? '') ? {
+            assetRepair: await buildPublishRepairGuidance({
+                rootDir: input.rootDir,
+                diagnostic: input.status.failureDiagnostic,
+                environment: input.project?.environment ?? input.environment ?? 'prod',
+            }),
+        } : {}),
         ...importRetryGuidance(input.status, input.project),
         environment: input.project?.environment ?? input.environment,
         generatedAt: new Date().toISOString(),

package/dist/import/project.js

@@ -35,6 +35,9 @@ function parseTarget(value, field) {
         appId: requireNonEmptyString(value.appId, `${field}.appId`),
         spaceId: requireNonEmptyString(value.spaceId, `${field}.spaceId`),
         lastVersionId: requireNonEmptyString(value.lastVersionId, `${field}.lastVersionId`),
+        ...(value.importVersionId === undefined ? {} : {
+            importVersionId: requireNonEmptyString(value.importVersionId, `${field}.importVersionId`),
+        }),
         lastSourceHash: requireNonEmptyString(value.lastSourceHash, `${field}.lastSourceHash`),
         updatedAt: requireNonEmptyString(value.updatedAt, `${field}.updatedAt`),
     };

package/dist/import/publish-repair.js

@@ -0,0 +1,74 @@
+import path from 'node:path';
+import { ASSET_REPAIR_STEPS, supportsAssetUpload } from './assets.js';
+import { preflightImport } from './preflight.js';
+const ADVICE = {
+    MEDIA: '支持的图片、音频和视频可使用 assets upload 外置；先确认构建产物对应的本地源文件及上传大小限制。',
+    DATA: 'JSON、CSV 等数据不能使用 assets upload。精简运行时数据、移除确认不参与运行的产物，或设计外置数据加载并验证接口、权限和 CORS。',
+    BUNDLE: '分析大依赖和重复代码，裁剪无用内容，移除非必要 source map 等产物；仅拆分 chunk 或懒加载不一定减少发布总包大小。JS/CSS 等代码不能使用 assets upload。',
+    DEPENDENT_ASSET: 'SVG、字体、模型及关联文件暂不支持 assets upload；优化资源并检查模型纹理、字体声明和相对路径依赖，不要直接删除文件。',
+    OTHER: '先确认文件类型、构建来源及运行时引用，再选择压缩、裁剪或单独的外置方案；不要默认使用 assets upload。',
+};
+function classify(filePath) {
+    const extension = path.extname(filePath).toLowerCase();
+    if (supportsAssetUpload(filePath, 1))
+        return 'MEDIA';
+    if (['.json', '.jsonl', '.csv', '.tsv', '.xml', '.yaml', '.yml'].includes(extension))
+        return 'DATA';
+    if (['.js', '.mjs', '.cjs', '.jsx', '.ts', '.tsx', '.css', '.html', '.map', '.wasm'].includes(extension))
+        return 'BUNDLE';
+    if (['.svg', '.woff', '.woff2', '.ttf', '.otf', '.eot', '.gltf', '.glb', '.obj', '.mtl', '.fbx', '.bin'].includes(extension))
+        return 'DEPENDENT_ASSET';
+    return 'OTHER';
+}
+/** Artifact paths describe build output, never an inferred local upload path. */
+export async function buildPublishRepairGuidance(input) {
+    const artifactFiles = input.diagnostic.publishBudget?.largestFiles ?? [];
+    const kinds = artifactFiles.length
+        ? [...new Set(artifactFiles.map(file => classify(file.path)))]
+        : Object.keys(ADVICE);
+    const groups = kinds.map(kind => ({
+        kind,
+        artifactFiles: artifactFiles.filter(file => classify(file.path) === kind),
+        advice: ADVICE[kind],
+    }));
+    let localInspection = 'NOT_NEEDED';
+    let localMediaCandidates = [];
+    if (kinds.includes('MEDIA')) {
+        try {
+            // Reinspect the current tree; a previous report may describe deleted or changed files.
+            const preflight = await preflightImport(input.rootDir);
+            localMediaCandidates = preflight.files
+                .filter(file => supportsAssetUpload(file.relativePath, file.sizeBytes))
+                .sort((a, b) => b.sizeBytes - a.sizeBytes || a.relativePath.localeCompare(b.relativePath))
+                .slice(0, 20)
+                .map(file => ({ sourcePath: file.relativePath, sizeBytes: file.sizeBytes, sha256: file.sha256 }));
+            localInspection = 'AVAILABLE';
+        }
+        catch {
+            // Guidance must not replace the original server failure with a local preflight error.
+            localInspection = 'UNAVAILABLE';
+        }
+    }
+    const canSuggestUpload = artifactFiles.some(file => classify(file.path) === 'MEDIA') &&
+        localMediaCandidates.length > 0;
+    return {
+        preflightReport: '.qmuse/asset-preflight.json',
+        artifactListAvailable: artifactFiles.length > 0,
+        groups,
+        localInspection,
+        localMediaCandidates,
+        pathAdvice: 'artifactFiles 是构建产物路径；localMediaCandidates 是当前源码中按大小排列的最多 20 个可上传候选，两者没有自动对应关系。上传前追踪引用并确认源文件，不能把构建产物路径直接传给上传命令。',
+        uploadCommand: canSuggestUpload
+            ? `qmuse assets upload <confirmed-local-media-file> [more-files...] --env ${input.environment} --json`
+            : null,
+        steps: [
+            artifactFiles.length
+                ? '按服务端最大文件清单逐项定位体积来源；其中单文件大小未压缩，最终以 APC 压缩包检查为准。'
+                : '服务端没有提供大文件清单，先查看构建产物和原始错误定位超限文件；不要推断超限原因或猜测本地上传路径。',
+            ...groups.map(group => group.advice),
+            ...(canSuggestUpload ? ASSET_REPAIR_STEPS.slice(0, -1) : []),
+            ...(localInspection === 'UNAVAILABLE' ? ['当前本地预检未完成，未生成上传命令；先检查项目目录和本地文件。'] : []),
+            '修复后运行构建及相关页面验证；确认当前环境的应用绑定，再按 retryCommand / retryAdvice 重新导入。',
+        ],
+    };
+}

package/dist/import/update.js

@@ -13,7 +13,7 @@ export async function resolveUpdateBase(options) {
     if (remoteChanged && !force) {
         const conflict = `平台版本已从 ${target.lastVersionId} 更新为 ${latest.id}`;
         if (!interactive) {
-            throw new Error(`${conflict}。请同步最新源码；确认以本地源码覆盖时，使用 qmuse import . --force`);
+            throw new Error(`${conflict}。请使用 qmuse pull 同步最新源码；确认以本地源码覆盖时，使用 qmuse import . --force`);
         }
         const answer = await prompt(`${conflict}。是否以本地全部源码覆盖平台代码（不会合并平台修改），并在原应用创建新版本？[y/N]：`);
         if (!/^y(?:es)?$/iu.test(answer.trim())) {

package/dist/project-lock.js

@@ -0,0 +1,36 @@
+import { lstat, mkdir, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+export async function withProjectLock(directory, action) {
+    const root = path.resolve(directory);
+    const metadata = path.join(root, '.qmuse');
+    const rootStat = await lstat(root);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('项目目录不能是符号链接');
+    await mkdir(metadata, { recursive: true });
+    if ((await lstat(metadata)).isSymbolicLink())
+        throw new Error('.qmuse 不能是符号链接');
+    const lock = path.join(metadata, 'sync.lock');
+    try {
+        await mkdir(lock);
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new Error(`项目正在导入或拉取。若上次进程已退出，请先检查 .qmuse/pull-backups，再移除 ${lock}`);
+        }
+        throw error;
+    }
+    try {
+        const recovery = await lstat(path.join(metadata, 'pull-recovery.json')).catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (recovery)
+            throw new Error('上次拉取未完成，请按 .qmuse/pull-recovery.json 的备份路径恢复文件和 project.json，确认后移除恢复标记');
+        await writeFile(path.join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() }));
+        return await action();
+    }
+    finally {
+        await rm(lock, { recursive: true, force: true });
+    }
+}

package/dist/pull.js

@@ -0,0 +1,249 @@
+import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
+import { copyFile, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { authHeaders, buildUrl, hasAuth, requestSourceHeaders } from './client.js';
+import { loadManagedProject, saveManagedProject } from './import/project.js';
+import { preflightImport } from './import/preflight.js';
+import { withProjectLock } from './project-lock.js';
+const MAX_RESPONSE_BYTES = 150 * 1024 * 1024;
+const MAX_SOURCE_BYTES = 100 * 1024 * 1024;
+const PROTECTED = new Set(['.git', '.qmuse', '.agents', '.local', '.muse-tmp', 'node_modules', 'dist', 'build', '.vite', '.turbo', '.qmuse-cli.json']);
+async function download(cfg, body) {
+    const response = await fetch(buildUrl(cfg, '/api/app-import/pull'), {
+        method: 'POST', headers: { ...authHeaders(cfg), ...requestSourceHeaders(cfg) },
+        body: JSON.stringify(body), redirect: 'error', signal: AbortSignal.timeout(120_000),
+    });
+    if (Number(response.headers.get('content-length')) > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel();
+        throw new Error('平台源码响应超过 150MB 限制');
+    }
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('平台未返回源码');
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > MAX_RESPONSE_BYTES)
+                throw new Error('平台源码响应超过 150MB 限制');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel();
+    }
+    let result;
+    try {
+        result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    }
+    catch {
+        throw new Error('平台未返回有效的同步响应，请确认 MusePub 已部署 qmuse pull 接口');
+    }
+    if (!response.ok || result?.success !== true) {
+        throw new Error(`拉取失败：${result?.errorMessage || result?.errorCode || `HTTP ${response.status}`}`);
+    }
+    return result.data;
+}
+function safePath(name) {
+    if (!name || name !== name.normalize('NFC') || /[\\:\x00-\x1f\x7f]/u.test(name) ||
+        name.split('/').some(part => !part || part === '.' || part === '..' || /[. ]$/u.test(part))) {
+        throw new Error(`平台源码包含不安全路径：${name}`);
+    }
+}
+async function stageSnapshot(snapshot, directory) {
+    if (!snapshot.files || typeof snapshot.files !== 'object' || Array.isArray(snapshot.files))
+        throw new Error('平台源码文件列表无效');
+    const entries = Object.entries(snapshot.files);
+    if (!entries.length || entries.length > 20_000)
+        throw new Error('平台源码文件数无效');
+    const seen = new Set();
+    const directories = new Map();
+    let bytes = 0;
+    for (const [name, entry] of entries) {
+        safePath(name);
+        if (!entry || entry.filePath !== name || typeof entry.value !== 'string' ||
+            (entry.encoding !== undefined && !['utf8', 'base64'].includes(entry.encoding)))
+            throw new Error(`平台源码格式无效：${name}`);
+        const folded = name.toLowerCase();
+        if (seen.has(folded))
+            throw new Error(`平台源码路径大小写冲突：${name}`);
+        seen.add(folded);
+        const parts = name.split('/');
+        for (let index = 1; index < parts.length; index++) {
+            const prefix = parts.slice(0, index).join('/');
+            const previous = directories.get(prefix.toLowerCase());
+            if (previous && previous !== prefix)
+                throw new Error(`平台源码目录大小写冲突：${name}`);
+            directories.set(prefix.toLowerCase(), prefix);
+        }
+        if (name.split('/').some(part => PROTECTED.has(part) || part === '.env' || part.startsWith('.env.')) || name === 'AGENTS.md')
+            continue;
+        const content = Buffer.from(entry.value, entry.encoding || 'utf8');
+        if (entry.encoding === 'base64' && content.toString('base64') !== entry.value)
+            throw new Error(`平台二进制编码无效：${name}`);
+        bytes += content.length;
+        if (bytes > MAX_SOURCE_BYTES)
+            throw new Error('平台源码超过 100MB 限制');
+        const destination = path.join(directory, name);
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, content, { flag: 'wx' });
+    }
+}
+async function assertParents(root, name) {
+    let current = root;
+    for (const part of name.split('/').slice(0, -1)) {
+        current = path.join(current, part);
+        const stat = await lstat(current).catch(error => {
+            if (error.code === 'ENOENT')
+                return undefined;
+            throw error;
+        });
+        if (stat && (!stat.isDirectory() || stat.isSymbolicLink()))
+            throw new Error(`本地路径冲突：${name}`);
+    }
+}
+export async function pullProject(directory, cfg, environment) {
+    if (!hasAuth(cfg))
+        throw new Error('请先执行 qmuse login');
+    return withProjectLock(directory, async () => {
+        const root = path.resolve(directory);
+        const context = await loadManagedProject(root, cfg, environment);
+        if (!context?.target)
+            throw new Error('当前环境没有导入绑定，请先执行 qmuse import');
+        if (Object.keys(context.manifest.pendingImports || {}).length)
+            throw new Error('存在未完成的导入，请先执行 qmuse import status <jobId> --wait');
+        const target = context.target;
+        const before = await preflightImport(root);
+        if (before.sourceHash !== target.lastSourceHash)
+            throw new Error('本地源码自上次导入或拉取后已有改动，已停止拉取。请先备份并处理这些改动；Git 提交不会改变 QMuse 同步基线。');
+        const originalManifest = await readFile(context.manifestPath);
+        const snapshot = await download({ ...cfg, spaceId: target.spaceId }, {
+            appId: target.appId, spaceId: target.spaceId,
+            importVersionId: target.importVersionId || target.lastVersionId, lastVersionId: target.lastVersionId,
+        });
+        if (!snapshot || snapshot.appId !== target.appId || !/^\d+$/u.test(snapshot.versionId) ||
+            snapshot.importVersionId !== (target.importVersionId || target.lastVersionId) || typeof snapshot.unchanged !== 'boolean') {
+            throw new Error('平台返回的应用或版本与绑定不一致');
+        }
+        if (snapshot.unchanged) {
+            if (snapshot.versionId !== target.lastVersionId)
+                throw new Error('平台返回的版本状态不一致');
+            return { appId: target.appId, versionId: snapshot.versionId, noChanges: true };
+        }
+        const backups = path.join(root, '.qmuse', 'pull-backups');
+        await mkdir(backups, { recursive: true });
+        if ((await lstat(backups)).isSymbolicLink())
+            throw new Error('备份目录不能是符号链接');
+        const transaction = await mkdtemp(path.join(backups, 'pull-'));
+        const stage = path.join(transaction, 'incoming');
+        const backup = path.join(transaction, 'original');
+        const recoveryPath = path.join(root, '.qmuse', 'pull-recovery.json');
+        await mkdir(stage);
+        await mkdir(backup);
+        const moved = [];
+        const written = [];
+        let applying = false;
+        let manifestSaved = false;
+        try {
+            await stageSnapshot(snapshot, stage);
+            // Validate the platform manifest through the same parser used by import.
+            if (!snapshot.project || snapshot.project.projectKind !== 'QMUSE_TEMPLATE')
+                throw new Error('平台未返回有效的工程模板信息');
+            const nextManifest = {
+                ...snapshot.project, defaultSpaceId: context.manifest.defaultSpaceId,
+                targets: context.manifest.targets, pendingImports: context.manifest.pendingImports,
+            };
+            await mkdir(path.join(stage, '.qmuse'), { recursive: true });
+            await writeFile(path.join(stage, '.qmuse', 'project.json'), JSON.stringify(nextManifest));
+            const validated = await loadManagedProject(stage, cfg, environment);
+            if (!validated)
+                throw new Error('平台工程模板信息无效');
+            const incoming = await preflightImport(stage);
+            const oldPaths = new Set(before.files.map(file => file.relativePath));
+            for (const file of incoming.files) {
+                await assertParents(root, file.relativePath);
+                const existing = await lstat(path.join(root, file.relativePath)).catch(error => {
+                    if (error.code === 'ENOENT')
+                        return undefined;
+                    throw error;
+                });
+                if (existing && (!oldPaths.has(file.relativePath) || !existing.isFile() || existing.isSymbolicLink())) {
+                    throw new Error(`平台文件与本地保留文件冲突，已停止：${file.relativePath}`);
+                }
+            }
+            if ((await preflightImport(root)).sourceHash !== before.sourceHash ||
+                !(await readFile(context.manifestPath)).equals(originalManifest))
+                throw new Error('下载期间本地源码或绑定发生变化，已停止拉取');
+            await writeFile(path.join(transaction, 'project.json'), originalManifest, { flag: 'wx' });
+            await writeFile(path.join(transaction, 'transaction.json'), JSON.stringify({
+                appId: target.appId, from: target.lastVersionId, to: snapshot.versionId,
+                originalFiles: before.files.map(file => file.relativePath), incomingFiles: incoming.files.map(file => file.relativePath),
+            }, null, 2));
+            await writeFile(recoveryPath, JSON.stringify({ backupDirectory: transaction }), { flag: 'wx' });
+            applying = true;
+            for (const file of before.files) {
+                await assertParents(root, file.relativePath);
+                const destination = path.join(backup, file.relativePath);
+                await mkdir(path.dirname(destination), { recursive: true });
+                await rename(file.absolutePath, destination);
+                moved.push(file.relativePath);
+                if (createHash('sha256').update(await readFile(destination)).digest('hex') !== file.sha256)
+                    throw new Error('写入期间本地文件发生变化');
+            }
+            for (const file of incoming.files) {
+                await assertParents(root, file.relativePath);
+                const destination = path.join(root, file.relativePath);
+                await mkdir(path.dirname(destination), { recursive: true });
+                await copyFile(file.absolutePath, destination, constants.COPYFILE_EXCL);
+                written.push({ name: file.relativePath, sha256: file.sha256 });
+            }
+            const after = await preflightImport(root);
+            if (after.sourceHash !== incoming.sourceHash)
+                throw new Error('本地保留文件与平台源码的忽略规则冲突，已停止拉取');
+            context.manifest = validated.manifest;
+            context.manifest.targets[context.environment] = {
+                ...target, importVersionId: snapshot.importVersionId,
+                lastVersionId: snapshot.versionId, lastSourceHash: after.sourceHash, updatedAt: new Date().toISOString(),
+            };
+            if (!(await readFile(context.manifestPath)).equals(originalManifest))
+                throw new Error('写入期间本地绑定发生变化');
+            await saveManagedProject(context);
+            manifestSaved = true;
+            await rm(recoveryPath);
+            return { appId: target.appId, versionId: snapshot.versionId, noChanges: false, fileCount: after.fileCount, backupDirectory: transaction };
+        }
+        catch (error) {
+            if (applying) {
+                try {
+                    for (const file of written.reverse()) {
+                        const filename = path.join(root, file.name);
+                        await assertParents(root, file.name);
+                        const current = await readFile(filename);
+                        if (createHash('sha256').update(current).digest('hex') !== file.sha256)
+                            throw new Error(`写入期间文件被修改：${file.name}`);
+                        await rm(filename);
+                    }
+                    for (const name of moved) {
+                        await assertParents(root, name);
+                        await copyFile(path.join(backup, name), path.join(root, name), constants.COPYFILE_EXCL);
+                    }
+                    if (manifestSaved)
+                        await writeFile(context.manifestPath, originalManifest);
+                    await rm(recoveryPath);
+                }
+                catch {
+                    throw new Error(`拉取失败且回滚未完成，原文件保存在 ${transaction}，请从备份恢复后再导入。原错误：${error instanceof Error ? error.message : error}`);
+                }
+            }
+            else {
+                await rm(transaction, { recursive: true, force: true });
+            }
+            throw error;
+        }
+    });
+}

package/package.json

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