dsh-tokenlens 1.2.2 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 本项目遵循 [Semantic Versioning](https://semver.org/)：修复 = PATCH，新功能 = MINOR，不兼容变更 = MAJOR。发布时同步更新 `package.json` 的 `version`、`index.js` 的 `PLUGIN_VERSION` 与本文件（`node scripts/bump-version.mjs <version> "<note>"`）；已发布的条目保持原样。
 
+## 1.3.0 — 2026-11-01
+
+- feat(update): 可选的**启动时检查更新**（默认关闭）：开启后仅向 npm registry 查询一次 `dsh-tokenlens` 的 latest 版本号，不携带凭据/账号/用量信息；主机离线或接口失败时记录错误并说明，不阻塞启动
+- feat(update): 供应商管理页「插件设置」新增「更新检查」块——开关、隐私提示、状态行（尚未检查 / 正在检查 / 已是最新 / 发现新版本 / 检查失败可重试）与「立即检查」；详情弹窗底部在发现新版本时显示一行「发现新版本 vX · 打开 npm」（链接到 npm 包页）
+- feat(wire): `hello` 与 `providers` 载荷新增 `update`（`UpdateInfo`）与 `updatePackageUrl`；`settingsUpdate` 新增 `settings.updateCheck`；新增 bridge action `updateCheck`（Agent 工具同步支持）
+- fix(update): 并发检查单飞（共享同一次在途请求）；仅在开关从关→开时触发检查，已开启时保存其它显示设置不会重复请求 npm
+- 测试：277 个自动化用例（新增 Host 版本比较/检查/设置/并发与客户端 UI 回归）
+
 ## 1.2.2 — 2026-11-01
 
 - fix(workspaces): 修复「工作区悬浮卡片不显示 Token 明细」——Host 在裁剪本地路径时把 `path` 字段误删成空串，客户端只剩标题精确匹配；默认工作区等「界面标题 ≠ 统计标签」的场景因此匹配不到统计（影响 v1.2.1 及更早版本）

package/PROTOCOL.md

@@ -32,12 +32,16 @@ from `dsh-app://app/` and forwards non-asset paths to the Host).
 
 ```jsonc
 {
-  "action": "snapshot" | "refresh" | "hello" | "stats" | "diagnostics",
+  "action": "snapshot" | "refresh" | "hello" | "stats" | "diagnostics" |
+            "providers" | "providerUpdate" | "providerTest" | "settingsUpdate" |
+            "customProviderSave" | "customProviderDelete" | "updateCheck",
   "providerId": "opencode-go",   // optional; defaults to the active provider
   "fresh": false,                 // stats only: bypass the scan TTL
   "origin": "dsh-app://app",      // hello only, optional
   "primitives": 290,              // hello only, optional (seeded primitives count)
-  "locale": "zh-CN"               // hello only, optional
+  "locale": "zh-CN",              // hello only, optional
+  "settings": { /* settingsUpdate only */ },
+  "update": { /* providerUpdate only */ }
 }
 ```
 
@@ -47,6 +51,9 @@ from `dsh-app://app/` and forwards non-asset paths to the Host).
   answers with a snapshot so the first paint needs one round trip.
 - `stats` — today/all-time token statistics folded from the local session logs.
 - `diagnostics` — config/cache/error state (verification aid, no secrets).
+- `updateCheck` — v1.3.0: run the optional npm-registry update check right now and
+  answer `{ ok: true, update: <UpdateInfo> }`. It is also run once at activation
+  when `settings.updateCheck` is enabled; disabled by default.
 - Unknown action → HTTP 400 `{ "ok": false, "error": { "code": "unknown-action", … } }`.
 
 ### Response envelope
@@ -54,10 +61,11 @@ from `dsh-app://app/` and forwards non-asset paths to the Host).
 ```jsonc
 { "ok": true,  "snapshot": <Snapshot> }            // snapshot / refresh / hello
 { "ok": true,  "stats": <Stats> }                  // stats
+{ "ok": true,  "update": <UpdateInfo> }            // updateCheck
 { "ok": false, "error": <Error>, "snapshot": <Snapshot|null> }
 ```
 
-`hello` answers `{ ok: true, plugin, version, bridge, pid, …snapshotResult }`.
+`hello` answers `{ ok: true, plugin, version, bridge, pid, update: <UpdateInfo|null>, …snapshotResult }`.
 
 ## Snapshot (wire shape, v3)
 
@@ -319,7 +327,7 @@ needs no provider catalog of its own.
 
 The dialog 「供应商管理」 page talks to three additional actions:
 
-- `{action:"providers"}` → `{ok:true, providers:[{providerId,label,shortLabel,kind,enabled,hasKey,keySource,apiKeyRef,baseURL,consoleUrl,builtin,dshManaged,dshProviderId}], dshProviders:[{providerId,label,supported,usageProviderId}], settings:{labelStyle,defaultView,defaultScope,detailsExpanded,detailsWindow}, storeFile, storeFileDisplay}`. `storeFile` is the real path (local tooling); `storeFileDisplay` replaces the user's home directory with `~` and is what the management page renders.
+- `{action:"providers"}` → `{ok:true, providers:[{providerId,label,shortLabel,kind,enabled,hasKey,keySource,apiKeyRef,baseURL,consoleUrl,builtin,dshManaged,dshProviderId}], dshProviders:[{providerId,label,supported,usageProviderId}], settings:{labelStyle,defaultView,defaultScope,detailsExpanded,detailsWindow,updateCheck}, update:<UpdateInfo|null>, updatePackageUrl, storeFile, storeFileDisplay}`. `storeFile` is the real path (local tooling); `storeFileDisplay` replaces the user's home directory with `~` and is what the management page renders. `update` (v1.3.0) is the last optional update-check result and `updatePackageUrl` the npm page the management UI links to.
 - `{action:"providerUpdate", providerId, update:{enabled?,apiKey?,apiKeyRef?,baseURL?,consoleUrl?,label?,shortLabel?}}` → same list payload;
   empty strings clear a stored value (falling back to the profile/default). `label` (全名, ≤40 chars) and
   `shortLabel` (短标签, ≤12 chars) let the management page rename a provider. The shipped management page no
@@ -327,7 +335,32 @@ The dialog 「供应商管理」 page talks to three additional actions:
   saves enabled/consoleUrl/label/shortLabel. Overrides are persisted atomically to
   `$DSH_HOME/dsh-tokenlens/providers.json` (plugin-owned, not the profile patch); the same file also
 - `{action:"providerTest", providerId}` → the normal snapshot envelope (`{ok,snapshot}` or `{ok:false,error}`), forcing one upstream read.
-- `{action:"settingsUpdate", settings:{labelStyle?:"short"|"full", defaultView?:"chart"|"data", defaultScope?:"provider"|"all", detailsExpanded?:"auto"|"expanded"|"collapsed", detailsWindow?:"today"|"last7Days"|"second"|"total"}}` → the same providers payload; every field is optional and persisted in the store (`settings.*`). `labelStyle` controls whether the composer chip shows each provider's `shortLabel` or full `label`; `defaultView` / `defaultScope` / `detailsExpanded` are the usage-dialog defaults; `detailsWindow` (v1.2.1) is the remembered 明细 donut window (falls back visually to `total` when that window is unavailable on the current provider/host). Invalid values answer `unsupported-provider`.
+- `{action:"settingsUpdate", settings:{labelStyle?:"short"|"full", defaultView?:"chart"|"data", defaultScope?:"provider"|"all", detailsExpanded?:"auto"|"expanded"|"collapsed", detailsWindow?:"today"|"last7Days"|"second"|"total", updateCheck?:boolean}}` → the same providers payload; every field is optional and persisted in the store (`settings.*`). `labelStyle` controls whether the composer chip shows each provider's `shortLabel` or full `label`; `defaultView` / `defaultScope` / `detailsExpanded` are the usage-dialog defaults; `detailsWindow` (v1.2.1) is the remembered 明细 donut window (falls back visually to `total` when that window is unavailable on the current provider/host); `updateCheck` (v1.3.0, default `false`) enables the optional startup update check — enabling it runs one check immediately. Invalid values answer `unsupported-provider`.
+
+### Optional update check (v1.3.0)
+
+Off by default: the plugin stays local-only unless the user enables
+`settings.updateCheck`. When enabled, one HTTPS `GET` to the fixed endpoint
+`https://registry.npmjs.org/dsh-tokenlens/latest` runs at activation, on the
+off→on transition of the setting, and on the `updateCheck` action. Concurrent
+checks are single-flight (one registry request shared by every caller). Nothing
+but the request itself leaves the machine — no credentials, identifiers or
+usage data.
+
+```jsonc
+// UpdateInfo (host → client)
+{
+  "current": "1.3.0",
+  "latest": "1.3.1" | null,      // null when the answer was unusable/failed
+  "available": true,             // strictly newer published version, error === null
+  "checkedAt": "2026-11-02T00:00:00.000Z",
+  "error": null | { "code": "network"|"timeout"|"http"|"parse", "message": "…", "retryable": true }
+}
+```
+
+A failed check never throws and never blocks activation; the client explains the
+error instead of inventing a version. The result lives in memory only and is
+surfaced through `hello`, `providers` and `diagnostics`.
 
 `dshProviders` lists every route registered in DSH model settings (in order) with a `supported` flag (whether a usage adapter exists); the shipped management page renders those routes as the primary list and keeps unconfigured preset adapters in a collapsed secondary section. `dshManaged`/`dshProviderId` tell the management page that the route already exists in DSH model settings
 (opencode-go / commandcode / deepseek), so the page can inherit the key and base URL instead of asking for them
@@ -438,6 +471,11 @@ configure the `opencode-go` provider.
    - **chart mode**: the daily bar chart, a click on a day bar drills into that
      day's 24 local-hour bars (when the Host delivers `daily[].hours`), and the
      明细 donuts switch between 今日 / 最近7天 / 最近X天 / 总计;
-   - refresh (usage + stats), last-updated/stale line, error banners, console link.
-3. Everything client-side must work with only the shell's seeded modules
+   - refresh (usage + stats), last-updated/stale line, error banners, console link;
+   - when `update.available` is true (v1.3.0) the footer shows one muted line
+     「发现新版本 vX · 打开 npm」 linking to `updatePackageUrl`.
+3. **Provider management page** (same modal, 管理 tab) — when the optional update
+   check is enabled the 插件设置 tab shows its toggle, the last result (up to date /
+   new version / failed) and a 「立即检查」 action that sends `updateCheck`.
+4. Everything client-side must work with only the shell's seeded modules
    (`react`, `react-dom`, `@deepseek-ai/dsh-client-ui-primitives`) — no build step.

package/README.en.md

@@ -9,7 +9,7 @@
 
 > One glance at your usage: plan capacity for the selected provider plus local token statistics across harnesses, right below the DSH composer.
 
-**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.2.2. It keeps two kinds of numbers separate:
+**dsh-TokenLens** is a usage plugin for DSH (DeepSeek Harness), version v1.3.0. It keeps two kinds of numbers separate:
 
 - **Plan capacity** — the provider's authoritative server-side values (percentage windows, used / cap, balance or remaining credit);
 - **Local token stats** — tokens consumed on this machine across every connected harness, for the selected provider or for all providers combined.
@@ -21,7 +21,7 @@ Everything is computed locally: zero runtime dependencies, no external database,
 - **Usage chip below the composer** — follows the selected model provider and shows its plan capacity; providers without an adapter or credentials stay hidden.
 - **Details dialog** — plan capacity windows with reset times (plus an optional "consumed · estimated consumable" hint) and local token stats for today / last 7 days / last 30 days / all-time, scoped to the current provider or all harnesses.
 - **Data and chart modes** — tables, a daily trend chart and ring charts with breakdowns by harness, provider, top model and unmapped providers. In chart mode, clicking a day's bar drills into that day's 24 hourly bars; the 明细 rings switch between today / last 7 days / last X days (or last 30 days) / all time.
-- **Provider management page** — enabled / built-in / all filters, enable switches, credential status, console links, label editing, connection tests, subscription badges and plugin settings (label style, default view/scope, details expansion, default 明细 donut window).
+- **Provider management page** — enabled / built-in / all filters, enable switches, credential status, console links, label editing, connection tests, subscription badges and plugin settings (label style, default view/scope, details expansion, default 明细 donut window, optional startup update check with a "check now" action).
 - **Auto-discovery and agent tool** — providers configured in DSH Settings → Model Services are detected by route id or base-URL host and reuse their DSH credentials; `tokenlens_usage` lets the model query snapshots, local stats and diagnostics.
 - **Local-only** — 5 harnesses (DSH, ZCode, OpenCode CLI, WorkBuddy / CodeBuddy CLI, Qoder CN CLI), 25 built-in providers (16 with plan / balance adapters), read-only local data, no telemetry.
 
@@ -66,7 +66,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 Then make sure `dsh.profile.bundles` in `$DSH_HOME/profiles/<profile>/package.json` contains `"dsh-tokenlens"`:
 
 ```jsonc
-{ "dependencies": { "dsh-tokenlens": "^1.2.2" },
+{ "dependencies": { "dsh-tokenlens": "^1.3.0" },
   "dsh": { "profile": { "bundles": ["…", "dsh-tokenlens"] } } }
 ```
 
@@ -123,7 +123,7 @@ Host bridge route: `/api/tokenlens`; agent tool: `tokenlens_usage`.
 
 - **Read-only**: only local session logs and harness databases are read; SQLite is opened read-only and only token counters, timestamps and provider / model fields are queried — never message contents.
 - **Keys stay local**: API keys are resolved in the Host process from DSH credentials, environment variables or the DSH credentials file, and are sent only to the matching provider's official HTTPS endpoint. They are never exposed to the browser, logged or included in diagnostics.
-- **No telemetry**: nothing is collected, uploaded, or fetched from remote config / CDN sources (icons are inline SVG).
+- **No telemetry**: nothing is collected, uploaded, or fetched from remote config / CDN sources (icons are inline SVG). The only optional outbound request is the startup update check (v1.3.0, off by default): when enabled it asks the npm registry once for the published version number, without credentials, identifiers or usage data.
 - **Owner-only data**: management overrides are written atomically to `$DSH_HOME/dsh-tokenlens/providers.json` with owner-only permissions; DSH model settings are never modified.
 
 ## Limitations
@@ -131,12 +131,13 @@ Host bridge route: `/api/tokenlens`; agent tool: `tokenlens_usage`.
 - Provider usage endpoints are mostly private / undocumented and may change at any time; the plugin degrades gracefully (retryable errors, hidden chips, per-row fallbacks) but availability is not guaranteed.
 - Plan capacity shows native server values only: no token → money conversion; Command Code monthly percentage is not guessed when no grant is reported.
 - "Estimated consumable" is derived from local tokens and the plan percentage; it is only a hint, not a provider commitment.
+- The startup update check compares the **latest npm release** only (off by default); commits on the GitHub repository are not detected — a git-installed plugin must be uninstalled and reinstalled to update.
 - Local stats cover connected harnesses on this machine only; uninstalled harnesses are hidden by default (`stats.showUninstalled: true` shows them). Workspace token badges are experimental.
 - **Trademarks**: OpenCode, Command Code, DeepSeek, ZCode, WorkBuddy, CodeBuddy, Qoder and other names are trademarks of their respective owners. This is an independent third-party project, not affiliated with or endorsed by them.
 
 ## Development
 
-Node.js ≥ 24, zero runtime dependencies: `node --test` runs the 256 tests.
+Node.js ≥ 24, zero runtime dependencies: `node --test` runs the 277 tests.
 
 Release: `node scripts/bump-version.mjs <version> "<note>"` updates `package.json`, `PLUGIN_VERSION` and `CHANGELOG.md`; see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
 

package/README.md

@@ -9,7 +9,7 @@
 
 > **一眼看清你的用量**：在 DSH 输入框下方显示当前供应商的套餐容量，并汇总本机跨 Harness 的 Token 消耗。
 
-**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.2.2，公开版本）。它把两类数字**按不同口径**分开呈现：
+**dsh-TokenLens（词元透镜）** 是 DSH（DeepSeek Harness）的用量插件（v1.3.0，公开版本）。它把两类数字**按不同口径**分开呈现：
 
 - **套餐容量**（供应商服务端权威值）：百分比窗口、`已用 / 上限`、账户余额或剩余额度；
 - **本机 Token 统计**（本机记录）：当前供应商在本机所有已接入 Harness 上的合计用量，也可切到「全部 Harness」看总账。
@@ -41,7 +41,7 @@
   - **本机 Token 统计**：今日 / 最近 7 天 / 最近 30 天 / 总计（订阅类供应商显示「最近 X 天」生效窗口），可按「当前供应商 · 全部 Harness」与「全部 Harness」两个视角查看。
   - **明细与图表**：按 Harness、按供应商、Top 模型、未映射供应商分组；支持「数据」（表格）与「图表」两种模式切换。图表模式里点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗，底部「明细」环形图支持 **今日 / 最近 7 天 / 最近 X 天（或最近 30 天）/ 总计** 窗口切换。
   - **工作区徽标**（实验性）：左侧工作区列表的名称旁显示该工作区的本机 Token 合计，悬浮卡片显示今日 / 7 天 / 30 天 / 总计；纯展示，找不到对应 UI 时自动降级。
-- **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围、明细展开状态与图表「明细」环形图的默认窗口（今日 / 最近 7 天 / 最近 X 天 / 总计，记住上次选择）。
+- **供应商管理页**：「已配置 / 内置 / 全部」筛选、启用开关、凭据状态、控制台链接、短标签与全名编辑、测试连接、已订阅徽章；另有「插件设置」可配置标签样式、默认展示模式、默认统计范围、明细展开状态、图表「明细」环形图的默认窗口（今日 / 最近 7 天 / 最近 X 天 / 总计，记住上次选择）与「启动时检查更新」（默认关闭，可手动立即检查）。
 - **自动识别**：在 DSH「设置 → 模型服务」中配置过的供应商会自动出现在管理页，并按路由 id 或 baseURL 主机匹配内置用量适配器，自动继承 DSH 中的凭据，无需重复填写。
 - **Agent 工具**：注册 `tokenlens_usage`，模型可以自行查询套餐容量与本机用量。
 
@@ -106,7 +106,7 @@ dsh plugin --profile <profile> add dsh-tokenlens
 ```jsonc
 {
   "dependencies": {
-    "dsh-tokenlens": "^1.2.2"
+    "dsh-tokenlens": "^1.3.0"
   },
   "dsh": {
     "profile": {
@@ -371,7 +371,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 - **只读**：插件只读取本机会话日志与各 harness 的本地数据库 / JSONL；SQLite 一律以只读方式打开，只取 token 计数、时间、provider / model 等字段，不读取对话正文。
 - **凭据不出本机**：API Key 只在 Host 进程内从 DSH 凭据服务 / 环境变量 / `.credentials.yaml` / OpenCode CLI 登录文件解析，只发往对应供应商的官方 HTTPS 接口；不下发浏览器、不写日志、不进诊断输出。
-- **无遥测**：插件不收集、不上传任何使用数据，不请求远程配置或 CDN 资源（图标均为内联 SVG）。
+- **无遥测**：插件不收集、不上传任何使用数据，不请求远程配置或 CDN 资源（图标均为内联 SVG）。唯一的可选外网请求是「启动时检查更新」（v1.3.0，默认关闭）：开启后仅向 npm registry 查询一次最新版本号，不携带任何账号、凭据或用量信息。
 - **覆盖文件仅本人可读**：供应商管理页的覆盖写入 `$DSH_HOME/dsh-tokenlens/providers.json`（原子写入，权限仅当前用户），不会改动 DSH 模型设置或 profile patch。
 - **可控降级**：上游接口不可用时只影响对应 chip / 行，不影响 DSH 本身；`enabled: false` 可整体停用插件。
 
@@ -380,6 +380,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 - 各供应商的用量接口多为**未公开的私有接口**，可能随时变更；插件对此做了优雅降级（可重试错误、静默隐藏、行级降级），但不保证长期可用。
 - 套餐容量只显示服务端原生数字：不做 token → 金额换算；Command Code 未报告 grant 时不计算月度百分比。
 - 「预计可消耗」是基于本机 Token 与套餐百分比的**估算**，仅供参考，不代表供应商承诺的额度。
+- 「启动时检查更新」只对比 **npm 上的最新发布版本**（默认关闭）；GitHub 仓库的提交更新不会被感知，需要卸载重装 git 安装的版本才会更新。
 - 本机 Token 统计只覆盖**已接入 harness**（当前 DSH / ZCode / OpenCode CLI / WorkBuddy / Qoder CN），只统计本机的本地记录。
 - Harness 卸载后其数据目录消失即判定为未安装，默认从弹窗隐藏（可用 `stats.showUninstalled: true` 显示「未安装」行）；数据目录仍在磁盘时按历史记录继续计入。
 - ZCode 数据库通常很大且持续写入：插件只做聚合查询并缓存结果，数据库被锁时会短暂显示不可用。
@@ -391,7 +392,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 
 ## 验证
 
-- `node --test`：**256 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
+- `node --test`：**277 个自动化用例**，覆盖 Host 数据层、供应商适配器、统计折叠、各 harness 读取、插件集成与浏览器端渲染 / 交互。
 - 在真实环境中验证过 **5 个 harness** 的数据源；本机统计与独立的 SQLite 查询、独立的日志解析逐项对账（差额为 0），跨 harness 合并与供应商映射算术自洽。
 - 供应商接口按各官方文档与参考客户端行为验证；未配置凭据时 chip 静默隐藏，接口异常时按可重试错误降级。
 
@@ -402,7 +403,7 @@ Host 半注册 `tokenlens_usage`，参数 `action`（默认 `snapshot`）与可
 ```powershell
 git clone https://github.com/daigahou/dsh-tokenlens.git
 cd dsh-tokenlens
-node --test        # 256 个用例
+node --test        # 277 个用例
 ```
 
 本地联调安装方式见[方式 C](#方式-c本地开发从源码-link)。

package/client.js

@@ -68,6 +68,14 @@ window.__ModuleLoader__.load({
     const MANAGEMENT_SYNC_MS = 15000
     /** Retry delay of a 明细-window save blocked by an in-flight settings request (v1.2.1). */
     const DETAILS_WINDOW_SAVE_RETRY_MS = 200
+    /**
+     * Delays of the network-free providers re-reads while 「启动时检查更新」 is on
+     * and no result exists yet: the Host's own startup / toggle check runs in
+     * the background, so hello or a settings answer can win the race. Two
+     * attempts cover a normal registry round-trip without ever asking the
+     * registry twice; the management page's silent check covers the rest.
+     */
+    const UPDATE_RESULT_REFRESH_MS = [1200, 4000]
     /** How many per-provider / per-model stats rows the dialog lists. */
     const MAX_PROVIDER_ROWS = 5
     const MAX_MODEL_ROWS = 3
@@ -137,7 +145,12 @@ window.__ModuleLoader__.load({
       defaultScope: 'provider',
       detailsExpanded: 'auto',
       detailsWindow: 'total',
+      // 「启动时检查更新」 is persisted too; off by default so an old Host and a
+      // fresh install never contact the npm registry (privacy first).
+      updateCheck: false,
     }
+    /** The npm package page the 「打开 npm」 update links point at. */
+    const NPM_PACKAGE_URL = 'https://www.npmjs.com/package/dsh-tokenlens'
 
     const zh = {
       title: '词元透镜（dsh-TokenLens）',
@@ -340,6 +353,18 @@ window.__ModuleLoader__.load({
       settingsDetailsCollapsed: '收起',
       settingsResetDefaults: '恢复默认设置',
       settingsResetDefaultsHint: '恢复为插件默认的显示设置',
+      updateCheckLabel: '启动时检查更新',
+      updateCheckHint: '仅当开启时才访问 npm registry 检查新版本；默认关闭',
+      updateCheckOff: '关闭',
+      updateCheckOn: '开启',
+      updateChecking: '正在检查…',
+      updateLatest: '已是最新版本 v{version}',
+      updateAvailable: '发现新版本 v{latest}（当前 v{current}）',
+      updateCheckFailed: '检查失败',
+      updateCheckNow: '立即检查',
+      updateCheckNever: '尚未检查',
+      updateOpenNpm: '打开 npm',
+      updateDialogLine: '发现新版本 v{latest} · 打开 npm',
       providerBothLabels: '短标签：{short} · 全名：{full}',
       providerShortLabel: '短标签',
       providerShortLabelHint: '1–12 字符',
@@ -568,6 +593,18 @@ window.__ModuleLoader__.load({
       settingsDetailsCollapsed: 'Collapsed',
       settingsResetDefaults: 'Restore defaults',
       settingsResetDefaultsHint: 'Restore the plugin default display settings',
+      updateCheckLabel: 'Check for updates at startup',
+      updateCheckHint: 'Contacts the npm registry for a new version only when enabled; off by default',
+      updateCheckOff: 'Off',
+      updateCheckOn: 'On',
+      updateChecking: 'Checking…',
+      updateLatest: 'Up to date: v{version}',
+      updateAvailable: 'New version v{latest} available (current v{current})',
+      updateCheckFailed: 'Update check failed',
+      updateCheckNow: 'Check now',
+      updateCheckNever: 'Not checked yet',
+      updateOpenNpm: 'Open on npm',
+      updateDialogLine: 'New version v{latest} · Open on npm',
       providerBothLabels: 'Short label: {short} · Full name: {full}',
       providerShortLabel: 'Short label',
       providerShortLabelHint: '1–12 characters',
@@ -1111,9 +1148,9 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * The five display settings of the `providers` payload (v0.29.0; the 明细
-     * donut window joined them in v1.2.1), every field normalized to a usable
-     * value so old Hosts keep the previous defaults.
+     * The five display settings plus 「启动时检查更新」 of the `providers`
+     * payload, every field normalized to a usable value so old Hosts keep the
+     * previous defaults.
      */
     function normalizePluginSettings(raw) {
       const source = raw !== null && typeof raw === 'object' && !Array.isArray(raw) ? raw : {}
@@ -1123,9 +1160,50 @@ window.__ModuleLoader__.load({
         defaultScope: normalizeDisplayScope(source.defaultScope),
         detailsExpanded: normalizeDetailsExpanded(source.detailsExpanded),
         detailsWindow: normalizeDetailsWindow(source.detailsWindow),
+        // The startup update check is opt-in: a value other than `true` (an old
+        // Host omits the field entirely) means off.
+        updateCheck: source.updateCheck === true,
+      }
+    }
+
+    /**
+     * The optional `update` object of the hello / providers envelope: the last
+     * known update check result, or null when the Host never checked.
+     *
+     * Defensive by design — the update UI must never throw on hostile wire
+     * data. String fields collapse to `''`/null, `available` is only claimed
+     * when it is literally `true` *and* names a version, and a wire error keeps
+     * the shared normalized error shape.
+     */
+    function normalizeUpdate(raw) {
+      if (raw === null || raw === undefined || typeof raw !== 'object' || Array.isArray(raw)) return null
+      const current = stringOrEmpty(raw.current).trim()
+      const latestText = stringOrEmpty(raw.latest).trim()
+      const latest = latestText === '' ? null : latestText
+      return {
+        current,
+        latest,
+        available: raw.available === true && latest !== null,
+        checkedAt: stringOrEmpty(raw.checkedAt).trim(),
+        error: raw.error === null || raw.error === undefined ? null : normalizeError(raw.error),
       }
     }
 
+    /** Whether two normalized update infos are render-identical (avoids store churn). */
+    function sameUpdate(a, b) {
+      if (a === b) return true
+      if (a === null || b === null || typeof a !== 'object' || typeof b !== 'object') return false
+      if (a.current !== b.current || a.latest !== b.latest || a.available !== b.available || a.checkedAt !== b.checkedAt) {
+        return false
+      }
+      if (a.error === null || b.error === null) return a.error === b.error
+      return (
+        a.error.code === b.error.code &&
+        a.error.message === b.error.message &&
+        a.error.retryable === b.error.retryable
+      )
+    }
+
     /**
      * One route discovered in the DSH model settings (v0.15.0), or null when it
      * has no usable id. `supported` plus a `usageProviderId` means the plugin has
@@ -1184,6 +1262,10 @@ window.__ModuleLoader__.load({
         ? raw.dshProviders.map((entry) => normalizeDshProviderEntry(entry)).filter((entry) => entry !== null)
         : []
       const settings = raw.settings !== null && typeof raw.settings === 'object' ? raw.settings : {}
+      // The update check result travels with every providers payload; `hasUpdate`
+      // distinguishes "the Host said null" from "an old Host omitted the field",
+      // so a hello-provided result is never wiped by a payload without it.
+      const hasUpdate = Object.prototype.hasOwnProperty.call(raw, 'update')
       return {
         // v0.17.0 identity: dedupe by providerId, last-wins, so the filter tabs
         // never list the same provider twice even if the Host sends a duplicate.
@@ -1196,6 +1278,10 @@ window.__ModuleLoader__.load({
         storeFile: stringOrEmpty(raw.storeFile).trim(),
         storeFileDisplay: stringOrEmpty(raw.storeFileDisplay).trim(),
         settings: normalizePluginSettings(settings),
+        update: hasUpdate ? normalizeUpdate(raw.update) : null,
+        hasUpdate,
+        // Optional: the Host may advertise the npm page its links should open.
+        updatePackageUrl: stringOrEmpty(raw.updatePackageUrl).trim(),
         labelCatalog,
       }
     }
@@ -1773,6 +1859,16 @@ window.__ModuleLoader__.load({
         labelCatalog: {},
         // Plugin version from the hello envelope (dialog footnote).
         pluginVersion: '',
+        // 「启动时检查更新」 (persisted setting) and the last check result the
+        // hello / providers envelope reported, plus the in-flight flag of an
+        // explicit 「立即检查」. The flag is deliberately independent from
+        // `management.settingsBusy`: a check never blocks a settings save.
+        updateCheck: DEFAULT_PLUGIN_SETTINGS.updateCheck,
+        update: null,
+        updateChecking: false,
+        // The canonical npm page the update links open; the Host may advertise
+        // its own (newer bundles may move the package), this is the fallback.
+        updatePackageUrl: NPM_PACKAGE_URL,
         // Extra DSH-only detail blocks (provider split / top models). Collapsed by
         // default on short screens so the dialog fits without a scrollbar.
         showDetails:
@@ -1808,8 +1904,8 @@ window.__ModuleLoader__.load({
     let usageEpoch = 0
 
     /**
-     * The five display settings currently in effect (v0.29.0; the 明细 donut
-     * window joined them in v1.2.1).
+     * The display settings currently in effect: the five v0.29.0 defaults (the
+     * v1.2.1 明细 donut window included) plus 「启动时检查更新」.
      */
     function currentPluginSettings() {
       const state = store.get()
@@ -1819,6 +1915,7 @@ window.__ModuleLoader__.load({
         defaultScope: normalizeDisplayScope(state.defaultScope),
         detailsExpanded: normalizeDetailsExpanded(state.detailsExpanded),
         detailsWindow: normalizeDetailsWindow(state.detailsWindow),
+        updateCheck: state.updateCheck === true,
       }
     }
 
@@ -2065,6 +2162,18 @@ window.__ModuleLoader__.load({
       if (options.adoptDetailsWindow === true && current.detailsWindow !== settings.detailsWindow) {
         patch.detailsWindow = settings.detailsWindow
       }
+      // 「启动时检查更新」 is adopted on every answer (it is the persisted value
+      // echoing back); the answered checkbox state must win after a toggle.
+      if (current.updateCheck !== settings.updateCheck) patch.updateCheck = settings.updateCheck
+      // A payload that carries `update` (even as null) is authoritative for the
+      // last check result; one that omits it (old Host) keeps what hello said.
+      if (parsed.hasUpdate === true && !sameUpdate(current.update, parsed.update)) {
+        patch.update = parsed.update
+      }
+      // The Host-advertised npm page travels with the same payload.
+      if (parsed.updatePackageUrl !== '' && current.updatePackageUrl !== parsed.updatePackageUrl) {
+        patch.updatePackageUrl = parsed.updatePackageUrl
+      }
       if (parsed.labelCatalog !== null && typeof parsed.labelCatalog === 'object') {
         const catalog = { ...current.labelCatalog, ...parsed.labelCatalog }
         if (Object.keys(catalog).length > 0) patch.labelCatalog = catalog
@@ -2123,6 +2232,9 @@ window.__ModuleLoader__.load({
             storeFileDisplay: parsed !== null ? parsed.storeFileDisplay : '',
             loadedAt: Date.now(),
           })
+          // 「启动时检查更新」: the first management-page load runs one silent
+          // check when the setting is on and no result is known yet.
+          maybeAutoUpdateCheck()
           return { kind: 'ok' }
         }
         patchManagement({ inFlight: false, phase: 'error', error: normalizeError(data.error) })
@@ -2273,6 +2385,10 @@ window.__ModuleLoader__.load({
                 }
               : {}),
           })
+          // Turning 「启动时检查更新」 on makes the Host run one check right away;
+          // its answer may still be in flight, so read the local result shortly
+          // after (no extra registry request).
+          if (store.get().updateCheck === true && store.get().update === null) scheduleUpdateResultRefresh()
           return { kind: 'ok' }
         }
         patchManagement({ settingsBusy: false, settingsError: normalizeError(data.error) })
@@ -2331,6 +2447,128 @@ window.__ModuleLoader__.load({
       void requestSettingsUpdate({ ...DEFAULT_PLUGIN_SETTINGS })
     }
 
+    /** Guards the one silent check the management page may start after opening. */
+    let autoUpdateCheckStarted = false
+    /** Whether the settings error banner currently shows an update-check failure. */
+    let updateCheckErrorShown = false
+    /** One delayed retry when the Host says "a check is already running". */
+    const UPDATE_CHECK_RETRY_MS = 1200
+    let updateCheckRetryTimer = null
+
+    /**
+     * Run one update check (「立即检查」, and the management page's one silent
+     * startup check when 「启动时检查更新」 is on).
+     *
+     * `updateChecking` is an independent flag, never `settingsBusy`: a check may
+     * not block a settings save (and vice versa). A Host-level failure travels
+     * inside `update.error` (the status row renders 检查失败); a transport or
+     * envelope failure uses the management page's existing error banner. Never
+     * throws.
+     */
+    async function requestUpdateCheck(options = {}) {
+      const retried = options.retried === true
+      if (store.get().updateChecking === true) return { kind: 'busy' }
+      store.set({ updateChecking: true })
+      let data
+      try {
+        data = await call({ action: 'updateCheck' })
+      } catch (error) {
+        store.set({ updateChecking: false })
+        updateCheckErrorShown = true
+        patchManagement({ settingsError: managementErrorOf(error) })
+        return { kind: 'transport' }
+      }
+      if (data !== null && typeof data === 'object' && typeof data.ok === 'boolean') {
+        if (data.ok === true) {
+          const update = normalizeUpdate(data.update)
+          if (update !== null) {
+            store.set({ updateChecking: false, update })
+            // A successful retry retires the banner of the failed one instead of
+            // leaving a stale check failure above a fresh result.
+            if (updateCheckErrorShown === true) {
+              updateCheckErrorShown = false
+              patchManagement({ settingsError: null })
+            }
+            return { kind: 'ok' }
+          }
+          // A first-ever check that is already in flight comes back as
+          // `{ok:true, update:null}` (the Host's single-flight returns the last
+          // result). Retry once after a short delay instead of reporting a bad
+          // response; a result that arrived meanwhile (management sync) retires
+          // the retry.
+          if (!retried) {
+            if (updateCheckRetryTimer !== null) window.clearTimeout(updateCheckRetryTimer)
+            updateCheckRetryTimer = window.setTimeout(() => {
+              updateCheckRetryTimer = null
+              store.set({ updateChecking: false })
+              if (store.get().update !== null) return
+              void requestUpdateCheck({ retried: true })
+            }, UPDATE_CHECK_RETRY_MS)
+            return { kind: 'pending' }
+          }
+          store.set({ updateChecking: false })
+          return { kind: 'pending' }
+        }
+        store.set({ updateChecking: false })
+        updateCheckErrorShown = true
+        patchManagement({ settingsError: normalizeError(data.error) })
+        return { kind: 'envelope' }
+      }
+      store.set({ updateChecking: false })
+      updateCheckErrorShown = true
+      patchManagement({
+        settingsError: { code: 'internal', message: 'unexpected updateCheck response', retryable: true },
+      })
+      return { kind: 'transport' }
+    }
+
+    /**
+     * The management page's ONE silent check: only while the setting is on and
+     * no result is known yet. The module-level flag makes a re-open, a tab
+     * switch or a provider-list refresh impossible to turn into a second check.
+     */
+    function maybeAutoUpdateCheck() {
+      if (autoUpdateCheckStarted === true) return
+      const state = store.get()
+      if (state.updateCheck !== true || state.update !== null) return
+      autoUpdateCheckStarted = true
+      void requestUpdateCheck()
+    }
+
+    /** The pending network-free providers re-read (see UPDATE_RESULT_REFRESH_MS). */
+    let updateResultRefreshTimer = null
+    let updateResultRefreshAttempt = 0
+
+    /**
+     * Read the local providers payload once more after the Host's background
+     * update check had time to finish (`updateCheck` on, no result known yet).
+     *
+     * This never asks the npm registry itself — it only re-reads the Host state
+     * that the Host's own startup / toggle check fills in. No-op once a result
+     * exists or the setting is off, so it can be armed from several places.
+     */
+    function scheduleUpdateResultRefresh() {
+      if (updateResultRefreshTimer !== null) return
+      const delay = UPDATE_RESULT_REFRESH_MS[updateResultRefreshAttempt]
+      if (delay === undefined) return
+      updateResultRefreshAttempt += 1
+      updateResultRefreshTimer = window.setTimeout(() => {
+        updateResultRefreshTimer = null
+        const state = store.get()
+        if (state.updateCheck !== true || state.update !== null) {
+          updateResultRefreshAttempt = 0
+          return
+        }
+        void bootstrapProviders().then(() => {
+          if (store.get().update !== null) {
+            updateResultRefreshAttempt = 0
+            return
+          }
+          scheduleUpdateResultRefresh()
+        })
+      }, delay)
+    }
+
     /** Force one upstream read for a provider and keep the row outcome. Never throws. */
     async function requestProviderTest(providerId) {
       const before = store.get().management
@@ -2519,6 +2757,9 @@ window.__ModuleLoader__.load({
       const current = store.get().management
       const stale = current.loadedAt === 0 || Date.now() - current.loadedAt >= PROVIDERS_TTL_MS
       if (current.inFlight !== true && stale) void requestProviders()
+      // A fresh check when the setting is already known and no result exists
+      // (the requestProviders answer triggers the same one-shot path otherwise).
+      maybeAutoUpdateCheck()
     }
 
     /** Switch back to the usage page (the modal chrome stays). */
@@ -2633,12 +2874,20 @@ window.__ModuleLoader__.load({
       void requestProviderUpdate(provider.providerId, { shortLabel: '', label: '' })
     }
 
-    /** Store the plugin version reported by the hello envelope (dialog footnote). */
+    /** Store the plugin version and the last update check result of the hello envelope. */
     function applyHelloInfo(data) {
       if (data === null || typeof data !== 'object') return
+      const patch = {}
       if (typeof data.version === 'string' && data.version !== '') {
-        if (store.get().pluginVersion !== data.version) store.set({ pluginVersion: data.version })
+        if (store.get().pluginVersion !== data.version) patch.pluginVersion = data.version
+      }
+      // `update` is optional on the wire: only an explicit field (null included)
+      // replaces what the store already knows.
+      if (Object.prototype.hasOwnProperty.call(data, 'update')) {
+        const update = normalizeUpdate(data.update)
+        if (!sameUpdate(store.get().update, update)) patch.update = update
       }
+      if (Object.keys(patch).length > 0) store.set(patch)
     }
 
     /** Announce this browser half to the Host (also records the current provider). */
@@ -2772,6 +3021,11 @@ window.__ModuleLoader__.load({
       // v0.10.0: learn the persisted chip label style + wire labels once, without
       // touching the management page state (silent when an old Host answers nothing).
       void bootstrapProviders()
+      // The Host runs its optional startup update check in the background; the
+      // hello / bootstrap answers above can win the race and carry no result yet.
+      // Re-read the (local, no-network) providers payload shortly after so the
+      // dialog footer can show the result without opening the management page.
+      scheduleUpdateResultRefresh()
       pollTimer = window.setInterval(() => {
         void poll()
       }, POLL_INTERVAL_MS)
@@ -2783,6 +3037,16 @@ window.__ModuleLoader__.load({
         disposed = true
         if (pollTimer !== null) window.clearInterval(pollTimer)
         if (retryTimer !== null) window.clearTimeout(retryTimer)
+        // Pending update-check timers must not fire into a disposed controller.
+        updateResultRefreshAttempt = 0
+        if (updateResultRefreshTimer !== null) {
+          window.clearTimeout(updateResultRefreshTimer)
+          updateResultRefreshTimer = null
+        }
+        if (updateCheckRetryTimer !== null) {
+          window.clearTimeout(updateCheckRetryTimer)
+          updateCheckRetryTimer = null
+        }
         if (typeof document !== 'undefined' && typeof document.removeEventListener === 'function') {
           document.removeEventListener('visibilitychange', onVisibilityChange)
         }
@@ -3118,6 +3382,20 @@ window.__ModuleLoader__.load({
 .dsh-tokenlens-settings-options .dsh-tokenlens-settings-option{display:inline-flex;align-items:center;gap:4px}
 .dsh-tokenlens-settings-actions{display:flex;flex-wrap:wrap;align-items:center;justify-content:flex-end;gap:8px;min-width:0}
 @media (max-width:560px){.dsh-tokenlens-settings-row{grid-template-columns:minmax(0,1fr)}}
+/* Update check block (update UI): toggle row, privacy hint, status line + 立即检查. */
+.dsh-tokenlens-update-section{display:flex;flex-direction:column;gap:6px;min-width:0;margin-top:2px;padding-top:8px;border-top:1px solid var(--dsw-alias-border-subtle,rgba(127,127,127,.18))}
+.dsh-tokenlens-update-hint{opacity:.8;font-size:11px}
+.dsh-tokenlens-update-status{align-items:center;flex-wrap:wrap;display:flex;gap:5px;min-width:0;color:var(--dsw-alias-label-secondary);font-size:var(--dsw-alias-font-size-sm,12px);line-height:1.4;overflow-wrap:anywhere}
+.dsh-tokenlens-update-status[data-kind=error]{color:var(--dsw-alias-label-error,#d9534f)}
+.dsh-tokenlens-update-status[data-kind=available]{color:var(--dsw-alias-label-primary)}
+.dsh-tokenlens-update-error-detail{opacity:.85;min-width:0;overflow-wrap:anywhere}
+.dsh-tokenlens-update-retry{font:inherit;font-size:11px;line-height:inherit;padding:0;border:0;background:0 0;color:inherit;cursor:pointer;text-decoration:underline;text-underline-offset:2px}
+.dsh-tokenlens-update-actions{display:flex;flex-wrap:wrap;justify-content:flex-end;gap:8px;min-width:0}
+.dsh-tokenlens-update-link{display:inline-flex;align-items:center;gap:4px;color:var(--dsw-alias-label-secondary);font-size:inherit;text-decoration:underline;text-underline-offset:2px;min-width:0}
+.dsh-tokenlens-update-link:hover,.dsh-tokenlens-update-retry:hover{color:var(--dsw-alias-label-primary)}
+.dsh-tokenlens-update-link:focus-visible,.dsh-tokenlens-update-retry:focus-visible{outline:none;box-shadow:0 0 0 2px var(--dsw-alias-border-strong,rgba(127,127,127,.5));border-radius:2px}
+.dsh-tokenlens-update-line{display:inline-flex;flex-wrap:wrap;align-items:center;gap:4px 6px;min-width:0;margin-right:auto;color:var(--dsw-alias-label-tertiary);font-size:var(--dsw-alias-font-size-sm,12px);line-height:1.4}
+.dsh-tokenlens-update-line .dsh-tokenlens-update-link{color:inherit}
 .dsh-tokenlens-provider-labels{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:1.4;overflow-wrap:anywhere;display:flex;flex-wrap:wrap;align-items:flex-start;gap:4px}
 .dsh-tokenlens-provider-labels .dsh-tokenlens-icon{margin-top:1px}
 /* Inline icons: currentColor stroke, never a text node (keeps textOf stable). */
@@ -5891,11 +6169,13 @@ window.__ModuleLoader__.load({
             h(
               'button',
               {
-                key: option.value,
+                key: String(option.value),
                 type: 'button',
                 className: `dsh-tokenlens-scope-option dsh-tokenlens-settings-option${field === 'labelStyle' ? ' dsh-tokenlens-label-style-option' : ''}`,
                 'data-setting': field,
-                'data-value': option.value,
+                // A boolean row (updateCheck) is stringified so `data-*` matches
+                // the real DOM; the string rows keep their wire value verbatim.
+                'data-value': typeof option.value === 'string' ? option.value : String(option.value),
                 'data-label-style': field === 'labelStyle' ? option.value : undefined,
                 'data-active': active === option.value ? 'true' : 'false',
                 'aria-pressed': active === option.value ? 'true' : 'false',
@@ -5913,6 +6193,127 @@ window.__ModuleLoader__.load({
       )
     }
 
+    /** The npm page the update links open (the Host-advertised one when present). */
+    function updatePackageUrlOf(state) {
+      return typeof state?.updatePackageUrl === 'string' && state.updatePackageUrl !== ''
+        ? state.updatePackageUrl
+        : NPM_PACKAGE_URL
+    }
+
+    /**
+     * The 「更新检查」 status line: checking → failed → update available → up to
+     * date → never checked. `data-update-status` names the branch for tests and
+     * styling; the error branch keeps a 重试 action only when retryable.
+     */
+    function buildUpdateStatusLine(state, t) {
+      const update = state.update
+      const packageUrl = updatePackageUrlOf(state)
+      const line = (kind, children) =>
+        h(
+          'div',
+          {
+            key: 'update-status',
+            className: 'dsh-tokenlens-update-status',
+            'data-update-status': kind,
+            'data-kind': kind,
+            role: 'status',
+          },
+          Icon(kind === 'error' ? 'alert' : kind === 'available' ? 'bolt' : kind === 'latest' ? 'check' : 'info', 12),
+          children,
+        )
+      if (state.updateChecking === true) {
+        return line('checking', h('span', { key: 'text' }, t('updateChecking')))
+      }
+      if (update !== null && update.error !== null) {
+        return line('error', [
+          h('span', { key: 'text' }, t('updateCheckFailed')),
+          h('span', { key: 'detail', className: 'dsh-tokenlens-update-error-detail', title: update.error.message }, managementErrorText(update.error, t)),
+          update.error.retryable === true
+            ? h(
+                'button',
+                {
+                  key: 'retry',
+                  type: 'button',
+                  className: 'dsh-tokenlens-update-retry',
+                  'data-update-retry': 'true',
+                  onClick: () => {
+                    void requestUpdateCheck()
+                  },
+                },
+                t('retry'),
+              )
+            : null,
+        ])
+      }
+      if (update !== null && update.available === true) {
+        return line('available', [
+          h('span', { key: 'text' }, t('updateAvailable', { latest: update.latest, current: update.current })),
+          h(
+            'a',
+            {
+              key: 'link',
+              className: 'dsh-tokenlens-update-link',
+              'data-update-link': 'true',
+              href: packageUrl,
+              target: '_blank',
+              rel: 'noreferrer noopener',
+              title: packageUrl,
+              onClick: (event) => openConsole(packageUrl, event),
+            },
+            Icon('external', 12),
+            t('updateOpenNpm'),
+          ),
+        ])
+      }
+      if (update !== null && update.latest !== null && update.available === false) {
+        return line('latest', h('span', { key: 'text' }, t('updateLatest', { version: update.latest })))
+      }
+      return line('never', h('span', { key: 'text' }, t('updateCheckNever')))
+    }
+
+    /**
+     * The 「更新检查」 block of 插件设置: the startup toggle (the shared settings
+     * row), the registry-privacy hint, the last check result and 「立即检查」.
+     * The check button works whether the startup toggle is on or off, and its
+     * `updateChecking` flag is independent from `settingsBusy`.
+     */
+    function buildUpdateSection(state, t) {
+      const checking = state.updateChecking === true
+      return h(
+        'div',
+        { key: 'update-section', className: 'dsh-tokenlens-update-section', 'data-update-section': 'true' },
+        buildSettingsRow(state, t, 'updateCheck', t('updateCheckLabel'), [
+          { value: false, label: t('updateCheckOff'), icon: 'ban' },
+          { value: true, label: t('updateCheckOn'), icon: 'check' },
+        ]),
+        h(
+          'div',
+          { key: 'hint', className: 'dsh-tokenlens-subtitle dsh-tokenlens-update-hint', 'data-update-hint': 'true' },
+          t('updateCheckHint'),
+        ),
+        buildUpdateStatusLine(state, t),
+        h(
+          'div',
+          { key: 'actions', className: 'dsh-tokenlens-update-actions' },
+          h(
+            Button,
+            {
+              variant: 'outline',
+              className: 'dsh-tokenlens-update-check',
+              'data-update-check-now': 'true',
+              title: t('updateCheckNow'),
+              disabled: checking,
+              onClick: () => {
+                void requestUpdateCheck()
+              },
+            },
+            Icon('spinner', 12),
+            checking ? t('updateChecking') : t('updateCheckNow'),
+          ),
+        ),
+      )
+    }
+
     /** The 插件设置 tab (v0.29.0): display defaults, reset button and store path. */
     function buildSettingsPanel(state, t) {
       const management = state.management
@@ -5937,6 +6338,9 @@ window.__ModuleLoader__.load({
           { value: 'collapsed', label: t('settingsDetailsCollapsed'), icon: 'list' },
         ]),
       ]
+      // 「更新检查」 is its own block (own status + own in-flight flag), kept
+      // apart from the display-defaults rows and their reset button.
+      children.push(buildUpdateSection(state, t))
       const actions = h(
         'div',
         { key: 'actions', className: 'dsh-tokenlens-settings-actions' },
@@ -6381,6 +6785,46 @@ window.__ModuleLoader__.load({
       })
     }
 
+    /**
+     * The usage dialog's 「发现新版本」 footer line, or null when the last check
+     * found no update (or never ran). The i18n sentence names 「打开 npm」 as its
+     * tail; that tail becomes the anchor that opens the npm package page, so the
+     * line itself stays a single sentence with one real link inside it.
+     */
+    function buildUpdateFooterLine(state, t) {
+      const update = state.update
+      if (update === null || update.available !== true) return null
+      const text = t('updateDialogLine', { latest: update.latest })
+      const linkLabel = t('updateOpenNpm')
+      const packageUrl = updatePackageUrlOf(state)
+      const link = h(
+        'a',
+        {
+          key: 'link',
+          className: 'dsh-tokenlens-update-link dsh-tokenlens-update-footer-link',
+          'data-update-link': 'true',
+          href: packageUrl,
+          target: '_blank',
+          rel: 'noreferrer noopener',
+          title: packageUrl,
+          onClick: (event) => openConsole(packageUrl, event),
+        },
+        linkLabel,
+        Icon('external', 12),
+      )
+      const index = text.indexOf(linkLabel)
+      const children =
+        index < 0
+          ? [h('span', { key: 'text' }, text), h('span', { key: 'sep' }, ' · '), link]
+          : [h('span', { key: 'text' }, text.slice(0, index)), link]
+      return h(
+        'div',
+        { key: 'update-line', className: 'dsh-tokenlens-update-line', 'data-update-line': 'true' },
+        Icon('bolt', 12),
+        children,
+      )
+    }
+
     /** The dialog contents (body + footer); may throw, the caller guards it. */
     function buildDialog(state, now, t) {
       if (state.view === 'management') return buildManagementDialog(state, t)
@@ -6440,6 +6884,9 @@ window.__ModuleLoader__.load({
               Icon('external', 12),
               consoleLabel,
             ),
+        // 「发现新版本」 line (only while an update is available): its 「打开 npm」
+        // tail is the real npm-package link, next to the refresh/close buttons.
+        buildUpdateFooterLine(state, t),
         h(
           Button,
           {

package/index.js

@@ -37,6 +37,7 @@ import {
 } from './lib/provider-store.mjs'
 import { makeCustomAdapter, sanitizeUsageBaseURL, validateCustomProvider } from './lib/custom-provider.mjs'
 import { redactEndpoint, redactPaths, redactTextPaths } from './lib/redact.mjs'
+import { UPDATE_CHECK_URL, UPDATE_PACKAGE_URL, buildUpdateInfo, parseLatestVersion } from './lib/update-check.mjs'
 
 /**
  * The one browser-facing route this plugin owns.
@@ -60,10 +61,11 @@ export const ACTIONS = [
   'settingsUpdate',
   'customProviderSave',
   'customProviderDelete',
+  'updateCheck',
 ]
 
 /** The tool-facing subset (a model has no reason to announce a browser). */
-export const TOOL_ACTIONS = ['snapshot', 'refresh', 'stats', 'diagnostics', 'status']
+export const TOOL_ACTIONS = ['snapshot', 'refresh', 'stats', 'diagnostics', 'status', 'updateCheck']
 
 /** Optional services; every one is probed with `ctx.get` at use time. */
 export const inject = []
@@ -72,7 +74,7 @@ export const inject = []
 export const PLUGIN_NAME = 'dsh-tokenlens'
 
 /** Plugin version; mirrors package.json (kept here so diagnostics need no fs read). */
-export const PLUGIN_VERSION = '1.2.2'
+export const PLUGIN_VERSION = '1.3.0'
 
 /** Documented defaults; every field of the raw row config is optional. */
 const DEFAULTS = {
@@ -282,6 +284,11 @@ export function apply(ctx, rawConfig) {
     requestCounts: new Map(), // providerId 鈫?successful reads
     subscribers: new Set(),
     client: null, // last browser `hello`
+    // Optional startup update check (settings.updateCheck): the last result
+    // `{current, latest, available, checkedAt, error}` or null before the first
+    // check. Never fetched unless the user enables the setting.
+    update: null,
+    updateChecking: false,
     bridge: { found: false, registered: false, path: BRIDGE, error: null },
     poll: { timer: null },
     status: { timer: null },
@@ -729,6 +736,11 @@ export function apply(ctx, rawConfig) {
       providers,
       dshProviders,
       settings: sanitizeSettings(providerStore.settings),
+      // Optional startup update check (settings.updateCheck): null until the
+      // first check; never fetched unless the setting is enabled or the user
+      // presses "check now".
+      update: state.update,
+      updatePackageUrl: UPDATE_PACKAGE_URL,
       storeFile: redactPaths(providerStoreFile),
       storeFileDisplay: redactPaths(providerStoreFile),
     }
@@ -876,6 +888,53 @@ export function apply(ctx, rawConfig) {
     return requestJson(url, { bearer: keyValue })
   }
 
+  // Single-flight guard for the optional update check (see runUpdateCheck).
+  let updateFlight = null
+
+  /**
+   * Ask the npm registry for the published `latest` version and remember the
+   * comparison result. This is the plugin's only non-provider outbound request
+   * and it only ever happens when the user enabled `settings.updateCheck`
+   * (startup / toggling it on) or presses "check now" on the management page.
+   *
+   * Single-flight: a concurrent call awaits the same in-flight check instead of
+   * answering `null`, and the function never throws — an offline machine or an
+   * upstream failure is stored as an error state so the UI can explain it.
+   */
+  async function runUpdateCheck() {
+    if (updateFlight !== null) return updateFlight
+    updateFlight = (async () => {
+      state.updateChecking = true
+      let latest = null
+      let failure = null
+      try {
+        const payload = await requestJson(UPDATE_CHECK_URL)
+        latest = parseLatestVersion(payload)
+        if (latest === null) {
+          throw new UsageError('parse', 'the npm registry response has no usable version', { retryable: false })
+        }
+      } catch (error) {
+        failure = errorToWire(error)
+      } finally {
+        state.updateChecking = false
+      }
+      state.update = buildUpdateInfo(PLUGIN_VERSION, latest, new Date().toISOString(), failure)
+      noteStatus('update-check')
+      announce()
+      if (failure !== null) {
+        warn(`update check failed: ${failure.code}: ${failure.message}`)
+      } else if (state.update.available === true) {
+        log('info', `update available: ${state.update.latest} (running ${PLUGIN_VERSION})`)
+      }
+      return state.update
+    })()
+    try {
+      return await updateFlight
+    } finally {
+      updateFlight = null
+    }
+  }
+
   /** Read one provider's usage: resolve its key (when it has one), call its adapter. */
   async function readProvider(providerId, now) {
     const id = canonicalProviderId(providerId)
@@ -1391,6 +1450,7 @@ export function apply(ctx, rawConfig) {
       activeProvider: activeProviderId(),
       client: state.client,
       bridge: { ...state.bridge },
+      update: state.update,
       providers,
       stats: statsService?.diagnostics?.() ?? null,
       subscribers: state.subscribers.size,
@@ -1586,7 +1646,15 @@ export function apply(ctx, rawConfig) {
         log('info', `browser half connected from ${String(state.client.origin ?? 'unknown origin')} (${providerId ?? 'default provider'})`)
         // Answer with a snapshot too, so the first paint needs one round trip.
         const first = await get(requestProvider(body))
-        return json({ ok: true, plugin: PLUGIN_NAME, version: PLUGIN_VERSION, bridge: BRIDGE, pid: process.pid, ...first })
+        return json({
+          ok: true,
+          plugin: PLUGIN_NAME,
+          version: PLUGIN_VERSION,
+          bridge: BRIDGE,
+          pid: process.pid,
+          update: state.update,
+          ...first,
+        })
       }
       if (action === 'snapshot' || action === 'status') {
         rememberRequestedProvider(body)
@@ -1598,6 +1666,7 @@ export function apply(ctx, rawConfig) {
       }
       if (action === 'stats') return json(await getStats({ fresh: body?.fresh === true }))
       if (action === 'providers') return json(await providersPayload())
+      if (action === 'updateCheck') return json({ ok: true, update: await runUpdateCheck() })
       if (action === 'customProviderSave') {
         const def = validateCustomProvider(body?.provider ?? body)
         if (PROVIDER_DEFAULTS[def.providerId] !== undefined || ADAPTERS[def.providerId] !== undefined) {
@@ -1668,11 +1737,23 @@ export function apply(ctx, rawConfig) {
           }
           next.detailsWindow = incoming.detailsWindow
         }
+        if (Object.prototype.hasOwnProperty.call(incoming, 'updateCheck')) {
+          if (typeof incoming.updateCheck !== 'boolean') {
+            throw new UsageError('unsupported-provider', 'settings.updateCheck must be a boolean', {
+              retryable: false,
+            })
+          }
+          next.updateCheck = incoming.updateCheck
+        }
         providerStore = saveProviderStore(providerStoreFile, {
           ...providerStore,
           settings: next,
         })
         noteStatus('settings-update', { providerStoreFile })
+        // Turning the optional update check ON runs one check right away, so the
+        // management page can show a result instead of waiting for a restart. A
+        // full-settings save while it is already on must not re-request npm.
+        if (incoming.updateCheck === true && current.updateCheck !== true) void runUpdateCheck()
         return json(await providersPayload())
       }
       if (action === 'providerUpdate') {
@@ -1765,6 +1846,12 @@ export function apply(ctx, rawConfig) {
   }
 
   noteStatus('activate', { pollIntervalMs: config.pollIntervalMs })
+  // Optional startup update check: one plain npm-registry request, only when the
+  // user enabled `settings.updateCheck`. Off by default to keep the plugin
+  // local-only; failures are recorded and never break activation.
+  if (sanitizeSettings(providerStore.settings).updateCheck === true) {
+    void runUpdateCheck()
+  }
   log(
     'info',
     `ready (providers ${Object.keys(config.providers).filter((id) => config.providers[id].enabled).join(', ') || 'none'}, cache ${config.minRefreshIntervalMs} ms, poll ${config.pollIntervalMs} ms)`,

package/lib/provider-store.mjs

@@ -40,6 +40,9 @@ export const DEFAULT_SETTINGS = {
   detailsExpanded: 'auto',
   // v1.2.1 图表明细窗口默认值: 总计 (the last choice is persisted there).
   detailsWindow: 'total',
+  // Optional startup update check (npm registry); off by default so the plugin
+  // stays local-only unless the user opts in.
+  updateCheck: false,
 }
 
 /** The default override file: `$DSH_HOME/dsh-tokenlens/providers.json`. */
@@ -126,6 +129,7 @@ export function sanitizeSettings(value) {
     detailsWindow: DETAILS_WINDOWS.includes(source.detailsWindow)
       ? source.detailsWindow
       : DEFAULT_SETTINGS.detailsWindow,
+    updateCheck: source.updateCheck === true,
   }
 }
 

package/lib/update-check.mjs

@@ -0,0 +1,87 @@
+/**
+ * Optional startup update check.
+ *
+ * The plugin stays local-only by default: nothing is sent anywhere unless the
+ * user enables `settings.updateCheck` in the management page. When enabled, one
+ * HTTPS GET asks the npm registry for the published `latest` version and the
+ * result is surfaced on the management page (and as a line in the detail dialog
+ * footer). No identifiers, credentials or usage data are sent — only a plain
+ * version-metadata request with the plugin's user agent.
+ */
+
+/** The npm registry endpoint that answers the published `latest` version. */
+export const UPDATE_CHECK_URL = 'https://registry.npmjs.org/dsh-tokenlens/latest'
+
+/** The canonical npm page of the package (for the "open on npm" link). */
+export const UPDATE_PACKAGE_URL = 'https://www.npmjs.com/package/dsh-tokenlens'
+
+/**
+ * Parse one version string into comparable parts.
+ *
+ * Accepts `1.2.3`, `v1.2.3` and an optional prerelease (`1.3.0-beta.1`). Junk,
+ * empty strings and absurdly long input return null.
+ */
+export function parseVersion(raw) {
+  if (typeof raw !== 'string') return null
+  const text = raw.trim()
+  if (text === '' || text.length > 64) return null
+  const match = /^v?(\d{1,9})\.(\d{1,9})\.(\d{1,9})(?:-([0-9A-Za-z.-]{1,40}))?$/.exec(text)
+  if (match === null) return null
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    pre: match[4] ?? '',
+  }
+}
+
+/**
+ * Compare two versions (`> 0` when `left` is newer, `< 0` when older, `0` when
+ * equal). A release always outranks its prereleases; prereleases compare as
+ * strings, which is enough for this plugin's plain `x.y.z` history.
+ */
+export function compareVersions(left, right) {
+  const a = parseVersion(left)
+  const b = parseVersion(right)
+  if (a === null || b === null) return null
+  for (const key of ['major', 'minor', 'patch']) {
+    if (a[key] !== b[key]) return a[key] - b[key]
+  }
+  if (a.pre === b.pre) return 0
+  if (a.pre === '') return 1
+  if (b.pre === '') return -1
+  return a.pre < b.pre ? -1 : 1
+}
+
+/** Whether `latest` is strictly newer than `current` (false for junk input). */
+export function isNewerVersion(latest, current) {
+  const compared = compareVersions(latest, current)
+  return compared !== null && compared > 0
+}
+
+/** The `version` field of the npm `/latest` document, or null. */
+export function parseLatestVersion(payload) {
+  if (payload === null || typeof payload !== 'object' || Array.isArray(payload)) return null
+  const version = payload.version
+  if (typeof version !== 'string') return null
+  const trimmed = version.trim()
+  return parseVersion(trimmed) === null ? null : trimmed
+}
+
+/**
+ * The wire shape the client renders:
+ * `{ current, latest, available, checkedAt, error }`.
+ *
+ * `available` is only true for a well-formed, strictly newer non-errored answer;
+ * the check never invents a version and an upstream failure keeps `latest: null`.
+ */
+export function buildUpdateInfo(current, latest, checkedAt, error = null) {
+  const latestVersion = typeof latest === 'string' && parseVersion(latest) !== null ? latest.trim() : null
+  return {
+    current: typeof current === 'string' ? current : '',
+    latest: latestVersion,
+    available: error === null && latestVersion !== null && isNewerVersion(latestVersion, current),
+    checkedAt: typeof checkedAt === 'string' && checkedAt !== '' ? checkedAt : new Date().toISOString(),
+    error: error === null || error === undefined ? null : error,
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-tokenlens",
-  "version": "1.2.2",
+  "version": "1.3.0",
   "type": "module",
   "description": "dsh-TokenLens (词元透镜) — provider-aware plan capacity plus local token statistics (today/7d/30d/all-time, by harness/provider/model/workspace) for DSH.",
   "license": "MIT",