---

用途 / 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）。Absolute path to an audio file; empty = built-in default sound.
volume	number	1	音量 0..1。仅非 wav 文件生效。Volume 0..1 (non-wav only).
onlyTopLevel	boolean	false	true 时只对顶层 agent 完成提示。Notify only for top-level agents.
cooldownMs	number	2000	防抖窗口（毫秒）。Debounce window (ms), per event type.
notifyApproval	boolean	true	审批等待时提示；策略为 never 时自动不响。Notify on approval requests.
preview	number	0	内部试听触发计数（UI 隐藏）。Internal preview counter (hidden).

---

工作原理 / How it works

事件监听 / Events

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

播放方式 / Playback

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

---

包结构 / Package layout

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

测试 / Tests

node "tests/trigger.test.mjs"

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

卸载 / Uninstall

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

License

MIT © Zyy1997