dsh-notify-me 1.5.3 → 1.6.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 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
 
 ### 新增

package/README.en.md

@@ -53,7 +53,8 @@ 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;
@@ -68,7 +69,7 @@ Open **Settings → Notify me** (refresh the page once after installing):
 ## 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).
@@ -123,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:
@@ -186,7 +193,8 @@ 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;
-- [@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.
+- [@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,7 +53,8 @@ dsh-notify-me 把「监督」和「守在屏幕前」解耦：只在真的出现
 
 - **启用提醒** 主开关：关闭后不再弹系统通知、不播放提示音、也不改标签页标题；
 - **运行环境**（默认自动识别）：按页面协议识别 Web 端 / 桌面端（DSH Desktop，`dsh-app://`），识别不准时可手动指定——桌面端点通知走 `dsh://` 深链抬窗、快捷裁决按钮不可用；Web 端走 `window.focus()` 与 Service Worker 桥。手动覆盖与自动识别不一致时，设置页会明示检测结果；
-- **系统通知 / 提示音 / 音量**：Toast、WebAudio 提示音与音量滑块；
+- **系统通知 / 提示音 / 音量**：Toast、提示音开关与音量滑块；
+- **音效来源**（「需要你」与「回复完成」各自独立选）：内置合成音（默认）/ 自定义音频文件 / 系统通知音。选「自定义音频文件」可在设置页挑一个本地音频（上限 1 MiB，存在浏览器本地，可试听与移除）；选「系统通知音」则完全不播插件音效，通知照发，声音交给操作系统（音色跟着系统通知设置走），此时「试听」会改发一条测试通知——该模式没有插件可播的音，你听到的就是它。任一来源缺文件、读不出来或存不下时自动回落到内置合成音，提醒不会因此变成哑的；
 - **页面打开时也提醒「需要你」**（默认开）与 **页面打开时也提醒「回复完成」**（默认关）；
 - **当前对话不弹通知**（默认开）：等待就发生在你正看着的对话里时只留标题标记，不弹通知也不响音（免得盖住审批卡片）；页面切到后台立刻补发，若你已经处理掉就作废。其它后台会话不受影响；
 - **子代理会话不提醒**（默认开）：后台子代理（subagent）子会话的「需要你」与「回复完成」都不提醒——它们是主对话那一轮的步骤，完成由主对话自己的提醒覆盖；你当前打开的那个子代理会话照常提醒；关掉后恢复逐会话提醒；
@@ -68,7 +69,7 @@ dsh-notify-me 把「监督」和「守在屏幕前」解耦：只在真的出现
 ## 提醒方式
 
 - **系统通知**：经浏览器弹出的系统通知，进 Windows 通知中心或 macOS 通知中心（点击回到提醒所属的对话；审批的通知点按钮直接裁决）
-- **提示音**：WebAudio 合成音（「需要你」与「完成」使用不同音型）
+- **提示音**：默认是 WebAudio 合成音（「需要你」与「完成」使用不同音型）；可在设置里为两类提醒分别换成自定义音频文件，或改成让操作系统播放它自己的通知音
 - **标签页标题标记**：有待处理事项时，标题前出现 `🔔 需要你 · …` / `🔔 Action needed · …`；后台会话**完成但还没看**时出现 `✅ 回复完成 · …` / `✅ Reply finished · …`，打开对应会话（或它再次开跑）即消失。两种标记可同时出现，「需要你」在前；宿主改写标题后标记基于新标题重建
 
 本插件是**浏览器层**实现：DSH 页面需保持打开（最小化/后台即可——那正是它监听的「离开」状态）。
@@ -119,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` 服务：
@@ -182,7 +189,8 @@ npm pack --dry-run               # 预览发布包
 
 - [@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 讨论里的建议，落地由维护者完成；
-- [@EliteOtaku](https://github.com/EliteOtaku) — [#9](https://github.com/chromoany/dsh-notify-me/issues/9)：桌面端抬窗链路（1.5.2）的逐层排查与真实壳三轮复测——确认点通知抬窗 + 切会话稳定生效，并定位出「无用户手势的脚本化注入被 Chromium 静默丢弃」这一复现差异，纠正了最初「沙箱拦死」的判断。
+- [@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
@@ -641,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: [
@@ -663,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) {
@@ -705,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();
@@ -1488,10 +1567,17 @@
       });
     } catch (e) {}
     // keep in sync with package.json "version" on every release
-    api.version = "1.5.3";
+    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;
     };
@@ -1524,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.
@@ -1571,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: "当前对话不弹通知",
@@ -1625,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",
@@ -1689,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() {
@@ -1734,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();
@@ -1812,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" }, [
@@ -1854,10 +2133,11 @@
               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"))
           ]),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-notify-me",
-  "version": "1.5.3",
+  "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",