前言¶
在 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
