dsh-client-ui-sounds

> 为 DeepSeek Harness（DSH）添加会话生命周期音效提示的插件：会话正常完成、主动停止回复、需要权限/提问、会话异常终止时播放对应的提示音，并支持在界面内导入自定义音效。

A sound-cue plugin for DeepSeek Harness (DSH) tied to the session lifecycle: plays a distinct tone when a session completes normally, when you stop an active response, when the agent needs your permission or asks a question, and when a session terminates abnormally — with an in-app UI to replace each tone with your own audio file.

---

功能特性 / Features

事件 Event	默认音效 Default tone	触发时机
✅ 会话正常完成 Session normal completion	上扬双音「叮-咚」	会话正常完成时
⏹️ 主动停止回复 Response stopped	下行双音	点击停止按钮中断当前回复
🔔 需要权限 / 提问	短促「滴滴」两声	弹出权限确认或提问时
⚠️ 会话异常终止 Session abnormal termination	低频警报下滑音	会话异常终止（如网络重置）

零音频文件：默认音效用 Web Audio 实时合成，无需携带任何资源。
界面内导入自定义音效：在设置面板里为四个事件分别选择音频文件（mp3 / wav / ogg 等浏览器支持的格式），即时试听，一键清除回退默认。
零构建、零依赖：纯手写客户端插件，pnpm 安装即可，无需编译。
标准 bundle 分发：声明了 dsh.bundle.patch，dsh plugin 会自动把它挂载为 profile layer，无需手动改任何配置。

---

前置条件 / Prerequisites

已安装 dsh：npm install -g @deepseek-ai/dsh
已安装 pnpm（dsh plugin 内部调用它）
有 web profile（dsh web 首次运行会自动初始化）

---

安装 / Install

从 GitHub 安装（推荐）

dsh plugin --profile web add github:FG-FOX/dsh-sound-plugin
# 或带分支
dsh plugin --profile web add "github:FG-FOX/dsh-sound-plugin#main"

从本地目录安装

dsh plugin --profile web add "D:/path/to/dsh-sound-plugin"

从 npm 安装（若已发布）

dsh plugin --profile web add dsh-client-ui-sounds

安装完成后 重启 dsh web 并刷新页面：

# 在运行 dsh web 的终端里 Ctrl+C 停掉，然后重新启动
dsh web
# 回到浏览器 / DSH Desktop 窗口按 Ctrl+R 刷新

> 无需手动编辑 profile 的 cordis.patch.yml——插件声明了 dsh.bundle.patch，dsh plugin 会自动把它加入 profile 的 bundle 列表并应用补丁。

---

使用 / Usage

1. 打开 DSH 的 设置面板（侧边栏设置图标）。 2. 找到新增的 「音效提示 / Sound Cues」 分类。 3. 四行分别对应四个事件，每行有： - 选择文件 / Choose file：导入自定义音频（存到浏览器 localStorage） - 试听 / Test：立即播放当前音效 - 清除 / Clear：移除自定义音效，回退到默认合成音 4. 之后对应事件触发时，会自动播放你设置的音效。

> 提示：localStorage 有容量上限（一般 5–10MB），单个音频建议控制在 1–2MB 以内。

---

目录结构 / Layout

dsh-sound-plugin/
├── package.json          # dsh.bundle + dsh.client 声明
├── cordis.patch.yml      # bundle 补丁：向 Loader 插入插件行
├── lib/
│   ├── index.js          # node 半（空 apply，供 host Loader 挂载）
│   └── client.js         # 浏览器半：音效引擎 + 事件检测 + 设置面板
└── README.md

---

工作原理 / How it works

事件检测：订阅 sessions.list 状态存储，对比前后快照，跟踪每个会话的生命周期：

- 会话从 running: true 变为 false 时：对该会话「停止生成 / Stop generating」按钮的捕获阶段点击（capture-phase click）会被保留 10 秒；若存在这样一次最近的停止点击，播放主动停止音；否则等待该会话的终止信号，根据信号选择播放正常完成音或异常终止音。该机制不依赖可能延迟到达的 turn/end 数据。 - 会话出现 pendingInteraction → 播放提问音 - 会话异常终止：等待该会话的事件流推进到 list 状态后，从会话 lastAgentError 或 end reason（error / aborted）判断异常终止 → 播放异常音

默认音效：Web Audio API 合成（振荡器 + 包络）。
自定义音效：<input type="file"> + FileReader 读成 base64 存 localStorage，播放用一次性 Audio 元素。
设置面板：通过 settings.section slot 接入官方设置 UI。

主动停止回复 / Response stopped

只有 DSH 对话自身的「停止生成 / Stop generating」按钮才算主动停止——其他点击不满足条件；请求失败或被取消、且未经历 idle（空闲）过渡时，不会误播停止音。

Only the DSH conversation's own stop button qualifies as an active stop; a failed or canceled request with no idle transition does not play a false stop cue.

---

自定义 / Customize

想改默认合成音的音色、音量、时长，编辑 lib/client.js 里的四个函数：

函数	对应事件
`playDone()`	会话正常完成
`playStop()`	主动停止回复
`playAsk()`	权限 / 提问
`playError()`	异常终止

本地 link: 安装（从本地目录安装）会直接加载源码改动，保存后在浏览器 / DSH Desktop 窗口按 Ctrl+R 刷新即可生效；GitHub / npm 安装则需要在更新或重新安装插件后，按情况刷新页面或重启 dsh web。

---

License

MIT