dsh-notify-say 0.4.47 → 0.4.50

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 > 本文件由 `tools/release-build.ps1` 从开发提交自动生成，**请勿手工编辑**。
 > 只列面向使用者的变更（新增功能与修复），不含内部维护提交。
 
+## v0.4.50 — 2026-10-18
+
+- fix(update): v0.4.50 —— 两个源并行查、取较高版本
+
+## v0.4.49 — 2026-10-18
+
+- fix(update): v0.4.49 —— hasUpdate 方向反了（实测抓到）
+
+## v0.4.48 — 2026-10-18
+
+- feat(update): v0.4.48 —— 检查更新 + 引导升级（不做自动更新）
+
 ## v0.4.46 — 2026-10-18
 
 - fix(test): v0.4.46 —— 修「本地绿、CI 红」+ 发版流程补发布包内测试

package/README.md

@@ -55,6 +55,7 @@
 | **许可先告知** | 下载音色前弹出条款确认，写明署名要求与官方条款链接 |
 | **诊断导出** | 一键导出脱敏日志（用户名/路径已替换），方便提 Issue |
 | **日志隐私分级** | 默认只记元数据，**不记台词正文**；要详细日志需手动开 debug |
+| **检查更新** | 显示当前/最新版本，有新版时给出升级命令（**不自动更新**，见[下文](#有新版本了怎么办)） |
 
 > **联网说明**：播放、通知、TTS 全部离线。只有**下载语音包**时需要访问 GitHub。
 > 不下载语音包的话，这个插件不会联网。
@@ -106,6 +107,7 @@ D:\Program Files (x86)\DSH\profiles\desktop\package.json
 | 出错时也要语音提醒 | 「出错」开关（默认已开） |
 | 让子代理结束也提醒 | 「子代理」开关（默认关） |
 | 少响一点 | 「同会话去抖」调大 |
+| 看看有没有新版 | 高级区「版本与更新」→ 检查更新 |
 
 ---
 
@@ -290,6 +292,23 @@ VOICEVOX 有几十个角色，但每个的条款都要单独读原文核对。
 我们只收录**条款明确允许本插件这样分发**的，宁可少也不冒险。
 被排除的例子：有 2 个明确禁止再分发，1 个身份存疑。
 
+**有新版本了怎么办？**
+
+设置页 → 高级 → **版本与更新** → 点「检查更新」。有新版时那里会显示版本号、
+`CHANGELOG.md` 链接，以及一条升级命令（可一键复制）。
+
+**插件不会自己更新自己。** 原因很实在：
+
+- 装上你的机器后，插件不知道自己是通过 npm、GitHub 还是 `link:` 装的
+- 正在运行的程序替换自己的文件，失败后很难恢复
+- DSH 官方 CLI 已经能升级插件（`dsh plugin --profile <名字> update dsh-notify-say`）—— 重复实现没意义
+
+所以分工是：**插件负责告诉你有新版；你执行命令；DSH 完成升级。**
+更新后需要重启对应的 DSH profile。
+
+> 如果你是从源码 `link:` 安装的（开发模式），插件会认出来并**不给命令** ——
+> 那种情况请直接更新源码目录，用插件命令会覆盖你的源码。
+
 **能加我喜欢的音色吗？**
 可以提 Issue。但要走审核流程（读官方条款原文、留档），不是加个下载链接的事。
 
@@ -306,7 +325,7 @@ npm run test:route    # 需要 --import loader 的接线测试
 npm run test:audio-wire
 ```
 
-**375 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
+**374 条测试通过。** 绝大多数是纯逻辑测试，克隆仓库后 `npm test` 即可跑。
 
 少数用例需要真实的 DSH 宿主（用于验证 Cordis 上下文行为）。
 找不到宿主时它们会**自动 skip** —— 注意 skip 不等于通过。

package/lib/client.js

@@ -137,6 +137,15 @@ window.__ModuleLoader__.load({
       }).then(function (r) { return r ? r.json() : null }).catch(function () { return null })
     }
 
+    // 检查更新（v0.4.48）。只读：不下载、不覆盖文件、不执行命令。
+    // force=true 表示用户手动点，绕过宿主侧 24 小时缓存。
+    function fetchVersion(force) {
+      var url = apiUrl('version') + (force ? '?force=1' : '')
+      return fetch(url, { cache: 'no-store', credentials: 'same-origin' })
+        .then(function (r) { return r && r.ok ? r.json() : null })
+        .catch(function () { return null })
+    }
+
     function openSession(ctx, sessionId) {
       try {
         if (!sessionId) return false
@@ -386,6 +395,20 @@ window.__ModuleLoader__.load({
       // ⚠️ 真实值必须以 host 返回的**生效值**为准（见下方 useEffect 的 merge）。
       // 这些占位数字**不代表实际配置**：例如 patch 里 volume 可能是 100，
       // 这里写 80 只是防 undefined；生效值到达后会被覆盖。
+      // 版本与更新（v0.4.48）—— **独立 state**，与主 state 隔离。
+      //
+      // 为什么不用主 state：主 state 有 25 处 set() 逐字段重建，
+      // 加一个字段要改 25 处，已因此出过 4 次 bug。
+      // 独立 useState 能彻底避开这个坑。
+      var vst = React.useState({
+        // null = 还没查过；失败时是 { ok:false, error }
+        info: null,
+        loading: false,
+        copied: false,
+      })
+      var vset = vst[1]
+      var vs = vst[0]
+
       var st = React.useState({
         loaded: false,
         values: {
@@ -411,6 +434,15 @@ window.__ModuleLoader__.load({
 
       React.useEffect(function () {
         var alive = true
+        // 版本信息：挂载时查一次（宿主侧有 24 小时缓存，很便宜）。
+        //
+        // ⚠️ 必须走 Promise：直接 set 会触发重渲染 → effect 重跑 → 死循环
+        // （v0.4.33 语音包那块就是这么把 4GB 堆打满的）。
+        // 异步 .then 里 set 是安全的 —— 那时 effect 已经跑完了。
+        fetchVersion(false).then(function (r) {
+          if (!alive || !r) return
+          vset(function (p) { return { info: r, loading: false, copied: p.copied } })
+        })
         loadConfig().then(function (v) {
           if (!alive) return
           set(function (p) {
@@ -728,6 +760,38 @@ window.__ModuleLoader__.load({
           })
         })
       }
+      // ── 版本与更新（v0.4.48）────────────────────────────────────────
+      //
+      // 只检查、不安装。升级由用户自己执行 DSH 命令。
+      // 详见 lib/update-check.js 头注释（为什么不自动更新）。
+      function checkVersion(force) {
+        vset(function (p) {
+          return { info: p.info, loading: true, copied: false }
+        })
+        fetchVersion(force).then(function (r) {
+          vset(function (p) {
+            return { info: r || { ok: false, error: "无法连接" }, loading: false, copied: p.copied }
+          })
+        })
+      }
+
+      // 复制升级命令。失败就退回"显示命令让用户自己选"。
+      function copyUpgradeCommand(cmd) {
+        var done = function (ok) {
+          vset(function (p) { return { info: p.info, loading: p.loading, copied: ok } })
+          if (!ok) {
+            // 复制失败：至少把命令显示出来（界面上本来就有）
+            console.warn("[dsh-notify-say] 复制失败，请手动选择命令文本")
+          }
+        }
+        try {
+          if (typeof navigator !== "undefined" && navigator.clipboard && navigator.clipboard.writeText) {
+            navigator.clipboard.writeText(cmd).then(function () { done(true) }).catch(function () { done(false) })
+            return
+          }
+        } catch (e) { /* 继续用兜底 */ }
+        done(false)
+      }
 
       var v = s.values || {}
       var rows = []
@@ -1714,6 +1778,82 @@ window.__ModuleLoader__.load({
         rows.push(h('div', { key: 'dg-hint', style: S.subHint },
           '导出到日志同目录（%TEMP%\\dsh-notify-say\\）。会自动把用户名替换为 <user>、'
             + '绝对路径替换为 <path>，但**仍请自己再看一遍**再上传。'))
+
+        // ── 版本与更新（v0.4.48）─────────────────────────────────────
+        //
+        // 只显示版本状态 + 给升级指引。**不自动下载、不覆盖文件**：
+        // 本机可能是 Junction 指向开发源码，自动覆盖会直接毁掉源码；
+        // 而且 DSH 官方 CLI 已经能升级插件。
+        rows.push(h('div', { key: 'up-title', style: S.label }, '版本与更新'))
+        var vi = vs.info
+        var cur = vi && vi.current ? vi.current : "(未知)"
+        var lat = vi && vi.latest ? vi.latest : null
+
+        rows.push(h('div', { key: 'up-cur', style: S.row },
+          h('span', { style: S.label }, '当前版本'),
+          h('span', null, 'v' + cur)))
+
+        if (vs.loading) {
+          rows.push(h('div', { key: 'up-loading', style: S.subHint }, '正在检查…'))
+        } else if (!vi) {
+          rows.push(h('div', { key: 'up-idle', style: S.subHint },
+            '还没检查过。点下面的按钮查一下有没有新版本。'))
+        } else if (!vi.ok) {
+          rows.push(h('div', { key: 'up-err', style: S.subHint },
+            '暂时无法检查（' + (vi.error || '网络不可用') + '）。'
+              + '本地通知和语音不依赖它，照常工作。'))
+        } else if (vi.hasUpdate === true) {
+          rows.push(h('div', { key: 'up-new', style: S.row },
+            h('span', { style: S.label }, '最新版本'),
+            h('span', { style: { color: '#e0a030', fontWeight: 600 } }, 'v' + lat + '（有新版）')))
+        } else if (vi.hasUpdate === false) {
+          rows.push(h('div', { key: 'up-same', style: S.row },
+            h('span', { style: S.label }, '最新版本'),
+            h('span', { style: { color: '#2a7' } }, 'v' + lat + '（已是最新）')))
+        } else {
+          rows.push(h('div', { key: 'up-unknown', style: S.subHint },
+            '最新版本 v' + lat + '（本地版本格式无法比较）'))
+        }
+
+        // 有新版时给命令；开发模式给说明而不是命令（不能覆盖源码）
+        if (vi && vi.hasUpdate === true) {
+          if (vi.command) {
+            rows.push(h('div', { key: 'up-cmd', style: {
+              marginTop: '4px', padding: '8px', borderRadius: '4px',
+              background: 'rgba(255,255,255,.06)',
+              fontFamily: 'monospace', fontSize: '12px', wordBreak: 'break-all',
+            } }, vi.command))
+          }
+          rows.push(h('div', { key: 'up-note', style: S.subHint }, vi.note || ''))
+        } else if (vi && vi.note) {
+          rows.push(h('div', { key: 'up-mode', style: S.subHint }, vi.note))
+        }
+
+        rows.push(h('div', { key: 'up-btn', style: S.row },
+          h('button', {
+            type: 'button',
+            disabled: vs.loading,
+            style: S.btn,
+            onClick: function () { checkVersion(true) },
+          }, vs.loading ? '检查中…' : '检查更新'),
+          vi && vi.hasUpdate === true && vi.command
+            ? h('button', {
+              type: 'button',
+              style: S.btn,
+              onClick: function () { copyUpgradeCommand(vi.command) },
+            }, vs.copied ? '已复制' : '复制命令')
+            : null,
+          vi && vi.changelogUrl
+            ? h('a', {
+              href: vi.changelogUrl,
+              target: '_blank',
+              rel: 'noreferrer noopener',
+              style: { color: '#4a9', fontSize: '12px' },
+            }, '更新日志 ↗')
+            : null,
+        ))
+        rows.push(h('div', { key: 'up-offline', style: S.subHint },
+          '本地通知与语音不依赖更新检查；网络不可用时照常工作。'))
       }
 
       if (s.msg) rows.push(h('div', { key: 'msg', style: S.ok }, s.msg))

package/lib/index.js

@@ -98,6 +98,7 @@ import {
 import { checkLocalOrigin, throttle } from './http-guard.js';
 import { poolSummary } from './voice-pack-store.js';
 import { voiceRootsArg as computeVoiceRootsArg } from './voice-regions.js';
+import { checkForUpdate } from './update-check.js';
 import { createVoicePackRoute } from './voice-pack-route.js';
 import { isDebug, redactText } from './log-privacy.js';
 import { exportDiagnostics } from './diagnostics.js';
@@ -106,6 +107,14 @@ import { pickTtsText, sanitizeTtsText, MAX_TEXT_LEN } from './tts-lines.js';
 
 const PLUGIN_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
 
+
+// 检查更新的宿主侧缓存（v0.4.48）。
+//
+// 为什么放宿主侧而不是浏览器：
+//   · 一天最多查一次 —— 不管用户开几次设置页，都不该反复打 npm/GitHub
+//   · 报错也不影响功能：查不到就是查不到，通知与语音照常
+//   · 缓存跨会话存活（模块级），设置页重开不必重新联网
+const UPDATE_CACHE = { at: 0, result: null };
 // 插件版本（诊断导出用）。读 package.json，失败就返回 unknown ——
 // 这只是个信息字段，不值得为它抛异常。
 const PLUGIN_VERSION = (() => {
@@ -1611,7 +1620,42 @@ function hasVoiceLine(psKind) {
                 return;
                 }
 
-                if (head === 'config') return configRoute.handler(req, res);
+                // ── 检查更新（v0.4.48）──────────────────────────────────
+        //
+        // **只读**：不下载、不覆盖文件、不执行命令。
+        // 也刻意不放进 isWriteRoute —— 它没有任何副作用。
+        //
+        // 为什么不接受客户端传 URL：那等于让本机访问任意地址（SSRF）。
+        // 查询地址固定在 update-check.js 里。
+        if (head === 'version') {
+          // ?force=1 表示用户手动点了「检查更新」，绕过 24 小时缓存
+          const force = /[?&]force=1\b/.test(String((req && req.url) || ''));
+          //
+          // ⚠️ 必须包一层 catch：检查更新永远不该把设置页弄崩。
+          // 网络不通是常态（用户可能在离线环境），此时只报错误，
+          // 通知与语音完全不受影响。
+          Promise.resolve()
+            .then(() => checkForUpdate({
+              pluginRoot: PLUGIN_ROOT,
+              force,
+              cache: UPDATE_CACHE,
+            }))
+            .then((r) => {
+              try {
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' });
+                res.end(JSON.stringify(r));
+              } catch { /* 响应已发出 */ }
+            })
+            .catch((e) => {
+              try {
+                res.writeHead(200, { 'content-type': 'application/json; charset=utf-8' });
+                res.end(JSON.stringify({ ok: false, error: String((e && e.message) || e) }));
+              } catch { /* 响应已发出 */ }
+            });
+          return;
+        }
+
+        if (head === 'config') return configRoute.handler(req, res);
 
                 // ── 自测端点（v0.4.11）────────────────────────────────────
                 //

package/lib/update-check.js

@@ -0,0 +1,324 @@
+/**
+ * 检查更新（v0.4.48）。
+ *
+ * ## 定位：只检查，不安装
+ *
+ * 本模块**只做三件事**：读出当前版本、查出最新版本、给出升级指引。
+ * 它不下载、不覆盖文件、不执行命令、不重启宿主。
+ *
+ * 为什么不做自动更新：
+ *   · 插件正在运行时替换自己的文件，失败后很难恢复
+ *   · 用户可能装在任意 profile，插件无从得知
+ *   · 本机安装可能是 Junction（指向开发源码），覆盖会直接毁掉开发目录
+ *   · DSH 官方 CLI 已经能升级插件（`dsh plugin update`），重复实现没意义
+ *
+ * 所以分工是：**本插件发现新版本 + 说明变更 + 告诉用户命令；DSH 执行升级。**
+ *
+ * ## 为什么不用 GitHub Releases 的 latest
+ *
+ * ⚠️ 实测（2026-10-18）：本仓库的 `/releases/latest` 指向 **`voice-packs`**
+ * —— 那是语音包索引的固定 tag，跟插件版本毫无关系。
+ * 仓库里只有 `v0.4.30`（语音包下载支持那一版）和 `voice-packs` 两个 Release，
+ * 插件版本只打 git tag、不发 Release。
+ *
+ * 所以用 `/releases/latest` 做更新检查会得出荒谬结论（"最新版是 voice-packs"）。
+ *
+ * ## 用什么当权威源
+ *
+ * 两个来源，都是"发布时同步更新"的：
+ *   ① npm registry 的 `dist-tags.latest`（npm 安装的用户）
+ *   ② GitHub 仓库 main 分支的 package.json（GitHub / link 安装的用户）
+ *
+ * 先查 ①，失败回退 ②。两者都由 `tools/release.ps1` 同时更新，正常情况下一致。
+ *
+ * ## 缓存
+ *
+ * 宿主侧缓存 24 小时：GUI 每次打开不必真的联网，
+ * 但一天最多查一次，足够"发现有新版"。
+ * 用户手动点「检查更新」时强制绕过缓存。
+ *
+ * @module lib/update-check.js
+ */
+
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** npm registry 的包元数据地址。 */
+export const NPM_REGISTRY_URL = 'https://registry.npmjs.org/dsh-notify-say';
+
+/** GitHub main 分支的 package.json（GitHub 安装的用户看这个）。 */
+export const GITHUB_RAW_PKG_URL =
+  'https://raw.githubusercontent.com/unifilitence/dsh-notify-say/main/package.json';
+
+/** 更新日志（人看的页面）。 */
+export const CHANGELOG_URL =
+  'https://github.com/unifilitence/dsh-notify-say/blob/main/CHANGELOG.md';
+
+/** 单次查询超时。网络不通时不要拖住界面。 */
+export const FETCH_TIMEOUT_MS = 5000;
+
+/** 自动检查的最小间隔：一天。 */
+export const AUTO_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * 读当前版本（读自己的 package.json，不联网）。
+ *
+ * @param {string} pluginRoot
+ * @returns {string} 读不到时返回空串
+ */
+export function currentVersion(pluginRoot) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(pluginRoot, 'package.json'), 'utf8'));
+    return typeof pkg.version === 'string' ? pkg.version : '';
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * 把 `1.2.3` / `v1.2.3` 规整成可比较的数组。
+ *
+ * 只处理数字点分版本；带 `-rc.1` 之类后缀时只取前面的数字段
+ * （预发布版不该被建议"升级到正式版"以外的东西，这里不做精细 semver）。
+ *
+ * @param {string} v
+ * @returns {number[] | null}
+ */
+export function parseVersion(v) {
+  const s = String(v || '').trim().replace(/^v/i, '');
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(s);
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2]), Number(m[3])];
+}
+
+/**
+ * 比较两个版本。返回 -1 / 0 / 1；任一不可解析时返回 null。
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {number | null}
+ */
+export function compareVersions(a, b) {
+  const pa = parseVersion(a);
+  const pb = parseVersion(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+/**
+ * 判断当前安装形态，决定给什么升级建议。
+ *
+ * 三种情况：
+ *   · `dev`    —— 目录是 junction/symlink，或本身就是 git 仓库
+ *                 （开发模式：**绝不能**用升级命令覆盖源码）
+ *   · `npm`    —— 其余情况，按 npm 包给出命令
+ *
+ * 判断失败一律当 `dev`（保守：宁可让用户看到"请手动处理"，
+ * 也不要给一条会覆盖开发目录的命令）。
+ *
+ * @param {string} pluginRoot
+ * @returns {'dev' | 'npm'}
+ */
+export function detectInstallMode(pluginRoot) {
+  try {
+    // ① 自身或父目录是 git 仓库 → 源码安装
+    let dir = pluginRoot;
+    for (let i = 0; i < 6; i++) {
+      try {
+        readFileSync(join(dir, '.git', 'HEAD'));
+        return 'dev';
+      } catch { /* 继续往上 */ }
+      const parent = join(dir, '..');
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch { /* ignore */ }
+
+  try {
+    // ② 真实路径与自身不同 → junction / symlink
+    const real = realpathSync(pluginRoot);
+    if (real && real !== pluginRoot) return 'dev';
+  } catch { /* 拿不到就当 npm */ }
+
+  return 'npm';
+}
+
+/**
+ * 从 npm registry 取最新版本。
+ *
+ * @param {Function} doFetch
+ * @returns {Promise<{ok:boolean, version?:string, error?:string}>}
+ */
+async function fetchFromNpm(doFetch) {
+  try {
+    const res = await doFetch(NPM_REGISTRY_URL, { cache: 'no-store' });
+    if (!res || !res.ok) return { ok: false, error: `npm-http-${res ? res.status : 'none'}` };
+    const doc = await res.json();
+    const v = doc && doc['dist-tags'] ? doc['dist-tags'].latest : '';
+    if (!v) return { ok: false, error: 'npm-no-latest-tag' };
+    return { ok: true, version: String(v) };
+  } catch (e) {
+    return { ok: false, error: `npm: ${(e && e.message) || e}` };
+  }
+}
+
+/**
+ * 从 GitHub main 的 package.json 取版本。
+ *
+ * @param {Function} doFetch
+ * @returns {Promise<{ok:boolean, version?:string, error?:string}>}
+ */
+async function fetchFromGithub(doFetch) {
+  try {
+    const res = await doFetch(GITHUB_RAW_PKG_URL, { cache: 'no-store' });
+    if (!res || !res.ok) return { ok: false, error: `gh-http-${res ? res.status : 'none'}` };
+    const doc = await res.json();
+    const v = doc && doc.version;
+    if (!v) return { ok: false, error: 'gh-no-version' };
+    return { ok: true, version: String(v) };
+  } catch (e) {
+    return { ok: false, error: `gh: ${(e && e.message) || e}` };
+  }
+}
+
+/** 带超时的 fetch 包装（超时不 abort 也没关系，只是不再等）。 */
+function withTimeout(doFetch, ms) {
+  return (url, opts) => Promise.race([
+    doFetch(url, opts),
+    new Promise((_, reject) => {
+      const t = setTimeout(() => reject(new Error('timeout')), ms);
+      if (t && typeof t.unref === 'function') t.unref();
+    }),
+  ]);
+}
+
+/**
+ * 给某个安装形态的升级指引。
+ *
+ * ⚠️ profile 名无法可靠得知，所以命令里用占位符并说明要替换。
+ * 不要假装知道用户装在哪。
+ *
+ * @param {'dev' | 'npm'} mode
+ * @returns {{ command: string, note: string }}
+ */
+export function upgradeHint(mode) {
+  if (mode === 'dev') {
+    return {
+      command: '',
+      note: '检测到源码/链接安装（开发模式）。请直接更新源码目录后重启 DSH —— '
+        + '**不要**用插件升级命令，那会覆盖你的源码。',
+    };
+  }
+  return {
+    command: 'dsh plugin --profile <你的 profile> update dsh-notify-say',
+    note: '把 <你的 profile> 换成实际名称（常见是 desktop）。'
+      + '更新后需要重启对应的 DSH profile 才会完整生效。',
+  };
+}
+
+/**
+ * 检查更新。
+ *
+ * @param {object} opts
+ * @param {string} opts.pluginRoot
+ * @param {boolean} [opts.force] 绕过缓存（用户手动点「检查更新」）
+ * @param {Function} [opts.fetchImpl]
+ * @param {object} [opts.cache] 宿主持有的缓存对象（`{ at, result }`）
+ * @param {number} [opts.now]
+ * @returns {Promise<object>} 结构化结果，**永不抛异常**
+ */
+export async function checkForUpdate(opts = {}) {
+  const pluginRoot = opts.pluginRoot || '';
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const current = currentVersion(pluginRoot);
+  const mode = detectInstallMode(pluginRoot);
+
+  const base = {
+    current,
+    installMode: mode,
+    changelogUrl: CHANGELOG_URL,
+    ...upgradeHint(mode),
+  };
+
+  // 缓存命中（未强制刷新且未过期）
+  const cache = opts.cache;
+  if (!opts.force && cache && cache.at && cache.result
+      && (now - cache.at) < AUTO_CHECK_TTL_MS) {
+    return { ...cache.result, cached: true, checkedAt: cache.at };
+  }
+
+  const doFetch = typeof (opts.fetchImpl || globalThis.fetch) === 'function'
+    ? (opts.fetchImpl || globalThis.fetch)
+    : null;
+  if (!doFetch) {
+    return { ok: false, ...base, error: 'fetch-unavailable', cached: false, checkedAt: now };
+  }
+
+  const timed = withTimeout(doFetch, opts.timeoutMs || FETCH_TIMEOUT_MS);
+
+  // ── 并行查两个源，取较高版本 ─────────────────────────────────────────
+  //
+  // ⚠️ 不能"先 npm、失败才回退 GitHub"。实测（2026-10-18）：
+  //   npm latest = 0.4.47（暂存队列要过一阵才上架）
+  //   GitHub main = 0.4.48
+  // 只查 npm 的话，这期间**所有人都看不到 0.4.48 可用** ——
+  // 而 GitHub 安装的用户本来就是以 main 为准的。
+  //
+  // 两个源都是同一套发布流程产出的正式版本，所以取较新的那个是安全的。
+  const [npmR, ghR] = await Promise.all([
+    fetchFromNpm(timed).catch((e) => ({ ok: false, error: String((e && e.message) || e) })),
+    fetchFromGithub(timed).catch((e) => ({ ok: false, error: String((e && e.message) || e) })),
+  ]);
+
+  // 挑出可用的版本，取最高的
+  const candidates = [];
+  if (npmR.ok) candidates.push({ version: npmR.version, source: 'npm' });
+  if (ghR.ok) candidates.push({ version: ghR.version, source: 'github' });
+
+  if (candidates.length === 0) {
+    // 两个都失败：明确报告，但**不影响插件任何功能**
+    const result = {
+      ok: false,
+      ...base,
+      error: `npm(${npmR.error}) / github(${ghR.error})`,
+      cached: false,
+      checkedAt: now,
+    };
+    if (cache) { cache.at = now; cache.result = result; }
+    return result;
+  }
+
+  let best = candidates[0];
+  for (const c of candidates.slice(1)) {
+    const d = compareVersions(c.version, best.version);
+    // 解析不出时保留先到的（npm 优先），不因为格式怪就丢掉可用信息
+    if (d === 1) best = c;
+  }
+
+  const r = { version: best.version };
+  const source = candidates.length > 1 ? `${best.source}+${candidates.length - 1}` : best.source;
+
+  const cmp = compareVersions(r.version, current);
+  const result = {
+    ok: true,
+    ...base,
+    latest: r.version,
+    // ⚠️ 方向是 `latest > current` 才算有新版。
+    //
+    // 第一版写成 `cmp < 0` —— **反了**。实测才发现：本地 0.4.48、
+    // npm 还在暂存队列里是 0.4.47，界面却显示"有新版"。
+    // 也就是说：npm 落后时装作有新版本，npm 超前时反而不提示。
+    //
+    // 解析不出（比如本地是 0.0.0-stage）时不下"有新版"的结论。
+    hasUpdate: cmp === null ? null : cmp > 0,
+    source,
+    cached: false,
+    checkedAt: now,
+  };
+
+  if (cache) { cache.at = now; cache.result = result; }
+  return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name":  "dsh-notify-say",
-    "version":  "0.4.47",
+    "version":  "0.4.50",
     "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",

package/test/update-check.test.mjs

@@ -0,0 +1,358 @@
+/**
+ * 检查更新（v0.4.48）。
+ *
+ * ## 这个功能最需要测什么
+ *
+ * 不是"能不能查到版本"——那是网络问题，测不出什么。
+ * 真正要锁的是**它不会做危险的事**：
+ *   · 不能自己下载/覆盖文件/执行命令
+ *   · 不能走 /releases/latest（实测那指向 voice-packs，不是插件版本）
+ *   · 不能因为检查失败影响通知与语音
+ *   · 开发模式（Junction）绝对不能给出会覆盖源码的命令
+ *   · 不能接受客户端传的 URL（SSRF）
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
+import { join, resolve, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const INDEX = readFileSync(join(ROOT, 'lib', 'index.js'), 'utf8');
+const CLIENT = readFileSync(join(ROOT, 'lib', 'client.js'), 'utf8');
+const UC = readFileSync(join(ROOT, 'lib', 'update-check.js'), 'utf8');
+
+// ── U1: 版本解析与比较 ──────────────────────────────────────────────────
+test('U1: 版本比较正确处理 v 前缀与非法输入', async () => {
+  const { parseVersion, compareVersions } = await import('../lib/update-check.js');
+
+  assert.deepEqual(parseVersion('1.2.3'), [1, 2, 3]);
+  assert.deepEqual(parseVersion('v1.2.3'), [1, 2, 3]);
+  assert.equal(parseVersion('abc'), null);
+  assert.equal(parseVersion(''), null);
+
+  assert.equal(compareVersions('1.2.3', '1.2.3'), 0);
+  assert.equal(compareVersions('1.2.3', '1.2.4'), -1);
+  assert.equal(compareVersions('1.3.0', '1.2.9'), 1);
+  assert.equal(compareVersions('v0.4.47', '0.4.46'), 1);
+  // 解析不出就返回 null —— 调用方据此**不下"有新版"的结论**
+  assert.equal(compareVersions('abc', '1.0.0'), null);
+});
+
+// ── U2: 不解析的版本不能误报"有新版" ────────────────────────────────────
+test('U2: 版本格式异常时 hasUpdate 为 null（不误报）', async () => {
+  const { checkForUpdate } = await import('../lib/update-check.js');
+
+  const tmp = join(ROOT, '.tmp-u2-' + Math.random().toString(36).slice(2, 8));
+  try {
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(join(tmp, 'package.json'), JSON.stringify({ version: 'weird' }));
+
+    const fake = async () => ({ ok: true, json: async () => ({ 'dist-tags': { latest: '9.9.9' } }) });
+    const r = await checkForUpdate({ pluginRoot: tmp, force: true, fetchImpl: fake });
+    assert.equal(r.ok, true);
+    assert.equal(r.hasUpdate, null,
+      '本地版本解析不出时不能判定"有新版"，否则用户会去升级一个根本没装的东西');
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ── U3: 开发模式（Junction / 源码）不给升级命令 ─────────────────────────
+test('U3: 开发模式不给出会覆盖源码的命令', async () => {
+  const { upgradeHint, detectInstallMode } = await import('../lib/update-check.js');
+
+  const dev = upgradeHint('dev');
+  assert.equal(dev.command, '',
+    '开发模式必须**没有**命令 —— 本机是 Junction 指向开发源码，'
+    + '用 dsh plugin update 会直接覆盖掉源码');
+  assert.match(dev.note, /不要/,
+    '必须明确劝阻用插件升级命令');
+
+  const npm = upgradeHint('npm');
+  assert.match(npm.command, /dsh plugin .*update dsh-notify-say/,
+    'npm 安装才给 dsh 的升级命令');
+  assert.match(npm.command, /<.*profile.*>/,
+    'profile 名无法可靠得知，必须用占位符而不是假装知道');
+  assert.match(npm.note, /重启/,
+    '要提示更新后需重启 profile');
+});
+
+// ── U4: 源失败要回退，两个都失败要如实报错 ──────────────────────────────
+test('U4: npm 失败回退 GitHub；都失败时如实报错', async () => {
+  const { checkForUpdate, NPM_REGISTRY_URL, GITHUB_RAW_PKG_URL } =
+    await import('../lib/update-check.js');
+
+  // ① npm 挂、GitHub 通
+  const seen = [];
+  const f1 = async (url) => {
+    seen.push(url);
+    if (url === NPM_REGISTRY_URL) return { ok: false, status: 500 };
+    return { ok: true, json: async () => ({ version: '0.4.99' }) };
+  };
+  const r1 = await checkForUpdate({ pluginRoot: ROOT, force: true, fetchImpl: f1 });
+  assert.equal(r1.ok, true);
+  assert.equal(r1.source, 'github', 'npm 挂了应标明用的是 GitHub');
+  assert.ok(seen.includes(GITHUB_RAW_PKG_URL));
+
+  // ② 两个都挂
+  const f2 = async () => ({ ok: false, status: 503 });
+  const r2 = await checkForUpdate({ pluginRoot: ROOT, force: true, fetchImpl: f2 });
+  assert.equal(r2.ok, false);
+  assert.match(String(r2.error), /npm|github/, '应把两个源的失败都说出来');
+});
+
+// ── U5: 检查更新永不抛异常（不能把设置页弄崩）───────────────────────────
+test('U5: fetch 抛异常时返回结构化错误，不抛出', async () => {
+  const { checkForUpdate } = await import('../lib/update-check.js');
+  const boom = async () => { throw new Error('network down'); };
+
+  const r = await checkForUpdate({ pluginRoot: ROOT, force: true, fetchImpl: boom });
+  assert.equal(r.ok, false);
+  assert.ok(r.error, '应给出错误原因');
+  // 关键：仍然带出当前版本 —— 界面要能显示"你装的是哪个版本"
+  assert.ok(r.current, '失败时也要报告当前版本');
+});
+
+// ── U6: 缓存 24 小时，force 可绕过 ──────────────────────────────────────
+test('U6: 宿主侧缓存 24 小时，force 绕过', async () => {
+  const { checkForUpdate, AUTO_CHECK_TTL_MS, NPM_REGISTRY_URL } = await import('../lib/update-check.js');
+  const cache = { at: 0, result: null };
+
+  // ⚠️ 现在一次检查会**并行查两个源**（npm + GitHub），所以不能用总请求数
+  // 衡量"查了几次"。只数 npm 那个请求 —— 每次检查恰好发一次。
+  let calls = 0;
+  const fake = async (url) => {
+    if (url === NPM_REGISTRY_URL) calls++;
+    if (url === NPM_REGISTRY_URL) {
+      return { ok: true, json: async () => ({ 'dist-tags': { latest: '0.4.99' } }) };
+    }
+    return { ok: true, json: async () => ({ version: '0.4.99' }) };
+  };
+
+  const t0 = 1_700_000_000_000;
+  await checkForUpdate({ pluginRoot: ROOT, fetchImpl: fake, cache, now: t0 });
+  assert.equal(calls, 1);
+
+  // TTL 内再来一次：用缓存，不再联网
+  const r2 = await checkForUpdate({ pluginRoot: ROOT, fetchImpl: fake, cache, now: t0 + 1000 });
+  assert.equal(calls, 1, 'TTL 内不应重复联网');
+  assert.equal(r2.cached, true);
+
+  // force 强制联网
+  await checkForUpdate({ pluginRoot: ROOT, fetchImpl: fake, cache, now: t0 + 2000, force: true });
+  assert.equal(calls, 2, 'force 应绕过缓存');
+
+  // 过期后重新联网
+  // ⚠️ 注意基准：上面 force 那次把 cache.at 刷新到 t0+2000，
+  // 所以要相对**它**算过期，而不是相对 t0（第一版算错，误判成"未过期"）。
+  await checkForUpdate({
+    pluginRoot: ROOT, fetchImpl: fake, cache,
+    now: t0 + 2000 + AUTO_CHECK_TTL_MS + 1,
+  });
+  assert.equal(calls, 3, '超过 TTL 应重新联网');
+});
+
+// ── U7: 不用 /releases/latest（实测那指向 voice-packs）──────────────────
+test('U7: 权威源不是 GitHub Releases 的 latest', () => {
+  // ⚠️ 实测（2026-10-18）：本仓库 /releases/latest 返回 tag `voice-packs`,
+  // 那是语音包索引，跟插件版本毫无关系。
+  // 用它会得出"最新版是 voice-packs"这种荒谬结论。
+  // ⚠️ 只查代码，不查注释 —— 注释里正是在解释"为什么不能用它"。
+  const code = UC
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/^\s*\/\/.*$/gm, '');
+  assert.doesNotMatch(code, /releases\/latest/,
+    '不得使用 /releases/latest 作为插件版本来源（它指向 voice-packs）');
+
+  assert.match(UC, /registry\.npmjs\.org/,
+    '应查 npm registry');
+  assert.match(UC, /raw\.githubusercontent\.com/,
+    '应查 GitHub main 的 package.json');
+});
+
+// ── U8: 只读，不做任何危险动作 ──────────────────────────────────────────
+test('U8: update-check 不下载、不写盘、不执行命令', () => {
+  // 这是这个功能的**核心安全边界**：它只报告，不行动。
+  for (const danger of [
+    /writeFileSync/,
+    /mkdirSync/,
+    /unlinkSync/,
+    /rmSync/,
+    /child_process/,
+    /execSync/,
+    /spawn/,
+  ]) {
+    assert.doesNotMatch(UC, danger,
+      `update-check 不应包含 ${danger} —— 它只检查，不安装`);
+  }
+});
+
+// ── U9: /version 路由是只读的 ───────────────────────────────────────────
+test('U9: /version 不在写操作白名单里，且不接受客户端 URL', () => {
+  // isWriteRoute 里不应出现 version
+  const at = INDEX.indexOf('const isWriteRoute');
+  assert.ok(at > 0);
+  const seg = INDEX.slice(at, at + 700);
+  assert.doesNotMatch(seg, /'version'/,
+    '/version 没有任何副作用，不该算写操作（否则会被强制要求 JSON 与 Origin）');
+
+  // 路由内部不能从请求里读 URL —— 那等于让本机访问任意地址（SSRF）
+  const vAt = INDEX.indexOf("if (head === 'version') {");
+  assert.ok(vAt > 0, '应有 /version 路由');
+  const vSeg = INDEX.slice(vAt, vAt + 1200);
+  assert.doesNotMatch(vSeg, /searchParams\.get\(['"]url/,
+    '不得接受客户端传入的查询地址');
+  assert.doesNotMatch(vSeg, /req\.url.*https?:/,
+    '不得把请求里的 URL 直接当抓取目标');
+});
+
+// ── U10: 前端只读结果，不执行任何安装动作 ───────────────────────────────
+test('U10: GUI 只显示版本与命令，绝不自动安装', () => {
+  // 界面上有版本卡片
+  assert.match(CLIENT, /版本与更新/);
+  assert.match(CLIENT, /检查更新/);
+
+  // 但**不能**有任何"自动更新"的调用
+  for (const danger of [
+    /updatePlugin\s*\(/,
+    /installUpdate\s*\(/,
+    /applyUpdate\s*\(/,
+  ]) {
+    assert.doesNotMatch(CLIENT, danger,
+      'GUI 不得有自动安装/自动更新的入口');
+  }
+
+  // 升级命令只能是"显示"和"复制"，不能被执行
+  const at = CLIENT.indexOf('copyUpgradeCommand');
+  assert.ok(at > 0, '应有复制命令的动作');
+  const seg = CLIENT.slice(at, at + 800);
+  assert.doesNotMatch(seg, /exec|spawn|shell/i,
+    '复制命令只能写剪贴板，不能执行');
+});
+
+// ── U11: 版本状态用独立 state，不掺进主 state ───────────────────────────
+test('U11: 版本信息用独立 useState（避开 25 处 set 的字段遗漏坑）', () => {
+  // 主 state 有 25 处 set() 逐字段重建，加字段要改 25 处 ——
+  // 已因此出过 4 次 bug。版本信息走独立 state 就一劳永逸。
+  assert.match(CLIENT, /var vst = React\.useState\(/,
+    '版本信息应有独立的 useState');
+  assert.match(CLIENT, /var vset = vst\[1\]/);
+
+  // 主 state 里不应出现 version 字段（那会要求 25 处都带上它）
+  const stAt = CLIENT.indexOf('var st = React.useState({');
+  const stEnd = CLIENT.indexOf('})', stAt);
+  const mainState = CLIENT.slice(stAt, stEnd);
+  assert.doesNotMatch(mainState, /^\s*version:/m,
+    '版本字段不该塞进主 state');
+});
+
+// ── U12: hasUpdate 的方向必须正确（本地旧→true，本地新→false）──────────
+test('U12: hasUpdate 方向 —— 只在远端更新时为 true', async () => {
+  // ⚠️ 2026-10-18 实测抓到的真 bug：第一版写成 `cmp < 0`，**方向反了**。
+  //
+  // 表现：本地 0.4.48、npm 还在暂存队列里是 0.4.47 ——
+  // 界面却显示"有新版"。也就是 npm 落后时装作有新版本，
+  // npm 超前时反而不提示。
+  //
+  // 这个 bug 能溜过去，是因为 U1 只测了 compareVersions 本身，
+  // 没有任何用例断言 hasUpdate 的**方向**。所以补上。
+  const { checkForUpdate } = await import('../lib/update-check.js');
+
+  const tmp = join(ROOT, '.tmp-u12-' + Math.random().toString(36).slice(2, 8));
+  try {
+    mkdirSync(tmp, { recursive: true });
+
+    // ① 远端更新（0.9.9 > 0.4.48）→ 有新版
+    writeFileSync(join(tmp, 'package.json'), JSON.stringify({ version: '0.4.48' }));
+    const newer = async () => ({ ok: true, json: async () => ({ 'dist-tags': { latest: '0.9.9' } }) });
+    const r1 = await checkForUpdate({ pluginRoot: tmp, force: true, fetchImpl: newer });
+    assert.equal(r1.hasUpdate, true,
+      '远端 0.9.9 > 本地 0.4.48，必须提示有新版');
+
+    // ② 远端落后（npm 暂存队列期间会这样）→ 不能提示有新版
+    const older = async () => ({ ok: true, json: async () => ({ 'dist-tags': { latest: '0.4.40' } }) });
+    const r2 = await checkForUpdate({ pluginRoot: tmp, force: true, fetchImpl: older });
+    assert.equal(r2.hasUpdate, false,
+      '远端 0.4.40 < 本地 0.4.48，**不能**提示有新版 —— '
+      + 'npm 暂存队列期间就会出现这种"远端落后"，提示更新会让用户困惑');
+
+    // ③ 相同版本 → 无新版
+    const same = async () => ({ ok: true, json: async () => ({ 'dist-tags': { latest: '0.4.48' } }) });
+    const r3 = await checkForUpdate({ pluginRoot: tmp, force: true, fetchImpl: same });
+    assert.equal(r3.hasUpdate, false, '版本相同不应提示更新');
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+// ── U13: 两个源都查，取较高版本（npm 暂存队列期间不能漏更新）────────────
+test('U13: 并行查两个源，取较高版本', async () => {
+  // 实测场景（2026-10-18）：npm 有暂存队列，发布后 latest 会落后一阵。
+  //   npm latest   = 0.4.47
+  //   GitHub main  = 0.4.48
+  // 若"先 npm、失败才回退 GitHub"，这期间**所有人都看不到 0.4.48 可用**，
+  // 而 GitHub 安装的用户本来就是以 main 为准的。
+  //
+  // 所以并行查两个源、取较高版本。两个源都是同一套发布流程的正式产物。
+  const { checkForUpdate, NPM_REGISTRY_URL, GITHUB_RAW_PKG_URL } =
+    await import('../lib/update-check.js');
+
+  const tmp = join(ROOT, '.tmp-u13-' + Math.random().toString(36).slice(2, 8));
+  try {
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(join(tmp, 'package.json'), JSON.stringify({ version: '0.4.47' }));
+
+    const seen = [];
+    // npm 落后、GitHub 较新
+    const fake = async (url) => {
+      seen.push(url);
+      if (url === NPM_REGISTRY_URL) {
+        return { ok: true, json: async () => ({ 'dist-tags': { latest: '0.4.47' } }) };
+      }
+      if (url === GITHUB_RAW_PKG_URL) {
+        return { ok: true, json: async () => ({ version: '0.4.48' }) };
+      }
+      return { ok: false, status: 404 };
+    };
+
+    const r = await checkForUpdate({ pluginRoot: tmp, force: true, fetchImpl: fake });
+
+    assert.equal(r.ok, true);
+    assert.equal(r.latest, '0.4.48',
+      'npm 落后时应采信 GitHub 的更高版本 —— 否则用户永远等不到更新提示');
+    assert.equal(r.hasUpdate, true, '0.4.48 > 0.4.47，应有新版');
+    assert.match(r.source, /github/,
+      'source 应标明采用了 GitHub 的版本');
+
+    // 两个源都要真的查过（不是串行等待）
+    assert.ok(seen.includes(NPM_REGISTRY_URL), '应查 npm');
+    assert.ok(seen.includes(GITHUB_RAW_PKG_URL), '应查 GitHub');
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+// ── U14: 反向 —— 本地较新时不提示（npm 超前也不会误报）──────────────────
+test('U14: 两个源都落后于本地时不提示更新', async () => {
+  const { checkForUpdate, NPM_REGISTRY_URL, GITHUB_RAW_PKG_URL } =
+    await import('../lib/update-check.js');
+
+  const tmp = join(ROOT, '.tmp-u14-' + Math.random().toString(36).slice(2, 8));
+  try {
+    mkdirSync(tmp, { recursive: true });
+    writeFileSync(join(tmp, 'package.json'), JSON.stringify({ version: '0.5.0' }));
+
+    const fake = async (url) => {
+      if (url === NPM_REGISTRY_URL) {
+        return { ok: true, json: async () => ({ 'dist-tags': { latest: '0.4.40' } }) };
+      }
+      return { ok: true, json: async () => ({ version: '0.4.48' }) };
+    };
+
+    const r = await checkForUpdate({ pluginRoot: tmp, force: true, fetchImpl: fake });
+    assert.equal(r.latest, '0.4.48', '取较高的那个（0.4.48 > 0.4.40）');
+    assert.equal(r.hasUpdate, false, '两个源都低于本地 0.5.0，不该提示更新');
+  } finally {
+    rmSync(tmp, { recursive: true, force: true });
+  }
+});