前言¶
在 DeepSeek Harness（DSH）里跑智能体或 Web 配置时，钱包余额显示在 设置 → 账号与余额 页面，对应的是 platform.deepseek.com 账户（充值额度与赠送额度），与 API key 余额、上下文余量不是同一套数据。若要在脚本、监控或自动化流程里周期性核对这笔余额，反复打开设置页并不顺手。社区插件 dsh-balance（维护者 EviMing）在 DSH Web 进程内注册一条仅本机可访问的 GET 接口，通过 DSH 自带的 deepseekAccount 服务读取与界面一致的钱包数字，对外用 curl 即可复现。
这是什么¶
dsh-balance 是 DSH 的 Web 侧插件：安装后在本机回环地址暴露 /api/balance，返回当前已登录 DeepSeek 账号的钱包余额 JSON 或纯文本。它不保存凭据，token 仍由 DSH 管理在 ~/.dsh/.credentials.yaml；余额查询走宿主已挂载的 deepseekAccount.getBalance。插件版本 1.0.0，许可证 MIT，要求 DSH 0.2.0 及以上且已在 DSH 中登录 DeepSeek 账号。目录页：SkillHub - dsh-balance；源码：GitHub - EviMing/dsh-balance。
核心功能¶
下面能力是 README 中已写明的行为，可按需裁剪使用场景。
余额数据与界面一致¶
接口返回的 recharge（充值余额）、bonus（赠送额度）、total（两者之和）以及 currency（示例为 CNY），与 DSH 设置里展示的 platform.deepseek.com 钱包一致，不是 API 计费余额。
本机 HTTP 接口¶
- 仅接受 GET，其他方法返回 405。
- 校验请求来源与
Host，非本机（loopback）访问返回 403，局域网其他机器无法直接读取。 - 端口跟随当前 DSH Web 地址，默认
127.0.0.1:3080。 - 15 秒缓存且 single-flight：短时间内重复请求复用上次结果，并发只打一次上游。
错误映射¶
失败时统一为 {"ok": false, "error": "...", "message": "..."}，常见 error 包括：signed-out（401，未登录）、forbidden（403）、method-not-allowed（405）、upstream-failed（502）、account-unavailable（503，宿主未挂载 deepseekAccount）。
安装与启用¶
DSH 生态里插件通过 CLI 安装；web 配置档对应 Web 服务与上述 HTTP 路由。
- 在已安装 DSH 的环境里执行官方安装命令：
dsh plugin --profile web add github:EviMing/dsh-balance
- 安装完成后刷新 DSH Web 页面即可，无需重启进程。
若使用本地目录调试，可将路径换成你的插件目录（README 示例为 Windows 路径，Linux 下改为实际绝对路径）：
dsh plugin --profile web add /path/to/dsh-balance
安装前建议浏览仓库中的 index.js、cordis.patch.yml 与 MIT 许可证，确认与当前 DSH 版本（engines.dsh: >=0.2.0）匹配。插件以当前 dsh 进程权限运行，与任何第三方插件一样，应自行评估源码后再安装。
典型用法¶
先确认 DSH Web 已启动且账号已登录，再在本机请求接口。
完整 JSON（字段含义见下文）：
curl -s http://127.0.0.1:3080/api/balance
示例响应：
{
"ok": true,
"currency": "CNY",
"recharge": 12.416959,
"bonus": 0,
"total": 12.416959,
"fetchedAt": 1794049067812
}
其中 fetchedAt 为本次读取时间的毫秒时间戳。若只需要一行数字，可使用文本格式：
curl -s "http://127.0.0.1:3080/api/balance?format=text"
# 12.416959 CNY
上述命令来自项目 README，在未改端口的前提下可直接复现；若你修改了 DSH Web 监听地址，应将 URL 中的主机与端口换成实际值。
适用场景与注意¶
适合谁：需要在 shell、定时任务或自建面板里读取与 DSH 设置页相同的钱包余额，且能接受「仅本机、只读 GET」的开发者。
前提：DSH 0.2.0+（依赖 webServer.register 与 deepseekAccount.getBalance），并已登录 DeepSeek 账号；未登录时会得到 401 / signed-out。
安全与范围：接口故意不对局域网开放；不要通过反向代理把该路径暴露到公网。插件不接触凭据文件，但也不改变 DSH 自身的账号安全策略——仍应对 ~/.dsh/.credentials.yaml 做好文件权限与备份习惯。
与社区目录的关系：SkillHub 等为 DSH 社区的独立插件目录站点，与 DeepSeek / 幻方无官方从属关系；安装来源以你信任的 GitHub 仓库与官方 README 为准。
结尾¶
dsh-balance 把「设置 → 账号与余额」里的平台钱包变成一条本机 curl 可调的 HTTP 读口，适合在自动化里做余额快照或告警前置检查。进一步了解可打开 SkillHub 目录页 与 GitHub 仓库 中的安装说明、错误码表与源码结构（index.js、locale/、icon.svg 等）。
