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

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,32 @@ 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`。备份包含完整源码，请确认无需恢复后自行清理。
+
+`import` 和 `pull` 会在命令结束时向当前登录环境自动上报一条诊断摘要，包括 CLI 版本、操作 ID、appId/jobId、版本与源码指纹、冲突/覆盖决定、结果、错误码和可用的服务端 traceId。服务端接入既有操作日志，维护方可直接排查，不需要用户发送本地日志。上报不包含源码、文件路径、请求/响应正文、原始错误文本或凭证；不读取和上传历史日志。
+
+需要 MusePub 部署 `/api/app-import/client-event`。上报要求已登录且已确定空间；每次最多等待 1 秒、不重试，离线、超时、权限拒绝或旧服务端返回 404 不影响原命令结果。关联操作 ID 通过请求头传递，兼容旧版 import/pull 接口。服务端分别记录“pull 源码快照返回结果”和“客户端操作结果”，下载成功不等于本地应用成功；导入成功率仍以原有服务端任务指标为准。上报是尽力而为，不能当作完整用户操作计数。
+
+详细过程仍写入项目的 `.qmuse/logs/<时间戳>-<操作ID>.jsonl`，作为复杂问题的本地补充，无需加 `--log`。`import status`、`import configure` 只记录本地过程，不重复上报任务指标，日志写入命令的当前目录。保留最近 100 次操作，单次最多 256 KiB；超限省略中间事件并保留最终结果和省略数量，异常退出可能没有 `FINISH`。写日志失败不阻断业务，不改变 `--json` 的 stdout 格式。日志不进入导入包，清理不会删除 `pull-backups` 或导入错误诊断。
+
+
+
 ### 外部云服务
 
 ```bash

package/dist/cli.js

@@ -1,4 +1,6 @@
 #!/usr/bin/env node
+import { reportCliOperation } from './operation-report.js';
+import { recordOperation, withOperationLog } from './operation-log.js';
 /**
  * QMuse CLI —— 将本地 React 项目导入 QMuse。
  *
@@ -27,6 +29,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',
@@ -192,12 +196,13 @@ async function pollImportWithLogs(jobId, cfg, flags) {
         return await pollAppImport(() => queryAppImportStatus(jobId, cfg), {
             signal: abortController.signal,
             onStatus: status => {
-                if (flags['--json'] === true)
-                    return;
                 const stage = `${status.status}:${status.stage ?? ''}`;
                 if (stage === lastStage)
                     return;
                 lastStage = stage;
+                recordOperation('IMPORT_STAGE', { jobId, appId: status.appId, status: status.status, stage: status.stage });
+                if (flags['--json'] === true)
+                    return;
                 log.info(status.message || status.stage || status.status);
             },
         });
@@ -270,6 +275,8 @@ async function resolveImportConfiguration(status, cfg, flags, cloudTarget) {
     return configured.data;
 }
 async function finishImport(status, sourceHash, cfg, flags, managedProject, rootDir) {
+    recordOperation('IMPORT_RESULT', { jobId: status.jobId, appId: status.appId, toVersionId: status.versionId,
+        status: status.status, stage: status.stage, errorCode: status.failureDiagnostic?.code });
     if (status.status !== 'READY' || !status.appId || !status.versionId) {
         const guidance = configurationGuidance(status, resolveProjectEnvironment(cfg, str(flags, '--env')), parseImportCloudMode(str(flags, '--cloud-mode')));
         if (flags['--json'] === true) {
@@ -374,6 +381,11 @@ async function cmdAssets(command, flags) {
 }
 async function cmdImport(command, flags) {
     const cfg = resolveCfg(flags);
+    recordOperation('CONTEXT', { environment: resolveProjectEnvironment(cfg, str(flags, '--env')),
+        spaceId: str(flags, '--space-id') || cfg.spaceId,
+        jobId: ['status', 'configure'].includes(command[1]) ? command[2] : undefined, force: flags['--force'] === true });
+    if (!hasAuth(cfg))
+        recordOperation('STOP', { reason: 'AUTH_REQUIRED' });
     requireAuth(cfg);
     const subcommand = command[1];
     if (subcommand === 'status') {
@@ -402,6 +414,7 @@ async function cmdImport(command, flags) {
             if (!result.ok || !result.data) {
                 fail(`查询导入任务失败：${result.errorMessage ?? result.errorCode ?? `HTTP ${result.status}`}`);
             }
+            recordOperation('IMPORT_STAGE', { jobId, appId: result.data.appId, status: result.data.status, stage: result.data.stage, toVersionId: result.data.versionId });
             printImportStatus(result.data, flags);
         }
         return;
@@ -456,10 +469,15 @@ 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'));
+    recordOperation('BINDING', { environment: managedProject.environment, appId: managedProject.target?.appId,
+        spaceId: managedProject.target?.spaceId || str(flags, '--space-id') || managedProject.manifest.defaultSpaceId || cfg.spaceId,
+        fromVersionId: managedProject.target?.lastVersionId,
+        importVersionId: managedProject.target?.importVersionId, baselineHash: managedProject.target?.lastSourceHash });
     if (managedProject.manifest.schemaVersion === 2)
         await assertTemplateProtocolSupported(cfg);
     const pendingImport = managedProject.manifest.pendingImports?.[managedProject.environment];
     if (pendingImport) {
+        recordOperation('STOP', { reason: 'IMPORT_PENDING', jobId: pendingImport.jobId });
         throw new Error(`当前目录有尚未完成的导入任务，请先执行 qmuse import status ${pendingImport.jobId} --wait --env ${managedProject.environment}，避免重复创建应用`);
     }
     const explicitSpaceId = str(flags, '--space-id');
@@ -481,7 +499,9 @@ async function cmdImport(command, flags) {
     const cloudMode = parseImportCloudMode(str(flags, '--cloud-mode'));
     if (flags['--json'] !== true)
         log.info('正在只读预检本地仓库...');
+    recordOperation('STEP', { stage: 'PREFLIGHT' });
     const preflight = await preflightImport(directory);
+    recordOperation('PREFLIGHT', { sourceHash: preflight.sourceHash, fileCount: preflight.fileCount, operation, spaceId });
     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 压缩包检查为准。`);
@@ -496,6 +516,7 @@ async function cmdImport(command, flags) {
         })
         : undefined;
     if (managedProject?.target?.lastSourceHash === preflight.sourceHash && !updateBase?.remoteChanged) {
+        recordOperation('IMPORT_RESULT', { status: 'READY', noChanges: true, appId: managedProject.target.appId, toVersionId: managedProject.target.lastVersionId });
         const result = {
             success: true,
             noChanges: true,
@@ -528,6 +549,7 @@ async function cmdImport(command, flags) {
         }
         log.info('正在打包并上传源码...');
     }
+    recordOperation('STEP', { stage: 'ARCHIVE' });
     const archive = await createImportArchive(preflight);
     let sourceToken;
     try {
@@ -564,6 +586,7 @@ async function cmdImport(command, flags) {
         throw new Error(`创建导入任务失败：${started.errorMessage ?? started.errorCode ?? `HTTP ${started.status}`}`);
     }
     const jobId = started.data.jobId;
+    recordOperation('IMPORT_STARTED', { jobId, appId: managedProject.target?.appId, operation, fromVersionId: updateBase?.baseVersionId });
     if (managedProject) {
         setPendingImport(managedProject, {
             apiBaseUrl: cfg.baseUrl,
@@ -880,6 +903,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 +970,23 @@ 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 withOperationLog({ directory: command[1] || '.', command: 'pull',
+                    report: summary => reportCliOperation(summary, resolveCfg(flags)) }, () => 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 +997,18 @@ async function main() {
                 await cmdAssets(command, flags);
                 break;
             case 'import':
-                await cmdImport(command, flags);
+                await withOperationLog({
+                    directory: command[1] && !['status', 'configure'].includes(command[1]) ? command[1] : process.cwd(),
+                    command: command[1] === 'status' ? 'import-status' : command[1] === 'configure' ? 'import-configure' : 'import',
+                    exitCode: () => Number(process.exitCode || 0),
+                    report: summary => reportCliOperation(summary, resolveCfg(flags)),
+                }, async () => {
+                    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/client.js

@@ -1,11 +1,4 @@
-/**
- * QMuse HTTP 客户端：
- *  - 拼接 baseUrl + apiPrefix + 路径
- *  - 仅向登录时绑定的 API Origin 注入 sessionId
- *  - 兼容两种响应包装：
- *      * CommonHttpResult<T> = { success, data?, errorCode?, errorMessage?, traceId? }
- *      * IQmuseResult<T>     = { success, errorCode, errorMessage, retriable?, resultObj? }
- */
+import { currentOperationId, recordHttpResult } from './operation-log.js';
 import { apiOrigin, loadConfig } from './config.js';
 import { QMUSE_CLI_DISTRIBUTION, QMUSE_CLI_NAME, QMUSE_CLI_VERSION, } from './version.js';
 /** 拼接完整请求地址。 */
@@ -40,6 +33,9 @@ export function authHeaders(cfg) {
         'x-qmuse-client-version': QMUSE_CLI_VERSION,
         'x-qmuse-client-distribution': QMUSE_CLI_DISTRIBUTION,
     };
+    const operationId = currentOperationId();
+    if (operationId)
+        headers['x-qmuse-operation-id'] = operationId;
     const sid = (cfg.sessionId || '').trim();
     if (sid && credentialMatchesTarget(cfg)) {
         headers['x-session-id'] = sid;
@@ -97,11 +93,13 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
     if (body !== undefined && method !== 'GET') {
         init.body = JSON.stringify(body);
     }
+    const startedAt = Date.now();
     let res;
     try {
         res = await fetch(url, init);
     }
     catch (err) {
+        recordHttpResult({ method, route: path, startedAt, networkError: true });
         const msg = err instanceof Error ? err.message : String(err);
         return {
             ok: false,
@@ -113,7 +111,10 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
         };
     }
     let json = null;
-    const text = await res.text();
+    const text = await res.text().catch(error => {
+        recordHttpResult({ method, route: path, startedAt, response: res, payload: { success: false, errorCode: 'RESPONSE_READ_ERROR' } });
+        throw error;
+    });
     if (text) {
         try {
             json = JSON.parse(text);
@@ -122,6 +123,7 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
             json = null;
         }
     }
+    recordHttpResult({ method, route: path, startedAt, response: res, payload: json });
     const setCookie = readSetCookie(res);
     const extracted = extractData(json);
     return {

package/dist/import/api.js

@@ -1,3 +1,4 @@
+import { recordHttpResult, recordOperation } from '../operation-log.js';
 import { openAsBlob } from 'node:fs';
 import { apiCall, authHeaders, buildUrl, requestSourceHeaders, } from '../client.js';
 import { assertImportArchiveSize } from './limits.js';
@@ -15,6 +16,8 @@ export async function uploadImportArchive(input, cfg) {
     headers['Content-Length'] = String(archive.size);
     headers['x-space-id'] = input.spaceId;
     Object.assign(headers, requestSourceHeaders(cfg));
+    const startedAt = Date.now();
+    recordOperation('STEP', { stage: 'UPLOAD' });
     let response;
     try {
         response = await fetch(buildUrl(cfg, '/api/app-import/source'), {
@@ -24,8 +27,10 @@ export async function uploadImportArchive(input, cfg) {
         });
     }
     catch (error) {
+        recordHttpResult({ method: 'POST', route: '/api/app-import/source', startedAt, networkError: true });
         throw new Error(`上传源码失败：${error instanceof Error ? error.message : String(error)}`);
     }
+    recordHttpResult({ method: 'POST', route: '/api/app-import/source', startedAt, response });
     const contentType = response.headers.get('content-type')?.split(';')[0].trim();
     const traceId = response.headers.get('x-trace-id') ?? response.headers.get('trace-id');
     const details = [
@@ -50,6 +55,8 @@ export async function uploadImportArchive(input, cfg) {
         throw new Error(`上传源码失败：服务端响应结构错误（${details}）`);
     }
     const result = payload;
+    recordOperation('UPLOAD_RESPONSE', { status: result.success === true ? 'SUCCESS' : 'FAILED', errorCode: result.errorCode,
+        traceId: typeof payload.traceId === 'string' ? payload.traceId : undefined });
     if (!response.ok || result.success !== true) {
         const reason = typeof result.errorMessage === 'string' ? result.errorMessage
             : typeof result.errorCode === 'string' ? result.errorCode : '服务端拒绝上传';

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

@@ -1,3 +1,4 @@
+import { recordOperation } from '../operation-log.js';
 import { apiCall } from '../client.js';
 export async function resolveUpdateBase(options) {
     const { target, cfg, force, interactive, prompt } = options;
@@ -10,16 +11,22 @@ export async function resolveUpdateBase(options) {
         throw new Error('平台未返回有效的应用最新版本，已停止导入');
     }
     const remoteChanged = latest.id !== target.lastVersionId;
+    recordOperation('VERSION_CHECK', { appId: target.appId, fromVersionId: target.lastVersionId, toVersionId: latest.id, remoteChanged, force });
     if (remoteChanged && !force) {
         const conflict = `平台版本已从 ${target.lastVersionId} 更新为 ${latest.id}`;
         if (!interactive) {
-            throw new Error(`${conflict}。请同步最新源码；确认以本地源码覆盖时，使用 qmuse import . --force`);
+            recordOperation('CONFLICT', { reason: 'REMOTE_VERSION_CHANGED', confirmed: false });
+            throw new Error(`${conflict}。请使用 qmuse pull 同步最新源码；确认以本地源码覆盖时，使用 qmuse import . --force`);
         }
         const answer = await prompt(`${conflict}。是否以本地全部源码覆盖平台代码（不会合并平台修改），并在原应用创建新版本？[y/N]：`);
-        if (!/^y(?:es)?$/iu.test(answer.trim())) {
+        const confirmed = /^y(?:es)?$/iu.test(answer.trim());
+        recordOperation('OVERWRITE_DECISION', { confirmed, force: false });
+        if (!confirmed) {
             throw new Error('已取消覆盖，未上传源码或更改本地版本绑定');
         }
     }
+    if (force)
+        recordOperation('OVERWRITE_DECISION', { confirmed: true, force: true });
     // Keep the confirmed version fixed so server-side concurrency checks still apply.
     return { baseVersionId: latest.id, remoteChanged };
 }

package/dist/operation-log.js

@@ -0,0 +1,156 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { closeSync, lstatSync, mkdirSync, openSync, readdirSync, unlinkSync, writeSync } from 'node:fs';
+import path from 'node:path';
+import { QMUSE_CLI_VERSION } from './version.js';
+const MAX_FILES = 100;
+const MAX_BYTES = 256 * 1024;
+const LOG_NAME = /^\d{13}-[a-f0-9-]{36}\.jsonl$/u;
+const context = new AsyncLocalStorage();
+const summaryKeys = ['environment', 'appId', 'spaceId', 'jobId', 'fromVersionId', 'toVersionId', 'importVersionId',
+    'sourceHash', 'baselineHash', 'stage', 'reason', 'errorCode', 'traceId', 'force', 'confirmed', 'remoteChanged', 'noChanges'];
+export function currentOperationId() {
+    return context.getStore()?.operationId;
+}
+const strings = ['cliVersion', 'environment', 'appId', 'spaceId', 'jobId', 'operation', 'fromVersionId', 'toVersionId',
+    'importVersionId', 'sourceHash', 'baselineHash', 'status', 'stage', 'reason', 'traceId', 'method'];
+const numbers = ['httpStatus', 'durationMs', 'fileCount', 'exitCode'];
+const booleans = ['force', 'confirmed', 'remoteChanged', 'noChanges'];
+function safeFields(fields) {
+    const safe = {};
+    for (const key of strings) {
+        const value = fields[key];
+        if (typeof value === 'string' && /^[a-z0-9_.:-]{1,128}$/iu.test(value))
+            safe[key] = value;
+    }
+    if (typeof fields.errorCode === 'string' && /^[A-Za-z][A-Za-z0-9_]{0,95}$/u.test(fields.errorCode))
+        safe.errorCode = fields.errorCode;
+    if (typeof fields.route === 'string' && /^\/api\/[a-z0-9/_-]{1,120}$/iu.test(fields.route))
+        safe.route = fields.route;
+    for (const key of numbers)
+        if (typeof fields[key] === 'number' && Number.isFinite(fields[key]))
+            safe[key] = fields[key];
+    for (const key of booleans)
+        if (typeof fields[key] === 'boolean')
+            safe[key] = fields[key];
+    return safe;
+}
+function warn(log) {
+    if (!log.warned) {
+        log.warned = true;
+        process.stderr.write('QMuse 操作日志写入失败；本次命令继续执行。\n');
+    }
+}
+function append(log, event, fields = {}, terminal = false) {
+    const safe = safeFields(fields);
+    for (const key of summaryKeys) {
+        if (safe[key] !== undefined)
+            Object.assign(log.summary, { [key]: safe[key] });
+    }
+    if (event === 'HTTP_RESULT' && !safe.errorCode)
+        delete log.summary.errorCode;
+    if (terminal) {
+        log.summary.result = safe.status;
+        log.summary.durationMs = safe.durationMs;
+    }
+    if (log.fd === undefined)
+        return;
+    const line = JSON.stringify({ schemaVersion: 1, time: new Date().toISOString(), operationId: log.operationId,
+        event, ...safe, ...(terminal ? { droppedEvents: log.dropped } : {}) }) + '\n';
+    const bytes = Buffer.byteLength(line);
+    // Reserve space for the terminal result even after a long polling session.
+    if (!terminal && log.bytes + bytes > MAX_BYTES - 4096) {
+        log.dropped++;
+        return;
+    }
+    try {
+        writeSync(log.fd, line);
+        log.bytes += bytes;
+    }
+    catch {
+        warn(log);
+    }
+}
+export function recordOperation(event, fields = {}) {
+    const log = context.getStore();
+    if (log)
+        append(log, event, fields);
+}
+export function recordHttpResult(input) {
+    if (!context.getStore())
+        return;
+    const payload = input.payload && typeof input.payload === 'object' ? input.payload : {};
+    const trace = input.response?.headers.get('x-trace-id') || input.response?.headers.get('trace-id') || payload.traceId;
+    recordOperation('HTTP_RESULT', {
+        method: input.method, route: input.route.split('?')[0], httpStatus: input.response?.status ?? 0,
+        durationMs: Date.now() - input.startedAt,
+        traceId: typeof trace === 'string' ? trace : undefined,
+        errorCode: input.networkError ? 'NETWORK_ERROR' : typeof payload.errorCode === 'string' ? payload.errorCode : undefined,
+        status: input.networkError || input.response?.ok === false || payload.success === false ? 'FAILED' : 'RECEIVED',
+    });
+}
+export async function withOperationLog(options, action) {
+    const operationId = randomUUID();
+    const log = { operationId, startedAt: Date.now(), bytes: 0, dropped: 0, warned: false,
+        summary: { operationId, command: options.command, cliVersion: QMUSE_CLI_VERSION } };
+    try {
+        const root = path.resolve(options.directory);
+        if (!lstatSync(root).isDirectory())
+            throw new Error('not a project directory');
+        let directory = root;
+        for (const name of ['.qmuse', 'logs']) {
+            directory = path.join(directory, name);
+            try {
+                mkdirSync(directory, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            const stat = lstatSync(directory);
+            if (!stat.isDirectory() || stat.isSymbolicLink())
+                throw new Error('unsafe log directory');
+        }
+        log.fd = openSync(path.join(directory, `${log.startedAt}-${log.operationId}.jsonl`), 'wx', 0o600);
+        // Delete only this logger's own files. Never prune pull backups or diagnostics.
+        const files = readdirSync(directory).filter(name => LOG_NAME.test(name)).sort();
+        for (const name of files.slice(0, Math.max(0, files.length - MAX_FILES))) {
+            try {
+                unlinkSync(path.join(directory, name));
+            }
+            catch { /* another command may have pruned it */ }
+        }
+    }
+    catch {
+        warn(log);
+    }
+    return context.run(log, async () => {
+        append(log, 'START', { operation: options.command, cliVersion: QMUSE_CLI_VERSION });
+        try {
+            const value = await action();
+            const exitCode = options.exitCode?.() ?? 0;
+            append(log, 'FINISH', { status: exitCode === 0 ? 'SUCCESS' : exitCode === 130 ? 'INTERRUPTED' : exitCode === 1 ? 'FAILED' : 'INCOMPLETE',
+                exitCode, durationMs: Date.now() - log.startedAt }, true);
+            return value;
+        }
+        catch (error) {
+            append(log, 'FINISH', { status: 'FAILED', exitCode: 1, durationMs: Date.now() - log.startedAt }, true);
+            throw error;
+        }
+        finally {
+            // A reporting failure must never replace the command's result or exception.
+            try {
+                await options.report?.({ ...log.summary });
+            }
+            catch { /* best effort */ }
+            if (log.fd !== undefined) {
+                try {
+                    closeSync(log.fd);
+                }
+                catch {
+                    warn(log);
+                }
+            }
+        }
+    });
+}

package/dist/operation-report.js

@@ -0,0 +1,24 @@
+import { authHeaders, buildUrl, hasAuth, requestSourceHeaders } from './client.js';
+/** One bounded summary per import/pull; never upload log files or retry a failed report. */
+export async function reportCliOperation(summary, cfg) {
+    if (!hasAuth(cfg) || !summary.spaceId || !['import', 'pull'].includes(summary.command))
+        return;
+    const controller = new AbortController();
+    let timer;
+    try {
+        const timeout = new Promise(resolve => {
+            timer = setTimeout(() => { controller.abort(); resolve(); }, 1000);
+        });
+        const request = fetch(buildUrl(cfg, '/api/app-import/client-event'), {
+            method: 'POST', redirect: 'error', signal: controller.signal,
+            headers: { ...authHeaders({ ...cfg, spaceId: summary.spaceId }), ...requestSourceHeaders(cfg) },
+            body: JSON.stringify(summary),
+        }).then(response => { void response.body?.cancel().catch(() => undefined); }).catch(() => undefined);
+        await Promise.race([request, timeout]);
+    }
+    catch { /* offline, old servers and telemetry errors do not affect the operation */ }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}

package/dist/project-lock.js

@@ -0,0 +1,40 @@
+import { recordOperation } from './operation-log.js';
+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') {
+            recordOperation('STOP', { reason: 'PROJECT_LOCKED' });
+            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) {
+            recordOperation('STOP', { reason: 'MANUAL_RECOVERY_REQUIRED' });
+            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,278 @@
+import { recordHttpResult, recordOperation } from './operation-log.js';
+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, resolveProjectEnvironment } 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 startedAt = Date.now();
+    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),
+    }).catch(error => {
+        recordHttpResult({ method: 'POST', route: '/api/app-import/pull', startedAt, networkError: true });
+        throw error;
+    });
+    recordHttpResult({ method: 'POST', route: '/api/app-import/pull', startedAt, response });
+    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 接口');
+    }
+    recordOperation('PULL_RESPONSE', { status: result?.success === true ? 'SUCCESS' : 'FAILED',
+        errorCode: result?.errorCode, traceId: result?.traceId });
+    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) {
+    recordOperation('CONTEXT', { environment: resolveProjectEnvironment(cfg, environment), spaceId: cfg.spaceId });
+    if (!hasAuth(cfg)) {
+        recordOperation('STOP', { reason: 'AUTH_REQUIRED' });
+        throw new Error('请先执行 qmuse login');
+    }
+    return withProjectLock(directory, async () => {
+        const root = path.resolve(directory);
+        const context = await loadManagedProject(root, cfg, environment);
+        if (!context?.target) {
+            recordOperation('STOP', { reason: 'BINDING_MISSING' });
+            throw new Error('当前环境没有导入绑定，请先执行 qmuse import');
+        }
+        if (Object.keys(context.manifest.pendingImports || {}).length) {
+            recordOperation('STOP', { reason: 'IMPORT_PENDING' });
+            throw new Error('存在未完成的导入，请先执行 qmuse import status <jobId> --wait');
+        }
+        const target = context.target;
+        recordOperation('BINDING', { appId: target.appId, spaceId: target.spaceId, fromVersionId: target.lastVersionId,
+            importVersionId: target.importVersionId || target.lastVersionId, baselineHash: target.lastSourceHash });
+        recordOperation('STEP', { stage: 'PREFLIGHT' });
+        const before = await preflightImport(root);
+        recordOperation('PREFLIGHT', { sourceHash: before.sourceHash, fileCount: before.fileCount });
+        if (before.sourceHash !== target.lastSourceHash) {
+            recordOperation('STOP', { reason: 'LOCAL_SOURCE_CHANGED' });
+            throw new Error('本地源码自上次导入或拉取后已有改动，已停止拉取。请先备份并处理这些改动；Git 提交不会改变 QMuse 同步基线。');
+        }
+        const originalManifest = await readFile(context.manifestPath);
+        recordOperation('STEP', { stage: 'DOWNLOAD' });
+        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('平台返回的应用或版本与绑定不一致');
+        }
+        recordOperation('VERSION_CHECK', { toVersionId: snapshot.versionId, importVersionId: snapshot.importVersionId, noChanges: snapshot.unchanged });
+        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 {
+            recordOperation('STEP', { stage: 'VALIDATE_SNAPSHOT' });
+            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' });
+            recordOperation('STEP', { stage: 'APPLY_SNAPSHOT' });
+            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);
+            recordOperation('PULL_APPLIED', { appId: target.appId, toVersionId: snapshot.versionId, sourceHash: after.sourceHash, fileCount: after.fileCount });
+            return { appId: target.appId, versionId: snapshot.versionId, noChanges: false, fileCount: after.fileCount, backupDirectory: transaction };
+        }
+        catch (error) {
+            if (applying) {
+                recordOperation('ROLLBACK', { status: 'STARTED' });
+                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);
+                    recordOperation('ROLLBACK', { status: 'SUCCESS' });
+                }
+                catch {
+                    recordOperation('ROLLBACK', { status: 'FAILED', reason: 'MANUAL_RECOVERY_REQUIRED' });
+                    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.3",
   "description": "将本地 React 项目安全导入 QMuse 的命令行客户端",
   "type": "module",
   "bin": {