wkgeo-cli 0.2.1 → 0.2.3

package/lib/commands/auth.mjs

@@ -5,7 +5,7 @@
  *    需要用户做的事（同意授权）表现为：打印网址 + 阻塞等待 + 超时给明确错误。
  */
 
-import { runLogin, DEFAULT_CALLBACK_FIRST_WAIT_MS } from '../login.mjs';
+import { runLogin } from '../login.mjs';
 import { requestDeviceCode, announceDeviceCode, pollDeviceToken, devicePasteText } from '../device.mjs';
 import {
   pendingDeviceFile,
@@ -62,34 +62,36 @@ export function resolveAutoDevice(flags = {}, env = {}) {
 }
 
 /**
- * 「回调模式首轮等待」窗口（毫秒）的解析 —— ★ 第二条保险（见 login.mjs 的同名注释）。
+ * 「回调模式首轮等待」窗口（毫秒）的解析 —— **可选自愈，默认关闭**。
  *
- * ## ⚠️⚠️ 2026-10-03 老板真机反馈后改了触发条件（这是本次修复的第一条）
- *   旧逻辑：**无条件**返回默认 60 秒 ⇒ 用户机器上**没有任何代理/VPN**时也会自愈。
- *   而"把授权页送到用户面前、他读完再点【同意】"经常超过 60 秒 ⇒ 明明不需要设备码也切了过去。
- *   老板原话：「现在变成设备码了，我们因为没有开任何VPN，所以这个是不对的。」
- *   ⇒ 现在：**只有 `proxyDetected === true`（真检测到生效中的代理）才用默认值启用**；
- *     **没有代理时不启用**（返回 0，老老实实等满 `--timeout`）。
+ * ## ★★ 0.2.2（老板 2026-10-21 反馈）：默认不再自动改设备码
+ *   老板原话：「默认的也不应该是设备授权，默认的就是那个传统的授权方式（浏览器打开授权页 +
+ *   本地 localhost 回调）。设备码是本地读不了/代理时才用的。」
+ *   ⇒ 本函数**不再**按"有没有代理"给默认值：用户没显式指定时**一律返回 0**。
+ *     也就是说 `wkgeo login` 默认会一路等回调到 `--timeout`，**不会**因为等太久自动改设备码。
  *
- * ## 优先级（显式 > 自动判断）
- *   `--callback-first-wait <时长>`（默认单位**秒**；`0` / `off` / `none` = 关掉自愈）
+ * 设备码只在这三种情况出现（见 loginCommand.run）：
+ *   1. 用户显式 `--device` / `--no-wait` / `--device-continue`；
+ *   2. 检测到系统代理且判定回调不可用（`--no-auto-device` 可关）；
+ *   3. 本地回调端口**真的起不来**（`kind = 'listen'`，真实失败兜底；`--no-auto-device` 可关）。
+ *
+ * ## 保留的显式开关（向后兼容，不参与默认判断）
+ *   `--callback-first-wait <时长>`（默认单位**秒**；`0` / `off` / `none` = 关闭）
  *   > `WKONGAI_CALLBACK_FIRST_WAIT_MS`（毫秒）
- *   > **有代理**时的 `DEFAULT_CALLBACK_FIRST_WAIT_MS`（180 秒）/ **无代理**时的 0
- *   ⇒ 用户**显式**指定时一律照旧尊重（哪怕没有代理）—— 显式指定优先于自动判断。
+ *   > 默认 **0（关闭）**
+ *   ⇒ 只有用户**显式**写了它，才会在首轮等待到点后并发启动设备码（两条路先到先得）。
+ *     显式指定是用户的明确选择，我们照旧尊重（但他不写就绝不会自动发生）。
  *
  * ⚠️ `--no-auto-device`（autoDevice=false）时**强制返回 0**：用户已经明确要求"只走回调"，
- *    我们没有"改道"这个选项，就不能背着他偷偷改（那样比不给自愈更糟：他会以为
- *    CLI 没听他的）。此时整段 `--timeout` 依然是兜底。
+ *    我们就连显式开关也不启用（不背着他改道）。此时整段 `--timeout` 依然是兜底。
  *
  * @param {object} flags 已解析的命令行标志（camelCase）
  * @param {object} env   环境变量
  * @param {{autoDevice?: boolean, proxyDetected?: boolean}} [opts]
- *   `proxyDetected` **必须**由调用方用 `proxyInfo.detected` 显式传入；
- *   缺省按 `false`（= 没检测到代理）处理 —— 这是刻意的保守默认：
- *   "信息不足时宁可不自愈"，也避免有人忘了传就又回到"无代理也切设备码"的老毛病。
- * @returns {number} 毫秒；0 = 关闭自愈
+ *   `proxyDetected` 仅为**兼容旧调用方**保留，**已不影响返回值**（0.2.2 起默认永不开启）。
+ * @returns {number} 毫秒；0 = 不启用（默认）
  */
-export function resolveCallbackFirstWaitMs(flags = {}, env = {}, { autoDevice = true, proxyDetected = false } = {}) {
+export function resolveCallbackFirstWaitMs(flags = {}, env = {}, { autoDevice = true } = {}) {
   if (!autoDevice) return 0;
   const off = new Set(['0', 'off', 'none', 'false', 'no']);
   if (flags.callbackFirstWait !== undefined && flags.callbackFirstWait !== '') {
@@ -103,11 +105,11 @@ export function resolveCallbackFirstWaitMs(flags = {}, env = {}, { autoDevice =
     return parseDurationMs(envVal, { defaultUnit: 'ms', flag: 'WKONGAI_CALLBACK_FIRST_WAIT_MS' });
   }
   /**
-   * ★ 走到这里 = 用户**没有**显式指定 ⇒ 只有"真检测到代理"才启用自愈。
-   *   没有代理时返回 0：`auto_device.applied=true, reason='callback_first_wait'`
-   *   因此**只可能**出现在有代理的机器上（老板真机那条反馈的口径）。
+   * ★ 走到这里 = 用户**没有**显式指定 ⇒ **默认不启用**（0.2.2 起）。
+   *   不再看 `proxyDetected`：有代理时命令层已经在第一跳直接走设备码了，
+   *   回调模式下的"等待超时"只该如实报错，不该偷偷改道。
    */
-  return proxyDetected ? DEFAULT_CALLBACK_FIRST_WAIT_MS : 0;
+  return 0;
 }
 
 /**
@@ -190,7 +192,9 @@ function bothPathsFailedError(deviceError, reason, { loginTimeoutMs }) {
   const callbackSide =
     reason === 'callback_timeout'
       ? `等待授权超时（${loginTimeoutMs}ms，本机回调监听当时仍然开着）`
-      : '首轮等待没收到回调（本机回调监听当时仍然开着）';
+      : reason === 'callback_listen_failed'
+        ? '本地回调端口起不来（根本没起监听）'
+        : '首轮等待没收到回调（本机回调监听当时仍然开着）';
   return new CliError(`本地回调没成功，改用设备码也失败了：${deviceError.message}`, {
     kind: deviceError.kind || 'device_authorization_failed',
     code: deviceError.code === undefined ? null : deviceError.code,
@@ -212,28 +216,28 @@ const TERMINAL_DEVICE_KINDS = new Set(['denied', 'expired', 'not_implemented', '
 
 export const loginCommand = {
   name: 'login',
-  summary: '浏览器授权一次，把 30 天令牌存到本地（默认本地回调模式；--device 走设备码）',
+  summary: '浏览器授权一次，把 30 天令牌存到本地（默认本地回调模式；设备码仅在本地无法回调/检测到代理时兜底）',
   usage:
     'wkgeo login [--scope "site:read site:write billing:self"] [--no-browser] [--open-browser] [--client-id <id>] [--callback-port <n>] [--timeout <秒>]\n' +
-    'wkgeo login --device          # 设备码模式：不需要回调地址/监听端口，给用户一个短码\n' +
+    'wkgeo login --device          # 设备码模式：不需要回调地址/监听端口，给用户一个短码（兜底路径）\n' +
     'wkgeo login --device --no-wait    # ★ 只申请短码就退出（AI 端友好），稍后用下面这条领令牌\n' +
     'wkgeo login --device-continue     # 用上次保存的设备码换票、写完凭据就完成登录\n' +
-    'wkgeo login --no-auto-device  # **检测到系统代理也不**自动改设备码（强制走回调；CLI 会警告）\n' +
+    'wkgeo login --no-auto-device  # 检测到系统代理也不自动改设备码（强制回调；CLI 会警告；端口真起不来也不兜底）\n' +
     'wkgeo login --open-browser    # 强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）\n' +
-    'wkgeo login --callback-first-wait 60   # 首轮等待 60 秒（★ 只在检测到代理时才有默认值 180；0/off = 关掉这个自愈）\n' +
+    'wkgeo login --callback-first-wait 60   # ★ 可选：显式启用"首轮等待 60 秒没回调就并行改设备码"（默认关闭；0/off = 关闭）\n' +
     'wkgeo login --timeout 600     # 等待授权 600 秒（默认单位是秒，不是毫秒；也支持 600s / 500ms）',
   flags: {
-    browser: { type: 'boolean', desc: '是否自动打开浏览器（★ 默认总是尝试打开：终端与 AI 场景都一样；--no-browser 关闭）' },
+    browser: { type: 'boolean', desc: '是否自动打开浏览器（★ 默认：人类终端打开；CI/管道/AI 子进程等非交互环境不打开；--no-browser 关闭）' },
     /**
-     * ★ 老板最终拍板走**传统路线**（弹系统浏览器）：CLI **默认总是尝试打开**，
-     *   唯一的"不打开"开关是 `--no-browser`。
-     *   本开关现在**与默认行为等价**，保留只为两件事：
-     *     1. **显式语义**（"我就是要弹，你别管"）；
+     * ★ 2026-10-21（老板反馈：CI 里弹了浏览器）：默认**只在人类终端**自动打开；
+     *   非交互/CI 环境（stdout 非 TTY / CI 环境变量 / `WKONGAI_CLI_NO_BROWSER=1`）**一律不打开**。
+     *   本开关保留只为两件事：
+     *     1. **显式语义**（终端里明确表达"我就是要弹"）；
      *     2. **兼容**既有脚本（不许删）。
-     * ⚠️ 与 `--no-browser` 同时出现时 **--no-browser 优先**（关掉就是关掉，见 resolveBrowserIntent）。
+     *   ⚠️ 它**压不过**非交互判定（CI 里写它也不弹）；与 `--no-browser` 同时出现时 `--no-browser` 优先。
      */
-    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）' },
-    device: { type: 'boolean', desc: '用设备码模式（RFC 8628）代替本地回调：不需要任何回调地址，对代理/防火墙免疫' },
+    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 仅在人类终端生效；CI/非交互环境仍不打开）' },
+    device: { type: 'boolean', desc: '用设备码模式（RFC 8628）代替本地回调：不需要任何回调地址，对代理/防火墙免疫（本地读不了回调时的兜底）' },
     /**
      * ★ 老板 2026-10-02 要的"AI 端友好路径"。
      * 为什么做成"申请完就退出"而不是"申请完继续挂着轮询"（后者靠 JSONL 事件流也能做）：
@@ -246,20 +250,20 @@ export const loginCommand = {
     'device-continue': { type: 'boolean', desc: '继续上一次 --no-wait/被中断的设备码登录（读取本地保存的设备码并轮询到出结果）' },
     'auto-device': {
       type: 'boolean',
-      desc: '检测到系统代理时自动改用设备码（**默认开**；--no-auto-device 或 WKONGAI_AUTO_DEVICE=0 关闭，关闭时会警告"代理可能吃掉回调"）',
+      desc: '检测到系统代理时自动改用设备码（**默认开**；--no-auto-device 或 WKONGAI_AUTO_DEVICE=0 关闭，关闭时会警告"代理可能吃掉回调"，且端口真起不来时也不兜底）',
     },
     /**
-     * ★ 第二条保险（见 login.mjs 的 DEFAULT_CALLBACK_FIRST_WAIT_MS）。
+     * ★ 可选自愈（默认**关闭**，0.2.2 起）。
      * 默认单位**秒**，与 `--timeout` 一致（人类写等待窗口都按秒想）；
-     * `0` / `off` / `none` = 关掉自愈，回到"只等整段 --timeout"的旧行为。
+     * `0` / `off` / `none` = 关闭（默认值就是关闭）。
      * 环境变量 `WKONGAI_CALLBACK_FIRST_WAIT_MS` 是毫秒（与 `WKONGAI_LOGIN_TIMEOUT_MS` 同口径）。
      *
-     * ⚠️ 2026-10-03 起：**不传它时默认值是"看有没有代理"** —— 有代理才是 180 秒，没有代理是 0
-     *   （老板真机反馈：没有开任何 VPN 也被切成了设备码）。显式传值时照旧尊重用户。
+     * ⚠️ 2026-10-21（老板反馈）：**默认不再自动改设备码** —— 不写它时无论等多久都只走回调，
+     *   超时只报错。只有显式写它，才会在首轮等待到点后并发启动设备码（显式优先）。
      */
     'callback-first-wait': {
       type: 'string',
-      desc: '回调模式的**首轮等待**（默认单位秒；★ 只在检测到系统代理时默认 180 秒，无代理默认不启用）：这段时间没等到回调就自动改用设备码继续（本地回调监听会同时保留）；0/off 关闭该自愈',
+      desc: '★ 可选自愈（默认**关闭**，默认单位秒）：显式写它才会在"首轮等待"到点后并行改用设备码继续（本地回调监听同时保留）；不写它时**不会**因为等待超时自动改设备码；0/off 关闭',
     },
     /**
      * 显式声明一次（`timeout` 本来就在 GLOBAL_FLAGS 里），只为让 `wkgeo login --help`
@@ -320,6 +324,12 @@ export const loginCommand = {
     const proxyInfo = !wantsDevice && !wantsContinue ? ctx.proxyInfo() : null;
     const proxyPayload = proxyInfo ? proxyWarningPayload(proxyInfo, { cmdName }) : null;
     const autoDevice = resolveAutoDevice(flags, ctx.env);
+    /**
+     * ★ 可选首轮等待（默认 0 = 关闭，0.2.2 起）。
+     *   只有用户**显式**写 `--callback-first-wait` / `WKONGAI_CALLBACK_FIRST_WAIT_MS`
+     *   才会启用；`--no-auto-device` 强制 0。它**不参与**"默认走什么模式"的判断。
+     */
+    const callbackFirstWaitMs = resolveCallbackFirstWaitMs(flags, ctx.env, { autoDevice });
 
     /**
      * ★★ 核心规则（2026-10-02 第二版加固）：**`detected === true` 就直接走设备码**。
@@ -335,7 +345,7 @@ export const loginCommand = {
      */
     const proxyDetected = !!(proxyInfo && proxyInfo.detected);
     let useDevice = wantsDevice;
-    /** 为什么会走设备码：proxy_detected / callback_first_wait / callback_timeout / callback_listen_failed */
+    /** 为什么会走设备码：proxy_detected / callback_listen_failed / callback_first_wait（仅显式开启时） */
     let downgradeReason = null;
     if (!useDevice && autoDevice && proxyDetected) {
       useDevice = true;
@@ -364,31 +374,33 @@ export const loginCommand = {
       /** 真 spawn 的注入点（单测验证"AI 场景一次都不 spawn 浏览器"；生产不传 = 真 spawn） */
       spawnImpl: ctx.spawnImpl,
       /**
-       * ★★ 「要不要替用户弹**系统**浏览器」的四个事实（老板最终拍板走**传统路线**）：
+       * ★★ 「要不要替用户弹**系统**浏览器」的输入（2026-10-21 起含 CI/非交互检测）：
        *   * `isTTY`   —— stdout 是不是终端（由 runtime 从 stdout.isTTY 读出，命令层原样透传）；
        *   * `json`    —— 是不是 JSON 输出（`--json` 或非 TTY 自动 JSON）；
-       *   * `forceBrowser` —— 用户写了 `--open-browser`（现在与默认行为等价，保留显式语义）；
-       *   * `noBrowser`    —— 用户写了 `--no-browser`（**唯一**的"不打开"开关，优先级最高）。
-       * 四个一起进 `resolveBrowserIntent()`（login.mjs 里的**唯一裁决点**）：
-       *   **默认总是尝试打开系统浏览器**（人在终端 ✔ + AI 场景 ✔）；
-       *   `isTTY` / `json` 现在只影响 `mode` 这个诊断字段，**不再**决定"要不要弹"。
+       *   * `forceBrowser` —— 用户写了 `--open-browser`（只在终端里保留显式语义）；
+       *   * `noBrowser`    —— 用户写了 `--no-browser`（**最高优先级**的"不打开"开关）；
+       *   * `env`     —— CI 环境变量判定（`CI` / `GITHUB_ACTIONS`… / `WKONGAI_CLI_NO_BROWSER=1`）。
+       * 全部进 `resolveBrowserIntent()`（login.mjs 里的**唯一裁决点**）：
+       * **人在终端默认打开**；`--no-browser` 与**非交互/CI**都不打开（`attempted:false`）；
+       * 非交互时还会打印"把链接转给有浏览器的用户 / 改用 `--device`"的提示。
        * ⚠️ 回调模式与设备码模式都吃这一份 deps —— 所以两条授权路径的行为天然一致。
        */
       isTTY: ctx.isTTY === true,
       json: ctx.out.json === true,
       forceBrowser: flags.openBrowser === true,
       noBrowser: flags.browser === false,
+      /** ★ CI / 非交互判定用（纯函数在 login.mjs 的 detectNonInteractive） */
+      env: ctx.env || {},
       platform: ctx.platform,
       /**
-       * ★ 第二条保险：回调模式的**首轮等待**。
+       * ★ 可选首轮等待（见上面 `callbackFirstWaitMs`）。
        *
-       * ⚠️⚠️ 2026-10-03 起默认值**取决于有没有代理**（老板真机反馈修的）：
-       *   * 有代理（`proxyDetected === true`）→ `DEFAULT_CALLBACK_FIRST_WAIT_MS`（180 秒）；
-       *   * **没有代理 → 0 = 不启用**（老老实实等满 `--timeout`）；
-       *   * 用户显式写 `--callback-first-wait` / `WKONGAI_CALLBACK_FIRST_WAIT_MS` → 照旧尊重；
+       * ⚠️⚠️ 0.2.2 起**默认 0 = 关闭**（老板 2026-10-21 反馈）：
+       *   * 不写 `--callback-first-wait` / 环境变量 → 0，一直等满 `--timeout`，**不会**自动改设备码；
+       *   * 显式写 `--callback-first-wait <秒>` / `WKONGAI_CALLBACK_FIRST_WAIT_MS` → 照旧启用；
        *   * `--no-auto-device` → 强制 0（用户明确要求只走回调，就不能偷偷改道）。
        */
-      callbackFirstWaitMs: resolveCallbackFirstWaitMs(flags, ctx.env, { autoDevice, proxyDetected }),
+      callbackFirstWaitMs,
       /**
        * ★★ 设备码先成功后，本地回调监听再多留多久（毫秒；0 = 立刻收尾）。
        *   生产不传 = `login.mjs` 的 `DEFAULT_POST_DEVICE_GRACE_MS`；
@@ -398,19 +410,23 @@ export const loginCommand = {
     };
 
     /**
-     * ★ 无代理时的一句说明（老板真机反馈的直接回应）。
+     * ★ 默认模式的正面说明（老板 2026-10-21 反馈的直接回应）。
      *
-     * 为什么值得打这一行：他这次的困惑正是"**我没有开代理，为什么变成设备码了**"。
-     * 明说"这次不会因为首轮等待就自动改设备码"能直接消掉这个困惑；
-     * 同时也要说清"整段 --timeout 用完仍可能改"（那是既有的兜底语义，本次没有改动）。
-     * ⚠️ 只在"回调模式 + 没检测到代理 + 没开自愈"时打：其它情况一律不打（正常环境不要噪音）。
+     * 老板原话：「默认的也不应该是设备授权，默认的就是那个传统的授权方式（浏览器打开授权页 +
+     * 本地 localhost 回调）。设备码是本地读不了/代理时才用的。」
+     * ⇒ 这里明说"本次就是回调、等多久都不会自动改设备码"，同时列出**唯一会走设备码**的三种情况，
+     *   并给出"主动提前切换"的显式开关，免得用户以为 CLI 背着他改道。
+     * ⚠️ 只在"回调模式 + 没检测到代理 + 没显式开首轮等待"时打：其它情况一律不打（正常环境不要噪音）。
      */
-    if (!useDevice && !wantsContinue && !proxyDetected && loginDeps.callbackFirstWaitMs === 0) {
+    if (!useDevice && !wantsContinue && !proxyDetected && callbackFirstWaitMs === 0) {
       log(
-        `ℹ️ 未检测到系统代理：本次会一直等你完成授权（最多 ${Math.round(config.loginTimeoutMs / 1000)} 秒），` +
-          '不会因为"首轮等待"到点就自动改用设备码。',
+        `ℹ️ 未检测到系统代理：本次使用浏览器回调授权（默认），会一直等你完成授权（最多 ${Math.round(config.loginTimeoutMs / 1000)} 秒）。`,
       );
-      log('   （想主动限制首轮等待：`--callback-first-wait <秒>`；想强制设备码：`--device`。）');
+      log(
+        '   不会因为"首轮等待/等待超时"到点就自动改用设备码；只有显式 `--device`、检测到系统代理、' +
+          '或本地回调端口真的起不来时才会用设备码（`--no-auto-device` 可关掉后两种自动兜底）。',
+      );
+      log('   （想主动提前切换：`--callback-first-wait <秒>`；想直接走设备码：`--device`。）');
     }
 
     /**
@@ -561,10 +577,10 @@ export const loginCommand = {
       }
     }
 
-    /* ---- 2c. 本地回调模式（含"回调没等到 → 并发改设备码"，★ 两条路并存） ---- */
+    /* ---- 2c. 本地回调模式（默认路径；显式首轮等待时才与设备码两条路并存） ---- */
     if (!result && !useDevice) {
       /**
-       * ★★ 2026-10-03（老板真机反馈 ⚠️）：「改用设备码」**不再关掉本地回调监听**。
+       * ★★ 2026-10-03（老板真机反馈 ⚠️）：显式开启的"首轮等待"到点改道时**不再关掉本地回调监听**。
        *
        * ## 旧行为（真机证据：ERR_CONNECTION_REFUSED）
        *   首轮等待到点 → `runLogin` 抛错，并在自己的 `finally` 里**关掉本地 server** → 命令层再走设备码。
@@ -572,15 +588,17 @@ export const loginCommand = {
        *   `http://127.0.0.1:<port>/callback?code=…` → **ERR_CONNECTION_REFUSED**
        *   （老板真机截图见过）→ 用户以为授权失败，再来一遍（而其实他马上就会登录成功）。
        *
-       * ## 新行为：两条路**并存**，哪个先拿到令牌就用哪个（先到先得）
+       * ## 新行为（仅显式 `--callback-first-wait` 时）：两条路**并存**，哪个先拿到令牌就用哪个
        *   * 回调那条路：本地 server 一直开着（`runLogin` 收到 `handoff` 时到点**不结束等待**）；
        *   * 设备码那条路：由下面的 `handoff.onSwitch` 启动，轮询到出结果为止。
        *   * 回调先成功 → 把设备码那条路**优雅停掉**（唤醒它挂着的 sleep + 删掉待完成状态文件）；
        *   * 设备码先成功 → `finishWithDevice()` 让回调那条路收尾（监听再多留几秒，
        *     迟到的回调会拿到"本次登录已经完成"的页面，见 login.mjs / page.mjs）。
+       * ★ 0.2.2 起默认**不启用**这套交接（`--callback-first-wait` 未显式给出时
+       *   `callbackFirstWaitMs === 0`）：默认就是一路等回调，超时只报错。
        */
-      /** 允许"自动改道"吗：用户没写 --no-auto-device，也不是显式设备码模式 */
-      const mayAutoSwitch = autoDevice && !wantsDevice && !wantsContinue;
+      /** 允许"等待到点改道"吗：只有用户**显式**开了首轮等待，且没写 --no-auto-device、不是显式设备码模式 */
+      const mayAutoSwitch = autoDevice && !wantsDevice && !wantsContinue && callbackFirstWaitMs > 0;
       /** 设备码那条路的可取消状态（回调先赢时要把它收拾干净） */
       const deviceSide = { reason: null, cancelled: false, promise: null, result: null, error: null };
       /** ★ 可被立刻叫醒的 sleep：回调先赢时，不能让设备码那个 5 秒定时器把进程吊住 */
@@ -648,13 +666,21 @@ export const loginCommand = {
             handoff,
             onAuthorizationUrl: (url, extra) => {
               if (jsonMode) {
+                /**
+                 * ★ 非交互（CI / 管道 / AI 子进程）时**不会**自动打开浏览器 ⇒ 给 AI/脚本的
+                 *   `user_action_required` 必须换成"把链接转给有浏览器的人 / 改用设备码"，
+                 *   否则调用方会以为"浏览器已经弹出来了"，只让用户干等。
+                 */
+                const nonInteractive = !!(extra && extra.open_browser && extra.open_browser.skipped_reason === 'non_interactive');
                 out.event({
                   ok: true,
                   command: 'login',
                   mode: 'callback',
                   stage: 'awaiting_callback',
                   authorization_url: url,
-                  user_action_required: '请让用户在浏览器中打开上面的 authorization_url，登录并点「同意」',
+                  user_action_required: nonInteractive
+                    ? '本机是非交互环境（CI/管道/AI 子进程），不会自动打开浏览器：请把 authorization_url 转给有浏览器的用户打开；若本机无法接收回调，改用 `wkgeo login --device`（设备码模式）'
+                    : '请让用户在浏览器中打开上面的 authorization_url，登录并点「同意」',
                   proxy_warning: proxyPayload,
                   ...extra,
                 });
@@ -668,31 +694,25 @@ export const loginCommand = {
         /** 设备码那条路也失败了 ⇒ 优先报"两条路都不通"（哪怕回调那边先抛了自己的错） */
         if (deviceSide.combinedError) throw deviceSide.combinedError;
         /**
-         * ★ 「回调失败也自动降级」（老板 2026-10-02 要求"不要直接失败退出"）。
-         *   走得到这里的是**没有启用交接**（`--no-auto-device`）或"连端口都起不来"的两种情况：
-         *     * `listen` —— 连回环端口都起不来（被安全软件/防火墙拦）：
-         *       此时**根本没有监听可保留**，只能老老实实改走设备码；
-         *     * `callback_first_wait` / `timeout` —— 只可能出现在没传 `handoff.onSwitch` 时（旧契约兜底）。
-         *   其它错误（换票失败、被拒绝、state 不匹配…）**不降级**：那些是"授权已经走到下一步了"，
-         *   再来一遍设备码只会让用户做重复劳动（甚至以为被耍了）—— 这条语义**本次没有改动**。
+         * ★★ 0.2.2 起：**只有"本地回调端口真的起不来"（`kind = 'listen'`）才自动兜底设备码**。
+         *   （老板：「设备码是本地读不了/代理时才用的」—— 连监听都起不来就是"本地读不了"。）
+         *   * `listen` —— 回环端口起不来（被安全软件/防火墙拦 / 端口非法）：
+         *     此时**根本没有监听可保留**，只能老老实实改走设备码；
+         *   * `timeout` / `callback_first_wait` —— **不再自动改道**：
+         *     等待超时只如实报错（默认就是回调，不该因为等太久变设备码）。
+         *   * `--no-auto-device` 时**连 listen 兜底也关闭**（`canSwitch=false`）。
+         *   其它错误（换票失败、被拒绝、state 不匹配…）本来就不降级。
          */
-        const canSwitch =
-          autoDevice && !wantsDevice && (e.kind === 'callback_first_wait' || e.kind === 'timeout' || e.kind === 'listen');
+        const canSwitch = autoDevice && !wantsDevice && e.kind === 'listen';
         if (!canSwitch) throw e;
         log('');
-        const reason =
-          e.kind === 'timeout' ? '等待超时' : e.kind === 'listen' ? '本地端口监听失败' : '首轮等待没收到回调';
-        log(`⚠️ 本地回调没有等到结果（${reason}）：${e.message}`);
-        if (e.kind === 'callback_first_wait') {
-          log('ℹ️ 等了这一小段时间没收到回调，已自动改用**设备码模式**继续（不需要本地回调）。');
-        } else {
-          log('ℹ️ 已自动改用**设备码模式**继续授权（不需要本地回调）—— 常见原因是代理/防火墙挡了 127.0.0.1。');
-        }
+        log(`⚠️ 本地回调端口起不来（${e.message}）：这是"本地读不了回调"的真实失败，改用【设备码模式】继续授权。`);
+        log('ℹ️ 设备码不需要本地监听（常见原因是端口被安全软件/防火墙拦）；授权页照旧点「同意」即可。');
         let device;
         try {
           device = await requestDeviceCode({ config, deps: loginDeps });
         } catch (e2) {
-          throw bothPathsFailedError(e2, e.kind === 'timeout' ? 'callback_timeout' : 'callback_first_wait', {
+          throw bothPathsFailedError(e2, 'callback_listen_failed', {
             loginTimeoutMs: config.loginTimeoutMs,
           });
         }
@@ -702,12 +722,7 @@ export const loginCommand = {
         result = await pollDeviceToken({ config, log, deps: loginDeps, device });
         deletePendingDevice(pendingFile);
         useDevice = true;
-        downgradeReason =
-          e.kind === 'callback_first_wait'
-            ? 'callback_first_wait'
-            : e.kind === 'timeout'
-              ? 'callback_timeout'
-              : 'callback_listen_failed';
+        downgradeReason = 'callback_listen_failed';
       }
 
       if (deviceSide.reason) {
@@ -722,7 +737,8 @@ export const loginCommand = {
            *   这里只要把"最终模式/原因"如实记下来。
            */
           useDevice = true;
-          downgradeReason = deviceSide.reason === 'callback_timeout' ? 'callback_timeout' : 'callback_first_wait';
+          // 0.2.2 起整段超时不再交接，`deviceSide.reason` 只可能是显式首轮等待
+          downgradeReason = 'callback_first_wait';
         } else {
           /**
            * ★ 回调那条路**先**成功（本次修复的核心价值：用户后来点的那次【同意】真的换到了令牌）
@@ -775,9 +791,9 @@ export const loginCommand = {
       if (downgradeReason === 'proxy_detected')
         out.info('  （本次因"检测到系统代理"自动改用了设备码模式：不再依赖 127.0.0.1 回调，绕过列表写了什么也不作依据。）');
       if (downgradeReason === 'callback_first_wait')
-        out.info('  （回调模式首轮等待没收到回调，已自动改用设备码模式完成登录。）');
-      if (downgradeReason === 'callback_timeout' || downgradeReason === 'callback_listen_failed')
-        out.info('  （本地回调没成功，已自动改用设备码模式完成登录。）');
+        out.info('  （已按显式 --callback-first-wait：首轮等待没收到回调，已自动改用设备码模式完成登录。）');
+      if (downgradeReason === 'callback_listen_failed')
+        out.info('  （本地回调端口起不来，已自动改用设备码模式完成登录。）');
     }
     return data;
   },

package/lib/commands/billing.mjs

@@ -16,7 +16,7 @@
 import { withTrailingSlash } from '../config.mjs';
 import { UsageError, CliError, EXIT } from '../errors.mjs';
 import { formatMoney, formatTime } from '../format.mjs';
-import { openUrlForUser, browserPasteText, browserOpenedText, browserFailedHintLines } from '../login.mjs';
+import { openUrlForUser, browserPasteText, browserOpenedText, browserFailedHintLines, detectNonInteractive, nonInteractiveBrowserHintLines } from '../login.mjs';
 import { renderQrOptional } from '../qr.mjs';
 
 /**
@@ -266,13 +266,12 @@ export const walletRechargeCommand = {
     'amount-cents': { type: 'string', required: true, desc: '充值金额，单位**分**（最低 990 = ¥9.90；**不设上限**）' },
     'no-browser': { type: 'boolean', desc: '不自动打开浏览器（自动化/无桌面环境用；地址仍会打印并放在 pay_url 里）' },
     /**
-     * ★ 老板最终拍板走**传统路线**：默认**总是尝试打开**系统浏览器（人在终端与 AI 场景都一样），
-     *   所以本开关现在**与默认行为等价**。保留它只为两件事：
-     *     1. **显式语义**（脚本里写"我就是要弹"比依赖默认值更清楚）；
-     *     2. **兼容**既有脚本（不许删）。
-     * ⚠️ `--no-browser` 优先（关掉就是关掉，见 login.mjs 的 resolveBrowserIntent）。
+     * ★ 2026-10-21（老板反馈：CI 里弹了浏览器）：默认**只在人类终端**自动打开；
+     *   非交互/CI 环境（stdout 非 TTY / CI 环境变量 / `WKONGAI_CLI_NO_BROWSER=1`）**一律不打开**。
+     *   本开关保留只为显式语义与兼容（⚠️ 它压不过非交互判定）。
+     *   `--no-browser` 优先（关掉就是关掉，见 login.mjs 的 resolveBrowserIntent）。
      */
-    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）' },
+    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 仅在人类终端生效；CI/非交互环境仍不打开）' },
     'dry-run': { type: 'boolean', desc: '只打印将要做什么，不真的创建订单' },
   },
   async run(ctx) {
@@ -364,15 +363,20 @@ export const walletRechargeCommand = {
           spawnImpl: ctx.spawnImpl,
           platform: ctx.platform,
           verbose: !!(ctx.config && ctx.config.verbose),
-          /** ★ 与 login 同源的四个事实（见 login.mjs 的 resolveBrowserIntent） */
+          /** ★ 与 login 同源的多个事实（见 login.mjs 的 resolveBrowserIntent / detectNonInteractive） */
           isTTY: ctx.isTTY === true,
           json: out.json === true,
           forceOpen: flags.openBrowser === true,
           noBrowser: flags.noBrowser === true,
+          /** CI / 非交互判定（`CI` / `GITHUB_ACTIONS`… / `WKONGAI_CLI_NO_BROWSER=1`） */
+          env: ctx.env || {},
         },
         log: (m) => out.info(m),
       });
-      data.paste_text = browserPasteText(payUrl, { kind: 'pay' });
+      data.paste_text = browserPasteText(payUrl, {
+        kind: 'pay',
+        nonInteractive: data.open_browser.skipped_reason === 'non_interactive',
+      });
     }
 
     if (!out.json) {
@@ -386,6 +390,13 @@ export const walletRechargeCommand = {
         out.line(`  ${payUrl}`);
         if (flags.noBrowser === true) {
           out.info('  （已按 --no-browser 跳过自动打开）请把上面这一整行复制到浏览器地址栏打开。');
+        } else if (data.open_browser.skipped_reason === 'non_interactive') {
+          /**
+           * ★ 2026-10-21：非交互/CI 里**不弹**，给出可照做的下一步（收银台链接转给用户）。
+           *   绝不能走下面的"打开失败"提示 —— 我们**根本没试**，报失败会误导排障。
+           */
+          const reason = detectNonInteractive({ isTTY: ctx.isTTY === true, env: ctx.env || {} }).reason;
+          for (const line of nonInteractiveBrowserHintLines({ kind: 'pay', reason, cmdName: 'wkgeo', url: payUrl })) out.info(line);
         } else if (data.open_browser.opened) {
           // ★ 成功：明说"已经打开了"（老板最终拍板走传统路线：弹系统浏览器）
           out.line(browserOpenedText({ kind: 'pay' }));
@@ -450,6 +461,10 @@ export const walletRechargeCommand = {
        */
       if (flags.noBrowser === true) {
         out.notice('（已按 --no-browser 跳过自动打开）请手动复制 pay_url 到浏览器地址栏打开。');
+      } else if (data.open_browser.skipped_reason === 'non_interactive') {
+        // ★ 非交互/CI：没弹 ≠ 失败。把"链接交给用户"说清楚（stdout 仍然只有 JSON）。
+        const reason = detectNonInteractive({ isTTY: ctx.isTTY === true, env: ctx.env || {} }).reason;
+        for (const line of nonInteractiveBrowserHintLines({ kind: 'pay', reason, cmdName: 'wkgeo', url: payUrl })) out.notice(line);
       } else if (data.open_browser.opened) {
         out.notice(browserOpenedText({ kind: 'pay' }));
       } else {
@@ -584,11 +599,13 @@ export const walletRechargeLinkCommand = {
           spawnImpl: ctx.spawnImpl,
           platform: ctx.platform,
           verbose: !!(ctx.config && ctx.config.verbose),
-          /** 与 login / wallet recharge 同源的四个事实（见 resolveBrowserIntent） */
+          /** 与 login / wallet recharge 同源的多个事实（见 resolveBrowserIntent / detectNonInteractive） */
           isTTY: ctx.isTTY === true,
           json: out.json === true,
           forceOpen: true,
           noBrowser: flags.noBrowser === true,
+          /** ★ CI / 非交互判定：CI 里即使写了 --open-browser 也不弹（见 login.mjs） */
+          env: ctx.env || {},
         },
         log: (m) => out.info(m),
       });
@@ -607,6 +624,10 @@ export const walletRechargeLinkCommand = {
       out.info('  （不需要登录会员中心；本命令不会代替他付款，也不会模拟支付成功。）');
       if (flags.noBrowser === true) {
         out.info('  （已按 --no-browser 跳过自动打开）');
+      } else if (data.open_browser.skipped_reason === 'non_interactive') {
+        // ★ 非交互/CI：明确说"没弹"，并让用户把链接发给有浏览器的人（不是打开失败）
+        const reason = detectNonInteractive({ isTTY: ctx.isTTY === true, env: ctx.env || {} }).reason;
+        for (const line of nonInteractiveBrowserHintLines({ kind: 'pay', reason, cmdName: 'wkgeo', url: payUrl })) out.info(line);
       } else if (data.open_browser.attempted === false) {
         out.info('  （默认不自动打开浏览器；需要在这台机器上弹出，请加 --open-browser）');
       } else if (data.open_browser.opened) {
@@ -626,6 +647,9 @@ export const walletRechargeLinkCommand = {
         out.notice(
           '（默认不自动打开浏览器；需要在这台机器上弹出请加 --open-browser。把上面的链接发给用户即可。）',
         );
+      } else if (data.open_browser.skipped_reason === 'non_interactive') {
+        const reason = detectNonInteractive({ isTTY: ctx.isTTY === true, env: ctx.env || {} }).reason;
+        for (const line of nonInteractiveBrowserHintLines({ kind: 'pay', reason, cmdName: 'wkgeo', url: payUrl })) out.notice(line);
       } else if (data.open_browser.opened) {
         out.notice(browserOpenedText({ kind: 'pay' }));
       } else {

package/lib/device.mjs

@@ -52,7 +52,7 @@ import { writeCredentials, credentialsFromToken } from './credentials.mjs';
 import { withTrailingSlash } from './config.mjs';
 import { canonicalOauthUrl } from './oauth-urls.mjs';
 import { CliError, EXIT, loginHint } from './errors.mjs';
-import { defaultOpenBrowser, resolveBrowserIntent, browserOpenedText, browserFailedHintLines } from './login.mjs';
+import { defaultOpenBrowser, resolveBrowserIntent, browserOpenedText, browserFailedHintLines, detectNonInteractive, nonInteractiveBrowserHintLines } from './login.mjs';
 
 /** RFC 8628 规定的 urn */
 export const DEVICE_GRANT_TYPE = 'urn:ietf:params:oauth:grant-type:device_code';
@@ -266,15 +266,18 @@ export function announceDeviceCode({ config, log = () => {}, deps = {}, device,
   /**
    * ★ 走**同一个闸门**（`resolveBrowserIntent`，与 login 回调模式、钱包充值完全同一份逻辑）。
    *
-   * ★ 老板最终拍板走**传统路线**：**默认总是尝试打开**系统浏览器（设备码模式同样如此，
-   *   人在终端与 AI 场景都一样）；唯一的"不打开"开关是 `--no-browser`。
-   *   （历史：2026-10-01 曾改成"只有人在终端才弹"，那版已按老板最终决定回退。）
+   * ★ 2026-10-21（老板反馈：CI 里弹了浏览器）：**人在终端默认打开**；
+   *   非交互/CI（stdout 非 TTY / CI 环境变量 / `WKONGAI_CLI_NO_BROWSER=1`）与 `--no-browser`
+   *   都不打开。设备码模式尤其适合非交互环境（不需要任何本地回调），所以这里只要
+   *   把链接/短码交给用户即可 —— 绝不能因为"没弹浏览器"中断流程。
+   *   （历史：2026-10-01 曾改成"只有人在终端才弹"；2026-10-02 又默认总弹；本次是第三版。）
    */
   const browserIntent = resolveBrowserIntent({
     isTTY: deps.isTTY === true,
     json: deps.json === true,
     forceOpen: deps.forceBrowser === true,
     noBrowser: deps.openBrowser === false || deps.noBrowser === true,
+    env: deps.env && typeof deps.env === 'object' ? deps.env : {},
   });
   if (browserIntent.allow) {
     // 传入函数时用注入的（测试/自定义）；否则用**真·打开浏览器**
@@ -297,6 +300,23 @@ export function announceDeviceCode({ config, log = () => {}, deps = {}, device,
   } else if (browserIntent.skipped_reason === 'no_browser') {
     // 用户主动关掉的，不该报"失败"
     log('（已按 --no-browser 跳过自动打开）');
+  } else if (browserIntent.skipped_reason === 'non_interactive') {
+    /**
+     * ★ 非交互（CI / 管道 / AI 子进程）：**不弹**，但把"下一步"说清楚。
+     *   设备码模式在 CI 里本来就能用（只要用户在自己的浏览器里确认），
+     *   所以这里只提示"把地址/短码交给用户"，**不建议**再改模式。
+     */
+    const reason = detectNonInteractive({
+      isTTY: deps.isTTY === true,
+      env: deps.env && typeof deps.env === 'object' ? deps.env : {},
+    }).reason;
+    for (const line of nonInteractiveBrowserHintLines({
+      kind: 'auth',
+      reason,
+      cmdName: config.cmdName || 'wkgeo',
+    })) {
+      log(line);
+    }
   }
   return pasteText;
 }