dsh-matrix-terminal-balance：为 DeepSeek Harness 提示行提供余额的 DSH plugin

它是做什么的？

它是 DeepSeek Harness（DSH）的账户余额查询插件，为 dsh-matrix-terminal 终端提示行提供后端支持。它解决的是「提示行想显示余额、但 API 密钥不能暴露给浏览器」的问题：插件在宿主进程内按请求解析密钥，只发起一次外部调用，浏览器最终只拿到十进制字符串。核心能力包括带鉴权的余额路由、30 秒缓存与并发合并、结构化失败原因返回，以及全程不记录任何密钥材料。

核心功能

• 鉴权余额路由：通过 DSH 已认证的 /api 通道暴露余额接口，未认证请求返回 401，携带外部 Origin 的请求返回 403，金额只能被本机宿主提供的页面读取。
• 密钥不出宿主：每次请求都通过凭据服务解析模型提供方所用的同一份密钥引用，仅用于一次出站调用，不写入响应、缓存文件或日志。
• 缓存与并发合并：最近一次成功结果缓存 30 秒，并发请求共享同一次进行中的读取，界面聚焦刷新不会各自消耗一次请求。
• 结构化失败返回：以 ok 为 false 加 reason 的形式返回 no-key、network、http- 或 protocol，而不是让路由直接报错，前端可保留上次已知金额。
• 精确金额格式：total 等字段保持平台文档规定的十进制字符串而非数字，便于前端精确格式化，多钱包可用加号拼接。

怎么使用这个插件？

在 DSH 中启用后，插件会自动注册余额路由，终端皮肤按需读取即可，无需手动触发。它需要宿主具备 connection 与 credentials 服务，并为 DeepSeek 提供方配置好 API 密钥；没有密钥时路由返回 no-key，提示行就只显示到光标处。你也可以在自己的 DSH 插件里请求该路由，读取返回的 ok、available 与 wallets 字段，把金额展示到任意界面位置。

报错怎么排查？

路由返回 no-key 说明宿主没有为 DeepSeek 提供方配置 API 密钥，按官方说明补齐凭据即可。返回 network 表示出站请求失败或超过 8 秒超时，检查宿主网络连通性。返回 http- 或 protocol 表示平台接口响应异常或返回格式不符合预期，可稍后重试并确认宿主版本满足要求。若请求直接得到 401 或 403，说明调用方未通过宿主鉴权或来源不被信任，应从本机宿主提供的页面发起请求。