dsh-usage-state

dsh plugin --profile web add dsh-usage-state

余额与额度（dsh-usage-state）

中文 | [English](README.en.md)

 

0.4.15 新增 OpenAI 组织月消费（Admin Key）、插件内设置与草稿保存／重置，并修复旧配置保存、端点编辑、凭据归属及生命周期取消。宿主支持声明保持不变。安装包及校验文件见 GitHub Release，详情见 [更新日志](CHANGELOG.md#0415---2026-11-06)。

在 DSH（DeepSeek Harness） 输入框上方显示当前模型供应商的账户余额或套餐额度。状态行与输入卡片同宽，保留原生统计行和上下文计量器。

z.ai / GLM · ◔ 5h 12% (4h0m) · ◔ 7d 59% (3d17h)
DeepSeek · ¥58.13

功能

• 已识别的供应商默认使用“自动”，复用DSH已有凭据；每个provider配置一次，模型列表用于参考。
• 显示余额、已用百分比、重置倒计时和SVG进度环；默认≥80%琥珀、≥95%红，可调整阈值和隐藏进度环。
• 可显式启用 OpenAI Admin 模式，显示整个组织在当前 UTC 月已报告的 USD 消费，独立于余额与套餐额度。
• 同一有效账户身份的源请求失败时保留上次成功读数并标记陈旧、年龄和原因；RPC传输失败也会明确标出旧值。
• 悬停查看数据源、模式、重置时刻及余额构成；中英界面跟随DSH语言设置。
• 只显示账户当前读数，不做成本归因、价格目录、预算或历史账单。

安装

要求：DSH版本满足 ^0.2.0-rc.2 || ^0.2.1-rc.1（已验证0.2.0-rc.2及0.2.1-rc.1/rc.2/rc.3/rc.5），运行预构建插件声明Node≥20，安装到正在使用的 web profile。

从npm安装：

dsh plugin --profile web add dsh-usage-state
# 安装后重启DSH；bundle patch在启动时读取

也可从GitHub安装：

dsh plugin --profile web add github:takboo/dsh-usage-state

本仓库提交预构建产物，供DSH的GitHub安装路径直接使用。浮动GitHub分支可能领先于npm；复现问题时记录安装来源和版本/提交。不要把这一行为推广到所有npm Git安装。

也可通过 dsh-market 搜索 余额与额度、Balance & Quota、dsh-usage-state 或 takboo 安装；安装后核对实际来源与版本。本插件已进入 精选列表；目录更新的可见时间取决于所用区域与成功构建。

DSH0.1使用历史版本0.3.2；该版本不适配0.2。0.4.0有RPC挂载缺陷，应升级至最新兼容版。完整版本记录见 [更新日志](CHANGELOG.md)。

快速开始

0.4.15 起使用以下插件内设置入口与草稿操作，0.4.14 及更早版本仍使用原独立设置入口。新入口已在 Desktop 0.2.1-rc.5 实机打开，并在同版隔离浏览器完成保存／重置验证；支持声明中的更早宿主仍待补验该入口，历史 RPC 检查不代表新配置页已验收。

1. 打开 插件 → 余额与额度 → 配置，不再从全局设置侧栏进入。

2. 每个供应商一行，用下拉菜单选择“自动”、支持的 API Key 余额／账号余额／Coding Plan，或“隐藏”；行内查看检测模式、来源和状态，模型清单与高级覆盖默认折叠。

3. 自建 Sub2API 复用供应商已有接口地址；仅在地址缺失或需要覆盖时展开高级设置填写。账号模式由 Harness 管理登录，不提供 API Key 输入；OpenAI 官方普通密钥仍不查余额，可手动选择“组织月消费（Admin Key）”，配置独立 Admin 凭据。

4. 修改模式、排序、端点、刷新策略或显示选项后，点击保存设置统一生效；重置采用最新已保存配置，离开页面则丢弃未保存草稿。未保存的配置不改变输入框上方状态行。

5. “立即刷新”主动查询已保存配置的读数，不保存草稿；出错查看行内原因及 排查指南。

凭据名不是密钥本身。 使用 OAI_USAGE_READONLY 这类名称，格式为 [A-Za-z_][A-Za-z0-9_]*：首字符只能是英文字母或下划线，后续可含数字，不支持连字符、空格或中文。API Key 与 Admin 凭据名不合法时，设置页会提示并阻止保存设置及写入／清除密钥；修正名称即可，无需靠重启解决。

配置与凭据分开保存。 密钥区域的“立即保存密钥／立即清除密钥”是独立操作，不随配置重置撤回。修改模式、来源、端点或凭据名后，须先保存设置并取得当前目标的权限描述，才能操作密钥；显示或排序草稿不阻止独立密钥操作。API Key 高级设置提供端点、凭据名和密钥入口；显式 provider 覆盖优先于旧 source 默认，凭据描述与读取共用候选顺序。固定端点不试镜像，配置或凭据身份变化后清除旧身份读数。配置与凭据写权限分别处理；保存中防止重复提交，失败保留配置草稿。若其他页面已修改配置，先重置并重新修改，不静默覆盖外部变更。

数据源

来源 · 余额／消费读数 · Coding Plan读数 · 主要凭据

DeepSeek官方 API Key · CNY/USD余额 · — · DEEPSEEK_API_KEY

DeepSeek账号登录 · CNY/USD充值与赠送余额 · — · Harness当前登录账号

OpenAI官方 · 普通密钥无余额接口；显式 Admin 模式显示组织级本月 USD 消费（非余额） · — · 手动独立 adminKeyRef；自动不读取密钥

z.ai / 智谱GLM · — · 5h / 7d已用% · ZAI_API_KEY等

Kimi / Moonshot · 人民币余额 · Kimi Code订阅窗口 · MOONSHOT_API_KEY / KIMI_CODING_API_KEY

OpenCode Zen Go · — · 5h / 7d / 30d已用% · OPENCODE_GO_API_KEY / OPENCODE_API_KEY

Sub2API · 余额或key配额 · 按实例响应，如5h / 1d / 7d / 30d · SUB2API_API_KEY及实例地址

DeepSeek 桌面端账号登录：deepseek-account 路由自动选择「账号余额」，通过 Harness 登录服务读取充值与赠送余额之和，无需 API Key；deepseek-official 路由选择「API Key 余额」。两者独立查询和缓存，账号模式不会探测或回退使用 DEEPSEEK_API_KEY。请在 Harness 账号设置中登录；账号模式要求宿主提供账号服务；旧宿主缺少该服务时需升级宿主。账号模式的端点与登录凭据由宿主管理，高级区不提供 API Key 输入。

OpenAI 官方： 自动模式和普通 API Key 模式仍只提示余额接口限制，并提供官方账单入口，不读取普通密钥或探测余额接口。要查看消费：

1. 由组织 owner 在 Admin keys 创建管理密钥，尽可能仅授予读取 Usage 的权限；普通项目／推理密钥不可替代。不要因 403 自动扩大权限。

2. 在供应商行手动选择“组织月消费（Admin Key）”，填写独立 Admin 凭据名并先保存设置，再在凭据区立即保存密钥；也可引用已由宿主管理的同名凭据。密钥不写入插件配置，不自动发现或复用推理凭据。

3. 读数来自官方 Costs API，是整个组织在当前 UTC 日历月已报告的 USD 消费，不是本项目、当前模型／会话或此密钥自身消费，更不是余额、预算剩余或最终账单。提示中显示实际月份及查询时间；可能有入账延迟，查询时间不代表数据已入账至该时刻。完整查询无金额行显示“暂无数据”，明确返回 0 才显示零。费用按 UTC 日桶查询，省略当前秒 end_time 以免排除当天费用；返回桶仍按捕获时钟限制在本月截至当日。

官方来源优先按解析后的精确主机名 api.openai.com 识别，不按模型名、OpenAI 协议或字符串包含关系判断；第三方兼容平台仍按其余额协议接入。Admin 请求另有更严格的安全策略：固定 https://api.openai.com/v1/organization/costs、拒绝重定向，不使用 HTTP、自定义端口、网关／端点覆盖。若要将网关模型路由显式关联到官方组织消费，需手动选 OpenAI 来源，不能自动推断二者账户相同。换凭据或 UTC 跨月清除旧消费；同身份同月刷新失败才保留旧值。当前每个 source+mode 仍只有首个有效供应商拥有目标，不代表独立多组织支持。

Kimi Code 的 kimi-code、kimi-coding、kimi-for-coding provider，以及声明 api.kimi.com / api.kimi.ai 的自定义 provider，会自动读取套餐用量。支持 5h、7d、月总额度及编程月用量，仅展示账户实际返回的窗口。Moonshot 国内/国际 API 继续显示人民币余额；可在设置中显式选择模式。

百分比表示已用。z.ai的key分国内/国际区域；默认国内地址，失败可尝试镜像。当前缓存按数据源与模式合并，不能将不同密钥/实例视为已支持独立多账户。厂商端点、字段和扩展步骤见 适配器指南。

截图

OpenCode Zen Go三个窗口，独立状态行位于输入框上方：

设置迁移版在 Desktop 0.2.1-rc.5 上的实机截图，已裁去私有侧栏；以下截图早于新增 Admin 模式，不展示 Admin 凭据区。亮色下每个供应商一行，模式下拉与高级项默认折叠，OpenAI 自动模式说明余额接口限制：

暗色下展开官方 DeepSeek 高级项：模型仅供参考，端点与凭据引用按需覆盖；密钥保存／清除为独立即时操作，不受配置 Reset 撤销。

刷新与凭据

宿主默认在回合结束2秒后调度刷新，并有5分钟兜底定时器；浏览器每30秒拉取RPC镜像。普通轮询仅在读数缺失或有效身份变化时初始化查询，不把idle查询改成每分钟一次。成功请求的默认最小间隔为60秒，显式刷新可绕过，失败的主动重试不受该成功间隔限制；修改空闲间隔会重调定时器。

插件查询余额/额度并读取当前模型及供应商目录，不写会话日志，也不向第三方上报这些读数。宿主不把已保存的密钥值返回浏览器；用户主动粘贴的草稿经DSH凭据服务写入所用home的凭据文件。凭据优先级跟随宿主：DSH 0.2.1-rc.1/rc.2/rc.3 的 Web/桌面端优先使用已保存凭据，环境变量作为回退；0.2.0-rc.2 则优先使用环境变量。凭据权限以设置页实际返回为准。

…(truncated)