e10-data 0.1.16 → 0.1.17-xiaoe

package/CHANGELOG.md

@@ -0,0 +1,71 @@
+# 变更记录
+
+## 0.1.17（2026-09-20）—— 启动性能改造
+
+本次只做性能与健壮性改造，**不改变任何命令的参数、输出与退出码**（已用 10 条命令做新旧输出逐字节对比，全部一致）。
+
+### 1. 免凭据命令提前返回（不再取凭据）
+
+`--version` / `-v`、`--help` / `-h`、以及**未知命令/未知子命令的用法提示**都不需要登录态。
+过去 `loadAuth()` 写在模块顶层，任何调用（含打印版本）都会先付一整笔取凭据开销；
+现在这三类在取凭据**之前**就返回。
+
+- 实测：`--version`、`--help`、未知命令 从 ~2.4s → **~0.2s**
+- 退出码约定：显式求助（`--help` / `-h`）为 `0`；用错命令（未知命令 / 缺子命令）为 `1`
+- 新增命令白名单 `commandIsKnown()`（与 `main()` 分发表一一对应）；`exp release --version v1.0.0`
+  这类"`--version` 作为版本号参数"的用法不受影响（仅拦截顶层单参数）
+
+### 2. 直连 `e10-login` 入口，去掉 `shell: true`
+
+`spawnSync("e10-login", …, { shell: true })` 在 Windows 上会先起一层 `cmd.exe`；
+实测**该层单独就耗时 ~0.98~1.04s**（杀软对每个新进程的实时扫描所致），
+而 `e10-login` 自身只花 ~0.1s。
+
+- 新增 `resolveLoginEntry()`：① 环境变量 `E10_LOGIN_ENTRY` → ② Node 模块解析
+  → ③ 沿 `PATH` 找 shim 再取 `<shimDir>/node_modules/e10-login` → ④ 常见全局前缀兜底
+- 改为 `spawnSync(process.execPath, [entry, ...args], { shell: false })`
+- 不能直接 spawn `.cmd`：Node ≥18.20/20.12 起禁止在 `shell:false` 下执行 `.cmd`/`.bat`（CVE-2024-27980），
+  因此必须解析到 shim 背后真正的 `.js` 入口
+- 解析失败会打印一行 warn 并**退化回 `shell: true`**（只慢不错）
+- 实测：单次取凭据 **~1.0s → ~0.22s**（每调用省 ~0.78s）
+- 附带收益：`login xiaoe-env` 里写 profile 的那次调用也从「拼 shell 字符串 + `shq` 转义」改为
+  **数组直传**，彻底消除 shell 注入面（`ETEAMSID_SAFE_RE` 仍作为二道防线保留）
+
+### 3. 凭据进程间 TTL 缓存（默认 300 秒，**不落明文**）
+
+新增 `bin/e10-cred-helper.mjs`：一个 detached 的「持有者」进程把凭据**只保存在内存**里，
+监听本机命名管道（Windows）/ Unix 域套接字（`0600`），供后续同用户·同 profile 的调用直接取用，
+TTL 到期自动退出。
+
+- **不写任何文件、不经过网络**；凭据经 `stdin` 从父进程传入（不走 `argv`，避免出现在进程列表里）
+- 通道名 = `sha1(用户主目录 + 用户名 + profile)` 前 16 位 → 不同用户 / 不同 profile 互不可见
+- **兜底出口（明文镜像）的凭据不写入缓存**，避免把可能已过期的凭据固化整个 TTL
+- 任何异常（连不上 / 超时 / JSON 损坏 / 已过期 / profile 不符）**静默回落**正常取凭据路径
+- 并发：后启动的持有者遇 `EADDRINUSE` 静默退出（先到先得）
+- 安全边界未扩大：同用户下的其它进程本来就能执行 `e10-login whoami` 拿到同样的凭据
+
+新增环境变量：`E10_DATA_CRED_TTL`（默认 300）、`E10_DATA_NO_CRED_CACHE=1`（关闭缓存）、
+`E10_LOGIN_ENTRY`（指定入口，排障用）。`E10_DATA_AUTH_MODE` / `E10_DATA_AUTH_PROBE` 存在时绕过缓存。
+
+> **一处附带的行为变化**：`syncCacheMd()`（把凭据同步到已废弃的明文镜像
+> `~/.workbuddy/e10-login-cache.md`）只在**缓存未命中**那条路径上执行。
+> 缓存命中的 5 分钟内不再刷新该镜像。因该镜像机制已被判定废弃、且不参与正常取数，
+> 此变化会**减少**明文落盘频率，符合既有的「不落明文」方向。
+
+### 综合效果
+
+| 命令 | 0.1.16 | 0.1.17 | 提升 |
+|---|---|---|---|
+| `--version` | ~2.4s | **~0.2s** | 12× |
+| `conf get CONN_EC_EDCAPP --json` | 2.35s | **0.62s** | 3.8× |
+
+按一次问数会话调用 10 次 `e10-data` 估算，**省约 17 秒**。
+
+### 回归验证
+
+- 9 个命令族 smoke（conf / noun / field / ds / doc / attend / eb / exp / query）全部通过
+- 10 条命令与 0.1.16 输出 + 退出码**逐字节一致**
+- helper 单元测试：TTL 到期自退（`ENOENT` + 进程消失）、`EADDRINUSE` 静默退出（退出码 0）
+- 缓存开关对照：关闭缓存 1.61s / 开启缓存 0.62s，确认提速来自缓存本身
+- 认证未被绕过：把 `USERPROFILE`/`HOME` 指向空目录后，真实命令仍以
+  「未取得登录凭据」退出，而免凭据命令正常工作

package/README.md

@@ -35,6 +35,32 @@ e10-data attend  statis   考勤假期余额统计 getAttendInfoStatis（hr-atte
 - 认证：**加解密由 `e10-login` 负责（本 CLI 不参与）**。凭据出口优先级：`e10-login auth --json` → `e10-login whoami --json` → `e10-login whoami`（文本）→ 明文镜像 `~/.workbuddy/e10-login-cache.md`（兜底，命中时告警）。命中的出口会记入 `~/.e10-cli/.e10-data-auth-mode`（只存模式名、不存凭据），下次优先复用。环境变量：`E10_DATA_AUTH_PROBE=1` 强制重新探测、`E10_DATA_AUTH_MODE=<模式名>` 手动指定、`E10_DATA_QUIET=1` 抑制告警（告警只走 stderr）。**没有任何可用凭据时**用 `e10-data login xiaoe-env` 登录（见下节）。
 - 版本更新：`npm i -g e10-data@latest`；查看源上最新 `npm view e10-data version`。
 
+## 性能：免凭据命令与凭据缓存（v0.1.17 新增）
+
+**① 免凭据命令不再取凭据**：`--version` / `-v`、`--help` / `-h`、以及**未知命令的用法提示**都不需要登录态，现在在取凭据之前直接返回。实测这些路径从 ~2.4s 降到 **~0.2s**。
+
+**② 直连 `e10-login`，去掉 shell 中转**：过去用 `spawnSync(..., { shell: true })` 拉起 `e10-login`，在 Windows 上会先起一层 `cmd.exe`——实测该层**单独就要约 1.0s**（杀软逐进程扫描）。现在改为定位 `e10-login` 的 JS 入口后用 `process.execPath` 直接拉起（`shell: false`）。单次取凭据 **~1.0s → ~0.22s**。
+> 若自动定位失败（会打印一行 warn），可用 `E10_LOGIN_ENTRY=<e10-login/bin/e10-login.js 绝对路径>` 显式指定；仍失败则自动退化为 shell 调用（只慢不错）。
+
+**③ 凭据进程间 TTL 缓存（默认 300 秒）**：一个 detached 的持有者进程把凭据**只保存在内存**里，监听本机命名管道（Windows）/ Unix 域套接字（0600），供后续同用户·同 profile 的调用直接取用，TTL 到期自动退出。**不写任何文件、不经过网络。**
+> - 通道名含「用户主目录 + 用户名 + profile」哈希 → 不同用户 / 不同 profile 互不可见；
+> - 兜底出口（明文镜像）的凭据**不写入缓存**，避免把可能过期的凭据固化；
+> - 任何异常（连不上 / 超时 / JSON 损坏 / 已过期 / profile 不符）**静默回落**到正常取凭据路径。
+
+**三项合计**：`e10-data conf get …` 单次调用实测 **2.35s → 0.62s（约 3.8 倍）**。
+
+相关环境变量：
+
+| 变量 | 作用 |
+|---|---|
+| `E10_DATA_CRED_TTL` | 缓存 TTL 秒数，默认 `300` |
+| `E10_DATA_NO_CRED_CACHE=1` | 整体关闭凭据缓存（每次仍直连 e10-login） |
+| `E10_DATA_AUTH_PROBE=1` / `E10_DATA_AUTH_MODE=…` | 存在时**绕过缓存**，强制重新解析凭据 |
+| `E10_LOGIN_ENTRY` | 显式指定 `e10-login` 的 JS 入口路径（排障用） |
+
+> ⚠️ TTL 采用「先到先得」：若已有一个 TTL=300 的持有者在服务，此时以更短的 `E10_DATA_CRED_TTL` 再调用不会立刻缩短它的寿命（新持有者因通道被占而静默退出）。日常使用无需关注。
+
+
 ## 用法示例
 
 ```bash

package/bin/e10-cred-helper.mjs

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+// -*- coding: utf-8 -*-
+/**
+ * e10-cred-helper —— 凭据进程间 TTL 缓存的「持有者」进程（v0.1.17 新增）
+ *
+ * 为什么存在：e10-data 每次调用都要向 e10-login 取一次凭据，那是一整笔进程开销
+ *   （去 shell 后 ~0.22s）。把凭据在一个**只存在于内存**的短命进程里放 TTL 秒，
+ *   后续同用户、同 profile 的 e10-data 调用直接从这里取，省掉反复拉起 e10-login。
+ *
+ * 安全边界（与既有约定一致，**不落明文**）：
+ *   · 凭据只保存在本进程内存里；**不写任何文件、不打印到 stdout/stderr**；
+ *   · 传输走本机命名管道（Windows）/ Unix 域套接字（0600），不经过网络；
+ *   · 通道名含「用户主目录 + 用户名 + profile」的哈希 → 不同用户/不同 profile 互不可见；
+ *   · TTL 到期自动退出（默认 300s），不长期驻留；
+ *   · 同用户下的其它进程本来就能执行 `e10-login whoami` 拿到同样的凭据，
+ *     因此本缓存**不扩大**攻击面。
+ *
+ * 用法（只应由 e10-data 拉起，不面向用户）：
+ *   node e10-cred-helper.mjs <pipePath> <ttlSeconds>
+ *   凭据 JSON 由父进程经 stdin 传入；父进程随即 unref 退出，本进程独立存活到 TTL。
+ * 生命周期：
+ *   ① 读 stdin 拿到凭据（拿不到 → 立刻退出，不影响任何命令）
+ *   ② 监听 pipePath（EADDRINUSE → 说明已有持有者，静默退出）
+ *   ③ 每个连接回一行 JSON：{"v":1,"exp":<ms>,"profile":"..","auth":{..}} 后关闭
+ *   ④ TTL 到期 / 收到 SIGINT·SIGTERM → 清理并退出
+ */
+import fs from "node:fs";
+import net from "node:net";
+
+const pipePath = process.argv[2];
+const ttlSec = Number(process.argv[3]) || 300;
+
+if (!pipePath) process.exit(0);
+
+let payload = null;
+try {
+  let raw = "";
+  process.stdin.setEncoding("utf-8");
+  for await (const chunk of process.stdin) raw += chunk;
+  payload = JSON.parse(raw);
+} catch { payload = null; }
+
+// 凭据不完整就不起服务（宁可让调用方回落到正常取凭据路径）
+if (!payload || !payload.auth || !payload.auth.baseUrl || !payload.auth.eteamsid || !payload.auth.cookie) {
+  process.exit(0);
+}
+
+const response = JSON.stringify({
+  v: 1,
+  exp: Number(payload.exp) || (Date.now() + ttlSec * 1000),
+  profile: payload.profile || "default",
+  auth: payload.auth,
+}) + "\n";
+
+function cleanupAndExit(code) {
+  try { server.close(); } catch {}
+  // Unix：套接字文件需要自行清理；Windows 命名管道无文件
+  if (process.platform !== "win32") { try { fs.unlinkSync(pipePath); } catch {} }
+  process.exit(code);
+}
+
+const server = net.createServer((sock) => {
+  // 只认 GET：其余一律拒绝，避免被当作通用通道
+  let buf = "";
+  let answered = false;
+  const reply = (text) => { if (answered) return; answered = true; try { sock.end(text); } catch {} };
+  sock.setEncoding("utf-8");
+  sock.setTimeout(3000, () => { try { sock.destroy(); } catch {} });
+  sock.on("data", (d) => {
+    buf += d;
+    if (buf.includes("\n")) reply(/"GET"/.test(buf) || /^GET/.test(buf.trim()) ? response : "MISS\n");
+  });
+  sock.on("error", () => { try { sock.destroy(); } catch {} });
+});
+
+server.on("error", (e) => {
+  // EADDRINUSE：已有持有者在服务 → 本次静默退出，交给它
+  if (e && (e.code === "EADDRINUSE" || e.code === "EACCES")) process.exit(0);
+  process.exit(0);
+});
+
+server.listen(pipePath, () => {
+  if (process.platform !== "win32") { try { fs.chmodSync(pipePath, 0o600); } catch {} }
+  // TTL 到期自退。刻意不 unref：保证 TTL 一定生效，进程不会提前或滞后退出。
+  setTimeout(() => cleanupAndExit(0), ttlSec * 1000);
+});
+
+process.on("SIGINT", () => cleanupAndExit(0));
+process.on("SIGTERM", () => cleanupAndExit(0));
+process.on("uncaughtException", () => cleanupAndExit(0));

package/bin/e10-data.mjs

@@ -38,8 +38,10 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import crypto from "node:crypto";
-import { spawnSync } from "node:child_process";
+import net from "node:net";
+import { spawn, spawnSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 function cliVersion() {
@@ -75,11 +77,108 @@ function authFilePath() {
   return { profile, file: path.join(home, ".e10-cli", "profiles", profile, "auth") };
 }
 
+// ---------------- e10-login 入口解析（v0.1.17：去掉 shell:true，这是最大的性能改动）----------------
+// 背景（2026-09-20 实测）：`spawnSync("e10-login", …, { shell: true })` 在 Windows 上会先起一层
+//   cmd.exe；该层**单独**耗时 ~0.98~1.04s（杀软对每个新进程的实时扫描所致），而 e10-login 自身
+//   的活（读 profile + 解密 auth + 打印）只花 ~0.1s。改为「定位 e10-login 的 JS 入口，用
+//   process.execPath 直接拉起」后，实测 **1.0s → 0.22s**（每调用省 ~0.78s）。
+// ⚠️ 不能直接 spawn `e10-login.cmd`：Node ≥18.20/20.12 起为修 CVE-2024-27980，禁止在 shell:false
+//   下执行 .cmd/.bat（抛 EINVAL）。因此必须解析到 .cmd shim 背后**真正的 .js 入口**。
+// 解析顺序：① 环境变量 E10_LOGIN_ENTRY → ② Node 模块解析（与 e10-data 同 prefix 时命中）
+//   → ③ 沿 PATH 找 shim，再取 <shimDir>/node_modules/e10-login → ④ 常见全局前缀兜底。
+//   全部失败 → 返回 null，调用方退化回 shell:true（保持旧行为可用，只慢不错）。
+let _loginEntry;          // 进程内缓存解析结果；null 表示"已尝试但未找到"
+let _loginEntryDone = false;
+
+function resolveLoginEntry() {
+  if (_loginEntryDone) return _loginEntry;
+  _loginEntryDone = true;
+  const tried = [];
+  const isFile = (p) => { try { return !!p && fs.statSync(p).isFile(); } catch { return false; } };
+
+  /** 读 <dir>/package.json 的 bin 字段定位入口文件；非 e10-login 包返回 null */
+  const entryFromPkgDir = (dir) => {
+    try {
+      const pj = path.join(dir, "package.json");
+      if (!isFile(pj)) return null;
+      const j = JSON.parse(fs.readFileSync(pj, "utf-8"));
+      if (j.name !== "e10-login") return null;
+      let b = j.bin;
+      if (typeof b === "string") b = { "e10-login": b };
+      const rel = b && b["e10-login"];
+      if (!rel) return null;
+      const entry = path.resolve(dir, rel);
+      return isFile(entry) ? entry : null;
+    } catch { return null; }
+  };
+
+  // ① 环境变量显式指定（排障与特殊安装方式用）
+  const envEntry = (process.env.E10_LOGIN_ENTRY || "").trim();
+  if (envEntry) {
+    if (isFile(envEntry)) { _loginEntry = envEntry; return _loginEntry; }
+    tried.push("E10_LOGIN_ENTRY 指向的文件不存在: " + envEntry);
+  }
+
+  // ② Node 模块解析（e10-data 与 e10-login 装在同一个 prefix 时命中）
+  try {
+    const pj = createRequire(import.meta.url).resolve("e10-login/package.json");
+    const e = entryFromPkgDir(path.dirname(pj));
+    if (e) { _loginEntry = e; return _loginEntry; }
+    tried.push("模块解析命中 " + pj + " 但 bin 入口不可用");
+  } catch (e) { tried.push("模块解析: " + ((e && e.message) || e)); }
+
+  // ③ 沿 PATH 找 shim，再取 shim 同级的 node_modules/e10-login
+  //    （npm 全局安装的常规布局：<prefix>/e10-login.cmd + <prefix>/node_modules/e10-login）
+  const pathDirs = String(process.env.PATH || "").split(path.delimiter).filter(Boolean);
+  const shimNames = process.platform === "win32"
+    ? ["e10-login.cmd", "e10-login.exe", "e10-login"]
+    : ["e10-login"];
+  for (const d of pathDirs) {
+    for (const n of shimNames) {
+      const shim = path.join(d, n);
+      if (!isFile(shim)) continue;
+      const e = entryFromPkgDir(path.join(d, "node_modules", "e10-login"));
+      if (e) { _loginEntry = e; return _loginEntry; }
+      tried.push("找到 shim " + shim + "，但其同级 node_modules/e10-login 不可用");
+    }
+  }
+
+  // ④ 常见全局前缀兜底
+  const home = os.homedir();
+  const prefixes = [
+    path.join(path.dirname(process.execPath), "node_modules"),
+    path.join(path.dirname(process.execPath), "..", "lib", "node_modules"),
+    path.join(home, ".npm-global", "lib", "node_modules"),
+    process.env.APPDATA ? path.join(process.env.APPDATA, "npm", "node_modules") : null,
+    process.env.ProgramFiles ? path.join(process.env.ProgramFiles, "nodejs", "node_modules") : null,
+  ].filter(Boolean);
+  for (const p of prefixes) {
+    const e = entryFromPkgDir(path.join(p, "e10-login"));
+    if (e) { _loginEntry = e; return _loginEntry; }
+  }
+  tried.push("常见全局前缀均未命中: " + prefixes.join(" | "));
+
+  if (!process.env.E10_DATA_QUIET) {
+    console.error("[e10-data][warn] 未定位到 e10-login 的 JS 入口，本次退化为 shell 调用（较慢，且 Windows 上多花约 1 秒）。"
+      + "可用 E10_LOGIN_ENTRY=<e10-login/bin/e10-login.js 绝对路径> 显式指定。诊断：" + tried.join(" ｜ "));
+  }
+  _loginEntry = null;
+  return null;
+}
+
 let lastLoginDiag = "";
+/** 底层调用 e10-login，返回 spawnSync 结果（供需要看 stderr/status 的调用方使用）。
+ *  优先 shell:false 直连 JS 入口；解析失败才退化为 shell:true。 */
+function spawnLoginCli(args, timeout = 20000) {
+  const entry = resolveLoginEntry();
+  if (entry) return spawnSync(process.execPath, [entry, ...args], { encoding: "utf-8", timeout, windowsHide: true });
+  return spawnSync("e10-login", args, { shell: true, encoding: "utf-8", timeout, windowsHide: true });
+}
+
 /** 调用 e10-login（凭据的唯一来源）；失败返回 null，并把诊断信息留在 lastLoginDiag */
 function runLoginCli(args) {
   try {
-    const r = spawnSync("e10-login", args, { shell: true, encoding: "utf-8", timeout: 20000, windowsHide: true });
+    const r = spawnLoginCli(args);
     const out = (r.stdout || "").trim();
     if (r.error || r.status !== 0) {
       lastLoginDiag = ((r.stderr || "") + out).trim().split(/\r?\n/).slice(0, 2).join(" / ") || (r.error ? String(r.error.message) : "exit=" + r.status);
@@ -247,6 +346,93 @@ function loadAuth() {
     (diag.length ? "  探测诊断：" + diag.join(" ｜ ") + "\n" : "")
   );
 }
+
+// ---------------- 凭据进程间 TTL 缓存（v0.1.17 新增，不落明文）----------------
+// 目的：避免每次调用都重新拉起 e10-login 取凭据（去掉 shell 后仍约 0.22s/次）。
+// 形态：一个 detached 的「持有者」进程把凭据**只保存在内存**里，监听本机命名管道
+//   （Windows）/ Unix 域套接字（0600），供后续同用户·同 profile 的 e10-data 调用取用，
+//   TTL（默认 300s）到期自动退出。**不写任何文件、不涉及网络。**
+// 边界：
+//   · 任何异常（连不上/超时/JSON 坏/过期/profile 不符）一律静默回落正常取凭据路径；
+//   · 兜底出口（明文镜像）的凭据不会写入缓存，避免把过期凭据固化；
+//   · E10_DATA_NO_CRED_CACHE=1 整体关闭；E10_DATA_AUTH_MODE / E10_DATA_AUTH_PROBE 存在时绕过缓存；
+//   · 缓存通道名含「主目录+用户名+profile」哈希 → 不同用户/不同 profile 互不可见。
+const CRED_CACHE_TTL = (() => {
+  const n = Number(process.env.E10_DATA_CRED_TTL);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 300;
+})();
+
+/** 缓存通道地址（只有 e10-data 与 e10-cred-helper 使用；由父进程算好后以 argv 传给持有者） */
+function credCachePath() {
+  const { profile } = authFilePath();
+  const tag = crypto.createHash("sha1")
+    .update([os.homedir(), process.env.USERNAME || process.env.USER || "", profile].join("|"))
+    .digest("hex").slice(0, 16);
+  if (process.platform === "win32") return "\\\\.\\pipe\\e10-data-cred-" + tag;
+  const uid = typeof process.getuid === "function" ? process.getuid() : "n";
+  const dir = process.env.XDG_RUNTIME_DIR || path.join(os.homedir(), ".e10-cli");
+  return path.join(dir, "e10-data-cred-" + tag + "-" + uid + ".sock");
+}
+
+/** 读缓存：命中返回 auth（结构同 loadAuth 的返回值）；未命中/超时/任何异常 → null */
+function credCacheGet() {
+  const { profile } = authFilePath();
+  return new Promise((resolve) => {
+    let done = false, buf = "", sock;
+    const finish = (v) => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      try { sock.destroy(); } catch {}
+      resolve(v);
+    };
+    const timer = setTimeout(() => finish(null), 1500);   // 取缓存必须快；超时即当未命中
+    try { sock = net.connect(credCachePath()); } catch { return finish(null); }
+    sock.setEncoding("utf-8");
+    sock.on("connect", () => { try { sock.write("GET\n"); } catch { finish(null); } });
+    sock.on("data", (d) => {
+      buf += d;
+      if (!buf.includes("\n")) return;
+      try {
+        const j = JSON.parse(buf.split("\n")[0]);
+        if (!j || j.v !== 1 || Number(j.exp) < Date.now()) return finish(null);
+        if ((j.profile || "default") !== profile) return finish(null);
+        const a = normalizeAuth(Object.assign({}, j.auth, { source: "进程间凭据缓存（e10-data cred-cache）" }));
+        return finish(a || null);
+      } catch { return finish(null); }
+    });
+    sock.on("error", () => finish(null));
+    sock.on("close", () => finish(null));
+  });
+}
+
+/** 写缓存：拉起 detached 持有者，凭据经 stdin 传入（不经 argv，避免出现在进程列表里） */
+function credCachePublish(auth) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      const helper = path.join(__dirname, "e10-cred-helper.mjs");
+      if (!fs.existsSync(helper)) return resolve();
+      child = spawn(process.execPath, [helper, credCachePath(), String(CRED_CACHE_TTL)], {
+        detached: true, stdio: ["pipe", "ignore", "ignore"], windowsHide: true,
+      });
+    } catch { return resolve(); }
+    const payload = JSON.stringify({
+      exp: Date.now() + CRED_CACHE_TTL * 1000,
+      profile: auth.profile || "default",
+      auth: {
+        baseUrl: auth.baseUrl, eteamsid: auth.eteamsid, cookie: auth.cookie,
+        userId: auth.userId, tenantKey: auth.tenantKey, source: auth.source,
+      },
+    });
+    let settled = false;
+    const done = () => { if (settled) return; settled = true; try { child.unref(); } catch {} resolve(); };
+    child.on("error", done);
+    child.stdin.on("error", done);
+    child.stdin.end(payload, done);
+    setTimeout(done, 1000);   // 兜底：不让发布环节拖住主命令
+  });
+}
 // ---------------- login（唯一"不需要已有凭据"的命令族：xiaoe-env，2026-09-17 移植）----------------
 // 来源：e10-login 1.6.4-xiaoe 的 `e10-login xiaoe-env [--domain <url>]`
 //   （lib/xiaoe.js 命令定义 + lib/login-flow.js 收尾 + scripts/xiaoe_env.py 换 token）。
@@ -317,10 +503,9 @@ async function cmdLoginXiaoeEnv(args, json) {
   say("✅ 已取得 ETEAMSID（来源: env，不回显）");
 
   if (!ETEAMSID_SAFE_RE.test(eteamsId)) throw new Error("换回的 ETEAMSID 含异常字符，已拒绝透传 e10-login（安全防护）");
-  const shq = (s) => '"' + String(s).replace(/"/g, "") + '"';
-  const r = spawnSync("e10-login " + ["set", "--eteamsid", shq(eteamsId), "--base-url", shq(baseUrl)].join(" "), {
-    shell: true, encoding: "utf-8", timeout: 60000, windowsHide: true,
-  });
+  // v0.1.17：改为数组直传 + shell:false（不再手工拼 shell 字符串、不再需要 shq 转义），
+  //   既省掉 cmd.exe 那一层开销，也彻底消除 shell 注入面。ETEAMSID_SAFE_RE 仍作为二道防线保留。
+  const r = spawnLoginCli(["set", "--eteamsid", eteamsId, "--base-url", baseUrl], 60000);
   const out = (r.stdout || "").trim(), err = (r.stderr || "").trim();
   if (r.error || r.status !== 0) {
     throw new Error("换 token 成功，但 e10-login 写 profile 失败（auth 文件的加密写入只有 e10-login 能做）："
@@ -376,7 +561,68 @@ async function cmdLoginXiaoeEnv(args, json) {
   }
 }
 
-const auth = loadAuth();
+// ---- 命令白名单（早期校验用；必须与下方 main() 的分发表保持一致）----
+// 返回 true = 该命令存在、可以继续（可能还需要凭据）；false = 未知命令，直接给用法提示。
+// 为什么需要：loadAuth() 写在模块顶层，过去"未知命令"也要先付一整笔取凭据的开销
+// （Windows 上 ~1.0s，去 shell 后 ~0.22s）才打印用法。v0.1.17 起提前判定。
+const CMD_SUBS = {
+  ds: ["tables", "fields", "list", "chart", "stat", "count"],
+  doc: ["count", "list"],
+  noun: ["list"],
+  field: ["id2name", "name2id"],
+  conf: ["get", "batch", "batch-file", "group", "group-file", "resolve", "resolve-file", "add", "add-file", "update", "delete"],
+  exp: ["status", "manifest", "commits", "file", "pull", "init", "commit", "lock", "release", "rollback"],
+  attend: ["statis"],
+  eb: ["perm-page"],
+};
+function commandIsKnown(pos) {
+  const family = pos[0], sub = pos[1];
+  if (!family) return false;                                   // 无命令 → 用法
+  if (family === "query") return true;                         // query 无子命令（cmdQuery 自行处理入参）
+  if (family === "login" || family === "xiaoe-env") return true; // 已由上方拦截块接管
+  const subs = CMD_SUBS[family];
+  if (!subs) return false;
+  return subs.includes(sub);
+}
+
+// ---- 拦截（必须早于 loadAuth()）：免凭据命令族 ----
+// ① 版本 / ② 帮助 / ③ 未知命令 —— 这三类都不需要凭据，故在取凭据之前 return。
+// （login 族由上方独立拦截块处理；exp release/rollback 的 --version 是版本号参数、长度 >1 不受影响）
+{
+  const rawArgv = process.argv.slice(2);
+  const { args: earlyArgs, pos: earlyPos } = parseArgs(rawArgv);
+
+  // ① --version / -v：仅顶层单参数
+  if (rawArgv.length === 1 && (rawArgv[0] === "--version" || rawArgv[0] === "-v")) {
+    console.log("e10-data " + cliVersion());
+    process.exit(0);
+  }
+
+  // ② --help / -h：显式求帮助 → 用法 + 退出码 0（区别于"用错了"的退出码 1）
+  //    只认「裸开关」（值为 true），避免把 --value --help 这类取值误判为求助；
+  //    -h 是单短横线、parseArgs 不识别，单独按顶层单参数处理
+  if (earlyArgs.help === true || (rawArgv.length === 1 && rawArgv[0] === "-h")) {
+    usage();
+    process.exit(0);
+  }
+
+  // ③ 未知命令族 / 未知子命令 / 缺子命令 → 用法提示，退出码 1
+  if (!commandIsKnown(earlyPos)) {
+    usage();
+    process.exit(1);
+  }
+}
+
+// ---- 取凭据（v0.1.17：先试进程间缓存，未命中再走 e10-login，并把结果发布给后续调用）----
+let auth = null;
+const CRED_CACHE_ON = !process.env.E10_DATA_NO_CRED_CACHE
+  && !process.env.E10_DATA_AUTH_MODE && !process.env.E10_DATA_AUTH_PROBE;
+if (CRED_CACHE_ON) auth = await credCacheGet();
+if (!auth) {
+  auth = loadAuth();
+  // 兜底出口（明文镜像）的凭据不写入缓存 —— 避免把可能已过期的凭据固化整个 TTL
+  if (CRED_CACHE_ON && !/镜像/.test(String(auth.source || ""))) await credCachePublish(auth);
+}
 const BASE = auth.baseUrl.replace(/\/+$/, "");
 const USER = { id: auth.userId || "", tenantKey: auth.tenantKey || "" };
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "e10-data",
-  "version": "0.1.16",
-  "description": "泛微 E10 数据接口统一 CLI（data-assistant 专家配套）：登录(login xiaoe-env，环境变量 XiaoE 全局 token 换 ETEAMSID，v0.1.16 新增，免浏览器/免 python)/DSL 查询/数据源/文档/词库/关联字段翻译/环境参数配置中心(conf，支持 confGroup 分组)/EB 建模表单权限校验(eb perm-page)/专家包版本管理；ds 取数（list/chart/stat/count）的 appId 由调用方显式传入 --app-id（v0.1.14 起 CLI 不再自动反查；EB 建模表单 weaver-ebuilder-form-service 必须带，appId 取自 eb perm-page 权限校验返回行）；认证加解密全部交由 weaver-e10-login（本 CLI 不再自行解密，通过 e10-login 命令出口获取凭据；仅 login xiaoe-env 在无凭据时自行换 token，写 profile 仍交 e10-login set）",
+  "version": "0.1.17-xiaoe",
+  "description": "泛微 E10 数据接口统一 CLI（data-assistant 专家配套）：登录(login xiaoe-env，环境变量 XiaoE 全局 token 换 ETEAMSID，免浏览器/免 python)/DSL 查询/数据源/文档/词库/关联字段翻译/环境参数配置中心(conf，支持 confGroup 分组)/EB 建模表单权限校验(eb perm-page)/专家包版本管理；ds 取数（list/chart/stat/count）的 appId 由调用方显式传入 --app-id（v0.1.14 起 CLI 不再自动反查；EB 建模表单 weaver-ebuilder-form-service 必须带，appId 取自 eb perm-page 权限校验返回行）；认证加解密全部交由 weaver-e10-login（本 CLI 不再自行解密，通过 e10-login 命令出口获取凭据；仅 login xiaoe-env 在无凭据时自行换 token，写 profile 仍交 e10-login set）。v0.1.17 性能改造：免凭据命令（--version/--help/未知命令）提前返回、直连 e10-login JS 入口（去掉 shell:true 的 cmd.exe 开销）、新增凭据进程间 TTL 缓存（不落明文）",
   "author": "e10-dw",
   "license": "MIT",
   "type": "module",
@@ -11,7 +11,8 @@
   "main": "bin/e10-data.mjs",
   "files": [
     "bin/",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=18.17.0"