dsh-balance-panel · DSH 模型余额面板

仓库名 dsh-model-balance；npm 包名 @wycto/dsh-balance-panel（scoped 命名，绑定 npm 账号 wycto，杜绝包名冲突；旧无前缀名 dsh-balance-panel 已废弃）。 DeepSeek Harness 插件：在侧边栏底部显示当前 DSH 配置的所有模型 Provider 的账号余额， 点击打开余额面板查看每个 Provider 的模型列表、密钥状态与余额明细。

功能特性

• 只列已配置项：只展示你在 settings 里实际配置过的 Provider（user/base 层有 profile，或为默认模型选中的 Provider）与其实际配置的模型；休眠声明与 schema 默认的全量模型列表不会出现。
• 真实余额：内置 DeepSeek 官方 /user/balance 接口；其他 Provider 可自定义余额接口（见下文）。
• 密钥状态：每个 Provider 显示其 apiKeyEnv 凭证是否已配置（密钥本身永不出 Host 进程）。
• 侧边栏入口：设置按钮旁的小胶囊显示当前余额摘要（如 余额 64.23 CNY），每 5 分钟自动刷新。
• 余额面板：点击胶囊打开全屏面板，逐 Provider 展示模型 chips、余额明细（总额/赠送/充值）与状态徽标。
• 优雅降级：无密钥 / 接口不支持 / 查询失败都给出明确文案，不影响其他 Provider（不支持的显示「不支持」）。

工作原理

┌────────────────────────── 浏览器（Client 半身 lib/client.js）──────────────────────────┐
│  tool.view.cordis        ← Run 卡片内嵌余额视图（最新一次运行卡片内）                     │
│  sidebar.footer.action   ← 余额胶囊（摘要 + 点击开面板）                                  │
│  shell.overlay           ← 余额面板（已配置的 Provider / 模型 / 余额）                    │
│          │  GET /dsh-balance-panel（同源 fetch，每 5 分钟 + 手动刷新）                          │
└──────────┼───────────────────────────────────────────────────────────────────────────────┘
           ▼
┌────────────────────────── Host 进程（Host 半身 lib/host.js）─────────────────────────────┐
│ 1. llm.listConfigurableProviders()  →  声明目录（含休眠条目，逐个过滤）                   │
│ 2. settings.describe({redactSecrets}) → 按 user/base 层定位已配置 profile（默认值不算）   │
│ 3. credentials.describe/resolve    →  密钥状态 / 密钥值（只在本进程内使用）               │
│ 4. 余额策略 → fetch 余额接口（DeepSeek /user/balance 或 profile.balance 自定义）          │
│ 5. webServer 注册 GET /dsh-balance-panel，返回归一化 JSON                                     │
└───────────────────────────────────────────────────────────────────────────────────────────┘

目录结构

dsh-balance-panel/
├── package.json           # npm 包元数据 + dsh 元数据（bundle.patch / client.inject）
├── cordis.patch.yml       # 插件加载行（- insert: { id: dsh-balance-panel, name: 包名 }）
├── lib/                   # 发布产物（files 只发布 lib/ + 上述文件）
│   ├── host.js            #   Host 半身（ESM；Node 全局 fetch；注册 /dsh-balance-panel 路由）
│   └── client.js          #   浏览器半身（__ModuleLoader__ 格式 bundle，由 src/client.js 生成）
├── src/                   # 源码
│   ├── host.js            #   Host 半身源码（= lib/host.js）
│   └── client.js          #   浏览器半身源码（纯 JS，React.createElement，无 JSX）
├── scripts/
│   └── build-client.mjs   # 把 src/client.js 打包成 lib/client.js（无需 esbuild）
├── README.md              # 本文档
├── LICENSE                # MIT
└── .gitignore

为什么是这个结构？ DSH 的插件约定：一个 npm 包 = 一个插件，cordis.patch.yml 提供一行 loader 行 （name 指向包名），Host 半身由 main/exports["."] 解析，浏览器半身由 exports["./client"] + dsh.client.inject 元数据解析。lib/ 是发布产物、src/ 是源码，改代码后 npm run build 重新生成客户端。

安装

方式一：profile 用户（推荐，dsh CLI）

dsh plugin --profile web add @wycto/dsh-balance-panel

等价于在 ~/.dsh/profiles/web 里执行 pnpm add @wycto/dsh-balance-panel。 包声明了 dsh.bundle.patch，装好后会自动进入插件的 layer 栈并生效。

重启 Web UI（或刷新 http://127.0.0.1:3080）。

方式二：源码运行（pnpm dsh web）

# 把本目录放进仓库，例如 scratch-plugin/
pnpm dsh web --patch ./dsh-balance-panel/cordis.patch.yml

方式三：本地开发调试

cd dsh-balance-panel
pnpm install          # 安装 peer 依赖（@deepseek-ai/cordis 等，profile 里已有可跳过）
pnpm dsh web --patch ./cordis.patch.yml

使用

1. 启动 DSH Web UI，侧边栏底部（设置按钮旁）出现 余额胶囊：
   • 余额 64.23 CNY —— 有可用余额的 Provider 摘要（取第一个）；
   • 余额 … —— 首次加载中；
   • 余额 — —— 尚无可用余额数据（如所有 Provider 都不支持查询）；
   • 余额 × —— 数据加载失败。
2. 点击胶囊打开 余额面板：每个 Provider 一张卡片，包含：
   • 名称（默认 Provider 带「默认」徽标）与状态徽标（可用 / 不支持 / 未配置密钥 / 查询失败）；
   • Provider id、API 类型、baseURL、密钥引用（apiKeyEnv）及是否已配置；
   • 该 Provider 下所有模型 chips；
   • 余额明细：货币、总额、赠送余额、充值余额（来自接口 balance_infos）。
3. 面板右上角可 手动刷新；胶囊每 5 分钟自动刷新一次。

支持的余额接口与自定义

策略匹配顺序：profile 自定义 balance 配置 > provider id（含别名，大小写不敏感）> baseURL 家族正则。所以用网关代理了 StepFun/Kimi 等官方端点时，只要 baseURL 域名匹配就会自动命中对应解析器；密钥引用可用配置的 apiKeyEnv，缺省回退到各策略默认的环境变量名（如 STEPFUN_API_KEY、OPENROUTER_API_KEY）。

为任意 Provider 自定义余额接口：在 settings 中该 Provider 的 profile 里加一个 balance 字段：

llm-pi-ai:
  providers:
    my-gateway:
      api: openai-completions
      baseURL: https://gateway.example.com/v1
      apiKeyEnv: MY_GATEWAY_API_KEY
      models:
        - id: my-model
      balance:                       # ← 插件读取的自定义余额配置
        endpoint: /billing/balance   # 相对 baseURL，或完整 URL
        auth: bearer                 # bearer（默认）或 none

endpoint 为 /xxx 时拼接在 baseURL 后；为 https://... 时直接使用。 auth: none 时请求不带 Authorization 头（适用于网关内网余额接口）。

常见问题（FAQ）

Q：为什么我的 Provider 显示「不支持」？ A：该 Provider 没有内置余额接口、也未配置 balance.endpoint。按上节配置自定义接口即可； 纯 OpenAI 兼容端点通常不提供余额 API，可先向你的服务商确认是否有查询余额的端点。

Q：显示「未配置密钥」？ A：apiKeyEnv 指向的凭证未配置。请把凭证放进 DSH 凭证系统 （如 ~/.dsh/.credentials.yaml，格式 KEY_NAME: value）或设置同名环境变量。

Q：密钥安全吗？ A：密钥只通过 credentials.resolve 在 Host 进程内解析使用，余额请求由 Host 发出， 浏览器端拿到的只是余额结果，密钥不会进入任何前端或日志。

Q：面板打不开 / 胶囊不出现？ A：确认插件已加载（启动日志应出现 dsh-balance-panel 相关行），并刷新页面； 再确认部署的 Web 是回环访问（localhost），/dsh-balance-panel 路由只在回环 webServer 上注册。

Q：没有 pnpm，dsh plugin 用不了？ A：npm 同样可以：cd ~/.dsh/profiles/<profile名> && npm install @wycto/dsh-balance-panel， 然后把 "@wycto/dsh-balance-panel" 追加到该目录 package.json 的 dsh.profile.bundles 列表，重启即可 （等价于 dsh plugin add 的效果）。

开发与构建

npm run build          # 重新生成 lib/client.js（src/client.js → __ModuleLoader__ 格式）

客户端源码是纯 JS（React.createElement，无 JSX），只依赖 react（web 平台 seed）， 因此构建脚本无需 esbuild；若后续引入更多依赖，把依赖加入 package.json 的 dsh.client.inject 并改用 esbuild --bundle --format=cjs 即可。

分享到社区

1. 发布 npm：改好 package.json 的 repository/homepage 后 npm publish。 关键元数据已就位：dsh.bundle.patch（自动进 layer 栈）、dsh.client（浏览器半身发现）、 files（只发布必要文件）。
2. 开源 GitHub：git init && git add . && git commit，推到你的仓库，附上本 README 与截图。
3. 用户安装只需一条命令：dsh plugin --profile web add @wycto/dsh-balance-panel。

License

MIT