weaver-work-cli 0.1.2 → 0.1.5

package/dist/shortcuts/yimiaoban/index.js

@@ -0,0 +1,271 @@
+import { readFile } from 'node:fs/promises';
+import { ExitCode, isCliError, toErrorEnvelope } from '../../core/errors.js';
+import { createYmbContinuationSigner } from './continuation.js';
+import { ymbValidationError } from './errors.js';
+import { createYmbHost } from './host.js';
+import { ymbManifest } from './manifest.js';
+import { executeYmbOperation } from './operations.js';
+function asOptions(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function stripBom(value) {
+    return value.replace(/^\uFEFF+/, '');
+}
+export async function inputFrom(options, extra = {}) {
+    const opts = asOptions(options);
+    let input = {};
+    if (opts.input && opts.inputJson) {
+        throw ymbValidationError('input_conflict', '不能同时传 --input 和 --input-json');
+    }
+    if (opts.inputJson) {
+        input = parseJsonInput(String(opts.inputJson), '--input-json');
+    }
+    if (opts.input) {
+        let raw;
+        try {
+            raw = stripBom(opts.input === '-' ? await readStdin() : await readFile(String(opts.input), 'utf8'));
+        }
+        catch {
+            throw ymbValidationError('input_unreadable', `无法读取 --input：${String(opts.input)}`);
+        }
+        input = parseJsonInput(raw, '--input');
+    }
+    return {
+        ...input,
+        ...Object.fromEntries(Object.entries(extra).filter(([, value]) => value !== undefined && value !== '')),
+    };
+}
+function parseJsonInput(raw, label) {
+    try {
+        const parsed = JSON.parse(stripBom(raw));
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            throw new Error('input must be an object');
+        }
+        return parsed;
+    }
+    catch {
+        throw ymbValidationError('input_invalid', `${label} 不是合法 JSON 对象`);
+    }
+}
+function withJsonInputOptions(command) {
+    command
+        .option('--input <path>', 'JSON input file, or - for stdin')
+        .option('--input-json <json>', 'inline JSON input object');
+    return command;
+}
+function successEnvelope(operation, result) {
+    return {
+        schemaVersion: 1,
+        ok: true,
+        operation,
+        // 业务数据为 undefined 时仍输出 data 键，避免调用方需额外判断键是否存在。
+        data: result.data === undefined ? null : result.data,
+        ...(result.meta && Object.keys(result.meta).length ? { meta: result.meta } : {}),
+        warnings: [],
+    };
+}
+function failureEnvelope(error) {
+    const structured = error;
+    return {
+        schemaVersion: 1,
+        ok: false,
+        ...(structured?.partialData === undefined ? {} : { data: structured.partialData }),
+        error: toErrorEnvelope(error),
+    };
+}
+async function executeAndPrint(ctx, operation, input) {
+    try {
+        const result = await executeYmbOperation(operation, input, {
+            ctx,
+            host: createYmbHost(ctx),
+            continuation: createYmbContinuationSigner(ctx),
+        });
+        ctx.output.write(successEnvelope(operation, result), { json: true });
+    }
+    catch (error) {
+        console.error(JSON.stringify(failureEnvelope(error), null, 2));
+        process.exitCode = isCliError(error) ? error.exitCode : ExitCode.GeneralError;
+    }
+}
+function boolOption(value) {
+    if (value === undefined || value === null || value === '')
+        return undefined;
+    return value === true || value === 'true' || value === '1';
+}
+/**
+ * 易秒办（即时通讯）CLI 命令注册。
+ * 所有操作统一走 `run <operation> --input-json '{}'`；便捷命令只覆盖高频只读场景，
+ * 写操作一律通过 `run ...prepare`（签发 continuation）→ `run ...apply --input-json '{"confirm":true,"continuation":"..."}'`
+ * 两段式执行，便捷层不绕过确认链。
+ */
+export const yimiaobanShortcut = {
+    name: 'yimiaoban',
+    description: '泛微E10易秒办（即时通讯）CLI',
+    category: 'shortcut',
+    register({ program, action }) {
+        const ymb = program.command('yimiaoban').description('泛微E10易秒办：消息/群组/会话/系统消息');
+        ymb.command('schema')
+            .description('Print yimiaoban operation manifest for agents')
+            .action(action((ctx) => {
+            ctx.output.write(ymbManifest, { json: true });
+        }));
+        withJsonInputOptions(ymb.command('run')
+            .description('Run a yimiaoban operation with JSON input')
+            .argument('<operation>', 'operation name, e.g. yimiaoban.msg.sync.group'))
+            .action(action(async (ctx, operation, options) => {
+            await executeAndPrint(ctx, String(operation), await inputFrom(options));
+        }));
+        // ---- 高频便捷命令：会话 ----
+        const session = ymb.command('session').description('Session commands');
+        withJsonInputOptions(session.command('list')
+            .description('拉取当前用户会话列表')
+            .option('--num <n>', '单页条数（默认 20，最多 50）')
+            .option('--msgid <id>', '锚点消息 id')
+            .option('--flag <0|1|2>', '0 up+down / 1 up / 2 down（默认 2）')
+            .option('--type <type>', '仅展示该 session_type'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.session.list', await inputFrom(options, {
+                num: opts.num !== undefined ? Number(opts.num) : undefined,
+                msgid: opts.msgid,
+                flag: opts.flag !== undefined ? Number(opts.flag) : undefined,
+                type: opts.type !== undefined ? Number(opts.type) : undefined,
+            }));
+        }));
+        // ---- 高频便捷命令：消息 ----
+        const msg = ymb.command('msg').description('Message commands');
+        withJsonInputOptions(msg.command('sync-single')
+            .description('拉取与某人的单聊消息')
+            .option('--from-uid <uid>', '对方 uid（必填）')
+            .option('--from-cid <cid>', '对方 cid（必填）')
+            .option('--num <n>', '单页数量（默认 20，最多 50）')
+            .option('--from <time>', '起始时间 YYYY-MM-DD[ HH:mm:ss] 或 unix 秒')
+            .option('--to <time>', '结束时间')
+            .option('--latest', '拉最新不限日期')
+            .option('--img-format <fmt>', 'small/large/original（默认 small）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.msg.sync.single', await inputFrom(options, {
+                fromUid: opts.fromUid,
+                fromCid: opts.fromCid,
+                num: opts.num !== undefined ? Number(opts.num) : undefined,
+                from: opts.from,
+                to: opts.to,
+                latest: boolOption(opts.latest),
+                imgFormat: opts.imgFormat,
+            }));
+        }));
+        withJsonInputOptions(msg.command('sync-group')
+            .description('拉取某群聊天消息')
+            .option('--gid <id>', '群 id（必填）')
+            .option('--num <n>', '单页数量（默认 20，最多 50）')
+            .option('--from <time>', '起始时间')
+            .option('--to <time>', '结束时间')
+            .option('--latest', '拉最新不限日期')
+            .option('--start-id <id>', '显式起始消息 id')
+            .option('--end-id <id>', '显式结束消息 id')
+            .option('--img-format <fmt>', 'small/large/original（默认 small）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.msg.sync.group', await inputFrom(options, {
+                groupId: opts.gid,
+                num: opts.num !== undefined ? Number(opts.num) : undefined,
+                from: opts.from,
+                to: opts.to,
+                latest: boolOption(opts.latest),
+                startId: opts.startId,
+                endId: opts.endId,
+                imgFormat: opts.imgFormat,
+            }));
+        }));
+        withJsonInputOptions(msg.command('top')
+            .description('同步群置顶消息')
+            .option('--gid <id>', '群 id（必填）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.msg.top.sync', await inputFrom(options, { groupId: opts.gid }));
+        }));
+        // ---- 高频便捷命令：群组 ----
+        const group = ymb.command('group').description('Group commands');
+        withJsonInputOptions(group.command('search')
+            .description('按条件搜索群（服务端过滤）')
+            .option('--name <kw>', '群名关键字')
+            .option('--precise', '精确匹配名称')
+            .option('--type <type>', '群类型（1 普通/6 部门/7 全员等）')
+            .option('--members', '我所在的群')
+            .option('--owner', '我是群主的群')
+            .option('--creator', '我创建的群')
+            .option('--page-size <n>', '每页大小（默认 100，最多 200）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.group.search', await inputFrom(options, {
+                name: opts.name,
+                precise: boolOption(opts.precise),
+                type: opts.type !== undefined ? Number(opts.type) : undefined,
+                members: boolOption(opts.members),
+                owner: boolOption(opts.owner),
+                creator: boolOption(opts.creator),
+                pageSize: opts.pageSize !== undefined ? Number(opts.pageSize) : undefined,
+            }));
+        }));
+        withJsonInputOptions(group.command('info')
+            .description('按群 id 查基础信息（支持批量，逗号分隔）')
+            .option('--gid <ids>', '群 id（逗号分隔或单值）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.group.info', await inputFrom(options, { groupIds: opts.gid }));
+        }));
+        withJsonInputOptions(group.command('users')
+            .description('拉取群成员列表')
+            .option('--gid <id>', '群 id（必填）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.group.users', await inputFrom(options, { groupId: opts.gid }));
+        }));
+        // ---- 高频便捷命令：人员解析 ----
+        withJsonInputOptions(ymb.command('resolve')
+            .description('按姓名/工号/手机/邮箱模糊查询在职员工')
+            .option('--name <kw>', '查询关键字（必填）'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.person.resolve', await inputFrom(options, { name: opts.name }));
+        }));
+        // ---- 高频便捷命令：发消息（两段式，仅演示 prepare 链） ----
+        const send = ymb.command('send').description('Send message commands (two-phase prepare -> apply)');
+        withJsonInputOptions(send.command('single-prepare')
+            .description('准备发送单聊消息（只读校验并签发 continuation）')
+            .option('--to-uid <uid>', '接收人 uid（必填）')
+            .option('--to-cid <cid>', '接收人 cid（必填）')
+            .option('--txt <text>', '文本内容')
+            .option('--img <path>', '本地图片路径')
+            .option('--file <path>', '本地文件路径'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.msg.send.single.prepare', await inputFrom(options, {
+                toUid: opts.toUid,
+                toCid: opts.toCid,
+                txt: opts.txt,
+                img: opts.img,
+                file: opts.file,
+            }));
+        }));
+        withJsonInputOptions(send.command('single-apply')
+            .description('执行发送单聊消息（需 --yes 与 continuation）')
+            .option('--continuation <token>', 'continuation token from send single-prepare')
+            .option('--yes', 'confirm the write operation'))
+            .action(action(async (ctx, options) => {
+            const opts = asOptions(options);
+            await executeAndPrint(ctx, 'yimiaoban.msg.send.single.apply', await inputFrom(options, {
+                continuation: opts.continuation,
+                confirm: opts.yes === true ? true : undefined,
+            }));
+        }));
+    },
+};

package/dist/shortcuts/yimiaoban/manifest.js

@@ -0,0 +1,28 @@
+import { ymbOperationDefinitions } from './operations/registry.js';
+function buildOperations() {
+    return ymbOperationDefinitions().map((definition) => ({
+        name: definition.name,
+        resource: definition.resource,
+        summary: definition.summary,
+        ...(definition.capability ? { capability: definition.capability } : {}),
+        risk: definition.risk,
+        ...(definition.requiresConfirmation ? { requiresConfirmation: true } : {}),
+        inputSchema: definition.inputSchema,
+    }));
+}
+/**
+ * 易秒办（即时通讯）模块 manifest。
+ * operations 清单直接来自 registry（含全部 prepare/apply 成对写操作），
+ * 供 `weaver-work-cli yimiaoban schema` 输出给 Agent/Skill 使用。
+ */
+export const ymbManifest = {
+    schemaVersion: 1,
+    name: 'yimiaoban',
+    title: '泛微E10易秒办（即时通讯：消息/群组/会话/系统消息）',
+    version: '0.1.0',
+    host: 'e10-yimiaoban',
+    status: 'builtin',
+    sourceSkill: 'weaver-e10-yimiaoban',
+    capabilities: ['person', 'msg', 'ding', 'group', 'session', 'sysmsg', 'file', 'user', 'i18n'],
+    operations: buildOperations(),
+};

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

@@ -0,0 +1,288 @@
+import { existsSync } from 'node:fs';
+import { rename, stat, writeFile } from 'node:fs/promises';
+import { dirname, extname, resolve } from 'node:path';
+import { ymbValidationError } from '../errors.js';
+import { READ, schemaOf, ymbSuccess, } from './types.js';
+import { assertImOk, compact, splitIds, str, toUint, unwrapInner } from './shared.js';
+import { fileObjToFile, fileObjToImg } from './write-util.js';
+/** 文件上传（两段式，module=im），返回 fileObj + 消息对象两种形态。 */
+const fileUpload = {
+    name: 'yimiaoban.file.upload',
+    resource: 'file',
+    method: 'file.upload',
+    action: 'yimiaoban.file.upload',
+    summary: '上传本地文件到 E10 文件服务（module=im），返回文件 id（供消息 img/file 引用）',
+    capability: 'file',
+    risk: 'external-artifact',
+    inputSchema: schemaOf({
+        file: { type: 'string', description: '本地文件路径（必填，兼容旧名 filePath）' },
+        name: { type: 'string', description: '文件名（默认取 basename）' },
+        shareGroup: { type: 'string', description: '分享群 id（发群消息用；兼容 shareGroups 逗号串）' },
+        shareUsers: { type: 'array', items: { type: 'string' }, description: '分享用户 uid（发单聊用）' },
+        permission: { type: 'string', description: '文件权限（默认 3）' },
+    }, { required: ['file'], description: '文件上传' }),
+    handler: async (args, { host }) => {
+        const filePath = String(args.file ?? args.filePath ?? '');
+        if (!filePath)
+            throw ymbValidationError('file_required', 'file 必填');
+        const abs = resolve(filePath);
+        if (!existsSync(abs))
+            throw ymbValidationError('file_not_found', `文件不存在: ${abs}`);
+        const shareUsers = Array.isArray(args.shareUsers) ? args.shareUsers.join(',') : String(args.shareUsers ?? '');
+        const shareGroups = args.shareGroup ?? args.shareGroups;
+        const fileObj = await host.uploadFile(abs, {
+            name: args.name !== undefined ? String(args.name) : undefined,
+            shareGroups: shareGroups !== undefined && shareGroups !== '' ? String(shareGroups) : undefined,
+            shareUsers: shareUsers || undefined,
+            permission: args.permission !== undefined ? String(args.permission) : undefined,
+        });
+        return ymbSuccess('yimiaoban.file.upload', {
+            fileObj,
+            img: fileObjToImg(fileObj),
+            file: fileObjToFile(fileObj),
+        });
+    },
+};
+/** 媒体预览（img/video）URL 构造 + 可选下载。 */
+const filePreview = {
+    name: 'yimiaoban.file.preview',
+    resource: 'file',
+    method: 'file.preview',
+    action: 'yimiaoban.file.preview',
+    summary: '生成图片/视频预览与下载 URL（需登录态访问；图片支持 small/large/original）',
+    capability: 'file',
+    risk: READ,
+    inputSchema: schemaOf({
+        kind: { type: 'string', enum: ['img', 'video'], description: 'img（默认）/ video' },
+        fileId: { type: 'string', minLength: 1, description: '文件 id' },
+        msgid: { type: 'string', pattern: '^\\d+$', description: '消息 id' },
+        groupId: { type: 'string', description: '群聊场景群 id' },
+        toUid: { type: 'string', description: '单聊场景对方 uid' },
+        toCid: { type: 'string', description: '单聊场景对方 cid' },
+        imgFormat: { type: 'string', enum: ['small', 'large', 'original'], description: '图片规格（默认 small）' },
+    }, { required: ['fileId', 'msgid'], description: '媒体预览 URL' }),
+    handler: async (args, { host }) => {
+        const kind = String(args.kind ?? 'img') === 'video' ? 'video' : 'img';
+        const fileId = String(args.fileId);
+        const msgid = String(args.msgid);
+        const groupId = args.groupId !== undefined && args.groupId !== '' ? String(args.groupId) : undefined;
+        const user = args.toUid || args.toCid ? { cid: str(args.toCid), uid: str(args.toUid) } : undefined;
+        if (!groupId && !user) {
+            throw ymbValidationError('context_required', 'groupId（群聊）或 toUid+toCid（单聊）必须提供其一');
+        }
+        const opts = {
+            fileId,
+            msgid,
+            kind: kind,
+            imgFormat: (args.imgFormat || 'small'),
+            ...(groupId ? { groupId } : {}),
+            ...(user ? { user } : {}),
+        };
+        return ymbSuccess('yimiaoban.file.preview', {
+            kind,
+            fileId,
+            previewUrl: await host.buildPreviewUrl(opts),
+            downloadUrl: await host.buildDownloadUrl(opts),
+            note: '预览/下载 URL 需要登录态（Cookie+eteamsid），直接嵌入 Markdown 会 401；需要真正可见请用 yimiaoban.file.download 落地到本地。',
+        });
+    },
+};
+/** 图片文件头签名（用于纠正扩展名：预览小图服务端会统一转 PNG）。 */
+const IMAGE_SIGNATURES = [
+    { ext: '.png', test: (b) => b.length >= 4 && b.subarray(0, 4).toString('hex') === '89504e47' },
+    { ext: '.jpg', test: (b) => b.length >= 3 && b.subarray(0, 3).toString('hex') === 'ffd8ff' },
+    { ext: '.gif', test: (b) => b.length >= 4 && b.subarray(0, 4).toString('hex') === '47494638' },
+    {
+        ext: '.webp',
+        test: (b) => b.length >= 12
+            && b.subarray(0, 4).toString('ascii') === 'RIFF'
+            && b.subarray(8, 12).toString('ascii') === 'WEBP',
+    },
+];
+/** 按文件头识别图片真实格式；不是已知图片格式时返回 null。 */
+function detectImageExt(buffer) {
+    for (const signature of IMAGE_SIGNATURES) {
+        if (signature.test(buffer))
+            return signature.ext;
+    }
+    return null;
+}
+/** 消息媒体/文件落地到本地（需登录态；父目录必须存在，禁止覆盖已存在文件）。 */
+const fileDownload = {
+    name: 'yimiaoban.file.download',
+    resource: 'file',
+    method: 'file.download',
+    action: 'yimiaoban.file.download',
+    summary: '下载消息里的图片/视频/文件到本地（需登录态；父目录必须存在，禁止覆盖）',
+    capability: 'file',
+    risk: 'local-file-write',
+    inputSchema: schemaOf({
+        fileId: { type: 'string', minLength: 1, description: '文件 id（取消息 media[].fileId）' },
+        msgid: { type: 'string', pattern: '^\\d+$', description: '消息 id（取消息 media[].msgid / msgid）' },
+        kind: { type: 'string', enum: ['img', 'video', 'file'], description: '媒体类型（默认 img；文件消息传 file）' },
+        groupId: { type: 'string', description: '群聊场景群 id（与单聊身份二选一）' },
+        toUid: { type: 'string', description: '单聊场景对方 uid（与 groupId 二选一）' },
+        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: '媒体/文件落地到本地' }),
+    handler: async (args, { host }) => {
+        const fileId = String(args.fileId ?? '');
+        const msgid = String(args.msgid ?? '');
+        const kindRaw = String(args.kind ?? 'img');
+        const kind = kindRaw === 'video' ? 'video' : 'img';
+        const output = String(args.output ?? '').trim();
+        if (!output)
+            throw ymbValidationError('output_required', 'output 必须是明确的本地文件路径');
+        const groupId = args.groupId !== undefined && args.groupId !== '' ? String(args.groupId) : undefined;
+        const user = args.toUid || args.toCid ? { cid: str(args.toCid), uid: str(args.toUid) } : undefined;
+        if (!groupId && !user) {
+            throw ymbValidationError('context_required', 'groupId（群聊）或 toUid+toCid（单聊）必须提供其一');
+        }
+        const resolved = resolve(output);
+        const parent = await stat(dirname(resolved)).catch(() => null);
+        if (!parent)
+            throw ymbValidationError('output_parent_missing', `输出目录不存在：${dirname(resolved)}`);
+        if (!parent.isDirectory())
+            throw ymbValidationError('output_parent_invalid', '输出文件的父路径不是目录');
+        if (existsSync(resolved))
+            throw ymbValidationError('output_exists', `输出文件已存在，拒绝覆盖：${resolved}`);
+        const url = await host.buildDownloadUrl({
+            fileId,
+            msgid,
+            kind: kind,
+            imgFormat: (args.imgFormat || 'small'),
+            ...(groupId ? { groupId } : {}),
+            ...(user ? { user } : {}),
+        });
+        const content = await host.requestBinary(url);
+        await writeFile(resolved, content, { flag: 'wx', mode: 0o600 });
+        // 图片（含以 file 形态下载的图片）：按文件头纠正扩展名，避免「.jpg 里其实是 PNG」
+        let finalPath = resolved;
+        let renamedFrom;
+        if (kind === 'img' || kindRaw === 'file') {
+            const detected = detectImageExt(content);
+            const currentExt = extname(resolved).toLowerCase();
+            if (detected && detected !== currentExt) {
+                const candidate = currentExt
+                    ? `${resolved.slice(0, resolved.length - currentExt.length)}${detected}`
+                    : `${resolved}${detected}`;
+                if (!existsSync(candidate)) {
+                    await rename(resolved, candidate);
+                    renamedFrom = resolved;
+                    finalPath = candidate;
+                }
+            }
+        }
+        return ymbSuccess('yimiaoban.file.download', {
+            fileId,
+            msgid,
+            kind: kindRaw,
+            output: finalPath,
+            size: content.length,
+            ...(renamedFrom
+                ? { renamedFrom, renameNote: '扩展名已按文件头纠正（small/large 预览为服务端转换后的格式）' }
+                : {}),
+        });
+    },
+};
+/** 人员在线状态。 */
+const userState = {
+    name: 'yimiaoban.user.state',
+    resource: 'user',
+    method: 'user.state',
+    action: 'yimiaoban.user.state',
+    summary: '查询指定人员各在线设备状态（sub_state 强制 0 不订阅）',
+    capability: 'user',
+    risk: READ,
+    inputSchema: schemaOf({
+        users: { type: 'array', items: { type: 'string' }, description: '人员 uid 列表' },
+        devType: { type: 'integer', description: '设备类型（缺省查全部在线设备）' },
+        mask: { type: 'integer', description: '信息掩码（默认 7）' },
+    }, { required: ['users'], description: '查询人员在线状态' }),
+    handler: async (args, { host }) => {
+        const rawUids = Array.isArray(args.users) ? args.users.map((x) => String(x)) : splitIds(args.users, 'users');
+        const map = await host.resolveUsersByIds(rawUids);
+        const members = [];
+        const failed = [];
+        for (const uid of rawUids) {
+            const p = map[uid];
+            if (!p?.cid || p.cid === '0') {
+                failed.push({ uid, name: p?.name || '' });
+                continue;
+            }
+            members.push({ cid: p.cid, uid });
+        }
+        if (failed.length && args.removeFailed !== true) {
+            throw ymbValidationError('members_resolve_failed', `以下人员解析失败：${failed.map((f) => f.name || f.uid).join('、')}；确认跳过请传 removeFailed:true`);
+        }
+        const body = compact({
+            users: members,
+            sub_state: 0,
+            dev_type: args.devType !== undefined ? toUint(args.devType, 'devType') : undefined,
+            mask: Number(args.mask ?? 7),
+        });
+        const res = await host.request({
+            method: 'POST',
+            path: '/api/em/msg/executeIm/state/syncUserState',
+            body,
+            operation: 'yimiaoban.user.state',
+        });
+        assertImOk(res, '查询人员状态');
+        const inner = unwrapInner(res);
+        const devTypeNames = {
+            1: 'Android', 2: 'iPhone', 3: 'iPad', 4: 'API', 5: 'PC Web', 6: '手机Web', 7: 'Mac', 8: 'Linux', 9: 'Windows', 10: '第三方', 11: '安卓Pad', 12: '鸿蒙', 13: '鸿蒙Pad', 0: '无效',
+        };
+        const infos = (inner?.infos || []).map((it) => {
+            const uid = str(it?.user?.uid);
+            const devices = (it?.dev_infos || []).map((d) => ({
+                dev: Number(d.dev ?? -1),
+                devName: devTypeNames[Number(d.dev)] ?? String(d.dev),
+                status: Number(d.status),
+                online: Number(d.status) === 1,
+                loginTime: formatTime(d.logintime),
+                activeTime: formatTime(d.active_time),
+                imei: str(d.imei),
+            }));
+            return { uid, name: map[uid]?.name || uid, devices };
+        });
+        return ymbSuccess('yimiaoban.user.state', { total: infos.length, infos });
+    },
+};
+function formatTime(ts) {
+    if (ts === undefined || ts === null || ts === '')
+        return '-';
+    const d = new Date(Number(ts) * 1000);
+    if (Number.isNaN(d.getTime()))
+        return '-';
+    const p = (n) => String(n).padStart(2, '0');
+    return `${d.getFullYear()}/${d.getMonth() + 1}/${d.getDate()} ${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}`;
+}
+/** i18n 标签翻译（内部支撑，也可单独查询）。 */
+const i18nLabels = {
+    name: 'yimiaoban.i18n.labels',
+    resource: 'i18n',
+    method: 'i18n.labels',
+    action: 'yimiaoban.i18n.labels',
+    summary: '批量翻译国际化标签 id → 当前语言文案',
+    capability: 'i18n',
+    risk: READ,
+    inputSchema: schemaOf({
+        ids: { type: 'array', items: { type: 'string' }, description: '标签 id（数字）列表' },
+    }, { required: ['ids'], description: 'i18n 标签翻译' }),
+    handler: async (args, { host }) => {
+        const ids = Array.isArray(args.ids) ? args.ids.map((x) => String(x)) : splitIds(args.ids, 'ids');
+        const labels = await host.fetchI18nLabels(ids);
+        return ymbSuccess('yimiaoban.i18n.labels', {
+            total: Object.keys(labels).length,
+            labels: ids.map((id) => ({ id, text: labels[id] ?? '(未取到文案)' })),
+        });
+    },
+};
+export const fileUserOperations = [
+    fileUpload,
+    filePreview,
+    fileDownload,
+    userState,
+    i18nLabels,
+];