dsh-notify-me 1.5.2 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,45 @@
 
 All notable changes to **dsh-notify-me** are documented here.
 
+## [1.6.0] — 2026-10-15
+
+### 新增
+- **设置页可选音效来源**（`soundDone` / `soundAttention`，「需要你」与「回复完成」各自独立）：
+  - `'synth'`（默认）——原有 WebAudio 合成音，行为不变；
+  - `'custom'`——自选一个本地音频文件（上限 1 MiB，可试听、可移除），提醒时播放该文件；
+  - `'system'`——完全不播插件音效，改为把通知以 `silent: false` 发出，交由操作系统播放它自己的通知音（Windows 通知中心／macOS 通知中心），音色跟着系统通知设置走。
+- 设置页新增「音效来源」卡片：两类提醒各一行来源下拉 + 「试听」，选「自定义音频文件」时展开文件选择、已选文件名与体积、「试听」「移除」。
+- `window.__dshNotifyMe.debug()` 新增 `soundDone` / `soundAttention`（当前生效来源）与 `customSoundDone` / `customSoundAttention`（该类别是否已存自选文件）。
+
+### 变更
+- **通知的 `silent` 不再硬编码为 `true`**：改为 `!systemCue(kind)`。默认两种模式仍是 `silent: true`（插件自己出声，避免与平台提示音叠成两声），只有 `'system'` 模式主动让平台出声。主开关 `sound: false` 仍会连系统通知音一起静音——关掉声音就该是安静的。
+- 自选音频存在**独立的 localStorage 键**（`dshNotifyMe.sound.done` / `dshNotifyMe.sound.attention`，值为 `{name, size, data}`），不塞进 `dshNotifyMe.config`：data URL 会膨胀约 1.37 倍，进配置会拖慢每次 `readConfig()`（每次提醒都会调用）。
+- `resetConfig()` 与设置页「恢复默认设置」现在**一并清掉**这两个音频键，不再只清配置——否则文件会残留占用 origin 配额，而 UI 上已经没有入口能删它。
+- **任何来源取不到声音都回落到内置合成音**（文件缺失、解码/自动播放被拒、超出配额），提醒不会因为音效配置坏掉而变成哑的。
+- 版本号 1.5.3 → 1.6.0；`window.__dshNotifyMe.version` 与 `package.json` 同步。
+- README（中英）同步：设置清单加「音效来源」，控制台配置块补 `soundDone` / `soundAttention` 与两个存储键的说明。
+
+### 修复
+- **「系统通知音」模式下点「试听」不再静默无反应**：该模式本就没有插件可播的音（声音是随通知由系统播放的），而初版实现让试听照样走插件音效通道、在 `'system'` 分支直接返回，按钮看起来就是坏的。现在改为按该类别**发一条测试通知**——你听到的就是它，并在按钮下方写明原因；`sound` 总开关关闭时同样给一句说明而不是静默。
+
+### 测试
+- `smoke/smoke-test.cjs` 新增音效来源用例段（**此前音效路径零覆盖**——harness 的 `AudioContext` 是 `undefined`，所有既有用例都静默走了「无音频」分支）：注入可捕获的 `AudioContext` 后，覆盖内置合成音的两种音型（done `659,988`、attention `880,1174,1568`）、`'system'` 不产生振荡器且通知 `silent === false`、`sound: false` 在 `'system'` 模式下重新静音、`'custom'` 播放所存 data URL 且音量跟随滑块、两类来源互不影响、文件缺失或浏览器拒绝播放（`play()` 异步拒绝）时回落内置音、`resetConfig()` 清空两个音频键。
+- 同一文件新增设置页渲染用例：`bootBundle` 支持注入 `require`（此前固定返回 `{}`，设置页永不注册、无法被测试），用例断言 `settings.section` 注册成功、「音效来源」两张卡片渲染、`custom` 时才出现文件选择行并显示文件名与体积，以及**按下 `'system'` 行的「试听」确实发出一条 `silent === false` 的测试通知**（为此假 React 改为按索引跨渲染保持 hook 状态，能读到点击后的反馈文案）；默认路径（不注入 react）行为不变。
+- `npm test` 两套件均通过；`smoke/cordis-host-test.mjs` 用 `DSH_NODE_MODULES` 指向本机 DSH 安装后**真跑**（此前在多数机器上静默 SKIP），真 cordis 下的 `inject` 语义守卫一并复核通过。
+
+## [1.5.3] — 2026-10-04
+
+### 新增
+- **设置页底部常显插件版本号**（`dsh-notify-me v…`，中英跟随界面语言）：报障、核对是否装上新版本时直接照抄这一行，不必再开控制台查 `window.__dshNotifyMe.version`（该字段保留）。
+
+### 变更
+- 版本号 1.5.2 → 1.5.3；`window.__dshNotifyMe.version` 同步。
+- README（中英）：「桌面端怎么抬窗的 / How the Desktop window gets raised」补真实壳复测结论与触发时机口径——深链必须在带用户手势的处理器里发（通知 `onclick` 自带手势，产品路径通）；无手势的脚本化注入会被 Chromium 静默丢弃、外部协议不回流，复现时看似「通道被拦死」。致谢名单新增 [@EliteOtaku](https://github.com/EliteOtaku)（issue #9 的逐层排查与三轮真实壳复测）。
+
+### 核实
+- issue #9 真实壳三轮复测（DSH Desktop 0.2.0-rc.2 / Windows 11）：点通知 = 抬窗 + 切会话一步到位，同会话、跨会话、窗口在后台均稳定 ✅，1.5.2 的抬窗修复确认生效。
+- 修正 1.5.2 发布当天「CDP 注入 iframe 导航 0 新进程 ⇒ 沙箱 renderer 拦截外部协议」的判断：从发行包 `lib/main.js` 逐处核对，壳对主窗口既没有 `will-frame-navigate` 拦截、页面无 CSP，非 media 权限（含 `openExternal`）一律放行；真实差异在**用户手势上下文**，与渲染进程的 OS 沙箱无关（OS 沙箱 ≠ iframe 的 `sandbox` 属性，GHSA-p2rr-rvmm-c5fp 只影响后者）。
+
 ## [1.5.2] — 2026-10-04
 
 ### 新增

package/README.en.md

@@ -53,21 +53,23 @@ Open **Settings → Notify me** (refresh the page once after installing):
 
 - **Enable reminders** — master switch; when off, no toasts, no sounds and the tab title is never touched;
 - **Environment** (auto-detect by default) — identifies Web vs Desktop (DSH Desktop, `dsh-app://`) from the page protocol, with a manual override for hosts where detection comes out wrong: on the Desktop a toast click rides the `dsh://` deep link to raise the window and quick-decision buttons are unavailable; on the Web it is `window.focus()` plus the Service Worker bridge. Whenever the override disagrees with detection, the settings page says what detection saw;
-- **System notifications / Sound / Volume** — toast toggle, WebAudio beep toggle and a volume slider;
+- **System notifications / Sound / Volume** — toast toggle, cue toggle and a volume slider;
+- **Alert sound** (picked separately for "needs you" and "reply finished") — built-in cue (default) / custom audio file / system notification sound. "Custom audio file" takes one local audio file in the settings page (1 MiB limit, stored in the browser, with preview and remove); "system notification sound" plays no plugin cue at all — the toast still appears and the operating system supplies the sound, so its timbre follows your system notification settings; in that mode "Preview" sends a test alert instead, because the sound only exists as part of a toast and that is the sound you hear. Any source that has no file, cannot be read, or does not fit falls back to the built-in cue, so an alert never goes silent;
 - **"Needs you" alerts while the page is open** (default on) and **"Reply finished" alerts while the page is open** (default off);
 - **Stay quiet for the conversation on screen** (default on): a wait inside the conversation you are looking at keeps only the tab marker — no toast or sound landing on the approval card. Backgrounding the page puts that alert back at once, unless you already handled it. Waits in other background sessions are unaffected;
 - **Ignore subagent sessions** (default on): background subagent child sessions raise neither "needs you" nor "reply finished" — those are steps of the parent conversation's turn, and the parent's own alert already covers them. The subagent session you have open alerts as usual. Turn it off to alert for every session;
 - **Click a toast to open that conversation** (default on): clicking brings DSH to the front and switches to the conversation the alert came from. With several DSH tabs open, one click raises exactly one window (a visible one first) and switches only that one — the others stay put; when off, clicking a toast does nothing. On the Desktop (DSH Desktop) the click likewise raises the window and switches conversations: page-side `window.focus()` cannot raise a native Electron window, so since 1.5.2 the plugin rides the app's own `dsh://open` deep link instead (a window hidden to the tray comes back too);
 - **Decide approvals from the toast** (default on): approval notifications carry Approve / Reject buttons, and one click settles the request exactly like the Allow once / Reject buttons on the approval card. Clicking the toast body still takes you back to the conversation. **Buttons are unavailable on the Desktop** (`dsh-app://` pages cannot register a Service Worker): approval toasts fall back to their buttonless form there, and the settings page says so;
 - **Notification language** — follow the interface / 简体中文 / English: controls the language of the alert text and the `🔔 …` title marker;
-- **Test buttons** — send one "needs you", "reply finished" or "approval buttons" test alert with the current settings (**not** limited by the "while the page is open" toggles; the "needs you" test's title marker clears itself after ~6s).
+- **Test buttons** — send one "needs you", "reply finished" or "approval buttons" test alert with the current settings (**not** limited by the "while the page is open" toggles; the "needs you" test's title marker clears itself after ~6s);
+- **Version info** — the settings page always shows the installed plugin version at its foot (`dsh-notify-me v…`); quote that line in bug reports or to check which build you are on.
 
 > Notification permission is required: click once on the page → **Allow** (or address-bar lock → Site settings → Notifications → Allow → reload). On macOS, also allow the browser under System Settings → Notifications.
 
 ## How it alerts
 
 - **System notification** — a toast through the browser into the Windows action center / macOS Notification Center (clicking it opens the conversation it came from; approval toasts can be decided straight from the buttons)
-- **Sound** — WebAudio beeps (distinct patterns for "needs you" vs "done")
+- **Sound** — WebAudio beeps by default (distinct patterns for "needs you" vs "done"); each kind can instead play a picked audio file, or hand the sound over to the operating system's own notification sound
 - **Tab title marker** — while something is waiting on you, the tab title is prefixed with `🔔 Action needed · …` / `🔔 需要你 · …`; while a background session is **finished but unread**, with `✅ Reply finished · …` / `✅ 回复完成 · …`, gone once you open that session (or it starts running again). Both kinds can be up together, "needs you" first; a host title change is rebased under the markers
 
 This is a **browser-layer** plugin: the DSH page must stay open (minimized or backgrounded is fine — that's exactly the "away" state it watches for).
@@ -122,15 +124,21 @@ window.__dshNotifyMe.setConfig({
   doneHiddenOnly: true,       // false = also alert "reply finished" while visible
   ignoreSubagent: true,       // true = never alert for background subagent sessions (the open one is exempt)
   toast: true,                // system-notification toggle
-  sound: true,                // sound toggle
+  sound: true,                // cue toggle (also governs the "system notification sound" mode)
+  soundDone: "synth",         // "reply finished" cue source: 'synth' built-in | 'custom' picked file | 'system' OS sound
+  soundAttention: "synth",    // "needs you" cue source, same values
   volume: 0.5,                // 0..1
   autoFocus: true,            // clicking a toast opens the conversation it came from
   quickActions: true          // Approve / Reject buttons on approval toasts
 })
-window.__dshNotifyMe.resetConfig()                // restore defaults
+window.__dshNotifyMe.resetConfig()                // restore defaults (also drops any picked audio files)
 window.__dshNotifyMe.decide("approval:3", "allowed-once")  // programmatic decision: "allowed-once" | "rejected"
 ```
 
+> Picked audio files do not live in `dshNotifyMe.config`: each kind gets its own key (`dshNotifyMe.sound.done` / `dshNotifyMe.sound.attention`, holding `{name, size, data}` with a data URL), because a file inflates by ~1.37x once base64-encoded and would slow down every config read. `resetConfig()` clears both keys along with the config.
+>
+> To see which source is live, check `soundDone` / `soundAttention` and `customSoundDone` / `customSoundAttention` in `window.__dshNotifyMe.debug()`.
+
 ## How it works
 
 The reminder core picks its interaction source per host generation (see the table above); the current session always comes from the client `sessions` service:
@@ -152,6 +160,8 @@ Every button toast is booked against its interaction key, so it can only decide
 
 DSH Desktop is a thin Electron shell and its page lives under `dsh-app://app`: DOM `window.focus()` only touches the browsing-context window, never the native one, and the shell's `will-navigate` / window-open handlers block every ordinary way for the page to fire a `dsh://` URL — so through 1.5.1 a toast click switched the conversation in the background but never brought the window forward. Since 1.5.2 a body click navigates a hidden iframe to `dsh://open`: subframe navigations pass the shell's `will-navigate` interception, the URL reaches the OS protocol registration, and the app's single-instance owner runs its own `focusPrimaryWindow()` (restore + show + focus) — the same path the login completion page uses to bring the client forward. A window hidden to the tray, buried under others, or minimized all come back. Browsers are unaffected and still use `window.focus()` / the worker's `client.focus()`.
 
+Verified on the real shell (DSH Desktop 0.2.0-rc.2, three rounds of retesting in issue #9): a toast click raises the window and switches the conversation in one step, stable across sessions and with the window in the background. Timing of the fire is what makes the chain work: the deep link must be launched from a **user-gesture handler** — the notification's `onclick` carries one, which is why the product path works — while gesture-less scripted injection (an iframe appended from a CDP evaluate, say) is silently dropped by Chromium and the external protocol never launches, which looks exactly like the channel being blocked.
+
 ## Known limitations
 
 - The page must be open for alerts to fire (background tab / minimized is fine; closing the tab stops it — that's inherent to a browser-layer plugin).
@@ -179,10 +189,12 @@ npm pack --dry-run               # preview the published tarball
 
 ## Credits & how contributions land
 
-Contributors (by handle; the linked PR is their change):
+Contributors (by handle; the link points at the PR / issue they worked on):
 
 - [@AgMahone](https://github.com/AgMahone) — [#7](https://github.com/chromoany/dsh-notify-me/pull/7): the 0.1.6+ / 0.2.0 host-generation support, plus the double-chime and cordis-lookup reports and retesting;
-- [@d0ublecl1ck](https://github.com/d0ublecl1ck) — [#8](https://github.com/chromoany/dsh-notify-me/pull/8): muting subagent sessions (`ignoreSubagent`) with its tests and docs; the 1.4.0 refinement — mute only background subagents, alert as usual for the one you have open — is his suggestion from the #8 discussion, landed by the maintainer.
+- [@d0ublecl1ck](https://github.com/d0ublecl1ck) — [#8](https://github.com/chromoany/dsh-notify-me/pull/8): muting subagent sessions (`ignoreSubagent`) with its tests and docs; the 1.4.0 refinement — mute only background subagents, alert as usual for the one you have open — is his suggestion from the #8 discussion, landed by the maintainer;
+- [@EliteOtaku](https://github.com/EliteOtaku) — [#9](https://github.com/chromoany/dsh-notify-me/issues/9): the layer-by-layer investigation and three rounds of real-shell retesting of the desktop raise path (1.5.2) — confirming that a toast click raises the window and switches conversations reliably, and pinning down the reproduction difference ("gesture-less scripted injection is silently dropped by Chromium"), which corrected the initial "the sandbox blocks it" reading;
+- [@Wh1stle05](https://github.com/Wh1stle05) — [#10](https://github.com/chromoany/dsh-notify-me/pull/10): the per-kind alert sound source (built-in synth / picked audio file / system notification sound, chosen independently for "needs you" and "reply done"), with its settings UI, fallback chain, tests and docs; the two refinements — a "system" preview sending a real test notification instead of doing nothing, and the fake React holding hook state by index across renders — come from the same PR.
 
 Attribution policy: external PRs are landed as maintainer commits — the original commit is not reused and no Co-authored-by trailer is added, so GitHub's contributors graph lists the maintainer only and contributors are credited above.
 

package/README.md

@@ -53,21 +53,23 @@ dsh-notify-me 把「监督」和「守在屏幕前」解耦：只在真的出现
 
 - **启用提醒** 主开关：关闭后不再弹系统通知、不播放提示音、也不改标签页标题；
 - **运行环境**（默认自动识别）：按页面协议识别 Web 端 / 桌面端（DSH Desktop，`dsh-app://`），识别不准时可手动指定——桌面端点通知走 `dsh://` 深链抬窗、快捷裁决按钮不可用；Web 端走 `window.focus()` 与 Service Worker 桥。手动覆盖与自动识别不一致时，设置页会明示检测结果；
-- **系统通知 / 提示音 / 音量**：Toast、WebAudio 提示音与音量滑块；
+- **系统通知 / 提示音 / 音量**：Toast、提示音开关与音量滑块；
+- **音效来源**（「需要你」与「回复完成」各自独立选）：内置合成音（默认）/ 自定义音频文件 / 系统通知音。选「自定义音频文件」可在设置页挑一个本地音频（上限 1 MiB，存在浏览器本地，可试听与移除）；选「系统通知音」则完全不播插件音效，通知照发，声音交给操作系统（音色跟着系统通知设置走），此时「试听」会改发一条测试通知——该模式没有插件可播的音，你听到的就是它。任一来源缺文件、读不出来或存不下时自动回落到内置合成音，提醒不会因此变成哑的；
 - **页面打开时也提醒「需要你」**（默认开）与 **页面打开时也提醒「回复完成」**（默认关）；
 - **当前对话不弹通知**（默认开）：等待就发生在你正看着的对话里时只留标题标记，不弹通知也不响音（免得盖住审批卡片）；页面切到后台立刻补发，若你已经处理掉就作废。其它后台会话不受影响；
 - **子代理会话不提醒**（默认开）：后台子代理（subagent）子会话的「需要你」与「回复完成」都不提醒——它们是主对话那一轮的步骤，完成由主对话自己的提醒覆盖；你当前打开的那个子代理会话照常提醒；关掉后恢复逐会话提醒；
 - **点击通知回到对应对话**（默认开）：点通知把 DSH 带到前台并切到提醒所属的对话；多个 DSH 标签页同时开着时，一次点击只调起一个窗口（优先当前可见的那个）并只切它的对话，其余标签页不动；关掉后点通知不做任何事。桌面端（DSH Desktop）同样会把窗口带到前台并切对话：页面侧的 `window.focus()` 在 Electron 里抬不动原生窗口，1.5.2 起改走应用自己的 `dsh://open` 深链调窗（窗口隐藏在托盘里也能被抬回来）；
 - **审批通知上直接裁决**（默认开）：权限审批的通知上带「同意 / 拒绝」按钮，点一下就按审批卡片的「允许一次 / 拒绝」直接裁决，不用切回页面；点通知正文仍是原来的「切回对应对话」。**桌面端暂不支持按钮**（`dsh-app://` 页面无法注册 Service Worker），审批通知自动退回无按钮样式，设置页会明示这一限制；
 - **通知语言**：跟随界面 / 简体中文 / English——决定通知文字与 `🔔 …` 标题标记使用的语言；
-- **测试按钮**：用当前设置立即发一条「需要你」「回复完成」或「审批按钮」测试提醒（**不受**上面「页面打开时也提醒」开关限制；「需要你」测试的标题标记约 6 秒后自动消失）。
+- **测试按钮**：用当前设置立即发一条「需要你」「回复完成」或「审批按钮」测试提醒（**不受**上面「页面打开时也提醒」开关限制；「需要你」测试的标题标记约 6 秒后自动消失）；
+- **版本信息**：设置页底部常显当前插件版本号（`dsh-notify-me v…`）——报障、核对是否装上新版本时直接照抄这一行。
 
 > 需要浏览器通知权限：页面上点一下 → 允许；或地址栏锁 → 站点设置 → 通知 → 允许 → 刷新。macOS 还要在 系统设置 → 通知 里允许该浏览器。
 
 ## 提醒方式
 
 - **系统通知**：经浏览器弹出的系统通知，进 Windows 通知中心或 macOS 通知中心（点击回到提醒所属的对话；审批的通知点按钮直接裁决）
-- **提示音**：WebAudio 合成音（「需要你」与「完成」使用不同音型）
+- **提示音**：默认是 WebAudio 合成音（「需要你」与「完成」使用不同音型）；可在设置里为两类提醒分别换成自定义音频文件，或改成让操作系统播放它自己的通知音
 - **标签页标题标记**：有待处理事项时，标题前出现 `🔔 需要你 · …` / `🔔 Action needed · …`；后台会话**完成但还没看**时出现 `✅ 回复完成 · …` / `✅ Reply finished · …`，打开对应会话（或它再次开跑）即消失。两种标记可同时出现，「需要你」在前；宿主改写标题后标记基于新标题重建
 
 本插件是**浏览器层**实现：DSH 页面需保持打开（最小化/后台即可——那正是它监听的「离开」状态）。
@@ -118,15 +120,21 @@ window.__dshNotifyMe.setConfig({
   doneHiddenOnly: true,       // false = 页面可见时「完成」也提醒
   ignoreSubagent: true,       // true = 后台子代理（subagent）会话不提醒（当前打开的照常）
   toast: true,                // 系统通知开关
-  sound: true,                // 提示音开关
+  sound: true,                // 提示音开关（含「系统通知音」模式）
+  soundDone: "synth",         // 「完成」音效来源：'synth' 内置 | 'custom' 自定义文件 | 'system' 系统通知音
+  soundAttention: "synth",    // 「需要你」音效来源，取值同上
   volume: 0.5,                // 音量 0~1
   autoFocus: true,            // 点通知回到提醒所属的对话
   quickActions: true          // 审批通知上的「同意 / 拒绝」按钮
 })
-window.__dshNotifyMe.resetConfig()                // 恢复默认
+window.__dshNotifyMe.resetConfig()                // 恢复默认（同时清掉已选的自定义音效文件）
 window.__dshNotifyMe.decide("approval:3", "allowed-once")  // 程序化裁决："allowed-once" | "rejected"
 ```
 
+> 自定义音效文件不在 `dshNotifyMe.config` 里，而是按类别各存一个键（`dshNotifyMe.sound.done` / `dshNotifyMe.sound.attention`，内容是 `{name, size, data}` 的 data URL）——一个文件转成 data URL 会膨胀约 1.37 倍，塞进配置会拖慢每次读取。`resetConfig()` 会连这两个键一起清掉。
+>
+> 想确认当前生效的来源，看 `window.__dshNotifyMe.debug()` 的 `soundDone` / `soundAttention` 与 `customSoundDone` / `customSoundAttention`。
+
 ## 工作原理
 
 提醒核心按宿主代际取源（见上表），当前会话一律来自客户端 `sessions` 服务：
@@ -148,6 +156,8 @@ window.__dshNotifyMe.decide("approval:3", "allowed-once")  // 程序化裁决：
 
 DSH Desktop 是一层 Electron 壳，页面跑在 `dsh-app://app` 下：DOM 的 `window.focus()` 只动浏览器窗口对象、碰不到原生窗口，壳的 `will-navigate` / `window-open` 又把页面里发 `dsh://` 的常规出口全堵上了——所以 1.5.1 及以前点通知只在后台切好对话，窗口不上前台。1.5.2 起点通知正文时页面发一条隐藏 iframe 导航到 `dsh://open`：子框架导航不经过壳的 `will-navigate` 拦截，URL 交给系统协议注册，应用的单实例锁收到第二次启动后走 `focusPrimaryWindow()`（restore + show + focus）——与登录完成页把客户端置前是同一条路。窗口隐藏在托盘、被别的窗口压住、最小化，都能被抬回来。浏览器端不受影响，仍走 `window.focus()` / worker `client.focus()`。
 
+真实壳已实测（DSH Desktop 0.2.0-rc.2，issue #9 三轮复测）：点通知 = 抬窗 + 切会话一步到位，跨会话、窗口在后台时同样稳定。触发时机是这条链路的关键：深链必须在**带用户手势的处理器**里发——通知的 `onclick` 自带手势，所以产品路径通；而无手势的脚本化注入（如 CDP evaluate 手工塞 iframe）会被 Chromium 静默丢弃、外部协议根本不回流，复现时看起来就像「通道被拦死」。
+
 ## 已知限制
 
 - 页面必须开着才会提醒（后台标签/最小化可以；关标签页即失效——浏览器层方案固有限制）。
@@ -175,10 +185,12 @@ npm pack --dry-run               # 预览发布包
 
 ## 致谢与贡献须知
 
-贡献者（按 handle 列出，对应 PR 就是他们提的改动）：
+贡献者（按 handle 列出，链接指向他们参与的 PR / issue）：
 
 - [@AgMahone](https://github.com/AgMahone) — [#7](https://github.com/chromoany/dsh-notify-me/pull/7)：0.1.6+ / 0.2.0 宿主代际支持，以及通知双响、cordis 查找路径的报障与复测；
-- [@d0ublecl1ck](https://github.com/d0ublecl1ck) — [#8](https://github.com/chromoany/dsh-notify-me/pull/8)：子代理会话静音（`ignoreSubagent`）与配套测试、文档；1.4.0 里「只静音后台子代理、当前打开的照常提醒」的口径同样出自他在 #8 讨论里的建议，落地由维护者完成。
+- [@d0ublecl1ck](https://github.com/d0ublecl1ck) — [#8](https://github.com/chromoany/dsh-notify-me/pull/8)：子代理会话静音（`ignoreSubagent`）与配套测试、文档；1.4.0 里「只静音后台子代理、当前打开的照常提醒」的口径同样出自他在 #8 讨论里的建议，落地由维护者完成；
+- [@EliteOtaku](https://github.com/EliteOtaku) — [#9](https://github.com/chromoany/dsh-notify-me/issues/9)：桌面端抬窗链路（1.5.2）的逐层排查与真实壳三轮复测——确认点通知抬窗 + 切会话稳定生效，并定位出「无用户手势的脚本化注入被 Chromium 静默丢弃」这一复现差异，纠正了最初「沙箱拦死」的判断；
+- [@Wh1stle05](https://github.com/Wh1stle05) — [#10](https://github.com/chromoany/dsh-notify-me/pull/10)：「音效来源」功能（内置合成音 / 自定义音频文件 / 系统通知音，「需要你」与「回复完成」各自独立选），含设置页交互、回落链与测试、文档；「系统通知音」试听改发测试通知、假 React 按索引跨渲染保持 hook 状态这两处修正同样出自该 PR。
 
 署名口径：本仓库收编外部 PR 时以维护者提交落地——不沿用原 commit、不挂 Co-authored-by，GitHub 的 contributors 图只显示维护者，贡献者以上面的致谢署名。
 

package/lib/client.js

@@ -239,6 +239,15 @@
       ignoreSubagent: true,
       toast: true,
       sound: true,
+      // Where each alert's cue comes from (per kind, so "needs you" and "reply
+      // finished" stay independent):
+      //   'synth'  — the built-in WebAudio cue (default, needs no asset)
+      //   'custom' — an audio file the user picked, kept in its own
+      //              localStorage key and played through an <audio> element
+      //   'system' — no plugin cue at all: the toast is raised un-silenced so
+      //              the operating system plays its own notification sound
+      soundDone: "synth",
+      soundAttention: "synth",
       volume: 0.5,
       autoFocus: true, // clicking the toast raises DSH and switches to the alerted conversation
       // Approval toasts carry 同意/拒绝 buttons and settle the request on one
@@ -272,6 +281,38 @@
       return config;
     }
 
+    // Picked cue files live in their own localStorage keys, never inside the
+    // config JSON: a data URL is ~1.37x the file size, and the config is parsed
+    // on every readConfig() — which happens on every alert.
+    var LS_SOUND = { done: "dshNotifyMe.sound.done", attention: "dshNotifyMe.sound.attention" };
+    // 1 MiB of source audio is ~1.37 MiB once base64-encoded; localStorage
+    // grants ~5 MiB per origin, and the other kind plus the config must fit too.
+    var SOUND_MAX_BYTES = 1048576;
+    function soundMode(kind) {
+      var v = kind === "attention" ? config.soundAttention : config.soundDone;
+      return (v === "custom" || v === "system") ? v : "synth";
+    }
+    // True when the platform, not this plugin, should make the noise: only then
+    // is the toast raised un-silenced. The master Sound switch still mutes it.
+    function systemCue(kind) { return config.sound && soundMode(kind) === "system"; }
+    function readSound(kind) {
+      try {
+        var raw = localStorage.getItem(LS_SOUND[kind]);
+        if (!raw) return null;
+        var rec = JSON.parse(raw);
+        return (rec && typeof rec.data === "string" && rec.data) ? rec : null;
+      } catch (e) { return null; }
+    }
+    // false = the record did not fit (quota) or storage is unavailable; the
+    // caller reports it and the previous record stays in place.
+    function writeSound(kind, rec) {
+      try {
+        if (rec) localStorage.setItem(LS_SOUND[kind], JSON.stringify(rec));
+        else localStorage.removeItem(LS_SOUND[kind]);
+        return true;
+      } catch (e) { return false; }
+    }
+
     // ───────────────────────── copy tables ─────────────────────────
     // Notification copy, keyed by language id. Selected through
     // effectiveLang() so a pinned language stays pinned even while the DSH UI
@@ -389,6 +430,15 @@
     // the protocol registration, and the single-instance owner restores,
     // shows and focuses the window — the same path the login completion page
     // uses to bring DSH forward.
+    //
+    // Verified on the real shell (DSH Desktop 0.2.0-rc.2, issue #9): a click
+    // on the notification raises the window and switches the conversation in
+    // one step, reproducibly. The fire must sit in a user-gesture context —
+    // the page-side Notification onclick carries one, and Chromium drops
+    // external-protocol navigations launched without it. That is also why
+    // gesture-less injections (CDP evaluate, scripted iframe appends) silently
+    // produce no protocol launch at all, which read like the channel being
+    // blocked when the gesture was the only difference.
     function raiseWindow() {
       try { window.focus(); } catch (e) {}
       if (!isDesktopShell()) return;
@@ -632,8 +682,10 @@
               body: body || "",
               tag: tag,
               renotify: true,
-              // The plugin owns the audio (see showToast's silent note below).
-              silent: true,
+              // The plugin owns the audio (see showToast's silent note below),
+              // except in the 'system' cue mode, which hands the sound back to
+              // the platform on purpose.
+              silent: !systemCue(kind),
               icon: (location.origin || "") + "/favicon.svg",
               data: { key: quick.key, sessionId: sessionId || null, kind: kind, test: !!quick.test, focus: config.autoFocus !== false },
               actions: [
@@ -654,8 +706,10 @@
           // The plugin owns the audio: its WebAudio cues already differ per
           // kind (attention vs done) and answer the Sound toggle and volume
           // slider. Without this flag the platform plays its own chime on top
-          // of the beep — two sounds stacked on one alert.
-          silent: true,
+          // of the beep — two sounds stacked on one alert. The single exception
+          // is the 'system' cue mode, which is precisely "let the platform play
+          // it"; the master Sound switch still mutes that too.
+          silent: !systemCue(kind),
           icon: (location.origin || "") + "/favicon.svg"
         });
         if (config.autoFocus) {
@@ -696,18 +750,52 @@
         osc.stop(t0 + durMs / 1000 + 0.05);
       } catch (e) {}
     }
-    function playAttentionSound() {
+    // 'custom' plays the file the user picked. Anything short of a started
+    // element — no file stored, a browser without the element, a constructor or
+    // play() that throws — falls through to the built-in cue, so an alert is
+    // never silent merely because a stored file went missing or unreadable.
+    // The last failure mode is different in kind: a decode or autoplay refusal
+    // rejects play()'s promise instead of throwing, so it gets the built-in cue
+    // handed to it as a fallback rather than falling through.
+    function playCustomSound(kind, fallback) {
+      var rec = readSound(kind);
+      if (!rec) return false;
+      try {
+        var el = new Audio(rec.data);
+        el.volume = Math.max(0, Math.min(1, config.volume));
+        var started = el.play();
+        if (started && typeof started.catch === "function") started.catch(fallback);
+        return true;
+      } catch (e) { return false; }
+    }
+    // 'system' returns silently on purpose: showToast raises the toast
+    // un-silenced for exactly this mode, so the OS plays its own notification
+    // sound and the plugin must not stack a second cue on top of it.
+    function playCue(kind, build) {
       if (!config.sound) return;
-      unlockAudio();
-      tone(880, 0.0, 140, config.volume);
-      tone(1174, 0.16, 140, config.volume);
-      tone(1568, 0.32, 200, config.volume);
+      var mode = soundMode(kind);
+      if (mode === "system") return;
+      function synth() {
+        // An async rejection can land after the user muted everything.
+        if (!config.sound) return;
+        unlockAudio();
+        build();
+      }
+      if (mode === "custom" && playCustomSound(kind, synth)) return;
+      synth();
+    }
+    function playAttentionSound() {
+      playCue("attention", function () {
+        tone(880, 0.0, 140, config.volume);
+        tone(1174, 0.16, 140, config.volume);
+        tone(1568, 0.32, 200, config.volume);
+      });
     }
     function playDoneSound() {
-      if (!config.sound) return;
-      unlockAudio();
-      tone(659, 0.0, 150, config.volume);
-      tone(988, 0.18, 260, config.volume);
+      playCue("done", function () {
+        tone(659, 0.0, 150, config.volume);
+        tone(988, 0.18, 260, config.volume);
+      });
     }
     function unlockOnce() {
       unlockAudio();
@@ -1479,10 +1567,17 @@
       });
     } catch (e) {}
     // keep in sync with package.json "version" on every release
-    api.version = "1.5.2";
+    api.version = "1.6.0";
     api.setConfig = function (patch) { return setConfigLocal(patch); };
     api.resetConfig = function () {
-      try { localStorage.removeItem(LS_CONFIG); } catch (e) {}
+      try {
+        localStorage.removeItem(LS_CONFIG);
+        // The picked cue files are per-kind keys of their own; dropping the
+        // config alone would leave them orphaned, still eating the origin's
+        // quota with no UI left to remove them from.
+        localStorage.removeItem(LS_SOUND.done);
+        localStorage.removeItem(LS_SOUND.attention);
+      } catch (e) {}
       config = readConfig();
       return config;
     };
@@ -1515,6 +1610,10 @@
         ignoreSubagent: config.ignoreSubagent,
         toast: config.toast,
         sound: config.sound,
+        soundDone: soundMode("done"),
+        soundAttention: soundMode("attention"),
+        customSoundDone: !!readSound("done"),
+        customSoundAttention: !!readSound("attention"),
         quickActions: config.quickActions,
         // quick-decision bridge: 'active' is the only state in which approval
         // toasts carry working 同意/拒绝 buttons.
@@ -1562,7 +1661,30 @@
       toast: "系统通知",
       toastHint: "经浏览器弹出系统 Toast（Windows 通知中心）；需要已授予通知权限。",
       sound: "提示音",
-      soundHint: "WebAudio 合成音，「需要你」与「回复完成」使用不同音型。",
+      soundHint: "提示音总开关；具体播什么由下面的「音效来源」决定。",
+      soundSource: "音效来源",
+      soundSourceHint: "两类提醒各自选择声音来源，互不影响。默认是插件自带的内置合成音。",
+      soundDoneLabel: "「回复完成」的声音",
+      soundAttentionLabel: "「需要你」的声音",
+      soundSynth: "内置合成音（默认）",
+      soundCustom: "自定义音频文件",
+      soundSystem: "系统通知音（系统播放）",
+      soundSynthNote: "插件合成音，「需要你」与「回复完成」音型不同。",
+      soundSystemNote: "不播插件音效：通知照发，声音交给操作系统——音色跟着系统通知设置走，开关仍听这里的「提示音」。",
+      soundNone: "尚未选择文件",
+      soundPick: "选择音频文件",
+      soundPreview: "试听",
+      soundClear: "移除",
+      soundTooBig: "文件太大，上限 ",
+      soundNotAudio: "这不是浏览器能播放的音频文件。",
+      soundSaved: "已保存自定义音效：",
+      soundCleared: "已移除自定义音效，该提醒回落到内置合成音。",
+      soundReadFail: "读取文件失败。",
+      soundQuota: "浏览器存储空间不足，存不下这个文件——先移除另一类提醒的自定义音效，或换一个更小的文件。",
+      soundPreviewDone: "试听「回复完成」音效",
+      soundPreviewAttention: "试听「需要你」音效",
+      soundOffHint: "「提示音」开关是关的：先打开它才能试听（关掉时提醒本身也确实不出声）。",
+      soundPreviewSystem: "「系统通知音」是随通知由系统播放的，插件这边没有可播的音；已发一条测试提醒，声音就是它。",
       attentionVisible: "页面打开时也提醒「需要你」",
       attentionVisibleHint: "默认开启：模型在等你审批 / 确认方案 / 回答问题（含提问弹窗）时，即使页面在最前也会提醒。",
       currentQuiet: "当前对话不弹通知",
@@ -1597,7 +1719,8 @@
       resetDone: "已恢复默认设置。",
       sent: "已发送测试提醒 · 通知语言：",
       permHint: "通知权限尚未授予：先在页面上点击一次并允许通知，系统通知才能弹出（提示音不受影响）。",
-      offHint: "已关闭提醒：先打开「启用提醒」再测试。"
+      offHint: "已关闭提醒：先打开「启用提醒」再测试。",
+      versionLine: "插件版本：dsh-notify-me v"
     };
     var UI_en = {
       nav: "Notify me",
@@ -1615,7 +1738,30 @@
       toast: "System notifications",
       toastHint: "Native toasts via the browser (Windows notification center); requires notification permission.",
       sound: "Sound",
-      soundHint: "WebAudio beeps — \"needs you\" and \"reply finished\" use different patterns.",
+      soundHint: "Master cue switch; what it actually plays comes from \"Alert sound\" below.",
+      soundSource: "Alert sound",
+      soundSourceHint: "Each alert kind picks its own sound source; the two never affect each other. The default is the plugin's built-in cue.",
+      soundDoneLabel: "\"Reply finished\" sound",
+      soundAttentionLabel: "\"Needs you\" sound",
+      soundSynth: "Built-in cue (default)",
+      soundCustom: "Custom audio file",
+      soundSystem: "System notification sound (OS plays it)",
+      soundSynthNote: "The plugin's synthesized cue — \"needs you\" and \"reply finished\" use different patterns.",
+      soundSystemNote: "No plugin cue: the toast still appears, but the sound is left to the operating system, so its timbre follows your system notification settings. The Sound switch above still mutes it.",
+      soundNone: "No file chosen yet",
+      soundPick: "Choose an audio file",
+      soundPreview: "Preview",
+      soundClear: "Remove",
+      soundTooBig: "File is too large; the limit is ",
+      soundNotAudio: "That is not an audio file this browser can play.",
+      soundSaved: "Custom sound saved: ",
+      soundCleared: "Custom sound removed; this alert falls back to the built-in cue.",
+      soundReadFail: "Could not read the file.",
+      soundQuota: "Not enough browser storage for this file — remove the other kind's custom sound first, or pick a smaller file.",
+      soundPreviewDone: "Preview the \"reply finished\" sound",
+      soundPreviewAttention: "Preview the \"needs you\" sound",
+      soundOffHint: "The Sound switch is off: turn it on to preview (with it off the alerts themselves stay silent too).",
+      soundPreviewSystem: "The system sound plays with a toast, not from the plugin — a test alert was sent instead; that sound is it.",
       attentionVisible: "Also alert \"needs you\" while the page is open",
       attentionVisibleHint: "On by default: alert even in the foreground when the model waits for approval / plan review / a question.",
       currentQuiet: "Stay quiet for the conversation on screen",
@@ -1650,7 +1796,8 @@
       resetDone: "Defaults restored.",
       sent: "Test alert sent · notification language: ",
       permHint: "Notification permission is not granted yet — click once on the page and allow notifications so toasts can appear (sound is unaffected).",
-      offHint: "Reminders are off: enable them first, then test."
+      offHint: "Reminders are off: enable them first, then test.",
+      versionLine: "Plugin version: dsh-notify-me v"
     };
     // Small element helper to keep the hand-written page readable.
     function h(tag, props) {
@@ -1678,6 +1825,7 @@
       ".dnm-btn:hover{background:var(--dsw-alias-bg-layer-1,rgba(128,128,128,.1))}" +
       ".dnm-btn[disabled]{opacity:.45;cursor:default}" +
       ".dnm-btnRow{display:flex;align-items:center;gap:10px;flex-wrap:wrap}" +
+      ".dnm-file{font-size:12px;font-family:inherit;color:var(--dsw-alias-label-primary,rgba(20,20,20,.9));max-width:200px}" +
       ".dnm-hint{font-size:12px;line-height:18px;color:var(--dsw-alias-label-tertiary,rgba(120,120,120,.9))}" +
       ".dnm-feedback{font-size:12px;line-height:18px;color:var(--dsw-alias-label-tertiary,rgba(120,120,120,.9));min-height:18px}";
     (function injectStyle() {
@@ -1723,9 +1871,137 @@
       var feedbackState = React.useState("");
       var feedback = feedbackState[0];
       var setFeedback = feedbackState[1];
+      // Picked cue files bypass the config object (own localStorage keys), so
+      // the page needs its own nudge to re-read them after a change.
+      var soundBumpState = React.useState(0);
+      var soundBump = soundBumpState[0];
+      var setSoundBump = soundBumpState[1];
       function patch(p) {
         setCfg(setConfigLocal(p));
       }
+      function previewSound(kind) {
+        // The master switch is authoritative here too, so a preview with sound
+        // off has to say why it stayed quiet instead of looking broken.
+        if (!config.sound) { setFeedback(t("soundOffHint")); return; }
+        // 'system' has no cue to play from here: the sound only exists as part
+        // of a toast, which the OS then chimes for. The honest preview is
+        // therefore a real test alert — otherwise the button is silent and
+        // reads as broken.
+        if (soundMode(kind) === "system") {
+          unlockOnce();
+          testAlert(kind);
+          setFeedback(t("soundPreviewSystem"));
+          return;
+        }
+        // Otherwise: the same cue the alert itself will play, volume included.
+        unlockOnce();
+        if (kind === "attention") playAttentionSound();
+        else playDoneSound();
+      }
+      // One row per alert kind. The source select is always there; the file
+      // picker only appears for 'custom', so the page stays short for anyone
+      // who never touches it.
+      function soundRows(kind, labelText) {
+        var modeKey = kind === "attention" ? "soundAttention" : "soundDone";
+        var previewLabel = t(kind === "attention" ? "soundPreviewAttention" : "soundPreviewDone");
+        var mode = soundMode(kind);
+        var rec = readSound(kind);
+        // The hint states what will actually be heard, so a stored file is
+        // named right where the choice is made.
+        var note = mode === "system" ? t("soundSystemNote")
+          : mode === "custom" ? (rec ? rec.name : t("soundNone"))
+            : t("soundSynthNote");
+        var rows = [
+          h("div", { className: "dnm-row" }, [
+            h("div", { className: "dnm-rowText" }, [
+              h("div", { className: "dnm-rowLabel" }, labelText),
+              h("div", { className: "dnm-rowHint" }, note)
+            ]),
+            h("div", { className: "dnm-btnRow" }, [
+              h("select", {
+                className: "dnm-select",
+                value: mode,
+                "aria-label": labelText,
+                onChange: function (e) {
+                  var p = {};
+                  p[modeKey] = e.currentTarget.value;
+                  patch(p);
+                }
+              }, [
+                h("option", { value: "synth" }, t("soundSynth")),
+                h("option", { value: "custom" }, t("soundCustom")),
+                h("option", { value: "system" }, t("soundSystem"))
+              ]),
+              h("button", {
+                type: "button",
+                className: "dnm-btn",
+                disabled: !cfg.enabled,
+                "aria-label": previewLabel,
+                onClick: function () { previewSound(kind); }
+              }, t("soundPreview"))
+            ])
+          ])
+        ];
+        if (mode !== "custom") return rows;
+        rows.push(h("div", { className: "dnm-row" }, [
+          h("div", { className: "dnm-rowText" }, [
+            h("div", { className: "dnm-rowLabel" }, t("soundPick")),
+            h("div", { className: "dnm-rowHint" }, (rec ? Math.round((rec.size || 0) / 1024) + " KB · " : t("soundNone") + " · ")
+              + "≤" + Math.round(SOUND_MAX_BYTES / 1024) + " KB")
+          ]),
+          h("div", { className: "dnm-btnRow" }, [
+            h("input", {
+              type: "file",
+              accept: "audio/*",
+              className: "dnm-file",
+              "aria-label": t("soundPick"),
+              onChange: function (e) {
+                var input = e.currentTarget;
+                var f = input.files && input.files[0];
+                if (!f) return;
+                if (f.size > SOUND_MAX_BYTES) {
+                  // Clear on every exit so re-picking the same file still fires.
+                  input.value = "";
+                  setFeedback(t("soundTooBig") + Math.round(SOUND_MAX_BYTES / 1024) + " KB");
+                  return;
+                }
+                var fr = new FileReader();
+                fr.onload = function () {
+                  input.value = "";
+                  var data = String(fr.result || "");
+                  if (data.indexOf("data:audio/") !== 0) { setFeedback(t("soundNotAudio")); return; }
+                  if (!writeSound(kind, { name: f.name, size: f.size, data: data })) {
+                    setFeedback(t("soundQuota"));
+                    return;
+                  }
+                  setSoundBump(soundBump + 1);
+                  setFeedback(t("soundSaved") + f.name);
+                };
+                fr.onerror = function () { input.value = ""; setFeedback(t("soundReadFail")); };
+                fr.readAsDataURL(f);
+              }
+            }),
+            h("button", {
+              type: "button",
+              className: "dnm-btn",
+              disabled: !rec,
+              "aria-label": previewLabel,
+              onClick: function () { previewSound(kind); }
+            }, t("soundPreview")),
+            h("button", {
+              type: "button",
+              className: "dnm-btn",
+              disabled: !rec,
+              onClick: function () {
+                writeSound(kind, null);
+                setSoundBump(soundBump + 1);
+                setFeedback(t("soundCleared"));
+              }
+            }, t("soundClear"))
+          ])
+        ]));
+        return rows;
+      }
       function runTest(kind) {
         if (!config.enabled) { setFeedback(t("offHint")); return; }
         unlockOnce();
@@ -1801,6 +2077,20 @@
             })
           ])
         ]),
+        // Alert sound source: the built-in cue, a picked file, or the platform's
+        // own notification sound. Kept next to the Sound/volume card so the
+        // sound-related knobs read together, and re-read through soundBump
+        // because picked files live outside the config object.
+        card([].concat(
+          [h("div", { className: "dnm-row" }, [
+            h("div", { className: "dnm-rowText" }, [
+              h("div", { className: "dnm-rowLabel" }, t("soundSource")),
+              h("div", { className: "dnm-rowHint" }, t("soundSourceHint"))
+            ])
+          ])],
+          soundRows("done", t("soundDoneLabel")),
+          soundRows("attention", t("soundAttentionLabel"))
+        )),
         card([
           h("div", { className: "dnm-row" }, [
             h("div", { className: "dnm-rowText" }, [
@@ -1843,17 +2133,21 @@
               h("div", { className: "dnm-rowHint" }, " ")
             ]),
             h("button", { type: "button", className: "dnm-btn", onClick: function () {
-              try { localStorage.removeItem(LS_CONFIG); } catch (e) {}
-              config = readConfig();
+              // api.resetConfig() also drops the picked cue files, which are
+              // stored outside the config.
+              setCfg(api.resetConfig());
               applyTitle();
-              setCfg(config);
+              setSoundBump(soundBump + 1);
               setFeedback(t("resetDone"));
             } }, t("reset"))
           ]),
           !permOK ? h("div", { className: "dnm-row" }, [
             h("div", { className: "dnm-rowText" }, [h("div", { className: "dnm-rowHint" }, t("permHint"))])
           ]) : null
-        ])
+        ]),
+        // Always-visible version line at the page foot: bug reports need it,
+        // and "which build am I on" should not require the console.
+        h("p", { className: "dnm-hint" }, t("versionLine") + api.version)
       ]);
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-notify-me",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "DSH 桌面消息提醒插件：模型需要你操作（审批/方案确认/提问的可操作提醒）或回复在后台完成时，系统通知+提示音+标签页标题提醒你；权限审批的通知上可直接点「同意/拒绝」完成裁决；可在设置页开关并切换通知语言。Desktop notification & message alerts for DeepSeek Harness web — toasts, sounds and a tab-title marker when the agent needs your input (approval / plan review / question) or a reply finishes in the background, Approve/Reject buttons on approval toasts to decide right from the notification; toggleable from Settings with zh/en notification language.",
   "license": "MIT",
   "type": "module",