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 图集格式与灵感