dsh-voice 0.5.11 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,15 @@
1
1
  # 更新记录
2
2
 
3
+ ## 0.6.1 (2026-11-18)
4
+
5
+ - 同步 `@stardustlc/dsh-updates` 0.2.3:侧边栏工作台平时默认隐藏底部更新栏(零高度占用),仅在检测到兼容新版本或执行更新时浮现单行精简提示条;完整更新设置与检查入口统一保留在 DSH「插件」详情页底部。
6
+ - Sync `@stardustlc/dsh-updates` 0.2.3: keep the sidebar workbench update footer hidden by default when up-to-date, surfacing a single-line compact strip only for actionable updates or active jobs while retaining full controls in native Plugin Details.
7
+
8
+ ## 0.6.0 (2026-11-18)
9
+
10
+ - 新增零外部依赖的宿主原生 `Config` 设置表单声明(`asrApiKey` 与 `proxyUrl` 自动脱敏并支持热更新生效),明确配音免密钥开箱即用与转写配置指引,并补齐日常配音/会议纪要使用流程。
11
+ - Export a zero-dependency native DSH `Config` schema with secret masking and live reload across all 10 voice/ASR settings, clearer zero-key TTS vs. ASR setup hints, and human-centric workflow docs.
12
+
3
13
  ## 0.5.11 (2026-11-18)
4
14
 
5
15
  - 更新区底部新增克制、无打扰的 GitHub 点赞与问题反馈快捷链接,并完善中英文检索关键词。
package/README.en.md CHANGED
@@ -2,13 +2,13 @@
2
2
 
3
3
  # Voice
4
4
 
5
- **Turn text into speech and recordings into text.**
5
+ **Turn text into natural speech and recordings into clean transcripts.**
6
6
 
7
- Voice plugin for DeepSeek Harness (`>=0.2.2-rc.3`): provides keyless Edge neural text-to-speech (TTS), short voice previews, and OpenAI/Groq-compatible speech-to-text (STT) bounded to the workspace.
7
+ Voice plugin for DeepSeek Harness (`>=0.2.2-rc.3`): provides zero-key Edge neural text-to-speech (TTS), batch voice previews, native live Settings forms with secret masking, and OpenAI/Groq-compatible speech-to-text (STT) strictly scoped to your session workspace.
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/dsh-voice)](https://www.npmjs.com/package/dsh-voice) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-voice-downloads.svg)](https://www.npmjs.com/package/dsh-voice) [![total downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-voice-total-downloads.svg)](https://www.npmjs.com/package/dsh-voice)
10
10
 
11
- **[Install](#install) · [Workflow](#start-using-it) · [Full guide](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.en.md)**
11
+ **[Install](#install) · [Get Started in 3 Steps](#get-started-in-3-steps) · [Full Guide](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.en.md)**
12
12
 
13
13
  <picture>
14
14
  <source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-en-mobile-dark.svg">
@@ -17,52 +17,55 @@ Voice plugin for DeepSeek Harness (`>=0.2.2-rc.3`): provides keyless Edge neural
17
17
  <img src="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-en-light.svg" alt="Turn text into speech and recordings into text. · workflow illustration" width="100%">
18
18
  </picture>
19
19
 
20
- ## Features
21
-
22
- - Choose a voice and speed with a short sample.
23
- - Keep audio files you can play or deliver.
24
- - Transcribe with your configured compatible ASR service.
25
-
26
20
  ## Install
27
21
 
28
- Open **Plugins** in the DSH desktop app and install `dsh-voice`. If the CLI is available:
22
+ Open **Plugins** in the DSH desktop app and install `dsh-voice`, or use the CLI:
29
23
 
30
24
  ```bash
31
25
  dsh plugin --profile desktop add dsh-voice
32
26
  ```
33
27
 
34
- For the web profile, replace `desktop` with `web`. Restart that DSH profile after installation. The package’s DSH requirement is `>=0.2.2-rc.3`.
35
-
36
- ## Start using it
28
+ For the web profile, replace `desktop` with `web`. Restart DSH once after installing. Requires DSH `>=0.2.2-rc.3`.
37
29
 
38
- 1. Start a DSH session in the workspace where you want the audio saved; ask it to check the voice tools.
39
- 2. Provide text, language, voice and speed, for example: “Make a Chinese MP3 from this text; give me a short sample first.”
40
- 3. Listen to the sample, generate the complete audio, then play or deliver the returned file.
41
- 4. For transcription, configure your own compatible ASR service, provide a local audio file, then review the transcript.
30
+ <a id="start-using-it"></a>
31
+ ## Get Started in 3 Steps
42
32
 
43
- Example request:
33
+ 1. **Read-aloud works out of the box (zero API keys)**: Open a DSH session in your target workspace and ask the assistant to preview voices or turn any script into an MP3 immediately.
34
+ 2. **Add an ASR key when you need transcription (applies live)**: Open **DSH Settings → Plugins → Voice (`dsh-voice`)** and enter your Groq or OpenAI-compatible `asrApiKey` (masked and applied immediately without restarting; `DSH_VOICE_ASR_KEY` env var is also supported).
35
+ 3. **Preview, synthesize, or transcribe inside your workspace**: Place recordings inside your session workspace; generated MP3s and `.txt` transcripts stay safely inside the workspace and auto-number instead of overwriting existing files.
44
36
 
45
- > Make a Chinese MP3 from this text. Start with a short voice sample.
37
+ ## Copy-Ready Prompts for Everyday Work
46
38
 
47
- ## Before you start
39
+ - **Audition 3 voices first, then synthesize the full audio (zero config)**
40
+ > Generate short voice preview samples for 3 natural narration voices so I can listen first, then synthesize the full MP3 once I pick one.
41
+ - **Turn a written briefing into a ready-to-play MP3**
42
+ > Condense today's notes into a 2-minute spoken script and generate `morning-brief.mp3` at `+10%` speed.
43
+ - **Transcribe a meeting recording & extract action items**
44
+ > Transcribe `meeting.m4a` in this workspace, save the full transcript to `meeting.txt`, and list the action items.
48
45
 
49
- Edge speech requires a network connection; ASR needs your own service configuration.
46
+ ## Quick Troubleshooting Checklist
50
47
 
51
- Configuration, detailed tools and troubleshooting: [full reference](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.en.md).
48
+ | Symptom | Likely Cause | Fix |
49
+ | :--- | :--- | :--- |
50
+ | Health check says `asrApiKey` is missing, but you only want TTS | ASR key is only needed for audio-to-text transcription | **Keep using TTS directly** — no key is required for speech synthesis or previews |
51
+ | "Must stay inside the session workspace" error | Recording or output path points outside the workspace folder | Copy the audio file into the current DSH workspace folder first |
52
+ | Network / connection error | Corporate firewall or proxy required to reach Edge TTS / ASR | Set `proxyUrl` (e.g. `http://127.0.0.1:7890`) in **DSH Settings → Plugins → Voice** (applies live) |
53
+ | Audio exceeds 25 MB limit | Standard Whisper/ASR upload limit is 25 MB | Compress or split the audio with `dsh-ffmpeg` first, then transcribe |
52
54
 
53
55
  ## Plugin updates
54
56
 
55
- Check updates at the bottom of the workbench or native plugin details. Automatic checks are on by default; **automatic installation is off**. You choose whether to install and when to restart. Suite-managed components update with their bundle. [Update behavior](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.en.md).
57
+ Check updates at the bottom of native plugin details. Automatic checks are on by default; **automatic installation is off**. Suite-managed components update with their bundle.
56
58
 
57
59
  ## Documentation
58
60
 
59
- - [Full usage, configuration and limits](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.en.md)
61
+ - [Usage guide and configuration reference](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.en.md)
62
+ - [Full reference](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.en.md)
60
63
  - [Release notes](https://github.com/STARDUSTLC666/dsh-voice/blob/master/CHANGELOG.md)
61
64
  - [Validation scope and history](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/VALIDATION.md)
62
65
 
63
66
  ## Feedback and contributions
64
67
 
65
- If the plugin helps, a Star makes it easier for others to discover. Report problems or suggest improvements in [Issues](https://github.com/STARDUSTLC666/dsh-voice/issues); code and documentation [PRs](https://github.com/STARDUSTLC666/dsh-voice/pulls) are welcome. Include versions and reproduction steps, and remove credentials from reports.
68
+ If the plugin helps, a Star makes it easier for others to discover. Report issues in [Issues](https://github.com/STARDUSTLC666/dsh-voice/issues) or open [PRs](https://github.com/STARDUSTLC666/dsh-voice/pulls) (please strip credentials).
66
69
 
67
70
  ## License
68
71
 
package/README.md CHANGED
@@ -2,13 +2,13 @@
2
2
 
3
3
  # Voice
4
4
 
5
- **把文字变成声音,把录音变成文字。**
5
+ **把文字变成自然人声,把会议录音转成干净文字。**
6
6
 
7
- DeepSeek Harness(`>=0.2.2-rc.3`)语音插件:提供零密钥 Edge 神经网络语音合成(TTS)、短试听音色预览以及 OpenAI/Groq 兼容语音转文字(STT),输出严格限定在工作区路径内。
7
+ DeepSeek Harness(`>=0.2.2-rc.3`)语音插件:内置零密钥 Edge 神经网络语音合成(TTS)与短试听音色挑选,支持原生设置表单与热生效、OpenAI / Groq 兼容语音转文字(STT),并严格将读写限制在当前会话工作区内。
8
8
 
9
9
  [![npm](https://img.shields.io/npm/v/dsh-voice)](https://www.npmjs.com/package/dsh-voice) [![downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-voice-downloads.svg)](https://www.npmjs.com/package/dsh-voice) [![total downloads](https://raw.githubusercontent.com/STARDUSTLC666/dsh-suite/npm-downloads/assets/dsh-voice-total-downloads.svg)](https://www.npmjs.com/package/dsh-voice)
10
10
 
11
- **[安装使用](#安装) · [使用流程](#开始使用) · [完整说明](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.zh.md)**
11
+ **[安装使用](#安装) · [最快 3 步用起来](#最快-3-步用起来) · [完整说明](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.md)**
12
12
 
13
13
  <picture>
14
14
  <source media="(prefers-color-scheme: dark) and (max-width: 640px)" srcset="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-zh-mobile-dark.svg">
@@ -17,52 +17,55 @@ DeepSeek Harness(`>=0.2.2-rc.3`)语音插件:提供零密钥 Edge 神经
17
17
  <img src="https://raw.githubusercontent.com/STARDUSTLC666/dsh-voice/master/docs/assets/intro/workflow-zh-light.svg" alt="把文字变成声音,把录音变成文字。 · 流程示意" width="100%">
18
18
  </picture>
19
19
 
20
- ## 功能
21
-
22
- - 短试听后再决定音色与语速。
23
- - 保留可直接播放和交付的音频文件。
24
- - 转写使用你配置的兼容 ASR 服务。
25
-
26
20
  ## 安装
27
21
 
28
- 在 DSH 桌面版「插件」面板安装 `dsh-voice`。已配置命令行时也可使用:
22
+ 在 DSH 桌面版「插件」面板搜索安装 `dsh-voice`,或使用命令行:
29
23
 
30
24
  ```bash
31
25
  dsh plugin --profile desktop add dsh-voice
32
26
  ```
33
27
 
34
- 网页版把 `desktop` 改为 `web`;安装后重启对应的 DSH。宿主要求以包声明 `>=0.2.2-rc.3` 为准。
35
-
36
- ## 开始使用
28
+ 网页版把 `desktop` 改为 `web`;安装后重启一次 DSH。宿主要求 `>=0.2.2-rc.3`。
37
29
 
38
- 1. 在要保存音频的工作区新建 DSH 会话,让助手先检查语音工具是否可用。
39
- 2. 提供要朗读的文字、语言、音色和语速,例如“把这段文字生成中文 MP3,先给我短试听”。
40
- 3. 试听后再生成完整音频,按工具返回的文件路径播放或交付。
41
- 4. 需要转写时先配置自己的兼容 ASR 服务,再提供本地音频文件;核对转写结果后使用。
30
+ <a id="开始使用"></a>
31
+ ## 最快 3 步用起来
42
32
 
43
- 可以这样说:
33
+ 1. **文字转语音开箱即用(零 API 密钥)**:装好插件后无需填任何密钥,直接在工作区新建会话,就能让助手试听多种音色并把文章、播客稿或早报合成 MP3。
34
+ 2. **录音转文字按需填密钥(保存即生效)**:需要把录音转文字时,打开 DSH「**设置 → 插件 → 语音(dsh-voice)**」填入 Groq 或 OpenAI 兼容的 `asrApiKey`(自动脱敏、保存即生效;也支持环境变量 `DSH_VOICE_ASR_KEY`)。
35
+ 3. **试听选声 → 合成或转写交付**:把待转写录音放到当前会话工作区,合成出的 MP3 或 `.txt` 纪要也会安全落在工作区且同名自动编号不误盖。
44
36
 
45
- > 把这段文字生成中文 MP3,先给我一段短试听。
37
+ ## 平时怎么对助手说(可直接复制的自然语言示例)
46
38
 
47
- ## 开始前要知道
39
+ - **先生成短试听挑音色,再合成完整配音(零配置)**
40
+ > 挑 3 个适合播客的中英文音色给我生成短试听样例,等我选好后再把这篇早报稿合成完整 MP3。
41
+ - **一步把总结变成可带走听的语音早报**
42
+ > 把今天的重点文档浓缩成 300 字口播稿,用温和自然的中文男声(语速 +10%)生成 `morning-brief.mp3`。
43
+ - **把工作区里的会议录音转成文字并提炼纪要**
44
+ > 把当前目录里的 `meeting.m4a` 转写成中文,原稿存到 `meeting.txt`,再帮我整理一份待办事项清单。
48
45
 
49
- Edge 朗读需要联网;ASR 需要自己的服务配置。
46
+ ## 常见卡点自检
50
47
 
51
- 配置、完整工具与排错见[详细使用说明](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.zh.md)。
48
+ | 遇到的现象 | 10 秒定位原因 | 怎么修 |
49
+ | :--- | :--- | :--- |
50
+ | 自检提示「缺 ASR 密钥」但只想做朗读配音 | ASR 密钥仅录音转文字需要,不影响朗读 | **直接正常合成语音即可**;日后需要转写录音再去「设置 → 插件 → 语音」补填 `asrApiKey` |
51
+ | 提示「必须位于会话工作区内」 | 录音或输出路径指到了工作区文件夹外面 | 先把音频复制进当前会话工作区文件夹再让助手转写 |
52
+ | 合成或转写报网络连接失败 | 受限网络无法直连在线语音 / ASR 服务 | 在 DSH「设置 → 插件 → 语音」填入本地 HTTP 代理 `proxyUrl`(如 `http://127.0.0.1:7890`,保存即生效) |
53
+ | 音频超过 25MB 无法转写 | 在线 ASR 接口单文件体积上限为 25MB | 先让助手用 `dsh-ffmpeg` 压缩码率或按时间切段后再转写 |
52
54
 
53
55
  ## 插件更新
54
56
 
55
- 在工作台或原生插件详情页底部检查更新。默认自动检查,**默认不自动安装**;是否安装、何时重启由你决定。Suite 管理的组件随整包更新。[查看更新规则](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.zh.md)。
57
+ 在原生插件详情页底部检查更新。默认自动检查,**默认不自动安装**;是否安装、何时重启由你决定。Suite 管理的组件随整包更新。
56
58
 
57
59
  ## 文档
58
60
 
59
- - [详细使用、配置与边界](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.zh.md)
61
+ - [使用说明与参数参考](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/USAGE.md)
62
+ - [详细参考说明](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/REFERENCE.zh.md)
60
63
  - [更新记录](https://github.com/STARDUSTLC666/dsh-voice/blob/master/CHANGELOG.md)
61
64
  - [验证范围与历史](https://github.com/STARDUSTLC666/dsh-voice/blob/master/docs/VALIDATION.md)
62
65
 
63
66
  ## 反馈与贡献
64
67
 
65
- 如果插件帮到了你,欢迎 Star,让更多人发现它。问题和建议请提交 [Issues](https://github.com/STARDUSTLC666/dsh-voice/issues),也欢迎代码与文档 [PR](https://github.com/STARDUSTLC666/dsh-voice/pulls)。反馈时附上版本与复现步骤,并移除凭据。
68
+ 如果插件帮到了你,欢迎 Star。问题和建议请提交 [Issues](https://github.com/STARDUSTLC666/dsh-voice/issues),也欢迎 [PR](https://github.com/STARDUSTLC666/dsh-voice/pulls)(反馈时请移除凭据)。
66
69
 
67
70
  ## License
68
71
 
package/docs/USAGE.en.md CHANGED
@@ -1,94 +1,100 @@
1
- # dsh-voice usage guide
1
+ # dsh-voice Usage Guide
2
2
 
3
3
  [Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
4
4
 
5
- ## Current improvements
5
+ ## Get Started in 3 Steps
6
6
 
7
- ASR stops on redirects instead of forwarding audio to another endpoint, including through the plugin proxy. Set `asrBaseUrl` to the trusted final API address. With `overwrite=false`, concurrent outputs are saved separately and tools return the actual saved path. Explicit overwrite requires a regular file with no hard links.
7
+ ### Step 1: Know What Works Out of the Box vs. Optional ASR Setup
8
8
 
9
- Check the ASR endpoint, key and response format after a failure. Blank results are not saved as successful transcripts. Verify TTS and ASR service availability separately.
9
+ - **Text-to-speech (`voice_tts`, `voice_list`, `voice_preview`) works with zero config**: No API keys needed — install the plugin and synthesize speech or audition voices right away.
10
+ - **Speech-to-text (`voice_stt`) needs an ASR key when you want transcription**:
11
+ - **Recommended**: Open **DSH → Settings → Plugins → Voice (`dsh-voice`)**, pick `asrEngine` (`groq` by default, `openai`, or `custom`), and paste `asrApiKey` (masked and **applied live on save without restarting**);
12
+ - **CLI / Environment variable**: Set `DSH_VOICE_ASR_KEY` or configure `cordis.patch.yml`:
10
13
 
11
- ## Installation
12
-
13
- ```bash
14
- dsh plugin --profile web add dsh-voice
14
+ ```yaml
15
+ - id: voice
16
+ name: 'dsh-voice'
17
+ config:
18
+ ttsVoice: zh-CN-XiaoxiaoNeural # default voice (applies live)
19
+ ttsRate: '+0%' # default speech rate, e.g. +15% or -10%
20
+ ttsPitch: '+0Hz' # default pitch, e.g. +2Hz or -1Hz
21
+ asrEngine: groq # groq | openai | custom
22
+ asrModel: whisper-large-v3-turbo # optional; defaults to engine preset
23
+ # asrApiKey: gsk_... # prefer DSH Settings or env var DSH_VOICE_ASR_KEY
24
+ # proxyUrl: http://127.0.0.1:7890 # optional HTTP(S) proxy URL
15
25
  ```
16
26
 
17
- ## Uninstall
27
+ ### Step 2: Keep Audio & Outputs Inside Your Session Workspace
18
28
 
19
- ```bash
20
- dsh plugin --profile web remove dsh-voice
21
- ```
29
+ All input audio and output MP3 / `.txt` files must resolve under the active DSH session workspace (`session.header.cwd`) to protect host files. Copy outside recordings into the workspace first.
22
30
 
23
- Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
31
+ ### Step 3: Audition Voices, Then Synthesize or Transcribe
24
32
 
25
- ## Configuration
33
+ Unsure which voice fits best? Ask the assistant to generate short preview samples in parallel before rendering your full script.
26
34
 
27
- `voice_tts` works with zero config; `voice_stt` needs an ASR key:
35
+ ---
28
36
 
29
- ```yaml
30
- - id: voice
31
- name: 'dsh-voice'
32
- config:
33
- asrEngine: groq # groq | openai | custom
34
- asrModel: whisper-large-v3-turbo # Groq whisper model
35
- # asrApiKey: gsk_... # prefer env var DSH_VOICE_ASR_KEY
36
- ttsVoice: zh-CN-XiaoxiaoNeural # default voice
37
- # proxyUrl: http://127.0.0.1:7890 # enable when the ASR endpoint needs a special proxy
38
- ```
37
+ ## Copy-Ready Prompts for Everyday Work
39
38
 
40
- ## Tools
41
-
42
- | Tool | Purpose | Key parameters |
43
- | :-- | :-- | :-- |
44
- | `voice_tts` | Synthesize MP3 from text (Edge online service) | `text` required; `voice`/`rate`/`pitch`/`output` optional |
45
- | `voice_stt` | Transcribe audio to text | `audio` required; `model`/`language`/`prompt`/`output` optional; `engine` may only repeat the configured `asrEngine` |
46
- | `voice_list` | Curated voice catalog | none |
47
- | `voice_preview` | Batch-generate short preview MP3s | optional `voices` (≤8) / `text` / `outputDir` |
48
- | `voice_health` | Offline config self-check | none |
49
-
50
- ### Examples
51
-
52
- ```text
53
- voice_tts { text: hello world } # outputs voice_output.mp3
54
- voice_tts { text: hello, voice: en-US-AriaNeural } # English female voice
55
- voice_stt { audio: meeting.mp3, language: zh } # transcribe a recording inside the session workspace
56
- voice_list {}
57
- voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # generate two preview samples
58
- voice_health {} # self-check TTS / ASR / proxy config
59
- ```
39
+ - **Audition voices before committing to a full render**
40
+ > List the built-in voices and generate short preview MP3s for 4 distinct voices so I can choose my favorite.
41
+ - **Render a polished voiceover MP3**
42
+ > Synthesize this release summary into `release-note.mp3` using `en-US-AriaNeural` at `+10%` speed.
43
+ - **Transcribe a recording with domain terminology hints**
44
+ > Transcribe `interview.mp3` in this workspace (prompt hint: DeepSeek Harness, Cordis), save the full text to `interview.txt`, and list the 5 key takeaways.
45
+ - **Offline configuration self-check**
46
+ > Run a voice health check to verify my default TTS voice, proxy, and ASR key status.
47
+
48
+ ---
49
+
50
+ ## Quick Troubleshooting Checklist
51
+
52
+ Run `voice_health` first (offline check with zero network traffic that clearly separates `voice_stt`-only issues from TTS):
60
53
 
61
- ## Implementation and file limits
54
+ | Symptom | Usual Cause | Quick Fix |
55
+ | :--- | :--- | :--- |
56
+ | Health check says `asrApiKey` is missing | `asrApiKey` and `DSH_VOICE_ASR_KEY` are both empty | Safe to ignore if you only need TTS (`voice_tts` needs no key); for transcription, fill `asrApiKey` in **DSH Settings → Plugins → Voice** (applies live) |
57
+ | Invalid voice ID error | `ttsVoice` does not match Edge neural voice format | Run `voice_list` to pick a valid ID (e.g. `zh-CN-XiaoxiaoNeural`) and update `ttsVoice` in Settings |
58
+ | Network error on TTS or STT | Direct connection blocked by corporate network | Enter an HTTP(S) `proxyUrl` (e.g. `http://127.0.0.1:7890`) in **DSH Settings → Plugins → Voice** (applies live) |
59
+ | Path outside session workspace error | Audio or output path resolves outside workspace | Copy the recording into the current session workspace folder first |
60
+ | Audio exceeds 25 MB limit | Standard Whisper / ASR multipart cap is 25 MB | Compress or split the recording with `dsh-ffmpeg` before transcribing |
61
+ | ASR refuses a 3xx redirect | Redirects are blocked so audio/keys never leak to another host | Set `asrBaseUrl` directly to the final non-redirecting `/v1` endpoint |
62
+ | Existing output file was not overwritten | `overwrite: false` (default) suffixes `_1`, `_2` safely | Use the exact path returned by the tool, or enable `overwrite` in Settings |
62
63
 
63
- - **Direct edge-tts protocol**: follows open-source edge-tts 7.3.1 Sec-MS-GEC v2, generating tokens locally in five-minute windows. Uses `ws` and optional HTTP CONNECT. This is not a Microsoft SDK, and the service protocol may change.
64
- - **API configuration**: TTS needs no separate API key. STT uses your configured ASR service, whose pricing and limits apply.
65
- - Up-front validation: text ≤ 5000 chars, audio ≤ 25MB (re-checked against the bytes actually read); same-name outputs auto-suffixed
66
- - **Reads and writes stay inside the session workspace**: `audio`, `output` and `outputDir` must resolve (symlinks included) under `session.header.cwd`; anything outside is rejected. Copy the file in first.
67
- - **Symlinks are never written through**: a target that is a symlink (including a dangling one) is refused, and new files are created with `O_EXCL`.
68
- - **Transcripts are 0600**: the `.txt` written by `voice_stt` is owner-only (Windows does not enforce the mode bits).
69
- - **The key only goes to the configured endpoint**: ASR always uses `asrBaseUrl` from config (the groq/openai presets are defaults only); an `engine` argument that differs from config is rejected instead of shipping the key to another vendor.
70
- - Protocol aligned with current open-source edge-tts (7.x) — no reliance on the outdated token endpoint
64
+ ---
71
65
 
72
- ## Troubleshooting
66
+ ## Tool & Safety Reference
73
67
 
74
- Run `voice_health` first: it makes no network requests and reports the TTS voice, proxy and ASR engine/endpoint/key one by one. Every failing check carries its fix and states the impact (a missing key only breaks `voice_stt`; the three TTS tools keep working).
68
+ ### Registered Tools (All 5)
75
69
 
76
- - **Invalid voice id**: pick one from `voice_list` (ids look like `zh-CN-XiaoxiaoNeural`), or change `ttsVoice` in config and restart.
77
- - **TTS reports a network error**: Edge read-aloud is a third-party online service and needs internet access. Behind a corporate network or proxy, set `proxyUrl` to an http(s) proxy such as `http://127.0.0.1:7890`.
78
- - **STT reports a missing key or endpoint**: set `DSH_VOICE_ASR_KEY` (recommended; keeps the key out of config files) or configure `asrApiKey`. With `asrEngine: custom` you must also provide `asrBaseUrl`.
79
- - **STT says the audio is missing or out of scope**: `audio` and every output must stay inside the current session workspace; copy outside recordings in first.
80
- - **Transcription refused with a 3xx**: the plugin stops instead of posting audio to the redirect target. Set `asrBaseUrl` to the trusted final endpoint.
81
- - **Same-name output was not overwritten**: with `overwrite: false` (default) the file is suffixed; use the `output` / `transcriptFile` the tool returned.
82
- - **Timeouts**: `timeoutMs` defaults to 60000, clamped to 5000-600000; raise it for large files or slow services.
70
+ | Tool | Purpose | Key Parameters & Notes |
71
+ | :--- | :--- | :--- |
72
+ | `voice_tts` | Synthesize MP3 from text (keyless Edge neural TTS) | `text` required (≤5000 chars); optional `voice`, `rate`, `pitch`, `output` |
73
+ | `voice_stt` | Transcribe audio to text (Groq / OpenAI / custom) | `audio` required (≤25 MB); optional `model`, `language`, `prompt`, `output` |
74
+ | `voice_list` | Browse curated multilingual & dialect voice catalog | No parameters |
75
+ | `voice_preview` | Bounded-concurrency (≤3) batch voice preview MP3s | Optional `voices` (≤8), `text` (≤200 chars), `outputDir` |
76
+ | `voice_health` | Offline configuration self-check | Checks TTS voice, proxy, and ASR engine/endpoint/key |
83
77
 
84
- ## Development
78
+ ### Workspace & Credential Guardrails
79
+
80
+ - **Workspace confinement & symlink protection**: All reads and writes stay under `session.header.cwd`, symlinks are never written through, new files use `O_EXCL`, and `.txt` transcripts use `0600` permissions on POSIX.
81
+ - **Pinned endpoint & redirect block**: ASR requests only go to the configured `asrBaseUrl`, mismatched `engine` overrides are rejected, and `3xx` redirects abort immediately before sending audio.
82
+ - **Instant cancellation**: `voice_tts`, `voice_preview`, and `voice_stt` propagate `exec.signal` to close WebSockets and abort uploads immediately on cancel.
83
+
84
+ ## Install, Uninstall & Development
85
85
 
86
86
  ```bash
87
+ # Install (use desktop instead of web for DSH Desktop)
88
+ dsh plugin --profile web add dsh-voice
89
+
90
+ # Uninstall
91
+ dsh plugin --profile web remove dsh-voice
92
+
93
+ # Build & run offline unit tests
87
94
  pnpm install
88
- pnpm test # build + offline unit tests with mocked TTS/ASR
89
- pnpm test:integration # opt-in real edge-tts request; network and assertion errors fail
95
+ pnpm test
90
96
  ```
91
97
 
92
98
  ## License
93
99
 
94
- Original code MIT; separate Edge v2 token module LGPLv3. See [third-party notices](../THIRD_PARTY_NOTICES.md).
100
+ Original code MIT; separate Edge v2 token module LGPL-3.0-only. See [third-party notices](../THIRD_PARTY_NOTICES.md).
package/docs/USAGE.md CHANGED
@@ -2,93 +2,99 @@
2
2
 
3
3
  [返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
4
4
 
5
- ## 本次改进
5
+ ## 最快 3 步用起来
6
6
 
7
- 转写失败时检查 ASR 地址、密钥与响应格式;空白识别结果不会作为成功转写保存。TTS 与 ASR 的外部服务可用性应分别核对。
7
+ ### 第 1 步:了解零配置范围与可选 ASR 配置
8
8
 
9
- ## 安装
9
+ - **文字转语音(`voice_tts` / `voice_list` / `voice_preview`)零配置即用**:无需申请任何 API 密钥,安装后联网即可试听音色与合成 MP3。
10
+ - **录音转文字(`voice_stt`)按需填密钥**:
11
+ - **推荐方式**:打开 **DSH → 设置 → 插件 → 语音(`dsh-voice`)**,选择 `asrEngine`(默认 `groq`,也可选 `openai` 或 `custom`),填入 `asrApiKey`(自动脱敏,**保存立即生效、无需重启**);
12
+ - **命令行 / 环境变量方式**:设置环境变量 `DSH_VOICE_ASR_KEY`,或在 `cordis.patch.yml` 中配置:
10
13
 
11
- ```bash
12
- dsh plugin --profile web add dsh-voice
14
+ ```yaml
15
+ - id: voice
16
+ name: 'dsh-voice'
17
+ config:
18
+ ttsVoice: zh-CN-XiaoxiaoNeural # 默认朗读音色(保存即生效)
19
+ ttsRate: '+0%' # 默认语速,如 +15% 或 -10%
20
+ ttsPitch: '+0Hz' # 默认音调,如 +2Hz 或 -1Hz
21
+ asrEngine: groq # groq | openai | custom
22
+ asrModel: whisper-large-v3-turbo # 可选;留空按引擎预设自动填入
23
+ # asrApiKey: gsk_... # 推荐在 DSH 设置页填写或用环境变量 DSH_VOICE_ASR_KEY
24
+ # proxyUrl: http://127.0.0.1:7890 # 网络需要 HTTP(S) 代理时填写
13
25
  ```
14
26
 
15
- ## 卸载
27
+ ### 第 2 步:在工作区内准备文稿或录音
16
28
 
17
- ```bash
18
- dsh plugin --profile web remove dsh-voice
19
- ```
29
+ 为了防止路径越界读取隐私文件,所有待转写音频与生成的 MP3 / `.txt` 都严格限制在**当前会话工作区**内;外部录音请先复制进工作区目录。
20
30
 
21
- 卸载后重启 Web 服务。如需彻底清理,可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
31
+ ### 第 3 步:试听选定音色,合成配音或转写纪要
22
32
 
23
- ## 配置
33
+ 不确定哪个声音好听时,先让助手生成几段 3 秒短试听样例对比,再一键合成正式音频。
24
34
 
25
- `voice_tts` 零配置可用;`voice_stt` 需要 ASR 密钥:
35
+ ---
26
36
 
27
- ```yaml
28
- - id: voice
29
- name: 'dsh-voice'
30
- config:
31
- asrEngine: groq # groq | openai | custom
32
- asrModel: whisper-large-v3-turbo # groq 的 whisper 模型
33
- # asrApiKey: gsk_... # 推荐改用环境变量 DSH_VOICE_ASR_KEY
34
- ttsVoice: zh-CN-XiaoxiaoNeural # 默认音色
35
- # proxyUrl: http://127.0.0.1:7890 # ASR 接口需要特殊代理时启用
36
- ```
37
+ ## 平时怎么对助手说(可直接复制的自然语言示例)
37
38
 
38
- ## 工具一览
39
-
40
- | 工具 | 作用 | 关键参数 |
41
- | :-- | :-- | :-- |
42
- | `voice_tts` | 文字合成 MP3(Edge 在线服务) | `text` 必填;`voice`/`rate`/`pitch`/`output` 可选 |
43
- | `voice_stt` | 音频转文字 | `audio` 必填;`model`/`language`/`prompt`/`output` 可选;`engine` 只能与配置 `asrEngine` 相同 |
44
- | `voice_list` | 常用音色清单 | 无 |
45
- | `voice_preview` | 音色试听:批量生成短样例 MP3 | `voices`(≤8 个)/ `text` / `outputDir` 可选 |
46
- | `voice_health` | 配置自检(不联网) | 无 |
47
-
48
- ### 示例
49
-
50
- ```text
51
- voice_tts { text: 今天的 AI 早报来了 } # 晓晓女声,输出 voice_output.mp3
52
- voice_tts { text: hello, voice: en-US-AriaNeural } # 英文女声
53
- voice_stt { audio: meeting.mp3, language: zh } # 转写会话工作区里的录音
54
- voice_list {}
55
- voice_preview { voices: [zh-CN-XiaoxiaoNeural, en-US-AriaNeural] } # 生成两个试听样例
56
- voice_health {} # 自检 TTS / ASR / 代理配置
57
- ```
39
+ - **批量短试听挑选音色(不盲猜 ID)**
40
+ > 先帮我看看常用中英文音色清单,挑 4 个风格不同的音色生成一段短试听 MP3 让我选。
41
+ - **把文章或报告合成可播放的语音文件**
42
+ > 用 `zh-CN-YunxiNeural` 男声(语速 `+10%`)把这段产品更新说明合成到 `update-audio.mp3`。
43
+ - **录音转写 + 专有名词纠偏 + 落盘存档**
44
+ > 把工作区里的 `interview.mp3` 转写成中文(提示词加上专有名词:DeepSeek Harness、Cordis),完整转写存进 `interview.txt`,并总结 5 条核心结论。
45
+ - **不确定代理或密钥是否就绪时先自检**
46
+ > 跑一下语音插件自检,看看当前默认音色、代理和语音转文字密钥状态。
47
+
48
+ ---
49
+
50
+ ## 常见卡点自检
51
+
52
+ 遇到问题先让助手执行 `voice_health`(纯本地检查,不发起网络请求,并明确区分哪些问题只影响 `voice_stt`):
58
53
 
59
- ## 实现与文件限制
54
+ | 现象 | 常见原因 | 一步修复 |
55
+ | :--- | :--- | :--- |
56
+ | 自检提示「缺 ASR 密钥」 | 尚未填写 `asrApiKey` 且未设 `DSH_VOICE_ASR_KEY` | 若只需朗读配音可忽略(`voice_tts` 不需要密钥);若需转写录音,在 **DSH「设置 → 插件 → 语音」**填入 `asrApiKey` 保存即生效 |
57
+ | 提示音色 ID 不合法 | `ttsVoice` 拼写不符合 Edge 神经音色格式 | 让助手运行 `voice_list` 查看合法 ID(如 `zh-CN-XiaoxiaoNeural`),在设置页更新 `ttsVoice` |
58
+ | `voice_tts` 或 `voice_stt` 报网络失败 | 当前网络无法直连 Edge 朗读服务或外网 ASR 接口 | 在 **DSH「设置 → 插件 → 语音」**填写 `proxyUrl`(如 `http://127.0.0.1:7890`,保存即生效) |
59
+ | 提示文件必须位于会话工作区内 | 传入了工作区外部路径或越界符号链接 | 将录音复制到当前会话工作区文件夹内再执行 |
60
+ | 音频超过 25MB 报超限 | OpenAI / Groq 兼容 ASR 单文件上限 25MB | 先用 `dsh-ffmpeg` 压低码率或分段裁剪后再转写 |
61
+ | ASR 返回 3xx 重定向被拦截 | 为防音频与密钥被转发到第三方主机,插件拒绝自动跟随重定向 | 将 `asrBaseUrl` 直接改为服务商最终无跳转的 `/v1` 地址 |
62
+ | 同名文件没有覆盖旧文件 | 默认 `overwrite: false` 防误删,自动追加 `_1`、`_2` 序号 | 查看工具返回的实际落盘路径,或在设置中显式开启 `overwrite` |
60
63
 
61
- - **edge-tts 协议直连**:对齐开源 edge-tts 7.3.1 的 Sec-MS-GEC v2 协议,令牌在本地按 5 分钟窗口生成;WS 使用 `ws` 库与可选 HTTP CONNECT 代理。不是微软官方 SDK,服务协议仍可能变更。
62
- - **接口配置**:TTS 无需另填 API Key;STT 使用你配置的 ASR 服务,其计费与额度由该服务决定。
63
- - 文本 ≤5000 字符、音频 ≤25MB 前置校验(读入后再按实际字节数复查一次);输出同名自动加序号
64
- - **读写都在会话工作区内**:`audio` 与 `output` / `outputDir` 解析后(含符号链接)必须落在 `session.header.cwd` 之下,越界直接报错。想转写工作区外的录音,先复制进来;输出同理
65
- - **不跟随符号链接写文件**:目标是符号链接(含悬空链接)时拒绝写入,新建文件用 `O_EXCL`,避免检查完再被换成链接
66
- - **转写文本 0600**:`voice_stt` 写出的 `.txt` 只给当前用户读写(Windows 不检查权限位)
67
- - **密钥只发给配置的地址**:ASR 请求地址一律取配置 `asrBaseUrl`(groq/openai 的预设只是缺省值),模型传的 `engine` 与配置不一致会直接报错,避免把密钥发到另一家的主机
68
- - **重定向需要用户确认地址**:接口返回 3xx 时停止,不向跳转地址发送音频。请检查服务文档,把 `asrBaseUrl` 设为可信的最终接口;这也适用于配置了插件代理的请求。
69
- - **并发生成不覆盖**:`overwrite=false` 时即使两个任务同时写同名文件,或合成期间出现用户同名文件,也会另存并返回实际文件名。显式覆盖只接受没有硬链接的普通文件。
70
- - Edge TTS 协议适配保留在插件实现中,不使用旧令牌端点。
64
+ ---
71
65
 
72
- ## 排错
66
+ ## 工具与安全边界参考
73
67
 
74
- 先跑 `voice_health`:它不发网络请求,逐项报 TTS 音色、代理、ASR 引擎/地址/密钥;失败项带修复动作,并说明影响面(缺密钥只影响 `voice_stt`,三个 TTS 工具照常可用)。
68
+ ### 注册工具清单(共 5 个)
75
69
 
76
- - **音色不合法**:用 `voice_list` 挑清单内 id(形如 `zh-CN-XiaoxiaoNeural`),或改配置 `ttsVoice` 后重启。
77
- - **TTS 报网络错误**:Edge 朗读是第三方在线服务,需要能访问外网;公司网络或代理下配置 `proxyUrl`(例如 `http://127.0.0.1:7890`)。
78
- - **STT 报缺密钥/接口地址**:设环境变量 `DSH_VOICE_ASR_KEY`(推荐,不落配置文件)或配置 `asrApiKey`;`asrEngine: custom` 时必须给 `asrBaseUrl`。
79
- - **STT 报音频不存在或越界**:`audio` 与本插件的所有输出都必须落在当前会话工作区内,工作区外的录音先复制进来。
80
- - **转写被拒(3xx)**:接口返回重定向时插件会停止,不向跳转地址发送音频;请把 `asrBaseUrl` 设为可信的最终接口地址。
81
- - **同名输出没被覆盖**:`overwrite: false`(默认)下自动加序号,请以工具返回的 `output` / `transcriptFile` 为准。
82
- - **超时**:`timeoutMs` 默认 60000,最小 5000、最大 600000;大文件或慢服务调大它。
70
+ | 工具 | 作用 | 关键参数与说明 |
71
+ | :--- | :--- | :--- |
72
+ | `voice_tts` | 文字合成 MP3(零密钥 Edge 在线神经语音) | `text` 必填(≤5000 字符);`voice` / `rate` / `pitch` / `output` 可选 |
73
+ | `voice_stt` | 音频转文字(Groq / OpenAI / 自定义兼容端点) | `audio` 必填(≤25MB);`model` / `language` / `prompt` / `output` 可选 |
74
+ | `voice_list` | 查看内置常用多语种与方言音色目录 | 无参数 |
75
+ | `voice_preview` | 有界并发(最多 3 路)批量生成短试听 MP3 | `voices`(最多 8 个)/ `text`(≤200 字)/ `outputDir` 可选 |
76
+ | `voice_health` | 本地配置自检(不触网) | 逐项检查默认音色、代理、ASR 引擎/地址/密钥与影响面 |
83
77
 
84
- ## 开发
78
+ ### 安全与文件保护细节
79
+
80
+ - **工作区沙箱与符号链接防护**:所有读写路径解析后必须位于 `session.header.cwd` 内;拒绝跟随符号链接覆写,新建文件使用 `O_EXCL` 防止并发竞态覆盖,转写 `.txt` 在类 Unix 系统以 `0600` 权限写入。
81
+ - **防凭据串台与防重定向泄露**:ASR 请求固定发往配置的 `asrBaseUrl`,拒绝模型调用时用 `engine` 临时切到其他厂商,且遇 `3xx` 重定向立即中止上传。
82
+ - **随时可取消**:`voice_tts`、`voice_preview` 与 `voice_stt` 全程透传 `exec.signal`,用户点击停止即刻关闭 WebSocket 或中止上传。
83
+
84
+ ## 安装、卸载与开发
85
85
 
86
86
  ```bash
87
+ # 安装(桌面版把 web 换为 desktop)
88
+ dsh plugin --profile web add dsh-voice
89
+
90
+ # 卸载
91
+ dsh plugin --profile web remove dsh-voice
92
+
93
+ # 本地构建与离线单元测试
87
94
  pnpm install
88
- pnpm test # 构建 + 离线单元测试(使用模拟的 TTS/ASR)
89
- pnpm test:integration # 显式联网,调用真实 edge-tts;网络或断言失败均报错
95
+ pnpm test
90
96
  ```
91
97
 
92
98
  ## License
93
99
 
94
- 主体 MIT;独立的 Edge v2 令牌模块 LGPLv3,见[第三方声明](../THIRD_PARTY_NOTICES.md)。
100
+ 主体代码采用 MIT;独立的 Edge v2 令牌计算模块遵循 LGPL-3.0-only,详见 [第三方声明](../THIRD_PARTY_NOTICES.md)。