dsh-deepseek-balance-badge

DeepSeek Harness (DSH) 的插件生态允许在客户端侧边栏集成功能。对于需要频繁调用 DeepSeek API 的开发者来说，实时监控账户余额至关重要。dsh-deepseek-balance-badge 旨在解决这个问题，它将余额信息嵌入 DSH 的 Web GUI 侧边栏底部。

该插件由 chenjingchun 维护，开源协议为 MIT。其核心价值在于将余额查询集成到工作流中，同时保持安全性和可配置性。

核心功能¶

侧边栏常驻徽标：在 Web GUI 侧边栏底部显示 DeepSeek 账户余额。徽标支持收起态（36px 圆形）与展开态（显示余额数值）。
明细浮层：点击徽标展开详情浮层，展示总余额、赠送余额、充值余额。浮层内含手动刷新按钮。
自动刷新与设置：插件支持按固定周期自动刷新。刷新周期（pollSeconds）与宿主缓存窗口（cacheTtlSeconds）可通过“设置 → 插件 → 插件配置”里的卡片进行调整。
安全机制：API Key 永不进入浏览器。浏览器仅访问同源宿主路由，密钥保留在宿主进程中。这避免了因 api.deepseek.com 不返回 CORS 头导致的浏览器直连失败问题。
多币种支持：支持逐行展示不同币种的余额。

安装与启用¶

使用 DSH CLI 安装该插件：

dsh plugin --profile web add dsh-deepseek-balance-badge

安装完成后刷新页面即可。宿主半（Host）在首次安装后需要重启一次应用才能生效。

配置说明¶

配置分为两层：

用户层：位于 ~/.dsh/settings.yaml 的 dsh-deepseek-balance: 分节。用户可在“设置 → 插件 → 插件配置”中直接修改，或编辑 YAML 文件。
组合层：位于 profile 的 cordis.patch.yml 里本插件条目的 config:。这是部署者配置，包含 apiKeyRef、baseUrl 等不直接暴露给用户的字段。

当两层配置了同一个键时，用户层生效。如果发现配置修改不生效，应先检查是否在卡片中覆盖了默认值。

# profile 的 cordis.patch.yml（组合层示例）
- id: dsh-deepseek-balance
  config:
    pollSeconds: 300      # 自动刷新周期（秒）
    apiKeyRef: DEEPSEEK_API_KEY
    baseUrl: https://api.deepseek.com
    cacheTtlSeconds: 10   # 宿主结果缓存窗口

卡片仅暴露 pollSeconds 与 cacheTtlSeconds。修改配置后无需重启，宿主会即时重新解析。

使用方式¶

查看余额：侧边栏底部会常驻余额徽标。点击可展开查看明细。
手动刷新：在浮层中点击“刷新”按钮。该操作会携带 ?force=1 参数，跳过宿主缓存，强制从上游拉取最新数据。
调整周期：在“设置 → 插件 → 插件配置”中修改轮询周期。该设置会立即应用到下一次轮询中。
后台行为：页面不可见时插件会跳过轮询以省电。页面回到前台且数据已过期时，会立即补拉。

行为细节¶

单飞机制：宿主的并发轮询会共享一次上游调用，避免刷新风暴。
错误处理：上游出错时，插件会保留上次成功的数据，并在浮层内显示错误码与原因，不会清空界面。
UI 对齐：徽标采用左对齐设计，通过 CSS 技巧消除页脚的 4px bleed，使其与下方设置行共用同一条左边线。

开发与限制¶

宿主改动需重启：DSH 不支持热加载宿主半代码，修改 src/host 相关文件必须重启应用。
客户端构建：客户端 bundle 采用手写代码，不使用打包器。
依赖管理：node_modules/@deepseek-ai/* 等依赖指向 DSH 安装的 junction，仅供本地测试，不会进入安装副本。

目录与源码¶

该插件目前仅通过 awesome-dsh-plugin 精选列表分发。如需上架内置市场或商店，需向该列表仓库提交 PR。

插件目录: https://www.skillhub.cn/plugins/chenjingchun/dsh-deepseek-balance-badge
源码仓库: https://github.com/chenjingchun/dsh-deepseek-balance-badge