weaver-work-cli 0.1.32 → 0.1.33

package/dist/shortcuts/ehr/operations/recruit.js

@@ -42,7 +42,7 @@ const LIST_KEYWORDS = {
     biz_config: ['业务配置映射表'],
 };
 /** 列表类型 -> 缓存键 + 表单逻辑名（candidate.list 四列表映射，同 recruit-list.mjs TYPES） */
-const LIST_TYPES = {
+export const LIST_TYPES = {
     demand: { listKey: 'demand', formType: 'demand_manage', title: '招聘需求' },
     position: { listKey: 'position', formType: 'position_manage', title: '招聘职位' },
     entry: { listKey: 'entry', formType: 'entry_manage', title: '入职管理' },
@@ -58,7 +58,7 @@ const INTERNAL_KEYS = new Set([
 const DISPLAY_UI_KEYS = new Set([
     ...INTERNAL_KEYS, 'operate', 'isToDo', 'todoPropSpan', 'flow_status',
 ]);
-function randHex32() {
+export function randHex32() {
     return randomUUID().replace(/-/g, '');
 }
 function randHex6() {
@@ -419,7 +419,7 @@ export function createRecruitContextLoader() {
     return { load };
 }
 /** EB 列表通用查询体（同 recruit-list.mjs baseBody） */
-function buildListBody(params) {
+export function buildListBody(params) {
     return {
         current: params.current ?? 1,
         pageSize: params.pageSize ?? 10,
@@ -444,7 +444,7 @@ function buildListBody(params) {
     };
 }
 /** 列表 + 计数并行；displayData 优先（同 recruit-search/recruit-list 的显示层策略） */
-async function fetchListRows(host, objId, listId, body) {
+export async function fetchListRows(host, objId, listId, body) {
     const countBody = { ...body };
     delete countBody.current;
     delete countBody.pageSize;
@@ -466,8 +466,33 @@ async function fetchListRows(host, objId, listId, body) {
     const hasDisplay = Array.isArray(displayRows) && displayRows.length > 0;
     const rows = hasDisplay ? displayRows : rawRows;
     const countData = countResponse ? normalizePaged(countResponse).data : null;
-    const total = countData?.total !== undefined ? countData.total : rows.length;
-    return { rows, displayRows: hasDisplay ? displayRows : null, total };
+    const pageSize = typeof body.pageSize === 'number'
+        ? body.pageSize
+        : (typeof body.pageSize === 'string' ? (Number(body.pageSize) || rows.length) : rows.length);
+    // 总数取值（不输出假值，对齐 ehr recruit-list.mjs 三态降级）：
+    // ① 计数接口可用（200 且 total 为数字）→ 精确；
+    // ② 计数不可用但本页未满（rows < pageSize，即已到末页）→ 总数=已取回行数（精确）；
+    // ③ 计数不可用且本页已满 → total=null（总数不可知），附 note 提示加大 pageSize。
+    // 背景：部分租户/列表 getListDataCount 恒 500，且 getListDatas 的 total 不可信，唯一可靠判据是分页本身。
+    const countUsable = countData !== null && typeof countData.total === 'number';
+    let total;
+    let totalExact;
+    let totalNote;
+    if (countUsable) {
+        total = countData.total;
+        totalExact = true;
+    }
+    else if (rows.length < pageSize) {
+        total = rows.length;
+        totalExact = true;
+        totalNote = '计数接口不可用，本页未满（已到末页），总数按已取回行数得出';
+    }
+    else {
+        total = null;
+        totalExact = false;
+        totalNote = '计数接口不可用且本页已满，总数不可知（可调大 pageSize 取回全部行数）';
+    }
+    return { rows, displayRows: hasDisplay ? displayRows : null, total, totalExact, totalNote };
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // operations
@@ -537,7 +562,7 @@ const candidateSearch = {
             pageSize: toNumber(args.pageSize, 'pageSize') ?? 10,
             conditions,
         });
-        const { rows, displayRows, total } = await fetchListRows(env.host, talentObjId, talentList.listId, body);
+        const { rows, displayRows, total, totalExact, totalNote } = await fetchListRows(env.host, talentObjId, talentList.listId, body);
         // 显示层优先：displayData 已内联人员/字典中文，零额外请求；
         // 缺失时回退原始层：字典映射 + 纯 ID 经 hrm getEmployeeByIds 批量反查（兜底，行为不变）
         let creatorNameMap = {};
@@ -590,7 +615,7 @@ const candidateSearch = {
                 createTime: row?.create_time || null,
             };
         });
-        return ehrSuccess('ehr.recruit.candidate.search', { total, rows: dataRows });
+        return ehrSuccess('ehr.recruit.candidate.search', { total, totalExact, ...(totalNote ? { totalNote } : {}), rows: dataRows });
     },
 };
 const candidateList = {
@@ -632,7 +657,7 @@ const candidateList = {
             current: toPositiveInt(args.current, 'current') ?? 1,
             pageSize: toNumber(args.pageSize, 'pageSize') ?? 10,
         });
-        const { rows, displayRows, total } = await fetchListRows(env.host, formObjId, listParam.listId, body);
+        const { rows, displayRows, total, totalExact, totalNote } = await fetchListRows(env.host, formObjId, listParam.listId, body);
         const outRows = rows.map((row) => {
             const cleaned = { form_data_id: row?.form_data_id || row?.id };
             for (const [key, value] of Object.entries(row || {})) {
@@ -669,7 +694,7 @@ const candidateList = {
             return cleaned;
         });
         return ehrSuccess('ehr.recruit.candidate.list', {
-            type, total, current: body.current, pageSize: body.pageSize, rows: outRows,
+            type, total, totalExact, ...(totalNote ? { totalNote } : {}), current: body.current, pageSize: body.pageSize, rows: outRows,
         });
     },
 };

package/dist/shortcuts/ehr/operations/registry.js

@@ -6,6 +6,9 @@ import { hrDataSourceOperations } from './hr-ds.js';
 import { hrReportOperations } from './hr-report.js';
 import { recruitOperations } from './recruit.js';
 import { recruitWriteOperations } from './recruit-write.js';
+import { recruitStatsOperations } from './recruit-stats.js';
+import { recruitPositionOperations } from './recruit-position.js';
+import { recruitCandidateImportOperations } from './recruit-candidate-import.js';
 import { salaryOperations } from './salary.js';
 function buildRegistry() {
     const registry = new Map();
@@ -18,6 +21,9 @@ function buildRegistry() {
         ...hrReportOperations,
         ...recruitOperations,
         ...recruitWriteOperations,
+        ...recruitStatsOperations,
+        ...recruitPositionOperations,
+        ...recruitCandidateImportOperations,
     ];
     for (const definition of definitions) {
         if (registry.has(definition.name)) {

package/dist/shortcuts/im/diagnostics.js

@@ -0,0 +1,97 @@
+/**
+ * 易秒办（im）域内的诊断能力：**只动本模块目录，不改公共 core/cmd/internal**。
+ *
+ * 两个能力都通过公共已有的扩展点实现：
+ * - 失败信封双写：`im` 自己的 catch 分支里写 stdout + stderr，不扩 `Output` 类；
+ * - 请求级追踪：走 `HookManager.registerE10RequestInterceptor()`，不碰 `E10RequestRuntime`。
+ */
+const TRACE_ENV = 'WEAVER_WORK_CLI_TRACE';
+/** 同一进程内只注册一次拦截器（`forCommand()` 复用同一个 HookManager 实例）。 */
+const registeredHooks = new WeakSet();
+function truthy(value) {
+    const raw = String(value ?? '').toLowerCase();
+    return raw === '1' || raw === 'true' || raw === 'yes';
+}
+/** 从当前命令向上找 `im --trace`：命令级开关，不占用全局选项槽位。 */
+function traceFromCommand(ctx) {
+    let current = ctx.activeCommand;
+    for (let depth = 0; current && depth <= 3; depth += 1) {
+        const opts = typeof current.opts === 'function' ? current.opts() : undefined;
+        if (opts?.trace === true)
+            return true;
+        current = current.parent ?? undefined;
+    }
+    return false;
+}
+export function imTraceEnabled(ctx) {
+    if (truthy(ctx.env?.[TRACE_ENV]) || truthy(process.env[TRACE_ENV]))
+        return true;
+    try {
+        return traceFromCommand(ctx);
+    }
+    catch {
+        // 单测里的 ctx 可能是最小 mock：追踪开关不得影响请求本身
+        return false;
+    }
+}
+/** 按 path 记录在途请求的起始时间；同 path 并发时按 FIFO 配对。 */
+const inflight = new Map();
+function remember(path) {
+    const list = inflight.get(path) ?? [];
+    list.push(Date.now());
+    inflight.set(path, list);
+}
+function forget(path) {
+    const list = inflight.get(path);
+    if (!list?.length)
+        return undefined;
+    const startedAt = list.shift();
+    if (!list.length)
+        inflight.delete(path);
+    return startedAt;
+}
+function label(request) {
+    const operation = request.operation || '-';
+    return `${request.method} ${request.path} op=${operation}`;
+}
+function traceInterceptor() {
+    return {
+        beforeRequest({ request }) {
+            remember(request.path);
+        },
+        afterResponse({ request, response }) {
+            const startedAt = forget(request.path);
+            const ms = startedAt === undefined ? '-' : `${Date.now() - startedAt}ms`;
+            process.stderr.write(`[trace] ${label(request)} status=${response.status} ${ms}\n`);
+        },
+        onError({ request, error }) {
+            const startedAt = forget(request.path);
+            const ms = startedAt === undefined ? '-' : `${Date.now() - startedAt}ms`;
+            const code = error?.subtype
+                || error?.code
+                || 'unknown';
+            // 只打方法/路径/operation/错误码/耗时，绝不打印请求头与请求体（可能含凭证）
+            process.stderr.write(`[trace] ${label(request)} status=ERR code=${code} ${ms}\n`);
+        },
+    };
+}
+/** 按需注册追踪拦截器：未开启 trace 时完全零开销。 */
+export function registerImTrace(ctx) {
+    if (!imTraceEnabled(ctx))
+        return;
+    const hooks = ctx.hooks;
+    if (!hooks || registeredHooks.has(hooks))
+        return;
+    registeredHooks.add(hooks);
+    ctx.hooks.registerE10RequestInterceptor(traceInterceptor());
+}
+/**
+ * 失败信封：**stdout 与 stderr 各写一份**（内容相同）。
+ * stdout 是主通道 —— 只读 stdout 的调用方也能拿到结构化错误；
+ * stderr 保留一份，兼容「stderr 有内容 = 失败」的历史判断。
+ */
+export function printImFailure(envelope) {
+    const text = `${JSON.stringify(envelope, null, 2)}\n`;
+    process.stdout.write(text);
+    process.stderr.write(text);
+}

package/dist/shortcuts/im/host.js

@@ -94,6 +94,7 @@ export function createImHost(ctx, dependencies = {}) {
         return createE10RequestRuntime(ctx, await ensureSession(), {
             interceptors: dependencies.interceptors,
             fetch: dependencies.fetch,
+            recoverAuthentication: dependencies.recoverAuthentication,
         });
     }
     async function request(request) {
@@ -144,41 +145,53 @@ export function createImHost(ctx, dependencies = {}) {
     }
     async function requestBinary(url, headers = {}) {
         const session = await ensureSession();
-        const controller = new AbortController();
-        const timer = setTimeout(() => controller.abort(), 60_000);
+        const baseUrl = new URL(session.getBaseUrl());
+        let target;
         try {
-            const resp = await (dependencies.fetch || globalThis.fetch)(url, {
-                headers: {
-                    accept: 'application/json, text/plain, */*',
-                    cookie: session.cookieHeader(),
-                    eteamsid: session.eteamsId,
-                    'user-agent': session.uaHeader(),
-                    origin: session.getBaseUrl(),
-                    ...headers,
-                },
-                redirect: 'manual',
-                signal: controller.signal,
+            target = new URL(url, baseUrl);
+        }
+        catch {
+            throw imValidationError('download_url_invalid', '下载地址不是合法 URL');
+        }
+        if (target.origin !== baseUrl.origin) {
+            throw imValidationError('download_url_cross_origin', '下载地址不允许跨 E10 环境');
+        }
+        assertPath(target.pathname);
+        const query = {};
+        for (const [key, value] of target.searchParams) {
+            const previous = query[key];
+            if (previous === undefined)
+                query[key] = value;
+            else if (Array.isArray(previous))
+                previous.push(value);
+            else
+                query[key] = [previous, value];
+        }
+        let response;
+        try {
+            response = await (await runtime()).requestBinary({
+                module: 'im',
+                operation: 'im.file.download',
+                method: 'GET',
+                path: target.pathname,
+                query,
+                headers,
+                timeoutMs: 60_000,
             });
-            if (resp.status === 401 || resp.status === 302) {
-                throw imAuthError('session_expired', E10_SESSION_EXPIRED_MESSAGE);
-            }
-            if (resp.status !== 200) {
-                throw new ImCliError('api', 'download_failed', `下载失败 HTTP ${resp.status}`, {
-                    code: resp.status,
-                    exitCode: 1,
-                });
-            }
-            return Buffer.from(await resp.arrayBuffer());
         }
         catch (error) {
-            if (error instanceof ImCliError)
-                throw error;
-            const message = error instanceof Error ? error.message : String(error);
-            throw imNetworkError('transport', `下载失败：${message}`, { retryable: true });
+            mapRuntimeNetworkError(error);
+        }
+        if (response.status === 401 || response.status === 302) {
+            throw imAuthError('session_expired', E10_SESSION_EXPIRED_MESSAGE);
         }
-        finally {
-            clearTimeout(timer);
+        if (response.status !== 200) {
+            throw new ImCliError('api', 'download_failed', `下载失败 HTTP ${response.status}`, {
+                code: response.status,
+                exitCode: 1,
+            });
         }
+        return response.content;
     }
     /** teamsCheck：解析当前登录人的 imUid/imCid/name（IM uid 语义 = 员工 id）。 */
     async function getSelfIdentity() {
@@ -248,11 +261,25 @@ export function createImHost(ctx, dependencies = {}) {
             timeoutMs: 15_000,
         });
         const preData = preRes?.data || {};
+        /**
+         * 秒传分支：服务端按 MD5 命中已有文件时**不再返回 preUploadId**，而是直接给出 fileObj
+         * （`uploadType: "second"`）。实测两种结构：
+         *   { uploadType: 'second', fileObj: {...} }
+         *   { uploadType: 'second', imUploadInfoDto: { uploadType: 'second', fileObj: {...}, transcode: {...} } }
+         * 旧实现只认 preUploadId，导致「同一张图/同一个文件第二次发送」必定失败（upload_check_failed，
+         * 但响应本身是 code:200 status:true）。命中秒传时直接复用 fileObj，跳过 valid/upload。
+         */
+        const preInfo = preData.imUploadInfoDto || preData;
+        const preFileObj = preInfo?.fileObj && (preInfo.fileObj.id || preInfo.fileObj.fileid) ? preInfo.fileObj : null;
+        const preUploadType = String(preData.uploadType || preInfo?.uploadType || '');
+        if (preFileObj && (!preData.preUploadId || preUploadType === 'second')) {
+            return preFileObj;
+        }
         if (!preData.preUploadId) {
-            throw new ImCliError('api', 'upload_check_failed', `preUploadCheck 失败`, { details: preRes, exitCode: 1 });
+            throw new ImCliError('api', 'upload_check_failed', `preUploadCheck 失败（未返回 preUploadId，也没有可复用的秒传 fileObj）`, { details: preRes, exitCode: 1 });
         }
         const preUploadId = String(preData.preUploadId);
-        const uploadType = preData.uploadType || 'common';
+        const uploadType = preUploadType || 'common';
         // 第 2 步：实传
         const upForm = new FormData();
         upForm.append('data', new Blob([data], { type: mime }), name);

package/dist/shortcuts/im/index.js

@@ -1,6 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { ExitCode, isCliError, toErrorEnvelope } from '../../core/errors.js';
 import { createImContinuationSigner } from './continuation.js';
+import { printImFailure, registerImTrace } from './diagnostics.js';
 import { imValidationError } from './errors.js';
 import { createImHost } from './host.js';
 import { imManifest } from './manifest.js';
@@ -81,6 +82,8 @@ function failureEnvelope(error) {
     };
 }
 async function executeAndPrint(ctx, operation, input) {
+    // 排障/接口计数：`im --trace` 或 WEAVER_WORK_CLI_TRACE=1（实现完全在 im 域内，不改公共 runtime）
+    registerImTrace(ctx);
     try {
         const result = await executeImOperation(operation, input, {
             ctx,
@@ -90,7 +93,7 @@ async function executeAndPrint(ctx, operation, input) {
         ctx.output.write(successEnvelope(operation, result), { json: true });
     }
     catch (error) {
-        console.error(JSON.stringify(failureEnvelope(error), null, 2));
+        printImFailure(failureEnvelope(error));
         process.exitCode = isCliError(error) ? error.exitCode : ExitCode.GeneralError;
     }
 }
@@ -110,7 +113,9 @@ export const imShortcut = {
     description: '泛微E10易秒办（即时通讯）CLI',
     category: 'shortcut',
     register({ program, action }) {
-        const im = program.command('im').description('泛微E10易秒办：消息/群组/会话/系统消息');
+        const im = program.command('im')
+            .description('泛微E10易秒办：消息/群组/会话/系统消息')
+            .option('--trace', '每个 E10 请求在 stderr 打一行 [trace]（method/path/op/status/耗时，不含凭证）');
         im.command('schema')
             .description('Print im operation manifest for agents')
             .action(action((ctx) => {

package/dist/shortcuts/im/operations/at-mention.js

@@ -0,0 +1,127 @@
+import { imValidationError } from '../errors.js';
+import { extractGroupMembers, isSystemMember, str, unwrapInner } from './shared.js';
+/**
+ * 群聊 @ 提及（@所有人 / @具体人）。
+ *
+ * 服务端契约（2026-10-29 实测 yunteams，群 1793244595701000005）：
+ * - 只能通过 `sendGroupMsg` 的 **`msg` 字段**（完整原生 msg JSON 字符串）携带 @；
+ *   `txt` 字段传 JSON 字符串会被服务端原样塞进 `dt[0].txt.v`，客户端直接显示 JSON 原文（踩坑确认）。
+ * - 原生结构：`{ bgc:'', cnt:'0', dev:5, display:'', dt:[{txt:{aus, ft:'china', next:'0', v}}],
+ *   guid:'0', idx:'0', opb:['received','reply'], scid, sname, suid, sysId:'', type:'1', ver:'1.0', weaOaId:'' }`
+ * - `txt.aus` 条目：@具体人 `{ cid:<人cid>, fd:'@', id:<人uid>, nm:<姓名>, t:'1' }`；
+ *   @所有人固定 `{ cid:'10000', fd:'@', id:'88', nm:'全体成员', t:'2' }`。
+ * - `txt.v` 中每个 @ 位置写占位符 `:@<id>;`（冒号+@+id+分号），其余文本原样保留；
+ *   客户端渲染时用 aus 把占位符还原为 `@<nm>`。
+ */
+/** @全体成员 的服务端固定条目。 */
+export const AT_ALL_ENTRY = { cid: '10000', fd: '@', id: '88', nm: '全体成员', t: '2' };
+function truthy(value) {
+    return value === true || value === 'true' || value === '1';
+}
+function uidList(value) {
+    if (value === undefined || value === null || value === '')
+        return [];
+    const raw = Array.isArray(value)
+        ? value.map((x) => str(x))
+        : String(value).split(/[,，;；\s]+/);
+    return raw.map((x) => x.trim()).filter((x) => x && x !== '0');
+}
+/** 调用方是否带了任何 @ 入参（含显式无效值，用于单聊报错）。 */
+export function hasAtInput(args) {
+    return args.atAll !== undefined || args.atUids !== undefined;
+}
+/**
+ * 解析 @ 入参为 aus 条目列表。
+ * @具体人必须逐个核实已在目标群（getGroupUsers，member_mask=6 只取 uid+cid），
+ * 不在群内直接拒绝（错误码 at_member_not_in_group）；姓名一律走 hrm 解析（不用 IM 返回的 name）。
+ */
+export async function resolveAtMentions(args, env, groupId) {
+    const atAll = truthy(args.atAll);
+    const atUids = uidList(args.atUids);
+    if (!atAll && !atUids.length)
+        return [];
+    const entries = [];
+    if (atAll)
+        entries.push({ ...AT_ALL_ENTRY });
+    if (atUids.length) {
+        let members = [];
+        try {
+            const res = await env.host.request({
+                method: 'POST',
+                path: '/api/em/msg/executeIm/group/getGroupUsers',
+                body: { group_id: groupId, type: 0, sync_type: 0, member_mask: 6, client_uc: '0' },
+                operation: 'im.msg.send.group.atMembers',
+            });
+            members = extractGroupMembers(unwrapInner(res));
+        }
+        catch (error) {
+            throw imValidationError('at_members_unavailable', `无法核实 @ 目标是否在群内：拉取群成员失败（${error instanceof Error ? error.message : String(error)}）`, { groupId, atUids });
+        }
+        const inGroup = new Map();
+        for (const m of members) {
+            if (isSystemMember(m))
+                continue;
+            inGroup.set(str(m.uid), str(m.cid));
+        }
+        const missing = atUids.filter((uid) => !inGroup.has(uid));
+        if (missing.length) {
+            throw imValidationError('at_member_not_in_group', `以下 @ 目标不在群 ${groupId} 内，已拒绝发送：${missing.join(', ')}`, { groupId, missing, atUids });
+        }
+        const personMap = await env.host.resolveUsersByIds([...new Set(atUids)]);
+        for (const uid of atUids) {
+            entries.push({ cid: inGroup.get(uid) || '', fd: '@', id: uid, nm: personMap[uid]?.name || uid, t: '1' });
+        }
+    }
+    return entries;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * 把 @ 入参落进文本：文本中出现的 `@<姓名>`（@全体成员兼认 `@所有人`）替换为 `:@<id>;` 占位符；
+ * 未在文本中出现的提及按传入顺序前置（`:@<id>;` 两空格分隔，仿客户端格式）。
+ * 返回原生 txt 需要的 `v`（占位文本）与 `aus`（按 v 中出现顺序）。
+ */
+export function buildAtText(text, entries) {
+    let v = String(text ?? '');
+    const used = new Set();
+    for (const entry of entries) {
+        const names = entry.t === '2' ? ['全体成员', '所有人'] : [entry.nm];
+        for (const nm of names) {
+            const re = new RegExp(`@${escapeRegExp(nm)}`, 'g');
+            if (!re.test(v))
+                continue;
+            v = v.replace(re, () => `:@${entry.id};`);
+            used.add(entry);
+            break;
+        }
+    }
+    const rest = entries.filter((e) => !used.has(e));
+    if (rest.length) {
+        const prefix = rest.map((e) => `:@${e.id};`).join('  ');
+        v = v.trim() ? `${prefix}  ${v}` : prefix;
+    }
+    const aus = [...used, ...rest];
+    return { v, aus };
+}
+/** 组装 sendGroupMsg 的 `msg` 字段值（完整原生 msg JSON 字符串）。 */
+export function buildAtMsgJson(v, aus, self, extra = {}) {
+    return JSON.stringify({
+        bgc: '',
+        cnt: '0',
+        dev: 5,
+        display: '',
+        dt: [{ txt: { aus, ft: 'china', next: '0', v } }],
+        guid: '0',
+        idx: '0',
+        opb: ['received', 'reply'],
+        scid: self.cid,
+        sname: self.name,
+        suid: self.uid,
+        sysId: '',
+        type: '1',
+        ver: '1.0',
+        weaOaId: '',
+        ...extra,
+    });
+}

package/dist/shortcuts/im/operations/file-user.js

@@ -72,7 +72,11 @@ const filePreview = {
         toUid: { type: 'string', description: '单聊场景对方 uid' },
         toCid: { type: 'string', description: '单聊场景对方 cid' },
         imgFormat: { type: 'string', enum: ['small', 'large', 'original'], description: '图片规格（默认 small）' },
-    }, { required: ['fileId', 'msgid'], description: '媒体预览 URL' }),
+    }, {
+        required: ['fileId', 'msgid'],
+        anyOf: [{ required: ['groupId'] }, { required: ['toUid', 'toCid'] }],
+        description: '媒体预览 URL（groupId 群聊 或 toUid+toCid 单聊，二选一）',
+    }),
     handler: async (args, { host }) => {
         const kind = String(args.kind ?? 'img') === 'video' ? 'video' : 'img';
         const fileId = String(args.fileId);
@@ -137,7 +141,11 @@ const fileDownload = {
         toCid: { type: 'string', description: '单聊场景对方 cid（与 groupId 二选一）' },
         imgFormat: { type: 'string', enum: ['small', 'large', 'original'], description: '图片规格（默认 small；要原图传 original）' },
         output: { type: 'string', minLength: 1, description: '本地输出文件路径（父目录必须存在，已存在则拒绝）' },
-    }, { required: ['fileId', 'msgid', 'output'], description: '媒体/文件落地到本地' }),
+    }, {
+        required: ['fileId', 'msgid', 'output'],
+        anyOf: [{ required: ['groupId'] }, { required: ['toUid', 'toCid'] }],
+        description: '媒体/文件落地到本地（groupId 群聊 或 toUid+toCid 单聊，二选一）',
+    }),
     handler: async (args, { host }) => {
         const fileId = String(args.fileId ?? '');
         const msgid = String(args.msgid ?? '');

package/dist/shortcuts/im/operations/group-read.js

@@ -1,6 +1,6 @@
 import { imValidationError } from '../errors.js';
 import { READ, schemaOf, imSuccess, } from './types.js';
-import { assertImOk, compact, extractGroupMembers, formatFullTime, splitIds, str, toPositiveInt, toUint, unwrapInner, } from './shared.js';
+import { assertImOk, compact, extractGroupMembers, formatFullTime, isSystemMember, splitIds, str, toPositiveInt, toUint, unwrapInner, } from './shared.js';
 const SEARCH_TYPE_MASK = {
     type: 1,
     key: 2,
@@ -153,7 +153,7 @@ const groupInfo = {
     inputSchema: schemaOf({
         groupIds: { type: 'array', items: { type: 'string' }, description: '群 id 列表（逗号串或数组）' },
         groupId: { type: 'string', description: '单群 id（groupIds 的便捷形式）' },
-    }, { description: 'groupIds / groupId 至少其一' }),
+    }, { requiredAny: ['groupIds', 'groupId'], description: '按群 id 查基础信息（groupIds / groupId 至少其一）' }),
     handler: async (args, { host }) => {
         let ids = [];
         if (Array.isArray(args.groupIds))
@@ -186,12 +186,23 @@ const groupInfo = {
             maskName: maskTypeName(Number(g.mask ?? 0)),
             userNum: g.user_num,
             maxNum: g.max_num,
-            hostUid: str(g.host_uid ?? g.hostUid ?? ''),
+            /** 群创建者 uid（服务端字段 host_uid）；**不是群主**，群主以 group.users 的 role=3 为准。 */
+            creatorUid: str(g.host_uid ?? g.hostUid ?? ''),
+            /** 群创建者 cid（服务端字段 host_cid），与 creatorUid 配对。 */
+            creatorCid: str(g.host_cid ?? g.hostCid ?? ''),
             state: Number(g.state ?? -1),
             stateName: stateName(Number(g.state ?? -1)),
             createTime: formatFullTime(g.create_time ?? g.createTime),
         }));
-        return imSuccess('im.group.info', { total: groups.length, groups });
+        return imSuccess('im.group.info', {
+            total: groups.length,
+            groups,
+            fieldNotes: {
+                creatorUid: '群创建者（host_uid），不是群主；创建后转让群主也不会变。',
+                creatorCid: '群创建者 cid（host_cid）。',
+                owner: '群主请用 im.group.users 的 role=3（或 im.group.admins）获取，不要用 creatorUid 判断。',
+            },
+        });
     },
 };
 /** 群成员列表。 */
@@ -233,7 +244,11 @@ const groupUsers = {
         const hasCid = (memberMask & 2) !== 0;
         const hasUid = (memberMask & 4) !== 0;
         const roleNames = { 0: '不可用', 1: '普通成员', 2: '管理员', 3: '群主', 4: '客户', 5: '负责人', 6: '协助人员' };
-        const personIds = members.map((m) => String(m?.uid ?? '')).filter((x) => x && x !== '0');
+        // 系统成员没有 hrm 资料，不必进解析批次（省一次无效 id，也避免被当成「解析失败」）
+        const personIds = members
+            .filter((m) => !isSystemMember(m))
+            .map((m) => String(m?.uid ?? ''))
+            .filter((x) => x && x !== '0');
         // 姓名一律走 hrm 解析（不看 member_mask 的 name 位，也不使用 IM 返回的 name 字段）
         const personMap = personIds.length ? await host.resolveUsersByIds([...new Set(personIds)]) : {};
         const rows = members.map((m) => ({
@@ -243,10 +258,16 @@ const groupUsers = {
             role: hasRole ? Number(m.role_type ?? m.role ?? -1) : undefined,
             roleName: hasRole ? roleNames[Number(m.role_type ?? m.role ?? -1)] ?? '-' : undefined,
             addTime: hasAddTime ? formatFullTime(m.add_time ?? m.addTime) : undefined,
+            /** 服务端自动补入的系统成员（可选功能，不是真实员工），统计真实成员时排除。 */
+            isSystem: hasCid ? isSystemMember(m) : undefined,
         }));
+        const personRows = rows.filter((row) => row.isSystem !== true);
         return imSuccess('im.group.users', {
             groupId,
+            /** 成员总数（含系统成员，即服务端返回的原始条数） */
             totalNum: inner?.total_num ?? rows.length,
+            /** 真实成员数（排除系统成员 cid=10002），判断「只剩自己」请用这个 */
+            personNum: personRows.length,
             endFlag: inner?.end_flag,
             serverUc: str(inner?.server_uc ?? ''),
             members: rows,