task-chime

Readme

# task-chime — DSH 任务提示音 / DSH Task Chime

> 一个为 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 设计的轻量提示音插件：**审批/权限请求**与**任务完成**时播放本地声音，全部可在 Web GUI 设置中自定义。A lightweight chime plugin for DeepSeek Harness: plays local sounds on **approval / permission requests** and **task completion**, fully configurable from the Web GUI.

## 功能 / Features

- 🔔 **权限确认提示音** — 每当 harness 发起审批/权限请求（如沙箱升级、受限文件操作）时播放，即使忙于其他窗口也能立刻注意到。
- ✅ **任务完成提示音** — 一次完整的 agent 回答（回合）结束时播放。
- 🎚️ **GUI 设置卡片** — 设置 → 插件 → 插件配置 → "DSH 任务提示音"：权限确认与任务完成两个板块，各自可更换声音文件、调节音量（0–100）、启用/禁用，另有公共冷却间隔。
- 💾 **设置持久化** — 写入 `$DSH_HOME/settings.yaml`，改动即时生效，重启保留。
- 🖥️ **系统级播放** — 通过 Windows 原生 MCI 接口（winmm.dll）在独立进程中播放，不依赖浏览器标签页；mp3 / wav 均支持。
- 🎨 **跟随主题** — 卡片 UI 使用 `--dsw-alias-*` 主题变量，浅色/深色自动适配。

## 安装 / Install

```sh
dsh plugin --profile web add task-chime
```

然后**重启 `dsh web`** 并**强制刷新浏览器页面**（Ctrl+Shift+R）。

> 注意：该插件为 bare-package 模块，被 Node ESM 缓存，修改代码后必须重启 dsh 才生效。

## 配置 / Configuration

重启后打开 **设置 → 插件 → 插件配置 → DSH 任务提示音**：

| 板块 | 字段 | 说明 |
| --- | --- | --- |
| 权限确认 | 启用 / 声音文件 / 音量 | 审批请求时播放；默认未配置声音（在 GUI 中设置后生效） |
| 任务完成 | 启用 / 声音文件 / 音量 | 回合结束时播放；默认 Windows 系统提示音 wav |
| 通用 | 冷却间隔（毫秒） | 两次提示音之间的最小间隔，防止连发 |

声音文件支持 `mp3`、`wav` 等 Windows 可解码格式，填本地绝对路径即可，例如：

```
D:/Music/my-approval-chime.mp3
C:/Windows/Media/Windows Notify System Generic.wav
```

## 工作原理 / How it works

- 宿主半监听 `session/event` 火线中的 `approval/asked`（审批）与 `turn/end`（任务完成）事件。
- 播放时派生一个 `powershell` 子进程，通过 MCI `mciSendString` 的 `play ... wait` 播放完毕后自动退出——无需窗口或 COM 消息泵。
- 浏览器半（`lib/client.js`）以客户端模块系统的 lazy-CJS 格式注册设置卡片。

## 平台 / Platform

- 已在 Windows + DSH Web 上实测通过。
- 播放依赖 Windows MCI（`winmm.dll`），非 Windows 平台需自行扩展播放后端。

## 常见问题 / FAQ

- **改代码后不生效？** 重启 dsh（Node ESM 缓存不会热重载 bare 包）。
- **没声音？** 确认声音文件路径存在；确认播放后端未被 `detached`/`stdio: ignore`/`windowsHide` 影响（本项目使用 `stdio: "inherit"`）。

## 许可 / License

[MIT](./LICENSE)