@mzzsfy/dsh-turn-notify 0.8.0 → 0.9.0

package/README.md

@@ -78,7 +78,7 @@ turn-notify:
 
 ## webhook 推送
 
-在面板填入 webhook URL 即启用。host 直发,标签页全关也送达;payload 为 Slack 兼容 JSON(text 字段承载通知文本,summary 字段承载通知小结),另附 event/category/status/session/workspace/durationMs/tokens/ts 结构化字段;超时 10 秒,不重试。凭据只写不回显,测试按钮返回真实投递结果。
+在面板填入 webhook URL 即启用。host 直发,标签页全关也送达;payload 为 Slack 兼容 JSON(text 字段承载通知文本,summary 字段承载通知小结),另附 event/category/status/session/workspace/durationMs/tokens/ts 结构化字段;超时 10 秒,不重试。URL 原文随配置响应回显、保存即提交输入框内容(清空并保存即禁用),测试按钮返回真实投递结果。
 
 ## IM 推送
 
@@ -106,7 +106,7 @@ turn-notify:
 
 ## settings.yaml 参考
 
-面板与 settings.yaml 读写同一命名空间,两边改动互通、保存即生效。webhookUrl 属凭据,面板只写不回显,yaml 直改仍可。
+面板与 settings.yaml 读写同一命名空间,两边改动互通、保存即生效。webhookUrl 随面板配置响应回显,yaml 直改同样可见。
 
 ```yaml
 turn-notify:
@@ -155,7 +155,7 @@ turn-notify:
 ## 安全
 
 - 配置写入类接口(config / mapping / upload / 音效改名与删除 / 测试)带同源守卫:Origin 与 Host 不符即 403,JSON 写入另校验 content-type,阻断跨站页面 drive-by 改写配置。
-- webhookUrl 标记为 secret,任何接口不回传原文。
+- webhookUrl 在 settings 层标记为 secret(导出与日志脱敏);面板配置接口原文回显,本机同源可读写。
 - 音效上传双重校验扩展名与真实音频内容;音效读取接口拒绝音频扩展名以外的文件。
 - 已知边界:同源守卫不防 DNS rebinding(Origin 与 Host 相等即放行)。该暴露面属 host webserver 全部 /api 路由的存量问题,应在 host 层统一解决而非逐插件补丁。
 

package/package.json

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

package/src/client.js

@@ -8,7 +8,7 @@ window.__ModuleLoader__.load({
   id: '@mzzsfy/dsh-turn-notify',
   factory(require) {
     const React = require('react')
-    const { useState, useEffect } = React
+    const { useState, useEffect, useRef } = React
 
     // 通知出口:公共依赖 @mzzsfy/dsh-toast,可选消费——共享依赖包的模块表注入
     // 全仓收敛到唯一权威消费方(session-manager),本插件不再代挂占位条目;
@@ -827,13 +827,28 @@ window.__ModuleLoader__.load({
 
     // 宿主重渲染会重建行节点抹掉高亮类,观察器在同一帧内补齐;
     // applySessionHighlights 幂等(类齐不写 DOM),观察器链自然收敛;
-    // 令牌承载 observer:HMR 重建闭包后先断开旧代再挂新代,旧闭包不滞留
+    // 令牌承载 observer 与 pending 帧:HMR 重建闭包后先断开旧代 observer、
+    // cancel 旧代 pending 帧(帧回调持有旧代高亮 Map,不取消会写幽灵高亮),
+    // 旧闭包不滞留;rAF 合批:流式期间 DOM 变更批远高于帧率,同帧多批合并
+    // 为一次重应用(同帧补齐语义不变),无高亮条目时不排帧
     const KEY_HL_OBSERVER = 'turn-notify:hl-observer'
+    const KEY_HL_FRAME = 'turn-notify:hl-frame'
     function ensureHighlightObserver() {
       if (typeof document === 'undefined' || typeof document.body === 'undefined' || typeof MutationObserver === 'undefined') return
       if (window[KEY_HL_OBSERVER] !== undefined && typeof window[KEY_HL_OBSERVER].disconnect === 'function') window[KEY_HL_OBSERVER].disconnect()
+      if (typeof window[KEY_HL_FRAME] === 'number') {
+        cancelAnimationFrame(window[KEY_HL_FRAME])
+      }
+      // 哨兵 0 = 无在途帧(规范 rAF 句柄自 1 起,cancel 0 为 no-op);新代显式归零,
+      // 防 undefined 初始态使在途判定恒真、帧永不排程
+      window[KEY_HL_FRAME] = 0
       const observer = new MutationObserver(() => {
-        if (sessionHighlightEnabled && sessionHighlights.size > 0) applySessionHighlights()
+        if (!sessionHighlightEnabled || sessionHighlights.size === 0) return
+        if (window[KEY_HL_FRAME] !== 0) return
+        window[KEY_HL_FRAME] = requestAnimationFrame(() => {
+          window[KEY_HL_FRAME] = 0
+          if (sessionHighlightEnabled && sessionHighlights.size > 0) applySessionHighlights()
+        })
       })
       observer.observe(document.body, { childList: true, subtree: true })
       window[KEY_HL_OBSERVER] = observer
@@ -994,10 +1009,10 @@ window.__ModuleLoader__.load({
 
     const PERMISSION_LABELS = { granted: '已授权', denied: '已拒绝', default: '未授权' }
 
-    // 面板表单占位:GET config 返回前展示;webhookUrl 凭据不出主机,面板只见是否已配置;
+    // 面板表单占位:GET config 返回前展示;webhookUrl 原文随响应回显,表单所见即所存;
     // imAvailable 缺省为假,加载响应后 dsh-im 在场才渲染 IM 投递卡
     const DEFAULT_CONFIG = {
-      webhookConfigured: false,
+      webhookUrl: '',
       minTurnDurationMs: 5 * 1000,
       rootsOnly: true,
       suppressSubagentWake: true,
@@ -1181,6 +1196,7 @@ window.__ModuleLoader__.load({
           .then((res) => {
             setConfig({ ...DEFAULT_CONFIG, ...res })
             setMappingState(res.soundMapping || {})
+            setUrlDraft(typeof res.webhookUrl === 'string' ? res.webhookUrl : '')
             setConfigLoaded(true)
           })
           .catch(() => {})
@@ -1351,14 +1367,12 @@ window.__ModuleLoader__.load({
             : String(config.minTurnDurationMs)
           if (raw.length === 0) throw new Error('最短回合时长不能为空')
           const trimmedUrl = urlDraft.trim()
-          // imTargets 由勾选单独即时保存,不随此入口提交;会话高亮为本机开关,不进 host 配置
-          const patchBody = { minTurnDurationMs: Number(raw), rootsOnly: config.rootsOnly, suppressSubagentWake: config.suppressSubagentWake }
-          // 只写语义:输入留空即保持现有 webhook 不变
-          if (trimmedUrl.length > 0) patchBody.webhookUrl = trimmedUrl
+          // 所见即所存:输入框即配置值,清空并保存即禁用 webhook 通道
+          const patchBody = { webhookUrl: trimmedUrl, minTurnDurationMs: Number(raw), rootsOnly: config.rootsOnly, suppressSubagentWake: config.suppressSubagentWake }
           const res = await api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify(patchBody) })
           setConfig({ ...DEFAULT_CONFIG, ...res })
           if (res.soundMapping) setMappingState(res.soundMapping)
-          setUrlDraft('')
+          setUrlDraft(typeof res.webhookUrl === 'string' ? res.webhookUrl : '')
           patch('配置已保存,立即生效')
         } catch (error) {
           patch('保存失败:' + (error && error.message ? error.message : String(error)), 'error')
@@ -1371,7 +1385,7 @@ window.__ModuleLoader__.load({
           const res = await api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify({ webhookUrl: '' }) })
           setConfig({ ...DEFAULT_CONFIG, ...res })
           if (res.soundMapping) setMappingState(res.soundMapping)
-          setUrlDraft('')
+          setUrlDraft(typeof res.webhookUrl === 'string' ? res.webhookUrl : '')
           patch('webhook 已清除')
         } catch (error) {
           patch('清除失败:' + (error && error.message ? error.message : String(error)), 'error')
@@ -1452,8 +1466,9 @@ window.__ModuleLoader__.load({
       }
 
       async function testWebhook() {
-        if (urlDraft.trim().length > 0) {
-          patch('表单中的新 webhook URL 尚未保存,本次测试的是已保存配置;请先保存再测试', 'error')
+        // 草稿与已保存值不同即存在未保存改动,测试的只能是已保存配置
+        if (urlDraft.trim() !== String(config.webhookUrl || '').trim()) {
+          patch('表单中的 webhook URL 尚未保存,本次测试的是已保存配置;请先保存再测试', 'error')
           return
         }
         try {
@@ -1484,14 +1499,16 @@ window.__ModuleLoader__.load({
       // 已绑 bot chips 由 imBoundBotIds 去重(见 LOGIC 段同源函数)
       const imBoundBots = imBoundBotIds(config.imTargets)
 
-      // 勾选即存:与分类开关同模式,列表整体替换,连续操作以最新一次请求为准
-      let imPersistSeq = 0
+      // 勾选即存:与分类开关同模式,列表整体替换,连续操作以最新一次请求为准;
+      // seq 守卫须跨渲染存活(useRef),组件体内 let 声明每次渲染重置使守卫失效
+      const imPersistSeqRef = useRef(0)
       async function persistImTargets(next, okMessage) {
-        const seq = ++imPersistSeq
+        imPersistSeqRef.current += 1
+        const seq = imPersistSeqRef.current
         setConfig({ ...config, imTargets: next })
         try {
           const res = await api('/api/turn-notify/config', { method: 'POST', body: JSON.stringify({ imTargets: next }) })
-          if (seq === imPersistSeq) {
+          if (seq === imPersistSeqRef.current) {
             setConfig({ ...DEFAULT_CONFIG, ...res })
             if (res.soundMapping) setMappingState(res.soundMapping)
             if (okMessage !== undefined) patch(okMessage)
@@ -1615,15 +1632,15 @@ window.__ModuleLoader__.load({
             field('webhook', [
               h('input', {
                 className: 'tn-input tn-fill', type: 'text',
-                title: '通知由 host 直接 POST 到该地址,标签页全关也送达;Slack 兼容 JSON 格式,超时 10 秒不重试,凭据不回显',
-                placeholder: config.webhookConfigured ? '已配置(输入新 URL 替换,留空保持不变)' : 'Slack-compatible URL,留空禁用',
+                title: '通知由 host 直接 POST 到该地址,标签页全关也送达;Slack 兼容 JSON 格式,超时 10 秒不重试',
+                placeholder: 'Slack-compatible URL,留空禁用',
                 value: urlDraft,
                 onChange: (e) => setUrlDraft(e.target.value),
               }),
-              config.webhookConfigured
+              String(config.webhookUrl || '').trim().length > 0
                 ? h('button', { className: 'tn-btn tn-btn--danger', disabled: busy, title: '清除已配置的 webhook,清除后该通道禁用', onClick: () => void clearWebhook() }, '清除')
                 : null,
-            ], 'URL 只写不回显'),
+            ], '保存即提交输入框内容,清空并保存即禁用;改动后先保存,测试按钮只测已保存配置'),
             field('最短回合时长', [
               h('input', {
                 className: 'tn-input', type: 'number', min: 0, step: 500, style: { width: '90px' },

package/src/core.mjs

@@ -664,7 +664,7 @@ export function resolvedConfig(settings) {
   }
 }
 
-// 面板可见配置:webhookUrl 属凭据不出主机,仅回是否已配置。
+// 面板可见配置:webhookUrl 原文随响应回显,面板所见即所存。
 export function publicConfig(settings) {
   const resolved = resolvedConfig(settings)
   return {
@@ -675,6 +675,6 @@ export function publicConfig(settings) {
     soundMapping: resolved.soundMapping,
     imTargets: resolved.imTargets,
     kindRoutes: resolved.kindRoutes,
-    webhookConfigured: resolved.webhookUrl.trim().length > 0,
+    webhookUrl: resolved.webhookUrl,
   }
-}
+}

package/test/core.test.mjs

@@ -679,7 +679,7 @@ test('配置解析:enabled 缺省键按开补全,字段类型回退默认', () =
   assert.equal(resolvedConfig({ suppressSubagentWake: false }).suppressSubagentWake, false)
 })
 
-test('面板可见配置:webhookUrl 不出主机,仅回是否已配置', () => {
+test('面板可见配置:webhookUrl 原文回显', () => {
   assert.deepEqual(
     publicConfig({ webhookUrl: 'https://hook.example/service/xxx', enabled: { completed: false }, soundMapping: { completed: 'snd-1' }, kindRoutes: { ask: ['im'] } }),
     {
@@ -690,12 +690,13 @@ test('面板可见配置:webhookUrl 不出主机,仅回是否已配置', () => {
       soundMapping: { completed: 'snd-1' },
       imTargets: [],
       kindRoutes: { ask: ['im'] },
-      webhookConfigured: true,
+      webhookUrl: 'https://hook.example/service/xxx',
     },
   )
-  assert.equal(publicConfig({}).webhookConfigured, false)
-  assert.equal(publicConfig({ webhookUrl: '   ' }).webhookConfigured, false)
-  assert.equal('webhookUrl' in publicConfig({ webhookUrl: 'https://hook.example' }), false)
+  assert.equal(publicConfig({}).webhookUrl, '')
+  // 空白串原样回显,不静默归一
+  assert.equal(publicConfig({ webhookUrl: '   ' }).webhookUrl, '   ')
+  assert.equal('webhookConfigured' in publicConfig({ webhookUrl: 'https://hook.example' }), false)
 })
 
 test('会话事件有界累积:标题提取后封账为字符串,内存不再增长', () => {

package/test/hooks-destructure.test.mjs

@@ -0,0 +1,28 @@
+// client 半区 React hooks 解构静态断言:client.js 为经典 bundle,组件渲染路径
+// 无运行时测试,hooks 未从 React 解构的缺陷(useRef is not a function)只能靠
+// 源码静态比对拦截——组件体内使用的全部 hooks 必须出现在解构清单。
+import test from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync } from 'node:fs'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const source = readFileSync(join(root, 'src', 'client.js'), 'utf8')
+
+test('client.js 组件使用的全部 React hooks 均在解构清单中', () => {
+  // Given 解构行(const { ... } = React)与全源码 hooks 调用
+  const destructure = /const\s*\{([^}]+)\}\s*=\s*React\b/.exec(source)
+  assert.notEqual(destructure, null, 'React 解构行必须存在')
+  const declared = new Set(destructure[1].split(',').map((name) => name.trim()).filter(Boolean))
+  const used = [...source.matchAll(/\b(use[A-Z]\w*)\s*\(/g)].map((match) => match[1])
+  assert.ok(used.length > 0, '至少存在一个 hooks 调用,否则断言失效')
+  // Then 每个使用的 hooks 都已声明
+  const missing = [...new Set(used)].filter((name) => !declared.has(name))
+  assert.deepEqual(missing, [], '未解构的 hooks(渲染即 ReferenceError)')
+})
+
+test('client.js 不存在 React.useXxx 直调形态(绕过解构清单)', () => {
+  const direct = [...source.matchAll(/\bReact\.(use[A-Z]\w*)\s*\(/g)].map((match) => match[1])
+  assert.deepEqual(direct, [], 'hooks 一律经解构清单使用,便于静态断言')
+})

package/test/route.test.mjs

@@ -79,7 +79,7 @@ function makeCtx(extraServices) {
   return { ctx, routes }
 }
 
-test('config GET 返回解析后的默认配置,webhookUrl 凭据不出主机', async () => {
+test('config GET 返回解析后的默认配置,webhookUrl 原文回显', async () => {
   const { ctx, routes } = makeCtx()
   apply(ctx)
   const handler = routes.get('/api/turn-notify/config')
@@ -87,8 +87,8 @@ test('config GET 返回解析后的默认配置,webhookUrl 凭据不出主机',
   const res = makeRes()
   await handler(makeReq('GET'), res)
   assert.equal(res.status, 200)
-  assert.equal(res.body.webhookConfigured, false)
-  assert.equal('webhookUrl' in res.body, false)
+  assert.equal(res.body.webhookUrl, '')
+  assert.equal('webhookConfigured' in res.body, false)
   assert.equal(res.body.minTurnDurationMs, MIN_TURN_MS)
   assert.equal(res.body.rootsOnly, true)
   assert.equal(res.body.enabled.completed, true)
@@ -105,12 +105,30 @@ test('config POST 非法补丁 400,合法补丁持久化且部分开关不覆盖
   const good = makeRes()
   await handler(makeReq('POST', { webhookUrl: 'https://hook.example', enabled: { completed: false } }, JSON_HEADERS), good)
   assert.equal(good.status, 200)
-  assert.equal(good.body.webhookConfigured, true)
+  assert.equal(good.body.webhookUrl, 'https://hook.example')
   assert.equal(good.body.enabled.completed, false)
   assert.equal(good.body.enabled.error, true)
   const readback = makeRes()
   await handler(makeReq('GET'), readback)
-  assert.equal(readback.body.webhookConfigured, true)
+  assert.equal(readback.body.webhookUrl, 'https://hook.example')
+})
+
+test('config POST 空串清空 webhookUrl:先存后清双向回环,清后通道禁用', async () => {
+  const { ctx, routes } = makeCtx()
+  apply(ctx)
+  const handler = routes.get('/api/turn-notify/config')
+  const save = makeRes()
+  await handler(makeReq('POST', { webhookUrl: 'https://hook.example/x' }, JSON_HEADERS), save)
+  assert.equal(save.status, 200)
+  assert.equal(save.body.webhookUrl, 'https://hook.example/x')
+  // 清空并保存=禁用:空串经校验落库,回读为空串而非回退旧值
+  const clear = makeRes()
+  await handler(makeReq('POST', { webhookUrl: '' }, JSON_HEADERS), clear)
+  assert.equal(clear.status, 200)
+  assert.equal(clear.body.webhookUrl, '')
+  const readback = makeRes()
+  await handler(makeReq('GET'), readback)
+  assert.equal(readback.body.webhookUrl, '')
 })
 
 test('config POST 负路径:跨源 403,非 JSON 400,畸形体 400,空补丁 200', async () => {
@@ -228,7 +246,7 @@ test('config POST 仅 imTargets 的部分补丁:不触碰其他配置项,响应
   const res = makeRes()
   await handler(makeReq('POST', { imTargets: [{ botId: 'wx_a', targetId: 'owner' }, { botId: 'wx_b', targetId: 'owner' }] }, JSON_HEADERS), res)
   assert.equal(res.status, 200)
-  assert.equal(res.body.webhookConfigured, true)
+  assert.equal(res.body.webhookUrl, 'https://hooks.example.com/x')
   assert.equal(res.body.enabled.completed, false)
   assert.deepEqual(res.body.imTargets, [{ botId: 'wx_a', targetId: 'owner' }, { botId: 'wx_b', targetId: 'owner' }])
   // 取消注册:整列表替换为空,其余配置仍原样
@@ -236,7 +254,7 @@ test('config POST 仅 imTargets 的部分补丁:不触碰其他配置项,响应
   await handler(makeReq('POST', { imTargets: [] }, JSON_HEADERS), clear)
   assert.equal(clear.status, 200)
   assert.deepEqual(clear.body.imTargets, [])
-  assert.equal(clear.body.webhookConfigured, true)
+  assert.equal(clear.body.webhookUrl, 'https://hooks.example.com/x')
   assert.equal(clear.body.enabled.completed, false)
 })