dsh-voice 0.1.0

package/README.en.md

@@ -0,0 +1,65 @@
+[中文](README.md)
+
+# dsh-voice
+
+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
+
+## Installation
+
+```bash
+dsh plugin --profile web add dsh-voice
+```
+
+## Configuration
+
+`voice_tts` works with zero config; `voice_stt` needs an ASR key:
+
+```yaml
+- id: voice
+  name: 'dsh-voice'
+  config:
+    asrEngine: groq                       # groq | openai | custom
+    asrModel: whisper-large-v3-turbo      # Groq whisper model
+    # asrApiKey: gsk_...                  # prefer env var DSH_VOICE_ASR_KEY
+    ttsVoice: zh-CN-XiaoxiaoNeural        # default voice
+    # proxyUrl: http://127.0.0.1:7890     # enable when the ASR endpoint needs a special proxy
+```
+
+## Tools
+
+| Tool | Purpose | Key parameters |
+| :-- | :-- | :-- |
+| `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 |
+
+### Examples
+
+```text
+voice_tts { text: hello world }                              # outputs voice_output.mp3
+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 {}
+```
+
+## Under the hood
+
+- **Direct edge-tts protocol**: the Sec-MS-GEC token is **generated locally** with the official DRM algorithm (SHA256 of Windows file time + trusted client token, 5-minute windows); transport uses the `ws` library with permessage-deflate and an optional HTTP CONNECT proxy tunnel
+- **Zero API cost**: TTS is completely free; STT costs only whatever your ASR provider charges
+- Up-front validation: text ≤ 5000 chars, audio ≤ 25MB; same-name outputs auto-suffixed
+- Protocol aligned with current open-source edge-tts (7.x) — no reliance on the outdated token endpoint
+
+## Development
+
+```bash
+pnpm install
+pnpm test       # build + 31 tests, including a real-synthesis integration test
+```
+
+## License
+
+MIT

package/README.md

@@ -0,0 +1,65 @@
+[English](README.en.md)
+
+# dsh-voice
+
+DSH（DeepSeek Harness）语音双件套插件：让 agent **会说话、能听懂**。
+
+- **voice_tts**：文字转语音，走 **edge-tts 协议**（微软 Edge 朗读服务，免费无限量，22+ 常用音色）
+- **voice_stt**：语音转文字，走 **OpenAI 兼容 ASR 接口**（Groq / OpenAI / 自定义端点）
+- **voice_list**：音色清单
+
+## 安装
+
+```bash
+dsh plugin --profile web add dsh-voice
+```
+
+## 配置
+
+`voice_tts` 零配置可用；`voice_stt` 需要 ASR 密钥：
+
+```yaml
+- id: voice
+  name: 'dsh-voice'
+  config:
+    asrEngine: groq                       # groq | openai | custom
+    asrModel: whisper-large-v3-turbo      # groq 的 whisper 模型
+    # asrApiKey: gsk_...                  # 推荐改用环境变量 DSH_VOICE_ASR_KEY
+    ttsVoice: zh-CN-XiaoxiaoNeural        # 默认音色
+    # proxyUrl: http://127.0.0.1:7890     # ASR 接口需要特殊代理时启用
+```
+
+## 工具一览
+
+| 工具 | 作用 | 关键参数 |
+| :-- | :-- | :-- |
+| `voice_tts` | 文字合成 MP3（免费） | `text` 必填；`voice`/`rate`/`pitch`/`output` 可选 |
+| `voice_stt` | 音频转文字 | `audio` 必填；`engine`/`model`/`language`/`prompt`/`output` 可选 |
+| `voice_list` | 常用音色清单 | 无 |
+
+### 示例
+
+```text
+voice_tts { text: 今天的 AI 早报来了 }                    # 晓晓女声，输出 voice_output.mp3
+voice_tts { text: hello, voice: en-US-AriaNeural }        # 英文女声
+voice_stt { audio: E:\audio\meeting.mp3, language: zh } # 转写会议录音
+voice_list {}
+```
+
+## 硬核细节
+
+- **edge-tts 协议直连**：Sec-MS-GEC 令牌按官方 DRM 算法**本地生成**（SHA256(Windows 文件时间 + TrustedClientToken)，5 分钟窗口），WS 传输用 `ws` 库 + permessage-deflate 压缩 + 可选 HTTP CONNECT 代理隧道
+- **零 API 成本**：TTS 完全免费；STT 只花你选的 ASR 接口的钱
+- 文本 ≤5000 字符、音频 ≤25MB 前置校验；输出同名自动加序号
+- 协议对齐开源 edge-tts 当前版本（7.x），不依赖过时的令牌端点
+
+## 开发
+
+```bash
+pnpm install
+pnpm test       # 构建 + 31 个测试（含真实合成集成测试）
+```
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,22 @@
+# dsh-voice 组合包补丁：把语音双件套工具插件行插入 profile。
+# 本补丁按 id 覆盖；用户应在自己 profile 的 cordis.patch.yml 里覆盖本行的整个
+# config（见 README 的配置示例）。配置缺失时插件仍会加载：voice_tts 零配置可用，
+# voice_stt 需要 ASR 接口（Groq / OpenAI 兼容）。
+#
+# 示例（用户 profile 的 cordis.patch.yml）：
+#   - id: voice
+#     name: 'dsh-voice'
+#     config:
+#       asrEngine: groq                 # groq | openai | custom（voice_stt 用）
+#       # asrApiKey: gsk_...            # 推荐改用环境变量 DSH_VOICE_ASR_KEY
+#       # asrBaseUrl: https://api.groq.com/openai/v1
+#       asrModel: whisper-large-v3-turbo
+#       # proxyUrl: http://127.0.0.1:7890   # 需要特殊代理访问 ASR/Bing 时启用
+#       ttsVoice: zh-CN-XiaoxiaoNeural
+#
+- insert:
+    - id: voice
+      name: 'dsh-voice'
+      config:
+        asrEngine: groq
+        asrModel: whisper-large-v3-turbo

package/lib/config.d.ts

@@ -0,0 +1,37 @@
+/**
+ * dsh-voice 配置解析：TTS 默认音色与语速、ASR 引擎与密钥、代理。
+ *
+ * @module dsh-voice/config
+ */
+/** 插件行配置（cordis.patch.yml 里的 config 段，可缺省）。 */
+export interface VoiceConfig {
+    ttsVoice?: string;
+    ttsRate?: string;
+    ttsPitch?: string;
+    asrEngine?: 'groq' | 'openai' | 'custom';
+    asrBaseUrl?: string;
+    asrApiKey?: string;
+    asrModel?: string;
+    proxyUrl?: string;
+    timeoutMs?: number;
+    overwrite?: boolean;
+}
+/** 解析后的配置。 */
+export interface ResolvedVoiceConfig {
+    ttsVoice: string;
+    ttsRate: string;
+    ttsPitch: string;
+    asrEngine: 'groq' | 'openai' | 'custom';
+    asrBaseUrl: string;
+    asrApiKey: string;
+    asrModel: string;
+    proxyUrl: string;
+    timeoutMs: number;
+    overwrite: boolean;
+}
+/** ASR 密钥：配置优先，其次环境变量 DSH_VOICE_ASR_KEY。 */
+export declare function resolveAsrApiKey(config: VoiceConfig | undefined, env?: NodeJS.ProcessEnv): string;
+/**
+ * 解析并校验配置。
+ */
+export declare function resolveConfig(config: VoiceConfig | undefined | null): ResolvedVoiceConfig;

package/lib/config.js

@@ -0,0 +1,41 @@
+/**
+ * dsh-voice 配置解析：TTS 默认音色与语速、ASR 引擎与密钥、代理。
+ *
+ * @module dsh-voice/config
+ */
+const ENGINE_PRESETS = {
+    groq: { baseUrl: 'https://api.groq.com/openai/v1', model: 'whisper-large-v3-turbo' },
+    openai: { baseUrl: 'https://api.openai.com/v1', model: 'whisper-1' },
+};
+/** ASR 密钥：配置优先，其次环境变量 DSH_VOICE_ASR_KEY。 */
+export function resolveAsrApiKey(config, env = process.env) {
+    const cfg = config ?? {};
+    if (typeof cfg.asrApiKey === 'string' && cfg.asrApiKey.trim() !== '')
+        return cfg.asrApiKey.trim();
+    return env.DSH_VOICE_ASR_KEY?.trim() ?? '';
+}
+/**
+ * 解析并校验配置。
+ */
+export function resolveConfig(config) {
+    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%';
+    const ttsPitch = typeof cfg.ttsPitch === 'string' && cfg.ttsPitch.trim() !== '' ? cfg.ttsPitch.trim() : '+0Hz';
+    const asrEngine = cfg.asrEngine === 'openai' ? 'openai' : cfg.asrEngine === 'custom' ? 'custom' : 'groq';
+    const preset = asrEngine === 'custom' ? undefined : ENGINE_PRESETS[asrEngine];
+    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 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)));
+    }
+    const overwrite = cfg.overwrite === true;
+    return { ttsVoice, ttsRate, ttsPitch, asrEngine, asrBaseUrl, asrApiKey, asrModel, proxyUrl, timeoutMs, overwrite };
+}

package/lib/edge-tts.d.ts

@@ -0,0 +1,36 @@
+/** 合成选项。 */
+export interface TtsOptions {
+    text: string;
+    voice: string;
+    rate: string;
+    pitch: string;
+}
+/** 可注入依赖（测试用假实现）。 */
+export interface TtsDeps {
+    webSocketFactory?: WebSocketFactory;
+    nowSeconds?: () => number;
+    proxyUrl?: string;
+}
+/** 最小的 WebSocket 面。 */
+export interface WebSocketLike {
+    addEventListener(type: 'message', listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: 'open' | 'close' | 'error', listener: (event?: unknown) => void): void;
+    send(data: string): void;
+    close(): void;
+}
+export type WebSocketFactory = (url: string, options: {
+    headers: Record<string, string>;
+}) => WebSocketLike;
+/**
+ * 本地生成 Sec-MS-GEC 令牌（对齐 edge-tts DRM 算法）。
+ */
+export declare function generateSecMsGec(nowSeconds?: number): string;
+/** 生成 SSML。 */
+export declare function buildSsml(options: TtsOptions): string;
+/**
+ * 合成语音，返回 MP3 字节。
+ * @throws 文本为空/超长 / 连接失败 / 超时 / 无音频数据时抛中文错误。
+ */
+export declare function synthesizeSpeech(options: TtsOptions, deps?: TtsDeps, timeoutMs?: number): Promise<Buffer>;

package/lib/edge-tts.js

@@ -0,0 +1,152 @@
+/**
+ * edge-tts 协议客户端：原生 WebSocket 直连微软 Edge 朗读服务，零 API 成本。
+ * 协议对齐开源 edge-tts 当前版本：Sec-MS-GEC 令牌由本地 DRM 算法生成
+ * （SHA256(Windows 文件时间 + TrustedClientToken)，5 分钟窗口），不再请求令牌端点。
+ *
+ * @module dsh-voice/edge-tts
+ */
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
+import { HttpsProxyAgent } from 'https-proxy-agent';
+import WebSocket from 'ws';
+const TRUSTED_CLIENT_TOKEN = '6A5AA1D4EAFF4E9FB37E23D68491D6F4';
+const WS_BASE = 'wss://speech.platform.bing.com/consumer/speech/synthesize/readaloud/edge/v1';
+const OUTPUT_FORMAT = 'audio-24khz-48kbitrate-mono-mp3';
+const SEC_MS_GEC_VERSION = '1-143.0.3650.75';
+const WIN_EPOCH_SECONDS = 11644473600;
+const WSS_HEADERS = {
+    Pragma: 'no-cache',
+    'Cache-Control': 'no-cache',
+    Origin: 'chrome-extension://jdiccldimpdaibmpdkjnbmckianbfold',
+    'Accept-Encoding': 'gzip, deflate, br, zstd',
+    'Accept-Language': 'en-US,en;q=0.9',
+    'Sec-WebSocket-Version': '13',
+    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36 Edg/143.0.0.0',
+};
+/** 直连工厂（ws 库，Node 全版本可用）。 */
+function directWebSocket(url, options) {
+    return new WebSocket(url, { headers: options.headers });
+}
+/** 代理工厂：经 HTTP CONNECT 隧道走本地代理（大陆直连会被重置时使用）。 */
+function proxyWebSocket(proxyUrl) {
+    const agent = new HttpsProxyAgent(proxyUrl);
+    return (url, options) => new WebSocket(url, { headers: options.headers, agent });
+}
+/**
+ * 本地生成 Sec-MS-GEC 令牌（对齐 edge-tts DRM 算法）。
+ */
+export function generateSecMsGec(nowSeconds = Date.now() / 1000) {
+    let ticks = Math.floor(nowSeconds) + WIN_EPOCH_SECONDS;
+    ticks -= ticks % 300;
+    const windowsTicks = ticks * 10000000;
+    const raw = String(windowsTicks) + TRUSTED_CLIENT_TOKEN;
+    return createHash('sha256').update(raw, 'ascii').digest('hex').toUpperCase();
+}
+/** XML 转义。 */
+function escapeXml(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/** 生成 SSML。 */
+export function buildSsml(options) {
+    const lang = /^[a-z]{2,3}(-[A-Z]{2})?/.exec(options.voice)?.[0] ?? 'zh-CN';
+    return "<speak version='1.0' xmlns='http://www.w3.org/2001/10/synthesis' xml:lang='" + lang + "'><voice name='" + options.voice + "'><prosody pitch='" + options.pitch + "' rate='" + options.rate + "' volume='+0%'>" + escapeXml(options.text) + '</prosody></voice></speak>';
+}
+/** 生成带时间戳与路径的协议消息头。 */
+function protocolHeader(path, extra) {
+    const lines = ['X-Timestamp:' + new Date().toISOString()];
+    for (const [key, value] of Object.entries(extra))
+        lines.push(key + ':' + value);
+    lines.push('Path:' + path);
+    return lines.join('\r\n') + '\r\n\r\n';
+}
+/**
+ * 合成语音，返回 MP3 字节。
+ * @throws 文本为空/超长 / 连接失败 / 超时 / 无音频数据时抛中文错误。
+ */
+export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
+    if (options.text.trim() === '')
+        throw new Error('要合成的文本为空。');
+    if (options.text.length > 5000)
+        throw new Error('文本过长（超过 5000 字符），请分段合成。');
+    const factory = deps.webSocketFactory ?? (deps.proxyUrl !== undefined && deps.proxyUrl !== '' ? proxyWebSocket(deps.proxyUrl) : directWebSocket);
+    const token = generateSecMsGec(deps.nowSeconds?.() ?? Date.now() / 1000);
+    // 对齐 edge-tts 当前协议：Sec-MS-GEC 走 URL 查询参数，MUID 走 header
+    const url = WS_BASE + '?TrustedClientToken=' + TRUSTED_CLIENT_TOKEN + '&ConnectionId=' + randomUUID().replace(/-/g, '') + '&Sec-MS-GEC=' + token + '&Sec-MS-GEC-Version=' + SEC_MS_GEC_VERSION;
+    const socket = factory(url, {
+        headers: { ...WSS_HEADERS, MUID: randomBytes(16).toString('hex').toUpperCase() },
+    });
+    const chunks = [];
+    let done = false;
+    await new Promise((resolvePromise, reject) => {
+        const timer = setTimeout(() => {
+            try {
+                socket.close();
+            }
+            catch { /* 忽略 */ }
+            reject(new Error('语音合成超时（' + timeoutMs + ' 毫秒无完整音频），请重试或检查网络。'));
+        }, timeoutMs);
+        const finish = () => { clearTimeout(timer); resolvePromise(); };
+        socket.addEventListener('open', () => {
+            const config = protocolHeader('speech.config', { 'Content-Type': 'application/json; charset=utf-8' })
+                + JSON.stringify({
+                    context: {
+                        synthesis: {
+                            audio: { metadataoptions: { sentenceBoundaryEnabled: 'false', wordBoundaryEnabled: 'false' }, outputFormat: OUTPUT_FORMAT },
+                        },
+                    },
+                });
+            const ssml = protocolHeader('ssml', { 'Content-Type': 'application/ssml+xml', 'X-RequestId': randomUUID() }) + buildSsml(options);
+            try {
+                socket.send(config);
+                socket.send(ssml);
+            }
+            catch (error) {
+                clearTimeout(timer);
+                reject(error instanceof Error ? error : new Error(String(error)));
+            }
+        });
+        socket.addEventListener('message', (event) => {
+            const data = event.data;
+            if (typeof data === 'string') {
+                if (data.includes('Path:turn.end')) {
+                    if (chunks.length === 0) {
+                        clearTimeout(timer);
+                        reject(new Error('合成结束但没有收到音频数据（服务端可能拒绝了请求）。'));
+                    }
+                    else if (!done) {
+                        done = true;
+                        finish();
+                    }
+                }
+                return;
+            }
+            // 二进制帧：2 字节大端头长 + 头文本 + 音频数据
+            const buffer = Buffer.isBuffer(data) ? data : Buffer.from(data);
+            if (buffer.length > 2) {
+                const headerLength = buffer.readUInt16BE(0);
+                if (buffer.length > 2 + headerLength) {
+                    chunks.push(buffer.subarray(2 + headerLength));
+                }
+            }
+        });
+        socket.addEventListener('error', () => {
+            clearTimeout(timer);
+            reject(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 连接在收到音频前关闭。'));
+                }
+            }
+        });
+    });
+    const audio = Buffer.concat(chunks);
+    if (audio.length === 0)
+        throw new Error('合成结果为空。');
+    return audio;
+}

package/lib/index.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 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/自定义端点）。
+ *
+ * @module dsh-voice
+ */
+import { type VoiceConfig } from './config.js';
+import { type VoiceToolDefinition } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export declare const inject: string[];
+/** 插件所需的最小 ctx 面。 */
+export interface VoicePluginContext {
+    tools: {
+        register(definition: VoiceToolDefinition): () => void;
+    };
+    on?(event: string, listener: () => void): () => void;
+}
+/**
+ * 插件入口：解析配置并注册三个语音工具。
+ */
+export declare function apply(ctx: VoicePluginContext, config?: VoiceConfig | null): void;
+export * from './config.js';
+export * from './edge-tts.js';
+export * from './paths.js';
+export * from './proxy-fetch.js';
+export * from './stt.js';
+export * from './tools.js';
+export * from './voices.js';

package/lib/index.js

@@ -0,0 +1,43 @@
+/**
+ * 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/自定义端点）。
+ *
+ * @module dsh-voice
+ */
+import { resolveConfig } from './config.js';
+import { buildVoiceTools } from './tools.js';
+/** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export const inject = ['tools'];
+/**
+ * 插件入口：解析配置并注册三个语音工具。
+ */
+export function apply(ctx, config) {
+    let cfg;
+    try {
+        cfg = resolveConfig(config);
+    }
+    catch (error) {
+        console.warn('[dsh-voice] ' + (error instanceof Error ? error.message : String(error)));
+        cfg = resolveConfig(null);
+    }
+    const disposers = [];
+    for (const definition of buildVoiceTools(cfg)) {
+        disposers.push(ctx.tools.register(definition));
+    }
+    if (typeof ctx.on === 'function') {
+        ctx.on('dispose', () => {
+            for (const dispose of disposers)
+                dispose();
+        });
+    }
+}
+export * from './config.js';
+export * from './edge-tts.js';
+export * from './paths.js';
+export * from './proxy-fetch.js';
+export * from './stt.js';
+export * from './tools.js';
+export * from './voices.js';

package/lib/paths.d.ts

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

package/lib/paths.js

@@ -0,0 +1,30 @@
+/**
+ * 输出路径与音频文件校验。
+ *
+ * @module dsh-voice/paths
+ */
+import { existsSync, statSync } from 'node:fs';
+import { basename, dirname, extname, join, resolve } from 'node:path';
+/** 校验音频文件存在且是文件；返回绝对路径。 */
+export function assertAudioFile(input) {
+    const absolute = resolve(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);
+    if (overwrite || !existsSync(target))
+        return target;
+    const directory = dirname(target);
+    const base = basename(target, extname(target));
+    const extension = extname(target);
+    for (let index = 1; index < 1000; index++) {
+        const candidate = join(directory, base + '_' + index + extension);
+        if (!existsSync(candidate))
+            return candidate;
+    }
+    throw new Error('找不到可用的输出文件名（同名文件超过 999 个），请显式指定 output。');
+}

package/lib/proxy-fetch.d.ts

@@ -0,0 +1,4 @@
+/**
+ * 构造一个把所有请求路由到 proxyUrl 的 fetch。
+ */
+export declare function createProxyFetch(proxyUrl: string): typeof globalThis.fetch;

package/lib/proxy-fetch.js

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

package/lib/stt.d.ts

@@ -0,0 +1,16 @@
+/** 转写选项。 */
+export interface SttOptions {
+    audio: Buffer;
+    filename: string;
+    model: string;
+    language?: string;
+    prompt?: string;
+}
+/**
+ * 调用 OpenAI 兼容 ASR 接口转写音频。
+ * @throws 缺密钥 / 文件过大 / HTTP 错误 / 无文本时抛中文错误。
+ */
+export declare function transcribe(baseUrl: string, apiKey: string, options: SttOptions, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<{
+    text: string;
+    model: string;
+}>;

package/lib/stt.js

@@ -0,0 +1,63 @@
+/**
+ * ASR 客户端：OpenAI 兼容 /audio/transcriptions multipart 上传。
+ *
+ * @module dsh-voice/stt
+ */
+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) {
+    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();
+    const mime = mimeOf(options.filename);
+    form.append('file', new Blob([options.audio], { type: mime }), options.filename);
+    form.append('model', options.model);
+    if (options.language !== undefined && options.language !== '')
+        form.append('language', options.language);
+    if (options.prompt !== undefined && options.prompt !== '')
+        form.append('prompt', options.prompt);
+    let response;
+    try {
+        response = await fetchImpl(baseUrl + '/audio/transcriptions', {
+            method: 'POST',
+            headers: { authorization: 'Bearer ' + apiKey },
+            body: form,
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (error) {
+        throw new Error('ASR 请求失败：' + (error instanceof Error ? error.message : String(error)) + '。若接口需要特殊代理（梯子），请在 cordis.patch.yml 配置 proxyUrl 后重启。');
+    }
+    if (!response.ok) {
+        const body = (await response.text()).slice(0, 300);
+        throw new Error('ASR 失败：HTTP ' + response.status + '。' + body);
+    }
+    let json;
+    try {
+        json = await response.json();
+    }
+    catch {
+        throw new Error('ASR 响应不是合法 JSON。');
+    }
+    const text = typeof json === 'object' && json !== null && typeof json.text === 'string' ? json.text : '';
+    return { text, model: options.model };
+}
+/** 常见音频扩展名 → MIME。 */
+function mimeOf(filename) {
+    const ext = extname(filename).toLowerCase();
+    const table = {
+        '.mp3': 'audio/mpeg', '.wav': 'audio/wav', '.m4a': 'audio/mp4', '.mp4': 'audio/mp4',
+        '.ogg': 'audio/ogg', '.opus': 'audio/ogg', '.flac': 'audio/flac', '.webm': 'audio/webm',
+    };
+    return table[ext] ?? 'application/octet-stream';
+}

package/lib/tools.d.ts

@@ -0,0 +1,33 @@
+import { type ResolvedVoiceConfig } from './config.js';
+import { synthesizeSpeech } from './edge-tts.js';
+import { transcribe } from './stt.js';
+/** 模型可见的内容块。 */
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+/** 注册给 ctx.tools.register 的原始工具定义。 */
+export interface VoiceToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    timeoutMs?: number;
+}
+/** 可注入依赖（测试用假实现）。 */
+export interface VoiceToolDeps {
+    tts?: typeof synthesizeSpeech;
+    stt?: typeof transcribe;
+}
+/**
+ * 构建三个工具定义。
+ */
+export declare function buildVoiceTools(config: ResolvedVoiceConfig, deps?: VoiceToolDeps): VoiceToolDefinition[];

package/lib/tools.js

@@ -0,0 +1,193 @@
+/**
+ * 三个面向模型的语音工具：voice_tts / voice_stt / voice_list。
+ *
+ * @module dsh-voice/tools
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import { basename } 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 { isValidVoiceId, VOICES } from './voices.js';
+function compileParameters(spec) {
+    const properties = {};
+    const required = [];
+    for (const [key, prop] of Object.entries(spec)) {
+        if (prop?.required === true)
+            required.push(key);
+        const node = {};
+        if (typeof prop?.type === 'string')
+            node.type = prop.type;
+        if (typeof prop?.description === 'string')
+            node.description = prop.description;
+        properties[key] = node;
+    }
+    return { type: 'object', properties, ...(required.length > 0 ? { required } : {}) };
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : {};
+}
+function optionalString(args, key) {
+    const value = args[key];
+    return typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
+}
+function requiredString(args, key, label) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        throw new Error(label + '（参数 ' + key + '）为必填，请提供非空字符串。');
+    return value;
+}
+const voiceItemSchema = {
+    type: 'object',
+    properties: { id: { type: 'string' }, gender: { type: 'string' }, locale: { type: 'string' } },
+    additionalProperties: true,
+};
+const listSchema = {
+    type: 'object',
+    properties: { count: { type: 'integer' }, voices: { type: 'array', items: voiceItemSchema } },
+    additionalProperties: true,
+};
+const ttsSchema = {
+    type: 'object',
+    properties: {
+        output: { type: 'string' },
+        bytes: { type: 'integer' },
+        voice: { type: 'string' },
+        rate: { type: 'string' },
+        pitch: { type: 'string' },
+        textLength: { type: 'integer' },
+    },
+    additionalProperties: true,
+};
+const sttSchema = {
+    type: 'object',
+    properties: {
+        text: { type: 'string' },
+        model: { type: 'string' },
+        language: { type: 'string' },
+        audio: { type: 'string' },
+        transcriptFile: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+/**
+ * 构建三个工具定义。
+ */
+export function buildVoiceTools(config, deps = {}) {
+    const cfg = config;
+    const fetchImpl = cfg.proxyUrl !== '' ? createProxyFetch(cfg.proxyUrl) : undefined;
+    const timeout = cfg.timeoutMs;
+    const voiceList = {
+        name: 'voice_list',
+        description: '列出常用语音合成音色（edge-tts 微软神经语音，免费）。含普通话/方言/粤语/英/日/韩/法/德/俄/西。voice_tts 的 voice 参数也接受清单外的合法 edge 音色 id（如 zh-CN-XXXNeural）。',
+        parameters: compileParameters({}),
+        output: {
+            schema: listSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const voices = Array.isArray(rec.voices) ? rec.voices : [];
+                const lines = ['共 ' + voices.length + ' 个常用音色：'];
+                for (const voice of voices) {
+                    const v = asRecord(voice);
+                    lines.push('- ' + v.id + '（' + v.locale + '）');
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute() {
+            return { count: VOICES.length, voices: VOICES };
+        },
+    };
+    const voiceTts = {
+        name: 'voice_tts',
+        description: '文字转语音：调用 edge-tts（微软 Edge 朗读服务，免费）合成 MP3。text 必填（≤5000 字符，更长请分段）；voice 可选（默认 zh-CN-XiaoxiaoNeural，清单见 voice_list）；rate/pitch 如 +10%、-2Hz；输出默认 voice_output.mp3（同名自动加序号）。',
+        parameters: compileParameters({
+            text: { type: 'string', required: true, description: '要合成的文本（必填，≤5000 字符）。' },
+            voice: { type: 'string', description: '音色 id（可选，默认配置的 ttsVoice）。' },
+            rate: { type: 'string', description: '语速，如 +20% 或 -10%（可选）。' },
+            pitch: { type: 'string', description: '音调，如 +2Hz 或 -1Hz（可选）。' },
+            output: { type: 'string', description: '输出 MP3 路径（可选）。' },
+        }),
+        output: {
+            schema: ttsSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                return [{ type: 'text', text: '语音合成完成：' + rec.output + '（' + rec.bytes + ' 字节，音色 ' + rec.voice + '）' }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const text = requiredString(args, 'text', '要合成的文本');
+            if (text.length > 5000)
+                throw new Error('文本超过 5000 字符，请分段合成。');
+            const voice = optionalString(args, 'voice') ?? cfg.ttsVoice;
+            if (!isValidVoiceId(voice))
+                throw new Error('音色 id 不合法：' + voice + '。请用 voice_list 查看常用音色，或使用 zh-CN-XXXNeural 形式的 edge 音色。');
+            const rate = optionalString(args, 'rate') ?? cfg.ttsRate;
+            const pitch = optionalString(args, 'pitch') ?? cfg.ttsPitch;
+            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);
+            return { output, bytes: audio.length, voice, rate, pitch, textLength: text.length };
+        },
+        timeoutMs: timeout + 10000,
+    };
+    const voiceStt = {
+        name: 'voice_stt',
+        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（可选，默认配置值）。' },
+            model: { type: 'string', description: '模型名（可选，覆盖配置）。' },
+            language: { type: 'string', description: '语言提示，如 zh（可选）。' },
+            prompt: { type: 'string', description: '提示词（专有名词/术语纠偏，可选）。' },
+            output: { type: 'string', description: '把转写文本写成 .txt 的路径（可选）。' },
+        }),
+        output: {
+            schema: sttSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                return [{ type: 'text', text: '转写完成（模型 ' + rec.model + '）：' + rec.text }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const audioPath = assertAudioFile(requiredString(args, 'audio', '音频文件'));
+            const engine = optionalString(args, 'engine') ?? cfg.asrEngine;
+            let baseUrl;
+            let model;
+            if (engine === 'openai') {
+                baseUrl = 'https://api.openai.com/v1';
+                model = optionalString(args, 'model') ?? 'whisper-1';
+            }
+            else if (engine === 'custom') {
+                baseUrl = cfg.asrBaseUrl;
+                model = optionalString(args, 'model') ?? cfg.asrModel;
+            }
+            else if (engine === 'groq') {
+                baseUrl = 'https://api.groq.com/openai/v1';
+                model = optionalString(args, 'model') ?? (cfg.asrModel !== '' && cfg.asrEngine === 'groq' ? cfg.asrModel : 'whisper-large-v3-turbo');
+            }
+            else
+                throw new Error('engine 必须是 groq / openai / custom 之一（当前：' + engine + '）。');
+            const { text } = await (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);
+            let transcriptFile = null;
+            const output = optionalString(args, 'output');
+            if (output !== undefined) {
+                const target = resolveOutputPath(output, '', cfg.overwrite);
+                writeFileSync(target, text, 'utf8');
+                transcriptFile = target;
+            }
+            return { text, model, language: optionalString(args, 'language') ?? null, audio: audioPath, transcriptFile };
+        },
+        timeoutMs: timeout + 10000,
+    };
+    return [voiceList, voiceTts, voiceStt];
+}

package/lib/voices.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 常用音色清单（edge-tts 全量约 500 个，这里收录常用中/英/日/韩/法/德/俄/西音色）。
+ *
+ * @module dsh-voice/voices
+ */
+/** 音色信息。 */
+export interface VoiceInfo {
+    id: string;
+    gender: 'Female' | 'Male';
+    locale: string;
+}
+/** 常用音色。 */
+export declare const VOICES: VoiceInfo[];
+/** 校验音色 id：常用清单内或符合 edge-tts 命名规则。 */
+export declare function isValidVoiceId(id: string): boolean;

package/lib/voices.js

@@ -0,0 +1,36 @@
+/**
+ * 常用音色清单（edge-tts 全量约 500 个，这里收录常用中/英/日/韩/法/德/俄/西音色）。
+ *
+ * @module dsh-voice/voices
+ */
+/** 常用音色。 */
+export const VOICES = [
+    { id: 'zh-CN-XiaoxiaoNeural', gender: 'Female', locale: '普通话（晓晓，温柔女声）' },
+    { id: 'zh-CN-XiaoyiNeural', gender: 'Female', locale: '普通话（晓伊，活泼女声）' },
+    { id: 'zh-CN-YunxiNeural', gender: 'Male', locale: '普通话（云希，青年男声）' },
+    { id: 'zh-CN-YunyangNeural', gender: 'Male', locale: '普通话（云扬，新闻男声）' },
+    { id: 'zh-CN-YunjianNeural', gender: 'Male', locale: '普通话（云健，浑厚男声）' },
+    { id: 'zh-CN-liaoning-XiaobeiNeural', gender: 'Female', locale: '东北话（晓北）' },
+    { id: 'zh-CN-shaanxi-XiaoniNeural', gender: 'Female', locale: '陕西话（晓妮）' },
+    { id: 'zh-TW-HsiaoChenNeural', gender: 'Female', locale: '台湾腔（晓臻）' },
+    { id: 'zh-HK-HiuMaanNeural', gender: 'Female', locale: '粤语（曉曼）' },
+    { id: 'en-US-AriaNeural', gender: 'Female', locale: '美式英语（Aria，女声）' },
+    { id: 'en-US-JennyNeural', gender: 'Female', locale: '美式英语（Jenny，女声）' },
+    { id: 'en-US-GuyNeural', gender: 'Male', locale: '美式英语（Guy，男声）' },
+    { id: 'en-US-DavisNeural', gender: 'Male', locale: '美式英语（Davis，男声）' },
+    { id: 'en-GB-SoniaNeural', gender: 'Female', locale: '英式英语（Sonia）' },
+    { id: 'en-GB-RyanNeural', gender: 'Male', locale: '英式英语（Ryan）' },
+    { id: 'ja-JP-NanamiNeural', gender: 'Female', locale: '日语（Nanami，女声）' },
+    { id: 'ja-JP-KeitaNeural', gender: 'Male', locale: '日语（Keita，男声）' },
+    { id: 'ko-KR-SunHiNeural', gender: 'Female', locale: '韩语（SunHi）' },
+    { id: 'fr-FR-DeniseNeural', gender: 'Female', locale: '法语（Denise）' },
+    { id: 'de-DE-KatjaNeural', gender: 'Female', locale: '德语（Katja）' },
+    { id: 'ru-RU-SvetlanaNeural', gender: 'Female', locale: '俄语（Svetlana）' },
+    { id: 'es-ES-ElviraNeural', gender: 'Female', locale: '西班牙语（Elvira）' },
+];
+/** 校验音色 id：常用清单内或符合 edge-tts 命名规则。 */
+export function isValidVoiceId(id) {
+    if (VOICES.some((voice) => voice.id === id))
+        return true;
+    return /^[a-z]{2,3}(-[A-Z]{2})?-[A-Z][A-Za-z]+Neural$/.test(id);
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "dsh-voice",
+  "version": "0.1.0",
+  "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",
+    "prepare": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "pnpm run build && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "pnpm run build"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "plugin",
+    "tts",
+    "stt",
+    "whisper",
+    "voice"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "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": "https://github.com/STARDUSTLC666/dsh-voice"
+  },
+  "bugs": {
+    "url": "https://github.com/STARDUSTLC666/dsh-voice/issues"
+  },
+  "homepage": "https://github.com/STARDUSTLC666/dsh-voice#readme",
+  "author": "stardustlc",
+  "packageManager": "pnpm@11.7.0"
+}