dsh-plugin-notify-sounds 1.5.0 → 1.6.1

package/README.md

@@ -1,5 +1,7 @@
 # dsh-plugin-notify-sounds
 
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-notify-sounds.svg)](https://www.npmjs.com/package/dsh-plugin-notify-sounds)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-notify-sounds.svg)](https://www.npmjs.com/package/dsh-plugin-notify-sounds)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![DeepSeek Harness plugin](https://img.shields.io/badge/dsh-plugin-8b5cf6.svg)](https://github.com/deepseek-ai/deepseek-harness)
 
@@ -12,11 +14,15 @@ Walk away from the window without missing anything: an OS notification in the ba
 **Install**: DSH → Settings → Plugins → Add plugin, paste the line below and press **Install**:
 
 ```
-https://github.com/BillCx330/dsh-plugin-notify-sounds
+dsh-plugin-notify-sounds
 ```
 
 ---
 
+## Consistent with DSH's own UI
+
+Every visual detail of the settings section comes from DSH's own design system: row geometry, dividers, type sizes and spacing use the official design tokens, the sound picker is the official `Menu` primitive, the icons come from the official family, and the layout follows the native text-left, control-right row shape. Installing it does not introduce a visually disjoint third-party block into your settings.
+
 ## What it does
 
 | What | What you get |
@@ -28,6 +34,7 @@ https://github.com/BillCx330/dsh-plugin-notify-sounds
 | **Only what you care about** | Sub-agents (background tasks) are completely silent by default — only your own conversation is announced |
 | **Quiet when it should be** | Quiet hours (e.g. 22:00–08:00, wrapping past midnight), notify-only-when-hidden, and a master switch |
 | **Your sound, your way** | Nine built-in sounds, custom ringtone upload, volume — each feature with its own toggle |
+| **Updates itself** | Check npm for a new version and install it in one click: verified against the published digest before anything is replaced, restored on failure; restart DSH to load it |
 
 ## Why
 
@@ -37,17 +44,15 @@ This plugin turns "it is waiting for you" and "it is done" into sound. With syst
 
 ## Sounds
 
-Nine Web Audio synthesized sounds — no audio files, no network requests:
+Bell · Chime · Ding · Drop · Pulse · Arc · Coin · Success · Knock — nine built-in sounds, all synthesized live with Web Audio: no audio files, no network requests.
 
-Bell · Chime · Ding · Drop · Pulse · Arc · Coin · Success · Knock
-
-Or upload your own ringtone (mp3/wav/ogg, ≤512KB, validated and volume-normalized automatically), or pick "None" for notifications only. Each trigger (approval / question / completion) can use a different sound, with preview right in the settings.
+Or upload your own ringtone (mp3/wav/ogg, ≤512KB, validated and volume-normalized automatically), or pick "None" for notifications only. Each trigger (approval / question / completion) gets its own sound, with preview right in the settings.
 
 ## Settings
 
 Settings → **Sounds** (between General and Models). Every feature has its own toggle, styled exactly like DSH's own preference pages:
 
-master switch and volume · per-trigger sounds with preview · sub-agent alerts · system notifications · window title alert · repeat interval · quiet hours · hidden-only mode · custom ringtone upload
+master switch and volume · per-trigger sounds with preview · sub-agent alerts · system notifications · window title alert · repeat interval · quiet hours · hidden-only mode · custom ringtone upload · update checks and one-click update
 
 Everything applies immediately — no restart needed.
 
@@ -56,20 +61,20 @@ Everything applies immediately — no restart needed.
 ### Simplest: two clicks inside DSH (recommended)
 
 1. In DSH open **Settings → Plugins** and press **Add plugin**;
-2. Paste this into the box:
+2. Paste the package name into the box (this plugin is published on [npm](https://www.npmjs.com/package/dsh-plugin-notify-sounds)):
 
    ```
-   https://github.com/BillCx330/dsh-plugin-notify-sounds
+   dsh-plugin-notify-sounds
    ```
 
-   (that is the "GitHub repository address" the box asks for; `github:BillCx330/dsh-plugin-notify-sounds` or a local directory path work too)
+   (the GitHub repository address `https://github.com/BillCx330/dsh-plugin-notify-sounds` or a local directory path work too)
 3. Press **Install**, then **restart DSH** once.
 
 The "install source" dropdown above the box picks the download mirror (mainland China mirror by default; leave it alone unless downloads are slow). DSH warns that a plugin runs with your permissions — this one only reads session state and plays sounds locally; its single request goes to **your own DSH** to raise the window when you click a notification, and nothing is sent anywhere else.
 
 ### Upgrading
 
-**There is no auto-update**: to upgrade, **uninstall** the old version from the same place first, then install the new one as above.
+DSH does not update plugins on its own, but this plugin **updates itself**: Settings → Sounds → Updates can check for a new version and install it in one click. Uninstalling and installing again also works.
 
 ### Other ways
 
@@ -94,6 +99,7 @@ The command line writes `dsh.profile.bundles` and installs the dependency for yo
 ## Known limitations
 
 - **Hand-edited config**: preferences live in the profile's `cordis.patch.yml`; values must match the schema (volume 0–100, a preset id, `HH:MM` times) or the plugin declines to load — just fix the value. The settings UI only ever writes valid values.
+- **One-click update only swaps files**: it replaces the seven files this package ships and **never touches the profile's configuration**. Downloaded code is never executed — the new code loads on a **DSH restart**. Let the row report a result before closing the window (an interrupted update restores itself, but there is no reason to gamble); if a future release adds a dependency, that needs installing separately (this one has none).
 - **Multiple windows** fire independently: the same event may chime once per window; turn on notify-only-when-hidden to avoid it.
 - **Quiet hours hold reminders, they do not drop them**: a repeat reminder that becomes due during the quiet range fires right after it ends, and several pending decisions can fire at once then.
 - **Click-to-return** is fully implemented and tested on Windows; macOS / Linux fall back to the system deep link and are unverified.
@@ -117,6 +123,8 @@ For anyone hacking on the code (exact details live in the source comments):
 
 ## Changelog
 
+- **v1.6.1** (2026-10-11) The README is rebuilt as a release page: a new **Consistent with DSH's own UI** section on how the UI matches DSH's own settings, copy polished throughout, and the upgrade notes corrected — the plugin updates itself, so no uninstall is needed. This release doubles as the live drill for one-click update.
+- **v1.6.0** (2026-10-11) New: **check for updates and install them in one click**. The settings section can fetch the newest npm version and install it: the download is checked against the registry's published sha512, only whitelisted files are unpacked (symlinks and path traversal are refused), the old files are kept aside, and any failure restores them. Downloaded code is never executed — the new code loads when DSH restarts. Automatic checks run at most once a day and can be turned off, with the mainland-China mirror as fallback.
 - **v1.5.0** (2026-10-08) The "finished" title mark is unread news now — set by a finish that happens while you are away, cleared when you return — instead of reappearing on every switch-away. The retrigger cooldown is per session, so two conversations deciding within 2 seconds both ring. The Host half gained tests (Config schema, focus route, title matching) that cross-check the shared constants between the halves; the sessions provider is now an explicit load prerequisite, and quiet-hours catch-up is documented.
 
 - **v1.4.4** (2026-10-08) Quiet hours now suppress the taskbar title alert too, and the title refreshes as the quiet-hours window begins or ends. Custom-sound upload/removal writes are ordered and roll back on refusal; synchronous config-write errors are handled as save failures.
@@ -143,6 +151,8 @@ node test/smoke.mjs     # client half: assembly, triggers, cooldown, quiet hours
 node test/host.mjs      # host half: config schema, focus route, title matching, cross-half contracts
 ```
 
+To publish to npm: bump the version, then `npm publish` (`npm login` and 2FA the first time). **npm versions are immutable** — bump for every change.
+
 ```
 dsh-plugin-notify-sounds/
 ├── package.json        # dsh.bundle.patch + dsh.client

package/README.zh.md

@@ -1,5 +1,7 @@
 # dsh-plugin-notify-sounds
 
+[![npm version](https://img.shields.io/npm/v/dsh-plugin-notify-sounds.svg)](https://www.npmjs.com/package/dsh-plugin-notify-sounds)
+[![npm downloads](https://img.shields.io/npm/dm/dsh-plugin-notify-sounds.svg)](https://www.npmjs.com/package/dsh-plugin-notify-sounds)
 [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![DeepSeek Harness plugin](https://img.shields.io/badge/dsh-plugin-8b5cf6.svg)](https://github.com/deepseek-ai/deepseek-harness)
 
@@ -12,11 +14,15 @@
 **安装**：DSH → 设置 → 插件 → 添加插件，粘贴下面这行，点「安装」：
 
 ```
-https://github.com/BillCx330/dsh-plugin-notify-sounds
+dsh-plugin-notify-sounds
 ```
 
 ---
 
+## 与 DSH 界面保持一致
+
+设置面板中的每一处视觉细节都取自 DSH 自身的设计体系：行几何、分隔线、字号与间距沿用官方设计令牌，音效选择器使用官方 `Menu` 组件，图标来自官方图标族，排布沿用「文字左 / 控件右」的原生行式。安装后不会在设置中出现风格割裂的第三方区块。
+
 ## 它做什么
 
 | 提醒什么 | 效果 |
@@ -28,6 +34,7 @@ https://github.com/BillCx330/dsh-plugin-notify-sounds
 | **只提醒你关心的** | 子智能体（后台任务）默认完全静默，只提醒主对话，可开关 |
 | **该安静时安静** | 静音时段（如 22:00–08:00，可跨午夜）、仅页面不可见时提示、总开关一键全静音 |
 | **声音随你** | 九种内置音效、自定义铃声上传、音量调节，每项独立开关 |
+| **自己更新** | 设置里检查 npm 新版本并一键更新：下载后校验完整性才替换，失败自动还原；更新后重启 DSH 生效 |
 
 ## 为什么需要它
 
@@ -37,17 +44,15 @@ DSH 的状态提示只有视觉——状态点、侧栏标记。你一切到别
 
 ## 声音
 
-九种 Web Audio 合成音效，不含任何音频文件、不发网络请求：
+双音铃 · 风铃 · 单音叮 · 水滴 · 脉冲 · 上行琶音 · 金币 · 达成 · 敲门 —— 九种内置音效全部由 Web Audio 现场合成，不含任何音频文件、不发一次网络请求。
 
-双音铃 · 风铃 · 单音叮 · 水滴 · 脉冲 · 上行琶音 · 金币 · 达成 · 敲门
-
-另可上传自己的铃声（mp3/wav/ogg，≤512KB，自动校验与音量归一化），或选「无声」只留通知。三种触发（审批 / 提问 / 完成）可各选各的音效，设置里直接试听。
+也可以换上你自己的铃声（mp3/wav/ogg，≤512KB，自动校验并做音量归一化），或者干脆选「无声」只留通知。三种触发（审批 / 提问 / 完成）各选各的音效，设置里随时试听。
 
 ## 设置
 
 设置 → **提示音**（位于「通用设置」与「模型」之间），每项功能都有独立开关，界面与 DSH 原生设置完全一致：
 
-总开关与音量 · 三种触发各自的音效（含试听）· 子智能体提醒 · 系统通知 · 窗口标题提醒 · 重复提醒间隔 · 静音时段 · 仅后台提示 · 自定义铃声上传
+总开关与音量 · 三种触发各自的音效（含试听）· 子智能体提醒 · 系统通知 · 窗口标题提醒 · 重复提醒间隔 · 静音时段 · 仅后台提示 · 自定义铃声上传 · 自动检查更新与一键更新
 
 改动即时生效，无需重启。
 
@@ -56,20 +61,20 @@ DSH 的状态提示只有视觉——状态点、侧栏标记。你一切到别
 ### 最简单：在 DSH 里点两下（推荐）
 
 1. 打开 DSH → **设置 → 插件**，点**添加插件**；
-2. 在输入框粘贴：
+2. 在输入框粘贴包名（本插件已发布在 [npm](https://www.npmjs.com/package/dsh-plugin-notify-sounds)）：
 
    ```
-   https://github.com/BillCx330/dsh-plugin-notify-sounds
+   dsh-plugin-notify-sounds
    ```
 
-   （粘贴的就是「GitHub 仓库地址」；填 `github:BillCx330/dsh-plugin-notify-sounds` 或本地目录路径也可以）
+   （填 GitHub 仓库地址 `https://github.com/BillCx330/dsh-plugin-notify-sounds` 或本地目录路径也可以）
 3. 点**安装**，装完**重启 DSH** 一次。
 
 输入框上方的「安装源」是下载源，默认中国大陆镜像源，国内一般不用改。DSH 会提示「插件以你的权限运行」——本插件只读会话状态、在本地发声；唯一的请求是点击系统通知时发给**本机 DSH** 的唤窗请求，不向外部发送任何数据。
 
 ### 升级
 
-**装完不支持自动更新**：要升级请先在同一处**卸载**旧版，再按上面的步骤装新版。
+DSH 不会自动更新插件，但本插件**自带更新**：设置 → 提示音 →「更新」里可以检查新版并一键安装。想走手动路径也可以：在同一处先**卸载**旧版，再按上面的步骤装新版。
 
 ### 其他安装方式
 
@@ -94,6 +99,7 @@ dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds
 ## 已知边界
 
 - **手改配置**：偏好写在 profile 的 `cordis.patch.yml`，值必须符合 schema（音量 0–100、音效为预设之一、时间 `HH:MM`）；写错会让插件不加载，改回即可。设置界面只会写入合法值。
+- **一键更新只换文件**：只替换本包内的七个文件，**不碰 profile 配置**；下载内容从不执行，新代码要等**重启 DSH** 才生效。更新过程请等状态行给出结果再关窗口（中断会自动还原，但没必要赌）；若未来的新版引入了新依赖，需另行安装（当前零依赖）。
 - **多窗口**：各窗口独立触发，同一事件可能各响一次；打开「仅在页面不可见时提示」即可避免。
 - **静音时段是「挂起」不是「丢弃」**：静音期间到期的重复提醒会在时段结束后立即补发，多个待决策可能同时补响。
 - **点击通知回到窗口**：Windows 完整实现并实测；macOS / Linux 走系统深链，未验证。
@@ -117,6 +123,8 @@ dsh plugin --profile <你的 profile> add ./dsh-plugin-notify-sounds
 
 ## 更新记录
 
+- **v1.6.1**（2026-10-11）README 重排为发布页风格：补「**与 DSH 界面保持一致**」一节讲清界面取自 DSH 自身设计体系；通篇表达润色，并修正升级说明（本插件自带更新，无需卸载重装）。本版同时是「一键更新」的发布演练。
+- **v1.6.0**（2026-10-11）新增**检查更新与一键更新**：设置里可查 npm 新版本并一键安装——下载后按 registry 公布的 sha512 校验、只解包白名单文件（拒绝符号链接与路径穿越）、先备份再替换、失败自动还原；下载内容从不执行，新代码在 DSH 重启时生效。自动检查每天最多一次、可关；npm 官方源不通时自动改用国内镜像。
 - **v1.5.0**（2026-10-08）「已完成」标题标记改为未读语义——离开期间发生的完成才标记，回到页面即清除，不再每次切走都重新出现；触发冷却按会话独立，2 秒内两个会话先后需要决策时都会响。补齐宿主半测试（配置 schema、唤窗路由、标题匹配）并交叉校验两半共享常量；`dsh.client.inject` 显式声明 sessions 提供包；静音时段结束后的补发行为写入文档。
 
 - **v1.4.4**（2026-10-08）静音时段现在也会屏蔽任务栏标题提醒；进入或离开静音时段时，标题标记会自动刷新。自定义音效上传/移除按顺序写入配置，写入被拒时回滚；配置写入同步抛错也会按保存失败处理。
@@ -143,6 +151,8 @@ node test/smoke.mjs     # 客户端半：装配、触发、冷却、静音、重
 node test/host.mjs      # 宿主半：配置 schema、唤窗路由、标题匹配、两半契约交叉校验
 ```
 
+发布到 npm：升好版本号后 `npm publish`（首次发布先 `npm login` 并按提示开启 2FA）。**npm 的版本号不可覆盖**——有任何改动都请升版本再发。
+
 ```
 dsh-plugin-notify-sounds/
 ├── package.json        # dsh.bundle.patch + dsh.client

package/lib/client.js

@@ -178,6 +178,22 @@ window.__ModuleLoader__.load({
 			"notify.decision.body": "智能体正在等待你的决定",
 			"notify.completion.title": "任务完成",
 			"notify.completion.body": "智能体已完成当前任务",
+			"update.title": "更新",
+			"update.description": "从 npm 检查本插件的新版本（只查询，不下载）",
+			"update.auto": "自动检查更新",
+			"update.auto.description": "每天最多静默检查一次，发现新版只在下方标记，不弹通知",
+			"update.check": "检查更新",
+			"update.current": "当前版本",
+			"update.idle": "尚未检查",
+			"update.checking": "检查中…",
+			"update.uptodate": "已是最新",
+			"update.available": "有新版",
+			"update.failed": "检查失败（网络不可用）",
+			"update.apply": "立即更新",
+			"update.updating": "更新中…",
+			"update.done": "更新完成",
+			"update.restart": "重启 DSH 后生效",
+			"update.applyFailed": "更新失败，已恢复原状",
 		};
 
 		/** English dictionary, checked complete against the zh key set. */
@@ -239,6 +255,22 @@ window.__ModuleLoader__.load({
 			"notify.decision.body": "The agent is waiting for your decision",
 			"notify.completion.title": "Task finished",
 			"notify.completion.body": "The agent has finished the current task",
+			"update.title": "Updates",
+			"update.description": "Check npm for a newer version of this plugin (a query only — nothing is downloaded)",
+			"update.auto": "Check for updates automatically",
+			"update.auto.description": "At most one quiet check a day; a newer version is only marked below, never announced",
+			"update.check": "Check now",
+			"update.current": "This version",
+			"update.idle": "Not checked yet",
+			"update.checking": "Checking…",
+			"update.uptodate": "Up to date",
+			"update.available": "New version available",
+			"update.failed": "Check failed (no network)",
+			"update.apply": "Update now",
+			"update.updating": "Updating…",
+			"update.done": "Updated",
+			"update.restart": "restart DSH to load it",
+			"update.applyFailed": "Update failed — the previous version is intact",
 		};
 		//#endregion
 
@@ -708,6 +740,12 @@ window.__ModuleLoader__.load({
 		/** Route the Host half serves for notification clicks; must match the Host half's FOCUS_PATH. */
 		const FOCUS_PATH = "/notify-sounds/focus";
 
+		/** Route the Host half answers the update check on; must match the Host half's UPDATE_CHECK_PATH. */
+		const UPDATE_CHECK_PATH = "/notify-sounds/update/check";
+
+		/** Route the Host half applies an update through; must match the Host half's UPDATE_APPLY_PATH. */
+		const UPDATE_APPLY_PATH = "/notify-sounds/update/apply";
+
 		/**
 		 * Show one OS notification; every failure mode is silent. The tag
 		 * collapses repeats per trigger kind, and `silent` keeps the OS from
@@ -1039,6 +1077,21 @@ window.__ModuleLoader__.load({
 						failed: failedField === "onlyWhenHidden",
 						onChange: (next) => write("onlyWhenHidden", next),
 					}),
+					h(SwitchRow, {
+						key: "updateAutoCheck",
+						t,
+						title: t("update.auto"),
+						description: t("update.auto.description"),
+						label: t("update.auto"),
+						checked: value?.updateAutoCheck !== false,
+						disabled,
+						failed: failedField === "updateAutoCheck",
+						onChange: (next) => write("updateAutoCheck", next),
+					}),
+					h(UpdateRow, {
+						key: "update",
+						t,
+					}),
 				]),
 			]);
 		}
@@ -1487,6 +1540,86 @@ window.__ModuleLoader__.load({
 				]),
 			]);
 		}
+
+		/**
+		 * The update row: what this installation runs, what npm has, and the
+		 * buttons to ask and to install.
+		 *
+		 * The check is a read-only question; the update is one POST to the
+		 * Host, which does the downloading, verifying and swapping itself —
+		 * the page never touches the package. Both routes are fixed to this
+		 * plugin's own package, so there is no input here to aim anywhere
+		 * else, and the Host answers recent questions from its own cache, so
+		 * opening the section costs no network at all.
+		 *
+		 * @param props - copy.
+		 * @returns the row element tree.
+		 */
+		function UpdateRow({ t }) {
+			const [state, setState] = useState({ phase: "idle" });
+			const check = (force) => async () => {
+				setState({ phase: "checking" });
+				try {
+					const response = await fetch(UPDATE_CHECK_PATH + (force ? "?force=1" : ""), { method: "GET" });
+					const payload = await response.json();
+					setState({ phase: "done", payload });
+				} catch {
+					setState({ phase: "failed" });
+				}
+			};
+			const apply = async () => {
+				setState({ phase: "updating" });
+				try {
+					const response = await fetch(UPDATE_APPLY_PATH, { method: "POST" });
+					const result = await response.json();
+					setState({ phase: result?.ok === true ? (result.upToDate === true ? "done" : "updated") : "applyFailed", result });
+				} catch {
+					setState({ phase: "applyFailed" });
+				}
+			};
+			// A cached answer makes this free; only a cold Host reaches out.
+			useEffect(() => {
+				check(false)();
+			}, []);
+			const payload = state.payload;
+			const version = (text) => (typeof text === "string" && text !== "" ? `v${text}` : "?");
+			let status = payload === undefined
+				? t("update.idle")
+				: payload.updateAvailable === true
+					? `${t("update.available")} ${version(payload.latest)}`
+					: t("update.uptodate");
+			if (state.phase === "checking") status = t("update.checking");
+			if (state.phase === "updating") status = t("update.updating");
+			if (state.phase === "applyFailed") status = t("update.applyFailed");
+			let detail = payload === undefined ? status : `${t("update.current")} ${version(payload.current)} · ${status}`;
+			if (state.phase === "updated") {
+				detail = `${t("update.done")}：${version(state.result?.from)} → ${version(state.result?.to)}，${t("update.restart")}`;
+			}
+			const busy = state.phase === "checking" || state.phase === "updating";
+			return h("div", { className: css.row }, [
+				h("div", { key: "text" }, [
+					h("div", { className: css.rowTitle, key: "title" }, t("update.title")),
+					h("div", { className: css.rowDescription, key: "description" }, t("update.description")),
+					h("div", { className: css.hint, key: "status" }, detail),
+				]),
+				h("div", { className: css.stackControl, key: "control" }, [
+					payload?.updateAvailable === true && state.phase !== "updated" ? h(Button, {
+						key: "apply",
+						variant: "outline",
+						size: "sm",
+						disabled: busy,
+						onClick: apply,
+					}, t("update.apply")) : null,
+					h(Button, {
+						key: "check",
+						variant: "outline",
+						size: "sm",
+						disabled: busy,
+						onClick: check(true),
+					}, t("update.check")),
+				]),
+			]);
+		}
 		//#endregion
 
 		//#region settings nav icon
@@ -1991,6 +2124,32 @@ window.__ModuleLoader__.load({
 				};
 			}, "notify-sounds: session status watcher");
 
+			// Quiet update check: shortly after the page settles, then at most
+			// once a day, and never while the user has it turned off. It asks
+			// the Host's own route — one small query, nothing downloaded — and
+			// the answer is waiting in the settings row whenever the user looks.
+			//
+			// A self-rescheduling timeout rather than an interval: the next
+			// check is scheduled after this one, so a suspended machine does not
+			// come back to a queue of them. `unref` keeps a test process from
+			// waiting on the next tick.
+			ctx.effect(() => {
+				let timer;
+				const tick = () => {
+					try {
+						if (form.getSnapshot().value?.updateAutoCheck === false) return;
+						fetch(UPDATE_CHECK_PATH, { method: "GET" }).catch(() => {});
+					} catch {}
+					timer = setTimeout(tick, 24 * 60 * 60 * 1000);
+					timer.unref?.();
+				};
+				timer = setTimeout(tick, 30 * 1000);
+				timer.unref?.();
+				return () => {
+					clearTimeout(timer);
+				};
+			}, "notify-sounds: update check");
+
 			// The Settings section: registered only while the Host serves this
 			// package's namespace, so a deployment without the entry shows no
 			// trace of the page. The nav glyph patch shares the gate — no
@@ -2029,6 +2188,8 @@ window.__ModuleLoader__.load({
 		// value must survive.
 		exports.SOUND_IDS = SOUND_IDS;
 		exports.FOCUS_PATH = FOCUS_PATH;
+		exports.UPDATE_CHECK_PATH = UPDATE_CHECK_PATH;
+		exports.UPDATE_APPLY_PATH = UPDATE_APPLY_PATH;
 		exports.timeOfDayToMinutes = timeOfDayToMinutes;
 		return module.exports;
 	},

package/lib/index.js

@@ -23,9 +23,12 @@
 
 import z from "@deepseek-ai/schemastery";
 import { spawn } from "node:child_process";
+import { createHash, timingSafeEqual } from "node:crypto";
 import { createRequire } from "node:module";
-import { existsSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { gunzipSync } from "node:zlib";
 
 /** Diagnostic name of this Host plugin. */
 export const name = "notify-sounds";
@@ -422,6 +425,435 @@ function focusDesktopWindow() {
 	}
 }
 
+//#region update check
+
+/** Route the browser half reads the update check through. */
+export const UPDATE_CHECK_PATH = "/notify-sounds/update/check";
+
+/** The npm package this plugin publishes as — the only name the check ever asks for. */
+const UPDATE_PACKAGE = "dsh-plugin-notify-sounds";
+
+/**
+ * Registries the update check consults, in order.
+ *
+ * HTTPS and hardcoded on purpose: this is the one place the plugin asks the
+ * outside world for something it may later act on, so nothing about it is
+ * configurable. The second entry is the mainland-China mirror, matching the
+ * install source DSH itself offers.
+ */
+const UPDATE_REGISTRIES = ["https://registry.npmjs.org", "https://registry.npmmirror.com"];
+
+/** How long one check result is trusted before the next check may run. */
+const UPDATE_CHECK_TTL_MS = 24 * 60 * 60 * 1000;
+
+/** Minimum spacing between real requests, so a held-down button cannot hammer a registry. */
+const UPDATE_CHECK_SPACING_MS = 15 * 1000;
+
+/** Bounds on the single request a check makes. */
+const UPDATE_FETCH_TIMEOUT_MS = 10 * 1000;
+const UPDATE_MAX_RESPONSE_BYTES = 256 * 1024;
+
+/** Result of the last check, and when the last real request went out. */
+const updateCheck = { checkedAt: 0, requestedAt: 0, result: undefined };
+
+/**
+ * Parse `major.minor.patch` with an optional prerelease tag.
+ *
+ * @returns the parts, or undefined when the text is not a version.
+ */
+export function parseVersion(text) {
+	if (typeof text !== "string") return undefined;
+	const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(text);
+	if (match === null) return undefined;
+	return [Number(match[1]), Number(match[2]), Number(match[3]), match[4] ?? ""];
+}
+
+/**
+ * Compare two versions the way an npm `latest` tag is meant to be compared.
+ *
+ * @returns negative when `a` sorts before `b`, 0 when they are the same
+ *   release, positive when `a` sorts after; `NaN` when either is not a version.
+ */
+export function compareVersions(a, b) {
+	const left = parseVersion(a);
+	const right = parseVersion(b);
+	if (left === undefined || right === undefined) return NaN;
+	for (let i = 0; i < 3; i++) {
+		if (left[i] !== right[i]) return left[i] - right[i];
+	}
+	// Same core: a prerelease sorts before its own release (1.5.0-rc.1 < 1.5.0).
+	if (left[3] !== right[3]) {
+		if (left[3] === "") return 1;
+		if (right[3] === "") return -1;
+		return left[3] < right[3] ? -1 : 1;
+	}
+	return 0;
+}
+
+/**
+ * The version this installation ships, read from the package's own manifest.
+ *
+ * @returns the version, or undefined when the manifest is unreadable.
+ */
+function readOwnVersion(root) {
+	try {
+		const manifest = root === undefined
+			? new URL("../package.json", import.meta.url)
+			: join(root, "package.json");
+		const parsed = JSON.parse(readFileSync(manifest, "utf8"));
+		return typeof parsed.version === "string" ? parsed.version : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+/**
+ * Whether a tarball URL is somewhere this plugin is willing to download from.
+ *
+ * The URL arrives inside a registry response, so it is untrusted input: https
+ * only, and the host must be one of the registries above. A registry pointing
+ * anywhere else is refused rather than followed. The download stage checks
+ * this again on its own — validating it here too means a hostile answer is
+ * rejected at the door, not at the moment it is about to be used.
+ */
+export function isTrustedTarball(url) {
+	try {
+		const parsed = new URL(url);
+		return parsed.protocol === "https:" && UPDATE_REGISTRIES.some((registry) => parsed.origin === registry);
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Read a response body under a hard size cap.
+ *
+ * The check asks for one small JSON document; anything longer is either not
+ * that document or is trying to be more than one, and neither is worth
+ * buffering. Chunks are counted as they arrive and the read is abandoned at
+ * the cap.
+ */
+async function readCappedBytes(response, cap) {
+	const declared = Number(response.headers.get("content-length") ?? 0);
+	if (Number.isFinite(declared) && declared > cap) throw new Error("response too large");
+	const reader = response.body?.getReader?.();
+	if (reader === undefined) throw new Error("response has no body");
+	const chunks = [];
+	let size = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		size += value.byteLength;
+		if (size > cap) {
+			try {
+				await reader.cancel();
+			} catch {}
+			throw new Error("response too large");
+		}
+		chunks.push(value);
+	}
+	const merged = new Uint8Array(size);
+	let offset = 0;
+	for (const chunk of chunks) {
+		merged.set(chunk, offset);
+		offset += chunk.byteLength;
+	}
+	return merged;
+}
+
+/**
+ * Ask the registries for the newest published version of this plugin.
+ *
+ * Every failure mode — offline, refused, oversized, malformed, a tarball URL
+ * pointing somewhere else — becomes a result the UI can show, never a throw.
+ * This stage only reads: nothing is written to disk and nothing is executed.
+ *
+ * @param options - `force` asks again inside the freshness window (the
+ *   button); otherwise a recent result is returned as-is.
+ * @returns `{ ok, current, latest, updateAvailable, checkedAt }`, or
+ *   `{ ok: false, current, error }` when no registry answered.
+ */
+export async function checkForUpdate(options = {}) {
+	const now = Date.now();
+	if (options.force !== true && updateCheck.result !== undefined && now - updateCheck.checkedAt < UPDATE_CHECK_TTL_MS) {
+		return updateCheck.result;
+	}
+	// Spacing applies to real requests of every kind: a forced check may
+	// refresh, it may not become a load generator.
+	if (now - updateCheck.requestedAt < UPDATE_CHECK_SPACING_MS && updateCheck.result !== undefined) {
+		return updateCheck.result;
+	}
+	updateCheck.requestedAt = now;
+	const current = readOwnVersion();
+	const answer = await fetchRegistryAnswer();
+	if (answer === undefined) {
+		const result = { ok: false, current, error: "no registry answered" };
+		updateCheck.checkedAt = now;
+		updateCheck.result = result;
+		return result;
+	}
+	const ordering = current === undefined ? NaN : compareVersions(current, answer.version);
+	const result = {
+		ok: true,
+		current,
+		latest: answer.version,
+		updateAvailable: Number.isFinite(ordering) && ordering < 0,
+		checkedAt: now,
+	};
+	updateCheck.checkedAt = now;
+	updateCheck.result = result;
+	return result;
+}
+
+/**
+ * Ask the registries for this plugin's newest release and believe only a
+ * well-formed answer.
+ *
+ * The response is untrusted input: the version must parse, the integrity must
+ * be a sha512 digest, and the tarball must live on one of the two registries.
+ * Anything else is skipped, so a hostile or broken answer is never the one a
+ * later download acts on. Both the check and the download go through here —
+ * the download never takes a URL from anywhere else.
+ *
+ * @returns `{ registry, version, tarball, integrity }`, or undefined when no
+ *   registry produced an answer worth believing.
+ */
+async function fetchRegistryAnswer() {
+	for (const registry of UPDATE_REGISTRIES) {
+		try {
+			log(`update check: asking ${registry}`);
+			const response = await fetch(`${registry}/${UPDATE_PACKAGE}/latest`, {
+				signal: AbortSignal.timeout(UPDATE_FETCH_TIMEOUT_MS),
+				redirect: "error",
+				headers: { accept: "application/json" },
+			});
+			if (!response.ok) continue;
+			const payload = JSON.parse(new TextDecoder().decode(await readCappedBytes(response, UPDATE_MAX_RESPONSE_BYTES)));
+			const version = payload?.version;
+			if (typeof version !== "string" || parseVersion(version) === undefined) continue;
+			const integrity = payload?.dist?.integrity;
+			const tarball = payload?.dist?.tarball;
+			if (typeof integrity !== "string" || !integrity.startsWith("sha512-")) continue;
+			if (typeof tarball !== "string" || !isTrustedTarball(tarball)) continue;
+			return { registry, version, tarball, integrity };
+		} catch {
+			// One registry failing is the ordinary case for the next one to
+			// answer; running out of registries is the failure worth reporting.
+		}
+	}
+	return undefined;
+}
+
+//#endregion
+
+//#region update apply
+
+/** Route the browser half asks for an update to be applied through. */
+export const UPDATE_APPLY_PATH = "/notify-sounds/update/apply";
+
+/** Largest update tarball accepted: this plugin is small, and anything larger is not one. */
+const UPDATE_MAX_TARBALL_BYTES = 8 * 1024 * 1024;
+
+/**
+ * The only files an update may replace, as package-relative paths.
+ *
+ * An update is a file swap, not an install: it replaces exactly what the
+ * package publishes and touches nothing else. The profile's own configuration
+ * lives outside this directory and is not on this list — no update can reach
+ * it, whatever an archive contains.
+ */
+const UPDATE_FILES = ["package.json", "cordis.patch.yml", "README.md", "README.zh.md", "LICENSE", "lib/client.js", "lib/index.js"];
+
+/** Where this package is installed: the only tree an update may write to. */
+function packageRoot() {
+	return fileURLToPath(new URL("..", import.meta.url));
+}
+
+/** Read a NUL-terminated string field from a tar header. */
+function readTarString(header, offset, length) {
+	const field = header.subarray(offset, offset + length);
+	let end = field.indexOf(0);
+	if (end === -1) end = field.length;
+	return new TextDecoder().decode(field.subarray(0, end)).trim();
+}
+
+/** Read an octal size field from a tar header; NaN when it is not one. */
+function readTarOctal(header, offset, length) {
+	const text = readTarString(header, offset, length);
+	if (text === "") return 0;
+	const value = parseInt(text, 8);
+	return Number.isFinite(value) ? value : NaN;
+}
+
+/**
+ * Map an archive path to the package-relative file it may replace.
+ *
+ * Everything about a tar path is hostile until shown otherwise: only the
+ * `package/` prefix the registry publishes under, only the whitelisted names,
+ * and never a path that climbs, escapes, or arrives by another separator.
+ */
+export function archivePathToRelative(path) {
+	const normalized = path.replaceAll("\\", "/");
+	if (normalized.startsWith("/") || normalized.split("/").includes("..")) throw new Error(`refusing tar path: ${path}`);
+	const prefix = "package/";
+	if (!normalized.startsWith(prefix)) throw new Error(`refusing tar path: ${path}`);
+	const relative = normalized.slice(prefix.length);
+	if (relative === "" || !UPDATE_FILES.includes(relative)) throw new Error(`refusing tar path: ${path}`);
+	return relative;
+}
+
+/**
+ * Read a tar archive into the few files an update may touch.
+ *
+ * The archive arrived from the network and is treated accordingly:
+ *
+ *   - regular files only — a symlink in an update could point the next write
+ *     anywhere, so any other entry type is refused outright;
+ *   - pax/gnu extension headers are skipped, not interpreted;
+ *   - every name must survive `archivePathToRelative`, so nothing outside
+ *     this package is ever named;
+ *   - a header claiming more than the archive holds is an error, not a read.
+ *
+ * @returns a Map of package-relative path → contents.
+ */
+export function unpackTar(bytes) {
+	const files = new Map();
+	let offset = 0;
+	while (offset + 512 <= bytes.length) {
+		const header = bytes.subarray(offset, offset + 512);
+		const name = readTarString(header, 0, 100);
+		if (name === "") break;
+		const size = readTarOctal(header, 124, 12);
+		if (!Number.isFinite(size) || size < 0) throw new Error("tar entry has no readable size");
+		const contentStart = offset + 512;
+		if (contentStart + size > bytes.length) throw new Error("tar entry claims more than the archive holds");
+		const typeflag = readTarString(header, 156, 1);
+		const prefix = readTarString(header, 345, 155);
+		const content = bytes.slice(contentStart, contentStart + size);
+		offset = contentStart + Math.ceil(size / 512) * 512;
+		if (typeflag === "x" || typeflag === "g" || typeflag === "L") continue;
+		if (typeflag !== "0" && typeflag !== "") throw new Error(`refusing non-file tar entry (${typeflag})`);
+		files.set(archivePathToRelative(prefix === "" ? name : `${prefix}/${name}`), content);
+	}
+	if (files.size === 0) throw new Error("the archive carried no usable files");
+	return files;
+}
+
+/**
+ * Check downloaded bytes against the digest the registry published.
+ *
+ * A mismatch is the one failure that must stop everything: whatever arrived is
+ * not the package the registry described, and not one byte of it is written.
+ */
+export function verifyIntegrity(bytes, integrity) {
+	const expected = Buffer.from(String(integrity).slice("sha512-".length), "base64");
+	const actual = createHash("sha512").update(bytes).digest();
+	if (expected.length === 0 || expected.length !== actual.length || !timingSafeEqual(expected, actual)) {
+		throw new Error("the tarball failed its sha512 check");
+	}
+}
+
+/**
+ * Download the tarball a validated registry answer named.
+ *
+ * The URL was checked when the answer arrived and is checked again here; the
+ * response is capped and time-limited like every other request, and never
+ * redirected.
+ */
+async function downloadTarball(url) {
+	if (!isTrustedTarball(url)) throw new Error("tarball URL is not a trusted registry");
+	log(`update: downloading ${url}`);
+	const response = await fetch(url, {
+		signal: AbortSignal.timeout(60 * 1000),
+		redirect: "error",
+		headers: { accept: "application/octet-stream" },
+	});
+	if (!response.ok) throw new Error(`download failed: HTTP ${response.status}`);
+	return readCappedBytes(response, UPDATE_MAX_TARBALL_BYTES);
+}
+
+/**
+ * Swap the package's files for the update's, keeping the previous ones.
+ *
+ * Each file is written to a temporary name and renamed into place, so a
+ * failure cannot leave a half-written file under a real name. Everything the
+ * update is about to replace is copied aside first, and any failure puts it
+ * all back: a failed update is not a half-updated plugin.
+ */
+export function installUpdate(root, files) {
+	const rootPrefix = resolve(root);
+	const backup = join(root, ".update-backup");
+	rmSync(backup, { recursive: true, force: true });
+	const written = [];
+	try {
+		for (const relative of UPDATE_FILES) {
+			const source = files.get(relative);
+			if (source === undefined) continue;
+			const target = resolve(root, relative);
+			if (target !== rootPrefix && !target.startsWith(rootPrefix)) throw new Error(`refusing to write outside the package: ${relative}`);
+			if (existsSync(target)) {
+				const aside = join(backup, relative);
+				mkdirSync(dirname(aside), { recursive: true });
+				writeFileSync(aside, readFileSync(target));
+			}
+			const temp = `${target}.update-tmp`;
+			writeFileSync(temp, source);
+			renameSync(temp, target);
+			written.push(relative);
+		}
+	} catch (error) {
+		for (const relative of written) {
+			const aside = join(backup, relative);
+			if (existsSync(aside)) writeFileSync(resolve(root, relative), readFileSync(aside));
+		}
+		throw error;
+	}
+}
+
+/**
+ * Replace this installation with the newest published version.
+ *
+ * The stages are deliberate, and each one is a gate for the next: ask a
+ * registry (the answer is validated as strictly as for a check); download the
+ * tarball from the URL that answer named and nowhere else; verify its sha512
+ * against the digest the registry published — a mismatch stops here, before a
+ * byte is written; unpack it in memory, accepting only whitelisted regular
+ * files; then back up what is there and swap the files, restoring on failure.
+ *
+ * Nothing downloaded is ever executed here. The new code runs when DSH
+ * restarts, which is the same trust model as the user updating by hand.
+ *
+ * @param options - `root` overrides the package directory (for tests).
+ * @returns `{ ok: true, from, to, requiresRestart }`, `{ ok: true,
+ *   upToDate: true, current }`, or `{ ok: false, stage, error }`.
+ */
+export async function applyUpdate(options = {}) {
+	const root = options.root ?? packageRoot();
+	const current = readOwnVersion(root);
+	let stage = "check";
+	try {
+		const answer = await fetchRegistryAnswer();
+		if (answer === undefined) return { ok: false, stage, error: "no registry answered" };
+		const ordering = current === undefined ? NaN : compareVersions(current, answer.version);
+		if (Number.isFinite(ordering) && ordering >= 0) return { ok: true, upToDate: true, current };
+		stage = "download";
+		const bytes = await downloadTarball(answer.tarball);
+		stage = "verify";
+		verifyIntegrity(bytes, answer.integrity);
+		stage = "unpack";
+		const files = unpackTar(gunzipSync(bytes));
+		stage = "replace";
+		installUpdate(root, files);
+		log(`update applied: ${current ?? "?"} -> ${answer.version}`);
+		return { ok: true, from: current, to: answer.version, requiresRestart: true };
+	} catch (error) {
+		warn(`update failed at ${stage}: ${error?.message ?? error}`);
+		return { ok: false, stage, error: error?.message ?? String(error) };
+	}
+}
+
+//#endregion
+
 /**
  * Live preferences projected to the browser. Every field is volatile: the
  * Settings document serves them, form edits reach them without restarting
@@ -440,6 +872,8 @@ export const Config = z.object({
 	completionSound: z.union(SOUND_IDS).default("ding").volatile(),
 	/** Also alert about sessions the agent spawned (sub-agents); off = only the user's own conversations. */
 	subagentAlerts: z.boolean().default(false).volatile(),
+	/** Check npm for a new version on its own (at most one real check a day); off = only when the user asks. */
+	updateAutoCheck: z.boolean().default(true).volatile(),
 	/** Play only while the page is not visible (background tab or window). */
 	onlyWhenHidden: z.boolean().default(false).volatile(),
 	/** Uploaded audio for the `custom` preset, as base64; empty when none. */
@@ -517,5 +951,72 @@ export function apply(ctx) {
 				}
 			},
 		}), "notify-sounds: focus route");
+
+		// The update check route: a fixed, read-only question about this
+		// plugin's own npm package. Same fence as the focus route. It takes no
+		// URL, package name or version from the caller — there is nothing here
+		// to aim anywhere else.
+		child.effect(() => child.webServer.register({
+			kind: "exact",
+			path: UPDATE_CHECK_PATH,
+			handler: async (req, res) => {
+				const rejection = child.connection.requestRejection(req);
+				if (rejection !== undefined) {
+					res.statusCode = rejection;
+					res.end();
+					return;
+				}
+				if (req.method !== "GET") {
+					res.statusCode = 405;
+					res.setHeader("allow", "GET");
+					res.end();
+					return;
+				}
+				try {
+					const force = new URL(req.url ?? "/", "http://localhost").searchParams.get("force") === "1";
+					const result = await checkForUpdate({ force });
+					res.statusCode = 200;
+					res.setHeader("content-type", "application/json");
+					res.end(JSON.stringify(result));
+				} catch (error) {
+					warn(`update check failed: ${error?.message ?? error}`);
+					res.statusCode = 502;
+					res.end();
+				}
+			},
+		}), "notify-sounds: update check route");
+
+		// The update apply route: same fence, same fixed target. It accepts no
+		// version and no URL from the caller — the update it performs is always
+		// the one a registry described for this package, verified against that
+		// registry's own digest before anything is written.
+		child.effect(() => child.webServer.register({
+			kind: "exact",
+			path: UPDATE_APPLY_PATH,
+			handler: async (req, res) => {
+				const rejection = child.connection.requestRejection(req);
+				if (rejection !== undefined) {
+					res.statusCode = rejection;
+					res.end();
+					return;
+				}
+				if (req.method !== "POST") {
+					res.statusCode = 405;
+					res.setHeader("allow", "POST");
+					res.end();
+					return;
+				}
+				try {
+					const result = await applyUpdate();
+					res.statusCode = 200;
+					res.setHeader("content-type", "application/json");
+					res.end(JSON.stringify(result));
+				} catch (error) {
+					warn(`update apply failed: ${error?.message ?? error}`);
+					res.statusCode = 500;
+					res.end();
+				}
+			},
+		}), "notify-sounds: update apply route");
 	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-notify-sounds",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "description": "Notification sounds for DeepSeek Harness — a soft chime when the agent needs your decision or finishes a task, with a Settings section styled like DSH's own · 需要决策或任务完成时播放提示音，点击系统通知可回到窗口，设置面板可调音量与音效",
   "type": "module",
   "main": "lib/index.js",
@@ -18,7 +18,8 @@
     "lib/index.js",
     "lib/client.js",
     "cordis.patch.yml",
-    "README.zh.md"
+    "README.zh.md",
+    "assets"
   ],
   "license": "MIT",
   "repository": {