wkgeo-cli 0.2.3 → 0.2.4

package/lib/commands/auth.mjs

@@ -70,10 +70,11 @@ export function resolveAutoDevice(flags = {}, env = {}) {
  *   ⇒ 本函数**不再**按"有没有代理"给默认值：用户没显式指定时**一律返回 0**。
  *     也就是说 `wkgeo login` 默认会一路等回调到 `--timeout`，**不会**因为等太久自动改设备码。
  *
- * 设备码只在这三种情况出现（见 loginCommand.run）：
+ * 设备码只在这两种情况出现（见 loginCommand.run）：
  *   1. 用户显式 `--device` / `--no-wait` / `--device-continue`；
- *   2. 检测到系统代理且判定回调不可用（`--no-auto-device` 可关）；
- *   3. 本地回调端口**真的起不来**（`kind = 'listen'`，真实失败兜底；`--no-auto-device` 可关）。
+ *   2. 检测到系统代理且判定回调不可用（`--no-auto-device` 可关）。
+ *   ⚠️ 0.2.4 起：**本地回调端口起不来不再自动改设备码**（老板反馈"服务没起来却换了模式"），
+ *      而是如实报 `kind:"listen"` 并在 hint 里明确建议用户显式加 `--device`。
  *
  * ## 保留的显式开关（向后兼容，不参与默认判断）
  *   `--callback-first-wait <时长>`（默认单位**秒**；`0` / `off` / `none` = 关闭）
@@ -192,9 +193,7 @@ 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,
@@ -216,13 +215,13 @@ const TERMINAL_DEVICE_KINDS = new Set(['denied', 'expired', 'not_implemented', '
 
 export const loginCommand = {
   name: 'login',
-  summary: '浏览器授权一次，把 30 天令牌存到本地（默认本地回调模式；设备码仅在本地无法回调/检测到代理时兜底）',
+  summary: '浏览器授权一次，把 30 天令牌存到本地（默认本地回调模式；设备码仅在显式 --device / 检测到系统代理时使用）',
   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 --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 秒没回调就并行改设备码"（默认关闭；0/off = 关闭）\n' +
     'wkgeo login --timeout 600     # 等待授权 600 秒（默认单位是秒，不是毫秒；也支持 600s / 500ms）',
@@ -237,7 +236,7 @@ export const loginCommand = {
      *   ⚠️ 它**压不过**非交互判定（CI 里写它也不弹）；与 `--no-browser` 同时出现时 `--no-browser` 优先。
      */
     'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 仅在人类终端生效；CI/非交互环境仍不打开）' },
-    device: { type: 'boolean', desc: '用设备码模式（RFC 8628）代替本地回调：不需要任何回调地址，对代理/防火墙免疫（本地读不了回调时的兜底）' },
+    device: { type: 'boolean', desc: '用设备码模式（RFC 8628）代替本地回调：不需要任何回调地址，对代理/防火墙免疫（显式兜底；CLI 不会在端口失败时自动切换过来）' },
     /**
      * ★ 老板 2026-10-02 要的"AI 端友好路径"。
      * 为什么做成"申请完就退出"而不是"申请完继续挂着轮询"（后者靠 JSONL 事件流也能做）：
@@ -250,7 +249,7 @@ 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 关闭，关闭时会警告"代理可能吃掉回调"）',
     },
     /**
      * ★ 可选自愈（默认**关闭**，0.2.2 起）。
@@ -345,7 +344,7 @@ export const loginCommand = {
      */
     const proxyDetected = !!(proxyInfo && proxyInfo.detected);
     let useDevice = wantsDevice;
-    /** 为什么会走设备码：proxy_detected / callback_listen_failed / callback_first_wait（仅显式开启时） */
+    /** 为什么会走设备码：proxy_detected / callback_first_wait（仅显式开启时） */
     let downgradeReason = null;
     if (!useDevice && autoDevice && proxyDetected) {
       useDevice = true;
@@ -414,7 +413,7 @@ export const loginCommand = {
      *
      * 老板原话：「默认的也不应该是设备授权，默认的就是那个传统的授权方式（浏览器打开授权页 +
      * 本地 localhost 回调）。设备码是本地读不了/代理时才用的。」
-     * ⇒ 这里明说"本次就是回调、等多久都不会自动改设备码"，同时列出**唯一会走设备码**的三种情况，
+     * ⇒ 这里明说"本次就是回调、等多久都不会自动改设备码"，同时列出**唯一会走设备码**的两种情况，
      *   并给出"主动提前切换"的显式开关，免得用户以为 CLI 背着他改道。
      * ⚠️ 只在"回调模式 + 没检测到代理 + 没显式开首轮等待"时打：其它情况一律不打（正常环境不要噪音）。
      */
@@ -423,10 +422,12 @@ export const loginCommand = {
         `ℹ️ 未检测到系统代理：本次使用浏览器回调授权（默认），会一直等你完成授权（最多 ${Math.round(config.loginTimeoutMs / 1000)} 秒）。`,
       );
       log(
-        '   不会因为"首轮等待/等待超时"到点就自动改用设备码；只有显式 `--device`、检测到系统代理、' +
-          '或本地回调端口真的起不来时才会用设备码（`--no-auto-device` 可关掉后两种自动兜底）。',
+        '   不会因为"首轮等待/等待超时"到点就自动改用设备码；只有显式 `--device` 或检测到系统代理时才会用设备码' +
+          '（`--no-auto-device` 可关掉代理这一种自动切换）。',
+      );
+      log(
+        '   （本地回调端口起不来会**如实报错**并建议 `--device`，不会静默换模式；想主动提前切换：`--callback-first-wait <秒>`。）',
       );
-      log('   （想主动提前切换：`--callback-first-wait <秒>`；想直接走设备码：`--device`。）');
     }
 
     /**
@@ -694,35 +695,18 @@ export const loginCommand = {
         /** 设备码那条路也失败了 ⇒ 优先报"两条路都不通"（哪怕回调那边先抛了自己的错） */
         if (deviceSide.combinedError) throw deviceSide.combinedError;
         /**
-         * ★★ 0.2.2 起：**只有"本地回调端口真的起不来"（`kind = 'listen'`）才自动兜底设备码**。
-         *   （老板：「设备码是本地读不了/代理时才用的」—— 连监听都起不来就是"本地读不了"。）
-         *   * `listen` —— 回环端口起不来（被安全软件/防火墙拦 / 端口非法）：
-         *     此时**根本没有监听可保留**，只能老老实实改走设备码；
-         *   * `timeout` / `callback_first_wait` —— **不再自动改道**：
-         *     等待超时只如实报错（默认就是回调，不该因为等太久变设备码）。
-         *   * `--no-auto-device` 时**连 listen 兜底也关闭**（`canSwitch=false`）。
-         *   其它错误（换票失败、被拒绝、state 不匹配…）本来就不降级。
+         * ★★ 0.2.4（2026-10-21 老板真机反馈）：**bind 失败不再静默改走设备码**。
+         *
+         * 旧行为（0.2.2~0.2.3）：本地回调端口起不来 → 命令层自动申请设备码继续授权。
+         * 现场问题是：用户明明要的是"本地服务 + 浏览器回调"，CLI 却在他不知情时换了
+         * 另一套授权协议（设备码），127.0.0.1 回调页始终没有出现，看起来就是"本地服务
+         * 没启动、浏览器也没东西可打开"。
+         *
+         * 新口径：**如实失败**，把 `--device` 作为明确的下一步建议交给用户/调用方
+         * （`runLogin` 抛的 `kind:"listen"` 错误 hint 里已经写了）。
+         * 设备码只在这两种情况下出现：用户显式 `--device` / 检测到系统代理。
          */
-        const canSwitch = autoDevice && !wantsDevice && e.kind === 'listen';
-        if (!canSwitch) throw e;
-        log('');
-        log(`⚠️ 本地回调端口起不来（${e.message}）：这是"本地读不了回调"的真实失败，改用【设备码模式】继续授权。`);
-        log('ℹ️ 设备码不需要本地监听（常见原因是端口被安全软件/防火墙拦）；授权页照旧点「同意」即可。');
-        let device;
-        try {
-          device = await requestDeviceCode({ config, deps: loginDeps });
-        } catch (e2) {
-          throw bothPathsFailedError(e2, 'callback_listen_failed', {
-            loginTimeoutMs: config.loginTimeoutMs,
-          });
-        }
-        savePending(device);
-        announceDeviceCode({ config, log, deps: deviceDeps({ no_wait: false, proxy_warning: proxyPayload }), device });
-        // 这一次再失败就如实抛出（不无限重试：两条路都失败，用户该看到真原因了）
-        result = await pollDeviceToken({ config, log, deps: loginDeps, device });
-        deletePendingDevice(pendingFile);
-        useDevice = true;
-        downgradeReason = 'callback_listen_failed';
+        throw e;
       }
 
       if (deviceSide.reason) {
@@ -792,8 +776,6 @@ export const loginCommand = {
         out.info('  （本次因"检测到系统代理"自动改用了设备码模式：不再依赖 127.0.0.1 回调，绕过列表写了什么也不作依据。）');
       if (downgradeReason === 'callback_first_wait')
         out.info('  （已按显式 --callback-first-wait：首轮等待没收到回调，已自动改用设备码模式完成登录。）');
-      if (downgradeReason === 'callback_listen_failed')
-        out.info('  （本地回调端口起不来，已自动改用设备码模式完成登录。）');
     }
     return data;
   },

package/lib/commands/billing.mjs

@@ -348,7 +348,8 @@ export const walletRechargeCommand = {
     /**
      * 自动打开收银台。
      *
-     * ⚠️ 复用 `login.mjs` 的 `openUrlForUser`（多策略 + 结果归一化 + ★「默认总是尝试打开」闸门），
+     * ⚠️ 复用 `login.mjs` 的 `openUrlForUser`（多策略 + 结果归一化 + 唯一闸门：
+     *    人类终端默认打开，CI/非交互与 `--no-browser` 不打开），
      *    **不是**在这里再写一份 spawn —— 那几个坑（cmd start 的引号、URL 里的 `&`
      *    被 shell 吃掉、error 事件没挂）在那边已经踩过并修过，复制一份必然会再踩。
      * ⚠️ 打开失败**绝不允许**让命令失败：地址已经完整打印（人类可读）并放在

package/lib/login.mjs

@@ -40,6 +40,7 @@
 
 import http from 'node:http';
 import { spawn } from 'node:child_process';
+import { win32 as pathWin32 } from 'node:path';
 import { URL } from 'node:url';
 
 import { createApi } from './api.mjs';
@@ -99,6 +100,63 @@ import { CliError, EXIT } from './errors.mjs';
  *    ② 虽是"用户双击"路径、命中率最高，却带上面那个残余解析风险，所以只在前一条不可用时
  *    才启用；③ 收尾。这样单条失败**不再等于**整个自动打开失败（这正是这次要修的问题）。
  */
+/**
+ * ★★ 2026-10-21（老板真机反馈「Application not found，浏览器没打开」）：Windows 默认处理器
+ *    坏了的时候，**不能只依赖 rundll32 / cmd start / powershell**——它们可能报告"应用未找到"
+ *    却仍然以退出码 0 结束（静默失败），于是后面的策略根本不会被尝试。
+ *
+ * ⇒ 在三条通用策略之后追加 **Chrome / Edge 的绝对路径**（不经过任何 shell、不依赖文件关联）。
+ *   路径覆盖 32/64 位安装位置与用户级安装（LOCALAPPDATA）；某个路径不存在时 spawn 会立刻
+ *   ENOENT，`openInBrowserWithFallback` 会静默试下一条，不会打扰用户。
+ *
+ * ⚠️ 顺序保持"默认处理器优先"：用户平时登录态在默认浏览器里，直接抢开 Chrome 会让他
+ *    重新登录一遍（体验更差）。所以绝对路径只能排在通用策略**之后**当兜底。
+ * ⚠️ 这里用 `path.win32.join` 而不是 `path.join`：在非 Windows 上跑单测时也必须拼出
+ *    Windows 风格路径，否则断言会随运行平台变化。
+ *
+ * @param {object} [env] 环境变量（默认 process.env；单测可注入确定性的路径）
+ * @returns {Array<{label:string, cmd:string, args:(url:string)=>string[]}>}
+ */
+export function windowsAbsoluteBrowserStrategies(env = process.env) {
+  const source = env && typeof env === 'object' ? env : {};
+  const programFiles = source.ProgramFiles || source.PROGRAMFILES || 'C:\\Program Files';
+  const programFilesX86 = source['ProgramFiles(x86)'] || source['PROGRAMFILES(X86)'] || 'C:\\Program Files (x86)';
+  const localAppData = source.LOCALAPPDATA || source.LocalAppData || '';
+  /** 安装根 + 诊断标签：先 Program Files / x86，再用户级 LOCALAPPDATA */
+  const roots = [
+    { label: 'Program Files', root: programFiles },
+    { label: 'Program Files (x86)', root: programFilesX86 },
+  ];
+  if (localAppData) roots.push({ label: 'LOCALAPPDATA', root: localAppData });
+  const strategies = [];
+  // Chrome 在前（老板/大多数国内用户桌面 Chrome 命中率最高），Edge 在后
+  for (const { label, root } of roots) {
+    strategies.push({
+      label: `chrome · ${label}`,
+      cmd: pathWin32.join(root, 'Google', 'Chrome', 'Application', 'chrome.exe'),
+      args: (url) => [url],
+    });
+  }
+  for (const { label, root } of roots) {
+    strategies.push({
+      label: `edge · ${label}`,
+      cmd: pathWin32.join(root, 'Microsoft', 'Edge', 'Application', 'msedge.exe'),
+      args: (url) => [url],
+    });
+  }
+  return strategies;
+}
+
+/**
+ * 通用 Windows 启动器"其实没打开"的输出特征（老板真机报的就是 `Application not found`）。
+ *
+ * 为什么要看输出而不是只看退出码：`rundll32` / `cmd start` 在文件关联坏掉时可能**退出码 0**，
+ * 但 stderr/stdout 里已经写了找不到应用。只信退出码就会把它当成功，绝对路径兜底永远不会触发
+ * ——这正是这次要修的那条真机故障。见 `launchStrategy` 的 captureOutput 分支。
+ */
+const WINDOWS_HANDLER_FAILURE_PATTERN =
+  /application not found|windows cannot find|cannot find the file|系统找不到|找不到应用程序|不是内部或外部命令|no application is associated/i;
+
 export const BROWSER_STRATEGY_TABLE = {
   /**
    * ⚠️⚠️ Windows 第 ② 条（`cmd /c start`）的**引号**是必须的（老板真机踩过，见上面那段记录）：
@@ -116,11 +174,31 @@ export const BROWSER_STRATEGY_TABLE = {
    */
   win32: [
     // ① 最稳的一条：不经任何 shell，URL 作为独立 argv 逐字符原样交给系统（线上实测能弹浏览器的那条）
-    { label: 'rundll32 url.dll,FileProtocolHandler', cmd: 'rundll32', args: (url) => ['url.dll,FileProtocolHandler', url] },
+    {
+      label: 'rundll32 url.dll,FileProtocolHandler',
+      cmd: 'rundll32',
+      args: (url) => ['url.dll,FileProtocolHandler', url],
+      captureOutput: true,
+      failureOutputPattern: WINDOWS_HANDLER_FAILURE_PATTERN,
+    },
     // ② 兜底：命令与引号写法**保持原样**（引号必须在字符串里）；它要经 cmd 解析，存在"退出码 0 却截断 URL"的残余风险，所以不排第一
-    { label: 'cmd /c start', cmd: 'cmd', args: (url) => ['/c', `start "" "${url}"`] },
+    {
+      label: 'cmd /c start',
+      cmd: 'cmd',
+      args: (url) => ['/c', `start "" "${url}"`],
+      captureOutput: true,
+      failureOutputPattern: WINDOWS_HANDLER_FAILURE_PATTERN,
+    },
     // ③ 前两条都哑了时的最后一条
-    { label: 'powershell Start-Process', cmd: 'powershell', args: (url) => ['-NoProfile', '-Command', `Start-Process '${url}'`] },
+    {
+      label: 'powershell Start-Process',
+      cmd: 'powershell',
+      args: (url) => ['-NoProfile', '-Command', `Start-Process '${url}'`],
+      captureOutput: true,
+      failureOutputPattern: WINDOWS_HANDLER_FAILURE_PATTERN,
+    },
+    // ④~⑨ 默认处理器/文件关联坏掉时的绝对路径兜底（Chrome / Edge，见 windowsAbsoluteBrowserStrategies）
+    ...windowsAbsoluteBrowserStrategies(),
   ],
   darwin: [
     { label: 'open', cmd: 'open', args: (url) => [url] },
@@ -191,9 +269,21 @@ export function strategiesFor(platform, strategies) {
   return BROWSER_STRATEGY_TABLE[platform] || FALLBACK_STRATEGIES;
 }
 
-/** 子进程的固定选项：不继承 stdio、独立进程组（CLI 退出后浏览器继续活着）、不闪黑框 */
-function browserSpawnOptions() {
-  return { stdio: 'ignore', detached: true, windowsHide: true };
+/**
+ * 子进程的固定选项：独立进程组（CLI 退出后浏览器继续活着）、不闪黑框。
+ *
+ * ★ 0.2.4：只有**异步多策略**链路里、且策略声明了 `captureOutput` 时才接管输出
+ *   （用来识别 Windows 通用启动器"退出码 0 但输出 Application not found"的静默失败）。
+ *   同步版 `openInBrowser`（device.mjs 用）必须保持 `stdio:'ignore'` —— 它不消费管道，
+ *   接管输出反而可能把子进程的管道缓冲区写满。
+ */
+function browserSpawnOptions(strategy = null, { captureOutput = false } = {}) {
+  const capture = captureOutput === true && strategy && strategy.captureOutput === true;
+  return {
+    stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'ignore',
+    detached: true,
+    windowsHide: true,
+  };
 }
 
 /**
@@ -333,16 +423,30 @@ function launchStrategy(strategy, target, spawnImpl, timeoutMs) {
   return new Promise((resolve) => {
     let settled = false;
     let timer = null;
+    /** ★ 0.2.4：Windows 通用启动器的输出（最多留 4KB，只为识别"Application not found"） */
+    let output = '';
+    let child = null;
     const settle = (result) => {
       if (settled) return;
       settled = true;
       if (timer) clearTimeout(timer);
+      // 超时/退出后把管道关掉：否则 pipe 句柄可能把 CLI 的事件循环多吊一会儿
+      for (const stream of [child && child.stdout, child && child.stderr]) {
+        try {
+          if (stream && typeof stream.destroy === 'function') stream.destroy();
+        } catch {
+          /* 清理失败不影响结论 */
+        }
+      }
       resolve(result);
     };
 
-    let child;
     try {
-      child = spawnImpl(strategy.cmd, strategy.args(target), browserSpawnOptions());
+      child = spawnImpl(
+        strategy.cmd,
+        strategy.args(target),
+        browserSpawnOptions(strategy, { captureOutput: strategy.captureOutput === true }),
+      );
     } catch (e) {
       resolve({ ok: false, error: e });
       return;
@@ -352,6 +456,20 @@ function launchStrategy(strategy, target, spawnImpl, timeoutMs) {
       return;
     }
 
+    if (strategy.captureOutput === true) {
+      const collect = (chunk) => {
+        if (output.length >= 4096) return;
+        output += String(chunk).slice(0, 4096 - output.length);
+      };
+      for (const stream of [child.stdout, child.stderr]) {
+        if (stream && typeof stream.on === 'function') {
+          // 流错误（管道提前关闭等）不能变成未捕获异常把 CLI 崩掉
+          stream.on('error', () => {});
+          stream.on('data', collect);
+        }
+      }
+    }
+
     timer = setTimeout(() => settle({ ok: true, timedOut: true }), timeoutMs);
 
     if (typeof child.on === 'function') {
@@ -359,7 +477,21 @@ function launchStrategy(strategy, target, spawnImpl, timeoutMs) {
       child.on('error', (e) => settle({ ok: false, error: e }));
       // 进程正常退出才算成功：非零退出码意味着"它自己认为没干成"（例如 xdg-open 找不到浏览器）
       child.on('exit', (code, signal) => {
-        if (code === 0) return settle({ ok: true });
+        if (code === 0) {
+          /**
+           * ★ 0.2.4：退出码 0 **不等于**浏览器真的打开了 —— Windows 上文件关联坏掉时，
+           *   rundll32 / cmd start 会打出 `Application not found` 却仍然返回 0。
+           *   这里把这种"静默失败"识别出来，交给下一条（Chrome/Edge 绝对路径）兜底。
+           */
+          const pattern = strategy.failureOutputPattern;
+          if (pattern instanceof RegExp && output && pattern.test(output)) {
+            return settle({
+              ok: false,
+              error: new Error(`退出码 0，但输出表明没有打开：${output.trim().replace(/\s+/g, ' ').slice(0, 160)}`),
+            });
+          }
+          return settle({ ok: true });
+        }
         settle({ ok: false, error: new Error(`退出码 ${code}${signal ? `（信号 ${signal}）` : ''}`) });
       });
     } else {
@@ -808,13 +940,10 @@ export async function runLogin({ config, log = () => {}, deps = {} }) {
   /**
    * ★★ 最终是否自动打开系统浏览器 = **唯一闸门**的结论。
    *
-   * ★ 本次变更（老板最终拍板）：「**总是尝试打开**」重新成为默认 ——
-   *   人在终端 ✔、AI 场景（非 TTY / `--json`）✔ 都打开；`json` / `isTTY` **不再**是"不打开"的理由。
-   *   唯一的"不打开"开关是 `--no-browser`（AI 端不想弹窗就用它）。
-   *   为什么回到传统路线（原话）：
-   *     「还是返回以前那种打开跳到一个浏览器，然后打开授权那个吧，大家也都是那个的。
-   *       我们在右侧这个……能力还不会太完善……还是走传统的路吧。」
-   *   ⇒ 稳定（成熟的系统启动器）+ `window.close()` 在独立浏览器里生效（页面能自己关）。
+   * ★ 2026-10-21（老板真机反馈「CI 里 login 弹了浏览器」）：
+   *   **人类终端**默认打开；**非交互 / CI**（stdout 非 TTY / CI 环境变量 /
+   *   `WKONGAI_CLI_NO_BROWSER=1`）与 `--no-browser` 都不打开。
+   *   `json` / `isTTY` 不再决定"要不要弹"（`json` 只影响 `mode` 诊断字段）。
    * ⚠️ 无论哪种情况，**绝不**因为"没打开浏览器"让登录失败 —— 地址一直完整打印，回调照旧等。
    */
   const shouldOpenBrowser = browserIntent.allow;
@@ -1214,23 +1343,68 @@ export async function runLogin({ config, log = () => {}, deps = {} }) {
       server.listen(port, config.callbackHost);
     });
 
+  /**
+   * ★★ 0.2.4（老板真机反馈）：端口优先 53682；被占用就自动换系统分配的空闲端口；
+   *    **bind 彻底失败时只报明确错误 + `--device` 建议，绝不静默改走设备码**
+   *    （设备码是另一条授权协议，用户没要求时不能替他换；命令层也不再兜底，见 commands/auth.mjs）。
+   */
+  const preferredPort = deps.listenPort ?? config.callbackPort;
+  const buildListenError = (cause, { afterFallback = false } = {}) => {
+    const what = afterFallback
+      ? `首选端口 ${preferredPort} 被占用后，系统分配端口也无法监听`
+      : `无法在 ${config.callbackHost}:${preferredPort} 上监听本地回调服务`;
+    const codeText = cause && cause.code ? `（${cause.code}）` : '';
+    return new CliError(`${what}${codeText}：${(cause && cause.message) || cause}`, {
+      kind: 'listen',
+      hint:
+        '本地回调服务没有启动，所以不会打开浏览器。请检查端口占用/防火墙，或用 --callback-port 指定其它端口；' +
+        `若本机确实无法监听回环地址，请显式改用 \`${config.cmdName || 'wkgeo'} login --device\`（设备码模式，不需要本地回调）` +
+        (proxyHint ? `。另外：${proxyHint}` : ''),
+      cause,
+    });
+  };
+
   let bound;
   try {
-    bound = await listenOn(deps.listenPort ?? config.callbackPort);
+    bound = await listenOn(preferredPort);
   } catch (e) {
-    if (e && e.code === 'EADDRINUSE') {
-      log(`端口 ${config.callbackPort} 被占用，改用随机回环端口（服务端按 RFC 8252 忽略端口，仍能回调成功）`);
-      bound = await listenOn(0);
+    if (e && e.code === 'EADDRINUSE' && Number(preferredPort) !== 0) {
+      log(`⚠️ 回调端口 ${preferredPort} 已被占用，自动改用系统分配的空闲端口（redirect_uri 会使用实际监听端口）`);
+      try {
+        bound = await listenOn(0);
+      } catch (e2) {
+        throw buildListenError(e2, { afterFallback: true });
+      }
     } else {
-      throw new CliError(`无法在 ${config.callbackHost} 上监听回调端口：${e.message}`, {
-        kind: 'listen',
-        hint: `检查防火墙/端口占用，或用 --callback-port 指定其它端口${proxyHint ? `。另外：${proxyHint}` : ''}`,
-        cause: e,
-      });
+      throw buildListenError(e);
     }
   }
   const actualPort = bound.port;
+  /**
+   * ⚠️ 顺序硬保证（0.2.4）：**监听真的成功**之后才允许构造/打印授权地址、才允许打开浏览器。
+   *    理论上 `listenOn` resolve 时 server 一定处于 listening；这里再核一次，是为了让
+   *    "服务没起来却把浏览器弹出去"这类故障在代码层**不可能**发生（而不是靠调用顺序的自觉）。
+   */
+  if (!server.listening) {
+    // 极端防御：真走到这里说明监听状态丢了 —— 先尽量关掉，再明确报错（绝不弹浏览器）
+    try {
+      server.close();
+    } catch {
+      /* 本来就没监听，忽略 */
+    }
+    throw new CliError('本地回调服务没有进入监听状态，已取消打开浏览器', {
+      kind: 'listen',
+      hint:
+        `请重新运行 \`${config.cmdName || 'wkgeo'} login\`；若仍失败，改用 \`${config.cmdName || 'wkgeo'} login --device\`（设备码模式，不需要本地回调）`,
+    });
+  }
   redirectUri = `http://${config.callbackHost}:${actualPort}${config.callbackPath}`;
+  /**
+   * ★★ 老板要求的可观测证据（0.2.4）：先明确告诉用户"本地服务已经在监听"，再谈浏览器。
+   *    顺序是：listen 成功 → 这行日志 → 打印授权网址 → 尝试打开浏览器。
+   *    用户/排障者因此能一眼分辨"服务没起来"和"浏览器没打开"这两类完全不同的故障。
+   */
+  log(`✅ 回调服务已启动 ${redirectUri}`);
   const authUrl = new URL(authorizeBase);
   authUrl.searchParams.set('client_id', config.clientId);
   authUrl.searchParams.set('redirect_uri', redirectUri);

package/lib/page.mjs

@@ -21,9 +21,10 @@
  *   3. **不依赖 JavaScript**：正文（结论 + 账号 + 兜底文案）全部是静态 HTML + CSS。
  *      这个页面出现的时机很敏感（用户刚在同意页点完"同意"），任何脚本报错
  *      都会让人以为授权失败，所以脚本只能做**锦上添花**的事，绝不能承载信息。
- *      目前唯一的脚本是**成功页**上的"尝试自动关闭标签页"（见 `AUTO_CLOSE_SCRIPT`）：
+ *      目前唯一的脚本是"尝试自动关闭标签页"（见 `autoCloseScript`）：
  *      它失败 / 被浏览器拒绝 / 被用户插件拦掉，页面照旧完整可读。
- *      ⚠️ 它**只**出现在成功页（那是换到令牌、凭据写盘之后的页），错误页一律没有脚本。
+ *      ⚠️ 0.2.4 起成功页与失败页都会带它（老板反馈「页面关不掉」），
+ *      差别只在延迟（成功 1.2s / 失败 6s），正文永远是静态可读的。
  *   4. **所有动态内容必须转义**（`escapeHtml`）。账号标识来自服务端 `userinfo`，
  *      其中昵称是**用户自己可控**的字符串，直接拼进 HTML 就等于在本机页面上
  *      开一个自伤型 XSS（本机页面同样能去访问 `http://127.0.0.1` 上的其它服务）。
@@ -168,43 +169,27 @@ function badgeSvg(tone) {
 }
 
 /**
- * 「尝试自动关闭标签页」的极简内联脚本 —— **只给"确实成功"的成功页用**。
+ * 「尝试自动关闭标签页」的极简内联脚本。
  *
  * ## 为什么加这段（老板 2026-10-01 对比阿里云 MCP 的实测结论）
  *   老板的原话：阿里云那套"点完授权，页面**自动就关了**，这样看着很正常"。
- *   我们的现状是：跳回本机后留一张成功页，**要用户自己动手关**——不够顺。
+ *   我们的现状是：跳回本机后留一张页面，**要用户自己动手关**——不够顺。
  *
- * ## 🔴 但我们**不抄它的时机**（这是它源码里实打实的坑）
- *   阿里云 `mcp-remote` 是在本地回调**刚收到 `code`** 的那一刻就把页面发回去、
- *   页面立刻 `window.close()`，而此刻它还**没有 POST token 端点换令牌**：
- *     `authCompletedResolve(code); res.send('Authorization successful! …<script>window.close();</script>')`
- *   —— 一旦接下来换票失败，用户已经被打发走了（窗口都关了），却只记得"它说我成功了"。
- *   所以本项目的口径是：
- *     * **只有** CLI 真的换到令牌、并且凭据已经写进本机之后的**那张成功页**才尝试关闭
- *       （对应 `login.mjs` 里 `api.token(...)` → `writeCredentials(...)` → `successPage(...)`
- *        这个顺序，**不许调换**）；
- *     * 中间态页面（例如"正在换取令牌…"）即使将来真加了，也**不自动关闭**，统一由成功页收尾；
- *     * 错误页（state 失败 / 缺少授权码 / 授权未完成·拒绝 / 换票失败 / 405）**一律不关**，
- *       详见 `errorPage` 的说明。
+ * ## 0.2.4（2026-10-21 老板反馈「127 那个页面关不掉」）
+ *   **授权成功页和失败页都要能自动关闭**，避免用户卡在一个已经结束的页面上。
+ *   页面仍然保留「本页面可以关闭了 / 直接关闭标签页」的兜底文案（浏览器只允许脚本关闭
+ *   **由脚本打开的**窗口，我们这张页大概率关不掉，文案就是兜底）。
+ *   * 成功页：延迟 1.2 秒关（先让用户看清「授权成功」再关，上来就关会让人以为页面崩了）；
+ *   * 失败页：延迟 6 秒关（失败原因要留够时间看清楚，但绝不能永远留在屏幕上）。
  *
- * ## ⚠️ 另一个关键事实：这一段**大概率关不掉**，所以它是"尽力而为 + 兜底文案"
- *   浏览器有一条硬规则：**只允许脚本关闭"由脚本打开的窗口"**（`window.open` 打开的那类）。
- *   我们这张页面是用户点同意后由**系统命令打开的那个浏览器**里导航过来的
- *   （`openInBrowser` 走 rundll32 / open / xdg-open），对浏览器来说它是
- *   "用户自己打开的标签页"，`window.close()` 通常被**静默忽略**
- *   （Chrome / Edge 控制台里会留一句 "Scripts may close only the windows that
- *   were opened by them"，Firefox 类似）。
- *   所以：
- *     * 这段脚本**不是**"关掉页面"的保证，只是"能关就顺手关掉"；
- *     * 页面上那句「本页面可以关闭了」**必须保留**——它就是给关不掉的情况兜底的；
- *     * 绝不为了"看起来关掉了"去做跳转 / 假按钮 / alert（那才是骗用户）。
+ * ## 🔴 时机约束（阿里云 `mcp-remote` 踩过的坑，别翻回去）
+ *   只有 CLI **真的换到令牌、并且凭据已经写进本机之后**的那张成功页才算"确实成功"；
+ *   收到 code 就宣告成功并关窗是不允许的（换票失败时用户已经被打发走，只剩疑惑）。
+ *   失败页虽然也自动关，但原因文案必须完整可读，且页面里**不出现任何令牌/授权码**。
  *
  * ## 为什么延迟 + 重试两次
- *   * **延迟 1.2 秒**：先让用户看清「授权成功」这四个字再关。上来就关，
- *     用户会以为自己点错了、页面崩了（这正是老板说阿里云"看着正常"的反面：
- *     页面一闪而过同样让人发慌）。
- *   * **再试一次**：部分浏览器（含移动端内核）对第一次 `close()` 会忽略、
- *     第二次才生效；也有的是 DOM 尚未稳定时忽略。重试成本几乎为零，所以试两次。
+ *   * **延迟**：先让用户看清结论；
+ *   * **再试一次**：部分浏览器（含移动端内核）对第一次 `close()` 会忽略、第二次才生效。
  *     两次之后就**不再骚扰**——继续调下去只会刷一屏控制台报错。
  *
  * ## 约束（单测钉住）
@@ -212,8 +197,12 @@ function badgeSvg(tone) {
  *     不用 `eval`；整段脚本不碰 DOM，也不接收任何数据（页面里没有令牌，脚本里更没有）。
  *   * 用 `try/catch` 包住：某些内嵌浏览器（Electron / 企业管控浏览器）里
  *     `window.close` 可能直接被禁用甚至抛异常，不能因此弄脏页面。
+ *
+ * @param {number} delayMs 首次尝试关闭前的延迟（毫秒；必须是有限正数）
  */
-const AUTO_CLOSE_SCRIPT = `<script>
+function autoCloseScript(delayMs) {
+  const delay = Number.isFinite(delayMs) && delayMs >= 0 ? Math.round(delayMs) : 1200;
+  return `<script>
 (function(){
   var n = 0;
   function tryClose(){
@@ -221,9 +210,10 @@ const AUTO_CLOSE_SCRIPT = `<script>
     try { window.close(); } catch (e) { /* 内嵌浏览器可能直接禁用，忽略 */ }
     if (n < 2) setTimeout(tryClose, 700);
   }
-  setTimeout(tryClose, 1200);
+  setTimeout(tryClose, ${delay});
 })();
 </script>`;
+}
 
 /**
  * 拼出整份文档。
@@ -237,11 +227,11 @@ const AUTO_CLOSE_SCRIPT = `<script>
  * @param {string} [spec.note]   小字说明
  * @param {string} [spec.hint]   更小的补充提示
  * @param {boolean} [spec.autoClose] 是否附上"尝试自动关闭标签页"的脚本。
- *   ⚠️ 默认 `false`，而且目前**只允许成功页**用它（`successPage`）——那个页面代表
- *      "令牌已换到、凭据已写盘"，是唯一"确实成功"的终态。
- *      错误页 / 任何中间态页**不要**打开它（理由见 `AUTO_CLOSE_SCRIPT` 与 `errorPage` 的注释；
- *      顺手关掉用户正在看的失败原因，正是阿里云那套踩过的坑）。
- *      打开它的页面**必须同时**有「本页面可以关闭了」这类兜底文案（它大概率关不掉）。
+ *   0.2.4 起**成功页与失败页都打开它**（老板反馈「页面关不掉」），差别只在延迟：
+ *   成功页 1.2 秒（先看清"授权成功"），失败页 6 秒（先看清原因）。
+ *   打开它的页面**必须同时**有「本页面可以关闭了 / 直接关闭标签页」这类兜底文案
+ *   （浏览器大概率不允许脚本关闭"用户自己打开的"标签页）。
+ * @param {number} [spec.autoCloseDelayMs] 首次尝试关闭前的延迟（默认 1200ms）
  */
 export function renderPage({
   title,
@@ -252,6 +242,7 @@ export function renderPage({
   note,
   hint,
   autoClose = false,
+  autoCloseDelayMs = 1200,
 } = {}) {
   const parts = [badgeSvg(tone), `<h1>${escapeHtml(heading)}</h1>`];
   if (lead) parts.push(`<p class="lead">${escapeHtml(lead)}</p>`);
@@ -275,7 +266,7 @@ export function renderPage({
 <main class="card" role="main">
 ${parts.join('\n')}
 </main>
-<footer>悟空AI · 云站平台</footer>${autoClose ? `\n${AUTO_CLOSE_SCRIPT}` : ''}
+<footer>悟空AI · 云站平台</footer>${autoClose ? `\n${autoCloseScript(autoCloseDelayMs)}` : ''}
 </body>
 </html>`;
   return { title, html };
@@ -292,11 +283,11 @@ ${parts.join('\n')}
  *
  * 文案分区（老板指定）：大标题 / 副文案（回终端）/ 已登录账号 / 小字说明。
  *
- * ## 唯一会尝试自动关闭标签页的页面（`autoClose: true`）
+ * ## 会尝试自动关闭标签页的页面之一（`autoClose: true`）
  *   这张页只在 `login.mjs` 里 **`api.token(...)` 换到令牌 → `writeCredentials(...)` 写盘之后**
  *   才被返回，所以"授权成功"是**已经落地的事实**，不是"收到了 code"这种半成品状态
  *   —— 这是与阿里云 `mcp-remote` 最关键的区别（它收到 code 就宣告成功并关窗，换票失败时
- *   用户已经被打发走了）。详见 `AUTO_CLOSE_SCRIPT` 的注释。
+ *   用户已经被打发走了）。详见 `autoCloseScript` 的注释。
  *   ⚠️ 副文案里的「本页面可以关闭了」和 hint 里的"直接关闭标签页"是**兜底**，
  *      关不掉时用户照着做就行，两条都不许删（单测钉住）。
  *
@@ -372,25 +363,31 @@ export function alreadyDonePage(account) {
  * @param {string} spec.heading   大标题（短，一眼能懂）
  * @param {string} spec.reason    明确的中文原因
  * @param {string} [spec.hint]    补充说明（例如"没有写入任何凭据"）
+ * @param {boolean} [spec.autoClose] 是否尝试自动关闭（默认 **true**，0.2.4 老板反馈"关不掉"）
+ * @param {number} [spec.autoCloseDelayMs] 首次关闭延迟（默认 6000ms：先让用户看清原因）
  *
- * ## 🔴 错误页**永远不**尝试自动关闭（这里刻意连开关都不留）
- *   失败分支一共五处：`state 校验失败` / `缺少授权码` / `授权未完成`（拒绝或服务端 error）/
- *   `换取令牌失败` / `405 方法不允许`。它们全都不带自动关闭脚本，理由分两层：
- *     1. 其中三处**流程还没结束**（state 校验失败、缺 code、405 时 CLI 仍在等真正的回调），
- *        用户可能正照着这一页的说明回同意页重来 —— 自动关掉等于把线索删了；
- *     2. 另外两处虽然已经终态，但**用户必须看清原因**（"为什么没成"是排障的唯一线索，
- *        而且失败提示里那句"请回到终端重试"要留在屏幕上让人照做）。
- *   ⚠️ 这里**不提供** `autoClose` 参数：不给调用方"图省事打开"的机会。
- *      真要改这条口径，请先读完 `AUTO_CLOSE_SCRIPT` 上面那段（阿里云 `mcp-remote` 的教训）。
+ * ## 0.2.4（2026-10-21 老板反馈「127 那个页面关不掉」）
+ *   失败页**也**尝试自动关闭，但延迟 6 秒 —— 既不让用户卡死在一个已经结束的页面上，
+ *   也留够时间看清"为什么没成"。正文（原因 + 回终端重试）全部是静态 HTML，
+ *   脚本关不掉时页面照旧可读，且带「直接关闭标签页」的兜底文案。
+ *   ⚠️ 仍然**不允许**把失败页做成"一出来就关"：失败原因是排障的唯一线索，
+ *      而且其中"state 校验失败 / 缺少授权码 / 405"出现时 CLI 还在等真正的回调，
+ *      用户可能正照着页面说明重试。延迟关闭是这两者之间的折中。
+ *   ⚠️ 任何页面都绝不回显 code / 令牌（模板里没有接收它们的位置）。
  */
-export function errorPage({ tone = 'error', heading, reason, hint } = {}) {
+export function errorPage({ tone = 'error', heading, reason, hint, autoClose = true, autoCloseDelayMs = 6000 } = {}) {
+  const seconds = Math.max(1, Math.round(autoCloseDelayMs / 1000));
+  const closeHint = autoClose
+    ? `本页面会在约 ${seconds} 秒后自动关闭；如果没有关掉，直接关闭标签页即可。`
+    : '看完后直接关闭标签页即可。';
   return renderPage({
     tone,
     title: `${heading} · 悟空AI`,
     heading,
     lead: reason,
     note: hint,
-    hint: RETRY_HINT,
-    // autoClose 保持默认 false：错误页一律留在屏幕上
+    hint: `${RETRY_HINT} ${closeHint}`,
+    autoClose,
+    autoCloseDelayMs,
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wkgeo-cli",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "云站平台官方命令行客户端：授权登录一次，之后建站 / 下单 / 钱包支付 / 查余额都不用再登录（OAuth 授权码 + PKCE，公共客户端，零第三方依赖）",
   "keywords": [
     "wkgeo",