@gong-ym/ai-spec-auto 0.2.3

package/bin/telemetry/README.md

@@ -0,0 +1,66 @@
+# bin/telemetry
+
+可选的匿名遥测切面（aspect），用于向 `br-ai-spec-visual` 上报 CLI 安装与使用情况。
+
+## 设计原则
+
+- **零侵入**：主流程 (`bin/cli.js`、`bin/install-workflow.js` 等) 不依赖本目录。删除整个 `bin/telemetry/` 目录后 CLI 仍可正常工作。
+- **降级四重保护**：
+  1. `bin/cli.js` 中 `require('./telemetry')` 失败 → 使用透明 wrap，不上报。
+  2. `index.js` 再次 try/catch 保护，阻止任何异常冒泡。
+  3. **健康探测兜底**：上报前先 `HEAD /api/health`（500ms 超时），目标不可达直接跳过本次所有上报；探测失败时间记入本地缓存，60 秒冷却窗口内的后续 CLI 调用直接跳过探测。
+  4. 网络上报 fire-and-forget + `AbortController(2000ms)`，绝不阻塞 `process.exit`。
+- **可选依赖**：`node-machine-id` 放在 `optionalDependencies`，缺失时用纯 Node `os` 模块 + `sha256` 兜底。
+- **用户可关闭**：`AI_SPEC_TELEMETRY_DISABLED=1` 禁用；`AI_SPEC_VISUAL_URL` 未设置时不发网络请求。
+
+## 文件
+
+| 文件 | 作用 |
+| --- | --- |
+| `index.js` | 对外唯一入口，导出 `wrap(command, fn)`。 |
+| `aspect.js` | 切面实现：在命令前后异步上报 started / success / failed。 |
+| `reporter.js` | REST / WS 上报；AbortController + 超时 + 静默失败。 |
+| `identity.js` | 生成 installationId（node-machine-id → sha256(mac+user+host) 兜底）。 |
+| `collect.js` | 收集非敏感字段（hostname/platform/node/cliVersion/projectHash/profile…）。 |
+| `config.js` | 读取环境变量 + 用户配置 + 仓库默认，三层合并。 |
+| `defaults.json` | 仓库内默认配置（仅 `visualUrl` / `disabled`，**禁止写入 secret**）。 |
+| `healthcheck.js` | 发送前探测 `HEAD /api/health`（500ms 超时，进程内缓存，失败 60s 冷却）。 |
+| `safe.js` | 统一兜底工具 (safeCall, safeRequire)。 |
+
+## 配置来源（优先级由高到低）
+
+1. **环境变量**（临时调试、CI 注入首选）
+2. **`~/.ai-spec-auto/config.json`**（用户主目录，个人本地覆盖，可存 secret）
+3. **`bin/telemetry/defaults.json`**（仓库默认，跟随 npm 包发布；**仅放公开字段**）
+
+### 可配置字段
+
+| 字段 | 环境变量 | 用户配置 key | 仓库默认 | 说明 |
+| --- | --- | --- | --- | --- |
+| Visual 地址 | `AI_SPEC_VISUAL_URL` | `visualUrl` | `visualUrl` | 未设置/为空则不发请求 |
+| 总开关 | `AI_SPEC_TELEMETRY_DISABLED=1` | `disabled: true` | `disabled` | 任一源为 true 即关闭 |
+| 鉴权密钥 | `AI_SPEC_TELEMETRY_SECRET` | `secret` | **不支持** | 与服务端 `.env` 一致；仓库绝不写入 |
+| 调试输出 | `AI_SPEC_TELEMETRY_DEBUG=1` | — | — | 仅环境变量，便于排查 |
+
+### 用户配置示例
+
+```jsonc
+// ~/.ai-spec-auto/config.json
+{
+  "visualUrl": "http://127.0.0.1:3000",   // 本地联调时覆盖为本机
+  "secret": "与服务端 .env 中的 AI_SPEC_TELEMETRY_SECRET 一致",
+  "disabled": false
+}
+```
+
+- 文件不存在或格式错误 → 静默回退到仓库默认，不影响 CLI。
+- 权限建议：`chmod 600 ~/.ai-spec-auto/config.json`（含 secret 时）。
+
+### 典型场景
+
+| 场景 | 做法 |
+| --- | --- |
+| 使用线上 Visual（`82.156.14.216:3001`），无 secret | **什么都不用设**，装包即走仓库默认 |
+| 使用线上 Visual + 需要 secret | 在 `~/.ai-spec-auto/config.json` 写入 `secret`，或导出 `AI_SPEC_TELEMETRY_SECRET` |
+| 本地联调，想打到本机 Visual | `export AI_SPEC_VISUAL_URL=http://127.0.0.1:3000`（或写入用户配置） |
+| 不想参与匿名统计 | `export AI_SPEC_TELEMETRY_DISABLED=1`（或用户配置 `disabled: true`） |

package/bin/telemetry/aspect.js

@@ -0,0 +1,153 @@
+'use strict';
+
+const path = require('path');
+const { collectCommon } = require('./collect');
+const { getConfig, markNoticeShown } = require('./config');
+const { resolveInstallationId } = require('./identity');
+const { fireAndForget } = require('./reporter');
+const { debugLog, safeCall, safeRequire } = require('./safe');
+
+const healthcheck = safeRequire('./healthcheck');
+
+const PKG_ROOT = path.join(__dirname, '..', '..');
+
+function maybePrintFirstNotice(config) {
+  if (!config.enabled) return;
+  safeCall(function () {
+    if (markNoticeShown()) {
+      process.stderr.write(
+        '[ai-spec-auto] 已开启匿名使用统计（可通过 AI_SPEC_TELEMETRY_DISABLED=1 关闭）\n',
+      );
+    }
+  });
+}
+
+function buildPayload(command, status, extra) {
+  const base = collectCommon({ cwd: process.cwd(), pkgRoot: PKG_ROOT });
+  const payload = {
+    installationId: resolveInstallationId(),
+    command: String(command || 'unknown').slice(0, 64),
+    status: String(status).slice(0, 32),
+    hostname: base.hostname,
+    username: base.username,
+    platform: base.platform,
+    arch: base.arch,
+    osRelease: base.osRelease,
+    nodeVersion: base.nodeVersion,
+    cliVersion: base.cliVersion,
+    profile: base.profile,
+    ides: base.ides,
+    level: base.level,
+    projectHash: base.projectHash,
+    projectName: base.projectName,
+    occurredAt: new Date().toISOString(),
+  };
+  if (extra && typeof extra === 'object') {
+    if (typeof extra.durationMs === 'number') payload.durationMs = extra.durationMs;
+    if (typeof extra.errorMessage === 'string') {
+      payload.errorMessage = extra.errorMessage.slice(0, 2000);
+    }
+  }
+  return payload;
+}
+
+function wrap(command, fn) {
+  if (typeof fn !== 'function') {
+    throw new TypeError('telemetry.wrap: fn must be a function');
+  }
+  const config = getConfig();
+  if (!config.enabled) {
+    debugLog('wrap: telemetry disabled, pass-through');
+    return fn();
+  }
+
+  safeCall(function () {
+    maybePrintFirstNotice(config);
+  });
+
+  // 预热健康探测（不 await，结果会被 reporter 里的 ensureReachable 复用）。
+  // 这样 reporter 发 POST 前的健康查询要么已完成、要么已在进行中。
+  safeCall(function () {
+    if (healthcheck && typeof healthcheck.ensureReachable === 'function') {
+      const p = healthcheck.ensureReachable(config.visualUrl);
+      if (p && typeof p.catch === 'function') p.catch(function () {});
+    }
+  });
+
+  const pending = [];
+  function track(p) {
+    if (p && typeof p.then === 'function') pending.push(p);
+  }
+  function flushPending() {
+    if (pending.length === 0) return Promise.resolve();
+    const all = Promise.allSettled(pending.splice(0, pending.length));
+    // 上限 1500ms：覆盖 HEAD 健康探测（最多 500ms）+ POST 落地（一般 <500ms）
+    // 的组合路径，同时保证即使网络故障也不会明显拖慢 CLI 退出。
+    const env = process.env || {};
+    const raw = env.AI_SPEC_TELEMETRY_FLUSH_MS;
+    const parsed = raw ? parseInt(raw, 10) : NaN;
+    const cap = Number.isFinite(parsed) && parsed >= 100 && parsed <= 5000 ? parsed : 1500;
+    return Promise.race([
+      all,
+      new Promise(function (resolve) {
+        const t = setTimeout(resolve, cap);
+        if (typeof t.unref === 'function') t.unref();
+      }),
+    ]);
+  }
+
+  safeCall(function () {
+    track(fireAndForget(buildPayload(command, 'started')));
+  });
+
+  const startedAt = Date.now();
+  let result;
+  try {
+    result = fn();
+  } catch (error) {
+    safeCall(function () {
+      track(fireAndForget(
+        buildPayload(command, 'failed', {
+          durationMs: Date.now() - startedAt,
+          errorMessage: error && error.message ? String(error.message) : String(error),
+        }),
+      ));
+    });
+    return flushPending().then(function () { throw error; });
+  }
+
+  if (result && typeof result.then === 'function') {
+    return result.then(
+      function (value) {
+        safeCall(function () {
+          track(fireAndForget(
+            buildPayload(command, 'success', {
+              durationMs: Date.now() - startedAt,
+            }),
+          ));
+        });
+        return flushPending().then(function () { return value; });
+      },
+      function (error) {
+        safeCall(function () {
+          track(fireAndForget(
+            buildPayload(command, 'failed', {
+              durationMs: Date.now() - startedAt,
+              errorMessage: error && error.message ? String(error.message) : String(error),
+            }),
+          ));
+        });
+        return flushPending().then(function () { throw error; });
+      },
+    );
+  }
+
+  safeCall(function () {
+    track(fireAndForget(
+      buildPayload(command, 'success', { durationMs: Date.now() - startedAt }),
+    ));
+  });
+  return flushPending().then(function () { return result; });
+}
+
+module.exports = { wrap };

package/bin/telemetry/collect.js

@@ -0,0 +1,67 @@
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { safeCall } = require('./safe');
+
+function readJson(file) {
+  return safeCall(function () {
+    const raw = fs.readFileSync(file, 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : null;
+  }, null);
+}
+
+function readCliVersion(pkgRoot) {
+  if (!pkgRoot) return null;
+  const pkg = readJson(path.join(pkgRoot, 'package.json'));
+  return pkg && typeof pkg.version === 'string' ? pkg.version : null;
+}
+
+function readProjectMeta(cwd) {
+  if (!cwd || typeof cwd !== 'string') {
+    return { projectHash: null, projectName: null };
+  }
+  const hash = crypto.createHash('sha256').update(cwd).digest('hex').slice(0, 32);
+  const pkg = readJson(path.join(cwd, 'package.json'));
+  const name = pkg && typeof pkg.name === 'string' ? pkg.name.slice(0, 200) : null;
+  return { projectHash: hash, projectName: name };
+}
+
+function readInstallState(cwd) {
+  if (!cwd) return null;
+  return readJson(path.join(cwd, '.ai-spec', 'install-state.json'));
+}
+
+function pickString(value) {
+  return typeof value === 'string' ? value : null;
+}
+
+function collectCommon(options) {
+  const opts = options || {};
+  const cwd = opts.cwd || process.cwd();
+  const userInfo = safeCall(function () {
+    return os.userInfo();
+  }, {});
+  const state = readInstallState(cwd);
+  const project = readProjectMeta(cwd);
+
+  return {
+    hostname: safeCall(function () { return os.hostname(); }, null),
+    username: userInfo && userInfo.username ? String(userInfo.username).slice(0, 128) : null,
+    platform: safeCall(function () { return os.platform(); }, null),
+    arch: safeCall(function () { return os.arch(); }, null),
+    osRelease: safeCall(function () { return os.release(); }, null),
+    nodeVersion: process.version,
+    cliVersion: readCliVersion(opts.pkgRoot),
+    profile: state ? pickString(state.profile) : null,
+    ides: state && Array.isArray(state.ides) ? state.ides : null,
+    level: state ? pickString(state.level) : null,
+    projectHash: project.projectHash,
+    projectName: project.projectName,
+  };
+}
+
+module.exports = { collectCommon };

package/bin/telemetry/config.js

@@ -0,0 +1,114 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { safeCall } = require('./safe');
+
+// 仓库内默认配置（禁止含 secret）。加载失败时回退为空对象，不影响主流程。
+function loadRepoDefaults() {
+  return safeCall(function () {
+    const raw = fs.readFileSync(path.join(__dirname, 'defaults.json'), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  }, {});
+}
+
+function getUserConfigFile() {
+  return path.join(os.homedir(), '.ai-spec-auto', 'config.json');
+}
+
+// 用户主目录配置，允许存放 secret、URL 覆盖、总开关。失败时回退空对象。
+function loadUserConfig() {
+  return safeCall(function () {
+    const raw = fs.readFileSync(getUserConfigFile(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  }, {});
+}
+
+function pickString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function pickBool(value) {
+  if (value === true) return true;
+  if (typeof value === 'string') return value === '1' || value === 'true';
+  return false;
+}
+
+// 合并优先级（高 → 低）：环境变量 > ~/.ai-spec-auto/config.json > 仓库默认。
+function getConfig() {
+  const env = process.env || {};
+  const repo = loadRepoDefaults();
+  const user = loadUserConfig();
+
+  const envDisabled = pickBool(env.AI_SPEC_TELEMETRY_DISABLED);
+  const userDisabled = pickBool(user.disabled);
+  const repoDisabled = pickBool(repo.disabled);
+  const disabled = envDisabled || userDisabled || repoDisabled;
+
+  const url =
+    pickString(env.AI_SPEC_VISUAL_URL) ||
+    pickString(user.visualUrl) ||
+    pickString(repo.visualUrl);
+
+  // secret 仅从环境变量或用户主目录读取，绝不从仓库默认读取
+  const secret = pickString(env.AI_SPEC_TELEMETRY_SECRET) || pickString(user.secret);
+
+  return {
+    disabled,
+    visualUrl: url,
+    secret,
+    enabled: !disabled && url.length > 0,
+  };
+}
+
+function getCacheDir() {
+  return path.join(os.homedir(), '.ai-spec-auto');
+}
+
+function getCacheFile() {
+  return path.join(getCacheDir(), 'telemetry.json');
+}
+
+function ensureCacheDir() {
+  safeCall(function () {
+    fs.mkdirSync(getCacheDir(), { recursive: true });
+  });
+}
+
+function readCache() {
+  return safeCall(function () {
+    const raw = fs.readFileSync(getCacheFile(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? parsed : {};
+  }, {});
+}
+
+function writeCache(next) {
+  ensureCacheDir();
+  safeCall(function () {
+    fs.writeFileSync(getCacheFile(), JSON.stringify(next, null, 2), 'utf8');
+  });
+}
+
+function markNoticeShown() {
+  const cache = readCache();
+  if (!cache.noticeShown) {
+    cache.noticeShown = true;
+    cache.noticeShownAt = new Date().toISOString();
+    writeCache(cache);
+    return true;
+  }
+  return false;
+}
+
+module.exports = {
+  getConfig,
+  getCacheDir,
+  getCacheFile,
+  readCache,
+  writeCache,
+  markNoticeShown,
+};

package/bin/telemetry/defaults.json

@@ -0,0 +1,5 @@
+{
+  "$schema_comment": "CLI 匿名使用统计默认配置。开源默认关闭；仅 visualUrl 非空且 disabled 为 false 时启用。用户可通过 ~/.ai-spec-auto/config.json 或环境变量覆盖。禁止写入 secret。",
+  "visualUrl": "",
+  "disabled": true
+}

package/bin/telemetry/healthcheck.js

@@ -0,0 +1,195 @@
+'use strict';
+
+// Visual 健康探测兜底。
+// 目的：当目标不可达/配置错误/服务未部署时，避免每条事件都去等 2 秒超时，
+//      也避免在 Visual 日志里刷一堆无意义的失败上报。
+//
+// 设计约束：
+//   - 进程内单例（同一次 CLI 调用只探一次），不要多次网络往返
+//   - 先发 HEAD（默认 1500ms 超时）；若超时/网络错/405/5xx，再用 GET 重试一次
+//     （超时翻倍，最长到 DEFAULT_TIMEOUT_MS * 2）。原因：
+//       * Next.js dev 模式对 /api/health 首次访问会触发冷编译，500ms 远远不够；
+//       * 部分反向代理（nginx 无 `proxy_method HEAD` 等配置）不支持 HEAD。
+//   - 任何异常都必须被吞掉；探测模块本身绝不能让主流程挂掉
+//   - 本地缓存（~/.ai-spec-auto/telemetry.json）里记录"最近一次失败时间"，
+//     下次 CLI 启动时若距失败不足 N 秒则直接跳过探测，进一步降低噪声
+
+const { debugLog } = require('./safe');
+const { readCache, writeCache } = require('./config');
+
+// 同一进程内的探测结果缓存（null=未探过，true/false=已探过的可用性）
+let probed = null;
+let probing = null; // 并发保护：多条事件同时 wrap 时，共享同一个探测 Promise
+
+// 跨进程短时间冷却：避免 CI 里连续多次 CLI 调用都去探已知宕机的服务
+const COOLDOWN_MS = 60 * 1000; // 失败后 60 秒内不再探测
+
+function buildHealthUrl(base) {
+  const trimmed = String(base || '').replace(/\/+$/, '');
+  return trimmed + '/api/health';
+}
+
+function shouldSkipByCooldown() {
+  try {
+    const cache = readCache();
+    if (!cache || !cache.lastHealthFailAt) return false;
+    const last = Date.parse(cache.lastHealthFailAt);
+    if (!Number.isFinite(last)) return false;
+    const elapsed = Date.now() - last;
+    return elapsed >= 0 && elapsed < COOLDOWN_MS;
+  } catch (_error) {
+    return false;
+  }
+}
+
+function recordFailure() {
+  try {
+    const cache = readCache() || {};
+    cache.lastHealthFailAt = new Date().toISOString();
+    writeCache(cache);
+  } catch (_error) {
+    /* ignore */
+  }
+}
+
+function recordSuccess() {
+  try {
+    const cache = readCache() || {};
+    if (cache.lastHealthFailAt) {
+      delete cache.lastHealthFailAt;
+      writeCache(cache);
+    }
+  } catch (_error) {
+    /* ignore */
+  }
+}
+
+// 默认 1500ms，单位毫秒。选这个值的原因：
+//   - 生产/容器内实际健康探测通常 <100ms，留一个 15 倍冗余仍很保守
+//   - Next.js dev 冷编译 /api/health 普遍 800~1200ms，500ms 会在 dev 场景
+//     命中率接近 0，1500ms 能覆盖 95% 以上首次冷启动
+//   - 上限仍由 AI_SPEC_TELEMETRY_HEALTH_TIMEOUT_MS 控制（最大 10s），
+//     CI / 远程部署可按需调大
+const DEFAULT_TIMEOUT_MS = 1500;
+const MIN_TIMEOUT_MS = 100;
+const MAX_TIMEOUT_MS = 10000;
+
+function getProbeTimeoutMs() {
+  const env = process.env || {};
+  const raw = env.AI_SPEC_TELEMETRY_HEALTH_TIMEOUT_MS;
+  const parsed = raw ? parseInt(raw, 10) : NaN;
+  if (Number.isFinite(parsed) && parsed >= MIN_TIMEOUT_MS && parsed <= MAX_TIMEOUT_MS) {
+    return parsed;
+  }
+  return DEFAULT_TIMEOUT_MS;
+}
+
+// 判定 HEAD 的结果是否"足以说明服务可达"。405 / 501 / 超时 / 网络错等都不算，
+// 需要继续用 GET 兜底再试一次。
+function isHeadConclusive(response) {
+  if (!response) return false;
+  // 2xx/3xx 及大多数 4xx 足以证明服务在线、有业务处理能力；
+  // 405/501 是"方法不被支持"，需要换方法再试一次。
+  if (response.status === 405 || response.status === 501) return false;
+  return response.status >= 200 && response.status < 500;
+}
+
+async function sendProbe(url, method, timeoutMs) {
+  const controller = typeof AbortController === 'function' ? new AbortController() : null;
+  const timer = controller
+    ? setTimeout(function () {
+        controller.abort();
+      }, timeoutMs)
+    : null;
+  if (timer && typeof timer.unref === 'function') timer.unref();
+
+  try {
+    debugLog('healthcheck:', method, url, 'timeoutMs=', timeoutMs);
+    const response = await fetch(url, {
+      method: method,
+      signal: controller ? controller.signal : undefined,
+    });
+    debugLog('healthcheck:', method, 'status=', response.status);
+    return { response: response, error: null };
+  } catch (error) {
+    debugLog(
+      'healthcheck:',
+      method,
+      'failed',
+      error && error.message ? error.message : error,
+    );
+    return { response: null, error: error };
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+async function doProbe(baseUrl) {
+  if (typeof fetch !== 'function') {
+    debugLog('healthcheck: global fetch unavailable, assume reachable');
+    return true; // 旧 Node 没 fetch 时不阻拦，让 reporter 自己去超时
+  }
+
+  const url = buildHealthUrl(baseUrl);
+  const firstTimeoutMs = getProbeTimeoutMs();
+
+  // Round 1: HEAD —— 轻量、快，生产路径 >99% 会在这里返回
+  const head = await sendProbe(url, 'HEAD', firstTimeoutMs);
+  if (isHeadConclusive(head.response)) {
+    recordSuccess();
+    return true;
+  }
+
+  // Round 2: GET 兜底 —— 针对 Next.js dev 冷编译、不接受 HEAD 的反代等情况，
+  // 允许一次"更长超时 + 真实 GET"的重试。超时 ×2，封顶 MAX_TIMEOUT_MS。
+  const secondTimeoutMs = Math.min(firstTimeoutMs * 2, MAX_TIMEOUT_MS);
+  debugLog('healthcheck: HEAD inconclusive, retry with GET');
+  const get = await sendProbe(url, 'GET', secondTimeoutMs);
+  if (get.response && get.response.status >= 200 && get.response.status < 500) {
+    recordSuccess();
+    return true;
+  }
+
+  recordFailure();
+  return false;
+}
+
+// 主入口：返回 Promise<boolean>。true=可上报；false=本次会话禁用上报。
+function ensureReachable(baseUrl) {
+  if (probed !== null) return Promise.resolve(probed);
+  if (probing) return probing;
+
+  if (!baseUrl) {
+    probed = false;
+    return Promise.resolve(false);
+  }
+
+  if (shouldSkipByCooldown()) {
+    debugLog('healthcheck: in cooldown window, skip reporting this session');
+    probed = false;
+    return Promise.resolve(false);
+  }
+
+  probing = doProbe(baseUrl)
+    .then(function (ok) {
+      probed = ok;
+      return ok;
+    })
+    .catch(function () {
+      probed = false;
+      return false;
+    })
+    .finally(function () {
+      probing = null;
+    });
+
+  return probing;
+}
+
+// 供测试复位
+function __resetForTests() {
+  probed = null;
+  probing = null;
+}
+
+module.exports = { ensureReachable, __resetForTests };

package/bin/telemetry/identity.js

@@ -0,0 +1,53 @@
+'use strict';
+
+const crypto = require('crypto');
+const os = require('os');
+const { safeCall, safeRequire } = require('./safe');
+
+let cached = null;
+
+function fallbackId() {
+  const interfaces = safeCall(function () {
+    return os.networkInterfaces();
+  }, {});
+  const macs = [];
+  if (interfaces && typeof interfaces === 'object') {
+    Object.keys(interfaces).forEach(function (name) {
+      const list = interfaces[name] || [];
+      list.forEach(function (entry) {
+        if (entry && entry.mac && entry.mac !== '00:00:00:00:00:00') {
+          macs.push(entry.mac);
+        }
+      });
+    });
+  }
+  macs.sort();
+  const userInfo = safeCall(function () {
+    return os.userInfo();
+  }, { username: 'unknown' });
+  const material = [
+    macs.join(','),
+    userInfo && userInfo.username ? userInfo.username : 'unknown',
+    safeCall(function () { return os.hostname(); }, 'unknown'),
+    safeCall(function () { return os.platform(); }, 'unknown'),
+  ].join('|');
+  return crypto.createHash('sha256').update(material).digest('hex');
+}
+
+function resolveInstallationId() {
+  if (cached) return cached;
+  const mod = safeRequire('node-machine-id');
+  let id = null;
+  if (mod && typeof mod.machineIdSync === 'function') {
+    id = safeCall(function () {
+      return mod.machineIdSync(true);
+    }, null);
+  }
+  if (!id || typeof id !== 'string' || id.length < 8) {
+    id = fallbackId();
+  }
+  cached = String(id).slice(0, 128);
+  return cached;
+}
+
+module.exports = { resolveInstallationId, fallbackId };

package/bin/telemetry/index.js

@@ -0,0 +1,25 @@
+'use strict';
+
+// 对外唯一入口。任一模块加载失败都必须返回一个"透明 wrap"，调用方无感。
+let impl = null;
+try {
+  // eslint-disable-next-line global-require
+  impl = require('./aspect');
+} catch (_error) {
+  impl = null;
+}
+
+function transparent(_command, fn) {
+  return typeof fn === 'function' ? fn() : undefined;
+}
+
+exports.wrap = function wrap(command, fn) {
+  if (!impl || typeof impl.wrap !== 'function') {
+    return transparent(command, fn);
+  }
+  try {
+    return impl.wrap(command, fn);
+  } catch (_error) {
+    return transparent(command, fn);
+  }
+};