前言¶

给智能体做界面时，常会遇到一件小事：想在自己的插件 UI 上显示当前 DeepSeek 账户还剩多少额度，但余额查询依赖 API key，而 key 通常只在服务端配置里，不想暴露给浏览器。一种做法是自己开一个后端接口，在另一个进程里读 key、再通过接口转发出去；这会把 key 多存一份，也多一个攻击面。

下面介绍的插件把这个功能收进 DSH 宿主进程：它只在宿主内部解析 key，对外暴露一个受鉴权的路由，浏览器拿到的只有余额的十进制字符串。

这是什么¶

victorcastro55/dsh-matrix-terminal-balance，由 victorcastro55 维护，分类「模型推理」。它是 dsh-matrix-terminal 的宿主侧插件，为 dsh-matrix-terminal 的 prompt line 提供 DeepSeek 账户余额，key 不离开宿主进程。

它解决的问题是：插件想显示余额时，不必自己持有或转发 API key，也不需要额外部署后端。

核心功能¶

先看清楚它实际做了什么，以下能力边界来自 README。

1、解析凭证。每次请求通过 credential service 解析 DEEPSEEK_API_KEY，与模型提供方读取的是同一个引用，所以界面上显示的数字就是实际在花的数字。

2、调用平台余额接口。向 https://api.deepseek.com/user/balance 发起一次请求，超时 8 秒。

3、缓存与合并请求。缓存最近一次成功应答 30 秒，并把并发请求合并成一次在途读取，避免界面因焦点变化触发的刷新各自消耗一次请求。

4、失败不报错。请求失败时返回 { ok: false, reason }，reason 取值为 no-key、network、http-<status> 或 protocol；皮肤端把所有失败都当作「无余额」，保留上一次已知金额。

5、不泄露 key。除了插件 id 之外不写日志，key 不会写进任何应答、缓存文件或日志行。

路由安全约束：走的是宿主已有的鉴权 /api 通道，未认证请求返回 401，带外部 Origin 的请求返回 403，因此余额只有你自己的 harness 服务给你的页面能读到。

安装与启用¶

该插件尚未发布到 npm，需要直接从仓库安装。命令来自 README 原文：

dsh plugin --profile web add github:victorcastro55/dsh-matrix-terminal-balance

事前条件：DeepSeek Harness 0.2.1-rc.5 或兼容版本，宿主需带 connection 和 credentials 两个服务（两者都是 stock host 标配）；并为 DeepSeek provider 配置好 API key。没有 key 时路由返回 no-key，prompt line 就停在光标处。

需要注意它和 dsh-matrix-terminal 的搭配关系：只装余额插件不会有问题，路由存在但没人读它；只装皮肤也没问题，prompt line 只是不显示金额。

典型用法¶

装好后，路由是带命名空间、owner 鉴权且稳定可用的，页面上的任何脚本都能读取：

const res = await fetch('/api/matrix-terminal.balance', { headers: { accept: 'application/json' } });
const body = await res.json(); // { ok, available?, wallets: [{ currency, total, granted?, toppedUp? }] }

返回示例：

{
  "ok": true,
  "available": true,
  "wallets": [
    { "currency": "USD", "total": "0.00", "granted": "0.00", "toppedUp": "0.00" }
  ]
}

total 是平台给出的十进制字符串，不是数值，这样格式转换才能保持精确。皮肤端按以下方式渲染：不足一美分显示为 <$0.01，千位分组，多个钱包用 + 连接。

在自己的插件里读取这个路由时，注意失败应答的结构：ok 为 false 时带 reason，读取方应按「余额不可用」处理，而不是当作异常抛出。

适用场景与注意¶

适合两类用法。一是装了 dsh-matrix-terminal 皮肤、想在 prompt line 上看余额的开发者；二是想在 DSH 页面里自己展示余额、又不想自己管理 key 的插件作者。

几个使用上的注意点：

1、插件以当前 dsh 进程的权限运行，安装前应检查源码与许可证（项目为 MIT，声明与 DeepSeek 无关）。

2、余额接口是平台文档接口，调用不消耗 token，但它会真实读取账户状态，不要把它放进高频轮询；插件自带的 30 秒缓存只是工程保护，不是带宽承诺。

3、no-key 意味着 DeepSeek provider 没配 key，此时界面没有余额是预期行为，不是插件故障。

4、社区目录 SkillHub 是独立站点，与 DeepSeek / 幻方无官方从属关系，插件信息以仓库 README 为准。

结尾¶

总体看，这个插件的价值不在于功能多，而在于把「读余额」这件事的 key 处理固定在宿主进程内：接口签名简单、失败语义清晰（ok: false 加 reason），适合直接接入现有 DSH 页面。需要进一步确认实现细节，可以读仓库源码：GitHub 上 victorcastro55/dsh-matrix-terminal-balance，目录页见 SkillHub 对应条目。

资料核对¶

本文事实取自 GitHub README 与 package.json（version 1.0.1，license MIT，作者 Victor Castro Solalto），未编造案例与数据。