dsh-usage-lite
为 DeepSeek Harness Web 界面提供简洁、优雅的余额与 Token 用量面板。
Compact provider balances and local token-usage analytics for the DeepSeek Harness Web UI.
界面示意图：直观展示折叠态余额、供应商账户与聚合用量；具体文字和数据以实际运行环境为准。
为什么选择 Lite
dsh-usage-lite 只保留高频信息和必要操作：侧边栏快速查看余额，展开后查看供应商账户与近半年用量。没有独立后台、复杂配置页或遥测服务。
- 一眼查看余额：侧边栏直接显示所选供应商、当前余额和上次拉取时间。
- 自动发现供应商：读取 DSH 已配置的模型供应商并逐行展示，超出高度后在列表内滚动。
- 聚合本地用量：按日期、供应商和模型汇总 Token，并用 27 周热力图展示趋势。
- 明确能力边界：当前仅查询 DeepSeek 余额；其他供应商仍会展示并参与 Token 统计。
- 隐私优先：凭据只在服务端解析，不会返回浏览器；HTTP 接口仅接受本机回环请求。
- 中英文界面：跟随 DSH Web 的语言环境。
功能
余额
- 展示 DSH 中已配置的供应商账户。
- 查询 DeepSeek 当前余额、赠送额度和充值额度。
- 支持刷新、隐藏余额以及选择折叠态默认账户。
- 刷新失败时保留最近一次成功余额和拉取时间。
- 不支持余额查询的供应商会明确标记，且不能设为折叠态默认账户。
用量
- 汇总输入、输出、缓存读取和缓存写入 Token。
- 按供应商与模型展示 Token 和估算开销。
- 展示最近 27 周的每日用量热力图。
- 点击日期查看当日 Token 与估算开销。
- 用量视角聚合所有供应商，不受余额页默认账户选择影响。
安装
需要已安装并能够运行 dsh web 的 DeepSeek Harness 环境。
dsh plugin --profile web add dsh-usage-lite
安装后重启正在运行的 dsh web，并在浏览器中硬刷新。入口会出现在侧边栏设置项上方。
更新
dsh plugin --profile web update dsh-usage-lite
更新后同样需要重启 dsh web 并硬刷新浏览器，以避免旧客户端资源缓存。
卸载
dsh plugin --profile web remove dsh-usage-lite
配置
插件不维护独立供应商配置，而是读取 DSH 已有设置：
- 官方 DeepSeek 配置来自
llm-deepseek。 - 其他模型供应商来自
llm-pi-ai.providers。 - DeepSeek 默认凭据引用为
DEEPSEEK_API_KEY；若 provider 配置了apiKeyEnv，则使用该引用。
例如在 DSH 凭据文件中配置：
# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here
不要将真实 API Key 提交到 Git、公开 Issue 或日志中。
供应商支持
| 能力 | DeepSeek | 其他 DSH 供应商 |
|---|---|---|
| 自动发现与列表展示 | 支持 | 支持 |
| Token 用量聚合 | 支持 | 支持，取决于会话事件是否包含 usage 信息 |
| 余额查询 | 支持 | 暂不支持 |
| 折叠态默认账户 | 支持 | 余额查询适配后可用 |
余额查询调用 provider 配置的 baseURL 下的 /user/balance。新增供应商余额适配器是后续扩展方向，欢迎贡献。
数据来源与估算
Token 数据来自 DSH 当前会话和本地持久化会话事件，不来自供应商账单 API。插件读取事件中的 data.usage 和模型来源信息，并按 UTC 日期聚合。
开销由内置价格表估算，单位为人民币 / 100 万 Token：
| 模型 | 输入 | 输出 | 缓存读取 | 缓存写入 |
|---|---|---|---|---|
deepseek-chat |
¥2 | ¥8 | ¥0.5 | ¥2 |
deepseek-reasoner |
¥4 | ¥16 | ¥1 | ¥4 |
重要：开销仅为估算值。 供应商定价、缓存计费、折扣、币种和账单规则可能变化；未知模型当前按
deepseek-chat价格估算。请始终以供应商实际账单为准。
隐私与安全
- API Key 通过 DSH credentials 在服务端解析，不会发送到插件客户端。
- 浏览器只接收展示所需的供应商状态、余额和聚合用量。
- 插件服务端接口只接受本机回环地址发起的
GET请求。 - 除查询已配置 DeepSeek
baseURL的余额接口外，插件不向第三方服务上传数据。 - 项目不包含遥测、用户跟踪或远程分析服务。
如发现安全问题，请优先使用 GitHub 的私密安全报告功能，或在不包含凭据、地址和原始响应的前提下联系维护者。不要在公开 Issue 中披露可利用细节或任何密钥。
常见问题
DeepSeek 显示“未配置访问凭据”
确认 llm-deepseek 的 apiKeyEnv 与 ~/.dsh/.credentials.yaml 中的键一致，然后重启 dsh web。
有供应商但没有余额
当前仅 DeepSeek 支持余额查询。其他供应商会显示“暂不支持额度查询”，但仍可出现在用量聚合中。
没有供应商或模型用量
用量依赖 DSH 会话事件中的 data.usage 和模型来源字段。尚未产生对话用量、历史事件未持久化或上游未返回 usage 时，对应明细为空。
更新后界面没有变化
重启 dsh web，然后对浏览器执行硬刷新，确保客户端没有继续使用旧插件资源。
开发
git clone https://github.com/ericw0315/dsh-usage-lite.git
cd dsh-usage-lite
npm install
npm test
npm run check
npm test：验证 bundle 声明、服务端聚合与客户端渲染行为。npm run check：检查 JavaScript 语法。
核心文件：
lib/index.js：供应商发现、余额查询、Token 聚合和本机 HTTP 接口。lib/client.js：侧边栏入口、余额列表、用量详情和交互状态。cordis.patch.yml：DSH bundle 注册声明。
贡献
Issue 和 Pull Request 都欢迎。提交改动前请：
- 保持实现聚焦，避免为少量信息引入复杂配置或大型依赖。
- 为行为变化补充测试，并运行
npm test与npm run check。 - 在 PR 中说明用户可见变化、验证方式和兼容性影响。
- 不提交真实凭据、个人用量、供应商原始响应或本地 DSH 配置。
问题反馈请使用 GitHub Issues。
路线图
- 增加更多供应商余额适配器。
- 让估算价格表更易维护和扩展。
- 在不增加使用负担的前提下完善异常状态与兼容性。
路线图不代表交付承诺；具体优先级以社区反馈和实际维护成本为准。
License
MIT © dsh-usage-lite contributors
No comments yet. Be the first to write one.