前言¶
在 DeepSeek Harness (DSH) 的开发与调试过程中，Agent 的思考过程与工具执行状态往往只能通过日志体现，缺乏直观的听觉反馈。这可能导致开发者难以通过环境音判断 Agent 的运行状态或工具调用的成功与否。dsh-soundscape 通过监听 Agent 状态与工具生命周期，在本地提供即时的声音反馈。
这是什么¶
dsh-soundscape 是一个 DSH 本机音效插件，由 berserk0501 维护。它通过常驻 PowerShell 双 MediaPlayer 守护进程（$think 思考循环 + $fx 一次性音效）来播放思考、工具、错误和情绪提示音。
核心功能¶
- Agent 状态监听：监听
agent/status事件。进入running状态时循环播放思考音，回到idle状态时停止思考音并播放结束音。 - 工具音闪避：播放工具音效时，会将思考循环降低至 20%，结束后自动恢复。这实现了无缝混音，避免音效打断思考循环。
- 情绪感知音效：根据 Agent 的表现播放不同的氛围音。连续成功触发上行和弦，连续失败触发下行不协和音，长时间运行触发低频无人机氛围音。
- 工具管理：支持对工具音效进行独立开关与节流保护。
- 音频资源：内置 15 种零素材 PCM WAV（验证日志显示 12 个），支持用户在
assets/sounds/目录下放置<工具名>.wav或<工具名>.mp3进行覆盖。插件内部会将 MP3 自动转换为 WAV。 - 设置面板：提供开关、音量、思考音、工具映射、试听、重新扫描和打开音效目录等功能。
- 工具映射：面板展示全部 51 个 DSH 标准工具，支持搜索过滤和逐工具自定义音效。
- 可靠性设计：支持深色模式。配置写入采用临时文件替换，卸载时自动清理。守护进程采用滑动窗口重启策略（30 秒内最多 3 次）。
安装与启用¶
在项目目录下执行以下命令安装依赖：
npm install --ignore-scripts --legacy-peer-deps
典型用法¶
- 自定义音效：在
assets/sounds/目录下创建<工具名>.wav或<工具名>.mp3文件，即可覆盖默认音效。 - 配置映射：通过设置面板自定义工具音效映射和音量，或使用 API 进行配置。
- 扫描更新：如果添加了新的音效文件，点击设置面板的“重新扫描”功能更新音效列表。
- 测试：使用设置面板的试听功能或调用
/api/dsh-soundscape/play-test接口进行测试。
适用场景与注意¶
- 适用场景：适合需要在开发过程中通过听觉反馈监控 Agent 状态和工具调用的开发者。
- 注意：插件以当前 DSH 进程的权限运行。安装前应检查源码与许可证（MIT）。MP3 转换缓存由插件管理，不应手工写入配置。验证日志提到 12 个内置音效清单，实际扬声器听感、最终代码完整重启、真实自定义文件命中和卸载净验证仍需人工验收，不能仅凭日志推断通过。
结尾¶
dsh-soundscape 通过双 MediaPlayer 守护进程和情绪感知机制，为 DSH Agent 提供了即时的听觉反馈。开发者可以通过设置面板或 API 快速配置工具音效。更多信息请参考 GitHub 仓库 或 SkillHub 目录页。
