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。

验证

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

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

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