dsh-qq-sounds

用 QQ 的提示音提醒你 DSH 的状态。 DSH 干完一个任务，响「QQ 好友消息」的「滴滴」；它要你放权限、要你回答问题，响「QQ 系统消息」的那种提示——不用一直盯着屏幕。

English | 中文

---

它做什么

时机	默认音效
任务完成（turn/end · completed）	QQ 好友消息 msg.wav
需要审批 / 放权限（approval/asked）	QQ 系统消息 system.wav，未处理会重复响
需要你回答问题（ask_user_question）	QQ 系统消息 system.wav，未处理会重复响
任务出错（turn/end · error）	内置「下行低鸣」（默认关闭）

• 直接用你本机 QQ 的音效文件：自动探测 QQ 安装目录（注册表卸载项 + 常见路径），读 Misc\Sound\Classic\*.wav；也能手填目录或任意本机音频。
• 没装 QQ 也不哑：内置两个「仿 QQ」合成音（好友消息 / 系统提示），版权干净，随包分发。
• 重复提醒：审批 / 提问没处理时按间隔重响（默认 25–30 秒，最多 4–6 次）；你点一下页面、切回窗口，或达到次数上限就停。
• 默认就有声，不管你在不在 DSH 界面：只在 DSH 不在前台时响 默认是关闭的——你在浏览器里看别的东西、DSH 缩在后台，该响还是响。
• 不吵你（可选）：静音时段（支持跨午夜）、只在 DSH 不在前台时响 可以手动打开、总音量 0–100%。
• 后台也知道：可选系统通知（点击回窗口）+ 窗口标题加 🔔。
• 四类事件独立配置：每类都能单独选音效 / 静音 / 关掉。

三条硬承诺（设计红线）

1. 绝不阻止 DSH 启动。 一个提醒音插件没有资格让宿主起不来。客户端半的 factory 与 apply 全量 try/catch（任何异常都退化成空插件），宿主半的初始化和 apply 同样分段兜底。最坏情况是「插件不工作」，而不是「DSH 起不来」。
2. 不改动别的插件。 本包零运行时依赖（dependencies 为空），安装只是往 profile 里新增一个包，不替换、不升级、不删除任何已有包；因此与 IM 桥接（@xmanrui/dsh-im）、论文雷达、token-stats 等共存时不存在依赖冲突。装完可以核对：

   Get-ChildItem "$env:USERPROFILE\.dsh\profiles\<profile>\node_modules\@xmanrui\dsh-im\lib"
   

3. 默认配置就能听见。 装完重启，不需要改任何设置；只在 DSH 不在前台时响 默认关闭，任务完成 默认用 QQ 的 msg.wav，需要审批 / 回答问题 默认用 system.wav。

安装

方式 1：在 DSH 里点（推荐）

左侧栏 「插件」→ 添加插件，粘贴：

dsh-qq-sounds

装完重启 DSH，然后进 设置 → QQ 提醒音，点「重新检测」确认找到 QQ 音效，试听一下「完成」和「审批」，就完事了。

方式 2：命令行

dsh plugin --profile <你的 profile> add dsh-qq-sounds

<你的 profile> 通常是 web 或 desktop（~/.dsh/profiles/ 下的目录名）。装完重启。

方式 3：从 GitHub 源码

dsh plugin --profile <你的 profile> add github:GeXiubinHelloWorld/dsh-qq-sounds

首次使用

1. 重启 DSH（插件进入 profile 的 bundles 列表只在 boot 时读取，无法热插）；
2. 打开 设置 → QQ 提醒音，顶部应显示「✓ 音频已解锁」；
   • 如果没解锁，点一下页面任意处（浏览器要求先有用户交互才允许出声）；
3. 「QQ 音效目录」里应看到 C:\...\Misc\Sound\Classic 与「已找到 N 个音效」；
4. 点几个 ▶ msg / ▶ system 试听，确认是对的声音；
5. 按需调整四类事件的音效、重复提醒、静音时段。

配置项

分区	项	说明
总开关	启用 QQ 提醒音	关掉后宿主不再记录事件，也不会响
	音量	0–100%，作用于合成音与音频文件的播放音量
QQ 音效目录	检测 / 手动目录	探测顺序：手填目录 → DSH_QQ_DIR 环境变量 → 常见路径 → 注册表卸载项
事件 ×4	启用 / 音效下拉	选项：QQ 的五种音效、内置七种音、自定义本机路径、静音
	重复提醒（审批 / 提问）	间隔 5–600 秒，最多 1–50 次；回到页面即停
何时提醒	只在 DSH 不在前台时响	document.hasFocus() + 可见性判定
	同时弹系统通知	需要浏览器通知权限；点击回到窗口
	标题前加 🔔	有待处理且页面不在前台时加，回来即去掉
	静音时段	HH:MM 起止，支持跨午夜；该时段内事件不记录、也不补发

配置保存在 ~/.dsh/qq-sounds/config.json（可用环境变量 DSH_QQ_SOUNDS_DATA 换目录），不写浏览器 localStorage，换浏览器 / 清缓存都不丢。

工作原理

DSH 宿主进程
  ├─ ctx.on("session/event")  →  识别四类事件（完成 / 审批 / 提问 / 出错）
  │                             →  过滤总开关、单事件开关、静音时段、5s 同会话去抖
  │                             →  写入 64 条环形事件日志（带 id 游标 + bootId）
  └─ ctx.webServer.register("/api/qq-sounds/{config,detect,poll,audio,health}")
                                ↑ 只监听本机回环
浏览器（设置页所在的 GUI 进程）
  └─ 每 1.2s 拉 /api/qq-sounds/poll?since=<cursor>  →  新事件 → 播声音 / 弹通知 / 加角标

• 为什么用轮询而不是推送：DSH 的客户端 RPC 只有单向 request/response，服务端没有下行通道；1.2s 游标增量轮询是当前架构下的最小代价（平时响应就是 {"events":[]} 几十字节）。
• 为什么不依赖 @deepseek-ai/*：宿主半只 import node: 内置模块，浏览器半侧走同源 HTTP，所以插件装进任何 profile 都不需要额外的 peer 依赖能被解析到。
• 音频怎么过来：/api/qq-sounds/audio?path=... 把本机文件按字节回传（白名单扩展名 + ≤4MB），<audio> 直接播；不做 base64 塞配置。

隐私与安全

• 插件的五条路由只接受本机回环请求（127.0.0.1 / ::1），别的机器连上来一律 403。
• 只能读 wav / mp3 / ogg / m4a / aac / flac / webm 且 ≤4MB 的文件；其他路径与格式直接拒绝。
• 插件不发起任何外网请求，不做 analytics，不上传任何内容。
• 事件日志只存在内存里（最多 64 条），不落盘、不外发。

版权

插件代码 MIT。QQ 的音效文件版权归腾讯：本插件不打包、不复制、不转发任何 QQ 音频，只在你本机按路径读取你自己安装的 QQ 里的那份。仓库与 npm 包里只有自制合成音。

故障排查

现象	原因 / 处理
完全没声音	① 页面还没交互过 → 点一下窗口任意处；② 总开关没开；③ 处于静音时段；④ 勾了「只在 DSH 不在前台时响」（默认关闭，勾上后你盯着窗口就不响）
你在用 DSH 时它不响、切走后响	就是上面第 ④ 条：把「只在 DSH 不在前台时响」关掉即可（默认就是关的）
系统有声音、只有 DSH 没声音	Windows 给这个应用单独指定了输出设备：设置 → 系统 → 声音 → 音量合成器，找到 DeepSeek Harness，输出设备选「默认」、音量拉起来
提示音是「叮咚」不是 QQ 的	没找到 QQ 音效 → 设置里点「重新检测」，或手填 QQ 安装目录（含 Misc\Sound\Classic 的那层之上）
找不到 QQ 目录	QQ 可能装在非标准盘符 → 手动填，例如 D:\apps\qq；或安装 QQ 后重启 DSH 再检测
声音延迟 1 秒多	轮询周期 1.2s，属预期
关闭 DSH 窗口后不响	声音由 GUI 页面播放，进程退出就没了；系统通知依赖窗口存活
审批请求很少触发	当前会话可能设了「审批永远放行」；换个允许审批的会话试

音效格式：QQ 经典版的 msg.wav 是 MS ADPCM，浏览器原生解不了；宿主侧会自动把它转成 PCM16 再送前端。其余音效（system.wav 等）本来就是 PCM，原样透传。

已知限制

• 多窗口：每个 GUI 窗口都会各自播放（没有做跨窗口去重），开两个窗口会听到两声。
• 进程退出后不响：声音由 GUI 页面播放，DSH 退出就没了；系统通知同样依赖进程存活。
• 只支持 DSH 0.2.1+ 的 web / desktop profile：用的是官方 settings.section 槽位与 webServer.register 路由，不依赖内部包。
• macOS / Linux：不做 Windows 注册表探测，找不到 QQ 音效时回落到内置合成音（功能可用）。

开发

dsh-qq-sounds/
├─ package.json        # dsh.bundle.patch + dsh.client（platform: web）
├─ cordis.patch.yml    # profile 补丁层：insert 一行 id=qq-sounds
├─ lib/host.js         # 宿主半：配置、QQ 探测、音频读取、事件检测、HTTP 路由
├─ lib/client.js       # 浏览器半：预构建 ModuleLoader bundle（无构建步骤）
└─ test/               # node --test：宿主逻辑、路由端到端、客户端装载与渲染

node --test test/            # 全部测试
dsh plugin --profile web add ./    # 装本地目录（开发用链接）

• 改 lib/client.js：DSH 的客户端 HMR 会热替换 bundle，不用重启，刷新页面即可看到；
• 改 lib/host.js / package.json / cordis.patch.yml：必须重启 DSH；
• 首次安装（进入 bundles 列表）一定需要重启——插件还没运行，无法参与自己的激活。