wkgeo-cli 0.2.0

package/lib/commands/auth.mjs

@@ -0,0 +1,974 @@
+/**
+ * 账号类命令：`login` / `logout` / `whoami` / `config`
+ *
+ * ⚠️ 非交互铁律：这些命令**任何情况下都不提问**（不用 AI 去"按 y"）。
+ *    需要用户做的事（同意授权）表现为：打印网址 + 阻塞等待 + 超时给明确错误。
+ */
+
+import { runLogin, DEFAULT_CALLBACK_FIRST_WAIT_MS } from '../login.mjs';
+import { requestDeviceCode, announceDeviceCode, pollDeviceToken, devicePasteText } from '../device.mjs';
+import {
+  pendingDeviceFile,
+  savePendingDevice,
+  readPendingDevice,
+  deletePendingDevice,
+  isPendingExpired,
+  pendingExpiredError,
+} from '../device-store.mjs';
+import { proxyWarningPayload, proxyDeviceSwitchLines, proxyForcedCallbackLines } from '../proxy.mjs';
+import { deleteCredentials, readCredentials, checkFileMode, isExpired } from '../credentials.mjs';
+import { formatRemaining, maskToken, formatTime } from '../format.mjs';
+import { CliError, EXIT, loginHint, UsageError } from '../errors.mjs';
+import { describeConfigSources, parseDurationMs } from '../config.mjs';
+import { GLOBAL_FLAGS } from '../args.mjs';
+
+/**
+ * 「检测到系统代理时自动改用设备码」这个开关的解析（默认 **开**）。
+ *
+ * ## 为什么默认开，而不是 opt-in（老板 2026-10-02 明确要求）
+ *   老板原话：「如果能检测到有代理，可不可以**直接返回设备码**，然后用户把它输入到 AI 端的
+ *   对话框里……你那个让用户检查代理设置太不方便了，**很多用户也不懂**。」
+ *   → 主路径必须是"用户什么都不用做就能成功"。三条"改代理设置"的提示保留为**补充说明**，
+ *     但绝不能是唯一出路（不懂代理的用户会直接卡死）。
+ *
+ * ## ⚠️ 2026-10-02 第二版加固：判定依据从 `risk` 改成 `detected`
+ *   第一版是"有代理 **且** 绕过列表没写回环（`risk`）才降级"。真机上彻底失效：
+ *   老板的机器绕过列表里**写着** `127.*;localhost`，于是判成"不风险"、走了回调，
+ *   结果他点了【同意授权】之后 CLI **一直拿不到令牌**
+ *   （独立证据：`curl -x http://127.0.0.1:7890 http://127.0.0.1:1/x` 返回 502，
+ *    说明那台机器上的代理**会尝试接管回环请求**）。
+ *   ⇒ 现在：**只要 `proxyInfo.detected === true` 就直接走设备码**，
+ *     宁可多一步（用户按一次短码），也绝不让用户卡在"点了同意却没反应"。
+ *     `loopback_bypassed` / `risk` 只进诊断字段。
+ *
+ * ## 什么情况下关掉它
+ *   `--no-auto-device` 或 `WKONGAI_AUTO_DEVICE=0`：
+ *   * 你确认回调一定通（例如内网、代理已正确绕过回环），不想被自动改道；
+ *   * 探测本身有误报（例如命中 PAC：绕过规则写在脚本里，我们无法零依赖求值）。
+ *   ⚠️ 关掉时 CLI **必须**警告"代理可能吃掉回调"（见 proxyForcedCallbackLines）——
+ *     否则用户就只剩"点了同意干等到超时"这一种结局。
+ *
+ * ## 优先级（显式 > 环境变量 > 默认）
+ *   `--auto-device` / `--no-auto-device`（命令行）> `WKONGAI_AUTO_DEVICE`（0/false/no/off = 关）> 默认开
+ */
+export function resolveAutoDevice(flags = {}, env = {}) {
+  if (flags.autoDevice === false) return false;
+  if (flags.autoDevice === true) return true;
+  const v = String((env && env.WKONGAI_AUTO_DEVICE) || '')
+    .trim()
+    .toLowerCase();
+  if (['0', 'false', 'no', 'off'].includes(v)) return false;
+  return true;
+}
+
+/**
+ * 「回调模式首轮等待」窗口（毫秒）的解析 —— ★ 第二条保险（见 login.mjs 的同名注释）。
+ *
+ * ## ⚠️⚠️ 2026-10-03 老板真机反馈后改了触发条件（这是本次修复的第一条）
+ *   旧逻辑：**无条件**返回默认 60 秒 ⇒ 用户机器上**没有任何代理/VPN**时也会自愈。
+ *   而"把授权页送到用户面前、他读完再点【同意】"经常超过 60 秒 ⇒ 明明不需要设备码也切了过去。
+ *   老板原话：「现在变成设备码了，我们因为没有开任何VPN，所以这个是不对的。」
+ *   ⇒ 现在：**只有 `proxyDetected === true`（真检测到生效中的代理）才用默认值启用**；
+ *     **没有代理时不启用**（返回 0，老老实实等满 `--timeout`）。
+ *
+ * ## 优先级（显式 > 自动判断）
+ *   `--callback-first-wait <时长>`（默认单位**秒**；`0` / `off` / `none` = 关掉自愈）
+ *   > `WKONGAI_CALLBACK_FIRST_WAIT_MS`（毫秒）
+ *   > **有代理**时的 `DEFAULT_CALLBACK_FIRST_WAIT_MS`（180 秒）/ **无代理**时的 0
+ *   ⇒ 用户**显式**指定时一律照旧尊重（哪怕没有代理）—— 显式指定优先于自动判断。
+ *
+ * ⚠️ `--no-auto-device`（autoDevice=false）时**强制返回 0**：用户已经明确要求"只走回调"，
+ *    我们没有"改道"这个选项，就不能背着他偷偷改（那样比不给自愈更糟：他会以为
+ *    CLI 没听他的）。此时整段 `--timeout` 依然是兜底。
+ *
+ * @param {object} flags 已解析的命令行标志（camelCase）
+ * @param {object} env   环境变量
+ * @param {{autoDevice?: boolean, proxyDetected?: boolean}} [opts]
+ *   `proxyDetected` **必须**由调用方用 `proxyInfo.detected` 显式传入；
+ *   缺省按 `false`（= 没检测到代理）处理 —— 这是刻意的保守默认：
+ *   "信息不足时宁可不自愈"，也避免有人忘了传就又回到"无代理也切设备码"的老毛病。
+ * @returns {number} 毫秒；0 = 关闭自愈
+ */
+export function resolveCallbackFirstWaitMs(flags = {}, env = {}, { autoDevice = true, proxyDetected = false } = {}) {
+  if (!autoDevice) return 0;
+  const off = new Set(['0', 'off', 'none', 'false', 'no']);
+  if (flags.callbackFirstWait !== undefined && flags.callbackFirstWait !== '') {
+    const raw = String(flags.callbackFirstWait).trim().toLowerCase();
+    if (off.has(raw)) return 0;
+    return parseDurationMs(flags.callbackFirstWait, { defaultUnit: 's', flag: '--callback-first-wait' });
+  }
+  const envVal = env && env.WKONGAI_CALLBACK_FIRST_WAIT_MS;
+  if (envVal !== undefined && envVal !== '') {
+    if (off.has(String(envVal).trim().toLowerCase())) return 0;
+    return parseDurationMs(envVal, { defaultUnit: 'ms', flag: 'WKONGAI_CALLBACK_FIRST_WAIT_MS' });
+  }
+  /**
+   * ★ 走到这里 = 用户**没有**显式指定 ⇒ 只有"真检测到代理"才启用自愈。
+   *   没有代理时返回 0：`auto_device.applied=true, reason='callback_first_wait'`
+   *   因此**只可能**出现在有代理的机器上（老板真机那条反馈的口径）。
+   */
+  return proxyDetected ? DEFAULT_CALLBACK_FIRST_WAIT_MS : 0;
+}
+
+/**
+ * ★ 「回调 / 设备码两条路并存」时用的**可被立刻叫醒的 sleep**。
+ *
+ * 为什么需要它：`pollDeviceToken()` 每轮之间会 `await sleep(interval)`（默认 5 秒）。
+ * 回调那条路先拿到令牌时，设备码那条路必须**马上**停下来 —— 如果只是置一个"别再轮询"的标志，
+ * 那个**已经挂上**的 `setTimeout` 会把 Node 的事件循环继续吊住（用户已经看到"登录成功"，
+ * 进程却迟迟不退出）。所以这里把 sleep 做成可唤醒的：谁赢了就 `wakeAll()`，
+ * 挂着的那一轮立刻醒来，醒来后由 `shouldStop()`（见 device.mjs）抛错退出。
+ *
+ * ⚠️ 测试注入的 `sleep`（例如 `async () => {}`）**照旧透传**：那种实现立刻返回，
+ *    不需要（也无法）被打断 —— 只有生产路径（真 `setTimeout`）才由这里持有并清理。
+ */
+export function createCancelGate(baseSleep) {
+  const waiters = new Set();
+  let cancelled = false;
+  const delegated = typeof baseSleep === 'function';
+  return {
+    sleep: (ms) => {
+      if (cancelled) return Promise.resolve();
+      if (delegated) return baseSleep(ms);
+      return new Promise((resolve) => {
+        const done = () => {
+          waiters.delete(done);
+          clearTimeout(timer);
+          resolve();
+        };
+        const timer = setTimeout(done, ms);
+        waiters.add(done);
+      });
+    },
+    wakeAll() {
+      cancelled = true;
+      for (const done of [...waiters]) done();
+    },
+  };
+}
+
+/** 回调那条路先成功时用来**安静地**叫停设备码那条路（不是给用户看的错误，命令层会吞掉它） */
+function deviceStoppedError() {
+  return new CliError('设备码轮询已停止（本地回调那条路已经拿到令牌）', {
+    kind: 'cancelled',
+    hint: '不需要做任何事：登录已经完成',
+    exitCode: EXIT.AUTH,
+  });
+}
+
+/**
+ * 把"设备码那条路"**等它退出**（失败/被叫停都不许把主流程带下水）。
+ *
+ * ⚠️ 这里刻意用 `Promise.race` 加一个 1 秒上限：`deviceSide.promise` 的结束速度取决于注入的
+ *    `sleep` 能不能被打断 —— 生产路径由 `createCancelGate()` 自己持有定时器，`wakeAll()`
+ *    一叫就醒（毫秒级）；而单测可能注入一个不可打断的假 sleep。
+ *    宁可让那次后台轮询在下一轮自己发现 `shouldStop()` 并退出，也不能把用户的登录卡在这里。
+ * ⚠️ `deviceSide.promise` 内部两个分支都已 catch（不会 reject），这里 await 它不会抛。
+ */
+async function 停掉设备码那条路(deviceSide, cancelGate) {
+  if (!deviceSide.promise) return;
+  deviceSide.cancelled = true;
+  cancelGate.wakeAll();
+  await Promise.race([
+    deviceSide.promise,
+    new Promise((resolve) => {
+      const t = setTimeout(resolve, 1000);
+      if (t && typeof t.unref === 'function') t.unref();
+    }),
+  ]);
+}
+
+/**
+ * 两条路都没走通时的报错 —— 回调没等到 + 设备码又失败。
+ *
+ * ⚠️ 必须把**两件事一起说清楚**：只报设备码那条错，用户会以为"回调其实没问题"，
+ *    于是又回去重跑 `login`，白等第二个 5 分钟（这是老板真机踩过的那类坑）。
+ * ⚠️ 文案里的 `本地回调没成功` / `回调侧的报错` / `设备码侧的报错` 是**契约字样**
+ *    （`test/proxy-login.test.mjs`「两条路都不通」那条用例按它们断言），不要改写。
+ */
+function bothPathsFailedError(deviceError, reason, { loginTimeoutMs }) {
+  const callbackSide =
+    reason === 'callback_timeout'
+      ? `等待授权超时（${loginTimeoutMs}ms，本机回调监听当时仍然开着）`
+      : '首轮等待没收到回调（本机回调监听当时仍然开着）';
+  return new CliError(`本地回调没成功，改用设备码也失败了：${deviceError.message}`, {
+    kind: deviceError.kind || 'device_authorization_failed',
+    code: deviceError.code === undefined ? null : deviceError.code,
+    hint: `回调侧的报错：${callbackSide}；设备码侧的报错：${deviceError.message}。两条路都没走通时，先按提示修掉代理/防火墙，或让服务端确认设备码端点可用`,
+    exitCode: deviceError.exitCode === undefined ? EXIT.ERROR : deviceError.exitCode,
+  });
+}
+
+/**
+ * 这些错误意味着"这个设备码已经没救了"（过期/被拒/服务端没有这个能力），
+ * 此时磁盘上的待完成状态应该删掉 —— 否则用户下次 `--device-continue` 会拿着一个
+ * 注定失败的码去轮询，白等一轮。**网络类错误不在此列**（码还是好的，可以再试）。
+ */
+const TERMINAL_DEVICE_KINDS = new Set(['denied', 'expired', 'not_implemented', 'token_exchange']);
+
+/* ------------------------------------------------------------------ */
+/* login                                                               */
+/* ------------------------------------------------------------------ */
+
+export const loginCommand = {
+  name: 'login',
+  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 --open-browser    # 强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）\n' +
+    'wkgeo login --callback-first-wait 60   # 首轮等待 60 秒（★ 只在检测到代理时才有默认值 180；0/off = 关掉这个自愈）\n' +
+    'wkgeo login --timeout 600     # 等待授权 600 秒（默认单位是秒，不是毫秒；也支持 600s / 500ms）',
+  flags: {
+    browser: { type: 'boolean', desc: '是否自动打开浏览器（★ 默认总是尝试打开：终端与 AI 场景都一样；--no-browser 关闭）' },
+    /**
+     * ★ 老板最终拍板走**传统路线**（弹系统浏览器）：CLI **默认总是尝试打开**，
+     *   唯一的"不打开"开关是 `--no-browser`。
+     *   本开关现在**与默认行为等价**，保留只为两件事：
+     *     1. **显式语义**（"我就是要弹，你别管"）；
+     *     2. **兼容**既有脚本（不许删）。
+     * ⚠️ 与 `--no-browser` 同时出现时 **--no-browser 优先**（关掉就是关掉，见 resolveBrowserIntent）。
+     */
+    'open-browser': { type: 'boolean', desc: '强制尝试打开系统浏览器（⚠️ 现在与默认行为等价，保留只为显式语义与兼容）' },
+    device: { type: 'boolean', desc: '用设备码模式（RFC 8628）代替本地回调：不需要任何回调地址，对代理/防火墙免疫' },
+    /**
+     * ★ 老板 2026-10-02 要的"AI 端友好路径"。
+     * 为什么做成"申请完就退出"而不是"申请完继续挂着轮询"（后者靠 JSONL 事件流也能做）：
+     *   AI 端是**一轮一轮**工作的 —— 一次工具调用里挂着等 10 分钟会把用户晾住、也容易撞超时。
+     *   拆成"申请"和"领取"两条命令后，中间隔多久都行，且**不需要任何长驻进程**。
+     * 两种用法都保留：交互式终端里 `login --device` 一口气跑完更省事；
+     * AI/脚本里用 `--device --no-wait` + `--device-continue`（见 README）。
+     */
+    'no-wait': { type: 'boolean', desc: '只申请设备码并打印（短码/网址），**立即退出不轮询**；稍后用 --device-continue 领取令牌' },
+    'device-continue': { type: 'boolean', desc: '继续上一次 --no-wait/被中断的设备码登录（读取本地保存的设备码并轮询到出结果）' },
+    'auto-device': {
+      type: 'boolean',
+      desc: '检测到系统代理时自动改用设备码（**默认开**；--no-auto-device 或 WKONGAI_AUTO_DEVICE=0 关闭，关闭时会警告"代理可能吃掉回调"）',
+    },
+    /**
+     * ★ 第二条保险（见 login.mjs 的 DEFAULT_CALLBACK_FIRST_WAIT_MS）。
+     * 默认单位**秒**，与 `--timeout` 一致（人类写等待窗口都按秒想）；
+     * `0` / `off` / `none` = 关掉自愈，回到"只等整段 --timeout"的旧行为。
+     * 环境变量 `WKONGAI_CALLBACK_FIRST_WAIT_MS` 是毫秒（与 `WKONGAI_LOGIN_TIMEOUT_MS` 同口径）。
+     *
+     * ⚠️ 2026-10-03 起：**不传它时默认值是"看有没有代理"** —— 有代理才是 180 秒，没有代理是 0
+     *   （老板真机反馈：没有开任何 VPN 也被切成了设备码）。显式传值时照旧尊重用户。
+     */
+    'callback-first-wait': {
+      type: 'string',
+      desc: '回调模式的**首轮等待**（默认单位秒；★ 只在检测到系统代理时默认 180 秒，无代理默认不启用）：这段时间没等到回调就自动改用设备码继续（本地回调监听会同时保留）；0/off 关闭该自愈',
+    },
+    /**
+     * 显式声明一次（`timeout` 本来就在 GLOBAL_FLAGS 里），只为让 `wkgeo login --help`
+     * 把**单位**打在用户眼前 —— 这条命令是最需要等超时的地方。
+     * 描述直接引用 `GLOBAL_FLAGS.timeout.desc`，**单一来源**，不会两处口径漂移。
+     */
+    timeout: { type: 'string', desc: GLOBAL_FLAGS.timeout.desc },
+  },
+  /**
+   * JSON 模式下的输出形状与其它命令**不同**：它是 JSONL 事件流，因为这条命令会长时间阻塞。
+   *   {"ok":true,"command":"login","stage":"awaiting_callback","authorization_url":"…"}
+   *   {"ok":true,"command":"login","stage":"done","data":{…}}
+   *   {"ok":false,"command":"login","stage":"failed","error":{…}}
+   * 设备码模式：
+   *   {"ok":true,"command":"login","stage":"awaiting_user","user_code":"ABCD-1234","verification_uri":"…",
+   *    "verification_uri_complete":"…","expires_in":600,"interval":5,"paste_text":"…"}
+   *   ★ `--no-wait` 时**最后一行就是这个 `stage=awaiting_user`**（进程随即退出，不再有 done）；
+   *     该行里带 `no_wait:true` / `resume_command` / `pending_file`，AI 端据此转达用户，
+   *     稍后再跑 `wkgeo login --device-continue`。
+   * 为什么不做成"一条最终 JSON"：AI 端需要在**等待期间**就把网址/短码交给用户，
+   * 等 5 分钟拿到最终结果时用户早就走了。
+   */
+  async run(ctx) {
+    const { out, config, flags } = ctx;
+    const jsonMode = out.json;
+    /** JSON 模式：人类可读文本一律走 stderr，stdout 只放机器可读事件 */
+    const log = jsonMode ? (m) => out.raw(m) : (m) => out.line(m);
+    const cmdName = config.cmdName || 'wkgeo';
+
+    /* ---- 0. 三种模式的互斥检查（用法错误 exit 2，脚本里好分辨） ---- */
+    const noWait = flags.noWait === true;
+    const wantsContinue = flags.deviceContinue === true;
+    if (noWait && wantsContinue) {
+      throw new UsageError('--no-wait 与 --device-continue 不能同时用：前者是"只申请短码就退出"，后者是"去领取上次申请的短码"');
+    }
+    if (wantsContinue && flags.device === true) {
+      throw new UsageError('--device-continue 与 --device 不能同时用：--device-continue 会自动读回上次保存的设备码');
+    }
+    /**
+     * `--no-wait` **隐含**设备码模式：回调模式没有"先返回、稍后再领"这回事
+     * （授权码 5 分钟失效，而且必须由浏览器打回本地端口）。
+     * 把隐含关系写死在实现里，比要求用户同时记住两个开关更不容易用错。
+     */
+    const wantsDevice = flags.device === true || noWait;
+
+    /** 回调模式的安全底线：只能监听回环（设备码模式不经过回调，跳过这条） */
+    if (!wantsDevice && !wantsContinue) {
+      if (config.callbackHost !== '127.0.0.1' && config.callbackHost !== 'localhost' && config.callbackHost !== '[::1]') {
+        throw new CliError(`回调地址必须监听回环（127.0.0.1 / localhost / [::1]），当前是 ${config.callbackHost}`, {
+          kind: 'usage',
+          hint: '不要用 --callback-host 绑 0.0.0.0：授权码会暴露给同网段所有人',
+          exitCode: EXIT.USAGE,
+        });
+      }
+    }
+
+    /* ---- 1. 代理检测（只有回调模式才关心：设备码不需要任何入站回调） ---- */
+    const proxyInfo = !wantsDevice && !wantsContinue ? ctx.proxyInfo() : null;
+    const proxyPayload = proxyInfo ? proxyWarningPayload(proxyInfo, { cmdName }) : null;
+    const autoDevice = resolveAutoDevice(flags, ctx.env);
+
+    /**
+     * ★★ 核心规则（2026-10-02 第二版加固）：**`detected === true` 就直接走设备码**。
+     *
+     * ⚠️ 为什么不再看 `loopback_bypassed` / `risk`：真机上老板的绕过列表里**写着**
+     *    `localhost;127.*`，第一版据此判"没风险"→ 走回调 → 他点了【同意授权】之后
+     *    回调请求从没到过本机，CLI 一直拿不到令牌
+     *    （独立证据：`curl -x http://127.0.0.1:7890 http://127.0.0.1:1/x` → 502，
+     *     证明那台机器上的代理**会尝试接管回环请求**，绕过列表并没有真正生效）。
+     *    ⇒ 结论：**"绕过列表里有 127.*"不等于绕过生效**，不同代理软件/浏览器对 bypass
+     *      的解释并不一致。宁可让用户多走一步设备码，也不能让他卡在"点了同意没反应"。
+     *    这两个字段仍然照样上报（`proxy_warning`），只是**不再作为放行回调的依据**。
+     */
+    const proxyDetected = !!(proxyInfo && proxyInfo.detected);
+    let useDevice = wantsDevice;
+    /** 为什么会走设备码：proxy_detected / callback_first_wait / callback_timeout / callback_listen_failed */
+    let downgradeReason = null;
+    if (!useDevice && autoDevice && proxyDetected) {
+      useDevice = true;
+      downgradeReason = 'proxy_detected';
+    }
+
+    if (downgradeReason === 'proxy_detected') {
+      // 人类模式：说清楚"为什么改了、怎么改回去"（AI 端看 proxy_warning 结构化字段）
+      for (const line of proxyDeviceSwitchLines(proxyInfo, { cmdName })) log(line);
+    } else if (!wantsDevice && !wantsContinue && !useDevice && proxyDetected) {
+      /**
+       * 走到这里只有一种情况：用户**显式**要求坚持回调模式（--no-auto-device / WKONGAI_AUTO_DEVICE=0）。
+       * ⚠️ 必须明确警告：否则他唯一的下场就是"点了同意，然后干等到超时"，
+       *    而他会以为是 CLI 坏了（这正是老板真机上遇到的那个现象）。
+       */
+      for (const line of proxyForcedCallbackLines(proxyInfo, { cmdName })) log(line);
+    }
+
+    /** 把运行期注入的依赖透传给两条登录流程（测试要能离线跑，见 runtime.mjs 的说明） */
+    const loginDeps = {
+      fetchImpl: ctx.fetchImpl,
+      now: ctx.now,
+      sleep: ctx.sleep,
+      // `--no-browser` → false；否则用注入的（测试）或默认的真·打开浏览器
+      openBrowser: flags.browser === false ? false : ctx.openBrowser,
+      /** 真 spawn 的注入点（单测验证"AI 场景一次都不 spawn 浏览器"；生产不传 = 真 spawn） */
+      spawnImpl: ctx.spawnImpl,
+      /**
+       * ★★ 「要不要替用户弹**系统**浏览器」的四个事实（老板最终拍板走**传统路线**）：
+       *   * `isTTY`   —— stdout 是不是终端（由 runtime 从 stdout.isTTY 读出，命令层原样透传）；
+       *   * `json`    —— 是不是 JSON 输出（`--json` 或非 TTY 自动 JSON）；
+       *   * `forceBrowser` —— 用户写了 `--open-browser`（现在与默认行为等价，保留显式语义）；
+       *   * `noBrowser`    —— 用户写了 `--no-browser`（**唯一**的"不打开"开关，优先级最高）。
+       * 四个一起进 `resolveBrowserIntent()`（login.mjs 里的**唯一裁决点**）：
+       *   **默认总是尝试打开系统浏览器**（人在终端 ✔ + AI 场景 ✔）；
+       *   `isTTY` / `json` 现在只影响 `mode` 这个诊断字段，**不再**决定"要不要弹"。
+       * ⚠️ 回调模式与设备码模式都吃这一份 deps —— 所以两条授权路径的行为天然一致。
+       */
+      isTTY: ctx.isTTY === true,
+      json: ctx.out.json === true,
+      forceBrowser: flags.openBrowser === true,
+      noBrowser: flags.browser === false,
+      platform: ctx.platform,
+      /**
+       * ★ 第二条保险：回调模式的**首轮等待**。
+       *
+       * ⚠️⚠️ 2026-10-03 起默认值**取决于有没有代理**（老板真机反馈修的）：
+       *   * 有代理（`proxyDetected === true`）→ `DEFAULT_CALLBACK_FIRST_WAIT_MS`（180 秒）；
+       *   * **没有代理 → 0 = 不启用**（老老实实等满 `--timeout`）；
+       *   * 用户显式写 `--callback-first-wait` / `WKONGAI_CALLBACK_FIRST_WAIT_MS` → 照旧尊重；
+       *   * `--no-auto-device` → 强制 0（用户明确要求只走回调，就不能偷偷改道）。
+       */
+      callbackFirstWaitMs: resolveCallbackFirstWaitMs(flags, ctx.env, { autoDevice, proxyDetected }),
+      /**
+       * ★★ 设备码先成功后，本地回调监听再多留多久（毫秒；0 = 立刻收尾）。
+       *   生产不传 = `login.mjs` 的 `DEFAULT_POST_DEVICE_GRACE_MS`；
+       *   单测可注入一个小值，确定性地验证"迟到的回调拿到已完成页"。
+       */
+      postDeviceGraceMs: ctx.postDeviceGraceMs,
+    };
+
+    /**
+     * ★ 无代理时的一句说明（老板真机反馈的直接回应）。
+     *
+     * 为什么值得打这一行：他这次的困惑正是"**我没有开代理，为什么变成设备码了**"。
+     * 明说"这次不会因为首轮等待就自动改设备码"能直接消掉这个困惑；
+     * 同时也要说清"整段 --timeout 用完仍可能改"（那是既有的兜底语义，本次没有改动）。
+     * ⚠️ 只在"回调模式 + 没检测到代理 + 没开自愈"时打：其它情况一律不打（正常环境不要噪音）。
+     */
+    if (!useDevice && !wantsContinue && !proxyDetected && loginDeps.callbackFirstWaitMs === 0) {
+      log(
+        `ℹ️ 未检测到系统代理：本次会一直等你完成授权（最多 ${Math.round(config.loginTimeoutMs / 1000)} 秒），` +
+          '不会因为"首轮等待"到点就自动改用设备码。',
+      );
+      log('   （想主动限制首轮等待：`--callback-first-wait <秒>`；想强制设备码：`--device`。）');
+    }
+
+    /**
+     * 设备码事件的统一构造（人类提示在 announceDeviceCode 里打；这里只负责机器可读那一份）。
+     * ⚠️ `user_action_required` 是**给 AI 端直接用的话术**：AI 不该自己组织语言，
+     *    照着念就不会漏掉网址或短码。
+     */
+    const deviceEvent = (info, extra = {}) => {
+      if (!jsonMode) return;
+      out.event({
+        ok: true,
+        command: 'login',
+        mode: 'device',
+        stage: 'awaiting_user',
+        ...info,
+        ...extra,
+        user_action_required: `请让用户访问 ${info.open_url}${info.verification_uri_complete ? '' : ` 并输入短码 ${info.user_code}`}`,
+      });
+    };
+    const deviceDeps = (extraEvent = {}) => ({ ...loginDeps, onDeviceCode: (info) => deviceEvent(info, extraEvent) });
+
+    const pendingFile = pendingDeviceFile(config.credentialsFile);
+    /** 申请到码之后立刻落盘：进程被 Ctrl+C / 终端被关掉，用户还能用 --device-continue 续上 */
+    const 保存待完成 = (device) => {
+      try {
+        savePendingDevice(pendingFile, { ...device, base: config.base, client_id: config.clientId });
+        return true;
+      } catch (e) {
+        // 落盘失败**不影响本次授权**（只是失去"稍后续跑"的能力），所以只提示不抛
+        log(`⚠️ 无法保存待完成的设备码状态（不影响本次授权，只是不能稍后用 --device-continue 续跑）：${e.message}`);
+        return false;
+      }
+    };
+
+    let result = null;
+
+    /* ---- 2a. `--device-continue`：续跑上次没等完的设备码 ---- */
+    if (wantsContinue) {
+      const pending = readPendingDevice(pendingFile);
+      if (!pending) {
+        throw new CliError('本地没有待完成的设备码登录', {
+          kind: 'device_state',
+          hint: `先运行 \`${cmdName} login --device --no-wait\`（或直接 \`${cmdName} login --device\`）申请一个短码`,
+          exitCode: EXIT.USAGE,
+        });
+      }
+      /**
+       * ⚠️ 设备码只对**当初申请它的那个服务端**有效。用户中途换了 `--base`（换了环境）时，
+       *    拿旧码去新环境轮询必然失败，不如在这里把话说明白。
+       */
+      if (pending.base && pending.base !== config.base) {
+        throw new CliError(`这份设备码是为 \`${pending.base}\` 申请的，与当前的 \`${config.base}\` 不一致`, {
+          kind: 'device_state',
+          hint: `用同一个 --base 重试，或重新运行 \`${cmdName} login --device\``,
+          exitCode: EXIT.USAGE,
+        });
+      }
+      if (isPendingExpired(pending, { now: ctx.now() })) {
+        deletePendingDevice(pendingFile);
+        throw pendingExpiredError(pendingFile);
+      }
+      log(`继续上一次的设备码登录：短码 ${pending.user_code}`);
+      log(`  （如果浏览器已经关掉了：${pending.open_url}）`);
+      try {
+        result = await pollDeviceToken({ config, log, deps: loginDeps, device: pending });
+        deletePendingDevice(pendingFile);
+        useDevice = true;
+      } catch (e) {
+        if (TERMINAL_DEVICE_KINDS.has(e.kind)) {
+          try {
+            deletePendingDevice(pendingFile);
+          } catch {
+            /* 删不掉不影响主流程：报错本身才是用户要看的 */
+          }
+        }
+        throw e;
+      }
+    }
+
+    /* ---- 2b. 设备码模式（等待式，或 --no-wait 只申请） ---- */
+    if (!result && useDevice) {
+      try {
+        const device = await requestDeviceCode({ config, deps: loginDeps });
+        保存待完成(device);
+        if (noWait) {
+          /**
+           * ★ AI 端友好路径：打印完就退出（不轮询）。
+           *    `extra` 同时进"机器可读事件"和"人类可读提示"，两处口径同源。
+           */
+          const extra = {
+            no_wait: true,
+            pending_file: pendingFile,
+            resume_command: `${cmdName} login --device-continue`,
+            expires_at: new Date(device.expires_at).toISOString(),
+            proxy_warning: proxyPayload,
+            logged_in: false,
+            next_step:
+              '请让用户在**自己的浏览器**里打开上面的网址并点「同意」（AI 端无法代点：device_confirm 需要用户自己的登录会话）；' +
+              `然后运行 \`${cmdName} login --device-continue\` 领取令牌`,
+          };
+          announceDeviceCode({ config, log, deps: deviceDeps(extra), device });
+          if (!jsonMode) {
+            out.line('');
+            out.info(`⏸ 已申请短码并退出（--no-wait）。用户点完「同意」后，运行 \`${cmdName} login --device-continue\` 领取令牌。`);
+            out.info(`   短码有效期约 ${Math.round(device.expires_in / 60)} 分钟；过期就重新运行 \`${cmdName} login --device --no-wait\`。`);
+          }
+          return {
+            mode: 'device',
+            stage: 'awaiting_user',
+            ...extra,
+            user_code: device.user_code,
+            verification_uri: device.verification_uri,
+            verification_uri_complete: device.verification_uri_complete,
+            open_url: device.open_url,
+            paste_text: devicePasteText(device),
+            expires_in: device.expires_in,
+            interval: device.interval,
+            credentials_file: config.credentialsFile,
+            client_id: config.clientId,
+          };
+        }
+        announceDeviceCode({ config, log, deps: deviceDeps({ no_wait: false, proxy_warning: proxyPayload }), device });
+        try {
+          result = await pollDeviceToken({ config, log, deps: loginDeps, device });
+          deletePendingDevice(pendingFile);
+        } catch (e) {
+          if (TERMINAL_DEVICE_KINDS.has(e.kind)) {
+            try {
+              deletePendingDevice(pendingFile);
+            } catch {
+              /* 同上：删不掉不影响主流程 */
+            }
+          }
+          throw e;
+        }
+      } catch (e) {
+        /**
+         * 自动降级时设备码端点却不可用（服务端缺口/形状不对）→ **老老实实回落回调模式**，
+         * 而不是把用户堵死。只有"我们自己主动改道"（autoReason 存在）且用户没显式要设备码时才回落；
+         * 显式 `--device` 的失败必须原样报出来（用户要的就是设备码，别替他做别的决定）。
+         */
+        const canFallback =
+          downgradeReason === 'proxy_detected' && !wantsDevice && (e.kind === 'not_implemented' || e.kind === 'device_authorization_failed');
+        if (!canFallback) throw e;
+        log(`⚠️ 设备码模式当前不可用（${e.message}），回落到本地回调模式继续…`);
+        useDevice = false;
+        downgradeReason = null;
+      }
+    }
+
+    /* ---- 2c. 本地回调模式（含"回调没等到 → 并发改设备码"，★ 两条路并存） ---- */
+    if (!result && !useDevice) {
+      /**
+       * ★★ 2026-10-03（老板真机反馈 ⚠️）：「改用设备码」**不再关掉本地回调监听**。
+       *
+       * ## 旧行为（真机证据：ERR_CONNECTION_REFUSED）
+       *   首轮等待到点 → `runLogin` 抛错，并在自己的 `finally` 里**关掉本地 server** → 命令层再走设备码。
+       *   于是用户**之后**才点【同意授权】时，浏览器跳到
+       *   `http://127.0.0.1:<port>/callback?code=…` → **ERR_CONNECTION_REFUSED**
+       *   （老板真机截图见过）→ 用户以为授权失败，再来一遍（而其实他马上就会登录成功）。
+       *
+       * ## 新行为：两条路**并存**，哪个先拿到令牌就用哪个（先到先得）
+       *   * 回调那条路：本地 server 一直开着（`runLogin` 收到 `handoff` 时到点**不结束等待**）；
+       *   * 设备码那条路：由下面的 `handoff.onSwitch` 启动，轮询到出结果为止。
+       *   * 回调先成功 → 把设备码那条路**优雅停掉**（唤醒它挂着的 sleep + 删掉待完成状态文件）；
+       *   * 设备码先成功 → `finishWithDevice()` 让回调那条路收尾（监听再多留几秒，
+       *     迟到的回调会拿到"本次登录已经完成"的页面，见 login.mjs / page.mjs）。
+       */
+      /** 允许"自动改道"吗：用户没写 --no-auto-device，也不是显式设备码模式 */
+      const mayAutoSwitch = autoDevice && !wantsDevice && !wantsContinue;
+      /** 设备码那条路的可取消状态（回调先赢时要把它收拾干净） */
+      const deviceSide = { reason: null, cancelled: false, promise: null, result: null, error: null };
+      /** ★ 可被立刻叫醒的 sleep：回调先赢时，不能让设备码那个 5 秒定时器把进程吊住 */
+      const cancelGate = createCancelGate(loginDeps.sleep);
+      /** 交接面：两边各填一半（`onSwitch` 由这里填，另两个由 runLogin 填；见 login.mjs 的 deps 说明） */
+      const handoff = { onSwitch: null, finishWithDevice: null, abort: null };
+
+      const 跑设备码那条路 = async () => {
+        const device = await requestDeviceCode({ config, deps: loginDeps });
+        // 回调那条路已经赢了 → 一个用户可见的动作都不要再做（不打印短码、不弹浏览器、不落盘）
+        if (deviceSide.cancelled) throw deviceStoppedError();
+        保存待完成(device);
+        if (deviceSide.cancelled) throw deviceStoppedError();
+        announceDeviceCode({ config, log, deps: deviceDeps({ no_wait: false, proxy_warning: proxyPayload }), device });
+        return pollDeviceToken({
+          config,
+          log,
+          deps: {
+            ...loginDeps,
+            sleep: cancelGate.sleep,
+            /** device.mjs 支持它：另一条路赢了就立刻停止轮询（不写凭据、不报错） */
+            shouldStop: () => deviceSide.cancelled,
+          },
+          device,
+        });
+      };
+
+      if (mayAutoSwitch) {
+        handoff.onSwitch = (reason) => {
+          deviceSide.reason = reason;
+          /**
+           * ⚠️ 这里**不 await**、也**不抛错**：交接只需把设备码那条路点起来。
+           *    成功 → `finishWithDevice` 让回调流程带着这份结果收尾（监听留 grace）；
+           *    失败 → `abort` 让回调流程用"两条路都不通"的错误结束（用户要看的是真原因）。
+           */
+          deviceSide.promise = 跑设备码那条路().then(
+            (res) => {
+              deviceSide.result = res;
+              if (typeof handoff.finishWithDevice === 'function') handoff.finishWithDevice(res);
+            },
+            (e2) => {
+              deviceSide.error = e2;
+              /**
+               * ★ 两条路都没成：把**两边的报错**合起来抛（只报设备码那条错，用户会以为
+               *   "回调其实没问题"、又回去白等一轮 —— 见 bothPathsFailedError 的注释）。
+               *   ⚠️ 同时存一份到 `deviceSide.combinedError`：万一回调那条路**抢先**抛了自己的错
+               *   （例如用户在这一刻点了「拒绝」），下面 catch 里也要优先把"两条路都不通"报出来。
+               */
+              deviceSide.combinedError = bothPathsFailedError(e2, reason, { loginTimeoutMs: config.loginTimeoutMs });
+              if (typeof handoff.abort === 'function') handoff.abort(deviceSide.combinedError);
+            },
+          );
+        };
+      }
+
+      try {
+        result = await runLogin({
+          config,
+          log,
+          deps: {
+            ...loginDeps,
+            /** 超时时要把"代理可能是元凶"写进错误 hint（见 login.mjs 的 timeout 分支） */
+            proxyRisk: proxyInfo,
+            /** ★★ 两条路并存的交接面（未启用自动改道时 `onSwitch` 为 null ⇒ runLogin 走旧契约） */
+            handoff,
+            onAuthorizationUrl: (url, extra) => {
+              if (jsonMode) {
+                out.event({
+                  ok: true,
+                  command: 'login',
+                  mode: 'callback',
+                  stage: 'awaiting_callback',
+                  authorization_url: url,
+                  user_action_required: '请让用户在浏览器中打开上面的 authorization_url，登录并点「同意」',
+                  proxy_warning: proxyPayload,
+                  ...extra,
+                });
+              }
+            },
+          },
+        });
+      } catch (e) {
+        /** ★ 无论怎么失败，都先把设备码那条路收拾干净（不能留一个还在轮询的后台任务） */
+        await 停掉设备码那条路(deviceSide, cancelGate);
+        /** 设备码那条路也失败了 ⇒ 优先报"两条路都不通"（哪怕回调那边先抛了自己的错） */
+        if (deviceSide.combinedError) throw deviceSide.combinedError;
+        /**
+         * ★ 「回调失败也自动降级」（老板 2026-10-02 要求"不要直接失败退出"）。
+         *   走得到这里的是**没有启用交接**（`--no-auto-device`）或"连端口都起不来"的两种情况：
+         *     * `listen` —— 连回环端口都起不来（被安全软件/防火墙拦）：
+         *       此时**根本没有监听可保留**，只能老老实实改走设备码；
+         *     * `callback_first_wait` / `timeout` —— 只可能出现在没传 `handoff.onSwitch` 时（旧契约兜底）。
+         *   其它错误（换票失败、被拒绝、state 不匹配…）**不降级**：那些是"授权已经走到下一步了"，
+         *   再来一遍设备码只会让用户做重复劳动（甚至以为被耍了）—— 这条语义**本次没有改动**。
+         */
+        const canSwitch =
+          autoDevice && !wantsDevice && (e.kind === 'callback_first_wait' || e.kind === 'timeout' || e.kind === 'listen');
+        if (!canSwitch) throw e;
+        log('');
+        const 原因 =
+          e.kind === 'timeout' ? '等待超时' : e.kind === 'listen' ? '本地端口监听失败' : '首轮等待没收到回调';
+        log(`⚠️ 本地回调没有等到结果（${原因}）：${e.message}`);
+        if (e.kind === 'callback_first_wait') {
+          log('ℹ️ 等了这一小段时间没收到回调，已自动改用**设备码模式**继续（不需要本地回调）。');
+        } else {
+          log('ℹ️ 已自动改用**设备码模式**继续授权（不需要本地回调）—— 常见原因是代理/防火墙挡了 127.0.0.1。');
+        }
+        let device;
+        try {
+          device = await requestDeviceCode({ config, deps: loginDeps });
+        } catch (e2) {
+          throw bothPathsFailedError(e2, e.kind === 'timeout' ? 'callback_timeout' : 'callback_first_wait', {
+            loginTimeoutMs: config.loginTimeoutMs,
+          });
+        }
+        保存待完成(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 =
+          e.kind === 'callback_first_wait'
+            ? 'callback_first_wait'
+            : e.kind === 'timeout'
+              ? 'callback_timeout'
+              : 'callback_listen_failed';
+      }
+
+      if (deviceSide.reason) {
+        /**
+         * ⚠️ 判定"谁赢了"用**凭据对象的同一性**：`runLogin` 返回时会 `{...result}` 复制一层外壳
+         *   （见 login.mjs 的返回值），所以比较外层对象会永远不相等；
+         *   而 `credentials` 是那一层里原样带出来的同一个对象，用它判定既准确又同步。
+         */
+        if (deviceSide.result && result.credentials === deviceSide.result.credentials) {
+          /**
+           * ★ 设备码那条路**先**成功：`runLogin` 已经把回调那条路收尾（监听再留一小会儿给迟到的回调），
+           *   这里只要把"最终模式/原因"如实记下来。
+           */
+          useDevice = true;
+          downgradeReason = deviceSide.reason === 'callback_timeout' ? 'callback_timeout' : 'callback_first_wait';
+        } else {
+          /**
+           * ★ 回调那条路**先**成功（本次修复的核心价值：用户后来点的那次【同意】真的换到了令牌）
+           *   ⇒ 把设备码那条路立刻停掉，并给用户一句说明（免得他再去浏览器里确认一个作废的短码）。
+           */
+          deviceSide.cancelled = true;
+          cancelGate.wakeAll();
+          await 停掉设备码那条路(deviceSide, cancelGate);
+          deletePendingDevice(pendingFile);
+          log('ℹ️ 本地回调已经拿到令牌：设备码那条路已停止（刚才那个短码作废，不用再去浏览器里确认）。');
+        }
+      }
+    }
+
+    const account = result.account || null;
+    const creds = result.credentials;
+    const data = {
+      account,
+      mode: useDevice ? 'device' : 'callback',
+      client_id: creds.client_id,
+      scope: creds.scope,
+      expires_at: creds.expires_at,
+      token_ttl_seconds: result.tokenTtlSeconds || creds.expires_in || result.metadata?.access_token_ttl_seconds || null,
+      on_token_expiry: result.onTokenExpiry || result.metadata?.on_token_expiry || null,
+      credentials_file: config.credentialsFile,
+      file_mode: result.mode && result.mode.supported ? result.mode.modeText : '无法判断（Windows）',
+      redirect_uri: result.redirectUri || null,
+      user_code: result.user_code || null,
+      verification_uri: result.verification_uri || null,
+      paste_text: result.paste_text || null,
+      poll_attempts: result.poll_attempts ?? null,
+      logged_in: true,
+      /** ★ 结构化告知"本机代理情况"与"是否因此改道"，AI 端不用去猜 */
+      proxy_warning: proxyPayload,
+      auto_device: downgradeReason ? { applied: true, reason: downgradeReason } : { applied: false, reason: null },
+    };
+
+    if (jsonMode) {
+      // 保持 JSONL：stage=done 是最后一行
+      out.event({ ok: true, command: 'login', stage: 'done', data });
+    } else {
+      out.line('');
+      out.ok(`✅ 授权成功，已登录：${account && (account.email || account.name) ? account.email || account.name : '（账号信息未取到）'}`);
+      if (account && account.sub) out.line(`  用户 ID：${account.sub}`);
+      out.line(`  能力范围：${creds.scope}`);
+      out.line(`  令牌有效期：${creds.expires_in ? `${Math.round(creds.expires_in / 86400)} 天` : '未知'}（到期时间 ${formatTime(creds.expires_at)}）`);
+      out.line(`  凭据文件：${config.credentialsFile}（权限 ${data.file_mode}）`);
+      out.info('  令牌本身不会显示在任何输出里（安全约定）。');
+      if (useDevice && data.user_code) out.info(`  设备码模式：本次短码 ${data.user_code} 已作废，不能再用于下一次授权。`);
+      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('  （本地回调没成功，已自动改用设备码模式完成登录。）');
+    }
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* logout                                                              */
+/* ------------------------------------------------------------------ */
+
+export const logoutCommand = {
+  name: 'logout',
+  summary: '删除本地凭据（默认还会调用服务端吊销接口作废该令牌）',
+  usage: 'wkgeo logout [--local-only]',
+  flags: {
+    'local-only': { type: 'boolean', desc: '只删本地文件，不调服务端吊销接口' },
+  },
+  async run(ctx) {
+    const { out, config, flags, api } = ctx;
+    const creds = readCredentials(config.credentialsFile);
+    if (!creds) {
+      out.warn('本地本来就没有凭据（未登录）');
+      const data = { removed: false, revoked_remote: false, credentials_file: config.credentialsFile };
+      ctx.done(data);
+      return data;
+    }
+
+    let revoke = { ok: false, reason: '已按要求跳过（--local-only）' };
+    if (flags.localOnly !== true) {
+      revoke = await api.revoke(creds.access_token);
+    }
+    const removed = deleteCredentials(config.credentialsFile);
+    const data = {
+      removed,
+      revoked_remote: revoke.ok === true,
+      revoke_error: revoke.ok ? null : revoke.reason || null,
+      credentials_file: config.credentialsFile,
+      client_id: creds.client_id,
+    };
+
+    if (revoke.ok) out.ok('服务端令牌已吊销');
+    else out.warn(`未能吊销服务端令牌（${revoke.reason || '未知原因'}）—— 本地凭据已删除，登录态在本机已清除`);
+    if (removed) out.ok(`本地凭据已删除：${config.credentialsFile}`);
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* whoami                                                              */
+/* ------------------------------------------------------------------ */
+
+export const whoamiCommand = {
+  name: 'whoami',
+  summary: '显示当前登录的是谁（只显示账号标识，绝不打印令牌）',
+  usage: 'wkgeo whoami [--verbose]',
+  async run(ctx) {
+    const { out, config, flags, api } = ctx;
+    const creds = ctx.requireAuth();
+    const info = await api.userinfo(creds.access_token);
+
+    const data = {
+      account: {
+        user_id: info.sub || null,
+        email: info.email || null,
+        nickname: info.name || null,
+      },
+      client_id: creds.client_id,
+      scope: creds.scope,
+      obtained_at: creds.obtained_at || null,
+      expires_at: creds.expires_at || null,
+      expires_in_ms: creds.expires_at ? new Date(creds.expires_at).getTime() - ctx.now() : null,
+      credentials_file: config.credentialsFile,
+      logged_in: true,
+    };
+    if (flags.verbose) {
+      // 掩码是**允许**的（前 6 位 + 长度，抄不走），完整令牌永远不出现
+      data.token_masked = maskToken(creds.access_token);
+      const mode = checkFileMode(config.credentialsFile);
+      data.file_mode = mode.supported ? mode.modeText : '无法判断（Windows）';
+      data.file_mode_too_open = mode.supported ? !!mode.tooOpen : null;
+    }
+
+    if (!out.json) {
+      out.head('当前登录身份');
+      out.line(`  账号：${data.account.email || data.account.nickname || '（服务端未返回账号标识）'}`);
+      out.line(`  用户 ID：${data.account.user_id || '-'}`);
+      out.line(`  应用（client_id）：${data.client_id}`);
+      out.line(`  能力范围：${data.scope}`);
+      out.line(`  令牌到期：${formatTime(data.expires_at)}（${formatRemaining(data.expires_in_ms)}）`);
+      out.line(`  凭据文件：${data.credentials_file}`);
+      if (flags.verbose) {
+        out.line(`  令牌（掩码）：${data.token_masked}`);
+        out.line(`  文件权限：${data.file_mode}${data.file_mode_too_open ? '  ⚠️ 权限过宽，建议 chmod 600' : ''}`);
+      }
+      out.info('  （令牌明文不会显示：需要的是账号标识，不是凭据本身）');
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* config                                                              */
+/* ------------------------------------------------------------------ */
+
+export const configCommand = {
+  name: 'config',
+  summary: '显示当前生效的配置与登录状态（不含任何令牌）',
+  usage: 'wkgeo config',
+  async run(ctx) {
+    const { out, config } = ctx;
+    const creds = readCredentials(config.credentialsFile);
+    const sources = describeConfigSources(ctx.flags, ctx.env);
+    const mode = checkFileMode(config.credentialsFile);
+    /**
+     * ★ 顺带报告"本机代理情况"。
+     *
+     * 为什么放在 `config` 里：这条命令就是**排障入口**（"把你的 config 输出发我"）。
+     * 老板说过"很多用户不懂代理"，让支持同学只用一条命令就能看出
+     * "哦，你机器上有代理且没绕过 127.0.0.1，所以回调收不到" —— 比让用户
+     * 自己去翻注册表/系统设置现实得多。
+     * 检测是**只读**的：不改用户任何设置（见 lib/proxy.mjs 开头三条硬约束）。
+     */
+    const proxy = proxyWarningPayload(ctx.proxyInfo(), { cmdName: config.cmdName || 'wkgeo' });
+
+    const data = {
+      base: config.base,
+      /**
+       * ⚠️ `web_base` 是**兼容字段**：三站拆分后它指向老站（管理端），
+       * 已经没有任何代码用它打开页面 —— 保留只为不破坏既有自动化脚本。
+       * 真正生效的是下面三个按站的基址（2026-10-02 三站拆分新增）。
+       */
+      web_base: config.webBase,
+      oauth_web_base: config.oauthWebBase,
+      pay_web_base: config.payWebBase,
+      user_web_base: config.userWebBase,
+      client_id: config.clientId,
+      scope: config.scope,
+      credentials_file: config.credentialsFile,
+      callback: `http://${config.callbackHost}:${config.callbackPort}${config.callbackPath}`,
+      http_timeout_ms: config.httpTimeoutMs,
+      login_timeout_ms: config.loginTimeoutMs,
+      sources,
+      logged_in: !!creds,
+      expired: creds ? isExpired(creds, { now: ctx.now() }) : null,
+      account: creds && creds.account ? { user_id: creds.account.sub || null, email: creds.account.email || null } : null,
+      expires_at: creds ? creds.expires_at || null : null,
+      file_mode: mode.supported ? mode.modeText : '无法判断（Windows）',
+      /** 结构化：有代理/有风险/建议怎么做（AI 端与支持同学都直接用这份） */
+      proxy,
+    };
+
+    if (!out.json) {
+      out.head('生效配置');
+      for (const [k, v] of Object.entries({
+        'API 基址': data.base,
+        '授权站基址': data.oauth_web_base,
+        '收银台基址': data.pay_web_base,
+        '会员站基址': data.user_web_base,
+        '老站基址（兼容字段，不再用于跳转）': data.web_base,
+        'client_id': data.client_id,
+        '能力范围': data.scope,
+        '回调地址': data.callback,
+        '凭据文件': data.credentials_file,
+      })) {
+        out.line(`  ${k}：${v}`);
+      }
+      out.line(`  登录状态：${data.logged_in ? (data.expired ? '已过期（需重新 login）' : '已登录') : '未登录'}`);
+      if (data.logged_in) {
+        out.line(`  账号：${(data.account && (data.account.email || data.account.user_id)) || '-'}`);
+        out.line(`  令牌到期：${formatTime(data.expires_at)}`);
+      }
+      out.line(`  系统代理：${proxy.detected ? `${proxy.proxy}（来源 ${proxy.source}）` : '未检测到'}`);
+      if (proxy.callback_may_fail) {
+        /**
+         * ⚠️ 口径与 login 一致：**检测到代理就一定会走设备码**（不看绕过列表），
+         *    所以这里不能说"已绕过回环就没问题"（真机上正是这么翻车的）。
+         */
+        out.warn(
+          '  检测到系统代理 → `wkgeo login` 会**直接改用设备码模式**（不再依赖 127.0.0.1 回调；绕过列表写了 127.*/localhost 也不作依据）。',
+        );
+        out.info('    想坚持浏览器回调模式：`wkgeo login --no-auto-device`，并把 127.0.0.1,localhost 加入代理绕过列表。');
+      }
+      out.info(`  （配置来源：${JSON.stringify(sources)}）`);
+    }
+    ctx.done(data);
+    return data;
+  },
+};
+
+/** 未登录时的统一提示（whoami / 业务命令共用） */
+export function notLoggedInError() {
+  return new CliError('尚未登录', { kind: 'unauthenticated', hint: loginHint(), exitCode: EXIT.AUTH });
+}