dsh-audio-cue：DeepSeek Harness 音频提示插件

前言¶

DeepSeek Harness（DSH）允许开发者以插件形式扩展功能。在长时间运行智能体任务时，屏幕上的终端输出可能无法直观反映当前是处于“思考/工作中”还是“等待决策”的状态。dsh-audio-cue 插件通过音频反馈解决这一问题：在工作时播放背景音，在需要用户介入时发出提示音。

插件简介¶

dsh-audio-cue 是一个运行在 DeepSeek Harness 环境下的音频插件，由 Goothe13-gugu 维护，采用 MIT 许可证。

它的核心作用是在智能体工作时提供听觉反馈，帮助开发者通过声音判断当前状态。

核心功能¶

• 工作环境音：当会话处于开启状态（思考或执行任务）时，播放背景音频。
• 提示音：当智能体请求审批或提问时，停止背景音并播放提示音。
• 闲置淡出：当工作停止时，背景音自动淡出。
• Web 设置面板：提供可视化的设置界面，无需手动编辑配置文件。
• 控制台 API：支持通过 JavaScript 脚本控制插件状态。
• 子代理支持：子代理的开放回合会被计入“工作”状态，继续播放背景音。
• 持久化配置：设置保存在宿主机而非浏览器端。

安装与启用¶

安装命令如下：

dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue

如果需要固定版本，可以使用标签：

dsh plugin --profile web add github:Goothe13-gugu/dsh-audio-cue#v0.1.0

安装完成后，必须重启 Harness 配置文件才能挂载该插件。

使用方法¶

检查状态¶

通过浏览器控制台或脚本，可以查询插件当前状态：

__DSH_AUDIO_CUE__.state()

控制台 API¶

插件提供了以下 API 供脚本调用：

__DSH_AUDIO_CUE__.state()                       // 获取状态
__DSH_AUDIO_CUE__.toggle()                      // 开关切换
__DSH_AUDIO_CUE__.setVolume(0.4)                // 设置音量
__DSH_AUDIO_CUE__.setEnabled(false)             // 启用/静音
__DSH_AUDIO_CUE__.open()                        // 打开设置面板
__DSH_AUDIO_CUE__.settings()                    // 获取设置
__DSH_AUDIO_CUE__.refresh()                     // 刷新配置
__DSH_AUDIO_CUE__.history()                     // 获取状态变更历史
__DSH_AUDIO_CUE__.setPosition(520)              // 调整按钮位置

配置与存储¶

设置文件位置¶

配置存储在宿主机的 DSH 目录下，而非浏览器缓存中。目录结构如下：

$DSH_HOME/dsh-audio-cue/
  ├── settings.json      # 存储静音、音量、播放模式及音效选择
  └── uploads/           # 导入的音频文件

数据安全¶

设置文件通过“临时文件 + 重命名”的方式写入，防止崩溃导致配置损坏。如果配置文件损坏或不可读，插件会使用默认值。如果导入的音效文件丢失，会自动回退到默认音效。

状态判断逻辑¶

插件订阅会话事件日志，根据以下规则判断当前状态：

状态变化通过 Server-Sent Events 流 (/dsh-audio-cue/events) 发布。

注意事项¶

• Node.js 版本：插件运行需要 Node.js 版本大于等于 22。
• 子代理处理：任何开启回合的会话（包括子代理）都会被视为“工作”，背景音不会中断。
• 权限范围：插件以当前 DSH 进程权限运行，安装前建议检查源码与许可证。

总结¶

dsh-audio-cue 通过环境音和提示音，为 DSH 用户提供了直观的状态反馈。其 Web 面板和 Console API 设计，兼顾了易用性与可编程性。

• GitHub 仓库
• 插件目录