dsh-usage-stats

为 DeepSeek Harness 网页端提供多供应商账户监测与 Token 用量分析。

Provider balances, subscription quotas, and token-usage analytics for the DeepSeek Harness Web GUI (dsh web).

展示图使用脱敏演示数据；插件不会把 API Key、Cookie、管理 PAT 或上游原始响应发送到浏览器。

🐋 OrcaRouter sponsors this project and is available as an optional OpenAI-compatible provider. Learn more · Referral link.

一眼看懂 / At a glance

	能力	说明
💳	统一账户卡片	API 供应商显示余额，Token Plan 显示分窗口额度；面板一次只呈现当前供应商
📊	Token 用量分析	今日、本月、累计、缓存命中率、月历热图，以及按日期/供应商/模型下钻
💰	估算费用与预算	按事件时间匹配历史价格，提供日/月费用、session 级聚合及可选预算预警
🔄	后台监测	账户按 active/detail/background 自适应刷新；间隔可配置或完全关闭，本地 Token 聚合保持独立运行
🧩	可扩展适配器	支持 New API、Sub2API、通用余额模板，以及声明式 JSON Pointer 自定义查询
📦	安全导出	提供 daily/session CSV 与版本化 JSON；Unicode、CSV 公式前缀和不完整费用均安全处理
🔒	本机安全边界	数据端点仅接受回环 GET；OrcaRouter preset 仅由带防跨站请求头的显式回环 POST 写入；凭据只在服务端解析

界面支持中文和英文。浏览器只请求当前选择的 provider；账户自动刷新由服务端统一调度。手动刷新会更新用量、供应商列表，并强制刷新当前账户，不会批量强制请求其他供应商。

快速安装 / Quick start

需要 DeepSeek Harness web profile（@deepseek-ai/dsh >= 0.1.0-rc.6）。

稳定版优先安装 npm 上的精确版本；这也是 DSH Desktop Market 使用的同一个包：

dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.3"

只有测试尚未发布的 source/RC 时才使用 dsh plugin --profile web add "github:Ychris12138/dsh-usage-stats"。GitHub main 可能领先 npm stable，不应把 source 安装当作市场安装验收。

然后重启已经运行的 dsh web，并在浏览器中硬刷新。侧边栏底部会出现“用量/余额”（Usage/Balance）入口。

插件市场 GUI 安装（DSH Community Market，Path A 标准来源）

本仓库按 DSH Community Market 目录 adapter 指南 的标准来源（Path A） 接入，无需修改 Market 代码。内置两份目录数据：

• catalog/catalog-source.json — 来源 manifest（catalog-source.schema.json v1.0.0）
• catalog/v1/plugins.json — 标准 provider page（catalog-provider-page.schema.json v1.0.0）

使用前提（重要）：市场托管安装只接受 npm registry 的精确稳定版本，git 条目仅可浏览。dsh-usage-stats 这个 npm 名已被其他项目占用，因此目录条目身份使用 @ychris12138/dsh-usage-stats。当前 stable/catalog 版本是 0.3.3；每个新版本都按以下顺序发布：

1. 运行 npm run release:sync -- 同步 package.json / package-lock.json / catalog/v1/plugins.json，再由 npm run check:release 阻止身份或版本漂移。
2. 发布 scoped 公共包：npm publish --access public。
3. 把 catalog/v1/plugins.json 内容发布到 https://ychris12138.github.io/dsh-usage-stats/v1/plugins（GitHub Pages，manifest 与 endpoint 必须同源、HTTPS 443、无凭据）。
4. 在 DSH 插件市场 → 来源管理 → 添加来源，粘贴 manifest URL：https://ychris12138.github.io/dsh-usage-stats/catalog-source.json，选择后即可走「可恢复安装边界」GUI 安装。

目录若先指向尚未发布的版本，市场安装会 fail-closed，这是预期行为。只有 npm、Pages catalog 与 Desktop Market 实际安装全部验证后，才算完成发布。

升级或卸载：

dsh plugin --profile web update "@ychris12138/dsh-usage-stats"
dsh plugin --profile web remove "@ychris12138/dsh-usage-stats"

兼容安装器：无法使用 dsh plugin 时展开

PowerShell、命令提示符和 macOS/Linux 终端使用同一条命令：

npx --yes github:Ychris12138/dsh-usage-stats

安装器会把运行文件复制到 ~/.dsh/profiles/node_modules/@ychris12138/dsh-usage-stats，并在 profiles/web/cordis.patch.yml 中以带引号的 scoped identity 幂等启用插件。重复运行即可更新，不会重复追加配置；旧版 name: dsh-usage-stats 和未加引号的 name: @ychris12138/dsh-usage-stats 会自动迁移。设置了 DSH_HOME 时使用该目录。

dsh plugin 与 npx 是两条独立安装路径，请选择其中一种；不要同时保留手工 Cordis entry 和 bundle 注册，否则会重复挂载。

## 凭据与供应商配置 / Configuration

凭据由 Harness 从 `~/.dsh/.credentials.yaml` 解析。安装器不会读取、创建或修改该文件。不要把真实 Key、Cookie 或管理令牌提交到 Git、公开 issue，或粘贴给编码 Agent。

### 账户刷新 / Account refresh

默认刷新间隔是 active 1 分钟、detail 2 分钟、background 15 分钟。严格限流的 New API 或公司中转可以调整全局策略，或完全关闭账户自动刷新：

```yaml

# DSH 模型页里为 Sub2API 面板配置 provider，baseURL 指向面板，API Key 填可用的密钥

Passion（provider id 为 passion 或域名为 *.passionapi.com）会自动识别。钱包响应显示余额；quota_limited 或包含 subscription 的响应自动切换为额度窗口。

声明式自定义查询只支持受限 GET + JSON Pointer，不执行 JavaScript：

        monitors:
          private-model:
            adapter: declarative
            mode: balance
            request:
              path: /account/balance
              auth:
                type: bearer
                credentialRef: PRIVATE_MODEL_API_KEY
            extract:
              root: /data
              remaining: /available_balance
              used: /used_balance
              total: /total_balance
              currency: /currency

支持的 adapter：deepseek-balance、openrouter-balance、moonshot-balance、zai-balance、new-api、sub2api、sub2api-auth、general、opencode-go、zai-token-plan、kimi-token-plan、minimax-token-plan、declarative。

warning.warnBelow 与 warning.criticalBelow 是余额绝对值阈值。具有总额度的余额和 Token Plan 会自动产生 normal / warning / critical 剩余比例状态（默认 30% / 10%）。

使用 / Usage

1. 点击侧边栏“用量/余额”。
2. 用“当前供应商”切换账户卡片；一次只显示一个 provider。
3. 使用 ‹ / › 切换月份，点击热图日期查看当天的 provider/model 明细。
4. 标题栏刷新会更新 Token、provider 列表，并强制刷新当前账户。

安全导出 / Secret-free export

三个下载端点只导出聚合后的白名单字段，不包含 credential ref/value、Authorization、Cookie、上游原始响应、prompt/reply 或文件路径：

• /api/usage-stats/export/daily.csv：每天 × provider/model 的四类 Token 与完整费用估算。
• /api/usage-stats/export/sessions.csv：session 标题、provider/model 集合、Token、完整费用估算和最后活动时间。
• /api/usage-stats/export.json：带 schemaVersion 的完整聚合数据、公开 pricing provenance、预算和安全账户状态。

CSV 使用 UTF-8、RFC 4180 引号与 spreadsheet formula 防护；Unicode 标题可直接打开。费用只在 costComplete=true 时导出，未知/混合币种保持空白或 null，不会输出部分金额。

“最近 14 天”按本地日历计算，只显示窗口内存在用量的日期；未来时间戳不会计入。同一模型来自不同 provider 时会分别统计，例如 deepseek-official · deepseek-chat 与 ark · deepseek-chat。

Agent 友好安装 / Agent-friendly installation

复制给 Codex、Claude Code 或其他本地编码 Agent

Install or update dsh-usage-stats from:
https://github.com/Ychris12138/dsh-usage-stats

Constraints:
- Resolve DSH_HOME from the environment; otherwise use ~/.dsh.
- Do not read, print, edit, or request .credentials.yaml, auth.json, cookies, or any API key.
- Do not expose the plugin through a reverse proxy.
- Do not restart or terminate an existing dsh process without asking me.

Procedure:
1. Confirm node, npx, and dsh are available.
2. Prefer the exact npm stable used by Desktop Market: `dsh plugin --profile web add "@ychris12138/dsh-usage-stats@0.3.3"` (or update the existing scoped package).
3. Use `github:Ychris12138/dsh-usage-stats` only when I explicitly ask to test unreleased source/RC code.
4. If dsh plugin is unavailable, use the compatible source installer only with my approval: `npx --yes github:Ychris12138/dsh-usage-stats`.
5. Do not combine bundle installation with an existing manual dsh-usage-stats Cordis entry.
6. For npx, require a verified package and exactly one Cordis entry, then run again with --check.
7. Report the exact package identity/version, installation path, and resolved profile paths.
8. If dsh web is running, report that a restart is needed and stop.

Optional account setup (never handle secret values yourself):
- OpenRouter account balance requires OPENROUTER_MANAGEMENT_KEY, not the inference key.
- OpenCode Go may reuse local auth.json or use OPENCODE_GO_API_KEY.
- Z.ai uses ZAI_API_KEY; China accounts may set ZAI_API_REGION=bigmodel-cn.
- Kimi and MiniMax use KIMI_API_KEY and MINIMAX_API_KEY.
- Never ask me to paste a key or browser cookie into chat.

Optional monitor setup:
- Read configured Harness provider ids and ask which id should receive a monitor.
- Add only non-secret config under the existing dsh-usage-stats Cordis entry.
- Store credential reference names, never credential values.
- Validate relative request.path and JSON Pointer fields beginning with /.
- Do not enable cross-origin, insecure HTTP, or private-network access unless I explicitly request it.

只获准检查而不能修改时运行：

npx --yes github:Ychris12138/dsh-usage-stats --check

安装器退出码：未知参数返回 2；文件、版本或配置验证失败返回非零；成功时输出已验证版本、安装目录和 patch 路径。Agent 无需自行解析或重写 YAML。

隐私与安全 / Privacy & security

• API Key、OpenCode auth.json、Cookie 与管理 PAT 不会进入浏览器响应、插件缓存或日志。
• Sub2API sub2api-auth 复用 provider 自己的推理 API Key（模型页已配置的那个），不会再引入或落盘额外的面板凭据。
• 自定义 monitor 默认要求 HTTPS、同源相对路径、手动 redirect 和 JSON 响应，body 上限为 1 MiB。
• 发凭据前会筛选域名的 IPv4/IPv6 解析结果并固定一个允许的连接地址，优先使用公网地址；HTTPS 域名解析到 198.18.0.0/15 时可作为 Clash/Mihomo 等代理的 synthetic fake-IP 使用。字面量 198.18/15、其他私网/特殊地址仍默认拒绝，防止 DNS rebinding 绕过私网限制。
• usageBaseURL 禁止内嵌 username/password；Authorization、X-API-Key、API-Key 等 header 必须由 credential ref 注入。
• 九个数据端点仅接受 GET；OrcaRouter 集成路由的 GET 只返回布尔状态，POST 仅在用户点击后执行局部 settings mutation，并要求非简单自定义 action header。所有路由同时校验 peer socket 与 Host，支持 IPv4、IPv4-mapped IPv6 和 [::1]:port。
• 用量缓存 ~/.dsh/storages/usage-stats-cache.json 只保存聚合 Token、会话 id、不透明 revision 与折叠游标，不保存提示词、回复或文件路径。

本机反向代理会让插件看到代理自身的回环地址。请勿把端点经反向代理暴露到局域网或公网；确需代理时必须在代理层增加可靠认证与访问控制。安全问题请按 SECURITY.md 私下报告。

正确性与数据口径 / Correctness

Token 统计值来自 assistant/chunk 或 assistant/message 中 provider-reported usage，不是本地估算。相同 turn/step 的后续样本会替换旧样本，并按 provider/model 归集。

费用是明确标注的估算派生值：每个 usage 样本使用自己的事件时间、原始 provider/model 与四类 token bucket 匹配 lib/pricing.js；替换样本会先减去旧费用，再加入新费用。绝不会用“当前价格 × 历史累计 Token”。每个 session 的派生费用继续进入 usage.sessions、session CSV、JSON export 与整体 billing aggregation；插件不会向 DSH composer 注入 session UI。

• 活跃会话只处理新追加事件。
• 持久化会话使用不透明 revision（Harness 的 list()；旧版 listSnapshots() 仍兼容）；未变化时不重复读取日志。
• 持久化日志通过 Harness 的 open(id, "read") 读句柄读取（旧版 readFrom() 仍兼容），每次读完立即关闭句柄。
• 已退出 live store 的会话（例如已结束的 sub-agent 运行）在下一次聚合时按 id 补读持久化日志，其 Token 计入日/模型总量，无需等待后台全量扫描。
• seq 缺口、日志重写或 live/persisted 切换时完整重折叠该会话。
• 聚合采用 single-flight，并在同一临界区原子保存缓存。
• validate:live 会逐会话比较 raw artifact、session.history、插件端点与官方 token projection；缺文件或不一致会返回非零。

API

Method	Path	Response
GET	/api/usage-stats/usage	按日期/provider/model 聚合的 Token、派生费用、session 明细与日/月预算状态
GET	/api/usage-stats/providers	provider 列表、account mode、adapter、状态与预警摘要
GET	/api/usage-stats/account?provider=	当前 provider 的统一余额或 Token Plan 快照；refresh=1 强制刷新
GET	/api/usage-stats/balance?provider=	0.1.x 余额兼容路由
GET	/api/usage-stats/subscriptions	0.1.x Token Plan 兼容路由
GET	/api/usage-stats/session-context?session=	当前 live session 的 route/model/account 与同一增量 fold 的 session 费用快照
GET	/api/usage-stats/export/daily.csv	secret-free daily provider/model CSV
GET	/api/usage-stats/export/sessions.csv	secret-free session CSV
GET	/api/usage-stats/export.json	versioned usage、budget、pricing provenance 与 account-safe JSON
GET	/api/usage-stats/integrations/orcarouter	仅返回 OrcaRouter preset 是否可写/已存在的 secret-free 布尔状态
POST	/api/usage-stats/integrations/orcarouter	用户明确请求后，以 revision-guarded path mutation 幂等加入 preset；要求 application/json 与 X-DSH-Usage-Stats-Action: add-orcarouter

除上述 OrcaRouter POST 外，非 GET 返回 405；非回环请求返回 403。API JSON 使用 Cache-Control: no-cache；下载响应使用 Cache-Control: no-store 与固定文件名。

开发与验证 / Development

npm install
npm run check
npm test
npm pack --json

npm test 完全离线，覆盖 bundle、客户端渲染与请求竞态、服务端安全边界、余额/Token Plan adapter、缓存和安装器幂等性。真实数据验证需先运行 dsh web：

npm run validate:live
node scripts/check-balance.mjs

所有服务端脚本均遵循 DSH_HOME。check-balance.mjs 可能显示真实余额，不要把输出粘贴到公开 issue。

兼容性与致谢 / Compatibility & credits

当前 npm stable 为 0.3.3；v0.3.3 的完整发布门禁见 docs/release-checklist.md，变更摘要见 docs/release-notes-v0.3.3.md。插件依赖 Harness 客户端模块加载器、Cordis 服务与 session persistence；Harness 预发布接口变化时可能需要同步适配。

持久化与活跃会话的读取按能力探测分支，不按版本号判断，因此 >= 0.1.0-rc.6 的支持范围未变：0.1.3-alpha.1–0.1.5-rc.2 用 list() 快照 + open(id, "read") 读句柄，0.1.0-rc.7–0.1.2-rc.1 用 listSnapshots() + readFrom()；活跃会话同时支持 seq/snapshotEvents() 与旧版 events 数组。session/disposed 在该范围内均存在（缺少它时已结束会话改由后台全量扫描补读）。缓存格式仍为 version: 5，旧缓存直接复用并原地重折叠。

display.currentSessionPill 作为 v0.3.0 legacy boolean 配置键继续被接受，避免旧配置导致启动失败；当前客户端不再注册任何 composer UI，因此该键不再产生可见效果。session-context 服务端 API 暂时保留原有响应语义，供 v0.3.0 API compatibility 与后续集成使用。

• Javis603/token-monitor：参考多 provider 配额归一化与 Z.ai 限额解析。
• xiaoqi20/dsh-opencode-go-usage：参考 DSH 凭据接入、OpenCode auth.json 回退与 Bearer usage endpoint。

本项目重新实现统一 account protocol、adapter 与单供应商 UI，不复制参考项目界面。

License

MIT

使用 / Usage

1. 点击侧边栏“用量/余额”。
2. 用“当前供应商”切换账户卡片；一次只显示一个 provider。
3. 使用 ‹ / › 切换月份，点击热图日期查看当天的 provider/model 明细。
4. 标题栏刷新会更新 Token、provider 列表，并强制刷新当前账户。

安全导出 / Secret-free export

三个下载端点只导出聚合后的白名单字段，不包含 credential ref/value、Authorization、Cookie、上游原始响应、prompt/reply 或文件路径：

• /api/usage-stats/export/daily.csv：每天 × provider/model 的四类 Token 与完整费用估算。
• /api/usage-stats/export/sessions.csv：session 标题、provider/model 集合、Token、完整费用估算和最后活动时间。
• /api/usage-stats/export.json：带 schemaVersion 的完整聚合数据、公开 pricing provenance、预算和安全账户状态。

CSV 使用 UTF-8、RFC 4180 引号与 spreadsheet formula 防护；Unicode 标题可直接打开。费用只在 costComplete=true 时导出，未知/混合币种保持空白或 null，不会输出部分金额。

“最近 14 天”按本地日历计算，只显示窗口内存在用量的日期；未来时间戳不会计入。同一模型来自不同 provider 时会分别统计，例如 deepseek-official · deepseek-chat 与 ark · deepseek-chat。