@mzzsfy/dsh-turn-notify 0.11.0 → 0.12.0

package/README.md

@@ -82,16 +82,16 @@ turn-notify:
 
 ## 宿主桌面通知
 
-开启面板"通知"页的宿主通知开关后,通知触发时由宿主进程直接弹操作系统级桌面通知,零依赖:macOS 走 osascript,Linux 走 notify-send,Windows 走 PowerShell 调 WinRT toast;超时 10 秒,失败即弃不重试,不影响其余通道。去重方向为**浏览器优先**:本机浏览器在场(2 秒内有在途长轮询)时由浏览器呈现,宿主让位,正常路径同机零重复;本机浏览器离场(标签页全关或仅远程浏览器在线)时宿主补位。重复只发生在在场判定的边界情况(认可窗口边界与网络抖动),宁可重复不可漏。两个开关判定一致,任一开启即生效:
+开启面板"通知"页的宿主通知开关后,通知触发时由宿主进程直接弹操作系统级桌面通知,零依赖:macOS 走 osascript,Linux 走 notify-send,Windows 走 PowerShell 调 WinRT toast;超时 10 秒,失败即弃不重试,不影响其余通道。去重方向为**浏览器优先**:浏览器在场(2 秒内有在途长轮询)时由浏览器呈现,宿主让位,正常路径零重复;浏览器离场(标签页全关)时宿主补位。重复只发生在在场判定的边界情况(认可窗口边界与网络抖动),宁可重复不可漏。两个开关判定一致,任一开启即生效:
 
 - **宿主机弹桌面通知**:启用宿主通知通道(浏览器优先去重内建)。
-- **仅当本机无浏览器接收时补位**:与总开关等效,作为显式的补位语义表达保留。
+- **仅当无浏览器接收时补位**:与总开关等效,作为显式的补位语义表达保留。
 
-"本机浏览器在场"按投影长轮询记账:回环来源 + 续传 cursor + 同源形态的 GET 在服务端挂起期间计为在途,断连(标签页关闭/请求中止)经连接关闭事件即时出账,最近活动在 2 秒认可窗口内仍算在场——优雅断连的盲区不超过 2 秒;异常断连(睡眠、强杀、断网)服务端无感知,受长轮询挂起上限约束,最坏约 25 秒后自愈出账。浏览器在场但本机呈现偏好全关(声音/弹窗/页内全关或系统通知未授权)时,宿主同样让位,该事件本机无 OS 级通知(仅剩会话行高亮)。宿主在无桌面的服务器上时 spawn 会静默失败,无害;测试页"测试宿主通知"返回真实结果,可据此验证宿主机桌面环境是否可用。聚焦时宿主通知照弹(宿主无法感知窗口焦点,聚焦静默是浏览器侧偏好)。
+"浏览器在场"按投影长轮询记账:任意来源 + 续传 cursor + 同源形态的 GET 在服务端挂起期间计为在途,断连(标签页关闭/请求中止)经连接关闭事件即时出账,最近活动在 2 秒认可窗口内仍算在场——优雅断连的盲区不超过 2 秒;异常断连(睡眠、强杀、断网)服务端无感知,受长轮询挂起上限约束,最坏约 25 秒后自愈出账。来源不限地址:浏览器可在任意机器访问 dsh(局域网部署),在场信号看的是"有无 dsh 页面在轮询",与浏览器同不同机无关。浏览器在场但在场浏览器的呈现偏好全关(声音/弹窗/页内全关或系统通知未授权)时,宿主同样让位,该事件在浏览器侧无 OS 级通知(仅剩会话行高亮)。宿主在无桌面的服务器上时 spawn 会静默失败,无害;测试页"测试宿主通知"返回真实结果,可据此验证宿主机桌面环境是否可用。聚焦时宿主通知照弹(宿主无法感知窗口焦点,聚焦静默是浏览器侧偏好)。
 
 ## IM 推送
 
-安装 [@xmanrui/dsh-im](https://www.npmjs.com/package/@xmanrui/dsh-im) 后自动启用,可推送到微信等九种渠道。投递目标的新建与平台测试在 dsh-im 设置页完成,本插件只做选择:从已绑 bot 的目标目录勾选即保存,支持绑定多个 bot。触发逻辑与 webhook 一致,fire-and-forget 不重试;bot 离线时该次通知弃置不补发。
+安装 [@xmanrui/dsh-im](https://www.npmjs.com/package/@xmanrui/dsh-im) 后自动启用,可推送到微信等九种渠道。投递目标的新建与平台测试在 dsh-im 设置页完成,本插件只做选择:从已绑 bot 的目标目录勾选即保存,支持绑定多个 bot。IM 卡顶部有总开关,关闭后不向已配目标投递、目标绑定原样保留,临时停用不必逐个移除目标,再开即恢复。触发逻辑与 webhook 一致,fire-and-forget 不重试;bot 离线时该次通知弃置不补发。测试页的"测试 IM 通知"为显式点火,不受总开关影响。
 
 ## 会话行高亮
 
@@ -114,7 +114,7 @@ turn-notify:
 | 通知 | webhook 地址、最短回合时长、子代理过滤、宿主通知(总开关与回退)、六类事件开关;存 settings.yaml,事件开关点击即存,其余点保存后生效。事件→通道路由(kindRoutes)亦存此命名空间,经 yaml 配置 |
 | 偏好 | 本机浏览器记忆的设置:会话高亮(独立开关)、声音总开关与分类静音、音量、系统弹窗与授权、页内提示开关、页内提示音(总开关 + 分类独立开关)、聚焦静默、降级标题闪烁 |
 | 音效 | 音效上传/试听/重命名/删除,六类事件的音效映射与双作用域开关,页内提示音映射(本机,未配置沿用通知音效) |
-| IM | 绑定 dsh-im bot、勾选投递目标(仅装了 dsh-im 时显示) |
+| IM | IM 总开关(关闭保留目标)、绑定 dsh-im bot、勾选投递目标(仅装了 dsh-im 时显示) |
 | 测试 | 声音/页内/系统/宿主/webhook/IM 逐通道点火,回执即真实结果 |
 
 ## settings.yaml 参考
@@ -127,8 +127,8 @@ turn-notify:
   minTurnDurationMs: 5000         # 最短回合时长(毫秒),回合结束类通知短于此不送达
   rootsOnly: true                 # 子代理会话不通知
   suppressSubagentWake: true      # 子代理相关回合不通知:后台委托未收尾或收尾唤醒(仅任务完成类)
-  hostNotify: false               # 宿主机桌面通知总开关;浏览器优先,本机浏览器在场(2 秒内有在途长轮询)时让位
-  hostNotifyFallback: false       # 宿主通知补位:本机浏览器离场(2 秒内无在途长轮询)时弹宿主桌面通知,与总开关判定一致
+  hostNotify: false               # 宿主机桌面通知总开关;浏览器优先,浏览器在场(2 秒内有在途长轮询)时让位
+  hostNotifyFallback: false       # 宿主通知补位:浏览器离场(2 秒内无在途长轮询)时弹宿主桌面通知,与总开关判定一致
   enabled:                        # 六类事件独立开关
     completed: true
     error: true
@@ -143,6 +143,7 @@ turn-notify:
   imTargets:                      # dsh-im 投递目标,空数组禁用
     - botId: wx_xxx
       targetId: owner
+  imEnabled: true                 # IM 推送总开关:关闭后不投递,目标绑定保留
 ```
 
 音量、聚焦静默、分类静音等本机偏好存浏览器 localStorage,不经 yaml。
@@ -153,18 +154,18 @@ 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 与宿主桌面通知(如开启)送达(声音与弹窗的浏览器前提)。
-- 宿主桌面通知为浏览器优先去重:本机浏览器在场(2 秒内有在途长轮询)时宿主让位,边界情况(认可窗口边界、网络抖动、反代致来源恒为回环而恒判在场)宁可不弹不误弹,优雅断连的离场盲区不超过 2 秒,异常断连受长轮询挂起上限约束(最坏约 25 秒);聚焦时宿主通知照弹(宿主无法感知窗口焦点);无桌面的宿主上 spawn 静默失败,无害。在场记账的形态校验(回环 + 续传 cursor + 同源)为启发式,防无意探活误压制与网页伪造在场(DNS rebinding 将域解析至回环的页面同源可过校验,但该页面同时已握有全部写配置 API,通知压制非最大损失面),不构成对抗本机进程的安全边界。
+- 宿主桌面通知为浏览器优先去重:浏览器在场(2 秒内有在途长轮询)时宿主让位,边界情况(认可窗口边界、网络抖动)宁可不弹不误弹,优雅断连的离场盲区不超过 2 秒,异常断连受长轮询挂起上限约束(最坏约 25 秒);聚焦时宿主通知照弹(宿主无法感知窗口焦点);无桌面的宿主上 spawn 静默失败,无害。在场记账的形态校验(续传 cursor + 同源 fetch 形态)为启发式,防无意探活误压制与网页伪造在场(DNS rebinding 将域解析至 dsh 的页面同源可过校验,但该页面同时已握有全部写配置 API,通知压制非最大损失面),不构成对抗本机进程的安全边界。
 - IM 依赖 dsh-im 的 bot 在线,离线时该次通知弃置不补发;成功回执仅代表平台受理。
 - 不同浏览器或不同地址打开的窗口各自发声,互不去重。
 - 系统弹窗在 HTTP 非回环下永久降级,HTTPS 化后自动恢复;Windows 下受系统通知设置与专注助手约束。
-- 长轮询空闲期连接由代理或服务端挂起,经中间反代时需允许数十秒的挂起响应,否则退化为更频繁的重连。
+- 长轮询空闲期连接由代理或服务端挂起,经中间反代时需允许数十秒的挂起响应,否则退化为更频繁的重连;反代还需透传 Host 头(如 nginx `proxy_set_header Host $host`),否则同源对账失败、真实浏览器不入账,宿主通知每次重复弹(失败方向与"宁可重复不可漏"一致)。
 - 等待动作二次提醒的"已处理"判定以本窗口可见信号(会话切换/高亮清除)近似,无会话标题的通知无法感知处理,宁可多响一次。
 - 点击直达依赖侧边栏会话行可被标题匹配命中,行未渲染或标题不同步时仅聚焦不切换。
 
@@ -189,3 +190,6 @@ node scripts/dev-link.mjs dsh-turn-notify   # 仓库根执行:归一 profile 依
 
 工作副本以 junction 挂进 profile,host 半区改动保存约 1 秒热重载,client 半区改动刷新页面即生效,无需发版;规约与全仓归一见 `node scripts/dev-link.mjs all`。
 
+## dsh 版本兼容
+
+三版本全部通过:通知开关与播报形态、激活 live。0.1.6 控件数 13→19 属宿主演进,不构成不兼容。

package/package.json

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

package/src/client.js

@@ -278,7 +278,7 @@ window.__ModuleLoader__.load({
     const IDLE_AWAY_MS = 5 * 60 * 1000
 
     // 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
@@ -1071,6 +1071,7 @@ window.__ModuleLoader__.load({
       folderRunningEnabled: true,
       enabled: Object.fromEntries(CATEGORIES.map((key) => [key, true])),
       imTargets: [],
+      imEnabled: true,
     }
 
     const CSS = [
@@ -1616,6 +1617,18 @@ window.__ModuleLoader__.load({
         void persistImTargets(removeImTargetFromList(config.imTargets, item.botId, item.targetId))
       }
 
+      // IM 总开关:目标绑定保留,关闭仅停投递;乐观回填,失败回滚
+      function toggleImEnabled(checked) {
+        setConfig((prev) => ({ ...prev, imEnabled: checked }))
+        api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify({ imEnabled: checked }) })
+          .then((res) => setConfig({ ...DEFAULT_CONFIG, ...res }))
+          .catch((error) => {
+            // 回滚到请求发出前的取值:两次异步 setConfig 闭包各自读到已更新的 prev
+            setConfig((prev) => ({ ...prev, imEnabled: !prev.imEnabled }))
+            patch('IM 开关切换失败:' + (error && error.message ? error.message : String(error)), 'error')
+          })
+      }
+
       // 取消注册:移除该 bot 全部目标;bot 在 dsh-im 已删除时借此清理残留绑定
       function unregisterImBot(botId) {
         void persistImTargets(
@@ -1755,19 +1768,19 @@ window.__ModuleLoader__.load({
                 ' 后台委托未收尾或收尾唤醒的回合不通知(仅完成类)'),
             ]),
             field('宿主通知', [
-              h('label', { className: 'tn-meta tn-switch', title: '通知触发时由宿主进程弹系统级桌面通知(osascript/notify-send/PowerShell toast);浏览器优先:本机有浏览器窗口在线(2 秒内有在途长轮询)时由浏览器呈现,宿主不重复弹;本机无浏览器(标签页全关或仅远程浏览器)时宿主弹' },
+              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 秒内有在途长轮询)时由浏览器呈现,离场时宿主补位桌面通知;与总开关判定一致,任一开启即生效' },
+              h('label', { className: 'tn-meta tn-switch', title: '浏览器在场(2 秒内有在途长轮询)时由浏览器呈现,离场时宿主补位桌面通知;与总开关判定一致,任一开启即生效' },
                 ...switchToggle({
                   checked: config.hostNotifyFallback,
                   onChange: (e) => setConfig({ ...config, hostNotifyFallback: e.target.checked }),
                 }),
-                ' 仅当本机无浏览器接收时补位'),
-            ], '由宿主进程直接弹 OS 桌面通知,服务器/浏览器全关场景可达;浏览器优先——本机浏览器在线时由浏览器呈现,宿主不重复弹,离场(2 秒内无在途长轮询)时宿主补位,边界情况(窗口边界与网络抖动)宁重复不漏。需点保存生效,测试页可逐条点火验证。'),
+                ' 仅当无浏览器接收时补位'),
+            ], '由宿主进程直接弹 OS 桌面通知,服务器/浏览器全关场景可达;浏览器优先——浏览器在线时由浏览器呈现,宿主不重复弹,离场(2 秒内无在途长轮询)时宿主补位,边界情况(窗口边界与网络抖动)宁重复不漏。需点保存生效,测试页可逐条点火验证。'),
             field('事件分类', h('div', { className: 'tn-pills' },
               CATEGORIES.map((category) => h('span', {
                 className: 'tn-pill' + (config.enabled[category] ? ' tn-pill--on' : ''),
@@ -2002,6 +2015,14 @@ window.__ModuleLoader__.load({
               h('span', { className: 'tn-card__title' }, 'IM 投递(dsh-im)'),
               h('span', { className: 'tn-card__sub' }, '勾选目标即自动保存;支持绑定多个 bot,点 bot 名加载其目录,× 取消注册'),
             ),
+            field('IM 开关', [
+              h('label', { className: 'tn-meta tn-switch', title: '关闭后不再向已配目标投递 IM 通知,目标绑定保留;再次开启即恢复推送' },
+                ...switchToggle({
+                  checked: config.imEnabled,
+                  onChange: (e) => toggleImEnabled(e.target.checked),
+                }),
+                ' 启用 IM 推送'),
+            ], '关闭时通知不推送 IM,已勾选的目标与 bot 绑定原样保留,无需移除目标'),
             field('Bot ID', [
               h('input', {
                 className: 'tn-input tn-fill', type: 'text',

package/src/core.mjs

@@ -499,35 +499,29 @@ 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 }) {
+export function hostNotifyWanted({ hostNotify, hostNotifyFallback, browserPresent }) {
   if (hostNotify !== true && hostNotifyFallback !== true) return false
-  return localBrowserPresent !== true
+  return browserPresent !== true
 }
 
-// 本机浏览器在场判定:有在途长轮询即在场信号(无论时间戳新旧);无在途时,
+// 浏览器在场判定:有在途长轮询即在场信号(无论时间戳新旧);无在途时,
 // 最近活动在认可窗口内(长轮询刚完成、断连刚出账)仍算在场,超窗或从未在场为假
-export function isLocalBrowserPresent({ inFlightPolls, lastSeenAt, now, windowMs }) {
+export function isBrowserPresent({ 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
+// 浏览器轮询判定:长轮询续传形态(带 cursor)+ fetch 请求形态 + Origin 对账。
+// 来源不限地址:浏览器可在任意机器访问 dsh(局域网部署),在场信号看的是
+// "有无 dsh 页面在轮询",与浏览器同不同机无关。投影为无守卫 GET,记账须排除
+// 可伪造在场的形态:no-cors(img 跨站探活)、无 cursor 的手工探测、跨源 fetch
+// (恶意网页,sec-fetch-mode 同为 cors 无法区分,凭 Origin 与 Host 不符识别;
+// 同源 GET fetch 不带 Origin,无 Origin 放行,旧浏览器同样覆盖)——只有 dsh
+// 同源页面自身能发出合格形态,伪造面与来源地址无关
+export function isBrowserPoll({ hasCursor, secFetchMode, origin, host }) {
   if (hasCursor !== true) return false
   if (secFetchMode !== undefined && secFetchMode !== 'cors') return false
   if (typeof origin === 'string' && origin.length > 0) {
@@ -641,7 +635,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', 'hostNotify', 'hostNotifyFallback', 'folderRunningEnabled']
+  const known = ['webhookUrl', 'minTurnDurationMs', 'rootsOnly', 'suppressSubagentWake', 'enabled', 'imTargets', 'imEnabled', 'kindRoutes', 'hostNotify', 'hostNotifyFallback', 'folderRunningEnabled']
   for (const key of Object.keys(patch)) {
     if (known.indexOf(key) < 0) return { ok: false, reason: '未知配置项: ' + key }
   }
@@ -681,6 +675,10 @@ export function validateConfigPatch(patch) {
     }
     next.imTargets = targets
   }
+  if ('imEnabled' in patch) {
+    if (typeof patch.imEnabled !== 'boolean') return { ok: false, reason: 'imEnabled 须为布尔' }
+    next.imEnabled = patch.imEnabled
+  }
   if ('minTurnDurationMs' in patch) {
     const ms = patch.minTurnDurationMs
     if (typeof ms !== 'number' || !Number.isInteger(ms) || ms < 0) return { ok: false, reason: 'minTurnDurationMs 须为非负整数' }
@@ -775,6 +773,8 @@ export function resolvedConfig(settings) {
     enabled: Object.fromEntries(CATEGORIES.map((key) => [key, enabled[key] !== false])),
     soundMapping,
     imTargets: normalizeImTargets(source.imTargets),
+    // 开关缺省回开:存量配置升级行为不变
+    imEnabled: source.imEnabled !== false,
     kindRoutes: routesVerdict.ok ? routesVerdict.routes : {},
   }
 }
@@ -792,6 +792,7 @@ export function publicConfig(settings) {
     enabled: resolved.enabled,
     soundMapping: resolved.soundMapping,
     imTargets: resolved.imTargets,
+    imEnabled: resolved.imEnabled,
     kindRoutes: resolved.kindRoutes,
     webhookUrl: resolved.webhookUrl,
   }

package/src/index.js

@@ -27,8 +27,8 @@ import {
   isSubagentWakeTurn,
   isValidImBotId,
   hostNotifyWanted,
-  isLocalBrowserPoll,
-  isLocalBrowserPresent,
+  isBrowserPoll,
+  isBrowserPresent,
   mapEventToCategory,
   mimeOf,
   normalizeImTargets,
@@ -62,7 +62,7 @@ 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
 
@@ -92,12 +92,13 @@ 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 秒内无在途长轮询)时宿主补位;与总开关判定一致,任一开启即生效'),
+  hostNotify: z.boolean().default(false).description('宿主机桌面通知:通知触发时由宿主进程弹系统级通知(osascript/notify-send/PowerShell toast);浏览器优先,浏览器在场(2 秒内有在途长轮询)时由浏览器呈现宿主不重复弹,离场时宿主补位'),
+  hostNotifyFallback: z.boolean().default(false).description('宿主通知回退:浏览器在场时由浏览器呈现,离场(2 秒内无在途长轮询)时宿主补位;与总开关判定一致,任一开启即生效'),
   folderRunningEnabled: z.boolean().default(true).description('工作区文件夹运行标记:侧边栏分组模式下,有运行中会话的文件夹组头显示运行点并给图标着色;关闭后标记整体不渲染,变更刷新页面生效'),
   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 通道'),
+  imEnabled: z.boolean().default(true).description('IM 推送总开关:关闭后不向已配目标投递,目标绑定保留'),
   kindRoutes: z.dict(z.array(z.string())).default({}).description('事件→通道路由:分类到放行通道名单(sound/system/toast/blink/webhook/im/host),未配置的分类全通道放行'),
 })
 
@@ -208,10 +209,10 @@ export function apply(ctx) {
   const titledSessions = new Set()
   // 回合尾部统计:assistant/message 的 tokens 累加与回答前缀,回合结束随通知消费即清
   const assistantTails = new Map()
-  // 本机(回环来源)浏览器在场信号:在途长轮询计数与最近活动时刻,
+  // 浏览器在场信号:在途长轮询计数与最近活动时刻,
   // 在场 = 有在途请求或认可窗口内有活动,宿主通知的浏览器优先去重据此判定
-  let inFlightLocalPolls = 0
-  let lastLocalClientSeenAt = 0
+  let inFlightBrowserPolls = 0
+  let lastBrowserSeenAt = 0
   let seq = 0
   // 音效库写互斥:展示名索引读改写与落盘非原子,串行化防并发交错
   let soundWriteQueue = Promise.resolve()
@@ -274,16 +275,16 @@ export function apply(ctx) {
     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,
+      browserPresent: isBrowserPresent({
+        inFlightPolls: inFlightBrowserPolls,
+        lastSeenAt: lastBrowserSeenAt,
         now: Date.now(),
         windowMs: CLIENT_PRESENCE_WINDOW_MS,
       }),
@@ -311,6 +312,8 @@ export function apply(ctx) {
   function deliverIm(unit, settings) {
     const dshIm = ctx.get('dshIm')
     if (dshIm === undefined) return
+    // 总开关关闭:目标绑定保留,仅不投递
+    if (settings.imEnabled === false) return
     for (const { botId, targetId } of normalizeImTargets(settings.imTargets)) {
       void Promise.resolve().then(() => dshIm.send(botId, targetId, unit.text, { signal: AbortSignal.timeout(WEBHOOK_TIMEOUT_MS) })).catch(() => {})
     }
@@ -441,27 +444,26 @@ export function apply(ctx) {
       path: '/api/turn-notify/projection',
       handler: route('GET', {}, async (req, res) => {
         const query = new URL(req.url, 'http://localhost').searchParams
-        // 回环来源的浏览器长轮询即本机在场信号,宿主通知的浏览器优先去重据此判定;
+        // 浏览器长轮询即在场信号,宿主通知的浏览器优先去重据此判定;
         // 记账形态收紧防伪造:裸 GET(img 探活/监控探测)与跨源 fetch 不入账。
         // 记账期间计入在途,断连(浏览器关闭/中止)经 res close 事件即时出账,
         // 离场盲区收敛到认可窗口
-        let releaseLocalPoll = null
-        if (isLocalBrowserPoll({
-          remoteAddress: req.socket && req.socket.remoteAddress,
+        let releaseBrowserPoll = null
+        if (isBrowserPoll({
           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
+          inFlightBrowserPolls += 1
           let settled = false
-          releaseLocalPoll = () => {
+          releaseBrowserPoll = () => {
             if (settled) return
             settled = true
-            inFlightLocalPolls -= 1
-            lastLocalClientSeenAt = Date.now()
+            inFlightBrowserPolls -= 1
+            lastBrowserSeenAt = Date.now()
           }
-          res.once('close', releaseLocalPoll)
+          res.once('close', releaseBrowserPoll)
         }
         try {
           const rawCursor = Number(query.get('cursor'))
@@ -472,7 +474,7 @@ export function apply(ctx) {
           const settings = readSettings(ctx)
           sendJson(res, 200, { units: projection.list(), soundMapping: settings.soundMapping, version: projection.version() })
         } finally {
-          if (releaseLocalPoll !== null) releaseLocalPoll()
+          if (releaseBrowserPoll !== null) releaseBrowserPoll()
         }
       }),
     })
@@ -758,6 +760,7 @@ export function apply(ctx) {
           sendJson(res, 200, { ok: false, detail: '未配置投递目标' })
           return
         }
+        // 点火测试与开关无关:显式验证通道连通,不受投递总开关压制
         // 逐目标结算,真实结果随响应返回,与 test-webhook 的不谎报原则一致
         const results = await Promise.all(targets.map(async ({ botId, targetId }) => {
           try {

package/test/core.test.mjs

@@ -646,6 +646,10 @@ test('配置补丁校验:非法输入逐类拒绝', () => {
   assert.equal(validateConfigPatch({ minTurnDurationMs: 'fast' }).ok, false)
   assert.equal(validateConfigPatch({ rootsOnly: 'yes' }).ok, false)
   assert.equal(validateConfigPatch({ suppressSubagentWake: 'yes' }).ok, false)
+  // imEnabled:布尔放行,非布尔拒绝
+  assert.deepEqual(validateConfigPatch({ imEnabled: false }), { ok: true, patch: { imEnabled: false } })
+  assert.equal(validateConfigPatch({ imEnabled: 'yes' }).ok, false)
+  assert.equal(validateConfigPatch({ imEnabled: 1 }).ok, false)
   assert.equal(validateConfigPatch({ enabled: { unknown: true } }).ok, false)
   assert.equal(validateConfigPatch({ enabled: { completed: 'no' } }).ok, false)
   assert.equal(validateConfigPatch({ enabled: [true] }).ok, false)
@@ -665,6 +669,7 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
+      imEnabled: true,
       kindRoutes: { completed: ['webhook'] },
     },
   )
@@ -679,10 +684,14 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
     enabled: Object.fromEntries(CATEGORIES.map((name) => [name, true])),
     soundMapping: {},
     imTargets: [],
+    imEnabled: true,
     kindRoutes: {},
   })
   assert.equal(resolvedConfig({ minTurnDurationMs: Number.NaN }).minTurnDurationMs, MIN_TURN_MS)
   assert.equal(resolvedConfig({ suppressSubagentWake: false }).suppressSubagentWake, false)
+  // imEnabled:显式 false 生效,缺省或类型异常回开(升级兼容)
+  assert.equal(resolvedConfig({ imEnabled: false }).imEnabled, false)
+  assert.equal(resolvedConfig({ imEnabled: 'no' }).imEnabled, true)
 })
 
 test('面板可见配置:webhookUrl 原文回显', () => {
@@ -698,6 +707,7 @@ test('面板可见配置:webhookUrl 原文回显', () => {
       enabled: { completed: false, error: true, interrupted: true, approval: true, ask: true, 'max-tokens': true },
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
+      imEnabled: true,
       kindRoutes: { ask: ['im'] },
       webhookUrl: 'https://hook.example/service/xxx',
     },

package/test/event-wiring.test.mjs

@@ -377,6 +377,27 @@ test('Given dshIm 在场且已配多目标 When 回合完成 Then 逐目标投
   assert.ok(sends.every((call) => String(call.text).startsWith('[dsh]')), 'IM 文本应与通知单元一致')
 })
 
+test('Given 已配目标且 imEnabled=false When 回合完成 Then 不投递且目标保留', async () => {
+  const sends = []
+  const { ctx, routes, handlers } = makeCtx({ dshIm: makeImDshIm(sends) })
+  apply(ctx)
+  await disableDurationFilter(routes)
+  await configureImTargets(routes, [{ botId: 'wx_a', targetId: 'owner' }, { botId: 'wx_b', targetId: 'group' }])
+  const offRes = makeRes()
+  await routes.get('/api/turn-notify/config')(makeReq('POST', { imEnabled: false }, JSON_HEADERS), offRes)
+  assert.equal(offRes.status, 200)
+  assert.equal(offRes.body.imEnabled, false)
+  assert.equal(offRes.body.imTargets.length, 2, '开关关闭不应清空目标')
+  const onEvent = handlers.get('session/event')
+  onEvent(MAIN, { type: 'turn/start' })
+  onEvent(MAIN, turnEnd('completed'))
+  await flushMicrotasks()
+  assert.equal(sends.length, 0, 'imEnabled=false 时不投递')
+  // 投影照常:开关只压制 IM 通道
+  const units = await projectionUnits(routes)
+  assert.equal(units.filter((unit) => unit.category === 'completed').length, 1)
+})
+
 test('Given send 拒绝 When 回合完成 Then 无未处理拒绝且投影照常', async () => {
   const rejections = []
   const onUnhandled = (reason) => rejections.push(reason)

package/test/host-notify.test.mjs

@@ -1,4 +1,4 @@
-// 宿主桌面通知 BDD:core 纯函数(回环判定 / 派发决策 / 平台命令 / spawn 执行 / 配置键)
+// 宿主桌面通知 BDD:core 纯函数(派发决策 / 平台命令 / spawn 执行 / 配置键)
 // 与 host 接线集成(stub ctx 装载真实 src/index.js,stub spawn 观测派发)。
 import test from 'node:test'
 import assert from 'node:assert/strict'
@@ -10,53 +10,32 @@ import {
   HOST_NOTIFY_TIMEOUT_MS,
   hostNotifyCommand,
   hostNotifyWanted,
-  isLocalBrowserPoll,
-  isLocalBrowserPresent,
-  isLoopbackAddress,
+  isBrowserPoll,
+  isBrowserPresent,
   publicConfig,
   resolvedConfig,
   sendHostNotify,
   validateConfigPatch,
 } from '../src/core.mjs'
 
-// ---- isLoopbackAddress:同机判定,回环地址即本机浏览器 ----
+// ---- isBrowserPoll:在场记账形态收紧,防伪造在场压制宿主通知 ----
 
-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 合格轮询形态(任意来源加 cursor 加 fetch 形态或无 Sec-Fetch 头)When 判定 Then 为真', () => {
+  assert.equal(isBrowserPoll({ hasCursor: true, secFetchMode: 'cors' }), true)
+  assert.equal(isBrowserPoll({ hasCursor: true, secFetchMode: undefined }), 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 无 cursor 或 no-cors 形态 When 判定 Then 为假', () => {
+  assert.equal(isBrowserPoll({ hasCursor: false, secFetchMode: 'cors' }), false)
+  assert.equal(isBrowserPoll({ hasCursor: true, secFetchMode: 'no-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 不放行')
+  const base = { hasCursor: true, secFetchMode: 'cors' }
+  assert.equal(isBrowserPoll({ ...base, origin: undefined, host: '127.0.0.1:3080' }), true, '同源 GET fetch 不带 Origin')
+  assert.equal(isBrowserPoll({ ...base, origin: 'http://127.0.0.1:3080', host: '127.0.0.1:3080' }), true)
+  assert.equal(isBrowserPoll({ ...base, origin: 'https://evil.example', host: '127.0.0.1:3080' }), false, '跨源 fetch 必带且与 Host 不符')
+  assert.equal(isBrowserPoll({ ...base, origin: 'not a url', host: '127.0.0.1:3080' }), false, '畸形 Origin 不放行')
 })
 
 // ---- hostNotifyWanted:浏览器优先,在场让位、离场补位;重复只发生在边界情况 ----
@@ -64,36 +43,36 @@ test('Given Origin 缺席或与 Host 一致 When 判定 Then 为真;跨源或畸
 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, browserPresent: false }), true)
+  assert.equal(hostNotifyWanted({ hostNotifyFallback: true, browserPresent: false }), true)
+  assert.equal(hostNotifyWanted({ hostNotify: true, hostNotifyFallback: true, browserPresent: 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({ hostNotify: true, browserPresent: true }), false)
+  assert.equal(hostNotifyWanted({ hostNotifyFallback: true, browserPresent: true }), false)
+  assert.equal(hostNotifyWanted({ hostNotify: true, hostNotifyFallback: true, browserPresent: true }), false)
 })
 
 test('Given 两开关均关 When 决策 Then 恒不弹', () => {
-  assert.equal(hostNotifyWanted({ localBrowserPresent: false }), false)
-  assert.equal(hostNotifyWanted({ hostNotify: false, hostNotifyFallback: false, localBrowserPresent: false }), false)
+  assert.equal(hostNotifyWanted({ browserPresent: false }), false)
+  assert.equal(hostNotifyWanted({ hostNotify: false, hostNotifyFallback: false, browserPresent: false }), false)
 })
 
-// ---- isLocalBrowserPresent:在场 = 有在途长轮询,或宽限窗口内有活动 ----
+// ---- isBrowserPresent:在场 = 有在途长轮询,或宽限窗口内有活动 ----
 
 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)
+  assert.equal(isBrowserPresent({ inFlightPolls: 1, lastSeenAt: NOW - WINDOW_MS - 1, now: NOW, windowMs: WINDOW_MS }), true)
+  assert.equal(isBrowserPresent({ 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)
+  assert.equal(isBrowserPresent({ inFlightPolls: 0, lastSeenAt: NOW - 1, now: NOW, windowMs: WINDOW_MS }), true)
+  assert.equal(isBrowserPresent({ inFlightPolls: 0, lastSeenAt: NOW - WINDOW_MS, now: NOW, windowMs: WINDOW_MS }), true)
+  assert.equal(isBrowserPresent({ inFlightPolls: 0, lastSeenAt: NOW - WINDOW_MS - 1, now: NOW, windowMs: WINDOW_MS }), false)
+  assert.equal(isBrowserPresent({ inFlightPolls: 0, lastSeenAt: 0, now: NOW, windowMs: WINDOW_MS }), false)
+  assert.equal(isBrowserPresent({ inFlightPolls: 0, lastSeenAt: undefined, now: NOW, windowMs: WINDOW_MS }), false)
 })
 
 // ---- hostNotifyCommand:平台命令构造与文本转义 ----
@@ -209,7 +188,7 @@ test('Given 缺省配置 When 解析 Then 两键回 false;CHANNELS 含 host', ()
   assert.ok(CHANNELS.indexOf('host') >= 0, 'host 应为可路由通道')
 })
 
-// ---- host 接线集成:stub spawn 观测派发,presence 经投影路由的来源地址注入 ----
+// ---- host 接线集成:stub spawn 观测派发,presence 经投影路由的请求形态注入 ----
 
 // res 桩带事件能力:投影处理器挂 close 事件感知断连,桩须支持 once/emit;
 // end 不自动触发 close,断连时机由测试显式 emit 模拟
@@ -272,30 +251,31 @@ async function postConfig(routes, patch) {
   return res
 }
 
-async function pollProjection(routes, remoteAddress) {
+async function pollProjection(routes) {
   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 取超前值立即返回,不挂起
+// 浏览器长轮询记账形态:任意来源 + 带续传 cursor + fetch 形态头;
+// cursor 取超前值立即返回,不挂起。跨机地址为主场景(真实部署拓扑:
+// 浏览器在局域网另一台机器访问 dsh),回环为同机特例
 const FUTURE_CURSOR = 2 ** 40
-async function browserPoll(routes, remoteAddress) {
+const REMOTE_BROWSER = '10.123.90.14'
+async function browserPoll(routes) {
   const req = makeReq('GET', undefined, { 'sec-fetch-mode': 'cors' })
   req.url = '/api/turn-notify/projection?cursor=' + FUTURE_CURSOR
-  req.socket = { remoteAddress }
+  req.socket = { remoteAddress: REMOTE_BROWSER }
   const res = makeRes()
   await routes.get('/api/turn-notify/projection')(req, res)
   assert.equal(res.status, 200)
   return res
 }
 
-// 伪形态轮询:回环来源但缺 cursor / no-cors / 跨源 Origin,记账须拒绝
+// 伪形态轮询:缺 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
@@ -330,9 +310,11 @@ async function emitCompletedTurn(handlers) {
 }
 
 // 挂起中的长轮询:cursor 等于当前版本(配置 POST 后为 1),服务端挂起等待,
-// 模拟真实客户端的在途请求;返回 pending 承诺与 res 桩(供断连模拟与唤醒等待)
-function hangingPoll(routes, remoteAddress) {
-  const req = makeReq('GET', undefined, { 'sec-fetch-mode': 'cors' })
+// 模拟真实客户端的在途请求;返回 pending 承诺与 res 桩(供断连模拟与唤醒等待);
+// secFetchMode 缺省 cors,传 undefined 模拟不发 Sec-Fetch 头的旧浏览器
+function hangingPoll(routes, remoteAddress, secFetchMode) {
+  const headers = secFetchMode === undefined ? {} : { 'sec-fetch-mode': secFetchMode }
+  const req = makeReq('GET', undefined, headers)
   req.url = '/api/turn-notify/projection?cursor=1'
   req.socket = { remoteAddress }
   const res = makeRes()
@@ -340,39 +322,53 @@ function hangingPoll(routes, remoteAddress) {
   return { pending, res }
 }
 
-test('Given 总开关开且本机长轮询在途 When 回合完成 Then 宿主让位;离场超窗后接管', async () => {
+test('Given 旧浏览器形态(无 Sec-Fetch 头)跨机长轮询在途 When 回合完成 Then 宿主让位', async () => {
+  await withStubSpawn(async (spawns) => {
+    const { ctx, routes, handlers } = makeCtx()
+    apply(ctx)
+    await postConfig(routes, { hostNotify: true, minTurnDurationMs: 0 })
+    const { pending } = hangingPoll(routes, REMOTE_BROWSER, undefined)
+    await flushMicrotasks()
+    await emitCompletedTurn(handlers)
+    assert.equal(spawns.length, 0, '无 Sec-Fetch 头的同源续传轮询同样入账,宿主让位')
+    await pending
+  })
+})
+
+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')
+    const { pending, res } = hangingPoll(routes, REMOTE_BROWSER)
     await flushMicrotasks()
-    // 在途请求即在场信号:浏览器优先,宿主让位,正常路径零重复
+    // 在途请求即在场信号:浏览器优先,宿主让位,正常路径零重复;
+    // 浏览器在局域网另一台机器访问时同样让位
     await emitCompletedTurn(handlers)
-    assert.equal(spawns.length, 0, '本机长轮询在途,宿主让位')
+    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)
+    const projection = await pollProjection(routes)
     assert.equal(projection.body.units.length, 3, '浏览器呈现通道不受让位影响')
   })
 })
 
-test('Given 总开关开且本机长轮询断连 When 回合完成 Then 认可窗口内让位,超窗接管', async () => {
+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')
+    const { pending, res } = hangingPoll(routes, REMOTE_BROWSER)
     await flushMicrotasks()
     // 浏览器关闭中止请求:close 事件即时出账,最近活动定格于断连时刻
     res.emit('close')
@@ -401,7 +397,7 @@ test('Given 记账轮询正常完成后再触发 close When 时钟推进越过
     let fake = 1000 * 1000
     Date.now = () => fake
     try {
-      const first = await browserPoll(routes, '127.0.0.1')
+      const first = await browserPoll(routes)
       // 生产正常完成路径:finally 已出账,响应完成后的 close 再触发须被幂等消化;
       // 若双出账致计数走负,时钟推进后本应让位的在途轮询将误弹
       first.emit('close')
@@ -427,8 +423,8 @@ test('Given 双 tab 并发挂起其一断连 When 时钟推进越过认可窗 Th
     let fake = 1000 * 1000
     Date.now = () => fake
     try {
-      const tabA = hangingPoll(routes, '127.0.0.1')
-      const tabB = hangingPoll(routes, '::1')
+      const tabA = hangingPoll(routes, REMOTE_BROWSER)
+      const tabB = hangingPoll(routes, '127.0.0.1')
       await flushMicrotasks()
       // tabA 断连即时出账,tabB 独力承载在途信号
       tabA.res.emit('close')
@@ -445,15 +441,23 @@ test('Given 双 tab 并发挂起其一断连 When 时钟推进越过认可窗 Th
   })
 })
 
-test('Given 总开关开且仅远程浏览器在线 When 回合完成 Then 宿主弹', async () => {
+test('Given 回退开关开 When 跨机长轮询在途 Then 不弹;无浏览器在场 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 传出')
+    const local = makeCtx()
+    apply(local.ctx)
+    await postConfig(local.routes, { hostNotifyFallback: true, minTurnDurationMs: 0 })
+    const localPoll = hangingPoll(local.routes, REMOTE_BROWSER)
+    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 emitCompletedTurn(remote.handlers)
+    assert.equal(spawns.length, 1, '无浏览器在场,回退触发')
   })
 })
 
@@ -477,40 +481,19 @@ test('Given kindRoutes 名单不含 host When 总开关开 Then 不弹', async (
   })
 })
 
-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')
+    // 浏览器来源但缺 cursor:手工探测形态
+    await rawShapePoll(routes, REMOTE_BROWSER, 'cors', false)
+    // 浏览器来源带 cursor 但 no-cors:dsh 同源网页的 img 探活形态
+    await rawShapePoll(routes, REMOTE_BROWSER, 'no-cors', true)
+    // 浏览器来源带 cursor 且 cors 但跨源 Origin:任意机器上恶意网页的标准 fetch 形态
+    await rawShapePoll(routes, REMOTE_BROWSER, 'cors', true, 'https://evil.example')
     await emitCompletedTurn(handlers)
-    assert.equal(spawns.length, 1, '伪造在场不入账,本机无真实浏览器时回退照常触发')
+    assert.equal(spawns.length, 1, '伪造在场不入账,无真实浏览器时回退照常触发')
   })
 })
 
@@ -529,7 +512,7 @@ test('Given spawn 失败 When 回合完成 Then 无未处理拒绝且投影照
     await flushMicrotasks()
     await flushMicrotasks()
     assert.equal(rejections.length, 0)
-    const projection = await pollProjection(routes, undefined)
+    const projection = await pollProjection(routes)
     assert.equal(projection.body.units.length, 1)
   } finally {
     process.off('unhandledRejection', onUnhandled)