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

package/README.md

@@ -62,6 +62,8 @@ qmuse assets upload public/photo.png public/audio/clip.wav --json
 
 导入时会生成 `.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
@@ -84,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

@@ -27,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',
@@ -880,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 保存密钥，不输出密钥值
@@ -946,6 +949,22 @@ 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;
@@ -956,7 +975,11 @@ async function main() {
                 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

@@ -17,11 +17,16 @@ const MEDIA = {
     '.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 不会减少发布体积。',
+    '确认当前环境的应用绑定后，重新执行 qmuse import .；服务端会重新构建并检查 APC 压缩发布包，单纯上传 CDN 不会减少发布体积。',
 ];
 async function writeJson(file, value) {
     const temporary = `${file}.${randomUUID()}.tmp`;
@@ -38,16 +43,19 @@ 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: Boolean(MEDIA[path.extname(asset.sourcePath).toLowerCase()]),
+            uploadSupported: supportsAssetUpload(asset.sourcePath, asset.sizeBytes),
         })).sort((a, b) => b.sizeBytes - a.sizeBytes),
-        uploadCommand: 'qmuse assets upload <relative-file> [more-files...] --json',
-        repairSteps: ASSET_REPAIR_STEPS,
+        uploadCommand: hasUploadCandidates ? 'qmuse assets upload <relative-file> [more-files...] --json' : null,
+        repairSteps: hasUploadCandidates ? ASSET_REPAIR_STEPS : [
+            '本地预检没有发现受支持的媒体上传候选。结合服务端发布包诊断检查数据、代码及其他构建产物；不要把 JSON、JS/CSS、SVG、字体或模型文件直接传给 assets upload。',
+        ],
     });
     return file;
 }

package/dist/import/diagnostic.js

@@ -1,4 +1,4 @@
-import { ASSET_REPAIR_STEPS } from './assets.js';
+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';
@@ -27,12 +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'}`)),
-            },
+        ...(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,

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.9-dev.1",
+  "version": "1.0.9-dev.2",
   "description": "将本地 React 项目安全导入 QMuse 的命令行客户端",
   "type": "module",
   "bin": {