dsh-token-metrics
中文 | English
一个 DSH 插件：把经过 DeepSeek Harness 的每一次模型调用都记下来，在侧边栏给你一个
Token 用量统计页，顺带管好成本与供应商余额。
统计
- 今天、近 7 天与全部的 token 总量，以及趋势涨跌
- 各模型、各供应商的用量排行
- 缓存命中率——钱有没有花在重复输入上
- 各项目、各子代理的 token 消耗
- 首字延迟与输出速度——调用快不快，而不只是花了多少
- 活动热力图：一年里哪天用得多，一眼看出使用节奏
成本
- 按模型估算实际花费，价格取自 LiteLLM 公开价目表（约 2800 个模型）
- 峰谷计价：DeepSeek 谷时价是峰时的一半，按调用时刻区分，不虚高
- 美元 / 人民币一键切换，汇率实时拉取
- 匹配不到价格的模型明确列出「未定价」并提供补价入口，不静默算成 0
- 预算：设日 / 月预算，全局或按模型分组（一组可含多个模型），实时看已用百分比
模型接入
- 35 个服务预设，国内优先排序，选中即填好地址与协议
- 供应商余额与配额：覆盖 Sub2API / new-api / one-api 三类网关与 11 家官方平台
- 从 pi-ai 模型目录（1241 个模型）自动识别上下文、输出上限、思考档位与附件能力
- 一键把供应商与模型写入 DSH 模型配置
提醒
- 余额不足、配额将尽、配额即将重置、查询失败、插件更新，以及峰谷切换前提醒、预算将尽，八类告警推送到右下角
数据来自 DSH 自己的会话日志，不额外发请求、不上传任何东西。
安装
按包名安装（推荐，走 npm）
在 DSH 的「添加插件」搜索框输入 dsh-token-metrics，或在插件管理里执行：
plugin_manager install_bundle dsh-token-metrics
走已发布到 npm 的版本，国际（npm 官方源）与国内（npmmirror 镜像源）都能装。
DSH 会并行探测两个源、自动选响应更快的一个，无需手动挑：海外用户走官方源，
国内用户走镜像源，都覆盖到。
发布只需推到 npm 官方源，npmmirror 会自动镜像同步（通常几分钟内）。刚发新版
若镜像还没跟上，在「添加插件」里把安装源临时切到官方源，或到 npmmirror 搜
本包点「同步」。
从 GitHub 安装
不依赖任何 npm 源、或想用尚未发布的最新版时，直接从仓库装：
plugin_manager install_bundle github:hugoyee75-cmyk/dsh-token-metrics
锁定某个版本加 #v0.3.2：
plugin_manager install_bundle github:hugoyee75-cmyk/dsh-token-metrics#v0.3.2
本地开发（link）
改代码即时生效时用本地目录，把 dsh-token-metrics 指到你的仓库：
{
"dsh": { "profile": { "bundles": ["dsh-token-metrics"] } },
"dependencies": { "dsh-token-metrics": "link:/path/to/dsh-token-metrics" }
}
装完重启 DSH（或热重载），侧边栏就会出现「Token 用量统计」图标。第一次打开页面，插件会自动回扫历史会话日志，把以前的用量补上。
界面
统计页（深色主题）
顶部是时间范围与模型筛选，中间是九项总计指标，下方是趋势图与模型占比环形图，
再往下是按模型 / 来源 / 项目 / 供应商 / 账号 / 日期切换的明细表。
切换「今日 / 近 7 天 / 全部」时，指标卡、图表、明细表与金额一起联动。
统计页（深色主题）
模型接入
「模型接入」页签管理第三方中转站与官方平台：余额、可用模型、订阅额度窗口
与重置倒计时。余额可点击在美元 / 人民币之间切换。
模型接入
订阅制平台（如智谱 GLM Coding Plan、Kimi Coding Plan）没有「余额」概念，
这里显示的是各时间窗口的剩余比例与重置倒计时。
右下角通知
余额不足、配额将尽、配额即将重置、查询失败、插件新版本等状态变化会推送到
右下角。告警有服务端冷却、状态落盘、客户端记忆三层去重，不会反复弹。
右下角通知
特性
- 总计：input / output / cacheRead / reasoning / total / 调用次数 / 缓存命中率 / 平均首字延迟
- 时间维度：今日、近 7 天、全部
- 图表：一张可切换的主趋势图，五种视角共用一张图
（总量 / 命中率 / 输入构成 / 按模型 / 成本），平滑曲线 + 悬停显示具体数值
- 趋势粒度自适应：今日按小时、近 7 天按天、全部按月；数据跨年时可选年份
- 模型筛选：下拉多选，可单选/多选/取消，指标卡与趋势图同时刷新
- 模型合并：占比图与趋势按模型名合并（跨供应商），明细表仍按供应商拆分
- 配色：图表分类色自带亮/暗两套值，跟随主题切换
- 版本指示：右上角版本号本身就是按钮，点击即检查更新，
结果用弹窗告知（有新版可一键更新，无新版显示当前版本）
状态灯：绿=最新 / 蓝=有新版本 / 灰=未检查
- 多语言：跟随 DSH 的语言设置自适应（中文 / English），运行时切换即时生效
- 按来源：主会话 / 子代理 / workflow
- 按项目：按会话工作目录归组
- 按账号：当前登录账号 + 余额 + 官方用量入口
- 明细表：按标签切换模型 / 来源 / 项目 / 供应商 / 账号 / 日期等视图
（会话明细默认隐藏，可配置打开）
- 失败请求：次数，以及上游真计费时的 token
- 启动回扫：首次安装即扫描已有会话日志补算历史，界面显示扫描进度
- 模型筛选下拉：点击外部或按 Esc 自动收起
- 两个可视化卡片等高对齐（趋势图与占比图上下边缘一致）
- 持久化：重启不丢，跨会话累计
- 自更新：检查新版本、安装、热重载，全程可回滚
- 零运行时依赖：无构建步骤，不需要 npm install
配置
所有配置项都有默认值。要改的话，在你自己 profile 的 cordis.patch.yml 里加一条同 id 的 override：
- id: token-metrics
config:
showSessions: true
snapshotCacheMs: 5000
注意：同 id 的 override 会整体替换 config，不是逐字段合并。改几项就把其余项一并写全，或者只写你要改的、其余依赖默认值。
| 配置项 | 默认值 | 范围 | 说明 |
|---|
flushDelayMs | 2000 | 250–60000 | 落盘防抖（毫秒）。调用本身很轻，磁盘写入才是开销 |
snapshotCacheMs | 3000 | 0–60000 | 聚合快照缓存时长（毫秒）。0 表示每次重算 |
retentionDays | 400 | 0–3650 | 按天分桶保留天数。0 表示不裁剪 |
maxSessions | 500 | 0–5000 | 统计页返回的会话明细上限 |
maxTrendSeries | 6 | 1–20 | 趋势图最多画几条模型曲线，多出的聚合成「其他」 |
maxSeenEntries | 200000 | 1000–2000000 | 去重表上限 |
showSessions | false | — | 是否展示「按会话」明细 |
trackFailedAttempts | false | — | 是否统计失败请求。详见「失败请求」 |
trackAccount | true | — | 是否读取登录账号身份与余额（只读，不碰凭据） |
autoUpdate | true | — | 是否启用自更新 |
watchFiles | false | — | 监视包目录，改文件即热重载。开发用 |
modelAliases | {} | — | 模型别名映射，把 provider 上报的内部代号转成真实模型名 |
alertThresholds.balanceLowUsd | 5 | 0–1e6 | 余额低于此值（美元）时通知；0 关闭 |
alertThresholds.quotaLowPercent | 10 | 0–100 | 配额窗口剩余低于此百分比时通知；0 关闭 |
alertThresholds.quotaResetSoonMinutes | 10 | — | 配额即将重置的提前量（分钟） |
HTTP 接口
服务在宿主进程里，端口随 DSH。统计页顶部有对应按钮，也可以直接调：
| 方法 | 路径 | 作用 |
|---|
GET | /api/dsh-token-metrics/summary | 聚合快照，统计页的数据源 |
GET | /api/dsh-token-metrics/flush | 立即落盘并返回最新快照 |
GET | /api/dsh-token-metrics/version | 当前版本与更新状态 |
GET | /api/dsh-token-metrics/update/check | 检查新版本 |
POST | /api/dsh-token-metrics/update/apply | 安装新版本并热重载 |
POST | /api/dsh-token-metrics/reload | 只热重载当前磁盘代码 |
POST | /api/dsh-token-metrics/rebuild | 从会话日志重算全部统计 |
手动重算：
curl -X POST http://127.0.0.1:53414/api/dsh-token-metrics/rebuild
统计口径
数据来源是 DSH 的会话日志，这是唯一权威来源。每一次完成的模型调用都会在日志里
追加一条 assistant/message 事件，携带：
data.message.source.{provider, model} —— 谁被调用了data.usage —— inputTokens / outputTokens / totalTokens /
cacheReadTokens / cacheWriteTokens / reasoningTokensdata.turn / data.step —— 天然的去重键event.time —— 按天分桶
因此统计覆盖：
| 场景 | 是否计入 | 原因 |
|---|
| 主会话对话 | ✅ | 日志有 assistant/message |
| 子代理 / teammate | ✅ | 各有独立会话日志 |
| workflow 子会话 | ✅ | 同上 |
| 压缩（compaction） | ✅ | 由 llm/stream 补充捕获 |
| 会话标题生成 | ✅ | 由 llm/stream 补充捕获 |
| 失败的请求尝试 | ❌ | assistant/attempt 是重试中间态，计入会重复 |
多语言
界面文案通过宿主的 locale 服务注册，因此跟随 DSH 的语言设置（中文 / English），
运行时切换即时生效，不需要重开页面。
实现上有两个容易踩的坑，都已处理：
LocaleSnapshot 的当前语言字段是 active（不是 locale 或 id）。
早先读错字段名，导致语言永远退回默认值、完全不跟随设置。- 只在注册时读一次语言也不够：面板需要订阅
ctx.locale.subscribe，否则
语言切换后已经打开的页面不会重渲染。
模型口径：合并 vs 拆分
同一个模型可能挂在多个供应商下（例如 deepseek-v4.1-flash 同时出现在
trae / workbuddy / dshlinux / workbuddy-ai）。插件维护两套口径：
| 视图 | 口径 | 用途 |
|---|
byModelName / 占比图 / 趋势图 | 按模型名合并 | 同一模型的多条曲线合并成一条，否则图上会出现 4 条同名线、占比也被拆散 |
byModel / 明细表 | 按供应商拆分 | 需要区分「哪个渠道花的钱」时看这里 |
两套口径的合计严格相等——它们只是对同一批事件的不同分组。
跨平台支持
插件不调用任何 shell / 系统命令，路径全部通过 node:path 拼接，
因此 macOS、Windows、Linux 以及 Web 端 DSH 都可用：
| 平台 | 支持 | 说明 |
|---|
| macOS | ✅ | 开发与验证环境 |
| Windows | ✅ | 更新时 rename 带重试，见下 |
| Linux | ✅ | fs.watch(recursive) 需 Node ≥ 20，engines 已要求 ≥ 22.19 |
| Web 端 DSH | ✅ | 只依赖 Host 的 webServer 路由；没有它时其余功能仍工作 |
Windows 专有处理：运行中的 Node 会锁住模块文件，直接 rename 会抛
EPERM/EACCES（macOS/Linux 不会）。更新器用退避重试处理这类锁，
非可重试的错误照常抛出，不掩盖真实问题。
会话日志用 Node 内置 zstdDecompressSync 读取（跨平台一致的纯 JS/C++ 实现），
不依赖系统 zstd 命令。
「重载插件」按钮何时出现
它默认不显示，只在一种情况下出现：磁盘上的代码已经换了，但运行中的
仍是旧版本（versionMismatch: true）。
理由：更新流程本身包含热重载（下载 → 替换 → 自动 selfReload），所以平时
那个按钮是多余的。它真正的用途是补救——例如更新后激活失败、或你手动
改了磁盘上的 index.js，此时需要一次显式重载把新代码加载进来。
判据由 Host 的 updater.status().versionMismatch 提供：它比较「模块声明并
运行的版本」与「磁盘 package.json 的版本」，两者不同即为需要重载。
图表配色
图表分类色不用 --dsw-alias-* 语义 token：那些 token 表达的是状态
（成功/警告/错误），不是分类，而且深色主题里 brand-primary 会渲染成近白色，
画环形图会出现一条白弧。
因此分类色用插件自己声明的 --tu-c1..7，并在样式表里给出亮/暗两套值
（[data-theme='dark'] 覆盖）。这样亮色模式是中等饱和度、暗色模式整体提亮，
相邻色始终可区分。
缓存命中率口径
命中率 = cacheReadTokens / (cacheReadTokens + inputTokens)
inputTokens 是真正新读入（未命中）的部分，cacheReadTokens 是命中缓存的部分，
两者相加才是这次调用消费的全部输入。cacheWriteTokens 是写入缓存的量，不计入
分母，否则会把命中率压低。
账号与用量归属
历史数据无法回溯到账号。 会话日志里 assistant/message 的结构化字段只有
turn / step / message / usage / stream，message.source 只有
kind / provider / model / replayState——没有 accountId、userId、keyId。
这是数据源的硬限制。
所以账号维度是这样工作的：
- 插件读取当前登录账号（
deepseekAccount.getProfile / getBalance，只读，
不碰凭据），显示在页面顶部，并给出官方用量页链接。
- 调用记录时带上「当时已知的账号」，因此切换账号之后的用量会归到新账号。
- 切换之前的历史统一归为「未知」。
- 官方账单口径以
usageUrl 指向的页面为准，本地统计用于趋势与归因。
不想让插件读取账号信息时，配置 trackAccount: false 关闭。
失败请求
assistant/attempt 是失败重试的中间态，理论上会消耗 token。但目前所有适配器
在这条路径上都只上报 {0,0,0} 的 usage——实测 259 次失败尝试、243 条 usage
记录，全部为零。
因此失败请求通常只有次数，没有 token 计入。插件保留了这条通道：如果上游
开始上报非零 usage，用量会自动出现在页面上，无需改代码。页面上会明确标注这个
限制，不会让你误以为失败请求不花钱。
该区块默认不显示，计数仍在内部累计。要看到它，把 trackFailedAttempts
设为 true：等上游开始上报真实用量后，数据会自动出现。
常见问题
页面打开是空的？
第一次打开要等回扫，几秒到十几秒，取决于会话数量。详见「启动回扫」。
换账号后历史用量跑哪去了？
归到「未知」。原因见上方「账号与用量归属」，日志里没有账号字段，补不回来。
数字和官方账单对不上？
本地统计按会话日志算，官方账单按实际计费算，两者口径不同。以官方为准，本地用来看趋势。
更新失败怎么办？
插件会明确报错并回滚。热重载依赖 Cordis 内部 API，DSH 或 Node 升级后可能失效，这时重启 DSH 即可。
会拖慢 DSH 吗？
不会。详见下方「性能」。
性能
统计分两条路径，开销差异很大：
| 路径 | 触发频率 | 实测开销 |
|---|
record() 记录一次调用 | 每个模型 step | ~0.9 µs |
| 无关事件（tool/call 等） | 日志绝大多数 | ~0.02 µs |
snapshot() 命中缓存 | 每次页面轮询 | ~0.0002 µs |
snapshot() 冷计算 | 有新数据时首次 | ~3-5 ms |
flush() 落盘 | 每 2 秒（防抖） | ~6 ms |
优化手段：
- 快照缓存：聚合结果只在有新调用时才变，按
snapshotCacheMs 缓存后，
轮询从 3ms 降到接近 0。
- 落盘防抖：多次调用合并成一次磁盘写入。
- prune 降频：清理过期数据要遍历整张去重表，改为最多每分钟一次。
- 页面轮询可调：10 秒 / 30 秒 / 1 分钟 / 5 分钟 / 关闭，选择记在
localStorage；页面隐藏时自动停表。
所以「实时统计」的成本主要不在统计本身，而在磁盘与页面轮询——两者都已可控。
启动回扫：历史用量如何补齐
首次安装即刻可用。 插件启动时把已有会话日志全部扫描一遍，所以你安装后
立刻就能看到历史用量，而不是从零开始累计。
扫描进度会显示在页面上：一个旋转图标 + 「正在扫描历史会话」+ 已扫描 12 / 27
的进度条。总数未知时进度条用循环动画表示「进行中」，不假装有确定的百分比。
三条扫描通路（任一条可用即完成扫描）：
sessionPersistence —— 通过宿主服务读取，最快；- 轮询同一个服务 —— 覆盖服务晚就绪的情况；
- 磁盘直读 —— 直接解压
.jsonl.zstd 会话日志，不依赖任何 Host 服务，
因此即使前两条都不可用，历史也一定能补回来。
扫描是增量的：每个会话记录已处理到的事件序号（scanned[id].seq），
之后启动只处理新增部分，不会重复全量扫描。
数据文件
$DSH_HOME/token-metrics/usage.json
数据一致性存疑时绝不丢弃历史。 早先的实现检测到 calls 与去重键数不符就
直接清零重建——而重建依赖 sessionPersistence，一旦该服务在某个组合里不可见，
历史数据就永久丢失。现在的行为是：
- 标记
needsRebuild，原样保留现有数据；
- 回扫成功后重建并清除标记；回扫失败则保留现有数据继续累计；
- 回扫有三条通路，其中一条直接从磁盘读取会话日志（Node 内置
zstdDecompressSync 解压 .jsonl.zstd），不依赖任何 Host 服务，因此
历史数据总是能重建。
写入采用 1.5 秒防抖 + 临时文件原子替换，避免每次调用都碰磁盘、也避免进程中断
留下半截 JSON。文件损坏或版本不符时会重新初始化，不会让插件启动失败。
按天分桶保留 400 天；去重表最多保留 20 万条键。
实现要点
两条数据通路，同一套去重键。
主通路监听 session/event，捕获 assistant/message 与 session/title。
补充通路包裹 llm/stream waterfall，只处理不落日志的调用（压缩、标题生成、
无会话的直连调用），其余一律 return next() 原样透传。
两条通路都用 (sessionId, turn, step) 作为去重键，所以：
- 实时增量与启动回扫不会重复计数；
- 同一事件被投递多次也只算一次；
- 重启后从日志重扫是幂等的。
回扫按 seq 增量。 scanned[sessionId] = { revision, seq }：revision 未变
直接跳过；变了则从已处理到的 seq 之后继续，不整段重扫。
进程级单例。 宿主热重载会加载第二份模块实例并各自 apply() 一次。若每个
实例各持一个 tracker，同一事件会被累加两次、两个实例又互相覆盖落盘结果。所以
tracker 挂在 globalThis 上，按 buildId（由 index.js 自身的大小与修改时间
派生）决定复用还是替换：
- 同一份代码 → 复用，不重复计数；
- 源码已变 → 换新实例并接管，修改立即生效。
自检与自愈。 正常情况下 total.calls 应严格等于去重键数（每次调用写一个
键）。接口返回 integrity 供页面判断；若读到偏差超过 10% 的历史文件，启动时
直接丢弃并按会话日志重建，而不是在错误数据上继续累加。
退出落盘只装一次监听器。 热重载会多次 apply()，每次都装
beforeExit 会累积监听器并拖住已废弃的 tracker；现在全局只装一个，并指向
当前 tracker。
成本核算
按模型的实际 token 用量自动估算成本，单位美元；卡片可点击切换人民币。
价格从哪来
- LiteLLM 公开价目表（社区事实标准，约 2800 个 chat 模型），启动后拉取并缓存到
$DSH_HOME/token-metrics/prices.json，之后离线也能用
- 内置兜底价目表：首次启动且尚未联网时，至少覆盖 DeepSeek / GPT-4o / Claude 等主力模型
- 手工补价：优先级最高，用于中转站自定义的模型名
同一模型有十几个价格时怎么选
LiteLLM 里同一个模型会挂在多个渠道下，价格能差几十倍（coralbricks/deepseek-v4.1-flash
是 $0.01/M，deepseek/ 官方是 $0.28/M）。插件按渠道可信度排序后取最权威的一个：
| 优先级 | 渠道 |
|---|
| 最高 | 官方直营（openai/、anthropic/、deepseek/、google/） |
| 高 | 主流云（azure_ai/、bedrock/、vertex_ai/） |
| 中 | 无渠道前缀的条目（通常是官方公布价） |
| 低 | 聚合与转售（openrouter/、coralbricks/、inferenceapis/） |
这样算出来的成本与官方口径一致，而不是随机落到某个最便宜的转售商。
自定义模型与倍率
- 中转站的自定义模型名（
qfmodel 之类）匹配不到价格时，页面会列出「未定价」并给出补价入口，填每百万 token 的美元单价即可，不会静默算成 0
- 供应商倍率：中转站常在官方价上加价，可通过
pricing/multiplier 接口按 provider 设置倍率
汇率
从 open.er-api.com 拉取实时 USD/CNY，缓存在 fx.json；拉取失败沿用上次的值，再失败用内置的 7.2。
供应商管理
顶部「模型接入」页签，管理第三方中转站与官方平台的余额、可用模型，并可一键
写入 DSH 模型配置。
添加供应商
先选「服务」，地址与协议会自动填好——比手抄 baseURL 可靠，也避免把
Anthropic 的地址配成 OpenAI 协议这类错误。
内置 35 个预设，按「国内 → 国际 → 自定义」排序：
| 分类 | 包含 |
|---|
| 国内模型 | DeepSeek、Kimi、智谱 GLM、MiniMax、阿里百炼、火山方舟、百度千帆、腾讯混元、百川、阶跃星辰、SiliconFlow、小米 MiMo |
| 国内 Coding Plan | 智谱、Kimi、MiniMax、阿里、火山、小米 MiMo |
| 国际 | OpenAI、Anthropic、Gemini、xAI、Groq、Mistral、Together、Fireworks、DeepInfra、Cerebras、OpenRouter、Novita、OpenCode Go |
| 自定义中转 | Sub2API、new-api、one-api、不查余额 |
选中服务后会标注该平台的能力：余额能否用 API key 查询、需要什么凭据。
余额与配额查询
两类数据分开呈现，语义不同：
| 类型 | 计费方式 | 展示 |
|---|
| 余额型 | 预充值，按量扣减 | 余额 · USD $60.09，点击可切换 RMB |
| 订阅制 | 按时间窗口限流 | 进度条 + 剩余 60% + 2h 15m 后重置 |
余额点击可在 USD / RMB 之间切换；CNY 余额在 USD 模式下按实时汇率换算，
不会出现「人民币数字配美元标签」。
余额接口
中转站按网关类型区分，从源头决定用哪个接口，不做盲目探测：
| 类型 | 端点 | 字段 |
|---|
| Sub2API | /v1/usage | balance（直接是美元） |
| new-api | /api/user/self | quota（÷500000 换算） |
| one-api | /dashboard/billing/subscription | hard_limit_usd |
官方平台适配器
按 baseURL 域名自动识别，走各自专用接口：
| 平台 | 端点 | 类型 |
|---|
| DeepSeek | /user/balance | 余额 |
| OpenRouter | /api/v1/credits | 余额 |
| SiliconFlow | /v1/user/info | 余额 |
| Novita | /v3/user/balance | 余额 |
| 阶跃星辰 | /v1/accounts | 余额 |
| 火山方舟 | /api/v3/billing/balance | 余额 |
| Kimi | /coding/v1/usages（无订阅时回退 /v1/users/me/balance） | 配额 + 余额 |
| 智谱 GLM | /api/monitor/usage/quota/limit | 配额 |
| MiniMax | /v1/usage | 配额 |
| OpenCode Go | /usage（rolling / weekly / monthly 三个窗口） | 配额 |
| OpenAI | /v1/organization/costs（需 sk-admin- 组织密钥） | 30 天用量 |
明确不支持查询的平台会给出原因而不是含糊失败：
- ChatGPT / Codex：订阅额度绑定账号登录态，API key 请求实测返回 403
- Gemini：Google 未提供公开的配额查询接口
- 阿里百炼 / 小米 MiMo：能识别域名，但没有公开的余额查询接口（MiMo 各候选
端点实测均 404），提示去控制台看，不发无谓请求
模型管理与同步
「该服务的模型」支持从端点拉取列表（GET {baseURL}/models）并勾选，也可手填
模型 ID。
模型能力自动识别
插件从 pi-ai 的模型目录（1241 个模型）读取每个模型的能力，勾选时自动填好：
| 能力 | 来源 |
|---|
| 上下文窗口 | 目录的 contextWindow |
| 输出上限 | 目录的 maxTokens |
| 思考档位 | 目录的 thinkingLevelMap（值为 null 表示该档不支持） |
| 附件能力 | 目录的 input（是否含 image） |
档位不是写死的 7 档：每个模型支持的档位不同——claude-fable-5 只有
xhigh/max，glm-5.2 只有 high/max。界面只列出该模型真正支持的档位，
目录没覆盖的模型则保留全部 7 档供手动勾选。
自定义协议值
网关不认档位名时（例如把 max 叫 ultra），可在「协议值」里为每个档位单独
指定实际发送的拼写：
reasoningEfforts:
low: low
max: ultra # 网关实际接受的词
同步到 DSH
「保存并同步」会把供应商写入 DSH 的 llm-pi-ai provider 配置，之后就能在
模型选择器里直接选它的模型。
密钥安全
插件不保存任何密钥。 密钥经 DSH 凭据服务托管，写入配置时只留引用名
（apiKeyEnv），任何形似 apiKey/token/secret 的字段都会被过滤掉。
右下角通知
关键状态变化通过右下角通知提醒，与 DSH 里其它插件的通知位置一致。
通知机制
用 SSE 长连接推送：DSH 没有通知服务，但 webServer 允许 handler 持有响应，
这正好是 SSE 需要的。定期写注释心跳防空闲超时，客户端断开即清理。
告警类型
| 类型 | 触发条件 | 级别 |
|---|
| 余额不足 | 余额 < 阈值（默认 $5） | 黄 |
| 余额已用尽 | 余额 ≤ $0 | 红 |
| 配额将尽 | 窗口剩余 < 阈值（默认 10%） | 黄 |
| 配额已用尽 | 窗口剩余 = 0% | 红 |
| 配额即将重置 | 已用尽且 10 分钟内恢复 | 绿 |
| 查询失败 | key 过期 / 站点挂 / 地址错 | 红 |
| 插件有新版本 | 检测到新版本 | 绿 |
告警消失时会发「已恢复」通知（余额已恢复 / 配额已恢复 / 查询已恢复）。
「即将重置」与「新版本」不是故障，消失时不提示。
三层去重，避免重复弹
| 层 | 机制 |
|---|
| 服务端冷却 | 余额/配额 30 分钟、查询失败 2 小时、新版本 24 小时 |
| 状态落盘 | 告警状态写入 alerts.json，插件重载后不会重推 |
| 客户端记忆 | localStorage 记 6 小时，页面刷新也不会重弹 |
告警条目与时间戳写在 $DSH_HOME/token-metrics/alerts.json，与用量数据分开
存放——它属于「已推送过什么」的记账，不是统计结果。
所有类型都有 60 秒硬下限，即使规则配 0 冷却也不允许短时间重复。
跨版本升级
跨版本升级是支持的——只要两版文件布局兼容，直接替换即可，不需要先卸载。
但差异过大时直接覆盖有风险，因此升级前会评估跨度：
| 情况 | 处理 |
|---|
| 补丁 / 普通次版本升级 | 直接执行 |
| 跨主版本、或跨 ≥3 个次版本 | 标为 risky：仍可尝试，失败时给出重装指引 |
目标包声明了 dsh.minSupportedVersion 且当前版本低于它 | 标为 incompatible：直接拒绝，不动磁盘 |
incompatible 或 risky 失败时，页面会弹窗提示：
该版本与当前版本差异较大，自动升级未能完成。请先在插件管理里卸载本插件，
再重新安装最新版本；你的统计数据保存在 $DSH_HOME/token-metrics 下，
卸载不会丢失。
包作者可以在 package.json 里声明最低可升级版本：
{ "dsh": { "minSupportedVersion": "0.2.0" } }
自更新与热重载
插件内置一条不依赖 pnpm 的更新通道，全自动，不需要手动重启：
检查新版本 → 下载 → 校验 → 备份 → 替换 → 热重载 → 失败回滚
- 更新源固定取自
package.json 的 repository，不接受任何来自配置或
请求的 URL——让配置项指向任意地址，就是从「写一个字段」直达「在宿主
进程里执行任意代码」的一步之遥。
- 版本比对用真正的 semver 优先级（预发布排在正式版之前）。
- 下载的 tar 包在解压时做路径穿越检查，拒绝
.. 与绝对路径。
- 替换前先备份整个包目录；激活失败会把磁盘和运行时都回滚，而不是留下
一个半装状态。
- 热重载用
expectedVersion 校验替换上去的代码版本，确保跑起来的是新代码
而不是缓存里的旧对象。
替换文件时先写临时名再 rename，避免半截文件被运行中的代码读到。Host 先回
202、再执行替换——热重载会注销当前 fiber，正在处理请求的 handler 会被
连带销毁。前端随后轮询版本号变化，确认升级真的生效，而不是凭「已受理」
就当成功。
热重载实测有效：改动 index.js 后触发 /reload，接口返回的 buildId
立即变为磁盘文件的新值（<size>:<mtime>），证明加载的是新代码。
统计页顶部有对应的按钮（检查更新 / 更新并重载 / 重载插件）。
关于热重载的边界
热重载依赖 Cordis 的内部 API（loader.internal、registry、fiber）。
这是在 DSH 没有「重载这个插件」官方 API 的情况下，唯一不受
already-installed 约束的路径。若某次 Node 版本升级改变了模块缓存的
形状，reload 会明确失败并说明原因，而不是悄悄留下旧代码；此时重启
DSH 即可。
开发
npm run check # 语法 + 三套测试
npm test # Host + Client + 更新器
npm run verify # 与真实会话日志独立比对（需宿主在跑）
Host 测试用假 ctx 驱动 apply()，覆盖：事件签名、去重、历史回扫、跨重启幂等、
热重载单例、buildId 交接、去重表裁剪策略。Client 测试用假 ModuleLoader 与假
React 驱动 factory，覆盖：slot 注册、文案双语键一致、样式仅用主题 token。
更新器测试覆盖版本比较、repository 解析、tar 解压安全、备份回滚。
文件
| 文件 | 作用 |
|---|
index.js | Host 侧：监听、聚合、回扫、账号快照、HTTP 接口 |
client.js | Client 侧：侧边栏入口 + 统计页 |
src/updater.js | 自更新：版本检查、下载校验、备份回滚 |
src/reload.js | 热重载：模块缓存清理、fiber 替换 |
src/pricing.js | 成本核算：价目表拉取、汇率、模型匹配、补价与倍率 |
src/balance.js | 中转站余额探测：Sub2API / new-api / one-api |
src/providers.js | 官方平台适配器（按域名识别）+ pi-ai 模型目录读取 |
src/sync.js | 把供应商写入 DSH 模型配置，密钥走凭据服务 |
src/push.js | SSE 推送与告警规则求值、冷却与去重 |
cordis.patch.yml | Bundle patch，插入插件行 |
locale/{zh,en}.json | Plugin Manager 里显示的标题与描述 |
icon.svg | 插件图标 |
test/ | 测试：Host 集成、Client 冒烟、更新器、日志比对 |
贡献
欢迎提 Issue 和 PR，见 CONTRIBUTING.md。
参与本项目即表示同意 行为准则。安全问题的报告方式见 SECURITY.md。
如果这个插件对你有用，欢迎点个 Star ⭐——这是对开源作者最直接的支持。
鸣谢
许可
MIT
