kld-sdd 2.6.17 → 2.7.3

package/skywalk-sdd/lib/usage-contract.cjs

@@ -0,0 +1,207 @@
+// kld-T01 — CLI 使用统计上报契约
+// 集中定义：七值 skill 枚举、ApiResponse 解包、内置默认上报地址、
+// Node 14 兼容的 URL/HTTP 基础函数。与 kb-sdd 跨仓契约保持一致。
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+
+/**
+ * 内置默认上报地址：四级 server 解析的最后一级兜底。
+ */
+const DEFAULT_SERVER_URL = 'http://10.29.213.80:8080';
+
+/**
+ * 七值使用统计 skill 枚举。
+ * test / explore 不属于统计范围，永不映射。
+ */
+const USAGE_SKILLS = Object.freeze([
+  'propose',
+  'spec',
+  'design',
+  'task',
+  'check',
+  'apply',
+  'archive',
+]);
+
+const USAGE_SKILL_SET = new Set(USAGE_SKILLS);
+
+/**
+ * 将 opsx 命令映射到使用统计 skill。
+ * @param {string} command
+ * @returns {string|null} 七值之一；非七值返回 null
+ */
+function mapCommandToUsageSkill(command) {
+  if (typeof command !== 'string' || !command) return null;
+  return USAGE_SKILL_SET.has(command) ? command : null;
+}
+
+/**
+ * 规范化 server URL：只接受 http/https，去尾斜杠，去首尾空白。
+ * @param {string} raw
+ * @returns {string|null} 规范化后的 base URL；非法返回 null
+ */
+function normalizeServerUrl(raw) {
+  if (typeof raw !== 'string') return null;
+  const trimmed = raw.trim();
+  if (!trimmed) return null;
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    return null;
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return null;
+  // 重组：protocol + // + host + pathname（去尾斜杠），忽略 search/hash
+  const path = parsed.pathname.replace(/\/+$/, '');
+  return `${parsed.protocol}//${parsed.host}${path}`;
+}
+
+/**
+ * 解开 ApiResponse 信封：{ code, message, data } → data；code 非 0 抛错。
+ * @param {object} body — 已 JSON.parse 的响应体
+ * @returns {*} data 字段内容
+ * @throws {Error} code 非 0、非对象、缺 code 字段
+ */
+function unwrapApiResponse(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    throw new Error('ApiResponse must be an object');
+  }
+  if (typeof body.code !== 'number') {
+    throw new Error('ApiResponse missing numeric code');
+  }
+  if (body.code !== 0) {
+    const msg = typeof body.message === 'string' && body.message
+      ? body.message
+      : `server error code ${body.code}`;
+    throw new Error(msg);
+  }
+  return body.data === undefined ? null : body.data;
+}
+
+/**
+ * 分类 usage 上报响应。
+ * - confirmed: 2xx/204，服务端已确认，可从 pending 队列移除
+ * - retry: 网络错误 / 429 / 5xx / timeout；保留在 pending 队列
+ * - drop: 其他 4xx（含 401）；不再重试但不上抛，也不清除任何本地状态
+ *
+ * @param {number|null} statusCode
+ * @returns {'confirmed'|'retry'|'drop'}
+ */
+function classifyUsageSubmitResponse(statusCode) {
+  if (statusCode == null || statusCode === 0) return 'retry';
+  if (statusCode >= 200 && statusCode < 300) return 'confirmed';
+  if (statusCode === 429) return 'retry';
+  if (statusCode >= 500) return 'retry';
+  return 'drop';
+}
+
+/**
+ * Node 14 兼容的 POST JSON 实现。
+ * - 仅用核心 http/https，不依赖全局 fetch
+ * - 任何网络/解析错误均不抛，返回 statusCode=null 让调用方分类
+ * - 4xx/5xx 不抛错，返回 statusCode + body 供分类
+ *
+ * @param {string} url — 完整 URL（必须 http/https）
+ * @param {object} payload — 请求体（JSON 序列化）
+ * @param {{timeoutMs?:number,headers?:object}} [options]
+ * @returns {Promise<{statusCode:number|null,body:*,data:*,error:*}>}
+ *   statusCode: HTTP 状态码，网络错误为 null
+ *   body: 原始解析后的 JSON 对象（如可解析）
+ *   data: 若为 ApiResponse 信封且 code=0，则为解包后的 data；否则为 undefined
+ *   error: 仅在 statusCode=null 时携带 Error；否则为 null
+ */
+function postJson(url, payload, options = {}) {
+  return new Promise((resolve, reject) => {
+    let target;
+    try {
+      target = new URL(url);
+    } catch (err) {
+      reject(new Error(`invalid url: ${err.message}`));
+      return;
+    }
+    if (target.protocol !== 'http:' && target.protocol !== 'https:') {
+      reject(new Error(`only http/https supported, got ${target.protocol}`));
+      return;
+    }
+    const transport = target.protocol === 'https:' ? https : http;
+    const timeoutMs = Number.isFinite(options && options.timeoutMs) && options.timeoutMs > 0
+      ? Math.floor(options.timeoutMs)
+      : 30000;
+
+    let body;
+    try {
+      body = JSON.stringify(payload === undefined ? {} : payload);
+    } catch (err) {
+      reject(new Error(`payload serialization error: ${err.message}`));
+      return;
+    }
+
+    const headers = Object.assign(
+      {
+        Accept: 'application/json',
+        'Content-Type': 'application/json; charset=utf-8',
+        'Content-Length': Buffer.byteLength(body),
+      },
+      options && options.headers && typeof options.headers === 'object' ? options.headers : {},
+    );
+
+    const request = transport.request(
+      {
+        hostname: target.hostname,
+        port: target.port || (target.protocol === 'https:' ? 443 : 80),
+        path: target.pathname + target.search,
+        method: 'POST',
+        headers,
+        timeout: timeoutMs,
+      },
+      (response) => {
+        const chunks = [];
+        response.on('data', (chunk) => chunks.push(chunk));
+        response.on('end', () => {
+          const raw = Buffer.concat(chunks).toString('utf8');
+          let parsedBody = null;
+          if (raw) {
+            try {
+              parsedBody = JSON.parse(raw);
+            } catch {
+              parsedBody = null;
+            }
+          }
+          let data;
+          if (parsedBody && typeof parsedBody === 'object' && parsedBody.code === 0) {
+            try {
+              data = unwrapApiResponse(parsedBody);
+            } catch {
+              data = undefined;
+            }
+          }
+          resolve({
+            statusCode: response.statusCode == null ? null : response.statusCode,
+            body: parsedBody,
+            data,
+            error: null,
+          });
+        });
+      },
+    );
+    request.on('timeout', () => {
+      request.destroy(new Error(`request timeout after ${timeoutMs}ms`));
+    });
+    request.on('error', (err) => {
+      resolve({ statusCode: null, body: null, data: undefined, error: err });
+    });
+    request.end(body);
+  });
+}
+
+module.exports = {
+  USAGE_SKILLS,
+  mapCommandToUsageSkill,
+  normalizeServerUrl,
+  unwrapApiResponse,
+  classifyUsageSubmitResponse,
+  postJson,
+  DEFAULT_SERVER_URL,
+};

package/skywalk-sdd/lib/usage-reporter.cjs

@@ -0,0 +1,460 @@
+// kld-T04 — 使用事件 reporter（git 身份缓存化韧性版）
+// 职责：git 身份取自 ~/.kld-sdd/git-identity.json 持久缓存（git 仅由 git-identity.cjs
+//       后台刷新读取，慢 git 环境前台零调用）；无身份当前事件入 pending 队列不跳过，
+//       身份就绪后 flush 时注入身份补报；
+//       server 四级解析（config > kb-state.api > KLD_SDD_SERVER > 内置默认）；
+//       单一 3s deadline；pending JSONL 原子追加；100 条上限；1MB 淘汰；
+//       HTTP 状态分类（confirmed/retry/drop，401 归入 drop 不清任何本地状态）；
+//       并发安全（appendFileSync O_APPEND + 事件 id 差集提交）；不改原业务退出码。
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const {
+  normalizeServerUrl,
+  classifyUsageSubmitResponse,
+  postJson,
+  mapCommandToUsageSkill,
+  DEFAULT_SERVER_URL,
+} = require('./usage-contract.cjs');
+const {
+  readUserConfig,
+} = require('./user-config.cjs');
+const gitIdentity = require('./git-identity.cjs');
+
+const PENDING_FILE_NAME = 'pending-usage.jsonl';
+const PENDING_MAX_BYTES = 1024 * 1024; // 1 MB
+const FLUSH_MAX_COUNT = 100;
+const SHARED_DEADLINE_MS = 3000;
+// 单行事件 JSON 的安全上限（小于 4KB 以保证 appendFileSync 在 POSIX/Windows 都原子）
+const SINGLE_EVENT_MAX_BYTES = 4096;
+
+function pendingPathFor(homeDir) {
+  const envHome = typeof process !== 'undefined' && process && process.env
+    ? process.env.KLD_SDD_HOME
+    : undefined;
+  const home = homeDir || envHome || require('node:os').homedir();
+  return path.join(home, '.kld-sdd', PENDING_FILE_NAME);
+}
+
+// git 身份进程内缓存：仅缓存成功读取；失败不缓存，下次重试
+let gitIdentityCache = null;
+
+/**
+ * 读取本机 git 身份。
+ * - 来源：~/.kld-sdd/git-identity.json 持久缓存（git-identity.cjs 维护，
+ *   git 仅由 detached 后台刷新进程读取——慢 git 环境（7-34s 启动）前台零调用）
+ * - 进程内缓存：首次成功后复用；失败不缓存
+ * - 无缓存 / 缓存缺字段 / tombstone → 返回 null（调用方将当前事件入队待补报，
+ *   并已由 ensureIdentity 触发一次后台刷新）
+ *
+ * @param {string} [homeDir] — 测试注入 home；缺省走 KLD_SDD_HOME/os.homedir
+ * @returns {{userName:string, email:string}|null}
+ */
+function readGitIdentity(homeDir) {
+  if (gitIdentityCache) return gitIdentityCache;
+  const identity = gitIdentity.ensureIdentity({ homeDir });
+  if (!identity) return null;
+  gitIdentityCache = identity;
+  return gitIdentityCache;
+}
+
+/**
+ * 测试专用：重置进程内 git 身份缓存。
+ */
+function _resetGitIdentityCache() {
+  gitIdentityCache = null;
+}
+
+/**
+ * 四级解析上报地址：config.server → 项目 kb-state.json api → env KLD_SDD_SERVER → 内置默认。
+ * 每级均经 normalizeServerUrl；结果永远非空（默认地址兜底）。
+ *
+ * @param {{homeDir?:string, projectRoot?:string, env?:object}} [options]
+ * @returns {string}
+ */
+function resolveReportServer(options = {}) {
+  const env = options.env || process.env;
+  const projectRoot = options.projectRoot || process.cwd();
+  // 1. 用户级 config.server
+  const config = readUserConfig(options.homeDir);
+  if (config && typeof config.server === 'string') {
+    const normalized = normalizeServerUrl(config.server);
+    if (normalized) return normalized;
+  }
+  // 2. 项目级 kb-state.json 的 api
+  try {
+    const kbStatePath = path.join(projectRoot, 'kb-state.json');
+    if (fs.existsSync(kbStatePath)) {
+      const kbState = JSON.parse(fs.readFileSync(kbStatePath, 'utf8'));
+      if (kbState && typeof kbState.api === 'string') {
+        const normalized = normalizeServerUrl(kbState.api);
+        if (normalized) return normalized;
+      }
+    }
+  } catch {
+    // kb-state 读取失败时静默，继续下一级
+  }
+  // 3. env KLD_SDD_SERVER
+  if (env && typeof env.KLD_SDD_SERVER === 'string') {
+    const normalized = normalizeServerUrl(env.KLD_SDD_SERVER);
+    if (normalized) return normalized;
+  }
+  // 4. 内置默认地址兜底
+  return normalizeServerUrl(DEFAULT_SERVER_URL);
+}
+
+/**
+ * 生成事件唯一 id（基于时间戳 + pid + 随机字节）。
+ * 用于 flush 提交时按 id 差集删除已确认行，避免 read-modify-write 覆盖并发 append。
+ */
+function generateEventId() {
+  return `ue_${Date.now().toString(36)}_${process.pid.toString(36)}_${crypto.randomBytes(4).toString('hex')}`;
+}
+
+/**
+ * 为没有 id 字段的旧事件规范化一个 id（基于内容 hash）。
+ * 同一行多次读出会得到同一个 id，使 flush 差集提交对旧 fixture 兼容。
+ */
+function ensureEventId(event) {
+  if (event && typeof event === 'object') {
+    if (typeof event.id === 'string' && event.id) return event;
+    const hash = crypto
+      .createHash('sha1')
+      .update(JSON.stringify(event))
+      .digest('hex')
+      .slice(0, 12);
+    return Object.assign({}, event, { id: `legacy_${hash}` });
+  }
+  return event;
+}
+
+/**
+ * 读取 pending 队列。
+ * - 尾部半行 / 损坏行被隔离：跳过但不污染合法记录
+ * - 没有 id 的旧事件会被规范化一个内容 hash id
+ * - 返回 { events, corrupted }
+ */
+function readPending(filePath) {
+  if (!fs.existsSync(filePath)) return { events: [], corrupted: 0 };
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { events: [], corrupted: 0 };
+  }
+  if (!raw) return { events: [], corrupted: 0 };
+  const lines = raw.split('\n');
+  const events = [];
+  let corrupted = 0;
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const parsed = JSON.parse(trimmed);
+      if (parsed && typeof parsed === 'object' && typeof parsed.skill === 'string') {
+        events.push(ensureEventId(parsed));
+      } else {
+        corrupted += 1;
+      }
+    } catch {
+      corrupted += 1;
+    }
+  }
+  return { events, corrupted };
+}
+
+/**
+ * 原子重写 pending 文件：先 temp 后 rename。
+ * 仅在 flush 提交时调用；并发 append 的新行必须在重写前重新读入并按 id 保留。
+ */
+function writePendingAtomic(filePath, events) {
+  const dir = path.dirname(filePath);
+  fs.mkdirSync(dir, { recursive: true });
+  if (!events || events.length === 0) {
+    try { fs.unlinkSync(filePath); } catch { /* ignore */ }
+    return;
+  }
+  const tmp = path.join(dir, `.${path.basename(filePath)}.${process.pid}.${Date.now()}.tmp`);
+  const payload = events.map((e) => JSON.stringify(e)).join('\n') + '\n';
+  fs.writeFileSync(tmp, payload, 'utf8');
+  try {
+    fs.renameSync(tmp, filePath);
+  } catch (err) {
+    try { fs.unlinkSync(tmp); } catch { /* ignore */ }
+    throw err;
+  }
+}
+
+/**
+ * 追加事件到 pending 队列。
+ * - 用 fs.appendFileSync 单行追加：POSIX O_APPEND 对小行原子；Windows 对 <4KB append 也原子
+ * - 超 1MB 时先重读并按需淘汰最旧完整行（O(n)：先算总大小，每次 shift 只减对应字节）
+ * - 事件自动补 id（如未含）
+ */
+function appendPending(event, filePath) {
+  if (!event || typeof event !== 'object') return;
+  const target = filePath || pendingPathFor();
+  const dir = path.dirname(target);
+  fs.mkdirSync(dir, { recursive: true });
+
+  // 自动补 id（用于 flush 差集删除）
+  const toAppend = Object.assign({}, event);
+  if (typeof toAppend.id !== 'string' || !toAppend.id) {
+    toAppend.id = generateEventId();
+  }
+  const line = JSON.stringify(toAppend) + '\n';
+  const lineBytes = Buffer.byteLength(line, 'utf8');
+  if (lineBytes > SINGLE_EVENT_MAX_BYTES) {
+    // 防御：单行超 4KB 直接丢弃（不应发生；正常事件 <200 字节）
+    return;
+  }
+
+  // 先检查追加后是否超 1MB；超则先淘汰
+  let existingSize = 0;
+  let existingEvents = [];
+  if (fs.existsSync(target)) {
+    const { events } = readPending(target);
+    existingEvents = events;
+    for (const e of events) {
+      existingSize += Buffer.byteLength(JSON.stringify(e), 'utf8') + 1;
+    }
+  }
+  if (existingSize + lineBytes > PENDING_MAX_BYTES) {
+    // O(n) 淘汰：先算总大小，每次 shift 只减对应字节
+    let currentSize = existingSize;
+    let dropCount = 0;
+    while (dropCount < existingEvents.length && currentSize + lineBytes > PENDING_MAX_BYTES) {
+      const evicted = existingEvents[dropCount];
+      currentSize -= (Buffer.byteLength(JSON.stringify(evicted), 'utf8') + 1);
+      dropCount += 1;
+    }
+    if (dropCount > 0) {
+      const retained = existingEvents.slice(dropCount);
+      // 原子重写（淘汰后才需要 rewrite；此后 append 当前行）
+      writePendingAtomic(target, retained);
+    }
+  }
+  // 原子 append（POSIX O_APPEND；Windows 单行 <4KB 也原子）
+  try {
+    fs.appendFileSync(target, line, 'utf8');
+  } catch {
+    // append 失败时静默（不改原业务退出码）
+  }
+}
+
+/**
+ * 提交单条事件；发送前注入 git 身份；返回分类。
+ * @returns {Promise<'confirmed'|'retry'|'drop'>}
+ */
+async function submitOne(server, identity, event, timeoutMs) {
+  // 提交时剔除内部 id（不上传给服务端），统一注入当前 git 身份
+  // （兼容 pending 队列里无身份字段的遗留事件）
+  const outgoing = Object.assign({}, event, {
+    userName: identity.userName,
+    email: identity.email,
+  });
+  delete outgoing.id;
+  const result = await postJson(
+    `${server}/api/v1/usage-events`,
+    outgoing,
+    { timeoutMs },
+  );
+  return classifyUsageSubmitResponse(result.statusCode);
+}
+
+/**
+ * 共享冲刷执行体：读 pending → 逐条提交 → 按 id 差集原子提交队列变化。
+ * reportUsageOnce（冲刷后发当前事件）与 flushPendingUsage（只冲刷）共用。
+ *
+ * @returns {Promise<{submitted:number, confirmedIds:Set, droppedIds:Set}>}
+ */
+async function flushPendingQueue(server, identity, pendingFile, deadlineStart) {
+  const deadline = deadlineStart || (Date.now() + SHARED_DEADLINE_MS);
+  const confirmedIds = new Set();   // 已成功的事件 id
+  const droppedIds = new Set();     // 4xx 永久失败的事件 id
+  let submitted = 0;
+
+  const { events: pendingEvents } = readPending(pendingFile);
+  let flushed = 0;
+  for (let i = 0; i < pendingEvents.length; i++) {
+    const ev = pendingEvents[i];
+    const remaining = deadline - Date.now();
+    if (flushed >= FLUSH_MAX_COUNT || remaining <= 0) break;
+
+    const timeoutMs = Math.max(50, remaining);
+    let classification;
+    try {
+      classification = await submitOne(server, identity, ev, timeoutMs);
+    } catch {
+      classification = 'retry';
+    }
+
+    if (classification === 'confirmed') {
+      flushed += 1;
+      submitted += 1;
+      if (ev.id) confirmedIds.add(ev.id);
+      continue;
+    }
+    if (classification === 'drop') {
+      // drop 丢弃该条（含 401），不 retained、不 break，继续下一条
+      if (ev.id) droppedIds.add(ev.id);
+      continue;
+    }
+    // retry：网络/5xx/429/timeout，本次及后续保留
+    break;
+  }
+
+  // 原子提交队列变化（按 id 差集删除已确认 + 已丢弃）
+  // 关键：rewrite 前必须重新读文件，把并发 append 的新行合并进来
+  if (confirmedIds.size > 0 || droppedIds.size > 0) {
+    const { events: latestEvents } = readPending(pendingFile);
+    const retained = latestEvents.filter((e) => {
+      if (e.id && confirmedIds.has(e.id)) return false;
+      if (e.id && droppedIds.has(e.id)) return false;
+      return true;
+    });
+    writePendingAtomic(pendingFile, retained);
+  }
+
+  return { submitted, confirmedIds, droppedIds };
+}
+
+/**
+ * 只冲刷 pending 队列，不产生新事件（cmdEnd / git 身份就绪后的补报入口）。
+ * 无身份返回 skipped 零请求；任何失败均不抛。
+ *
+ * @param {object} [options]
+ * @param {string} [options.homeDir] — 测试注入
+ * @param {string} [options.projectRoot] — kb-state.json 查找目录，缺省 process.cwd()
+ * @returns {Promise<{submitted:number,enqueued:boolean,skipped:boolean}>}
+ */
+async function flushPendingUsage(options = {}) {
+  const result = { submitted: 0, enqueued: false, skipped: false };
+  try {
+    const identity = readGitIdentity(options.homeDir);
+    if (!identity) {
+      result.skipped = true;
+      return result;
+    }
+    const pendingFile = pendingPathFor(options.homeDir);
+    const { events: pendingEvents } = readPending(pendingFile);
+    if (pendingEvents.length === 0) return result;
+    const server = resolveReportServer({ homeDir: options.homeDir, projectRoot: options.projectRoot });
+    const flushed = await flushPendingQueue(server, identity, pendingFile);
+    result.submitted = flushed.submitted;
+    return result;
+  } catch {
+    // 兜底：永不抛到调用方
+    return result;
+  }
+}
+
+/**
+ * 上报一次使用事件（主入口）。任何失败均不抛。
+ *
+ * @param {object} options
+ * @param {string} options.skill — 七值之一；非七值立即返回
+ * @param {string} [options.startedAt] — ISO8601；缺省取当前
+ * @param {string} [options.homeDir] — 测试注入
+ * @param {string} [options.projectRoot] — kb-state.json 查找目录，缺省 process.cwd()
+ * @returns {Promise<{submitted:number,enqueued:boolean,skipped:boolean}>}
+ */
+async function reportUsageOnce(options = {}) {
+  const result = { submitted: 0, enqueued: false, skipped: false };
+  const skill = mapCommandToUsageSkill(options.skill);
+  if (!skill) {
+    result.skipped = true;
+    return result;
+  }
+
+  const startedAt = typeof options.startedAt === 'string' && options.startedAt
+    ? options.startedAt
+    : new Date().toISOString();
+  const currentEvent = { skill, startedAt, id: generateEventId() };
+  const pendingFile = pendingPathFor(options.homeDir);
+
+  try {
+    // 无 git 身份：当前事件入队（无身份字段，与遗留事件同构），本次冲刷整体跳过、
+    // 队列原有内容保留；身份就绪后由后续 flush 注入身份补报（慢 git 环境不静默丢失）。
+    const identity = readGitIdentity(options.homeDir);
+    if (!identity) {
+      try {
+        appendPending(currentEvent, pendingFile);
+        result.enqueued = true;
+      } catch { /* append 失败静默，不改退出码 */ }
+      return result;
+    }
+    const server = resolveReportServer({ homeDir: options.homeDir, projectRoot: options.projectRoot });
+
+    const MAX_TIMEOUT_SKEW_MS = 500; // 调度容差
+    // 共享 3s deadline：冲刷与当前事件共用同一预算
+    const deadline = Date.now() + SHARED_DEADLINE_MS;
+
+    // 1. 先冲刷 pending（最多 100 条；retry 提前终止时剩余保留）
+    const flushOutcome = await flushPendingQueue(server, identity, pendingFile, deadline);
+    result.submitted += flushOutcome.submitted;
+    // 冲刷提前失败判定：零提交、零 drop，且队列仍有残留（retry 语义）
+    const failedEarly = flushOutcome.submitted === 0
+      && flushOutcome.confirmedIds.size === 0
+      && flushOutcome.droppedIds.size === 0
+      && readPending(pendingFile).events.length > 0;
+
+    // 2. 发当前事件（若仍有预算且未提前失败）
+    // flush 提前失败时当前事件必须入队，不得静默丢弃。
+    let currentOutcome = 'pending'; // 'confirmed' | 'enqueued' | 'dropped' | 'pending'
+    if (failedEarly) {
+      currentOutcome = 'enqueued';
+    } else {
+      const remaining = deadline - Date.now();
+      if (remaining > MAX_TIMEOUT_SKEW_MS) {
+        let classification;
+        try {
+          classification = await submitOne(server, identity, currentEvent, remaining);
+        } catch {
+          classification = 'retry';
+        }
+        if (classification === 'confirmed') {
+          result.submitted += 1;
+          currentOutcome = 'confirmed';
+        } else if (classification === 'drop') {
+          // 当前事件 drop（含 401）直接丢弃不入队，不清任何本地状态
+          currentOutcome = 'dropped';
+        } else {
+          currentOutcome = 'enqueued';
+        }
+      } else {
+        currentOutcome = 'enqueued';
+      }
+    }
+
+    // 3. append 当前事件（若需要）
+    try {
+      if (currentOutcome === 'enqueued') {
+        appendPending(currentEvent, pendingFile);
+        result.enqueued = true;
+      }
+    } catch { /* ignore */ }
+
+    return result;
+  } catch {
+    // 兜底：永不抛到调用方
+    return result;
+  }
+}
+
+module.exports = {
+  reportUsageOnce,
+  flushPendingUsage,
+  appendPending,
+  readPending,
+  readGitIdentity,
+  resolveReportServer,
+  _resetGitIdentityCache,
+  PENDING_FILE_NAME,
+  PENDING_MAX_BYTES,
+  FLUSH_MAX_COUNT,
+  SHARED_DEADLINE_MS,
+};