vps-work 2.4.1 → 2.5.1

package/dist/packages/vps-work/src/commands/hr/job-responsibilities.js

@@ -0,0 +1,266 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { z } from 'zod';
+import { VertuError } from '../../core/errors.js';
+import { vpsServiceGet } from '../../core/sales-query-client.js';
+import { attachSharedShortcutOptions, mergeShortcutParams, resolveShortcutVpsServiceUrl, } from '../shortcut-common.js';
+const POSITION_DOCS_PATH = '/v1/workbench/position-docs';
+const summarySchema = z.object({
+    id: z.number().int().positive(),
+    title: z.string(),
+    updated_at: z.string().nullable(),
+}).passthrough();
+const employeeSchema = z.object({
+    user_id: z.number().int().positive(),
+    barcode: z.string(),
+    name: z.string(),
+    position: z.string(),
+    department_id: z.number().int().nullable(),
+    department_name: z.string(),
+    department_path: z.string(),
+    profile_doc: summarySchema.nullable(),
+    sop_doc: summarySchema.nullable(),
+});
+const documentSchema = summarySchema.extend({
+    odoo_user_id: z.number().int().positive(),
+    doc_type: z.enum(['profile', 'sop']),
+    content_md: z.string().nullable().optional(),
+    content_json: z.unknown(),
+}).passthrough();
+const responseSchema = z.object({
+    ok: z.literal(true),
+    can_manage_all: z.boolean(),
+    viewer_user_id: z.number().int().positive(),
+    selected_user_id: z.number().int().positive(),
+    selected_employee: employeeSchema.nullable(),
+    employees: z.array(employeeSchema),
+    counts: z.object({ employees: z.number().int().nonnegative() }),
+    docs: z.object({ profile: documentSchema.nullable(), sop: documentSchema.nullable() }),
+});
+const optionalText = z.string().trim().min(1).optional();
+const positiveInteger = z.union([z.string().regex(/^[1-9]\d*$/).transform(Number), z.number()])
+    .pipe(z.number().int().positive().max(Number.MAX_SAFE_INTEGER));
+const querySchema = z.object({
+    department: optionalText,
+    include_children: z.boolean().default(true),
+    job: optionalText,
+    name: optionalText,
+    barcode: optionalText,
+    user_id: positiveInteger.optional(),
+    my: z.boolean().default(false),
+    all: z.boolean().default(false),
+    page: positiveInteger.default(1),
+    limit: positiveInteger.pipe(z.number().max(100)).default(20),
+    doc_type: z.enum(['profile', 'sop', 'all']).default('profile'),
+    summary_only: z.boolean().default(false),
+}).strict();
+export function normalizeJobResponsibilitiesQuery(input) {
+    const result = querySchema.safeParse(input);
+    if (!result.success) {
+        const issue = result.error.issues[0];
+        throw new VertuError(`岗位职责查询参数无效：${issue?.path.join('.') || 'params'} ${issue?.message ?? ''}`);
+    }
+    const query = result.data;
+    const hasFilter = [query.department, query.job, query.name, query.barcode, query.user_id].some(v => v !== undefined);
+    if (query.my && hasFilter)
+        throw new VertuError('--my 不能与部门、岗位或其他个人筛选同时使用。');
+    if (query.all && query.page !== 1)
+        throw new VertuError('--all 不能与大于 1 的 --page 同时使用。');
+    if (!Number.isSafeInteger((query.page - 1) * query.limit))
+        throw new VertuError('--page 超出有效范围。');
+    if (query.department && !departmentParts(query.department).length)
+        throw new VertuError('--department 不能为空部门路径。');
+    if (!hasFilter && !query.all)
+        query.my = true;
+    return query;
+}
+function departmentParts(value) {
+    return value.split('/').map(v => v.trim().toLocaleLowerCase()).filter(Boolean);
+}
+function matchesEmployee(employee, query, viewerUserId) {
+    if (query.my && employee.user_id !== viewerUserId)
+        return false;
+    if (query.user_id !== undefined && employee.user_id !== query.user_id)
+        return false;
+    if (query.name && employee.name.trim() !== query.name)
+        return false;
+    if (query.barcode && employee.barcode.trim() !== query.barcode)
+        return false;
+    if (query.job && !employee.position.toLocaleLowerCase().includes(query.job.toLocaleLowerCase()))
+        return false;
+    if (query.department) {
+        const wanted = departmentParts(query.department);
+        const actual = departmentParts(employee.department_path || employee.department_name);
+        // Match complete path segments, so AI业务 never includes sibling AI业务中台.
+        const found = actual.some((_, start) => wanted.every((part, offset) => part === actual[start + offset])
+            && (query.include_children || start + wanted.length === actual.length));
+        if (!found)
+            return false;
+    }
+    return true;
+}
+function parseResponse(payload) {
+    const parsed = responseSchema.safeParse(payload);
+    if (!parsed.success)
+        throw new VertuError('岗位文档接口返回的数据结构无效，未输出查询结果。');
+    const data = parsed.data;
+    if (data.employees.length >= 5000 || data.counts.employees !== data.employees.length) {
+        throw new VertuError('岗位人员列表可能被截断，无法确认完整查询范围。');
+    }
+    if (new Set(data.employees.map(e => e.user_id)).size !== data.employees.length) {
+        throw new VertuError('岗位人员列表存在重复用户编号。');
+    }
+    if (!data.can_manage_all && data.employees.some(e => e.user_id !== data.viewer_user_id)) {
+        throw new VertuError('岗位人员列表与当前会话的本人范围不一致。');
+    }
+    return data;
+}
+function checkedDocuments(data, initial, employee) {
+    const selected = data.selected_employee;
+    if (data.viewer_user_id !== initial.viewer_user_id || data.can_manage_all !== initial.can_manage_all
+        || data.selected_user_id !== employee.user_id || selected?.user_id !== employee.user_id) {
+        throw new VertuError(`岗位文档归属不一致（用户 ${employee.user_id}），已停止查询。`);
+    }
+    for (const key of ['name', 'barcode', 'position', 'department_id', 'department_path']) {
+        if (selected[key] !== employee[key])
+            throw new VertuError('查询期间人员档案发生变化，请重试。');
+    }
+    for (const type of ['profile', 'sop']) {
+        const doc = data.docs[type];
+        const summary = employee[`${type}_doc`];
+        if ((doc?.id ?? null) !== (summary?.id ?? null)
+            || (doc?.updated_at ?? null) !== (summary?.updated_at ?? null)
+            || (doc?.id ?? null) !== (selected[`${type}_doc`]?.id ?? null)) {
+            throw new VertuError(`查询期间岗位文档发生变化（用户 ${employee.user_id}），请重试。`);
+        }
+        if (doc && (doc.odoo_user_id !== employee.user_id || doc.doc_type !== type)) {
+            throw new VertuError(`岗位文档归属不一致（用户 ${employee.user_id}），已停止查询。`);
+        }
+        if (doc && !doc.content_md?.trim() && doc.content_json == null) {
+            throw new VertuError(`岗位文档 ${doc.id} 内容为空，无法导出完整职责。`);
+        }
+    }
+    return data.docs;
+}
+export async function queryJobResponsibilities(query, baseUrl) {
+    const fetchDocs = async (userId) => parseResponse(await vpsServiceGet(POSITION_DOCS_PATH, { odoo_user_id: userId }, baseUrl, '岗位职责查询'));
+    const initial = await fetchDocs();
+    const matches = initial.employees.filter(e => matchesEmployee(e, query, initial.viewer_user_id))
+        .sort((a, b) => a.department_path.localeCompare(b.department_path, 'zh-CN')
+        || a.position.localeCompare(b.position, 'zh-CN') || a.name.localeCompare(b.name, 'zh-CN') || a.user_id - b.user_id);
+    if (query.name && matches.length > 1) {
+        throw new VertuError(`姓名“${query.name}”匹配到 ${matches.length} 人，请用 --user-id、--barcode 或部门条件区分。`);
+    }
+    if (query.barcode && matches.length > 1)
+        throw new VertuError('工号匹配到多个人员，请用 --user-id 区分。');
+    const offset = query.all ? 0 : (query.page - 1) * query.limit;
+    const selected = query.all ? matches : matches.slice(offset, offset + query.limit);
+    const types = query.doc_type === 'all' ? ['profile', 'sop'] : [query.doc_type];
+    const rows = [];
+    // Bound detail requests; fetch only the chosen page and never fetch bodies in summary mode.
+    for (let start = 0; start < selected.length; start += 4) {
+        const batch = await Promise.allSettled(selected.slice(start, start + 4).map(async (employee) => {
+            if (query.summary_only)
+                return employee;
+            const response = initial.selected_user_id === employee.user_id ? initial : await fetchDocs(employee.user_id);
+            const docs = checkedDocuments(response, initial, employee);
+            return { ...employee, documents: Object.fromEntries(types.map(type => [type, docs[type]])) };
+        }));
+        for (const result of batch) {
+            if (result.status === 'rejected')
+                throw result.reason;
+            rows.push(result.value);
+        }
+    }
+    const profileCount = matches.filter(e => e.profile_doc).length;
+    const sopCount = matches.filter(e => e.sop_doc).length;
+    return {
+        ok: true,
+        source: 'vps-position-documents',
+        queried_at: new Date().toISOString(),
+        scope: {
+            viewer_user_id: initial.viewer_user_id,
+            can_manage_all: initial.can_manage_all,
+            description: initial.can_manage_all ? '岗位文档页面可见的当前在职人员' : '岗位文档页面可见的本人在职档案',
+        },
+        filters: query,
+        summary: {
+            employees: matches.length,
+            profile_documents: profileCount,
+            missing_profile_documents: matches.length - profileCount,
+            sop_documents: sopCount,
+            missing_sop_documents: matches.length - sopCount,
+        },
+        pagination: {
+            page: query.all ? 1 : query.page,
+            page_size: query.all ? matches.length : query.limit,
+            total_rows: matches.length,
+            returned_rows: rows.length,
+            has_more: offset + rows.length < matches.length,
+        },
+        rows,
+    };
+}
+function plainResult(result) {
+    const lines = [
+        '# 岗位职责查询', '',
+        `范围：${result.scope.description}。匹配 ${result.pagination.total_rows} 人，本次返回 ${result.pagination.returned_rows} 人。`,
+        `岗位说明 ${result.summary.profile_documents} 份，缺失 ${result.summary.missing_profile_documents} 份；SOP ${result.summary.sop_documents} 份，缺失 ${result.summary.missing_sop_documents} 份。`,
+        result.pagination.has_more ? '还有后续结果，请使用 --page 翻页或 --all 查询全部匹配人员。' : '',
+    ];
+    for (const row of result.rows) {
+        lines.push('', `## ${row.name} — ${row.position}`, `部门：${row.department_path}；用户编号：${row.user_id}；工号：${row.barcode}`);
+        if (!row.documents) {
+            lines.push(`岗位说明：${row.profile_doc ? '有文档' : '缺失'}；SOP：${row.sop_doc ? '有文档' : '缺失'}（仅返回清单，未读取正文）。`);
+            continue;
+        }
+        for (const [type, doc] of Object.entries(row.documents)) {
+            lines.push('', `### ${type === 'profile' ? '岗位说明' : 'SOP'}`);
+            if (!doc)
+                lines.push('系统当前未提供此文档。');
+            else
+                lines.push(`文档编号：${doc.id}；更新时间：${doc.updated_at ?? '未知'}`, '', doc.content_md?.trim() || JSON.stringify(doc.content_json, null, 2));
+        }
+    }
+    return lines.join('\n');
+}
+export function attachJobResponsibilitiesShortcut(parent) {
+    attachSharedShortcutOptions(parent.command('+job-responsibilities')
+        .alias('+position-docs')
+        .description('岗位职责/岗位说明及 SOP；按部门、岗位或个人查询，默认本人')
+        .option('--department <name-or-path>', '部门名称或完整路径（按路径段精确匹配）')
+        .option('--no-include-children', '部门仅匹配本层，不含下属部门')
+        .option('--job <keyword>', '人员档案岗位关键词，包含匹配')
+        .option('--name <name>', '员工姓名精确匹配；重名需用部门或用户编号区分')
+        .option('--barcode <code>', '员工工号精确匹配')
+        .option('--user-id <id>', '用户编号（非 hr.employee 编号）')
+        .option('--my', '仅查询本人', false)
+        .option('--doc-type <type>', 'profile（岗位说明）、sop 或 all', 'profile')
+        .option('--summary-only', '仅返回文档清单及缺失状态，不读取正文', false)
+        .option('--page <n>', '页码，从 1 开始', '1')
+        .option('--limit <n>', '每页人数，1–100', '20')
+        .option('--all', '返回全部匹配人员，仍受当前账号可见范围限制', false)
+        .option('--output <path>', '保存为 UTF-8 文件；默认 JSON，--no-json 输出 Markdown'))
+        .action(async (opts, cmd) => {
+        const baseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+        const query = normalizeJobResponsibilitiesQuery(await mergeShortcutParams({
+            department: opts.department, include_children: opts.includeChildren, job: opts.job,
+            name: opts.name, barcode: opts.barcode, user_id: opts.userId, my: opts.my, all: opts.all,
+            page: opts.page, limit: opts.limit, doc_type: opts.docType, summary_only: opts.summaryOnly,
+        }, opts));
+        if (opts.validateOnly || opts.dryRun) {
+            console.log(JSON.stringify({ validateOnly: true, source: 'vps-position-documents', endpoint: `${baseUrl}${POSITION_DOCS_PATH}`, filters: query }, null, 2));
+            return;
+        }
+        const result = await queryJobResponsibilities(query, baseUrl);
+        const content = opts.json === false ? plainResult(result) : JSON.stringify(result, null, 2);
+        if (opts.output !== undefined) {
+            if (!opts.output.trim())
+                throw new VertuError('--output 不能为空路径。');
+            const output = resolve(opts.output);
+            await mkdir(dirname(output), { recursive: true });
+            await writeFile(output, `${content}\n`, 'utf8');
+        }
+        console.log(content);
+    });
+}

package/dist/packages/vps-work/src/commands/hr/payslip.js

@@ -0,0 +1,45 @@
+import { VertuError } from '../../core/errors.js';
+import { trySalesQueryExecute } from '../../core/sales-query-client.js';
+/** 规范化工资月份：接受 YYYY-MM 或 YYYY-MM-DD，统一为当月 1 日。 */
+export function normalizeSalaryMonth(raw) {
+    const t = raw.trim();
+    if (/^\d{4}-\d{2}-\d{2}$/.test(t)) {
+        return t;
+    }
+    if (/^\d{4}-\d{2}$/.test(t)) {
+        return `${t}-01`;
+    }
+    throw new VertuError(`Invalid salary month "${raw}": use YYYY-MM or YYYY-MM-DD (e.g. 2026-04 or 2026-04-01).`);
+}
+/**
+ * 查询工资条。工资条已迁到 VPS 原生 HR（vps_tenant_payslips），
+ * 只经 vps-service `execute(vps-hr-compensation-documents/payslip)` 读取 VPS 工资条。
+ * 身份解析与访问控制均在服务端完成：本人可查，他人需薪酬管理组及有效薪酬访问凭证。
+ * 管理员身份及 Agent Key 不豁免授权；无凭证时请在人事助手中解锁查看，不在对话中输入密码。
+ */
+export async function fetchPayslip(opts) {
+    const params = {
+        salary_month: normalizeSalaryMonth(opts.salaryMonth),
+        limit: opts.limit ?? 5,
+    };
+    if (opts.useMyEmployee) {
+        params.my = true;
+    }
+    if (opts.employeeId?.trim()) {
+        const id = Number.parseInt(opts.employeeId, 10);
+        if (!Number.isFinite(id)) {
+            throw new VertuError('Invalid --employee-id: expected an integer.');
+        }
+        params.employee_id = id;
+    }
+    if (opts.name?.trim()) {
+        params.name = opts.name.trim();
+    }
+    const result = await trySalesQueryExecute('vps-hr-compensation-documents', 'payslip', params, opts.baseUrl);
+    if (result === null) {
+        throw new VertuError('工资条查询需要 vps-service 地址', {
+            hint: '请先 vps-work login，或配置 ~/.vps-work/vps-service.json / VPS_SERVICE_URL。',
+        });
+    }
+    return result;
+}

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

@@ -0,0 +1,146 @@
+import { VertuError } from '../../core/errors.js';
+import { publicBusinessResult } from '../../core/public-result.js';
+import { runVpsServiceDataView, vpsServiceGet } from '../../core/sales-query-client.js';
+import { attachSharedShortcutOptions, parseOptionalInt, resolveShortcutVpsServiceUrl, } from '../shortcut-common.js';
+import { attachOrgStructureShortcut } from '../org-structure.js';
+import { applyHrDirectoryScope, assertHrDirectoryScopeApplied, } from './data-view-shortcuts.js';
+import { fetchPayslip } from './payslip.js';
+function printShortcutJson(opts, out) {
+    out = publicBusinessResult(out);
+    if (opts.json !== false) {
+        console.log(JSON.stringify(out, null, 2));
+    }
+    else {
+        console.log(typeof out === 'string' ? out : JSON.stringify(out));
+    }
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : null;
+}
+function rows(value) {
+    const record = asRecord(value);
+    const raw = record ? record.rows : undefined;
+    return Array.isArray(raw)
+        ? raw.filter((row) => asRecord(row) !== null)
+        : [];
+}
+function num(value) {
+    if (typeof value === 'number' && Number.isFinite(value)) {
+        return value;
+    }
+    if (typeof value === 'string' && value.trim()) {
+        const n = Number(value);
+        return Number.isFinite(n) ? n : null;
+    }
+    return null;
+}
+function str(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+async function currentHrIdentity(opts, cmd) {
+    const serviceBaseUrl = resolveShortcutVpsServiceUrl(opts, cmd);
+    const payload = asRecord(await vpsServiceGet('/v1/auth/me', {}, serviceBaseUrl, 'Vertu 身份')) ?? {};
+    const user = asRecord(payload.user) ?? {};
+    const userinfo = asRecord(payload.userinfo) ?? {};
+    const employeeId = num(user.employeeId) ?? num(userinfo.employee_id);
+    let profile = {};
+    let profileUnavailable;
+    if (employeeId) {
+        try {
+            const profileResult = await runVpsServiceDataView('hr-personnel-directory', applyHrDirectoryScope({ employee_id: employeeId }, opts.includeNonDirectory), 1, serviceBaseUrl);
+            assertHrDirectoryScopeApplied(profileResult, opts.includeNonDirectory);
+            profile = rows(profileResult)[0] ?? {};
+        }
+        catch (error) {
+            // HR 档案视图返回 503 表示当前环境该能力不可用，
+            // 身份主体仍来自平台会话，只降级掉档案补充字段，不让 +me 整体失败。
+            if (!(error instanceof VertuError) || error.statusCode !== 503) {
+                throw error;
+            }
+            profileUnavailable = error.message;
+        }
+    }
+    return {
+        ...(profileUnavailable ? { profile_unavailable: profileUnavailable } : {}),
+        user_id: num(user.userId) ?? num(userinfo.user_id),
+        login: str(user.login) ?? str(userinfo.login),
+        name: str(user.name) ?? str(userinfo.name) ?? str(user.employeeName) ?? str(userinfo.employee_name),
+        employee_id: employeeId,
+        employee_name: str(user.employeeName) ?? str(userinfo.employee_name) ?? str(profile.name),
+        barcode: str(user.barcode) ?? str(user.employeeNo) ?? str(userinfo.barcode) ?? str(profile.barcode),
+        job_title: str(user.jobTitle) ?? str(userinfo.job_title) ?? str(profile['工作岗位']),
+        job_id: num(profile.job_id),
+        job_name: str(profile['岗位名称']),
+        department_id: num(user.departmentId) ?? num(userinfo.department_id) ?? num(profile.department_id),
+        department_name: str(user.departmentName) ?? str(userinfo.department_name) ?? str(profile.current_name),
+        department_path: str(user.departmentPath) ?? str(userinfo.department_path),
+        department_chain: departmentChain(profile, str(user.departmentPath) ?? str(userinfo.department_path)),
+        manager_id: num(profile.manager_employee_id),
+        manager_name: str(profile['上级姓名']),
+        manager_user_id: num(profile.manager_user_id),
+        employment_started_at: str(userinfo.employment_started_at) ?? str(profile['入职日期']),
+        employment_ended_at: str(userinfo.employment_ended_at) ?? str(profile['离职日期']),
+        role: str(user.role) ?? str(userinfo.role),
+        active: typeof user.active === 'boolean' ? user.active : userinfo.active,
+        source: 'vertu',
+    };
+}
+/** 部门链优先取 HR 档案的四级部门；档案不可用时按平台 department_path（"A / B / C"）拆分。 */
+function departmentChain(profile, departmentPath) {
+    const fromProfile = [profile.one_name, profile.two_name, profile.three_name, profile.current_name]
+        .map((item) => str(item))
+        .filter((item, index, arr) => Boolean(item) && arr.indexOf(item) === index);
+    if (fromProfile.length) {
+        return fromProfile;
+    }
+    return (departmentPath ?? '').split('/').map((item) => item.trim()).filter(Boolean);
+}
+function employeeLineOptions(cmd, limitDefault = '20') {
+    return cmd
+        .option('--name <name>', 'Employee name (unique match)')
+        .option('--employee-id <id>', 'hr.employee id')
+        .option('--my', 'Current user (@my_employee)', false)
+        .option('--limit <n>', 'Max rows', limitDefault);
+}
+function requireEmployeeTarget(opts) {
+    if (!opts.my && !opts.employeeId && !opts.name?.trim()) {
+        throw new VertuError('Pass --name <姓名>, --employee-id <id>, or --my.');
+    }
+}
+function invokeOpts(opts, cmd) {
+    const merged = cmd.optsWithGlobals();
+    return {
+        baseUrl: opts.baseUrl ?? merged.baseUrl,
+        endpoint: opts.endpoint ?? merged.endpoint,
+    };
+}
+/** Features · 人力资源 — `vps-work hr +…`（vps-service：身份与工资条） */
+export function attachHrShortcuts(parent) {
+    attachSharedShortcutOptions(parent
+        .command('+me')
+        .description('当前用户身份（user/employee/department/manager）')
+        .option('--include-non-directory', '允许补充通讯录不可见的 HR 档案', false)).action(async (opts, cmd) => {
+        printShortcutJson(opts, await currentHrIdentity(opts, cmd));
+    });
+    attachOrgStructureShortcut(parent, '+org-tree', '组织部门树（默认一级/二级；用 --max-depth 0 查看全量）');
+    attachSharedShortcutOptions(employeeLineOptions(parent
+        .command('+payslip')
+        .description('月度工资条（VPS 原生 HR，本人可查，查他人需企业管理员）')
+        .requiredOption('--salary-month <ym>', 'YYYY-MM or YYYY-MM-DD'), '5')).action(async (opts, cmd) => {
+        requireEmployeeTarget(opts);
+        const month = opts.salaryMonth;
+        if (!month) {
+            throw new VertuError('--salary-month is required.');
+        }
+        printShortcutJson(opts, await fetchPayslip({
+            baseUrl: invokeOpts(opts, cmd).baseUrl,
+            salaryMonth: month,
+            name: opts.name,
+            employeeId: opts.employeeId,
+            useMyEmployee: !!opts.my,
+            limit: parseOptionalInt(opts.limit, '--limit') ?? 5,
+        }));
+    });
+}

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

@@ -0,0 +1,150 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { VertuError } from '../../core/errors.js';
+import { imRequest } from '../../core/im-client.js';
+import { expandAtFileToken } from '../../utils/at-file.js';
+import { parseJsonArg } from '../../utils/parse-json-arg.js';
+import { readStdinText, readUtf8File } from '../../utils/read-text.js';
+const EXT_MIME = {
+    '.png': 'image/png',
+    '.jpg': 'image/jpeg',
+    '.jpeg': 'image/jpeg',
+    '.gif': 'image/gif',
+    '.webp': 'image/webp',
+    '.svg': 'image/svg+xml',
+    '.pdf': 'application/pdf',
+    '.html': 'text/html',
+    '.htm': 'text/html',
+    '.md': 'text/markdown',
+    '.txt': 'text/plain',
+    '.csv': 'text/csv',
+    '.json': 'application/json',
+    '.doc': 'application/msword',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.xls': 'application/vnd.ms-excel',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.ppt': 'application/vnd.ms-powerpoint',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.zip': 'application/zip',
+    '.mp3': 'audio/mpeg',
+    '.wav': 'audio/wav',
+    '.mp4': 'video/mp4',
+    '.mov': 'video/quicktime',
+    '.webm': 'video/webm',
+};
+function guessMimetype(filePath) {
+    return EXT_MIME[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';
+}
+async function readBodyFromFileToken(token) {
+    if (token === '-') {
+        return readStdinText();
+    }
+    if (token.startsWith('@')) {
+        return expandAtFileToken(token, '--body-file');
+    }
+    return readUtf8File(path.resolve(token));
+}
+export async function resolveImMessageBody(opts) {
+    if (opts.bodyFile?.trim()) {
+        return (await readBodyFromFileToken(opts.bodyFile.trim())).trimEnd();
+    }
+    return opts.body?.trim() ?? '';
+}
+function normalizeAttachmentItem(item, index) {
+    if (typeof item !== 'object' || item === null || Array.isArray(item)) {
+        throw new VertuError(`attachments[${index}] 必须为对象。`);
+    }
+    const row = item;
+    const name = typeof row.name === 'string' ? row.name.trim() : '';
+    if (!name) {
+        throw new VertuError(`attachments[${index}].name 为必填。`);
+    }
+    const rawType = typeof row.attachment_type === 'string' ? row.attachment_type.trim() : 'file';
+    const allowed = ['image', 'file', 'audio', 'video', 'link', 'emoji', 'other'];
+    if (!allowed.includes(rawType)) {
+        throw new VertuError(`attachments[${index}].attachment_type 不支持: ${rawType}`);
+    }
+    return {
+        attachment_type: rawType,
+        name,
+        mime_type: typeof row.mime_type === 'string' ? row.mime_type.trim() : null,
+        size_bytes: typeof row.size_bytes === 'number' ? row.size_bytes : null,
+        url: typeof row.url === 'string' ? row.url.trim() : null,
+        storage_key: typeof row.storage_key === 'string' ? row.storage_key.trim() : null,
+        sha256: typeof row.sha256 === 'string' ? row.sha256.trim() : null,
+        metadata: typeof row.metadata === 'object' && row.metadata !== null && !Array.isArray(row.metadata)
+            ? row.metadata
+            : {},
+    };
+}
+export async function resolveImAttachments(attachPaths, attachmentsJson, baseUrl) {
+    const fromFiles = [];
+    for (const raw of attachPaths ?? []) {
+        const token = raw.trim();
+        if (!token)
+            continue;
+        const filePath = path.resolve(token.startsWith('@') ? token.slice(1) : token);
+        const buf = await readFile(filePath);
+        const mime = guessMimetype(filePath);
+        const name = path.basename(filePath);
+        const uploaded = await imRequest('POST', '/v1/im/files', {
+            baseUrl,
+            body: {
+                action: 'upload',
+                name,
+                mime_type: mime,
+                data_base64: buf.toString('base64'),
+            },
+        });
+        const file = typeof uploaded === 'object' && uploaded !== null && 'file' in uploaded
+            ? uploaded.file
+            : null;
+        if (typeof file !== 'object' || file === null || Array.isArray(file)) {
+            throw new VertuError(`文件上传成功但未返回文件信息：${name}`);
+        }
+        const attachment = normalizeAttachmentItem(file, fromFiles.length);
+        if (!attachment.url || !attachment.storage_key) {
+            throw new VertuError(`文件上传成功但缺少 url/storage_key：${name}`);
+        }
+        fromFiles.push({
+            ...attachment,
+            sha256: attachment.sha256 ||
+                createHash('sha256').update(buf).digest('hex'),
+        });
+    }
+    let fromJson = [];
+    if (attachmentsJson?.trim()) {
+        const parsed = parseJsonArg(attachmentsJson.trim(), '--attachments-json');
+        if (!Array.isArray(parsed)) {
+            throw new VertuError('--attachments-json 必须为 JSON 数组。');
+        }
+        fromJson = parsed.map((item, index) => normalizeAttachmentItem(item, index));
+    }
+    const merged = [...fromFiles, ...fromJson];
+    return merged.length ? merged : undefined;
+}
+export async function buildImMessagePayload(opts) {
+    const body = await resolveImMessageBody(opts);
+    const attachments = await resolveImAttachments(opts.attach, opts.attachmentsJson, opts.baseUrl);
+    if (!body && !attachments?.length) {
+        throw new VertuError('请提供 --body / --body-file，或至少一个 --attach / --attachments-json。');
+    }
+    return attachments?.length ? { body, attachments } : { body };
+}
+export function parseUserIdList(raw, label) {
+    if (!raw?.trim()) {
+        throw new VertuError(`${label} 为必填。`);
+    }
+    const trimmed = raw.trim();
+    const parts = trimmed.startsWith('[')
+        ? parseJsonArg(trimmed, label).map((item) => String(item))
+        : trimmed.split(/[,，\s]+/).filter(Boolean);
+    return parts.map((part, index) => {
+        const n = Number.parseInt(part, 10);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new VertuError(`Invalid ${label}[${index}]: expected a positive integer.`);
+        }
+        return n;
+    });
+}

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

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import { attachImShortcuts } from './shortcuts.js';
+export function buildImCommand() {
+    const im = new Command('im').description('Vertu IM shortcuts: private chat, groups, org channels, broadcast, bots.');
+    attachImShortcuts(im);
+    return im;
+}