@xbongbong/xbbcli 2.2.0 → 2.4.0

package/README.md

@@ -1,6 +1,6 @@
 # xbbcli
 
-销帮帮 CRM (`xbb`) 命令行工具。所有命令直接调用 HTTP API，不依赖 `opencli` 或浏览器。
+销帮帮 CRM (`xbb`) 命令行工具。业务命令全部直接调用 HTTP API，不依赖 `opencli`；只有 `auth-login` 会拉起本地浏览器完成一次交互式登录。
 
 ## 安装
 
@@ -15,9 +15,13 @@ xbbcli --help
 
 
 
-首次使用时配置销帮帮凭证：
+首次使用时配置销帮帮凭证（二选一）：
 
 ```bash
+# 方式一：浏览器登录（推荐），自动换取 API token 并完成初始化
+xbbcli auth-login
+
+# 方式二：手动填入已有 token
 xbbcli token-set --corpid <CORPID> --token <TOKEN> --userId <USERID>
 ```
 
@@ -75,7 +79,26 @@ xbbcli token-set --corpid <CORPID> --token <TOKEN> --userId <USERID>
 ]
 ```
 
-`token-set` 会按 `corpid` 新增或覆盖一家公司，并把该公司置为 `enable=true`（其余公司自动置为 `false`），同时写入公司名称 `corpName`（取部门 `id` 为 `1` 的部门名称）和操作人姓名 `userName`（从员工列表中按 `userId` 匹配）。除 `token-set`、`token-list`、`token-use`、`token-del` 外，其余命令都使用 `enable` 为 `true` 的公司配置。
+### 浏览器登录（auth-login，推荐）
+
+不带参数执行 `xbbcli auth-login`：命令会拉起本地 Chrome / Edge 打开销帮帮登录页，你在浏览器里用**任意方式**完成登录（账号密码、短信验证码、钉钉 / 企微 / 飞书扫码都可以），命令检测到登录态后自动换取 API token：
+
+```bash
+xbbcli auth-login                 # 自动探测 Chrome / Edge
+xbbcli auth-login --browser edge  # 指定浏览器（chrome / edge / 可执行文件路径）
+xbbcli auth-login --timeout 600   # 等待登录完成的秒数，默认 300
+xbbcli auth-login --corpid <CORPID>  # 校验登录的企业，不一致时报错
+xbbcli auth-login --keepOpen      # 登录成功后保留浏览器窗口（默认自动关闭）
+```
+
+执行后与 `token-set` 等价：写入 `~/.xbbcli/config.env`、刷新表单缓存、命令映射与部门/员工缓存，并同步 `XBB_*` 环境变量（加 `--noEnv` 可跳过）。
+
+技术实现：零依赖，用 `node:child_process` 以 `--remote-debugging-pipe` 启动浏览器（fd3 写 / fd4 读 CDP，**不开任何调试端口**），profile 固定为 `~/.xbbcli/browser-profile`（与日常浏览器隔离，登录态可复用）；CLI 读取页面 `localStorage` 的 `{corpid, userId, xbbAccessToken}`，再在页面内 `fetch` 网关 `apiToken/getApiToken` 换取个人 token。只支持 Chromium 内核浏览器（Chrome / Edge / Chromium），更多细节见 [`doc/auth-login-command-design.md`](doc/auth-login-command-design.md)。
+
+- `--debug` 输出请求体、返回体与浏览器信息（密钥只显示掩码），`--raw` 输出换取 API token 接口的原始响应
+- 失败时返回合成错误行：`NO_BROWSER`、`BROWSER_CLOSED`、`LOGIN_TIMEOUT`、`API_TOKEN_FAILED`、`CORPID_MISMATCH`、`SAVE_FAILED` 等
+
+`token-set` 会按 `corpid` 新增或覆盖一家公司，并把该公司置为 `enable=true`（其余公司自动置为 `false`），同时写入公司名称 `corpName`（取部门 `id` 为 `1` 的部门名称）和操作人姓名 `userName`（从员工列表中按 `userId` 匹配）。除 `token-set`、`token-list`、`token-use`、`token-del`、`auth-status`、`auth-logout` 外，其余命令都使用 `enable` 为 `true` 的公司配置。
 
 同时会自动拉取两份表单清单并合并缓存到：
 
@@ -116,6 +139,37 @@ xbbcli user-list --pageSize 200 -f json
 - `corpid` 以 `ding` 开头，或包含 `$$ding` 时，使用 `https://proapi.xbongbong.com`
 - 其他 `corpid` 使用 `https://appapi.xbongbong.com`
 
+## 查看当前配置与登出
+
+```bash
+xbbcli auth-status                # 回显当前激活的配置（token 默认掩码）
+xbbcli auth-status --showToken    # 需要完整 token 时
+xbbcli auth-logout                # 登出：删除激活的那一家配置 + 清除 XBB_* 环境变量
+xbbcli auth-logout --noEnv        # 只删 config.env，保留环境变量
+```
+
+- `auth-status` 以 `key` / `value` 两列回显当前生效的配置值，固定 6 行：`corpid`、`corpName`、`userName`、`userId`、`baseurl`、`token`；不再输出 `status`、`source`、`message`、`enable`、`companyCount`、`envActive`、`configFile`、`code`、`msg` 这些元信息列。
+
+```text
+key       value
+corpid    dinge3fa697f86d461d2
+corpName  杭州逍邦网络科技有限公司
+userName  陈会兵
+userId    02415643151585
+baseurl   https://proapi.xbongbong.com
+token     user_6***a7da
+note      以上取值来自环境变量 XBB_*（config.env 中没有启用公司，回落到环境变量）；环境变量模式不支持多公司切换
+```
+
+- 来源（`config.env` 启用公司 还是 `XBB_*`）与冲突提醒只在需要时以 `note` 行追加：环境变量与 `config.env` 同时存在时提示「config.env 启用项优先」；`config.env` 里出现多个 `enable=true` 时提示用 `token-use` 修正。
+- 没有任何生效配置时，6 个值一律留空并给出 `note` 提示下一步命令（即使 `XBB_BASEURL` / `XBB_USERID` 单独残留也不会当成生效值回显）。配置文件路径、公司数量、生效的环境变量名改用 `--debug` 输出到 stderr。
+- `auth-status` 默认把 token 掩码为「前 6 + `***` + 后 4」（长度不足 11 时只保留前 2 位），只有 `--showToken` 才输出明文。
+- `auth-logout` 只删除 `enable=true` 的那一条，**不会**把其他公司自动提升为启用：登出后本地可能一个启用公司都没有，需要 `xbbcli token-use --corpid <CORPID>` 或重新 `auth-login` / `token-set`。想保留其他公司并可切换时，用 `xbbcli token-del --corpid <CORPID>`（它会保证剩余配置仍有且仅有一个启用）。
+- 删除前 `config.env` 会整份备份到 `~/.xbbcli/config.env.bak`（每次登出覆盖），`backupFile` 列给出路径；误删把 `.bak` 复制回 `config.env` 即可恢复。
+- 默认**同时**清除 `XBB_*` 环境变量：Windows 用 `reg delete HKCU\Environment` 删除用户级变量（已打开的终端要重开才生效，`envStored` 为 `user`，原本就不存在时为 `none`）；macOS/Linux 清理 `~/.xbbcli/env.sh` 里的 `export XBB_*` 行（文件清空则删除，`envStored` 为 `cleared` / `removed` / `none`）。加 `--noEnv`（或 `--env=false`）时只删 `config.env`，此时若环境变量仍在，`message` 会提示「业务命令会回落到它，本次不算彻底登出」（`XBB_ENV_ONLY=1` 时提示为「已强制只用环境变量」）。
+- `config.env` 没有启用公司时：只有在环境变量确实存在时才只清环境变量（`config.env` 保持不动）；两者都不存在则返回 `NO_ACTIVE_CONFIG`，不写任何文件。
+- 任何情况都不改动 `<corpid>.formlist.json` / `<corpid>.command-map.md` / `<corpid>.department-user.json` 三份缓存，重新启用该公司时无需再次拉取。
+
 ## 环境变量模式（单公司）
 
 除 `config.env` 外，命令也支持从环境变量读取一家公司的凭证，便于 CI、容器与其他工具集成：
@@ -142,12 +196,15 @@ xbbcli user-list --pageSize 200 -f json
 
 环境变量模式只支持一家公司：此时 `token-list` 以 `source=env` 单行显示，`token-use` / `token-del` 会返回不支持多公司的错误行，并提示改用 `config.env`。
 
-> 注意：`token-del` 不会清理已经写入的环境变量。如需移除环境变量模式，Windows 下执行 `setx XBB_TOKEN ""`（其余 `XBB_*` 同理）并重开终端；macOS/Linux 下删除 `~/.xbbcli/env.sh`，再 `unset` 当前 shell 中已导出的变量。
+> 注意：`token-del` 不会清理已经写入的环境变量。要连环境变量一起登出，执行 `xbbcli auth-logout`（默认就会清除 `XBB_*`）；也可以手工执行 `setx XBB_TOKEN ""`（其余 `XBB_*` 同理，Windows 需重开终端）或删除 `~/.xbbcli/env.sh` 并 `unset` 当前 shell 中已导出的变量。
 
 ## 当前支持的命令
 
 ### 配置
 
+- `auth-login`：拉起本地浏览器完成交互式登录（账号密码 / 短信 / 扫码均可），自动读取 Web 会话、换取 API token 并复用 `token-set` 落盘；支持 `--browser`、`--timeout`、`--corpid`、`--keepOpen`、`--noEnv`、`--debug`、`--raw`
+- `auth-status`：以 `key` / `value` 两列回显当前激活配置的 `corpid`、`corpName`、`userName`、`userId`、`baseurl`、`token`（token 默认中间掩码，`--showToken` 出明文），来源与冲突提醒以 `note` 行追加，无生效配置时六个值留空并给出 `note`；`--debug` 在 stderr 输出配置文件路径、公司数量与生效的环境变量名
+- `auth-logout`：删除 `config.env` 中 `enable=true` 的那一条配置，删除前整份备份为 `~/.xbbcli/config.env.bak`；不自动把其他公司提升为启用；默认同时清除 `XBB_*` 环境变量（`--noEnv` / `--env=false` 跳过，返回 `envStored` / `envFile`）；既无启用公司又无环境变量时返回 `NO_ACTIVE_CONFIG` 且不改动文件
 - `token-set`：保存个人 token、`corpid`、`userId`、`baseurl`，并刷新本地表单缓存、命令映射文件与部门/员工缓存；传入的 token 不以 `user_` 开头时，会先为该 `userId` 刷新并保存个人 token；成功后同步写入 `XBB_*` 环境变量（Windows 用 `setx`，其他平台写 `~/.xbbcli/env.sh`），`--noEnv` 可跳过；返回 `envStored` / `envFile` 两列
 - `token-list`：列出本地保存的所有公司配置和唯一启用的公司（含 `corpName` 公司名称与 `userName` 操作人姓名，`source` 列标记来源 `config`/`env`）；`--showToken` 显示完整 token（默认脱敏）；环境变量模式下单行显示
 - `token-use`：切换当前启用的公司（`xbbcli token-use --corpid <CORPID>`），保证仅且只有一个公司被启用
@@ -394,7 +451,8 @@ xbbcli user-list --pageSize 200 -f json
 
 ## 通用行为
 
-- 先执行一次 `token-set` 保存有效的 `corpid`、`token`、`userId`
+- 先执行一次 `token-set`（或 `auth-login`）保存有效的 `corpid`、`token`、`userId`
+- 用 `xbbcli auth-status` 查看当前生效的配置来自 `config.env` 还是环境变量；`xbbcli auth-logout` 删除激活配置并默认清除 `XBB_*` 环境变量（`--noEnv` 保留）
 - 除 `token-set` 外，其余命令都会从 `~/.xbbcli/config.env` 读取 `corpid`
 - 大部分命令会从 `~/.xbbcli/config.env` 读取 `token`
 - 未配置 `config.env`（或其中没有启用公司）时，命令会回落到 `XBB_CORPID` / `XBB_TOKEN` / `XBB_BASEURL` / `XBB_USERID` / `XBB_CORPNAME` / `XBB_USERNAME` 环境变量；`XBB_ENV_ONLY=1` 可强制只用环境变量
@@ -416,7 +474,10 @@ xbbcli user-list --pageSize 200 -f json
 ### 基础配置/初始化
 
 ```bash
+xbbcli auth-login
 xbbcli token-set --corpid your_corpid --token your_token --userId your_userid
+xbbcli auth-status
+xbbcli auth-logout
 ```
 
 ### 员工信息

package/auth-login.js

@@ -0,0 +1,306 @@
+import crypto from 'node:crypto';
+import { cli, Strategy } from './xbb-registry.js';
+import { openBrowser, findBrowserExecutable, LOGIN_PAGE_URL } from './xbb-browser.js';
+import { saveCompanyCredentials } from './xbb-token-store.js';
+
+const API_TOKEN_PATH = '/pro/v1/apiToken/getApiToken';
+const PRO_GATEWAY_ORIGIN = 'https://progateway.xbongbong.com';
+const APP_GATEWAY_ORIGIN = 'https://appgateway.xbongbong.com';
+const PLATFORM = 'web';
+// 登录成功判据：页面已跳转到工作台首页 /#/app/home
+const LOGIN_SUCCESS_PATTERN = /#\/app\/home/;
+const DEFAULT_TIMEOUT_SECONDS = 300;
+const POLL_INTERVAL_MS = 1000;
+// 网关提示登录态过期时，清掉页面里的旧会话并继续等待用户重新登录
+const SESSION_EXPIRED_CODE = 100012;
+
+function delay(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function normalizeArg(value) {
+  return String(value ?? '').trim();
+}
+
+// 网关域名与企业 baseurl 用同一套 corpid 判定：ding 开头或含 $$ding 走 pro 网关
+function resolveGatewayUrl(corpid) {
+  const value = normalizeArg(corpid);
+  const origin = value.startsWith('ding') || value.includes('$$ding') ? PRO_GATEWAY_ORIGIN : APP_GATEWAY_ORIGIN;
+  return `${origin}${API_TOKEN_PATH}`;
+}
+
+function buildSign(body, secret) {
+  return crypto.createHash('sha256').update(body + secret).digest('hex');
+}
+
+function maskSecret(value) {
+  const text = String(value || '');
+  if (!text) return '';
+  return `${text.slice(0, 6)}***(${text.length})`;
+}
+
+// 统一输出：成功时与 token-set 的列保持一致，失败时回落到合成错误行（不抛异常）
+function makeRow(fields) {
+  return [{
+    status: '',
+    message: '',
+    configFile: '',
+    corpid: '',
+    baseurl: '',
+    userId: '',
+    enable: '',
+    companyCount: '',
+    formlistFile: '',
+    commandMapFile: '',
+    departmentUserFile: '',
+    corpName: '',
+    userName: '',
+    envStored: '',
+    envFile: '',
+    code: '',
+    msg: '',
+    ...fields,
+  }];
+}
+
+function makeErrorRow(code, msg, extra = {}) {
+  return makeRow({ status: 'error', code, msg, message: msg, ...extra });
+}
+
+// 读取登录页写入的 web 会话（登录成功后前端会写入 corpid / userId / xbbAccessToken）
+const READ_SESSION_EXPRESSION = `JSON.stringify({
+  corpid: localStorage.getItem('corpid') || '',
+  userId: localStorage.getItem('userId') || '',
+  accessToken: localStorage.getItem('xbbAccessToken') || '',
+  corpName: localStorage.getItem('corpName') || '',
+  userName: localStorage.getItem('userName') || '',
+  href: location.href
+})`;
+
+async function readSession(session) {
+  const raw = await session.evaluate(READ_SESSION_EXPRESSION, { attempts: 1, delayMs: 100 });
+  if (typeof raw !== 'string' || !raw) throw new Error('未读取到页面登录态');
+  const parsed = JSON.parse(raw);
+  return {
+    corpid: normalizeArg(parsed.corpid),
+    userId: normalizeArg(parsed.userId),
+    accessToken: normalizeArg(parsed.accessToken),
+    corpName: normalizeArg(parsed.corpName),
+    userName: normalizeArg(parsed.userName),
+    href: normalizeArg(parsed.href),
+  };
+}
+
+// 在页面内调用网关换取 API token：CORS 全开，sign = SHA256(JSON body + xbbAccessToken)
+async function exchangeApiToken(session, loginSession, debug) {
+  const url = resolveGatewayUrl(loginSession.corpid);
+  const body = JSON.stringify({ corpid: loginSession.corpid, userId: loginSession.userId, platform: PLATFORM });
+  const sign = buildSign(body, loginSession.accessToken);
+  const expression = `(async () => {
+  const response = await fetch(${JSON.stringify(url)}, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json;charset=UTF-8', corpid: ${JSON.stringify(loginSession.corpid)}, sign: ${JSON.stringify(sign)} },
+    body: ${JSON.stringify(body)}
+  });
+  return await response.text();
+})()`;
+
+  if (debug) {
+    process.stderr.write(`[debug] Gateway: ${url}\n[debug] Headers: ${JSON.stringify({ 'Content-Type': 'application/json;charset=UTF-8', corpid: loginSession.corpid, sign })}\n[debug] RequestBody: ${body}\n[debug] SessionToken: ${maskSecret(loginSession.accessToken)}\n`);
+  }
+
+  const text = await session.evaluate(expression, { attempts: 3, delayMs: 200 });
+  const responseText = typeof text === 'string' ? text : JSON.stringify(text);
+  if (debug) process.stderr.write(`[debug] ResponseBody: ${responseText}\n`);
+
+  let data;
+  try {
+    data = JSON.parse(responseText);
+  } catch {
+    return { error: `换取 API token 失败：返回内容不是 JSON（${responseText.slice(0, 200)}）` };
+  }
+  if (Number(data.code) === SESSION_EXPIRED_CODE) {
+    return { sessionExpired: true };
+  }
+  if (Number(data.code) !== 1) {
+    return { error: `换取 API token 失败：${data.msg || '未知错误'}（code ${data.code ?? ''}）；也可到销帮帮「个人中心 - API 设置」复制 token 后执行 xbbcli token-set` };
+  }
+
+  const result = data.result;
+  const token = normalizeArg(typeof result === 'string' ? result : (result && result.token));
+  if (!token) {
+    return { error: '接口未返回 API token；可到销帮帮「个人中心 - API 设置」复制 token 后执行 xbbcli token-set' };
+  }
+  return {
+    token,
+    corpid: normalizeArg(result && result.corpid) || loginSession.corpid,
+    userId: normalizeArg(result && result.userId) || loginSession.userId,
+    responseText,
+  };
+}
+
+async function clearAccessToken(session) {
+  try {
+    await session.evaluate(`(() => { localStorage.removeItem('xbbAccessToken'); return 'ok'; })()`, { attempts: 1 });
+  } catch {
+    // 忽略：清理旧会话失败不阻塞后续等待
+  }
+}
+
+async function finish(session, keepOpen) {
+  if (!session) return;
+  if (keepOpen) {
+    session.detach();
+    return;
+  }
+  try {
+    await session.close();
+  } catch {
+    // 忽略：浏览器可能已被用户手动关闭
+  }
+}
+
+async function authLogin(kwargs) {
+  const debug = Boolean(kwargs.debug);
+  const explicitBrowser = normalizeArg(kwargs.browser);
+  const keepOpen = Boolean(kwargs.keepOpen);
+  const expectCorpid = normalizeArg(kwargs.corpid);
+  const timeoutValue = normalizeArg(kwargs.timeout);
+  const timeoutSeconds = timeoutValue === '' ? DEFAULT_TIMEOUT_SECONDS : Number(timeoutValue);
+
+  if (!Number.isFinite(timeoutSeconds) || timeoutSeconds <= 0) {
+    return makeErrorRow('INVALID_TIMEOUT', '--timeout 需为大于 0 的秒数');
+  }
+  if (!findBrowserExecutable(explicitBrowser)) {
+    return makeErrorRow('NO_BROWSER', '未找到 Chrome 或 Edge 浏览器；请用 --browser <chrome|edge|可执行文件路径> 指定');
+  }
+
+  let session;
+  try {
+    session = await openBrowser({ browser: explicitBrowser, url: LOGIN_PAGE_URL });
+  } catch (error) {
+    return makeErrorRow('BROWSER_SPAWN_FAILED', `启动浏览器失败：${error.message || error}`);
+  }
+
+  if (debug) {
+    process.stderr.write(`[debug] Browser: ${session.executablePath}\n[debug] Profile: ${session.userDataDir}\n[debug] LoginPage: ${LOGIN_PAGE_URL}\n`);
+  }
+
+  try {
+    await session.waitForPage(30000);
+  } catch (error) {
+    await finish(session, keepOpen);
+    return makeErrorRow('BROWSER_LAUNCH_FAILED', `打开销帮帮登录页失败：${error.message || error}`);
+  }
+
+  process.stderr.write('请在打开的浏览器中完成登录，登录成功后本命令会自动获取并保存 API token。\n');
+
+  const deadline = Date.now() + timeoutSeconds * 1000;
+  let lastMessage = '';
+  while (Date.now() < deadline) {
+    if (session.isClosed()) {
+      await finish(session, keepOpen);
+      return makeErrorRow('BROWSER_CLOSED', '浏览器已被关闭，登录未完成');
+    }
+
+    let current;
+    try {
+      current = await readSession(session);
+    } catch (error) {
+      lastMessage = String(error.message || error);
+      await delay(POLL_INTERVAL_MS);
+      continue;
+    }
+
+    if (!current.accessToken) {
+      await delay(POLL_INTERVAL_MS);
+      continue;
+    }
+
+    // accessToken 已写入但页面还在登录流程中：等跳转到工作台首页再换取，避免会话未就绪时误判
+    if (!LOGIN_SUCCESS_PATTERN.test(current.href)) {
+      lastMessage = `页面地址为 ${current.href || '未知'}，尚未跳转到登录成功页 /#/app/home`;
+      await delay(POLL_INTERVAL_MS);
+      continue;
+    }
+
+    const exchange = await exchangeApiToken(session, current, debug);
+    if (exchange.sessionExpired) {
+      // 旧会话已过期：清掉后继续等待用户重新登录
+      await clearAccessToken(session);
+      await delay(POLL_INTERVAL_MS);
+      continue;
+    }
+    if (exchange.error) {
+      await finish(session, keepOpen);
+      return makeErrorRow('API_TOKEN_FAILED', exchange.error, { corpid: current.corpid, userId: current.userId });
+    }
+    if (kwargs.raw) {
+      await finish(session, keepOpen);
+      return [{ raw: exchange.responseText }];
+    }
+    if (expectCorpid && exchange.corpid !== expectCorpid) {
+      await finish(session, keepOpen);
+      return makeErrorRow(
+        'CORPID_MISMATCH',
+        `浏览器登录的企业是 ${exchange.corpid}，与 --corpid ${expectCorpid} 不一致；请确认浏览器中登录了正确的企业`,
+        { corpid: exchange.corpid, userId: exchange.userId },
+      );
+    }
+
+    let savedRows;
+    try {
+      savedRows = await saveCompanyCredentials({
+        corpid: exchange.corpid,
+        token: exchange.token,
+        userId: exchange.userId,
+        noEnv: Boolean(kwargs.noEnv),
+      });
+    } catch (error) {
+      await finish(session, keepOpen);
+      return makeErrorRow('SAVE_FAILED', `保存凭证失败：${error.message || error}`, { corpid: exchange.corpid, userId: exchange.userId });
+    }
+
+    await finish(session, keepOpen);
+
+    const saved = (savedRows && savedRows[0]) || {};
+    const savedOk = normalizeArg(saved.status) === 'ok';
+    return [{
+      ...saved,
+      status: savedOk ? 'ok' : (normalizeArg(saved.status) || 'error'),
+      message: savedOk
+        ? `登录成功；${saved.message || ''}`
+        : `已换取 API token，但初始化未完成：${saved.message || '未知原因'}`,
+      corpid: normalizeArg(saved.corpid) || exchange.corpid,
+      userId: normalizeArg(saved.userId) || exchange.userId,
+      baseurl: normalizeArg(saved.baseurl),
+    }];
+  }
+
+  await finish(session, keepOpen);
+  return makeErrorRow(
+    'LOGIN_TIMEOUT',
+    `等待登录超时（${timeoutSeconds}s），未在浏览器中检测到登录成功态${lastMessage ? `；${lastMessage}` : ''}`,
+  );
+}
+
+cli({
+  site: 'xbb',
+  name: 'auth-login',
+  description: '打开浏览器完成销帮帮登录授权（等价于token-set）',
+  strategy: Strategy.PUBLIC,
+  access: 'write',
+  browser: false,
+  domain: 'appwebfront.xbongbong.com',
+  args: [
+    { name: 'browser', type: 'str', default: '', help: '浏览器：chrome / edge / 可执行文件路径；不传则自动探测' },
+    { name: 'timeout', type: 'str', default: '', help: `等待登录完成的秒数（默认 ${DEFAULT_TIMEOUT_SECONDS}）` },
+    { name: 'corpid', type: 'str', default: '', help: '期望登录的企业 ID；与实际登录企业不一致时报错（可选）' },
+    { name: 'keepOpen', type: 'bool', default: false, help: '登录成功后保留浏览器窗口（默认自动关闭）' },
+    { name: 'noEnv', type: 'bool', default: false, help: '不写入环境变量，仅保存到 config.env' },
+    { name: 'debug', type: 'bool', default: false, help: '输出请求体、返回体与浏览器信息（密钥只显示掩码）' },
+    { name: 'raw', type: 'bool', default: false, help: '输出换取 API token 接口返回的原文' },
+  ],
+  columns: ['status', 'message', 'configFile', 'corpid', 'baseurl', 'userId', 'enable', 'companyCount', 'formlistFile', 'commandMapFile', 'departmentUserFile', 'corpName', 'userName', 'envStored', 'envFile', 'code', 'msg'],
+  func: authLogin,
+});

package/auth-logout.js

@@ -0,0 +1,175 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { cli, Strategy } from './xbb-registry.js';
+import { clearEnvVars, getEnvVarNames, hasEnvConfig, isEnvOnly, readEnvConfig } from './xbb-config.js';
+
+const CONFIG_DIR = path.join(os.homedir(), '.xbbcli');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.env');
+const BACKUP_FILE = path.join(CONFIG_DIR, 'config.env.bak');
+
+function trim(value) {
+  return String(value ?? '').trim();
+}
+
+function readCompanies() {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+    if (Array.isArray(parsed)) {
+      return parsed.filter((item) => item && typeof item === 'object');
+    }
+    if (parsed && Array.isArray(parsed.companies)) {
+      return parsed.companies.filter((item) => item && typeof item === 'object');
+    }
+    if (parsed && parsed.corpid) {
+      const { corpid, token, baseurl, userId } = parsed;
+      return [{ corpid, token, baseurl, userId, enable: true }];
+    }
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+function writeCompanies(companies) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(companies, null, 2) + '\n', 'utf8');
+}
+
+function createRow(fields) {
+  return [{
+    status: '',
+    message: '',
+    configFile: CONFIG_FILE,
+    backupFile: '',
+    corpid: '',
+    corpName: '',
+    userId: '',
+    companyCount: '',
+    hasActive: '',
+    envStored: '',
+    envFile: '',
+    code: '',
+    msg: '',
+    ...fields,
+  }];
+}
+
+function previewCorpids(companies) {
+  const names = companies.slice(0, 3).map((item) => trim(item.corpid)).filter(Boolean);
+  return names.join(', ') + (companies.length > 3 ? ' …' : '');
+}
+
+async function authLogout(kwargs) {
+  const alsoEnv = !kwargs.noEnv && kwargs.env !== false;
+  const companies = readCompanies();
+  const index = companies.findIndex((item) => item && item.enable === true);
+  const envPresent = hasEnvConfig();
+  const envBefore = envPresent ? trim(readEnvConfig().corpid) : '';
+
+  if (kwargs.debug) {
+    process.stderr.write(`[debug] ConfigFile: ${CONFIG_FILE}\n[debug] BackupFile: ${BACKUP_FILE}\n[debug] Companies: ${companies.length}\n[debug] EnabledIndex: ${index}\n[debug] ClearEnv: ${alsoEnv}\n[debug] EnvCorpid: ${envBefore || 'none'}\n[debug] EnvVarsSet: ${getEnvVarNames().filter((name) => trim(process.env[name])).join(', ') || 'none'}\n`);
+  }
+
+  if (index === -1 && (!alsoEnv || !envPresent)) {
+    const scope = companies.length
+      ? `本地共 ${companies.length} 家公司（${previewCorpids(companies)}）且均未启用；要登出某家请先用 xbbcli token-use --corpid <CORPID> 启用，或改用 xbbcli token-del --corpid <CORPID> 直接删除`
+      : '本地没有任何公司配置';
+    const envNote = envPresent
+      ? '环境变量 XBB_* 仍存在，本次未清除（去掉 --noEnv / --env=false 即可一并清除）'
+      : '环境变量 XBB_* 也不存在，本次无可清除内容';
+    const hint = `${scope}；${envNote}`;
+    return createRow({
+      status: 'error',
+      message: `config.env 中没有处于激活状态（enable=true）的配置；${hint}`,
+      companyCount: String(companies.length),
+      hasActive: 'false',
+      envStored: 'skipped',
+      code: 'NO_ACTIVE_CONFIG',
+      msg: isEnvOnly() ? `${hint}（当前 XBB_ENV_ONLY=1，config.env 被忽略）` : hint,
+    });
+  }
+
+  const target = index === -1 ? null : companies[index];
+  const remaining = target ? companies.filter((item, itemIndex) => itemIndex !== index) : companies;
+  let backupFile = '';
+
+  if (target) {
+    try {
+      if (fs.existsSync(CONFIG_FILE)) {
+        fs.copyFileSync(CONFIG_FILE, BACKUP_FILE);
+        backupFile = BACKUP_FILE;
+      }
+      writeCompanies(remaining);
+    } catch (error) {
+      const detail = String(error.message || error);
+      return createRow({
+        status: 'error',
+        message: `删除激活配置失败：${detail}；config.env 未被改动`,
+        corpid: trim(target.corpid),
+        companyCount: String(companies.length),
+        envStored: 'skipped',
+        code: 'WRITE_FAILED',
+        msg: detail,
+      });
+    }
+  }
+
+  let envStored = 'skipped';
+  let envFile = '';
+  const parts = [];
+  parts.push(target
+    ? `已登出 corpid=${trim(target.corpid)}（config.env 中该条配置已删除，剩余 ${remaining.length} 家${remaining.length ? '，均未启用' : '，本地已无配置'}）`
+    : 'config.env 中没有激活配置，未改动');
+  if (backupFile) {
+    parts.push(`原配置已备份到 ${backupFile}`);
+  }
+
+  if (alsoEnv) {
+    try {
+      const result = clearEnvVars();
+      envStored = result.stored;
+      envFile = result.file;
+      const suffix = process.platform === 'win32' ? '；已打开的终端需重开才会消失' : '';
+      parts.push(`环境变量 ${getEnvVarNames().join('、')} 已清除（${envStored}）${suffix}`);
+    } catch (error) {
+      envStored = 'failed';
+      envFile = String(error.message || error);
+      parts.push(`清除环境变量失败：${envFile}`);
+    }
+  } else if (envBefore) {
+    const forced = isEnvOnly() ? '且 XBB_ENV_ONLY=1 已强制只用环境变量' : '业务命令会回落到它';
+    parts.push(`注意：环境变量 XBB_*（corpid=${envBefore}）仍然有效，${forced}，本次不算彻底登出；如需一并清除请去掉 --noEnv（auth-logout 默认会清除环境变量）`);
+  }
+
+  const remainingCompanies = target ? remaining : readCompanies();
+  return createRow({
+    status: envStored === 'failed' ? 'partial' : 'ok',
+    message: parts.join('；'),
+    backupFile,
+    corpid: target ? trim(target.corpid) : '',
+    corpName: target ? trim(target.corpName) : '',
+    userId: target ? trim(target.userId) : '',
+    companyCount: String(remainingCompanies.length),
+    hasActive: remainingCompanies.some((item) => item && item.enable === true) ? 'true' : 'false',
+    envStored,
+    envFile,
+  });
+}
+
+cli({
+  site: 'xbb',
+  name: 'auth-logout',
+  description: '登出',
+  strategy: Strategy.PUBLIC,
+  access: 'write',
+  browser: false,
+  domain: 'proapi.xbongbong.com',
+  args: [
+    { name: 'env', type: 'bool', default: true, help: '同时清除 XBB_* 环境变量（默认开启；--env=false 跳过）。Windows 删除用户级变量，其他平台清理 ~/.xbbcli/env.sh' },
+    { name: 'noEnv', type: 'bool', default: false, help: '不清除环境变量，仅删除 config.env 中的激活配置（与 token-set 的 --noEnv 一致）' },
+    { name: 'debug', type: 'bool', default: false, help: '输出配置文件、备份路径与生效的环境变量名（不打印 token）' },
+  ],
+  columns: ['status', 'message', 'configFile', 'backupFile', 'corpid', 'corpName', 'userId', 'companyCount', 'hasActive', 'envStored', 'envFile', 'code', 'msg'],
+  func: authLogout,
+});