dsh-usage-blance：DeepSeek Harness Web 界面的用量与余额监控插件

DeepSeek Harness (DSH) 采用插件化架构，其 Web 界面允许通过自定义插件扩展功能。在本地调试或开发智能体时，频繁切换到网页后台查看 API 消费和余额不够高效。dsh-usage-blance 插件通过将监控数据嵌入到聊天对话框输入框上方的 conversation.input.dock 插槽中，实现了在对话过程中直接查看 DeepSeek API 的用量与余额。

功能介绍¶

该插件在聊天界面的输入框上方展示五项核心指标：本月消费、本月日均、昨日消费、今日消费以及账户余额。

点击任意一行账单数据，会打开一个控制面板。该面板支持以下配置：
* 玻璃拟态调节：支持实时调节透明度、模糊度和饱和度。
* 位置切换：账单条可固定在输入框上方或下方，设置会持久化保存。
* 双列布局：左侧配置 userToken，右侧调节主题与位置。
* 余额预警：可设置余额阈值，当余额低于该阈值时，余额数值会显示为红色感叹号，并出现充值按钮。

数据每 60 秒自动刷新，每行数据在出现错误（如 Key 缺失、Token 过期、网络故障）时会显示错误状态提示。界面颜色会跟随 DSH 应用本身的主题色（--dsw-* tokens）。

安装与启用¶

安装前需确保已安装 DSH CLI 和 pnpm。

克隆仓库并安装：

    git clone https://github.com/zhou-yihang/dsh-usage-blance.git
    cd dsh-usage-blance
    dsh plugin --profile web add .

重启 DSH Web 服务以加载插件：

    dsh web

打开 Web 界面并刷新页面，账单条将出现在对话框下方。

配置说明¶

插件需要两个关键配置项来获取不同维度的数据。

1. 获取 userToken（用于用量数据）¶

用量数据（今日、昨日、本月消费）需要使用平台会话令牌。点击账单行打开控制面板后：
1. 登录 platform.deepseek.com。
2. 打开浏览器开发者工具（F12）。
3. 在 Console 中执行以下命令获取 token：

    JSON.parse(localStorage.getItem('userToken')).value

将获取的字符串粘贴到控制面板输入框中，点击“保存”。配置将存储在 $DSH_HOME/storages/dsh-usage-blance.json。

2. 使用 DEEPSEEK_API_KEY（用于余额数据）¶

余额数据直接从官方接口获取。插件会自动读取环境变量或 ~/.dsh/.credentials.yaml 中的 DEEPSEEK_API_KEY。如果未配置，余额行会提示 Key 缺失，但用量数据仍可正常显示。

数据源与隐私¶

数据来源：
- 余额：官方公开接口 GET https://api.deepseek.com/user/balance。
- 用量：平台仪表板接口 GET https://platform.deepseek.com/api/v0/usage/by_api_key/cost（需 userToken）。
时间窗口：锚定北京时间 (UTC+8)。
隐私与安全：API Key 和 userToken 仅在本地路由传输，不会离开机器。所有数据请求由 DSH 进程发起，用户偏好设置持久化存储于 localStorage 和 $DSH_HOME/storages/dsh-usage-blance。

总结¶

dsh-usage-blance 通过将官方接口的数据聚合展示在 DSH Web 界面的输入框上方，解决了本地开发时监控 API 成本的需求。插件遵循 MIT 许可证，代码托管在 GitHub，适合需要在本地频繁查看 DeepSeek API 使用情况的开发者使用。