前言¶
DeepSeek Harness (DSH) 采用插件化架构，旨在通过模块化扩展提升开发与调试效率。在使用 DSH 进行智能体开发时，精确掌握 API 调用成本、追踪每日余额变动是刚需。dsh-balance-pie 插件提供可视化的余额监控与历史数据记录，帮助开发者快速定位消耗异常，避免超支。
插件简介¶
该插件由 f1yan9 维护，定位为 DSH 网页端的客户端插件。它通过一个可拖拽的悬浮饼图展示每日初始余额、真实项目消耗及剩余余额，并提供 GitHub 风格的历史热力图与每日表格，实现余额的实时监控与历史回溯。
核心功能¶
1. 悬浮饼图与交互¶
插件在 DSH 网页端右下角显示一个悬浮饼图，直观展示“今日初始余额”、“真实消耗”和“剩余余额”三个维度的数据。
* 交互操作：支持拖拽饼图以调整位置；鼠标悬停在扇区上可查看详细数据；提供最小化按钮（—）、设置按钮（⚙）、刷新按钮（↻）以及充值图标按钮。
* 侧边栏自适应：当侧边栏折叠时，组件会变为条形图（展开时为水平条形图，在窄轨道时显示为垂直条形图+余额），点击侧边栏可展开饼图。
2. 真实消耗计算¶
插件直接基于余额的实际减少来计算消耗，而非单纯估算。
* 分摊逻辑：消耗金额会按估算的用量分摊至各个项目。
* 自动处理：充值和退款操作会被自动识别并计入计算，确保数据反映真实的账户变动。
3. 充值检测与一键充值¶
插件支持自动检测充值行为，并在检测到充值后更新余额基线。同时提供一键跳转至官方充值页面的按钮，方便用户快速操作。
4. 历史数据记录¶
插件提供完整的消耗历史记录功能：
* 可视化：GitHub 风格的每月热力图，无记录的日期显示为白色。
* 表格：按日期显示的详细表格，包含日期、花费和剩余余额。
5. 本地持久化¶
所有状态数据存储在本地，包括初始余额和今日的充值总额。同日重启 DSH 后，这些状态会自动恢复。
安装与启用¶
在确保已安装 DeepSeek Harness (DSH) 并配置好 API Key 的前提下，使用以下命令安装该插件：
dsh plugin --profile web add github:f1yan9/dsh-balance-pie
安装完成后，重启 DSH 网页端并打开界面，悬浮饼图将出现在右下角。如需卸载，可执行：
dsh plugin --profile web remove dsh-balance-pie
典型用法¶
- 监控余额：在 DSH 网页端查看右下角的悬浮饼图，拖动可调整位置，悬停查看详情。
- 查看历史：点击悬浮饼图上的设置图标（⚙），进入「Balance」设置中心，切换至历史页面查看热力图和表格。
- 充值操作：当检测到余额不足或手动充值时，点击充值图标直接跳转至官方充值页面。
配置参数¶
插件支持通过设置中心的「Balance」面板或 DSH Profile 的 cordis.patch.yml 文件进行配置。常用参数如下：
| 参数名 | 描述 | 默认值 |
|---|---|---|
pollIntervalMs |
余额查询间隔 | 10000 ms |
pricesJson |
各模型非高峰期单价（每百万 Token） | deepseek-v4-flash 预设 |
peakMultiplier |
峰时价格倍率 | 2 |
language |
界面语言（auto 自动跟随 DSH） |
auto |
displayCurrency |
显示货币（转换后） | auto (账户货币) |
fxRatesJson |
人民币对目标货币汇率 JSON | {"USD":0.14,"EUR":0.13,"GBP":0.11,"JPY":20,"KRW":190} |
topUpUrl |
充值页面 URL | 官方充值页 |
注意事项¶
- 消耗计算：插件统计的是真实的余额减少量，项目金额是按估算用量分摊的。如果发现消耗与账单不符，可在设置中校准价格。
- 数据恢复：初始余额和今日状态仅在本地持久化，同日重启后可恢复。
- 充值延迟：充值检测依赖于下一次轮询（默认 10 秒），已花费的历史充值无法 retro-fix。
- 数据存储：历史数据存储在
$DSH_HOME/dsh-balance-pie/目录下，包含每日状态文件和 90 天保留期的 JSONL 日志文件。 - 许可证：该插件采用 MIT 许可证开源。
总结¶
dsh-balance-pie 插件通过可视化的饼图和历史热力图，为 DSH 用户提供了清晰的余额监控手段。它支持真实消耗计算、自动充值检测及本地持久化，适合需要在开发过程中精细管理 API 成本的用户。
