wkgeo-cli 0.2.0

package/lib/proxy.mjs

@@ -0,0 +1,454 @@
+/**
+ * 系统代理检测 —— **只读**，只回答一个问题：
+ *   「浏览器能不能把授权码送回 127.0.0.1？」
+ *
+ * ===========================================================================
+ * ## 为什么需要它（老板报的真实故障）
+ *   本地回调模式要求浏览器访问 `http://127.0.0.1:<端口>/callback?code=…`。
+ *   多数代理默认绕过回环地址，但**全局/系统代理 + 绕过列表为空**时，
+ *   浏览器会把这条回环请求也交给代理 → CLI 的本地服务永远收不到 code
+ *   → 用户在页面上点了「同意」，终端却一直卡在"等待授权"，最后超时。
+ *   （极少数代理还会回一个 502/连接失败页，用户以为站点坏了。）
+ *
+ *   2026-10-02 老板原话：「有代理的时候不能成功。」
+ *   → 我们的做法：**检测到代理就直接改走设备码（不需要任何回调）**，
+ *     同时在文档/错误提示里保留"改代理绕过列表"这条补充说明。
+ *
+ * ===========================================================================
+ * ## ⚠️⚠️ 2026-10-02 真机第二次翻车 → 第二版加固（**这条最容易被写错，别改回去**）
+ *   第一版的判定是"有代理 **且** 绕过列表里没有回环 → 算风险 → 才降级"。
+ *   真机上它**失效了**，过程如下（直接采信，不需要复现）：
+ *     * 老板的代理是虚拟网卡代理，Windows 系统代理 = `127.0.0.1:7890`，
+ *       而 `ProxyOverride` 里**确实写着** `localhost;127.*;…`；
+ *     * 我们的检测据此得出 `loopback_bypassed: true` → `risk: false`
+ *       → **不降级、走回调模式**；
+ *     * 结果：老板在同意页点了【同意授权】，CLI **一直拿不到令牌**
+ *       （回调请求根本没到本机）；
+ *     * 独立探测证据：`curl -x http://127.0.0.1:7890 http://127.0.0.1:1/x`
+ *       → **返回 502** —— 说明该代理**会尝试接管回环请求**（而不是直接拒绝），
+ *       也就是说"绕过列表里有 127.*"在这台机器上**并没有真正让请求直连**。
+ *   ⇒ 结论：**"绕过列表里有 127.*"不等于绕过一定生效**。不同代理软件 / 浏览器 /
+ *     系统代理 + PAC 叠加时，对 bypass 的解释并不一致（有的只认主机名不认 `127.*`
+ *     这种通配、有的先把回环发到上游再回连、有的 PAC 求值根本不看 ProxyOverride）。
+ *   ⇒ 因此**本次起：只要 `detected === true` 就一定走设备码**。
+ *     宁可让用户多走一步（按一次短码），也绝不能让用户卡在"点了同意却没反应"。
+ *   ⇒ `loopback_bypassed` / `risk` **只作诊断字段继续上报**（`--json` 里还在，支持同学
+ *     仍然能看到"绕过列表写了什么"），但**不再作为放行回调的依据**。
+ *   ⇒ 想坚持回调的高级用户仍可用 `--no-auto-device` / `WKONGAI_AUTO_DEVICE=0`
+ *     强制走回调（那是他的显式选择），但 CLI 必须把"代理可能吃掉回调"明确警告出来
+ *     —— 见 `proxyForcedCallbackLines()`。
+ *
+ * ===========================================================================
+ * ## 三条硬约束（改这个文件时别越线）
+ *   1. **绝不修改用户的代理设置**：只读注册表 / 只读 `scutil` / 只读环境变量。
+ *      代理由用户的 VPN/代理软件管理，我们改动它等于替用户改网络配置（危险且不可预期）。
+ *   2. **零第三方依赖**：Windows 用系统自带 `reg.exe`，macOS 用系统自带 `scutil`，
+ *      Linux 只读环境变量 —— 刻意**不**引入任何 npm 包（本项目 CLI 依赖数为 0），
+ *      也刻意不去读 gsettings / /etc/environment（没有跨发行版通用做法，收益极低）。
+ *   3. **检测失败一律当成"没检测到"**：拿不到信息最多是"少给一条提示"，
+ *      **绝不能**因此让登录失败（宁可少提示，也不要把登录拦下来）。
+ *
+ * ===========================================================================
+ * ## 各平台到底看什么
+ *   * Windows：注册表 `HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings`
+ *     —— `ProxyEnable`（0/1）、`ProxyServer`（可能是 `http=…;https=…` 这种按协议的写法）、
+ *     `ProxyOverride`（绕过列表，分号分隔，可以含 `<local>`）、`AutoConfigURL`（PAC）。
+ *     ⚠️ 真机数据（本机实测）：`ProxyEnable=0x0` + `ProxyServer=127.0.0.1:7890`
+ *     + `ProxyOverride=…;localhost;*.local;127.*;10.*;…`
+ *     —— 典型的"装过 Clash 类代理，但当前**没有**开启系统代理"。
+ *     所以**只看 `ProxyServer` 存不存在会误报**，必须同时看 `ProxyEnable`；
+ *     反过来 `ProxyOverride` 里有 `127.*` / `localhost` 也算合格绕过（不能误报）。
+ *   * macOS：`scutil --proxy`（系统自带）。它把 HTTP/HTTPS/SOCKS 的开关、地址、端口
+ *     和 `ExceptionsList`（绕过列表）都打出来。`scutil` 不存在时静默跳过。
+ *   * Linux：只看 `HTTP_PROXY` / `HTTPS_PROXY` / `ALL_PROXY` / `NO_PROXY`（大小写都认）。
+ *     桌面环境的 gsettings/环境变量差异太大，不做猜测。
+ *
+ * ===========================================================================
+ * ## ⚠️ 一个容易被误解的点（写文档时要带上）
+ *   这里的"代理"对我们有**两种截然不同的影响**：
+ *     * 对**浏览器**：系统代理直接生效 —— 这正是"回调被接管"的根因（我们主要防这个）。
+ *     * 对 **CLI 自己**：Node 的 fetch（undici）**默认不读** `HTTP_PROXY` 环境变量，
+ *       也不读系统代理（要 Node ≥ 24 的 `--use-env-proxy` / `NODE_USE_ENV_PROXY=1`
+ *       才会走环境变量代理）。所以"CLI 出网失败"通常不是这里的代理造成的，
+ *       我们也不据此改 CLI 的网络行为 —— 只提示、只降级。
+ *       （设备码流程全程只需要 CLI **出网**，不需要任何入站回调，因此对代理天然免疫。）
+ */
+
+import { spawnSync } from 'node:child_process';
+
+/** Windows 系统代理设置的注册表位置（WinINET，即 Edge/Chrome/IE 共用的那份） */
+export const WININET_KEY = 'HKCU\\Software\\Microsoft\\Windows\\CurrentVersion\\Internet Settings';
+
+/** 外部命令的超时：宁可"没检测到"，也不能把登录卡住（`reg.exe` 正常 <50ms） */
+export const PROXY_PROBE_TIMEOUT_MS = 2000;
+
+/** 环境变量里"代理"和"绕过列表"的常见键名（大小写两种写法都认，Linux 上两种都有人写） */
+const PROXY_ENV_KEYS = ['HTTPS_PROXY', 'https_proxy', 'HTTP_PROXY', 'http_proxy', 'ALL_PROXY', 'all_proxy'];
+const NO_PROXY_ENV_KEYS = ['NO_PROXY', 'no_proxy'];
+
+/**
+ * 一个绕过表项是否"**看起来**覆盖了回环地址"。
+ *
+ * ⚠️ 这里刻意认了 **`<local>`** 和 **`*`**：
+ *   * `<local>`：Windows 的"绕过本地地址"约定。实测 Clash / V2Ray 这类客户端
+ *     写的就是 `localhost;127.*;<local>`。
+ *   * `*`：WinINET 与 NO_PROXY 里都表示"全部绕过"（等于没有代理）。
+ *
+ * 🔴 **但它的结论只是"诊断"**：本函数回答的是"绕过列表**写了**回环"，
+ *    而**不是**"绕过**真的生效了" —— 真机上就撞见过"写了 127.* 却依然被代理接管"
+ *    （见文件顶部那段真机证据）。所以 `loopback_bypassed` **绝不允许**再被当成
+ *    "可以放心走回调"的依据；要不要降级只由 `detected` 决定。
+ *    （这条注释是刻意留在这里的：后来的人很容易看到"绕过了"就顺手拿它去放行。）
+ */
+const LOOPBACK_ENTRY_PATTERNS = [
+  /^\*$/,
+  /^<local>$/i,
+  /^localhost(?::\d+)?$/i,
+  /^127(?:\.(?:\d{1,3}|\*)){1,3}(?::\d+)?$/, // 127.0.0.1 / 127.* / 127.0.0.*
+  /^127\.0\.0\.0\/8$/,
+  /^::1$/,
+  /^\[::1\](?::\d+)?$/,
+];
+
+/** 按 `,` / `;` / 空白切分绕过列表（Windows 用分号，Unix 用逗号，还有人手写空格） */
+export function splitBypass(text) {
+  return String(text == null ? '' : text)
+    .split(/[,;\s]+/)
+    .map((s) => s.trim())
+    .filter(Boolean);
+}
+
+/** 绕过列表里是否有"覆盖回环地址"的项 */
+export function isLoopbackBypassed(list) {
+  const entries = Array.isArray(list) ? list : splitBypass(list);
+  return entries.some((e) => LOOPBACK_ENTRY_PATTERNS.some((re) => re.test(String(e).trim())));
+}
+
+/** `0x1` / `1` / `'0x0'` → boolean（注册表里 ProxyEnable 是 REG_DWORD，值是 `0x1`/`0x0`） */
+export function parseDword(value) {
+  const text = String(value == null ? '' : value).trim();
+  if (!text) return false;
+  if (/^0x[0-9a-f]+$/i.test(text)) return Number.parseInt(text, 16) !== 0;
+  return Number(text) !== 0;
+}
+
+/**
+ * 解析 `reg query "<key>"` 的输出。
+ *
+ * 输出形如（只取键值行，子键行没有 `REG_` 标记，天然被忽略）：
+ * ```
+ * HKEY_CURRENT_USER\...\Internet Settings
+ *     ProxyEnable    REG_DWORD    0x0
+ *     ProxyServer    REG_SZ    127.0.0.1:7890
+ *     ProxyOverride    REG_SZ    localhost;127.*;<local>
+ * ```
+ * ⚠️ 值可能是空串（有人把 ProxyServer 清空了），所以值部分要允许为空。
+ * ⚠️ 每个值名在同一次输出里可能出现多次（按协议分列时也会），取**第一条**即可。
+ */
+export function parseRegQuery(stdout) {
+  const values = {};
+  for (const line of String(stdout == null ? '' : stdout).split(/\r?\n/)) {
+    const m = /^\s+([^\s]+)\s+(REG_[A-Z_]+)\s*(.*)$/.exec(line);
+    if (!m) continue;
+    const [, name, , value] = m;
+    if (values[name] === undefined) values[name] = value.trim();
+  }
+  return values;
+}
+
+/**
+ * 解析 `scutil --proxy` 的输出。
+ *
+ * 输出形如：
+ * ```
+ * <dictionary> {
+ *   ExceptionsList : <array> {
+ *     0 : *.local
+ *     1 : 169.254/16
+ *   }
+ *   HTTPEnable : 0
+ *   HTTPSEnable : 1
+ *   HTTPSPort : 7890
+ *   HTTPSProxy : 127.0.0.1
+ * }
+ * ```
+ * ⚠️ 数组块要单独处理：里面的行也是 `数字 : 值` 的形状，若不区分就会把 `0 : *.local`
+ *    当成一个叫 "0" 的键（无害但绕过列表会丢）。
+ */
+export function parseScutilProxy(stdout) {
+  const text = String(stdout == null ? '' : stdout);
+  const values = {};
+  const exceptions = [];
+  let inArray = false;
+
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    if (/^(<array>|ExceptionsList\s*:\s*<array>)\s*\{/.test(trimmed)) {
+      inArray = true;
+      continue;
+    }
+    if (inArray) {
+      if (trimmed === '}') {
+        inArray = false;
+        continue;
+      }
+      const em = /^\d+\s*:\s*(.+)$/.exec(trimmed);
+      if (em) exceptions.push(em[1].trim());
+      continue;
+    }
+    const m = /^([A-Za-z0-9_]+)\s*:\s*(.*)$/.exec(trimmed);
+    if (m) values[m[1]] = m[2].trim();
+  }
+
+  const servers = [];
+  if (parseDword(values.HTTPEnable)) servers.push(`http://${values.HTTPProxy || ''}:${values.HTTPPort || ''}`);
+  if (parseDword(values.HTTPSEnable)) servers.push(`https://${values.HTTPSProxy || ''}:${values.HTTPSPort || ''}`);
+  if (parseDword(values.SOCKSEnable)) servers.push(`socks://${values.SOCKSProxy || ''}:${values.SOCKSPort || ''}`);
+
+  return {
+    enabled: servers.length > 0,
+    servers,
+    exceptions,
+    autoConfig: parseDword(values.ProxyAutoConfigEnable) && !!values.ProxyAutoConfigURLString,
+    autoConfigUrl: values.ProxyAutoConfigURLString || null,
+  };
+}
+
+/**
+ * 默认的"跑一条外部命令拿 stdout"实现。
+ * 失败（命令不存在 / 超时 / 非 0 退出）一律返回 `null` —— 检测不到就当没有代理。
+ */
+export function runCommand(cmd, args) {
+  try {
+    const r = spawnSync(cmd, args, {
+      encoding: 'utf8',
+      timeout: PROXY_PROBE_TIMEOUT_MS,
+      windowsHide: true,
+    });
+    if (r.error || r.status !== 0) return null;
+    return typeof r.stdout === 'string' ? r.stdout : null;
+  } catch {
+    return null;
+  }
+}
+
+/** 从 env 里取第一个非空的键值（`''` 视为没设） */
+function firstEnv(env, keys) {
+  for (const k of keys) {
+    const v = env && env[k];
+    if (v !== undefined && v !== null && String(v).trim() !== '') return String(v).trim();
+  }
+  return null;
+}
+
+/**
+ * 检测系统代理。
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform]  平台（默认 process.platform；测试注入）
+ * @param {object} [opts.env]       环境变量（默认 process.env；测试注入）
+ * @param {Function} [opts.exec]    `(cmd, args) => stdout|null`（默认 runCommand；测试注入，**单测绝不起子进程**）
+ * @returns {{
+ *   detected: boolean,          // 是否发现"生效中"的代理 —— ★ **这是唯一的降级依据**
+ *   risk: boolean,              // 诊断字段：有代理，且至少一个来源**没有**绕过 127.0.0.1/localhost
+ *   loopback_bypassed: boolean, // 诊断字段：发现的代理是否**全部**绕过了回环（⚠️ 不代表绕过真的生效）
+ *   sources: Array<{source:string,label:string,proxy:string,bypass:string[],loopback_bypassed:boolean}>,
+ *   platform: string,
+ *   probe_error: string|null    // 探测本身失败的原因（只作诊断，不影响判定）
+ * }}
+ */
+export function detectProxy({ platform = process.platform, env = process.env, exec = runCommand } = {}) {
+  const sources = [];
+  let probeError = null;
+
+  /* ---- 1. 环境变量（三平台都看；Linux 只有这一条） ---- */
+  const envProxy = firstEnv(env, PROXY_ENV_KEYS);
+  if (envProxy) {
+    const bypass = splitBypass(firstEnv(env, NO_PROXY_ENV_KEYS));
+    sources.push({
+      source: 'env',
+      label: '环境变量代理（HTTP_PROXY/HTTPS_PROXY/ALL_PROXY）',
+      proxy: envProxy,
+      bypass,
+      loopback_bypassed: isLoopbackBypassed(bypass),
+    });
+  }
+
+  /* ---- 2. Windows：注册表（WinINET，浏览器实际用的那份） ---- */
+  if (platform === 'win32') {
+    const stdout = exec('reg', ['query', WININET_KEY]);
+    if (stdout === null) {
+      probeError = 'reg query 没拿到结果（可能不在 PATH 或被安全软件拦了）';
+    } else {
+      const v = parseRegQuery(stdout);
+      const enabled = parseDword(v.ProxyEnable);
+      if (enabled && v.ProxyServer) {
+        const bypass = splitBypass(v.ProxyOverride);
+        sources.push({
+          source: 'windows-registry',
+          label: 'Windows 系统代理（Internet 设置）',
+          proxy: v.ProxyServer,
+          bypass,
+          loopback_bypassed: isLoopbackBypassed(bypass),
+        });
+      }
+      /**
+       * PAC（自动配置脚本）：绕过规则写在**脚本里**，我们无法在零依赖的前提下求值。
+       * 保守起见按"存在代理且绕过规则未知"处理 → 判为风险。
+       * 理由：宁可让用户走一次设备码（体验仍然顺畅），也不要让他点在同意页上干等 5 分钟。
+       */
+      if (enabled && v.AutoConfigURL) {
+        sources.push({
+          source: 'windows-pac',
+          label: `Windows 自动配置脚本（PAC：${v.AutoConfigURL}）`,
+          proxy: v.AutoConfigURL,
+          bypass: [],
+          loopback_bypassed: false,
+        });
+      }
+    }
+  }
+
+  /* ---- 3. macOS：`scutil --proxy`（系统自带；不存在/失败就跳过） ---- */
+  if (platform === 'darwin') {
+    const stdout = exec('scutil', ['--proxy']);
+    if (stdout === null) {
+      probeError = 'scutil --proxy 没拿到结果';
+    } else {
+      const p = parseScutilProxy(stdout);
+      if (p.enabled) {
+        sources.push({
+          source: 'macos-scutil',
+          label: 'macOS 系统代理',
+          proxy: p.servers.join(' , '),
+          bypass: p.exceptions,
+          loopback_bypassed: isLoopbackBypassed(p.exceptions),
+        });
+      }
+      if (p.autoConfig) {
+        sources.push({
+          source: 'macos-pac',
+          label: `macOS 自动代理配置（PAC：${p.autoConfigUrl}）`,
+          proxy: p.autoConfigUrl,
+          bypass: [],
+          loopback_bypassed: false,
+        });
+      }
+    }
+  }
+
+  const detected = sources.length > 0;
+  return {
+    detected,
+    risk: sources.some((s) => !s.loopback_bypassed),
+    loopback_bypassed: detected && sources.every((s) => s.loopback_bypassed),
+    sources,
+    platform,
+    probe_error: probeError,
+  };
+}
+
+/**
+ * 把检测结果变成 **`--json` 用的结构化字段**（`meta.proxy_warning` / 事件里的 `proxy_warning`）。
+ *
+ * 为什么连"建议动作"也结构化：AI 端要能**照着念给用户**，而不是自己组织语言。
+ * 之前 AI 端拿到的只有一句错误文本，它只能猜该让用户做什么。
+ *
+ * ⚠️ 2026-10-02 第二版加固后的口径（**改这里之前先读文件顶部那段真机证据**）：
+ *   * `callback_may_fail` = **`detected`** —— 只要检测到生效中的代理就认为回调不可信，
+ *     **不再**看绕过列表（真机上"写了 127.* 也照样被接管"）；
+ *   * `risk` / `loopback_bypassed` / `risky_sources` **只作诊断**保留，
+ *     方便支持同学看清楚"这台机器上代理与绕过列表长什么样"；
+ *   * 新增 `loopback_bypass_trusted: false`，把"绕过列表已不再作为放行依据"这件事
+ *     明确写进机器可读输出（AI 端就不会再自作聪明地说"你绕过了所以没事"）。
+ */
+export function proxyWarningPayload(info, { cmdName = 'wkgeo' } = {}) {
+  if (!info) return null;
+  const risky = info.sources.filter((s) => !s.loopback_bypassed);
+  /** ★ 唯一的降级依据：有没有检测到生效中的代理（与绕过列表无关） */
+  const detected = !!info.detected;
+  return {
+    detected,
+    /** ★ 只有它为 true 才需要用户/CLI 做点什么（现在等价于 detected） */
+    callback_may_fail: detected,
+    /** ⚠️ 恒为 false：绕过列表**不再**是"可以走回调"的凭据（真机证据见文件顶部） */
+    loopback_bypass_trusted: false,
+    /** 旧口径，纯诊断：有代理且至少一个来源没绕过回环 */
+    risk: !!info.risk,
+    loopback_bypassed: !!info.loopback_bypassed,
+    platform: info.platform || null,
+    proxy: info.sources.length ? info.sources.map((s) => s.proxy).join(' , ') : null,
+    source: info.sources.length ? info.sources.map((s) => s.source).join(',') : null,
+    bypass: info.sources.length ? info.sources[0].bypass : [],
+    risky_sources: risky.map((s) => ({ source: s.source, proxy: s.proxy, bypass: s.bypass })),
+    probe_error: info.probe_error || null,
+    /** 主路径：改用设备码（不需要任何回调）；后两条是"如果你就想用回调模式"的补充办法 */
+    actions: detected
+      ? [
+          {
+            type: 'use_device_code',
+            label: '改用设备码模式（不需要本地回调，推荐）',
+            command: `${cmdName} login --device`,
+          },
+          {
+            type: 'bypass_loopback',
+            label: '把 127.0.0.1,localhost 加进代理绕过列表（想继续用浏览器回调模式时；注意它不保证生效）',
+          },
+          { type: 'disable_proxy', label: '临时关闭代理后重试' },
+        ]
+      : [],
+  };
+}
+
+/**
+ * 人类可读提示块：**"已自动改用设备码模式"**（人类模式下走这条路，AI 端看上面的 payload）。
+ *
+ * ⚠️ 触发条件与 payload 的 `callback_may_fail` 保持一致：`detected`，**不是** `risk`。
+ * ⚠️ 没有检测到代理返回 `[]`（**不要在正常环境里制造噪音**）。
+ */
+export function proxyDeviceSwitchLines(info, { cmdName = 'wkgeo' } = {}) {
+  if (!info || !info.detected) return [];
+  const first = info.sources[0] || { proxy: '', bypass: [], source: '' };
+  const bypass = (first.bypass || []).join(',') || '空';
+  return [
+    `⚠️ 检测到系统代理（${first.proxy || '未知地址'}）。为避免“点了同意却一直收不到结果”，已自动改用【设备码模式】。`,
+    `   想强制用浏览器回调模式：加 --no-auto-device，并把 127.0.0.1,localhost 加入代理绕过列表。`,
+    `   （检测详情：源=${info.sources.map((s) => s.source).join(',')} 代理=${first.proxy || '-'} 绕过列表=${bypass}；` +
+      `⚠️ 绕过列表里就算写了 127.*/localhost 也**不再**作为放行回调的依据 —— 真机上出现过"写了却仍被代理接管"。）`,
+  ];
+}
+
+/**
+ * 人类可读警告块：用户**显式强制**走回调模式（`--no-auto-device` / `WKONGAI_AUTO_DEVICE=0`），
+ * 但本机确实有代理 —— 必须把"你可能一直等不到结果"讲清楚，否则他只会觉得 CLI 坏了。
+ *
+ * ⚠️ 这一段是**唯一的**阻止"用户点了同意却干等超时"的东西（因为我们按他的要求没有改道），
+ *    所以文案里必须同时给出**两条**可照做的出路。
+ */
+export function proxyForcedCallbackLines(info) {
+  if (!info || !info.detected) return [];
+  const first = info.sources[0] || { proxy: '' };
+  return [
+    `⚠️ 你已强制使用回调模式（--no-auto-device / WKONGAI_AUTO_DEVICE=0），但本机检测到系统代理（${first.proxy || '未知地址'}）。`,
+    '   若这个代理会接管 127.0.0.1，你在页面上点了【同意授权】之后本机也收不到结果（会一直等到超时）。',
+    '   两条出路：① 把 127.0.0.1,localhost 加入代理绕过列表；② 去掉 --no-auto-device，让 CLI 自动改用设备码模式。',
+  ];
+}
+
+/**
+ * 给**错误 `hint`** 用的一句话版本（错误对象里只能放短文本）。
+ * 没有检测到代理返回 `null` —— 调用方据此决定要不要加这句。
+ *
+ * ⚠️ 触发条件同样是 `detected`（不是 `risk`）：超时那一刻我们已经无法判断
+ *    "绕过列表到底有没有生效"，所以有代理就要把这条线索给出去。
+ */
+export function proxyRiskHint(info, { cmdName = 'wkgeo' } = {}) {
+  if (!info || !info.detected) return null;
+  const proxy = (info.sources[0] && info.sources[0].proxy) || '未知地址';
+  return (
+    `本机检测到系统代理（${proxy}）；若它接管 127.0.0.1，浏览器回调就收不到（绕过列表里写了 127.*/localhost 也不保证生效）。` +
+    `三选一：① 改用不需要回调的 \`${cmdName} login --device\`；` +
+    `② 把 127.0.0.1,localhost 加入代理绕过列表；③ 临时关闭代理后重试`
+  );
+}

package/lib/qr.mjs

@@ -0,0 +1,31 @@
+/**
+ * 可选的终端二维码。
+ *
+ * 为什么做成"有就用、没有就打印链接"：
+ *   微信 Native 支付返回的 `code_url` 是 `weixin://wxpay/...`，
+ *   **手机直接扫这段文本是扫不了的**，所以给人看的场景最好在终端画一个 ASCII 二维码。
+ *   但 `qrcode-terminal` 是个第三方包，而老板要求"尽量零第三方依赖"。
+ *   折中：动态 import —— 装了就用，没装就只打印链接（并说明"用手机打开/复制到微信"）。
+ *   ⚠️ 绝不能因为二维码库缺失就让下单/充值命令失败。
+ */
+
+export async function renderQrOptional(text, out) {
+  if (!text) return false;
+  try {
+    const mod = await import('qrcode-terminal');
+    const gen = mod && (mod.default || mod);
+    if (gen && typeof gen.generate === 'function') {
+      let printed = '';
+      gen.generate(text, { small: true }, (q) => {
+        printed = q;
+      });
+      if (printed) {
+        out.line(printed);
+        return true;
+      }
+    }
+  } catch {
+    /* 没装 → 静默降级 */
+  }
+  return false;
+}