前言¶
在 DeepSeek Harness（DSH）里跑多模型、多提供商时，账户余额和订阅余量往往分散在各个后台或上游接口里。要在开发或日常使用里随时判断「还能不能用、离限流还有多远」，通常得切页面或靠经验猜。社区里已有 dougen/dsh-deepseek-usage 等实现；dsh-usage（AAxium/dsh-usage）是在其基础上二次开发的非官方分支，由维护者 AAxium 独立维护，侧重侧栏表盘、额度分组与设置整理，并在 v1.0.2 预览版中加固额度查询相关的网络请求。下面介绍它是什么、能做什么，以及如何在本机 DSH 中安装与使用。
这是什么¶
dsh-usage 是面向 DSH 的客户端插件：在侧栏展示当前模型相关的账户余额或订阅余量，并在设置页管理监控目标与额度分组。包名为 dsh-usage，当前文档标注版本为 v1.0.2 preview（维护与加固预览版）；未发布到 npm，不要执行 npm install dsh-usage，以免装到同名其他项目。
项目声明基于 dougen/dsh-deepseek-usage 二次开发，不代表原作者或 DeepSeek 官方。分类上属于 DSH 生态的客户端能力（package.json 中 dsh.client.platform 为 web）。许可为 MIT。
核心功能¶
资料中明确的能力如下，具体是否可用仍取决于上游接口与宿主服务。
账户用量与额度分组¶
- 账户用量：按当前模型和提供商展示余额或订阅剩余额度。
- 模型额度分组：区分 Gemini 与 Claude/GPT 等额度组，分别处理 5 小时窗口与周窗口；缺失窗口标记为不可用，不跨组补值。
侧栏表盘与配色¶
- 侧栏表盘：放大数字，辅以「5 时」「周额」「月额」等下标；支持 D 形、圆环、半圆、紧凑和详细等样式。
- 连续配色：随已用比例从绿到橙再到红平滑过渡；默认剩余 40% 为橙色锚点、剩余 20% 为红色锚点，阈值可配置。
设置与路由¶
- 监控设置：概览与额度组置顶；提供商映射和 OAuth 放在默认折叠的「高级设置」。
- 监控与模型路由分离：监控目标不会自动等同于实际模型路由；插件提供独立的路由查看与管理入口。
README 中的表盘预览图为本项目渲染函数生成的模拟数字，并非真实账户截图。
相对上游的主要调整¶
本分支在用户提供的候选代码上继续完善，涉及：模型额度识别和分组、监控与路由设置、侧栏展开详情、设置页布局、中文标签与渐变配色，以及额度查询相关的网络请求安全加固。上游公开版本 0.20.0 的追溯链接见 原项目提交；本分支版本号与上游不对应。
安装与启用¶
环境要求¶
- 已安装并可正常使用的 DSH / DSH Desktop，具备插件加载能力。
- 开发与本地验证文档使用 Node.js 24；宿主依赖范围见仓库
package.json的peerDependencies（如@deepseek-ai/dsh-credentials、@deepseek-ai/dsh-host-webserver、@deepseek-ai/schemastery等）。文档不保证每个宿主版本都经实际测试。 - 查询需要对应提供商的有效凭据，或宿主提供的账户服务；插件不会生成额度，也不能保证所有反代都有查询接口。
从源码或发布包安装¶
- 从 GitHub Releases 获取 v1.0 源码或压缩包，解压到准备长期保留的目录（README 亦提到可克隆仓库；你也可按习惯获取源码，但安装步骤以本地路径为准）。
- 先备份 DSH 配置。若已安装上游版或旧分支，先停用旧版，不要同时加载两者。
- 使用当前 DSH 版本支持的本地插件安装方式。README 中已确认支持目录参数的示例为：
dsh plugin --profile desktop add /absolute/path/to/dsh-usage
Windows 路径含空格时请加引号。Web 宿主将 desktop 改为实际使用的 profile 名称。该命令会修改对应 profile，不宜在未备份时反复试装。
- 按宿主提示重新加载插件或重启 DSH，在侧栏及用量设置页检查提供商、模型和账户是否正确。
迁移提示：包名与浏览器模块 ID 已改为 dsh-usage，内部配置 ID deepseek-usage、API 路径 /api/deepseek-usage 及凭据引用保留以减少兼容变化；旧包引用仍可能需要迁移，文档未宣称一键无损迁移。
典型用法与凭据¶
凭据由 DSH 服务管理，查询时会发给对应提供商用于授权。不要将真实令牌、auth.json、.credentials.yaml、.env、运行日志或真实账户截图提交到仓库。
高级设置中的手动映射只决定额度适配器，不等于修改实际模型路由。安装并 reload 后，在侧栏查看表盘，在设置页配置监控目标与额度分组；需要时在高级设置中调整提供商映射或 OAuth。
安全与已知限制¶
安全加固（v1.0.2）¶
README 记载：已修复账户/额度查询中的危险 IP、映射 IPv6 绕过、DNS 失败放行和二次解析等风险；加入流式响应及解压限额，并移除原始异常日志。远程 HTTP、私网、保留地址、危险或失败的 DNS 解析会被拒绝；明确的本机回环代理保留。请求使用 Node 直接传输，不自动继承全局 fetch dispatcher 或隐式 HTTP_PROXY。
本地验证记录（2026-11-08）：标准 npm test 为 222 项通过、0 失败。这是项目自述的自动化测试结果，不是第三方独立安全审计。模型推理由 DSH 宿主负责，不能据此认为整个 DSH 都完成了相同网络防护。细节见仓库 SECURITY.md 与 docs/VALIDATION.md。
已知限制¶
- 尚未覆盖所有真实账户、提供商返回格式、DSH 版本、主题或安装迁移组合。
- 底部 DeepSeek 模块目前为说明卡片，尚不是完整用量面板的独立迁移。
- Node 22 及其他平台以实际 CI/用户环境为准；完整本地测试环境文档记载为 Windows + Node 24。
- 插件以当前 DSH 进程权限运行；安装前应阅读源码与 MIT 许可，并结合自身环境评估。
项目为 vibe coding / AI-assisted development，AI 参与开发与测试不代表经独立人工安全审计。
结尾¶
dsh-usage 适合需要在 DSH 侧栏直观查看模型额度与账户用量、并愿意从 GitHub 发布包或源码本地安装的非官方客户端插件用户。目录页：skillhub.cn 上的 dsh-usage；源码与 Releases：github.com/AAxium/dsh-usage。问题可通过 Issues 反馈，提交时请脱敏并注明 DSH 与 Node 版本。
