vps-work 2.4.1 → 2.5.1

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

@@ -0,0 +1,598 @@
+import { VertuError } from '../../core/errors.js';
+import { imRequest, printImResult } from '../../core/im-client.js';
+import { attachSharedShortcutOptions, mergeShortcutParams, resolveShortcutVpsServiceUrl, } from '../shortcut-common.js';
+import { parseUserIdList } from '../im/im-message-payload.js';
+const DAY_MS = 86_400_000;
+const MAX_RANGE_DAYS = 370;
+const AVAILABILITY_RANGE_DAYS = 8;
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function recordArray(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => asRecord(item) !== null)
+        : [];
+}
+function shanghaiToday() {
+    return new Intl.DateTimeFormat('en-CA', {
+        timeZone: 'Asia/Shanghai',
+        year: 'numeric',
+        month: '2-digit',
+        day: '2-digit',
+    }).format(new Date());
+}
+function parseYmd(raw, flag) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
+    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 date = new Date(Date.UTC(year, month - 1, day));
+    if (date.getUTCFullYear() !== year
+        || date.getUTCMonth() !== month - 1
+        || date.getUTCDate() !== day) {
+        throw new VertuError(`${flag} 不是有效日期。`);
+    }
+    return { year, month, day };
+}
+function ymdAtUtc(raw, flag) {
+    const { year, month, day } = parseYmd(raw, flag);
+    return Date.UTC(year, month - 1, day);
+}
+function addDays(raw, days) {
+    const timestamp = ymdAtUtc(raw, '日期') + days * DAY_MS;
+    return new Date(timestamp).toISOString().slice(0, 10);
+}
+function resolveDateRange(opts, maxDays = MAX_RANGE_DAYS) {
+    const today = shanghaiToday();
+    const startDate = opts.startDate?.trim() || opts.endDate?.trim() || today;
+    const endDate = opts.endDate?.trim() || startDate;
+    const startDay = ymdAtUtc(startDate, '--start-date');
+    const endDay = ymdAtUtc(endDate, '--end-date');
+    const days = Math.round((endDay - startDay) / DAY_MS) + 1;
+    if (days <= 0) {
+        throw new VertuError('--end-date 不能早于 --start-date。');
+    }
+    if (days > maxDays) {
+        throw new VertuError(`日期范围最多 ${maxDays} 天。`);
+    }
+    return {
+        startDate,
+        endDate,
+        start: `${startDate}T00:00:00+08:00`,
+        endExclusive: `${addDays(endDate, 1)}T00:00:00+08:00`,
+        days,
+    };
+}
+function isDryRun(opts) {
+    return opts.validateOnly === true || opts.dryRun === true;
+}
+function baseUrl(opts, cmd) {
+    return resolveShortcutVpsServiceUrl(opts, cmd);
+}
+function printPreview(opts, endpoint, query) {
+    printImResult(opts.json, {
+        validateOnly: true,
+        method: 'GET',
+        endpoint,
+        query,
+    });
+}
+function printMutationPreview(opts, method, endpoint, body) {
+    printImResult(opts.json, {
+        validateOnly: true,
+        method,
+        endpoint,
+        body,
+    });
+}
+function decorateEvents(payload, scope, range, calendarId) {
+    const record = asRecord(payload) ?? {};
+    const calendars = recordArray(record.calendars);
+    const calendarNames = new Map(calendars.flatMap((calendar) => {
+        const id = typeof calendar.id === 'string' ? calendar.id : '';
+        return id ? [[id, typeof calendar.name === 'string' ? calendar.name : null]] : [];
+    }));
+    if (calendarId && !calendarNames.has(calendarId)) {
+        throw new VertuError(`日历不存在或无权查看：${calendarId}`);
+    }
+    const rows = recordArray(record.events)
+        .filter((event) => !calendarId || event.calendar_id === calendarId)
+        .map((event) => ({
+        ...event,
+        calendar_name: typeof event.calendar_id === 'string'
+            ? calendarNames.get(event.calendar_id) ?? null
+            : null,
+    }));
+    return {
+        ok: true,
+        scope,
+        filter: {
+            start_date: range.startDate,
+            end_date: range.endDate,
+            time_zone: 'Asia/Shanghai',
+            ...(calendarId ? { calendar_id: calendarId } : {}),
+        },
+        rows,
+        summary: { events: rows.length },
+    };
+}
+function positiveUserId(raw, flag) {
+    const text = raw?.trim();
+    if (!text) {
+        return undefined;
+    }
+    if (!/^\d+$/.test(text)) {
+        throw new VertuError(`${flag} 需为正整数。`);
+    }
+    const value = Number(text);
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new VertuError(`${flag} 需为正整数。`);
+    }
+    return value;
+}
+function nonEmpty(raw, flag) {
+    const value = raw?.trim();
+    if (!value) {
+        throw new VertuError(`${flag} 为必填。`);
+    }
+    return value;
+}
+function optionalBoolean(raw, flag) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = raw.trim().toLocaleLowerCase();
+    if (['true', '1', 'yes', '是'].includes(value)) {
+        return true;
+    }
+    if (['false', '0', 'no', '否'].includes(value)) {
+        return false;
+    }
+    throw new VertuError(`${flag} 需为 true 或 false。`);
+}
+function optionalDateTime(raw, flag) {
+    const value = raw?.trim();
+    if (!value) {
+        return undefined;
+    }
+    const local = /^(\d{4}-\d{2}-\d{2})[ T](\d{2}:\d{2})(?::(\d{2}))?$/.exec(value);
+    const normalized = local
+        ? `${local[1]}T${local[2]}:${local[3] ?? '00'}+08:00`
+        : value;
+    if (!Number.isFinite(Date.parse(normalized))) {
+        throw new VertuError(`${flag} 需为有效 ISO 时间，例如 2026-07-24T09:00:00+08:00。`);
+    }
+    return normalized;
+}
+function requiredDateTime(raw, flag) {
+    const value = optionalDateTime(raw, flag);
+    if (!value) {
+        throw new VertuError(`${flag} 为必填。`);
+    }
+    return value;
+}
+function optionalEventType(raw) {
+    const value = raw?.trim();
+    if (!value) {
+        return undefined;
+    }
+    if (value !== 'schedule' && value !== 'meeting') {
+        throw new VertuError('--event-type 需为 schedule 或 meeting。');
+    }
+    return value;
+}
+function optionalRecurrenceScope(raw) {
+    const value = raw?.trim();
+    if (!value) {
+        return undefined;
+    }
+    if (value !== 'current' && value !== 'series') {
+        throw new VertuError('--recurrence-scope 需为 current 或 series。');
+    }
+    return value;
+}
+function responseStatus(raw) {
+    const value = raw?.trim();
+    if (value === 'accepted' || value === 'declined' || value === 'tentative') {
+        return value;
+    }
+    throw new VertuError('--status 需为 accepted、declined 或 tentative。');
+}
+function optionalInteger(raw, flag) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isSafeInteger(value)) {
+        throw new VertuError(`${flag} 需为整数。`);
+    }
+    return value;
+}
+function optionalReminderMinutes(raw) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = raw.trim().toLocaleLowerCase();
+    const tokens = value.split(/[,，\s]+/).filter(Boolean);
+    if (tokens.includes('none') || tokens.includes('无') || tokens.length === 0) {
+        return [];
+    }
+    const aliases = new Map([
+        ['start', 0], ['0', 0],
+        ['5m', 5], ['5', 5],
+        ['15m', 15], ['15', 15],
+        ['1h', 60], ['60', 60],
+        ['1d', 1440], ['1440', 1440],
+    ]);
+    const selected = new Set();
+    for (const token of tokens) {
+        const minutes = aliases.get(token);
+        if (minutes === undefined) {
+            throw new VertuError('--reminder-minutes 仅支持 none、start、5m、15m、1h、1d，或 0/5/15/60/1440。');
+        }
+        selected.add(minutes);
+    }
+    return [0, 5, 15, 60, 1440].filter((minutes) => selected.has(minutes));
+}
+function putDefined(target, key, value) {
+    if (value !== undefined) {
+        target[key] = value;
+    }
+}
+function participantsFromOptions(requiredRaw, optionalRaw) {
+    if (requiredRaw === undefined && optionalRaw === undefined) {
+        return undefined;
+    }
+    const participants = new Map();
+    for (const userId of requiredRaw === undefined
+        ? []
+        : parseUserIdList(requiredRaw, '--participant-user-ids')) {
+        participants.set(userId, { user_id: userId, optional: false });
+    }
+    for (const userId of optionalRaw === undefined
+        ? []
+        : parseUserIdList(optionalRaw, '--optional-user-ids')) {
+        participants.set(userId, { user_id: userId, optional: true });
+    }
+    return [...participants.values()];
+}
+async function calendarMutationBody(opts) {
+    const body = {};
+    putDefined(body, 'calendar_id', opts.calendarId?.trim() || undefined);
+    putDefined(body, 'title', opts.title?.trim() || undefined);
+    putDefined(body, 'event_type', optionalEventType(opts.eventType));
+    putDefined(body, 'starts_at', optionalDateTime(opts.startsAt, '--starts-at'));
+    putDefined(body, 'ends_at', optionalDateTime(opts.endsAt, '--ends-at'));
+    putDefined(body, 'all_day', optionalBoolean(opts.allDay, '--all-day'));
+    putDefined(body, 'time_zone', opts.timeZone?.trim() || undefined);
+    putDefined(body, 'location', opts.location);
+    putDefined(body, 'description', opts.description);
+    putDefined(body, 'recurrence_rule', opts.recurrenceRule);
+    putDefined(body, 'recurrence_scope', optionalRecurrenceScope(opts.recurrenceScope));
+    putDefined(body, 'occurrence_at', optionalDateTime(opts.occurrenceAt, '--occurrence-at'));
+    putDefined(body, 'drag_origin_at', optionalDateTime(opts.dragOriginAt, '--drag-origin-at'));
+    putDefined(body, 'calendar_day_shift', optionalInteger(opts.calendarDayShift, '--calendar-day-shift'));
+    putDefined(body, 'meeting_url', opts.meetingUrl);
+    putDefined(body, 'ai_minutes_enabled', optionalBoolean(opts.aiMinutesEnabled, '--ai-minutes-enabled'));
+    putDefined(body, 'reminder_minutes', optionalReminderMinutes(opts.reminderMinutes));
+    putDefined(body, 'participants', participantsFromOptions(opts.participantUserIds, opts.optionalUserIds));
+    putDefined(body, 'push_to_participants', optionalBoolean(opts.pushToParticipants, '--push-to-participants'));
+    return mergeShortcutParams(body, opts);
+}
+function validateCreateBody(body) {
+    body.title = nonEmpty(typeof body.title === 'string' ? body.title : undefined, '--title');
+    body.starts_at = requiredDateTime(typeof body.starts_at === 'string' ? body.starts_at : undefined, '--starts-at');
+    body.ends_at = requiredDateTime(typeof body.ends_at === 'string' ? body.ends_at : undefined, '--ends-at');
+    if (Date.parse(String(body.ends_at)) <= Date.parse(String(body.starts_at))) {
+        throw new VertuError('--ends-at 必须晚于 --starts-at。');
+    }
+}
+function validateUpdateBody(body) {
+    if ('title' in body) {
+        body.title = nonEmpty(typeof body.title === 'string' ? body.title : undefined, '--title');
+    }
+    if ('starts_at' in body) {
+        body.starts_at = requiredDateTime(typeof body.starts_at === 'string' ? body.starts_at : undefined, '--starts-at');
+    }
+    if ('ends_at' in body) {
+        body.ends_at = requiredDateTime(typeof body.ends_at === 'string' ? body.ends_at : undefined, '--ends-at');
+    }
+    if (Object.keys(body).length === 0) {
+        throw new VertuError('至少提供一个要修改的字段。');
+    }
+}
+function attachCalendarMutationOptions(command, update) {
+    if (update) {
+        command
+            .requiredOption('--event-id <id>', '日程 UUID')
+            .option('--title <text>', '日程主题')
+            .option('--starts-at <iso>', '开始时间，例如 2026-07-24T09:00+08:00')
+            .option('--ends-at <iso>', '结束时间，例如 2026-07-24T10:00+08:00');
+    }
+    else {
+        command
+            .requiredOption('--title <text>', '日程主题')
+            .requiredOption('--starts-at <iso>', '开始时间；无时区时按 Asia/Shanghai')
+            .requiredOption('--ends-at <iso>', '结束时间；无时区时按 Asia/Shanghai')
+            .option('--calendar-id <id>', '日历 UUID；省略则使用默认日历');
+    }
+    return command
+        .option('--event-type <type>', 'schedule|meeting')
+        .option('--all-day <boolean>', '是否全天，true|false')
+        .option('--time-zone <zone>', '时区，默认 Asia/Shanghai')
+        .option('--location <text>', '地点；更新时传空字符串可清空')
+        .option('--description <text>', '描述；更新时传空字符串可清空')
+        .option('--meeting-url <url>', '会议链接；更新时传空字符串可清空')
+        .option('--ai-minutes-enabled <boolean>', '是否开启 AI 纪要，true|false')
+        .option('--reminder-minutes <list>', '多选提醒：none|start|5m|15m|1h|1d，逗号分隔；none 清空其他提醒')
+        .option('--recurrence-rule <rule>', '重复规则；更新时传空字符串可清空')
+        .option('--recurrence-scope <scope>', '重复日程拖动范围：current|series')
+        .option('--occurrence-at <iso>', '重复日程当前实例的原始时间')
+        .option('--drag-origin-at <iso>', '整组拖动前的实例时间')
+        .option('--calendar-day-shift <n>', '整组重复日程移动的自然日数')
+        .option('--participant-user-ids <list>', '必选参与人 user_id，逗号分隔或 JSON 数组')
+        .option('--optional-user-ids <list>', '可选参与人 user_id，逗号分隔或 JSON 数组')
+        .option('--push-to-participants <boolean>', '是否发送日程通知，true|false');
+}
+function validatePersonTarget(opts) {
+    const userId = positiveUserId(opts.userId, '--user-id');
+    const name = opts.name?.trim() || undefined;
+    if (userId && name) {
+        throw new VertuError('--user-id 与 --name 只能传一个。');
+    }
+    if (!userId && !name) {
+        throw new VertuError('请传 --user-id <id> 或 --name <姓名>。');
+    }
+    return { userId, name };
+}
+async function directoryUsers(query, serviceBaseUrl) {
+    const payload = asRecord(await imRequest('GET', '/v1/im/org/users', {
+        baseUrl: serviceBaseUrl,
+        query,
+    })) ?? {};
+    return recordArray(payload.users).flatMap((row) => {
+        const userId = Number(row.user_id);
+        return Number.isInteger(userId) && userId > 0
+            ? [{
+                    user_id: userId,
+                    employee_name: typeof row.employee_name === 'string' ? row.employee_name : null,
+                    login: typeof row.login === 'string' ? row.login : null,
+                    barcode: typeof row.barcode === 'string' ? row.barcode : null,
+                    department_name: typeof row.department_name === 'string' ? row.department_name : null,
+                }]
+            : [];
+    });
+}
+async function resolvePerson(opts, serviceBaseUrl) {
+    const { userId, name } = validatePersonTarget(opts);
+    if (userId) {
+        return (await directoryUsers({ user_ids: userId }, serviceBaseUrl))[0] ?? { user_id: userId };
+    }
+    // validatePersonTarget guarantees one selector is present.
+    const queryName = name;
+    const users = await directoryUsers({ query: queryName, limit: 20 }, serviceBaseUrl);
+    const normalized = queryName.toLocaleLowerCase();
+    const exact = users.filter((user) => [user.employee_name, user.login, user.barcode]
+        .some((value) => value?.toLocaleLowerCase() === normalized));
+    const matches = exact.length ? exact : users;
+    if (matches.length === 0) {
+        throw new VertuError(`未找到人员：${queryName}`);
+    }
+    if (matches.length > 1) {
+        const candidates = matches
+            .slice(0, 8)
+            .map((user) => `${user.employee_name ?? user.login ?? '未命名'}(${user.user_id})`)
+            .join('、');
+        throw new VertuError(`人员不唯一，请改用 --user-id：${candidates}`);
+    }
+    return matches[0];
+}
+async function queryPersonAvailability(user, range, serviceBaseUrl) {
+    const rows = [];
+    let cursor = Date.parse(range.start);
+    const end = Date.parse(range.endExclusive);
+    while (cursor < end) {
+        const chunkEnd = Math.min(cursor + AVAILABILITY_RANGE_DAYS * DAY_MS, end);
+        const payload = asRecord(await imRequest('GET', '/v1/calendar/availability', {
+            baseUrl: serviceBaseUrl,
+            query: {
+                user_ids: user.user_id,
+                start: new Date(cursor).toISOString(),
+                end: new Date(chunkEnd).toISOString(),
+            },
+        })) ?? {};
+        rows.push(...recordArray(payload.busy).filter((row) => Number(row.user_id) === user.user_id));
+        cursor = chunkEnd;
+    }
+    const unique = new Map();
+    for (const row of rows) {
+        unique.set(`${String(row.event_id)}:${String(row.user_id)}:${String(row.starts_at)}`, row);
+    }
+    return [...unique.values()].sort((a, b) => String(a.starts_at ?? '').localeCompare(String(b.starts_at ?? '')));
+}
+export function attachCalendarShortcuts(parent) {
+    attachSharedShortcutOptions(parent
+        .command('+mine')
+        .alias('+agenda')
+        .description('查看指定日期范围内我的可见日程（默认今天）')
+        .option('--start-date <ymd>', '开始日期 YYYY-MM-DD，默认今天')
+        .option('--end-date <ymd>', '结束日期 YYYY-MM-DD，默认与开始日期相同')).action(async (opts, cmd) => {
+        const range = resolveDateRange(opts);
+        const query = { start: range.start, end: range.endExclusive };
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        if (isDryRun(opts)) {
+            printPreview(opts, `${serviceBaseUrl}/v1/calendar`, query);
+            return;
+        }
+        const payload = await imRequest('GET', '/v1/calendar', {
+            baseUrl: serviceBaseUrl,
+            query,
+        });
+        printImResult(opts.json, decorateEvents(payload, 'mine', range));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+person')
+        .description('按 user_id 或姓名查看某个人的忙碌日程')
+        .option('--user-id <id>', 'VPS 用户 ID')
+        .option('--name <name>', '姓名、登录名或工号；必须唯一')
+        .option('--start-date <ymd>', '开始日期 YYYY-MM-DD，默认今天')
+        .option('--end-date <ymd>', '结束日期 YYYY-MM-DD，默认与开始日期相同')).action(async (opts, cmd) => {
+        const range = resolveDateRange(opts);
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        if (isDryRun(opts)) {
+            const { userId, name } = validatePersonTarget(opts);
+            printPreview(opts, `${serviceBaseUrl}/v1/calendar/availability`, {
+                user_ids: userId ?? `<resolve:${name}>`,
+                start: range.start,
+                end: range.endExclusive,
+                chunk_days: AVAILABILITY_RANGE_DAYS,
+            });
+            return;
+        }
+        const user = await resolvePerson(opts, serviceBaseUrl);
+        const rows = await queryPersonAvailability(user, range, serviceBaseUrl);
+        printImResult(opts.json, {
+            ok: true,
+            scope: 'person',
+            target: user,
+            filter: {
+                start_date: range.startDate,
+                end_date: range.endDate,
+                time_zone: 'Asia/Shanghai',
+            },
+            rows,
+            summary: { events: rows.length },
+        });
+    });
+    attachSharedShortcutOptions(parent
+        .command('+calendar')
+        .description('查看指定日历在日期范围内的日程')
+        .requiredOption('--calendar-id <id>', '日历 UUID')
+        .option('--start-date <ymd>', '开始日期 YYYY-MM-DD，默认今天')
+        .option('--end-date <ymd>', '结束日期 YYYY-MM-DD，默认与开始日期相同')).action(async (opts, cmd) => {
+        const calendarId = opts.calendarId?.trim();
+        if (!calendarId) {
+            throw new VertuError('--calendar-id 为必填。');
+        }
+        const range = resolveDateRange(opts);
+        const query = { start: range.start, end: range.endExclusive };
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        if (isDryRun(opts)) {
+            printPreview(opts, `${serviceBaseUrl}/v1/calendar`, {
+                ...query,
+                client_filter_calendar_id: calendarId,
+            });
+            return;
+        }
+        const payload = await imRequest('GET', '/v1/calendar', {
+            baseUrl: serviceBaseUrl,
+            query,
+        });
+        printImResult(opts.json, decorateEvents(payload, 'calendar', range, calendarId));
+    });
+    attachSharedShortcutOptions(parent.command('+calendars').description('列出我有权查看的全部日历及成员')).action(async (opts, cmd) => {
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        if (isDryRun(opts)) {
+            printPreview(opts, `${serviceBaseUrl}/v1/calendar/calendars`, {});
+            return;
+        }
+        printImResult(opts.json, await imRequest('GET', '/v1/calendar/calendars', {
+            baseUrl: serviceBaseUrl,
+        }));
+    });
+    attachSharedShortcutOptions(attachCalendarMutationOptions(parent.command('+create').description('创建日程或会议'), false)).action(async (opts, cmd) => {
+        const body = await calendarMutationBody(opts);
+        validateCreateBody(body);
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        if (isDryRun(opts)) {
+            printMutationPreview(opts, 'POST', `${serviceBaseUrl}/v1/calendar`, body);
+            return;
+        }
+        printImResult(opts.json, await imRequest('POST', '/v1/calendar', {
+            baseUrl: serviceBaseUrl,
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+response')
+        .description('查看我对某个日程邀请的当前响应状态')
+        .requiredOption('--event-id <id>', '日程 UUID')).action(async (opts, cmd) => {
+        const eventId = nonEmpty(opts.eventId, '--event-id');
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        const endpoint = `/v1/calendar/${encodeURIComponent(eventId)}/response`;
+        if (isDryRun(opts)) {
+            printPreview(opts, `${serviceBaseUrl}${endpoint}`, {});
+            return;
+        }
+        printImResult(opts.json, await imRequest('GET', endpoint, {
+            baseUrl: serviceBaseUrl,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+respond')
+        .description('同意、拒绝或暂定一个日程邀请')
+        .requiredOption('--event-id <id>', '日程 UUID')
+        .requiredOption('--status <status>', 'accepted|declined|tentative')).action(async (opts, cmd) => {
+        const eventId = nonEmpty(opts.eventId, '--event-id');
+        const status = responseStatus(opts.status);
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        const endpoint = `/v1/calendar/${encodeURIComponent(eventId)}/response`;
+        const body = { status };
+        if (isDryRun(opts)) {
+            printMutationPreview(opts, 'PATCH', `${serviceBaseUrl}${endpoint}`, body);
+            return;
+        }
+        printImResult(opts.json, await imRequest('PATCH', endpoint, {
+            baseUrl: serviceBaseUrl,
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(attachCalendarMutationOptions(parent.command('+update').description('局部修改日程；未提供的字段保持不变'), true)).action(async (opts, cmd) => {
+        const eventId = nonEmpty(opts.eventId, '--event-id');
+        const body = await calendarMutationBody(opts);
+        validateUpdateBody(body);
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        const endpoint = `/v1/calendar/${encodeURIComponent(eventId)}`;
+        if (isDryRun(opts)) {
+            printMutationPreview(opts, 'PATCH', `${serviceBaseUrl}${endpoint}`, body);
+            return;
+        }
+        printImResult(opts.json, await imRequest('PATCH', endpoint, {
+            baseUrl: serviceBaseUrl,
+            body,
+        }));
+    });
+    attachSharedShortcutOptions(parent
+        .command('+availability')
+        .description('查看多人忙闲（单次最多 50 人、8 天）')
+        .requiredOption('--user-ids <list>', 'user_id，逗号分隔或 JSON 数组')
+        .option('--start-date <ymd>', '开始日期 YYYY-MM-DD，默认今天')
+        .option('--end-date <ymd>', '结束日期 YYYY-MM-DD，默认与开始日期相同')
+        .option('--exclude-event-id <id>', '排除正在编辑的事件 UUID')).action(async (opts, cmd) => {
+        const userIds = [...new Set(parseUserIdList(opts.userIds, '--user-ids'))];
+        if (userIds.length > 50) {
+            throw new VertuError('--user-ids 最多 50 人。');
+        }
+        const range = resolveDateRange(opts, AVAILABILITY_RANGE_DAYS);
+        const query = {
+            user_ids: userIds.join(','),
+            start: range.start,
+            end: range.endExclusive,
+            exclude_event_id: opts.excludeEventId?.trim() || undefined,
+        };
+        const serviceBaseUrl = baseUrl(opts, cmd);
+        if (isDryRun(opts)) {
+            printPreview(opts, `${serviceBaseUrl}/v1/calendar/availability`, query);
+            return;
+        }
+        printImResult(opts.json, await imRequest('GET', '/v1/calendar/availability', {
+            baseUrl: serviceBaseUrl,
+            query,
+        }));
+    });
+}

package/dist/packages/vps-work/src/commands/catalog.js

@@ -0,0 +1,29 @@
+import { Command } from 'commander';
+import { CLI_BIN } from '../core/cli-bin.js';
+import { fetchExecuteCatalog } from '../core/execute-catalog-client.js';
+import { resolveVpsServiceUrl } from '../core/sales-query-client.js';
+/** 让 Agent 先查活目录，而不是依赖本机 --help 或过期 Skill 表。 */
+export function buildCatalogCommand() {
+    return new Command('catalog')
+        .description('列出当前企业身份可用的命令（服务端裁剪，无需升级 CLI）')
+        .option('--domain <name>', '只看某个域，如 sales / im / hr')
+        .option('--json', '机读输出', true)
+        .option('--no-json', '人类可读表格')
+        .action(async (opts, cmd) => {
+        const merged = cmd.optsWithGlobals();
+        const catalog = await fetchExecuteCatalog(opts.baseUrl ?? merged.baseUrl ?? resolveVpsServiceUrl(), opts.domain);
+        if (opts.json !== false) {
+            console.log(JSON.stringify(catalog, null, 2));
+            return;
+        }
+        console.log(`企业类型 : ${catalog.tenant_type}`);
+        console.log(`产品包   : ${catalog.product_profile}`);
+        console.log(`目录版本 : ${catalog.revision}`);
+        console.log('');
+        for (const item of catalog.shortcuts) {
+            const cli = item.cli ? `${CLI_BIN} ${item.cli}` : `${CLI_BIN} exec --skill ${item.skill_key} --script ${item.script_key}`;
+            console.log(`${item.domain}\t${item.script_key}\t${item.summary}\t${cli}`);
+        }
+        console.log(`\n共 ${catalog.count} 条。transport=execute 的条目用 ${CLI_BIN} exec 执行。`);
+    });
+}