@dsh-external/dsh-soundscape

Readme

# dsh-soundscape

DSH 本机音效插件：监听 Agent 状态与工具生命周期，通过常驻
PowerShell 双 `System.Windows.Media.MediaPlayer` 守护进程
（`$think` 思考循环 + `$fx` 一次性音效）播放思考、工具、错误和情绪提示音。

## 当前能力

- `agent/status` 进入 `running` 时循环思考音，回到 `idle` 时停止并播放结束音。
- **工具音闪避**：工具音播放时思考循环降低至闪避电平（默认 20%），
  结束后自动恢复，实现无缝混音而非打断。
- **情绪感知音效**：连续成功触发「顺利进展」上行和弦，连续失败触发
  「连续困难」下行不协和音，长时间运行触发「深度思考」低频无人机氛围音。
  阈值和音效均可在设置页自定义。
- 工具开始、完成和失败音可独立开关；同工具调用有节流保护。
- 15 种零素材内置 PCM WAV（含 3 种情绪音效）；用户可在 `assets/sounds/` 放入
  `<工具名>.wav` 或 `<工具名>.mp3` 覆盖。
- MP3 由 `mpg123-decoder` 在 Node 进程内转换并缓存为 WAV。
- DSH 设置页提供开关、音量、思考音、工具映射、试听、重新扫描和打开音效目录。
- 工具映射面板展示全部 51 个 DSH 标准工具，按分类分组并带彩色标签，
  支持搜索过滤和逐工具音效自定义；分类采用精确映射表确保准确归类。
- 深色模式下所有下拉菜单（select/option）均有显式背景色和 `color-scheme: dark`，
  确保选项文字可见。
- 配置写入采用临时文件替换，插件卸载时停止定时器并终止播放进程。
- 守护进程采用滑动窗口重启策略（30 秒内最多 3 次），成功启动后计数器重置，
  长期会话不会因偶发崩溃而永久放弃重启。

## 配置与解析顺序

配置保存在 `assets/config.json`。工具音按以下顺序解析：

1. `assets/sounds/<工具名>.wav`
2. 已扫描转换的 `assets/sounds/<工具名>.mp3`
3. `config.tools.<工具名>`
4. 工具分类音
5. `config.tools.default`

映射值支持 `builtin:<名称>`、`file:<文件名>` 和 `none`。`cache:` 前缀是
运行时 MP3 转换缓存键，`sanitizeEntry` 会显式拒绝其写入配置。`file:` 条目
中的 `..` 和路径分隔符同样在校验层被拦截。MP3 转换缓存由
插件管理，不应手工写入配置。

## 本地 API

静态 hybrid bundle 使用 DSH 已验证的 `webServer.register` 同源接口：

- `GET/POST /api/dsh-soundscape/config`
- `GET /api/dsh-soundscape/sounds`
- `POST /api/dsh-soundscape/play-test`
- `POST /api/dsh-soundscape/rescan`
- `POST /api/dsh-soundscape/open-sounds-folder`

这些接口只由本机 DSH 页面调用。设计草案中的 `harness.handle/host.call`
属于动态 Cordis runner，不是此静态 bundle 的运行时 API。

## 验证

```powershell
npm install --ignore-scripts --legacy-peer-deps
npm run verify
```

`verify` 包含全部源码语法检查、Node 单元测试和宿主 mock smoke。

当前已在真实 DSH 中验证：热重载 active、5 条本地 API、设置页完整挂载、
保存立即生效、12 个内置音效清单、MediaPlayer 守护进程 `DAEMON READY`
及 `PLAYED` 回执。实际扬声器听感、最终代码完整重启、真实自定义文件命中
和卸载净验证仍需人工验收，不能仅凭日志推断通过。