dsh-token-guard-lite · Token 护盾(开源版)
这是开源版(Lite)。 它只做一件事:把每一次模型调用的花费如实算出来。
需要下面这些能力,请装 Pro 版:
npm i @xuanzhiyouxuan1020/dsh-token-guard
- 子代理路由漂移预警 —— 子代理的路由在创建时冻结,主会话之后切模型不会回溯, 于是一不留神就会出现"我以为在用便宜模型,实际子代理在按贵的路由扣费"
- 预算护栏 —— 会话/单轮花费逼近阈值时提醒,或在子代理花钱之前阻断委派
- 缓存诊断 —— 命中/未命中的来源分析
这些能力的代码只存在于 Pro 版,本仓库里没有,所以本版也不存在 "输入某个 License Key 就解锁"的路径(
POST /token-guard-lite/license恒返回未授权)。
能力对照
| 能力 | Lite(本仓库) | Pro |
|---|---|---|
| 🛡️ 预估单轮花费 | ✅ | ✅ |
| 会话汇总(预估总花费 / 缓存命中率 / 峰谷占比) | ✅ | ✅ |
| 归因明细导出 CSV / JSON | ✅(子代理路由被遮罩) | ✅(全量) |
| 本地定价表 + 改价即重算历史 | ✅ | ✅ |
| "⚠️ 检测到子代理消耗" | ✅(不含具体路由) | ✅ |
| 子代理真实路由 | 🔒 显示「Pro 版提供」 | ✅ |
| 路由漂移预警(顶部横幅 + 路由对比) | — | ✅ |
| 缓存诊断(命中/未命中来源) | — | ✅ |
| 预算护栏(提醒 / 阻断委派) | — | ✅ |
金额是估算,不是账单
本地合计(例如 ¥5.56)常常高于官方控制台的实际扣费(例如 ¥1.04)。 差异可能来自:宿主层的重试(同一次请求尝试多次)、被 provider 折算掉的隐藏 usage、 以及两边的统计窗口口径不同。本地只看得到 usage 快照,看不到官方账单的折后口径 —— 所以我们不宣称本地数字等于账单。
界面上所有金额都带「预估」二字,展开的明细下方固定有一行灰字:
* 金额基于本地定价表与全量 usage 估算,实际扣费请以 DeepSeek 官方账单为准。
导出的 CSV 列名是 estimatedCostCNY,JSON 响应带 estimated: true 与 disclaimer 字段。
安装
# 从 npm(发布后)
dsh plugin --profile <profile> add dsh-token-guard-lite
# 或本地目录:插件管理器 → 添加插件 → 选择本目录
装好后刷新,会话输入框旁与设置页会出现「护盾授权」(Lite 版里这一页只剩定价表和导出)。
配置(cordis.patch.yml)
- insert:
- id: dsh-token-guard-lite # 同时是设置命名空间,别改
name: dsh-token-guard-lite
config:
purchaseUrl: 'https://www.npmjs.com/package/@xuanzhiyouxuan1020/dsh-token-guard'
display:
showTurnCost: true
showCacheHitRate: true
showPeakStatus: true
decimals: 6 # 金额展示小数位
exportMaxRecords: 400
pricing:
currency: CNY
peak:
enabled: true
utcOffsetHours: 8 # 北京时间
peakMultiplierBp: 10000 # 万分比:10000 = ×1.0
idleMultiplierBp: 5000
windows:
- days: [1, 2, 3, 4, 5]
start: '09:00'
end: '12:00'
models:
- provider: deepseek-account
model: deepseek-flash
inputMiss: 2 # 元 / 百万 tokens(缓存未命中输入)
cacheHit: 0.5
cacheWrite: 2
output: 8
label: deepseek-flash
- provider: ''
model: '*' # 兜底价
inputMiss: 4
cacheHit: 1
cacheWrite: 4
output: 16
label: 未配置模型的兜底价
价格只来自这里(或设置页);defaultPriceTable() 只是配置缺失时的兜底,请以本文件为准。
端点(Host 半体)
| 方法 | 路径 | 用途 |
|---|---|---|
| GET | /token-guard-lite/ping.json |
存活探测 |
| GET | /token-guard-lite/report.json?sessionId= |
看板数据(不传 sessionId = 全局) |
| GET | /token-guard-lite/export.csv / export.json |
归因明细导出 |
| POST | /token-guard-lite/license |
恒返回 {ok:false, reason:'pro-only'}(Lite 无解锁路径) |
| POST | /token-guard-lite/pricing |
保存定价表(写回 profile patch,需 configEditor) |
所有金额字段都是微元整数(1e-6 元);
report与导出 JSON 都带estimated: true与免责声明。路由前缀用
-lite是为了和 Pro 版的/token-guard/*并存不冲突。
开发
npm install
npm run build # tsc(宿主)+ esbuild(浏览器半体)→ lib/
node test/run-all.mjs
src/index.ts 宿主:装配、usage 观察、HTTP、报告装饰
src/usage-collector.ts 归因与用量折叠(纯函数)
src/pricing.ts 整数微元计费 + 峰谷(Host/Client 共用)
src/report.ts 事实 → 当前价目的报告 + CSV
src/client/index.tsx 浏览器半体:turnTail / composer.dock / settings.section
test/ 验收测试
已知限制
- 金额是估算,不要拿本地数字对账(见上)。
- 子代理的真实路由在 Lite 里被遮罩;需要它请用 Pro 版。
- 子会话若在读报告时尚未落盘(或
sessionQuery不可用),花费显示为"待回填",刷新后补齐。 - 浏览器半体文案目前是中文单份(
src/client/index.tsx顶部TEXT表)。
许可证
MIT
No comments yet. Be the first to write one.