token-usage-statistic

dsh plugin --profile web add token-usage-statistic

token-usage-statistic

DeepSeek Harness（DSH）插件：统计本机所有模型调用的 token 用量与按事件时间估算的费用，提供历史回填、账户余额/订阅额度、日/月预算与无凭据导出，并在侧边栏面板中呈现。同时适配 DSH Desktop 与 DSH Web —— 两者加载同一份 Web 客户端包和同一套 Host 插件图，因此只有一份实现。

1.0.2 把每日图表的指标切换（Tokens / 调用次数 / 预估费用）移到图表标题旁，并增加“当前指标 · 合计”摘要，切换后能直接看到数值和柱状图变化；同时补齐了 Desktop / Web 的安装说明。

界面预览

账户余额与订阅额度 · 无凭据导出

!账户 · !导出

能力

能力 · 说明

用量采样 · assistant/message、assistant/chunk、compaction/summary 三源；同一 turn:step 的后续样本替换先前样本

历史回填 · 启动后增量扫描 sessionPersistence；账本中每个会话的最高 seq 就是游标，fork 从 inheritedEventCount 起读

费用估算 · 每个样本按自己的事件时间匹配历史价格规则（DeepSeek 峰谷时段、上海时区）；未定价 fail-closed

账户余额 · DSH Desktop 账户服务、官方 DeepSeek API Key、llm-pi-ai provider 的公开余额接口

订阅额度 · 通用 JSON Pointer 映射的额度窗口（已用/上限/剩余/重置时间），支持自定义 monitor

预算 · 日/月上限、80% 预警/超限状态；费用不完整时不拿部分和比较

导出 · 按日 CSV、会话 CSV、版本化 JSON；无凭据、Excel 安全

面板 · 用量 / 账户 / 导出三个标签页，中英文文案跟随界面语言

架构

Session 事件（DSH 的真相来源）
  assistant/message · assistant/chunk · compaction/summary
        │
        ▼
┌──────────────────── Host（src/host）─────────────────────┐
│ collector  事件 → 样本（route/turn:step/usage）           │
│ pricing    事件时间 → 单价规则 → 单样本费用               │
│ store      样本 → 日/模型/会话折叠（替换＝先减后加）       │
│ ledger     每次接受追加一行 JSONL（可重放）               │
│ backfill   sessionPersistence 增量补历史（后台、限并发）   │
│ accounts   发现/刷新账户，凭据只在 Host 解析，结果归一化    │
│ budgets    日/月费用与上限状态                            │
│ api        summary · accounts · 3 个导出端点              │
└───────────────────────────────────────────────────────────┘
        │ same-origin fetch（仅回环）
        ▼
┌──────────────────── Client（src/client）──────────────────┐
│ sidebar.panellist  侧边栏行（文案 thunk 跟随语言）         │
│ main (key=token-usage)  面板：用量 / 账户 / 导出           │
└───────────────────────────────────────────────────────────┘

设计要点：

• 账本是唯一可重放的来源。内存折叠是从账本重建的派生态；重启、热更新、重装都不会丢统计。
• 费用不落盘。账本只存原始 token 桶与路由，费用在重放时按价格规则重新计算 —— 价格表更新后可以重算历史。
• 账户凭据不出 Host。credentials.resolve() 只在每次刷新时于 Host 内调用；落盘缓存 accounts.json 与接口响应都只有归一化数字和粗粒度错误码。
• 网络出口有边界。账户查询仅 HTTPS（回环允许 HTTP）、不跟随重定向、15 秒超时、1 MiB 上限、拒绝 URL 内嵌凭据。
• 同源 HTTP 而不是生成式 Remote。路由必须是 exact（当前 Web 载体接受 prefix 注册但不派发）；所有端点只接受回环 GET/HEAD。

目录

src/host/usage.ts          纯函数：token 桶、日键、事件采样、v1→v2 迁移
src/host/pricing.ts        DeepSeek 历史价格表、峰谷规则、模型别名
src/host/cost.ts           费用累加器与 fail-closed 渲染
src/host/store.ts          折叠、替换、范围过滤、快照、导出行
src/host/ledger.ts         JSONL 串行追加与坏行跳过
src/host/collector.ts      事件 → 样本，route 回退
src/host/backfill.ts       持久化会话增量回填（含 fork 边界）
src/host/accounts/         账户类型、网络、schemes、注册表与刷新调度
src/host/budgets.ts        日/月预算
src/host/export.ts         CSV/JSON 投影与 CSV 注入防护
src/host/api.ts            只读 HTTP 路由
src/host/config.ts         配置归一化
src/host/index.ts          Host 入口 apply()
src/client/*.ts            React 面板、格式化、i18n、React 绑定
index.js / client.js       esbuild 构建产物（仓库内提交）
test/                      vitest 单元测试（120 个）
scripts/smoke-client.mjs   对构建后的 client.js 做假 shell 冒烟

安装

兼容性

运行环境 · 支持 · 面板

DSH Desktop · ✅ · 侧边栏「模型用量统计」

DSH Web (dsh web) · ✅ · 同一个侧边栏面板

DSH CLI / headless · ⚠️ 仅采集 · 无侧边栏；账本仍写入，但面板与 HTTP 导出依赖 Web 载体

插件是 bundle 包：package.json 同时声明 dsh.bundle.patch 和 dsh.client.platform: "web"。Host 负责采集、计价、账本和账户查询，Client 是同一份 Web 面板；Desktop 与 Web 加载同一份 index.js / client.js。

Desktop 与 Web 使用不同的 profile（desktop / web），安装是分开的：在 Desktop 安装不会自动出现在 Web，反之亦然。两端都需要时，各装一次。

前置条件

• Node.js >= 20（从源码构建或本地开发时需要）
• 已初始化的 DSH profile：desktop 或 web
• 安装 npm 包时需要能访问 npm registry
• 账户余额功能需要 DSH 已登录 DeepSeek 账户，或配置了对应 provider 凭据

方式一：npm 包（推荐）

DSH Desktop

1. 打开 DSH Desktop → 插件 / Plugins

2. 搜索或直接输入包名 token-usage-statistic，点击安装

3. 安装完成后重启 DSH Desktop（Host 代码只在启动时加载）

4. 左侧边栏出现「模型用量统计」

如果 Discover 里暂时搜不到，说明官方索引尚未同步；直接按包名安装即可。

也可以在对话中让 agent 执行：

plugin_manager( action: "install_bundle", target: "token-usage-statistic" )

DSH Web

dsh plugin --profile web add token-usage-statistic
# 然后重启 dsh web
dsh web

方式二：GitHub 源码

dsh plugin --profile web add github:zhiwuli0228/token-usage-statistic

Desktop 端可以先 clone 到本地，再按方式三安装。

方式三：本地目录（开发/调试）

plugin_manager( action: "install_bundle", target: "E:\\009workspace\\dsh\\token-usage-statistic" )

Web profile：

dsh plugin --profile web add E:\009workspace\dsh\token-usage-statistic

本地目录是链接安装。修改 src/ 后必须：

npm install
npm run build

然后重启 Host 并刷新页面；只改源码不会生效。

方式四：手动 patch（高级）

如果不用插件管理器，可以把包加入 profile 的 package.json 依赖，并在 cordis.patch.yml 中插入：

- insert:
    - id: token-usage-statistic
      name: token-usage-statistic

然后重新加载 profile。一般不需要这样做。

安装后检查

# Web profile
dsh plugin --profile web list | findstr token-usage-statistic

Desktop 端在 插件 页应能看到 token-usage-statistic 已启用。

面板入口：左侧边栏 → 模型用量统计。如果看不到入口，先确认 Host 已重启、页面已刷新。

数据位置

默认：%DSH_HOME%\token-usage-statistic\usage.jsonl。可用 dataFile 配置覆盖。

配置

所有字段可选，非法值回退默认：

- override:
    - id: token-usage-statistic
      config:
        dataFile: 'D:\\dsh-data\\usage.jsonl'   # 默认 $DSH_HOME/token-usage-statistic/usage.jsonl
        refreshMs: 60000                        # 面板轮询，最小 3000，默认 15000
        sessionLimit: 12                        # 会话表条数，1..100
        recentLimit: 200                        # 内存保留的最近样本，0..5000
        backfill: true                          # 是否回填历史会话
        modelAlia

…(truncated)