dsh-notify-say 0.4.21 → 0.4.25

package/lib/session-bridge.js

@@ -1,117 +1,138 @@
-/**
- * 会话状态桥（host 半侧 HTTP route）。
- *
- * ## 为什么需要它
- *
- * client 半侧要「点 Toast 后跳到那条通知对应的会话」，但它拿不到会话 id：
- *
- *   - 渲染进程是 `sandbox:true / contextIsolation:true / nodeIntegration:false`
- *     （app.asar 实测）→ **没有 `process`**，读不了 `$DSH_HOME` 下的文件；
- *   - 也不能直接访问 host 的 Cordis 服务（只有白名单里的 remote 事件）。
- *
- * 所以走官方给的正路：host 注册一个 `/api/...` route，client 用 `fetch` 取。
- * 本机先例：`dsh-our-free-model` 用 `webServer.register({ kind:'prefix' })` +
- * client 侧 `fetch('api/our-free-model')`（注释里提醒要用 `document.baseURI` 解析，
- * 不能写 origin-absolute 的 `/api/...`，否则反向代理下会 404）。
- *
- * ## 稳定性设计（本插件首要目标）
- *
- * `webServer` 是可选依赖，**拿不到就整体不注册**，插件其余功能（Toast + 语音）
- * 完全不受影响。这与「配置层失败就降级」是同一套思路：
- * 任何增强能力都不得连累主功能。
- *
- * route 只做两件事：
- *   GET  /api/dsh-notify-say/last-session  → { sessionId, at } 或 204
- *   POST /api/dsh-notify-say/consume       → 读一次并清空（防重复跳转）
- */
-
-/** route 前缀（client 侧据此拼接）。 */
-export const ROUTE_PREFIX = '/api/dsh-notify-say';
-
-/** 取最近通知会话的路径。 */
-export const ROUTE_LAST = ROUTE_PREFIX + '/last-session';
-
-/** 消费（读取并清空）的路径。 */
-export const ROUTE_CONSUME = ROUTE_PREFIX + '/consume';
-
-/**
- * 创建 route handler。状态放在闭包里，不落盘 ——
- * 这是**进程内、短生命周期**的一次性信号，重启即失效，正好符合语义
- * （重启后没有"刚才那条通知"了）。
- *
- * @returns {{ handler: Function, setLast: Function, peek: Function }}
- */
-export function createSessionBridge() {
-  /** @type {{ sessionId: string, at: number } | null} */
-  let last = null;
-
-  /** 记录一条通知对应的会话（供 client 取用）。 */
-  function setLast(sessionId, now) {
-    try {
-      const sid = typeof sessionId === 'string' ? sessionId.trim() : '';
-      if (!sid) return;
-      last = { sessionId: sid, at: typeof now === 'number' ? now : Date.now() };
-    } catch { /* 通知主流程不因此中断 */ }
-  }
-
-  /** 只看不取。 */
-  function peek() {
-    return last;
-  }
-
-  /**
-   * HTTP handler。
-   *
-   * 支持两种形态的 register 回调（本机实测不同插件用法不同）：
-   *   - `{ request, response }` 风格（Node http）
-   *   - `(req, res)` 位置参数风格
-   * 统一从第一个参数上取 request/response，兼容两者。
-   */
-  function handler(...args) {
-    const req = args[0] && args[0].request ? args[0].request
-      : (args[0] && args[0].req ? args[0].req : args[0]);
-    const res = args[0] && args[0].response ? args[0].response
-      : (args[0] && args[0].res ? args[0].res : args[1]);
-
-    const send = (code, body) => {
-      try {
-        if (res && typeof res.writeHead === 'function') {
-          const text = body === undefined ? '' : JSON.stringify(body);
-          res.writeHead(code, {
-            'content-type': 'application/json; charset=utf-8',
-            'cache-control': 'no-store',
-          });
-          res.end(text);
-          return;
-        }
-        if (res && typeof res.setHeader === 'function' && typeof res.end === 'function') {
-          res.statusCode = code;
-          res.setHeader('content-type', 'application/json; charset=utf-8');
-          res.setHeader('cache-control', 'no-store');
-          res.end(body === undefined ? '' : JSON.stringify(body));
-        }
-      } catch { /* 响应写失败不影响后续 */ }
-    };
-
-    try {
-      const url = String((req && (req.url || req.path)) || '');
-      const isConsume = url.indexOf('/consume') >= 0;
-
-      if (isConsume) {
-        const hit = last;
-        last = null;                 // 消费即清，避免重复跳转
-        if (!hit) { send(204); return; }
-        send(200, hit);
-        return;
-      }
-
-      // 默认走 last-session
-      if (!last) { send(204); return; }
-      send(200, last);
-    } catch {
-      send(500, { error: 'internal' });
-    }
-  }
-
-  return { handler, setLast, peek };
-}
+/**
+ * 会话状态桥（host 半侧 HTTP route）。
+ *
+ * ## 为什么需要它
+ *
+ * client 半侧要「点 Toast 后跳到那条通知对应的会话」，但它拿不到会话 id：
+ *
+ *   - 渲染进程是 `sandbox:true / contextIsolation:true / nodeIntegration:false`
+ *     （app.asar 实测）→ **没有 `process`**，读不了 `$DSH_HOME` 下的文件；
+ *   - 也不能直接访问 host 的 Cordis 服务（只有白名单里的 remote 事件）。
+ *
+ * 所以走官方给的正路：host 注册一个 `/api/...` route，client 用 `fetch` 取。
+ * 本机先例：`dsh-our-free-model` 用 `webServer.register({ kind:'prefix' })` +
+ * client 侧 `fetch('api/our-free-model')`（注释里提醒要用 `document.baseURI` 解析，
+ * 不能写 origin-absolute 的 `/api/...`，否则反向代理下会 404）。
+ *
+ * ## 稳定性设计（本插件首要目标）
+ *
+ * `webServer` 是可选依赖，**拿不到就整体不注册**，插件其余功能（Toast + 语音）
+ * 完全不受影响。这与「配置层失败就降级」是同一套思路：
+ * 任何增强能力都不得连累主功能。
+ *
+ * route 只做两件事：
+ *   GET  /api/dsh-notify-say/last-session  → { sessionId, at } 或 204
+ *   POST /api/dsh-notify-say/consume       → 读一次并清空（防重复跳转）
+ */
+
+/** route 前缀（client 侧据此拼接）。 */
+export const ROUTE_PREFIX = '/api/dsh-notify-say';
+
+/** 取最近通知会话的路径。 */
+export const ROUTE_LAST = ROUTE_PREFIX + '/last-session';
+
+/** 消费（读取并清空）的路径。 */
+export const ROUTE_CONSUME = ROUTE_PREFIX + '/consume';
+
+/**
+ * 创建 route handler。状态放在闭包里，不落盘 ——
+ * 这是**进程内、短生命周期**的一次性信号，重启即失效，正好符合语义
+ * （重启后没有"刚才那条通知"了）。
+ *
+ * @returns {{ handler: Function, setLast: Function, peek: Function }}
+ */
+export function createSessionBridge() {
+  /** @type {{ sessionId: string, at: number } | null} */
+  let last = null;
+
+  /** 记录一条通知对应的会话（供 client 取用）。 */
+  function setLast(sessionId, now) {
+    try {
+      const sid = typeof sessionId === 'string' ? sessionId.trim() : '';
+      if (!sid) return;
+      last = { sessionId: sid, at: typeof now === 'number' ? now : Date.now() };
+    } catch { /* 通知主流程不因此中断 */ }
+  }
+
+  /** 只看不取。 */
+  function peek() {
+    return last;
+  }
+
+  /**
+   * HTTP handler。
+   *
+   * 支持两种形态的 register 回调（本机实测不同插件用法不同）：
+   *   - `{ request, response }` 风格（Node http）
+   *   - `(req, res)` 位置参数风格
+   * 统一从第一个参数上取 request/response，兼容两者。
+   */
+  function handler(...args) {
+    const req = args[0] && args[0].request ? args[0].request
+      : (args[0] && args[0].req ? args[0].req : args[0]);
+    const res = args[0] && args[0].response ? args[0].response
+      : (args[0] && args[0].res ? args[0].res : args[1]);
+
+    const send = (code, body) => {
+      try {
+        if (res && typeof res.writeHead === 'function') {
+          const text = body === undefined ? '' : JSON.stringify(body);
+          res.writeHead(code, {
+            'content-type': 'application/json; charset=utf-8',
+            'cache-control': 'no-store',
+          });
+          res.end(text);
+          return;
+        }
+        if (res && typeof res.setHeader === 'function' && typeof res.end === 'function') {
+          res.statusCode = code;
+          res.setHeader('content-type', 'application/json; charset=utf-8');
+          res.setHeader('cache-control', 'no-store');
+          res.end(body === undefined ? '' : JSON.stringify(body));
+        }
+      } catch { /* 响应写失败不影响后续 */ }
+    };
+
+    try {
+      const url = String((req && (req.url || req.path)) || '');
+      // ⚠️ 必须按**路径段**判断，不能用 indexOf，
+      // 否则 `/last-session?next=/consume` 会被误判成 consume（子串匹配）。
+      const pathname = url.split('?')[0].split('#')[0];
+      // ⚠️ 必须先剥掉 route 前缀再取第一段。
+      // 否则 `/api/dsh-notify-say/consume` 的第一段是 `api`，
+      // 永远匹配不到 consume —— 消费不会清状态（v0.4.25 实测踩到）。
+      const rest = pathname.startsWith(ROUTE_PREFIX)
+        ? pathname.slice(ROUTE_PREFIX.length)
+        : pathname;
+      const head = rest.replace(/^\/+/, '').split('/')[0];
+
+      const isConsume = head === 'consume';
+
+      if (isConsume) {
+        // ⚠️ 只接受 POST：这个动作会**清除服务端状态**，用 GET 既语义不当，
+        // 也会被浏览器的跨站简单请求（<img>/<a>）触发。
+        // 客户端已改为 POST + JSON（见 client.js 的 consumeLastSession）。
+        const method = String((req && req.method) || 'GET').toUpperCase();
+        if (method !== 'POST') {
+          if (res && typeof res.setHeader === 'function') {
+            res.setHeader('allow', 'POST');
+          }
+          send(405, { error: 'method-not-allowed', allow: 'POST' });
+          return;
+        }
+        const hit = last;
+        last = null;                 // 消费即清，避免重复跳转
+        if (!hit) { send(204); return; }
+        send(200, hit);
+        return;
+      }
+      // 默认走 last-session（只读，不改状态）
+      if (!last) { send(204); return; }
+      send(200, last);
+    } catch {
+      send(500, { error: 'internal' });
+    }
+  }
+
+  return { handler, setLast, peek };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-notify-say",
-    "version":  "0.4.21",
+    "version":  "0.4.25",
     "description":  "Desktop notifications for DSH Desktop that actually speak: Windows TTS out of the box (zero download), VOICEVOX voice packs optional, a selectable system-sound fallback, and an idle gate that waits for running subagents before saying the turn is done. Includes a settings-page GUI (sound source, per-event overrides, jump-back-to-session, cooldowns) and a self hot-reload for development.",
     "license":  "MIT",
     "type":  "module",
@@ -29,7 +29,9 @@
                   "tools",
                   "README.md",
                   "LICENSE",
-                  "THIRD-PARTY-NOTICES.md"
+                  "THIRD-PARTY-NOTICES.md",
+                  "test",
+                  "docs"
               ],
     "keywords":  [
                      "dsh",
@@ -47,6 +49,13 @@
                     "node":  "\u003e=20",
                     "dsh":  "\u003e=0.1.7-rc.2"
                 },
+    "scripts":  {
+                    "test":  "node --test",
+                    "test:all":  "node --test \u0026\u0026 node --import ./test/route-loader-register.mjs --test test/fail-route.test.mjs test/audio-wiring.test.mjs",
+                    "test:route":  "node --import ./test/route-loader-register.mjs --test test/fail-route.test.mjs",
+                    "test:audio-wire":  "node --import ./test/route-loader-register.mjs --test test/audio-wiring.test.mjs",
+                    "check:client":  "node ./test/client-bundle.test.mjs"
+                },
     "dsh":  {
                 "manifestVersion":  1,
                 "bundle":  {

package/test/audio-source.test.mjs

@@ -0,0 +1,184 @@
+/**
+ * audio-source 测试：音源解析的穷举验证。
+ *
+ * 这块决定"到底播什么"，写错的表现往往是**静默**的（该说话的变成了静音、
+ * 该用警告音的用了完成音），用户很难察觉。所以穷举所有组合。
+ *
+ * 覆盖：
+ *  - A1  全局默认解析
+ *  - A2  按事件覆盖优先于全局
+ *  - A3  与默认相同的覆盖项被丢弃（保持配置最小）
+ *  - A4  非法值一律收敛到安全默认，不产生半截脏配置
+ *  - A5  回退链：想要的拿不到时，保证仍有声音（除非显式 none）
+ *  - A6  ps1 的 chime → blocked 映射
+ *  - A7  系统音效的语义映射（失败用警告音，不是完成音）
+ *  - A8  自定义文件只接受绝对路径与合法扩展名（防"随机失败"）
+ *  - A9  真实场景组合：完成用语音包、失败用系统音（用户举的例子）
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+
+import {
+  AUDIO_SOURCES, AUDIO_KINDS, DEFAULT_SOURCE, SYSTEM_SOUNDS,
+  normalizeSource, normalizeByKind, resolveSource, audioKindOf,
+  effectiveSource, resolveSystemSound, resolveCustomFile,
+} from '../lib/audio-source.js';
+
+// ── A1: 全局默认 ────────────────────────────────────────────────────────────
+test('A1: 没设置时所有事件都用 tts（零下载即可说话）', () => {
+  assert.equal(normalizeSource(undefined), 'tts');
+  for (const kind of AUDIO_KINDS) {
+    assert.equal(resolveSource(kind, {}), 'tts', `${kind} 应默认 tts`);
+    assert.equal(resolveSource(kind, { audioSource: undefined }), 'tts');
+  }
+  assert.equal(DEFAULT_SOURCE, 'tts');
+});
+
+// ── A2: 按事件覆盖 ──────────────────────────────────────────────────────────
+test('A2: 按事件覆盖优先于全局默认', () => {
+  const cfg = { audioSource: 'tts', audioSourceByKind: { fail: 'system' } };
+  assert.equal(resolveSource('fail', cfg), 'system', 'fail 应被覆盖');
+  assert.equal(resolveSource('done', cfg), 'tts', '未覆盖的事件跟全局');
+  assert.equal(resolveSource('question', cfg), 'tts');
+});
+
+// ── A3: 配置最小化 ──────────────────────────────────────────────────────────
+test('A3: 与全局默认相同的覆盖项被丢弃', () => {
+  const got = normalizeByKind({ done: 'tts', fail: 'system' }, 'tts');
+  assert.deepEqual(got, { fail: 'system' },
+    'done 与默认相同应被丢掉，只留真正偏离的 fail');
+});
+
+// ── A4: 非法值收敛 ──────────────────────────────────────────────────────────
+test('A4: 非法音源/事件一律丢弃，不产生脏配置', () => {
+  assert.equal(normalizeSource('nonsense'), 'tts');
+  assert.equal(normalizeSource(123), 'tts');
+  assert.equal(normalizeSource(null), 'tts');
+
+  const got = normalizeByKind({
+    done: 'nonsense',        // 非法音源
+    fail: 'system',          // 合法
+    notAKind: 'system',      // 非法事件名
+    question: 123,           // 非法类型
+  }, 'tts');
+  assert.deepEqual(got, { fail: 'system' }, '只保留唯一合法项');
+
+  // 非对象输入不应崩
+  assert.doesNotThrow(() => normalizeByKind(null));
+  assert.doesNotThrow(() => normalizeByKind([]));
+  assert.deepEqual(normalizeByKind([]), {});
+});
+
+// ── A5: 回退链保证"有声音" ─────────────────────────────────────────────────
+test('A5: 想要的拿不到时按回退链降级，绝不无声（除非显式 none）', () => {
+  // 选了语音包但没下载 → 退到系统音
+  let r = effectiveSource('bundled', { hasBundledVoice: false });
+  assert.equal(r.source, 'system');
+  assert.equal(r.fellBack, true);
+  assert.equal(r.from, 'bundled');
+
+  // 有语音包就直接用
+  r = effectiveSource('bundled', { hasBundledVoice: true });
+  assert.equal(r.source, 'bundled');
+  assert.equal(r.fellBack, false);
+
+  // 选了自定义但没配文件 → 退到系统音
+  r = effectiveSource('custom', { hasCustomFile: false });
+  assert.equal(r.source, 'system');
+  assert.equal(r.fellBack, true);
+
+  // TTS 不可用 → 系统音
+  r = effectiveSource('tts', { hasTtsVoice: false });
+  assert.equal(r.source, 'system');
+
+  // 显式 none → 就是 none，不要自作聪明出声
+  r = effectiveSource('none', {});
+  assert.equal(r.source, 'none');
+  assert.equal(r.fellBack, false);
+
+  // 极端：系统音也被禁（不该发生，但要保证不返回空）
+  r = effectiveSource('bundled', { hasBundledVoice: false, hasTtsVoice: false });
+  assert.ok(AUDIO_SOURCES.includes(r.source), '必须返回合法音源');
+});
+
+// ── A6: chime → blocked 映射 ────────────────────────────────────────────────
+test('A6: ps1 的 chime 映射到 blocked 事件', () => {
+  assert.equal(audioKindOf('chime'), 'blocked');
+  assert.equal(audioKindOf('done'), 'done');
+  assert.equal(audioKindOf('fail'), 'fail');
+  assert.equal(audioKindOf('approval'), 'approval');
+  assert.equal(audioKindOf('question'), 'question');
+  assert.equal(audioKindOf('unknown'), '');
+  assert.equal(audioKindOf(''), '');
+});
+
+// ── A7: 系统音效语义 ───────────────────────────────────────────────────────
+test('A7: 系统音效按语义映射（失败用警告音，不用完成音）', () => {
+  assert.equal(resolveSystemSound('fail'), 'Hand');
+  assert.equal(resolveSystemSound('done'), 'Asterisk');
+  assert.equal(resolveSystemSound('question'), 'Question');
+  assert.equal(resolveSystemSound('approval'), 'Question');
+  assert.equal(resolveSystemSound('blocked'), 'Exclamation');
+
+  // fail 绝不能和 done 同一个音（那会让"失败"听起来像"成功"）
+  assert.notEqual(resolveSystemSound('fail'), resolveSystemSound('done'));
+
+  // 用户可覆盖
+  assert.equal(resolveSystemSound('done', { systemSounds: { done: 'Beep' } }), 'Beep');
+  // 非法值回落到默认
+  assert.equal(resolveSystemSound('done', { systemSounds: { done: 'NotASound' } }), 'Asterisk');
+
+  // 所有返回值都必须是合法音效名
+  for (const k of AUDIO_KINDS) {
+    assert.ok(SYSTEM_SOUNDS.includes(resolveSystemSound(k)), `${k} 应返回合法音效名`);
+  }
+});
+
+// ── A8: 自定义文件路径校验 ─────────────────────────────────────────────────
+test('A8: 自定义文件只接受绝对路径 + 合法扩展名（防随机失败）', () => {
+  const ok = { customFiles: { done: 'D:\\sounds\\done.wav' } };
+  assert.equal(resolveCustomFile('done', ok), 'D:\\sounds\\done.wav');
+
+  // 相对路径必须拒绝：播放进程 cwd 不确定，会随机失败
+  assert.equal(resolveCustomFile('done', { customFiles: { done: 'sounds\\done.wav' } }), '');
+  assert.equal(resolveCustomFile('done', { customFiles: { done: './done.wav' } }), '');
+
+  // UNC 路径可接受
+  assert.equal(
+    resolveCustomFile('done', { customFiles: { done: '\\\\server\\share\\a.wav' } }),
+    '\\\\server\\share\\a.wav',
+  );
+
+  // 非法扩展名拒绝
+  assert.equal(resolveCustomFile('done', { customFiles: { done: 'D:\\a.exe' } }), '');
+  assert.equal(resolveCustomFile('done', { customFiles: { done: 'D:\\a.txt' } }), '');
+
+  // 支持的扩展名
+  for (const ext of ['wav', 'mp3', 'm4a', 'flac', 'ogg']) {
+    assert.ok(resolveCustomFile('done', { customFiles: { done: `D:\\a.${ext}` } }), `应接受 ${ext}`);
+  }
+
+  // 大小写不敏感
+  assert.ok(resolveCustomFile('done', { customFiles: { done: 'D:\\A.WAV' } }));
+
+  // 缺失/空值不崩
+  assert.equal(resolveCustomFile('done', {}), '');
+  assert.equal(resolveCustomFile('done', null), '');
+});
+
+// ── A9: 用户举的真实场景 ───────────────────────────────────────────────────
+test('A9: 用户场景 —— 完成听日语语音包、失败听系统警告音', () => {
+  const cfg = {
+    audioSource: 'bundled',                    // 默认用语音包
+    audioSourceByKind: { fail: 'system' },     // 但失败改成系统音
+    systemSounds: { fail: 'Hand' },
+    voiceName: 'zundamon-normal',
+  };
+  assert.equal(resolveSource('done', cfg), 'bundled', '完成用语音包');
+  assert.equal(resolveSource('fail', cfg), 'system', '失败用系统音');
+  assert.equal(resolveSystemSound('fail', cfg), 'Hand');
+
+  // 失败时不该去拿语音包文件
+  const eff = effectiveSource(resolveSource('fail', cfg), { hasBundledVoice: true });
+  assert.equal(eff.source, 'system', '即使语音包可用，fail 也走 system');
+});