🔔 dsh-notify-sound
个人 DSH 会话提示音插件：会话完成 / 需要人介入（审批、提问、计划评审、目标受阻、后台任务失败）时播放内置合成提示音，不同情况可配不同声音，内置一套合理默认；配置服务端持久化，所有浏览器 / 设备同步。
参考 ldchaowin/dsh-plugin-notify-sound（MIT）裁剪改造：去掉自定义音频上传、TTS 语音播报与按工作区配置，改为仅内置合成音 + 插件设置卡片（dsh 0.1.6+ 在 Plugins 面板插件详情页，≤0.1.5 在「设置 > 插件 > 插件配置」）。
✨ 特性
- 内置 6 种合成提示音 + 静音：叮咚 / 风铃 / 铃铛 / 完成 / 成功 / 警示，Web Audio 实时合成，无任何音频文件
- 按情况区分：完成类（一次对话整回合结束）与注意类（审批请求、用户提问、计划评审、目标受阻、后台任务失败）各自独立配置，可"跟随通用注意音"
- 默认配置一套：装完即用（完成=风铃、注意=叮咚、受阻=铃铛、失败=警示）
- 配置所有浏览器同步：配置存服务端 profile 设置（用户层），任何浏览器 / 设备改动全局生效；本页每 30s 定时刷新 + 页面聚焦 / 可见时刷新，近实时同步
- 「提示音」设置卡片：兼容两代槽位——0.1.6+ 挂
plugins.bundle.config（Plugins 面板 → 插件详情页，按 owner view 渲染一行摘要 / 配置表单）；≤0.1.5 挂 settings.plugin.item（设置 → 插件配置 TAB，折叠卡形态），每行下拉 + 试听
- 注意类事件不受「当前会话不响铃」限制：需要你介入的事永远响，完成类可设为"当前正在查看的会话不响"
🎯 界面位置
dsh 0.1.6+：Plugins 面板（左侧）→ 已安装列表点「提示音」→ 详情页配置表单（官方 plugins.bundle.config 契约只请求 page 视图；组件同时实现了 summary 摘要视图，供 owner 请求时使用）。
dsh ≤0.1.5：设置（侧边栏底部）→ 插件配置 → 「提示音」折叠卡片。
两版控件相同：
☑ 启用提示音
☐ 当前正在查看的会话完成时不响铃
完成铃声（一次对话整回合结束）
完成铃声 [风铃 Chime] [试听]
需要人介入时（注意铃声，不受「当前会话不响铃」限制）
通用注意音 [叮咚 Ding] [试听]
审批请求 [跟随通用注意音] [试听]
用户提问 [跟随通用注意音] [试听]
计划评审 [跟随通用注意音] [试听]
目标受阻 [铃铛 Bell] [试听]
后台任务失败 [警示 Alert] [试听]
配置保存在服务端设置中，所有浏览器/设备同步生效…
🔊 内置音与默认配置
| 键 | 名称 | 听感 | 默认用于 |
|---|
ding | 叮咚 Ding | 门铃式双音（A5→D5） | 通用注意音 |
chime | 风铃 Chime | A5→E6 悠长双音 | 完成铃声（默认） |
bell | 铃铛 Bell | 钟铃非谐泛音（B4） | 目标受阻（默认） |
complete | 完成 Complete | C-E-G-C 上行琶音 | 可选 |
success | 成功 Success | G5→C6 明快双音 | 可选 |
alert | 警示 Alert | 220Hz 方波双声报警 | 后台任务失败（默认） |
none | 静音 | — | 可选 |
默认配置：完成 = chime；通用注意 = ding；审批 / 提问 / 计划评审 = 跟随通用（ding）；目标受阻 = bell；后台任务失败 = alert。
🎬 触发的事件
| 事件 | 检测 | 声音 |
|---|
| 回合结束（回答完成） | session running: true → false | 完成铃声（受「当前会话不响」约束） |
| 后台任务完成 / 终止 | job running/stopping → completed/killed | 不响（一次对话里的多个后台小任务不逐个提示，避免与回合结束提示重复） |
| 审批请求 | uiSession 交互快照出现 kind: approval（0.1.6+ 读 sessionStatus[*].pendingInteraction；≤0.1.5 读 pendingInteractions[*]） | 审批音 → 通用注意音 |
| 用户提问 | 同上，kind: question | 提问音 → 通用注意音 |
| 计划评审 | 同上，kind: plan-review | 评审音 → 通用注意音 |
| 目标受阻 | goal 投影 goal.goal.phase → blocked | goalBlockedSound（只响一次） |
| 后台任务失败 | job → failed | failureSound（不受约束） |
同源事件 600ms 内去抖，避免重复快照误响。
🔧 工作原理 / How it works
- 配置存储：宿主半区经
ctx.inject(['settings'], ...) 接入 dsh-settings，配置落在 profile 用户层（服务端落盘）。兼容两代 settings API（运行时择一）：≤0.1.6 用 sctx.settings.installSection(...) 显式注册 notify-sound 命名空间；0.1.7+ 的 settings 服务（SettingsForms）改由 configEditor 自动识别活动插件条目——Config schema 中标注 .volatile() 的字段即成为可热更新表单字段（命名空间名 = profile 条目 id，本插件同名 notify-sound，故视图结构与路由契约不变），插件只声明页面策略 configure({ auto: false })（自带卡片，不要官方自动表单）。官方 apiproxy 的 settings 白名单不暴露第三方命名空间，故宿主另注册 /notify-sound/settings 路由（GET 视图 / POST 批量写，同源护栏 + revision 栅栏）作为读写接缝
- 浏览器作用域：
NotifyConfigScope 实现 SettingsScope 契约直连该路由；启动拉取一次，写入即 POST 落盘，另每 30s + 聚焦/可见刷新——所有浏览器读同一份配置即天然同步
- 音效引擎：Web Audio 合成（Oscillator + Gain），
AudioContext 惰性创建；首次播放受浏览器自动播放策略约束，页面任意交互（如点「试听」）后即解锁
- 事件监听：订阅
sessions.list 快照（byId/ids/current/jobsBySession）+ uiSession 权威交互快照（审批/提问/计划评审；SessionSummary 无该字段，不能从 list 行读）。交互快照按 dsh 版本自动择一：0.1.6+ 为 sessionStatus（Map<SessionId, {running, pendingInteraction, completionUnread}>，交互在 status.pendingInteraction）；≤0.1.5 为 pendingInteractions（值本身即交互）。无轮询、无额外数据通道
- 包结构：标准 DSH 插件 bundle（
dsh.bundle.patch + dsh.client web 平台），lib/ 随源码提交，link 安装直接可用
📦 安装 / Installation
# 方式一：npm 安装（已发布到 npm registry，推荐——任意 mac/win/linux 机器）
dsh plugin --profile web add dsh-notify-sound
# 方式二：link 安装（源码目录，用于本地开发）
dsh plugin --profile web add link:/root/.dsh/external/notify-sound
# 注意：首次 add 可能只登记依赖、未进 dsh.profile.bundles，重跑一次（幂等）即补齐
dsh plugin --profile web add link:/root/.dsh/external/notify-sound
⚠️ 安装后需重启 dsh web，并在浏览器里 Ctrl+Shift+R 强制刷新一次（bundle 仅页面加载时获取）。
宿主依赖
@deepseek-ai/schemastery / @deepseek-ai/dsh-settings 未发布到 npm，运行时由 DSH 安装树提供（同 describe-image 既定流程）：
cd /root/.dsh/external/notify-sound/node_modules/@deepseek-ai
ln -sfn /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/schemastery schemastery
ln -sfn /usr/local/lib/node_modules/@deepseek-ai/dsh/node_modules/@deepseek-ai/dsh-settings dsh-settings
🖱️ 使用 / Usage
- 打开 设置 → 插件配置 → 提示音 卡片
- 每行下拉选择声音（注意类事件可选「跟随通用注意音」），点「试听」确认
- 改动即时落盘：其他浏览器 / 设备最迟 30s 内（或切回页面时）同步生效
- 需要安静时：关「启用提示音」，或只勾「当前正在查看的会话完成时不响铃」（注意类仍会响）
🧪 开发 / Development
npm test # 宿主契约 33 断言 + 浏览器逻辑 60 断言（node 内置，无需浏览器）
npm run check # 语法检查
布局：
lib/index.js — 宿主半区：设置命名空间 + /notify-sound/settings 读写路由lib/client.js — 浏览器半区：提示音卡片、事件监听、音效引擎、同步作用域tests/ — node 内置测试（假 loader / 假 AudioContext 频率捕获 / 内存版 settings 服务）cordis.patch.yml — bundle patch 层（insert notify-sound）
📜 部署记录
- 2026-09-23：适配 dsh 0.1.7 的 settings API 重构（v0.1.6）。0.1.7 把 dsh-settings 换成
SettingsForms——移除 SettingsProvider.installSection / register 方法与 installSettingsSection / settingsNamespace 导出，配置改由 configEditor 从活动插件条目 + Config schema 自动识别（字段须标 .volatile()），命名空间名 = profile 条目 id；settings 存储同时从 ~/.dsh/settings.yaml 迁到 profile 的 cordis.patch.yml（各插件条目 config 下）。改法（双版本兼容）：① Config 九个字段经 live() 包装——新版 schemastery（3.18.4，随 0.1.7 发布）支持 .volatile() 即标记为可热更新字段，旧版（3.18.2）无此方法则原样返回；② apply 运行时择一：有 installSection 走旧机制（≤0.1.6），否则调 settings.configure({ auto: false }, ctx.fiber) 声明页面策略（0.1.7+，自带卡片、不要官方自动表单）；③ describe() / replace() / writable 两代同名同义，buildSettingsView / applySettingsWrites 与 /notify-sound/settings 路由契约零改动。测试：宿主 33 → 39 断言（新增 modern API 六项），另用 schemastery 3.18.4 临时环境跑 40 断言（含「9 字段全部 volatile」）全过；客户端 60 断言不变。112（dsh 0.1.7-rc.1）实测全过：/notify-sound/settings GET 200（视图 9 字段 + writable:true，此前 404）、POST set → 落盘 cordis.patch.yml 的 - id: notify-sound 条目、unset → 条目移除回默认；插件详情页卡片恢复完整（7 下拉 + 2 复选 + 12 按钮，「无法读取服务端配置」消失，显示「配置保存在服务端设置中，所有浏览器/设备同步生效」）、console 不再有 notify-sound 404（仅剩未适配的 theme-center）；UI 改「完成铃声」→ 落盘 defaultSound: complete、回合结束探针捕获 complete 琶音（523.25/659.25/783.99/1046.5 + 泛音）、刷新后按服务器真源回落 chime。回滚：profile specifier 恢复 file:/root/dsh-notify-sound-0.1.5.tgz + pnpm install + 重启（备份 package.json.bak-pre-notify-016-20260923_224949、pnpm-lock.yaml.bak-pre-notify-016-20260923_224949）。⚠️ 111（0.1.5-rc.1）不受影响（仍走 installSection 旧分支）；本次 host 端改动需重启才生效，111 部署待用户确认。
- 2026-09-22：去掉后台任务（"小任务"）完成提示音（v0.1.5）。用户反馈"小任务完成时也响，只想在一次对话整回合做完时响"。改动：
check() 的后台任务分支只保留 failed → failureSound（注意类，需人介入），completed / killed 一律不响；完成提示仅由会话 running: true → false（回合结束）触发；配置卡文案「完成铃声（回合结束 / 后台任务完成）」→「完成铃声（一次对话整回合结束）」。测试 58 → 60 断言。112（dsh 0.1.7-alpha.1）实测：普通回合结束捕获 chime 振荡器 880/2428.8/1318.5/2637（4 个，栈落在 tone()/ensureContext()）；后台任务结束时刻（sleep 8 退出码 0、sleep 5; exit 3）无任何振荡器；同回合内 agent 被任务完成唤醒后的第二个回合结束仍正常响 chime。⚠️ 验证探针注意： 在 后仍返回默认 440，必须 patch 才能读到真实频率。回滚：profile specifier 恢复 + + 重启（备份 、）。：111 为 link 安装（，原 v0.1.3），复制 v0.1.5 文件后由 热重组 bundle（功能改动全在浏览器端 ，host 半区 仅注释改动）——实测 已是新代码、页面 + ns-card 样式注入、「设置 → 插件 → 提示音」卡片展开渲染 7 下拉 + 2 复选 + 8 按钮（下拉值 ，即用户原服务端配置未被改动）、文案已是「完成铃声（一次对话整回合结束）」、console 0 错误、host 路由 200 且回显 。备份 （回滚： 覆盖回 external 目录）。已打开的页面需刷新（Ctrl+Shift+R）才会加载新 bundle。📦 同批（dist-tag ，账号 ）——其他 mac/win/linux 机器可直接 安装；注意 registry 传播约需 5 分钟（期间 仍显示旧版本、重试 会报 ，均属暂态，勿反复发布）。
📄 License
MIT。音效合成参数与事件检测思路参考 ldchaowin/dsh-plugin-notify-sound（MIT）。
