weaver-e9-assistant-cli 1.0.0 → 1.1.1

package/dist/client.js

@@ -174,15 +174,36 @@ export class E9Api {
             throw new Error(`请求失败：${method} ${url}。服务器可能不可达或网络不通。`);
         return er;
     }
-    /** GET。URL+query 拼好后委托 requestWithRetry。 */
-    async get(path, query) {
-        return this.requestWithRetry('GET', buildUrl(this.baseUrl, path, query));
+    /**
+     * GET。URL+query 拼好后委托 requestWithRetry。
+     * opts.forceCookie=true 时强制走 cookie 头裸发一次（跳过 token/ensureValid）——
+     * 供 token 通道 no-op（200 但业务空、非 401 不走重试）的接口逃生，如 /api/ec/dev/app/getUserInfo。
+     */
+    async get(path, query, opts = {}) {
+        const url = buildUrl(this.baseUrl, path, query);
+        if (opts?.forceCookie) {
+            const headers = await this.getHeaders(undefined, { forceCookie: true });
+            const res = await fetch(url, { method: 'GET', headers, signal: AbortSignal.timeout(30000) }).catch(() => null);
+            return res ? await toE9Response(res) : null;
+        }
+        return this.requestWithRetry('GET', url, undefined, 30000);
     }
-    /** POST。body 用 URLSearchParams（与原 e9Request 编码一致），委托 requestWithRetry。 */
-    async post(path, body) {
+    /**
+     * POST。body 用 URLSearchParams（与原 e9Request 编码一致），委托 requestWithRetry。
+     * opts.forceCookie=true 时强制走 cookie 头裸发一次（跳过 token/ensureValid）——
+     * 供 token 通道 no-op（200 但业务空、非 401 不走重试）的接口逃生，如 hrm 下属查询。
+     */
+    async post(path, body, opts = {}) {
         const form = new URLSearchParams();
         for (const [k, v] of Object.entries(body ?? {}))
             form.append(k, v);
+        if (opts?.forceCookie) {
+            const headers = await this.getHeaders('application/x-www-form-urlencoded; charset=utf-8', { forceCookie: true });
+            const res = await fetch(buildUrl(this.baseUrl, path), {
+                method: 'POST', headers, body: form.toString(), signal: AbortSignal.timeout(30000),
+            }).catch(() => null);
+            return res ? await toE9Response(res) : null;
+        }
         return this.requestWithRetry('POST', buildUrl(this.baseUrl, path), form.toString(), 30000);
     }
 }

package/dist/cube.js

@@ -79,6 +79,74 @@ export async function getCubeCondition(cfg, opts = {}) {
         .filter((it) => it.label);
     return { items, raw: j };
 }
+/**
+ * ★越权防护 人员条件 label 白名单（专项守卫正则，不复用 wfuser.js PERSON_LABEL——
+ *   它漏了 审批人/接收人/操作人/下属，且含 联系人 会误伤 联系人电话）。
+ * 判定前先剔除含 电话/手机/邮箱/号码/传真/部门/日期/时间 的字段（非人筛选）。
+ * 说明：方案A（label 正则）为主判据；conditionType 码未知，实跑校准后补 type 码 OR。
+ */
+/**
+ * 明确排除的非人字段：联系方式（联系人电话…）/ 日期时间（填报日期…）/ 计数单位（人数/人次/人天…）。
+ * 不排除「部门」——部门负责人/部门经办人/部门审批人仍是人员，后缀「人」判据应当命中。
+ */
+const NON_PERSON_LABEL = /电话|手机|邮箱|号码|传真|日期|时间|区间|人数|人次|人天/;
+/** 明确的人员白名单（不含「人」字或不在后缀规则内的：姓名/人员/联系人/下属/上级）。 */
+export const PERSON_CONDITION_LABEL =
+    /^(姓名|人员|联系人|下属|上级|领导)$/u;
+/** 人员后缀判据（先剔除 NON_PERSON 后）：X人/ X人员/ X员/ X者（报销人/值班人员/采购员/阅读者…）。
+ * 人员类别/人员类型等「人员+名词」不是人员过滤（人员类别=正式工），靠「末尾字符∈人者员」排除。 */
+const PERSON_SUFFIX = /[人者员]$/u;
+
+/**
+ * 该 label 是否属于「按人过滤」查询条件（fail-closed：宁可多拦）。
+ * 判据 = 后缀启发式「X人」（报销人/使用人/领用人/申请人/审批人/经办人/填报人…全部覆盖）+
+ *        白名单（姓名/人员/联系人/下属/上级）；先剔除联系方式/日期时间/计数单位。
+ * 后缀启发式替代旧白名单枚举——旧白名单漏「报销人/使用人/领用人」等，会放行越权查询。
+ */
+export function isPersonConditionLabel(label) {
+    if (typeof label !== 'string' || !label.trim())
+        return false;
+    const l = label.trim();
+    if (NON_PERSON_LABEL.test(l))
+        return false;
+    if (PERSON_SUFFIX.test(l))
+        return true;
+    if (l.includes('姓名'))
+        return true;
+    return PERSON_CONDITION_LABEL.test(l);
+}
+
+/**
+ * ★越权防护 人员条件分类（纯函数，便于单测）。
+ * condItems：getCubeCondition 返回的条件项 [{label, domkey, type}]。
+ * rawPairs：[["键","值"],...]（键可能是 domkey 也可能是中文 label）。
+ * 返回 [{label, domkey, value}]——命中人员条件白名单的键值对。
+ */
+export function classifyPersonConditions(condItems, rawPairs) {
+    if (!Array.isArray(rawPairs) || rawPairs.length === 0)
+        return [];
+    // domkey → label 索引（label 键也能命中 condItems 的 label）
+    const domToLabel = {};
+    for (const it of condItems || [])
+        for (const dk of (it.domkey ?? []))
+            if (it.label && !(dk in domToLabel))
+                domToLabel[dk] = it.label;
+    const labels = new Set((condItems || []).map((it) => it.label).filter(Boolean));
+    const personConditions = [];
+    for (const [k, v] of rawPairs) {
+        const key = String(k ?? '').trim();
+        const val = String(v ?? '').trim();
+        if (!key || !val)
+            continue;
+        const label = domToLabel[key] ?? (labels.has(key) ? key : null);
+        // 后缀启发式直接判按键名（即使条件定义缺失，也能拦「报销人=王五」）；
+        // domkey 依赖 domToLabel 反查；两者皆无则落到 unverifiablePerson 由调用方 fail-closed 拒绝。
+        if (isPersonConditionLabel(label ?? key))
+            personConditions.push({ label: label ?? key, domkey: key, value: val });
+    }
+    return personConditions;
+}
+
 /**
  * ★新 条件字符串 → conditionValues 映射（P2-3，0.4.8）。
  *
@@ -86,7 +154,10 @@ export async function getCubeCondition(cfg, opts = {}) {
  *   - 键以 `con_`/`dom_`/`field`/`col` 开头 → 视为合法 domkey，原样透传（向后兼容）。
  *   - 其它 → 视为中文 label，用 getCubeCondition 的 label→domkey 映射自动转换；
  *     未匹配时返回 unresolved（含候选 label 列表），由调用方报错提示，不静默放空。
- * 返回 { conditionValues, unresolved:[{label, candidates:[...]}] }。
+ * ★越权防护（1.1.0）：只要传了条件就取一次条件定义——含 domkey 直传也要反查 label 分类，
+ *   堵 `con_7261=...` 直接给 domkey 绕开中文 label 的越权口；getCubeCondition 抛错 → 透传不阻断
+ *   但打 stderr 警告「本次未做人员越权校验」。
+ * 返回 { conditionValues, unresolved:[{label, candidates:[...]}], personConditions:[{label, domkey, value}] }。
  */
 export async function resolveCubeCondition(cfg, opts = {}) {
     const customid = String(opts.customid);
@@ -100,21 +171,27 @@ export async function resolveCubeCondition(cfg, opts = {}) {
                 pairs.push([kv.slice(0, i).trim(), kv.slice(i + 1).trim()]);
         }
     if (pairs.length === 0)
-        return { conditionValues, unresolved: [] };
+        return { conditionValues, unresolved: [], personConditions: [] };
     // 判断是否含中文 label 键
     const needsLabelMap = pairs.some(([k]) => !/^(con|dom|field|col)[-_]?/i.test(k));
-    let labelToDom = {};
-    let mappingFailed = false;
-    if (needsLabelMap) {
-        try {
-            const cond = await getCubeCondition(cfg, { customid });
-            for (const it of cond.items)
-                for (const dk of (it.domkey ?? []))
-                    if (it.label && !(it.label in labelToDom))
-                        labelToDom[it.label] = dk;
-        }
-        catch { mappingFailed = true; }
+    let condItems = [];
+    let condFetched = false;
+    // ★越权防护：只要传了条件就取一次条件定义（含 domkey 直传也要反查 label 分类）
+    try {
+        const cond = await getCubeCondition(cfg, { customid });
+        condItems = cond.items;
+        condFetched = true;
+    }
+    catch {
+        // fail-closed：定义读不到时 domkey 无法反查 → 由下方 unverifiablePerson 拒绝；中文 label 按名称判定不受影响
+        if (pairs.some(([k]) => /^(con|dom|field|col)[-_]?/i.test(k)))
+            process.stderr.write('⚠ 无法读取台账查询条件定义：domkey 类条件将被拒绝（无法确认是否按人过滤），中文字段名条件按名称判定。\n');
     }
+    const labelToDom = {};
+    for (const it of condItems)
+        for (const dk of (it.domkey ?? []))
+            if (it.label && !(it.label in labelToDom))
+                labelToDom[it.label] = dk;
     const unresolved = [];
     for (const [k, v] of pairs) {
         if (/^(con|dom|field|col)[-_]?/i.test(k)) {
@@ -125,8 +202,8 @@ export async function resolveCubeCondition(cfg, opts = {}) {
         if (domkey) {
             conditionValues[domkey] = v;
         }
-        else if (mappingFailed) {
-            // 映射接口本身失败（网络抖动/无权限）：按原样透传，不阻断（用户可能直接给了 domkey）
+        else if (!condFetched) {
+            // 条件定义接口本身失败（网络抖动/无权限）：按原样透传，不阻断（用户可能直接给了 domkey）——但已打越权警告
             conditionValues[k] = v;
         }
         else {
@@ -135,7 +212,21 @@ export async function resolveCubeCondition(cfg, opts = {}) {
             unresolved.push({ label: k, candidates });
         }
     }
-    return { conditionValues, unresolved };
+    // ★越权防护（fail-closed）：无法确认是否按人过滤的条件 → 调用方硬拒绝。
+    //   - 条件定义读取失败：domkey 类键无法反查 label → 无法确认；
+    //   - 定义读取成功但 domkey 不在定义中：可能是未进筛选定义的人员字段 → 无法确认；
+    //   中文 label 键可经后缀启发式直接判定，不依赖定义。
+    const knownDom = new Set();
+    for (const it of condItems)
+        for (const dk of (it.domkey ?? []))
+            knownDom.add(dk);
+    let unverifiablePerson = false;
+    for (const [k, v] of pairs)
+        if (v && /^(con|dom|field|col)[-_]?/i.test(String(k)) && !knownDom.has(String(k).trim()))
+            unverifiablePerson = true;
+    // ★越权防护：人员条件分类（供调用方 assertNamesInScope 校验）
+    const personConditions = classifyPersonConditions(condItems, pairs);
+    return { conditionValues, unresolved, unverifiablePerson, personConditions };
 }
 /**
  * ★新 字段下拉选项全表。GET /api/cube/search/getSearchColumnInfo?customid=<id>。
@@ -1112,9 +1203,13 @@ export async function submitCubeCard(cfg, opts = {}) {
     await e9Request(ep, { method: 'POST', path: '/api/cube/new/card/cubeVerifyRepeat', body: { billid, type: '1', modeId, formId, _key, guid: 'card', verifys: '{}' } });
     await e9Request(ep, { method: 'POST', path: '/api/cube/new/card/checkCardDataChange', body: { billid, type: '1', modeId, formId, _key, guid: 'card', changeDataTime: cdt, iscreate } });
     // ④ JSONStr 全字段（cf.fields 所有 id，values 覆盖，未填给空）
+    // 修复 #37：只读字段（isedit=false）未填时优先带 mainFields 返回的默认值 f.value——
+    //   填报人(dkr)/填报日期(dkrq)/填报时间(dksj)/员工类型(yglx) 等由后端在新建态 mainFields
+    //   预填当前用户/今天/当前时间，旧实现兜底 '' 覆盖为空格，实测 billid=35 这些字段提交后为空。
+    //   f.value 兜底同样修复 edit：编辑态 mainFields 带当前值，未传字段不再被清空。
     const jsonObj = {};
     for (const f of fields)
-        jsonObj[`field${f.id}`] = String(values[f.id] ?? values[`field${f.id}`] ?? '');
+        jsonObj[`field${f.id}`] = String(values[f.id] ?? values[`field${f.id}`] ?? f.value ?? '');
     // ⑤ doSubmit（cookie，同 session）
     const body = {
         billid, type: '1', modeId, formId, _key, guid: 'card', token: cardToken,
@@ -1157,7 +1252,15 @@ export async function previewCubeCard(cfg, opts = {}) {
             return { fieldId: String(fid), label: f?.label ?? `field${fid}`, value: so?.name ?? info.value };
         });
     }
-    return { modeId, formId, billid, layoutid, fields, finalValues: values, linked, files };
+    // 未填字段并入 mainFields 默认值（只读字段填报人/填报日期等后端预填），
+    // 保证 dry-run 确认表与真实提交字段集一致（同 submitCubeCard 的 f.value ?? '' 兜底）。
+    const finalValues = { ...values };
+    for (const f of fields) {
+        const fid = String(f.id);
+        if (finalValues[fid] === undefined && finalValues[`field${fid}`] === undefined && f.value !== undefined && f.value !== null && f.value !== '')
+            finalValues[fid] = f.value;
+    }
+    return { modeId, formId, billid, layoutid, fields, finalValues, linked, files };
 }
 /** 删除台账记录（cookie）。GET /api/cube/expand/deleteData?operate=DeleteAction&billids=。 */
 export async function deleteCubeData(cfg, opts = {}) {

package/dist/email.js

@@ -773,7 +773,10 @@ export async function uploadEmailAttachment(cfg, filePath, { name } = {}) {
     catch {
         j = null;
     }
-    return { ok: j?.status === '1' || r.ok, data: j?.data ?? null, raw: j };
+    // 修复 #3：cookie 过期时后端返回 HTTP 200 + {msg:"登录信息超时",errorCode:"002",status:false}，
+    // 旧判断把 r.ok（HTTP 200）当成功 → 附件实际未上传却显示成功。只认 body 的 status 成功标志。
+    const ok = j?.status === '1' || j?.status === 1 || j?.status === true;
+    return { ok, data: j?.data ?? null, raw: j };
 }
 /**
  * 附件列表。链路：GET /api/email/attachment/list?filename=&subject= → sessionkey

package/dist/subordinate.js

@@ -0,0 +1,419 @@
+/**
+ * 我的下属：查询直接/全部层级下属 + 越权防护（fail-closed）。
+ *
+ * 链路（用户抓包确认，POST 均表单编码）：
+ *   1) /api/hrm/subordinateinfo/getSearchResult  body { id, lastname, showAllLevel } → dataKey
+ *   2) /api/ec/dev/table/datas                    body { dataKey, current, sortParams } → 行 + columns（不带 pageSize，跟随服务端默认）
+ *   3) /api/ec/dev/table/counts                   body { dataKey } → 总数 {count:N,status:true}
+ *
+ * 越权边界（用户明确要求，fail-closed）：
+ *   查询数据只能查「当前登录用户 + 全部层级下属」，目标人员不在授权集合 → 拒绝。
+ *   授权集合加载失败/不可靠时，非本人查询一律拒绝；本人永远允许。
+ *
+ * 安全设计要点：
+ *   - 授权集合按环境隔离缓存 ~/.e9/subordinate_scope_<envkey>.json，TTL 12h（E9_SCOPE_TTL_HOURS 可调）。
+ *   - 缓存必须 selfId 匹配才可用（错用户/过期/不可靠一律不用，防离职下属仍被放行）。
+ *   - 姓名→userid 解析唯一入口是 blog at-list（SKILL.md 硬规则），候选按 精确>前缀>拼音 排序后过滤到范围。
+ *   - 下属表找不到 id 列 → scope 标记 reliable:false → 非本人查询拒绝（安全但功能受限，实跑校准回填规则）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { createApiFromProfile } from './client.js';
+import { extractDataKey, extractRows, extractColumns, extractTotal, pickByPaths, stripHtml } from './parse.js';
+import { getCurrentUser } from './wfuser.js';
+import { getAtAllList } from './blog.js';
+import { profileNameFromBaseUrl } from './config.js';
+
+/** 全层级下属翻页上限（超限仍未收全 → reliable:false）。 */
+export const MAX_SCOPE_PAGES = 20;
+/** 授权集合缓存 TTL（默认 12h，比台账目录的 7 天短——越权集合同理会随组织变动，宁短勿长）。 */
+export const SCOPE_TTL_MS = (Number(process.env.E9_SCOPE_TTL_HOURS ?? '12') || 12) * 3600 * 1000;
+/** 缓存目录（测试可用 E9_SCOPE_CACHE_DIR 覆盖，避免污染真实 ~/.e9）。 */
+function scopeCacheDir() {
+    return process.env.E9_SCOPE_CACHE_DIR || path.join(os.homedir(), '.e9');
+}
+function scopeCachePath(cfg) {
+    const envkey = profileNameFromBaseUrl(cfg.baseUrl);
+    return path.join(scopeCacheDir(), `subordinate_scope_${envkey}.json`);
+}
+
+// ─── 链路函数 ────────────────────────────────────────────
+
+/** 拿下属列表 dataKey。token no-op 逃生：200 但无 dataKey 且配了 cookie → 强制 cookie 重试一次。 */
+export async function fetchSubordinateDataKey(cfg, { lastname = '', showAllLevel = false } = {}) {
+    const api = await createApiFromProfile(cfg);
+    const body = { id: '', lastname: String(lastname ?? ''), showAllLevel: showAllLevel ? 'true' : 'false' };
+    let r = await api.post('/api/hrm/subordinateinfo/getSearchResult', body);
+    let dataKey = extractDataKey(r?.json);
+    if (!dataKey && cfg.cookie) {
+        r = await api.post('/api/hrm/subordinateinfo/getSearchResult', body, { forceCookie: true });
+        dataKey = extractDataKey(r?.json);
+    }
+    if (!dataKey) {
+        throw new Error('未能从 getSearchResult 响应中提取 dataKey。\n' + `响应(前300字): ${truncate(r?.text)}`);
+    }
+    return { dataKey, raw: r?.json ?? null };
+}
+
+/** 取下属表一页数据（不带 pageSize，跟随服务端默认每页条数）。 */
+export async function fetchSubordinateDataPage(cfg, dataKey, page) {
+    const api = await createApiFromProfile(cfg);
+    const r = await api.post('/api/ec/dev/table/datas', { dataKey, current: String(page), sortParams: '[]' });
+    const json = r?.json ?? {};
+    return {
+        rows: extractRows(json),
+        columns: extractColumns(json),
+        pageSize: pickNum(json, ['pageSize', 'data.pageSize', 'rootMap.pagesize', 'data.rootMap.pagesize']),
+        raw: json,
+    };
+}
+
+/** 下属表总数。 */
+export async function fetchSubordinateCount(cfg, dataKey) {
+    const api = await createApiFromProfile(cfg);
+    const r = await api.post('/api/ec/dev/table/counts', { dataKey });
+    return { total: extractTotal(r?.json), raw: r?.json ?? null };
+}
+
+// ─── 列检测（校准锚点，fail-closed 关键） ────────────────
+
+/** 找下属表的 id 列（拿不到 → scope 不可靠 → 非本人查询拒绝）。 */
+export function detectSubordinateIdColumn(columns) {
+    if (!Array.isArray(columns))
+        return null;
+    return columns.find((c) => {
+        const di = String(c?.dataIndex ?? '').toLowerCase();
+        const db = String(c?.dbField ?? '').toLowerCase();
+        return /^(id|userid|hrmid|randomfieldid)$/i.test(di) || /^(id|userid|hrmid)$/i.test(db);
+    }) ?? null;
+}
+
+/** 找下属表的姓名列（取不到 → userName 匹配失效，但 userId 匹配仍生效）。 */
+export function detectSubordinateNameColumn(columns) {
+    if (!Array.isArray(columns))
+        return null;
+    return columns.find((c) => {
+        const di = String(c?.dataIndex ?? '').toLowerCase();
+        const title = String(c?.title ?? '');
+        return /^(lastname|name)$/i.test(di) || /姓名|人员|名字/.test(title);
+    }) ?? null;
+}
+
+// ─── 列表命令后端 ────────────────────────────────────────
+
+/** 规范化一行下属：id/name + 全部列（<field>span 优先去 HTML）。人员无独立页面 → 纯文本。 */
+export function normalizeSubordinateRow(row, columns) {
+    if (!row || typeof row !== 'object')
+        return {};
+    const idCol = detectSubordinateIdColumn(columns);
+    const nameCol = detectSubordinateNameColumn(columns);
+    const get = (k) => pickByPaths(row, [k]);
+    const id = idCol ? stripHtml(get(idCol.dataIndex)) : '';
+    const name = nameCol ? stripHtml(get(`${nameCol.dataIndex}span`) ?? get(nameCol.dataIndex)) : '';
+    const fields = (columns || []).map((c) => ({
+        dataIndex: c.dataIndex,
+        title: c.title,
+        value: stripHtml(get(`${c.dataIndex}span`) ?? get(c.dataIndex)),
+    }));
+    return { id, name, fields, raw: row };
+}
+
+/**
+ * 查询我的下属列表。showAllLevel=false=直接下属（抓包默认）/true=全部层级。
+ * 返回 { lastname, allLevel, page, pageSize, total, count, dataKey, columns, items, raw }。
+ */
+export async function getSubordinates(cfg, opts = {}) {
+    const lastname = opts.lastname ?? '';
+    const allLevel = !!opts.allLevel;
+    const page = Number(opts.page ?? '1') || 1;
+    const { dataKey, raw: searchRaw } = await fetchSubordinateDataKey(cfg, { lastname, showAllLevel: allLevel });
+    const data = await fetchSubordinateDataPage(cfg, dataKey, page);
+    const count = await fetchSubordinateCount(cfg, dataKey);
+    const total = count.total ?? null;
+    const items = data.rows.map((r) => normalizeSubordinateRow(r, data.columns));
+    return {
+        lastname,
+        allLevel,
+        page,
+        pageSize: data.pageSize ?? (data.rows.length || null),
+        total,
+        count: items.length,
+        dataKey,
+        columns: data.columns,
+        items,
+        raw: { getSearchResult: searchRaw, datas: data.raw, counts: count.raw },
+    };
+}
+
+// ─── 授权集合加载 + 缓存（严格 fail-closed） ─────────────
+
+/**
+ * 加载授权集合 { 当前用户 } ∪ { 全部层级下属 }。
+ * 返回 { reliable, error?, selfId, selfName, userIds:Set, userNames:Set, fromCache, fetchedAt }。
+ *   reliable:false 表示集合不可靠（身份未确认/拉取失败/未收全/id 列缺失）→ 调用方只允许放行本人。
+ */
+export async function loadScope(cfg, opts = {}) {
+    // 1. 自证身份：getCurrentUser → cookie 兜底 → 仍空则连本人都无法确认，一切带人查询拒绝
+    let selfId = '';
+    let selfName = '';
+    try {
+        const u = await getCurrentUser(cfg);
+        selfId = String(u?.userid ?? '');
+        selfName = String(u?.username ?? '');
+    }
+    catch { /* 走 cookie 兜底 */ }
+    if (!selfId)
+        selfId = parseUserIdFromCookie(cfg?.cookie);
+    if (!selfId) {
+        return { reliable: false, error: 'no-self', selfId: '', selfName: '', userIds: new Set(), userNames: new Set() };
+    }
+    // 2. 缓存命中：selfId 匹配 + 未过期 + reliable 才可用（错用户/过期/不可靠一律弃）
+    if (!opts.refresh && !opts.noCache) {
+        const cached = readScopeCache(cfg, selfId);
+        if (cached) {
+            return { ...cached, selfId, selfName, userIds: new Set(cached.userIds), userNames: new Set(cached.userNames), fromCache: true };
+        }
+    }
+    // 3. 拉全层级下属，逐页收行
+    const userIds = new Set([selfId]);
+    const userNames = new Set([selfName].filter(Boolean));
+    let reliable = false;
+    let idCol = null;
+    let nameCol = null;
+    let rows = [];
+    let total = null;
+    try {
+        const { dataKey } = await fetchSubordinateDataKey(cfg, { lastname: '', showAllLevel: true });
+        let page = 1;
+        let hitEnd = false;
+        while (page <= MAX_SCOPE_PAGES) {
+            const d = await fetchSubordinateDataPage(cfg, dataKey, page);
+            if (page === 1) {
+                idCol = detectSubordinateIdColumn(d.columns);
+                nameCol = detectSubordinateNameColumn(d.columns);
+            }
+            const pageRows = d.rows;
+            rows = rows.concat(pageRows);
+            if (pageRows.length === 0) {
+                hitEnd = true;
+                break;
+            }
+            // 短页 = 末尾（响应给了 pageSize 时能判；不给就靠 counts total 判完整）
+            if (d.pageSize && pageRows.length < d.pageSize) {
+                hitEnd = true;
+                break;
+            }
+            page++;
+        }
+        const count = await fetchSubordinateCount(cfg, dataKey);
+        total = count.total;
+        // 完整性判定：有 total 时收行数必须 >= total；无 total 时必须见到空页/短页才算到底
+        reliable = idCol != null && (total != null ? rows.length >= total : hitEnd);
+        if (reliable) {
+            for (const row of rows) {
+                const uid = stripHtml(pickByPaths(row, [idCol.dataIndex]));
+                if (/^\d+$/.test(uid))
+                    userIds.add(uid);
+                if (nameCol) {
+                    const nm = stripHtml(pickByPaths(row, [`${nameCol.dataIndex}span`, nameCol.dataIndex]));
+                    if (nm)
+                        userNames.add(nm);
+                }
+            }
+        }
+    }
+    catch { reliable = false; }
+    const scope = { reliable, error: reliable ? undefined : 'scope-unreliable', selfId, selfName, userIds, userNames, fetchedAt: Date.now() };
+    // 仅 reliable 才写缓存（写失败不阻断）
+    if (reliable)
+        writeScopeCache(cfg, scope);
+    return scope;
+}
+
+/** 读缓存；selfId 不匹配 / 过期 / 不可靠 → null。 */
+function readScopeCache(cfg, selfId) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(scopeCachePath(cfg), 'utf8'));
+        if (!raw || raw.selfId !== selfId || raw.reliable !== true)
+            return null;
+        if (Date.now() - (raw.fetchedAt || 0) > SCOPE_TTL_MS)
+            return null;
+        return raw;
+    }
+    catch {
+        return null;
+    }
+}
+
+/** 写缓存（失败不阻断）。 */
+function writeScopeCache(cfg, scope) {
+    try {
+        fs.mkdirSync(scopeCacheDir(), { recursive: true });
+        fs.writeFileSync(scopeCachePath(cfg), JSON.stringify({
+            envkey: profileNameFromBaseUrl(cfg.baseUrl),
+            baseUrl: cfg.baseUrl,
+            selfId: scope.selfId,
+            selfName: scope.selfName,
+            userIds: [...scope.userIds],
+            userNames: [...scope.userNames],
+            reliable: scope.reliable,
+            fetchedAt: scope.fetchedAt,
+        }, null, 2) + '\n', 'utf8');
+    }
+    catch { /* 缓存写失败不阻断查询 */ }
+}
+
+/** 是否在授权集合内（纯函数，便于单测）。 */
+export function isInScope(scope, { userId, userName } = {}) {
+    if (!scope || !scope.userIds)
+        return false;
+    if (userId != null && scope.userIds.has(String(userId).trim()))
+        return true;
+    if (userName != null && String(userName).trim() && scope.userNames?.has(String(userName).trim()))
+        return true;
+    return false;
+}
+
+// ─── 校验/拒绝 ───────────────────────────────────────────
+
+/**
+ * 按数字 userid 校验：目标必须 == 本人 或 ∈ 下属集合，否则 throw。
+ * ids 里的每个目标都校验；scope 不可靠时本人放行、他人一律拒绝。
+ */
+export async function assertUserIdsInScope(cfg, ids, opts = {}) {
+    const scope = await loadScope(cfg, opts);
+    for (const id of ids) {
+        const s = String(id ?? '').trim();
+        if (!s)
+            continue;
+        // 本人恒允许（即使 scope 不可靠）——越权边界定义：本人 + 全部层级下属；
+        // no-self 时 selfId 为空，非空 id 自然落空走拒绝。
+        if (s === scope.selfId)
+            continue;
+        if (scope.reliable && scope.userIds.has(s))
+            continue;
+        throw new Error(outOfScopeMessage(s, { reason: scope.reliable ? 'not-subordinate' : (scope.error === 'no-self' ? 'no-self' : 'scope-unreliable') }));
+    }
+}
+
+/**
+ * 按姓名校验：纯数字走 assertUserIdsInScope；否则 blog at-list 解析（SKILL.md 硬规则唯一入口），
+ * 候选按 精确>前缀>拼音 排序后过滤到授权集合：
+ *   - 恰 1 个在范围 → 放行，返回其 uid；
+ *   - 全部越界 / 多个在范围 → throw（拒绝，附范围内候选清单）。
+ * 返回单个 uid（names 长度 1）或 uid 数组。调用方可忽略返回值（如 cube 仅校验、值保持原样）。
+ */
+export async function assertNamesInScope(cfg, names, opts = {}) {
+    const scope = await loadScope(cfg, opts);
+    const resolved = [];
+    for (const name of names) {
+        const n = String(name ?? '').trim();
+        if (!n)
+            continue;
+        if (/^\d+$/.test(n)) {
+            await assertUserIdsInScope(cfg, [n], opts);
+            resolved.push(n);
+            continue;
+        }
+        const r = await getAtAllList(cfg, { name: n });
+        const candidates = sortPersonCandidates(r.items, n);
+        const { inScope, outCount } = filterCandidatesToScope(scope, candidates);
+        if (inScope.length === 0) {
+            throw new Error(outOfScopeMessage(n, { reason: 'none-in-scope', candidates: candidates.slice(0, 5), outCount }));
+        }
+        if (inScope.length === 1) {
+            resolved.push(String(inScope[0].uid ?? ''));
+            continue;
+        }
+        throw new Error(outOfScopeMessage(n, { reason: 'multiple-in-scope', candidates: inScope }));
+    }
+    return resolved.length === 1 ? resolved[0] : resolved;
+}
+
+/** 候选过滤到授权集合（纯函数）。 */
+export function filterCandidatesToScope(scope, candidates) {
+    const inScope = [];
+    let outCount = 0;
+    for (const c of candidates) {
+        const uid = String(c.uid ?? '');
+        const name = stripHtml(String(c.name ?? '')).trim();
+        if (uid && isInScope(scope, { userId: uid })) {
+            inScope.push({ ...c, name });
+        }
+        else if (name && isInScope(scope, { userName: name })) {
+            inScope.push({ ...c, name });
+        }
+        else {
+            outCount++;
+        }
+    }
+    return { inScope, outCount };
+}
+
+/** 人员候选排序：精确 > 前缀 > 其它（复刻 cli.js at-list 逻辑）。 */
+function sortPersonCandidates(items, query) {
+    const q = String(query ?? '').trim().toLowerCase();
+    return (items || [])
+        .map((it) => {
+            const name = String(it.name ?? '').trim();
+            const nameLow = name.toLowerCase();
+            let matchType = 'other';
+            if (q && nameLow === q)
+                matchType = 'exact';
+            else if (q && nameLow.startsWith(q))
+                matchType = 'prefix';
+            return { ...it, name, matchType, _sort: matchType === 'exact' ? 0 : matchType === 'prefix' ? 1 : 2 };
+        })
+        .sort((a, b) => a._sort - b._sort)
+        .map(({ _sort, ...rest }) => rest);
+}
+
+/** 越权拒绝文案（fail-closed 显式归因）。 */
+export function outOfScopeMessage(target, { reason = 'not-subordinate', candidates = [], outCount = 0 } = {}) {
+    let cause;
+    if (reason === 'no-self')
+        cause = '无法确认当前登录用户身份，为安全起见拒绝所有按人查询';
+    else if (reason === 'scope-unreliable')
+        cause = '下属范围加载失败，为安全起见仅允许查询您本人的数据';
+    else if (reason === 'none-in-scope')
+        cause = `匹配到 ${outCount} 位人员，均不在您的下属名单中`;
+    else if (reason === 'multiple-in-scope')
+        cause = '匹配到多位在您授权范围内的人员，请指定唯一目标';
+    else
+        cause = '目标不在您的下属名单中';
+    const lines = [`拒绝越权查询：目标“${target}”不在您的授权范围（您本人 + 您的全部层级下属）内。`, `原因：${cause}。`];
+    if (candidates.length) {
+        lines.push('在您授权范围内匹配到以下人员：');
+        candidates.forEach((c, i) => {
+            lines.push(`${i + 1}. ${c.name}  [uid=${c.uid}]${c.matchType === 'exact' ? ' ★精确匹配' : c.matchType === 'prefix' ? ' ·前缀' : ''}`);
+        });
+        lines.push('如需继续，请指定其中一人的 ID 作为目标。');
+    }
+    lines.push('如需查询其本人数据，请在 OA 中由其本人或对其有权限的上级办理。');
+    return lines.join('\n');
+}
+
+// ─── 工具 ────────────────────────────────────────────────
+
+function parseUserIdFromCookie(cookie) {
+    if (!cookie)
+        return '';
+    const m = String(cookie).match(/loginuuids=([^;]+)/);
+    return m ? m[1].trim() : '';
+}
+
+function pickNum(obj, paths) {
+    const v = pickByPaths(obj, paths);
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && /^\d+$/.test(v))
+        return parseInt(v, 10);
+    return null;
+}
+
+function truncate(s, n = 300) {
+    if (s == null)
+        return '(空)';
+    return String(s).length > n ? String(s).slice(0, n) + '…(已截断)' : String(s);
+}