dsh-voice 0.3.2 → 0.3.4

package/README.en.md

@@ -11,10 +11,12 @@ DSH (DeepSeek Harness) voice plugin pair: let the agent **speak and listen**.
 - **voice_tts**: text-to-speech over the **edge-tts protocol** (Microsoft Edge read-aloud service — free, unlimited, 22+ curated voices)
 - **voice_stt**: speech-to-text over any **OpenAI-compatible ASR endpoint** (Groq / OpenAI / custom)
 - **voice_list**: voice catalog
+- **voice_preview**: batch-generate short preview MP3s to pick a voice by ear
+- **voice_health**: offline self-check of TTS voice / ASR key / endpoint / proxy
 
 ## Compatibility
 
-Verified against `@deepseek-ai/dsh@0.1.2-alpha.2` on 2026-08-31. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Verified with official `@deepseek-ai/dsh@0.1.5-rc.1` and Node `24.16.0` on 2026-09-11: all 18 components load alongside Modlens, with passing tool-schema, skill-registration and offline read-only invocation checks. Uses the `cordis.patch.yml` + `dsh.bundle.patch` bundle model. Node requirements match this Harness release: 22.19 or later within 22.x, or 24 or later. Live external-service workflows require separate configuration and validation.
 
 ## Installation
 
@@ -53,6 +55,8 @@ Then restart the web service. To clean up fully, also remove the plugin entry fr
 | `voice_tts` | Synthesize MP3 from text (free) | `text` required; `voice`/`rate`/`pitch`/`output` optional |
 | `voice_stt` | Transcribe audio to text | `audio` required; `engine`/`model`/`language`/`prompt`/`output` optional |
 | `voice_list` | Curated voice catalog | none |
+| `voice_preview` | Batch-generate short preview MP3s | optional `voices` (≤8) / `text` / `outputDir` |
+| `voice_health` | Offline config self-check | none |
 
 ### Examples
 
@@ -61,6 +65,8 @@ voice_tts { text: hello world }                              # outputs voice_out
 voice_tts { text: hello, voice: en-US-AriaNeural }           # English female voice
 voice_stt { audio: E:\audio\meeting.mp3, language: zh }     # transcribe a recording
 voice_list {}
+voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # generate two preview samples
+voice_health {}                                              # self-check TTS / ASR / proxy config
 ```
 
 ## Under the hood
@@ -81,3 +87,7 @@ pnpm test:integration  # opt-in real edge-tts request; network and assertion err
 ## License
 
 MIT
+
+## Changelog
+
+- **0.3.4 (2026-09-18)**: 修复代理路径 STT 上传 `[object FormData]`、25MB 校验在读入之后、输出目录不存在白烧一次合成、默认输出落宿主 cwd; `exec.signal` 全程透传、preview 改 3 路并发. 测试 55 项. 

package/README.md

@@ -14,10 +14,12 @@ DSH（DeepSeek Harness）语音双件套插件：让 agent **会说话、能听
 - **voice_tts**：文字转语音，走 **edge-tts 协议**（微软 Edge 朗读服务，免费无限量，22+ 常用音色）
 - **voice_stt**：语音转文字，走 **OpenAI 兼容 ASR 接口**（Groq / OpenAI / 自定义端点）
 - **voice_list**：音色清单
+- **voice_preview**：音色试听，用一段样例文本批量生成短 MP3，挑音色不用盲选
+- **voice_health**：配置自检，体检 TTS 音色 / ASR 密钥 / 接口地址 / 代理（不联网）
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+已在官方 `@deepseek-ai/dsh@0.1.5-rc.1`、Node `24.16.0` 上验证（2026-09-11）：18 个组件与 Modlens 同载，工具 schema、技能注册及离线只读调用检查通过。采用 `cordis.patch.yml` + `dsh.bundle.patch` 组合包模型。Node 要求与该版本 Harness 一致：22.19 及以上的 22.x，或 24 及以上。外部服务的实际业务操作需按各组件配置单独验证。
 
 ## 安装
 
@@ -56,6 +58,8 @@ dsh plugin --profile web remove dsh-voice
 | `voice_tts` | 文字合成 MP3（免费） | `text` 必填；`voice`/`rate`/`pitch`/`output` 可选 |
 | `voice_stt` | 音频转文字 | `audio` 必填；`engine`/`model`/`language`/`prompt`/`output` 可选 |
 | `voice_list` | 常用音色清单 | 无 |
+| `voice_preview` | 音色试听：批量生成短样例 MP3 | `voices`（≤8 个）/ `text` / `outputDir` 可选 |
+| `voice_health` | 配置自检（不联网） | 无 |
 
 ### 示例
 
@@ -64,6 +68,8 @@ voice_tts { text: 今天的 AI 早报来了 }                    # 晓晓女声
 voice_tts { text: hello, voice: en-US-AriaNeural }        # 英文女声
 voice_stt { audio: E:\audio\meeting.mp3, language: zh } # 转写会议录音
 voice_list {}
+voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # 生成两个试听样例
+voice_health {}                                          # 自检 TTS / ASR / 代理配置
 ```
 
 ## 硬核细节
@@ -84,3 +90,7 @@ pnpm test:integration  # 显式联网，调用真实 edge-tts；网络或断言
 ## License
 
 MIT
+
+## 版本记录
+
+- **0.3.4（2026-09-18）**：修复代理路径 STT 上传 `[object FormData]`、25MB 校验在读入之后、输出目录不存在白烧一次合成、默认输出落宿主 cwd；`exec.signal` 全程透传、preview 改 3 路并发。测试 55 项。

package/lib/config.d.ts

@@ -32,6 +32,7 @@ export interface ResolvedVoiceConfig {
 /** ASR 密钥：配置优先，其次环境变量 DSH_VOICE_ASR_KEY。 */
 export declare function resolveAsrApiKey(config: VoiceConfig | undefined, env?: NodeJS.ProcessEnv): string;
 /**
- * 解析并校验配置。
+ * 解析并校验配置：非法字段逐项回退到默认值，其余字段照常生效。
+ * @param onWarning 非法字段的告警回调，默认打到 console.warn。
  */
-export declare function resolveConfig(config: VoiceConfig | undefined | null): ResolvedVoiceConfig;
+export declare function resolveConfig(config: VoiceConfig | undefined | null, onWarning?: (message: string) => void): ResolvedVoiceConfig;

package/lib/config.js

@@ -14,10 +14,15 @@ export function resolveAsrApiKey(config, env = process.env) {
         return cfg.asrApiKey.trim();
     return env.DSH_VOICE_ASR_KEY?.trim() ?? '';
 }
+/** 默认告警出口：非法字段逐项回退时点名，避免一个字段拖垮整份配置。 */
+function defaultWarn(message) {
+    console.warn('[dsh-voice] ' + message);
+}
 /**
- * 解析并校验配置。
+ * 解析并校验配置：非法字段逐项回退到默认值，其余字段照常生效。
+ * @param onWarning 非法字段的告警回调，默认打到 console.warn。
  */
-export function resolveConfig(config) {
+export function resolveConfig(config, onWarning = defaultWarn) {
     const cfg = config ?? {};
     const ttsVoice = typeof cfg.ttsVoice === 'string' && cfg.ttsVoice.trim() !== '' ? cfg.ttsVoice.trim() : 'zh-CN-XiaoxiaoNeural';
     const ttsRate = typeof cfg.ttsRate === 'string' && cfg.ttsRate.trim() !== '' ? cfg.ttsRate.trim() : '+0%';
@@ -27,14 +32,19 @@ export function resolveConfig(config) {
     const asrBaseUrl = (typeof cfg.asrBaseUrl === 'string' && cfg.asrBaseUrl.trim() !== '' ? cfg.asrBaseUrl.trim() : preset?.baseUrl ?? '').replace(/\/$/, '');
     const asrModel = typeof cfg.asrModel === 'string' && cfg.asrModel.trim() !== '' ? cfg.asrModel.trim() : preset?.model ?? '';
     const asrApiKey = resolveAsrApiKey(cfg);
-    const proxyUrl = (typeof cfg.proxyUrl === 'string' && cfg.proxyUrl.trim() !== '' ? cfg.proxyUrl.trim() : '');
-    if (proxyUrl !== '' && !/^https?:\/\//i.test(proxyUrl))
-        throw new Error('proxyUrl 必须是 http(s):// 开头的地址，例如 http://127.0.0.1:7890。');
+    let proxyUrl = typeof cfg.proxyUrl === 'string' && cfg.proxyUrl.trim() !== '' ? cfg.proxyUrl.trim() : '';
+    if (proxyUrl !== '' && !/^https?:\/\//i.test(proxyUrl)) {
+        onWarning('proxyUrl 配置不合法（必须以 http(s):// 开头，例如 http://127.0.0.1:7890），已忽略该项，其余配置继续生效：' + proxyUrl);
+        proxyUrl = '';
+    }
     let timeoutMs = 60000;
     if (cfg.timeoutMs !== undefined) {
-        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0)
-            throw new Error('timeoutMs 必须是大于 0 的数字（毫秒）。');
-        timeoutMs = Math.min(10 * 60 * 1000, Math.max(5000, Math.round(cfg.timeoutMs)));
+        if (typeof cfg.timeoutMs !== 'number' || !Number.isFinite(cfg.timeoutMs) || cfg.timeoutMs <= 0) {
+            onWarning('timeoutMs 配置不合法（必须是大于 0 的数字，毫秒），已回退默认值 60000。');
+        }
+        else {
+            timeoutMs = Math.min(10 * 60 * 1000, Math.max(5000, Math.round(cfg.timeoutMs)));
+        }
     }
     const overwrite = cfg.overwrite === true;
     return { ttsVoice, ttsRate, ttsPitch, asrEngine, asrBaseUrl, asrApiKey, asrModel, proxyUrl, timeoutMs, overwrite };

package/lib/edge-tts.d.ts

@@ -10,6 +10,8 @@ export interface TtsDeps {
     webSocketFactory?: WebSocketFactory;
     nowSeconds?: () => number;
     proxyUrl?: string;
+    /** 取消信号（可选）；也可通过 synthesizeSpeech 第 4 个参数传入。 */
+    signal?: AbortSignal;
 }
 /** 最小的 WebSocket 面。 */
 export interface WebSocketLike {
@@ -33,4 +35,4 @@ export declare function buildSsml(options: TtsOptions): string;
  * 合成语音，返回 MP3 字节。
  * @throws 文本为空/超长 / 连接失败 / 超时 / 无音频数据时抛中文错误。
  */
-export declare function synthesizeSpeech(options: TtsOptions, deps?: TtsDeps, timeoutMs?: number): Promise<Buffer>;
+export declare function synthesizeSpeech(options: TtsOptions, deps?: TtsDeps, timeoutMs?: number, signal?: AbortSignal): Promise<Buffer>;

package/lib/edge-tts.js

@@ -62,7 +62,10 @@ function protocolHeader(path, extra) {
  * 合成语音，返回 MP3 字节。
  * @throws 文本为空/超长 / 连接失败 / 超时 / 无音频数据时抛中文错误。
  */
-export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
+export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000, signal) {
+    const abortSignal = signal ?? deps.signal;
+    if (abortSignal?.aborted === true)
+        throw abortSignal.reason;
     if (options.text.trim() === '')
         throw new Error('要合成的文本为空。');
     if (options.text.length > 5000)
@@ -77,17 +80,56 @@ export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
     const chunks = [];
     let done = false;
     await new Promise((resolvePromise, reject) => {
-        const timer = setTimeout(() => {
+        const canListen = typeof abortSignal?.addEventListener === 'function';
+        let settled = false;
+        let timer;
+        let onAbort = () => { };
+        // 先结算再关 socket：即使 socket.close() 同步触发 close 事件，取消原因也不会被通用错误覆盖。
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (canListen)
+                abortSignal.removeEventListener('abort', onAbort);
+            reject(error);
+        };
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            if (canListen)
+                abortSignal.removeEventListener('abort', onAbort);
+            try {
+                socket.close();
+            }
+            catch { /* 忽略 */ }
+            resolvePromise();
+        };
+        onAbort = () => {
+            const reason = abortSignal?.reason ?? new Error('语音合成已取消。');
+            fail(reason);
+            try {
+                socket.close();
+            }
+            catch { /* 忽略 */ }
+        };
+        timer = setTimeout(() => {
+            fail(new Error('语音合成超时（' + timeoutMs + ' 毫秒无完整音频），请重试或检查网络。'));
             try {
                 socket.close();
             }
             catch { /* 忽略 */ }
-            reject(new Error('语音合成超时（' + timeoutMs + ' 毫秒无完整音频），请重试或检查网络。'));
         }, timeoutMs);
-        const finish = () => { clearTimeout(timer); try {
-            socket.close();
+        if (canListen)
+            abortSignal.addEventListener('abort', onAbort, { once: true });
+        if (abortSignal?.aborted === true) {
+            onAbort();
+            return;
         }
-        catch { /* 忽略 */ } resolvePromise(); };
         socket.addEventListener('open', () => {
             const config = protocolHeader('speech.config', { 'Content-Type': 'application/json; charset=utf-8' })
                 + JSON.stringify({
@@ -103,8 +145,7 @@ export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
                 socket.send(ssml);
             }
             catch (error) {
-                clearTimeout(timer);
-                reject(error instanceof Error ? error : new Error(String(error)));
+                fail(error instanceof Error ? error : new Error(String(error)));
             }
         });
         socket.addEventListener('message', (event) => {
@@ -112,8 +153,7 @@ export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
             if (typeof data === 'string') {
                 if (data.includes('Path:turn.end')) {
                     if (chunks.length === 0) {
-                        clearTimeout(timer);
-                        reject(new Error('合成结束但没有收到音频数据（服务端可能拒绝了请求）。'));
+                        fail(new Error('合成结束但没有收到音频数据（服务端可能拒绝了请求）。'));
                     }
                     else if (!done) {
                         done = true;
@@ -132,18 +172,16 @@ export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
             }
         });
         socket.addEventListener('error', () => {
-            clearTimeout(timer);
-            reject(new Error('edge-tts WebSocket 连接失败。若网络需要特殊代理（梯子），请在 cordis.patch.yml 配置 proxyUrl 后重启。'));
+            fail(new Error('edge-tts WebSocket 连接失败。若网络需要特殊代理（梯子），请在 cordis.patch.yml 配置 proxyUrl 后重启。'));
         });
         socket.addEventListener('close', () => {
             if (!done) {
-                clearTimeout(timer);
                 if (chunks.length > 0) {
                     done = true;
                     finish();
                 }
                 else {
-                    reject(new Error('edge-tts 连接在收到音频前关闭。'));
+                    fail(new Error('edge-tts 连接在收到音频前关闭。'));
                 }
             }
         });

package/lib/index.d.ts

@@ -1,9 +1,9 @@
 /**
  * dsh-voice —— 语音双件套工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册三个面向模型的工具（voice_tts / voice_stt /
- * voice_list）。TTS 走 edge-tts 协议（原生 WebSocket，零 API 成本）；STT 走 OpenAI
- * 兼容 ASR 接口（Groq/OpenAI/自定义端点）。
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（voice_tts / voice_stt /
+ * voice_list / voice_preview / voice_health）。TTS 走 edge-tts 协议（原生 WebSocket，
+ * 零 API 成本）；STT 走 OpenAI 兼容 ASR 接口（Groq/OpenAI/自定义端点）。
  *
  * @module dsh-voice
  */
@@ -20,7 +20,7 @@ export interface VoicePluginContext {
     on?(event: string, listener: () => void): () => void;
 }
 /**
- * 插件入口：解析配置并注册三个语音工具。
+ * 插件入口：解析配置并注册五个语音工具。
  */
 export declare function apply(ctx: VoicePluginContext, config?: VoiceConfig | null): void;
 export * from './config.js';

package/lib/index.js

@@ -1,9 +1,9 @@
 /**
  * dsh-voice —— 语音双件套工具插件（node 半身，配置走 cordis.patch.yml）。
  *
- * 插件导出 apply(ctx, config)：注册三个面向模型的工具（voice_tts / voice_stt /
- * voice_list）。TTS 走 edge-tts 协议（原生 WebSocket，零 API 成本）；STT 走 OpenAI
- * 兼容 ASR 接口（Groq/OpenAI/自定义端点）。
+ * 插件导出 apply(ctx, config)：注册五个面向模型的工具（voice_tts / voice_stt /
+ * voice_list / voice_preview / voice_health）。TTS 走 edge-tts 协议（原生 WebSocket，
+ * 零 API 成本）；STT 走 OpenAI 兼容 ASR 接口（Groq/OpenAI/自定义端点）。
  *
  * @module dsh-voice
  */
@@ -13,7 +13,7 @@ import { buildVoiceTools } from './tools.js';
 export const name = 'voice';
 export const inject = ['tools'];
 /**
- * 插件入口：解析配置并注册三个语音工具。
+ * 插件入口：解析配置并注册五个语音工具。
  */
 export function apply(ctx, config) {
     let cfg;

package/lib/paths.d.ts

@@ -1,4 +1,4 @@
-/** 校验音频文件存在且是文件；返回绝对路径。 */
-export declare function assertAudioFile(input: string): string;
-/** 决定输出路径：缺省放在当前工作目录，同名自动加 _1/_2 序号。 */
-export declare function resolveOutputPath(explicit: string | undefined, defaultName: string, overwrite: boolean): string;
+/** 校验音频文件存在且是文件；相对路径按 cwd（会话工作区）解析，返回绝对路径。 */
+export declare function assertAudioFile(input: string, cwd?: string): string;
+/** 决定输出路径：缺省放在会话工作目录（缺省回退宿主 cwd），同名自动加 _1/_2 序号。 */
+export declare function resolveOutputPath(explicit: string | undefined, defaultName: string, overwrite: boolean, cwd?: string): string;

package/lib/paths.js

@@ -5,17 +5,17 @@
  */
 import { existsSync, statSync } from 'node:fs';
 import { basename, dirname, extname, join, resolve } from 'node:path';
-/** 校验音频文件存在且是文件；返回绝对路径。 */
-export function assertAudioFile(input) {
-    const absolute = resolve(input);
+/** 校验音频文件存在且是文件；相对路径按 cwd（会话工作区）解析，返回绝对路径。 */
+export function assertAudioFile(input, cwd = process.cwd()) {
+    const absolute = resolve(cwd, input);
     if (!existsSync(absolute) || !statSync(absolute).isFile()) {
         throw new Error('音频文件不存在：' + input);
     }
     return absolute;
 }
-/** 决定输出路径：缺省放在当前工作目录，同名自动加 _1/_2 序号。 */
-export function resolveOutputPath(explicit, defaultName, overwrite) {
-    let target = explicit !== undefined && explicit.trim() !== '' ? resolve(explicit.trim()) : resolve(process.cwd(), defaultName);
+/** 决定输出路径：缺省放在会话工作目录（缺省回退宿主 cwd），同名自动加 _1/_2 序号。 */
+export function resolveOutputPath(explicit, defaultName, overwrite, cwd = process.cwd()) {
+    let target = explicit !== undefined && explicit.trim() !== '' ? resolve(cwd, explicit.trim()) : resolve(cwd, defaultName);
     if (overwrite || !existsSync(target))
         return target;
     const directory = dirname(target);

package/lib/proxy-fetch.d.ts

@@ -1,4 +1,11 @@
 /**
- * 构造一个把所有请求路由到 proxyUrl 的 fetch。
+ * 代理 fetch 一并带出 undici 自己的 FormData 构造器。
+ *
+ * undici 的 fetch/Response 只认自己那份 FormData（brand symbol 属于该模块），而 Node 的
+ * 全局 FormData 是另一份实现：喂错会被当成普通对象序列化成 "[object FormData]"
+ * （content-type: text/plain），ASR 接口必回 400 —— 实测见 README 的代理场景。
  */
-export declare function createProxyFetch(proxyUrl: string): typeof globalThis.fetch;
+export type ProxyFetch = typeof globalThis.fetch & {
+    FormData: typeof globalThis.FormData;
+};
+export declare function createProxyFetch(proxyUrl: string): ProxyFetch;

package/lib/proxy-fetch.js

@@ -1,11 +1,10 @@
 /**
  * 插件级 HTTP 代理：给 TTS 令牌与 ASR 请求一个走指定代理的 fetch，不影响同进程其他插件。
  */
-import { ProxyAgent, fetch as undiciFetch } from 'undici';
-/**
- * 构造一个把所有请求路由到 proxyUrl 的 fetch。
- */
+import { FormData as UndiciFormData, ProxyAgent, fetch as undiciFetch } from 'undici';
 export function createProxyFetch(proxyUrl) {
     const agent = new ProxyAgent(proxyUrl);
-    return ((input, init) => undiciFetch(input, { ...init, dispatcher: agent }));
+    const impl = ((input, init) => undiciFetch(input, { ...init, dispatcher: agent }));
+    impl.FormData = UndiciFormData;
+    return impl;
 }

package/lib/stt.d.ts

@@ -5,12 +5,20 @@ export interface SttOptions {
     model: string;
     language?: string;
     prompt?: string;
+    /** 取消信号（可选）；也可通过 transcribe 第 6 个参数传入。 */
+    signal?: AbortSignal;
 }
+/** 字节数超过 25MB 时抛错：调用方可在读文件前先按 statSync 大小快速拒绝，避免白读整文件。 */
+export declare function assertAudioSize(bytes: number): void;
 /**
  * 调用 OpenAI 兼容 ASR 接口转写音频。
  * @throws 缺密钥 / 文件过大 / HTTP 错误 / 无文本时抛中文错误。
  */
-export declare function transcribe(baseUrl: string, apiKey: string, options: SttOptions, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<{
+/** 传给 transcribe 的 fetch：可以像代理那样一并带上自己的 FormData/Blob 构造器。 */
+export type SttFetch = typeof fetch & {
+    FormData?: typeof FormData;
+};
+export declare function transcribe(baseUrl: string, apiKey: string, options: SttOptions, fetchImpl?: SttFetch, timeoutMs?: number, signal?: AbortSignal): Promise<{
     text: string;
     model: string;
 }>;

package/lib/stt.js

@@ -5,20 +5,44 @@
  */
 import { extname } from 'node:path';
 const MAX_AUDIO_BYTES = 25 * 1024 * 1024;
-/**
- * 调用 OpenAI 兼容 ASR 接口转写音频。
- * @throws 缺密钥 / 文件过大 / HTTP 错误 / 无文本时抛中文错误。
- */
-export async function transcribe(baseUrl, apiKey, options, fetchImpl = globalThis.fetch, timeoutMs = 120000) {
+/** 字节数超过 25MB 时抛错：调用方可在读文件前先按 statSync 大小快速拒绝，避免白读整文件。 */
+export function assertAudioSize(bytes) {
+    if (bytes > MAX_AUDIO_BYTES)
+        throw new Error('音频超过 25MB 上限（ASR 接口限制），请先用 ffmpeg 压缩。');
+}
+/** 已取消则抛出取消原因；作为 await 前后的统一取消检查。 */
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw signal.reason;
+}
+/** 让不认 signal 的 fetch 实现也能在外部取消时立即 reject。 */
+function raceAbort(value, signal) {
+    const promise = Promise.resolve(value);
+    if (signal === undefined || typeof signal.addEventListener !== 'function')
+        return promise;
+    if (signal.aborted === true)
+        return Promise.reject(signal.reason);
+    return new Promise((resolvePromise, rejectPromise) => {
+        const onAbort = () => rejectPromise(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((settled) => { signal.removeEventListener('abort', onAbort); resolvePromise(settled); }, (error) => { signal.removeEventListener('abort', onAbort); rejectPromise(error); });
+    });
+}
+export async function transcribe(baseUrl, apiKey, options, fetchImpl = globalThis.fetch, timeoutMs = 120000, signal) {
+    const abortSignal = signal ?? options.signal;
+    throwIfAborted(abortSignal);
     if (apiKey === '')
         throw new Error('未配置 ASR 密钥：请设置环境变量 DSH_VOICE_ASR_KEY，或在 cordis.patch.yml 的 asrApiKey 配置后重启。');
     if (baseUrl === '')
         throw new Error('未配置 ASR 接口地址（asrEngine=custom 时必须提供 asrBaseUrl）。');
     if (options.audio.length === 0)
         throw new Error('音频文件为空。');
-    if (options.audio.length > MAX_AUDIO_BYTES)
-        throw new Error('音频超过 25MB 上限（ASR 接口限制），请先用 ffmpeg 压缩。');
-    const form = new FormData();
+    assertAudioSize(options.audio.length);
+    // 代理 fetch（undici）只认它自己那份 FormData：喂 Node 全局 FormData 会被当成普通
+    // 对象序列化成 "[object FormData]"（content-type: text/plain），所以优先用调用方 fetch
+    // 附带的构造器。文件部分继续用全局 Blob —— 实测 undici 的 FormData 收它并输出真 multipart。
+    const FormDataImpl = fetchImpl.FormData ?? FormData;
+    const form = new FormDataImpl();
     const mime = mimeOf(options.filename);
     form.append('file', new Blob([options.audio], { type: mime }), options.filename);
     form.append('model', options.model);
@@ -26,16 +50,19 @@ export async function transcribe(baseUrl, apiKey, options, fetchImpl = globalThi
         form.append('language', options.language);
     if (options.prompt !== undefined && options.prompt !== '')
         form.append('prompt', options.prompt);
+    const timeoutSignal = AbortSignal.timeout(timeoutMs);
+    const requestSignal = abortSignal === undefined ? timeoutSignal : AbortSignal.any([timeoutSignal, abortSignal]);
     let response;
     try {
-        response = await fetchImpl(baseUrl + '/audio/transcriptions', {
+        response = await raceAbort(fetchImpl(baseUrl + '/audio/transcriptions', {
             method: 'POST',
             headers: { authorization: 'Bearer ' + apiKey },
             body: form,
-            signal: AbortSignal.timeout(timeoutMs),
-        });
+            signal: requestSignal,
+        }), abortSignal);
     }
     catch (error) {
+        throwIfAborted(abortSignal);
         throw new Error('ASR 请求失败：' + (error instanceof Error ? error.message : String(error)) + '。若接口需要特殊代理（梯子），请在 cordis.patch.yml 配置 proxyUrl 后重启。');
     }
     if (!response.ok) {

package/lib/tools.js

@@ -1,14 +1,14 @@
 /**
- * 五个面向模型的语音工具：voice_tts / voice_stt / voice_list / voice_preview。
+ * 五个面向模型的语音工具：voice_tts / voice_stt / voice_list / voice_preview / voice_health。
  *
  * @module dsh-voice/tools
  */
-import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, join, resolve } from 'node:path';
+import { mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { synthesizeSpeech } from './edge-tts.js';
 import { assertAudioFile, resolveOutputPath } from './paths.js';
 import { createProxyFetch } from './proxy-fetch.js';
-import { transcribe } from './stt.js';
+import { assertAudioSize, transcribe } from './stt.js';
 import { isValidVoiceId, VOICES } from './voices.js';
 function compileParameters(spec) {
     const properties = {};
@@ -21,6 +21,10 @@ function compileParameters(spec) {
             node.type = prop.type;
         if (typeof prop?.description === 'string')
             node.description = prop.description;
+        if (prop?.enum !== undefined)
+            node.enum = prop.enum;
+        if (prop?.items !== undefined)
+            node.items = prop.items;
         properties[key] = node;
     }
     return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
@@ -38,6 +42,56 @@ function requiredString(args, key, label) {
         throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
     return value;
 }
+/** 取本次调用的取消信号；取不到就当未提供。 */
+function execSignal(exec) {
+    const signal = exec?.signal;
+    return signal !== null && typeof signal === 'object' && typeof signal.aborted === 'boolean' ? signal : undefined;
+}
+/** 已取消则抛出取消原因；作为 await 前后的统一取消检查。 */
+function throwIfAborted(signal) {
+    if (signal?.aborted === true)
+        throw signal.reason;
+}
+/** 让不认 signal 的实现也能在取消时立即 reject；signal 缺 addEventListener 时只能原样等待。 */
+function raceAbort(value, signal) {
+    const promise = Promise.resolve(value);
+    if (signal === undefined || typeof signal.addEventListener !== 'function')
+        return promise;
+    if (signal.aborted === true)
+        return Promise.reject(signal.reason);
+    return new Promise((resolvePromise, rejectPromise) => {
+        const onAbort = () => rejectPromise(signal.reason);
+        signal.addEventListener('abort', onAbort, { once: true });
+        promise.then((settled) => { signal.removeEventListener('abort', onAbort); resolvePromise(settled); }, (error) => { signal.removeEventListener('abort', onAbort); rejectPromise(error); });
+    });
+}
+/** 有界并发：同一时刻最多跑 limit 个任务；取消时停止派发并抛出取消原因。 */
+async function mapLimit(items, limit, signal, worker) {
+    const results = new Array(items.length);
+    let next = 0;
+    const run = async () => {
+        for (;;) {
+            throwIfAborted(signal);
+            const index = next;
+            next += 1;
+            if (index >= items.length)
+                return;
+            results[index] = await worker(items[index]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, () => run()));
+    return results;
+}
+/** 取本次调用的会话工作区；harness 从不 chdir，取不到时才回退宿主进程 cwd。 */
+function sessionCwd(exec) {
+    const cwd = exec?.agent?.session?.header?.cwd;
+    return typeof cwd === 'string' && cwd.trim() !== '' ? cwd : process.cwd();
+}
+/** 写文件前先建父目录，避免合成/转写完成后才因 ENOENT 白烧一次接口调用。 */
+function writeFileWithDir(target, data) {
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, data);
+}
 const voiceItemSchema = {
     type: 'object',
     properties: { id: { type: 'string' }, gender: { type: 'string' }, locale: { type: 'string' } },
@@ -83,6 +137,8 @@ const previewSchema = {
 };
 /** 默认试听文本（中英混合，便于感知发音差异）。 */
 export const DEFAULT_PREVIEW_TEXT = '你好，这是音色试听。Hello, this is a voice preview.';
+/** voice_preview 同时合成的音色数上限：有界并发，避免 8 个音色串行把最坏等待拖成 8 倍超时。 */
+const PREVIEW_CONCURRENCY = 3;
 /**
  * 构建三个工具定义。
  */
@@ -119,7 +175,7 @@ export function buildVoiceTools(config, deps = {}) {
             voice: { type: 'string', description: '音色 id（可选，默认配置的 ttsVoice）。' },
             rate: { type: 'string', description: '语速，如 +20% 或 -10%（可选）。' },
             pitch: { type: 'string', description: '音调，如 +2Hz 或 -1Hz（可选）。' },
-            output: { type: 'string', description: '输出 MP3 路径（可选）。' },
+            output: { type: 'string', description: '输出 MP3 路径（可选，相对路径按会话工作目录解析）。' },
         }),
         output: {
             schema: ttsSchema,
@@ -128,7 +184,9 @@ export function buildVoiceTools(config, deps = {}) {
                 return [{ type: 'text', text: '语音合成完成：' + rec.output + '（' + rec.bytes + ' 字节，音色 ' + rec.voice + '）' }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
+            const signal = execSignal(exec);
+            throwIfAborted(signal);
             const args = asRecord(rawArgs);
             const text = requiredString(args, 'text', '要合成的文本');
             if (text.length > 5000)
@@ -142,9 +200,10 @@ export function buildVoiceTools(config, deps = {}) {
                 if (!/^[+-]?\d+(\.\d+)?(%|Hz|st)$/.test(value))
                     throw new Error(label + ' 不合法：' + value + '。合法格式如 +10%、-2Hz、+1st。');
             }
-            const output = resolveOutputPath(optionalString(args, 'output'), 'voice_output.mp3', cfg.overwrite);
-            const audio = await (deps.tts ?? synthesizeSpeech)({ text, voice, rate, pitch }, { proxyUrl: cfg.proxyUrl }, timeout);
-            writeFileSync(output, audio);
+            const output = resolveOutputPath(optionalString(args, 'output'), 'voice_output.mp3', cfg.overwrite, sessionCwd(exec));
+            const audio = await raceAbort((deps.tts ?? synthesizeSpeech)({ text, voice, rate, pitch }, { proxyUrl: cfg.proxyUrl }, timeout, signal), signal);
+            throwIfAborted(signal);
+            writeFileWithDir(output, audio);
             return { output, bytes: audio.length, voice, rate, pitch, textLength: text.length };
         },
         timeoutMs: timeout + 10000,
@@ -154,11 +213,11 @@ export function buildVoiceTools(config, deps = {}) {
         description: '语音转文字：调用 OpenAI 兼容 ASR 接口（默认 Groq whisper-large-v3-turbo；可切 openai/custom）。audio 为音频文件路径（mp3/wav/m4a/ogg/flac，≤25MB）；language/prompt 可选；output 可把转写文本写成 .txt。密钥用环境变量 DSH_VOICE_ASR_KEY 或配置 asrApiKey。',
         parameters: compileParameters({
             audio: { type: 'string', required: true, description: '音频文件路径（必填）。' },
-            engine: { type: 'string', description: '引擎：groq / openai / custom（可选，默认配置值）。' },
+            engine: { type: 'string', enum: ['groq', 'openai', 'custom'], description: '引擎：groq / openai / custom（可选，默认配置值）。' },
             model: { type: 'string', description: '模型名（可选，覆盖配置）。' },
             language: { type: 'string', description: '语言提示，如 zh（可选）。' },
             prompt: { type: 'string', description: '提示词（专有名词/术语纠偏，可选）。' },
-            output: { type: 'string', description: '把转写文本写成 .txt 的路径（可选）。' },
+            output: { type: 'string', description: '把转写文本写成 .txt 的路径（可选，相对路径按会话工作目录解析）。' },
         }),
         output: {
             schema: sttSchema,
@@ -167,9 +226,12 @@ export function buildVoiceTools(config, deps = {}) {
                 return [{ type: 'text', text: '转写完成（模型 ' + rec.model + '）：' + rec.text }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
+            const signal = execSignal(exec);
+            throwIfAborted(signal);
             const args = asRecord(rawArgs);
-            const audioPath = assertAudioFile(requiredString(args, 'audio', '音频文件'));
+            const audioPath = assertAudioFile(requiredString(args, 'audio', '音频文件'), sessionCwd(exec));
+            assertAudioSize(statSync(audioPath).size);
             const engine = optionalString(args, 'engine') ?? cfg.asrEngine;
             let baseUrl;
             let model;
@@ -187,18 +249,19 @@ export function buildVoiceTools(config, deps = {}) {
             }
             else
                 throw new Error('engine 必须是 groq / openai / custom 之一（当前：' + engine + '）。');
-            const { text } = await (deps.stt ?? transcribe)(baseUrl, cfg.asrApiKey, {
+            const { text } = await raceAbort((deps.stt ?? transcribe)(baseUrl, cfg.asrApiKey, {
                 audio: readFileSync(audioPath),
                 filename: basename(audioPath),
                 model,
                 language: optionalString(args, 'language'),
                 prompt: optionalString(args, 'prompt'),
-            }, fetchImpl ?? globalThis.fetch, timeout);
+            }, fetchImpl ?? globalThis.fetch, timeout, signal), signal);
+            throwIfAborted(signal);
             let transcriptFile = '';
             const output = optionalString(args, 'output');
             if (output !== undefined) {
-                const target = resolveOutputPath(output, '', cfg.overwrite);
-                writeFileSync(target, text, 'utf8');
+                const target = resolveOutputPath(output, '', cfg.overwrite, sessionCwd(exec));
+                writeFileWithDir(target, text);
                 transcriptFile = target;
             }
             // The output schema declares these as strings — never return null, or
@@ -209,11 +272,11 @@ export function buildVoiceTools(config, deps = {}) {
     };
     const voicePreview = {
         name: 'voice_preview',
-        description: '音色试听：用一段固定试听文本批量生成短样例 MP3，方便挑选音色。voices 为音色 id 数组（可选，缺省 voice_list 前 4 个，最多 8 个）；text 可自定义（≤200 字符）；样例文件写入输出目录（默认工作目录 voice_previews），文件名含音色 id。单个音色失败不阻断其他。',
+        description: '音色试听：用一段固定试听文本批量生成短样例 MP3，方便挑选音色。voices 为音色 id 数组（可选，缺省 voice_list 前 4 个，最多 8 个）；text 可自定义（≤200 字符）；样例文件写入输出目录（默认会话工作目录 voice_previews），文件名含音色 id。单个音色失败不阻断其他。',
         parameters: compileParameters({
             voices: { type: 'array', items: { type: 'string' }, description: '音色 id 数组（可选，缺省 voice_list 前 4 个，最多 8 个）。' },
             text: { type: 'string', description: '试听文本（可选，默认中英混合试听句，≤200 字符）。' },
-            outputDir: { type: 'string', description: '输出目录（可选，默认工作目录下 voice_previews）。' },
+            outputDir: { type: 'string', description: '输出目录（可选，默认会话工作目录下 voice_previews）。' },
         }),
         output: {
             schema: previewSchema,
@@ -233,7 +296,9 @@ export function buildVoiceTools(config, deps = {}) {
                 return [{ type: 'text', text: lines.join('\n') }];
             },
         },
-        async execute(rawArgs) {
+        async execute(rawArgs, exec) {
+            const signal = execSignal(exec);
+            throwIfAborted(signal);
             const args = asRecord(rawArgs);
             const rawVoices = Array.isArray(args.voices)
                 ? args.voices.filter((v) => typeof v === 'string' && v.trim() !== '').map((v) => v.trim())
@@ -244,24 +309,32 @@ export function buildVoiceTools(config, deps = {}) {
             const text = optionalString(args, 'text') ?? DEFAULT_PREVIEW_TEXT;
             if (text.length > 200)
                 throw new Error('试听文本请控制在 200 字以内（试听要短平快）。');
-            const outDir = resolve(optionalString(args, 'outputDir') ?? 'voice_previews');
+            const outDir = resolve(sessionCwd(exec), optionalString(args, 'outputDir') ?? 'voice_previews');
             mkdirSync(outDir, { recursive: true });
-            const samples = [];
-            const failed = [];
-            for (const voice of targets) {
+            const outcomes = await mapLimit(targets, PREVIEW_CONCURRENCY, signal, async (voice) => {
+                throwIfAborted(signal);
                 if (!isValidVoiceId(voice)) {
-                    failed.push({ voice, error: '音色 id 不合法（应为 zh-CN-XXXNeural 形式的 edge 音色）' });
-                    continue;
+                    return { voice, error: '音色 id 不合法（应为 zh-CN-XXXNeural 形式的 edge 音色）' };
                 }
                 try {
-                    const audio = await (deps.tts ?? synthesizeSpeech)({ text, voice, rate: cfg.ttsRate, pitch: cfg.ttsPitch }, { proxyUrl: cfg.proxyUrl }, timeout);
+                    const audio = await raceAbort((deps.tts ?? synthesizeSpeech)({ text, voice, rate: cfg.ttsRate, pitch: cfg.ttsPitch }, { proxyUrl: cfg.proxyUrl }, timeout, signal), signal);
+                    throwIfAborted(signal);
                     const file = join(outDir, 'voice-preview-' + voice.replace(/[^a-zA-Z0-9-]/g, '_') + '.mp3');
                     writeFileSync(file, audio);
-                    samples.push({ voice, output: file, bytes: audio.length });
+                    return { voice, output: file, bytes: audio.length };
                 }
                 catch (error) {
-                    failed.push({ voice, error: error instanceof Error ? error.message : String(error) });
+                    throwIfAborted(signal);
+                    return { voice, error: error instanceof Error ? error.message : String(error) };
                 }
+            });
+            const samples = [];
+            const failed = [];
+            for (const outcome of outcomes) {
+                if (outcome.error !== undefined)
+                    failed.push({ voice: outcome.voice, error: outcome.error });
+                else
+                    samples.push({ voice: outcome.voice, output: outcome.output, bytes: outcome.bytes });
             }
             return { count: samples.length, samples, failed, text };
         },
@@ -269,7 +342,7 @@ export function buildVoiceTools(config, deps = {}) {
     };
     const voiceHealth = {
         name: 'voice_health',
-        description: 'dsh-voice 自检：检查 TTS 音色合法性、代理配置与 ASR 引擎/密钥就绪状态（不发起网络请求）。遇到问题时先运行本工具定位。',
+        description: 'dsh-voice 自检：检查 TTS 音色合法性、代理配置与 ASR 引擎/接口地址/密钥就绪状态（不发起网络请求）。遇到问题时先运行本工具定位。',
         parameters: compileParameters({}),
         output: {
             schema: { type: 'object', additionalProperties: true },
@@ -293,6 +366,10 @@ export function buildVoiceTools(config, deps = {}) {
                 ok = false;
             checks.push({ name: '特殊代理', ok: true, detail: cfg.proxyUrl !== '' ? '已配置 ' + cfg.proxyUrl : '未配置' });
             checks.push({ name: 'ASR 引擎', ok: true, detail: cfg.asrEngine });
+            const baseUrlOk = cfg.asrBaseUrl !== '';
+            checks.push({ name: 'ASR 接口地址', ok: baseUrlOk, detail: baseUrlOk ? cfg.asrBaseUrl : '未配置：asrEngine=custom 时必须提供 asrBaseUrl。' });
+            if (!baseUrlOk)
+                ok = false;
             const hasKey = cfg.asrApiKey !== '' || typeof process.env.DSH_VOICE_ASR_KEY === 'string' && process.env.DSH_VOICE_ASR_KEY !== '';
             checks.push({ name: 'ASR 密钥', ok: hasKey, detail: hasKey ? '已配置' : '未配置：voice_stt 需要 DSH_VOICE_ASR_KEY 环境变量或配置 asrApiKey' });
             if (!hasKey)

package/package.json

@@ -1,68 +1,68 @@
-{
-  "name": "dsh-voice",
-  "version": "0.3.2",
-  "description": "DSH 语音双件套插件：voice_tts（edge-tts 协议零成本微软神经语音合成）/ voice_stt（OpenAI 兼容 ASR 语音转文字）/ voice_list（音色列表），原生 WebSocket + 插件级代理。",
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./cordis.patch.yml": "./cordis.patch.yml",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib",
-    "cordis.patch.yml",
-    "README.md",
-    "README.en.md"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
+{
+  "name": "dsh-voice",
+  "version": "0.3.4",
+  "description": "DSH 语音插件：edge-tts 微软神经语音合成（免费、无需密钥）+ OpenAI 兼容语音转文字，支持插件级代理。",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.en.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
     "test": "pnpm run build && node --test \"test/*.test.mjs\"",
     "test:integration": "pnpm run build && node --test \"integration/*.test.mjs\"",
-    "prepublishOnly": "pnpm run build"
-  },
-  "dsh": {
-    "bundle": {
-      "patch": "./cordis.patch.yml"
-    }
-  },
-  "keywords": [
-    "dsh",
-    "deepseek-harness",
-    "plugin",
-    "tts",
-    "stt",
-    "whisper",
-    "voice",
-    "dsh-plugin"
-  ],
-  "license": "MIT",
-  "engines": {
-    "node": ">=22.19.0"
-  },
-  "dependencies": {
-    "https-proxy-agent": "^9.1.0",
-    "undici": "^8.10.0",
-    "ws": "^8.21.3"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.0",
-    "@types/ws": "^8.18.1",
-    "typescript": "^5.6.0"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/STARDUSTLC666/dsh-voice.git"
-  },
-  "bugs": {
-    "url": "https://github.com/STARDUSTLC666/dsh-voice/issues"
-  },
-  "homepage": "https://github.com/STARDUSTLC666/dsh-voice#readme",
-  "author": "stardustlc",
-  "packageManager": "pnpm@11.7.0"
-}
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "tts",
+    "stt",
+    "whisper",
+    "voice",
+    "dsh-plugin"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dependencies": {
+    "https-proxy-agent": "^9.1.0",
+    "undici": "^8.10.0",
+    "ws": "^8.21.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@types/ws": "^8.18.1",
+    "typescript": "^5.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/STARDUSTLC666/dsh-voice.git"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-voice/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-voice#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}