dsh-ai-wallet

Readme

# dsh-ai-wallet

> DSH（DeepSeek Harness）AI 钱包插件——可拖动悬浮球实时显示当前使用模型的余额 / 配额，点击展开多供应商余额面板。

## 功能

### 悬浮球（Floating Ball）
- 固定悬浮于界面任意位置，**自由拖动**，位置自动记忆
- 球面实时显示**当前对话正在使用的模型**对应的余额 / 配额（从最近一次模型调用推断，每 60 秒自动刷新）
- 点击展开完整余额面板（Esc / 点击遮罩关闭）

### 余额面板
- 一屏查看所有已配置供应商的金额余额或配额余量
- 配额型供应商展示进度条 + 重置时间
- 手动刷新 + 错误 / 未配置 Key 的友好提示

### 8 套内置主题
液态玻璃（默认）/ 浅色玻璃 / 磷光绿 / 赛博青 / Dracula / Nord 冰蓝 / 琥珀 / 羊皮纸——面板底部一键切换，**主题与悬浮球位置持久化到服务端文件**（`~/.dsh/dsh-ai-wallet.prefs.json`），不随 DSH 端口变化丢失。

## 支持的供应商

| ID | 名称 | 类型 | 需要的 Key |
| --- | --- | --- | --- |
| `deepseek` | DeepSeek | 金额余额 | `DEEPSEEK_API_KEY` |
| `zhipu` | 智谱 GLM | 配额 | `ZP_API_KEY` / `ZHIPU_API_KEY` |
| `zai` | Z.ai (GLM 国际) | 配额 | `Z_AI_API_KEY` |
| `moonshot` | Moonshot Kimi | 金额余额 | `MOONSHOT_API_KEY` |
| `minimax` | MiniMax | 配额 | `MINIMAX_API_KEY` |
| `stepfun` | StepFun 阶跃星辰 | 金额余额 | `STEP_API_KEY` |
| `siliconflow` | SiliconFlow 硅基流动 | 金额余额 | `SILICONFLOW_API_KEY` |
| `openrouter` | OpenRouter | 金额余额 | `OPENROUTER_API_KEY` |
| `xai` | xAI / Grok | 金额余额 | `XAI_API_KEY` |

> 说明：
> - 供应商 API 以官方文档为准，字段可能随版本调整。
> - `xai` 使用社区维护的非官方 credits 端点（xAI 预付费 credits 无公开 API），若失效会显示错误。
> - 仅控制台查询、无公开余额 API 的供应商（通义千问、百川、Groq）暂不支持；OpenAI / Anthropic 普通 key 查不了用量，故未内置。

## 安装

```sh
dsh plugin --profile desktop add dsh-ai-wallet
```

重启 DSH 后生效。

## 配置（可选）

默认启用 `deepseek` + `zhipu`。在 profile 的 `cordis.patch.yml` 中覆盖：

```yaml
- id: dsh-ai-wallet
  config:
    providers:
      - deepseek
      - moonshot
      - zhipu
```

`providers` 数组顺序即面板展示顺序，支持全部供应商 ID 中的任意子集。

### 自定义供应商（customProviders）

不在内置白名单、或走私有端点的供应商，可通过 `config.customProviders` 声明式接入，无需改源码。支持 `quota` 与 `balance` 两种类型，鉴权支持 `bearer`（默认）与 `cookie`。

```yaml
- id: dsh-ai-wallet
  config:
    providers:
      - deepseek
      - my-gateway
    customProviders:
      - id: my-gateway
        name: 内部网关
        kind: quota            # quota | balance
        url: https://your-gateway.example.com/api/profile/quota
        auth: cookie           # cookie | bearer
        keyNames: [GATEWAY_COOKIE]
        fields:
          level: data.status
          limits:
            # 单条配额可省略 items；多条时写响应里数组的路径
            # items: data.plans
            label: 月度配额
            remaining: data.remainingCny
            total: data.limitCny
            percentage: data.utilizationPercent
            resetTime: data.period.resetsAt
```

字段说明：
- `id` / `name`：供应商标识与面板显示名。
- `kind`：`quota`（进度条 + 剩余/重置）或 `balance`（金额行）。
- `url`：余额/配额接口地址。
- `auth`：`cookie` 时把 `keyNames` 读到的值放进 `Cookie` 头；`bearer`（默认）放 `Authorization: Bearer <value>`。
- `keyNames`：读取凭据的环境变量名（`.env` / `~/.dsh/.credentials.yaml`），按顺序尝试。
- `fields.limits`：`quota` 响应的字段映射（均为到响应的点路径）。`label` 可为路径或常量文本；`items` 可选，指向响应里的数组以显示多条配额。
- `fields.rows`：`balance` 时的行映射，`[{ label, path, suffix? }]`。

## 开发

- `lib/index.js` — 服务端：`/ds-balance/v1` 余额聚合路由、`/ds-balance/v1/prefs` 偏好读写路由；`PROVIDERS` 注册表 + `collect()` 汇总；注入 `sessionQuery` 从 DSH 会话推断当前模型（`assistant/message` 事件 → `source.provider/model` → `PROVIDER_ALIASES` 映射）
- `lib/client.js` — 客户端：悬浮球 + 面板渲染、主题系统、拖拽；当前模型与映射由服务端于 `active.balanceProvider` 下发，客户端只渲染不推断

新增供应商：在 `lib/index.js` 的 `PROVIDERS` 中加一项 `{ name, kind, keyNames, fetch(key) }`，或按上文通过 `config.customProviders` 声明式接入；两种方式客户端都无需改动。

## 许可

MIT