vps-work 2.5.0 → 2.5.1

package/dist/packages/vps-work/src/core/documents-client.js

@@ -0,0 +1,57 @@
+import { request } from 'undici';
+import { VertuError } from './errors.js';
+import { resolveVpsServiceUrl } from './sales-query-client.js';
+import { vpsServiceAuthHeaders } from './vps-service-http.js';
+function buildPath(path, query) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined && value !== null && value !== '') {
+            search.set(key, String(value));
+        }
+    }
+    const encoded = search.toString();
+    return encoded ? `${path}?${encoded}` : path;
+}
+function errorMessage(payload, statusCode) {
+    if (typeof payload === 'object' && payload !== null) {
+        const record = payload;
+        if (typeof record['error'] === 'string') {
+            return record['error'];
+        }
+        if (typeof record['message'] === 'string') {
+            return record['message'];
+        }
+    }
+    return `HTTP ${statusCode}`;
+}
+export async function documentsRequest(method, path, opts = {}) {
+    const baseUrl = resolveVpsServiceUrl(opts.baseUrl);
+    const response = await request(`${baseUrl}${buildPath(path, opts.query)}`, {
+        method,
+        headers: {
+            accept: 'application/json',
+            'content-type': 'application/json',
+            ...vpsServiceAuthHeaders(),
+        },
+        body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    });
+    const text = await response.body.text();
+    let payload = {};
+    try {
+        payload = text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new VertuError(`文档服务返回非 JSON（HTTP ${response.statusCode}）`);
+    }
+    if (response.statusCode >= 400) {
+        throw new VertuError(`文档服务失败：${errorMessage(payload, response.statusCode)}`);
+    }
+    return payload;
+}
+export function printDocumentsResult(json, payload) {
+    if (json !== false) {
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+    }
+    console.log(typeof payload === 'string' ? payload : JSON.stringify(payload));
+}

package/dist/packages/vps-work/src/core/endpoints.js

@@ -0,0 +1,46 @@
+import { PRIMARY_ALIAS, findAliasForBaseUrl, getEndpointBaseUrl, isValidAlias, resolveEffectiveBaseUrl, } from './config.js';
+import { EndpointNotConfiguredError, VertuError } from './errors.js';
+/**
+ * Resolve the target endpoint for one CLI invocation.
+ *
+ * Priority (highest first):
+ *   1. `baseUrlOverride` — explicit `--base-url` wins, no alias resolution.
+ *   2. `endpointOverride` — explicit `--endpoint <alias>` debug flag.
+ *   3. `leafEndpointAlias` — server-side capabilities hint.
+ *   4. Primary endpoint (`config.defaultBaseUrl` registered as alias `default`).
+ *
+ * Throws:
+ *   - `VertuError` when no base URL can be determined at all.
+ *   - `EndpointNotConfiguredError` when an alias is requested but not registered.
+ */
+export function resolveEndpoint(opts) {
+    const { config, baseUrlOverride, endpointOverride, leafEndpointAlias, leafLabel } = opts;
+    if (baseUrlOverride && baseUrlOverride.trim()) {
+        const baseUrl = baseUrlOverride.trim();
+        const alias = findAliasForBaseUrl(config, baseUrl) ?? PRIMARY_ALIAS;
+        return { alias, baseUrl, reason: 'override-base-url' };
+    }
+    if (endpointOverride && endpointOverride.trim()) {
+        const alias = endpointOverride.trim();
+        if (!isValidAlias(alias)) {
+            throw new VertuError(`Invalid --endpoint alias "${alias}"; expected ^[a-z][a-z0-9-]*$ (e.g. "im", "default").`);
+        }
+        const baseUrl = getEndpointBaseUrl(config, alias);
+        if (!baseUrl)
+            throw new EndpointNotConfiguredError(alias, { leafLabel });
+        return { alias, baseUrl, reason: 'override-endpoint' };
+    }
+    const hint = (leafEndpointAlias ?? '').trim();
+    if (hint) {
+        if (!isValidAlias(hint)) {
+            throw new VertuError(`Capabilities hint endpoint_alias="${hint}" does not match ^[a-z][a-z0-9-]*$. ` +
+                `Fix the server-side vt.cli.command record.`);
+        }
+        const baseUrl = getEndpointBaseUrl(config, hint);
+        if (!baseUrl)
+            throw new EndpointNotConfiguredError(hint, { leafLabel });
+        return { alias: hint, baseUrl, reason: 'leaf-hint' };
+    }
+    const primary = getEndpointBaseUrl(config, PRIMARY_ALIAS) ?? resolveEffectiveBaseUrl(config);
+    return { alias: PRIMARY_ALIAS, baseUrl: primary, reason: 'primary' };
+}

package/dist/packages/vps-work/src/core/erp-mcp-client.js

@@ -0,0 +1,11 @@
+import { VertuError } from './errors.js';
+import { hermesRequest } from './hermes-client.js';
+const tools = new Set(['erp-query', 'erp-list-tables', 'erp-table-columns']);
+export async function runErpMcp(operation, baseUrl) {
+    if (operation && !tools.has(operation.tool))
+        throw new VertuError('仅支持 ERP 只读工具，请先运行 vps-work vertu-erp tools。');
+    const reply = await hermesRequest('POST', '/hermes-console/api/platform-tools/vertu-erp', { baseUrl, body: operation ? { action: 'call', tool: operation.tool, arguments: operation.arguments } : { action: 'tools' } });
+    if (!reply.result || typeof reply.result !== 'object')
+        throw new VertuError('ERP 服务响应无效。');
+    return reply.result;
+}

package/dist/packages/vps-work/src/core/errors.js

@@ -0,0 +1,107 @@
+import { publicBusinessErrorMessage } from './public-result.js';
+export class VertuError extends Error {
+    exitCode;
+    hint;
+    /** 由服务端 HTTP 响应触发时的状态码；本地校验类错误为 undefined。 */
+    statusCode;
+    constructor(message, options = {}) {
+        super(message);
+        this.name = 'VertuError';
+        this.exitCode = options.exitCode ?? 1;
+        this.hint = options.hint;
+        this.statusCode = options.statusCode;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+export class AuthRequiredError extends VertuError {
+    constructor(message = 'Not authenticated.') {
+        super(message, {
+            exitCode: 2,
+            hint: 'Agent/Bot/Hermes: verify injected app_key credentials (Hermes app_id must be vertu-hermes-agent). Human operator: run `vps-work auth login` interactively.',
+        });
+        this.name = 'AuthRequiredError';
+    }
+}
+export class SessionExpiredError extends VertuError {
+    constructor(message = 'Session expired or invalid.') {
+        super(message, {
+            exitCode: 2,
+            hint: 'Agent/Bot/Hermes: refresh the injected app_key through the host. Human operator: log in interactively again.',
+        });
+        this.name = 'SessionExpiredError';
+    }
+}
+export class EndpointNotConfiguredError extends VertuError {
+    alias;
+    constructor(alias, opts = {}) {
+        const leafBit = opts.leafLabel ? `Leaf "${opts.leafLabel}" requires` : 'Command requires';
+        const msg = `${leafBit} endpoint "${alias}" but it is not configured locally. ` +
+            `This is a human-only legacy service endpoint. ` +
+            `Agent/Bot/Hermes must not log in with a password or configure legacy endpoints.`;
+        super(msg, {
+            exitCode: 2,
+            hint: `Configured endpoints: \`vps-work auth list\` or \`vps-work auth status\`.`,
+        });
+        this.name = 'EndpointNotConfiguredError';
+        this.alias = alias;
+    }
+}
+export class RemoteError extends VertuError {
+    status;
+    code;
+    data;
+    constructor(message, options = {}) {
+        super(message, { hint: options.hint, exitCode: options.exitCode });
+        this.name = 'RemoteError';
+        this.status = options.status;
+        this.code = options.code;
+        this.data = options.data;
+    }
+}
+/**
+ * 服务端限流（AiRateLimitError）。exitCode=3 便于外层 agent / 脚本区分
+ * 「被限流」与普通远端错误，从而做退避（backoff）而非直接失败。
+ */
+export class RateLimitError extends RemoteError {
+    retryAfterSeconds;
+    limitType;
+    constructor(message, options = {}) {
+        super(message, { ...options, exitCode: 3 });
+        this.name = 'RateLimitError';
+        this.retryAfterSeconds = options.retryAfterSeconds;
+        this.limitType = options.limitType;
+    }
+}
+/** 从服务端限流消息体中解析机读字段（RATE_LIMITED limit_type=... retry_after_seconds=...）。 */
+export function parseRateLimitInfo(message) {
+    const out = {};
+    const ra = /retry_after_seconds=(\d+)/.exec(message);
+    if (ra)
+        out.retryAfterSeconds = Number(ra[1]);
+    const lt = /limit_type=([a-z_]+)/i.exec(message);
+    if (lt)
+        out.limitType = lt[1];
+    return out;
+}
+export function formatErrorForCli(err) {
+    if (err instanceof RateLimitError) {
+        const lines = [publicBusinessErrorMessage(err.message)];
+        if (err.limitType)
+            lines.push(`  limit_type: ${err.limitType}`);
+        if (err.retryAfterSeconds != null) {
+            lines.push(`  retry_after_seconds: ${err.retryAfterSeconds}`);
+        }
+        lines.push('  hint: 命中服务端限流。请降低调用频率、合并查询或减少并发，并在 retry_after_seconds 之后再重试。');
+        return lines.join('\n');
+    }
+    if (err instanceof VertuError) {
+        const message = publicBusinessErrorMessage(err.message);
+        return err.hint ? `${message}\n  hint: ${publicBusinessErrorMessage(err.hint)}` : message;
+    }
+    if (err instanceof Error) {
+        return /odoo/i.test(err.message) ? publicBusinessErrorMessage(err.message) : err.stack ?? err.message;
+    }
+    return publicBusinessErrorMessage(err);
+}

package/dist/packages/vps-work/src/core/execute-catalog-client.js

@@ -0,0 +1,42 @@
+import { request } from 'undici';
+import { VertuError } from './errors.js';
+import { resolveVpsServiceUrl } from './sales-query-client.js';
+import { vpsServiceAuthHeaders } from './vps-service-http.js';
+/** 拉取当前身份可见的命令清单。 */
+export async function fetchExecuteCatalog(serviceBaseUrl, domain) {
+    const base = resolveVpsServiceUrl(serviceBaseUrl);
+    const query = domain?.trim() ? `?domain=${encodeURIComponent(domain.trim())}` : '';
+    const res = await request(`${base}/v1/execute/catalog${query}`, {
+        method: 'GET',
+        headers: {
+            accept: 'application/json',
+            ...vpsServiceAuthHeaders(base),
+        },
+    });
+    const text = await res.body.text();
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        throw new VertuError(`读取命令目录失败：非 JSON（HTTP ${res.statusCode}）`);
+    }
+    if (res.statusCode >= 400) {
+        const errMsg = data && typeof data === 'object' && 'error' in data
+            ? String(data.error)
+            : `HTTP ${res.statusCode}`;
+        throw new VertuError(`读取命令目录失败：${errMsg}`);
+    }
+    if (!data || typeof data !== 'object' || !('shortcuts' in data)) {
+        throw new VertuError('读取命令目录失败：响应无效');
+    }
+    const raw = data;
+    const { disabled_third_party_apps: _internalDisabledApps, ...publicCatalog } = raw;
+    return {
+        ...publicCatalog,
+        shortcuts: raw.shortcuts.map((shortcut) => {
+            const { provider: _internalProvider, ...item } = shortcut;
+            return item;
+        }),
+    };
+}

package/dist/packages/vps-work/src/core/hermes-client.js

@@ -0,0 +1,70 @@
+import { request } from 'undici';
+import { VertuError } from './errors.js';
+import { vpsServiceAuthHeaders } from './vps-service-http.js';
+const DEFAULT_HERMES_AGENT_ADMIN_BASE_URL = 'https://vps-console.vertu.cn';
+function normalizeServiceRoot(url) {
+    const raw = url?.trim() || DEFAULT_HERMES_AGENT_ADMIN_BASE_URL;
+    let trimmed = raw.replace(/\/+$/, '');
+    if (!/^https?:\/\//i.test(trimmed)) {
+        trimmed = `https://${trimmed}`;
+    }
+    return trimmed;
+}
+function firstEnv(...keys) {
+    for (const key of keys) {
+        const value = process.env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+export function resolveHermesAgentAdminUrl(override) {
+    return normalizeServiceRoot(override ||
+        firstEnv('VERTU_HERMES_BASE_URL', 'HERMES_AGENT_ADMIN_BASE_URL', 'HERMES_CONSOLE_BASE_URL', 'HERMES_BASE_URL'));
+}
+function headers() {
+    const authHeaders = vpsServiceAuthHeaders();
+    const authorization = authHeaders.authorization;
+    return {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...authHeaders,
+        ...(authorization ? { cookie: `vps_session=${authorization.replace(/^Bearer\s+/i, '')}` } : {}),
+    };
+}
+async function parseJson(res) {
+    const text = await res.body.text();
+    try {
+        return text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new VertuError(`Hermes 服务返回非 JSON（HTTP ${res.statusCode}）`);
+    }
+}
+export async function hermesRequest(method, path, opts = {}) {
+    const base = resolveHermesAgentAdminUrl(opts.baseUrl);
+    const target = new URL(base);
+    const trusted = new URL(resolveHermesAgentAdminUrl());
+    if (target.origin !== trusted.origin || target.username || target.password
+        || target.search || target.hash || target.pathname !== '/') {
+        throw new VertuError('Hermes 请求目标不受信任；请由宿主配置服务地址，不能通过临时参数转发凭据。');
+    }
+    const res = await request(`${base}${path}`, {
+        method,
+        headers: headers(),
+        body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    });
+    const data = await parseJson(res);
+    if (res.statusCode >= 400) {
+        const errMsg = data && typeof data === 'object' && 'error' in data
+            ? String(data.error)
+            : `HTTP ${res.statusCode}`;
+        throw new VertuError(`Hermes 服务失败：${errMsg}`);
+    }
+    if (data && typeof data === 'object' && 'ok' in data && data.ok === false) {
+        const errMsg = 'error' in data ? String(data.error) : 'unknown error';
+        throw new VertuError(`Hermes 服务失败：${errMsg}`);
+    }
+    return data;
+}

package/dist/packages/vps-work/src/core/im-attachment-download.js

@@ -0,0 +1,109 @@
+import { createWriteStream } from 'node:fs';
+import { mkdir, rm, stat } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { request } from 'undici';
+import { VertuError } from './errors.js';
+import { resolveVpsServiceUrl } from './sales-query-client.js';
+import { vpsServiceAuthHeaders } from './vps-service-http.js';
+const IM_FILE_PREFIX = '/v1/im/files/';
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+const MAX_REDIRECTS = 3;
+function encodedStorageKey(storageKey) {
+    const segments = storageKey.trim().split('/').filter(Boolean);
+    if (segments.length === 0) {
+        throw new VertuError('--storage-key 不能为空。');
+    }
+    return segments.map(encodeURIComponent).join('/');
+}
+export function resolveImAttachmentDownloadPath(serviceBaseUrl, input) {
+    const storageKey = input.storageKey?.trim() ?? '';
+    const rawUrl = input.url?.trim() ?? '';
+    if (Boolean(storageKey) === Boolean(rawUrl)) {
+        throw new VertuError('--url 与 --storage-key 必须且只能提供一个。');
+    }
+    if (storageKey) {
+        return `${IM_FILE_PREFIX}${encodedStorageKey(storageKey)}`;
+    }
+    let parsed;
+    try {
+        parsed = new URL(rawUrl, `${serviceBaseUrl.replace(/\/+$/, '')}/`);
+    }
+    catch {
+        throw new VertuError('--url 不是有效的附件 URL。');
+    }
+    const service = new URL(serviceBaseUrl);
+    if (parsed.origin !== service.origin || !parsed.pathname.startsWith(IM_FILE_PREFIX)) {
+        throw new VertuError('--url 必须是当前 VPS 服务的 /v1/im/files/... 地址。');
+    }
+    if (parsed.search || parsed.hash || parsed.pathname.length === IM_FILE_PREFIX.length) {
+        throw new VertuError('--url 不是有效的聊天附件地址。');
+    }
+    return parsed.pathname;
+}
+async function responseError(status, text) {
+    try {
+        const payload = JSON.parse(text);
+        if (payload.error)
+            return new VertuError(`聊天附件下载失败：${String(payload.error)}`);
+    }
+    catch {
+        // 非 JSON 错误响应使用 HTTP 状态兜底。
+    }
+    return new VertuError(`聊天附件下载失败：HTTP ${status}`);
+}
+export async function downloadImAttachment(input) {
+    const baseUrl = resolveVpsServiceUrl(input.baseUrl).replace(/\/+$/, '');
+    const sourcePath = resolveImAttachmentDownloadPath(baseUrl, input);
+    const sourceUrl = `${baseUrl}${sourcePath}`;
+    let currentUrl = sourceUrl;
+    let response = await request(currentUrl, {
+        method: 'GET',
+        headers: { accept: '*/*', ...vpsServiceAuthHeaders() },
+    });
+    for (let redirects = 0; REDIRECT_STATUSES.has(response.statusCode); redirects += 1) {
+        if (redirects >= MAX_REDIRECTS) {
+            await response.body.dump();
+            throw new VertuError(`聊天附件下载失败：重定向超过 ${MAX_REDIRECTS} 次。`);
+        }
+        const location = response.headers.location;
+        await response.body.dump();
+        if (typeof location !== 'string' || !location.trim()) {
+            throw new VertuError('聊天附件下载失败：服务端重定向缺少 Location。');
+        }
+        currentUrl = new URL(location, currentUrl).toString();
+        response = await request(currentUrl, {
+            method: 'GET',
+            headers: { accept: '*/*' },
+        });
+    }
+    if (response.statusCode >= 400) {
+        const text = await response.body.text();
+        throw await responseError(response.statusCode, text);
+    }
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+        await response.body.dump();
+        throw new VertuError(`聊天附件下载失败：HTTP ${response.statusCode}`);
+    }
+    const output = resolve(input.output);
+    await mkdir(dirname(output), { recursive: true });
+    try {
+        await pipeline(response.body, createWriteStream(output, { flags: 'wx' }));
+    }
+    catch (error) {
+        if (error.code === 'EEXIST') {
+            throw new VertuError(`输出文件已存在：${output}`);
+        }
+        await rm(output, { force: true }).catch(() => undefined);
+        throw error;
+    }
+    const file = await stat(output);
+    return {
+        bytes: file.size,
+        content_type: typeof response.headers['content-type'] === 'string'
+            ? response.headers['content-type']
+            : null,
+        output,
+        source_url: sourcePath,
+    };
+}

package/dist/packages/vps-work/src/core/im-client.js

@@ -0,0 +1,64 @@
+import { request } from 'undici';
+import { VertuError } from './errors.js';
+import { resolveVpsServiceUrl } from './sales-query-client.js';
+import { vpsServiceAuthHeaders } from './vps-service-http.js';
+import { publicBusinessResult } from './public-result.js';
+function headers(baseUrl) {
+    return {
+        accept: 'application/json',
+        'content-type': 'application/json',
+        ...vpsServiceAuthHeaders(baseUrl),
+    };
+}
+async function parseJson(res) {
+    const text = await res.body.text();
+    try {
+        return text.trim() ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new VertuError(`Vertu 服务返回非 JSON（HTTP ${res.statusCode}）`);
+    }
+}
+function buildPath(path, query) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value === undefined || value === null || value === '') {
+            continue;
+        }
+        search.set(key, String(value));
+    }
+    const q = search.toString();
+    return q ? `${path}?${q}` : path;
+}
+export async function imRequest(method, path, opts = {}) {
+    const base = resolveVpsServiceUrl(opts.baseUrl);
+    const res = await request(`${base}${buildPath(path, opts.query)}`, {
+        method,
+        headers: headers(base),
+        body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
+    });
+    const data = await parseJson(res);
+    if (res.statusCode >= 400) {
+        const errMsg = data && typeof data === 'object' && 'error' in data
+            ? String(data.error)
+            : `HTTP ${res.statusCode}`;
+        throw new VertuError(`Vertu 服务失败：${errMsg}`);
+    }
+    if (data && typeof data === 'object' && 'ok' in data) {
+        const payload = data;
+        if (payload.ok === false) {
+            const errMsg = 'error' in payload ? String(payload.error) : 'unknown error';
+            throw new VertuError(`Vertu 服务失败：${errMsg}`);
+        }
+    }
+    return data;
+}
+export function printImResult(json, out) {
+    const publicOut = publicBusinessResult(out);
+    if (json !== false) {
+        console.log(JSON.stringify(publicOut, null, 2));
+    }
+    else {
+        console.log(typeof publicOut === 'string' ? publicOut : JSON.stringify(publicOut));
+    }
+}

package/dist/packages/vps-work/src/core/keychain.js

@@ -0,0 +1,58 @@
+import { CLI_KEYCHAIN_SERVICE } from './cli-bin.js';
+const SERVICE_NAME = CLI_KEYCHAIN_SERVICE;
+let cachedModulePromise = null;
+async function loadKeytar() {
+    if (process.env.VERTU_DISABLE_KEYTAR === '1')
+        return null;
+    if (cachedModulePromise)
+        return cachedModulePromise;
+    cachedModulePromise = (async () => {
+        try {
+            const mod = (await import('keytar'));
+            const keytar = mod.default ?? mod;
+            if (!keytar || typeof keytar.setPassword !== 'function')
+                return null;
+            return keytar;
+        }
+        catch {
+            return null;
+        }
+    })();
+    return cachedModulePromise;
+}
+export async function isKeychainAvailable() {
+    return (await loadKeytar()) !== null;
+}
+export async function setSecret(account, secret) {
+    const keytar = await loadKeytar();
+    if (!keytar)
+        throw new Error('Keychain not available');
+    await keytar.setPassword(SERVICE_NAME, account, secret);
+}
+export async function getSecret(account) {
+    const keytar = await loadKeytar();
+    if (!keytar)
+        return null;
+    return keytar.getPassword(SERVICE_NAME, account);
+}
+export async function deleteSecret(account) {
+    const keytar = await loadKeytar();
+    if (!keytar)
+        return false;
+    return keytar.deletePassword(SERVICE_NAME, account);
+}
+export function sessionAccount(baseUrl) {
+    return `session:${baseUrl}`;
+}
+export function bearerAccount(baseUrl) {
+    return `bearer:${baseUrl}`;
+}
+export function passwordAccount(baseUrl) {
+    return `password:${baseUrl}`;
+}
+export function agentKeyAccount(serviceBaseUrl, appId) {
+    return `vps-agent:${serviceBaseUrl}:${appId}`;
+}
+export function vpsSessionTokenAccount(serviceBaseUrl) {
+    return `vps-session:${serviceBaseUrl}`;
+}

package/dist/packages/vps-work/src/core/mail-client.js

@@ -0,0 +1,82 @@
+import { openAsBlob } from 'node:fs';
+import { open, stat, unlink } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { pipeline } from 'node:stream/promises';
+import { FormData, request } from 'undici';
+import { VertuError } from './errors.js';
+import { resolveVpsServiceUrl } from './sales-query-client.js';
+import { vpsServiceAuthHeaders } from './vps-service-http.js';
+const timeout = 30 * 60_000;
+export function mailUrl(path, scope, query = {}) {
+    const url = new URL(`${resolveVpsServiceUrl(scope.baseUrl).replace(/\/$/, '')}/v1/mail${path}`);
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined && value !== '')
+            url.searchParams.set(key, String(value));
+    }
+    if (scope.mailboxId)
+        url.searchParams.set('mailbox_id', scope.mailboxId);
+    return url.toString();
+}
+async function jsonResponse(res) {
+    const text = await res.body.text();
+    let data;
+    try {
+        data = text ? JSON.parse(text) : {};
+    }
+    catch {
+        throw new VertuError(`邮箱服务返回非 JSON（HTTP ${res.statusCode}）`);
+    }
+    if (res.statusCode >= 300) {
+        const value = data;
+        const reason = typeof value?.error === 'string' ? value.error : value?.error?.message;
+        throw new VertuError(`邮箱服务失败（HTTP ${res.statusCode}）：${value?.message || reason || '请求失败'}`);
+    }
+    return data;
+}
+export async function mailRequest(method, path, scope, body, query) {
+    const url = mailUrl(path, scope, query);
+    return jsonResponse(await request(url, {
+        method, headersTimeout: timeout, bodyTimeout: timeout,
+        headers: { ...vpsServiceAuthHeaders(resolveVpsServiceUrl(scope.baseUrl)), accept: 'application/json', 'content-type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body),
+    }));
+}
+export async function inspectMailFile(file) {
+    const info = await stat(file);
+    if (!info.isFile() || info.size > 1073741824)
+        throw new VertuError('附件必须是普通文件且不超过 1 GiB。');
+    return { name: basename(file), size: info.size };
+}
+export async function uploadMailFile(file, scope) {
+    const info = await inspectMailFile(file);
+    const form = new FormData();
+    form.set('file', await openAsBlob(file), info.name);
+    return jsonResponse(await request(mailUrl('/attachments', scope), {
+        method: 'POST', headersTimeout: timeout, bodyTimeout: timeout,
+        headers: vpsServiceAuthHeaders(resolveVpsServiceUrl(scope.baseUrl)), body: form,
+    }));
+}
+export async function downloadMailFile(blobId, output, scope) {
+    // Exclusive creation preserves existing files. A failed stream removes only this new file.
+    const file = await open(output, 'wx', 0o600);
+    try {
+        const res = await request(mailUrl(`/attachments/${encodeURIComponent(blobId)}`, scope), {
+            method: 'GET', headersTimeout: timeout, bodyTimeout: timeout,
+            headers: vpsServiceAuthHeaders(resolveVpsServiceUrl(scope.baseUrl)),
+        });
+        if (res.statusCode !== 200) {
+            await jsonResponse(res);
+            throw new VertuError('附件下载未返回完整文件。');
+        }
+        await pipeline(res.body, file.createWriteStream());
+        return { output, size: (await stat(output)).size };
+    }
+    catch (error) {
+        await file.close();
+        await unlink(output);
+        throw error;
+    }
+    finally {
+        await file.close();
+    }
+}