前言¶

对经常使用 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