前言¶
用 DeepSeek Harness（DSH）做日常开发时，API 余额往往要另开浏览器或控制台去查，和「在本机跑 Harness」的工作流是断开的。社区插件 dsh-plugin-deepseek-balance 把余额、构成、日均消耗和趋势曲线收进 DSH 的「设置 → 余额」分区：装好插件并重启 DSH 后，在设置页即可查看，Host 侧按固定间隔采样，趋势数据留在本机。
本文介绍该插件的定位、能力、安装方式与使用注意。事实以仓库 README 与 package.json 为准；安装命令须用 github:MatthewTian2018/... 形式，勿与 npm 上他人同名包混淆。
这是什么¶
dsh-plugin-deepseek-balance 是 DeepSeek Harness 的组合包（bundle）插件，不是独立应用。维护者为 MatthewTian2018，在 SkillHub 目录中归类为联网工具（需请求 DeepSeek /user/balance）。当前仓库版本 0.1.3，许可证 MIT。
插件由 Host（lib/index.js）与 Client（lib/client.js）两半组成，通过根目录 package.json 中的 dsh.bundle.patch 指向 cordis.patch.yml，在被 profile 的 dsh.profile.bundles 列出时挂载到 Loader。一句话价值：装完后不必再切出去查余额——打开 DSH 设置即可看到还剩多少钱、按当前消耗速度大约还能用多少天。
核心功能¶
下面能力均来自官方 README，未在资料中出现的细节不写。
- 环形仪表：以可编辑「预算」为分母显示当前余额占比；预算在页面内修改，防抖约 450 ms 后落盘。
- 余额构成：区分充值余额与赠送余额；多币种按符号展示（CNY / USD / EUR / JPY）。
- 消耗指标：日均消耗、按当前速率估算可用天数、预算剩余、距上次快照时间。
- 余额趋势：24 小时 / 7 天 / 30 天 / 全部四档；悬停可看单点数值；图表宽度随容器自适应。
- 后台采样：Host 每 10 分钟补一次快照，即使不打开设置页，趋势也不断档（依赖 DSH 进程常驻）。
- 本地优先：API Key、历史与预算配置留在本机；浏览器侧只拿到展示用数字。
DeepSeek 余额接口本身只返回当前快照，历史曲线由本插件采样积累；安装当天曲线从零开始。
安装与启用¶
前提：DSH 已能正常启动，本机已配置可用的 DeepSeek API Key。文档中验证环境为 DSH 0.2.2-rc.1（桌面端与 web 端共用 profile 机制）。将命令里的 --profile web 换成你实际使用的 profile（桌面端一般为 desktop）。安装后须重启 DeepSeek Harness，插件才会被 Loader 挂载。
不要用裸包名安装：npm 上的
dsh-plugin-deepseek-balance为另一位作者（fanlr）的同名不同项目。本插件请使用github:或 tgz 方式安装。
方式一：从 GitHub 安装（推荐）¶
dsh plugin --profile web add github:MatthewTian2018/dsh-plugin-deepseek-balance
生产环境可锁定 commit：
dsh plugin --profile web add github:MatthewTian2018/dsh-plugin-deepseek-balance#<sha>
方式二：Release 包（tgz）¶
从 Releases 下载 .tgz 后：
dsh plugin --profile web add ./dsh-plugin-deepseek-balance-0.1.2.tgz
（示例文件名来自 README；请以 Release 页实际文件名为准。）
卸载与校验¶
卸载：
dsh plugin --profile web remove dsh-plugin-deepseek-balance
校验是否装好：
dsh --profile web --dump-config | grep -A2 '^# == dsh-plugin-deepseek-balance'
应看到 # == dsh-plugin-deepseek-balance 层与 - id: deepseek-balance 行。
配置与数据路径¶
API Key 由 Host 进程读取，顺序为：
- 环境变量
DEEPSEEK_API_KEY ~/.dsh/.credentials.yaml（DSH 凭证文件）
| 环境变量 | 默认值 | 说明 |
|---|---|---|
DEEPSEEK_API_KEY |
自动读取 | 显式指定 Key |
DEEPSEEK_API_BASE |
https://api.deepseek.com |
接口地址 |
本地数据（不进仓库）：
~/.dsh/deepseek-balance/history.json— 余额采样，最多 20 000 条；新采样与上一条间隔小于 45 s 时合并。~/.dsh/deepseek-balance/config.json— 预算（默认 100）。
Host 暴露的路由挂在 DSH 鉴权之后：未带登录 cookie 返回 401，且仅监听回环地址。除 api.deepseek.com 外，插件不向其它远程服务发请求；Key 不下发浏览器。
典型用法¶
- 按上一节装好插件并重启 DSH。
- 确认本机已有有效 DeepSeek API Key（环境变量或
~/.dsh/.credentials.yaml）。 - 打开 DSH 设置 → 余额，查看总余额、赠金与充值构成、日均消耗与可用天数，并按需切换趋势时间范围或修改预算。
- 若需立即刷新汇总（跳过约 15 s 缓存），可由已登录会话请求
GET /api/deepseek-balance/summary?force=1；改预算使用POST /api/deepseek-balance/budget，body 形如{"budget": 100}。
调试 Host 时，可对回环地址执行（需先通过 DSH 登录换 cookie）：
curl -s http://127.0.0.1:<port>/api/deepseek-balance/summary | head -c 400
适用场景与注意¶
适合谁：长期在 DSH 里调用 DeepSeek API、希望在本机 Harness 内随时掌握余额与消耗趋势的智能体或应用开发者。
运行与信任：插件以当前 DSH 进程权限运行，会读取本机 Key 并请求官方余额接口；安装前宜浏览源码与 MIT 许可证，确认符合你的安全策略。
已知限制（README 原文要点）：
- 仪表盘挂在
settings.section，在设置页而非独立主路由。 - 关闭 DSH 期间不会有后台采样点。
- 趋势历史从零积累，无法回溯安装前的官方侧历史。
DSH 生态是「一切皆插件」；SkillHub 目录页 为社区收录，与 DeepSeek / 幻方无官方从属关系。
结尾¶
dsh-plugin-deepseek-balance 把 DeepSeek 账户余额与本地采样的消耗趋势收敛到 DSH 设置里，减少在 Harness 与外部控制台之间来回切换。需要安装说明与接口细节时，以仓库 README 为准。
- 目录页：https://www.skillhub.cn/plugins/MatthewTian2018/dsh-plugin-deepseek-balance
- GitHub：https://github.com/MatthewTian2018/dsh-plugin-deepseek-balance
