# balance-dsh 中文文档

规范地址：https://npmcn.com/package/balance-dsh/

版本：2\.2\.0
npm 元数据更新时间：2026-11-03T02:35:37.740Z
中文译文更新时间：2026-11-03T04:59:12.366Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：857 kB，6 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20
- 运行依赖：0 个
- 首次发布：2026-08-24T10:58:10.309Z
- 最新版本发布：2026-11-03T02:35:37.604Z
- 已发布版本数：35（近 12 个月 35 个）

## 中文简介

在 DeepSeek Harness 中显示 DeepSeek 账户余额和当前会话 token/费用消耗（含高峰/空闲峰谷计费）。仅支持 DeepSeek 官方模型与账号，暂不支持其他大模型。

## 安装

```sh
npm install balance-dsh
```

也可以使用：`pnpm add balance-dsh`、`yarn add balance-dsh`、`bun add balance-dsh`

## README

# balance-dsh

DeepSeek Harness 插件：在 Web UI 中直接显示 DeepSeek 账户余额和当前会话 token / 金额消耗。

> **仅支持 DeepSeek，暂不支持其他大模型。** 余额读的是 DeepSeek 官方账号（未登录时回退 DeepSeek API Key），费用按 DeepSeek 官方价表估算，模型识别也只认 DeepSeek 的模型名。如果你通过其他厂商或自建服务用 DeepSeek Harness（OpenAI、Claude、本地模型等），本插件**不会**给出正确的余额和费用：余额会显示为不可用，模型会回落按 Flash 价估算，数字仅供参考。

最新版本见 [npm](https://www.npmjs.com/package/balance-dsh)；装好之后也可以在插件设置卡片里直接检查并更新。

## 功能

### 侧边栏余额行

侧边栏展开时贴在底部，紧挨「设置」齿轮。两种样式可在配置界面切换：

-   **新版（默认）**：上方一行文字信息 + 下方一条扁刻度条。
    -   文字分两段：`今日 ¥21.42`（今天累计消耗）和 `空闲 剩 3h57m`（当前时段 + 距切换还剩多久，高峰为红色、空闲为绿色）。
    -   刻度条整条代表**一整天**：彩色分段标出这一天里哪些时段是高峰、哪些是空闲，一个指针标出「此刻走在今天的哪个位置」，每分钟前进一格。换日或同步到新的节假日安排时，颜色分布会交叉淡入。
-   **旧版**：钱包图标 + `余额` + 金额（带货币单位）的纯文字行，右侧可带时段标签。

金额按余额状态变色：充足为主题绿、低于阈值（默认 10 元）为琥珀黄、为 0 时显示红色「去充值」。金额变化时按位滚动切换（只滚变化的数位），不会整块闪一下。

### 收起态圆钮

侧边栏收起时，余额显示为左下角的 **60px 圆形**悬浮按钮（liquid glass 质感，圆内显示 `¥金额`，余额耗尽时显示「充值」）。直径与距左缘距离均可调，垂直方向自动对齐聊天输入框的中心。

### 刷新

-   默认每 **60 秒**自动刷新一次，间隔可调（5~3600 秒）。
-   对话产生新消耗时会顺带刷新一次余额。
-   **右键**任意余额元素可立即刷新（有防抖，连续点击不会重复打 API）。

### 余额与使用统计

**单击余额**打开居中弹窗（带半透明模糊遮罩），展示：

-   账户余额、近 90 天计费 Token、估算费用、活跃天数
-   Token 构成与缓存命中率
-   按模型拆分（Flash / Pro）、按高峰 / 空闲拆分
-   今日 / 近 7 天 / 近 30 天、日均与峰值日
-   按日使用热力图

点遮罩、按 `Esc`、点关闭按钮均可关闭。

### 高峰 / 空闲计费

-   高峰时段 = **工作日 09:00-12:00、14:00-18:00（北京时间）**。
-   **其余时段全部按空闲计费**：包括周末、中国法定节假日全天。**调休上班的周末也按空闲**——官方原文是「其余时段，包括周末及中国法定节假日全天均为空闲时段」，并没有给调休开例外。
-   节假日与调休安排从国务院公告（公开数据源）自动同步，内置当年表作离线兜底，**无需每年手动维护**；配置界面里能看到上次同步时间，也能手动触发立即同步。
-   消耗金额**跨时段精确计费**：高峰时段的 token 按高峰价、空闲时段按目录价，按每条消息的**事件时间**分桶计算，不会用「当前时段」笼统估算整个会话。

### 会话消耗行

对话框下方实时显示当前会话消耗（`数据库图标 + 本会话消耗 + ≈¥金额`）。**点击**展开明细浮层：Token 用量、缓存命中率、模型、高峰 / 空闲拆分、子代理消耗、网页搜索 / 抓取次数与费用、图片张数与估算 token。

### 智能体团队（Agent Teams）

会话里开了团队（Lead + teammate）时：

-   消耗行里多一颗 `团队 N` 小圆片，说明这颗金额是**本会话 + N 个队友**的合计（队友的钱本来就按子会话算进去了）。
-   明细浮层多一块「智能体团队」，按人头列出每个队友的 `名字 · 状态` 与 `≈ ¥金额`，右上角是团队合计。
-   队友干活时 Lead 自己的 token 不变，所以有团队时会每 15 秒补拉一次（页面不可见时跳过），团队金额不会停在旧值。
-   `context: "fork"` 的队友会继承父会话的历史前缀，插件只算 fork 之后产生的事件，不会把父会话的钱重复算一遍。

roster 直接读会话里的 `team/member` 事件，不依赖 `agentTeams` 服务或 `agentTeam` 投影 —— 团队功能没启用时这些事件不存在，上面这些都不出现。

### 网页搜索 / 抓取按次计费

调用 `web_search` / `web_fetch` 时统计次数。官方 **2026-11-01 00:00（北京）起**按次收费（每千次 ¥5），此前的调用标注为「免费期内」。这笔费用不属于峰谷计价，直接叠加。

### 图片（vision）消耗

发图时 DeepSeek 会按图片尺寸把图折算成 token，**和文字 token 一起计费**，没有单独的「图片费用」。也就是说图片消耗本来就在输入里，插件要做的是把它标出来——明细浮层里多一行：

```
图片    12 张 · 约 4,300 tok · 已计入输入
```

token 数用官方文档站「图片 Token 计算器」的同一套算法估算（像素按 14 对齐 → 按 3 折成视觉网格 → 每张上限 1024），所以和官网计算器算出来的数字一致。同一张图只算一次（按附件 ID 去重，不会因为同时出现在两处事件里被重复统计）。

要注意的是：**图一旦进入上下文，后面每一轮请求都会再把它计一遍输入**（多数能命中缓存，单价便宜很多）。所以「图片 N 张 · 约 X tok」说的是这些图本身的体积，不是它们累计产生的费用。

### 查看官方用量

双击余额，或点统计面板里的「查看官方用量」/「去充值」，会按三级顺序打开官方页面：

1.  **DeepSeek Harness 内置平台窗口**（首选）。这个窗口自带平台登录凭据，所以**不需要在网页里再登录一次**。
2.  应用内侧栏浏览器（内置窗口拿不到时）。
3.  系统默认浏览器（最后兜底）。

余额重置 / 充值的入口就是同一个窗口里的 `top-up` 页，两个页面之间可以直接切换。

### 设置卡片

位置：主界面左上角 **「插件」** → 点 `balance-dsh` → 「余额与用量」卡片。包含：

-   **版本与更新**：显示当前版本；点「检查更新」读取 npm 上的最新版本号（只查版本，不下载）。发现新版时原地变成「检测到新版本 X，是否更新？」——点「更新」才会下载并覆盖本机插件文件（旧文件先备份到 `~/.dsh/balance-update-backup/`），**完成后需重启 DeepSeek Harness 才生效**。
-   **启动自动检查**：每次打开 DeepSeek Harness 会在启动后稍等片刻自动查一次；有新版本时左侧「余额与用量」入口旁显示 **「新版本！」** 胶囊提示。检查失败或断网时完全静默，不打扰。
-   **节假日数据**：显示同步状态（已同步天数、上次同步时间、尚未公布的年份）与「立即同步」按钮。
-   **侧边栏入口开关**：关掉后左侧导航不再显示「余额与用量」。关闭的那一刻会弹一个官方提示窗，告诉你从哪儿可以再打开。

整张卡片可以收起（点标题一行展开 / 折叠）。**没有保存按钮**，改动后约 0.35 秒自动保存，左下角依次显示「修改中… → 保存中… → 已保存」；点「恢复默认」立刻写回全部默认值。设置存放在你的 `.dsh` 目录下的 `balance-dsh.json`。

### `/balance-dsh-rannist` 命令

在对话里输入 `/balance-dsh-rannist` 查询余额明细和当前会话消耗。

命令名带作者后缀是刻意的：DSH 的命令名全局唯一，`/balance` 这类通用名会和别的余额插件撞车（先注册的赢、后来的整条命令消失），所以用全名、不设备用名。注意 DSH 只接受**小写**命令名，写成大写会在注册时被判非法。

## 使用统计口径

**插件显示的所有金额都是本地估算，不是 DeepSeek 官方账单。** 想要准确数字请用「查看官方用量」打开官方页面。

-   热力图按北京时间聚合最近 90 天持久化会话中的 `assistant/message` Token usage。
-   费用按每条消息的**实际模型**和**峰谷时段**估算：高峰时段的 token 按高峰价、空闲时段按目录价，按事件分桶计算。
-   **峰谷归属按「请求发起时刻」判定**（取 `step/start` 事件的 `time`；拿不到时回退消息完成时刻）。**官方并未公开跨时段请求到底按发起还是按完成计费**，所以这是一个合理猜测而非官方口径；如果官方实际按响应生成时间逐段计费，一次横跨边界的请求真实费用会介于「全高峰」和「全空闲」之间，本插件两种口径都算不出这个中间值。（实测影响很小：请求平均耗时约 6 秒，长请求也只到分钟级，撞上窗口边界的概率极低。）
-   其他已知误差来源：本地 token 数与官方计费口径可能不同（系统提示、工具调用的内部算法未公开）；缓存命中与否按 usage 字段判断，官方口径可能不同；官方调价后需等插件更新价表；模型靠事件里的切换点推断，同名不同版本分不清。
-   峰值倍率只乘一次：高峰桶乘以倍率，空闲桶原价，网页工具费不参与峰谷倍数。
-   **图片 token 已包含在输入里**，插件不会再为它算一次钱（那会让金额翻倍）。明细里的「图片约 X tok」是各张图本身的体积之和，按官方计算器算法估算；图留在上下文里每轮都会重新计一遍输入，这部分体现在「缓存读取」中。
-   为避免历史会话过多拖慢 DeepSeek Harness，默认最多扫描最近 200 个会话；服务端统计与客户端展示结果均缓存 5 分钟，重复打开菜单不会重复请求。**这两个值、以及刷新间隔、各类显示开关，都能在配置界面里改。**
-   账户余额优先读取 **DeepSeek Harness 官方账号**（登录后即可用，无需 API Key）；未登录时回退到 API Key。两者都不可用时仍可查看本地 Token 与费用统计，只是余额会显示为不可用。

## 安装

前提：已安装 DeepSeek Harness 桌面版，且知道自己的 profile 目录（通常是 `C:\Users\<你的用户名>\.dsh\profiles\desktop\`）。

### 方式一：通过 npm 安装（推荐）

```powershell
cd C:\Users\<你的用户名>\.dsh\profiles\desktop
pnpm add balance-dsh
```

### 方式二：从 tarball 安装

```powershell
cd C:\Users\<你的用户名>\.dsh\profiles\desktop
pnpm add "file:C:\path\to\balance-dsh-<版本>.tgz"
```

### 方式三：从 GitHub 安装

```powershell
cd C:\Users\<你的用户名>\.dsh\profiles\desktop
dsh plugin --profile desktop add github:Rannist/balance-dsh
```

> 用 npm 安装后，插件自带 `dsh.bundle.patch`（`cordis.patch.yml`），安装即自动注册，**无需手动改 profile 的 cordis.patch.yml**。只有用旧版 tarball / 手动方式时才需要手动注册：

```yaml
# profile 目录的 cordis.patch.yml（只有手动安装时才需要）
- insert:
    - id: balance
      name: balance-dsh
```

### 余额来源

**官方 DeepSeek Harness 桌面版**：在应用内登录 DeepSeek 账号后，插件会**自动读取官方余额，无需任何配置**。

**其他环境**（或不想登录官方账号时）：改用 API Key，三选一——

1.  环境变量 `DEEPSEEK_API_KEY`，或
2.  在注册项的 `config.apiKey` 中设置，或
3.  使用 Harness 凭据存储中的 `DEEPSEEK_API_KEY`

### 重启

客户端界面改动**刷新页面即生效**；服务端逻辑（刷新间隔、统计范围、API Key、计费倍率等）改动需**重启 DeepSeek Harness 桌面版**。

## 配置

### 可视化配置（推荐）

主界面左上角 **「插件」** → 点 `balance-dsh` → 详情页里的「余额与用量」卡片。分组从上到下：

| 分组 | 可调项 |
| --- | --- |
| 版本与更新 | 当前版本、检查更新、就地更新 |
| 节假日数据 | 同步状态、立即同步 |
| 余额 | 刷新间隔、低余额警示阈值、API Key |
| 界面显示 | 侧边栏余额行开关、余额行样式（新版 / 旧版）、侧边栏入口开关、右键刷新浪潮、会话消耗行开关、（仅旧版）高峰空闲标签开关 |
| 收起态圆钮 | 显示开关、直径、距左缘 |
| 用量统计 | 扫描会话数上限、统计缓存时长 |
| 计费 | 高峰时段倍率 |

卡片最顶部是一条固定的范围声明：「计费仅支持 DeepSeek Harness 内的 DeepSeek 官方模型与账号；其他大模型不计入金额。」

### 配置文件 / 注册项覆盖

也可以在插件注册项（或 `cordis.patch.yml`）中覆盖：

```yaml
- id: balance
  name: balance-dsh
  config:
    apiKey: sk-xxxx                        # 可选；缺省用 DEEPSEEK_API_KEY 环境变量/凭据
    peakWindows:                           # 可选；默认周一至周五，如下
      - {start: 9, end: 12}
      - {start: 14, end: 18}
    peakWeekdays: [1, 2, 3, 4, 5]          # 可选；1=周一 … 5=周五，0/6=周末
    price:                                 # 可选；逐项覆盖对应模型价格（元/百万 tokens）
      inputCnyPerMillion: 1
      cacheReadCnyPerMillion: 0.02
      cacheWriteCnyPerMillion: 0
      outputCnyPerMillion: 4
```

> 注意：插件已自动按高峰 / 空闲时段计费（高峰价 = 目录价 × 倍率），**不要再设置 `config.peak: true`**，否则会重复翻倍。

## 卸载

```powershell
cd C:\Users\<你的用户名>\.dsh\profiles\desktop
pnpm remove balance-dsh
```

如需删除手动注册行（若你手动加过），从 profile 的 `cordis.patch.yml` 移除对应的 `balance` 条目。

## 权限 / 数据

-   已登录官方账号时，余额通过 **DeepSeek Harness 内置账号服务**读取（登录凭据由应用自身管理，插件不接触、不保存任何 token）。
-   仅当回退到 API Key 时，才会向 `api.deepseek.com` 的 `/user/balance` 端点查询余额（且只在你**主动刷新**或对话完成时）。
-   检查更新只请求 `registry.npmjs.org` 上本包的版本号，不发送任何账户信息；就地更新只下载本插件自己的发布包。
-   节假日数据来自公开的国务院公告镜像（`cdn.jsdelivr.net` 上的 holiday-cn），只读取、不上报。
-   插件不收集、不上传任何会话内容到第三方。
-   消费统计完全基于本地会话事件（`request/header`、`assistant/message` 的 token usage）计算，不向 DeepSeek 之外的服务发送数据。

## 价格表（空闲时段价，元/百万 tokens）

| 模型 | 输入（缓存未命中） | 输入（缓存命中） | 输出 |
| --- | --- | --- | --- |
| deepseek-flash | 1 | 0.02 | 4 |
| deepseek-v4-pro | 4.5 | 0.15 | 13.5 |
| deepseek-chat（旧） | 2 | 0.5 | 3 |
| deepseek-reasoner（旧） | 4 | 1 | 16 |

价格自 **2026-09-10 12:00（北京时间）** 起生效（flash 系列由 1.5 / 0.05 / 4.5 下调）；**高峰时段 = 空闲价 × 倍率（默认 2）**。调价前的历史消耗仍按当时的旧价计算，不会被重算。

DeepSeek 再次调价时需同步更新 `lib/index.js` 的 `MODEL_PRICING` 与 `lib/client.js` 的 `DEFAULT_PRICING`，并把被替换的旧价移入 `LEGACY_MODEL_PRICING`。

## 常见问题

**金额和官方页面上的不一致** 正常。本插件算的是**本地估算**（按事件 token × 价表），官方账单还包含插件看不到的口径差异，见上面「使用统计口径」。要准确数字就点「查看官方用量」。

**为什么调休上班的周末不算高峰？** 官方定价页原话是「其余时段，**包括周末**及中国法定节假日**全天**均为空闲时段」，没有为调休留例外。插件按这个口径实现。如果你有官方另有规定的证据，改 `lib/index.js` 的 `isPeakAt` 与 `lib/client.js` 的 `currentPeriod`（两处必须同口径）。

**设置里改了刷新间隔，怎么没立刻生效？** 服务端项需要重启 DeepSeek Harness；纯界面项（开关、样式、圆钮尺寸）刷新页面就生效。

**点了更新，但版本号没变？** 就地更新只是替换磁盘上的插件文件。Node 不会热替换已加载的模块，所以要**重启 DeepSeek Harness** 才会跑新代码。

**关掉了侧边栏入口，怎么找回来？** 左上角「插件」→ `balance-dsh` → 上面那张卡片里重新打开「侧边栏显示本插件」。

## License

MIT

## 常见问题

### balance-dsh 是什么？

在 DeepSeek Harness 中显示 DeepSeek 账户余额和当前会话 token/费用消耗（含高峰/空闲峰谷计费）。仅支持 DeepSeek 官方模型与账号，暂不支持其他大模型。

### 如何安装 balance-dsh？

在项目目录运行 npm install balance-dsh，或使用 pnpm add / yarn add / bun add。

### balance-dsh 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/balance-dsh 是否存在。

### balance-dsh 支持 ESM 还是 CommonJS？

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

### balance-dsh 需要什么版本的 Node\.js？

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

### balance-dsh 可以商用吗？

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

### balance-dsh 还在维护吗？

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