🔔 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

1. 打开 设置 → 插件配置 → 提示音 卡片
2. 每行下拉选择声音（注意类事件可选「跟随通用注意音」），点「试听」确认
3. 改动即时落盘：其他浏览器 / 设备最迟 30s 内（或切回页面时）同步生效
4. 需要安静时：关「启用提示音」，或只勾「当前正在查看的会话完成时不响铃」（注意类仍会响）

🧪 开发 / 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。⚠️ 验证探针注意：osc.frequency.value 在 setValueAtTime 后仍返回默认 440，必须 patch frequency.setValueAtTime 才能读到真实频率。回滚：profile specifier 恢复 file:/root/dsh-notify-sound-0.1.4.tgz + pnpm install + 重启（备份 package.json.bak-pre-notify-015-20260922_2218、pnpm-lock.yaml.bak-pre-notify-015-20260922_2218）。111（正式机）已热更新部署、未重启服务：111 为 link 安装（/root/.dsh/external/notify-sound，原 v0.1.3），复制 v0.1.5 文件后由 dsh-client-hmr 热重组 bundle（功能改动全在浏览器端 client.js，host 半区 index.js 仅注释改动）——实测 /plugins/??dsh-notify-sound/client.js 已是新代码、页面 body[data-dsh-notify-sound] + ns-card 样式注入、「设置 → 插件 → 提示音」卡片展开渲染 7 下拉 + 2 复选 + 8 按钮（下拉值 ["success","ding","","","","bell","alert"]，即用户原服务端配置未被改动）、文案已是「完成铃声（一次对话整回合结束）」、console 0 错误、host 路由 /notify-sound/settings 200 且回显 defaultSound: success。备份 /root/notify-sound-bak-pre-015-20260922_2245.tgz（回滚：tar -xzf 覆盖回 external 目录）。已打开的页面需刷新（Ctrl+Shift+R）才会加载新 bundle。📦 同批已发布 npm [email protected]（dist-tag latest，账号 npm-liqingfeng）——其他 mac/win/linux 机器可直接 dsh plugin --profile web add dsh-notify-sound 安装；注意 registry 传播约需 5 分钟（期间 npm view 仍显示旧版本、重试 npm publish 会报 E409 previously staged/published version，均属暂态，勿反复发布）。
• 2026-09-19：适配 dsh 0.1.6-alpha.2 的槽位与交互 API 变更（v0.1.4）。该版本移除了 settings.plugin.item 槽（「设置 > 插件配置」TAB 一并移除），并把 uiSession.pendingInteractions 改为 uiSession.sessionStatus，导致 v0.1.3 在新版下配置卡不显示、需人介入提示音失效。改法为双版本兼容：两个槽同时注册（settings.plugin.item 给 ≤0.1.5；plugins.bundle.config 给 0.1.6+，key = 包名 dsh-notify-sound，组件按 owner view 分派 summary/page）；交互源优先取 sessionStatus（status.pendingInteraction），缺失时回退 pendingInteractions。112（dsh 0.1.6-alpha.2）实测通过：插件详情页渲染完整表单（v0.1.4、7 下拉 + 2 复选 + 7 试听）、console 0 错误 0 警告；试听捕获 chime 频率 880/2428.8/1318.5/2637；真实调用 ask_user_question 弹出提问卡片时探针捕获 ding 频率 698.46/1396.92/2102.3646/587.33/1174.66（与「通用注意音 ding」参数完全一致），证明新版 sessionStatus 检测链路生效。测试：宿主 33 + 客户端 58 断言全过（新增 page/summary/legacy 三组用例）。回滚：profile specifier 恢复 file:/root/dsh-notify-sound-0.1.3.tgz + pnpm install + 重启 dsh-web.service（备份 package.json.bak-pre-notify-014-*）
• 2026-09-06：112 部署验证 v0.1.3 通过（本次修复「提问/审批/计划评审/目标受阻」不响）：npm 打包 dsh-notify-sound-0.1.3.tgz + file: 引用装 112（dsh 0.1.2-rc.1），重启 dsh-web.service 后浏览器实测——bundle 加载 200、/notify-sound/settings 200、真实调用 ask_user_question 弹出提问卡片时探针捕获到 ding 合成音（振荡器 5 个、基频 698.46/1396.92/2102.36/587.33/1174.66，与「通用注意音 ding」参数完全一致）、console 0 错误；提交答案后 agent 正常收尾
• 2026-08-16：112（AI-2，192.168.31.112）验证全过——curl：GET 视图（默认值完整）、POST set/unset（用户层落盘 /root/.dsh/settings.yaml、unset 回退 base 默认）、跨站 403 / 坏体 400 / PUT 405；浏览器（playwright-core + chromium headless）18/18：bundle 注入、body[data-dsh-notify-sound] 作用域与样式注入、设置 → 插件配置「提示音」卡片渲染/展开、7 下拉/2 复选/7 试听、默认值 chime·ding·跟随×3·bell·alert、下拉修改 → POST → 服务端持久化、试听真实发声（AudioContext 振荡器探针）、刷新后服务端回显、双页面跨浏览器同步（focus 刷新即跟随）、无 console 错误
• 2026-08-16：样式统一（官方皮肤令牌体系），112 实测 6/6 全过（与主题卡计算样式逐项一致）
• 111（AI 主机，正式使用）已部署：2026-08-16 用户确认后重启 dsh-web.service，验证 5/5 全过（bundle 注入、body 作用域、样式注入、插件配置卡片渲染、无错误）

📄 License

MIT。音效合成参数与事件检测思路参考 ldchaowin/dsh-plugin-notify-sound（MIT）。