前言¶
DeepSeek Harness (DSH) 的插件生态允许在浏览器端扩展交互能力。在开发智能体或工具时，Agent 处于后台运行状态，或者用户不在当前页面时，视觉反馈往往会被忽略。dsh-sonic 插件通过浏览器实时合成音效，填补了听觉反馈的空白，用于在 Agent 需要用户确认（如审批请求、等待作答）或任务完成（Agent 状态变为 idle）时播放提示音。
插件概述¶
dsh-sonic 是一个由 xjwwjx 维护的客户端插件。它利用 Web Audio API 实时合成 8 种音效，无需加载任何外部音频文件。插件旨在提供清晰、即时的听觉反馈，帮助用户感知 Agent 的状态变化。
核心功能¶
音效触发¶
- 确认音：在审批请求（沙箱提权、插件运行授权）、
ask_user_question等待用户作答时触发。 - 完成音：当 Agent 状态由
running转为idle时触发。
8 种实时合成音效¶
所有音效均由浏览器端实时合成，支持以下类型：
- ding：单音清脆
- dingdong：门铃双音
- pop：轻快气泡
- chime：柔和三连音
- success：上扬琶音
- beep：电子短哔
- alarm：提醒双音
- marimba：木琴敲击
设置面板¶
在 DeepSeek Harness Web 的设置 → 通用中，可配置以下选项：
- 一键静音
- 音量滑块
- 分别挑选确认音与完成音
- 点击即试听
- 自动保存配置并同步给模型
模型工具¶
插件向模型提供了两个工具：
- sonic_play：立即播放指定的音效（用于测试或演示）。
- sonic_status：读取当前面板的选择状态。
安装与启用¶
dsh-sonic 以 bundle 插件的形式安装，类似于 @liustack/modlens，随 Web profile 自动加载。
- 将本包链接进 profile。编辑
~/.dsh/profiles/web/package.json：
- 在dependencies中添加："dsh-sonic": "file:<本包路径>"
- 在dsh.profile.bundles列表中添加："dsh-sonic" - 在 profile 目录执行安装命令：
pnpm install - 重启 DeepSeek Harness Web —— 插件随组合自动加载，进程重启后依然生效。
工作原理¶
插件采用 Host 与 Browser 分离的架构：
- Host 端：监听
approval/request、ask_user_question、agent/status等事件，将通知放入队列。提供POST /sonic/state接口接收设置，以及GET /sonic/drain接口供浏览器拉取待播放的音效队列。 - Browser 端：每 1 秒轮询
/sonic/drain，根据返回的数据播放对应的音效。同时维护设置面板，通过settings.general.item接收用户配置。
自定义音效¶
音效的配置位于 dsh/client.js 的 PRESETS 常量中。每个音效是一组音符参数，支持频率（freq/endFreq）、时长（at/dur）、波形（type）和音量（gain/attack）。
若需新增音效，在 PRESETS 中添加条目，并在 Host 端 sonic_play 工具的枚举中补充对应的 key 即可。
注意事项¶
- 安装方式：本文介绍的是静态 bundle 插件的安装方式。动态版（会话内
cordis_define加载）源码位于examples/dynamic-host.js与examples/dynamic-client.js，仅作参考，且进程重启后会丢失。 - 权限与路径：静态版安装需配置 profile 的
package.json和dsh.profile.bundles，请确保本地文件路径配置正确。
