@mzzsfy/dsh-turn-notify 0.9.0 → 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:
@@ -80,6 +80,15 @@ turn-notify:
 
 在面板填入 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 推送
 
 安装 [@xmanrui/dsh-im](https://www.npmjs.com/package/@xmanrui/dsh-im) 后自动启用,可推送到微信等九种渠道。投递目标的新建与平台测试在 dsh-im 设置页完成,本插件只做选择:从已绑 bot 的目标目录勾选即保存,支持绑定多个 bot。触发逻辑与 webhook 一致,fire-and-forget 不重试;bot 离线时该次通知弃置不补发。
@@ -98,11 +107,11 @@ turn-notify:
 
 | 分区 | 内容 |
 |------|------|
-| 通知 | webhook 地址、最短回合时长、子代理过滤、六类事件开关;存 settings.yaml,事件开关点击即存,其余点保存后生效。事件→通道路由(kindRoutes)亦存此命名空间,经 yaml 配置 |
+| 通知 | webhook 地址、最短回合时长、子代理过滤、宿主通知(总开关与回退)、六类事件开关;存 settings.yaml,事件开关点击即存,其余点保存后生效。事件→通道路由(kindRoutes)亦存此命名空间,经 yaml 配置 |
 | 偏好 | 本机浏览器记忆的设置:会话高亮(独立开关)、声音总开关与分类静音、音量、系统弹窗与授权、页内提示开关、页内提示音(总开关 + 分类独立开关)、聚焦静默、降级标题闪烁 |
 | 音效 | 音效上传/试听/重命名/删除,六类事件的音效映射与双作用域开关,页内提示音映射(本机,未配置沿用通知音效) |
 | IM | 绑定 dsh-im bot、勾选投递目标(仅装了 dsh-im 时显示) |
-| 测试 | 声音/页内/系统/webhook/IM 逐通道点火,回执即真实结果 |
+| 测试 | 声音/页内/系统/宿主/webhook/IM 逐通道点火,回执即真实结果 |
 
 ## settings.yaml 参考
 
@@ -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 下受系统通知设置与专注助手约束。

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mzzsfy/dsh-turn-notify",
-  "description": "消息通知:六类回合事件送达声音、系统弹窗、页内提示、webhook 与 IM;内置八种合成音色,自定义音效,按事件分类指定;多窗口只响一次",
-  "version": "0.9.0",
+  "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
@@ -1016,6 +1017,8 @@ window.__ModuleLoader__.load({
       minTurnDurationMs: 5 * 1000,
       rootsOnly: true,
       suppressSubagentWake: true,
+      hostNotify: false,
+      hostNotifyFallback: false,
       enabled: Object.fromEntries(CATEGORIES.map((key) => [key, true])),
       imTargets: [],
     }
@@ -1368,7 +1371,7 @@ window.__ModuleLoader__.load({
           if (raw.length === 0) throw new Error('最短回合时长不能为空')
           const trimmedUrl = urlDraft.trim()
           // 所见即所存:输入框即配置值,清空并保存即禁用 webhook 通道
-          const patchBody = { webhookUrl: trimmedUrl, minTurnDurationMs: Number(raw), rootsOnly: config.rootsOnly, suppressSubagentWake: config.suppressSubagentWake }
+          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)
@@ -1465,6 +1468,16 @@ 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() !== String(config.webhookUrl || '').trim()) {
@@ -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', {
@@ -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),
@@ -671,10 +781,12 @@ export function publicConfig(settings) {
     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,
     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',

package/test/core.test.mjs

@@ -659,6 +659,8 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
       minTurnDurationMs: MIN_TURN_MS,
       rootsOnly: true,
       suppressSubagentWake: true,
+      hostNotify: false,
+      hostNotifyFallback: false,
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
@@ -670,6 +672,8 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
     minTurnDurationMs: MIN_TURN_MS,
     rootsOnly: true,
     suppressSubagentWake: true,
+    hostNotify: false,
+    hostNotifyFallback: false,
     enabled: Object.fromEntries(CATEGORIES.map((name) => [name, true])),
     soundMapping: {},
     imTargets: [],
@@ -686,6 +690,8 @@ test('面板可见配置:webhookUrl 原文回显', () => {
       minTurnDurationMs: MIN_TURN_MS,
       rootsOnly: true,
       suppressSubagentWake: true,
+      hostNotify: false,
+      hostNotifyFallback: false,
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],

package/test/event-wiring.test.mjs

@@ -6,13 +6,14 @@ import { EventEmitter } from 'node:events'
 
 import { apply } from '../src/index.js'
 
+// res 桩带事件能力:投影处理器挂 close 事件感知断连,桩须支持 once
 function makeRes() {
-  return {
-    status: null,
-    body: null,
-    writeHead(status) { this.status = status },
-    end(body) { this.body = JSON.parse(body) },
-  }
+  const res = new EventEmitter()
+  res.status = null
+  res.body = null
+  res.writeHead = (status) => { res.status = status }
+  res.end = (body) => { res.body = JSON.parse(body) }
+  return res
 }
 
 function makeReq(method, payload, headers) {

package/test/host-notify.test.mjs

@@ -0,0 +1,593 @@
+// 宿主桌面通知 BDD:core 纯函数(回环判定 / 派发决策 / 平台命令 / spawn 执行 / 配置键)
+// 与 host 接线集成(stub ctx 装载真实 src/index.js,stub spawn 观测派发)。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { EventEmitter } from 'node:events'
+
+import { apply, __hostSpawn, CLIENT_PRESENCE_WINDOW_MS } from '../src/index.js'
+import {
+  CHANNELS,
+  HOST_NOTIFY_TIMEOUT_MS,
+  hostNotifyCommand,
+  hostNotifyWanted,
+  isLocalBrowserPoll,
+  isLocalBrowserPresent,
+  isLoopbackAddress,
+  publicConfig,
+  resolvedConfig,
+  sendHostNotify,
+  validateConfigPatch,
+} from '../src/core.mjs'
+
+// ---- isLoopbackAddress:同机判定,回环地址即本机浏览器 ----
+
+test('Given 回环形态地址 When 判定 Then 为真', () => {
+  assert.equal(isLoopbackAddress('::1'), true)
+  assert.equal(isLoopbackAddress('127.0.0.1'), true)
+  assert.equal(isLoopbackAddress('127.8.8.8'), true)
+  assert.equal(isLoopbackAddress('::ffff:127.0.0.1'), true)
+})
+
+test('Given 非回环或非法地址 When 判定 Then 为假', () => {
+  assert.equal(isLoopbackAddress('192.168.1.5'), false)
+  assert.equal(isLoopbackAddress('::ffff:192.168.1.5'), false)
+  assert.equal(isLoopbackAddress('::2'), false)
+  assert.equal(isLoopbackAddress(''), false)
+  assert.equal(isLoopbackAddress(undefined), false)
+  assert.equal(isLoopbackAddress(null), false)
+})
+
+// ---- isLocalBrowserPoll:在场记账形态收紧,防伪造在场压制宿主通知 ----
+
+test('Given 回环加 cursor 加 fetch 形态或无 Sec-Fetch 头 When 判定 Then 为真', () => {
+  assert.equal(isLocalBrowserPoll({ remoteAddress: '127.0.0.1', hasCursor: true, secFetchMode: 'cors' }), true)
+  assert.equal(isLocalBrowserPoll({ remoteAddress: '::1', hasCursor: true, secFetchMode: undefined }), true)
+})
+
+test('Given 非回环或无 cursor 或 no-cors 形态 When 判定 Then 为假', () => {
+  assert.equal(isLocalBrowserPoll({ remoteAddress: '192.168.1.5', hasCursor: true, secFetchMode: 'cors' }), false)
+  assert.equal(isLocalBrowserPoll({ remoteAddress: '127.0.0.1', hasCursor: false, secFetchMode: 'cors' }), false)
+  assert.equal(isLocalBrowserPoll({ remoteAddress: '127.0.0.1', hasCursor: true, secFetchMode: 'no-cors' }), false)
+  assert.equal(isLocalBrowserPoll({ remoteAddress: undefined, hasCursor: true, secFetchMode: 'cors' }), false)
+})
+
+test('Given Origin 缺席或与 Host 一致 When 判定 Then 为真;跨源或畸形 Origin Then 为假', () => {
+  const base = { remoteAddress: '127.0.0.1', hasCursor: true, secFetchMode: 'cors' }
+  assert.equal(isLocalBrowserPoll({ ...base, origin: undefined, host: '127.0.0.1:3080' }), true, '同源 GET fetch 不带 Origin')
+  assert.equal(isLocalBrowserPoll({ ...base, origin: 'http://127.0.0.1:3080', host: '127.0.0.1:3080' }), true)
+  assert.equal(isLocalBrowserPoll({ ...base, origin: 'https://evil.example', host: '127.0.0.1:3080' }), false, '跨源 fetch 必带且与 Host 不符')
+  assert.equal(isLocalBrowserPoll({ ...base, origin: 'not a url', host: '127.0.0.1:3080' }), false, '畸形 Origin 不放行')
+})
+
+// ---- hostNotifyWanted:浏览器优先,在场让位、离场补位;重复只发生在边界情况 ----
+
+const NOW = 1000 * 1000
+const WINDOW_MS = 2 * 1000
+
+test('Given 任一开关开且本机浏览器不在场 When 决策 Then 弹', () => {
+  assert.equal(hostNotifyWanted({ hostNotify: true, localBrowserPresent: false }), true)
+  assert.equal(hostNotifyWanted({ hostNotifyFallback: true, localBrowserPresent: false }), true)
+  assert.equal(hostNotifyWanted({ hostNotify: true, hostNotifyFallback: true, localBrowserPresent: false }), true)
+})
+
+test('Given 任一开关开且本机浏览器在场 When 决策 Then 让位不弹(浏览器优先,正常路径零重复)', () => {
+  assert.equal(hostNotifyWanted({ hostNotify: true, localBrowserPresent: true }), false)
+  assert.equal(hostNotifyWanted({ hostNotifyFallback: true, localBrowserPresent: true }), false)
+  assert.equal(hostNotifyWanted({ hostNotify: true, hostNotifyFallback: true, localBrowserPresent: true }), false)
+})
+
+test('Given 两开关均关 When 决策 Then 恒不弹', () => {
+  assert.equal(hostNotifyWanted({ localBrowserPresent: false }), false)
+  assert.equal(hostNotifyWanted({ hostNotify: false, hostNotifyFallback: false, localBrowserPresent: false }), false)
+})
+
+// ---- isLocalBrowserPresent:在场 = 有在途长轮询,或宽限窗口内有活动 ----
+
+test('Given 在途长轮询存在 When 判定在场 Then 为真(时间戳过期不影响)', () => {
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 1, lastSeenAt: NOW - WINDOW_MS - 1, now: NOW, windowMs: WINDOW_MS }), true)
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 3, lastSeenAt: 0, now: NOW, windowMs: WINDOW_MS }), true)
+})
+
+test('Given 无在途 When 判定在场 Then 最近活动在窗口内为真,超窗或从未为假', () => {
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 0, lastSeenAt: NOW - 1, now: NOW, windowMs: WINDOW_MS }), true)
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 0, lastSeenAt: NOW - WINDOW_MS, now: NOW, windowMs: WINDOW_MS }), true)
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 0, lastSeenAt: NOW - WINDOW_MS - 1, now: NOW, windowMs: WINDOW_MS }), false)
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 0, lastSeenAt: 0, now: NOW, windowMs: WINDOW_MS }), false)
+  assert.equal(isLocalBrowserPresent({ inFlightPolls: 0, lastSeenAt: undefined, now: NOW, windowMs: WINDOW_MS }), false)
+})
+
+// ---- hostNotifyCommand:平台命令构造与文本转义 ----
+
+test('Given darwin When 构造 Then osascript 单命令携带转义后的标题与正文', () => {
+  const command = hostNotifyCommand('darwin', '标题', '正文')
+  assert.equal(command.file, 'osascript')
+  assert.deepEqual(command.args.slice(0, 1), ['-e'])
+  const script = command.args[1]
+  assert.ok(script.includes('display notification'), '应含 display notification')
+  assert.ok(script.includes('with title'), '应含 with title')
+  assert.ok(script.includes('标题'), '应含标题')
+  assert.ok(script.includes('正文'), '应含正文')
+})
+
+test('Given darwin 且文本含双引号反斜杠换行 When 构造 Then 转义并压平', () => {
+  const script = hostNotifyCommand('darwin', 'a"b\\c\nd', 'x').args[1]
+  assert.ok(script.includes('a\\"b\\\\c d'), '双引号反斜杠须转义且换行压平: ' + script)
+  assert.ok(!script.includes('\n'), '不得残留换行')
+})
+
+test('Given linux When 构造 Then notify-send 选项终结符后标题正文直传', () => {
+  const command = hostNotifyCommand('linux', 'T', 'B')
+  assert.equal(command.file, 'notify-send')
+  assert.deepEqual(command.args, ['--', 'T', 'B'])
+})
+
+test('Given linux 且正文以减号开头 When 构造 Then 经选项终结符原样直传', () => {
+  const command = hostNotifyCommand('linux', 'T', '- 修改了配置')
+  assert.deepEqual(command.args, ['--', 'T', '- 修改了配置'])
+})
+
+test('Given linux 且文本含换行 When 构造 Then 换行压平为空格', () => {
+  const command = hostNotifyCommand('linux', 'a\nb', 'c\nd')
+  assert.deepEqual(command.args, ['--', 'a b', 'c d'])
+})
+
+test('Given win32 When 构造 Then powershell 无配置非交互单命令脚本', () => {
+  const command = hostNotifyCommand('win32', 'T', 'B')
+  assert.equal(command.file, 'powershell.exe')
+  assert.deepEqual(command.args.slice(0, 3), ['-NoProfile', '-NonInteractive', '-Command'])
+  const script = command.args[3]
+  assert.ok(script.includes('ToastNotificationManager'), '应使用 WinRT toast')
+  assert.ok(script.includes('ToastText02'), '应使用双行模板')
+  assert.ok(script.includes('CreateTextNode'), '文本应经 CreateTextNode 注入')
+})
+
+test('Given win32 且文本含单引号 When 构造 Then 单引号加倍且换行压平', () => {
+  const script = hostNotifyCommand('win32', "it's\nok", 'B').args[3]
+  assert.ok(script.includes("it''s ok"), '单引号须加倍且换行压平: ' + script)
+  assert.ok(!script.includes('\n'), '不得残留换行')
+})
+
+test('Given 未知平台 When 构造 Then 返回 null', () => {
+  assert.equal(hostNotifyCommand('freebsd', 'T', 'B'), null)
+})
+
+// ---- sendHostNotify:真实结果返回,依赖注入 ----
+
+test('Given spawn 成功 When 发送 Then 返回 ok 且传参含超时与隐藏窗口', async () => {
+  const calls = []
+  const result = await sendHostNotify({
+    title: 'T', body: 'B', platform: 'linux',
+    execFileImpl: (file, args, options, callback) => {
+      calls.push({ file, args, options })
+      callback(null)
+    },
+  })
+  assert.deepEqual(result, { ok: true, detail: '已触发宿主通知' })
+  assert.equal(calls.length, 1)
+  assert.equal(calls[0].file, 'notify-send')
+  assert.equal(calls[0].options.timeout, HOST_NOTIFY_TIMEOUT_MS)
+  assert.equal(calls[0].options.windowsHide, true)
+})
+
+test('Given spawn 失败 When 发送 Then 返回失败与原因', async () => {
+  const result = await sendHostNotify({
+    title: 'T', body: 'B', platform: 'linux',
+    execFileImpl: (file, args, options, callback) => callback(new Error('boom')),
+  })
+  assert.equal(result.ok, false)
+  assert.equal(result.detail, 'boom')
+})
+
+test('Given 不支持平台 When 发送 Then 不触碰 spawn 返回不支持', async () => {
+  let touched = false
+  const result = await sendHostNotify({
+    title: 'T', body: 'B', platform: 'freebsd',
+    execFileImpl: () => { touched = true },
+  })
+  assert.equal(touched, false)
+  assert.equal(result.ok, false)
+  assert.ok(result.detail.includes('freebsd'))
+})
+
+// ---- 配置键:校验与解析 ----
+
+test('Given 补丁含两键布尔 When 校验 Then 通过并归一;非布尔 Then 拒绝', () => {
+  const good = validateConfigPatch({ hostNotify: true, hostNotifyFallback: false })
+  assert.equal(good.ok, true)
+  assert.deepEqual(good.patch, { hostNotify: true, hostNotifyFallback: false })
+  assert.equal(validateConfigPatch({ hostNotify: 'yes' }).ok, false)
+  assert.equal(validateConfigPatch({ hostNotifyFallback: 1 }).ok, false)
+})
+
+test('Given 缺省配置 When 解析 Then 两键回 false;CHANNELS 含 host', () => {
+  const resolved = resolvedConfig({})
+  assert.equal(resolved.hostNotify, false)
+  assert.equal(resolved.hostNotifyFallback, false)
+  const config = publicConfig({ hostNotify: true })
+  assert.equal(config.hostNotify, true)
+  assert.equal(config.hostNotifyFallback, false)
+  assert.ok(CHANNELS.indexOf('host') >= 0, 'host 应为可路由通道')
+})
+
+// ---- host 接线集成:stub spawn 观测派发,presence 经投影路由的来源地址注入 ----
+
+// res 桩带事件能力:投影处理器挂 close 事件感知断连,桩须支持 once/emit;
+// end 不自动触发 close,断连时机由测试显式 emit 模拟
+function makeRes() {
+  const res = new EventEmitter()
+  res.status = null
+  res.body = null
+  res.writeHead = (status) => { res.status = status }
+  res.end = (body) => { res.body = JSON.parse(body) }
+  return res
+}
+
+function makeReq(method, payload, headers) {
+  const req = new EventEmitter()
+  req.method = method
+  req.url = '/api/turn-notify/config'
+  req.headers = { host: '127.0.0.1:3080', ...(headers || {}) }
+  const data = payload === undefined ? null : Buffer.from(JSON.stringify(payload))
+  process.nextTick(() => {
+    if (data !== null) req.emit('data', data)
+    req.readableEnded = true
+    req.emit('end')
+  })
+  return req
+}
+
+const JSON_HEADERS = { 'content-type': 'application/json' }
+
+function makeCtx() {
+  const routes = new Map()
+  const handlers = new Map()
+  const doc = new Map()
+  const settingsService = {
+    register(ns) {
+      if (!doc.has(ns)) doc.set(ns, {})
+      return { get: () => doc.get(ns), watch: () => () => {} }
+    },
+    get: (ns) => doc.get(ns),
+    update: async (ns, patch) => { doc.set(ns, { ...(doc.get(ns) ?? {}), ...patch }) },
+  }
+  const ctx = {
+    on(event, fn) { handlers.set(event, fn) },
+    get(key) { return key === 'settings' ? settingsService : undefined },
+    inject(deps, fn) { fn({ settings: settingsService }) },
+    effect(thunk) { thunk() },
+    webServer: { register(route) { routes.set(route.path, route.handler) } },
+  }
+  return { ctx, routes, handlers }
+}
+
+const flushMicrotasks = () => new Promise((resolve) => setImmediate(resolve))
+
+const MAIN = { id: 'M', header: { delegationDepth: 0 } }
+const turnEnd = (kind) => ({ type: 'turn/end', data: { reason: { kind } } })
+
+async function postConfig(routes, patch) {
+  const res = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('POST', patch, JSON_HEADERS), res)
+  assert.equal(res.status, 200)
+  return res
+}
+
+async function pollProjection(routes, remoteAddress) {
+  const req = makeReq('GET')
+  req.url = '/api/turn-notify/projection'
+  if (remoteAddress !== undefined) req.socket = { remoteAddress }
+  const res = makeRes()
+  await routes.get('/api/turn-notify/projection')(req, res)
+  assert.equal(res.status, 200)
+  return res
+}
+
+// 本机浏览器长轮询记账形态:回环 + 带续传 cursor + fetch 形态头;
+// cursor 取超前值立即返回,不挂起
+const FUTURE_CURSOR = 2 ** 40
+async function browserPoll(routes, remoteAddress) {
+  const req = makeReq('GET', undefined, { 'sec-fetch-mode': 'cors' })
+  req.url = '/api/turn-notify/projection?cursor=' + FUTURE_CURSOR
+  req.socket = { remoteAddress }
+  const res = makeRes()
+  await routes.get('/api/turn-notify/projection')(req, res)
+  assert.equal(res.status, 200)
+  return res
+}
+
+// 伪形态轮询:回环来源但缺 cursor / no-cors / 跨源 Origin,记账须拒绝
+async function rawShapePoll(routes, remoteAddress, secFetchMode, withCursor, origin) {
+  const headers = secFetchMode === undefined ? {} : { 'sec-fetch-mode': secFetchMode }
+  if (origin !== undefined) headers.origin = origin
+  const req = makeReq('GET', undefined, headers)
+  req.url = '/api/turn-notify/projection' + (withCursor ? '?cursor=' + FUTURE_CURSOR : '')
+  req.socket = { remoteAddress }
+  const res = makeRes()
+  await routes.get('/api/turn-notify/projection')(req, res)
+  assert.equal(res.status, 200)
+  return res
+}
+
+// spawn 观测缝:替换实现收集调用,测试结束还原
+async function withStubSpawn(run) {
+  const spawns = []
+  const original = __hostSpawn.impl
+  __hostSpawn.impl = (file, args, options, callback) => {
+    spawns.push({ file, args })
+    callback(null)
+  }
+  try {
+    return await run(spawns)
+  } finally {
+    __hostSpawn.impl = original
+  }
+}
+
+async function emitCompletedTurn(handlers) {
+  handlers.get('session/event')(MAIN, { type: 'turn/start' })
+  handlers.get('session/event')(MAIN, turnEnd('completed'))
+  await flushMicrotasks()
+}
+
+// 挂起中的长轮询:cursor 等于当前版本(配置 POST 后为 1),服务端挂起等待,
+// 模拟真实客户端的在途请求;返回 pending 承诺与 res 桩(供断连模拟与唤醒等待)
+function hangingPoll(routes, remoteAddress) {
+  const req = makeReq('GET', undefined, { 'sec-fetch-mode': 'cors' })
+  req.url = '/api/turn-notify/projection?cursor=1'
+  req.socket = { remoteAddress }
+  const res = makeRes()
+  const pending = routes.get('/api/turn-notify/projection')(req, res)
+  return { pending, res }
+}
+
+test('Given 总开关开且本机长轮询在途 When 回合完成 Then 宿主让位;离场超窗后接管', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    const saved = await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    assert.equal(saved.body.hostNotify, true)
+    const { pending, res } = hangingPoll(routes, '127.0.0.1')
+    await flushMicrotasks()
+    // 在途请求即在场信号:浏览器优先,宿主让位,正常路径零重复
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 0, '本机长轮询在途,宿主让位')
+    // 在途请求被回合事件唤醒完成,宽限窗口内仍算在场
+    await pending
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 0, '长轮询刚完成,宽限窗口内仍由浏览器呈现')
+    // 推进时钟越过宽限窗口:本机视为离场,宿主接管(宁可重复不可漏)
+    const realNow = Date.now
+    Date.now = () => realNow() + CLIENT_PRESENCE_WINDOW_MS + 1
+    try {
+      await emitCompletedTurn(handlers)
+    } finally { Date.now = realNow }
+    assert.equal(spawns.length, 1, '离场超窗,宿主接管')
+    const projection = await pollProjection(routes, undefined)
+    assert.equal(projection.body.units.length, 3, '浏览器呈现通道不受让位影响')
+  })
+})
+
+test('Given 总开关开且本机长轮询断连 When 回合完成 Then 认可窗口内让位,超窗接管', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    const { pending, res } = hangingPoll(routes, '127.0.0.1')
+    await flushMicrotasks()
+    // 浏览器关闭中止请求:close 事件即时出账,最近活动定格于断连时刻
+    res.emit('close')
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 0, '断连后认可窗口内仍算在场(边界情况宁可不弹)')
+    // 推进时钟越过认可窗口:宿主接管
+    const realNow = Date.now
+    Date.now = () => realNow() + CLIENT_PRESENCE_WINDOW_MS + 1
+    try {
+      await emitCompletedTurn(handlers)
+    } finally { Date.now = realNow }
+    assert.equal(spawns.length, 1, '断连超窗,宿主接管')
+    // 唤醒挂起的等待事务,防测试尾部悬挂 25 秒定时器
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    await pending
+  })
+})
+
+test('Given 记账轮询正常完成后再触发 close When 时钟推进越过认可窗 Then 出账幂等不双计', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    // 全程虚拟时钟:消解真实间隔,配平断言只依赖显式推进
+    const realNow = Date.now
+    let fake = 1000 * 1000
+    Date.now = () => fake
+    try {
+      const first = await browserPoll(routes, '127.0.0.1')
+      // 生产正常完成路径:finally 已出账,响应完成后的 close 再触发须被幂等消化;
+      // 若双出账致计数走负,时钟推进后本应让位的在途轮询将误弹
+      first.emit('close')
+      const second = hangingPoll(routes, '127.0.0.1')
+      await flushMicrotasks()
+      fake += CLIENT_PRESENCE_WINDOW_MS + 1
+      await emitCompletedTurn(handlers)
+      assert.equal(spawns.length, 0, '计数未被双出账破坏,在途轮询仍正常让位')
+      await second.pending
+      fake += CLIENT_PRESENCE_WINDOW_MS + 1
+      await emitCompletedTurn(handlers)
+      assert.equal(spawns.length, 1, '出账配平正确,超窗接管不受影响')
+    } finally { Date.now = realNow }
+  })
+})
+
+test('Given 双 tab 并发挂起其一断连 When 时钟推进越过认可窗 Then 在途方仍让位,全部出账后接管', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    const realNow = Date.now
+    let fake = 1000 * 1000
+    Date.now = () => fake
+    try {
+      const tabA = hangingPoll(routes, '127.0.0.1')
+      const tabB = hangingPoll(routes, '::1')
+      await flushMicrotasks()
+      // tabA 断连即时出账,tabB 独力承载在途信号
+      tabA.res.emit('close')
+      await flushMicrotasks()
+      fake += CLIENT_PRESENCE_WINDOW_MS + 1
+      await emitCompletedTurn(handlers)
+      assert.equal(spawns.length, 0, 'tabA 断连出账,tabB 在途,整体在场')
+      // 回合事件唤醒两个挂起轮询,出账后计数归零
+      await Promise.all([tabA.pending, tabB.pending])
+      fake += CLIENT_PRESENCE_WINDOW_MS + 1
+      await emitCompletedTurn(handlers)
+      assert.equal(spawns.length, 1, '全部出账,计数归零,超窗接管')
+    } finally { Date.now = realNow }
+  })
+})
+
+test('Given 总开关开且仅远程浏览器在线 When 回合完成 Then 宿主弹', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    await browserPoll(routes, '192.168.1.5')
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 1, '远程浏览器不与宿主同机,照常弹')
+    assert.ok(spawns[0].args.flat().join(' ').includes('任务完成'), '通知文本应随 spawn 传出')
+  })
+})
+
+test('Given 总开关开且无浏览器在场 When 回合完成 Then 宿主弹', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 1)
+  })
+})
+
+test('Given kindRoutes 名单不含 host When 总开关开 Then 不弹', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0, kindRoutes: { completed: ['webhook'] } })
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 0, '路由名单外的宿主通道不送达')
+  })
+})
+
+test('Given 回退开关开 When 本机长轮询在途 Then 不弹;仅远程在线 Then 弹', async () => {
+  await withStubSpawn(async (spawns) => {
+    const local = makeCtx()
+    apply(local.ctx)
+    await postConfig(local.routes, { hostNotifyFallback: true, minTurnDurationMs: 0 })
+    const localPoll = hangingPoll(local.routes, '::1')
+    await flushMicrotasks()
+    await emitCompletedTurn(local.handlers)
+    assert.equal(spawns.length, 0, '本机浏览器在途,回退不触发')
+    await postConfig(local.routes, { hostNotifyFallback: true, minTurnDurationMs: 0 })
+    await localPoll.pending
+    // 独立实例:本机从未有浏览器,仅远程浏览器轮询过
+    const remote = makeCtx()
+    apply(remote.ctx)
+    await postConfig(remote.routes, { hostNotifyFallback: true, minTurnDurationMs: 0 })
+    await browserPoll(remote.routes, '10.0.0.8')
+    await emitCompletedTurn(remote.handlers)
+    assert.equal(spawns.length, 1, '本机无浏览器,回退触发')
+  })
+})
+
+test('Given 裸 GET 形态(无 cursor 或 no-cors 或跨源)When 回合完成 Then 回退不触发(伪造在场不入账)', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotifyFallback: true, minTurnDurationMs: 0 })
+    // 回环来源但缺 cursor:手工探测形态
+    await rawShapePoll(routes, '127.0.0.1', 'cors', false)
+    // 回环来源带 cursor 但 no-cors:同机网页 img 探活形态
+    await rawShapePoll(routes, '127.0.0.1', 'no-cors', true)
+    // 回环来源带 cursor 且 cors 但跨源 Origin:同机恶意网页标准 fetch 形态
+    await rawShapePoll(routes, '127.0.0.1', 'cors', true, 'https://evil.example')
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 1, '伪造在场不入账,本机无真实浏览器时回退照常触发')
+  })
+})
+
+test('Given spawn 失败 When 回合完成 Then 无未处理拒绝且投影照常', async () => {
+  const rejections = []
+  const onUnhandled = (reason) => rejections.push(reason)
+  process.on('unhandledRejection', onUnhandled)
+  const original = __hostSpawn.impl
+  __hostSpawn.impl = (file, args, options, callback) => callback(new Error('no desktop'))
+  try {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    handlers.get('session/event')(MAIN, { type: 'turn/start' })
+    handlers.get('session/event')(MAIN, turnEnd('completed'))
+    await flushMicrotasks()
+    await flushMicrotasks()
+    assert.equal(rejections.length, 0)
+    const projection = await pollProjection(routes, undefined)
+    assert.equal(projection.body.units.length, 1)
+  } finally {
+    process.off('unhandledRejection', onUnhandled)
+    __hostSpawn.impl = original
+  }
+})
+
+test('Given 两开关均关 When 回合完成 Then 不弹', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { minTurnDurationMs: 0 })
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 0)
+  })
+})
+
+test('Given test-host 路由 When 合法点火 Then 返回真实结果;非法方法与跨源被拒', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    const ok = makeRes()
+    await routes.get('/api/turn-notify/test-host')(makeReq('POST'), ok)
+    assert.equal(ok.status, 200)
+    assert.deepEqual(ok.body, { ok: true, detail: '已触发宿主通知' })
+    assert.equal(spawns.length, 1)
+    assert.ok(spawns[0].args.flat().join(' ').includes('[dsh]'), '测试事件文本应随 spawn 传出')
+    const method = makeRes()
+    await routes.get('/api/turn-notify/test-host')(makeReq('PUT'), method)
+    assert.equal(method.status, 405)
+    const cross = makeRes()
+    await routes.get('/api/turn-notify/test-host')(makeReq('POST', undefined, { origin: 'https://evil.example' }), cross)
+    assert.equal(cross.status, 403)
+    assert.equal(spawns.length, 1, '被拒请求不触发 spawn')
+  })
+})
+
+test('Given 测试点火在途 When 再次点火 Then 429 且不重复 spawn', async () => {
+  const releases = []
+  const original = __hostSpawn.impl
+  __hostSpawn.impl = (file, args, options, callback) => { releases.push(callback) }
+  try {
+    const { ctx, routes } = makeCtx()
+    apply(ctx)
+    const first = routes.get('/api/turn-notify/test-host')(makeReq('POST'), makeRes())
+    const secondRes = makeRes()
+    await routes.get('/api/turn-notify/test-host')(makeReq('POST'), secondRes)
+    assert.equal(secondRes.status, 429, '在途期间拒绝并发点火')
+    assert.equal(releases.length, 1, '在途期间不重复 spawn')
+    releases[0](null)
+    await first
+    // 释放后互斥复位:再次点火可正常 spawn;spawn 回执由本测试持有,先到账再释放
+    const third = makeRes()
+    const thirdCall = routes.get('/api/turn-notify/test-host')(makeReq('POST'), third)
+    await flushMicrotasks()
+    assert.equal(releases.length, 2, '互斥复位后恢复 spawn')
+    releases[1](null)
+    await thirdCall
+    assert.equal(third.status, 200)
+  } finally { __hostSpawn.impl = original }
+})

package/test/sounds.route.test.mjs

@@ -20,19 +20,20 @@ const soundsDir = join(homeRoot, '.dsh', 'dsh-turn-notify', 'sounds')
 const JSON_HEADERS = { 'content-type': 'application/json' }
 const WAV_BYTES = Buffer.from([1, 2, 3, 4])
 
+// res 桩带事件能力:投影处理器挂 close 事件感知断连,桩须支持 once
 function makeRes() {
-  return {
-    status: null,
-    body: null,
-    raw: null,
-    headers: null,
-    writeHead(status, headers) { this.status = status; this.headers = headers },
-    end(body) {
-      if (Buffer.isBuffer(body)) this.raw = body
-      else if (typeof body === 'string' && (this.headers ? String(this.headers['content-type']) : '').includes('json')) this.body = JSON.parse(body)
-      else this.raw = body
-    },
+  const res = new EventEmitter()
+  res.status = null
+  res.body = null
+  res.raw = null
+  res.headers = null
+  res.writeHead = (status, headers) => { res.status = status; res.headers = headers }
+  res.end = (body) => {
+    if (Buffer.isBuffer(body)) res.raw = body
+    else if (typeof body === 'string' && (res.headers ? String(res.headers['content-type']) : '').includes('json')) res.body = JSON.parse(body)
+    else res.raw = body
   }
+  return res
 }
 
 function makeReq(method, payload, headers, url) {