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

package/README.md

@@ -104,6 +104,14 @@ qmuse import .               # 更新同一应用
 
 每次更新前，原源码和绑定保存在终端返回的 `.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。
  *
@@ -194,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);
             },
         });
@@ -272,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) {
@@ -376,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') {
@@ -404,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;
@@ -458,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');
@@ -483,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 压缩包检查为准。`);
@@ -498,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,
@@ -530,6 +549,7 @@ async function cmdImport(command, flags) {
         }
         log.info('正在打包并上传源码...');
     }
+    recordOperation('STEP', { stage: 'ARCHIVE' });
     const archive = await createImportArchive(preflight);
     let sourceToken;
     try {
@@ -566,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,
@@ -953,7 +974,8 @@ async function main() {
                 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'));
+                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 {
@@ -975,11 +997,18 @@ async function main() {
                 await cmdAssets(command, flags);
                 break;
             case 'import':
-                if (command[1] && !['status', 'configure'].includes(command[1])) {
-                    await withProjectLock(command[1], () => cmdImport(command, flags));
-                }
-                else
-                    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/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) {
+            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

@@ -1,3 +1,4 @@
+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) {
@@ -15,6 +16,7 @@ export async function withProjectLock(directory, action) {
     }
     catch (error) {
         if (error.code === 'EEXIST') {
+            recordOperation('STOP', { reason: 'PROJECT_LOCKED' });
             throw new Error(`项目正在导入或拉取。若上次进程已退出，请先检查 .qmuse/pull-backups，再移除 ${lock}`);
         }
         throw error;
@@ -25,8 +27,10 @@ export async function withProjectLock(directory, action) {
                 return undefined;
             throw error;
         });
-        if (recovery)
+        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();
     }

package/dist/pull.js

@@ -1,19 +1,25 @@
+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 } from './import/project.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 限制');
@@ -44,6 +50,8 @@ async function download(cfg, body) {
     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}`}`);
     }
@@ -108,20 +116,34 @@ async function assertParents(root, name) {
     }
 }
 export async function pullProject(directory, cfg, environment) {
-    if (!hasAuth(cfg))
+    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)
+        if (!context?.target) {
+            recordOperation('STOP', { reason: 'BINDING_MISSING' });
             throw new Error('当前环境没有导入绑定，请先执行 qmuse import');
-        if (Object.keys(context.manifest.pendingImports || {}).length)
+        }
+        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);
-        if (before.sourceHash !== target.lastSourceHash)
+        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,
@@ -130,6 +152,7 @@ export async function pullProject(directory, cfg, environment) {
             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('平台返回的版本状态不一致');
@@ -150,6 +173,7 @@ export async function pullProject(directory, cfg, environment) {
         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')
@@ -185,6 +209,7 @@ export async function pullProject(directory, cfg, environment) {
                 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);
@@ -215,10 +240,12 @@ export async function pullProject(directory, cfg, environment) {
             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);
@@ -235,8 +262,10 @@ export async function pullProject(directory, cfg, environment) {
                     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}`);
                 }
             }

package/package.json

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