dsh-voice 0.1.1 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 stardustlc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.en.md

@@ -1,5 +1,7 @@
 [中文](README.md)
 
+![npm](https://img.shields.io/npm/v/dsh-voice) ![downloads](https://img.shields.io/npm/dm/dsh-voice) ![license](https://img.shields.io/github/license/STARDUSTLC666/dsh-voice) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-voice?style=social)
+
 # dsh-voice
 
 [![Awesome DSH Plugin](https://awesome-dsh-plugin.com/badge.svg)](https://awesome-dsh-plugin.com)
@@ -10,12 +12,25 @@ DSH (DeepSeek Harness) voice plugin pair: let the agent **speak and listen**.
 - **voice_stt**: speech-to-text over any **OpenAI-compatible ASR endpoint** (Groq / OpenAI / custom)
 - **voice_list**: voice catalog
 
+## 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.
+
 ## Installation
 
 ```bash
 dsh plugin --profile web add dsh-voice
 ```
 
+## Uninstall
+
+```bash
+dsh plugin --profile web remove dsh-voice
+```
+
+Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
+
+
 ## Configuration
 
 `voice_tts` works with zero config; `voice_stt` needs an ASR key:

package/README.md

@@ -15,12 +15,25 @@ DSH（DeepSeek Harness）语音双件套插件：让 agent **会说话、能听
 - **voice_stt**：语音转文字，走 **OpenAI 兼容 ASR 接口**（Groq / OpenAI / 自定义端点）
 - **voice_list**：音色清单
 
+## 兼容性
+
+在 `@deepseek-ai/dsh@0.1.2-alpha.2` 上验证（2026-08-31）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+
 ## 安装
 
 ```bash
 dsh plugin --profile web add dsh-voice
 ```
 
+## 卸载
+
+```bash
+dsh plugin --profile web remove dsh-voice
+```
+
+卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
+
+
 ## 配置
 
 `voice_tts` 零配置可用；`voice_stt` 需要 ASR 密钥：
@@ -69,5 +82,4 @@ pnpm test       # 构建 + 31 个测试（含真实合成集成测试）
 
 ## License
 
-MIT
-
+MIT

package/lib/edge-tts.js

@@ -84,7 +84,10 @@ export async function synthesizeSpeech(options, deps = {}, timeoutMs = 30000) {
             catch { /* 忽略 */ }
             reject(new Error('语音合成超时（' + timeoutMs + ' 毫秒无完整音频），请重试或检查网络。'));
         }, timeoutMs);
-        const finish = () => { clearTimeout(timer); resolvePromise(); };
+        const finish = () => { clearTimeout(timer); try {
+            socket.close();
+        }
+        catch { /* 忽略 */ } resolvePromise(); };
         socket.addEventListener('open', () => {
             const config = protocolHeader('speech.config', { 'Content-Type': 'application/json; charset=utf-8' })
                 + JSON.stringify({

package/lib/index.d.ts

@@ -10,6 +10,7 @@
 import { type VoiceConfig } from './config.js';
 import { type VoiceToolDefinition } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export declare const name = "voice";
 export declare const inject: string[];
 /** 插件所需的最小 ctx 面。 */
 export interface VoicePluginContext {

package/lib/index.js

@@ -10,6 +10,7 @@
 import { resolveConfig } from './config.js';
 import { buildVoiceTools } from './tools.js';
 /** cordis 服务注入：apply 里要用 ctx.tools，必须显式声明。 */
+export const name = 'voice';
 export const inject = ['tools'];
 /**
  * 插件入口：解析配置并注册三个语音工具。

package/lib/tools.d.ts

@@ -22,6 +22,8 @@ export interface VoiceToolDefinition {
     execute(args: unknown, exec: unknown): Promise<unknown>;
     timeoutMs?: number;
 }
+/** 默认试听文本（中英混合，便于感知发音差异）。 */
+export declare const DEFAULT_PREVIEW_TEXT = "\u4F60\u597D\uFF0C\u8FD9\u662F\u97F3\u8272\u8BD5\u542C\u3002Hello, this is a voice preview.";
 /** 可注入依赖（测试用假实现）。 */
 export interface VoiceToolDeps {
     tts?: typeof synthesizeSpeech;

package/lib/tools.js

@@ -1,10 +1,10 @@
 /**
- * 三个面向模型的语音工具：voice_tts / voice_stt / voice_list。
+ * 五个面向模型的语音工具：voice_tts / voice_stt / voice_list / voice_preview。
  *
  * @module dsh-voice/tools
  */
-import { readFileSync, writeFileSync } from 'node:fs';
-import { basename } from 'node:path';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join, resolve } from 'node:path';
 import { synthesizeSpeech } from './edge-tts.js';
 import { assertAudioFile, resolveOutputPath } from './paths.js';
 import { createProxyFetch } from './proxy-fetch.js';
@@ -71,6 +71,18 @@ const sttSchema = {
     },
     additionalProperties: true,
 };
+const previewSchema = {
+    type: 'object',
+    properties: {
+        count: { type: 'integer' },
+        samples: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        failed: { type: 'array', items: { type: 'object', additionalProperties: true } },
+        text: { type: 'string' },
+    },
+    additionalProperties: true,
+};
+/** 默认试听文本（中英混合，便于感知发音差异）。 */
+export const DEFAULT_PREVIEW_TEXT = '你好，这是音色试听。Hello, this is a voice preview.';
 /**
  * 构建三个工具定义。
  */
@@ -126,6 +138,10 @@ export function buildVoiceTools(config, deps = {}) {
                 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;
+            for (const [value, label] of [[rate, '语速 rate'], [pitch, '音调 pitch']]) {
+                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);
@@ -178,16 +194,112 @@ export function buildVoiceTools(config, deps = {}) {
                 language: optionalString(args, 'language'),
                 prompt: optionalString(args, 'prompt'),
             }, fetchImpl ?? globalThis.fetch, timeout);
-            let transcriptFile = null;
+            let transcriptFile = '';
             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 };
+            // The output schema declares these as strings — never return null, or
+            // dsh rejects the whole tool result (issue #1).
+            return { text, model, language: optionalString(args, 'language') ?? '', audio: audioPath, transcriptFile };
         },
         timeoutMs: timeout + 10000,
     };
-    return [voiceList, voiceTts, voiceStt];
+    const voicePreview = {
+        name: 'voice_preview',
+        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）。' },
+        }),
+        output: {
+            schema: previewSchema,
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const samples = Array.isArray(rec.samples) ? rec.samples : [];
+                const failed = Array.isArray(rec.failed) ? rec.failed : [];
+                const lines = ['试听样例已生成 ' + samples.length + ' 个（试听文本：' + rec.text + '）：'];
+                for (const item of samples) {
+                    const s = asRecord(item);
+                    lines.push('- ' + s.voice + ' -> ' + s.output);
+                }
+                for (const item of failed) {
+                    const f = asRecord(item);
+                    lines.push('- ' + f.voice + ' 失败：' + String(f.error ?? ''));
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute(rawArgs) {
+            const args = asRecord(rawArgs);
+            const rawVoices = Array.isArray(args.voices)
+                ? args.voices.filter((v) => typeof v === 'string' && v.trim() !== '').map((v) => v.trim())
+                : [];
+            const targets = rawVoices.length > 0 ? rawVoices : VOICES.slice(0, 4).map((v) => v.id);
+            if (targets.length > 8)
+                throw new Error('voices 最多 8 个（当前 ' + targets.length + ' 个），试听一次别太多，慢且耗资源。');
+            const text = optionalString(args, 'text') ?? DEFAULT_PREVIEW_TEXT;
+            if (text.length > 200)
+                throw new Error('试听文本请控制在 200 字以内（试听要短平快）。');
+            const outDir = resolve(optionalString(args, 'outputDir') ?? 'voice_previews');
+            mkdirSync(outDir, { recursive: true });
+            const samples = [];
+            const failed = [];
+            for (const voice of targets) {
+                if (!isValidVoiceId(voice)) {
+                    failed.push({ voice, error: '音色 id 不合法（应为 zh-CN-XXXNeural 形式的 edge 音色）' });
+                    continue;
+                }
+                try {
+                    const audio = await (deps.tts ?? synthesizeSpeech)({ text, voice, rate: cfg.ttsRate, pitch: cfg.ttsPitch }, { proxyUrl: cfg.proxyUrl }, timeout);
+                    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 });
+                }
+                catch (error) {
+                    failed.push({ voice, error: error instanceof Error ? error.message : String(error) });
+                }
+            }
+            return { count: samples.length, samples, failed, text };
+        },
+        timeoutMs: timeout + 10000,
+    };
+    const voiceHealth = {
+        name: 'voice_health',
+        description: 'dsh-voice 自检：检查 TTS 音色合法性、代理配置与 ASR 引擎/密钥就绪状态（不发起网络请求）。遇到问题时先运行本工具定位。',
+        parameters: compileParameters({}),
+        output: {
+            schema: { type: 'object', additionalProperties: true },
+            render: (_args, value) => {
+                const rec = asRecord(value);
+                const checks = Array.isArray(rec.checks) ? rec.checks : [];
+                const lines = ['dsh-voice 自检' + (rec.ok === true ? '：正常。' : '：发现问题。')];
+                for (const item of checks) {
+                    const c = asRecord(item);
+                    lines.push('- ' + c.name + '：' + (c.ok === true ? '✅ ' + String(c.detail ?? '') : '❌ ' + String(c.detail ?? '')));
+                }
+                return [{ type: 'text', text: lines.join('\n') }];
+            },
+        },
+        async execute() {
+            const checks = [];
+            let ok = true;
+            const voiceOk = isValidVoiceId(cfg.ttsVoice);
+            checks.push({ name: 'TTS 音色', ok: voiceOk, detail: voiceOk ? cfg.ttsVoice : '不合法：' + cfg.ttsVoice + '（用 voice_list 查看）' });
+            if (!voiceOk)
+                ok = false;
+            checks.push({ name: '特殊代理', ok: true, detail: cfg.proxyUrl !== '' ? '已配置 ' + cfg.proxyUrl : '未配置' });
+            checks.push({ name: 'ASR 引擎', ok: true, detail: cfg.asrEngine });
+            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)
+                ok = false;
+            return { ok, plugin: 'dsh-voice', checks };
+        },
+        timeoutMs: 5000,
+    };
+    return [voiceList, voiceTts, voiceStt, voicePreview, voiceHealth];
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-voice",
-  "version": "0.1.1",
+  "version": "0.3.1",
   "description": "DSH 语音双件套插件：voice_tts（edge-tts 协议零成本微软神经语音合成）/ voice_stt（OpenAI 兼容 ASR 语音转文字）/ voice_list（音色列表），原生 WebSocket + 插件级代理。",
   "type": "module",
   "main": "lib/index.js",
@@ -21,7 +21,6 @@
   ],
   "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"