@xbongbong/xbbcli 2.4.1 → 2.4.3

package/README.md

@@ -98,6 +98,20 @@ xbbcli auth-login --keepOpen      # 登录成功后保留浏览器窗口（默
 - `--debug` 输出请求体、返回体与浏览器信息（密钥只显示掩码），`--raw` 输出换取 API token 接口的原始响应
 - 失败时返回合成错误行：`NO_BROWSER`、`BROWSER_CLOSED`、`LOGIN_TIMEOUT`、`API_TOKEN_FAILED`、`CORPID_MISMATCH`、`SAVE_FAILED` 等
 
+### 刷新本地缓存（auth-refresh-cache）
+
+`token-set` / `auth-login` 保存凭证时会顺带刷新三份本地缓存。插件升级（新增命令导致命令映射变化）、缓存过期或被删除后，可以单独重刷，不需要重新输入 token：
+
+```bash
+xbbcli auth-refresh-cache -f json
+```
+
+- 刷新范围（仅当前启用公司）：`~/.xbbcli/<corpid>.formlist.json`（表单清单）、`~/.xbbcli/<corpid>.command-map.md`（命令映射）、`~/.xbbcli/<corpid>.department-user.json`（部门/员工清单），并把 `corpName` / `userName` 回填进 `config.env`
+- 环境变量模式（`XBB_*`）下同样可用：只刷新缓存文件，不回填 `config.env`
+- 只支持当前启用公司：底层接口一律使用启用公司的凭证，切换公司请先用 `xbbcli token-use`
+- `--userId` 覆盖用于匹配 `userName` 的员工 id（默认取配置里的 `userId`）；`--debug` 在 stderr 输出配置来源、corpid 与三份缓存文件路径
+- 失败时返回 `status=error`、`code=CACHE_REFRESH_FAILED`，`message` 以「步骤 formlist / command-map / department-user / profile」指出中断位置，已完成的部分照常在对应列输出
+
 `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` 的公司配置。
 
 同时会自动拉取两份表单清单并合并缓存到：
@@ -145,10 +159,10 @@ xbbcli user-list --pageSize 200 -f json
 xbbcli auth-status                # 回显当前激活的配置（token 默认掩码）
 xbbcli auth-status --showToken    # 需要完整 token 时
 xbbcli auth-logout                # 登出：删除激活的那一家配置 + 清除 XBB_* 环境变量
-xbbcli auth-logout --noEnv        # 只删 config.env，保留环境变量
+xbbcli auth-logout --env 0        # 只删 config.env，保留环境变量
 ```
 
-- `auth-status` 以 `key` / `value` 两列回显当前生效的配置值，固定 6 行：`corpid`、`corpName`、`userName`、`userId`、`baseurl`、`token`；不再输出 `status`、`source`、`message`、`enable`、`companyCount`、`envActive`、`configFile`、`code`、`msg` 这些元信息列。
+- `auth-status` 以 `key` / `value` 两列回显当前生效的配置值，固定 6 行：`corpid`、`corpName`、`userName`、`userId`、`baseurl`、`token`；随后追加 1 行 `验证`（用一次 `user-list --pageSize 1` 调用实测 token：`有效` / `无效-请重新配置token`）；不再输出 `status`、`source`、`message`、`enable`、`companyCount`、`envActive`、`configFile`、`code`、`msg` 这些元信息列。
 
 ```text
 key       value
@@ -158,15 +172,17 @@ 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。
+- 来源（`config.env` 启用公司 还是 `XBB_*`）与冲突提醒只在需要时以 `note` 行追加：环境变量与 `config.env` 同时存在时提示「环境变量优先，`config.env` 中启用（`enable=true`）的公司被覆盖」并提示清除环境变量可切回配置文件；`config.env` 里出现多个 `enable=true` 时提示用 `token-use` 修正。
+- `auth-status` 的 `验证` 行会实打实发起一次 `user-list --pageSize 1` 请求（等价于手工执行 `xbbcli user-list --pageSize 1`）：接口成功（含 `NO_DATA` 空清单）→ `有效`；接口返回业务错误码或请求异常 → `无效-请重新配置token`。没有生效配置或缺少 token 时不再发起请求，直接给出 `无效-请重新配置token`；`--debug` 会输出判定结果与原因。
+- 没有任何生效配置时，6 个配置值一律留空（`验证` 行为 `无效-请重新配置token`）并给出 `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>`（它会保证剩余配置仍有且仅有一个启用）。
+- `auth-logout` 只删除 `enable=true` 的那一条，**不会**把其他公司自动提升为启用：登出后本地可能一个启用公司都没有，需要 `xbbcli token-use --corpid <CORPID>` 或重新 `auth-login` / `token-set`。想保留其他公司并可切换时，用 `xbbcli token-del --corpid <CORPID>`（它会保证剩余配置仍有且仅有一个启用；默认还会删除 `XBB_*` 环境变量，传 `--env 0` 可保留）。
 - 删除前 `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` 时提示为「已强制只用环境变量」）。
+- 默认**同时**清除 `XBB_*` 环境变量：Windows 用 `reg delete HKCU\Environment` 删除用户级变量（已打开的终端要重开才生效，`envStored` 为 `user`，原本就不存在时为 `none`）；macOS/Linux 清理 `~/.xbbcli/env.sh` 里的 `export XBB_*` 行（文件清空则删除，`envStored` 为 `cleared` / `removed` / `none`）。传 `--env 0` 时只删 `config.env`，此时若环境变量仍在，`message` 会提示「其优先级高于 config.env，业务命令仍会使用它，本次不算彻底登出」（`XBB_ENV_ONLY=1` 时提示为「已强制只用环境变量」）。
 - `config.env` 没有启用公司时：只有在环境变量确实存在时才只清环境变量（`config.env` 保持不动）；两者都不存在则返回 `NO_ACTIVE_CONFIG`，不写任何文件。
 - 任何情况都不改动 `<corpid>.formlist.json` / `<corpid>.command-map.md` / `<corpid>.department-user.json` 三份缓存，重新启用该公司时无需再次拉取。
 
@@ -185,30 +201,33 @@ note      以上取值来自环境变量 XBB_*（config.env 中没有启用公
 
 读取优先级：
 
-1. `config.env` 中存在 `enable=true` 的公司时，使用该配置（多公司切换行为不变）
-2. `config.env` 缺失、解析失败或没有启用公司时，回落到上述环境变量
+1. 环境变量 `XBB_*` 中 `XBB_CORPID` / `XBB_TOKEN` 有值时，优先使用环境变量（`config.env` 中 `enable=true` 的公司被覆盖，命令会以环境变量为准）
+2. 环境变量不存在时，使用 `config.env` 中存在 `enable=true` 的公司（多公司切换行为不变）
 3. 设置 `XBB_ENV_ONLY=1` 可强制只使用环境变量（完全忽略 `config.env`）
 
+> 注意：由于环境变量优先，早先 `--env 1` 写入的 `XBB_*` 会覆盖之后 `token-set --env 0` 写入的 `config.env`（`token-set` 的 `message` 会给出提示）。要切回 `config.env` 请先清除 `XBB_*` 环境变量，或执行 `xbbcli auth-logout`（默认会一并清除）。
+
 `token-set` / `auth-login` 通过 `--env` 控制存储方式：`--env 0`（默认）仅写入本地文件（`config.env` 与各类缓存），`--env 1` 仅写入环境变量（不写任何本地文件）。选 `--env 1` 时会把 `corpid`/`token`/`baseurl`/`userId` 写入环境变量：
 
 - Windows：用 `setx` 写入用户级环境变量，**只对新开的终端生效**
 - macOS/Linux：写入 `~/.xbbcli/env.sh`（`export` 形式，权限 600），需要 `source ~/.xbbcli/env.sh` 才在当前 shell 生效
 
-环境变量模式只支持一家公司：此时 `token-list` 以 `source=env` 单行显示，`token-use` / `token-del` 会返回不支持多公司的错误行，并提示改用 `config.env`。
+环境变量模式只支持一家公司：此时 `token-list` 会把环境变量行（`source=env`）与 `config.env` 中的公司行（`source=config`）一起列出，并在 `msg` 列标注各自当前是否生效；`token-use` 会在切换 `config.env` 启用公司的同时，把该公司凭证同步写回 `XBB_*` 环境变量（目标公司缺 `token` 时拒绝切换，避免残留旧 `XBB_TOKEN`）；`token-del` 默认在删除公司的同时一并删除 `XBB_*` 环境变量（`--env 0` 可保留），并在 `message` 说明删除后的实际生效来源。
 
-> 注意：`token-del` 不会清理已经写入的环境变量。要连环境变量一起登出，执行 `xbbcli auth-logout`（默认就会清除 `XBB_*`）；也可以手工执行 `setx XBB_TOKEN ""`（其余 `XBB_*` 同理，Windows 需重开终端）或删除 `~/.xbbcli/env.sh` 并 `unset` 当前 shell 中已导出的变量。
+> 注意：`token-del --env 0` 保留环境变量时，若 `XBB_*` 仍有效，其优先级高于 `config.env`，业务命令仍会使用它（`message` 会给出提示）；要连环境变量一起清理，用 `token-del` 默认行为（不传 `--env`）或执行 `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`、`--env`、`--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` 且不改动文件
+- `auth-status`：以 `key` / `value` 两列回显当前激活配置的 `corpid`、`corpName`、`userName`、`userId`、`baseurl`、`token`（token 默认中间掩码，`--showToken` 出明文），并追加 `验证` 行（调用一次 `user-list --pageSize 1` 实测 token，`有效` / `无效-请重新配置token`）；来源与冲突提醒以 `note` 行追加，无生效配置时六个值留空并给出 `note`；`--debug` 在 stderr 输出配置文件路径、公司数量、生效的环境变量名与验证结果
+- `auth-logout`：删除 `config.env` 中 `enable=true` 的那一条配置，删除前整份备份为 `~/.xbbcli/config.env.bak`；不自动把其他公司提升为启用；默认同时清除 `XBB_*` 环境变量（`--env 0` 跳过，返回 `envStored` / `envFile`）；既无启用公司又无环境变量时返回 `NO_ACTIVE_CONFIG` 且不改动文件
+- `auth-refresh-cache`：对当前启用公司重新拉取表单缓存、命令映射与部门/员工缓存，并回填 `corpName` / `userName`；失败时返回 `code=CACHE_REFRESH_FAILED`，`message` 注明中断步骤（`formlist` / `command-map` / `department-user` / `profile`），已完成的部分照常输出；支持 `--userId`、`--debug`
 - `token-set`：保存个人 token、`corpid`、`userId`、`baseurl`，并刷新本地表单缓存、命令映射文件与部门/员工缓存；传入的 token 不以 `user_` 开头时，会先为该 `userId` 刷新并保存个人 token；`--env` 控制存储方式：`0`（默认）仅写入本地文件，`1` 仅写入 `XBB_*` 环境变量（Windows 用 `setx`，其他平台写 `~/.xbbcli/env.sh`）且不写任何本地文件；返回 `envStored` / `envFile` 两列
-- `token-list`：列出本地保存的所有公司配置和唯一启用的公司（含 `corpName` 公司名称与 `userName` 操作人姓名，`source` 列标记来源 `config`/`env`）；`--showToken` 显示完整 token（默认脱敏）；环境变量模式下单行显示
-- `token-use`：切换当前启用的公司（`xbbcli token-use --corpid <CORPID>`），保证仅且只有一个公司被启用
-- `token-del`：删除指定公司的本地配置（`xbbcli token-del --corpid <CORPID>`），并保证剩余配置中仅且只有一个公司被启用
+- `token-list`：同时列出环境变量行（`source=env`，仅 `XBB_CORPID` / `XBB_TOKEN` 有值时出现）与 `config.env` 中保存的全部公司（`source=config`，含 `corpName` 公司名称与 `userName` 操作人姓名），`msg` 列标注各行当前状态（当前生效 / 被环境变量覆盖 / 被 `XBB_ENV_ONLY=1` 忽略）；`--showToken` 显示完整 token（默认脱敏）
+- `token-use`：切换当前启用的公司（`xbbcli token-use --corpid <CORPID>`），保证仅且只有一个公司被启用；若环境变量 `XBB_*` 有值，同时把该公司凭证（`corpid`/`token`/`baseurl`/`userId`/`corpName`/`userName`，缺 `baseurl` 时按 `corpid` 推导）同步写回环境变量——Windows 用 `setx`（需重开终端）、macOS/Linux 写 `~/.xbbcli/env.sh`（需重新 `source`）；同步失败时返回 `status=partial`，目标公司缺 `token` 时返回错误且不改动任何配置
+- `token-del`：删除指定公司的本地配置（`xbbcli token-del --corpid <CORPID>`），并保证剩余配置中仅且只有一个公司被启用；默认同时删除 `XBB_*` 环境变量（`--env 0` 保留，返回 `envStored` / `envFile` 两列）
 - `token-generate`：生成/获取个人 token，`--resetToken 0` 获取（默认）、`1` 刷新；`--checkUserId` 未传则用配置中的 `userId`
 
 ### 组织与人员
@@ -452,10 +471,10 @@ note      以上取值来自环境变量 XBB_*（config.env 中没有启用公
 ## 通用行为
 
 - 先执行一次 `token-set`（或 `auth-login`）保存有效的 `corpid`、`token`、`userId`
-- 用 `xbbcli auth-status` 查看当前生效的配置来自 `config.env` 还是环境变量；`xbbcli auth-logout` 删除激活配置并默认清除 `XBB_*` 环境变量（`--noEnv` 保留）
+- 用 `xbbcli auth-status` 查看当前生效的配置来自 `config.env` 还是环境变量；`xbbcli auth-logout` 删除激活配置并默认清除 `XBB_*` 环境变量（`--env 0` 保留）
 - 除 `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` 可强制只用环境变量
+- 环境变量 `XBB_*` 的优先级高于 `config.env`：`XBB_CORPID` / `XBB_TOKEN` 有值时，所有命令都以环境变量为准（`config.env` 中的启用公司被覆盖）；两者都不存在时才没有任何生效配置。`XBB_ENV_ONLY=1` 可强制只用环境变量
 - 所有命令会从配置中读取 `userId` 并附加到请求 header 中
 - 大部分命令需要 formId 参数，可以根据业务名称或 businessType 从 `~/.xbbcli/<corpid>.formlist.json` 中获取 formId
 - 需要查询部门 id/名称，或员工 userId/所属部门时，可以先查 `~/.xbbcli/<corpid>.department-user.json`（由 `token-set` 分页抓取并缓存全部部门与员工）

package/auth-login.js

@@ -287,7 +287,7 @@ async function authLogin(kwargs) {
 cli({
   site: 'xbb',
   name: 'auth-login',
-  description: '打开浏览器完成销帮帮登录授权（等价于token-set）',
+  description: '打开浏览器完成销帮帮登录授权',
   strategy: Strategy.PUBLIC,
   access: 'write',
   browser: false,

package/auth-logout.js

@@ -61,7 +61,7 @@ function previewCorpids(companies) {
 }
 
 async function authLogout(kwargs) {
-  const alsoEnv = !kwargs.noEnv && kwargs.env !== false;
+  const alsoEnv = String(kwargs.env ?? '1').trim() !== '0';
   const companies = readCompanies();
   const index = companies.findIndex((item) => item && item.enable === true);
   const envPresent = hasEnvConfig();
@@ -76,7 +76,7 @@ async function authLogout(kwargs) {
       ? `本地共 ${companies.length} 家公司（${previewCorpids(companies)}）且均未启用；要登出某家请先用 xbbcli token-use --corpid <CORPID> 启用，或改用 xbbcli token-del --corpid <CORPID> 直接删除`
       : '本地没有任何公司配置';
     const envNote = envPresent
-      ? '环境变量 XBB_* 仍存在，本次未清除（去掉 --noEnv / --env=false 即可一并清除）'
+      ? '环境变量 XBB_* 仍存在，本次未清除（用 --env 1 或不指定该参数即可一并清除）'
       : '环境变量 XBB_* 也不存在，本次无可清除内容';
     const hint = `${scope}；${envNote}`;
     return createRow({
@@ -138,8 +138,8 @@ async function authLogout(kwargs) {
       parts.push(`清除环境变量失败：${envFile}`);
     }
   } else if (envBefore) {
-    const forced = isEnvOnly() ? '且 XBB_ENV_ONLY=1 已强制只用环境变量' : '业务命令会回落到它';
-    parts.push(`注意：环境变量 XBB_*（corpid=${envBefore}）仍然有效，${forced}，本次不算彻底登出；如需一并清除请去掉 --noEnv（auth-logout 默认会清除环境变量）`);
+    const forced = isEnvOnly() ? '且 XBB_ENV_ONLY=1 已强制只用环境变量' : '且其优先级高于 config.env，业务命令仍会使用它';
+    parts.push(`注意：环境变量 XBB_*（corpid=${envBefore}）仍然有效，${forced}，本次不算彻底登出；如需一并清除请改用 --env 1（或不指定该参数，auth-logout 默认会清除环境变量）`);
   }
 
   const remainingCompanies = target ? remaining : readCompanies();
@@ -166,8 +166,7 @@ cli({
   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 中的激活配置（等价于 --env=false）' },
+    { name: 'env', type: 'str', default: '1', help: '是否同时清除 XBB_* 环境变量：1 清除（默认），0 仅删除 config.env 保留环境变量。Windows 删除用户级变量，其他平台清理 ~/.xbbcli/env.sh' },
     { name: 'debug', type: 'bool', default: false, help: '输出配置文件、备份路径与生效的环境变量名（不打印 token）' },
   ],
   columns: ['status', 'message', 'configFile', 'backupFile', 'corpid', 'corpName', 'userId', 'companyCount', 'hasActive', 'envStored', 'envFile', 'code', 'msg'],

package/auth-refresh-cache.js

@@ -0,0 +1,117 @@
+import { cli, Strategy } from './xbb-registry.js';
+import { readActiveConfig, isEnvActive } from './xbb-config.js';
+import {
+  refreshLocalCaches,
+  getFormlistFile,
+  getCommandMapFile,
+  getDepartmentUserFile,
+} from './xbb-token-store.js';
+
+function trim(value) {
+  return String(value ?? '').trim();
+}
+
+// 统一输出：成功时给出三份缓存与回填结果，失败时回落到合成错误行（不抛异常）
+function makeRow(fields) {
+  return [{
+    status: '',
+    message: '',
+    corpid: '',
+    userId: '',
+    corpName: '',
+    userName: '',
+    formlistFile: '',
+    formlistCount: '',
+    commandMapFile: '',
+    departmentUserFile: '',
+    departmentCount: '',
+    userCount: '',
+    profileUpdated: '',
+    code: '',
+    msg: '',
+    ...fields,
+  }];
+}
+
+function makeErrorRow(code, msg, extra = {}) {
+  return makeRow({ status: 'error', code, msg, message: msg, ...extra });
+}
+
+async function authRefreshCache(kwargs) {
+  const active = readActiveConfig();
+  const corpid = trim(active.corpid);
+  const userId = trim(kwargs.userId) || trim(active.userId);
+
+  if (kwargs.debug) {
+    const source = isEnvActive() ? 'env' : 'config';
+    process.stderr.write(`[debug] ConfigSource: ${source}\n[debug] Corpid: ${corpid || '(none)'}\n[debug] UserId: ${userId || '(none)'}\n[debug] FormlistFile: ${corpid ? getFormlistFile(corpid) : ''}\n[debug] CommandMapFile: ${corpid ? getCommandMapFile(corpid) : ''}\n[debug] DepartmentUserFile: ${corpid ? getDepartmentUserFile(corpid) : ''}\n`);
+  }
+
+  if (!corpid) {
+    return makeErrorRow('NO_ACTIVE_CONFIG', '没有生效的配置：config.env 中不存在 enable=true 的公司，环境变量 XBB_* 也为空；请先执行 xbbcli auth-login 或 xbbcli token-set');
+  }
+
+  let cache;
+  try {
+    cache = await refreshLocalCaches(corpid, userId);
+  } catch (error) {
+    const partial = error.cache || {};
+    const step = trim(error.step) || 'unknown';
+    const message = `刷新本地缓存失败（步骤 ${step}）：${error.message || error}`;
+    return makeRow({
+      status: 'error',
+      code: 'CACHE_REFRESH_FAILED',
+      msg: message,
+      message,
+      corpid,
+      userId,
+      corpName: partial.corpName ?? '',
+      userName: partial.userName ?? '',
+      formlistFile: partial.formlistFile ?? '',
+      formlistCount: partial.formlistCount ?? '',
+      commandMapFile: partial.commandMapFile ?? '',
+      departmentUserFile: partial.departmentUserFile ?? '',
+      departmentCount: partial.departmentCount ?? '',
+      userCount: partial.userCount ?? '',
+      profileUpdated: partial.profileUpdated ?? '',
+    });
+  }
+
+  const message = cache.profileUpdated
+    ? '已刷新表单清单缓存、命令映射与部门/员工缓存，并回填 corpName/userName 到 config.env'
+    : isEnvActive()
+      ? '已刷新表单清单缓存、命令映射与部门/员工缓存；当前为环境变量模式，corpName/userName 未回填 config.env'
+      : '已刷新表单清单缓存、命令映射与部门/员工缓存；该公司不在 config.env 中，corpName/userName 未回填';
+
+  return makeRow({
+    status: 'ok',
+    message,
+    corpid,
+    userId,
+    corpName: cache.corpName,
+    userName: cache.userName,
+    formlistFile: cache.formlistFile,
+    formlistCount: cache.formlistCount,
+    commandMapFile: cache.commandMapFile,
+    departmentUserFile: cache.departmentUserFile,
+    departmentCount: cache.departmentCount,
+    userCount: cache.userCount,
+    profileUpdated: cache.profileUpdated,
+  });
+}
+
+cli({
+  site: 'xbb',
+  name: 'auth-refresh-cache',
+  description: '刷新当前启用公司的本地缓存（表单清单、命令映射等）',
+  strategy: Strategy.PUBLIC,
+  access: 'write',
+  browser: false,
+  domain: 'proapi.xbongbong.com',
+  args: [
+    { name: 'userId', type: 'str', default: '', help: '操作人 id，用于从员工清单匹配 userName；默认取当前启用配置的 userId' },
+    { name: 'debug', type: 'bool', default: false, help: '在 stderr 输出配置来源、corpid 与三份缓存文件路径' },
+  ],
+  columns: ['status', 'message', 'corpid', 'userId', 'corpName', 'userName', 'formlistFile', 'formlistCount', 'commandMapFile', 'departmentUserFile', 'departmentCount', 'userCount', 'profileUpdated', 'code', 'msg'],
+  func: authRefreshCache,
+});

package/auth-status.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { cli, Strategy } from './xbb-registry.js';
-import { readActiveConfig, hasEnvConfig, isEnvActive, isEnvOnly, getEnvVarNames } from './xbb-config.js';
+import { cli, Strategy, getRegistry } from './xbb-registry.js';
+import { readActiveConfig, isEnvActive, isEnvOnly, getEnvVarNames } from './xbb-config.js';
 
 const CONFIG_DIR = path.join(os.homedir(), '.xbbcli');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.env');
@@ -50,9 +50,35 @@ function withNotes(rows, notes) {
   return [...rows, ...notes.map((value) => ({ key: 'note', value }))];
 }
 
+const VERIFY_VALID = '有效';
+const VERIFY_INVALID = '无效-请重新配置token';
+
+// 用一次轻量调用（等价于 user-list --pageSize 1）验证当前 token 是否有效
+// 判定：业务错误码（code 非空且非 NO_DATA）或请求异常 → 无效；成功（含 NO_DATA 空清单）→ 有效
+async function verifyToken() {
+  const command = getRegistry().get('xbb/user-list');
+  if (!command || typeof command.func !== 'function') {
+    return { valid: false, detail: '找不到 user-list 命令，无法验证' };
+  }
+  try {
+    const rows = await command.func({ page: '1', pageSize: '1' });
+    const list = Array.isArray(rows) ? rows : [];
+    const errorRow = list.find((item) => item && String(item.code ?? '') !== '');
+    if (!errorRow) return { valid: true, detail: 'user-list 调用成功' };
+    // NO_DATA 表示接口成功但清单为空，token 仍然有效
+    if (String(errorRow.code) === 'NO_DATA') return { valid: true, detail: 'user-list 调用成功（无数据）' };
+    return { valid: false, detail: `user-list 返回 ${errorRow.code} ${errorRow.msg || ''}`.trim() };
+  } catch (error) {
+    return { valid: false, detail: `user-list 调用异常：${String(error.message || error)}` };
+  }
+}
+
+function withVerify(rows, verify) {
+  return [...rows, { key: 'token验证', value: verify.valid ? VERIFY_VALID : VERIFY_INVALID }];
+}
+
 async function authStatus(kwargs) {
   const showToken = Boolean(kwargs.showToken);
-  const envActive = hasEnvConfig();
   const envUsed = isEnvActive();
   const active = readActiveConfig();
   const companies = readCompanies();
@@ -67,31 +93,49 @@ async function authStatus(kwargs) {
   const token = trim(active.token);
   const rows = toRows({ ...active, token: showToken ? token : maskToken(token) });
 
+  // 没有生效配置或缺少 token 时无需发起调用，直接判定为无效
+  let verify;
+  if (source === 'none' || !token) {
+    verify = { valid: false, detail: source === 'none' ? '没有生效配置，无法验证' : '生效配置缺少 token，无法验证' };
+  } else {
+    verify = await verifyToken();
+  }
+  if (kwargs.debug) {
+    process.stderr.write(`[debug] Verify: ${verify.valid ? 'valid' : 'invalid'}（${verify.detail}）\n`);
+  }
+  const verifiedRows = withVerify(rows, verify);
+
   if (source === 'none') {
     // 没有生效配置时不把残留的环境变量值当真值回显（XBB_BASEURL 等可能单独存在）
-    return withNotes(toRows({}), [
+    return withNotes(verifiedRows, [
       '没有处于激活状态的配置：config.env 中不存在 enable=true 的公司，环境变量 XBB_* 也为空；请先执行 xbbcli auth-login 或 xbbcli token-set',
     ]);
   }
 
   if (source === 'env') {
-    const reason = isEnvOnly() ? 'XBB_ENV_ONLY=1 已强制使用环境变量' : 'config.env 中没有启用公司，回落到环境变量';
-    return withNotes(rows, [
-      `以上取值来自环境变量 XBB_*（${reason}）；环境变量模式不支持多公司切换，配置文件路径与公司数量见 --debug`,
-    ]);
+    const enabledCount = companies.filter((item) => item.enable === true).length;
+    const reason = isEnvOnly()
+      ? 'XBB_ENV_ONLY=1 已强制使用环境变量'
+      : enabledCount > 0
+        ? '环境变量优先于 config.env，其中 enable=true 的公司被覆盖'
+        : 'config.env 中没有启用公司，回落到环境变量';
+    const notes = [`以上取值来自环境变量 XBB_*（${reason}）；环境变量模式不支持多公司切换，配置文件路径与公司数量见 --debug`];
+    if (!isEnvOnly() && enabledCount > 0) {
+      notes.push('如需改用 config.env 中的启用公司，请先清除 XBB_* 环境变量（或执行 xbbcli auth-logout）');
+    }
+    return withNotes(verifiedRows, notes);
   }
 
   const notes = [];
-  if (envActive) notes.push('环境变量 XBB_* 同时存在，但 config.env 启用项优先；如需彻底登出请执行 xbbcli auth-logout');
   const enabledCount = companies.filter((item) => item.enable === true).length;
   if (enabledCount > 1) notes.push(`config.env 中存在 ${enabledCount} 个 enable=true，仅第一条生效，请用 xbbcli token-use 修正`);
-  return withNotes(rows, notes);
+  return withNotes(verifiedRows, notes);
 }
 
 cli({
   site: 'xbb',
   name: 'auth-status',
-  description: '回显当前激活的配置',
+  description: '回显当前激活的配置，并验证 token 是否有效',
   strategy: Strategy.PUBLIC,
   access: 'read',
   browser: false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xbongbong/xbbcli",
-  "version": "2.4.1",
+  "version": "2.4.3",
   "description": "销帮帮 CRM 的独立命令行工具",
   "type": "module",
   "bin": {

package/token-del.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { cli, Strategy } from './xbb-registry.js';
-import { isEnvActive, isEnvOnly, getEnvVarNames } from './xbb-config.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');
@@ -50,7 +50,7 @@ function maskToken(token) {
   if (value.length <= 12) return `${value.slice(0, 4)}****`;
   return `${value.slice(0, 8)}****${value.slice(-4)}`;
 }
-function createResult(status, message, corpid, enable, companyCount) {
+function createResult(status, message, corpid, enable, companyCount, envStored = 'skipped', envFile = '') {
   return [{
     status,
     message,
@@ -58,6 +58,8 @@ function createResult(status, message, corpid, enable, companyCount) {
     corpid,
     enable,
     companyCount,
+    envStored,
+    envFile,
   }];
 }
 
@@ -67,9 +69,9 @@ async function delCompany(kwargs) {
     return createResult('error', '缺少 --corpid', '', '', '');
   }
 
-  if (isEnvOnly() || isEnvActive()) {
-    return createResult('error', `当前为环境变量模式（${getEnvVarNames().join(', ')}），不支持删除公司配置；如需多公司请改用 config.env`, corpid, '', '');
-  }
+  const alsoEnv = String(kwargs.env ?? '1').trim() !== '0';
+  const envPresent = hasEnvConfig();
+  const envBefore = envPresent ? String(readEnvConfig().corpid || '').trim() : '';
 
   const companies = readCompanies();
   if (!companies.length) {
@@ -84,23 +86,61 @@ async function delCompany(kwargs) {
   const next = remaining.length ? enableSingle(remaining) : [];
   writeCompanies(next);
   const enabledCorpid = next.find((item) => item.enable === true)?.corpid || '';
-  const message = next.length
+  const parts = [next.length
     ? `已删除 corpid=${corpid}，剩余 ${next.length} 家公司，当前启用 corpid=${enabledCorpid}`
-    : `已删除 corpid=${corpid}，本地已无公司配置`;
-  return createResult('ok', message, corpid, next.length ? 'true' : '', next.length);
+    : `已删除 corpid=${corpid}，本地已无公司配置`];
+
+  let envStored = 'skipped';
+  let envFile = '';
+
+  if (alsoEnv) {
+    try {
+      const result = clearEnvVars();
+      envStored = result.stored;
+      envFile = result.file;
+      if (envStored === 'none') {
+        parts.push('未检测到 XBB_* 环境变量，无需删除');
+      } else {
+        const suffix = process.platform === 'win32' ? '（已打开的终端需重开才会消失）' : '';
+        parts.push(`环境变量 ${getEnvVarNames().join('、')} 已删除${suffix}`);
+      }
+      // 环境变量已清空，说明删除后的实际生效来源
+      if (envStored !== 'none' || envBefore) {
+        if (isEnvOnly()) {
+          parts.push('注意：XBB_ENV_ONLY=1 仍然开启，环境变量已清空，业务命令将报 NO_ACTIVE_CONFIG；如需恢复请先写入凭证或去掉该变量');
+        } else if (next.length) {
+          parts.push(`此后业务命令使用 config.env 中启用的 corpid=${enabledCorpid}`);
+        } else {
+          parts.push('此后没有可用凭证，请重新执行 xbbcli token-set 或 xbbcli auth-login');
+        }
+      }
+    } catch (error) {
+      envStored = 'failed';
+      envFile = String(error.message || error);
+      return createResult('partial', `${parts.join('；')}；删除环境变量失败：${envFile}`, corpid, next.length ? 'true' : '', next.length, envStored, envFile);
+    }
+  } else if (envPresent) {
+    const forced = isEnvOnly()
+      ? '且 XBB_ENV_ONLY=1 已强制只用环境变量（config.env 被忽略）'
+      : '且其优先级高于 config.env';
+    parts.push(`注意：环境变量 XBB_*（corpid=${envBefore || '未知'}）仍然有效，${forced}，业务命令仍会使用它；如需一并删除请改用 --env 1（或不指定该参数）`);
+  }
+
+  return createResult('ok', parts.join('；'), corpid, next.length ? 'true' : '', next.length, envStored, envFile);
 }
 
 cli({
   site: 'xbb',
   name: 'token-del',
-  description: '删除指定的已保存公司配置，并保证剩余配置中仅且只有一个被启用',
+  description: '删除指定的已保存公司配置，并保证剩余配置中仅且只有一个被启用；默认同时删除 XBB_* 环境变量',
   strategy: Strategy.PUBLIC,
   access: 'write',
   browser: false,
   domain: 'proapi.xbongbong.com',
   args: [
     { name: 'corpid', type: 'str', help: '要删除的公司 id，必须是已保存的 corpid（必填）' },
+    { name: 'env', type: 'str', default: '1', help: '是否同时删除 XBB_* 环境变量：1 删除（默认），0 仅删除 config.env 保留环境变量。Windows 删除用户级变量，其他平台清理 ~/.xbbcli/env.sh' },
   ],
-  columns: ['status', 'message', 'configFile', 'corpid', 'enable', 'companyCount'],
+  columns: ['status', 'message', 'configFile', 'corpid', 'enable', 'companyCount', 'envStored', 'envFile'],
   func: delCompany,
 });

package/token-list.js

@@ -67,40 +67,59 @@ cli({
   ],
   columns: ['enable', 'corpid', 'userId', 'baseurl', 'token', 'corpName', 'userName', 'code', 'msg', 'source'],
   func: async (kwargs) => {
+    const showToken = Boolean(kwargs.showToken);
     const companies = readCompanies();
     const envConfig = readEnvConfig();
-    if (isEnvOnly() || (!companies.some((item) => item && item.enable === true) && hasEnvConfig(envConfig))) {
-      return [{
+    const envPresent = hasEnvConfig(envConfig);
+    const envOnly = isEnvOnly();
+    const rows = [];
+
+    // 环境变量行：XBB_CORPID / XBB_TOKEN 有值就回显，source=env（优先级高于 config.env）
+    if (envPresent) {
+      rows.push({
         enable: 'true',
         corpid: String(envConfig.corpid || ''),
         userId: String(envConfig.userId || ''),
         baseurl: String(envConfig.baseurl || ''),
-        token: Boolean(kwargs.showToken) ? String(envConfig.token || '') : maskToken(envConfig.token),
+        token: showToken ? String(envConfig.token || '') : maskToken(envConfig.token),
         corpName: String(envConfig.corpName || ''),
         userName: String(envConfig.userName || ''),
         code: '',
-        msg: '来源为环境变量 XBB_*（环境变量模式不支持多公司切换）',
+        msg: envOnly
+          ? '来源为环境变量 XBB_*（XBB_ENV_ONLY=1 已强制只用环境变量，config.env 被忽略）'
+          : '来源为环境变量 XBB_*（优先级高于 config.env，当前生效）',
         source: 'env',
-      }];
+      });
     }
-    if (!companies.length) {
+
+    const enabledCount = companies.filter((item) => item.enable === true).length;
+    for (const item of companies) {
+      const isEnabled = item.enable === true;
+      rows.push({
+        enable: isEnabled ? 'true' : 'false',
+        corpid: String(item.corpid || ''),
+        userId: String(item.userId || ''),
+        baseurl: String(item.baseurl || ''),
+        token: showToken ? String(item.token || '') : maskToken(item.token),
+        corpName: String(item.corpName || ''),
+        userName: String(item.userName || ''),
+        code: '',
+        msg: isEnabled
+          ? envOnly
+            ? '来源为 config.env，但 XBB_ENV_ONLY=1 已将其忽略，当前不生效'
+            : envPresent
+              ? '来源为 config.env，但已被环境变量 XBB_* 覆盖，当前不生效'
+              : '来源为 config.env，当前生效'
+          : '',
+        source: 'config',
+      });
+    }
+
+    if (!rows.length) {
       return makeErrorRow('NO_CONFIG', '缺少本地配置；请先执行 xbbcli token-set --corpid <CORPID> --token <TOKEN> --userId <USERID>');
     }
-    const showToken = Boolean(kwargs.showToken);
-    const enabledCount = companies.filter((item) => item.enable === true).length;
-    const rows = companies.map((item) => ({
-      enable: item.enable === true ? 'true' : 'false',
-      corpid: String(item.corpid || ''),
-      userId: String(item.userId || ''),
-      baseurl: String(item.baseurl || ''),
-      token: showToken ? String(item.token || '') : maskToken(item.token),
-      corpName: String(item.corpName || ''),
-      userName: String(item.userName || ''),
-      code: '',
-      msg: '',
-      source: 'config',
-    }));
-    if (enabledCount !== 1) {
+
+    if (companies.length && enabledCount !== 1) {
       rows.push({
         enable: '',
         corpid: '',

package/token-use.js

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { cli, Strategy } from './xbb-registry.js';
-import { isEnvActive, isEnvOnly, getEnvVarNames } from './xbb-config.js';
+import { hasEnvConfig, isEnvOnly, getEnvVarNames, persistEnvVars } from './xbb-config.js';
+import { resolveBaseUrl } from './xbb-token-store.js';
 
 const CONFIG_DIR = path.join(os.homedir(), '.xbbcli');
 const CONFIG_FILE = path.join(CONFIG_DIR, 'config.env');
@@ -67,8 +68,10 @@ async function useCompany(kwargs) {
     return createResult('error', '缺少 --corpid', '', '', '');
   }
 
-  if (isEnvOnly() || isEnvActive()) {
-    return createResult('error', `当前为环境变量模式（${getEnvVarNames().join(', ')}），不支持切换公司；如需多公司请改用 config.env`, corpid, '', '');
+  const envPresent = hasEnvConfig();
+  // XBB_ENV_ONLY=1 且 XBB_* 全空：config.env 被强制忽略，写入也无法生效
+  if (isEnvOnly() && !envPresent) {
+    return createResult('error', `当前 XBB_ENV_ONLY=1 已强制只用环境变量，但 ${getEnvVarNames().join(', ')} 均为空；请先执行 xbbcli token-set --env 1 写入环境变量`, corpid, '', '');
   }
 
   const companies = readCompanies();
@@ -81,15 +84,45 @@ async function useCompany(kwargs) {
     return createResult('error', `未找到 corpid=${corpid} 的本地配置`, corpid, '', companies.length);
   }
 
+  const target = companies[index];
+  // 同步 XBB_* 需要完整凭证：缺 token 时直接拒绝，避免残留上一家公司的 XBB_TOKEN 被继续使用
+  if (envPresent && !String(target.token || '').trim()) {
+    return createResult('error', `corpid=${corpid} 的本地配置缺少 token，无法同步到 XBB_* 环境变量；请先执行 xbbcli token-set --corpid ${corpid} --token <TOKEN> --userId <USERID>`, corpid, '', companies.length);
+  }
+
   const next = enableOnly(companies, index);
   writeCompanies(next);
-  return createResult('ok', `已启用 corpid=${corpid}，其余公司已标记为 enable=false`, corpid, 'true', next.length);
+
+  const parts = [`已启用 corpid=${corpid}，其余公司已标记为 enable=false`];
+
+  // 环境变量中有值时把生效公司同步写回 XBB_*，否则切换会被优先级更高的环境变量覆盖
+  if (envPresent) {
+    try {
+      persistEnvVars({
+        corpid: target.corpid,
+        token: target.token,
+        // 条目缺少 baseurl 时按 corpid 规则推导，避免残留上一家公司的 XBB_BASEURL
+        baseurl: target.baseurl || resolveBaseUrl(target.corpid),
+        userId: target.userId,
+        corpName: target.corpName,
+        userName: target.userName,
+      });
+      const suffix = process.platform === 'win32'
+        ? '（Windows 需重开终端后才生效）'
+        : '（重新 source ~/.xbbcli/env.sh 后才生效）';
+      parts.push(`检测到环境变量 XBB_* 有值，已同步更新为该公司凭证${suffix}`);
+    } catch (error) {
+      return createResult('partial', `已启用 corpid=${corpid}，但同步更新环境变量失败：${String(error.message || error)}`, corpid, 'true', next.length);
+    }
+  }
+
+  return createResult('ok', parts.join('；'), corpid, 'true', next.length);
 }
 
 cli({
   site: 'xbb',
   name: 'token-use',
-  description: '切换当前启用的公司（enable），保证仅且只有一个公司被启用',
+  description: '切换当前启用的公司（enable），保证仅且只有一个公司被启用；XBB_* 环境变量有值时同步更新为该公司凭证',
   strategy: Strategy.PUBLIC,
   access: 'write',
   browser: false,

package/xbb-config.js

@@ -62,25 +62,21 @@ function readFileConfig() {
   }
 }
 
-// 配置文件优先：有启用公司就用配置，否则回落到环境变量
+// 环境变量优先：XBB_* 中 corpid/token 非空时只用环境变量，否则用 config.env 里 enable=true 的公司
 export function readActiveConfig() {
   const envConfig = readEnvConfig();
   if (isEnvOnly()) {
     return envConfig;
   }
-  const fileConfig = readFileConfig();
-  if (Object.keys(fileConfig).length > 0) {
-    return fileConfig;
+  if (hasEnvConfig(envConfig)) {
+    return envConfig;
   }
-  return envConfig;
+  return readFileConfig();
 }
 
 // 当前生效来源是否为环境变量
 export function isEnvActive() {
-  if (isEnvOnly()) {
-    return hasEnvConfig();
-  }
-  return Object.keys(readFileConfig()).length === 0 && hasEnvConfig();
+  return hasEnvConfig();
 }
 
 export function getEnvVarNames() {

package/xbb-token-store.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { getRegistry } from './xbb-registry.js';
-import { persistEnvVars } from './xbb-config.js';
+import { persistEnvVars, hasEnvConfig } from './xbb-config.js';
 
 // token-set 与 auth-login 共用的凭证落盘逻辑：写 config.env、表单缓存、命令映射、部门/员工缓存、环境变量
 export const CONFIG_DIR = path.join(os.homedir(), '.xbbcli');
@@ -109,7 +109,7 @@ async function writeFormlistFile(corpid) {
   const mergedRows = [...customForms, ...systemForms];
 
   fs.writeFileSync(formlistFile, JSON.stringify(mergedRows, null, 2) + '\n', 'utf8');
-  return formlistFile;
+  return { file: formlistFile, count: mergedRows.length };
 }
 
 async function fetchAllRows(name, pageSize) {
@@ -178,7 +178,7 @@ async function writeDepartmentUserFile(corpid, userId) {
   const file = getDepartmentUserFile(corpid);
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
   fs.writeFileSync(file, JSON.stringify(payload, null, 2) + '\n', 'utf8');
-  return { file, corpName: getCorpName(departmentRows), userName: getUserName(userRows, userId) };
+  return { file, corpName: getCorpName(departmentRows), userName: getUserName(userRows, userId), departmentCount: departmentRows.length, userCount: userRows.length };
 }
 
 function getCorpName(departmentRows) {
@@ -196,16 +196,89 @@ function getUserName(userRows, userId) {
   return matched ? String(matched.name || '').trim() : '';
 }
 
+// 把 corpName / userName 合并进 config.env 对应公司，返回是否真的写过文件
+// config.env 里没有这家公司的条目时（纯环境变量模式）直接跳过，避免凭空生成一份只有 corpName 的 config.env
 export function writeCompanyProfile(corpid, profile) {
+  const target = String(corpid || '').trim();
   const fields = Object.entries(profile).filter(([, value]) => String(value || '').trim() !== '');
-  if (!fields.length) {
-    return;
+  if (!target || !fields.length) {
+    return false;
+  }
+  const companies = readCompanies();
+  const index = companies.findIndex((item) => String(item.corpid || '').trim() === target);
+  if (index === -1) {
+    return false;
   }
   const patch = Object.fromEntries(fields);
-  const companies = readCompanies().map((item) => (
-    String(item.corpid || '').trim() === corpid ? { ...item, ...patch } : item
-  ));
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(companies, null, 2) + '\n', 'utf8');
+  const next = companies.map((item, itemIndex) => (itemIndex === index ? { ...item, ...patch } : item));
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(next, null, 2) + '\n', 'utf8');
+  return true;
+}
+
+// token-set / auth-login / auth-refresh-cache 共用：刷新三份本地缓存并回填 corpName、userName
+// 失败时抛出的 error 上带 step（formlist/command-map/department-user/profile）与已完成部分的 cache，便于命令回显进度
+export async function refreshLocalCaches(corpid, userId) {
+  const target = String(corpid || '').trim();
+  if (!target) {
+    const error = new Error('缺少 corpid，无法确定要刷新哪家公司的缓存');
+    error.step = 'formlist';
+    error.cache = { formlistFile: '', commandMapFile: '', departmentUserFile: '', formlistCount: '', departmentCount: '', userCount: '', corpName: '', userName: '', profileUpdated: false };
+    throw error;
+  }
+  const cache = {
+    formlistFile: getFormlistFile(target),
+    commandMapFile: '',
+    departmentUserFile: '',
+    formlistCount: '',
+    departmentCount: '',
+    userCount: '',
+    corpName: '',
+    userName: '',
+    profileUpdated: false,
+  };
+
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+
+  try {
+    const formlist = await writeFormlistFile(target);
+    cache.formlistFile = formlist.file;
+    cache.formlistCount = formlist.count;
+  } catch (error) {
+    error.step = 'formlist';
+    error.cache = cache;
+    throw error;
+  }
+
+  try {
+    cache.commandMapFile = writeCommandMap(target);
+  } catch (error) {
+    error.step = 'command-map';
+    error.cache = cache;
+    throw error;
+  }
+
+  try {
+    const departmentUser = await writeDepartmentUserFile(target, userId);
+    cache.departmentUserFile = departmentUser.file;
+    cache.corpName = departmentUser.corpName;
+    cache.userName = departmentUser.userName;
+    cache.departmentCount = departmentUser.departmentCount;
+    cache.userCount = departmentUser.userCount;
+  } catch (error) {
+    error.step = 'department-user';
+    error.cache = cache;
+    throw error;
+  }
+
+  try {
+    cache.profileUpdated = writeCompanyProfile(target, { corpName: cache.corpName, userName: cache.userName });
+  } catch (error) {
+    error.step = 'profile';
+    error.cache = cache;
+    throw error;
+  }
+
+  return cache;
 }
 
 function normalizeBusinessType(value) {
@@ -372,16 +445,19 @@ export async function saveCompanyCredentials(kwargs) {
   fs.mkdirSync(CONFIG_DIR, { recursive: true });
   fs.writeFileSync(CONFIG_FILE, JSON.stringify(companies, null, 2) + '\n', 'utf8');
 
+  // 环境变量优先级高于 config.env：此时只写文件不会改变业务命令实际使用的凭证，需在结果里提示
+  const envShadow = hasEnvConfig()
+    ? '；注意：检测到 XBB_* 环境变量，其优先级高于 config.env，业务命令仍会使用环境变量；如需改用本次保存的配置，请清除 XBB_* 环境变量或执行 xbbcli auth-logout'
+    : '';
+
   try {
-    const formlistFile = await writeFormlistFile(corpid);
-    const commandMapFile = writeCommandMap(corpid);
-    const { file: departmentUserFile, corpName, userName } = await writeDepartmentUserFile(corpid, userId);
-    writeCompanyProfile(corpid, { corpName, userName });
-    return createResult('ok', '已保存 corpid、token、baseurl、userId，并同步表单模板缓存、命令映射文件与部门/员工缓存', corpid, baseurl, userId, formlistFile, commandMapFile, true, companies.length, departmentUserFile, corpName, userName, 'skipped', '');
+    const cache = await refreshLocalCaches(corpid, userId);
+    const { formlistFile, commandMapFile, departmentUserFile, corpName, userName } = cache;
+    return createResult('ok', `已保存 corpid、token、baseurl、userId，并同步表单模板缓存、命令映射文件与部门/员工缓存${envShadow}`, corpid, baseurl, userId, formlistFile, commandMapFile, true, companies.length, departmentUserFile, corpName, userName, 'skipped', '');
   } catch (error) {
     return createResult(
       'partial',
-      `已保存 corpid、token、baseurl、userId，但同步缓存失败：${error.message}`,
+      `已保存 corpid、token、baseurl、userId，但同步缓存失败${error.step ? `（步骤 ${error.step}）` : ''}：${error.message}${envShadow}`,
       corpid,
       baseurl,
       userId,