dsh-tokenlens 1.2.2 → 1.3.1

package/CHANGELOG.md

@@ -1,97 +1,59 @@
 # Changelog
 
-本项目遵循 [Semantic Versioning](https://semver.org/)：修复 = PATCH，新功能 = MINOR，不兼容变更 = MAJOR。发布时同步更新 `package.json` 的 `version`、`index.js` 的 `PLUGIN_VERSION` 与本文件（`node scripts/bump-version.mjs <version> "<note>"`）；已发布的条目保持原样。
+本项目遵循 [Semantic Versioning](https://semver.org/)：修复 = PATCH，新功能 = MINOR，不兼容变更 = MAJOR。发布时同步更新 `package.json` 的 `version`、`index.js` 的 `PLUGIN_VERSION` 与本文件（`node scripts/bump-version.mjs <version> "<note>"`）。
 
-## 1.2.2 — 2026-11-01
+**版本记录约定**：同一发布日只保留一个章节，标题取当日**最后一个**已发布版本号；当日多次发布的改动合并到该章节，并在标题下注明当日实际发布过的版本号（npm 上仍可安装这些独立版本）。若当日已有发布，后续小改动不再单独增加版本号，而是并入下一篇日志。这样日志按天规整、不出现同日多个小版本。
 
-- fix(workspaces): 修复「工作区悬浮卡片不显示 Token 明细」——Host 在裁剪本地路径时把 `path` 字段误删成空串，客户端只剩标题精确匹配；默认工作区等「界面标题 ≠ 统计标签」的场景因此匹配不到统计（影响 v1.2.1 及更早版本）
-- fix(workspaces): 悬浮卡片匹配增强——标题匹配改为大小写不敏感；Host 只下发文件夹名 basename（不含完整路径）；旧 Host 未下发 `path` 时用文件夹名与标签兜底
-- docs: README 增加「用 `link:` 安装的插件不要从插件市场重复安装/升级」的排错说明（Windows 下 pnpm 会遇到 EPERM）
-- 测试：256 个自动化用例（新增工作区 wire basename 回归；客户端匹配逻辑断言）
+## 1.3.1 — 2026-11-01
 
-## 1.2.1 — 2026-10-31
+（当日已发布版本：v1.2.2 / v1.3.0 / v1.3.1）
+
+- feat(update): 「启动时检查更新」改为**默认开启**（可在插件设置关闭）；启动时向 npm registry 查询一次 latest 版本号，不携带凭据 / 账号 / 用量，失败只记录错误、不阻塞启动
+- feat(ui): 详情弹窗（统计首页）右下角的**插件版本处**显示更新状态——有新版本时显示「有新版本 vX」并可点击打开 npm；无新版本时显示「已是最新版本」；检查失败或关闭检查时不显示
+- feat(update): 供应商管理页「插件设置 → 更新检查」保留开关、隐私提示、状态行（尚未检查 / 正在检查 / 已是最新 / 发现新版本 / 检查失败可重试）与「立即检查」；并发检查单飞，仅在开关关→开时补查
+- feat(wire): `hello` / `providers` 携带 `update`（`UpdateInfo`）与 `updatePackageUrl`；`settings.updateCheck` 默认 `true`；新增 bridge action `updateCheck`（Agent 工具同步支持）
+- fix(workspaces): 修复「工作区悬浮卡片不显示 Token 明细」——Host 裁剪本地路径时把 `path` 误删成空串，默认工作区等「界面标题 ≠ 统计标签」的场景匹配失败；现只下发文件夹名 basename，客户端标题匹配大小写不敏感并兼容旧 Host
+- docs: README 增加「用 `link:` 安装的插件不要从插件市场重复安装/升级」的 Windows pnpm EPERM 排错说明；CHANGELOG 改为按发布日合并
+- 测试：278 个自动化用例（版本比较/检查/并发、设置开关、状态行、图表下钻与窗口、工作区 wire 回归）
 
-- feat(settings): 图表模式「明细」环形图的窗口选择（今日 / 最近7天 / 最近X天（或最近30天）/ 总计）持久化到插件设置：点击 pill 立即保存，重开弹窗、切换供应商或重启 DSH 后仍保留上次选择；当前供应商没有该窗口时自动回落到总计
-- feat(wire): `providers` 载荷与 `settingsUpdate` 增加 `settings.detailsWindow`（`today|last7Days|second|total`），旧 Host 会忽略未知字段、旧 client 读取时回落 `total`，双向兼容
-- 修复：请求进行中连续点击窗口时只保留最后一个选择（单定时器 200ms 重试）；「恢复默认设置」同时把窗口重置为总计
-- 测试：255 个自动化用例（新增 5 个持久化回归，更新 8 个既有设置/窗口用例）
+## 1.2.1 — 2026-10-31
 
-## 1.2.0 — 2026-10-31
+（当日已发布版本：v1.2.0 / v1.2.1）
 
-- feat(chart): 图表模式点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗棒状图（横轴 00:00–23:00，悬浮显示小时与占比，回车/空格同样可操作，返回或再次点击回到日趋势）
+- feat(chart): 图表模式点击某一天的柱子可下钻查看**当天 24 小时**的 Token 消耗（横轴 00:00–23:00，悬浮显示小时与占比，回车/空格可操作，返回或再次点击回到日趋势）
 - feat(chart): 小时数据覆盖全部 5 个本机 harness（DSH、ZCode、OpenCode CLI、WorkBuddy、Qoder）；无小时数据的旧日期不可下钻，不伪造全零序列
-- feat(chart): 图表模式「明细」的三张环形图（按 Harness / 按供应商 / Top 模型）新增 **今日 / 最近7天 / 最近X天（或最近30天）/ 总计** 窗口切换，默认总计；切换 scope 或数据/图表视图时保持，缺失窗口自动隐藏
-- feat(wire): `stats.daily[]` 新增可选 `hours`（24 个本地小时 Token 整数）与 `providers[pid].hours`（v1.2.0 协议，已在 PROTOCOL 中写明）
-- 测试：250 个自动化用例（新增 13 个：小时聚合、外部 harness 小时分组、下钻交互与窗口切换的前后端回归）
+- feat(chart): 明细三张环形图（按 Harness / 按供应商 / Top 模型）支持 **今日 / 最近7天 / 最近X天（或最近30天）/ 总计** 窗口切换，默认总计，缺失窗口自动隐藏
+- feat(settings): 明细窗口选择持久化到插件设置——点击 pill 立即保存，重开弹窗、切换供应商或重启 DSH 后仍保留，窗口不可用时回落到总计
+- feat(wire): `stats.daily[]` 新增 `hours` 与 `providers[pid].hours`（24 个本地小时 Token 整数）；`settings.detailsWindow`
+- 修复：请求进行中连续点击窗口只保留最后一次选择（单定时器 200ms 重试）；「恢复默认设置」同时把窗口重置为总计
+- 测试：250 → 255（小时聚合、外部 harness 小时分组、下钻交互、窗口切换与持久化回归）
 
 ## 1.1.0 — 2026-10-30
 
 - feat(providers): 接入 Open Design（OpenDesign）只读额度查询——Design Plan 的 5 小时 / 7 天窗口已用百分比与重置时间，以及独立的钱包 USD 余额
 - feat(providers): Open Design 使用工作区 `workspaceId` + Control Key（`OPENDESIGN_CONTROL_KEY` / `VELA_CONTROL_KEY`）鉴权；推理 API Key 不能查询计费接口
-- feat(ui): `windows` 快照现在可以附带钱包余额——详情弹窗在额度窗口下方多一行「账户余额」，chip 悬浮提示追加金额
+- feat(ui): `windows` 快照可附带钱包余额——详情弹窗在额度窗口下方多一行「账户余额」，chip 悬浮提示追加金额
 - docs: 中英 README 与 PROTOCOL 补充 Open Design；说明其余仅元数据供应商没有可用 API Key 查询的公开用量接口（千问/百炼额度仅官方 CLI 可查，腾讯混元/百度千帆只有云账户余额 API）
 
 ## 1.0.9 — 2026-10-29
 
-- ci: GitHub Actions 升级到 v7（actions/checkout、actions/setup-node），发布链路仅依赖 OIDC
-
-## 1.0.8 — 2026-10-29
-
-- fix(release): npm registry 发布延迟时索引更新回退到 PUBLISH_TIMESTAMP；补录 1.0.7 到市场索引
-
-## 1.0.7 — 2026-10-29
-
-- ci: 发布改用 npm Trusted Publishing（OIDC），不再依赖仓库令牌；docs: 归并 1.0.0 之前版本历史并修订文档措辞
-
-## 1.0.6 — 2026-10-29
-
-- fix(market): 发布后等待 npm registry 同步再写索引（自动重试）；索引补录 1.0.5
-
-## 1.0.5 — 2026-10-29
-
-- feat(market): 提供 DSH 插件市场索引（market/index.json + icon）并支持发布后自动同步；README 增加从 DSH 市场安装的说明
-
-## 1.0.4 — 2026-10-29
-
-- chore: 插件市场元数据（dsh-plugin 关键词、engines.dsh）与 GitHub 源安装说明
-
-## 1.0.3 — 2026-10-29
+（当日已发布版本：v1.0.3 / v1.0.4 / v1.0.5 / v1.0.6 / v1.0.7 / v1.0.8 / v1.0.9）
 
+- feat(market): 提供 DSH 插件市场索引（`market/index.json` + icon）并支持发布后自动同步；README 增加从 DSH 市场安装的说明
+- feat: 插件市场元数据（`dsh-plugin` 关键词、`engines.dsh`）与 GitHub 源安装说明
 - fix(stats): 逐帧解压 zstd，兼容 Node >= 24.22（尾部撕裂帧不再拖垮整份日志，修复 CI 三平台失败）
+- fix(market): 发布后等待 npm registry 同步再写索引（自动重试，`PUBLISH_TIMESTAMP` 回退）；补录历史版本到索引
+- ci: 发布改用 npm Trusted Publishing（OIDC），不再依赖仓库令牌；GitHub Actions 升级到 v7
+- docs: 归并 1.0.0 之前版本历史并修订文档措辞
 
 ## 1.0.2 — 2026-10-28
 
-- fix(security+privacy): audit hardening — OpenCode auth key scoping, workspace badge observer loop, canonical provider cache keys, stats path redaction incl. free-form errors, baseURL HTTPS validation (profile/custom), effective-day full history, prototype-pollution-safe maps, WorkBuddy no-id dedupe, immutable provider store writes, secure temp files, DST-safe windows, console link/provider aliases, management scroll; screenshots sanitized
-
-## 1.0.1 — 2026-10-28
-
-- fix(privacy): 状态文件/诊断/管理页路径脱敏（~）、状态文件 0600、网络错误 URL 去凭据/查询串；匿名化测试 fixture 与公共文档中的个人邮箱；工作区统计 tick 增加隐藏页保护；新增 redact 单测与网络错误回归测试
-
-## 1.0.0 — 2026-10-28
-
-首个公开版本：插件定名 **dsh-TokenLens · 词元透镜**，技术包名与内部标识统一为 `dsh-tokenlens` / `tokenlens`，以 MIT 许可开源。本版本合并了此前 0.1.0–0.36.3 的全部开发历史：
-
-**供应商与套餐容量**
-
-- OpenCode（Go 套餐的 5 小时 / 本周 / 本月窗口）、Command Code（美元额度与方案）、DeepSeek 余额、DeepSeek Account 钱包、OpenRouter、Moonshot / Kimi、SiliconFlow、StepFun、Novita、Hyperbolic、DeepInfra、Z.ai GLM Coding Plan、MiniMax Coding Plan；随后接入智谱 AI 国内版与火山引擎 Coding / Agent Plan
-- 内置供应商元数据池扩充到 25 家（商汤 SenseNova、通义千问、百度千帆、腾讯混元、讯飞星火、零一万物、百川智能、Intern AI、Agnes AI、Open Design 等）
-- 按 DSH 模型设置自动发现路由、自动匹配用量接口并继承凭据；支持短标签 / 全名、启用开关、订阅徽章与控制台链接
-
-**本机 Token 统计**
-
-- 接入 5 个 harness：DSH 会话日志（zstd 逐帧解码、seed 前缀与重试口径）、ZCode（只读 SQLite）、OpenCode CLI、WorkBuddy / CodeBuddy CLI、Qoder CN CLI
-- 跨 harness 按供应商合并（alias、同 id、vendor-namespaced 模型唯一匹配），无法映射的供应商单列
-- 窗口：今日 / 最近 7 天 / 最近 30 天 / 总计、订阅供应商的「最近 X 天」、滚动 5 小时；按 Harness / 供应商 / Top 模型 / 工作区拆分
-- 工作区 Token 徽标与悬浮卡片
-
-**界面**
-
-- 输入框下方的用量 chip（跟随当前供应商）与详情弹窗：套餐容量、本机 Token 两套口径分区展示
-- 数据 / 图表两种模式：每日趋势柱状图（坐标轴、悬浮读数）、环形占比图、明细表格
-- 供应商管理页（已配置 / 内置 / 全部、凭据状态、短标签编辑、测试连接）与插件设置页；深色主题与窄屏适配
-
-**工程**
+（当日已发布版本：v1.0.0 / v1.0.1 / v1.0.2）
 
-- Host ↔ Client bridge 协议 v3、`planUsage` 服务与 `tokenlens_usage` Agent 工具
-- 配置覆盖（profile patch 与 providers.json）、统计缓存、诊断与状态文件
-- 231 个自动化测试（Node 内置测试器，三平台 CI），零运行时依赖，要求 Node ≥ 24（`node:sqlite`、zstd）
+- fix(security+privacy): 安全 / 隐私审计加固——OpenCode key 作用域、工作区徽标观察器循环、缓存 canonical、统计路径与自由文本脱敏、baseURL HTTPS 校验、effective-day 全历史、原型污染防护、WorkBuddy 去重、0600 原子写、DST 窗口、控制台链接、管理页滚动；截图脱敏（账号 / 本机路径）
+- fix(privacy): 状态文件 / 诊断 / 管理页路径脱敏（`~`）、状态文件 0600、网络错误 URL 去凭据 / 查询串；测试 fixture 与公开文档去除个人邮箱
+- 首个公开版本（v1.0.0）：插件定名 **dsh-TokenLens · 词元透镜**，包名与内部标识统一为 `dsh-tokenlens` / `tokenlens`，以 MIT 许可开源；本版本合并了此前 0.1.0–0.36.3 的全部开发历史：
+  - **供应商与套餐容量**：OpenCode（Go 套餐窗口）、Command Code、DeepSeek / DeepSeek Account、OpenRouter、Moonshot / Kimi、SiliconFlow、StepFun、Novita、Hyperbolic、DeepInfra、Z.ai GLM、MiniMax、智谱国内版、火山引擎 Coding / Agent Plan；内置 25 家供应商元数据池；按 DSH 模型设置自动发现路由并继承凭据
+  - **本机 Token 统计**：接入 5 个 harness（DSH、ZCode、OpenCode CLI、WorkBuddy / CodeBuddy CLI、Qoder CN CLI）；跨 harness 按供应商合并；窗口 今日 / 最近 7 天 / 最近 30 天 / 总计 与订阅供应商「最近 X 天」、滚动 5 小时；按 Harness / 供应商 / Top 模型 / 工作区拆分
+  - **界面**：输入框下方用量 chip（跟随当前供应商）与详情弹窗（套餐容量 vs 本机 Token 分区）、数据 / 图表两种模式、供应商管理页与插件设置页
+  - **工程**：Host ↔ Client bridge 协议 v3、`planUsage` 服务、`tokenlens_usage` Agent 工具、配置覆盖、统计缓存、诊断与状态文件、231 个自动化测试、零运行时依赖、Node ≥ 24

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 `true` since v1.3.1) enables the startup update check — the off→on transition runs one check immediately. Invalid values answer `unsupported-provider`.
+
+### Update check (v1.3.0, on by default since v1.3.1)
+
+On by default: at activation the Host makes one HTTPS `GET` to the fixed endpoint
+`https://registry.npmjs.org/dsh-tokenlens/latest`; the same request also runs on
+the off→on transition of `settings.updateCheck` and on the `updateCheck` action.
+Users can switch it off (`settings.updateCheck: false`) to keep the plugin fully
+local-only. 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.1. 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, startup update check — on by default — 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.1" },
   "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 outbound request is the startup update check (introduced in v1.3.0, on by default since v1.3.1 and switchable off): 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 is on by default (switchable off) and compares the **latest npm release** only; 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 278 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.1，公开版本）。它把两类数字**按不同口径**分开呈现：
 
 - **套餐容量**（供应商服务端权威值）：百分比窗口、`已用 / 上限`、账户余额或剩余额度；
 - **本机 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.1"
   },
   "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 引入，v1.3.1 起默认开启，可在插件设置关闭）：仅向 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`：**278 个自动化用例**，覆盖 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        # 278 个用例
 ```
 
 本地联调安装方式见[方式 C](#方式-c本地开发从源码-link)。