前言¶

在 DeepSeek Harness（DSH）里跑智能体或长对话时，token 用量会在 composer 下方以统计项形式展示，但账户里还剩多少 API 余额通常要另开页面或控制台去查。频繁切换上下文容易在余额不足时才察觉，影响调试和日常使用。下面介绍社区插件 display-api-balance：它把 DeepSeek API 余额嵌进 composer 统计行，与 turns、steps、tok/s 等同排显示，并支持本地低余额提醒。

这是什么¶

display-api-balance 由维护者 river291 发布，分类为客户端插件，当前在 GitHub 上为 1 star。插件定位是：在 DSH 桌面版（及兼容的 web 构建）中，以 ambient stat 形式展示 DeepSeek API 余额，默认每 60 秒刷新；点击余额可设置本地低余额阈值，达到或低于阈值时金额变红加粗。密钥只留在宿主进程，浏览器侧通过相对路径请求宿主路由，不把 API Key 交给前端。

核心功能¶

经 README 核实，插件具备以下能力：

1. 展示位置与样式：渲染在 composer 输入框下方的 stat 行，排在自带的 turns · steps · tok/s 与 token 占用统计之后，共用字号、颜色与图标风格，不单独浮层。
2. 刷新策略：每 60 秒自动刷新；窗口或标签重新获得焦点时立即刷新。
3. 低余额提醒：点击余额打开小面板，可设置低余额阈值（默认 ¥20）；等于或低于阈值时金额变红并加粗；留空则关闭提醒。阈值保存在浏览器 localStorage（键名 display-api-balance:threshold），不上传、不随网络发送。
4. 异常状态：未配置 DEEPSEEK_API_KEY、请求失败或未登录账号时，有明确状态展示，不显示错误数字。
5. 主题：颜色使用 DSH 的 --dsw-alias-* 语义 token，随主题变化。

宿主侧（index.js）注册 GET /api/balance：每次请求重新解析 DEEPSEEK_API_KEY（轮换密钥无需重启），以 Bearer 调用 https://api.deepseek.com/user/balance，15 秒超时，返回上游 JSON。客户端（client.js）在 conversation.composer.dock 插槽注册统计项（order: 2），通过 fetch('/api/balance') 访问上述路由。纯 HTTP 的 web 部署下，与其他宿主路由一样，/api/balance 应仅绑定 loopback。

与旧版 web 做法的区别：旧方案用 webServer.tapIndex 向 index.html 注入脚本；桌面 Electron 窗口加载打包前端，不执行宿主 renderIndex，注入脚本无效。本插件改用 client slot + React，桌面与 web 均可工作。

安装与启用¶

插件随 DSH profile 安装，可从桌面 Plugins 页或 CLI 操作。当前无 npm 发布，须用 GitHub 源（无需构建、无需 allowBuilds）：

dsh plugin --profile <profile> add github:river291/display-api-balance

安装后在 Plugins 页确认 display-api-balance 已启用。若日后发布到 npm，README 说明也可使用 dsh plugin add display-api-balance（以届时文档为准）。

卸载：

dsh plugin --profile <profile> remove display-api-balance

典型用法¶

1. 前置条件：宿主凭证服务能解析 DEEPSEEK_API_KEY——在 DSH Settings → Models 填写 DeepSeek API Key，或在启动 DSH 的环境中导出该变量。
2. 版本：在 DSH 0.2.1-rc.5（desktop）上开发与验证；宿主仅用 webServer、credentials，客户端仅用 slots、locale。
3. 日常使用：启用插件后，在 composer 下方即可看到余额；需要提醒时点击余额，设置阈值（例如默认 ¥20）；不需要提醒时将阈值字段留空。
4. 密钥轮换：更换 Settings 或环境中的 Key 后，下次请求会自动用新凭证，无需重启 DSH。

适用场景与注意¶

适合：长期在 DSH 桌面版开发、调试智能体，希望余额与对话统计同屏可见、并做本地低余额预警的开发者。

注意：

• 插件以当前 DSH 进程权限运行，安装前建议阅读 GitHub 仓库 源码与 MIT 许可证，确认行为符合你的安全策略。
• 社区插件目录（如 SkillHub）为独立生态站点，与 DeepSeek / 幻方无官方从属关系；DSH 理念是「一切皆插件」，选用社区包需自行评估维护者与更新频率。
• package.json 版本为 1.0.0；星标与目录信息以各站点当时展示为准。

结尾¶

display-api-balance 把 DeepSeek API 余额收进 composer 统计行，定时刷新并支持仅本地的低余额阈值，密钥留在宿主、前端只读余额接口。需要安装说明与实现细节时，可查阅社区目录页与上游 README：

• 目录页：https://www.skillhub.cn/plugins/river291/display-api-balance
• GitHub：https://github.com/river291/display-api-balance