vps-work 2.4.1 → 2.5.1

package/.well-known/skills/index.json

@@ -1,5 +1,16 @@
 {
   "skills": [
+    {"name":"vertu-aisales","description":"查询 VERTU 员工获授权的客户聊天记录、沟通摘要，分析客户跟进和成交障碍。通过 vps-work vertu-aisales 调用 AI Native Sales MCP；销售订单、业绩和回款数字使用销售业务技能。","files":["skills/vertu-aisales/SKILL.md"]},
+    {
+      "name": "vertu-erp",
+      "description": "通过 vps-work 调用当前账号获授权的 Vertu ERP MCP，查询业务表结构或执行只读 SQL。适用于明确需要 ERP 底层数据、已有业务命令不能覆盖的分析；常规业务报表优先使用对应业务技能。",
+      "files": ["skills/vertu-erp/SKILL.md"]
+    },
+    {
+      "name": "vps-dealer-ops",
+      "description": "经销商专用只读查询：本企业进销对比、五件套、业绩目标、产品排名与占比、提发货、自然进店，以及原账号授权的订单、库存、结算、合同付款和物流。不适用于其他企业、人事、考勤或业务写入。",
+      "files": ["skills/vps-dealer-ops/SKILL.md"]
+    },
     {
       "name": "vps-shared",
       "description": "vps-work 共用约定：登录、当前用户身份、活目录 catalog / exec、数据查询与反馈。业务域技能开始前应先读本文件。",

package/README.md

@@ -214,6 +214,10 @@ vps-work skill +delete-personal --slug sales-follow-up
 | `vps-work auth use --tenant <uuid>` | 切换当前企业；Agent 不得自行执行 |
 | `vps-work catalog [--domain sales]` | 当前企业身份可见的活目录（服务端裁剪） |
 | `vps-work exec --skill <key> --script <key>` | 按 catalog 执行，不必为每个新脚本发 npm |
+| `vps-work vertu-aisales tools` | 获取当前企业获授权的客户沟通工具及参数 schema |
+| `vps-work vertu-aisales call --tool <name> --args @params.json` | 按可见员工范围查询聊天；多个实例用 `--service-id` 指定 |
+| `vps-work vertu-erp tools` | 获取当前账号授权的 ERP MCP 工具及参数 schema |
+| `vps-work vertu-erp call --tool <name> --args @params.json` | 调用 ERP 只读工具，参数按实时 schema 填写；支持 `@-` 标准输入 |
 | `vps-work install [--tag latest]` | 执行 `npm install -g vps-work@<tag>`（与 `npx vps-work@latest install` 等价） |
 
 CI / 自动化常用环境变量：`VERTU_BOT_INBOUND_KEY`（Bearer）、`VERTU_APP_ID` + `VERTU_APP_KEY`（App Key）。
@@ -244,6 +248,12 @@ CI / 自动化常用环境变量：`VERTU_BOT_INBOUND_KEY`（Bearer）、`VERTU_
 
 完整列表：`vps-work sales --help`（各域同理）。
 
+ERP 统一经 `vps-work` 调用平台 `/hermes-console/api/platform-tools/vertu-erp`。服务端使用当前登录身份，逐次验证原企业、有效成员和 `vertu-erp:super-read` 显式授权。无需 ERP 插件或 Secure 执行池，不下发个人 MCP bearer，也没有指定账号例外；旧 MCP 地址返回 410。仅提供 `erp-query`、`erp-list-tables`、`erp-table-columns`，参数以 `vertu-erp tools` 为准。上游数据库凭证仅存服务端；只读保证须由数据库角色执行。
+
+配套技能为 `vertu-erp`。常规业务优先使用已有业务命令；确需 ERP 底层分析时才调用此入口。这里的广泛查询能力依赖已有服务端授权，没有客户端“全权限”开关，也不补充 Odoo 行级规则或授予数据库写权限。
+
+企业专用集成的命令与技能统一使用企业前缀：ERP 为 `vertu-erp`；AI Native Sales 为 `vertu-aisales`。企业前缀表示能力归属，不替代服务端租户和账号授权。
+
 常见查询示例：
 
 ```bash

package/dist/packages/vps-work/src/bin/vps-work.js

@@ -0,0 +1,271 @@
+import { Command } from 'commander';
+import { buildPurchaseCommand } from '../commands/purchase/index.js';
+import { formatErrorForCli, VertuError } from '../core/errors.js';
+import { buildAuthCommand } from '../commands/auth/index.js';
+import { buildAgentCommand } from '../commands/agent/index.js';
+import { buildApprovalCommand } from '../commands/approval/index.js';
+import { buildImCommand } from '../commands/im/index.js';
+import { buildMailCommand } from '../commands/mail/index.js';
+import { buildOkrCommand } from '../commands/okr/index.js';
+import { buildReportCommand } from '../commands/report/index.js';
+import { buildAttendanceCommand } from '../commands/attendance/index.js';
+import { buildTaskCommand } from '../commands/task/index.js';
+import { buildToolsCommand } from '../commands/tools/index.js';
+// `dev` 命令已弃用并并入 `task`（task-center / task-assistant 直连库）。
+import { buildHrCommand } from '../commands/hr/index.js';
+import { buildProductCommand } from '../commands/product/index.js';
+import { buildSalesCommand } from '../commands/sales/index.js';
+import { buildStoreCommand } from '../commands/store/index.js';
+import { buildVemoryCommand } from '../commands/vemory/index.js';
+import { buildMeetingCommand } from '../commands/meeting/index.js';
+import { buildCalendarCommand } from '../commands/calendar/index.js';
+import { buildCreativeCommand } from '../commands/creative/index.js';
+import { buildCorporateCommand } from '../commands/corporate/index.js';
+import { buildDocumentsCommand } from '../commands/documents/index.js';
+import { buildOfficeCommand } from '../commands/office/index.js';
+import { buildKnowledgeCommand } from '../commands/knowledge/index.js';
+import { buildDriveCommand } from '../commands/drive/index.js';
+import { buildPopupCommand } from '../commands/popup/index.js';
+import { buildSkillCommand } from '../commands/skill/index.js';
+import { buildCatalogCommand } from '../commands/catalog.js';
+import { buildExecCommand } from '../commands/exec.js';
+import { buildVertuAiSalesCommand } from '../commands/vertu-aisales.js';
+import { buildVertuErpCommand } from '../commands/vertu-erp.js';
+import { buildCliInstallCommand } from '../commands/cli-install.js';
+import { CLI_BIN, CLI_BIN_ALIASES } from '../core/cli-bin.js';
+import { buildCliRootHelpAfter, buildCliRootHelpBefore } from '../core/cli-root-help.js';
+import { normalizeSnakeFlags } from '../utils/normalize-argv.js';
+const PKG_VERSION = typeof __VERTU_VERSION__ === 'string' && __VERTU_VERSION__ ? __VERTU_VERSION__ : '0.0.0-dev';
+/**
+ * Compute a suggestion for an unknown long flag.
+ *
+ * commander 13's built-in `suggestSimilar` uses Damerau–Levenshtein with a
+ * hard-coded `maxDistance = 3`, which silently fails the most common AI
+ * mistake on this CLI: typing the schema-shortened form (`--model`) when the
+ * registered flag is the longer kebab-cased schema key (`--model-name`,
+ * `--knowledge-types`, `--start-date`). The edit distance there is ≥4, so
+ * commander emits no hint at all.
+ *
+ * We replace it with a two-stage matcher tuned for that pattern:
+ *   1. **Prefix-of-candidate** (`--model` → `--model-name`): treat candidates
+ *      that start with `<flag>-` as the strongest hit. AI agents typing the
+ *      shortened form are almost always after the prefix-extended flag.
+ *   2. **Levenshtein with cap=6**: catch typos and snake/kebab swaps the
+ *      argv normalizer didn't already canonicalize. Min similarity 0.4 keeps
+ *      the bar for spurious matches similar to commander's default.
+ *
+ * Returns the suggestion line (with leading `\n` to match commander's format)
+ * or an empty string when no candidate is close enough.
+ */
+function smartFlagSuggest(flag, candidates) {
+    if (!flag.startsWith('--') || flag.length < 4)
+        return '';
+    const word = flag.slice(2);
+    const stripped = candidates
+        .filter((c) => c.startsWith('--') && c.length > 3)
+        .map((c) => c.slice(2));
+    const seen = new Set();
+    // Defensively drop exact matches: in real usage commander wouldn't reach the
+    // unknown-option path for a registered flag, but keeping the suggester pure
+    // makes it safe to compose elsewhere.
+    const cands = stripped.filter((c) => {
+        if (c === word || seen.has(c))
+            return false;
+        seen.add(c);
+        return true;
+    });
+    if (cands.length === 0)
+        return '';
+    const prefixHits = cands
+        .filter((c) => c.length > word.length && c.startsWith(`${word}-`))
+        .sort();
+    if (prefixHits.length) {
+        const formatted = prefixHits.map((c) => `--${c}`);
+        return prefixHits.length === 1
+            ? `\n(Did you mean ${formatted[0]}?)`
+            : `\n(Did you mean one of ${formatted.join(', ')}?)`;
+    }
+    const editDistance = (a, b) => {
+        if (Math.abs(a.length - b.length) > 8)
+            return Math.max(a.length, b.length);
+        // Flat 1-D matrix indexed as `(rows+1) cells per row`; avoids
+        // `noUncheckedIndexedAccess` complaints from nested array slots that
+        // TypeScript otherwise types as `number | undefined`.
+        const w = b.length + 1;
+        const d = new Array((a.length + 1) * w);
+        for (let i = 0; i <= a.length; i++)
+            d[i * w] = i;
+        for (let j = 0; j <= b.length; j++)
+            d[j] = j;
+        for (let i = 1; i <= a.length; i++) {
+            for (let j = 1; j <= b.length; j++) {
+                const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+                const del = d[(i - 1) * w + j] + 1;
+                const ins = d[i * w + (j - 1)] + 1;
+                const sub = d[(i - 1) * w + (j - 1)] + cost;
+                let v = Math.min(del, ins, sub);
+                if (i > 1 && j > 1 && a[i - 1] === b[j - 2] && a[i - 2] === b[j - 1]) {
+                    v = Math.min(v, d[(i - 2) * w + (j - 2)] + 1);
+                }
+                d[i * w + j] = v;
+            }
+        }
+        return d[a.length * w + b.length];
+    };
+    const MAX_DIST = 6;
+    const MIN_SIM = 0.4;
+    let bestDist = MAX_DIST;
+    let best = [];
+    for (const c of cands) {
+        const dist = editDistance(word, c);
+        const len = Math.max(word.length, c.length);
+        if ((len - dist) / len <= MIN_SIM)
+            continue;
+        if (dist < bestDist) {
+            bestDist = dist;
+            best = [c];
+        }
+        else if (dist === bestDist) {
+            best.push(c);
+        }
+    }
+    if (!best.length)
+        return '';
+    best.sort();
+    const formatted = best.map((c) => `--${c}`);
+    return best.length === 1
+        ? `\n(Did you mean ${formatted[0]}?)`
+        : `\n(Did you mean one of ${formatted.join(', ')}?)`;
+}
+function asInternal(cmd) {
+    return cmd;
+}
+/** 沿命令树向上收集所有可用长选项（含 --help），供拼写建议使用。 */
+function collectLongFlags(start) {
+    const candidateFlags = [];
+    for (let cur = start; cur; cur = cur.parent ? asInternal(cur.parent) : null) {
+        for (const opt of cur.options ?? []) {
+            if (opt.long)
+                candidateFlags.push(opt.long);
+        }
+        candidateFlags.push('--help');
+    }
+    return candidateFlags;
+}
+function patchSmartSuggester(cmd) {
+    const target = asInternal(cmd);
+    const original = target.unknownOption.bind(target);
+    target.unknownOption = function patched(flag) {
+        if (this._allowUnknownOption)
+            return;
+        if (!flag.startsWith('--'))
+            return original(flag);
+        const suggestion = smartFlagSuggest(flag, collectLongFlags(this));
+        if (!suggestion)
+            return original(flag);
+        this.error(`error: unknown option '${flag}'${suggestion}`, {
+            code: 'commander.unknownOption',
+        });
+    };
+}
+/**
+ * Apply commander's "did you mean" affordances to every command in the tree.
+ *
+ * commander 13 stores `_showSuggestionAfterError` and `_showHelpAfterError`
+ * per-Command and **does not** inherit them from the parent. So setting them
+ * only on the root program would leave nested subcommands
+ * dynamic leaves, …) printing the bare `unknown option '--model'` without any
+ * hint. We walk the registered tree once, after every subcommand has been
+ * attached (built-ins + dynamic), and turn both behaviours on. We also patch
+ * each command's `unknownOption` with the smarter suggester (see above).
+ *
+ * The tree walk is intentionally idempotent: calling `showSuggestionAfterError`
+ * twice is a no-op, so re-running this after late additions stays safe.
+ */
+function applyErrorAffordances(root) {
+    const stack = [root];
+    while (stack.length) {
+        const node = stack.pop();
+        if (!node)
+            continue;
+        node.showSuggestionAfterError(true);
+        node.showHelpAfterError('(use -h or --help for usage)');
+        patchSmartSuggester(node);
+        stack.push(...node.commands);
+    }
+}
+// Exposed for unit tests; keeping the implementation co-located with the
+// command-tree walker so the heuristic can evolve next to the integration.
+export { smartFlagSuggest };
+async function main() {
+    const program = new Command(CLI_BIN)
+        .version(PKG_VERSION, '-V, --version')
+        .description('VPS business CLI for enterprise tenants, employees and partners.')
+        .option('--base-url <url>', 'Override Vertu service URL for shortcuts and auth')
+        .addHelpText('beforeAll', buildCliRootHelpBefore())
+        .addHelpText('after', buildCliRootHelpAfter());
+    program.addCommand(buildCliInstallCommand());
+    program.addCommand(buildAuthCommand());
+    program.addCommand(buildAgentCommand());
+    program.addCommand(buildSalesCommand());
+    program.addCommand(buildStoreCommand());
+    program.addCommand(buildHrCommand());
+    program.addCommand(buildProductCommand());
+    program.addCommand(buildPurchaseCommand());
+    program.addCommand(buildApprovalCommand());
+    program.addCommand(buildOkrCommand());
+    program.addCommand(buildReportCommand());
+    program.addCommand(buildAttendanceCommand());
+    program.addCommand(buildTaskCommand());
+    program.addCommand(buildToolsCommand());
+    program.addCommand(buildImCommand());
+    program.addCommand(buildMailCommand());
+    program.addCommand(buildVemoryCommand());
+    program.addCommand(buildMeetingCommand());
+    program.addCommand(buildCalendarCommand());
+    program.addCommand(buildCreativeCommand());
+    program.addCommand(buildCorporateCommand());
+    program.addCommand(buildDocumentsCommand());
+    program.addCommand(buildOfficeCommand());
+    program.addCommand(buildKnowledgeCommand());
+    program.addCommand(buildDriveCommand());
+    program.addCommand(buildPopupCommand());
+    program.addCommand(buildCatalogCommand());
+    program.addCommand(buildExecCommand());
+    program.addCommand(buildVertuErpCommand());
+    program.addCommand(buildVertuAiSalesCommand());
+    program.addCommand(buildSkillCommand());
+    // Accept snake_case long flags (e.g. `--start_date`) as aliases of the
+    // canonical kebab-case form. server-side `parameters_schema` keys are
+    // snake_case, so users / AI agents reading the schema often type that form
+    // first. Normalizing once at the entry point keeps commander unaware of the
+    // alternate spelling and avoids touching every dynamic option registration.
+    const userArgv = normalizeSnakeFlags(process.argv.slice(2));
+    const fullArgv = [...process.argv.slice(0, 2), ...userArgv];
+    // Apply after built-in commands are registered, so the
+    // walker covers the whole tree in one pass.
+    applyErrorAffordances(program);
+    try {
+        await program.parseAsync(fullArgv);
+    }
+    catch (err) {
+        handleError(err);
+    }
+}
+function handleError(err) {
+    process.stderr.write(`${formatErrorForCli(err)}\n`);
+    if (err instanceof VertuError) {
+        process.exit(err.exitCode);
+    }
+    process.exit(1);
+}
+function isCliEntryPoint() {
+    const entry = process.argv[1] ?? '';
+    return (entry.includes('vps-work.ts') ||
+        entry.includes('vps-work.cjs') ||
+        entry.endsWith(`${CLI_BIN}`) ||
+        CLI_BIN_ALIASES.some((alias) => entry.endsWith(alias)));
+}
+if (isCliEntryPoint()) {
+    void main().catch(handleError);
+}

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

@@ -0,0 +1,264 @@
+import { randomUUID } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { Command } from 'commander';
+import { VertuError } from '../../core/errors.js';
+import { DEFAULT_AGENT_APP_ID, formatAgentEnvExports, VERTU_APP_ID_ENV, VERTU_APP_KEY_ENV, } from '../../core/vertu-agent-env.js';
+import { bindVpsServiceAgentCredential, loadStoredAgentKey, persistVpsServiceAgentCredential, } from '../../core/vps-service-auth.js';
+import { readVpsServiceConfig } from '../../core/vps-service-config.js';
+import { resolveVpsServiceUrl } from '../../core/sales-query-client.js';
+import { promptText } from '../../utils/prompt.js';
+import { expandAtFileToken } from '../../utils/at-file.js';
+import { imRequest } from '../../core/im-client.js';
+const HARNESS_COLLABORATION_KIND = 'vps-harness-agent-collaboration';
+function isVpsSessionExpired(expiresAt) {
+    if (!expiresAt) {
+        return true;
+    }
+    const parsed = Date.parse(expiresAt);
+    return !Number.isFinite(parsed) || parsed <= Date.now() + 30_000;
+}
+function requiredUserId(raw) {
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0) {
+        throw new VertuError('--user-id 必须是正整数。');
+    }
+    return value;
+}
+export function collaborationTurnFromHistory(out, requestId) {
+    if (!out || typeof out !== 'object' || !('messages' in out))
+        return null;
+    const messages = out.messages;
+    if (!Array.isArray(messages))
+        return null;
+    for (const value of [...messages].reverse()) {
+        if (!value || typeof value !== 'object')
+            continue;
+        const message = value;
+        const metadata = message.metadata;
+        if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata))
+            continue;
+        const envelope = metadata[HARNESS_COLLABORATION_KIND];
+        if (!envelope || typeof envelope !== 'object' || Array.isArray(envelope))
+            continue;
+        const record = envelope;
+        const turn = Number(record.turn);
+        if (record.request_id !== requestId
+            || (record.type !== 'request' && record.type !== 'response')
+            || !Number.isInteger(turn)
+            || turn <= 0)
+            continue;
+        return {
+            body: typeof message.body === 'string' ? message.body : '',
+            messageId: typeof message.id === 'string' ? message.id : '',
+            turn,
+            type: record.type,
+        };
+    }
+    return null;
+}
+export function buildAgentCommand() {
+    const cmd = new Command('agent').description('Agent host credentials (app_id + app_key) after human sign-in.');
+    cmd
+        .command('bind')
+        .description('用当前 Vertu 会话为指定 app_id 签发/轮换 app_key')
+        .option('--base-url <url>', 'Vertu 服务地址')
+        .option('--app-id <id>', `可信应用 ID（默认 ${DEFAULT_AGENT_APP_ID}，可用环境变量 ${VERTU_APP_ID_ENV}）`)
+        .action(async (opts, command) => {
+        const merged = command.optsWithGlobals();
+        const cfg = await readVpsServiceConfig();
+        const serviceUrl = resolveVpsServiceUrl(opts.baseUrl ?? merged.baseUrl);
+        const sessionToken = cfg.sessionToken?.trim();
+        if (!sessionToken || isVpsSessionExpired(cfg.expiresAt)) {
+            throw new VertuError('签发 app_key 需要人工登录会话；Agent 不得自行执行账号密码登录。');
+        }
+        const appId = opts.appId?.trim() ??
+            merged.appId?.trim() ??
+            process.env[VERTU_APP_ID_ENV]?.trim() ??
+            cfg.agentAppId ??
+            (await promptText('Agent app_id', DEFAULT_AGENT_APP_ID));
+        const bound = await bindVpsServiceAgentCredential(serviceUrl, sessionToken, appId);
+        await persistVpsServiceAgentCredential(serviceUrl, bound);
+        console.log(`已绑定 Agent：app_id=${bound.appId}，login=${bound.login}`);
+        console.log(`过期：${bound.expiresAt ?? '长效（永不过期）'}`);
+        console.log('宿主环境：执行 `vps-work agent env` 查看 export 语句');
+    });
+    cmd
+        .command('env')
+        .description('输出 Agent 宿主应注入的环境变量（export / $env:）')
+        .option('--base-url <url>', 'Vertu 服务地址')
+        .option('--app-id <id>', '应用 ID（默认读配置或 cursor）')
+        .option('--shell <name>', 'bash | powershell', 'bash')
+        .action(async (opts, command) => {
+        const merged = command.optsWithGlobals();
+        const cfg = await readVpsServiceConfig();
+        const serviceUrl = resolveVpsServiceUrl(opts.baseUrl ?? merged.baseUrl);
+        const appId = opts.appId?.trim() ??
+            merged.appId?.trim() ??
+            cfg.agentAppId ??
+            DEFAULT_AGENT_APP_ID;
+        const login = cfg.login?.trim();
+        if (!login) {
+            throw new VertuError('未找到宿主注入的 Agent 账号；Agent 不得自行执行账号密码登录。');
+        }
+        const appKey = process.env[VERTU_APP_KEY_ENV]?.trim() ??
+            (await loadStoredAgentKey(serviceUrl, appId));
+        if (!appKey) {
+            throw new VertuError('无 app_key。请由宿主或人工管理员完成绑定；Agent 不得自行执行账号密码登录。');
+        }
+        const shell = opts.shell ?? merged.shell ?? 'bash';
+        if (shell === 'powershell') {
+            const esc = (s) => s.replace(/'/g, "''");
+            console.log(`$env:VERTU_VPS_SERVICE_URL='${esc(serviceUrl)}'`);
+            console.log(`$env:VERTU_APP_ID='${esc(appId)}'`);
+            console.log(`$env:VERTU_APP_KEY='${esc(appKey)}'`);
+            console.log(`$env:VERTU_USER_LOGIN='${esc(login)}'`);
+            return;
+        }
+        process.stdout.write(formatAgentEnvExports(serviceUrl, appId, appKey, login));
+    });
+    cmd
+        .command('ask')
+        .description('向另一位员工的 VPS Harness Agent 发起请求并等待答复')
+        .requiredOption('--user-id <id>', '对方 user_id')
+        .requiredOption('--message <text|@file>', '请求内容；长内容可使用 @file / @-')
+        .option('--base-url <url>', 'Vertu 服务地址')
+        .option('--stop-at <datetime>', '循环协作截止时间（ISO 8601 或本地 YYYY-MM-DDTHH:mm）')
+        .option('--duration-minutes <n>', '从现在起循环协作多少分钟（与 --stop-at 二选一）')
+        .option('--timeout <seconds>', '等待对方首轮答复的秒数', '180')
+        .option('--no-wait', '只发送请求，不等待答复')
+        .action(async (opts, command) => {
+        const merged = command.optsWithGlobals();
+        const serviceUrl = resolveVpsServiceUrl(opts.baseUrl ?? merged.baseUrl);
+        const userId = requiredUserId(opts.userId);
+        const message = (await expandAtFileToken(opts.message ?? '', '--message')).trim();
+        if (!message)
+            throw new VertuError('--message 不能为空。');
+        if (message.length > 20_000)
+            throw new VertuError('--message 不能超过 20000 个字符。');
+        if (opts.stopAt && opts.durationMinutes) {
+            throw new VertuError('--stop-at 与 --duration-minutes 只能使用一个。');
+        }
+        let stopAt;
+        if (opts.stopAt) {
+            const parsed = Date.parse(opts.stopAt);
+            if (!Number.isFinite(parsed) || parsed <= Date.now()) {
+                throw new VertuError('--stop-at 必须是未来的有效日期时间。');
+            }
+            stopAt = new Date(parsed).toISOString();
+        }
+        else if (opts.durationMinutes) {
+            const minutes = Number(opts.durationMinutes);
+            if (!Number.isFinite(minutes) || minutes <= 0 || minutes > 1440) {
+                throw new VertuError('--duration-minutes 必须大于 0 且不超过 1440 分钟。');
+            }
+            stopAt = new Date(Date.now() + minutes * 60_000).toISOString();
+        }
+        const timeoutSeconds = Number(opts.timeout);
+        if (!Number.isFinite(timeoutSeconds) || timeoutSeconds < 1 || timeoutSeconds > 1800) {
+            throw new VertuError('--timeout 必须在 1 到 1800 秒之间。');
+        }
+        const requestId = randomUUID();
+        const sent = await imRequest('POST', '/v1/im/user-robots/harness/send', {
+            baseUrl: serviceUrl,
+            body: {
+                body: message,
+                idempotency_key: `vps-harness-request-${requestId}`,
+                message_type: 'text',
+                target_user_id: userId,
+                metadata: {
+                    [HARNESS_COLLABORATION_KIND]: {
+                        objective: message,
+                        protocol: 1,
+                        request_id: requestId,
+                        ...(stopAt ? { stop_at: stopAt } : {}),
+                        turn: 0,
+                        type: 'request',
+                    },
+                },
+            },
+        });
+        const channelId = extractAgentAskChannelId(sent);
+        if (opts.wait === false) {
+            console.log(JSON.stringify({ channel_id: channelId, request_id: requestId, status: 'sent' }, null, 2));
+            return;
+        }
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        while (Date.now() < deadline) {
+            await sleep(1_000);
+            const history = await imRequest('GET', `/v1/im/channels/${encodeURIComponent(channelId)}/messages`, { baseUrl: serviceUrl, query: { limit: 50 } });
+            const response = collaborationTurnFromHistory(history, requestId);
+            if (response) {
+                console.log(JSON.stringify({
+                    answer: response.body,
+                    channel_id: channelId,
+                    message_id: response.messageId,
+                    request_id: requestId,
+                    status: response.type === 'request' ? 'continuing' : 'completed',
+                    turn: response.turn,
+                }, null, 2));
+                return;
+            }
+        }
+        throw new VertuError(`等待员工 VPS Harness Agent 答复超时（${timeoutSeconds} 秒）。请确认对方在线且已开启 Agent 联系开关。`);
+    });
+    cmd
+        .command('message-user')
+        .description('以我的 VPS Harness Agent 身份给员工发起私聊')
+        .requiredOption('--user-id <id>', '对方 user_id')
+        .requiredOption('--message <text|@file>', '消息内容；长内容可使用 @file / @-')
+        .option('--base-url <url>', 'Vertu 服务地址')
+        .action(async (opts, command) => {
+        const merged = command.optsWithGlobals();
+        const serviceUrl = resolveVpsServiceUrl(opts.baseUrl ?? merged.baseUrl);
+        const userId = requiredUserId(opts.userId);
+        const message = (await expandAtFileToken(opts.message ?? '', '--message')).trim();
+        if (!message)
+            throw new VertuError('--message 不能为空。');
+        if (message.length > 20_000)
+            throw new VertuError('--message 不能超过 20000 个字符。');
+        const requestId = randomUUID();
+        const sent = await imRequest('POST', '/v1/im/user-robots/harness/message-user', {
+            baseUrl: serviceUrl,
+            body: {
+                body: message,
+                idempotency_key: `vps-harness-human-${requestId}`,
+                message_type: 'text',
+                target_user_id: userId,
+            },
+        });
+        console.log(JSON.stringify({
+            channel_id: extractAgentAskChannelId(sent),
+            message_id: extractHarnessMessageId(sent),
+            request_id: requestId,
+            status: 'sent',
+        }, null, 2));
+    });
+    return cmd;
+}
+function extractHarnessMessageId(out) {
+    if (!out || typeof out !== 'object' || !('message' in out))
+        return null;
+    const message = out.message;
+    if (!message || typeof message !== 'object' || !('id' in message))
+        return null;
+    const id = message.id;
+    return typeof id === 'string' && id ? id : null;
+}
+function extractAgentAskChannelId(out) {
+    if (out && typeof out === 'object' && 'channel_id' in out) {
+        const id = out.channel_id;
+        if (typeof id === 'string' && id)
+            return id;
+    }
+    if (!out || typeof out !== 'object' || !('channel' in out)) {
+        throw new VertuError('Vertu IM 未返回 channel_id。');
+    }
+    const channel = out.channel;
+    if (!channel || typeof channel !== 'object' || !('id' in channel)) {
+        throw new VertuError('Vertu IM 未返回 channel.id。');
+    }
+    const id = channel.id;
+    if (typeof id !== 'string' || !id)
+        throw new VertuError('Vertu IM 返回了无效的 channel.id。');
+    return id;
+}

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

@@ -0,0 +1,7 @@
+import { Command } from 'commander';
+import { attachApprovalShortcuts } from './shortcuts.js';
+export function buildApprovalCommand() {
+    const approval = new Command('approval').description('Approval shortcuts: pending queue, approval history, pass/reject guidance.');
+    attachApprovalShortcuts(approval);
+    return approval;
+}