volcengine-api-mcp 0.0.0-stage → 0.1.0

package/dist/lib/client.js

@@ -0,0 +1,117 @@
+import { signRequest } from './signer.js';
+import { VolcengineApiError, } from './types.js';
+/** 常见服务的默认 Host（不在此表中的服务回退为 <service>.<region>.volcengineapi.com） */
+export const SERVICE_HOSTS = {
+    ecs: 'ecs.cn-north-1.volcengineapi.com',
+    vpc: 'vpc.cn-north-1.volcengineapi.com',
+    iam: 'iam.volcengineapi.com',
+    vod: 'vod.volcengineapi.com',
+    live: 'live.volcengineapi.com',
+    tls: 'tls-cn-beijing.volces.com',
+    ces: 'ces.cn-north-1.volcengineapi.com',
+};
+export class VolcengineClient {
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    resolveHost(service, host, region) {
+        if (host)
+            return host;
+        return SERVICE_HOSTS[service] ?? `${service}.${region ?? this.opts.region ?? 'cn-north-1'}.volcengineapi.com`;
+    }
+    async request(req) {
+        const method = req.method ?? 'GET';
+        const region = req.region ?? this.opts.region ?? 'cn-north-1';
+        const service = req.service;
+        const host = this.resolveHost(service, req.host, region);
+        const credentials = this.opts.credentials;
+        if (!credentials?.accessKeyId || !credentials?.secretAccessKey) {
+            throw new VolcengineApiError('缺少火山引擎 AK/SK，请通过环境变量 VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY 配置', 0, 'MissingCredentials', undefined);
+        }
+        const bodyStr = method === 'POST' || method === 'PUT'
+            ? req.params
+                ? JSON.stringify(req.params)
+                : ''
+            : '';
+        const query = method === 'POST' || method === 'PUT'
+            ? { Action: req.action, Version: req.version }
+            : {
+                Action: req.action,
+                Version: req.version,
+                ...flattenParams(req.params ?? {}),
+            };
+        const headers = {
+            Host: host,
+            'Content-Type': 'application/json',
+            ...(bodyStr ? { 'Content-Length': String(Buffer.byteLength(bodyStr)) } : {}),
+            ...(req.headers ?? {}),
+        };
+        const signed = signRequest({
+            method,
+            path: '/',
+            query,
+            headers,
+            body: bodyStr,
+            accessKeyId: credentials.accessKeyId,
+            secretAccessKey: credentials.secretAccessKey,
+            region,
+            service,
+        });
+        const url = `https://${host}/?${new URLSearchParams(query)}`;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.opts.timeoutMs ?? 30_000);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers: { ...headers, ...signed },
+                body: bodyStr || undefined,
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const resHeaders = {};
+        res.headers.forEach((v, k) => {
+            resHeaders[k] = v;
+        });
+        const text = await res.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            parsed = text;
+        }
+        if (!res.ok) {
+            const errObj = (parsed ?? {});
+            const data = errObj.ResponseMetadata ?? errObj;
+            throw new VolcengineApiError(`${req.action} 调用失败: ${data?.Error?.Message ?? data?.Message ?? res.statusText}`, res.status, data?.Error?.Code ?? data?.Code, data?.RequestId, parsed);
+        }
+        return { status: res.status, headers: resHeaders, body: parsed };
+    }
+}
+/**
+ * 把嵌套参数展开成火山 API 需要的扁平 query（如 List.1.Name=a&List.1.Id=b）。
+ */
+export function flattenParams(params, prefix = '') {
+    const result = {};
+    for (const [key, value] of Object.entries(params)) {
+        const fullKey = prefix ? `${prefix}.${key}` : key;
+        if (value === null || value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            Object.assign(result, flattenParams(Object.fromEntries(value.map((v, i) => [String(i + 1), v])), fullKey));
+        }
+        else if (typeof value === 'object') {
+            Object.assign(result, flattenParams(value, fullKey));
+        }
+        else {
+            result[fullKey] = String(value);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/lib/client.ts"],"names":[],"mappings":"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"}

package/dist/lib/index.d.ts

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './signer.js';
+export * from './client.js';
+export * from './ark.js';
+export * from './tos.js';
+export * from './auc.js';
+export * from './tts.js';
+export * from './search.js';

package/dist/lib/index.js

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './signer.js';
+export * from './client.js';
+export * from './ark.js';
+export * from './tos.js';
+export * from './auc.js';
+export * from './tts.js';
+export * from './search.js';
+//# sourceMappingURL=index.js.map

package/dist/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC"}

package/dist/lib/search.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 火山引擎联网搜索（豆包搜索 / WebSearch）。
+ * 移植自 mcp-server/server/mcp_server_askecho_search_infinity（Python）。
+ * 两条调用路径：
+ * - API Key 模式: POST https://open.feedcoopapi.com/search_api/web_search（Bearer）
+ * - AK/SK 模式:  POST https://mercury.volcengineapi.com/?Action=WebSearch&Version=2025-01-01（V4 签名）
+ */
+import type { VolcengineCredentials } from './types.js';
+/** API Key 模式网关 */
+export declare const SEARCH_API_HOST = "open.feedcoopapi.com";
+/** AK/SK 模式（火山 mercury 网关） */
+export declare const SEARCH_V4_HOST = "mercury.volcengineapi.com";
+export declare const SEARCH_V4_SERVICE = "volc_torchlight_api";
+export declare const SEARCH_V4_VERSION = "2025-01-01";
+export declare const SEARCH_V4_REGION = "cn-beijing";
+export interface WebSearchParams {
+    query: string;
+    count?: number;
+    searchType?: 'web' | 'image';
+    /** OneDay/OneWeek/OneMonth/OneYear 或 YYYY-MM-DD..YYYY-MM-DD */
+    timeRange?: string;
+    /** 权威等级过滤，0 默认 / 1 非常权威 */
+    authLevel?: 0 | 1;
+    needContent?: boolean;
+    needUrl?: boolean;
+    /** 仅搜索指定站点，最多 20 个 */
+    sites?: string[];
+    /** 排除指定站点，最多 5 个 */
+    blockHosts?: string[];
+    /** 行业搜索 finance / game / gov */
+    industry?: 'finance' | 'game' | 'gov';
+    queryRewrite?: boolean;
+    /** 网页正文格式 text / markdown */
+    contentFormats?: 'text' | 'markdown';
+}
+/** 参数校验并组装请求 payload（结构与官方 WebSearch 接口一致，大写字段名） */
+export declare function buildWebSearchPayload(params: WebSearchParams): Record<string, unknown>;
+/** API Key 模式：feedcoopapi 网关，Bearer 鉴权 */
+export declare function webSearchByApiKey(apiKey: string, payload: Record<string, unknown>): Promise<unknown>;
+/** AK/SK 模式：mercury 网关，V4 签名（Action=WebSearch） */
+export declare function webSearchByAkSk(credentials: VolcengineCredentials, payload: Record<string, unknown>): Promise<unknown>;

package/dist/lib/search.js

@@ -0,0 +1,160 @@
+/**
+ * 火山引擎联网搜索（豆包搜索 / WebSearch）。
+ * 移植自 mcp-server/server/mcp_server_askecho_search_infinity（Python）。
+ * 两条调用路径：
+ * - API Key 模式: POST https://open.feedcoopapi.com/search_api/web_search（Bearer）
+ * - AK/SK 模式:  POST https://mercury.volcengineapi.com/?Action=WebSearch&Version=2025-01-01（V4 签名）
+ */
+import { VolcengineClient } from './client.js';
+/** API Key 模式网关 */
+export const SEARCH_API_HOST = 'open.feedcoopapi.com';
+/** AK/SK 模式（火山 mercury 网关） */
+export const SEARCH_V4_HOST = 'mercury.volcengineapi.com';
+export const SEARCH_V4_SERVICE = 'volc_torchlight_api';
+export const SEARCH_V4_VERSION = '2025-01-01';
+export const SEARCH_V4_REGION = 'cn-beijing';
+const TIME_RANGE_SHORTCUTS = new Set(['OneDay', 'OneWeek', 'OneMonth', 'OneYear']);
+const SUPPORTED_INDUSTRIES = new Set(['finance', 'game', 'gov']);
+const SUPPORTED_CONTENT_FORMATS = new Set(['text', 'markdown']);
+function validateTimeRange(timeRange) {
+    if (!timeRange)
+        return undefined;
+    if (TIME_RANGE_SHORTCUTS.has(timeRange))
+        return timeRange;
+    const match = /^(\d{4}-\d{2}-\d{2})\.\.(\d{4}-\d{2}-\d{2})$/.exec(timeRange);
+    if (!match) {
+        throw new Error('timeRange 需为 OneDay/OneWeek/OneMonth/OneYear，或日期区间 YYYY-MM-DD..YYYY-MM-DD');
+    }
+    const [startText, endText] = match.slice(1);
+    const start = new Date(startText);
+    const end = new Date(endText);
+    if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
+        throw new Error('timeRange 中的日期需为有效的 YYYY-MM-DD');
+    }
+    if (start > end)
+        throw new Error('timeRange 的开始日期不能晚于结束日期');
+    return timeRange;
+}
+function validateHostList(value, fieldName, maxCount) {
+    if (!value || value.length === 0)
+        return undefined;
+    const items = value.map((item) => item.trim()).filter((item) => item.length > 0);
+    if (items.length === 0)
+        throw new Error(`${fieldName} 需为非空域名列表`);
+    if (items.length > maxCount)
+        throw new Error(`${fieldName} 最多支持 ${maxCount} 个域名`);
+    return items.join('|');
+}
+/** 参数校验并组装请求 payload（结构与官方 WebSearch 接口一致，大写字段名） */
+export function buildWebSearchPayload(params) {
+    const query = (params.query ?? '').trim();
+    if (!query)
+        throw new Error('query 不能为空');
+    if (query.length > 100)
+        throw new Error('query 长度需为 1~100 个字符');
+    const searchType = (params.searchType ?? 'web').toLowerCase();
+    if (searchType !== 'web' && searchType !== 'image') {
+        throw new Error('searchType 仅支持 web 或 image');
+    }
+    const count = params.count ?? (searchType === 'web' ? 10 : 5);
+    if (count < 1)
+        throw new Error('count 需大于等于 1');
+    const maxCount = searchType === 'web' ? 50 : 5;
+    if (count > maxCount)
+        throw new Error(`${searchType} 类型最多返回 ${maxCount} 条`);
+    const authLevel = params.authLevel ?? 0;
+    if (authLevel !== 0 && authLevel !== 1)
+        throw new Error('authLevel 仅支持 0 或 1');
+    const industry = params.industry?.toLowerCase();
+    if (industry && !SUPPORTED_INDUSTRIES.has(industry)) {
+        throw new Error('industry 仅支持 finance、game 或 gov');
+    }
+    const contentFormats = params.contentFormats?.toLowerCase();
+    if (contentFormats && !SUPPORTED_CONTENT_FORMATS.has(contentFormats)) {
+        throw new Error('contentFormats 仅支持 text 或 markdown');
+    }
+    const queryControl = params.queryRewrite !== undefined ? { QueryRewrite: params.queryRewrite } : undefined;
+    if (searchType === 'image') {
+        const webOnly = [
+            ['timeRange', params.timeRange],
+            ['authLevel', authLevel || undefined],
+            ['needContent', params.needContent],
+            ['needUrl', params.needUrl],
+            ['sites', params.sites?.length ? params.sites : undefined],
+            ['blockHosts', params.blockHosts?.length ? params.blockHosts : undefined],
+            ['industry', industry],
+            ['contentFormats', contentFormats],
+        ];
+        const unsupported = webOnly.filter(([, v]) => v !== undefined).map(([k]) => k);
+        if (unsupported.length > 0) {
+            throw new Error(`${unsupported.join(', ')} 仅支持 web 搜索`);
+        }
+        const payload = { Query: query, SearchType: searchType, Count: count };
+        if (queryControl)
+            payload.QueryControl = queryControl;
+        return payload;
+    }
+    const filter = {};
+    if (authLevel > 0)
+        filter.AuthInfoLevel = authLevel;
+    if (params.needContent !== undefined)
+        filter.NeedContent = params.needContent;
+    if (params.needUrl !== undefined)
+        filter.NeedUrl = params.needUrl;
+    const sites = validateHostList(params.sites, 'sites', 20);
+    if (sites)
+        filter.Sites = sites;
+    const blockHosts = validateHostList(params.blockHosts, 'blockHosts', 5);
+    if (blockHosts)
+        filter.BlockHosts = blockHosts;
+    if (industry)
+        filter.Industry = industry;
+    const payload = { Query: query, SearchType: searchType, Count: count };
+    if (Object.keys(filter).length > 0)
+        payload.Filter = filter;
+    const timeRange = validateTimeRange(params.timeRange);
+    if (timeRange)
+        payload.TimeRange = timeRange;
+    if (queryControl)
+        payload.QueryControl = queryControl;
+    if (contentFormats)
+        payload.ContentFormats = contentFormats;
+    return payload;
+}
+const REQUEST_TIMEOUT_MS = 30_000;
+/** API Key 模式：feedcoopapi 网关，Bearer 鉴权 */
+export async function webSearchByApiKey(apiKey, payload) {
+    const res = await fetch(`https://${SEARCH_API_HOST}/search_api/web_search`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+            'X-Traffic-Tag': 'volcengine-api-mcp_web_search',
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    const text = await res.text();
+    if (!res.ok)
+        throw new Error(`搜索接口返回 ${res.status}:${text.slice(0, 300)}`);
+    return JSON.parse(text);
+}
+/** AK/SK 模式：mercury 网关，V4 签名（Action=WebSearch） */
+export async function webSearchByAkSk(credentials, payload) {
+    const client = new VolcengineClient({
+        credentials,
+        region: SEARCH_V4_REGION,
+        timeoutMs: REQUEST_TIMEOUT_MS,
+    });
+    const res = await client.request({
+        method: 'POST',
+        service: SEARCH_V4_SERVICE,
+        action: 'WebSearch',
+        version: SEARCH_V4_VERSION,
+        host: SEARCH_V4_HOST,
+        params: payload,
+        headers: { 'X-Traffic-Tag': 'volcengine-api-mcp_web_search' },
+    });
+    return res.body;
+}
+//# sourceMappingURL=search.js.map

package/dist/lib/search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"search.js","sourceRoot":"","sources":["../../src/lib/search.ts"],"names":[],"mappings":"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"}

package/dist/lib/signer.d.ts

@@ -0,0 +1,17 @@
+export interface SignOptions {
+    method: string;
+    path: string;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+    /** 已序列化的 body（GET 时为空字符串） */
+    body: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    region: string;
+    service: string;
+}
+/**
+ * 火山引擎 Signature V4 签名。
+ * 返回需要附加到请求的 header（Authorization / X-Date / X-Content-Sha256）。
+ */
+export declare function signRequest(opts: SignOptions): Record<string, string>;

package/dist/lib/signer.js

@@ -0,0 +1,58 @@
+import { createHash, createHmac } from 'node:crypto';
+const SHA256_HEX = (data) => createHash('sha256').update(data).digest('hex');
+const HMAC_SHA256_HEX = (key, data) => createHmac('sha256', key).update(data).digest('hex');
+const HMAC_SHA256_RAW = (key, data) => createHmac('sha256', key).update(data).digest();
+/** RFC3986 编码（火山签名要求，空格编码为 %20 而非 +） */
+function uriEncode(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (ch) => `%${ch.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+ * 火山引擎 Signature V4 签名。
+ * 返回需要附加到请求的 header（Authorization / X-Date / X-Content-Sha256）。
+ */
+export function signRequest(opts) {
+    const xDate = opts.headers['X-Date'] ?? new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+    const date = xDate.slice(0, 10);
+    const payloadHash = SHA256_HEX(opts.body);
+    const headers = {
+        ...opts.headers,
+        'X-Date': xDate,
+        'X-Content-Sha256': payloadHash,
+    };
+    // 1. Canonical Request
+    const sortedHeaders = Object.keys(headers)
+        .map((k) => [k.toLowerCase(), String(headers[k]).trim()])
+        .sort(([a], [b]) => (a < b ? -1 : 1));
+    const canonicalHeaders = sortedHeaders.map(([k, v]) => `${k}:${v}\n`).join('');
+    const signedHeaders = sortedHeaders.map(([k]) => k).join(';');
+    const canonicalQuery = Object.entries(opts.query)
+        .map(([k, v]) => [uriEncode(k), uriEncode(v)])
+        .sort(([a], [b]) => (a < b ? -1 : 1))
+        .map(([k, v]) => `${k}=${v}`)
+        .join('&');
+    const canonicalRequest = [
+        opts.method.toUpperCase(),
+        opts.path,
+        canonicalQuery,
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join('\n');
+    // 2. String to Sign
+    const credentialScope = `${date}/${opts.region}/${opts.service}/request`;
+    const stringToSign = [
+        'HMAC-SHA256',
+        xDate,
+        credentialScope,
+        SHA256_HEX(canonicalRequest),
+    ].join('\n');
+    // 3. Signature
+    let signingKey = HMAC_SHA256_RAW(opts.secretAccessKey, date);
+    for (const part of [opts.region, opts.service, 'request']) {
+        signingKey = HMAC_SHA256_RAW(signingKey, part);
+    }
+    const signature = HMAC_SHA256_HEX(signingKey, stringToSign);
+    const authorization = `HMAC-SHA256 Credential=${opts.accessKeyId}/${credentialScope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return { 'X-Date': xDate, 'X-Content-Sha256': payloadHash, Authorization: authorization };
+}
+//# sourceMappingURL=signer.js.map

package/dist/lib/signer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../../src/lib/signer.ts"],"names":[],"mappings":"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"}

package/dist/lib/tos.d.ts

@@ -0,0 +1,29 @@
+/** 按扩展名映射 Content-Type（覆盖常见音视频/图片/文档类型） */
+export declare const CONTENT_TYPES: Record<string, string>;
+export declare const TOS_ENV_NAMES: Record<string, string>;
+export interface TosOptions {
+    accessKeyId: string;
+    accessKeySecret: string;
+    bucket: string;
+    region: string;
+    endpoint?: string;
+}
+export interface TosResolveInput extends Partial<TosOptions> {
+    prefix?: string;
+}
+/** 读取 VOLC_TOS_* 环境变量（可被显式参数覆盖）；配置不全时抛出缺失变量清单 */
+export declare function resolveTosOptions(overrides?: TosResolveInput): TosOptions & {
+    prefix: string;
+};
+/** Object key：<prefix>/<date>/<basename>（空格转连字符） */
+export declare function buildObjectKey(prefix: string, date: string, filePath: string): string;
+/**
+ * 上传本地文件到 TOS 并返回预签名下载 URL。
+ * expires 默认 24h（86400s）；contentType 不传时按扩展名推导。
+ */
+export declare function uploadToTos(opts: TosOptions, filePath: string, key: string, expires?: number, contentType?: string): Promise<{
+    url: string;
+    key: string;
+    bytes: number;
+    bucket: string;
+}>;

package/dist/lib/tos.js

@@ -0,0 +1,93 @@
+/**
+ * 火山引擎 TOS 上传：putObject + 预签名下载 URL（bucket 保持私有）。
+ * 凭据来自 VOLC_TOS_* 环境变量。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { TosClient } from '@volcengine/tos-sdk';
+/** 按扩展名映射 Content-Type（覆盖常见音视频/图片/文档类型） */
+export const CONTENT_TYPES = {
+    wav: 'audio/wav',
+    mp3: 'audio/mpeg',
+    ogg: 'audio/ogg',
+    spx: 'audio/ogg',
+    amr: 'audio/amr',
+    aac: 'audio/aac',
+    m4a: 'audio/mp4',
+    mp4: 'video/mp4',
+    mov: 'video/quicktime',
+    webm: 'video/webm',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    svg: 'image/svg+xml',
+    pdf: 'application/pdf',
+    txt: 'text/plain',
+    json: 'application/json',
+    zip: 'application/zip',
+};
+export const TOS_ENV_NAMES = {
+    accessKeyId: 'VOLC_TOS_ACCESS_KEY',
+    accessKeySecret: 'VOLC_TOS_SECRET_KEY',
+    bucket: 'VOLC_TOS_BUCKET',
+    region: 'VOLC_TOS_REGION',
+    endpoint: 'VOLC_TOS_ENDPOINT',
+};
+/** 读取 VOLC_TOS_* 环境变量（可被显式参数覆盖）；配置不全时抛出缺失变量清单 */
+export function resolveTosOptions(overrides) {
+    const resolved = {
+        accessKeyId: overrides?.accessKeyId ?? process.env.VOLC_TOS_ACCESS_KEY,
+        accessKeySecret: overrides?.accessKeySecret ?? process.env.VOLC_TOS_SECRET_KEY,
+        bucket: overrides?.bucket ?? process.env.VOLC_TOS_BUCKET,
+        region: overrides?.region ?? process.env.VOLC_TOS_REGION,
+        endpoint: overrides?.endpoint ?? process.env.VOLC_TOS_ENDPOINT,
+    };
+    const missing = ['accessKeyId', 'accessKeySecret', 'bucket', 'region']
+        .filter((k) => !resolved[k])
+        .map((k) => TOS_ENV_NAMES[k]);
+    if (missing.length > 0) {
+        throw new Error(`缺少 TOS 配置，请设置环境变量：${missing.join(', ')}`);
+    }
+    return {
+        accessKeyId: resolved.accessKeyId,
+        accessKeySecret: resolved.accessKeySecret,
+        bucket: resolved.bucket,
+        region: resolved.region,
+        endpoint: resolved.endpoint,
+        prefix: overrides?.prefix ?? process.env.VOLC_TOS_PREFIX ?? 'volcengine-api-mcp',
+    };
+}
+/** Object key：<prefix>/<date>/<basename>（空格转连字符） */
+export function buildObjectKey(prefix, date, filePath) {
+    const base = path.basename(filePath).replace(/\s+/g, '-');
+    return `${prefix}/${date}/${base}`;
+}
+/**
+ * 上传本地文件到 TOS 并返回预签名下载 URL。
+ * expires 默认 24h（86400s）；contentType 不传时按扩展名推导。
+ */
+export async function uploadToTos(opts, filePath, key, expires = 86_400, contentType) {
+    if (!fs.existsSync(filePath)) {
+        throw new Error(`本地文件不存在：${filePath}`);
+    }
+    const size = fs.statSync(filePath).size;
+    const client = new TosClient({
+        accessKeyId: opts.accessKeyId,
+        accessKeySecret: opts.accessKeySecret,
+        region: opts.region,
+        ...(opts.endpoint ? { endpoint: opts.endpoint } : {}),
+    });
+    const ext = path.extname(filePath).replace(/^\./, '').toLowerCase();
+    await client.putObject({
+        bucket: opts.bucket,
+        key,
+        body: fs.createReadStream(filePath),
+        contentLength: size,
+        contentType: contentType ?? CONTENT_TYPES[ext] ?? 'application/octet-stream',
+    });
+    const url = client.getPreSignedUrl({ bucket: opts.bucket, key, method: 'GET', expires });
+    return { url, key, bytes: size, bucket: opts.bucket };
+}
+//# sourceMappingURL=tos.js.map

package/dist/lib/tos.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tos.js","sourceRoot":"","sources":["../../src/lib/tos.ts"],"names":[],"mappings":"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"}

package/dist/lib/tts.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 豆包语音合成大模型 - 单向流式 HTTP 接口（HTTP Chunked）。
+ * 文档: https://www.volcengine.com/docs/6561/1327536 （单向流式语音合成 HTTP）
+ * - Agent Plan 网关: POST https://openspeech.bytedance.com/api/v3/plan/tts/unidirectional（ark- 密钥）
+ * - 语音控制台:     POST https://openspeech.bytedance.com/api/v3/tts/unidirectional（X-Api-Key）
+ * 响应为流式 JSON 分片，每片 {code, message, data: base64音频, sentence?, usage?}，拼接 data 直到流结束。
+ */
+/** 语音控制台密钥使用的官方端点（Agent Plan 之外的接入方式，暂未暴露为工具参数） */
+export declare const CONSOLE_TTS_URL = "https://openspeech.bytedance.com/api/v3/tts/unidirectional";
+export declare const TTS_DEFAULT_SPEAKER = "zh_female_vv_uranus_bigtts";
+export declare const TTS_DEFAULT_RESOURCE_ID = "seed-tts-2.0";
+export declare const TTS_DEFAULT_SAMPLE_RATE = 24000;
+export type TtsAudioFormat = 'mp3' | 'pcm' | 'ogg_opus' | 'wav';
+export interface TtsOptions {
+    apiKey: string;
+    text: string;
+    speaker?: string;
+    /** 模型版本资源：seed-tts-2.0 / seed-icl-2.0（复刻音色） */
+    resourceId?: string;
+    /** 复刻音色时需指定，如 seed-tts-2.0-standard */
+    model?: string;
+    format?: TtsAudioFormat;
+    sampleRate?: number;
+    /** 语速 [-50, 100]，100 = 2.0 倍速 */
+    speechRate?: number;
+    /** 音量 [-50, 100]，100 = 2.0 倍音量 */
+    loudnessRate?: number;
+    enableSubtitle?: boolean;
+    /** 显式朗读语种，如 zh-cn / en / ja */
+    explicitLanguage?: string;
+    /** 覆盖默认端点 */
+    endpoint?: string;
+    timeoutMs?: number;
+}
+export interface TtsResult {
+    audio: Buffer;
+    format: TtsAudioFormat;
+    sampleRate: number;
+    /** 最后一个分片的句级信息（含字幕时间戳，enableSubtitle 开启时） */
+    sentence?: {
+        text: string;
+        words?: Array<{
+            word: string;
+            startTime: number;
+            endTime: number;
+            confidence?: number;
+        }>;
+    };
+    usage?: {
+        text_words?: number;
+    };
+}
+/** 从流式 buffer 中提取顶层 JSON 对象（兼容换行分隔与直接拼接两种分片方式） */
+export declare function extractJsonObjects(buffer: string): {
+    objects: unknown[];
+    rest: string;
+};
+/** 提交单向流式合成并收集完整音频。 */
+export declare function unidirectionalTts(opts: TtsOptions): Promise<TtsResult>;