dsh-balance

一句话定位

这是一个 DSH 插件，让你在 Web 界面"设置"里查看 DeepSeek API 账户余额（总余额、充值余额、赠送余额）和当前 API Key 可用的模型，并在每个聊天会话的输入框下方长期显示一个小余额指示灯。

核心能力

• 在 DSH 设置里新增"DeepSeek 余额"专属页面，展示总余额、充值余额、赠送余额，以及"有可用余额 / 无可用余额"状态指示
• 在每个会话的输入框下方长期挂一个紧凑的余额摘要（按币种列出总额），状态点随可用性变化颜色（绿/灰/红）
• 高峰时段（北京时间 09:00–12:00、14:00–18:00）聊天框下方的余额指示灯变为橙色，并提示距下一时段切换的时间
• 列出当前 API Key 可访问的全部 DeepSeek 模型，每条展示模型 ID 和归属方
• 同源 Host 接口内置 30 秒缓存（可配置），设置页面有手动刷新按钮，请求 URL 加 ?refresh=1 可绕过缓存
• 默认仅允许 127.0.0.1 / localhost / [::1] 同源访问，API 密钥始终留在本机 Host，浏览器从不接触密钥

技术实现

• 语言: TypeScript（ESM）
• 关键依赖: @deepseek-ai/cordis、@deepseek-ai/schemastery、@deepseek-ai/dsh-credentials、@deepseek-ai/dsh-host-webserver、``@deepseek-ai/dsh-client-ui-slots`
• 架构模式: 典型的 Host/Client 双面插件 — Host 端在 webServer 注册两条 kind: 'exact' 同源路由 /dsh-balance/api/balance 与 /dsh-balance/api/models；Client 端通过 ctx.slots.inject 在 settings.section 注册独立设置面板，在 conversation.composer.dock 注册聊天框余额挂件
• 入口文件: src/index.ts（Host）+ src/client/index.tsx（Client）

适用场景

在 DSH 中频繁使用 DeepSeek API 时，普通用户希望随时掌握账户余额和可用模型，不必反复登录 DeepSeek 后台查消耗；同时给希望直观判断"现在调用 API 是高峰还是低谷价"的用户提供时段提示。

前置依赖与兼容性

安装方式

dsh plugin --profile web add github:crazywoola/dsh-balance

配置项

通过 DSH 配置系统（src/index.ts:14-28 中的 Config Schema）暴露：

常见问题

Q: 安装后看不到余额页面怎么办？

A: API Key 是查询余额的前提，需要先在 DSH 设置 → 模型 中保存 DeepSeek API 密钥，或设置环境变量 DEEPSEEK_API_KEY，否则接口会返回 401 MISSING_API_KEY，余额页面会显示"未配置 DeepSeek API 密钥"。

Q: 这个插件会向浏览器泄露 API Key 吗？

A: 不会。API Key 只在本机 Host 端被读取（通过 DSH 凭据服务 ctx.credentials.resolve），浏览器只通过同源接口 /dsh-balance/api/balance 与 /dsh-balance/api/models 拿到余额和模型数据，密钥从不离开本机进程。

Q: 聊天下方的指示灯什么时候会变成橙色？

A: 余额指示灯在北京时间 09:00–12:00 和 14:00–18:00 这两个高峰时段显示为橙色，其他时段为绿色；高峰期 API 价格是低谷的两倍，2026-08-17 起按 DeepSeek 官方峰谷定价生效。

Q: 为什么我的请求被拒 403？

A: 插件默认仅允许本机（127.0.0.1 / localhost / [::1]）访问这两个接口，非本机访问会直接返回 403 FORBIDDEN。如果确实需要在同网段其他机器访问，可将配置 allowRemote 设为 true。

Q: 数据多久刷新一次？

A: 聊天框下方的余额指示灯默认 60 秒刷新一次，设置页面点击"刷新"按钮可绕过 30 秒缓存立即拉取；后端 Host 默认 30 秒缓存（cacheMs）。

Q: 余额数字多久会变成最新值？

A: 设置面板与聊天指示灯都遵循同一个 30 秒缓存；点击"刷新"按钮或在请求 URL 后加 ?refresh=1 可绕过缓存立刻拿到最新值。

Q: 支持哪些语言？

A: 原生提供简体中文和英文两套字典，会跟随 DSH 系统语言自动切换；切换逻辑在客户端的 locale 注册处完成。

Q: 如何卸载这个插件？

A: 通过 dsh plugin --profile web remove @pinkbanana/dsh-balance 卸载，插件只在内存中缓存查询结果，不写入任何本地文件或凭据，卸载即彻底清除。

上手难度

入门 — 安装后只要在设置里保存一次 DeepSeek API Key 即可使用，无需手写任何配置文件；想调节缓存、远程访问、API 地址等行为时再配置 Schema 即可。

已知问题与限制

• 客户端代码保留了 @deprecated 标记的 BalanceTab 与 ModelsTab 导出（src/client/BalanceTab.tsx:94、src/client/ModelsTab.tsx:85），它们原是"插件"标签页下的入口，现已被独立的 DeepSeekPanel（设置里的"DeepSeek 余额"板块）取代；旧入口在 0.4.x 之后的 DSH 版本可能不再渲染
• timeoutMs 上限为 60 秒、cacheMs 上限为 300 秒（src/index.ts:25-28），不适合需要长轮询或长缓存窗口的场景
• baseUrl 仅允许 HTTPS，HTTP 仅对 127.0.0.1 / localhost / ::1 三个回环地址放开，用于本地调试；公网 HTTP 端点会直接抛错
• 高峰/低谷判定（src/client/pricing.ts:14）写死生效时间为 2026-08-17 北京时间零点，DeepSeek 后续若再次调整峰谷时段，需要更新源码中的 PEAK_WINDOWS 数组并重新发布

简体中文 | English

DeepSeek Harness 插件，用于查询 API 余额和当前可用模型。API Key 仅由本机 Host 使用，不会发送到浏览器。

功能

• 查看总余额、充值余额和赠送余额
• 在聊天框下方持续显示余额摘要
• 查看当前 API Key 可用的模型
• 缓存查询结果并支持手动刷新
• 依据 DeepSeek 峰谷定价，在高峰时段（北京时间 9:00–12:00、14:00–18:00）将聊天框下方的余额指示灯变为橙色
• 原生支持简体中文和英文，并跟随 Harness 系统语言切换
• 支持 Harness 已保存的 DEEPSEEK_API_KEY

安装

dsh plugin --profile web add @pinkbanana/dsh-balance@latest
dsh --profile web

打开 http://127.0.0.1:3080/，进入“设置 → DeepSeek 余额”。该入口位于“Agent 预设”下方，余额摘要也会显示在已有会话的聊天框下方。API Key 可在“设置 → 模型”中保存，或通过 DEEPSEEK_API_KEY 环境变量提供。

开发

pnpm install
pnpm check

License

MIT