鲸鱼娘用量宠物 ShanHaiFish/dsh-usage-pet

dsh-usage-pet

DeepSeek Harness 的悬浮鲸鱼娘宠物：跟着当前会话的模型，显示 OpenCode Go 额度、DeepSeek 账户消费/余额与 DeepSeek 官方 API 余额。

这是什么

dsh-usage-pet 是 DeepSeek Harness（dsh）Web 的静态 bundle 插件。它在对话输入框上方放一只会游动的「鲸鱼娘（精致版）」，跟随当前会话使用的模型自动切换面板：

| 供应商（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 |

当前会话切到其他供应商时卡片自动隐藏，切回受支持模型时重新出现。

功能

- 多厂商用量面板：同一个悬浮卡随会话模型切换，不额外占页面空间，也没有侧边栏入口或独立页面。
- 可爱的宠物动画：6 帧待机雪碧图（3.2 秒循环）+ 轻微上下浮动；prefers-reduced-motion 下自动停止。
- 可拖动：收起态按住整卡、展开态按住标题栏即可拖动；位置存进 localStorage，窗口缩放时自动钳回视口，一键复位。
- 详情视图：原地展开，显示额度/余额拆分、重置时间与倒计时、更新时间，以及刷新/收起按钮；Esc 可关闭。
- 自动刷新：每 60 秒刷新一次（页面不可见时暂停），也可手动强制刷新。
- 只看该看的：OpenCode Go 达到 70% / 90% 时切换警告色/错误色；账户未登录、密钥缺失、上游异常都有独立错误提示。
- 主题与双语：所有样式使用 dsh 主题 token，跟随明暗主题；中英文文案齐全。
- 凭据不落地到浏览器：所有密钥和 DeepSeek Platform token 都只存在于 Host 半区，浏览器只拿到归一化后的百分比和金额。

界面预览

安装

要求：

- dsh Web profile ≥ 0.2.1-rc.2
- Node.js ≥ 20（Host 半区运行在 dsh 进程里）
- 按需准备凭据：
- OpenCode Go：OPENCODE_GO_API_KEY
- DeepSeek 官方 API：DEEPSEEK_API_KEY
- DeepSeek 账户：在 dsh 设置里登录即可，无需额外密钥

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 半区在进程启动时加载）。之后打开对话页，当前模型属于上述供应商时就会看到悬浮卡。

macOS / Linux 用户把 (Get-Location).Path 换成 "$(pwd)" 即可。

配置

插件的 loader 行可以覆盖以下配置（cordis.patch.yml 或 profile patch 层）：

| 字段 | 默认值 | 说明 |
| credentialRef | OPENCODE_GO_API_KEY | OpenCode Go 密钥的 dsh 凭据引用（环境变量名形式） |
| baseUrl | https://opencode.ai | OpenCode API 源站；只接受 HTTPS（本机回环地址可用 HTTP） |
| timeoutMs | 20000 | 上游请求超时（1000–120000 毫秒），三个服务商共用 |
| providerId | opencode-go | OpenCode Go 的服务商 id |
| deepseekApiKeyRef | DEEPSEEK_API_KEY | DeepSeek 官方 API 密钥的 dsh 凭据引用 |
| deepseekBaseUrl | https://api.deepseek.com | DeepSeek 官方 API 源站；只接受 HTTPS（本机回环可用 HTTP） |
| accountClientVersion | 0.5.0 | 请求 DeepSeek Platform 时发送的 x-client-version（身份标识，可保持默认） |

示例：

- id: dsh-usage-pet
config:
credentialRef: OPENCODE_GO_API_KEY
deepseekApiKeyRef: DEEPSEEK_API_KEY
timeoutMs: 20000

密钥本身走 dsh 凭据存储（~/.dsh/.credentials.yaml 的 refs），也支持进程环境变量同名回退；插件不会写入或回显密钥。浏览器路由和内置路由一样，都要经过 dsh connection 的 Host/Origin 与会话鉴权。

数据与隐私

浏览器只访问插件自己的同源路由：

GET /dsh-usage-pet/api?provider=<id|auto>&lang=<locale>&tz=<offsetMinutes>

- provider=auto 按进程默认模型选择服务商；未知服务商返回 unsupported-provider，卡片随之隐藏。
- 每个服务商独立做 10 秒成功缓存与并发合并，?refresh=1 强制刷新。
- DeepSeek 账户通过 dsh 的 deepseekAccount 服务读取：getState() 判断登录状态，getPlatformSession() 提供 Host 专用 会话，再由 Host 读取 Platform 账户摘要；token 不会进入浏览器。摘要接口不可用时，降级到 getBalance() 的钱包读取（无累计消费）。
- 插件不收集遥测，不写入除 localStorage 拖动位置以外的任何浏览器数据。

开发与测试

npm run check # node --check index.js / client.js
npm test # 离线契约测试：Host 42 项 + Client 50 项

- Host 契约测试（test/host-contract.test.mjs）完全离线：本地 HTTP 桩模拟 OpenCode、DeepSeek Platform 与 DeepSeek 官方 API，覆盖三个服务商的路由、缓存、鉴权、错误映射与凭据不泄漏。
- Client 契约测试（test/client-contract.test.mjs）用桩浏览器环境 + 最小 hook 渲染器，校验 slot 注册、locale 键集、内嵌素材一致性、额度/余额渲染、拖动/位置记忆/复位生命周期。
- 改 client.js 时 dsh-client-hmr 会热替换浏览器半区；改 index.js 需要重启 dsh 进程。

项目结构

dsh-usage-pet/
├── index.js # Host 半区：凭据解析、三供应商采集、同源路由 ├── client.js # 浏览器半区：悬浮卡、面板渲染、拖动、i18n ├── cordis.patch.yml # dsh bundle patch 入口 ├── assets/ │ ├── whale-girl-idle.webp # 内嵌进 client.js 的 6 帧待机条带 │ └── README.md # 素材来源与再生成步骤 ├── locale/ # 插件元数据（zh / en） ├── docs/ # README 预览图 ├── test/ # 两端契约测试 ├── THIRD_PARTY_NOTICES.md # 形象素材署名与许可 └── LICENSE # MIT

已知边界

- OpenCode Go 接口返回百分比而非美元金额；percent 由上游按模型权重折算，插件只做展示。「剩余额度 / 折合月额度」是展示层推算，依赖 README 中的额度占比假设。
- DeepSeek 官方 API 只提供余额与可用状态，不提供历史消费明细；金额保留服务端字符串并做两位小数本地化展示。
- DeepSeek 账户的「累计消费」来自 Platform 账户摘要端点；不可用时降级为钱包余额（无累计消费）。该面板要求 dsh 已登录 DeepSeek 账户，且构建包含 deepseekAccount 服务。
- 服务商跟随当前会话的有效模型；切到未支持的服务商会自动隐藏卡片。全新且未发消息的会话在 Host 返回 defaultModel 前可能稍晚出现。
- 拖动位置只保存在本浏览器 localStorage，不上传、不跨浏览器同步；拖动仅支持指针/触摸，键盘仍可展开/收起。
- 该路由只返回用量/余额聚合值与官方用量页链接，不含凭据；仍建议只在可信网络下暴露 dsh Web。

素材与许可

- 悬浮宠物形象使用 Codex 宠物包 @linxin666/dsh-pet（v0.4.8）中的「鲸鱼娘（精致版）」（whale-girl-refined）。其 pet.json 声明 license: MIT，精致版参考 DreamSkin 的「DeepSeek-Whale」主题（原作者 powerdog996，记录为 MIT）。
- 本仓库只从原图集裁出 idle 行前 6 帧，缩放为 768×139 WebP，没有其他修改；署名、MIT 文本与同人/非官方说明见 THIRD_PARTY_NOTICES.md，裁切与再生成步骤见 assets/README.md。
- 鲸鱼娘是社区同人形象：DeepSeek 名称与鲸鱼标识归 DeepSeek 所有，本项目与 DeepSeek 无隶属、赞助或官方授权关系，不把该形象呈现为官方作品；素材按个人非商业用途使用。商用或公开再分发前请先核对许可并取得相应授权。
- 本项目代码以 MIT License 开源。

贡献

欢迎 Issue 和 PR。提交前请先看 CONTRIBUTING.md，并确保 npm run check && npm test 通过。新增服务商时请同步更新 README、locale 文案与两端契约测试。

致谢

- DeepSeek Harness —— 插件宿主与客户端模块契约
- @linxin666/dsh-pet 与 powerdog996 / DreamSkin —— 悬浮宠物形象与主题来源
- Codex Pets / Petdex 社区 —— Code Pet 图集格式与灵感