@kenz1117/dsh-ui-usage-billing 1.0.25 → 1.0.26

package/README.en.md

@@ -8,6 +8,7 @@
   <a href="https://github.com/kenz1117/dsh-ui-usage-billing/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/kenz1117/dsh-ui-usage-billing?logo=github"></a>
   <a href="https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing"><img alt="npm version" src="https://img.shields.io/npm/v/@kenz1117/dsh-ui-usage-billing?logo=npm"></a>
   <a href="https://www.npmjs.com/package/@kenz1117/dsh-ui-usage-billing"><img alt="npm downloads" src="https://img.shields.io/npm/dm/@kenz1117/dsh-ui-usage-billing?logo=npm"></a>
+  <a href="https://github.com/kenz1117/dsh-ui-usage-billing/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/kenz1117/dsh-ui-usage-billing/actions/workflows/ci.yml/badge.svg"></a>
   <a href="https://github.com/kenz1117/dsh-ui-usage-billing/blob/main/LICENSE"><img alt="License MIT" src="https://img.shields.io/github/license/kenz1117/dsh-ui-usage-billing"></a>
   <a href="https://github.com/kenz1117/dsh-ui-usage-billing/pulls"><img alt="PRs welcome" src="https://img.shields.io/badge/PRs-welcome-brightgreen"></a>
   <a href="https://github.com/kenz1117/dsh-ui-usage-billing"><img alt="GitHub last commit" src="https://img.shields.io/github/last-commit/kenz1117/dsh-ui-usage-billing?logo=github"></a>
@@ -38,6 +39,17 @@
 - **Offline & self-contained** — no chart library, no external CDN, pure design tokens; lightweight and ready to use.
 - **Multi-language + dual currency** — Chinese / English, ¥/$ toggle that only affects this plugin.
 
+## ⚖️ How it differs from similar plugins
+
+Peer plugins (cost-meter, usage-stats, dsh-bill, …) each have their strengths; this plugin's positioning:
+
+- **Live pricing sources** — a real-time models.dev catalog + a built-in catalog of 73 models across 24 vendors + user-defined prices in the settings panel (bindable per relay origin); new models don't wait for a hand-edited price table.
+- **History is never recomputed** — every call is priced at its own moment, segmented by official change boundaries (base price before 08-17 → peak/off-peak v1 → weekend all-day off-peak from 08-23); pre-install history is backfilled from existing session logs, and later price changes never rewrite old bills.
+- **Not just "how much" but "on what"** — input split by cache hit/miss (including reasoning), official vs third-party buckets, drill-down by workspace/session/relay site, per-turn cost-spike attribution; plus a performance panel few peers offer (per-model TTFT mean/P50/P90 and generation speed).
+- **Subscription & balance loop** — 7 official provider balances + Coding Plan quotas + relay-station balances and rolling quota windows + self-declared endpoints + cross-reconciliation between official balance deltas and the local ledger.
+- **Uncatalogued models stay visible** — they are explicitly marked "uncatalogued" and counted in the Hero hint; a custom price takes effect immediately instead of silently billing 0 or charging the wrong model's rate.
+- **The model can check for itself** — an optional `usage_stats` tool lets the model answer "what did I spend today" or "which site used the most".
+
 ## 📊 Dashboard
 
 - **Sidebar entry**: a dashboard-style trigger card above the Settings button — month cost as the headline number (monospace) with a 7-day sparkline mini-trend, second line "Today / This week"; collapses to an icon button; hover reveals a quick-look card.
@@ -206,6 +218,16 @@ npm publish --access public
 
 The host discovers the browser side automatically via the `dsh.client` declaration (`platform: web`) and the `exports["./client"]` bundle in `package.json` — no registry registration needed.
 
+## 🔐 Permissions & Compatibility (DSH STORE)
+
+- **Permission level: high**: reads durable session logs (files), calls official multi-vendor / subscription / balance / pricing APIs (network), reads `apiKeyEnv` via the credentials seam (credentials), writes the ledger under `~/.dsh` (persistent state); **no** command execution / shell.
+- **Update channel: `user-reviewed`**: with file / network / credential capabilities, DSH STORE requires local manual confirmation on every install; review the repo, pinned commit, lifecycle scripts, and impact scope before installing.
+- **Compatibility**: the preview line (npm `latest`/`alpha`, 1.0.x) targets DSH `0.1.2` (including `0.1.2-rc.1`); the stable line (npm `stable`, 1.1.x) targets legacy hosts `0.1.0-rc.8` ~ `0.1.1-rc.2`. Per-version declarations live in `package.json` under `dsh.compatibility`; the two-line mapping and monitoring mechanism are documented in [COMPATIBILITY.md](COMPATIBILITY.md). Node.js `^22.19.0 || >=24.0.0`.
+- **Lifecycle**: no `preinstall` / `install` / `postinstall` / `prepare` (ready on install).
+- **No impersonation**: adds only its own entry id `ui-usage-billing`; `@deepseek-ai/dsh-*` packages are `peerDependencies` only (no reinstall / replace / shadowing of official components); the package uses the third-party namespace `@kenz1117/*`.
+- **Build artifacts**: runtime files `lib/*` and `cordis.patch.yml` are committed at the pinned commit and declared in `files`.
+- **Source anchor**: sources are locked to a pinned commit on the GitHub default branch and traceable. DSH STORE automation re-reads the default-branch HEAD roughly every 8 hours as the new pinned commit and decides re-review by SemVer change.
+
 ## 🤖 Model Experience
 
 None. This plugin is a pure UI surface: it registers no tools, injects no system prompt, writes no model-visible events to the session log, and touches no session KV cache; usage statistics are aggregated by the server from existing session logs, whose content is owned by other packages.

package/README.md

@@ -38,6 +38,17 @@
 - **离线自包含** — 无图表库、无外部 CDN、纯设计令牌；依赖极轻，随装随用。
 - **多语种 + 双币种** — 中文/English、¥/≈$ 切换，只对本插件生效。
 
+## ⚖️ 与同类计费插件的差异
+
+同类插件（cost-meter、usage-stats、dsh-bill 等）各有所长，本插件的定位差异如下：
+
+- **价格来源是活的** — models.dev 实时目录 + 内置 24 厂商 73 款模型目录 + 设置面板自定义单价（可按中转站来源绑定同模型不同价），新模型无需等待手填价表。
+- **历史永不重算** — 费用按事件发生时刻的价格计价，并按官方变更节点分段（8-17 前基础价 → 峰谷 v1 → 8-23 起周末全谷）；安装前的历史用量从既有会话日志自动回填，价格调整不回写旧账。
+- **不止「花了多少」，还答「花在哪」** — 输入按缓存命中/未命中分桶（含 reasoning）、官方/三方分桶、按工作区/会话/中转站下钻、每轮成本突增归因；还有同类少有的性能面板（各模型 TTFT 均值/P50/P90 与生成速度）。
+- **订阅与余额闭环** — 7 家官方余额 + Coding Plan 额度 + 中转站余额与滚动额度窗口 + 自声明端点 + 官方余额变动与本地账本的交叉对账。
+- **目录外模型不静默** — 未收录模型显著标注「未收录」并在 Hero 区提示数量，自定义单价填入即生效，不会被静默计 0 或错按其他模型价格。
+- **模型可自查** — 可选的 `usage_stats` 工具让模型直接回答「今天花了多少」「哪个站点用得最多」。
+
 ## 📊 仪表盘
 
 - **侧边栏入口**：设置按钮上方的仪表盘式触发卡——本月费用主数字（等宽字体）+ 近 7 天 sparkline 迷你趋势，副行「今日 / 本周」；折叠栏自动切为图标钮；悬停浮现速览卡。
@@ -224,11 +235,11 @@ npm publish --access public
 
 - **权限等级：high**：读取持久会话日志（文件）、访问多厂商官方 / 订阅 / 余额 / 定价 API（网络）、经凭据 seam 读取 `apiKeyEnv`（凭据）、写入 `~/.dsh` 账本（持久状态）；**不含**命令执行 / Shell。
 - **更新通道：`user-reviewed`**：本插件具备文件 / 网络 / 凭据能力，DSH STORE 采用每次安装需本机人工确认的通道；安装前请复核仓库、固定 Commit、生命周期脚本与影响范围。
-- **兼容范围**：DSH `0.1.2-alpha.1` 起声明为 `compatible`（见 `package.json` 的 `dsh.compatibility.dshReleases`）；旧宿主（`0.1.0-rc.8` ~ `0.1.1-rc.2`）请停留在 v1.0.11。Node.js `^22.19.0 || >=24.0.0`。
+- **兼容范围**：预览线（npm `latest`/`alpha`，1.0.x）适配 DSH `0.1.2` 系（含 `0.1.2-rc.1`）；稳定线（npm `stable`，1.1.x）适配旧宿主 `0.1.0-rc.8` ~ `0.1.1-rc.2`。逐版本声明见 `package.json` 的 `dsh.compatibility`，双线对照与监控机制见 [COMPATIBILITY.md](COMPATIBILITY.md)。Node.js `^22.19.0 || >=24.0.0`。
 - **生命周期**：无 `preinstall` / `install` / `postinstall` / `prepare`（安装即用）。
 - **不冒用官方**：仅新增自有 entry id `ui-usage-billing`；对 `@deepseek-ai/dsh-*` 仅为 `peerDependencies` 依赖（不重复安装 / 不替换 / 不遮蔽官方组件），包名使用第三方命名空间 `@kenz1117/*`。
 - **打包产物**：运行文件 `lib/*` 与 `cordis.patch.yml` 已随固定 Commit 提交并声明在 `files`。
-- **源码锚点**：源码以 GitHub 默认分支上的固定 Commit 锁定并可追溯；例如 v1.0.13 对应 `c8e2a325689fb823d90c5c44857e6224465ea6cf`。DSH STORE 自动化每约 8 小时重新读取默认分支 HEAD 作为新的固定 Commit，并按 SemVer 变更判定是否重新审查。
+- **源码锚点**：源码以 GitHub 默认分支上的固定 Commit 锁定并可追溯；例如 v1.0.13 对应 `efd67dea133a4fee0aacfee8dff416f1ce418b14`。DSH STORE 自动化每约 8 小时重新读取默认分支 HEAD 作为新的固定 Commit，并按 SemVer 变更判定是否重新审查。
 
 ## 🤖 Model Experience