dsh-sound-effects

Readme

# dsh-sound-effects 🔔

DeepSeek Harness (DSH) 音效提示插件 —— **任务完成**或**需要权限审批**时播放提示音，可随时更换音效。

## ✨ 功能

| 能力 | 说明 |
| --- | --- |
| 🔔 任务完成音效 | agent 回合正常结束时播放（出错/中断不响） |
| ⚠️ 权限请求音效 | 每次需要用户批准（审批弹窗）时播放 |
| 🎛️ 随时更换音效 | 设置 → 音效提示：4 种预设 + **上传自定义音频**（<512KB）+ 音量 + 静音 + 试听 |
| 🔄 自动播放兼容 | 浏览器拦截时挂起，首次点击页面后自动解锁并补播 |
| 📊 运行状态 | 设置页显示音频状态与最近播放记录 |

## 🚀 安装

```sh
# 方式一：GitHub 源
dsh plugin --profile web add github:fenghua00/dsh-sound-effects

# 方式二：本地目录（复制到 profile 的 plugins/ 后）
dsh plugin --profile web add <plugins>/dsh-sound-effects
```

重启 `dsh web` 后生效。打开 **设置 → 音效提示** 即可使用。

## 🧰 使用

1. 重启后到 **设置 → 音效提示**：
   - 「完成音效」与「权限音效」分别选择预设（清脆叮咚 / 叮咚提示 / 短促嘀声 / 柔和警报）
   - 点「上传」可用自己的音频文件（`wav/mp3/ogg`，≤512KB，存于浏览器本地）
   - 拖动「音量」、勾选「静音」、点「▶ 试听」预览
2. 音频配置存在浏览器 `localStorage`（键前缀 `dsh-sfx:`），刷新/重启不丢

> 首次使用若浏览器阻止自动播放，点击页面任意位置即可解锁，挂起的提示音会自动补播。

## 🛠️ 实现说明

- **事件源**（宿主半区）：监听会话事件 `session/event`
  - `approval/asked` → 权限请求 → 播放权限音效
  - `turn/end`（reason=`completed`）→ 回合正常结束 → 播放完成音效
- **通信**：宿主在 `/plugin/sfx/*` 挂 HTTP 路由，浏览器半区 `fetch` 轮询取事件（无需 `host.call`，兼容标准 dsh-plugin 安装方式）
- 双面插件：`dsh.bundle.patch`（Host 半区）+ `dsh.client`（浏览器半区）

## 📁 结构

```
dsh-sound-effects/
├── package.json        # type:module + dsh.bundle.patch + dsh.client
├── cordis.patch.yml    # 插入 sound-effects 配置行
└── lib/
    ├── index.js        # Host: 事件监听 + /plugin/sfx HTTP 接口
    └── client.js       # 浏览器: 播放/设置页/轮询 (__ModuleLoader__)
```

## License

MIT