余额状态环 dsh-plugin-lab/dsh-ds-balance

dsh-ds-balance

DeepSeek account balance in the DSH sidebar
把 DeepSeek 账户余额放进 DSH 的左边栏

Per-version changes → Releases (one-to-one with npm versions)

简体中文 · English

状态环固定在左边栏底部，点一下就能看到实际余额数字。要改设置，打开左边栏的 Plugins 页面，选中这个插件。密钥和账户都跟随官方 Models 页面，端点也是官方端点——这三样都不在这里设置。

数据与凭据

余额直接从 DeepSeek 官方 API 读取，不是根据用量估算出来的。

- 凭据通过 DSH 的凭据通道解析；插件自己不存密钥：密钥永远不会落进设置文件。
- UI 只能看到头尾掩码（sk-cf08d3b84，和 DeepSeek 平台控制台用的形状一样）；完整密钥不会出现在传输过程中，不会写进日志，也不会写进本插件的任何文件。
- 只访问 api.deepseek.com；不代理、不转发其他任何流量。
- 余额快照按凭据分别存储——换密钥就重新开始记录，旧数字绝不会混进来。

快速上手

前置条件：DSH 用当前 RC 线（安装时指定 @next）；Node >= 20。兼容范围的唯一来源是 package.json 里的 engines.dsh。

1. 安装宿主。latest 和 alpha 都不是我们声明的版本线，所以要指定版本线：

npm install -g @deepseek-ai/dsh@next

2. 安装插件：

dsh plugin --profile web add dsh-ds-balance

3. 启动（或重启）dsh --profile web；余额条目会出现在侧边栏底部。

从源码安装：先 git clone，再 pnpm install && pnpm run build，然后 dsh plugin --profile web add "$PWD" —— 同样需要重启。
pnpm install 这一步不能跳过：按路径安装时，仓库自带依赖，缺了依赖插件会显示为「未运行」。

显示什么

三个界面，各司其职：

| 界面 | 位置 | 作用 |
| 状态环 | 固定在侧边栏底部 | 一眼看出还剩多少、离警告阈值还有多近 |
| 余额浮层 | 点击展开 | 查看总额、赠送 / 充值各占多少，以及数据是几分钟前的 |
| 设置卡片 | 插件下的本插件详情页 | 查看两种读取余额的方式，并设置货币、警告阈值和刷新频率 |

条目固定在侧边栏底部；点击它打开余额浮层：总额、赠送 / 充值各占多少、数据是几分钟前的，右下角可手动刷新。

状态环本身表达的是「此刻是什么情况」，五种状态一眼可辨：

| 状态环 | 含义 | 你该做什么 |
| 彩色环 + 一段弧 | 有余额；颜色表示多还是少 | 读数字 |
| 灰色环 + 旋转缺口 | 正在拉取，还没有结果 | 等待 |
| 灰色环 + 中间一个 + | 还没连上你的账号 | 去配置 |
| 灰色空环 | 已连上账号，只是账号里没有余额 | 无需处理 |
| 红色环 + 中间一个 叉 | 这里没有可用的数字 | 检查一下 |

各项含义

| 项 | 含义 |
| 弧长 | 余额占该货币警告阈值的比例，最多画满一圈 |
| 颜色 | 只表示状态（正常 / 偏低 / 严重），从不表示金额；严重阈值只决定颜色，不参与画环 |
| 中间的标记 | + 表示还没连上，去配置；叉 表示这里没有可用的数字 —— 可能是读不到，也可能是读到了但账号不可用 |
| 悬停文字 | 数字可信时显示金额，否则显示该状态自己的一句话；折叠和展开说的是同一句 |
| 来源方括号 | 浮层标题右侧：这个数字来自哪个凭证 —— 形如 sk-cf08d3b84 的头尾掩码，或已登录账号的名称 |
| 数据新鲜度 | 浮层里的「多久之前」，从数据到达那一刻算起 |
| 手动刷新 | 有冷却时间；刷新结束后冷却重新计时，弹层上显示的秒数是真实剩余秒数 |
| 设置分组 | 连接 / 显示 / 阈值 / 刷新 |

配置

卡片位于 Plugins 页面：侧边栏 Plugins → 「Installed」→ 点击 DeepSeek Balance 卡片，进入它的详情页。

配置区就在详情页上，紧挨着描述下方，可以直接编辑：

- 连接 —— 只读：这个插件读取余额的两种方式、每种方式当前用的是哪一种、凭据来自哪里，还有一个 Test 按钮，会真正调用服务商。
- 显示 —— 金额使用哪种货币，也可以让它跟随账户。
- 阈值 —— 每种货币两行：一个警告阈值和一个严重阈值。同一种货币内，严重值必须低于警告值；否则无法保存。
- 刷新 —— 服务端刷新间隔、UI 轮询间隔和手动刷新冷却时间；默认值适合大多数场景。

保存后立即生效，无需重启 DSH。

详情页上的配置区。某一项填写无效时，所在分组会自动展开。

升级说明：这些设置所在的键名随一次宿主升级改过一次，旧值不会迁移；升级后请按上面的说明重新填写四个分组。另外，3.0 版本移除了两项设置：手写的 apiKey 和自定义 baseUrl 现在都不生效 —— 凭据用的是官方 Models 页面保存的那一个，端点也是官方端点。如果你之前手动设置过，请从设置文件里删掉。

版本兼容性

- 需要哪个宿主版本：以 package.json 中 engines.dsh 声明的为准 —— 这个范围列出了本插件覆盖的宿主产品线，包含上限；超出上限的一概不支持。如果你需要设置 UI，请把宿主升级到最新产品线：npm install -g @deepseek-ai/dsh@next。
- 声明会逐条列出产品线：只有 engines.dsh 中列出的产品线才有承诺。超出上限的新产品线，只有在 compat.yml 矩阵中测过、并写入声明之后才会得到支持；它不会自动跟随宿主。已列出产品线内的补丁版本（含预发布版）无需修改声明。
- 兼容性靠实测：每周 compat.yml 会在声明的宿主产品线上跑测试，另有一个独立步骤检查声明的范围是否仍覆盖它；已提交的产品线一旦变红就会开一个跟踪 issue。判定与处理方式见：兼容性。

许可证

MIT。

参与贡献

Bug 和需求请提到仓库 Issues。

维护者文档地图 → AGENTS.md。