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")。面板文案爲硬編碼中文，無國際化支持。