vps-work 2.5.0 → 2.5.1

package/dist/packages/vps-work/src/commands/im/shortcuts.js

@@ -0,0 +1,856 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { CLI_AUTH_CHANNEL } from '../../core/cli-bin.js';
+import { VertuError } from '../../core/errors.js';
+import { hermesRequest, resolveHermesAgentAdminUrl } from '../../core/hermes-client.js';
+import { downloadImAttachment } from '../../core/im-attachment-download.js';
+import { imRequest, printImResult } from '../../core/im-client.js';
+import { parseJsonArg } from '../../utils/parse-json-arg.js';
+import { attachOrgStructureShortcut } from '../org-structure.js';
+import { attachSharedShortcutOptions, mergeShortcutParams, parseOptionalInt, } from '../shortcut-common.js';
+import { buildImMessagePayload, parseUserIdList } from './im-message-payload.js';
+function baseUrl(opts, cmd) {
+    const merged = cmd.optsWithGlobals();
+    return opts.baseUrl ?? merged.baseUrl;
+}
+function print(opts, out) {
+    printImResult(opts.json, out);
+}
+function requiredDate(value, flag) {
+    const trimmed = value?.trim() ?? '';
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(trimmed);
+    if (!match) {
+        throw new VertuError(`${flag} 需为 YYYY-MM-DD。`);
+    }
+    const year = Number(match[1]);
+    const month = Number(match[2]);
+    const day = Number(match[3]);
+    const parsed = new Date(Date.UTC(year, month - 1, day));
+    if (parsed.getUTCFullYear() !== year ||
+        parsed.getUTCMonth() !== month - 1 ||
+        parsed.getUTCDate() !== day) {
+        throw new VertuError(`${flag} 不是有效日期。`);
+    }
+    return trimmed;
+}
+function requiredPositiveInteger(value, flag, max) {
+    const trimmed = value?.trim() ?? '';
+    if (!/^\d+$/.test(trimmed)) {
+        throw new VertuError(`${flag} 需为正整数。`);
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || (max !== undefined && parsed > max)) {
+        throw new VertuError(max === undefined ? `${flag} 需为正整数。` : `${flag} 需为 1-${max}。`);
+    }
+    return parsed;
+}
+function requiredBoundedInteger(value, flag, min, max) {
+    const trimmed = value?.trim() ?? '';
+    if (!/^\d+$/.test(trimmed)) {
+        throw new VertuError(`${flag} 需为 ${min}-${max} 的整数。`);
+    }
+    const parsed = Number(trimmed);
+    if (!Number.isSafeInteger(parsed) || parsed < min || parsed > max) {
+        throw new VertuError(`${flag} 需为 ${min}-${max} 的整数。`);
+    }
+    return parsed;
+}
+function collectAttach(value, previous) {
+    return [...previous, value];
+}
+function requiredInt(value, flag) {
+    const n = parseOptionalInt(value, flag);
+    if (n === undefined) {
+        throw new VertuError(`Invalid ${flag}.`);
+    }
+    return n;
+}
+function channelId(opts) {
+    const id = opts.channelId?.trim();
+    if (!id) {
+        throw new VertuError('--channel-id is required.');
+    }
+    return id;
+}
+function messageId(opts) {
+    const id = opts.messageId?.trim();
+    if (!id) {
+        throw new VertuError('--message-id is required.');
+    }
+    return id;
+}
+function callId(opts) {
+    const id = opts.callId?.trim();
+    if (!id) {
+        throw new VertuError('--call-id is required.');
+    }
+    return id;
+}
+function firstEnv(...keys) {
+    for (const key of keys) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return '';
+}
+function jsonObject(raw, flag) {
+    if (!raw?.trim()) {
+        return undefined;
+    }
+    const parsed = parseJsonArg(raw.trim(), flag);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new VertuError(`${flag} 必须为 JSON 对象。`);
+    }
+    return parsed;
+}
+function jsonArray(raw, flag) {
+    if (!raw?.trim()) {
+        return undefined;
+    }
+    const parsed = parseJsonArg(raw.trim(), flag);
+    if (!Array.isArray(parsed)) {
+        throw new VertuError(`${flag} 必须为 JSON 数组。`);
+    }
+    return parsed;
+}
+function extractChannelId(out) {
+    if (typeof out === 'object' && out !== null && 'channel' in out) {
+        const channel = out.channel;
+        if (typeof channel === 'object' && channel !== null && 'id' in channel) {
+            const id = channel.id;
+            if (typeof id === 'string') {
+                return id;
+            }
+        }
+    }
+    throw new VertuError('Vertu IM 未返回 channel.id。');
+}
+function attachmentDocument(out) {
+    if (typeof out !== 'object' || out === null || !('document' in out)) {
+        throw new VertuError('Vertu IM 未返回 document。');
+    }
+    const document = out.document;
+    if (typeof document !== 'object' || document === null) {
+        throw new VertuError('Vertu IM 返回的 document 无效。');
+    }
+    const row = document;
+    const id = typeof row.id === 'string' ? row.id : '';
+    const status = typeof row.status === 'string' ? row.status : '';
+    if (!id || !status) {
+        throw new VertuError('Vertu IM 返回的 document 缺少 id/status。');
+    }
+    return {
+        id,
+        status,
+        errorMessage: typeof row.error_message === 'string' ? row.error_message : '',
+    };
+}
+async function buildMessageBody(opts, serviceBaseUrl) {
+    const payload = await buildImMessagePayload({ ...opts, baseUrl: serviceBaseUrl ?? opts.baseUrl });
+    const body = { body: payload.body };
+    if (payload.attachments?.length) {
+        body.attachments = payload.attachments;
+    }
+    if (opts.messageType?.trim()) {
+        body.message_type = opts.messageType.trim();
+    }
+    if (opts.parentMessageId?.trim()) {
+        body.parent_message_id = opts.parentMessageId.trim();
+    }
+    if (opts.quoteMessageId?.trim()) {
+        body.quote_message_id = opts.quoteMessageId.trim();
+    }
+    body.client_message_id = opts.clientMessageId?.trim() || randomUUID();
+    body.idempotency_key = opts.idempotencyKey?.trim() || body.client_message_id;
+    const metadata = jsonObject(opts.metadataJson, '--metadata-json');
+    if (metadata) {
+        body.metadata = metadata;
+    }
+    return body;
+}
+async function buildAgentNotifyBody(opts, serviceBaseUrl) {
+    const agentSlug = opts.agentSlug?.trim() || firstEnv('VERTU_AGENT_SLUG', 'HERMES_AGENT_SLUG');
+    if (!agentSlug) {
+        throw new VertuError('--agent-slug is required，或设置 VERTU_AGENT_SLUG。');
+    }
+    const channelId = opts.channelId?.trim() || firstEnv('VERTU_AGENT_CHANNEL_ID');
+    const rawUserId = opts.userId?.trim() || firstEnv('VERTU_AGENT_USER_ID', 'VERTU_AGENT_ODOO_USER_ID');
+    const userId = rawUserId ? requiredInt(rawUserId, '--user-id') : undefined;
+    const agentName = opts.agentName?.trim() || firstEnv('VERTU_AGENT_NAME', 'VERTU_AGENT_PROFILE_NAME');
+    const sessionId = opts.sessionId?.trim() || firstEnv('VERTU_AGENT_SESSION_ID', 'HERMES_SESSION_ID');
+    const eventId = opts.eventId?.trim() || `agent:${agentSlug}:${userId ?? 'current'}:${randomUUID()}`;
+    const message = await buildMessageBody({
+        ...opts,
+        idempotencyKey: opts.idempotencyKey?.trim() || eventId,
+    }, serviceBaseUrl);
+    const metadata = {
+        ...(typeof message.metadata === 'object' && message.metadata !== null && !Array.isArray(message.metadata)
+            ? message.metadata
+            : {}),
+        source: CLI_AUTH_CHANNEL,
+        agent_slug: agentSlug,
+        agent_name: agentName || null,
+        session_id: sessionId || null,
+    };
+    return {
+        ...message,
+        agent_slug: agentSlug,
+        ...(channelId ? { channel_id: channelId } : {}),
+        ...(userId !== undefined ? { user_id: userId } : {}),
+        ...(agentName ? { agent_name: agentName } : {}),
+        ...(opts.botKey?.trim() ? { bot_key: opts.botKey.trim() } : {}),
+        ...(opts.botName?.trim() ? { bot_name: opts.botName.trim() } : {}),
+        ...(sessionId ? { session_id: sessionId } : {}),
+        event_id: eventId,
+        metadata,
+    };
+}
+async function buildAgentSessionNotifyBody(opts, serviceBaseUrl) {
+    const message = await buildMessageBody({
+        ...opts,
+        idempotencyKey: opts.idempotencyKey?.trim() || opts.eventId?.trim(),
+    }, serviceBaseUrl);
+    const agentName = opts.agentName?.trim() || firstEnv('VERTU_AGENT_NAME', 'VERTU_AGENT_PROFILE_NAME');
+    const eventId = opts.eventId?.trim() || String(message.idempotency_key || message.client_message_id || randomUUID());
+    const metadata = {
+        ...(typeof message.metadata === 'object' && message.metadata !== null && !Array.isArray(message.metadata)
+            ? message.metadata
+            : {}),
+        source: CLI_AUTH_CHANNEL,
+        agent_name: agentName || null,
+        event_id: eventId,
+    };
+    return {
+        ...message,
+        ...(agentName ? { agent_name: agentName } : {}),
+        event_id: eventId,
+        metadata,
+    };
+}
+function attachMessageOptions(cmd) {
+    return cmd
+        .option('--body <text>', '消息正文')
+        .option('--body-file <path>', '从文件读取正文；- 表示 stdin')
+        .option('--attach <path>', '附件路径，可重复', collectAttach, [])
+        .option('--attachments-json <json>', '附件 JSON 数组')
+        .option('--message-type <type>', 'text/rich_text/image/file/audio/video/link/emoji')
+        .option('--parent-message-id <id>', '回复的消息 id')
+        .option('--quote-message-id <id>', '引用的消息 id')
+        .option('--client-message-id <id>', '客户端消息 id，用于并发幂等')
+        .option('--idempotency-key <key>', '幂等键')
+        .option('--metadata-json <json>', '消息 metadata JSON 对象');
+}
+export function attachImShortcuts(parent) {
+    attachSharedShortcutOptions(parent.command('+me').description('当前 IM 身份')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', '/v1/im/me', { baseUrl: baseUrl(opts, cmd) }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+users')
+        .description('按姓名/工号/登录名/部门搜索组织成员')
+        .option('--query <text>', '搜索关键字')
+        .option('--department-path <path>', '部门路径')
+        .option('--include-children', '部门路径包含子部门', true)
+        .option('--limit <n>', '数量', '30')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', '/v1/im/org/users', {
+            baseUrl: baseUrl(opts, cmd),
+            query: {
+                query: opts.query,
+                department_path: opts.departmentPath,
+                include_children: opts.includeChildren,
+                limit: opts.limit,
+            },
+        }));
+    });
+    attachOrgStructureShortcut(parent, '+departments', '组织部门树（默认一级/二级；用 --max-depth 0 查看全量）');
+    attachSharedShortcutOptions(parent.command('+channels').description('我的 IM 会话列表').option('--limit <n>', '数量', '50')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', '/v1/im/channels', {
+            baseUrl: baseUrl(opts, cmd),
+            query: { limit: opts.limit },
+        }));
+    });
+    attachSharedShortcutOptions(parent.command('+chat').description('获取或创建私聊').requiredOption('--user-id <id>', '对方 user_id').option('--membership-id <id>', '对方当前企业 membership_id')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({ channel_type: 'direct', user_id: requiredInt(opts.userId, '--user-id'), membership_id: opts.membershipId?.trim() || undefined }, opts);
+        print(opts, await imRequest('POST', '/v1/im/channels', { baseUrl: baseUrl(opts, cmd), body }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+create-group')
+        .description('创建群聊')
+        .requiredOption('--name <text>', '群名称')
+        .requiredOption('--user-ids <list>', '成员 user_id，逗号分隔或 JSON 数组')
+        .option('--description <text>', '群说明')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            channel_type: 'group',
+            name: opts.name?.trim(),
+            description: opts.description?.trim(),
+            user_ids: parseUserIdList(opts.userIds, '--user-ids'),
+        }, opts);
+        print(opts, await imRequest('POST', '/v1/im/channels', { baseUrl: baseUrl(opts, cmd), body }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+create-org-group')
+        .description('按组织架构创建群聊')
+        .requiredOption('--department-path <path>', '部门完整路径')
+        .option('--name <text>', '群名称')
+        .option('--include-children', '包含子部门', true)).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            channel_type: 'org',
+            name: opts.name?.trim(),
+            department_path: opts.departmentPath?.trim(),
+            include_children: opts.includeChildren,
+        }, opts);
+        print(opts, await imRequest('POST', '/v1/im/channels', { baseUrl: baseUrl(opts, cmd), body }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+history')
+        .description('查看会话消息历史')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .option('--date-from <iso>', '起始时间')
+        .option('--date-to <iso>', '结束时间')
+        .option('--keyword <text>', '正文关键字')
+        .option('--limit <n>', '数量', '50')
+        .option('--offset <n>', '分页偏移')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/messages`, {
+            baseUrl: baseUrl(opts, cmd),
+            query: {
+                date_from: opts.dateFrom,
+                date_to: opts.dateTo,
+                keyword: opts.keyword,
+                limit: opts.limit,
+                offset: opts.offset,
+            },
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+all-chat-records')
+        .description('凭独立权限分页查询全域聊天记录')
+        .requiredOption('--start-date <ymd>', '起始日期 YYYY-MM-DD（中国时区）')
+        .requiredOption('--end-date <ymd>', '结束日期 YYYY-MM-DD（中国时区，最多 31 天）')
+        .requiredOption('--page <n>', '页码，从 1 开始')
+        .requiredOption('--page-size <n>', '每页条数，1-100')).action(async (opts, cmd) => {
+        const startDate = requiredDate(opts.startDate, '--start-date');
+        const endDate = requiredDate(opts.endDate, '--end-date');
+        const page = requiredPositiveInteger(opts.page, '--page');
+        const pageSize = requiredPositiveInteger(opts.pageSize, '--page-size', 100);
+        print(opts, await imRequest('GET', '/v1/im/audit/messages', {
+            baseUrl: baseUrl(opts, cmd),
+            query: {
+                start_date: startDate,
+                end_date: endDate,
+                page,
+                page_size: pageSize,
+            },
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+attachments')
+        .description('凭独立附件权限按发送人精确查询最近聊天附件')
+        .requiredOption('--sender-name <name>', '发送人姓名，精确匹配')
+        .requiredOption('--access-reason <text>', '本次查询附件的业务事由')
+        .option('--limit <n>', '返回数量，1-100', '20')).action(async (opts, cmd) => {
+        const senderName = opts.senderName?.trim() ?? '';
+        const accessReason = opts.accessReason?.trim() ?? '';
+        if (!senderName) {
+            throw new VertuError('--sender-name is required.');
+        }
+        if (!accessReason) {
+            throw new VertuError('--access-reason is required.');
+        }
+        const limit = requiredBoundedInteger(opts.limit, '--limit', 1, 100);
+        print(opts, await imRequest('GET', '/v1/im/audit/attachments', {
+            baseUrl: baseUrl(opts, cmd),
+            query: {
+                sender_name: senderName,
+                access_reason: accessReason,
+                limit,
+            },
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+attachment-content')
+        .description('凭精确审计权限把聊天附件解析为 Markdown')
+        .requiredOption('--attachment-id <id>', '聊天附件 id')
+        .requiredOption('--access-reason <text>', '本次读取附件内容的业务事由')
+        .option('--wait-seconds <n>', '等待解析完成的秒数，0 表示不等待', '120')
+        .option('--poll-interval-ms <n>', '解析状态轮询间隔', '2000')).action(async (opts, cmd) => {
+        const attachmentId = opts.attachmentId?.trim() ?? '';
+        const accessReason = opts.accessReason?.trim() ?? '';
+        if (!attachmentId) {
+            throw new VertuError('--attachment-id is required.');
+        }
+        if (!accessReason) {
+            throw new VertuError('--access-reason is required.');
+        }
+        const waitSeconds = requiredBoundedInteger(opts.waitSeconds, '--wait-seconds', 0, 900);
+        const pollIntervalMs = requiredBoundedInteger(opts.pollIntervalMs, '--poll-interval-ms', 500, 10_000);
+        const path = `/v1/im/audit/attachments/${encodeURIComponent(attachmentId)}/content`;
+        let out = await imRequest('POST', path, {
+            baseUrl: baseUrl(opts, cmd),
+            body: { access_reason: accessReason },
+        });
+        let document = attachmentDocument(out);
+        const deadline = Date.now() + waitSeconds * 1000;
+        while ((document.status === 'pending' || document.status === 'processing') &&
+            Date.now() < deadline) {
+            await sleep(Math.min(pollIntervalMs, Math.max(1, deadline - Date.now())));
+            out = await imRequest('GET', path, {
+                baseUrl: baseUrl(opts, cmd),
+                query: {
+                    access_reason: accessReason,
+                    document_id: document.id,
+                },
+            });
+            document = attachmentDocument(out);
+        }
+        if (document.status === 'failed') {
+            throw new VertuError(`附件解析失败：${document.errorMessage || '未知错误'}`);
+        }
+        print(opts, out);
+    });
+    attachSharedShortcutOptions(parent
+        .command('+attachment-download')
+        .description('下载当前账号有权访问的聊天图片或附件原文件')
+        .option('--url <path>', '+history 返回的 attachments[].url')
+        .option('--storage-key <key>', '+history 返回的 attachments[].storage_key')
+        .requiredOption('--output <path>', '保存到本地的完整文件路径；不会覆盖已有文件')).action(async (opts, cmd) => {
+        const output = opts.output?.trim() ?? '';
+        if (!output)
+            throw new VertuError('--output is required.');
+        print(opts, await downloadImAttachment({
+            baseUrl: baseUrl(opts, cmd),
+            output,
+            storageKey: opts.storageKey,
+            url: opts.url,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+channel-update')
+        .description('更新群名称、头像、公告')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .option('--name <text>', '群名称')
+        .option('--description <text>', '群说明')
+        .option('--avatar-url <url>', '群头像 URL')
+        .option('--announcement <text>', '群公告')
+        .option('--group-nature <value>', '群性质：daily_report/日报群；传空字符串取消日报群；已设置其他性质后不可修改')
+        .option('--expected-version <n>', '并发版本号')).action(async (opts, cmd) => {
+        const expectedVersion = parseOptionalInt(opts.expectedVersion, '--expected-version');
+        const body = await mergeShortcutParams({
+            name: opts.name?.trim(),
+            description: opts.description?.trim(),
+            avatar_url: opts.avatarUrl?.trim(),
+            announcement: opts.announcement?.trim(),
+            group_nature: opts.groupNature?.trim(),
+            expected_version: expectedVersion,
+        }, opts);
+        print(opts, await imRequest('PATCH', `/v1/im/channels/${encodeURIComponent(channelId(opts))}`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(attachMessageOptions(parent.command('+send').description('向会话发送消息').requiredOption('--channel-id <id>', '会话 id'))).action(async (opts, cmd) => {
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        const body = await mergeShortcutParams(await buildMessageBody(opts, serviceBaseUrl), opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/messages`, {
+            baseUrl: serviceBaseUrl,
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(attachMessageOptions(parent
+        .command('+send-approval-card')
+        .description('发送审批类互动卡片')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .requiredOption('--title <text>', '审批标题')
+        .option('--summary <text>', '审批摘要')
+        .option('--approval-id <id>', '外部审批单 id')
+        .option('--actions-json <json>', '按钮动作 JSON 数组'))).action(async (opts, cmd) => {
+        const title = opts.title?.trim();
+        if (!title) {
+            throw new VertuError('--title is required.');
+        }
+        const metadata = {
+            ...(jsonObject(opts.metadataJson, '--metadata-json') ?? {}),
+            card: {
+                kind: 'approval',
+                title,
+                summary: opts.summary?.trim() ?? '',
+                approval_id: opts.approvalId?.trim() ?? null,
+                actions: jsonArray(opts.actionsJson, '--actions-json') ?? [
+                    { key: 'approve', label: '同意' },
+                    { key: 'reject', label: '拒绝' },
+                ],
+            },
+        };
+        const body = await mergeShortcutParams({
+            ...(await buildMessageBody({
+                ...opts,
+                body: opts.body?.trim() || title,
+                messageType: 'approval_card',
+                metadataJson: JSON.stringify(metadata),
+            }, baseUrl(opts, cmd))),
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/messages`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+revoke')
+        .description('撤回消息')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .requiredOption('--message-id <id>', '消息 id')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({ action: 'revoke', message_id: messageId(opts) }, opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/messages`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+interact')
+        .description('对消息执行互动动作：表情、审批按钮、卡片按钮、确认')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .requiredOption('--message-id <id>', '消息 id')
+        .requiredOption('--interaction-type <reaction|approval_action|card_action|ack>', '互动类型')
+        .requiredOption('--value <text>', '互动值，例如 approve/reject/👍')
+        .option('--metadata-json <json>', '互动 metadata JSON 对象')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            action: 'interact',
+            message_id: messageId(opts),
+            interaction_type: opts.interactionType?.trim(),
+            value: opts.value?.trim(),
+            metadata: jsonObject(opts.metadataJson, '--metadata-json'),
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/messages`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(attachMessageOptions(parent
+        .command('+send-user')
+        .description('给某人发消息（自动创建/复用私聊）')
+        .requiredOption('--user-id <id>', '对方 user_id')
+        .option('--membership-id <id>', '对方当前企业 membership_id'))).action(async (opts, cmd) => {
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        const created = await imRequest('POST', '/v1/im/channels', {
+            baseUrl: serviceBaseUrl,
+            body: { channel_type: 'direct', user_id: requiredInt(opts.userId, '--user-id'), membership_id: opts.membershipId?.trim() || undefined },
+        });
+        const id = extractChannelId(created);
+        const body = await mergeShortcutParams(await buildMessageBody(opts, serviceBaseUrl), opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(id)}/messages`, {
+            baseUrl: serviceBaseUrl,
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(attachMessageOptions(parent
+        .command('+agent-notify')
+        .description('专家智能体主动通知；默认有 channel_id 写入 IM，否则回退专家会话')
+        .option('--agent-slug <slug>', '专家 agent_slug；默认读 VERTU_AGENT_SLUG')
+        .option('--agent-name <text>', '专家名称；默认读 VERTU_AGENT_NAME / VERTU_AGENT_PROFILE_NAME')
+        .option('--user-id <id>', '目标 user_id；默认读 VERTU_AGENT_USER_ID 或服务端当前用户')
+        .option('--event-id <id>', '业务事件 id；默认自动生成并作为幂等键')
+        .option('--session-id <id>', 'Hermes 会话 id；默认读 VERTU_AGENT_SESSION_ID')
+        .option('--target <target>', '投递目标：auto / im / hermes-session；默认读 VERTU_AGENT_NOTIFY_TARGET，缺省为 auto')
+        .option('--hermes-base-url <url>', 'Hermes agent admin URL；默认读 VERTU_HERMES_BASE_URL / HERMES_AGENT_ADMIN_BASE_URL')
+        .option('--channel-id <id>', '目标 IM 会话 id；默认读 VERTU_AGENT_CHANNEL_ID，提供后不会自动创建专家会话')
+        .option('--bot-key <key>', '覆盖 bot_key')
+        .option('--bot-name <text>', '覆盖 bot_name'))).action(async (opts, cmd) => {
+        const rawTarget = (opts.target?.trim() || firstEnv('VERTU_AGENT_NOTIFY_TARGET') || 'auto').toLowerCase();
+        const agentSlugForEvent = opts.agentSlug?.trim() || firstEnv('VERTU_AGENT_SLUG', 'HERMES_AGENT_SLUG');
+        const rawUserIdForEvent = opts.userId?.trim() || firstEnv('VERTU_AGENT_USER_ID', 'VERTU_AGENT_ODOO_USER_ID');
+        if (!opts.eventId && agentSlugForEvent) {
+            opts.eventId = `agent:${agentSlugForEvent}:${rawUserIdForEvent || 'current'}:${randomUUID()}`;
+        }
+        if (rawTarget === 'auto') {
+            const body = await mergeShortcutParams(await buildAgentNotifyBody(opts, baseUrl(opts, cmd)), opts);
+            const agentSlug = String(body.agent_slug || '').trim();
+            if (!agentSlug) {
+                throw new VertuError('--agent-slug is required，或设置 VERTU_AGENT_SLUG。');
+            }
+            print(opts, await hermesRequest('POST', `/hermes-console/api/agents/${encodeURIComponent(agentSlug)}/notify`, { baseUrl: resolveHermesAgentAdminUrl(opts.hermesBaseUrl), body }));
+            return;
+        }
+        const target = rawTarget;
+        if (target === 'hermes-session' || target === 'session' || target === 'agent-session') {
+            const agentSlug = opts.agentSlug?.trim() || firstEnv('VERTU_AGENT_SLUG', 'HERMES_AGENT_SLUG');
+            const sessionId = opts.sessionId?.trim() || firstEnv('VERTU_AGENT_SESSION_ID', 'HERMES_SESSION_ID');
+            const rawUserId = opts.userId?.trim() || firstEnv('VERTU_AGENT_USER_ID', 'VERTU_AGENT_ODOO_USER_ID');
+            if (!agentSlug) {
+                throw new VertuError('--agent-slug is required，或设置 VERTU_AGENT_SLUG。');
+            }
+            if (!sessionId) {
+                throw new VertuError('--session-id is required for --target hermes-session，或设置 VERTU_AGENT_SESSION_ID。');
+            }
+            const body = await mergeShortcutParams({
+                ...(await buildAgentSessionNotifyBody(opts, baseUrl(opts, cmd))),
+                odoo_user_id: rawUserId ? requiredInt(rawUserId, '--user-id') : undefined,
+            }, opts);
+            print(opts, await hermesRequest('POST', `/hermes-console/api/agents/${encodeURIComponent(agentSlug)}/sessions/${encodeURIComponent(sessionId)}/messages`, { baseUrl: resolveHermesAgentAdminUrl(opts.hermesBaseUrl), body }));
+            return;
+        }
+        if (target !== 'im') {
+            throw new VertuError('--target 仅支持 auto、hermes-session 或 im。');
+        }
+        const body = await mergeShortcutParams(await buildAgentNotifyBody(opts, baseUrl(opts, cmd)), opts);
+        print(opts, await imRequest('POST', '/v1/im/agents/hermes/notify', { baseUrl: baseUrl(opts, cmd), body }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+add-members')
+        .description('添加群成员')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .requiredOption('--user-ids <list>', '成员 user_id')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({ user_ids: parseUserIdList(opts.userIds, '--user-ids') }, opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/members`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+set-role')
+        .description('调整群成员角色')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .requiredOption('--user-id <id>', '成员 user_id')
+        .requiredOption('--role <owner|admin|member>', '角色')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({ user_id: requiredInt(opts.userId, '--user-id'), role: opts.role }, opts);
+        print(opts, await imRequest('PATCH', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/members`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+remove-member')
+        .description('移除群成员')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .requiredOption('--user-id <id>', '成员 user_id')).action(async (opts, cmd) => {
+        print(opts, await imRequest('DELETE', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/members`, {
+            baseUrl: baseUrl(opts, cmd),
+            query: { user_id: requiredInt(opts.userId, '--user-id') },
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+sync')
+        .description('按游标同步 IM 增量事件')
+        .option('--cursor <n>', '事件游标', '0')
+        .option('--limit <n>', '数量', '100')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', '/v1/im/sync', {
+            baseUrl: baseUrl(opts, cmd),
+            query: { cursor: opts.cursor, limit: opts.limit },
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+call-start')
+        .description('发起语音/视频通话，支持群通话')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .option('--call-type <audio|video>', '通话类型', 'audio')
+        .option('--user-ids <list>', '邀请成员 user_id；默认邀请会话内所有成员')
+        .option('--title <text>', '通话标题')
+        .option('--device-id <id>', '当前设备 id')
+        .option('--audio-enabled', '开启麦克风', true)
+        .option('--video-enabled', '开启摄像头', false)
+        .option('--metadata-json <json>', '通话 metadata JSON 对象')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            call_type: opts.callType?.trim() || 'audio',
+            user_ids: opts.userIds ? parseUserIdList(opts.userIds, '--user-ids') : undefined,
+            title: opts.title?.trim(),
+            device_id: opts.deviceId?.trim(),
+            audio_enabled: opts.audioEnabled,
+            video_enabled: opts.videoEnabled,
+            metadata: jsonObject(opts.metadataJson, '--metadata-json'),
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/calls`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+call-join')
+        .description('加入语音/视频通话')
+        .requiredOption('--call-id <id>', '通话 id')
+        .option('--device-id <id>', '当前设备 id')
+        .option('--audio-enabled', '开启麦克风', true)
+        .option('--video-enabled', '开启摄像头', false)).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            action: 'join',
+            device_id: opts.deviceId?.trim(),
+            audio_enabled: opts.audioEnabled,
+            video_enabled: opts.videoEnabled,
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/calls/${encodeURIComponent(callId(opts))}`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+call-leave')
+        .description('离开或拒绝通话')
+        .requiredOption('--call-id <id>', '通话 id')
+        .option('--status <left|declined|failed>', '离开状态', 'left')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({ action: 'leave', status: opts.status?.trim() || 'left' }, opts);
+        print(opts, await imRequest('POST', `/v1/im/calls/${encodeURIComponent(callId(opts))}`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+call-end')
+        .description('结束通话')
+        .requiredOption('--call-id <id>', '通话 id')
+        .option('--status <ended|cancelled|missed|failed>', '结束状态', 'ended')
+        .option('--reason <text>', '结束原因')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            action: 'end',
+            status: opts.status?.trim() || 'ended',
+            reason: opts.reason?.trim(),
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/calls/${encodeURIComponent(callId(opts))}`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+call-signal')
+        .description('发送 WebRTC 通话信令')
+        .requiredOption('--call-id <id>', '通话 id')
+        .requiredOption('--signal-type <type>', 'offer/answer/ice_candidate/heartbeat 等')
+        .option('--recipient-user-id <id>', '目标 user_id；省略为广播给通话内成员')
+        .option('--payload-json <json>', '信令 payload JSON 对象')
+        .option('--client-signal-id <id>', '客户端信令 id，用于幂等')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            signal_type: opts.signalType?.trim(),
+            recipient_user_id: parseOptionalInt(opts.recipientUserId, '--recipient-user-id'),
+            payload: jsonObject(opts.payloadJson, '--payload-json') ?? {},
+            client_signal_id: opts.clientSignalId?.trim() || randomUUID(),
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/calls/${encodeURIComponent(callId(opts))}/signals`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+call-signals')
+        .description('拉取通话信令')
+        .requiredOption('--call-id <id>', '通话 id')
+        .option('--cursor <iso>', 'created_at 游标')
+        .option('--limit <n>', '数量', '100')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', `/v1/im/calls/${encodeURIComponent(callId(opts))}/signals`, {
+            baseUrl: baseUrl(opts, cmd),
+            query: { cursor: opts.cursor, limit: opts.limit },
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+watch')
+        .description('轮询 IM 增量事件，用于命令行及时推送')
+        .option('--cursor <n>', '事件游标', '0')
+        .option('--limit <n>', '每轮数量', '100')
+        .option('--interval-ms <n>', '轮询间隔毫秒', '3000')
+        .option('--once', '只拉取一次', false)).action(async (opts, cmd) => {
+        let cursor = parseOptionalInt(opts.cursor, '--cursor') ?? 0;
+        const intervalMs = parseOptionalInt(opts.intervalMs, '--interval-ms') ?? 3000;
+        do {
+            const out = await imRequest('GET', '/v1/im/sync', {
+                baseUrl: baseUrl(opts, cmd),
+                query: { cursor, limit: opts.limit },
+            });
+            print(opts, out);
+            if (typeof out === 'object' && out !== null && 'next_cursor' in out) {
+                const nextCursor = Number(out.next_cursor);
+                if (Number.isInteger(nextCursor) && nextCursor >= cursor) {
+                    cursor = nextCursor;
+                }
+            }
+            if (!opts.once) {
+                await sleep(Math.max(intervalMs, 1000));
+            }
+        } while (!opts.once);
+    });
+    attachSharedShortcutOptions(attachMessageOptions(parent
+        .command('+broadcast')
+        .description('群发消息')
+        .option('--user-ids <list>', '收件人 user_id')
+        .option('--department-path <path>', '按部门路径群发')
+        .option('--include-children', '部门包含子部门', true)
+        .option('--name <text>', '群发会话名称')
+        .option('--limit <n>', '部门群发人数上限', '1000'))).action(async (opts, cmd) => {
+        const payload = await buildMessageBody(opts, baseUrl(opts, cmd));
+        const body = await mergeShortcutParams({
+            ...payload,
+            user_ids: opts.userIds ? parseUserIdList(opts.userIds, '--user-ids') : undefined,
+            department_path: opts.departmentPath?.trim(),
+            include_children: opts.includeChildren,
+            name: opts.name?.trim(),
+            limit: opts.limit,
+        }, opts);
+        print(opts, await imRequest('POST', '/v1/im/broadcast', { baseUrl: baseUrl(opts, cmd), body }));
+    });
+    attachSharedShortcutOptions(parent.command('+bots').description('我的机器人列表').option('--include-public', '同时列出其他人的公开机器人')).action(async (opts, cmd) => {
+        const path = opts.includePublic ? '/v1/im/user-robots?include_public=true' : '/v1/im/user-robots';
+        print(opts, await imRequest('GET', path, { baseUrl: baseUrl(opts, cmd) }));
+    });
+    attachSharedShortcutOptions(parent.command('+bot-channels').description('查询我的全部机器人已加入的群聊')).action(async (opts, cmd) => {
+        print(opts, await imRequest('GET', '/v1/im/user-robots/channels', { baseUrl: baseUrl(opts, cmd) }));
+    });
+    attachSharedShortcutOptions(attachMessageOptions(parent
+        .command('+bot-send-user')
+        .description('以我的指定机器人身份给员工发起私聊')
+        .requiredOption('--app-id <id>', '机器人 App ID')
+        .requiredOption('--user-id <id>', '对方 user_id'))).action(async (opts, cmd) => {
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        const appID = opts.appId?.trim() ?? '';
+        if (!appID)
+            throw new VertuError('--app-id is required.');
+        const body = await mergeShortcutParams({
+            ...(await buildMessageBody(opts, serviceBaseUrl)),
+            user_id: requiredInt(opts.userId, '--user-id'),
+        }, opts);
+        print(opts, await imRequest('POST', `/v1/im/user-robots/${encodeURIComponent(appID)}/message-user`, { baseUrl: serviceBaseUrl, body }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+bot-create')
+        .description('创建 IM 机器人')
+        .requiredOption('--name <text>', '机器人名称')
+        .option('--bot-key <key>', '机器人唯一 key')
+        .option('--description <text>', '说明')
+        .option('--webhook-url <url>', '机器人 webhook')
+        .option('--public', '设为公开，允许其他群管理员添加')).action(async (opts, cmd) => {
+        const body = await mergeShortcutParams({
+            name: opts.name?.trim(),
+            bot_key: opts.botKey?.trim(),
+            description: opts.description?.trim(),
+            webhook_url: opts.webhookUrl?.trim(),
+            is_public: opts.public === true,
+        }, opts);
+        print(opts, await imRequest('POST', '/v1/im/user-robots', { baseUrl: baseUrl(opts, cmd), body }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+bot-update')
+        .description('更新机器人的公开范围')
+        .requiredOption('--app-id <id>', '机器人 App ID')
+        .option('--public', '设为公开')
+        .option('--private', '设为仅自己可见')).action(async (opts, cmd) => {
+        if (opts.public === opts.private) {
+            throw new VertuError('--public 和 --private 必须且只能指定一个。');
+        }
+        const appID = opts.appId?.trim() ?? '';
+        const body = await mergeShortcutParams({ is_public: opts.public === true }, opts);
+        print(opts, await imRequest('PATCH', `/v1/im/user-robots/${encodeURIComponent(appID)}`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+add-bot')
+        .description('添加机器人到会话')
+        .requiredOption('--channel-id <id>', '会话 id')
+        .option('--app-id <id>', '机器人 App ID')
+        .option('--bot-id <id>', '机器人 App ID（兼容旧参数名）')).action(async (opts, cmd) => {
+        const appID = opts.appId?.trim() || opts.botId?.trim();
+        if (!appID) {
+            throw new VertuError('--app-id is required.');
+        }
+        const body = await mergeShortcutParams({ app_id: appID }, opts);
+        print(opts, await imRequest('POST', `/v1/im/channels/${encodeURIComponent(channelId(opts))}/bots`, {
+            baseUrl: baseUrl(opts, cmd),
+            body,
+        }));
+    });
+}