zq0951/dsh-voice-gateway

description: "DSH Web 客户端的语音网关客户端界面插件：麦克风状态指示器、六态状态机（空闲、监听、思考、生成、播报、断开连接）、声纹注册以及自动播报控制。"
kind: "package-reference"

@xp1024/dsh-voice-gateway

DeepSeek Harness (DSH) 物理语音交互网关客户端插件 (Client Surface Plugin)。

为 DSH Web 客户端提供物理麦克风状态指示器、声纹识别与注册管理、对话自动语音朗读（Auto-speak）等全双工语音交互控制能力。

Note: 本项目为第三方独立开源插件，非 DeepSeek 官方附属产品。
需配合物理语音网关守护进程 Local Voice Gateway 一起使用。

快速上手 (Quick Start)

1. 前置条件：启动语音网关守护进程
本插件作为客户端 UI 表面，需与运行中的语音网关（默认端口 8765）通过 WebSocket / REST API 通信：

克隆并启动本地语音网关
git clone https://github.com/zq0951/local-voice-gateway.git
cd local-voice-gateway
./start.sh
网关默认监听 http://127.0.0.1:8765 与 ws://127.0.0.1:8765/v1/events

2. 在 DSH 中安装本插件
在已配置好的 DSH Profile（如 web）中安装并激活本插件：

dsh plugin --profile web add @xp1024/dsh-voice-gateway

或者在本地开发测试时，直接指向本地路径安装：
dsh plugin --profile web add /path/to/dsh-voice-gateway

3. 启动 DSH Web 界面
dsh web --no-open --port 3080
启动后在浏览器打开 DSH，对话输入栏右侧将渲染麦克风控制按钮。

功能特性 (Features)

- 六态实时状态指示器 (Six-State Machine Indicator)：
- idle：空闲就绪，麦克风处于待命状态。
- listening：正在被动侦听有效声纹或等待唤醒。
- thinking：智能体（Agent）正在思考与生成回复。
- generating：大模型回复中，正在合成语音流。
- speaking：扬声器正在播报回复音频。
- disconnected：未连接到语音网关守护进程。
- 声纹过滤与多发言人管理 (Voiceprint Enrollment & Filtering)：
- 内置向导式声纹录制弹窗，引导用户录制固定发音语料并注册声纹特征。
- 支持多用户声纹列表管理，主动过滤未授权发言人语音，杜绝环境杂音或旁人误唤醒。
- 双向语音交互 (Bi-directional Voice Turn-Taking)：
- 语音识别结果格式化为带有发言人标记的提示词 [] ，无缝注入当前活动会话。
- 支持 auto_speak 自动播报开关，监听到智能体回复时自动调用网关硬件扬声器进行 TTS 朗读。
- 动态网关地址配置 (Custom Gateway Endpoint)：
- 支持在 UI 设置面板中灵活修改语音网关地址（默认为 http://${window.location.hostname}:8765）。

Table of Contents

- Use this package
- Understand the implementation
- Compatible Gateway Specification
- License

Use this package

语音控制按钮挂载到对话输入栏中：
- 六态指示器：反映 idle、listening、thinking、generating、speaking 和 disconnected 网关状态。
- 触发模式切换：在被动声纹识别、仅唤醒词和混合模式之间切换。
- 自动播报开关：启用或禁用助手回复的自动文本转语音。
- 声纹注册：打开引导式向导以录制说话人样本并管理已保存的配置文件。
- 网关地址配置：动态自定义并更新本地语音网关端点。

Understand the implementation

Implementation internals — click to expand

Reactive Hooks Compartment
浏览器端将 VoiceControl 组件注册到 conversation.input.right。遵循 DSH 客户端纪律规则，该组件不包含任何外部订阅机制；响应式状态通过保留的 hooks 隔间传递，并由渲染器绑定到 useVoice。

会话事件观察

VoiceManager 服务通过 ctx.sessions 观察活动会话更新。助手完成情况是通过会话 eventSource 上的权威 assistant/message 事件检测的，而非抓取呈现视图。

兼容网关规范

客户端插件通过标准 HTTP REST 和 WebSocket 协议与语音网关守护进程（Local Voice Gateway）通信：

1. 端点发现与寻址：
- 默认：自动绑定到 http://${window.location.hostname}:8765 和 ws://${window.location.hostname}:8765/v1/events。
- 自定义：可通过设置弹出界面或 localStorage.setItem('dsh.voice.gateway_url', 'http://:') 进行配置。

2. 单一事实来源（SSOT）：
- 网关守护进程拥有 trigger_mode、auto_speak、audio_duplex_mode 和 registered_speakers 的权威状态。
- 插件在连接时通过 GET /v1/system/status 初始化状态，并订阅 /v1/events 以实现实时同步，防止本地状态漂移。

3. 必需的后端接口契约：
- GET /v1/system/status — 返回网关健康状况、模式和说话人名单。
- POST /v1/system/mode — 切换活动触发模式（wake_word、voiceprint_passive、hybrid）。
- POST /v1/system/autospeak — 切换自动语音响应播报。
- POST /v1/audio/speak 和 POST /v1/audio/stop — 硬件语音输出和即时中断。
- GET /v1/voiceprint/profiles 和 DELETE /v1/voiceprint/:name — 说话人配置文件管理。
- POST /v1/voiceprint/enroll/* — 分步引导式声纹样本采集。
- WS /v1/events — 实时事件广播（speech_recognized、wake_word_detected、playback_started、playback_stopped、tts_generating、mode_changed 等）。

许可证

MIT 许可证 © 2026 xp1024 (zq0951)