# @cassius0924/dsh-usage-dashboard 中文文档

规范地址：https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/

版本：0\.9\.0
npm 元数据更新时间：2026-11-02T04:53:03.021Z
中文译文更新时间：2026-11-09T13:47:02.797Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40cassius0924/dsh-usage-dashboard
原文对照：https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/?lang=original
项目主页：https://github.com/Cassius0924/dsh-usage-dashboard#readme
源码仓库：https://github.com/Cassius0924/dsh-usage-dashboard

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1 MB，41 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：react ^18\.2\.0，@deepseek-ai/cordis ^4\.0\.0
- 首次发布：2026-08-15T05:40:01.503Z
- 最新版本发布：2026-11-02T04:53:02.641Z
- 近 30 天下载量：2497（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：11（近 12 个月 11 个）

## 中文简介

DeepSeek 额度与用量仪表盘 —— DSH (DeepSeek Harness) Web 插件：余额还能撑几天、今日/本月花了多少、哪个模型和哪个会话最贵、图片/多模态用量、缓存省了多少、高峰挪到闲时能省多少

## 安装

```sh
npm install @cassius0924/dsh-usage-dashboard
```

也可以使用：`pnpm add @cassius0924/dsh-usage-dashboard`、`yarn add @cassius0924/dsh-usage-dashboard`、`bun add @cassius0924/dsh-usage-dashboard`

## README

# dsh-usage-dashboard

[![npm](https://img.shields.io/npm/v/@cassius0924/dsh-usage-dashboard?color=cb3837&logo=npm)](https://www.npmjs.com/package/@cassius0924/dsh-usage-dashboard) [![license](https://img.shields.io/npm/l/@cassius0924/dsh-usage-dashboard?color=blue)](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/LICENSE)

在 [DSH](https://github.com/deepseek-ai)（DeepSeek Harness）的 Web GUI 里，随时看得见 DeepSeek 的钱花在哪： **余额还能撑几天、今天花了多少、哪个模型最贵、缓存替你省了多少、钱里有多少来自图片**，以及峰谷定价生效后把任务挪到闲时能省多少。

![dsh-usage-dashboard](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/hero.png)

装上之后 GUI 里多两样东西：右下角一个可拖动的**悬浮额度窗**，顶部栏多一个\*\*「额度」tab\*\*。 还能在「额度 → 设置」里加一个**侧边栏额度入口**（顶部或底部，点开账号级额度页）、**拖动调整「额度」tab 的位置**。 额度页会收起聊天输入框，把整屏留给数据；「图片 / 多模态用量」并入用量趋势卡，切换 7 天 / 30 天 / 90 天 / 1 年 时随图片有无平滑展开或收起。界面支持简体中文与 English，直接跟随 DSH 全局的「Settings → Language」设置； 切换无需刷新，选择由 DSH 持久化。

* * *

## 为什么需要它

用 DSH 跑 agent，钱是一点一点漏掉的，而 DSH 自己不会告诉你：

| 你真正想知道的 | 装之前 |
| --- | --- |
| 余额还能用几天？ | 只有一个余额数字 |
| 今天花了多少？这个月呢？ | 只有「累计」，没有时间感 |
| 钱花在哪个模型上？ | 不知道 |
| 缓存到底帮我省了多少？ | 完全看不到 |
| 钱里有多少来自图片？ | 多模态模型上线后更是看不见 |
| 高峰时段多付了多少？ | 只能自己算 |

这个插件把这些问题逐个翻译成一眼能看懂的数字。**费用全部为估算**，算法与单价公开可查（见[费用是怎么算的](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/#readme-%E8%B4%B9%E7%94%A8%E6%98%AF%E6%80%8E%E4%B9%88%E7%AE%97%E7%9A%84)）。

* * *

## 悬浮额度窗

![悬浮额度窗](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/widget.png)

常驻右下角，不打断你干活：

-   余额 + **今日消耗**，一眼就够。
-   可拖动，松手自动吸附四角；边界避开侧边栏、右侧详情面板、会话顶栏和输入框——**不会挡住发送按钮**。
-   可收起成一行；**显示/隐藏、所在角落、收起状态都会记住**，刷新页面后原样回来。
-   余额跌破预警线时，状态点和余额数字一起转成警示色。
-   60 秒自动刷新余额。今日消耗读共享缓存，点 ↻ 同时刷新两者。
-   插件加载时就把余额和用量预取到缓存里，所以打开「额度」tab 通常是秒开， 不用等那几秒的会话日志重放；预取失败不报错，交给各自挂载时再取。

## 「额度」仪表盘

### 余额：还能撑几天

![账户余额与可用天数](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/balance.png)

「还剩多少钱」不解决余额焦虑，「还能用几天」才行。按近 7 个自然日（含没用的日子）的日均消耗折算，hover 能看到估算口径；不足 3 天转红。

### 今日 / 本月花了多少 —— 以及这个数怎么来的

![消耗概览与计价说明](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/overview.png)

今日、本月、累计三个窗口，今日带「较昨日」、本月带「较上月同期」环比（**上月同期**而不是上月整月，免得月初总是显得便宜）。

展开**计价说明**能看到费用估算实际套用的单价表——估算不该是个黑箱。

### 高峰时段多付了多少

![高峰 / 闲时分布](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/peak.png)

DeepSeek 从 2026-08-17 00:00 起改峰谷定价，高峰（北京时间 09:00–12:00、14:00–18:00）价格是闲时的两倍。

这张卡告诉你用量落在峰谷两侧的比例，以及**如果高峰用量都挪到闲时能省多少**——批量、可延后的任务放到闲时跑，同样的 token 只要一半的钱。

### 缓存替你省了多少

![缓存命中与节省](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/cache.png)

前缀缓存的命中价只有未命中价的百分之一量级，是 DSH 这类高重复 prompt 负载上**最大的省钱杠杆**——上图这份用量实付 ¥50.61，缓存省下了 ¥1,220.87。

命中率掉到 60% 以下时，文案会换成怎么把它救回来的建议。

### 钱里有多少来自图片

![图片 / 多模态用量](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/vision.png)

`deepseek-v4-flash-vision-exp` 上线后，图片按尺寸折算成 token 与文本一并计费，但「看了一堆截图」和「纯文本」在账单里长得一模一样。

这张卡重放会话日志时顺手数出图片：用户消息里的附件和 tool result 里的截图都会统计（不用读附件本体，日志里就有宽高）。每组数字给出**图片张数、按官方换算规则估算的 token 与费用，以及占窗口输入 / 费用的比例**，旁边是每天图片数的趋势和「图片最多的会话」排行——一个不停刷截图的循环会话，在这里一眼就能认出来。

图片归属到随后一次模型调用，按该调用的时段与模型单价估算；实际 token 数以接口返回的用量为准。

### 钱花在哪个模型上

![模型成本排行](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/models.png)

按费用降序，带占比条和输入/输出/缓存拆分。模型配色在排行、下拉选择器和图表图例三处一致。

### 哪个会话最烧钱

![会话成本排行](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/sessions.png)

按模型、按天的视图告诉你「花在什么上」和「什么时候花的」；这张告诉你**是哪一次跑掉的**——对 agent 用户来说，这是唯一能直接动手改的东西：一个特别贵的会话，通常意味着一段值得看看的 prompt 或一个没收住的循环。上图里最贵的会话占了近 30 天总花费的 24.4%，前 6 个会话合起来约 65%。

会话标题直接从会话日志里读（`session/title` 事件），跟用量重放搭同一趟车，不额外读盘。

### 用量的时间分布

![逐天用量柱状图](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/charts.png)

近 30 天逐天、0–23 点逐小时（可按模型多选过滤，叠成分组柱状图）；逐天/逐小时切换、周期与指标都在这张卡上。hover 立刻出 tooltip，不用等系统那一秒。

![近一年用量热力图](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/heatmap.png)

热力图单独成卡，覆盖近一年每一天：一眼看出长期的使用节奏，而不是只看最近几周。

### 余额预警

![余额低预警警示条](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/alert.png)

在「设置」里定一条预警线（默认 ¥10，填 0 关闭）。跌破时仪表盘顶部出现警示条——带上还能撑几天和充值入口——同时悬浮窗一起转警示色，两边不会各说各话：

余额低于 ¥10、或跌破设置的预警线时，「预计可用」右侧还会出现一个实心的「去充值 ↗」按钮，点开在浏览器新标签页直达 DeepSeek 开放平台的充值页。预警线填 0 只关掉上面的警示条，不会关掉这个入口——余额快到零时，总该有个一键跳出去的地方：

![预计可用右侧的去充值按钮](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/top-up.png) ![悬浮窗的警示态](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/docs/widget-low.png)

* * *

## 安装

标准 DSH 插件包（bundle + client 双面包），用 `dsh plugin` 装：

```sh
# 从 npm 安装
dsh plugin --profile web add @cassius0924/dsh-usage-dashboard

# 或从 GitHub（git 依赖会跑 prepare 脚本现场构建）
dsh plugin --profile web add github:Cassius0924/dsh-usage-dashboard

# 或本地 checkout
dsh plugin --profile web add ./path/to/dsh-usage-dashboard
```

然后**重启 dsh**（`dsh --profile web`）生效。

前提：

-   余额优先走 DSH 的**账号登录**（浏览器授权，不需要 API Key）；未登录账号时才回退到 `DEEPSEEK_API_KEY`（「设置 → 模型」里填，或放在 `$DSH_HOME/.credentials.yaml`）。
-   本机有 pnpm（`dsh plugin` 是 pnpm 的转发器）。

装好后打开 GUI，**进入任意一个会话**（「额度」tab 挂在 `conversation.view` 上，New Session 首页没有 tab 栏），顶部就能看到 `Chat / Trajectory / 额度`。

> 兼容性：同时支持两代宿主接口——旧版 `readFrom(id, 0)` 与新版 handle 化 `open(id, 'read')` / `read` / `close`。 宿主升级到移除 `readFrom` 的版本后，插件无需更换版本，会话日志照常重放。

## 界面语言

跟随 DSH 全局的 **Settings → Language**，切换即时生效、无需刷新，选择由 DSH 持久化：

-   **简体中文** —— DSH 内置 `zh`；
-   **English** —— DSH 内置 `en`。

插件只提供这两种语言，与宿主内置语言保持一致，**不额外注册语言包**：语言目录属于宿主的设置面， 插件私自加一门宿主没翻译的语言，会让宿主界面和仪表盘说两种语言（宿主只能回落到简中）。 日期与数字格式化按当前语言取对应的 `Intl` 标签（`zh-CN` / `en-US`），不随浏览器区域设置漂移。

## 费用是怎么算的

费用是**估算**，不是账单。规则都在 [`src/pricing.ts`](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/src/pricing.ts) 一个文件里：

-   逐条用量记录按「**模型** + **是否落在高峰时段** + **当时的价目表**」计价，而不是全局一套价。
-   2026-08-17 00:00（北京时间）之前按旧的固定价；之后按峰谷价，闲时为高峰的一半。
-   2026-09-10 12:00 起 Flash 系列降价（V4.1-Flash），高峰时段同时收紧为**周一至周五**。
-   2026-09-14 12:00 起 `deepseek-v4-pro` 的请求由 V4.1-Flash 承接，按 Flash 价计费。
-   高峰时段按**北京时间**判定，不随机器时区漂移。
-   未识别的模型按 `deepseek-v4-pro`（较贵的一侧）计价。

单价（CNY / 百万 tokens，与官方价目表的两档一致）：

| 模型 | 时段 | 输入·缓存命中 | 输入·未命中 | 输出 |
| --- | --- | --- | --- | --- |
| deepseek-flash | 高峰 / 闲时 | 0.04 / 0.02 | 2 / 1 | 8 / 4 |
| deepseek-v4-pro | 高峰 / 闲时 | 0.3 / 0.15 | 9 / 4.5 | 27 / 13.5 |

`deepseek-v4-flash`、`deepseek-v4-flash-vision-exp` 是旧模型名，现由 `deepseek-flash` 承接、按 Flash 价计费；2026-09-14 12:00 起 `deepseek-v4-pro` 的请求也路由到 V4.1-Flash，按 Flash 价计费。历史各时期单价：08-17 前 pro 0.025/3/6、flash 0.02/1/2；08-17 – 09-10 12:00 的 flash 高峰 0.1/3/9、闲时 0.05/1.5/4.5。

图片不另外收费，而是按尺寸折算成 token 与文本一并计费：官方规则是先把图片按比例缩放到 ~800×800（小于 ~384×384 的放大），token 与缩放后面积成正比、每张上限 384 tokens。多模态卡的估算就套这条规则。

DeepSeek 再调价时，只改这张表。

## 开发 / 构建

```sh
pnpm install
pnpm test           # Node 内置测试运行器：计价、缓存、信任围栏与用量聚合
pnpm run build      # esbuild 出 lib/index.js（host）+ lib/client.js（client），再 tsc 出类型
pnpm run typecheck
```

产物：

-   `lib/index.js` —— Host 半（ESM，Node），注册 `/api/dsh-usage-dashboard/*` 路由。
-   `lib/client.js` —— Client 半（CJS 闭包），通过 `window.__ModuleLoader__` 注册进 web 启动图。

改动生效方式不同：只改 `src/client/**` 时，浏览器硬刷新（Ctrl/Cmd+Shift+R）即可；改了 `src/index.ts` 等 host 端要重启 dsh。

```
src/
├── index.ts        # Host 半入口（webServer 路由 + TTL 记忆化）
├── usage.ts        # 余额 + 用量聚合（按天/小时/模型/峰谷分桶）
├── pricing.ts      # 价目表与费用估算（唯一改价的地方）
├── contract.ts     # host ↔ client 的 wire 类型
├── trust-fence.ts  # 浏览器信任校验
└── client/
    ├── index.tsx   # Client 半入口（slots 注册）
    ├── widget.tsx  # 悬浮额度窗
    ├── dashboard.tsx # 「额度」tab
    ├── charts.tsx  # 柱状图 / 热力图 / tooltip
    ├── locales.ts  # 中英文完整词典
    ├── i18n.tsx    # DSH locale 桥接与 Intl 标签映射
    ├── styles.ts   # 全部样式
    ├── api.ts      # fetch + 客户端缓存
    ├── cache.ts    # TTL 缓存（含 localStorage 持久化）
    ├── prefs.ts    # 用户设置持久化
    └── store.ts    # 两个界面共享的设置
```

样式全部走 DSH 自己的 `--dsw-alias-*` CSS 变量，跟随宿主主题，不引入独立配色。

## 已知限制

-   用量数据来自**本机** DSH 会话日志，不含其它机器/账户的用量。
-   费用是估算：不含 DeepSeek 侧的折扣、赠金消耗顺序等因素，以官方账单为准。
-   图片 token 按官方换算规则估算，且把图片归属到随后一次模型调用；若缺少图片宽高或图片后没有成功的调用，则不纳入估算（无调用即无计费）。
-   首次加载用量需要重放全部会话日志（本机实测约 5 秒），因此有 5 分钟的服务端记忆化；界面在此期间显示骨架屏。

## License

[MIT](https://npmcn.com/package/%40cassius0924/dsh-usage-dashboard/LICENSE)

## 常见问题

### @cassius0924/dsh-usage-dashboard 是什么？

DeepSeek 额度与用量仪表盘 —— DSH \(DeepSeek Harness\) Web 插件：余额还能撑几天、今日/本月花了多少、哪个模型和哪个会话最贵、图片/多模态用量、缓存省了多少、高峰挪到闲时能省多少

### 如何安装 @cassius0924/dsh-usage-dashboard？

在项目目录运行 npm install @cassius0924/dsh-usage-dashboard，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：react（^18\.2\.0）、@deepseek-ai/cordis（^4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @cassius0924/dsh-usage-dashboard 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @cassius0924/dsh-usage-dashboard 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @cassius0924/dsh-usage-dashboard 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cassius0924/dsh-usage-dashboard 可以商用吗？

@cassius0924/dsh-usage-dashboard 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @cassius0924/dsh-usage-dashboard 的下载量有多少？

根据 npm 官方下载统计，@cassius0924/dsh-usage-dashboard 在 2026/10/09 – 2026/11/07 这 30 天内被下载 2,497 次，日均约 83 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @cassius0924/dsh-usage-dashboard 还在维护吗？

最新版本 0\.9\.0 发布于 2026/11/02（7 天前）；至今共发布 11 个版本，其中过去 12 个月发布了 11 个；首次发布于 2026/08/15。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。