前言¶
在 DeepSeek Harness（dsh）Web 里跑多供应商模型时，额度与余额往往分散在各自控制台或环境变量背后。切到 OpenCode Go、DeepSeek 官方 API 或已在 dsh 登录的 DeepSeek 账户时，若要在对话现场一眼看到剩余窗口与余额，通常得另开页面或自己拼脚本。dsh-usage-pet 把用量聚合进对话输入框上方的一张可拖动悬浮卡，并用社区同人形象「鲸鱼娘（精致版）」做待机动画，属于 dsh 社区目录里的「趣味换装」类静态 bundle 插件。
这是什么¶
dsh-usage-pet 由维护者 ShanHaiFish 发布，仓库为 github.com/ShanHaiFish/dsh-usage-pet，在 SkillHub 插件目录 可查到条目。它是 dsh Web 的 bundle 插件：Host 半区拉取上游用量，浏览器半区只渲染归一化后的百分比与金额，密钥与 Platform token 不进入浏览器。
当前会话使用的模型属于下列供应商时，同一张卡片会切换对应面板；切到未支持的供应商时卡片隐藏，切回后重新出现。
| 供应商（provider id） | 面板内容 | 数据来源 |
|---|---|---|
OpenCode Go（opencode-go） |
5 小时 / 每周 / 每月三窗口已用百分比、重置倒计时；展开后显示剩余额度与折合月额度 | GET https://opencode.ai/zen/go/v1/usage |
DeepSeek 账户（deepseek-account） |
累计消费、余额、赠送余额；展开后可跳转官方用量页 | dsh deepseekAccount 服务 + DeepSeek Platform account summary |
DeepSeek 官方 API（deepseek-official） |
可用状态、总余额、赠送、充值余额 | GET https://api.deepseek.com/user/balance |
项目以 MIT 许可证开源，当前 package 版本为 0.5.0（以仓库 package.json 为准）。
核心功能¶
下面介绍 README 中已写明、且与实现对应的能力。
多厂商用量面板：不单独占侧边栏或独立页面；跟随当前会话有效模型切换内容。OpenCode Go 在用量达 70% / 90% 时切换警告色与错误色；账户未登录、密钥缺失、上游异常有独立提示。
宠物与交互：6 帧待机雪碧图（约 3.2 秒循环）并轻微上下浮动；系统开启 prefers-reduced-motion 时动画停止。收起态可拖整卡，展开态拖标题栏；位置写入本机 localStorage，窗口缩放时钳回视口，支持一键复位。详情在原位展开，含刷新与收起，Esc 可关闭。
刷新与缓存：每 60 秒自动刷新（页面不可见时暂停），也可手动强制刷新。浏览器访问同源路由 GET /dsh-usage-pet/api?provider=<id|auto>&lang=<locale>&tz=<offsetMinutes>；provider=auto 按进程默认模型选供应商。各供应商成功结果有 10 秒缓存与并发合并，?refresh=1 可强制刷新。
主题与文案：样式使用 dsh 主题 token，跟随明暗主题；中英文文案齐全。
环境与凭据¶
启用前确认：
- dsh Web profile ≥
0.2.1-rc.2 - Node.js ≥
20（Host 半区运行在 dsh 进程内） - 按需准备凭据：
- OpenCode Go：环境变量或 dsh 凭据引用
OPENCODE_GO_API_KEY - DeepSeek 官方 API：
DEEPSEEK_API_KEY - DeepSeek 账户：在 dsh 设置里登录即可，无需额外密钥
密钥走 dsh 凭据存储（~/.dsh/.credentials.yaml 的 refs），也支持同名环境变量回退；插件不写入或回显密钥。
安装与启用¶
官方 README 给出的安装步骤如下。先把插件目录放到本机，再用 dsh plugin 指向该路径加入 Web profile；macOS / Linux 将 PowerShell 的 (Get-Location).Path 换成 "$(pwd)"。
git clone https://github.com/ShanHaiFish/dsh-usage-pet.git
cd dsh-usage-pet
dsh plugin --profile web add (Get-Location).Path
安装后重启一次 dsh web（Host 半区在进程启动时加载）。打开对话页，当前模型属于上述供应商时即可看到悬浮卡。
配置¶
可在 loader 行通过 cordis.patch.yml 或 profile patch 覆盖部分字段，例如：
- id: dsh-usage-pet
config:
credentialRef: OPENCODE_GO_API_KEY
deepseekApiKeyRef: DEEPSEEK_API_KEY
timeoutMs: 20000
常用配置项（默认值见 README 表格）包括：credentialRef、baseUrl（默认 https://opencode.ai）、timeoutMs（默认 20000，三供应商共用）、providerId（默认 opencode-go）、deepseekApiKeyRef、deepseekBaseUrl（默认 https://api.deepseek.com）、accountClientVersion（默认 0.5.0）。baseUrl 与 deepseekBaseUrl 仅接受 HTTPS（本机回环可用 HTTP）。
典型用法¶
1、在 dsh Web 中把对话模型设为 OpenCode Go、DeepSeek 账户或 DeepSeek 官方 API 之一，确认对应凭据或登录状态已就绪。
2、在输入框上方查看收起态：OpenCode Go 显示三窗口进度与倒计时；DeepSeek 侧显示消费或余额摘要。
3、点击展开查看拆分数据、重置时间与更新时间；需要即时数据时使用刷新按钮，或依赖 60 秒自动刷新。
4、拖动卡片到不挡输入的位置；位置仅保存在当前浏览器，换浏览器或清站点数据需重新摆放。
开发调试时，仓库提供 npm run check（语法检查）与 npm test（Host / Client 离线契约测试）。改 client.js 可由 dsh-client-hmr 热替换浏览器半区；改 index.js 需重启 dsh 进程。
适用场景与注意¶
适合经常在 dsh Web 里切换 OpenCode Go 与 DeepSeek 线路、希望在对话页直接盯额度与余额的开发者。宠物形象来自社区素材包 @linxin666/dsh-pet 的「鲸鱼娘（精致版）」，与 DeepSeek 无官方隶属关系；商用或再分发前需自行核对 THIRD_PARTY_NOTICES.md 与许可。
插件以当前 dsh 进程权限访问上游 API 与 Platform 会话，安装前应阅读源码与 MIT 许可证，仅在可信网络下暴露 dsh Web。已知边界包括：OpenCode Go 上游返回百分比而非美元金额，「剩余额度 / 折合月额度」为展示层推算；DeepSeek 官方 API 无历史消费明细；DeepSeek 账户摘要不可用时会降级为钱包余额且无累计消费；全新未发消息的会话可能在 Host 返回 defaultModel 前稍晚出现卡片。
结尾¶
dsh-usage-pet 把 OpenCode Go 三窗口额度、DeepSeek 账户消费/余额与官方 API 余额收进一张跟随模型的悬浮卡，并用鲸鱼娘动画降低「查用量」的上下文切换成本。条目与说明见 SkillHub 目录页，源码与安装细节见 GitHub 仓库。
