# dsh-plugin-notify-sound

[English](README.md) | 中文

DeepSeek Harness（DSH）Web 端插件：**任务完成后按工作区播放可定制的通知铃声**，
并在**需要人介入时**（审批、提问、计划评审、目标受阻、任务失败）播放注意提示音。

## 功能

### 完成铃声（按工作区）

- 会话「一次回答结束」（回合完成，`running: true → false`）或后台任务完成时播放。
- 铃声按工作区解析：先查该工作区的单独配置，未配置则使用默认铃声。
- 声音来源三选：
  - **内置合成音** — 6 种（叮咚 / 风铃 / 铃铛 / 完成 / 成功 / 静音），Web Audio 实时合成，无需音频文件；
  - **语音播报（TTS）** — 浏览器用系统中文语音朗读自定义文案（如「我做完啦！」），可选声音与语速；
  - **自定义音频** — 上传任意 MP3/WAV 等文件。

### 注意铃声（需要人介入时）

以下事件**始终响铃**（不受「当前会话不响铃」限制）：

| 事件 | 检测来源 | 默认声音 |
|---|---|---|
| 审批请求 | 会话 `pendingInteraction: approval` | 通用注意音 |
| 用户提问 | `pendingInteraction: question` | 通用注意音 |
| 计划评审 | `pendingInteraction: plan-review` | 通用注意音 |
| 目标受阻 | goal 投影进入 `blocked` | 通用注意音 |
| 后台任务失败 | 任务状态 `failed` | 铃铛（独立失败音） |

每类事件可单独覆盖声音（或跟随通用注意音），也可统一使用一句播报文案
（如「需要你的确认」）。

### 设置面板（设置 → 通知铃声）

总开关、「当前会话完成时不响铃」、默认完成铃声、每工作区完成铃声、
通用注意音 + 五类注意事件、语音设置（声音/语速/试听/刷新列表）、逐项试听与上传。

## 安装

需要支持 bundle 插件的 DSH 版本（`dsh.profile.bundles` + `dsh.bundle.patch`），
且 PATH 中有 `pnpm`（`corepack enable` 或 `npm i -g pnpm`）。

```sh
# 一键安装：pnpm 安装依赖并把本包加入 profile 的 bundles 层
dsh plugin --profile web add dsh-plugin-notify-sound

# 重启服务（或刷新页面），打开 设置 → 通知铃声 即可配置
```

其他 profile 同理：`dsh plugin --profile <name> add dsh-plugin-notify-sound`。

### 手动安装（无 pnpm 时）

1. 把本包及依赖（`@deepseek-ai/schemastery`、`@deepseek-ai/cosmokit`、`@standard-schema/spec`）
   复制到 `$DSH_HOME/profiles/web/node_modules/`；
2. 在 `$DSH_HOME/profiles/web/package.json` 的 `dsh.profile.bundles` 中追加 `"dsh-plugin-notify-sound"`；
3. 重启 `dsh web`。

## 配置持久化

- 客户端配置保存在浏览器 **localStorage**（键 `dsh-notify-sound:config`），读取时做字段校验与默认值兜底。
- 宿主端同时注册 `dsh-plugin-notify-sound` 设置命名空间：rc.6 的 settings API 白名单
  （`dsh-host-apiproxy` 的 `WEB_SETTINGS_NAMESPACES`）不会把第三方命名空间暴露给浏览器，
  该注册为平台开放暴露机制后的无缝迁移预留（客户端存储接口外形与 settingsScope 一致）。

## 开发

```sh
npm test      # 宿主端 + 客户端 50 余项自动化断言（Node 即可，无需浏览器）
npm run check # 语法检查
```

结构：

- `lib/index.js` — 宿主端：注册 settings 命名空间（schemas 校验 + 默认值）
- `lib/client.js` — 浏览器端 bundle：完成/注意事件监听、声音引擎（Web Audio / TTS / Audio）、设置面板
- `lib/types/index.d.ts` — 宿主端类型声明
- `cordis.patch.yml` — bundle 补丁层（插入 `notify-sound` 行）
- `tools/` — 测试与验收脚本（不随 npm 包发布）

## 发布

```sh
npm login                       # 登录 npm（建议开启 2FA）
npm publish --access public
```

## 许可证

[MIT](LICENSE)