DOCUMENTATION

5 分钟跑通本地语音 Agent

第一目标平台：MacBook Pro M1 Pro。公开 npm 安装已开放，使用已发布的 Muxiva 0.1.1 Python wheel；兼容 DSH rc.5 / rc.6。

零侵入保证本仓库不修改 DSH agent-loop，也不修改 Muxiva Runtime。所有能力都通过 DSH Bundle、公开 Session face 和 Muxiva 项目 Node Pack 扩展。

1. 安装

确认官方 DSH 与 Muxiva CLI 已安装，然后执行：

dsh plugin --profile web add @muxiva/dsh-voice@alpha
npx @muxiva/dsh-voice@alpha setup

setup 创建隔离 Python 环境，不会改系统 Python。约 2.5 GB 模型固定 revision 并执行 SHA-256 校验；环境与模型位于稳定用户数据目录，不会随 npx 缓存清理。用 npx @muxiva/dsh-voice@alpha home 查看路径。

2. 运行

TERMINAL A · PRODUCTnpx @muxiva/dsh-voice@alpha start

TERMINAL Bdsh --profile web

默认使用低开销 Headless Runtime。排障或调优时运行 npx @muxiva/dsh-voice@alpha start --observe，在自动打开的 Muxiva Studio 中点击 Run，再打开 ◎ Observe 查看 Node 延迟/吞吐、Edge 速率/队列年龄、内部缓冲、Trace 和热点判断。两种模式都把桥、Runtime 与 Node Host 输出持久化到稳定数据目录的 runtime.log。

源码贡献者在模型安装完成后可运行 npm run test:e2e，在不调用云模型和麦克风的情况下认证真实 TTS → PCM → VAD/ASR 闭环。

3. 使用

打开 DSH 打印的 Web 地址。
新建或打开一个 Session。
点击输入框上方的大型语音 Orb。
允许浏览器麦克风权限，然后直接说话。
再次点击大 Orb 会停止发送 PCM，并把 Muxiva Audio Source 切到 paused；Web Audio、WebSocket 和 Graph 保持常驻。恢复时 Source 先重置 VAD/ASR，再接收新的 utterance。右侧小“结束”按钮才关闭链路。
Agent 播放回答时继续说话，ASR 出字后验证可靠打断。

架构

Browser Mic
16 kHz PCM

→

Silero VAD
barge-in

→

Zipformer
preview

→

SenseVoice
zh/en final

→

DSH Agent
session / tools

→

Normalizer + TTS
24 kHz PCM

低延迟 Zipformer Partial 只用于 UI 预览；连续静音 2 秒后，SenseVoice 才自动检测中英文并生成唯一提交给 Agent 的 Final，因此自然的短暂停顿不会提前切句。默认 VAD 阈值为 0.75、最短语音为 350 ms；Final 还会拒绝非语音事件、日文/韩文分类和单字符幻觉。Agent 文本采用两阶段上下文：一个 48–96 字的自然段尽早开口，剩余增量到 Final 后合并为一次生成，长回答最多两次 Qwen 调用。Muxiva formatter 与独立 normalizer Node 会清除 Markdown、emoji、网页地址、邮箱、横线和装饰符号，再用统一的温柔平静语速、音区和情绪配置进入本机 MLX Qwen3-TTS。

打断语义

Silero 检测到新语音时只产生候选并把 UI 切到“识别”，不会取消任何内容。Zipformer 出现非空 Partial，或多语 Final 首次出字时，Muxiva 才发出 muxiva.voice.barge_in.confirmed Signal，取消 TTS、清空播放并让浏览器调用 DSH session.cancel()。没有识别出文字的噪声段会发出 asr.rejected 并回到聆听。Generation fence 会丢弃已经在后台返回的旧 PCM。

默认模型

层	默认选择	原因
VAD	Silero ONNX	成熟、轻量、MIT
ASR Preview	Zipformer2 CTC zh small	真流式、低延迟、Apache-2.0
ASR Final	SenseVoiceSmall int8	中英自动检测、ITN、Apple Silicon CPU
Text	speech_text_normalizer	Markdown / emoji / 中文数字口语化
TTS	Qwen3-TTS 0.6B / Serena	温暖轻柔的普通话年轻女声、MLX 原生、24 kHz 流式、可取消

性能数据

alpha.2 在 16 GB MacBook Pro M1 Pro、Muxiva 0.1.1 与 DSH rc.6 上完成 130/130 回合、30/30 次打断、5 分钟 idle 和 30 分钟 soak：零失败、零 TTS underrun、零过期打断音频。可靠性策略的 p95 为 Capture 14.9 ms、ASR 出字确认打断 1157.0 ms、语音结束到 Final 2181.2 ms（包含配置的 2 秒静音）、完整上下文 TTS 首 PCM 1175.3 ms。每个版本都提交完整 p50/p95/p99、实时系数、CPU、峰值内存、CER/WER 与稳定性 JSON，否则 Release 会失败。查看完整性能报告与测量边界。

Doctor

npx @muxiva/dsh-voice@alpha doctor

检查 Apple Silicon、Node、Muxiva CLI、隔离 Python 导入和每个模型校验和。任何一行失败都不会启动 Graph。

安全

桥只绑定 127.0.0.1，拒绝第二个浏览器客户端。
内部 Node Host 平面使用每次启动生成的 256-bit token。
npm 安装不执行 prepare/postinstall。
音频不上传，无云端 fallback。
模型不打进 npm 包，按锁文件单独下载。
稳定版前会为浏览器平面补充不落盘的 bearer challenge。

发布到哪里

DSH 当前没有集中式插件市场。正式发布采用 npm 包 @muxiva/dsh-voice，GitHub 仓库添加 dsh-plugin Topic，并提供 GitHub Pages Showcase。每个版本精确声明兼容的 DSH RC 与 Muxiva Release。