提示音通知 Zyy1997/dsh-sound-notify

dsh-sound-notify

DeepSeek Harness (dsh) 插件：agent 任务完成 / 等待审批时播放提示音

A dsh plugin that plays a sound on the host when an agent finishes its turn or waits for approval.

用途 / What it does

当 agent 完成任务（状态从 running 变为 idle），或开始等待审批（session 记录 approval/asked）时，在 宿主端 播放提示音——即使浏览器切到后台也能听到，让你不用一直盯着 GUI。

Plays a sound on the host machine when an agent finishes its turn (running → idle) or starts waiting for your approval (approval/asked) — audible even when the browser is in the background.

特性 / Features

- 任务完成提示 — agent 每轮回复完成响一次
- 审批等待提示 — agent 发起审批请求时响一次，提醒你去 GUI 处理（策略为 never 时自动不响）
- 可配置卡片 — 设置 → 插件 → 插件配置 → "提示音"卡片（与官方 bash / agent-loop / web-search 卡片同级）
- 自定义音源 — 任意 wav / mp3 / ogg 文件；留空使用内置默认音效（assets/default-notify.mp3，直接替换该文件即可换默认音）
- 防抖 — 任务完成与审批等待各自独立防抖窗口，并行事件不轰炸
- 可过滤 — 可选只对顶层 agent 提示（子 agent 不响）
- 安全 — 播放失败只记日志，绝不阻塞或干扰 agent 循环
- 轻依赖 — 宿主端仅依赖 schemastery；client bundle 手写零构建工具链

安装 / Installation

环境要求 / Requirements

- DeepSeek Harness（dsh）0.1.0-rc.6 或更新版本
- Windows / macOS / Linux（Windows 体验最佳）
- pnpm（用于安装 link 依赖）

1. 克隆仓库 / Clone the repo

git clone https://github.com/Zyy1997/dsh-sound-notify.git

2. 在 profile 的 package.json 中添加 link 依赖 / Add a link dependency to your profile

编辑 %DSH_HOME%\profiles\web\package.json（或你的 profile 目录）：

{
"dependencies": {
"@dsh-external/dsh-sound-notify": "link:<克隆到的绝对路径>" } }

3. 在 profile 的 cordis.patch.yml 中激活 / Activate in the profile patch

- insert:
- id: sound-notify
name: '@dsh-external/dsh-sound-notify'
config:
sound: '' # 自定义音频绝对路径；留空用内置默认音效 volume: 1 # 0..1，仅 MediaPlayer 路径（非 wav）生效 onlyTopLevel: false # true 时仅顶层 agent 完成提示 cooldownMs: 2000 # 防抖窗口（毫秒） notifyApproval: true # agent 等待审批时也提示

4. 安装依赖并重启 / Install and restart

cd %DSH_HOME%\profiles\web
pnpm install
重启 dsh web

5. 应用 apiproxy 补丁（一次性）/ Apply the apiproxy patch (once)

⚠️ 为什么需要补丁？ dsh 的 dsh-host-apiproxy 用硬编码白名单 WEB_SETTINGS_NAMESPACES 决定哪些 settings namespace 暴露给 Web 客户端（官方注释：插件自暴露是 deferred work）。不在白名单的 namespace 在设置页不可见、写入被拒。dsh 升级/重装后需重新执行本补丁。

powershell -ExecutionPolicy Bypass -File "<克隆到的绝对路径>\patch-dsh-apiproxy.ps1"

- 幂等：已打补丁时自动跳过，可重复执行
- 补丁前自动备份原始文件为 lib/index.js.bak-soundnotify

6. 完成 / Done

打开 设置 → 插件 → 插件配置，找到"提示音"卡片，展开即可配置：

- 启用开关
- 音源文件路径（保存后自动试听，另有"试听"按钮）
- 审批提示开关、仅顶层 agent 开关
- 音量、防抖窗口

也可直接编辑 %DSH_HOME%\settings.yaml：

sound-notify:
enabled: true
sound: 'C:\path\to\your\sound.wav'
volume: 1
onlyTopLevel: false
cooldownMs: 2000
notifyApproval: true

配置项 / Configuration

| 字段 Field | 类型 Type | 默认 Default | 说明 Description |
| enabled | boolean | true | 总开关；false 时任务完成与审批都不提示。Master switch. |
| sound | string | "" | 音频文件绝对路径（wav/mp3/ogg…）。留空使用内置默认音效（assets/default-notify.mp3）。 |
| volume | number | 1 | 音量 0..1。仅非 wav 文件生效。 |
| onlyTopLevel | boolean | false | true 时只对顶层智能体完成提示。 |
| cooldownMs | number | 2000 | 防抖窗口（毫秒），按事件类型分别计算。 |
| notifyApproval | boolean | true | 审批等待时提示；策略为 never 时自动不响。 |
| preview | number | 0 | 内部试听触发计数（UI 隐藏）。 |

工作原理

事件监听

1. agent/status（任务完成）：running → idle 转变 = 任务跑完 = 播放声音
2. session/event（审批等待）：approval/asked 事件且会话策略非 never 时播放
3. settings watch（试听）：sound 变化或 preview 计数变化时播放一次

播放方式

| 平台 | 方式 |
| Windows | SystemSounds；wav 用 SoundPlayer.PlaySync；其他格式用 WPF MediaPlayer 轮询播放 |
| macOS | afplay |
| Linux | paplay（缺失时仅记日志） |

包结构

dsh-sound-notify/
├── lib/
│ ├── index.js # 宿主端插件：settings 注册 + 事件监听 + 播放 │ └── client.js # Web client bundle：插件配置卡片（手写，无构建工具链） ├── assets/ │ └── default-notify.mp3 # 内置默认音效（替换此文件换默认音） ├── patch-dsh-apiproxy.ps1 # dsh apiproxy 白名单补丁脚本 ├── tests/ # node:test 单元测试 + 端到端冒烟脚本 ├── package.json └── README.md

测试

node "tests/trigger.test.mjs"

（node:test 在当前进程内运行；受限沙箱下 node --test 可能报 EPERM，请直接运行文件。）

卸载

- 删除 cordis.patch.yml 中对应的 - insert: 条目
- 从 profile package.json 删除 link 依赖
- 重启 dsh

License

MIT © Zyy1997