任务提示音 Abel-86/task-chime

task-chime — DSH 任务提示音 / DSH Task Chime

为 DeepSeek Harness 设计的轻量提示音插件：审批/权限请求与任务完成时播放本地声音，全部可在 Web GUI 设置中自定义。A lightweight chime plugin for DeepSeek Harness: plays local sounds on approval / permission requests and task completion, fully configurable from the Web GUI.

功能 / Features

- 🔔 权限确认提示音 — 每当 harness 发起审批/权限请求（如沙箱升级、受限文件操作）时播放，即使忙于其他窗口也能立刻注意到。
- ✅ 任务完成提示音 — 一次完整的 agent 回答（回合）结束时播放。
- 🎚️ GUI 设置卡片 — 设置 → 插件 → 插件配置 → "DSH 任务提示音"：权限确认与任务完成两个板块，各自可更换声音文件、调节音量（0–100）、启用/禁用，另有公共冷却间隔。
- 💾 设置持久化 — 写入 $DSH_HOME/settings.yaml，改动即时生效，重启保留。
- 🖥️ 进程内播放 — 直接在当前进程调用 Windows 原生 MCI 接口（winmm.dll mciSendStringW），不派生任何子进程、不开窗口；mp3 / wav 均支持。
- 🎨 跟随主题 — 卡片 UI 使用 --dsw-alias-* 主题变量，浅色/深色自动适配。

安装 / Install

从 npm / GitHub 安装（已发布时）
dsh plugin --profile web add task-chime

或从本地检出安装（离线可用，改完源码重跑一次即可同步）
dsh plugin --profile web add file:D:/path/to/task-chime

然后重启 dsh web 并强制刷新浏览器页面（Ctrl+Shift+R）。

注意：该插件为 bare-package 模块，被 Node ESM 缓存，修改代码后必须重启 dsh 才生效。

另一个坑：file: 安装是硬链接副本，而且只跑 add 不够——pnpm 看到 spec 没变会直接回 "Already up to date" 而不重新取源码。改完源码必须 remove 再 add：

dsh plugin --profile web remove task-chime
dsh plugin --profile web add file:D:/path/to/task-chime

想让源码改动直接可见（省掉重装），可以改用 link: 代替 file:——代价是 profile 会依赖检出目录的位置。

配置 / Configuration

重启后打开 设置 → 插件 → 插件配置 → DSH 任务提示音：

| 板块 | 字段 | 说明 |
| 权限确认 | 启用 / 声音文件 / 音量 | 审批请求时播放；默认未配置声音（在 GUI 中设置后生效） |
| 任务完成 | 启用 / 声音文件 / 音量 | 回合结束时播放；默认 Windows 系统提示音 wav |
| 通用 | 冷却间隔（毫秒） | 两次提示音之间的最小间隔，防止连发 |

也可以直接编辑 $DSH_HOME/settings.yaml（每个插件占一个顶层键，与 GUI 等价，热加载）：

task-chime:
approvalSound: D:/Music/my-approval-chime.mp3
taskSound: C:/Windows/Media/Windows Notify System Generic.wav
approvalEnabled: true
taskEnabled: true
approvalVolume: 100
taskVolume: 100
cooldownMs: 1500

声音文件支持 mp3、wav 等 Windows 可解码格式，填本地绝对路径即可，路径含空格也没问题（内部已加引号）。

音量说明：setaudio volume 只有部分 MCI 驱动实现——mp3（mpegvideo）支持，wav（waveaudio）会返回 261 并被忽略，即 wav 按系统音量播放。这是驱动行为，不是插件缺陷。

工作原理 / How it works

- 宿主半监听 session/event 火线中的 approval/asked（审批）与 turn/end（任务完成）事件。
- 播放时在当前进程内通过 koffi FFI 调用 winmm.dll 的 mciSendStringW：open → setaudio → status <alias> length 取时长 → play（不带 wait，立即返回）→ 定时 close。所有 MCI 调用都是同步的（微秒级），不阻塞事件循环。
- 浏览器半（lib/client.js）以客户端模块系统的 lazy-CJS 格式注册设置卡片。

兼容性红线 / Do not regress

永远不要为了播放声音再去派生 powershell / cmd 子进程。 1.0.1 及更早版本的播放路径会派生一个隐藏窗口的 PowerShell 子进程，并在运行期编译一段 P/Invoke 垫片去调 winmm。

2026-09-12，Windows Defender 把那条命令行判定为 Trojan:Win32/PowhidSubExec.B（隐藏式 PowerShell 子进程执行）并直接终止了 harness 进程——一个提示音插件因此把宿主搞挂了。

因此后续修改必须遵守：这里不允许出现任何子进程——不 spawn shell、不调用 PowerShell（无论是否隐藏窗口）、不内联编译 C#、不传编码后的命令载荷。播放留在进程内。

红线二：所有 MCI 调用必须同步，绝不能用 mci.async

MCI 的别名（alias）绑定在执行 open 的那个线程上。koffi 的 async 会把调用丢到线程池线程，那个线程不认识该别名，返回 263（"指定的设备未打开，或不被 MCI 所识别"），而且一声都不会响。

1.0.2 / 1.0.3 / 1.0.4 三个版本的提示音全程无声，就是死在这里——事件送达、设置解析、koffi 加载全部正常，唯独 play 返回 263。实测对比：

| 调用方式 | open | play 返回码 | status mode |
| 同步 play（不 wait） | 0 | 0 | playing ✓ |
| 同步 play … wait | 0 | 0 | ✓ |
| mci.async('play') | 0 | 263 | stopped ✗ |
| mci.async('play … wait') | 0 | 263 | stopped ✗ |

需要"播完再关设备"时，用同步 status <alias> length 取毫秒数，再交给 setTimeout 去 close —— 不要图省事换成 async。

平台 / Platform

- 已在 Windows + DSH Web 上实测通过。
- 插件本体（挂载、事件、设置、GUI 卡片）是 DSH 通用的；只有发声层是 Windows 专属（winmm.dll）。非 Windows 平台会加载但静默，需自行扩展播放后端（macOS afplay / Linux paplay）。
- koffi 由 DSH 随附（profiles/node_modules/koffi），运行期动态解析；找不到时插件会打印一条明确错误而不是退化回子进程。

诊断日志 / Diagnostics

默认不写任何日志。排查"没声音"时，给 dsh 进程设一个环境变量再复现即可：

TASK_CHIME_TRACE=D:/tmp/task-chime.log dsh web

日志按行记录关键事件与播放结果，例如：

turn/end; taskEnabled=true taskSound="D:/Music/chime.mp3" cooldownMs=1500
playSound ok type=mpegvideo vol=100 len=447ms hold=847ms file=D:/Music/chime.mp3

失败时会写出 MCI 返回码（如 playSound play FAILED rc=263）。排查完删掉该变量即可恢复零日志。

为什么不默认开：写死的本机路径不该被带进公开仓库，也不该在别人的机器上往无关位置写文件。
另外真正的故障码同时也会输出到 stderr（[task-chime] …），不开这个日志也能看到。

常见问题 / FAQ

- 改代码后不生效？ 重启 dsh（Node ESM 缓存不会热重载 bare 包）；file: 安装还需重新 add 一次以刷新硬链接副本。
- 没声音？ 依次确认：声音路径存在 → 对应板块已启用 → 冷却间隔未拦截 → 用上面的 TASK_CHIME_TRACE 开日志看 playSound ok 还是带错误码的 FAILED。
（历史教训：本插件曾有连续三个版本全程无声，原因是 mci.async 的 263，见上文红线二。）
- 音量滑到 0 还是响？ 该文件是 wav，走了不支持音量的驱动；换成 mp3 即可。

许可 / License

MIT