@qmuse/qmuse-cli 1.0.9-dev.4 → 1.0.10-dev.1

package/dist/client.js

@@ -1,6 +1,27 @@
 import { currentOperationId, recordHttpResult } from './operation-log.js';
+import { normalizeRoute, recordEvent, telemetryCommand, telemetryEnvironment, telemetryRequestHeaders } from './telemetry.js';
+import { classifyNetworkError, httpStatusHint, parseRetryAfterMs, sanitizeMessage } from './errors.js';
+/** T01.02/03：每次业务 HTTP 请求记录受控来源事件 + 服务端 traceId 对账键。 */
+function recordTelemetryHttp(input) {
+    const headerTrace = input.response?.headers.get('x-trace-id') || input.response?.headers.get('trace-id') || undefined;
+    recordEvent({
+        kind: 'cli.http.request',
+        method: input.method,
+        route: normalizeRoute(input.route),
+        httpStatus: input.response?.status ?? 0,
+        durationMs: Date.now() - input.startedAt,
+        errorCode: input.errorCode,
+        result: input.networkError || input.response?.ok === false || input.businessFailed ? 'failed' : 'received',
+        operationId: currentOperationId(),
+        command: telemetryCommand(),
+        environment: telemetryEnvironment(),
+        trace: input.trace ?? headerTrace ?? undefined,
+    });
+}
 import { apiOrigin, loadConfig } from './config.js';
 import { QMUSE_CLI_DISTRIBUTION, QMUSE_CLI_NAME, QMUSE_CLI_VERSION, } from './version.js';
+/** 业务请求默认超时：避免服务端无响应时 CLI 无限挂起。长任务（上传/SSE）调用方显式放大。 */
+export const DEFAULT_REQUEST_TIMEOUT_MS = 120_000;
 /** 拼接完整请求地址。 */
 export function buildUrl(cfg, path) {
     const base = cfg.baseUrl.replace(/\/+$/, '');
@@ -36,6 +57,8 @@ export function authHeaders(cfg) {
     const operationId = currentOperationId();
     if (operationId)
         headers['x-qmuse-operation-id'] = operationId;
+    // T01.02：受控命令链与进程级 invocation 关联（服务端按未知头忽略，兼容旧网关）。
+    Object.assign(headers, telemetryRequestHeaders());
     const sid = (cfg.sessionId || '').trim();
     if (sid && credentialMatchesTarget(cfg)) {
         headers['x-session-id'] = sid;
@@ -67,12 +90,27 @@ function extractData(json) {
     // 非标准包装：按 HTTP 状态判定，原始体作为 data 返回
     return { ok: false, data: json };
 }
+/**
+ * 区分 CallOptions 与 QmuseCliConfig：
+ * 带 baseUrl 的对象默认是配置；若同时显式带了 timeoutMs，则按「配置 + 选项」混合处理，
+ * 让 `apiCall(..., { ...cfg, timeoutMs })` 这种写法也能生效。
+ */
+function isCallOptions(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    if (!('baseUrl' in record))
+        return true;
+    return ['timeoutMs', 'anonymous', 'signal', 'redirect'].some(key => key in record);
+}
 /** 发起一次 musepub 调用。 */
 export async function apiCall(method, path, body, cfgOverrideOrOpts) {
-    const opts = cfgOverrideOrOpts && typeof cfgOverrideOrOpts === 'object' && !('baseUrl' in cfgOverrideOrOpts)
+    const opts = isCallOptions(cfgOverrideOrOpts)
         ? cfgOverrideOrOpts
         : { cfg: cfgOverrideOrOpts };
-    const cfg = opts.cfg ?? loadConfig();
+    const cfg = opts.cfg ?? (cfgOverrideOrOpts && typeof cfgOverrideOrOpts === 'object' && 'baseUrl' in cfgOverrideOrOpts
+        ? cfgOverrideOrOpts
+        : loadConfig());
     const url = buildUrl(cfg, path);
     const headers = opts.anonymous
         ? {
@@ -81,13 +119,17 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
             'x-qmuse-client': QMUSE_CLI_NAME,
             'x-qmuse-client-version': QMUSE_CLI_VERSION,
             'x-qmuse-client-distribution': QMUSE_CLI_DISTRIBUTION,
+            ...telemetryRequestHeaders(),
         }
         : authHeaders(cfg);
     if (method === 'POST' && !headers['Referer']) {
         Object.assign(headers, requestSourceHeaders(cfg));
     }
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const signal = opts.signal ? AbortSignal.any([opts.signal, timeoutSignal]) : timeoutSignal;
     const init = { method, headers,
-        ...(opts.signal ? { signal: opts.signal } : {}),
+        signal,
         ...(opts.redirect ? { redirect: opts.redirect } : {}),
     };
     if (body !== undefined && method !== 'GET') {
@@ -99,15 +141,20 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
         res = await fetch(url, init);
     }
     catch (err) {
+        // 调用方主动中止（如 Ctrl-C）不算网络错误，保留原语义给上层判断。
+        if (opts.signal?.aborted === true)
+            throw err;
+        const classified = classifyNetworkError(err, timeoutMs);
+        recordTelemetryHttp({ method, route: path, startedAt, networkError: true, errorCode: classified.code });
         recordHttpResult({ method, route: path, startedAt, networkError: true });
-        const msg = err instanceof Error ? err.message : String(err);
         return {
             ok: false,
             status: 0,
             raw: null,
             setCookie: [],
-            errorCode: 'NETWORK_ERROR',
-            errorMessage: `请求失败 ${url}: ${msg}`,
+            errorCode: classified.code,
+            errorMessage: `${classified.message}（${buildUrl(cfg, '')}）`,
+            ...(classified.hint ? { hint: classified.hint } : {}),
         };
     }
     let json = null;
@@ -124,18 +171,43 @@ export async function apiCall(method, path, body, cfgOverrideOrOpts) {
         }
     }
     recordHttpResult({ method, route: path, startedAt, response: res, payload: json });
+    recordTelemetryHttp({
+        method, route: path, startedAt, response: res,
+        errorCode: typeof json?.errorCode === 'string'
+            ? json.errorCode : undefined,
+        trace: typeof json?.traceId === 'string'
+            ? json.traceId : undefined,
+        // HTTP 200 但包装层 success=false 也计为业务失败（T01.18 失败口径）。
+        businessFailed: json?.success === false,
+    });
     const setCookie = readSetCookie(res);
     const extracted = extractData(json);
+    const traceId = (typeof json?.traceId === 'string'
+        ? json.traceId
+        : res.headers.get('x-trace-id') ?? undefined);
+    const retryAfterMs = res.status === 429 ? parseRetryAfterMs(res.headers.get('retry-after')) : undefined;
+    const hint = buildHttpHint(res.status, extracted.errorCode, extracted.ok);
     return {
         ok: extracted.ok,
         data: extracted.data,
         errorCode: extracted.errorCode,
-        errorMessage: extracted.errorMessage,
+        errorMessage: extracted.errorMessage === undefined ? undefined : sanitizeMessage(extracted.errorMessage),
         raw: json,
         status: res.status,
         setCookie,
+        ...(hint ? { hint } : {}),
+        ...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
+        ...(traceId ? { traceId } : {}),
     };
 }
+/** HTTP 状态 + 服务端错误码 → 可执行建议（限流单独给等待时间）。 */
+function buildHttpHint(status, errorCode, ok) {
+    if (ok)
+        return undefined;
+    if (status === 429)
+        return '触发限流：请按 retryAfterMs 等待后重试';
+    return httpStatusHint(status) ?? (errorCode ? undefined : undefined);
+}
 /** 从响应读取所有 Set-Cookie 头（Node undici Headers.getSetCookie）。 */
 function readSetCookie(res) {
     const h = res.headers;

package/dist/errors.js

@@ -0,0 +1,143 @@
+/**
+ * 统一错误协议与输出脱敏（对齐业界 CLI 最佳实践）。
+ *
+ *  - 结构化错误：{ success:false, error:{ code, message, hint, traceId?, details? } }
+ *    人读模式：`✖ message` + 缩进 `hint`，退出码由调用方决定。
+ *  - 脱敏：服务端回显可能带 ANSI 转义、URL 账密、Bearer token、key=value 形式的密钥，
+ *    输出与埋点前统一清洗，避免凭证经 stdout 泄漏。
+ */
+const ANSI_OSC = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
+const ANSI_CSI = /\x1b\[[0-?]*[ -/]*[@-~]/g;
+const CONTROL_CHARS = /[\x00-\x08\x0b-\x1f\x7f-\x9f]/g;
+/** 清洗服务端/第三方回显的文本：去控制字符、脱敏凭证、限长。 */
+export function sanitizeMessage(value, limit = 4000) {
+    const text = typeof value === 'string' ? value : value == null ? '' : String(value);
+    const cleaned = text
+        .replace(ANSI_OSC, '')
+        .replace(ANSI_CSI, '')
+        .replace(CONTROL_CHARS, '')
+        // URL 账密：https://user:pass@host → https://[REDACTED]@host
+        .replace(/([a-z][a-z0-9+.-]*:\/\/)[^\s/@]+@/giu, '$1[REDACTED]@')
+        // Bearer / Basic 认证
+        .replace(/\b(Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/giu, '$1 [REDACTED]')
+        // key=value / key: value 形式的密钥，以及 Cookie 内容
+        .replace(/((?:[\w-]*(?:key|token|secret|password|passwd|credential|session|signature|cookie)[\w-]*)\s*["']?\s*[:=]\s*)(?:"[^"]*"|'[^']*'|[^\s,;}]+)/giu, '$1[REDACTED]')
+        // muse_user=<sid> 这类裸 cookie 片段
+        .replace(/\b(muse_user|muse_session)=[^\s;,"']+/giu, '$1=[REDACTED]');
+    return cleaned.length > limit ? `${cleaned.slice(0, limit)}…` : cleaned;
+}
+const NETWORK_HINTS = {
+    REQUEST_TIMEOUT: '服务端响应超时：请稍后重试；持续超时请检查网络或联系平台',
+    ECONNREFUSED: '无法连接到 API 服务：请确认地址正确、服务已启动（本地开发请用 --env local）',
+    ENOTFOUND: '域名解析失败：请检查网络与 --env 配置',
+    EAI_AGAIN: '域名解析暂时失败：请检查网络后重试',
+    ECONNRESET: '连接被重置：请重试；如持续出现请联系平台',
+    UND_ERR_CONNECT_TIMEOUT: '连接超时：请检查网络后重试',
+};
+/** 网络层错误 → CLI 错误码与建议。 */
+export function classifyNetworkError(error, timeoutMs) {
+    const err = error;
+    const code = err?.cause?.code || err?.code || '';
+    if (err?.name === 'TimeoutError' || err?.name === 'AbortError' && /abort/i.test(String(err?.message ?? ''))) {
+        return {
+            code: 'REQUEST_TIMEOUT',
+            message: timeoutMs ? `请求在 ${timeoutMs}ms 内未完成` : '请求超时',
+            hint: NETWORK_HINTS.REQUEST_TIMEOUT,
+        };
+    }
+    if (code && NETWORK_HINTS[code]) {
+        return { code, message: `网络请求失败：${err?.message ?? code}`, hint: NETWORK_HINTS[code] };
+    }
+    return {
+        code: 'NETWORK_ERROR',
+        message: `网络请求失败：${err?.message ?? String(error)}`,
+        hint: '请检查网络连接后重试',
+    };
+}
+/** 服务端错误码 → 建议（HTTP 状态不可用时兜底，覆盖面按实际契约逐条补）。 */
+export function errorCodeHint(code) {
+    switch (String(code ?? '').toUpperCase()) {
+        case 'NOT_FOUND':
+            return '资源不存在：请核对 appId/表单/版本 ID；也可能是该环境尚未部署对应接口';
+        case 'FORBIDDEN':
+        case 'UNAUTHORIZED':
+            return '无权限或登录态失效：请重新 qmuse login，或确认当前账号对目标空间/应用的权限';
+        case 'PERMISSION_DENIED':
+            return '权限不足：请确认账号在该空间/应用的角色';
+        case 'MODEL_REQUIRED':
+            return '未指定模型：加 --model <model>，或用 qmuse models 查看可用清单';
+        case 'INTERNAL_ERROR':
+        case 'INTERNALSERVERERROR':
+            return '服务端异常：请稍后重试；如持续出现请携带 traceId 反馈平台';
+        case 'APPWRITE_PROJECT_SECRET_NOT_FOUND':
+            return '密钥不存在或不属于当前应用：请用 qmuse secret list 核对 ID';
+        case 'APPWRITE_PROJECT_SECRET_DELETE_FORBIDDEN':
+            return '服务端只允许删除“已停用且同步完成”的密钥：先 qmuse secret disable 再 delete';
+        case 'CLOUD_SERVICE_LIMIT_EXCEEDED':
+            return '空间云服务额度已满：请释放不再使用的应用云服务或扩容';
+        default:
+            return undefined;
+    }
+}
+/** HTTP 状态 → 建议（仅在服务端没给出更具体 errorCode 时使用）。 */
+export function httpStatusHint(status) {
+    if (status === 401)
+        return '登录态无效或已过期：请重新执行 qmuse login';
+    if (status === 403)
+        return '无权限：请确认当前账号对目标空间/应用的权限';
+    if (status === 404)
+        return '资源不存在：请核对 ID/路径；接口可能尚未在该环境部署';
+    if (status === 409)
+        return '状态冲突：请先同步最新状态后重试';
+    if (status === 429)
+        return '触发限流：请稍后重试';
+    if (status >= 500)
+        return '服务端异常：请稍后重试；如持续出现请携带 traceId 反馈平台';
+    return undefined;
+}
+/** 从响应头解析 Retry-After（秒数或 HTTP-date 均可）。 */
+export function parseRetryAfterMs(value) {
+    if (!value)
+        return undefined;
+    const seconds = Number(value);
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return Math.ceil(seconds * 1000);
+    const at = Date.parse(value);
+    if (!Number.isNaN(at))
+        return Math.max(0, at - Date.now());
+    return undefined;
+}
+/** 本地语义错误码：没有服务端错误码时，从消息里推断稳定的 code（便于脚本分支）。 */
+export function inferLocalCode(message) {
+    const text = String(message ?? '');
+    if (/未知命令|unknown command/iu.test(text))
+        return 'UNKNOWN_COMMAND';
+    if (/未知 .*子命令|用法/iu.test(text))
+        return 'INVALID_ARGUMENTS';
+    if (/未登录|请先运行 `?qmuse login/iu.test(text))
+        return 'NOT_LOGGED_IN';
+    if (/超时|未完成|timeout/iu.test(text))
+        return 'REQUEST_TIMEOUT';
+    if (/网络|network/iu.test(text))
+        return 'NETWORK_ERROR';
+    if (/没有导入绑定|未找到.*绑定/iu.test(text))
+        return 'BINDING_MISSING';
+    if (/不存在|not found/iu.test(text))
+        return 'NOT_FOUND';
+    return 'UNKNOWN';
+}
+/** 组装结构化错误：错误码优先取服务端 errorCode，其次 HTTP_<status>，最后从消息推断。 */
+export function buildCliError(input) {
+    const status = input.status ?? 0;
+    const code = (input.errorCode && input.errorCode.trim())
+        || (status ? `HTTP_${status}` : inferLocalCode(input.errorMessage));
+    const message = sanitizeMessage(input.errorMessage) || (status ? `HTTP ${status}` : '未知错误');
+    const hint = input.hint ?? httpStatusHint(status) ?? errorCodeHint(code);
+    return {
+        code,
+        message,
+        ...(hint ? { hint } : {}),
+        ...(input.traceId ? { traceId: input.traceId } : {}),
+        ...(input.details && Object.keys(input.details).length > 0 ? { details: input.details } : {}),
+    };
+}

package/dist/login.js

@@ -92,8 +92,10 @@ export async function loginBrowser(cfg, options = {}, dependencyOverrides) {
             message: `创建登录请求失败：${request.errorMessage ?? request.errorCode ?? `HTTP ${request.status}`}`,
         };
     }
+    // 渠道标记：未注册用户首次登录时记录来源为 CLI 侧（chInfo 透传到注册/授权环节）。
     const authUrl = new URL('/cli-auth', cfg.webBaseUrl);
     authUrl.searchParams.set('request', token);
+    authUrl.searchParams.set('chInfo', 'ch_qmuse_active__qmuse_cli');
     if (options.logRequestDetails) {
         log.dim(`登录页面：${authUrl.origin}${authUrl.pathname}`);
     }

package/dist/telemetry.js

@@ -0,0 +1,229 @@
+/**
+ * 全链路埋点（T01）：CLI 本地事件源与有界补报。
+ *
+ * 原则（使用规则）：
+ *  - 所有实际 CLI 请求、SSE、上传下载、异步任务与适用模型/工具调用都保留来源；
+ *  - 上报失败不阻断业务：补报只尝试一次/次进程，队列有界，丢弃最旧事件也静默；
+ *  - 脱敏：序列化仅接受白名单字段（T01.16），错误消息、路径、提示词、凭证永不入事件。
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { QMUSE_CLI_DISTRIBUTION, QMUSE_CLI_VERSION } from './version.js';
+const MAX_EVENTS = 5000;
+const MAX_BYTES = 4 * 1024 * 1024;
+const MAX_FLUSH = 50;
+const MAX_ATTEMPT = 5;
+/** 简单字符串安全模式：仅闭集内的受控标识。 */
+const SAFE_ID = /^[a-z0-9_.:-]{1,128}$/iu;
+/** 命令链：允许多词子命令（chat send / release status），拒绝其它空白与控制符。 */
+const SAFE_COMMAND = /^[a-z0-9_.:-]+(?: [a-z0-9_.:-]+)*$/iu;
+const SAFE_ROUTE = /^\/api\/[a-z0-9/_-]{1,120}$/iu;
+const SAFE_CODE = /^[A-Za-z][A-Za-z0-9_]{0,95}$/u;
+let invocationIdCache;
+/** 每个进程一个 invocationId（T01.01），与 operation-log 的 operationId 正交。 */
+export function invocationId() {
+    if (!invocationIdCache) {
+        invocationIdCache = `inv_${Date.now()}_${randomUUID().replaceAll('-', '').slice(0, 24)}`;
+    }
+    return invocationIdCache;
+}
+export function currentCommandLabel(command) {
+    const [root, sub] = command;
+    return [root, sub && !sub.startsWith('-') ? sub : undefined].filter(Boolean).join(' ');
+}
+// ---- T01.02：请求来源关联（受控 command、invocation、operation、trace 由服务端缀联） ----
+let commandContext;
+let environmentContext;
+/** main() 在解析命令后设置；客户端请求头携带受控命令链，遥测事件携带环境分组。 */
+export function setTelemetryCommand(label, environment) {
+    commandContext = label && SAFE_COMMAND.test(label) ? label : undefined;
+    environmentContext = environment && SAFE_ID.test(environment) ? environment : undefined;
+}
+export function telemetryCommand() {
+    return commandContext;
+}
+export function telemetryEnvironment() {
+    return environmentContext;
+}
+/** 请求来源头：client/version/distribution 由 authHeaders 提供，这里补 invocation/command 关联。 */
+export function telemetryRequestHeaders() {
+    const headers = { 'x-qmuse-invocation-id': invocationId() };
+    if (commandContext)
+        headers['x-qmuse-command'] = commandContext;
+    return headers;
+}
+function telemetryPath() {
+    return process.env.QMUSE_CLI_TELEMETRY_PATH
+        ?? process.env.QMUSE_TELEMETRY_PATH
+        ?? path.join(homedir(), '.qmuse-cli-telemetry.jsonl');
+}
+/**
+ * 构造事件：显式白名单序列化。未知字段直接丢弃；敏感字段永远不进入事件。
+ */
+export function buildEvent(input) {
+    const event = {
+        schemaVersion: 1,
+        eventId: `evt_${randomUUID()}`,
+        occurredAt: new Date().toISOString(),
+        kind: input.kind,
+        invocationId: input.invocationId ?? invocationId(),
+        attempt: 0,
+        cliVersion: QMUSE_CLI_VERSION,
+        distribution: QMUSE_CLI_DISTRIBUTION,
+    };
+    if (input.operationId && SAFE_ID.test(input.operationId))
+        event.operationId = input.operationId;
+    if (input.command && SAFE_COMMAND.test(input.command))
+        event.command = input.command;
+    if (input.environment && SAFE_ID.test(input.environment))
+        event.environment = input.environment;
+    if (input.method === 'GET' || input.method === 'POST')
+        event.method = input.method;
+    if (input.route && SAFE_ROUTE.test(input.route))
+        event.route = input.route;
+    if (typeof input.httpStatus === 'number' && input.httpStatus >= 100 && input.httpStatus < 600)
+        event.httpStatus = input.httpStatus;
+    if (typeof input.durationMs === 'number' && Number.isFinite(input.durationMs) && input.durationMs >= 0)
+        event.durationMs = Math.round(input.durationMs);
+    if (input.result && SAFE_ID.test(input.result))
+        event.result = input.result;
+    if (input.status && SAFE_ID.test(input.status))
+        event.status = input.status;
+    if (input.stage && SAFE_ID.test(input.stage))
+        event.stage = input.stage;
+    if (input.errorCode && SAFE_CODE.test(input.errorCode))
+        event.errorCode = input.errorCode;
+    if (input.fileId && SAFE_ID.test(input.fileId))
+        event.fileId = input.fileId;
+    if (input.appType && SAFE_ID.test(input.appType))
+        event.appType = input.appType;
+    if (input.target && SAFE_ID.test(input.target))
+        event.target = input.target;
+    if (input.agent && SAFE_ID.test(input.agent))
+        event.agent = input.agent;
+    if (typeof input.bytes === 'number' && Number.isFinite(input.bytes) && input.bytes >= 0)
+        event.bytes = Math.round(input.bytes);
+    if (input.digest && /^[a-f0-9]{8,128}$/iu.test(input.digest))
+        event.digest = input.digest;
+    if (input.trace && /^[a-f0-9]{12,64}$/iu.test(input.trace))
+        event.trace = input.trace;
+    return event;
+}
+/** 规范化 HTTP 路由：剥离 query，保留受控 path。 */
+export function normalizeRoute(pathWithQuery) {
+    return pathWithQuery.split('?')[0] ?? pathWithQuery;
+}
+function readQueue() {
+    const file = telemetryPath();
+    if (!existsSync(file))
+        return [];
+    try {
+        const lines = readFileSync(file, 'utf8').split('\n').filter(Boolean);
+        const events = [];
+        for (const line of lines) {
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed?.eventId && parsed.kind && typeof parsed.attempt === 'number')
+                    events.push(parsed);
+            }
+            catch { /* 单行损坏跳过 */ }
+        }
+        return events;
+    }
+    catch {
+        return [];
+    }
+}
+function writeQueue(events) {
+    const file = telemetryPath();
+    try {
+        // 有界：事件数与字节数双重上限，超限静默丢弃最旧（T01.15 有界补报）。
+        // 裁剪后保留一半预算作为水位，避免饱和期每事件一次全量重写（O(n²) → O(n)）。
+        let kept = events.slice(-MAX_EVENTS);
+        const lines = kept.map(e => JSON.stringify(e));
+        const total = lines.reduce((sum, line) => sum + Buffer.byteLength(line, 'utf8') + 1, 0);
+        if (total > MAX_BYTES) {
+            const budget = Math.floor(MAX_BYTES / 2);
+            let used = 0, start = 0;
+            for (let i = 0; i < lines.length; i += 1) {
+                used += Buffer.byteLength(lines[i], 'utf8') + 1;
+                if (used > budget) {
+                    start = i;
+                    break;
+                }
+            }
+            kept = kept.slice(Math.max(1, start));
+        }
+        const body = kept.map(e => JSON.stringify(e)).join('\n');
+        const temporary = path.join(tmpdir(), `qmuse-tele-${process.pid}-${randomUUID()}.tmp`);
+        writeFileSync(temporary, body ? `${body}\n` : '', { encoding: 'utf8', mode: 0o600 });
+        if (existsSync(file))
+            unlinkSync(file);
+        else
+            mkdirSync(path.dirname(file), { recursive: true });
+        renameSync(temporary, file);
+    }
+    catch { /* 本地持久化失败不影响业务 */ }
+}
+/** 记录一条事件。本地写入失败静默；调用方永远不需要 try/catch 包裹。 */
+export function recordEvent(input) {
+    try {
+        const event = buildEvent(input);
+        const file = telemetryPath();
+        try {
+            appendFileSync(file, `${JSON.stringify(event)}\n`, { encoding: 'utf8', mode: 0o600 });
+            // 单次 stat：仅在读回尺寸用于压缩判断（追加后 > 上限才全量重写）。
+            if (statSync(file).size > MAX_BYTES)
+                writeQueue(readQueue());
+        }
+        catch {
+            // 首次写入（目录/文件不存在）或追加失败：走全量重写路径兜底。
+            writeQueue([...readQueue(), event]);
+        }
+    }
+    catch { /* 埋点永不抛出 */ }
+}
+/**
+ * 有界补报（T01.15）：一次进程只尝试一轮，最多 MAX_FLUSH 条，attempt+1；
+ * 超过 MAX_ATTEMPT 的丢弃。任何失败都静默且不改变业务结果。
+ * 404（采集端点尚未部署/网关未路由）不消耗 attempt——事件原样保留，
+ * 避免“端点未就绪”烧光重试预算；真正被服务端处理的失败才计数。
+ */
+export async function flushTelemetry(cfg, send) {
+    if (!cfg)
+        return undefined;
+    const queue = readQueue();
+    const alive = queue.filter(e => e.attempt < MAX_ATTEMPT);
+    if (alive.length === 0) {
+        if (queue.length > 0)
+            writeQueue([]); // 超过补报上限的事件有界丢弃
+        return undefined;
+    }
+    const batch = alive.slice(0, MAX_FLUSH).map(e => ({ ...e, attempt: e.attempt + 1 }));
+    const rest = alive.slice(MAX_FLUSH);
+    const url = `${cfg.baseUrl.replace(/\/+$/, '')}${cfg.apiPrefix ?? ''}/api/app-import/client-events`;
+    try {
+        const response = await Promise.race([
+            // 服务端 SPACE WRITE 鉴权请 batch 顶层 spaceId；缺失时不发（终端会在旧amiento端点上退化为静默）。
+            send(url, JSON.stringify({ schemaVersion: 1, spaceId: cfg.spaceId ?? '', events: batch })),
+            new Promise(resolve => setTimeout(() => resolve({ ok: false }), 2500)),
+        ]);
+        if (response.ok) {
+            writeQueue(rest);
+            return { flushed: batch.length, kept: rest.length };
+        }
+        if (response.httpStatus === 404) {
+            // 端点缺失：不消耗 attempt，队列保持原样（未被处理，无需重试计数）。
+            writeQueue(queue);
+            return { flushed: 0, kept: queue.length };
+        }
+        writeQueue([...batch, ...rest]);
+        return { flushed: 0, kept: batch.length + rest.length };
+    }
+    catch {
+        writeQueue([...batch, ...rest]);
+        return { flushed: 0, kept: batch.length + rest.length };
+    }
+}

package/dist/tracker.js

@@ -0,0 +1,130 @@
+/**
+ * CLI 命令埋点（模拟 Tracert dwcookie 协议 → 蚂蚁采集 MAU）
+ *
+ * 模式参考 muse-cli scripts/utils/tracker.js（同一作者，已验证有效）：
+ *  - POST https://collect.alipay.com/dwcookie
+ *  - x-www-form-urlencoded: data=<24 个逗号分隔字段（仅填必填 7 项）>
+ *  - fire-and-forget，失败不影响主流程
+ *
+ * 需要注册 SPM 位（a5400 是 QMuse Web 的 A 位）：
+ *  - B 位：CLI 入口
+ *  - C 位：每个命令一个 click 事件
+ */
+import { randomUUID } from 'node:crypto';
+const COLLECT_URL = 'https://collect.alipay.com/dwcookie';
+const QMUSE_WEB_ORIGIN = 'https://www.qmuse.cn';
+const SPM_A = 'a5400'; // QMuse Web 的 SPM A 位（config/config.ts tracert.spmAPos）
+const SPM_B = 'b272935'; // antlog spm apply-b 注册（demand 265100137，name=QMuse CLI，event=virtual）
+/** CLI 命令的 SPM C 位（B 位已通过 antlog CLI 注册；C 位发送后由采集平台自动归入 B 位） */
+const SPM_MAP = {
+    login: 'c480301',
+    whoami: 'c480302',
+    import: 'c480303',
+    pull: 'c480304',
+    'import-status': 'c480305',
+    'import-configure': 'c480306',
+    create: 'c480307',
+    deploy: 'c480308',
+    'release-status': 'c480309',
+    'release-list': 'c480310',
+    'app-list': 'c480311',
+    'app-info': 'c480312',
+    'app-use': 'c480313',
+    'app-current': 'c480314',
+    'app-unlink': 'c480315',
+    'app-update': 'c480316',
+    'app-delete': 'c480317',
+    'app-create': 'c480318',
+    'chat-send': 'c480319',
+    'chat-resume': 'c480320',
+    'chat-state': 'c480321',
+    'chat-history': 'c480322',
+    'chat-cancel': 'c480323',
+    'chat-clear': 'c480324',
+    'sandbox-status': 'c480330',
+    'sandbox-logs': 'c480331',
+    'sandbox-restart': 'c480332',
+    'sandbox-health': 'c480333',
+    'secret-list': 'c480340',
+    'secret-delete': 'c480341',
+    'secret-enable': 'c480342',
+    'secret-disable': 'c480343',
+    'secret-sync-retry': 'c480344',
+    'secret-sync-status': 'c480345',
+    'db-tables': 'c480350',
+    'db-records': 'c480351',
+    'db-permission': 'c480352',
+    'fn-list': 'c480353',
+    'fn-info': 'c480354',
+    'fn-retry': 'c480355',
+    'model-list': 'c480360',
+    'info': 'c480370',
+    'account': 'c480371',
+    'upgrade': 'c480380',
+    'agent-skill-install': 'c480390',
+    'agent-skill-status': 'c480391',
+    'cloud-enable': 'c480392',
+    'cloud-status': 'c480393',
+    'cloud-retry': 'c480394',
+    'cloud-pull-env': 'c480395',
+    dev: 'c480396',
+};
+const CLIENT_ID = randomUUID();
+const BIZ_TYPE = 'qmuse';
+let cachedUserId = null;
+/** 从 CLI 会话获取 userId（fire-and-forget；拿不到用空串，采集平台会丢这条但主流程不受影响） */
+async function fetchUserId(cfg) {
+    if (cachedUserId !== null)
+        return cachedUserId;
+    try {
+        const { whoami } = await import('./api.js');
+        const r = await whoami(cfg);
+        cachedUserId = r.data?.userId?.trim() || '';
+    }
+    catch {
+        cachedUserId = '';
+    }
+    return cachedUserId;
+}
+/** 发送 dwcookie 埋点（fire-and-forget，绝不抛出） */
+export function trackCommand(command, cfg) {
+    const spmC = SPM_MAP[command];
+    if (!spmC)
+        return;
+    const spm = `${SPM_A}.${SPM_B}.${spmC}`;
+    const sessionId = `${CLIENT_ID}_${Date.now()}`;
+    void fetchUserId(cfg)
+        .catch(() => '')
+        .then(userId => {
+        const fields = [
+            'DW-COOKIE',
+            sessionId,
+            userId,
+            'clicked',
+            spm,
+            '', '', '', '', '',
+            '', '', '', '',
+            '', '', '', '', '',
+            '', '', '', '',
+        ];
+        // 字段 17 是 bizType
+        fields[17] = BIZ_TYPE;
+        // 字段 20-22 是屏幕参数，CLI 场景填 terminal
+        fields[20] = 'terminal';
+        fields[21] = 'terminal';
+        fields[22] = '1';
+        const data = fields.join(',');
+        const body = `data=${encodeURIComponent(data)}`;
+        void fetch(COLLECT_URL, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/x-www-form-urlencoded',
+                referer: `${QMUSE_WEB_ORIGIN}/`,
+            },
+            body,
+            signal: AbortSignal.timeout(5000),
+        }).catch(() => {
+            /* 采集失败不影响业务 */
+        });
+    });
+}