前言¶

對經常使用 dsh web 的開發者來說，agent 任務完成後的反饋有時只落在日誌、終端或瀏覽器狀態裏。dsh-niulai-pet 是一個 dsh web 客戶端桌寵插件：在界面角落養一頭《牛來》小牛，agent 任務完成時它會蹦出來並喊「媽~~媽~~」。它不是替代狀態提示，而是把任務完成、運行計時和互動反饋放進一個網頁角落的輕量對象裏。

DSH 強調「一切皆插件」，社區目錄是獨立站點，不等同於官方應用商店。下面介紹這個插件能做什麼、怎麼安裝、哪些場景適合使用。

這是什麼¶

dsh-niulai-pet 是 dsh web 客戶端桌寵插件，桌寵本體在瀏覽器端運行。npm 包名爲 dsh-niulai-pet，已覈實版本爲 0.4.9，主入口爲 index.js，許可證爲 MIT。倉庫地址爲 https://github.com/whitefirer/dsh-niulai-pet。

它主要解決三件事：

1、agent 任務完成時有聲音、氣泡和動作提示。

2、提供一個可配置、可多隻、可自定義皮膚的桌寵交互層。

3、在 dsh rc.7+ 裏通過設置卡片持久化配置。

核心功能¶

任務完成反饋¶

當 agent 任務完成時，桌寵可觸發：

• 喊聲；
• 氣泡；
• 嘴型動畫；
• 綁定動作。

這裏支持連喊、延遲和互動停止。循環喊的停止條件包括戳它、拎它、新任務開跑、靜音或關掉開關，另有 60 聲兜底自停。

日常行爲與交互¶

插件支持：

• 待機動效；
• AI 會話運行計時氣泡；
• 點擊喊聲；
• 拖拽位置記憶；
• 多隻桌寵；
• 物理碰撞。

多隻桌寵可在主寵菜單「再添一隻」，數量上限可配置，默認連主 10 只。拖拽位置按設備保存在 localStorage，不進入設置。

皮膚與動作¶

內置 9 個皮膚：牛來、牛來原皮、小黃、熊貓、藍鯨、奶龍、小奶龍、大狗、賽博貓。

動作庫包括：飛行、搖擺舞、轉圈、連跳、翻滾、躍出水面、搖擺。任意皮膚可綁定任意動作。

素材方面，已覈實資料說明：熊貓/藍鯨爲手繪原創，大狗立繪來自 Dagou-Tap-New。

自定義角色包¶

支持自定義角色包導入，一個 zip 包含 pack.json、透明底圖和 mp3。可在設置卡片「自定義角色」區導入；試玩頁也支持直接拖入 .nlpack.zip 即時預覽。

語音停喊¶

語音停喊用於循環喊場景，提供雙引擎：

• 模型識別：sherpa-onnx 中文 KWS wasm；
• 模板匹配：MFCC + DTW。

可選指令詞包括：牛來、別喊了、安靜、停下。

模型識別資產約 17MB 隨 npm 包分發，首次啓用加載一次；加載失敗會自動回落模板匹配。模型識別 worker 在循環停止後空閒 10 秒即終止，下次啓用秒級重建。

模板匹配對他人嗓音有固有上限，建議在設置中錄自己的「牛來」作爲優先模板。模板匹配需連續 3 次過閾才判命中，閾值 0.54，正樣本最高約 0.43，負樣本最低約 0.66。

配置與持久化¶

dsh rc.7+ 提供設置卡片，可配置聲音、完成時喊、皮膚、動作、數量上限、大小、語錄、物理碰撞、閒置打盹等。

dsh rc.7+ 的配置由 dsh host 持久化到 ~/.dsh/settings.yaml。rc.6 及更早版本沒有設置卡片，插件照常工作，配置回落到 localStorage。

右鍵菜單也可以調整聲音、完成時喊、氣泡、閒置打盹、物理碰撞、隱藏全部、皮膚、動作和全家福。

安裝與啓用¶

先確認 dsh web 環境可用。從 npm 安裝：

dsh plugin --profile web add dsh-niulai-pet

也可以從 GitHub 安裝：

dsh plugin --profile web add github:whitefirer/dsh-niulai-pet

首次安裝需要重啓一次 dsh web；之後升級刷新頁面即可。

如果不打算立即安裝，可以先訪問在線試玩頁：

https://whitefirer.org/niulai-pet/

典型用法¶

下面按常見路徑給出可復現步驟。

1、安裝插件並重啓 dsh web：

dsh plugin --profile web add dsh-niulai-pet

2、右鍵桌寵打開菜單，調整聲音、完成時喊、氣泡、閒置打盹、物理碰撞、隱藏全部、皮膚、動作和全家福。

3、想養多隻桌寵時，在主寵菜單「再添一隻」。數量上限可配置，默認連主 10 只。

4、導入自定義角色：在設置卡片「自定義角色」區導入 zip，zip 內應包含 pack.json、透明底圖和 mp3。也可以在試玩頁拖入 .nlpack.zip 即時預覽。

5、體驗循環喊和語音停喊：在 demo 試玩頁控制檯預設：

localStorage['dsh-niulai-pet:state-v1'] = '{"shoutLoop":true}'

刷新頁面後，可在循環喊進行期間對着麥克風喊「牛來」，或設置中勾選的指令詞（別喊了/安靜/停下）。

6、調試時，在頁面 URL 加 ?petdebug=1，會在 window.__niulai 暴露 celebrate、poke、setBusy、destroy 句柄。

7、替換素材：覆蓋 assets/ 裏的文件後執行：

npm run build

刷新頁面生效。

8、本地開發可執行：

npm install
npm run build
npm run typecheck

適用場景與注意¶

這個插件適合：

• 想在 dsh web 里加一個任務完成視覺/聲音提示的開發者；
• 想試皮膚、動作、氣泡和自定義角色包的 dsh 插件用戶；
• 需要免安裝先體驗桌寵交互的人。

使用前注意：

• dsh rc.7+ 纔有設置卡片；舊版沒有設置卡片，但插件仍可工作，配置留在 localStorage。
• 宿主太舊沒有 sessions 服務時，任務完成信號會降級爲僅手動交互。
• 語音功能依賴 getUserMedia，僅在 https 或 localhost 等安全上下文可用；局域網 http://192.168.x.x 訪問時麥克風 API 不可用，開關會禁用。
• 打開語音開關時瀏覽器會真實試取麥克風；授權被拒則開關彈回關閉並提示。
• 模板匹配對他人嗓音有固有上限，本人嗓音建議優先錄模板。
• 插件以當前 dsh 進程權限運行，安裝前應檢查源碼與許可證。本插件許可證爲 MIT。

結尾¶

dsh-niulai-pet 把 dsh 的任務完成事件變成一個可看見、可互動、可配置的桌面小對象。它不改變 agent 本身，只在 dsh web 客戶端側補充一層反饋。

倉庫地址：

https://github.com/whitefirer/dsh-niulai-pet