dsh-xiaoai-bridge

dsh plugin --profile web add dsh-xiaoai-bridge

<div align="center">

<img src="https://raw.githubusercontent.com/OMSociety/dsh-xiaoai-bridge/main/docs/logo.png" alt="DSH XiaoAI Bridge" width="160">

<h1>小爱音箱桥接器 DSH XiaoAI Bridge</h1>

<p>把小爱音箱接进 DeepSeek Harness：喊一声唤醒词，答案从音箱里念出来。</p>

<p>桥接器是本地 Python 服务（源码在 <code>bridge/</code>），由插件当子进程托管；设置页、状态卡、播报纪律都在插件这一半。</p>

<p>

<a href="https://www.npmjs.com/package/dsh-xiaoai-bridge"><img src="https://img.shields.io/npm/v/dsh-xiaoai-bridge?label=version&color=4f6ef7" alt="version"></a>

<a href="https://github.com/deepseek-ai/dsh"><img src="https://img.shields.io/badge/DSH-%3E%3D0.2.0--rc.1-4f6ef7" alt="DSH"></a>

<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-4f6ef7" alt="license"></a>

<a href="https://github.com/OMSociety/dsh-xiaoai-bridge/stargazers"><img src="https://img.shields.io/github/stars/OMSociety/dsh-xiaoai-bridge?color=4f6ef7" alt="stars"></a>

<a href="https://github.com/OMSociety/dsh-xiaoai-bridge/issues"><img src="https://img.shields.io/github/issues/OMSociety/dsh-xiaoai-bridge?color=4f6ef7" alt="issues"></a>

</p>

<p>

<a href="#这是什么">这是什么</a> •

<a href="#核心特性">核心特性</a> •

<a href="#功能概览">功能概览</a> •

<a href="#工作原理">工作原理</a> •

<a href="#安装方式">安装方式</a> •

<a href="#模型工具">模型工具</a> •

<a href="#配置项说明">配置项说明</a> •

<a href="#数据放在哪">数据放在哪</a> •

<a href="#排错">排错</a> •

<a href="#开发">开发</a> •

<a href="#许可证与作者">许可证与作者</a>

</p>

</div>

免责声明：本项目是非官方技术研究项目，与小米及其关联公司没有隶属、合作、授权或背书关系；按「现状」提供，不附带任何保证。刷机与客户端补丁存在设备损坏、数据丢失、账号封禁等未知风险，动手前请读 [DISCLAIMER.md](DISCLAIMER.md)。

这是什么

小爱音箱刷成 open-xiaoai 客户端之后，就能在设备上跑自己的语音程序。这个项目把它接进 DeepSeek Harness：

• 你说唤醒词，音箱开始收音；识别出来的文本被当成一句用户消息，送进 DSH 的一个会话。
• 会话的回复正文会被念回音箱（念之前先做一次口语化润色，让它听起来像在说话）。
• 模型也可以反过来主动开口：调 xiaoai_speak，让音箱念出指定的内容。

仓库分两半：根目录是 DSH 插件（Node，lib/），bridge/ 是 桥接器。桥接器负责设备那一侧（TCP 音频、VAD、唤醒词、语音识别、语音合成、播放闸门），插件负责 DSH 这一侧（设置页、运行状态卡、进程托管与看门狗、接口鉴权、随包技能与预设）。插件拉起桥接器进程、渲染它的配置、看住它；桥接器也能脱离插件单独跑。

bridge/ 的源码来自 coderzc/open-xiaoai-bridge（MIT，其上游是 Open-XiaoAI），本仓库在它之上加了 DSH 后端、播报纪律、鉴权与生命周期管理。本仓库独立演进，不跟进上游。

核心特性

特性 · 说明

唤醒即对话 · 说唤醒词后直接说话，识别文本交给 DSH 会话；回复正文自动念出来，模型不用显式调工具。

主动说话 · xiaoai_speak 工具让 agent 主动播报：提醒到点、任务完成，或者你在电脑上让它读一段原文。

半双工防自问自答 · 播报期间麦克风通路被播放闸门关掉，音箱不会听见自己。

播报留痕 · 每句真正念出去的话追加进 spoken.jsonl，随时可回看。

进程托管与看门狗 · 桥接器是插件拉起的子进程：崩溃按滑动窗口重启，起不来会留诊断；插件退出时先停它。

接口鉴权 · /asr 走 bearer 门禁且 fail closed：没有令牌回 503，bearer 对不上回 401，不看来源地址。

状态卡与诊断 · 设置页里有一张运行状态卡：进程、API Server、令牌、预设，以及最近的错误码。

卸载不留残渣 · 卸载时删掉可以重建的那一半（渲染配置、pid、缓存），保留你的播报记录。

小爱模式（可选） · 随仓库带一个音箱会话专用的 Agent 预设：会说话，能读写文件、查资料、跑命令、记待办，没有子代理与计划模式。

功能概览

唤醒即对话

唤醒词由桥接器在本地用 sherpa-onnx 识别，命中后开始收这句话，过 VAD 判断说完了，再做语音识别，最后把文本 POST 给插件的 /plugin/xiaoai/asr。插件把它投进这台音箱绑定的 DSH 会话（会话不存在就建一个），并把回复写回音箱。一次唤醒说一句，或者打开「连续对话」连着说，直到静默超时或说出退出词。

播报纪律

「什么时候出声、出声说什么」由插件里的一层纪律决定，不是模型想说什么就念什么：

• 音箱发起的对话：回复正文会自动送进回复器润色后念出来；模型如果已经用 xiaoai_speak 指定了要念的话，就不再念回复正文。
• 其他会话：默认不出声；打开「任何会话都能让小爱说话」后，桌面与网页会话也能让音箱开口。
• 工具卡在审批上时念一句固定的提示，审批请求的正文永远不会被念出来。
• 每次播放都走桥接器的播放闸门，播报期间麦克风通路是关的。

主动说话

xiaoai_speak 让 agent 不等人问就先开口：任务跑完了、提醒到点了、你要求把某段原文逐字念出来。桥接器没在跑时工具会顺手把它拉起来（「随插件启动桥接器」开着时），再等一会儿（最长约 12 秒）。音箱发起的会话里，工具与技能只注册在这台设备的会话作用域内；打开「任何会话都能让小爱说话」后注册回全局，桌面会话也能用。

进程托管与看门狗

插件负责桥接器的整个生命周期：启动前渲染配置、把设置项转成环境变量、把凭据从 DSH 凭据库解析进子进程环境；运行中收日志、探活、崩溃后按滑动窗口重启；DSH 退出或插件重载时先停子进程，再清掉可以重建的文件（bridge.log、spoken.jsonl 这些记录留着）。

状态卡与诊断

设置页的运行状态卡显示桥接器进程、API Server 是否可达、令牌是否配置、预设是否挂上，以及最近几条错误码（卡片最多显示 3 条，同一编码且详情相同才合并计数）。诊断行也会写进 DSH 日志，前缀是 dsh-xiaoai-bridge:，编码含义见[排错](#排错)。

小爱模式

插件自带的 bundle 里还有一个音箱会话专用的 Agent 预设（显示名「小爱模式」）：只有音箱会话用它，能跑命令、读写文件、查资料、记待办，没有子代理、工作流与计划模式——在音箱上这些只会拖慢第一句话。它随插件一起装好，设置页默认已经指向它；宿主读不到这个预设也不会报错，只回落宿主默认预设并留一条诊断。

桥接器 HTTP 接口

桥接器进程里有一个 HTTP API Server（默认 127.0.0.1:9092），插件用它做播报与健康检查，端点见 bridge/docs/openxiaoai-voice-api.md。插件自己的路由挂在宿主 webServer 上，前缀 /plugin/xiaoai：

方法 · 路径 · 用途

GET · /plugin/xiaoai/health · 插件概况（含令牌是否配置）

GET · /plugin/xiaoai/config · 读设置（供设置页用；保存时带 revision）

POST · /plugin/xiaoai/config · 写设置（ops 或 patch，二选一）

POST · /plugin/xiaoai/asr · 桥接器提交一句识别文本（bearer 门禁）

GET · /plugin/xiaoai/devices · 已绑定的音箱设备与它们的会话键

GET · /plugin/xiaoai/bridge/status · 桥接器进程状态与日志路径

GET · /plugin/xiaoai/bridge/health · 经插件访问桥接器的健康检查

GET · /plugin/xiaoai/bridge/logs · 最近日志（limit 1-400）

POST · /plugin/xiaoai/bridge/start · 启动桥接器

POST · /plugin/xiaoai/bridge/stop · 停止桥接器

POST · /plugin/xiaoai/bridge/restart · 重启桥接器（换了环境变量类的设置后用）

POST · /plugin/xiaoai/data/wipe · 清空数据目录（body 必须是 {"confirm":"wipe"}）

工作原理

flowchart LR
    Spk[小爱音箱] -- 唤醒词 --> Rust
    Rust["Rust 扩展 dsh_xiaoai_server（TCP 4399）"] --> App["bridge/core/app.py"]
    App -- 识别文本 --> Http["插件 lib/http.js（/plugin/xiaoai/asr）"]
    Http --> Session["DSH 会话"]
    Session -- 回复正文或 xiaoai_speak --> Http
    Http -- 播放请求 --> Api["桥接器 API Server（127.0.0.1:9092）"]
    Api --> Rust
    Rust -- 播放 --> Spk

三个端口要分清：4399 是 Rust 扩展固定的音频端口，音箱侧要拨到它（默认要带令牌，见下面的「音箱连接鉴权」）；9092 是桥接器的 API Server；插件自己的路由挂在宿主 webServer 上，不额外占端口。

安装方式

前置条件

需要 · 版本 / 说明

DSH · 0.2.0-rc.2 至 0.3.0 之前（含各补丁线的预发布形态）

Node · 20 或更新

pnpm · 装插件依赖用（只有一个运行依赖 @deepseek-ai/schemastery）

Python · 3.12

uv · 建桥接器虚拟环境、装依赖、编译 Rust 扩展

Rust 工具链 · uv sync 会用 maturin 现场编译 PyO3 扩展，第一次要十几分钟

小爱音箱 · 已刷机并打过 open-xiaoai 客户端补丁（这一步在上游，见下）

步骤

1. 把仓库取回来：

git clone https://github.com/OMSociety/dsh-xiaoai-bridge.git
Set-Location dsh-xiaoai-bridge

2. 准备桥接器的 Python 侧（在仓库的 bridge/ 下）：

Set-Location bridge
uv sync --no-install-project
uv sync
.\.venv\Scripts\pyth

…(truncated)