Lwc-LiuWenCheng/dsh-provider-usage

dsh-provider-usage

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

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

功能 / 功能

- 右下角小气泡 / 右下角小气泡：精简显示 + 悬浮详情（shell.overlay）；悬浮容器覆盖气泡与浮层，鼠标可自由移入。
- 跟随主题 / 跟随主题：使用 --dsw-alias-* 设计令牌着色，亮/暗主题自动适配。
- 本地时间 / 本地时间：更新于 显示设备本地完整时间；窗口 重置 只显示本地月日。
- 自动发现提供商 / 自动发现提供商：从 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。
- 更新策略 / 更新策略（可配置，含默认值）：
- on-request（默认）：用户发起请求时更新（宿主监听 session/event 计数）；
- steps：每隔 N 个消息步更新（N 可配，默认 1）；
- interval：固定间隔（10–3600 秒，默认 60）；
- reset：最早用量窗口重置后更新（智能调度）；
- hover：仅查看/手动刷新。
- 设置页 / 设置页（settings.section）：选择策略与参数，更改立即生效。
- i18n：通过 locale 服务注册 provider-usage 命名空间词典（zh/en）。
- 模型工具：注册 provider_usage 工具，对话中可直接询问用量。

安装 / 安装

一键安装（推荐）

包内自带安装脚本（本地源码构建 → 打包 → 官方 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  →
校验 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-.tgz）与安装脚本
均从它派生；发版流程为 npm version  → npm run build
→ pnpm pack → 安装脚本。

cordis.patch.yml bundle 补丁会自动挂载插件行；无需编辑 profile 文件。安装后，重启 DSH 以使新的 bundle 层生效。如果同一会话仍在运行动态开发副本，重启前会同时存在两个气泡——重启后动态副本消失。

配置 / 配置
组合默认值（可在配置文件的 cordis.patch.yml 行中覆盖，或
通过应用内设置页面覆盖；应用内的更改在插件生命周期内优先）：

- 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 项目——宿主端和客户端均使用 tsc 编译（编译器 API，
不启动 shell），客户端输出会被包装成 dsh Web 客户端运行时
所消费的 ModuleLoader 打包格式：

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

目录结构：

- src/index.ts — 宿主端 cordis 插件：webServer JSON 路由
（/provider-usage/query、/provider-usage/config、/provider-usage/activity）、
session/event 活动计数器，以及 provider_usage 模型工具。
- src/usage-core.ts — 提供方发现 + 凭据 + node -e
抓取辅助程序 + 响应规范化。
- src/client/index.ts — 气泡、设置页面、语言字典。
- scripts/build.mjs / scripts/smoke-test.mjs — 构建与打包冒烟测试。

宿主端使用 src/vendor.d.ts 环境存根，因此无需安装完整的 peer 依赖树
即可直接运行 tsc；在完整安装中，运行时由真实的包类型接管。

Architecture notes / 架构说明

- 提供方密钥在每次查询时通过凭据服务解析；
node -e 辅助程序在调用会话的沙箱策略下运行，并且
仅使用单引号，因为 pwsh 本地执行器会将命令字符串
传递给 pwsh -Command。
- “按用户请求” / “每 N 步”从不轮询提供方 API：宿主端
从 session/event 事件流中统计 user/message 和 assistant/message 事件，
客户端则读取这些开销极低的本地计数器。

License

MIT