@mzzsfy/dsh-turn-notify 0.8.1 → 0.10.0

package/README.md

@@ -1,6 +1,6 @@
 # @mzzsfy/dsh-turn-notify
 
-DeepSeek Harness 消息通知插件:AI 回合产生六类事件(完成/出错/被中断/等待审批/AI 提问/达到上限),按你的配置送达声音、系统弹窗、页内提示、webhook、IM 五种通道,多窗口只响一次。
+DeepSeek Harness 消息通知插件:AI 回合产生六类事件(完成/出错/被中断/等待审批/AI 提问/达到上限),按你的配置送达声音、系统弹窗、页内提示、webhook、IM、宿主桌面通知六种通道,多窗口只响一次。
 
 ## 快速上手
 
@@ -8,7 +8,7 @@ DeepSeek Harness 消息通知插件:AI 回合产生六类事件(完成/出错/
 dsh plugin --profile web add @mzzsfy/dsh-turn-notify
 ```
 
-安装后打开 设置 > 消息通知:默认全部事件开启,声音与系统弹窗即装即用(系统弹窗经一次浏览器授权后生效);webhook 与 IM 填配置后启用。页内提示经公共依赖 @mzzsfy/dsh-toast 提供,由 session-manager 插件代挂装载——未安装 session-manager 时该通道自动禁用,其余通道不受影响。声音通道受浏览器自动播放策略约束,首次点击页面后才会出声。想推到微信等聊天工具,见 [IM 推送](#im-推送);想推到自建服务,见 [webhook 推送](#webhook-推送)。
+安装后打开 设置 > 消息通知:默认全部事件开启,声音与系统弹窗即装即用(系统弹窗经一次浏览器授权后生效);webhook、IM 与宿主桌面通知填配置后启用。页内提示经公共依赖 @mzzsfy/dsh-toast 提供,由 session-manager 插件代挂装载——未安装 session-manager 时该通道自动禁用,其余通道不受影响。声音通道受浏览器自动播放策略约束,首次点击页面后才会出声。想推到微信等聊天工具,见 [IM 推送](#im-推送);想推到自建服务,见 [webhook 推送](#webhook-推送);想在宿主机桌面弹系统通知(浏览器全关也送达),见 [宿主桌面通知](#宿主桌面通知)。
 
 ## 六类通知事件
 
@@ -65,7 +65,7 @@ dsh plugin --profile web add @mzzsfy/dsh-turn-notify
 
 ## 事件→通道路由
 
-六类事件各自可指定放行通道名单(kindRoutes,存 settings.yaml),名单外的通道对该类事件一律不送达;未配置的分类全通道放行,名单为空数组即全禁。通道名:`sound`(提示音)/ `system`(系统弹窗)/ `toast`(页内提示,页内提示音随行)/ `blink`(降级标题闪烁)/ `webhook` / `im`。典型用法:任务完成只推 webhook,重要事件(审批/提问)走 IM:
+六类事件各自可指定放行通道名单(kindRoutes,存 settings.yaml),名单外的通道对该类事件一律不送达;未配置的分类全通道放行,名单为空数组即全禁。通道名:`sound`(提示音)/ `system`(系统弹窗)/ `toast`(页内提示,页内提示音随行)/ `blink`(降级标题闪烁)/ `webhook` / `im` / `host`(宿主桌面通知)。典型用法:任务完成只推 webhook,重要事件(审批/提问)走 IM:
 
 ```yaml
 turn-notify:
@@ -78,7 +78,16 @@ turn-notify:
 
 ## webhook 推送
 
-在面板填入 webhook URL 即启用。host 直发,标签页全关也送达;payload 为 Slack 兼容 JSON(text 字段承载通知文本,summary 字段承载通知小结),另附 event/category/status/session/workspace/durationMs/tokens/ts 结构化字段;超时 10 秒,不重试。凭据只写不回显,测试按钮返回真实投递结果。
+在面板填入 webhook URL 即启用。host 直发,标签页全关也送达;payload 为 Slack 兼容 JSON(text 字段承载通知文本,summary 字段承载通知小结),另附 event/category/status/session/workspace/durationMs/tokens/ts 结构化字段;超时 10 秒,不重试。URL 原文随配置响应回显、保存即提交输入框内容(清空并保存即禁用),测试按钮返回真实投递结果。
+
+## 宿主桌面通知
+
+开启面板"通知"页的宿主通知开关后,通知触发时由宿主进程直接弹操作系统级桌面通知,零依赖:macOS 走 osascript,Linux 走 notify-send,Windows 走 PowerShell 调 WinRT toast;超时 10 秒,失败即弃不重试,不影响其余通道。去重方向为**浏览器优先**:本机浏览器在场(2 秒内有在途长轮询)时由浏览器呈现,宿主让位,正常路径同机零重复;本机浏览器离场(标签页全关或仅远程浏览器在线)时宿主补位。重复只发生在在场判定的边界情况(认可窗口边界与网络抖动),宁可重复不可漏。两个开关判定一致,任一开启即生效:
+
+- **宿主机弹桌面通知**:启用宿主通知通道(浏览器优先去重内建)。
+- **仅当本机无浏览器接收时补位**:与总开关等效,作为显式的补位语义表达保留。
+
+"本机浏览器在场"按投影长轮询记账:回环来源 + 续传 cursor + 同源形态的 GET 在服务端挂起期间计为在途,断连(标签页关闭/请求中止)经连接关闭事件即时出账,最近活动在 2 秒认可窗口内仍算在场——优雅断连的盲区不超过 2 秒;异常断连(睡眠、强杀、断网)服务端无感知,受长轮询挂起上限约束,最坏约 25 秒后自愈出账。浏览器在场但本机呈现偏好全关(声音/弹窗/页内全关或系统通知未授权)时,宿主同样让位,该事件本机无 OS 级通知(仅剩会话行高亮)。宿主在无桌面的服务器上时 spawn 会静默失败,无害;测试页"测试宿主通知"返回真实结果,可据此验证宿主机桌面环境是否可用。聚焦时宿主通知照弹(宿主无法感知窗口焦点,聚焦静默是浏览器侧偏好)。
 
 ## IM 推送
 
@@ -98,15 +107,15 @@ turn-notify:
 
 | 分区 | 内容 |
 |------|------|
-| 通知 | webhook 地址、最短回合时长、子代理过滤、六类事件开关;存 settings.yaml,事件开关点击即存,其余点保存后生效。事件→通道路由(kindRoutes)亦存此命名空间,经 yaml 配置 |
+| 通知 | webhook 地址、最短回合时长、子代理过滤、宿主通知(总开关与回退)、六类事件开关;存 settings.yaml,事件开关点击即存,其余点保存后生效。事件→通道路由(kindRoutes)亦存此命名空间,经 yaml 配置 |
 | 偏好 | 本机浏览器记忆的设置:会话高亮(独立开关)、声音总开关与分类静音、音量、系统弹窗与授权、页内提示开关、页内提示音(总开关 + 分类独立开关)、聚焦静默、降级标题闪烁 |
 | 音效 | 音效上传/试听/重命名/删除,六类事件的音效映射与双作用域开关,页内提示音映射(本机,未配置沿用通知音效) |
 | IM | 绑定 dsh-im bot、勾选投递目标(仅装了 dsh-im 时显示) |
-| 测试 | 声音/页内/系统/webhook/IM 逐通道点火,回执即真实结果 |
+| 测试 | 声音/页内/系统/宿主/webhook/IM 逐通道点火,回执即真实结果 |
 
 ## settings.yaml 参考
 
-面板与 settings.yaml 读写同一命名空间,两边改动互通、保存即生效。webhookUrl 属凭据,面板只写不回显,yaml 直改仍可。
+面板与 settings.yaml 读写同一命名空间,两边改动互通、保存即生效。webhookUrl 随面板配置响应回显,yaml 直改同样可见。
 
 ```yaml
 turn-notify:
@@ -114,6 +123,8 @@ turn-notify:
   minTurnDurationMs: 5000         # 最短回合时长(毫秒),回合结束类通知短于此不送达
   rootsOnly: true                 # 子代理会话不通知
   suppressSubagentWake: true      # 子代理相关回合不通知:后台委托未收尾或收尾唤醒(仅任务完成类)
+  hostNotify: false               # 宿主机桌面通知总开关;浏览器优先,本机浏览器在场(2 秒内有在途长轮询)时让位
+  hostNotifyFallback: false       # 宿主通知补位:本机浏览器离场(2 秒内无在途长轮询)时弹宿主桌面通知,与总开关判定一致
   enabled:                        # 六类事件独立开关
     completed: true
     error: true
@@ -138,13 +149,14 @@ turn-notify:
 
 1. **事件监听**:host 观察 `session/event`(回合结束、ask_user_question 工具调用与 assistant 消息)与 `approval/request` 审批请求(只观察,不拦截)。回合结束原因逐一映射:正常结束归任务完成,错误与手动停止归任务出错,审批拦截归等待审批,输出触顶归达到上限,会话收尾补发的中断归被中断;assistant 消息流经途累积回合小结(tokens 与回答前缀),回合结束随通知消费。
 2. **分类与过滤**:事件归入六类,经子代理会话、子代理相关静默(仅任务完成类)、最短回合时长三道过滤,通过即产生一条通知,并按 kindRoutes 裁定放行通道。
-3. **host 直发通道**:webhook 与 IM 由 host 进程直接投递(经路由名单过滤),不依赖浏览器;同时通知写入内存队列(环形 20 条,60 秒过期,不落盘),路由名单随单元下发。
+3. **host 直发通道**:webhook、IM 与宿主桌面通知由 host 进程直接投递(经路由名单过滤),不依赖浏览器;宿主通知按本机(回环来源)浏览器在场(在途长轮询)浏览器优先去重,离场补位;同时通知写入内存队列(环形 20 条,60 秒过期,不落盘),路由名单随单元下发。
 4. **浏览器通道**:各窗口以长轮询挂起在该队列上(cursor 续传,事件与配置变更即时唤醒,空闲期单次挂起至多数十秒,失败指数退避重连),localStorage 协调保证同一通知只有一个窗口呈现,再按本机偏好与路由名单分发到声音/系统弹窗/页内提示;等待用户动作的审批与提问超时未处理时补发一轮提醒。
 5. **降级链**:声音通道开启而系统弹窗不可用(HTTP 非回环、未授权)→ 标题闪烁;页内提示依赖缺失 → 干净禁用该通道;localStorage 不可用 → 该窗口直接发声(可能与多窗口重复,诚实降级)。
 
 ## 已知取舍
 
-- 标签页全关时,仅 webhook 与 IM 送达(声音与弹窗的浏览器前提)。
+- 标签页全关时,仅 webhook、IM 与宿主桌面通知(如开启)送达(声音与弹窗的浏览器前提)。
+- 宿主桌面通知为浏览器优先去重:本机浏览器在场(2 秒内有在途长轮询)时宿主让位,边界情况(认可窗口边界、网络抖动、反代致来源恒为回环而恒判在场)宁可不弹不误弹,优雅断连的离场盲区不超过 2 秒,异常断连受长轮询挂起上限约束(最坏约 25 秒);聚焦时宿主通知照弹(宿主无法感知窗口焦点);无桌面的宿主上 spawn 静默失败,无害。在场记账的形态校验(回环 + 续传 cursor + 同源)为启发式,防无意探活误压制与网页伪造在场(DNS rebinding 将域解析至回环的页面同源可过校验,但该页面同时已握有全部写配置 API,通知压制非最大损失面),不构成对抗本机进程的安全边界。
 - IM 依赖 dsh-im 的 bot 在线,离线时该次通知弃置不补发;成功回执仅代表平台受理。
 - 不同浏览器或不同地址打开的窗口各自发声,互不去重。
 - 系统弹窗在 HTTP 非回环下永久降级,HTTPS 化后自动恢复;Windows 下受系统通知设置与专注助手约束。
@@ -155,7 +167,7 @@ turn-notify:
 ## 安全
 
 - 配置写入类接口(config / mapping / upload / 音效改名与删除 / 测试)带同源守卫:Origin 与 Host 不符即 403,JSON 写入另校验 content-type,阻断跨站页面 drive-by 改写配置。
-- webhookUrl 标记为 secret,任何接口不回传原文。
+- webhookUrl 在 settings 层标记为 secret(导出与日志脱敏);面板配置接口原文回显,本机同源可读写。
 - 音效上传双重校验扩展名与真实音频内容;音效读取接口拒绝音频扩展名以外的文件。
 - 已知边界:同源守卫不防 DNS rebinding(Origin 与 Host 相等即放行)。该暴露面属 host webserver 全部 /api 路由的存量问题,应在 host 层统一解决而非逐插件补丁。
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-turn-notify",
-  "description": "消息通知:六类回合事件送达声音、系统弹窗、页内提示、webhook 与 IM;内置八种合成音色,自定义音效,按事件分类指定;多窗口只响一次",
-  "version": "0.8.1",
+  "description": "消息通知:六类回合事件送达声音、系统弹窗、页内提示、webhook、IM 与宿主桌面通知;内置八种合成音色,自定义音效,按事件分类指定;多窗口只响一次",
+  "version": "0.10.0",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -35,9 +35,9 @@ window.__ModuleLoader__.load({
     // 显示回执等待上限:超时未回执按环境层拦截给出诊断
     const SYSTEM_SHOW_TIMEOUT_MS = 3 * 1000
 
-    // 导航图标声明:交给 dsh-settings-nav-icons 统一渲染(本插件分区 → bell);
-    // 该插件未就绪时入队,由其启动时排空
-    const NAV_ICON = { '消息通知': 'bell' }
+    // 导航图标声明:交给 dsh-settings-nav-icons 统一渲染;双键 = 分区 label + 市场
+    // 短名(发现页收录显示形态);该插件未就绪时入队,由其启动时排空
+    const NAV_ICON = { '消息通知': 'bell', 'dsh-turn-notify': 'bell' }
     if (window.__navicIcons !== undefined) window.__navicIcons.register(NAV_ICON)
     else if (Array.isArray(window.__navicIconQueue)) window.__navicIconQueue.push(NAV_ICON)
     else window.__navicIconQueue = [NAV_ICON]
@@ -277,7 +277,8 @@ window.__ModuleLoader__.load({
     // 放入 LOGIC 段由 parity 测试保证双实现不漂移
     const IDLE_AWAY_MS = 5 * 60 * 1000
 
-    // routes 为事件→通道路由放行名单(null=未配置全放行),语义与 core 同源
+    // routes 为事件→通道路由放行名单(null=未配置全放行),语义与 core 同源。
+    // 宿主通知去重由浏览器优先模型承载:本机浏览器在场时宿主让位,本窗口照常弹系统通知
     function chooseChannels(hasFocus, permission, idleMs, soundCategories, category, routes) {
       const idleAway = typeof idleMs === 'number' && idleMs >= IDLE_AWAY_MS
       const quiet = hasFocus && localGet(KEY_DND) !== '0' && !idleAway
@@ -1009,13 +1010,15 @@ window.__ModuleLoader__.load({
 
     const PERMISSION_LABELS = { granted: '已授权', denied: '已拒绝', default: '未授权' }
 
-    // 面板表单占位:GET config 返回前展示;webhookUrl 凭据不出主机,面板只见是否已配置;
+    // 面板表单占位:GET config 返回前展示;webhookUrl 原文随响应回显,表单所见即所存;
     // imAvailable 缺省为假,加载响应后 dsh-im 在场才渲染 IM 投递卡
     const DEFAULT_CONFIG = {
-      webhookConfigured: false,
+      webhookUrl: '',
       minTurnDurationMs: 5 * 1000,
       rootsOnly: true,
       suppressSubagentWake: true,
+      hostNotify: false,
+      hostNotifyFallback: false,
       enabled: Object.fromEntries(CATEGORIES.map((key) => [key, true])),
       imTargets: [],
     }
@@ -1196,6 +1199,7 @@ window.__ModuleLoader__.load({
           .then((res) => {
             setConfig({ ...DEFAULT_CONFIG, ...res })
             setMappingState(res.soundMapping || {})
+            setUrlDraft(typeof res.webhookUrl === 'string' ? res.webhookUrl : '')
             setConfigLoaded(true)
           })
           .catch(() => {})
@@ -1366,14 +1370,12 @@ window.__ModuleLoader__.load({
             : String(config.minTurnDurationMs)
           if (raw.length === 0) throw new Error('最短回合时长不能为空')
           const trimmedUrl = urlDraft.trim()
-          // imTargets 由勾选单独即时保存,不随此入口提交;会话高亮为本机开关,不进 host 配置
-          const patchBody = { minTurnDurationMs: Number(raw), rootsOnly: config.rootsOnly, suppressSubagentWake: config.suppressSubagentWake }
-          // 只写语义:输入留空即保持现有 webhook 不变
-          if (trimmedUrl.length > 0) patchBody.webhookUrl = trimmedUrl
+          // 所见即所存:输入框即配置值,清空并保存即禁用 webhook 通道
+          const patchBody = { webhookUrl: trimmedUrl, minTurnDurationMs: Number(raw), rootsOnly: config.rootsOnly, suppressSubagentWake: config.suppressSubagentWake, hostNotify: config.hostNotify, hostNotifyFallback: config.hostNotifyFallback }
           const res = await api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify(patchBody) })
           setConfig({ ...DEFAULT_CONFIG, ...res })
           if (res.soundMapping) setMappingState(res.soundMapping)
-          setUrlDraft('')
+          setUrlDraft(typeof res.webhookUrl === 'string' ? res.webhookUrl : '')
           patch('配置已保存,立即生效')
         } catch (error) {
           patch('保存失败:' + (error && error.message ? error.message : String(error)), 'error')
@@ -1386,7 +1388,7 @@ window.__ModuleLoader__.load({
           const res = await api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify({ webhookUrl: '' }) })
           setConfig({ ...DEFAULT_CONFIG, ...res })
           if (res.soundMapping) setMappingState(res.soundMapping)
-          setUrlDraft('')
+          setUrlDraft(typeof res.webhookUrl === 'string' ? res.webhookUrl : '')
           patch('webhook 已清除')
         } catch (error) {
           patch('清除失败:' + (error && error.message ? error.message : String(error)), 'error')
@@ -1466,9 +1468,20 @@ window.__ModuleLoader__.load({
         }, SYSTEM_TEST_DELAY_MS)
       }
 
+      // 宿主桌面通知通道单独测试:等待 spawn 结束,真实结果随响应返回
+      async function testHostNotify() {
+        try {
+          const result = await api('/api/turn-notify/test-host', { method: 'POST' })
+          patch(result.ok ? '宿主通知已触发(' + result.detail + ')' : '宿主通知失败:' + result.detail, result.ok ? 'ok' : 'error')
+        } catch (error) {
+          patch('发送失败:' + (error && error.message ? error.message : String(error)), 'error')
+        }
+      }
+
       async function testWebhook() {
-        if (urlDraft.trim().length > 0) {
-          patch('表单中的新 webhook URL 尚未保存,本次测试的是已保存配置;请先保存再测试', 'error')
+        // 草稿与已保存值不同即存在未保存改动,测试的只能是已保存配置
+        if (urlDraft.trim() !== String(config.webhookUrl || '').trim()) {
+          patch('表单中的 webhook URL 尚未保存,本次测试的是已保存配置;请先保存再测试', 'error')
           return
         }
         try {
@@ -1611,7 +1624,7 @@ window.__ModuleLoader__.load({
       return h('div', { className: 'tn-panel' },
         h('div', { className: 'tn-head' },
           h('span', { className: 'tn-head__title' }, '消息通知'),
-          h('span', { className: 'tn-head__hint' }, '保存即生效;标签页全关时仅 webhook 与 IM 送达'),
+          h('span', { className: 'tn-head__hint' }, '保存即生效;标签页全关时仅 webhook、IM 与宿主通知(如开启)送达'),
         ),
         h('div', { className: 'tn-tabs', role: 'tablist' },
           tabs.map((item) => h('button', {
@@ -1632,15 +1645,15 @@ window.__ModuleLoader__.load({
             field('webhook', [
               h('input', {
                 className: 'tn-input tn-fill', type: 'text',
-                title: '通知由 host 直接 POST 到该地址,标签页全关也送达;Slack 兼容 JSON 格式,超时 10 秒不重试,凭据不回显',
-                placeholder: config.webhookConfigured ? '已配置(输入新 URL 替换,留空保持不变)' : 'Slack-compatible URL,留空禁用',
+                title: '通知由 host 直接 POST 到该地址,标签页全关也送达;Slack 兼容 JSON 格式,超时 10 秒不重试',
+                placeholder: 'Slack-compatible URL,留空禁用',
                 value: urlDraft,
                 onChange: (e) => setUrlDraft(e.target.value),
               }),
-              config.webhookConfigured
+              String(config.webhookUrl || '').trim().length > 0
                 ? h('button', { className: 'tn-btn tn-btn--danger', disabled: busy, title: '清除已配置的 webhook,清除后该通道禁用', onClick: () => void clearWebhook() }, '清除')
                 : null,
-            ], 'URL 只写不回显'),
+            ], '保存即提交输入框内容,清空并保存即禁用;改动后先保存,测试按钮只测已保存配置'),
             field('最短回合时长', [
               h('input', {
                 className: 'tn-input', type: 'number', min: 0, step: 500, style: { width: '90px' },
@@ -1664,6 +1677,20 @@ window.__ModuleLoader__.load({
                 }),
                 ' 后台委托未收尾或收尾唤醒的回合不通知(仅完成类)'),
             ]),
+            field('宿主通知', [
+              h('label', { className: 'tn-meta tn-switch', title: '通知触发时由宿主进程弹系统级桌面通知(osascript/notify-send/PowerShell toast);浏览器优先:本机有浏览器窗口在线(2 秒内有在途长轮询)时由浏览器呈现,宿主不重复弹;本机无浏览器(标签页全关或仅远程浏览器)时宿主弹' },
+                ...switchToggle({
+                  checked: config.hostNotify,
+                  onChange: (e) => setConfig({ ...config, hostNotify: e.target.checked }),
+                }),
+                ' 宿主机弹桌面通知'),
+              h('label', { className: 'tn-meta tn-switch', title: '本机浏览器在场(2 秒内有在途长轮询)时由浏览器呈现,离场时宿主补位桌面通知;与总开关判定一致,任一开启即生效' },
+                ...switchToggle({
+                  checked: config.hostNotifyFallback,
+                  onChange: (e) => setConfig({ ...config, hostNotifyFallback: e.target.checked }),
+                }),
+                ' 仅当本机无浏览器接收时补位'),
+            ], '由宿主进程直接弹 OS 桌面通知,服务器/浏览器全关场景可达;浏览器优先——本机浏览器在线时由浏览器呈现,宿主不重复弹,离场(2 秒内无在途长轮询)时宿主补位,边界情况(窗口边界与网络抖动)宁重复不漏。需点保存生效,测试页可逐条点火验证。'),
             field('事件分类', h('div', { className: 'tn-pills' },
               CATEGORIES.map((category) => h('span', {
                 className: 'tn-pill' + (config.enabled[category] ? ' tn-pill--on' : ''),
@@ -1964,6 +1991,7 @@ window.__ModuleLoader__.load({
               }, '测试声音'),
               h('button', { className: 'tn-btn', title: '弹出一条页内卡片;页内提示音已开启时随卡片补一声(点火测试,不经分类静音约束)', onClick: testPageNotification }, '测试页内通知'),
               h('button', { className: 'tn-btn', title: '弹一条系统通知验证授权与送达;未授权会先引导授权', onClick: testSystemNotification }, '测试系统通知'),
+              h('button', { className: 'tn-btn', title: '由宿主进程弹一条系统级桌面通知(osascript/notify-send/PowerShell toast),验证宿主通道可用性;弹在宿主所在机器', onClick: () => void testHostNotify() }, '测试宿主通知'),
               h('button', { className: 'tn-btn', title: '向已配置的 webhook 发送真实测试事件,回执显示投递结果;未配置时提示失败', onClick: () => void testWebhook() }, '测试 webhook'),
               config.imAvailable ? h('button', { className: 'tn-btn', disabled: busy, title: '向全部已配置目标发送真实测试事件,逐目标显示结果', onClick: () => void testIm() }, '测试 IM 通知') : null,
             ),

package/src/core.mjs

@@ -283,8 +283,8 @@ export function decideClaim({ stored, done, now, windowId, lockTtlMs = CLAIM_LOC
 export const USER_IDLE_AWAY_MS = 5 * 60 * 1000
 
 // 呈现通道名单:事件→通道路由(kindRoutes)的合法取值;host 直发通道
-// (webhook/im)由 host 侧过滤,投影单元携带 routes 供浏览器侧过滤呈现通道。
-export const CHANNELS = ['sound', 'system', 'toast', 'blink', 'webhook', 'im']
+// (webhook/im/host)由 host 侧过滤,投影单元携带 routes 供浏览器侧过滤呈现通道。
+export const CHANNELS = ['sound', 'system', 'toast', 'blink', 'webhook', 'im', 'host']
 
 // 发声通道判定:页内提示、提示音与系统弹窗各自独立开关,聚焦静默仅压声音与系统弹窗;
 // 提示音另受分类配置约束:soundCategories 中该分类显式 false 即静音,缺省键与空分类放行。
@@ -496,6 +496,106 @@ export async function sendWebhook({ url, payload, fetchImpl = fetch }) {
 
 const CONFIG_WEBHOOK_SCHEMES = ['http:', 'https:']
 
+// 宿主桌面通知 spawn 超时:与 webhook 同语义,超时强杀不重试
+export const HOST_NOTIFY_TIMEOUT_MS = 10 * 1000
+
+// 回环判定:IPv6 环回、IPv4 环回与 IPv4 映射形态的 IPv4 环回;空与非法为假。
+// 回环来源的浏览器窗口即与宿主同机,是本机去重的判定依据
+export function isLoopbackAddress(address) {
+  if (typeof address !== 'string' || address.length === 0) return false
+  return address === '::1' || address.startsWith('127.') || address.startsWith('::ffff:127.')
+}
+
+// 宿主通知决策:浏览器优先——本机浏览器在场由浏览器呈现,宿主让位(正常路径
+// 零重复);离场由宿主补位。重复只发生在在场判定的边界情况(认可窗口边界与
+// 网络抖动),宁可重复不可漏。两开关均关不弹,任一开启即启用该通道。
+export function hostNotifyWanted({ hostNotify, hostNotifyFallback, localBrowserPresent }) {
+  if (hostNotify !== true && hostNotifyFallback !== true) return false
+  return localBrowserPresent !== true
+}
+
+// 本机浏览器在场判定:有在途长轮询即在场信号(无论时间戳新旧);无在途时,
+// 最近活动在认可窗口内(长轮询刚完成、断连刚出账)仍算在场,超窗或从未在场为假
+export function isLocalBrowserPresent({ inFlightPolls, lastSeenAt, now, windowMs }) {
+  if (typeof inFlightPolls === 'number' && inFlightPolls > 0) return true
+  return typeof lastSeenAt === 'number' && lastSeenAt > 0 && now - lastSeenAt <= windowMs
+}
+
+// 本机浏览器轮询判定:回环来源 + 长轮询续传形态(带 cursor)+ fetch 请求形态
+// + Origin 对账。投影为无守卫 GET,记账须排除可伪造在场的形态:no-cors(img
+// 跨站探活)、无 cursor 的手工探测、跨源 fetch(同机恶意网页,sec-fetch-mode
+// 同为 cors 无法区分,凭 Origin 与 Host 不符识别;同源 GET fetch 不带 Origin,
+// 无 Origin 放行,旧浏览器同样覆盖)
+export function isLocalBrowserPoll({ remoteAddress, hasCursor, secFetchMode, origin, host }) {
+  if (!isLoopbackAddress(remoteAddress)) return false
+  if (hasCursor !== true) return false
+  if (secFetchMode !== undefined && secFetchMode !== 'cors') return false
+  if (typeof origin === 'string' && origin.length > 0) {
+    try {
+      if (new URL(origin).host !== host) return false
+    } catch {
+      return false
+    }
+  }
+  return true
+}
+
+// 文本规整:换行压平为空格,防命令行参数与通知文案中的换行歧义
+const flattenNotifyText = (text) => String(text).replace(/[\r\n]+/g, ' ')
+
+// AppleScript 字符串字面量:反斜杠与双引号转义
+const appleScriptQuote = (text) => '"' + flattenNotifyText(text).replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+
+// PowerShell 单引号字符串字面量:单引号加倍
+const powerShellQuote = (text) => "'" + flattenNotifyText(text).replace(/'/g, "''") + "'"
+
+// Windows toast 的调用方标识:未打包进程借用系统 PowerShell 的 AppUserModelId,
+// 缺此注册标识 toast 不展示
+const WINDOWS_POWERSHELL_AUMID = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe'
+
+// 平台命令构造:零依赖 spawn 所需的可执行文件与参数;未知平台返回 null。
+// darwin 走 AppleScript 通知,linux 走 libnotify,win32 走 WinRT toast 双行模板
+export function hostNotifyCommand(platform, title, body) {
+  if (platform === 'darwin') {
+    return { file: 'osascript', args: ['-e', 'display notification ' + appleScriptQuote(body) + ' with title ' + appleScriptQuote(title)] }
+  }
+  if (platform === 'linux') {
+    // '--' 终结选项解析:正文(回答前缀)以 '-' 开头时防被 getopt 误作选项簇
+    return { file: 'notify-send', args: ['--', flattenNotifyText(title), flattenNotifyText(body)] }
+  }
+  if (platform === 'win32') {
+    const script = [
+      '[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null',
+      '$t = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)',
+      "$e = $t.GetElementsByTagName('text')",
+      '$e.Item(0).AppendChild($t.CreateTextNode(' + powerShellQuote(title) + ')) | Out-Null',
+      '$e.Item(1).AppendChild($t.CreateTextNode(' + powerShellQuote(body) + ')) | Out-Null',
+      '[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier(' + powerShellQuote(WINDOWS_POWERSHELL_AUMID) + ').Show([Windows.UI.Notifications.ToastNotification]::new($t))',
+    ].join('; ')
+    return { file: 'powershell.exe', args: ['-NoProfile', '-NonInteractive', '-Command', script] }
+  }
+  return null
+}
+
+// 宿主桌面通知:spawn 平台命令并等待退出,真实结果返回;超时强杀,失败即弃
+// 不重试(fire-and-forget,与 webhook 同语义)。execFileImpl 须为注入的
+// node:child_process execFile,保持纯逻辑层可测。
+export async function sendHostNotify({ title, body, platform, execFileImpl }) {
+  const command = hostNotifyCommand(platform, title, body)
+  if (command === null) return { ok: false, detail: '不支持的平台: ' + String(platform) }
+  try {
+    await new Promise((resolve, reject) => {
+      execFileImpl(command.file, command.args, { timeout: HOST_NOTIFY_TIMEOUT_MS, windowsHide: true }, (error) => {
+        if (error) reject(error)
+        else resolve()
+      })
+    })
+    return { ok: true, detail: '已触发宿主通知' }
+  } catch (error) {
+    return { ok: false, detail: error && error.message ? error.message : String(error) }
+  }
+}
+
 // imTargets 读侧归一化:非数组回空,剔除形态非法项,仅保留两字段
 export function normalizeImTargets(raw) {
   if (!Array.isArray(raw)) return []
@@ -541,7 +641,7 @@ export function imBoundBotIds(list) {
 // 返回归一化后的补丁。
 export function validateConfigPatch(patch) {
   if (patch === null || typeof patch !== 'object' || Array.isArray(patch)) return { ok: false, reason: '补丁须为对象' }
-  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'kindRoutes']
+  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'kindRoutes', 'hostNotify', 'hostNotifyFallback']
   for (const key of Object.keys(patch)) {
     if (known.indexOf(key) < 0) return { ok: false, reason: '未知配置项: ' + key }
   }
@@ -594,6 +694,14 @@ export function validateConfigPatch(patch) {
     if (typeof patch.suppressSubagentWake !== 'boolean') return { ok: false, reason: 'suppressSubagentWake 须为布尔' }
     next.suppressSubagentWake = patch.suppressSubagentWake
   }
+  if ('hostNotify' in patch) {
+    if (typeof patch.hostNotify !== 'boolean') return { ok: false, reason: 'hostNotify 须为布尔' }
+    next.hostNotify = patch.hostNotify
+  }
+  if ('hostNotifyFallback' in patch) {
+    if (typeof patch.hostNotifyFallback !== 'boolean') return { ok: false, reason: 'hostNotifyFallback 须为布尔' }
+    next.hostNotifyFallback = patch.hostNotifyFallback
+  }
   if ('enabled' in patch) {
     const enabled = patch.enabled
     if (enabled === null || typeof enabled !== 'object' || Array.isArray(enabled)) return { ok: false, reason: 'enabled 须为对象' }
@@ -657,6 +765,8 @@ export function resolvedConfig(settings) {
     minTurnDurationMs: duration,
     rootsOnly: source.rootsOnly !== false,
     suppressSubagentWake: source.suppressSubagentWake !== false,
+    hostNotify: source.hostNotify === true,
+    hostNotifyFallback: source.hostNotifyFallback === true,
     enabled: Object.fromEntries(CATEGORIES.map((key) => [key, enabled[key] !== false])),
     soundMapping,
     imTargets: normalizeImTargets(source.imTargets),
@@ -664,17 +774,19 @@ export function resolvedConfig(settings) {
   }
 }
 
-// 面板可见配置:webhookUrl 属凭据不出主机,仅回是否已配置。
+// 面板可见配置:webhookUrl 原文随响应回显,面板所见即所存。
 export function publicConfig(settings) {
   const resolved = resolvedConfig(settings)
   return {
     minTurnDurationMs: resolved.minTurnDurationMs,
     rootsOnly: resolved.rootsOnly,
     suppressSubagentWake: resolved.suppressSubagentWake,
+    hostNotify: resolved.hostNotify,
+    hostNotifyFallback: resolved.hostNotifyFallback,
     enabled: resolved.enabled,
     soundMapping: resolved.soundMapping,
     imTargets: resolved.imTargets,
     kindRoutes: resolved.kindRoutes,
-    webhookConfigured: resolved.webhookUrl.trim().length > 0,
+    webhookUrl: resolved.webhookUrl,
   }
 }

package/src/index.js

@@ -2,6 +2,7 @@
 // 命中分类即发 webhook、写入内存投影;webServer 路由供浏览器半区轮询投影与管理音效。
 // 音效持久化在 ~/.dsh/dsh-turn-notify/sounds/,投影不落盘。
 
+import { execFile } from 'node:child_process'
 import { createHash } from 'node:crypto'
 import { mkdir, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises'
 import { homedir } from 'node:os'
@@ -25,6 +26,9 @@ import {
   isSubagent,
   isSubagentWakeTurn,
   isValidImBotId,
+  hostNotifyWanted,
+  isLocalBrowserPoll,
+  isLocalBrowserPresent,
   mapEventToCategory,
   mimeOf,
   normalizeImTargets,
@@ -32,6 +36,7 @@ import {
   readRawBody,
   resolvedConfig,
   sendWebhook,
+  sendHostNotify,
   shouldNotify,
   storedSessionTitle,
   unitRoutes,
@@ -49,11 +54,17 @@ export const name = 'dsh-turn-notify'
 
 export const inject = ['webServer']
 
+// spawn 实现缝:测试注入观测 stub,生产恒为 child_process.execFile(client 半区 __test 同先例)
+export const __hostSpawn = { impl: execFile }
+
 const NAMESPACE = 'turn-notify'
 const SOUNDS_DIR = join(homedir(), '.dsh', 'dsh-turn-notify', 'sounds')
 const REQUEST_BODY_MAX_BYTES = 64 * 1024
 // 长轮询挂起上限:低于客户端请求超时,保证客户端总在服务端放弃后才超时
 const LONG_POLL_WAIT_MS = 25 * 1000
+// 本机浏览器在场认可窗口:在途长轮询出账后的宽限时长,浏览器优先去重的时间边界;
+// 窗口内事件仍视为浏览器呈现,超窗即宿主补位(宁可重复不可漏)
+export const CLIENT_PRESENCE_WINDOW_MS = 2 * 1000
 
 // dsh-im 投递错误码到 HTTP 状态的映射,未收录错误按网关失败处理
 const IM_ERROR_STATUS = { 'bad-request': 400, 'unknown-bot': 404, 'bot-not-connected': 503 }
@@ -81,10 +92,12 @@ const SETTINGS_SCHEMA = z.object({
   minTurnDurationMs: z.number().default(MIN_TURN_DURATION_MS).description('最短回合时长(毫秒),回合结束类通知短于此不送达;AI 提问与审批请求即时送达'),
   rootsOnly: z.boolean().default(true).description('子代理会话不通知'),
   suppressSubagentWake: z.boolean().default(true).description('子代理相关回合不通知(仅任务完成类):后台委托未收尾的回合与收尾唤醒的回合'),
+  hostNotify: z.boolean().default(false).description('宿主机桌面通知:通知触发时由宿主进程弹系统级通知(osascript/notify-send/PowerShell toast);浏览器优先,本机浏览器在场(2 秒内有在途长轮询)时由浏览器呈现宿主不重复弹,离场时宿主补位'),
+  hostNotifyFallback: z.boolean().default(false).description('宿主通知回退:本机浏览器在场时由浏览器呈现,离场(2 秒内无在途长轮询)时宿主补位;与总开关判定一致,任一开启即生效'),
   enabled: z.object(Object.fromEntries(CATEGORIES.map((key) => [key, z.boolean().default(true)]))).description('六类事件独立开关:完成/出错/被中断/等待审批/AI 提问/达到上限'),
   soundMapping: z.object(Object.fromEntries(CATEGORIES.map((key) => [key, z.string().default('')]))).description('每类事件的声音映射,空为内置默认,非空为内置音名或上传音效 id'),
   imTargets: z.array(z.object({ botId: z.string().default(''), targetId: z.string().default('') })).default([]).description('dsh-im 推送目标列表,空数组禁用 IM 通道'),
-  kindRoutes: z.dict(z.array(z.string())).default({}).description('事件→通道路由:分类到放行通道名单(sound/system/toast/blink/webhook/im),未配置的分类全通道放行'),
+  kindRoutes: z.dict(z.array(z.string())).default({}).description('事件→通道路由:分类到放行通道名单(sound/system/toast/blink/webhook/im/host),未配置的分类全通道放行'),
 })
 
 // 读侧归一交由 core 的 resolvedConfig:字段类型异常回退默认值,与写路径校验宽松度一致
@@ -194,6 +207,10 @@ export function apply(ctx) {
   const titledSessions = new Set()
   // 回合尾部统计:assistant/message 的 tokens 累加与回答前缀,回合结束随通知消费即清
   const assistantTails = new Map()
+  // 本机(回环来源)浏览器在场信号:在途长轮询计数与最近活动时刻,
+  // 在场 = 有在途请求或认可窗口内有活动,宿主通知的浏览器优先去重据此判定
+  let inFlightLocalPolls = 0
+  let lastLocalClientSeenAt = 0
   let seq = 0
   // 音效库写互斥:展示名索引读改写与落盘非原子,串行化防并发交错
   let soundWriteQueue = Promise.resolve()
@@ -253,6 +270,25 @@ export function apply(ctx) {
       void sendWebhook({ url: settings.webhookUrl, payload: buildWebhookPayload(unit) })
     }
     if (routes === null || routes.indexOf('im') >= 0) deliverIm(unit, settings)
+    if (routes === null || routes.indexOf('host') >= 0) deliverHostNotify(unit, settings)
+  }
+
+  // 宿主桌面通知:浏览器优先,本机浏览器在场由浏览器呈现,宿主让位(正常路径
+  // 零重复);离场(无在途长轮询且超认可窗口)由宿主补位;fire-and-forget,
+  // spawn 失败不影响其余通道
+  function deliverHostNotify(unit, settings) {
+    const wanted = hostNotifyWanted({
+      hostNotify: settings.hostNotify,
+      hostNotifyFallback: settings.hostNotifyFallback,
+      localBrowserPresent: isLocalBrowserPresent({
+        inFlightPolls: inFlightLocalPolls,
+        lastSeenAt: lastLocalClientSeenAt,
+        now: Date.now(),
+        windowMs: CLIENT_PRESENCE_WINDOW_MS,
+      }),
+    })
+    if (!wanted) return
+    void sendHostNotify({ title: unit.text, body: unit.summary ?? '', platform: process.platform, execFileImpl: __hostSpawn.impl })
   }
 
   // 会话显示标题:优先 session-title 服务(与侧边栏行标题同一投影,客户端文本匹配高亮
@@ -404,13 +440,39 @@ export function apply(ctx) {
       path: '/api/turn-notify/projection',
       handler: route('GET', {}, async (req, res) => {
         const query = new URL(req.url, 'http://localhost').searchParams
-        const rawCursor = Number(query.get('cursor'))
-        const cursor = Number.isFinite(rawCursor) ? rawCursor : 0
-        if (query.has('cursor') && projection.version() === cursor) {
-          await projection.wait(cursor, LONG_POLL_WAIT_MS)
+        // 回环来源的浏览器长轮询即本机在场信号,宿主通知的浏览器优先去重据此判定;
+        // 记账形态收紧防伪造:裸 GET(img 探活/监控探测)与跨源 fetch 不入账。
+        // 记账期间计入在途,断连(浏览器关闭/中止)经 res close 事件即时出账,
+        // 离场盲区收敛到认可窗口
+        let releaseLocalPoll = null
+        if (isLocalBrowserPoll({
+          remoteAddress: req.socket && req.socket.remoteAddress,
+          hasCursor: query.has('cursor'),
+          secFetchMode: req.headers ? req.headers['sec-fetch-mode'] : undefined,
+          origin: req.headers ? req.headers.origin : undefined,
+          host: req.headers ? req.headers.host : undefined,
+        })) {
+          inFlightLocalPolls += 1
+          let settled = false
+          releaseLocalPoll = () => {
+            if (settled) return
+            settled = true
+            inFlightLocalPolls -= 1
+            lastLocalClientSeenAt = Date.now()
+          }
+          res.once('close', releaseLocalPoll)
+        }
+        try {
+          const rawCursor = Number(query.get('cursor'))
+          const cursor = Number.isFinite(rawCursor) ? rawCursor : 0
+          if (query.has('cursor') && projection.version() === cursor) {
+            await projection.wait(cursor, LONG_POLL_WAIT_MS)
+          }
+          const settings = readSettings(ctx)
+          sendJson(res, 200, { units: projection.list(), soundMapping: settings.soundMapping, version: projection.version() })
+        } finally {
+          if (releaseLocalPoll !== null) releaseLocalPoll()
         }
-        const settings = readSettings(ctx)
-        sendJson(res, 200, { units: projection.list(), soundMapping: settings.soundMapping, version: projection.version() })
       }),
     })
     return () => projection.dispose()
@@ -631,6 +693,29 @@ export function apply(ctx) {
       }),
     }), 'turn-notify test-webhook route')
 
+  // 宿主通知测试点火互斥:spawn 代价高于既有端点(powershell/osascript 秒级),
+  // 单在途防连点堆积
+  let hostTestInFlight = false
+  ctx.effect(() =>
+    ctx.webServer.register({
+      kind: 'exact',
+      path: '/api/turn-notify/test-host',
+      // 等待 spawn 结束,真实结果随响应返回,测试按钮不谎报
+      handler: route('POST', { crossOrigin: true }, async (req, res) => {
+        if (hostTestInFlight) {
+          sendJson(res, 429, { error: '宿主通知测试进行中,请稍候' })
+          return
+        }
+        hostTestInFlight = true
+        try {
+          const unit = buildTestUnit()
+          sendJson(res, 200, await sendHostNotify({ title: unit.text, body: unit.summary ?? '', platform: process.platform, execFileImpl: __hostSpawn.impl }))
+        } finally {
+          hostTestInFlight = false
+        }
+      }),
+    }), 'turn-notify test-host route')
+
   ctx.effect(() =>
     ctx.webServer.register({
       kind: 'exact',