@angelyeye/dsh-cost-tracker 1.7.0

package/README.md

@@ -0,0 +1,335 @@
+<div align="center">
+
+# <img src="./docs/icon-mark.svg" width="30" valign="bottom" alt="icon"> DSH Cost Tracker · 花费统计
+
+**DEEPSEEK HARNESS LLM 花费与用量统计插件**
+
+**简体中文** | [English](./README.en.md)
+
+![version](https://img.shields.io/badge/version-v1.6.0-blue?style=flat-square)
+![license](https://img.shields.io/badge/license-MIT-green?style=flat-square)
+![status](https://img.shields.io/badge/status-stable-brightgreen?style=flat-square)
+![platform](https://img.shields.io/badge/platform-DSH%20Web-blueviolet?style=flat-square)
+[![GitHub stars](https://img.shields.io/github/stars/Angelyeye/dsh-cost-tracker?style=flat-square)](https://github.com/Angelyeye/dsh-cost-tracker/stargazers)
+
+</div>
+
+---
+
+> 一个为 [DeepSeek Harness](https://github.com/deepseek-ai/dsh) 打造的 LLM 花费统计插件:自动记录每一次 API 调用的 Token 用量与费用(人民币),**原生支持 DeepSeek 官方峰值价格计费(高峰 / 闲时半价自动区分)与 Kimi Coding Plan 订阅套餐的用量及等效费用统计**。设置页可视化仪表盘、图表悬停明细、对话内 Agent 查询、账户余额与订阅配额监控,数据全部本地持久化——重启不丢、卸载无痕。
+
+> An LLM cost-tracking plugin for [DeepSeek Harness](https://github.com/deepseek-ai/dsh): records token usage and cost (CNY) for every API call, with **native support for DeepSeek's official peak/off-peak pricing and Kimi Coding Plan subscription usage & equivalent-cost statistics**. Visual settings dashboard with hover tooltips, in-chat agent queries, balance & quota monitoring — all persisted locally.
+
+![花费统计仪表盘:概览卡片 + 按峰谷分段的消费柱状图,悬停显示明细](docs/screenshots/dashboard-overview.png)
+
+---
+
+## 它能做什么?
+
+| | 功能 | 说明 |
+| --- | --- | --- |
+| 💰 | **花费统计** | 每一次 API 调用自动记账:输入 / 输出 / 缓存命中 / 缓存写入 Tokens 与费用(缓存写入按缓存命中价计),按天、按模型聚合 |
+| ⏰ | **峰谷定价** | 内置单价表,高峰时段(北京时间周一至周五 9:00–12:00、14:00–18:00)与闲时半价自动区分,**周末全天计为闲时**,本地模型(ollama 等)计 0;**单价表按「计费时代」分版**,北京时间 2026-09-10 12:00 起自动切换为 V4.1 Flash 新价(2.0 / 0.04 / 8.0 高峰),并按官方规则把 V4-Pro 与旧 V4-Flash 系请求路由到 V4.1 Flash 计费 |
+| 🔔 | **峰谷计价提示** | 设置页「峰谷计价与提示」面板:当前档位/距下次切换倒计时时段条、样式切换(**简洁单行·按24h比例** / **环形表盘·相位色点**)、简洁样式可选**双行紧凑**(上下布局,条上文下/文上条下)、「显示时间」开关、峰/谷切换前弹窗提醒与浏览器系统通知、提前提醒分钟、弹窗位置(右下角/屏幕中心)、提醒类型;侧边栏底部常驻显示时段条(窄栏/展开自适应)。对齐 `dsh-cost-meter` 交互 |
+| 📌 | **六组概览卡** | 设置页顶部六张卡:今日费用 / 本月费用 / 总花费 / API 请求次数 / Tokens / **总余额**。前三个金额卡**不含订阅会员等效费用**,订阅以附注展示 |
+| 👁️ | **视觉模型** | 支持 `deepseek-v4-flash-vision-exp`:legacy 时代单价与 flash 一致,2026-09-10 12:00 起随 V4.1 Flash 新价计费;图片按官方规则换算 token(每张上限 384 个,以接口用量计费) |
+| 📊 | **可视化仪表盘** | 设置页新增「花费统计」:概览卡片、消费柱状图(按峰谷/按模型)、分模型的请求次数与 Tokens 图表,**全部支持鼠标悬停查看明细** |
+| 🔥 | **用量热力图** | 设置页新增「Token 用量统计」:类 Codex 的 **26 周日用量方格热图**,按天着色(输入 / 缓存 / 输出 / 费用),悬停看当日明细、今天高亮描边,顶部显示全时段累计 |
+| 📈 | **订阅配额监控** | Kimi Coding Plan 等订阅套餐:本周配额、5 小时滚动窗口限额、等效按量费用参考 |
+| 💳 | **余额查询** | 一键查询 DeepSeek 官方账户余额(总余额 / 充值 / 赠送 / 状态) |
+| 🤖 | **Agent 工具** | 直接在对话里问:"我现在花了多少钱?"——Agent 会调用 `cost_stats` / `cost_prices` 等工具回答 |
+| 🔻 | **状态栏** | 聊天输入框下方实时显示:**本会话花费**(胶囊分段:本会话 / 订阅套餐 / 分模型),按会话实际用到的模型与订阅拆分,**多模型默认折叠只显示 top2,点击展开全部明细**;订阅显示具体套餐名,不再展示配额与调用次数 |
+| 💾 | **本地持久化** | 数据存本机 `~/.dsh/storages/cost-tracker-records.json`,重启不丢、不上传;**明细保留最近 180 天,更早自动压缩为永久日汇总,全时段统计永远精确且内存/磁盘有界** |
+| 📤 | **CSV 导出** | 一键导出明细 + 日汇总(purpose=rollup),方便用 Excel / Numbers 做进一步分析 |
+
+## 界面展示
+
+**在对话中直接查询**——Agent 自带花费/余额/单价工具,边聊边查:
+
+![对话中查询花费与余额,输入框下方显示实时花费状态栏](docs/screenshots/chat-tools.png)
+
+**订阅套餐与账户余额**——配额进度条、重置倒计时、余额一目了然:
+
+![Kimi Coding Plan 配额监控与 DeepSeek 账户余额](docs/screenshots/subscription-balance.png)
+
+**分模型明细**——每个模型的请求趋势、Token 构成,悬停显示每日明细:
+
+![单个模型的请求次数面积图与 Tokens 堆叠图,悬停提示显示完整日期与分段数值](docs/screenshots/model-detail.png)
+
+---
+
+## 安装(三选一)
+
+> 前提:你已经在用 `dsh web`(DSH 的 Web 模式)。`~/.dsh` 即 DSH 的数据目录(如设置了 `DSH_HOME` 环境变量则指向该目录)。
+>
+> 走方式一时请注意:插件市场本身要求 `dsh web ≥ 0.1.0-rc.6`,更旧的宿主里根本不会出现「插件市场」这一项——那种情况请用方式二或方式三。
+
+### 方式一:从插件市场安装(推荐)
+
+本插件已收录于 [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) 精选列表(分类 `usage`)。在 DSH 里打开 **设置 → 插件市场**,搜索 `dsh-cost-tracker` 点安装即可;市场展示的等价命令行是:
+
+```bash
+dsh plugin --profile web add @angelyeye/dsh-cost-tracker
+```
+
+> 若在 npm 映射生效前就看到这段:`dsh plugin --profile web add github:Angelyeye/dsh-cost-tracker` 同样可用——按仓库安装,装出来是同一个包。
+
+市场会把插件装进当前 profile 并自动写好 loader 配置,**装的是市场上架的最新版本**,装完按提示重启 `dsh web`、刷新浏览器,无需手工 `git clone`,也不用自己改 patch 文件。
+
+### 方式二:让 DSH 帮你装(不懂命令行也能用)
+
+打开 DSH 的任意会话,把下面这段话**原样粘贴**发送给 Agent 即可:
+
+```
+请帮我安装 DSH 插件 @angelyeye/dsh-cost-tracker:
+1. git clone https://github.com/Angelyeye/dsh-cost-tracker.git 到 ~/.dsh/profiles/node_modules/@angelyeye/dsh-cost-tracker(目录名必须与包名一致)
+2. 在 ~/.dsh/profiles/web/cordis.patch.yml 顶层数组追加一行:
+   - insert:
+       - id: dsh-cost-tracker
+         name: "@angelyeye/dsh-cost-tracker"
+3. 完成后告诉我,我自己重启 dsh web
+```
+
+看到提示后,在终端按 `Ctrl+C` 停掉 `dsh web`,再重新运行 `dsh web`,刷新浏览器即可。
+
+### 方式三:手动安装(3 条命令)
+
+```bash
+# 1. 下载插件(目录名必须与包名一致)
+mkdir -p ~/.dsh/profiles/node_modules/@angelyeye
+git clone https://github.com/Angelyeye/dsh-cost-tracker.git ~/.dsh/profiles/node_modules/@angelyeye/dsh-cost-tracker
+
+# 2. 注册插件(往 patch 文件里追加配置)
+cat >> ~/.dsh/profiles/web/cordis.patch.yml <<'EOF'
+- insert:
+    - id: dsh-cost-tracker
+      name: "@angelyeye/dsh-cost-tracker"
+EOF
+
+# 3. 重启 DSH(先 Ctrl+C 停掉当前 dsh web,再执行)
+dsh web
+```
+
+### 验证安装成功
+
+1. 浏览器打开 DSH Web GUI → 左下角 **设置** → 侧边栏出现 **「花费统计」**;
+2. 聊天输入框下方出现一行花费状态条;
+3. 对 Agent 说一句"查一下我现在的花费",能正常回答即全部就绪。
+
+> ⚠️ 如果 `~/.dsh/profiles/web/cordis.patch.yml` 里已有其他内容,请保留原有行,只追加上面那段;该文件顶层必须是 YAML 数组(每行以 `- ` 开头)。
+
+### 从旧包名迁移(仅 v1.6.0 及更早的安装需要)
+
+v1.7.0 起包名由 `dsh-cost-tracker` 改为 `@angelyeye/dsh-cost-tracker` —— 因为 npm 上原名已被他人占用,而市场的 npm 映射要求「已发布的包名 = 仓库 `package.json` 的 `name`」。
+
+⚠️ **不要只是"再装一次新版"**:新旧两份的 `cordis.patch.yml` 用的是**同一个 loader id**(`dsh-cost-tracker`),叠加安装会让**两份同时被加载** —— 表现为重复的 HTTP 路由、Agent 工具与 UI 插槽。必须先清掉旧的:
+
+**市场安装的**(用 `dsh plugin add` 装的):
+
+```bash
+dsh plugin --profile web remove dsh-cost-tracker
+dsh plugin --profile web add github:Angelyeye/dsh-cost-tracker
+```
+
+**手工 clone 装的**:
+
+```bash
+# 1. 编辑 ~/.dsh/profiles/web/cordis.patch.yml,删除 id 为 dsh-cost-tracker 的那段 - insert:(共 4 行)
+# 2. 删除旧目录
+rm -rf ~/.dsh/profiles/node_modules/dsh-cost-tracker
+# 3. 再按上面的「方式一」重新安装一次
+```
+
+**数据不会丢**:用量记录在 `~/.dsh/storages/cost-tracker-records.json`,与插件目录无关。
+
+---
+
+## 使用说明
+
+### 设置页「花费统计」
+
+- **时间范围**:右上角可切换近 7 天 / 近 30 天 / 全部;
+- **消费金额图**:支持「按峰谷」「按模型」两种分段方式,鼠标悬停查看当日明细;
+- **配色切换**:「按模型」视图下,消费金额标题旁有三套装色款条(橙→黄 / 蓝→紫 / 蓝→浅蓝)可切换;模型按总消费降序排名取色(第 1 名最深夜底、逐级变浅,不循环不撞色),选择保存在浏览器本地;
+- **分模型区块**:每个模型一张请求次数图 + 一张 Tokens 构成图(输入/缓存写入/输出/缓存命中);
+- **Token 用量统计热力图**:类 Codex 的 26 周每日用量方格,颜色深浅按当日 token 相对最大值分档;悬停任一格看该日明细(输入 / 缓存 / 输出 / 费用),今天高亮描边;
+- **导出 CSV**:导出明细记录(近 180 天)+ 日汇总行(`purpose=rollup`)。
+
+### 对话中的 Agent 工具
+
+| 工具 | 作用 | 你可以这样问 |
+| --- | --- | --- |
+| `cost_stats` | 查询花费与用量统计 | "我今天花了多少钱?" |
+| `cost_prices` | 查看内置单价表与峰谷规则 | "现在 deepseek-v4-flash 什么价?" |
+| `cost_peak` | 查询当前峰谷档位与下次切换倒计时 | "现在是不是高峰时段?" |
+| `cost_recompute` | **按计费时代重算已入库记录的费用(一次性补账)**,默认只试算 | "把价格调整前的记录按新价重算一下" |
+| `cost_reset` | **清空全部统计数据(不可恢复)** | "把花费统计清零" |
+
+### HTTP API(供其他工具调用)
+
+全部为 `POST` + JSON,监听本机地址:
+
+```
+POST /api/cost-tracker/summary      概览(含本会话按模型拆分 / 订阅)
+POST /api/cost-tracker/dashboard    仪表盘数据
+POST /api/cost-tracker/usage        用量热力图(全时段累计 + 按天 token 聚合)
+POST /api/cost-tracker/peak         峰谷相位快照(当前档位/下次切换/配置)
+POST /api/cost-tracker/peak-config  保存峰谷计价提示配置
+POST /api/cost-tracker/kimi-usage   Kimi 订阅配额
+POST /api/cost-tracker/balance      账户余额
+POST /api/cost-tracker/prices       单价表(按计费时代分版)
+POST /api/cost-tracker/recompute    按计费时代重算已入库记录(默认只试算,传 {"apply":true} 落盘)
+POST /api/cost-tracker/export       导出 CSV
+```
+
+示例:`curl -X POST http://127.0.0.1:3080/api/cost-tracker/summary -d '{}'`
+
+---
+
+## 更新记录
+
+### v1.6.0(2026-09-10)
+
+**新增**
+- **适配 V4.1 Flash 新计费规则(北京时间 2026-09-10 12:00 起生效)**:单价表改为**按「计费时代」分版**(`PRICE_ERAS`),按**每条记录自身的时间戳**选版计费,因此历史记录口径不变、切换点自动生效,无需重启或改配置。
+  - 新增时代 `v41`(北京时间 2026-09-10 12:00 = `2026-09-10T04:00:00Z`):V4.1 Flash 高峰价 **输入(缓存命中)0.04 / 输入(缓存未命中)2 / 输出 8**(元/百万 tokens),空闲时段仍为高峰半价(0.02 / 1 / 4)。**峰谷窗口不变**,故时段条与倒计时逻辑无需调整。
+  - 新增**模型路由**(时代内的 `routes`):V4.1 Pro 上线前,V4-Pro 的请求全部路由到 V4.1 Flash 并按 V4.1 Flash 单价计费;旧 V4-Flash 系(含 `deepseek-v4-flash-vision-exp`)已被 V4.1 Flash 取代,一并按新价计费。**记录以实际计费模型名入账**(如 `deepseek-v4-pro` → `deepseek-v4.1-flash`),按模型聚合看到的就是真实计费口径。
+  - 新增导出 `V41_EFFECTIVE_AT` / `V41_FLASH_MODEL` / `PRICE_ERAS` / `eraAt()` / `exactModelsAt()` / `resolveModelInEra()` / `normalizeModelName()`。
+- **模型名归一化匹配**:小写并剔除分隔符,使 `deepseek-v4.1-flash` / `deepseek-v4-1-flash` / `deepseek-v41-flash` / `DeepSeek-V4.1-Flash` 等等价写法命中同一档价,避免官方模型 ID 措辞变化导致漏计而落入兜底估算。
+- `cost_prices` 工具与 HTTP `/prices` 接口改为**按版本渲染**:逐时代列出生效时刻、单价与路由规则,并标出当前生效版本(`era` / `eraLabel` / `eras` / `v41EffectiveAt`)。
+
+- **新增 `cost_recompute` 一次性补账工具**(同时开放 HTTP `/api/cost-tracker/recompute`):按记录自身时间戳重算已入库记录的费用与计费模型名。用于「价格时代已切换、但宿主尚未重启」期间按旧价入库的记录;**默认只试算不落盘**,传 `apply: true` 才写回,幂等可重复执行。只重算明细(明细保留最近 180 天;更早的记录已折叠进日汇总,其时间段远早于任何价格切换窗口)。
+
+**变更**
+- `priceFor(np, model, ts)` 新增第三个参数 `ts`(调用发生时刻),缺省为当前时间;返回值新增 `model`(**计费模型规范名**,命中路由时为被路由到的模型)与 `era` 字段。记账链路改为传入记录时间戳。
+- DeepSeek provider 兜底单价同步至 V4.1 Flash 档(`2.0 / 8.0 / 0.04`),未知 deepseek 模型不再按旧价高估。
+- `EXACT_MODELS` 语义收敛为 **legacy(旧价)时代的单价表**,保留导出以兼容既有调用与历史口径。
+
+**测试**
+- `test/pricing.test.js` 新增计费时代分版与模型路由用例(切换边界 11:59:59 / 12:00:00、V4-Pro 路由、旧 V4-Flash 系路由、别名归一化、空闲半价、悬空路由防护)。
+- 所有涉及单价的断言改为**显式传入时间戳**,不再随运行时刻漂移(否则跨 12:00 切换后必然误报)。
+
+**计费影响(同一调用对比,高峰价)**
+- V4-Pro(10 万输入未命中 + 6 千输出 + 2 万缓存命中):旧 **¥1.068** → 新 **¥0.2488**(约 **-76.7%**)。
+- 旧 V4-Flash 同量:旧 **¥0.356** → 新 **¥0.2488**(约 **-30.1%**)。
+
+### v1.5.2(2026-08-25)
+
+**新增**
+- **「简洁」时段条新增「双行紧凑(上下布局)」选项**:时段条样式为「简洁(单行紧凑)」时可勾选,勾选后由左右单行改为上下两行,并可进一步选择「时段条在上·文字在下」(默认)或「文字在上·时段条在下」;侧边栏与设置页预览同步生效。
+- 新增 `peakCompactStack`(默认 `false`)与 `peakCompactOrder`(`bar-first` / `text-first`,默认 `bar-first`)配置项,纳入 `defaultPeakConfig` / `normalizePeakConfig` 与配置层单元测试。
+
+**修复**
+- 双行紧凑下轨道的 `flex-basis(72px)` 落到纵轴,时段条被拉成 72px 高;已覆盖为 `flex: 0 0 auto`,保持与单行一致的 6px 细条。
+
+### v1.5.1(2026-08-24)
+
+**修复**
+- **侧边栏底部(sidebar.footer.action)与多插件 UI 兼容**:DSH 渲染器把该槽锚点设为 `display:contents`,多个插件内容会被并进同一行(如与 `linxin666/dsh-web-ui-all` 冲突);改为纵向堆叠后,本插件的时段条与其它 footer 插件共存不重叠。
+
+### v1.5.0(2026-08-24)
+
+**新增**
+- **峰谷「时段条样式」新增「环形表盘(24h 中空圆环)」**(替代原「经典(两行)」):按 24h 划分(0:00 顶部、6:00 右、12:00 底、18:00 左),橙色 = 高峰时段(9:00–12:00、14:00–18:00)、蓝色 = 平价时段,周末整环无橙色(全天谷价);共 12 档「当前时刻」指针式样可选,默认采用**相位色点**(峰橙 / 平蓝 / 周末绿),不再使用从圆心连到边缘的长指针;圆心显示当前相位词 + 距下次切换倒计时。
+- **「显示时间」开关**(仅环形表盘):控制是否显示 00:00–21:00 小时刻度,默认开启。
+- **「简洁(单行紧凑)」时段条改为按 24h 比例划分**:蓝色平价底条铺满 24h,橙色高峰段按窗口比例定位(9:00–12:00 → 37.5%–50%,14:00–18:00 → 58.33%–75%),白色分割线标出「当前时间」实时进度;周末仅蓝底 + 白线。
+
+**改进**
+- 后端 `peakSnapshot()` 新增下发结构化窗口数组 `peakHours`(`PEAK_HOUR_WINDOWS`),前端据此绘制比例轨道/圆弧,与 `isPeak`/`peakPhaseAt` 计费口径一致;前端内置兜底窗口 `[9,12]` / `[14,18]`。
+- 新增 `peakShowTickLabels` 配置项(默认 `true`),纳入 `defaultPeakConfig` / `normalizePeakConfig`。
+- 新增设计文档 `docs/peak-dial-design.md` 与可交互预览页 `docs/peak-dial-preview.html`(含 12 档指针式样对比)。
+
+### v1.4.1(2026-08-23)
+
+**修复缓存写入计价并补充 reasoning 计费(对齐官方规则与 dsh-cost-meter)**
+
+- **修复缓存写入(cache write)计价 bug**:原先 `cacheWrite` 被按「缓存未命中价」计费(flash 3.0 / pro 9.0),导致缓存写入量大的会话费用被严重高估。官方规则(及 `dsh-cost-meter`)约定**缓存写入与缓存命中同价**,现统一为 `(cacheRead + cacheWrite) × 缓存命中价`(flash 0.10 / pro 0.30)。
+- `computeCost()` 改为 `输入×未命中价 + 输出×输出价 + (缓存读+缓存写)×命中价`,与官方/参考口径完全一致。
+- **补充 reasoning(推理)token 计费**:`normalizeTokens()` 新增 `reasoning` 桶(读 `usage.reasoningTokens`),模型单价含 `reasoning` 时按单独单价计费(DeepSeek 当前模型未单独列 reasoning 价,计 0)。
+- 同步 `EXACT_MODELS` / `SUBSCRIPTION_RATES` / `PROVIDER_RATES` / `GENERIC_RATES` 的 cacheWrite 值(均改为命中价)。
+- 更新 `cost_prices` 工具文案与单元测试(新增「缓存写入按命中价」与「reasoning 计费」用例)。
+
+> 说明:本版只修正**单模型计价规则**;不同插件间「调用次数 / 累计用量」的差异源自统计口径(实时 `llm/stream` 与 DSH 会话投影 `(turn,step)` 粒度不同),不属于计价 bug。
+
+### v1.4.0(2026-08-23)
+
+**新增**
+- **峰谷计价提示(对标 dsh-cost-meter)**:设置页新增「峰谷计价与提示」面板——启用峰谷时段价格、峰时高价时段显著提示、时段条样式(简洁/经典)、峰/谷切换前弹窗提醒、提前提醒分钟(1–30)、提醒类型(峰和谷/进入峰/进入谷)、弹窗位置(右下角/屏幕中心)、同步发送系统通知;全部设置即时保存到 `~/.dsh/storages/cost-tracker-config.json`。侧边栏底部常驻显示时段条(当前档位 + 距下次切换倒计时),窄栏(rail)自适应为短词。新增 `POST /api/cost-tracker/peak` 与 `POST /api/cost-tracker/peak-config`,以及 Agent 工具 `cost_peak`。
+- **六组概览卡**:设置页顶部改版为六张卡——今日费用 / 本月费用 / 总花费 / API 请求次数 / Tokens / **总余额**。今日、本月、总花费三个金额卡**不含订阅会员等效费用**(订阅以附注展示),本月按北京日历月统计,总花费为全时段累计(明细 + 永久日汇总,永远精确)。
+
+**改进**
+- **同步 DeepSeek 最新定价规则**:高峰时段限定为北京时间**周一至周五 9:00–12:00、14:00–18:00**,**周末全天计为闲时(闲时半价)**;`isPeak()` 不再忽略星期几,修复周末被误判为高峰价的问题。
+- 峰谷面板时段条对齐参考项目样式:两段轨道(左橙右蓝)+ 标记线 + 单行着色 chip。
+
+**修复**
+- 预览弹窗此前强制居中,现已**跟随用户配置的弹窗位置**(右下角/屏幕中心)。
+
+### v1.3.0(2026-08-23)
+
+**新增**
+- **Token 用量统计热力图**:设置页新增「Token 用量统计」面板,类 Codex 的 **26 周每日用量方格热图**,颜色深浅按当日 token 相对最大值分 4 档;悬停任一格显示当日明细(输入 / 缓存 / 输出 / 费用),今天高亮描边;顶部显示全时段累计(`累计 X tokens · 输入 · 缓存 · 输出 · N 次调用`)。新增 `POST /api/cost-tracker/usage` 端点。数据日期键统一按北京时间(UTC+8),与服务端口径完全一致。
+- **本会话按模型拆分**:状态栏新增按会话实际使用的模型拆分,订阅与按量分开统计。
+
+**改进**
+- **状态栏改版**:改为**胶囊分段**布局(本会话 / 订阅套餐 / 分模型),信息清晰、竖线分隔、基线对齐;只显示**本会话花费**,不再显示累计与当前峰/闲时价。
+- **订阅去重**:订阅只显示一个着色徽标(具体套餐名 + 总等效费用),不再在模型区重复出现。
+- **多模型折叠**:默认只显示消耗 top2 模型 + 数量,点击 `▸` 展开全部模型明细;订阅模型不再混入模型区。
+- **显示精简**:去掉配额(周配额剩)与模型调用次数(`×N`)等噪音信息;金额字重与配色统一。
+
+**修复**
+- 状态栏不再依赖"当前选中的模型"判定显示,而是**按会话实际用到的模型 / 订阅**决定,修复多会话切换时显示错误、订阅会话显示为 ¥0 的问题。
+
+---
+
+## 常见问题
+
+**Q:数据存在哪里?安全吗?**
+全部数据只存在你本机的 `~/.dsh/storages/cost-tracker-records.json`,不会上传到任何服务器。API 只监听本机回环地址,但无鉴权——**不要把 DSH 端口暴露到公网**。
+
+**Q:重启 DSH 数据会丢吗?**
+不会。记录防抖写入磁盘(原子写入),重启后自动恢复;文件损坏时自动备份为 `.corrupt-<时间戳>` 并从头开始。
+
+**Q:历史记录会保留多久?统计有上限吗?**
+明细记录保留最近 **180 天**;更早的记录自动按「天 + 模型」压缩为**永久日汇总**(只保留聚合数字:调用数 / 各段 tokens / 费用,不再保留单次调用)。因此「全部」时间的总花费、分模型统计**永远精确**,且内存、磁盘、写入量有界,跑多久都不会膨胀。按天图表日期轴最长 730 天。数据文件支持旧版格式自动迁移;可用环境变量 `DSH_COST_TRACKER_STORE` 覆盖存储路径(默认 `$DSH_HOME/storages`,未设 `DSH_HOME` 时为 `~/.dsh`)。
+
+**Q:启动日志怎么开启/关闭?**
+插件默认**静默启动**,不打印日志。设置环境变量 `DSH_COST_TRACKER_LOG=1`(或 `true` / `yes` / `on`)可启用启动日志:nav-icon 自检结果、数据恢复报告(`restored N detail records ...`)、就绪标记。**错误日志**(持久化失败、文件损坏等)始终打印,不受此开关影响。
+
+**Q:订阅套餐(kimi-coding)的"等效费用"是什么意思?**
+订阅制不按量扣费。插件按内置单价估算出"如果这些调用走按量计费会花多少钱",仅供你评估订阅是否划算,**不是真实扣费**。
+
+**Q:金额和官方账单对不上?**
+插件在本地按内置单价表估算,可能与官方实际计费存在细微差异(如官方价格调整、阶梯定价)。精确金额请以官方账单为准。余额以「余额查询」实时拉取的官方数据为准。
+
+**Q:如何卸载?**
+1. **先摘掉 loader 条目**——市场安装的:打开 **设置 → 插件市场 → 已安装** 点卸载;手工安装的:打开 `~/.dsh/profiles/web/cordis.patch.yml`,删除 `dsh-cost-tracker` 那段 `- insert:`(共 4 行),或直接让 DSH Agent 帮你删;
+2. 重启 `dsh web`;
+3. 可选:删除插件目录 `~/.dsh/profiles/node_modules/@angelyeye/dsh-cost-tracker` 和数据文件 `~/.dsh/storages/cost-tracker-records.json`。
+
+**Q:如何更新插件?**
+- **市场安装的**:打开 **设置 → 插件市场 → 更新**,或重新执行 `dsh plugin --profile web add @angelyeye/dsh-cost-tracker`;
+- **手工安装的**:进入插件目录执行 `git pull`。
+
+两种情况更新后:只改了界面(client.js)的话**硬刷新浏览器**(Cmd/Ctrl+Shift+R)即可;改了 index.js 则需要重启 `dsh web`。
+
+## 仓库结构
+
+```
+├── index.js        Host 半端:用量采集、聚合、HTTP API、Agent 工具
+├── store.js        存储层:明细保留 + 永久日汇总 + 持久化(纯逻辑,可独立测试)
+├── pricing.js      定价与 Token 层:单价表、峰谷计价、视觉模型、峰值相位(纯逻辑,可独立测试)
+├── config.js       配置层:峰谷计价提示的默认值与规范化(纯逻辑,可独立测试)
+├── client.js       Client 半端:设置页仪表盘、状态栏与峰谷提示 UI
+├── package.json    插件清单:声明 dsh.bundle(插件可被安装的关键)与 dsh.client(前端 UI)
+├── cordis.patch.yml Bundle 补丁:把本插件注册进 DSH 的 loader,由 dsh.bundle 指向
+├── screenshots.json 插件市场详情页的截图清单(相对路径,1-8 张)
+├── README.md       中文说明文档
+├── README.en.md    英文说明文档
+├── CHANGELOG.md    更新记录(中文)
+├── test/           单元测试(storage / pricing / config / recompute,node test/*.test.js)
+└── docs/           README 截图与设计文档
+```
+
+## License
+
+[MIT](./LICENSE) · 欢迎 Issue 与 PR