前言¶
DeepSeek Harness (DSH) 是一个本地运行的智能体开发环境。在使用本地模型调用 DeepSeek API 时，开发者通常需要追踪具体的 Token 消耗量和账户余额。现有的监控方式往往依赖第三方工具或手动计算，缺乏统一的后端记录和可视化的实时状态。
下面介绍的 dsh-deepseek-usage-monitor 插件专为解决这一痛点设计。它运行在 DSH Host 进程中，负责记账，同时通过 DSH Web 界面提供可视化的卡片，实时展示用量统计与余额状态。
核心功能¶
令牌用量记录¶
插件在 Host 端监听 DSH 的 session/event，通过 assistant/message 中的 TokenUsage 字段作为主要数据源，同时也兼容 assistant/chunk 的备用数据。它会以 session:turn:step 为键进行去重，确保同一个步骤不会重复计费。
统计逻辑自动处理两种字段格式：DSH 的标准字段 (inputTokens, outputTokens 等) 以及 DeepSeek 原始响应字段 (prompt_tokens 等)。对于原始字段中缺失的 prompt_cache_hit_tokens，插件会自动通过 prompt_tokens - hit 补全。
统计数据按 模型 和 提供商 分组展示，并保留最近的会话记录。所有数据持久化到本地 JSON 文件 (~/.deepseek-harness/deepseek-usage.)，重启 DSH 后数据依然保留。
余额查询¶
插件会在后台开启定时任务，轮询 DeepSeek 官方接口 GET /user/balance（默认间隔 60 秒）。查询逻辑会自动解析并复用 DSH 配置中已有的 API Key，无需手动配置。如果在启动后添加了新的 Key，下次轮询时会自动生效，无需重启进程。
Web 状态卡片¶
安装完成后，DSH Web 界面的右下角会出现一个 “Usage” 卡片。该卡片由 Web 端 (client.js) 渲染，通过轮询 GET /plugins/deepseek-usage-monitor/state 接口获取数据（默认间隔 5 秒，标签页隐藏时暂停）。
卡片支持以下交互：
* 拖拽与调整大小：拖动标题栏可移动卡片，拖动右下角手柄可调整大小。
* 展开/折叠：默认折叠，点击 “+” 展开，”−” 折叠。状态保存在浏览器 localStorage 中。
* 刷新：点击卡片上的 “Refresh” 按钮可强制调用 ?refresh=1 接口立即更新余额。
* 多语言：卡片界面语言跟随浏览器区域设置（如 zh-* 显示中文）。
安装与启用¶
在安装前，请确保环境满足以下要求：
* Node.js >= 22.19
* pnpm
DSH 的插件通过 pnpm dlx 运行，无需全局安装。请根据实际情况替换 0.1.1-rc.2 为你当前使用的 DSH 版本号。
1、在任意目录运行以下命令，将插件安装到 DSH 的 Web Profile 中：
pnpm dlx @deepseek-ai/dsh@0.1.1-rc.2 plugin --profile web add dsh-deepseek-usage-monitor
该命令会自动将插件依赖添加到 ~/.dsh/profiles/web/node_modules，并将其加入到 dsh.profile.bundles 中，无需手动编辑 YAML 配置文件。
使用说明¶
安装完成后，重启 DSH Web Profile 并打开 Web 界面。右下角将出现 “Usage” 卡片。
- 查看数据：卡片展开后显示总 Token 数、请求次数、缓存命中率、各模型/提供商的用量分组，以及 DeepSeek 账户余额。
- 访问数据接口：你可以通过 HTTP 接口获取数据，例如：
GET http://localhost:PORT/plugins/deepseek-usage-monitor/state
添加 `?refresh=1` 参数可强制刷新余额。
- 重置统计：如果想清空本地历史记录，删除
~/.deepseek-harness/deepseek-usage.文件并重启 DSH 即可。
注意事项¶
- API 密钥安全：插件的 API Key 仅存在于 DSH Host 进程内存中，绝不会发送到浏览器端。
- 版本依赖：确保 Node.js 版本不低于 22.19，否则插件无法运行。
- 数据隐私：持久化的 JSON 文件仅包含数字、分组名称和时间戳，不会记录提示词或模型回复内容。
总结¶
dsh-deepseek-usage-monitor 为 DSH 用户提供了一个轻量级的用量监控方案。它将记账逻辑置于 Host 端，利用 DSH 的事件流保证准确性，并通过 Web 卡片提供直观的实时反馈，适合需要在本地环境中精细化管理 DeepSeek API 成本的开发者。
- 插件目录: dsh-deepseek-usage-monitor
- GitHub 仓库: KamChiHei/dsh-deepseek-usage-monitor
