Ychris12138/dsh-usage-stats

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

本版本为 @ychris12138/dsh-usage-stats@0.3.6。npm 与市场安装要求该精确版本已经发布；发布前验收使用从冻结提交构建并核对哈希的本地 .tgz。

基础功能支持 @deepseek-ai/dsh >= 0.1.0-rc.6。安装时选择实际使用的 profile：命令行网页通常是 web，Desktop 使用 desktop；不要把插件装到另一个 profile 后只刷新当前窗口。DSH Desktop 的 DeepSeek Account 登录余额接入依赖 DSH 0.2.0-rc.2+ 提供的 Host account service；旧版 Harness 仍继续使用 API Key 余额路径。

确认 npm 上存在本版本后，优先安装精确版本；DSH Desktop Market 使用同一个包：

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

Desktop 安装时将上面的 --profile web 改为 --profile desktop，并使用 Desktop 对应的 DSH CLI。只有明确测试未发布 source/RC 时才使用 GitHub 来源；验收指定候选版本时优先安装从该提交打出的本地 .tgz，以免跟随分支变化。GitHub main 可能领先 npm stable。

安装后重启对应 profile 的 DSH Host；Desktop 需要退出并重新打开应用，然后刷新客户端。只刷新窗口不会加载新的服务端插件。侧边栏底部会出现“用量/余额”（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。本版本 package 与 catalog 元数据均为 0.3.6；目录中的版本号不代表 npm 发布已完成。每个新版本都按以下顺序发布：

1. 在 release 分支运行 npm run release:sync -- 同步 package、lockfile、README 与 catalog，检查候选包。npm 发布前不要把新 catalog 合入 main，因为 Pages 会自动部署。
2. 从冻结的 .tgz 发布 scoped 公共包：npm publish /absolute/path/to/ychris12138-dsh-usage-stats-0.3.6.tgz --access public --registry=https://registry.npmjs.org/，再核对 registry tarball 与冻结包的哈希。
3. npm 包核验通过后，将 main 快进到冻结的发布提交，触发 Pages 部署；核验 https://ychris12138.github.io/dsh-usage-stats/v1/plugins 的精确版本（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 注册，否则会重复挂载。

# 预览，不修改文件
npx --yes github:Ychris12138/dsh-usage-stats --dry-run

# 检查现有安装
npx --yes github:Ychris12138/dsh-usage-stats --check

# 安装但不修改 Cordis patch
npx --yes github:Ychris12138/dsh-usage-stats --no-enable

无法使用 npx 时可从源码运行 node scripts/install.mjs。

支持的账户类型 / Providers

插件自动发现官方 DeepSeek API Key 路由、DSH 0.2 的 deepseek-account 路由，以及 llm-pi-ai 中的 provider profile。只有存在公开账户接口、Host-owned account service 或显式 monitor 的供应商才会查询账户；Token 用量统计不需要额外凭据。

DSH 0.2 Desktop：0.3.5 已支持 Host-owned deepseek-account 登录余额；该路径依赖 DSH 0.2.0-rc.2+ 的 account service，不读取原始 token、Cookie 或 PKCE。旧版 Harness 与 API Key DeepSeek 仍继续使用 /user/balance 路径。

Provider / adapter · 模式 · 默认凭据 · 上游接口 DeepSeek API Key · 余额 · provider apiKeyEnv · /user/balance DeepSeek Account（DSH 0.2 Desktop） · 余额 · DSH Host-owned account grant；插件不读取 token/cookie · deepseekAccount.getState() + getBalance() OpenRouter · 余额 · OPENROUTER_MANAGEMENT_KEY · /api/v1/credits OrcaRouter · 余额 · ORCAROUTER_API_KEY · /v1/balance（旧部署回退到账单摘要接口） Moonshot / Kimi API · 余额 · provider apiKeyEnv · /v1/users/me/balance OpenCode Go · 订阅 · OPENCODE_API_KEY，兼容旧 OPENCODE_GO_API_KEY · /inference/go/v1/usage（兼容旧 /zen/go/v1/usage） Z.ai / 智谱 · 订阅 · 全球区 ZAI_API_KEY；中国区 ZAI_CODING_CN_API_KEY · Coding Plan quota/subscription Kimi For Coding · 订阅 · KIMI_API_KEY · /coding/v1/usages MiniMax Coding Plan · 订阅 · 全球区 MINIMAX_API_KEY；中国区 MINIMAX_CN_API_KEY · /v1/token_plan/remains Ollama 云 · 订阅 · OLLAMA_API_KEY · /api/usage（5小时 + 周窗口） Command Code（Go / GOAT / Pro / Max） · 订阅 + 余额 · COMMANDCODE_API_KEY · /alpha/billing/credits 等 /alpha/*（实验性：未公开端点） New API · 余额 · provider 推理 Token · /api/usage/token/ Sub2API / Passion · 自动判别 · provider apiKeyEnv · /v1/usage Sub2API 面板（真实） · 余额 · provider 推理 Token · /user/balance（复用 apiKey） CodeArts 系反代（dsh-codearts-auth） · 订阅 · 宿主插件账号池；本插件不读取 AK/SK · creditBalance.creditsBalances()（进程内） General / Declarative · 余额或订阅 · 配置中的 credential ref · 受限 GET + JSON

DSH 注册表仅返回路由 ID、未提供连接字段时，minimax 默认读取 MINIMAX_API_KEY 并请求全球区，minimax-cn 默认读取 MINIMAX_CN_API_KEY 并请求中国区。两条默认凭据不会互相回退。显式 credentialRef / provider apiKeyEnv 仍优先，引用缺失时不会借用默认 Key；自定义路由、provider endpoint 或自定义 usageBaseURL 不会自动继承这些凭据。这里显示的是 Coding Plan 订阅额度，不代表支持任意 MiniMax API 钱包余额或 Providers Hub 的 MiniMax Code 账号池。

MiniMax 区域优先级为 monitors..region > MINIMAX_API_REGION > route/baseURL/credential ref 推断。中国区与全球区凭据请匹配相应区域；明确区域的请求不会因 1004/2049 拒绝而切到另一区域，显式 usageBaseURL 仍只访问指定地址。

没有公开账户接口的供应商仍会正常统计 Token；账户卡片会明确显示“不支持”，不会猜测余额。

凭据与供应商配置 / Configuration

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

账户刷新 / Account refresh

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

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        refresh:
          enabled: false
          activeMs: 60000
          detailMs: 120000
          backgroundMs: 900000

三个间隔必须是 60000 至 86400000 毫秒之间的整数。需要停止时使用 refresh.enabled: false，不要填写超大的 timeout。关闭后，每个相同 provider 配置仍允许首次查询；之后普通面板读取只返回缓存，不会因缓存过期访问上游。账户端点的 refresh=1（Retry）仍可显式刷新，provider/monitor 配置变化后也会为新配置重新查询一次。

旧配置 disableBackgroundRefresh: true 继续等价于 refresh.enabled: false；两者同时存在时，显式的 refresh.enabled 优先。该开关只关闭账户上游自动刷新，不会关闭本地 Token 用量聚合。

估算费用与预算 / Estimated cost and budgets

预算是可选的非敏感配置，默认关闭。金额只在 provider、model、事件时间与货币均能由内置价格规则可靠确定时计算；未知中转、订阅路线、无价格的 cache write 或混合币种会整体显示 —，不会展示部分费用或进行汇率换算。

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: "@ychris12138/dsh-usage-stats"
      config:
        budgets:
          currency: USD
          daily: 5
          monthly: 100

预算使用本机日历日/月边界：低于 80% 为正常，达到 80% 为 warning，达到 100% 为 critical。daily / monthly 必须是正数或 null；当前版本不做 FX 换算，因此预算货币与可靠价格货币不兼容时状态保持 unknown。

面板的当前 provider 会保存在浏览器的命名空间 localStorage 中；刷新页面或重启 DSH 后恢复。若该 provider 已被删除，插件会清除旧值；DSH 0.2 Desktop 已登录时优先选择 deepseek-account，否则回退到已配置的 deepseek-official / 其他 provider。用户已有的有效选择始终优先，不会被自动切换。该选择不会写入 DSH 设置、服务端缓存或新 API。

DSH Desktop DeepSeek Account（DSH 0.2）

DSH 0.2 将浏览器登录的 DeepSeek Account 与 deepseek-official API Key 路由分开。插件通过 Host 的可选 deepseekAccount service 读取客户端安全的登录状态和余额结果，不会读取或复制账号 token、Cookie、PKCE 数据，也不会把它们发送到浏览器。

• deepseek-official：继续使用 DEEPSEEK_API_KEY / /user/balance，兼容旧 Harness；
• deepseek-account：使用 Desktop/Settings 已保存的账号 grant，通过官方 Host service 查询；
• 充值余额与赠送余额按币种合并；CNY 与 USD 同时存在时分别显示，绝不跨币种相加；
• Host Account 不参加后台账户轮询。只有带真实 UI 版本/语言/时区 metadata 的面板读取才会查询余额；退出或切换账号后，下一次 UI 读取不会继续复用旧余额；
• Host 账户服务动态获取，服务晚加载或重载后可自动恢复；服务替换、移除或退出登录后不复用此前余额。Desktop 更新插件后若服务端尚未重新加载，需要重启 Desktop Host，单独刷新窗口不能替代服务端重载；
• 未登录显示“未登录 DeepSeek Account”，不会误提示用户配置 DEEPSEEK_API_KEY。

CodeArts 系反代供应商（dsh-codearts-auth）

实验集成，当前官方包不可用：2026-10-23 校验的公开 npm 2.1.261022 仍不提供 creditBalance 服务，上游服务 PR #9 也已关闭且未合并。旧源码/运行包补丁仅适用于各自精确基线，不能直接用于新版，也不代表正式支持。见当前阻塞与历史配套构建说明。后续须先明确上游接受的脱敏服务边界与受支持构建，再完成真实隔离 profile 和账户对账。

deepseek-harness-codearts 的账号池路线包括 codearts / buddy / workbuddy / lobsterai / qoder / qodercn / trae / cline / loomy / raccoon / zcode，以及与内置供应商同名的 minimax。这些账号池路线的凭据由宿主插件持有，因此使用进程内余额接口。

宿主配套通过 ctx.provide('creditBalance', service) 提供以下接口：同步的 supportedProviders() 返回 { id, displayName? }[]，异步的 creditsBalances(providerId) 返回 { accounts: [{ accountId, nickname?, balance, error? }] }。仅有 accountPool 或内部 credits.balances RPC 不满足此契约。

2026-10-20 已对上游当前源码与 npm 1.9.261020 分别制作配套候选包，并在解包后通过真实 Cordis/宿主余额分派与本插件的联调。供应商取数使用合成读数；真实账户对账仍待完成。安装 Usage Stats 不会自动修改已安装的 Providers Hub。标准 MiniMax Coding Plan 不依赖这项实验集成。

本插件经 ctx.get('creditBalance') 读取服务计算的 CreditBalance。服务清单只补充不存在的 provider，并为这些条目标记明确的宿主来源；不会覆盖已注册的同名路由。裸 minimax 仍按内置 MiniMax token plan 查询，缺少 apiKeyEnv / baseURL 不能证明它属于 CodeArts。

新增渠道名如 gemini、modelscope 也可能属于独立 API 供应商，不能仅凭名字将其归入宿主账号池。服务新增的条目可依来源标记识别；既有同名路由需显式配置 codearts-credits。徽章简称不构成账户或定价归属证据。

若已注册的 minimax 实际使用 CodeArts 账号池，需要在现有 usage-stats 配置下显式选择适配器：

monitors:
  minimax:
    adapter: codearts-credits

• 数据所有权完全在宿主插件：本插件不读取、不复制、不转发 AK/SK、token、Cookie；只读余额结果与积分包元数据；
• 积分按包展示（每个包的已用比例与到期日），不压成单一余额数字——用户要看的正是「哪个包快过期」；
• 活跃包可由 total - used 补出缺失的剩余额度；只有 remaining 时显示绝对值，不猜百分比。所有分包都不可读而有有效汇总余额时使用汇总，不叠加重复统计；
• 过期包可保留已知的历史消耗比例，但不参与当前剩余额度告警或侧栏最低额度。缺失金额显示 —；
• 宿主响应缺少 accounts 列表时报响应异常；标记 stale 的旧余额不作为新鲜额度展示；
• 宿主插件缺席时这些卡片显示“不支持”，不影响其余 provider，也不会让插件启动失败；
• 查询失败不会显示成 0；reason / partial 只包含固定安全原因码，不包含上游原始错误、失败账号的昵称或 ID。

余额型供应商

DeepSeek API Key、Moonshot 等默认复用对应 provider profile 的 apiKeyEnv。例如：

# ~/.dsh/.credentials.yaml
DEEPSEEK_API_KEY: sk-your-key-here

OpenRouter 是明确的例外：官方账户 credits 接口要求 Management Key，不能复用普通推理 OPENROUTER_API_KEY。插件默认读取独立引用；未配置时显示“未配置”，不会拿推理 Key 试探：

# ~/.dsh/.credentials.yaml
OPENROUTER_MANAGEMENT_KEY: sk-or-v1-your-management-key

插件按 total_credits - total_usage 显示 OpenRouter 余额，并同时展示累计已用和总 credits。普通 Key 的 /api/v1/key 只描述单个 Key 的 spending limit，不会被当作账户余额。自定义引用可在 monitors.openrouter 中设置 adapter: openrouter-balance 与 credentialRef。

OrcaRouter 优先读取其余额接口 /v1/balance，将 paid、free 和 promo credits 汇总为当前可用余额；旧部署没有该接口时，回退到官方文档提供的 OpenAI-compatible 账单摘要接口（订阅端点总额度 + usage 端点累计用量，按美分换算）。任一可用路径返回无法识别的数据时会显示明确的错误状态，不会把未知结果当作 0；无限额度哨兵值会显示为 ∞，OrcaRouter 路由仍不参与本插件的模型价格估算。

Token Plan 供应商

# ~/.dsh/.credentials.yaml
OPENCODE_API_KEY: sk-opencode-your-key
ZAI_API_KEY: your-zai-key
# 中国区 Z.ai 用户可选；默认 global
ZAI_API_REGION: bigmodel-cn
KIMI_API_KEY: your-kimi-key
MINIMAX_API_KEY: your-minimax-key
# 中国区 MiniMax 用户可选；默认 global
MINIMAX_API_REGION: cn
# DSH 中国区 minimax-cn 路由默认使用此凭据名
MINIMAX_CN_API_KEY: your-minimax-cn-key
OLLAMA_API_KEY: sk-ollama-your-key
COMMANDCODE_API_KEY: user-your-command-code-key

OpenCode Go 原生路由先读取当前 DSH 使用的 OPENCODE_API_KEY，缺少时才兼容旧 OPENCODE_GO_API_KEY，然后尝试旧版 OpenCode 的 ~/.local/share/opencode/auth.json，最后才使用显式 OPENCODE_GO_AUTH_COOKIE + OPENCODE_GO_WORKSPACE_ID 兼容回退。显式 monitor/provider credential ref 始终优先，缺失时不借用本地文件或其他账户的凭据。先访问官方迁移后的 /inference/go/v1/usage，仅在 404/405 时用同一密钥尝试旧路径；401/403/429 不重试或更换密钥。Bearer usage endpoint 仍不是稳定的公开 API。

若账户卡片显示「未配置」，说明未找到凭据，还未发起额度查询。OpenCode V2 的凭据存储不再等同于旧 auth.json；已登录 OpenCode 不代表 DSH 已配置密钥。请在 DSH 的 OpenCode Go 模型设置中配置自己的 Console API Key，或在 DSH credentials 中配置上述引用。不要导出 OpenCode 的凭据数据库或把密钥、Cookie 贴到 issue；本插件不会扫描或解密 V2 凭据数据库。

也可以使用官方 Console 查看账户额度，或用 OpenCode 的 stats 查看该客户端的本地 token/费用；数据范围与限制见 OpenCode 用量来源。Providers Hub 的 OpenCode 通道可用数不作为 Go 额度显示。

Cookie 路径仅在没有选中任何 API Key 时使用；已选中的 Key 查询失败，不会再切换到 Cookie 所属的另一账户。

Ollama 云读取 OLLAMA_API_KEY，调用 /api/usage 展示两个订阅窗口（5 小时会话 + 每周），无余额；usage 按 0..1 比例换算为进度条。

Ollama 适配器只对已配置的 provider 生效，不会自动添加账户：当 provider 的 id 为 ollama，或其 baseURL 主机为 ollama.com（含子域）时自动选用；本地 Ollama（localhost:11434）不会被当作云配额账户。特殊代理/自定义端点可用显式 monitor 绑定：

# ~/.dsh/profiles/web/cordis.patch.yml
- insert:
    - id: usage-stats
      name: dsh-usage-stats
      config:
        monitors:
          relay-ollama:            # 你配置的 provider id
            adapter: ollama
            usageBaseURL: https://ollama.example.com
            credentialRef: OLLAMA_API_KEY   # 非已配置 provider 时必填

Command Code（Go / GOAT / Pro / Max）——实验性适配器。 它读取 COMMANDCODE_API_KEY，调用的是 Command Code 自己 CLI 使用的一组未公开、未版本化端点（不属于其公开 Provider API）：/alpha/billing/credits 给出 credits 与 5 小时/每周窗口，/alpha/usage/summary 给出本期请求数与花费，/alpha/billing/subscriptions 给出档位（Go / GOAT / Pro / Max）与计费周期。上游随时可以改动或收紧这些端点，届时卡片会退化为「响应异常」，不会影响 Token 统计本身。卡片因此显示三条窗口——5 小时、每周、每月（每月的重置时间就是订阅周期结束时间）——外加一行 credits 美元余额，这是本插件里唯一一张余额与订阅窗口并存的卡片。

三条窗口的口径：5 小时与每周按上游直接给出的「已用金额 ÷ 上限」换算；月度池只用它自己那一对数字——credits.monthlyCredits（月度池剩余）与 /alpha/usage/summary 的 totalMonthlyCredits（本期从月度池花掉的部分）——作为分母的两半（推导值）。充值 purchasedCredits 与赠送 freeCredits 是另外两个池：它们只出现在余额行与 breakdown 里，不进月度窗口的分母；聚合的 totalCredits 同样不进，若 totalMonthlyCredits 缺失就干脆不画月度窗口，而不是拿聚合值凑一个分母。