api-monitor: 常驻 API 用量监控插件

前言¶

在 DSH 生态中，当同时对接 DeepSeek、GLM、OpenCode Go 和火山引擎等多家供应商时，手动查看余额与配额较为繁琐。api-monitor 插件提供了一个常驻的监控面板，侧边栏底部设有入口，点击后弹出浮动窗，聚合显示各供应商的余额、配额，以及当前会话树中的 token 使用量与花费。

该插件由 jcleener 维护，基于 MIT 协议开源。

核心功能¶

多路供应商轮询
插件宿主进程负责定时轮询 5 个数据源：DeepSeek 余额、GLM Coding Plan 配额、OpenCode Go 用量、火山 Coding Plan（GetCodingPlanUsage）以及火山 Agent Plan（GetAFPUsage）。

侧边栏与浮动窗
侧边栏底部提供一个竖排的「API 用量」摘要入口，每个供应商一行，显示状态点。点开浮动窗可查看详细数据。

会话树用量聚合
插件会收集根会话及其子代理会话（subagents.listDescendants）的 token 使用量，按来源（provider/model）分桶。仅 DeepSeek 会话会计算具体花费。

峰谷分时计价
基于助手/消息事件的 time 字段，识别高峰与空闲时段（北京时间周一至周五 9:00-12:00、14:00-18:00 为高峰），分别显示用量与金额。

官方价格自动抓取
插件内置正则解析 DeepSeek 官方定价页（6 小时 TTL），解析失败时会保留内置价目表。

零第三方依赖
宿主半仅使用 Node.js 内置能力（fetch / crypto.subtle）及 @deepseek-ai/schemastery，火山签名采用手动实现的 SigV4。

安装与启用¶

插件不提供自动安装脚本，需手动放入 DSH 的 profile 目录。

将插件包放入 profile/node_modules。
在 profile/cordis.patch.yml 中添加挂载行：

    - insert:
        - id: api-monitor
          name: api-monitor

重启 DSH 实例以激活插件。
（可选）若需使用火山引擎功能，在设置中配置 volcesAccessKeyId 和 volcesSecretAccessKey。

配置项¶

插件通过宿主 settings 命名空间注册配置，字段如下：

字段	类型	默认值	说明
`volcesAccessKeyId`	string	`''`	火山引擎 AccessKey ID
`volcesSecretAccessKey`	string	`''`	火山引擎 SecretKey
`volcesTier`	string	`'auto'`	套餐档位。仅保存与回显，代码中未用于请求
`pollIntervalSeconds`	number	`60`	轮询间隔秒数。仅在 apply 时生效，修改需重启
`warnPercent`	number	`70`	预警阈值（剩余额度 ≤ 100−该值时变黄）
`dangerPercent`	number	`90`	危险阈值（剩余额度 ≤ 100−该值时变红）
`balanceWarn`	number	`10`	余额低于该值（CNY）标红
`priceTable`	dict(any)	`{}`	单价覆盖表，支持 `{peak,offPeak}` 形态
`showCacheHitRate`	boolean	`true`	是否显示缓存命中率行
`showResetTime`	boolean	`false`	客户端代码未读取该字段
`entryVisibility`	object	全 true	控制各供应商是否显示在侧边栏入口

浮动窗 UI 内可直接修改火山 AK/SK、套餐档位及各区块的显示状态。priceTable、pollIntervalSeconds、阈值及 showCacheHitRate 需在设置中直接修改。

典型用法¶

强制刷新数据
在浏览器控制台或使用 API 调用：

POST /api-monitor/refresh

这将强制刷新官方价格并立即执行一次轮询。

查看会话快照
通过 API 查看当前会话的聚合数据：

GET /api-monitor/snapshot?root=<会话ID>

配置火山引擎
若需监控火山 Coding 或 Agent Plan，需在设置中提供 AccessKey，并通过浮动窗中的「key配置」项写入。

注意事项¶

依赖内部类名
客户端 CSS 直接绑定了 DSH 内部的类名（如 .hHd-Xa_*）。壳层类名变更可能导致竖排布局失效，但不影响功能运行。

客户端与宿主轮询差异
浏览器半实际轮询间隔为 8000ms，而浮动窗 UI 文案显示的是宿主 pollIntervalSeconds 的值（默认 60s）。

Qwen 区块特性
qwen 区块在侧边栏入口可见，但宿主无对应轮询逻辑。其数据来自会话桶聚合，额度行在客户端写死为「接口不可查」并提供外部控制台链接。

会话归因
只有带有 source.provider 的事件会进入来源桶。没有路由信息的事件仅计入总量，不区分来源，因此「各来源相加 ≤ 总量」是预期行为。

版本与依赖声明
package.json 声明了三个客户端依赖（@deepseek-ai/dsh-client-locale 等），但 lib/client.js 实际仅 require("react")。面板文案为硬编码中文，无国际化支持。