只截插件自己的面板（真实组件，与宿主同款深色主题），不带 DSH 左侧导航栏；每行说明在鼠标停在标题文字上时才出现，所以这里只看到标题。

• 音效来源（「需要你」与「回复完成」各自独立选）：内置合成音（默认）/ 自定义音频文件 / 系统通知音。选「自定义音频文件」可在设置页挑一个本地音频（上限 1 MiB，存在浏览器本地，可试听与移除）；选「系统通知音」则完全不播插件音效，通知照发，声音交给操作系统（音色跟着系统通知设置走），此时「试听」会改发一条测试通知——该模式没有插件可播的音，你听到的就是它。任一来源缺文件、读不出来或存不下时自动回落到内置合成音，提醒不会因此变成哑的；

• 外部通知（默认关）：把提醒同时转发到你自己的推送端点，人不在电脑前也能收到——支持 Discord Webhook / Bark / Gotify / 飞书群机器人 / Server酱 / WxPusher / 自定义 Webhook，可加多个目标，每个目标可单独启用/停用（Discord 填 Webhook 地址；Bark 填 https://api.day.app/<设备密钥>；Gotify 填 https://<服务器>/message?token=<应用令牌>；飞书填群机器人 Webhook，可选填签名校验密钥；Server酱 填 …/send/<SendKey>.send 完整地址；WxPusher 填 appToken 与接收者 UID；自定义端点收一条 POST JSON：{source, event, title, body, text, sessionId, time}）；「转发「需要你」」「转发「回复完成」」各自独立开关；发送测试通知往所有目标发一条测试消息（不受这两类开关限制，也不会冒充真提醒）。转发跟本地提醒走同一套触发规则（「当前对话不弹通知」等开关同样管它）；提醒正文会原样发往你填的地址，只填你自己信任的端点；
• 可靠投递：明显是临时故障的失败（网络中断、5xx、429）按 2 秒 / 6 秒自动重试两次，其它错误立即停；重试仍失败会把这一条记进「失败记录」（最多 10 条，只留标题与正文摘要和主机名，不留完整端点），设置页能一眼看到并清空；
• 每个目标的状态：目标行右侧显示它最近一次投递的结果（上次成功 / 上次已送出但不可确认 / 上次失败 + 原因），并各自带一个启停开关——某个端点临时不可用就单独关掉它，不用关掉整类事件；
• 签名：自定义目标填了签名密钥时，请求带 X-DSH-Notify-Signature（对请求体做 HMAC-SHA256，sha256=<hex>）；飞书填了签名密钥时按官方算法在请求体里带 timestamp / sign；
• 消息模板（可选）：飞书 / Server酱 / WxPusher / 自定义目标可填模板，占位符 {{title}} {{body}} {{event}} {{time}} {{session}}，留空默认是「标题 + 换行 + 正文」；
• 钉钉不在支持列表里：钉钉群机器人接口不返回任何 CORS 头，且只接受 application/json——浏览器页面既读不到响应，也无法发出符合要求的请求（no-cors 下 Content-Type 会被限制成 safelisted 类型）。要用钉钉，请在自己能控制的机器上搭一个中转，再把「自定义 Webhook」指向它。

• 通知语言：跟随界面 / 简体中文 / English——决定通知文字与 🔔 … 标题标记使用的语言；
• 桌面端怎么抬窗：页面侧的 window.focus() 在 Electron 里抬不动原生窗口，1.14.0 起由页面 POST 到宿主路由 /__dsh-notify-me/focus-window、宿主跑一次 PowerShell 做原生激活——窗口最小化、被别的窗口盖住都实测能抬回来（详见下一节）；
• 恢复默认设置：把所有开关与音效设置还原成出厂值（不动外部推送目标和已选的自定义音频文件）。

插件按宿主代际自动选源；下表是各形状的边界，不是门禁：

区间仅作示意：插件按 store 形状自动选源（sessionStatus 存在即走新路），版本号只是各形状的出现边界。package.json 的 peerDependencies 范围决定 npm 的 peer 提示——0.2.1-rc.2 已落在 >=0.2.0-rc.1 <0.3.0-0 里，不需要豁免；dshReleases 只是存档，真实兼容性以逐版实测为准，未实测的新版本由形状驱动兜底。

两个坑值得记住：一是 dsh.client.inject 里列了新版运行时已不再提供的包，客户端条目会停在 pending (waiting for services: …) 而永不执行——1.1.3 在 0.1.2-rc.1 及以后正是这样失效的；二是宿主换存储/字段名时不会报错，提醒只会静默失效——0.2.0-rc.2 上 pendingInteractions→sessionStatus、list.current→retainedBy.mainView、sessions.open()→uiWorkspace.openSession() 都是这一类，所以每次适配都要用 window.__dshNotifyMe.debug() 确认真的是 bound、以及用的是哪个来源。0.2.1-rc.2 这两处都没有再变：sessionStatus 仍是 {running, pendingInteraction, completionUnread} 的 Map，uiWorkspace.openSession(id) 照旧，会话列表里仍然没有 current。

window.__dshNotifyMe.config                       // 查看
window.__dshNotifyMe.setConfig({
  enabled: true,           // false = 关闭所有提醒（主开关）
  language: "auto",        // 'auto' 跟随界面 | 'zh' 简体中文 | 'en' English
  attentionHiddenOnly: false, // true = 页面可见时「需要你」不提醒
  currentHiddenOnly: true,    // true = 当前对话的等待只留标题标记（人离开后补发）
  donePolicy: "background",   // 「回复完成」策略：'background' 仅后台 | 'smart' 仅当前对话静默 | 'always' 总是提醒
  idleMinutes: 3,             // 超过多少分钟没有键鼠输入算「离开」（0 = 关掉闲置判定）
  autoDismiss: "present",     // 通知自动消失：'present' 离开时保留 | 'always' 总是关闭 | 'never' 从不关闭
  ignoreSubagent: true,       // true = 后台子代理（subagent）会话不提醒（当前打开的照常）
  sound: true,                // 提示音开关（含「系统通知音」模式）
  soundDone: "synth",         // 「完成」音效来源：'synth' 内置 | 'custom' 自定义文件 | 'system' 系统通知音
  soundAttention: "synth",    // 「需要你」音效来源，取值同上
  volume: 0.5,                // 音量 0~1
  autoFocus: true,            // 点通知回到提醒所属的对话
  quickActions: true,         // 审批通知上的「同意 / 拒绝」按钮
  externalEnabled: false,     // 外部通知转发主开关（默认关：不填端点就什么都不发）
  externalAttention: true,    // 转发「需要你」（触发规则跟本地提醒完全一致）
  externalDone: true,         // 转发「回复完成」
  externalRetryDelays: [2000, 6000], // 可重试失败的退避间隔（毫秒，带抖动；[] = 只发一次）
  externalTargets: []         // 推送目标，见下方字段说明
})
// 目标的形状：{id, type, url, secret?, token?, uid?, template?, enabled?}
// type: 'discord' | 'bark' | 'gotify' | 'feishu' | 'serverchan' | 'wxpusher' | 'custom'
// token/uid 只用于 wxpusher（url 固定为官方端点）；secret 用于飞书签名与自定义 HMAC 签名；
// template 可选，占位符 {{title}} {{body}} {{event}} {{time}} {{session}}；enabled:false 单独停用该目标
window.__dshNotifyMe.resetConfig()                // 恢复默认（同时清掉已选的自定义音效文件）
window.__dshNotifyMe.decide("approval:3", "allowed-once")  // 程序化裁决："allowed-once" | "rejected"
window.__dshNotifyMe.testExternal()               // 显式外发测试：向有效目标发送，返回 {sent, unverified, failed, statuses}

外部通知测试的开关边界：设置页「发送测试通知」要求「启用提醒」与「外部通知」主开关开启，但忽略两类提醒的转发开关。控制台 testExternal() 是显式测试调用：只要配置了有效目标，即使上述主开关关闭，也会向这些目标发送测试消息；没有有效目标则不发送。普通的 test("done") / test("attention") / test("approval") 只测试本地提醒，不外发。

自定义音效文件不在 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 服务：

• 当前会话 SessionSnapshot：running true→false = 回复完成；
• 待办交互：uiSession 的 sessionStatus（≥ 0.1.6，逐会话 pendingInteraction）或 pendingInteractions（0.1.2 .. 0.1.5）出现新 key = 模型在等你，容器里带上审批工具名 / 理由、提问文本；旧宿主回落到控制器快照的 pending[]；
• 其它已列会话摘要：running true→false（或旧宿主的 completed 边沿）= 后台工作提醒。宿主的「完成未读」级别标志负责补漏与标题标记：≥ 0.1.6 用 sessionStatus 行的 completionUnread（后台会话完成即点亮、打开该会话/再次开跑/会话消失即清零），旧宿主用列表行的 completed 提醒位（选中会话即清零）；页面没看见的完成边沿（插件热重载中途、快照合并跳变）由此补报一次，边沿与级别标志同来时按短时间窗合并，只响一声。
• 子代理会话：列表行带 origin: 'subagent'（并有 parentId）的后台会话默认静音；你正打开着的那个子代理会话不算静音对象，它的提醒走当前对话的常规规则（页面可见时默认只留标题标记、转后台补发），切进来时积压的等待同样补上，切走后重新静音。只有 parentId、没有 origin 的分支（fork）会话属于你自己的对话，始终照常提醒。

提醒核心仍然零第三方运行时依赖、完全自包含：通知文字按所选语言（跟随界面 / 中文 / English）即时解析。设置页是可选的 React 呈现层——当 DSH web profile 提供 slots / locale / react 时才注册进「设置 → 通知提醒」，缺任一能力时插件自动降级为纯提醒（无设置页），不影响功能。

快捷裁决怎么走通的

通知按钮（actions）只属于 Service Worker 弹的持久通知，往 new Notification() 里传 actions 会直接抛 TypeError——这是绕不开的浏览器限制。所以 bundle 一份文件干两件事：页面里照常注册提醒工厂，同一份字节再注册成一个只干转信的 Service Worker，把「点了哪个按钮」（同意 / 拒绝 / 点正文）带回页面。真正的裁决发生在页面里，调的是对话里审批「允许一次 / 拒绝」用的同一个 PendingApproval.answer('allowed-once' | 'rejected')，所以「同意」就是「允许一次」，不多放行任何东西。点正文的「调窗口 + 切对话」同样归 worker 这半侧调度：它用 client.focus() 只调起一个窗口（优先当前可见的），并只让那个窗口切对话——多个 DSH 标签页不会互相抢焦点或一起乱切。

每条按钮通知按交互 key 记账，一次只认领一条等待；请求被页面里答掉、或被新请求顶替之后，残留通知上的按钮再点也不会误裁，只是安静地关掉。带按钮的通知停留 12 秒（普通通知 5 秒），到点自动撤；没来得及点就回页面里裁决，对话里的审批一直等着你。

桌面端怎么抬窗的

DSH Desktop 是一层 Electron 壳，页面跑在 dsh-app://app 下：DOM 的 window.focus() 只动浏览器窗口对象、碰不到原生窗口，壳的 will-navigate 又把页面里发 dsh: 的常规出口堵上了。1.5.2 到 1.13.0 靠一条隐藏 iframe 导航到 dsh://open 绕过去，借应用的单实例让位间接聚焦——在 0.2.1-rc.2 上隔离复测 3/3 无效，1.14.0 起整条删掉。

现在走插件自己的宿主路由。壳把 dsh-app://app 下除静态资源以外的所有路径原样转发给宿主 HTTP server（带 origin 校验、注入宿主 cookie），所以页面对 /__dsh-notify-me/focus-window 发 POST 是同源请求，没有 CORS 问题；宿主半（lib/index.js）本来就跑在 Electron 主进程的子进程里，process.ppid 就是主窗口所属的浏览器进程。点通知时：页面 POST → 宿主起一次 powershell.exe 跑 lib/focus-window.ps1 -ProcessId <ppid> → 脚本枚举该 pid 下可见、无 owner、非 toolwindow 的顶层窗口（优先类名 Chrome_WidgetWin_1，再按 GetWindowRect 面积取最大）→ 自适应激活 → 比对 GetForegroundWindow() 打印 FOCUSED=1|0 → 宿主回 200 / 202。

激活顺序是实的，来自 discussions #10446 那份五种手法的实测：已经在前台就什么都不做（最常见的情况，零闪烁）；最小化了先 SW_RESTORE；然后合成一次 ALT 按键（keybd_event 按下抬起）给本线程前台权限，再 SetForegroundWindow；这一串都不行才退到 SW_MINIMIZE + SW_RESTORE 兜底。单独调 SetForegroundWindow 会被前台锁直接拒，按调用算、跟 ForegroundLockTimeout 无关；这也重新解释了 1.5.2 那套深链「时灵时不灵」——能抬起来的那些次，多半是系统在通知被点击时自己激活了应用。

实测（powershell.exe 5.1，同一轮跑完）：窗口在前台 ×3、最小化 + 记事本在前台 ×3、可见但被盖住 ×3，全部 FOCUSED=1 且前台窗口比对一致，最小化那几个的 IsIconic 都从 true 变回 false；记事本最大化完全遮挡、最小化 + 完全遮挡、-ProcessId 0 自动探测同样成功。脚本内部耗时最坏 434 ms，进程启动到退出最坏 782 ms，都在 8 秒上限内；pwsh 7.6 对照一轮行为一致，只是 Add-Type 编译慢约 100 ms（脚本刻意不用 7 的语法）。不存在的 pid、存在但没有可见窗口的 pid 都稳定 FOCUSED=0 并 exit 0。

安全上只开一条 exact 路由。词表之外的请求一律拒：非 GET / HEAD / POST 回 405（包括预检的 OPTIONS，且从不回任何 CORS 头），非桌面宿主（Web 版、macOS / Linux、纯 Node）回 501，缺 x-dsh-notify-me-focus: focus 头回 403。

那个头只是「这是页面发来的」标记，不是防线——DNS rebinding 的恶意页对目标地址而言是同源的，能带任意自定义头、也不触发预检。真正的闸门是三层：对端地址必须是 loopback；Host 必须是 loopback 名（127.0.0.1 / localhost / [::1]，可带端口），因为壳转发时 host 已被删掉、由 fetch 按 loopback URL 重填，而 rebinding 的页面 Host 仍是攻击者域名；带了 Origin 就必须和 Host 同源。任一条不符回 403，reason 分别是 bad-remote / bad-host / cross-origin。GET 只回 {ok, route, enabled, desktop, platform}，装完可以先用浏览器打开确认路由在不在。400 毫秒内的重复调用合并成一次，脚本超过 8 秒没回话就 kill 掉按失败处理。

抬不起来的场合还剩几种，都会如实回 202、对话照常切：目标窗口属于更高完整性级别（提权 / UAC）、窗口在另一个虚拟桌面、前台被别的进程反复抢回去。托盘隐藏（SW_HIDE 而非最小化）的窗口也选不到，DSH 当前不会这样。

已知限制

• 页面必须开着才会提醒（后台标签/最小化可以；关标签页即失效——浏览器层方案固有限制）。

• 通知经由浏览器弹出，需允许浏览器通知权限，且勿扰模式不能屏蔽它。

• 桌面端（DSH Desktop，Windows）点通知后窗口仍可能抬不起来：目标窗口属于更高完整性级别（提权 / UAC）、窗口在另一个虚拟桌面、前台被别的进程反复抢回去、或窗口被 SW_HIDE 隐藏到托盘时，宿主脚本回 FOCUSED=0、路由回 202，对话照常切（详见桌面端怎么抬窗的）。

• 系统通知横幅只画在主屏：Windows 没有设置项、Chromium 没有 API 能把它指到别的显示器（多屏时副屏收不到系统通知）。要跨屏提醒只能靠外部推送转到手机（1.12.0 起页面里不再画审批卡片）。

• 每次页面加载后第一次出声/弹通知前，需在页面上点击过一次（浏览器自动播放与权限策略）。

• 未授权通知权限时只有提示音与标题标记。

• 快捷裁决按钮要 Service Worker：http://127.0.0.1、https 可用，http://192.168.x.x 这类局域网地址不行；桌面端（dsh-app://）已实测无法注册 Service Worker（宿主未开放 allowServiceWorkers 特权），按钮渲染不了，审批通知退回无按钮样式。浏览器或桌面宿主不渲染通知按钮时，window.__dshNotifyMe.debug() 的 bridge 字段会说明原因，其余功能不受影响。

• macOS：浏览器里提醒、提示音、标题标记、点通知跳转都没有平台假设，照常工作；但 DSH Desktop（Electron）的系统通知要求应用已签名，未签名的通知直接发不出去，官方 macOS 版是否满足这一前提未实测；审批按钮在 macOS 桌面宿主上的渲染同样未实测（Windows 桌面端已实测不渲染，见上条），不渲染时自动退回无按钮通知。

• 配置存在浏览器 localStorage：换浏览器/设备或清除站点数据后会回到默认值（设置页可一键恢复默认）。

• ≥ 0.1.6（含 0.2.0-rc.2、0.2.1-rc.2）的「回复完成」提醒正文只有会话名，不再附带回复摘要——宿主快照已不再提供 nodes；提醒本身照常触发。

• 标题标记由宿主与插件共同写 document.title：宿主重算标题时标记可能被覆盖，直到下一次提醒事件重新写成。

• 「当前对话不弹通知」按「窗口是否在前台」判定：窗口被别的应用盖住、切到别的应用、最小化都算后台，此时当前对话的等待照常提醒；窗口回到前台、或重新有键鼠输入（不再闲置）之后，再恢复静默。

• 外部通知转发受浏览器跨域（CORS）限制：端点不放行时自动降级为「送出但不可确认」（no-cors），如实标为「已送出不可确认」；Discord、飞书、Server酱、WxPusher 都放行跨域，可直接确认送达。钉钉不放行任何 CORS 头、又只收 application/json，页面发不出去，所以没有做成目标类型（自建中转 + 自定义目标才行）。明显临时的失败（网络中断、5xx、429）会按退避重试，重试仍失败进失败记录；其余错误立即停、不重试。转发在本地提醒决定要发之后才触发，所以被「当前对话不弹通知」等规则静音的提醒也不会外发。

• 设置左侧导航行图标靠 DOM 补丁：外壳按分区 id 硬编码图标且 settings.section 没有图标字段，插件只能在面板渲染后把那一行的 <svg> 换成铃铛。命中依赖宿主当前的面板结构（data-shortcut-modal="settings" + 导航按钮里的标签 <span>）；如果 DSH 改了这套结构，补丁会静默失效、显示回默认齿轮，其他功能不受影响。

开发自检

node --check lib\client.js
node --check lib\index.js
node smoke\smoke-test.cjs        # 离线状态机冒烟测试：三代宿主 + 主开关 + 中英语言用例 + 快捷裁决桥（Service Worker 半侧一并跑）+ 闲置判定与通知自收
node smoke\cordis-host-test.mjs  # 真 cordis 端到端（找不到本机 DSH 时自动跳过）
powershell -NoProfile -File lib\focus-window.ps1 -ProcessId 0   # 手动验证抬窗脚本，末行应是 FOCUSED=1
npm pack --dry-run               # 预览发布包

cordis-host-test.mjs 会从本机 DSH 安装借 @deepseek-ai/cordis（依次探测 npm 全局目录、~/.dsh/profiles/web/node_modules 与 ~/.dsh/profiles/node_modules 平铺回退目录）；源码 checkout 里没有 profile 依赖时，用 DSH_CORDIS_PATH=<checkout>/vendor/cordis/lib/index.js 指定即可。

致谢与贡献须知

贡献者（按 handle 列出，链接指向他们参与的 PR / issue）：

• @AgMahone — #7：0.1.6+ / 0.2.0 宿主代际支持，以及通知双响、cordis 查找路径的报障与复测；

• @d0ublecl1ck — #8：子代理会话静音（ignoreSubagent）与配套测试、文档；1.4.0 里「只静音后台子代理、当前打开的照常提醒」的口径同样出自他在 #8 讨论里的建议，落地由维护者完成；

• @EliteOtaku — #9：桌面端抬窗链路（1.5.2）的逐层排查与真实壳三轮复测——确认点通知抬窗 + 切会话稳定生效，并定位出「无用户手势的脚本化注入被 Chromium 静默丢弃」这一复现差异，纠正了最初「沙箱拦死」的判断；

• @Wh1stle05 — #10：「音效来源」功能（内置合成音 / 自定义音频文件 / 系统通知音，「需要你」与「回复完成」各自独立选），含设置页交互、回落链与测试、文档；「系统通知音」试听改发测试通知、假 React 按索引跨渲染保持 hook 状态这两处修正同样出自该 PR。

• @yanzhaohui1999 — #13 / #14：482 个会话下空闲页面烧 CPU 的性能报告（定位到 currentSessionId() 每行重扫全表，实测占 CPU 5.9%~6.5%）与修复（一次列表变化只推导一次「当前会话」），并带先红后绿的回归断言——4 行与 40 行的列表变化代价必须相等（上游报 7 vs 43，修后 5 vs 5）。

• @RiZhiZhaoYi — #12：外部通知转发（Discord Webhook / Bark / Gotify / 自定义 Webhook）的功能建议与使用场景（1.7.0）。

• @yuexian7 — #17：安卓端收消息的诉求——Discord 在国内不便、Bark 没有安卓端，只能自己搭后台中转；1.13.0 的飞书 / Server酱 / WxPusher 三种目标、自动重试与失败记录都是据此做的。

• @shrekcg — #16：把「人在前台但离开了」并入离开判定（idleMinutes，默认 3 分钟）、「回复完成」按哪个对话完成决定是否提醒（donePolicy 三选一）、通知自动消失的三档策略（autoDismiss），并带上对应冒烟用例与旧配置迁移；1.12.0 落地时维护者补了闲置到期补发被压下的审批、删掉残留的页内审批卡片、补齐文档与版本。

• @xinming-chenniang — deepseek-harness discussions #10446：五种 Win32 抬窗手法的实测对照（单独 SetForegroundWindow 被前台锁拒、合成 ALT 键后通过、最小化→恢复两种场景都有效），以及「宿主注册同源路由 + PowerShell 兜底链」这条绕法的可运行验证；1.14.0 的宿主路由与 lib/focus-window.ps1 的直接依据。 署名口径：本仓库收编外部 PR 时以维护者提交落地——不沿用原 commit、不挂 Co-authored-by，GitHub 的 contributors 图只显示维护者，贡献者以上面的致谢署名。

License

MIT — 见 LICENSE。