dsh-provider-usage

Readme

# 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
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）：**

```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）

```bash
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):

```yaml
- 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:

```bash
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