dsh-provider-usage

A DSH web plugin that shows the live usage/quota of every configured LLM model provider in a small bubble at the bottom-right of the page. The bubble shows a minimal summary (the worst usage percent, color-coded) and expands into per-provider detail on hover — percent bars per usage window, reset times, numeric values, and a refresh button. Styling follows the app theme, times are rendered in device-local time (resets as month+day), and text follows the app language (zh / en).

一个 DSH Web 插件：在页面右下角以小气泡展示所有已配置模型提供商的实时用量/配额。气泡默认精简显示（最差窗口百分比，按状态着色），悬浮展开每个提供商的详情（各用量窗口百分比条、重置时间、数值与刷新按钮）。样式跟随应用主题，时间按设备本地时区显示（重置时间只显示月日），文字跟随系统语言（中/英）。

Features / 功能

• Bottom-right bubble / 右下角小气泡：精简显示 + 悬浮详情（shell.overlay）；悬浮容器覆盖气泡与浮层，鼠标可自由移入。
• Theme-aware / 跟随主题：使用 --dsw-alias-* 设计令牌着色，亮/暗主题自动适配。
• Local times / 本地时间：更新于 显示设备本地完整时间；窗口 重置 只显示本地月日。
• Auto-discovery / 自动发现提供商：从 llm-pi-ai / llm-deepseek 设置枚举；内置 OpenCodeGo（/v1/usage，rolling/weekly/monthly 百分比 + 重置时间）、OpenRouter（/auth/key）、OpenAI（billing subscription + usage）、DeepSeek（/user/balance）；未知提供商自动探测 /usage、/user/balance、/dashboard/billing/subscription。
• Update policy / 更新策略（可配置，含默认值）：
  • on-request（默认）：用户发起请求时更新（宿主监听 session/event 计数）；
  • steps：每隔 N 个消息步更新（N 可配，默认 1）；
  • interval：固定间隔（10–3600 秒，默认 60）；
  • reset：最早用量窗口重置后更新（智能调度）；
  • hover：仅查看/手动刷新。
• Settings page / 设置页（settings.section）：选择策略与参数，更改立即生效。
• i18n：通过 locale 服务注册 provider-usage 命名空间词典（zh/en）。
• Model tool：注册 provider_usage 工具，对话中可直接询问用量。

Install / 安装

一键安装（推荐）

包内自带安装脚本（本地源码构建 → 打包 → 官方 CLI 安装 → bundle 自动注册）：

Windows（PowerShell 5.1 / pwsh）：

powershell -ExecutionPolicy Bypass -File scripts\install.ps1            # 默认 web profile
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Restart   # 装完自动 pm2 重启
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -DryRun    # 只预览

macOS / Linux（bash）：

./scripts/install.sh
./scripts/install.sh -r          # 装完尝试 pm2 restart

脚本会自动：检出并构建缺失的 lib/ → pnpm pack → dsh plugin --profile web add <tarball> → 校验 dsh.profile.bundles 已包含 dsh-provider-usage。

已发布版本（registry）

dsh plugin --profile web add dsh-provider-usage@latest
# 或指定版本（版本号唯一来源是 package.json）
powershell -ExecutionPolicy Bypass -File scripts\install.ps1 -Version latest

版本管理：package.json 的 version 是唯一版本来源——构建产物 （lib/）、tarball 名称（dsh-provider-usage-<version>.tgz）与安装脚本 均从它派生；发版流程为 npm version <major|minor|patch> → npm run build → pnpm pack → 安装脚本。

The cordis.patch.yml bundle patch mounts the plugin row automatically; no profile file edits are needed. After install, restart DSH so the new bundle layer activates. If the same session is still running the dynamic development copy, two bubbles coexist until the restart — the dynamic copy disappears afterwards.

Configuration / 配置

Composition defaults (overridable in the profile's cordis.patch.yml row or through the in-app settings page; in-app changes win for the plugin lifetime):

- id: provider-usage
  name: 'dsh-provider-usage'
  config:
    updatePolicy: on-request   # on-request | steps | interval | reset | hover
    updateIntervalSeconds: 60  # used by the interval policy
    updateEverySteps: 1        # used by the steps policy

Build / 构建

TypeScript project — host and client are compiled with tsc (compiler API, no shell spawning), and the client output is wrapped into the ModuleLoader bundle format the dsh web client runtime consumes:

npm install          # devDependencies: typescript only
npm run build        # → lib/index.js (host) + lib/client.js (client bundle)
npm run typecheck    # tsc --noEmit for both halves
npm publish          # runs prepublishOnly (build) first

Layout:

• src/index.ts — host cordis plugin: webServer JSON routes (/provider-usage/query, /provider-usage/config, /provider-usage/activity), the session/event activity counter, and the provider_usage model tool.
• src/usage-core.ts — provider discovery + credentials + the node -e fetch helper + response normalization.
• src/client/index.ts — the bubble, the settings page, locale dictionaries.
• scripts/build.mjs / scripts/smoke-test.mjs — build and bundle smoke test.

The host uses src/vendor.d.ts ambient stubs so a bare tsc run works without the full peer tree installed; the real package types take over at runtime in a full install.

Architecture notes / 架构说明

• Provider keys are resolved per query through the credentials service; the node -e helper runs under the calling session's sandbox policy and is single-quote-only because the pwsh-local executor passes the command string to pwsh -Command.
• "On user request" / "every N steps" never poll the provider APIs: the host counts user/message and assistant/message events from the session/event feed, and the client reads those cheap local counters.

License

MIT