前言¶
在 DeepSeek Harness（DSH）里跑 agent，常见入口是桌面或网页：打字或麦克风进会话，回复落在屏幕上。若你家里已有刷成 open-xiaoai 客户端的小爱音箱，更自然的交互是站在设备旁说唤醒词、听音箱念出结论，而不是每次走到电脑前。
社区插件 dsh-xiaoai-bridge（维护者 OMSociety，GitHub 仓库 OMSociety/dsh-xiaoai-bridge）把这条链路接进 DSH：本地桥接器负责唤醒、收音、识别与播放，插件负责会话、播报纪律和进程托管。下面介绍它是什么、能做什么，以及按官方 README 复现安装与试用的步骤。
这是什么¶
dsh-xiaoai-bridge 是 DSH 的客户端类插件（当前版本 1.0.0，MIT 许可证）。一句话定位：把小爱音箱接进 DeepSeek Harness——说唤醒词，识别出的文本作为用户消息进入 DSH 会话，会话回复经润色后从音箱播放；模型也可通过工具主动让音箱开口。
仓库分两半：根目录是 Node 写的 DSH 插件（lib/），负责设置页、状态卡、桥接器子进程托管、鉴权与随包预设；bridge/ 是 Python 桥接器，负责设备侧 TCP 音频、VAD、唤醒词、语音识别、合成与播放闸门。桥接器源码基于 coderzc/open-xiaoai-bridge，本仓库在其上接 DSH 后端并独立演进。
插件目录页：SkillHub — OMSociety/dsh-xiaoai-bridge。
核心功能¶
唤醒即对话¶
唤醒词在桥接器本地用 sherpa-onnx 识别；命中后收一句话，VAD 判断结束再 ASR，文本 POST 到插件路由 /plugin/xiaoai/asr（bearer 鉴权，fail closed）。插件把文本投进该音箱绑定的 DSH 会话（不存在则创建），回复正文会自动口语化润色后播放。支持一次唤醒一句，或开启「连续对话」直到静默超时或退出词。
播报纪律¶
何时出声、念什么由插件层规则决定，而非模型随意输出：
- 音箱发起的对话：默认念回复正文；若本轮已调用
xiaoai_speak，则不再念回复正文。 - 其他会话：默认不出声；可开启「任何会话都能让小爱说话」，让桌面/网页会话也能驱动音箱。
- 工具卡在审批时只播固定提示，审批正文不会被念出。
- 播放期间播放闸门关闭麦克风，避免半双工自问自答。
主动说话：xiaoai_speak¶
| 工具 | 用途 | 关键参数 |
|---|---|---|
xiaoai_speak |
让音箱念出一段文字 | text（必填），逐字念 |
同一轮只生效一次；text 勿含 Markdown、代码块或 URL。桥接器未运行时，在「随插件启动桥接器」开启时会尝试拉起并等待（最长约 12 秒）。
进程、状态与数据¶
- 插件拉起桥接器子进程，崩溃按滑动窗口重启，退出 DSH 时先停子进程。
- 设置页运行状态卡展示进程、API、令牌、预设及最近错误码；日志前缀
dsh-xiaoai-bridge:。 - 实际播报到音箱的句子追加在
spoken.jsonl，卸载时可保留记录。 - 随包 小爱模式 Agent 预设（
cordis.patch.yml），面向音箱会话：能跑命令、读写文件、查资料、记待办，无子代理与计划模式；设置页默认预设名为xiaoai。
端口与路由（便于排错）¶
| 端口/前缀 | 作用 |
|---|---|
4399 |
Rust 扩展 dsh_xiaoai_server 音频 TCP；音箱拨到此地址（默认可带 URL token） |
127.0.0.1:9092 |
桥接器 HTTP API（播报、健康检查） |
/plugin/xiaoai/* |
插件挂在宿主 webServer 上的路由（如 /plugin/xiaoai/asr、/plugin/xiaoai/bridge/start 等） |
安装与启用¶
前置条件¶
| 需要 | 版本 / 说明 |
|---|---|
| DSH | 0.2.0-rc.1 或更新 |
| Node | 20 或更新 |
| pnpm | 安装插件依赖 |
| Python | 3.12 |
| uv | 桥接器虚拟环境与依赖；首次会编译 Rust 扩展（约十几分钟） |
| Rust 工具链 | uv sync 通过 maturin 编译 PyO3 扩展 |
| 小爱音箱 | 已刷机并打 open-xiaoai 客户端补丁（见上游文档） |
步骤¶
1. 安装插件并重启 DSH
先停止正在运行的 DSH，再执行（<profile> 换成你的 profile）：
dsh plugin --profile <profile> add "dsh-xiaoai-bridge"
装完后必须重启 DSH。插件包内含 bridge/ 源码，但不含桥接器虚拟环境与语音模型包，需在本地补齐并在设置页把「桥接器目录」指到该路径。
2. 准备桥接器 Python 环境
进入插件自带的 bridge/ 目录（路径以你本机插件安装位置为准），执行：
uv sync --no-install-project
uv sync
.\.venv\Scripts\python.exe -c "import dsh_xiaoai_server; print('ok')"
Linux/macOS 上将最后一行改为对应虚拟环境中的 python。仅当修改 bridge/native/**/*.rs 后需重跑 uv sync；重跑前应先停桥接器。
3. 下载并放置模型包
约 470 MB，不随仓库分发，需手动解压到 bridge/core/models/：
| 项目 | 值 |
|---|---|
| 下载 | https://github.com/coderzc/open-xiaoai-bridge/releases/download/vad-kws-asr-models/models.zip |
| sha256 | 8E8A709D6EA011F644F3C5055F536D5E6EB363EEAFBA53CC3232398FD636D273 |
4. 音箱与设置页
设备侧属于 open-xiaoai 上游：刷机与客户端补丁见 flash.md 与 client-rust README。音箱上 /data/open-xiaoai/server.txt 应指向 ws://<运行桥接器的电脑局域网 IP>:4399?token=<访问令牌>（与设置页「音箱连接鉴权」一致；关鉴权则同网任意主机可注音，需自行权衡）。
在 DSH 插件设置页确认：启用插件、音箱名称、音箱 IP、会话工作区；按需选择「随插件启动桥接器」与「小爱模式」预设。保存部分配置会热重载桥接器配置文件；日志级别、API 监听、凭据等写在子进程环境变量中的项需重启桥接器后生效。
5. 验证
对着音箱说唤醒词再说话；若链路正常，DSH 会话会收到识别文本，回复会从音箱播出。
典型用法¶
语音问答（默认路径）¶
无需模型显式调工具：唤醒 → 说话 → 等待 VAD 结束 → 插件创建或复用音箱会话 → 回复正文自动润色并播放。
让 agent 主动播报¶
在需要逐字念出口令、验证码、任务完成或提醒时，在 agent 可用工具中调用：
xiaoai_speak(text="会议还有五分钟开始。")
若希望桌面会话也能驱动音箱，在设置页打开「任何会话都能让小爱说话」。
运维与诊断¶
- 设置页状态卡查看桥接器进程与最近错误码。
- 需要换环境变量类配置后，可通过设置页或 API 重启桥接器，例如
POST /plugin/xiaoai/bridge/restart。 - 桥接器未起、地址错、token 缺失时，常见表现是音箱无反应或桥接器日志 401；README「排错」节列出了诊断编码含义。
适用场景与注意¶
适合谁： 已在 DSH 0.2.0-rc.1+ 上跑 agent，且愿意按 open-xiaoai 流程维护音箱设备；希望用唤醒词把语音输入/输出并到同一套 Harness 会话与工作区的人。
权限与安全： 插件与桥接器随 当前 DSH 进程 运行，agent 在音箱会话里能做的事（读文件、跑命令等）受你为该会话配置的预设与 DSH 权限约束。安装前应阅读仓库源码、LICENSE（MIT）及 DISCLAIMER.md：项目非小米官方，刷机与补丁存在设备与账号风险；/asr 使用 bearer 门禁，无令牌返回 503，令牌错误返回 401。
生态说明： DSH 采用「一切皆插件」；SkillHub 为社区目录，与 DeepSeek / 幻方无官方从属关系，本文介绍的是社区维护的客户端插件，而非官方应用商店条目。
结尾¶
dsh-xiaoai-bridge 把 open-xiaoai 音箱的唤醒与播放接到 DSH 会话上，用插件管生命周期与播报规则，用本地桥接器管语音链路。若你要在现有 Harness 工作流里加一条「喊一声、听答案」的入口，可按上文步骤安装插件、补齐 bridge/ 环境与模型，再在设置页对齐音箱地址与鉴权。
- 目录页：https://www.skillhub.cn/plugins/OMSociety/dsh-xiaoai-bridge
- 源码与完整配置说明：https://github.com/OMSociety/dsh-xiaoai-bridge
