@sligqoer/dsh-usage-stats 0.2.0 → 0.2.2

package/CHANGELOG.md

@@ -1,4 +1,92 @@
-# Changelog / 更新日志
+# 更新日志 / Changelog
+
+## 0.2.2 - 2026-10-16
+
+<a id="v022-zh"></a>
+**简体中文** · [English](#v022-en)
+
+### 🐛 问题修复
+
+- 修正 DSH Desktop 兼容版本声明为 0.2.0-rc.2，避免该版本被宿主插件管理器误拒绝安装或启用。
+- 保留 0.2.1-alpha.2 支持，并同步安装说明与中英日插件描述。
+
+<a id="v022-en"></a>
+**English** · [简体中文](#v022-zh)
+
+### 🐛 Bug Fixes
+
+- Correct the DSH Desktop compatibility declaration to 0.2.0-rc.2 so the host plugin manager accepts installation and activation on that version.
+- Retain support for 0.2.1-alpha.2 and update installation instructions and Chinese, English and Japanese plugin descriptions.
+
+## 0.2.1 - 2026-10-14
+
+<a id="v021-zh"></a>
+**简体中文** · [English](#v021-en)
+
+### ✨ 新增功能
+
+- 模型检测改用 LM Fingerprint，通过随机数样本与参考库生成候选排名；独立选择已配置供应商与模型，默认带入当前会话模型。
+- 默认采样 3 次，支持 1 次初筛；单次输出上限默认 4,096 Token，可设为 1,024–16,384。支持预算确认、取消、超时与用量预算控制。
+- 内置指纹引擎与参考库，每日检查上游更新；代码与数据通过完整性和接口校验后共同启用，更新失败保留已验证版本，检测任务固定引擎版本。
+- 新增逐模型推理强度设置，支持关闭、极低、低、中、高、极高、最大七档，保留已有模型属性与参数映射；推理强度和高级模型选择器分别控制。
+
+### 🐛 问题修复
+
+- 检测停止、失败或重启后保留已发生用量，按任务与样本 ID 去重后计入统计，避免恢复历史结果时重复计数。
+- 参数变更使已确认预算失效，避免继续使用与当前设置不一致的检测计划。
+- 兼容读取已有控制设置与供应商配额缓存，查询失败时保留最近成功的数据和获取时间。
+- 单张供应商卡片刷新时，仅对应按钮显示加载状态；支持不同供应商并发刷新，失败提示局限于对应卡片，较旧响应不会覆盖其他供应商的新结果。
+- 配额页仅显示当前已有供应商，已移除供应商的历史缓存不再显示；刷新、重启和迟到响应不会恢复其卡片。
+
+### 🎨 体验优化
+
+- 展示候选排名、逐次采样状态及已发生用量，保留有效的部分样本。仅 3 个有效样本显示库内置信度，低于 75% 提示不足；排名和置信度不作为模型身份或能力证明。
+- 默认开启输出速度、模型推理强度、高级模型选择器和模型检测，关闭模型明细与分布、自动获取余额；查询间隔默认 10 分钟，自定义查询默认为空，保留已保存的个人设置。
+- 查询来源在浮层中编辑，已启用的自定义查询默认折叠。控制设置统一位于控制页，插件详情页提供简洁说明。
+- 配额页优先显示 DeepSeek，再按已开启账号的顺序展示账号积分与周期额度。
+
+### ⚠️ 其他变更
+
+- 不再提供旧版行为参考、KBF 导入／导出与能力基线测试。普通对话仍从 DSH 会话日志计数，读取模型目录、预算与历史结果不会启动推理。
+- 用量展示偏好保存于 usage-stats-display.json，查询与模型设置、供应商配额缓存保存于 usage-stats-quota-controls.json；检测历史与去重用量独立持久化。
+- 提供 protocolVersion: 1 的 dshUsageStats 服务，支持读取用量、模型速度、配额和控制设置。
+- 适配 DSH Desktop 0.2.1-alpha.2 和 0.2.1-rc.2，由宿主插件管理器拒绝不匹配版本的安装与启用。
+- 发布包包含指纹引擎、参考库、品牌资源、来源校验信息与第三方许可；使用 Undici 处理更新请求，使用 TypeScript 擦除上游引擎类型。
+- 补齐私人运行数据的忽略规则与发布隐私检查，校验版本、构建产物、第三方哈希及独立项目安装；提供版本安装包、通用安装包和 SHA256SUMS。
+
+<a id="v021-en"></a>
+**English** · [简体中文](#v021-zh)
+
+### ✨ New Features
+
+- Replace model detection with LM Fingerprint candidate rankings based on random-number samples and a reference library. Select a configured provider and model independently, with the current conversation model selected initially.
+- Use three samples by default or one for screening. The default per-sample output cap is 4,096 tokens, adjustable from 1,024 to 16,384, with budget confirmation, cancellation, timeouts and reported-usage limits.
+- Bundle the fingerprint engine and reference library and check upstream daily. Activate code and data together after integrity and interface checks; failed updates retain the verified version, and running tasks keep their engine version.
+- Add per-model reasoning settings with off, minimal, low, medium, high, xhigh and max levels. Preserve model properties and parameter mappings, and control reasoning features and the advanced model selector independently.
+
+### 🐛 Bug Fixes
+
+- Retain incurred detection usage after stops, failures and restarts, deduplicate it by task and sample ID, and avoid counting restored history twice.
+- Invalidate confirmed budgets when parameters change so a detection plan cannot run with mismatched settings.
+- Read existing control settings and provider quota caches compatibly, retaining the last successful data and fetch time after query failures.
+- Keep each provider's refresh indicator and errors on its own card, allow different providers to refresh concurrently, and prevent older responses from overwriting newer results from other providers.
+- Show quotas only for providers that still exist in the current configuration. Removed providers stay hidden despite cached balances, refreshes, restarts or delayed responses.
+
+### 🎨 Improvements
+
+- Show candidate rankings, per-sample status and incurred usage, retaining valid partial samples. Display library confidence only with three valid samples and warn below 75%; rankings and confidence do not prove model identity or capability.
+- Enable output speed, reasoning features, the advanced model selector and detection by default. Model breakdowns and automatic balance queries start off, the query interval starts at ten minutes, and custom queries start empty while saved preferences remain available.
+- Edit query sources in an overlay and collapse enabled custom queries by default. Keep settings together in Controls and provide a concise plugin description.
+- Show DeepSeek first in Quotas, followed by enabled accounts in their configured order, including account credits and quota windows.
+
+### ⚠️ Other Changes
+
+- Remove the earlier behavioral references, KBF import/export and capability baseline tests. Conversation usage still comes from DSH session logs; reading catalogs, budgets or saved results never starts inference.
+- Store display preferences in usage-stats-display.json and query/model settings and provider quota caches in usage-stats-quota-controls.json. Persist detection history and deduplicated usage separately.
+- Expose the dshUsageStats host service with protocolVersion: 1 for usage, model speed, quotas and control settings.
+- Support DSH Desktop 0.2.1-alpha.2 and 0.2.1-rc.2, with the host plugin manager rejecting installation and activation on mismatched versions.
+- Ship the fingerprint engine, reference library, brand assets, source checksums and third-party licenses. Use Undici for updates and TypeScript to erase upstream engine types.
+- Exclude private runtime data and validate release privacy, versions, generated files, third-party hashes and installation in an isolated project. Provide a versioned archive, a generic archive and SHA256SUMS.
 
 ## 0.2.0 - 2026-10-05
 

package/NOTICE

@@ -0,0 +1,39 @@
+dsh-usage-stats — third-party notices
+
+Apache-2.0; see LICENSE. The read-only quota UI uses the brand assets described below.
+
+1. Bundled brand artwork
+------------------------
+
+Provider and model logos are shipped locally as data URIs. Source revisions
+and licence texts are recorded under third_party/brand-icons. Artwork comes
+from Ebony-Vinyl/dsh-our-free-model (MIT), LobeHub/lobe-icons (MIT), and the
+Simple Icons collection (CC0) distributed by react-icons (MIT). Kilo,
+LobsterAI, Loomy and fallback glyphs are locally drawn identifiers. Only logo
+assets from dsh-our-free-model are redistributed. Brand names and logos belong
+to their owners; no affiliation is implied.
+
+2. LM Fingerprint engine and reference data (MIT)
+------------------------------------------------
+
+Source: https://github.com/Ikaleio/lm-detector
+Package: lmfpd 0.0.1791719537634
+Commit: 2d71e10cec030ca786dcbcd14eba84edb4ecf10c
+Copyright (c) 2026 xqy2006
+
+Official shared modules and the published reference bank/detector are bundled
+under third_party/lm-fingerprint. Its verbatim MIT licence, source revision,
+package integrity and per-file hashes ship in LICENSE and UPSTREAM.json.
+TypeScript type erasure and relative import extensions are the only source
+transformations. The upstream CLI, web proxy and third-party skill wrapper
+are not redistributed. Verified updates use the same source and licence.
+
+The detection result layout and confidence bars are adapted from the same
+project's web/src/components/result-panel.tsx and web/src/index.css (MIT),
+using DSH theme tokens, localized sample status and bounded partial results.
+https://lm.ikale.io/docs/web/ describes the upstream result semantics.
+
+3. Runtime dependencies
+------------------------
+
+undici (MIT) provides proxy-aware updates. TypeScript 5.9.3 (Apache-2.0) erases upstream engine types. Their licences are included by npm.

package/README.en.md

@@ -0,0 +1,187 @@
+<p align="center">
+  <img src="screenshots/icon.svg" alt="dsh-usage-stats" width="80" height="80">
+</p>
+
+<h1 align="center">dsh-usage-stats</h1>
+
+<p align="center">
+  <strong>See your token usage, balances, and provider quotas inside DSH.</strong><br>
+  A local usage dashboard for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness Desktop</a>.
+</p>
+
+<p align="center">
+  <a href="#installation"><img src="https://img.shields.io/badge/DSH-Desktop-2563eb?style=flat-square" alt="DSH Desktop"></a>
+  <a href="https://github.com/Jockjrop/dsh-usage-stats/releases/latest"><img src="https://img.shields.io/badge/release-v0.2.1-64748b?style=flat-square" alt="Plugin version 0.2.1"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache--2.0-22c55e?style=flat-square" alt="Apache 2.0 license"></a>
+</p>
+
+<p align="center">
+  <a href="README.md">简体中文</a><br>
+  <a href="https://github.com/Jockjrop/dsh-usage-stats/releases/latest">Download</a> ·
+  <a href="#features">Features</a> ·
+  <a href="#installation">Installation</a> ·
+  <a href="#usage">Usage</a> ·
+  <a href="#faq">FAQ</a> ·
+  <a href="CHANGELOG.md">Changelog</a> ·
+  <a href="https://github.com/Jockjrop/dsh-usage-stats/issues">Feedback</a>
+</p>
+
+<p align="center">
+  <a href="screenshots/usage.png"><img src="screenshots/usage.png" alt="Usage overview, hourly tokens and calendar heatmap" width="800"></a>
+</p>
+
+<p align="center"><sub>Today's usage, lifetime totals, and usage patterns.</sub></p>
+
+<table align="center">
+  <thead>
+    <tr><th align="center">Quotas</th><th align="center">Controls</th></tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td align="center"><a href="screenshots/quotas.png"><img src="screenshots/quotas.png" alt="Provider balances and account credits" width="400"></a></td>
+      <td align="center"><a href="screenshots/controls.png"><img src="screenshots/controls.png" alt="Model features, display preferences and query sources" width="400"></a></td>
+    </tr>
+    <tr>
+      <td align="center">Check provider balances, account credits and quota windows.</td>
+      <td align="center">Set model features, display preferences and custom quota queries.</td>
+    </tr>
+  </tbody>
+</table>
+
+<p align="center">
+  <a href="screenshots/detection.png"><img src="screenshots/detection.png" alt="Detection candidates, library confidence and sample status" width="800"></a>
+</p>
+
+<p align="center"><sub>LM Fingerprint candidate rankings, sample status and incurred usage.</sub></p>
+
+## Features
+
+| Tab | What you can do |
+| --- | --- |
+| **Usage** | View today's and lifetime tokens, active days, hourly calls, daily/weekly heatmaps, trends, model breakdowns and output speed. |
+| **Quotas** | Check provider balances, account credits and quota windows, with manual or scheduled refresh and custom queries. |
+| **Detection** | Select a provider and model independently, confirm a budget, then run LM Fingerprint sampling and review candidate rankings, sample status and history. |
+| **Controls** | Adjust display preferences, quota query settings, the advanced model selector and per-model reasoning levels. |
+
+- **Follow usage trends:** browse daily/weekly heatmaps, switch between 7/30-day trends and compare providers and models.
+- **Compare output speed:** rank models by TPS and show average time to first token (TTFT); samples without valid timing are excluded from speed rankings.
+- **Refresh quotas on demand:** use DSH credentials for configured providers. Account quotas require the corresponding plugin or host service. Automatic refresh is off by default.
+- **Run independent detection:** use three samples by default or one for screening. Confirm the budget before manually starting; cancellation, timeouts and usage budgets are supported.
+- **Adjust model settings:** control the advanced model selector and reasoning features independently while retaining model properties, parameter mappings and saved preferences.
+- **Follow the application language:** Chinese, English and Japanese UI text follows DSH's selected language; custom names and quota labels remain unchanged.
+
+Detection compares random-number samples with a reference library. Rankings and library confidence measure similarity to known candidates; they do not prove model identity or capability. Reading catalogs, budgets or saved results does not start inference.
+
+## Installation
+
+Plugin version **0.2.2** requires **DSH Desktop `0.2.1-alpha.2` or `0.2.0-rc.2`**. The host plugin manager rejects installation or activation on a mismatched runtime.
+
+**Recommended: install the [npm package `@sligqoer/dsh-usage-stats`](https://www.npmjs.com/package/@sligqoer/dsh-usage-stats) through DSH Desktop.** It includes prebuilt modules, needs no Git checkout or local build, and supports Check updates when installed by package name.
+
+### 1. Open the plugin installer
+
+In DSH Desktop's main sidebar, open **Plugins → Add plugin**.
+
+### 2. Enter the full npm package name
+
+```text
+@sligqoer/dsh-usage-stats
+```
+
+Paste it into **Package name or address**, click **Install**, and keep the full `@sligqoer/` scope.
+
+### 3. Enable and open
+
+Click **Enable now**, then open **Settings → Usage Stats**. Fully exit and reopen DSH Desktop when the plugin manager requests a restart.
+
+<details>
+<summary>Install a specific version or a downloaded archive</summary>
+
+Enter this in the same installer for this release:
+
+```text
+@sligqoer/dsh-usage-stats@0.2.1
+```
+
+Alternatively, download a `.tgz` and `SHA256SUMS` from the [GitHub release page](https://github.com/Jockjrop/dsh-usage-stats/releases/latest), verify the hash and enter the archive's local absolute path. Do not extract it before installation.
+
+```powershell
+Get-FileHash ./sligqoer-dsh-usage-stats-0.2.1.tgz -Algorithm SHA256
+```
+
+Assets include `sligqoer-dsh-usage-stats-0.2.1.tgz`, the equivalent `dsh-usage-stats.tgz`, and `SHA256SUMS`. Both archives contain identical modules.
+
+</details>
+
+<details>
+<summary>Updates and migration</summary>
+
+Use **Check updates** for installations made by npm package name. Installations from GitHub URLs, archives or local paths require a new manual installation.
+
+If you use the old `dsh-usage-stats` package name, uninstall it once and install `@sligqoer/dsh-usage-stats`. Saved settings and usage remain available. See [CHANGELOG.md](CHANGELOG.md) for upgrade changes.
+
+</details>
+
+## Usage
+
+1. Open Usage for the overview, trends, heatmaps and output speed. Use Controls to adjust model breakdown and speed visibility.
+2. Refresh provider or account cards in Quotas. Automatic refresh is off by default; enable it in Controls after confirming the notice.
+3. Select a provider and model in Detection, set sample counts and output limits, confirm a budget, then start manually. Reading catalogs or saved results never starts detection.
+4. Use Controls to toggle the advanced model selector, reasoning features and detection independently, or edit custom quota queries.
+
+## Data and compatibility
+
+Local data is stored under `DSH_HOME/storages`:
+
+| File or directory | Contents |
+| --- | --- |
+| `usage-stats-corpus.json` | Session usage aggregates. |
+| `usage-stats-display.json` | Usage display preferences. |
+| `usage-stats-quota-controls.json` | Query and model settings plus provider quota caches. |
+| `usage-stats-detections.json` | Detection results and reported sample usage. |
+| `usage-stats-lm-fingerprint/` | Verified engine and reference updates. |
+| `usage-stats-supplemental.json` | Detection usage deduplicated by task and sample ID and retained across restarts. |
+
+Conversation tokens come from DSH session logs. Detection usage is deduplicated by task and sample ID before aggregation. Request diagnostics are excluded from token totals. Updates retain saved configuration and usage history.
+
+After upgrading from 0.2.0, detection uses LM Fingerprint. The earlier behavioral references, KBF import/export and capability baseline tests are no longer provided; previously incurred detection usage remains available. Release packages exclude personal sessions, account credentials, quota caches and detection history.
+
+## FAQ
+
+**Does it work in DSH Web?**
+
+This version supports only DSH Desktop's desktop profile.
+
+**Why is a quota card missing or unavailable?**
+
+Check provider configuration, credentials, enabled account plugins and support for the quota API. A model API key may not have billing permissions.
+
+**Are token totals a bill?**
+
+No. Token totals come from local sessions and reported detection usage. Balances and quota windows come from provider APIs.
+
+**Can detection rankings prove model identity?**
+
+No. Rankings measure similarity to the reference library. When the requested model is outside the library, candidates serve only as comparisons.
+
+## API
+
+The `dshUsageStats` host service uses `protocolVersion: 1` and exposes `readStats`, `readControls`, `updateControls`, `readProviderQuotas` and `readSupplementalUsage`.
+
+HTTP routes under `/api/dsh-usage-stats/*` provide statistics, controls, quotas and detection. They require loopback access and trusted origins and disable caching.
+
+## Development
+
+Use Node.js 24 and the dependencies pinned in `package-lock.json`:
+
+```sh
+npm ci
+npm run build
+npm test
+npm run check:release
+npm run release
+```
+
+Edit `src/` and run `npm run build` to generate `lib/`. `npm run check:release` checks versions, generated files, third-party integrity and private workspace files. `npm run release` builds the package and verifies installation and loading in an isolated temporary project; artifacts go to `release/`.
+
+The GitHub workflow requires the tag to match the package version (`v0.2.1` for this release) and publishes the same verified archive to npm and GitHub Releases. The npm trusted publisher workflow file is `.github/workflows/release.yml`. Third-party assets, source revisions and licenses are recorded in `third_party/` and [NOTICE](NOTICE). This project uses the [Apache-2.0 license](LICENSE).