dsh-token-gauge 0.1.10 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 dsh-token-gauge contributors
+Copyright (c) 2026 liumiaozhi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.en.md

@@ -1,67 +1,95 @@
 # dsh-token-gauge · Token Gauge Dashboard
 
-A DeepSeek Harness (DSH) Web sidebar plugin that shows Token usage and cost on a **motorcycle-style dashboard**.
-The needle rotates smoothly as usage grows; usage and cost figures sit below the needle. Click ⚙ to open a settings
-popup to switch style, palette, displayed metrics, usage scope, limits (global/daily/weekly/monthly), language, and export reports.
+<p align="center">
+  <img src="screenshots/single-classical.png" alt="Single gauge · Vintage skin" width="48%">
+  <img src="screenshots/dual-starfield.png" alt="Dual gauge · Starfield skin" width="48%">
+</p>
 
-> Default style: **Modern EV Tech** · Default palette: **Neon Blue** · Default metric: **global cumulative**.
+<p align="center">
+  <img src="screenshots/styles.png" alt="Vintage / Macaron / Minimal / Starfield skins" width="78%">
+</p>
+
+<p align="center">
+  <a href="https://github.com/liumiaozhi/dsh-token-gauge/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/liumiaozhi/dsh-token-gauge?style=flat-square"></a>
+  <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/github/license/liumiaozhi/dsh-token-gauge?style=flat-square"></a>
+  <img alt="DeepSeek Harness" src="https://img.shields.io/badge/DeepSeek%20Harness-Web%20Plugin-4f46e5?style=flat-square">
+</p>
+
+A sidebar Token gauge for **DeepSeek Harness (DSH)**. Four skins — Vintage, Macaron, Minimal and Starfield — turn token speed, session/today usage and spend, and cache hit rate into a quick car-dashboard read.
+
+> Preview images use sample data. Real values are aggregated from local DSH session logs; nothing is fabricated.
 
 ## Features
 
-- **Live gauge**: SVG arc gauge; needle rotates with `usage / limit`; turns red when over limit.
-- **6 styles**: Modern EV Tech (default), Raw Motorcycle, Luxury Sports, Cute Car, Cyberpunk, Retro Dial.
-- **8 palettes**: Amber Gold, Neon Blue, Track Red, Aurora Green, Sakura Pink, Night Purple, Titanium Silver, Volcano Orange (freely combinable with styles).
-- **Usage & cost**: total tokens, cost (¥), plus optional cards (input/output, cache hit, sessions, today, quota progress).
-- **Limits**: global / daily / weekly / monthly (default global = empty → auto scale).
-- **i18n**: one-click zh / en.
-- **Export**: one-click CSV / JSON usage reports (global, per-model, per day/week/month/session).
-- **Zero runtime deps**: Client is pure DOM/SVG (no React); Host listens to DSH usage events and aggregates on its own.
+- **Two structures**
+  - **Single**: token-speed gauge on the left, current-session / today tokens and spend on the right, cache-hit progress bar at the bottom.
+  - **Dual**: token-speed gauge and cache-hit gauge side by side on top; current-session and today tokens / spend below.
+- **Four skins**: Vintage (warm amber), Macaron, Minimal, Starfield. Structure and skin combine freely — eight presentations.
+- **Live speed**: reads streaming output deltas from the current session and moves the needle smoothly across 0–500 tokens/s.
+- **Cache gauge**: 70–100% range with 70 / 75 / 100 ticks; below 70% the needle parks at 70% while the readout keeps the real value.
+- **Token formatting**: always in **k (thousand tokens)**, two decimals and thousands separators, e.g. `15,098.77k`.
+- **Settings**: the slider icon at the card's top-right opens structure/skin choices; selections persist in `localStorage`.
+- **Theme-aware** and dependency-free: no billing plugin, no chart library, no external CDN. The Host half aggregates DSH session logs itself.
 
 ## Install
 
-> **Pin the version**: `dsh plugin add` is backed by pnpm and can be affected by mirror sync lag (e.g. npmmirror).
-> A bare `add dsh-token-gauge` may resolve `0.1.0` under `^0.1.0` — that old build lacks `dsh.bundle`, so it installs
-> as a plain dependency (no bundle layer, no sidebar tab). **Pin `0.1.1` to avoid this**:
+The plugin ships its own Host half: it reads DSH's `sessionPersistence` logs and aggregates usage locally. **No billing plugin is required.**
+
 ```bash
-# From marketplace (recommended — pin to avoid resolving to the legacy 0.1.0)
-dsh plugin --profile web add dsh-token-gauge@0.1.1
-dsh web
-
-# From source
-npm install
-node build.mjs
-dsh plugin --profile web add .
+dsh plugin --profile web add dsh-token-gauge
 ```
 
-### Migrating from legacy 0.1.0
+From source (current repository version):
 
-If you already installed `0.1.0` (no `token-gauge` layer in `dsh.profile.bundles`, warning `declares no dsh.bundle —
-installed as a plain dependency`), switch with:
 ```bash
-dsh plugin --profile web remove dsh-token-gauge
-dsh plugin --profile web add dsh-token-gauge@0.1.1
+git clone https://github.com/liumiaozhi/dsh-token-gauge.git
+dsh plugin --profile web add "link:<absolute-path-to-repo>"
 ```
-After reconcile, `token-gauge` is added as a bundle layer automatically; restart `dsh web` to see the **Token Gauge** tab.
 
-## Data & pricing
+> If npm still serves an older `dsh-token-gauge`, install from source until 1.1.0 is published.
+
+Restart or hard-refresh DSH Web. The card replaces the original billing trigger at the same sidebar-footer slot without needing that plugin.
+
+## Usage
 
-- **Source**: Host subscribes to `assistant/message.usage` in the DSH session event stream and aggregates it.
-- **Views**: global / daily / weekly / monthly / session / model.
-- **Cost**: `(missInput×inMiss + cacheHit×inHit + cacheWrite×write + output×out) / 1,000,000` (¥/M tokens).
-  Ships DeepSeek official CNY presets, editable per model in settings (advanced · pricing).
+1. Click the slider icon at the **top-right** of the card.
+2. Choose **Single / Dual** under Layout.
+3. Pick one of **Vintage / Macaron / Minimal / Starfield**.
+4. Start a conversation; speed follows streaming output and usage refreshes every 1.5s.
 
-## Settings (⚙ popup)
+<p align="center">
+  <img src="screenshots/settings.png" alt="Settings: layout and four skins" width="62%">
+</p>
 
-Language · Style · Palette · Metric (global/session/today/daily/weekly/monthly) · Display toggles ·
-Limits (global/daily/weekly/monthly) · Advanced pricing · Export CSV/JSON · Clear / Reset.
+## Data
 
-## Publish
+| Metric | Source |
+| --- | --- |
+| Token speed | Streaming text / reasoning / tool-call deltas of the current session, estimated over a 0–500 tokens/s scale |
+| Current-session tokens | `input + output` over all turns of the current session |
+| Today tokens | Today's `input + output` from the plugin's own `byDay` aggregate |
+| Current-session spend | Estimated from successful model calls in the current session |
+| Today spend | Estimated from DeepSeek Flash / Pro list prices with peak/off-peak bands |
+| Cache hit rate | Today's `cacheHit / (cacheHit + cacheMiss)`, gauge range 70–100% |
+
+The Host half reads `assistant/message.usage` from DSH `sessionPersistence`, adds 0.02 CNY per web-search call, and prices DeepSeek Flash (2 / 0.04 / 8 CNY per million tokens) and Pro (9 / 0.3 / 27). Peak hours are weekdays 09–12 and 14–18; weekends and off-peak are half price. Unknown models fall back to Flash rates. Amounts are estimates, not an official invoice.
+
+## Development
 
 ```bash
-npm version patch
-npm publish --registry=https://registry.npmjs.org
+git clone https://github.com/liumiaozhi/dsh-token-gauge.git
+cd dsh-token-gauge
+dsh plugin --profile web add "link:$PWD"
 ```
 
+`client.js` is a hand-written Client bundle; no build step. DSH Client HMR reloads it after edits; refresh the page if HMR is unavailable.
+
+## Compatibility
+
+- DSH Web (`platform: web`), requiring `@deepseek-ai/dsh-client-ui-sidebar` and `@deepseek-ai/dsh-client-ui-session`.
+- Host half uses DSH's built-in `sessionPersistence` and `webServer`; no billing plugin.
+- Preview images are generated from the actual component styles with sample data.
+
 ## License
 
-MIT
+[MIT](LICENSE) © 2026 liumiaozhi

package/README.md

@@ -1,129 +1,115 @@
-# dsh-token-gauge · Token 机车仪表盘
+# dsh-token-gauge · 费用仪表盘
 
-DeepSeek Harness（DSH）Web 侧边栏插件：以「机车风格仪表盘」实时展示 Token 用量与费用。
-指针随用量增长平滑转动，下方显示用量与费用数字；点击 ⚙ 打开设置弹窗，可切换风格、配色、显示内容、用量口径、限额（全局/日/周/月）、语言并导出用量报表。
+<p align="center">
+  <img src="screenshots/single-classical.png" alt="单表 · 古典风格" width="48%">
+  <img src="screenshots/dual-starfield.png" alt="双表 · 星空风格" width="48%">
+</p>
 
-> 默认风格：**现代电车科技**；默认配色：**霓虹蓝**；默认用量口径：**全局累计**。
+<p align="center">
+  <img src="screenshots/styles.png" alt="古典 / 马卡龙 / 极简 / 星空四种皮肤" width="78%">
+</p>
 
-## 特性
+<p align="center">
+  <a href="https://github.com/liumiaozhi/dsh-token-gauge/stargazers"><img alt="GitHub stars" src="https://img.shields.io/github/stars/liumiaozhi/dsh-token-gauge?style=flat-square"></a>
+  <a href="LICENSE"><img alt="License MIT" src="https://img.shields.io/github/license/liumiaozhi/dsh-token-gauge?style=flat-square"></a>
+  <img alt="DeepSeek Harness" src="https://img.shields.io/badge/DeepSeek%20Harness-Web%20Plugin-4f46e5?style=flat-square">
+  <img alt="Token Gauge" src="https://img.shields.io/badge/UI-Token%20Gauge-0ea5e9?style=flat-square">
+</p>
 
-- **实时仪表盘**：SVG 弧形表盘，指针随 `用量 / 限额` 比值转动；超限进入红色危险区并提示。
-- **多风格（6 种）**：现代电车科技（默认）、原始机车、豪华跑车、可爱小车、赛博朋克、复古机械表盘。
-- **多配色（8 种）**：琥珀金、霓虹蓝、赛道红、极光绿、樱粉、暗夜紫、钛银、火山橙。风格与配色可自由组合。
-- **用量与费用**：显示总 Token、费用（¥），并可开启输入/输出、缓存命中、会话数、今日用量、限额进度等副卡片。
-- **限额**：支持全局 / 日 / 周 / 月 四类限额（默认全局为空=自动量程）。指针按所选口径对限额扫动。
-- **中英文界面**：设置内一键切换 zh / en。
-- **导出报表**：一键导出 CSV / JSON 用量明细（全局、分模型、按日/周/月/会话）。
-- **侧边栏 Tab**：通过 `dsh-better-sidebar` 注册（稳定版 0.1.1-rc.x 唯一的外部 Tab 入口，web profile 需已安装）；Client 半边将 react 打进 bundle，无需额外运行时。Host 半边监听 DSH 会话用量事件自行累计，可独立发布。
+一个给 **DeepSeek Harness（DSH）** 用的侧边栏 Token 费用仪表盘。用老式车机 / 马卡龙 / 极简 / 星空四种皮肤，把 Token 输出速度、当前会话与今日消耗、缓存命中率做成一眼能读懂的仪表。
 
-## 安装
+> 界面预览使用示例数据；实际数据来自 DSH 本地会话日志聚合，不伪造样本。
 
-> **兼容性**：本插件面向 **DSH 0.1.1-rc.1 / 0.1.1-rc.2（稳定版）**。采用 `dsh.bundle.patch` 清单 + `cordis.patch.yml` 注册，符合稳定版的插件机制（不兼容新版 0.1.2-alpha 的 `dsh.host/client` 清单）。
-> **前置依赖 `dsh-better-sidebar`**：本插件的 Tab 通过 `ctx.betterSidebar.registerTab` 注册到它的**右侧工作台**，所以它必须是 **profile 的直接依赖、且已挂进 `dsh.profile.bundles`**：
->
-> `dsh plugin --profile web add dsh-better-sidebar`
->
-> ⚠️ **陷阱（很常见）**：它若只是本插件的**传递依赖**，只会被装进 `node_modules` 而**不会**被挂成 bundle 层 —— 加载树里没有条目、`betterSidebar` 服务不会被 provide，表现就是本插件「已启用 / 已挂载」却没有任何侧边栏 Tab，**而且全程零报错**（0.1.7 起会在浏览器控制台打出明确指引）。同理请确认 `cordis.patch.yml` 与 `.dsh-market/state.json` 没有把它列为 `disabled`。
->
-> 另注：Tab 注册后会出现在侧边栏 **「+ 新建 Tab」菜单**里（这是 better-sidebar 的设计：注册的是 tab *类型*，需你点开一次才会出现在标签栏），详见下方「排查」。
+## 特性
 
-### 方式一：从市场安装（推荐）
+- **两种结构**
+  - **单表**：左侧 Token 速度仪表盘，右侧当前会话 / 今日 Token 与金额，底部缓存命中率进度条。
+  - **双表**：上方左侧 Token 速度、右侧缓存命中率两个仪表盘；下方并列展示当前会话与今日的 Token 量、金额。
+- **四种皮肤**：古典（老式车机琥珀色）、马卡龙、极简、星空。结构 × 皮肤可自由组合，共 8 种呈现。
+- **实时 Token 速度**：读取当前会话的流式输出增量，指针在 0–500 token/秒之间平滑摆动。
+- **缓存命中率表盘**：量程 70–100%，刻度 70 / 85 / 100；低于 70% 时指针停在 70%，中央数字仍显示真实值。
+- **Token 口径**：统一以 **k（千 token）** 显示，保留两位小数并带千分位，例如 `15,098.77k`。
+- **设置入口**：卡片右上角滑杆图标；选择结构与皮肤后立即生效，并写入 `localStorage`，刷新后保留。
+- **主题自适应**：颜色来自 DSH 主题令牌，深浅色模式均可读；不引入图表库、不请求外部 CDN。
 
-> **强烈建议钉版本安装**：`dsh plugin add` 底层是 pnpm，受你本地 `.npmrc` 指向的镜像（如 npmmirror）同步延迟影响，裸 `add dsh-token-gauge` 在 `^0.1.0` 范围内可能解析到尚未带 `dsh.bundle` 的旧版 `0.1.0`（装上去只会是普通依赖、不进 bundle 层、侧边栏不出现）。**显式钉 `0.1.7` 可彻底规避这一坑**：
-```bash
-dsh plugin --profile web add dsh-token-gauge@0.1.7
-dsh web
-```
-> 若想装最新版，可先 `dsh plugin --profile web update dsh-token-gauge` 升级，再确认 `node_modules/dsh-token-gauge/package.json` 的 `dsh.bundle.patch` 字段存在。
+## 安装
 
-### 从旧版 0.1.0 迁移
+本插件自带 Host 半边，直接从 DSH 的 `sessionPersistence` 读取本地会话日志并聚合用量，**不依赖任何计费插件**。
 
-若此前已误装 `0.1.0`（表现为 `dsh.profile.bundles` 未新增 `token-gauge` 层，并出现 `declares no dsh.bundle — installed as a plain dependency` 警告），按下面两步切换即可，无需手动改 bundles：
 ```bash
-dsh plugin --profile web remove dsh-token-gauge
-dsh plugin --profile web add dsh-token-gauge@0.1.7   # 钉版本，避免又解析回 0.1.0
+dsh plugin --profile web add dsh-token-gauge
 ```
-装完后 `dsh.profile.bundles` 在 reconcile 时自动把 `token-gauge` 加为最后一层，重启 `dsh web` 后，在侧边栏 **「+ 新建 Tab」菜单**里选「Token 仪表盘」即可打开。
 
-### 方式二：本地源码安装
-```bash
-git clone <本仓库> dsh-token-gauge
-cd dsh-token-gauge
-npm install
-node build.mjs                 # 生成 lib/index.mjs 与 lib/client.mjs
-dsh plugin --profile web add . # 读取 package.json 的 dsh 字段
-dsh web
-```
-或在已运行 DSH 的情况下以本地 overlay 调试：
+从源码安装（本仓库当前版本）：
+
 ```bash
-node build.mjs
-dsh web --patch ./cordis.patch.yml
+git clone https://github.com/liumiaozhi/dsh-token-gauge.git
+dsh plugin --profile web add "link:<本仓库绝对路径>"
 ```
 
-安装后**完整重启** DSH Web（进程内 client 缓存只在重启时清空，硬刷新不够），然后在侧边栏点 **「+ 新建 Tab」→「Token 仪表盘」** 打开它。开始对话产生 Token 后，仪表盘即实时更新。
+> npm 上的 `dsh-token-gauge` 若仍为旧版，请先用源码安装；发布 1.1.0 后可直接按名称安装。
 
-### 排查：侧边栏 Tab 不出现
+安装后重启或硬刷新 DSH Web，侧边栏底部会出现「费用仪表盘」。插件以 slot 优先级覆盖原计费卡片，但不需要计费插件本身。
 
-DSH 把插件拆成 host（Node 端）与 client（浏览器端）两半，走不同机制。若装好却看不到 Tab，可分别验证：
+## 使用
 
-- **host 半边是否正常**：浏览器访问 `http://<dsh-host>/plugins/dsh-token-gauge/state` 应返回 200 + 状态 JSON，且 `~/.dsh-token-gauge/` 目录已生成。host 不工作通常是 bundle 层没挂上（`dsh.profile.bundles` 缺 `token-gauge`）。
-- **client 半边是否正常**：访问 `/plugins/dsh-token-gauge/client.js` 应返回 200（打包后的客户端脚本）；首页 `window.__DSH_BOOT__` 里应包含该 client。若此处 404，常见原因是 `package.json` 的 `exports` 未导出 `./package.json`——DSH 的 client 加载器用 `require.resolve('<包名>/package.json')` 定位 client 包，缺少该子路径导出会被静默判为「非 client 包」且（进程内）缓存。**本包已显式导出 `"./package.json"`，如遇此问题请确认装的是 0.1.2+**。
-- **`dsh-better-sidebar` 是否真的挂载了**（「已启用/已挂载却无 Tab」的头号原因）：Tab 挂在它的右侧工作台上。检查 `~/.dsh/profiles/web/package.json` 的 `dsh.profile.bundles` **和** `dependencies` 里是否**都**有 `dsh-better-sidebar` —— **只存在于 `node_modules` 不算**：作为传递依赖装进来的包不会被挂成 bundle 层，服务不会被 provide，于是本插件完全静默（0.1.7 起浏览器控制台会打出指引）。同时确认 `cordis.patch.yml` 与 `.dsh-market/state.json` 未把它标为 `disabled`。
-- **类型已注册，但标签栏里看不到**：`registerTab` 注册的是 tab **类型**，不会自动出现在标签栏 —— 需到侧边栏 **「+ 新建 Tab」菜单**点选「Token 仪表盘」打开一次。若菜单里也找不到，去看侧边栏**设置面板的 Tab 列表**：列表里有 = 注册成功只是没打开；列表里也没有 = 服务没拿到（回到上一条）。
-- 改动后务必**完整重启 `dsh web`**（进程内 client 缓存只在重启时清空），仅硬刷新不够。
+1. 点击卡片**右上角**的滑杆图标打开设置。
+2. 在「结构」中选择 **单表 / 双表**。
+3. 在下方四种皮肤中选择 **古典 / 马卡龙 / 极简 / 星空**。
+4. 开始对话，Token 速度表会随流式输出更新；会话与今日数据每 1.5 秒刷新。
 
-## 数据来源与费用口径
+<p align="center">
+  <img src="screenshots/settings.png" alt="设置面板：结构 + 四种皮肤" width="62%">
+</p>
 
-- **数据源**：Host 半边订阅 DSH 会话事件流中的 `assistant/message.usage`（含输入/输出/缓存命中/缓存写入 token），自行累计，不依赖其他插件。
-- **累计视图**：全局 / 当日 / 当周 / 当月 / 会话 / 模型 六套。
-- **费用**：`费用 = (未命中输入×输入未命中单价 + 缓存命中×输入命中单价 + 缓存写入×写入单价 + 输出×输出单价) / 1,000,000`。
-  内置 DeepSeek 官方 ¥ 预设（如 deepseek-chat：输入缓存命中 0.5 / 未命中 2、输出 8；deepseek-reasoner：1 / 4 / 16），可在设置「高级·定价」中按模型自定义（¥/百万 token）。
+## 数据与口径
 
-## 设置项（⚙ 弹窗）
+| 指标 | 来源 / 口径 |
+| --- | --- |
+| Token 速度 | 当前会话 `assistant/live-chunk` 文本 / reasoning / tool-call 增量估算，0–500 token/秒 |
+| 当前会话 Token | 当前会话所有轮次的 `input + output` |
+| 今日 Token | 本插件 `byDay` 中今天的 `input + output` |
+| 当前会话金额 | 当前会话所有成功模型调用按单价估算 |
+| 今日金额 | 本插件按 DeepSeek Flash / Pro 列表价与峰谷时段估算的今日费用 |
+| 缓存命中率 | 今日 `cacheHit / (cacheHit + cacheMiss)`，仪表盘量程 70–100% |
 
-| 分组 | 说明 |
-|---|---|
-| 语言 | 中文 / English |
-| 风格 | 6 种机车风格 |
-| 配色 | 8 种调色板 |
-| 用量口径 | 全局累计 / 当前会话 / 今日 / 每日 / 每周 / 每月 |
-| 显示内容 | 用量、费用、输入/输出、缓存节省、会话数、今日用量、限额进度（可独立开关） |
-| 限额 | 全局 / 日 / 周 / 月（留空为不限，仪表盘自动量程） |
-| 高级·定价 | 按模型编辑输入命中/未命中、输出、缓存写入 单价（¥/百万 token） |
-| 导出报表 | CSV / JSON |
-| 其他 | 清空用量、恢复默认 |
+Host 半边读取 DSH 的 `sessionPersistence` 会话日志，按 `assistant/message.usage` 聚合；搜索调用按 0.02 元/次估算。DeepSeek Flash（2 / 0.04 / 8 元每百万 token）与 Pro（9 / 0.3 / 27）使用官方列表价，工作日高峰外与周末按半价；其他模型回退到 Flash 价格估算。金额是参考值，不是官方账单。
 
 ## 目录结构
 
-```
+```text
 dsh-token-gauge/
-├── package.json          # dsh 字段声明 bundle.patch 契约 + client.inject（稳定版 0.1.1-rc.x 兼容）
-├── tsconfig.json
-├── build.mjs             # esbuild 构建脚本
-├── cordis.patch.yml      # 本地 overlay
-├── src/
-│   ├── host.ts           # Host 半边：用量监听/累计/计费/持久化
-│   ├── client.ts         # Client 半边：注册侧边栏 Tab + 装配
-│   ├── gauge.ts          # SVG 仪表盘（指针/读数）
-│   ├── styles.ts         # 风格+配色定义与全局 CSS
-│   ├── settings.ts       # 设置弹窗
-│   ├── i18n.ts           # 中英文案
-│   ├── export.ts         # 报表导出
-│   └── util.ts           # 格式化/量程工具
-├── lib/                  # 构建产物（lib/index.mjs / lib/client.mjs），随包发布
-├── README.md / README.en.md / LICENSE
+├── package.json          # DSH bundle + Client 声明
+├── cordis.patch.yml      # 插入 token-gauge 行
+├── index.js              # Host 半边：注册 /api/token-gauge/usage-stats
+├── usage-server.js       # 会话日志聚合 + DeepSeek 峰谷计价
+├── client.js             # Client 半边：仪表盘 / 设置 / 样式
+├── locale/
+│   ├── zh.json           # 插件市场中文标题与描述
+│   └── en.json
+├── icon.svg              # 插件图标
+├── screenshots/          # README 预览图
+└── README.md / README.en.md / LICENSE
 ```
 
-## 上架市场
-
-本包已按 DSH 插件规范命名（`dsh.bundle.patch` 清单 + `lib/index.mjs` / `lib/client.mjs`），并声明 `files` 白名单。
-发布到 npm 后，其他用户即可 `dsh plugin --profile web add dsh-token-gauge` 安装发现：
+## 开发
 
 ```bash
-npm version patch        # 或 minor/major
-npm publish              # 须使用官方源 registry.npmjs.org
+git clone https://github.com/liumiaozhi/dsh-token-gauge.git
+cd dsh-token-gauge
+# 本插件是手写 Client bundle，无构建步骤
+dsh plugin --profile web add "link:$PWD"
 ```
 
+修改 `client.js` 后，DSH 的 Client HMR 会在文件变化后重新加载模块；没有热更新时刷新页面即可。
+
+## 兼容与限制
+
+- 面向 DSH Web（`platform: web`），需要 `@deepseek-ai/dsh-client-ui-sidebar` 与 `@deepseek-ai/dsh-client-ui-session`。
+- Host 半边依赖 DSH 自带的 `sessionPersistence` 与 `webServer` 服务；不需要计费插件。
+- 缓存命中率低于 70% 时指针停在 70% 刻度，中央数字保留真实值，避免表盘外推。
+- README 图片为按实际组件样式生成的示例预览，数据为演示值。
+
 ## 许可
 
-MIT
+[MIT](LICENSE) © 2026 liumiaozhi