dsh-sound-feedback
成功/失败提示音插件 for DeepSeek Harness (DSH) · Plays distinct Windows system sounds when a DSH task succeeds or fails.
一个 DSH 事件插件：监听 agent 回合（turn/end）和（可选）工具调用结果（tools/result），在成功和失败时播放不同的 Windows 系统提示音，让你不盯屏幕也知道当前状态。
A DSH events plugin: watches agent turns (turn/end) and (optionally) tool-call results (tools/result), and plays different Windows system sounds on success vs failure — know the state without watching the screen.
零运行时 npm 依赖：只使用宿主传入的 ctx 与 Node 内建 node:child_process（由 powershell.exe 播放声音）。所有 @deepseek-ai/* 均为 import type，编译期擦除。
Zero runtime npm dependencies: only the host-provided ctx and the Node builtin node:child_process (PowerShell plays the sound). All @deepseek-ai/* imports are import type — erased at compile time.
功能 / Features
| 场景 / Scenario | 默认提示音 / Default sound |
|---|
回合成功 turn/end reason=completed | asterisk（Windows 默认通知音） |
回合失败 turn/end reason=error | hand（Windows 关键停止/错误音） |
回合被打断/阻塞/超长 aborted blocked max-tokens interrupted | 静音（可配置 otherSound） |
| 工具调用成功/失败（`mode: 'tool' | 'both'` 时） |
提示音来源：先读当前 Windows 声音方案（注册表 HKCU\AppEvents\Schemes\Apps\.Default\<event>\.current），未设置时回退到 C:\Windows\Media\*.wav；也可直接配置任意 .wav 绝对路径。
Sound source: the user's current Windows sound scheme (registry HKCU\AppEvents\Schemes\Apps\.Default\<event>\.current), falling back to C:\Windows\Media\*.wav; or any explicit .wav path.
仅 Windows。其他平台加载时打印警告并空转。Windows-only; other platforms warn and no-op.
快速开始 / Quick start
pnpm install
pnpm run build # tsc -> dist/index.js (pure ESM)
# 在「父目录」执行（相对路径锚定调用目录）：
dsh plugin --profile my-profile add ./dsh-sound-feedback
dsh --profile my-profile
或者作为 bundle 加入 profile（把 dsh-sound-feedback 加进 profile 的 bundles 即可，插件自带 cordis.patch.yml 会把自身插入配置树）。
Or add as a bundle: list dsh-sound-feedback in the profile's bundles; the plugin's own cordis.patch.yml inserts it into the config tree.
配置 / Configuration
默认配置即可用；通过 patch 层覆盖（后层按 id 整行替换）：
Defaults work out of the box; override through patch layers (whole-row replace by id):
# profile 的 cordis.patch.yml (or a later bundle layer)
- insert:
- id: dsh-sound-feedback
name: dsh-sound-feedback
config:
enabled: true # 总开关 (master switch)
mode: turn # turn | tool | both
successSound: asterisk # 或任意 .wav 绝对路径
failureSound: hand
otherSound: '' # 静音；可设成 exclamation/question 等
minIntervalMs: 1200 # 两次播放最小间隔（防轰炸）
ignoreTools: [] # tool/both 模式下忽略的工具名
支持的 successSound / failureSound / otherSound：
| 名字 / Name | AppEvents 事件 | Media 回退 |
|---|
asterisk | SystemAsterisk | Windows Background.wav → notify.wav → ding.wav |
hand | SystemHand | Windows Foreground.wav → Windows Error.wav → Windows Critical Stop.wav |
exclamation | SystemExclamation | Windows Background.wav → Windows Exclamation.wav → notify.wav |
question | SystemQuestion | Windows Ding.wav → notify.wav → Windows Background.wav |
beep / default | SystemDefault | Windows Default.wav → ding.wav → tada.wav |
任意 .wav 路径 | — | 直接播放 |
项目结构 / Layout
src/index.ts # 插件源码（apply + 纯函数 soundCommand/classifyTurnEnd）
cordis.patch.yml # bundle 补丁层（默认配置）
test/index.test.mjs # 单元测试（纯逻辑，无声音）
test/integration.mjs # 集成测试（真实 Cordis fiber + 事件总线）
scripts/play-sounds.mjs # 手动试听：node scripts/play-sounds.mjs
开发 / Development
npm run build # tsc -> dist/index.js
npm test # 单元测试（in-process，不需要声音设备）
node test/integration.mjs # 真实 Cordis Context 装载 + 事件触发（会真播放声音）
node scripts/play-sounds.mjs # 试听默认成功/失败/自定义声音
集成测试会真实播放提示音（成功/失败/自定义各一次），请确定喇叭开着。
The integration test actually plays sounds (success/failure/custom once each) — make sure your speakers are on.
依赖版本 / Pinned versions
- runtime deps: none
@deepseek-ai/dsh-tools / @deepseek-ai/dsh-session: 0.1.0-rc.7（对齐宿主运行时，devDependencies，仅类型）@deepseek-ai/cordis: ^4.0.1（peerDependency，宿主提供）- Node
^22.19.0 || >=24.0.0
坑 / Pitfalls
@deepseek-ai/dsh-tools 的 npm latest 是过期线（0.0.1-rc.1），正确线在 next tag。本项目对齐宿主运行时锁 0.1.0-rc.7，勿用 npm i @deepseek-ai/dsh-tools 覆盖。- 纯 ESM：
"type": "module"，module: esnext + moduleResolution: bundler。
@deepseek-ai/cordis 只 import type；运行时 ctx 由宿主传入。- 注册即 effect：
ctx.on(...) 卸载自动清理，集成测试已验证 fiber dispose 干净。
powershell.exe 是 Windows 5.1 版语法（无三元表达式），脚本面向 5.1 编写。
License
MIT
