计费观测台 hoyyang/dsh-agent-billing

dsh-agent-billing

banner

Agent 计费与用量可观测插件 — 多账号计费档案 + 玻璃拟态双层 UI（实时徽标 + 详细面板）+ 中转站余额实查 + 预算告警。

Agent billing & usage observability for DeepSeek Harness — multi-account billing profiles, glassmorphism dual-layer UI (live badge + full dashboard), relay-station balance queries, and budget alerts.

version platform license

功能 / Features

- 实时记账：会话日志直扫通道（zstd 解压 → 逐事件按自带时间戳入账，水位 + lastSeq 双防双计），按 provider + model 双归属落账（Node 内建 SQLite），零额外模型请求
- Per-window「本会话」：徽标经 React fiber 读取所在窗口的会话唯一 id（标题重复/改名免疫），?session= 精确账单——多窗口各自显示自己的成本，切会话实时更新
- 多账号计费档案：每个 provider 路由（公司 API / 中转站 / Kiro / 官方）独立一套四档费率（输入 / 输出 / 缓存读 / 缓存写，每 Mtok）+ 币种 + 折扣 + 按模型覆盖（mini-glob）
- 双层 UI：
- 实时徽标（侧栏底部）：本会话/今日花费实时跳动 + 预算状态色点，点击开面板
- 详细面板（全屏玻璃拟态）：概览（四统计卡 + 14 天趋势 sparkline + 预算条）/ 明细（按账号·按模型）/ 会话 / 设置 四页签，今日·本月·累计三窗口
- 余额实查：DeepSeek 官方（/user/balance）与 New API 兼容中转站（/v1/dashboard/billing/）两种适配器，按档案配置
- 预算告警：日/月预算，80% 预警（黄）、超限（红）反映在徽标色点与预算条
- 展示可定制：档案、费率、预算、刷新频率全部设置页驱动（存 settings.json），无需改代码
- 模型计费规则库：内置 332 模型官方计费规则库（可配置数据源定期自动刷新）；按模型手动配置；智能配置（Agent 模型解析网页/描述/截图自动生成规则）
- 币种体系：CNY / USD / credit（Kiro 类积分，估算系数，全链路积分显示不折人民币）
- 导入导出：一键导出全量 JSON（档案 + 规则 + 账本）；导入合并 / 替换

安装 / Install

本机开发（super-injector 快路径）
dev_build_plugin { dir: "" } # host tsc + client tsdown
dev_inject_plugin { dir: "" } # 免重启热注入

打包安装（bundle 形态）
dsh plugin add

要求 / Requirements：DSH web 实例（host 需含 webServer 服务）；Node ≥ 22（内建 node:sqlite）。

快速开始 / Quick start

1. 点击侧栏底部徽标打开面板 → 设置 页签
2. ＋ 新建档案：填名称、Provider 匹配（如 kiro、zhipuai、relay-）、币种、四档费率（每 1M token）→ 保存档案
3. 费用立即按 Σ(tokens × 费率) × 折扣 重算历史与实时；未匹配档案的用量按 0 计费并在「(未匹配)」行提示
4. 可选：档案内配置余额查询（适配器 + Base URL + API Key）→ 查询余额 按钮
5. 可选：设置日/月预算 → 徽标色点与预算条进入预警/超限状态

费率档案 Schema / Profile schema

{
"id": "zhipuai-direct", // 稳定唯一 id "label": "智谱直连", // 展示名 "providerMatch": "zhipuai", // 精确 / / 前缀* / 后缀 / 含（大小写不敏感） "currency": "CNY", "discount": 0.9, // 可选，1 = 原价
"rates": { "input": 2, "output": 8, "cacheRead": 0.5, "cacheWrite": 2 }, // 每 1M token
"byModel": { "glm-4.7": { "input": 2, "output": 6, "cacheRead": 0.2, "cacheWrite": 2 } },
"balance": { // 可选
"adapter": "deepseek", // 'deepseek' | 'openai-billing'
"baseUrl": "https://api.deepseek.com",
"apiKey": "sk-..." // 仅存本地 settings } }

数据与存储 / Data & storage

| 文件 | 内容 |
| DSH_HOME/dsh-agent-billing/ledger.sqlite | 用量样本（ts/session/provider/model/四档 tokens）+ 水位表（防重放/重启双计） |
| DSH_HOME/dsh-agent-billing/profiles.json | 费率档案（原子写） |
| DSH_HOME/dsh-agent-billing/settings.json | 预算、刷新频率、汇率、智能配置 |
| DSH_HOME/dsh-agent-billing/model-rules.json | 模型计费规则（手动 + 智能生成） |
| DSH_HOME/dsh-agent-billing/smart-log.jsonl | 智能配置运行日志 |

卸载不删数据：卸载插件后上述文件保留，重装即恢复历史账本。彻底清除请手动删除 DSH_HOME/dsh-agent-billing/ 目录。

安全 / Security

- 本地优先：除余额查询外零网络外发；账本/档案全部本地
- HTTP 路由仅服务 loopback 对端 + 变更请求同源校验（先例：dsh-session-manager）
- 余额 API Key 仅存本地文件、仅在按下「查询余额」时向你配置的 Base URL 发起请求
- 不碰 DSH 凭据库、不注册任何 Agent 工具（上下文经济：零 tools schema 负担）

卸载 / Uninstall

super-injector 快路径
dev_uninject_plugin { match: "dsh-agent-billing" }

bundle 安装
dsh plugin remove dsh-agent-billing

从 profile 的 cordis.patch.yml 移除 dsh-agent-billing-patch 条目并删除对应 junction 后重启 dsh web 即净；账本数据 ~/.dsh/dsh-agent-billing/ 保留，可手动删除。

卸载即净：loader entry / junction / 注入清单 / client 模块全部移除，profile patch 写入 disabled 阻断条目防自装配加回。

已知边界 / Known limits

- 预算为各档案花费数值直加：混合币种场景请统一档案币种口径（UI 有提示）
- 装插件之前的历史用量不可回补（水位从安装时刻起算）；重装不丢（水位持久化）
- usage chunk 早样本无 provider 归属，沿用该会话最近一次已知的 provider/model
- 中转站余额依赖其 OpenAI billing 兼容接口；不兼容的站点会得到点名失败的 502
- Kiro credit 为任务级封装，插件按估算系数（credit/1M token，用户可配）显示『积分（估算）』，非精确账单
- 非 token 计量维度（搜索按次/机器时/音频时长/生图张数）DSH usage 不上报，规则中仅存展示单价不参与合计

License

BSD-3-Clause