weaver-e9-assistant-cli 1.1.1 → 1.1.3

package/dist/subordinate.js

@@ -1,419 +1,433 @@
-/**
- * 我的下属：查询直接/全部层级下属 + 越权防护（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);
-}
+/**
+ * 我的下属：查询直接/全部层级下属 + 越权防护（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;
+}
+
+// ─── 校验/拒绝 ───────────────────────────────────────────
+
+/**
+ * 「只能查本人 + 全部层级下属」策略开关（当前默认**不生效**）。
+ * 设 E9_SCOPE_ENFORCE=1 可恢复强制校验；后台 OA 权限仍是最终兜底。
+ */
+export function isScopeEnforced() {
+    return process.env.E9_SCOPE_ENFORCE === '1';
+}
+
+/**
+ * 按数字 userid 校验：目标必须 == 本人 或 ∈ 下属集合，否则 throw。
+ * ids 里的每个目标都校验；scope 不可靠时本人放行、他人一律拒绝。
+ * 策略未启用（默认）时直接放行——不做任何拦截。
+ */
+export async function assertUserIdsInScope(cfg, ids, opts = {}) {
+    if (!isScopeEnforced())
+        return;
+    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) {
+    if (!isScopeEnforced()) {
+        return { inScope: (candidates || []).map((c) => ({ ...c, name: stripHtml(String(c?.name ?? '')).trim() })), outCount: 0 };
+    }
+    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);
+}