dsh-sophnet-balance

Readme

# dsh-sophnet-balance

SophNet 余额查询插件（DeepSeek Harness Web GUI / dsh web）。

- 输入框右侧显示一个「呼吸灯」小圆点，实时反映 SophNet 余额状态（绿色 = 正常，黄色 = 偏低，红色 = 低于提醒阈值 / 无余额）。
- 点击圆点展开液态玻璃面板：**余额展示在面板右上角**（总余额 + 状态徽标），下方一排小字显示
  充值/赠送/信用额度/当前欠款/提醒阈值明细；**面板主体是用量明细**（日期范围 + Token/请求/费用汇总卡 +
  按服务与按日期的 Token 明细），余额与用量合并为单面板，无标签页切换。
- **仅在使用 sophnet 提供商时才启用**：插件通过宿主端 `agentDefaultModel.currentSelection()` 检测当前提供商，
  提供商名匹配 `sophnet`（含 `modlens-sophnet` 等包装名）时控件才显示；切换走其他提供商后控件自动隐藏。
- **使用 sophnet 时禁用 opencodego 查询插件**：同一输入框内 `dsh-opencodego-usage` 的呼吸灯会被隐藏
  （客户端注入 `.ocgr-root { display: none !important }` 样式随 sophnet 启用状态开关）；
  切走 sophnet 后 opencodego 呼吸灯恢复。未安装 opencodego 插件时此规则无副作用。

## API

官方文档：

| 项 | 值 |
|---|---|
| 地址 | `GET https://www.sophnet.com/api/open-apis/projects/balance` |
| Header | `Authorization: Bearer <APIKEY>` |
| 响应 | `{ status, message, result: { currentBalance, currentBalanceWithoutGift, currentGiftBalance, balanceThreshold } }` |

`status = 0`（或 `200`）视为成功；`result.currentBalance` 为总余额（含赠送），
`currentBalanceWithoutGift` 为充值余额，`currentGiftBalance` 为赠送余额，
`balanceThreshold` 为余额提醒阈值。

## 用量查询（Token 用量）

| 项 | 值 |
|---|---|
| 地址 | `GET https://www.sophnet.com/api/open-apis/projects/usage_detail?beginTime=yyyy-MM-dd&endTime=yyyy-MM-dd` |
| Header | `Authorization: Bearer <APIKEY>` |
| 文档响应 | `{ status, message, result: { service, dates, invokeDetails, invokeSummary, costDetails, costSummary, tokenDetails, tokenSummary, latency50Details, latency90Details, latency99Details } }` |

面板主体为「用量」视图：**Token 总用量 / 总请求数 / 总费用** 三张汇总卡、
按服务的 Token（附比例条）、请求数、费用、P90 延迟明细，以及按日期的 Token 汇总；
余额（含状态徽标与明细条）固定在面板顶部右侧。
默认查询近 30 天（含今天），可在面板内选择起止日期。

### 实测返回结构（2026-08，与文档有出入，已兼容）

- 服务列表字段名是 **`result.services`（复数）**，文档写的是 `service`（单数）；已两者兼容。
- 服务对象字段为 `logicResourceId / logicResourceName / logicResourceUUID / displayServiceName`；
  `displayServiceName` 可能为空字符串——展示名按
  `displayServiceName > serviceName > logicResourceName > name > service > 短UUID` 解析。
- 各 Details 是 **与 `result.dates` 对齐的按日数组**：`details[服务键] = [d0, d1, …]`，
  下标 i 对应 `dates[i]`；服务键可能是空字符串（无展示名的服务）。`bucketDetails` 统一按
  「路径上的日期 key 归入按日期、服务 key 归入按服务」递归聚合，对
  按服务 / 按日期 / 对齐数组三种结构都兼容。

### 为什么可能查到全 0

- 用量统计存在延迟，且**默认窗口（近 30 天）里如果确实没有调用就会全 0**——
  例如本账户在 48 天里只有一次调用（2026-08-07，费用 ¥9.9），选 8 月 11 日之后就开始会全空。
- 余额接口额外返回了 `creditLimit / currentDebt / securityDeposit / creditLimitLocked`
  （文档未列出）；当 `currentBalanceWithoutGift` 与 `currentGiftBalance` 都是 0 时，
  余额全部来自信用额度（`余额 = 信用额度 − 当前欠款`）。插件会显示「信用额度 / 当前欠款」行。

## 安装

DSH 以「profile + bundle」方式加载插件：把插件装成 profile 依赖后，`dsh plugin`
会自动把声明了 `dsh.bundle` 的包追加进 `dsh.profile.bundles` 层列表。
安装完成后**重启 `dsh web`**（新增客户端模块需要重启才进入浏览器清单）。

### 方式一：从 GitHub 安装（推荐）

仓库：`github.com/caijiachen34/dsh-sophnet-balance`

```sh
# 方式 A：GitHub 依赖速写（公开仓库，走 HTTPS）
dsh plugin --profile web add github:caijiachen34/dsh-sophnet-balance

# 方式 B：SSH 安装（私有仓库或有 SSH key 认证）
dsh plugin --profile web add git+ssh://git@github.com/caijiachen34/dsh-sophnet-balance.git
```

如果 `github.com:22` 被墙/不可达，可改走 GitHub 的 443 端口 SSH：

```sh
dsh plugin --profile web add git+ssh://git@ssh.github.com:443/caijiachen34/dsh-sophnet-balance.git
```

> 若 pnpm 提示 `allowBuilds`（git 依赖的 prepare 脚本默认被拦截），按它的提示把
> `dsh-sophnet-balance` 加到 profile 的 `pnpm-workspace.yaml` 的 `allowBuilds` 里再重跑；
> 本插件没有 prepare 脚本，一般不会触发。

### 方式二：本地源码安装（开发调试）

```sh
# 在本仓库（插件源码目录）外任意目录执行：
dsh plugin --profile web add file:/绝对/路径/dsh-sophnet-balance
```

用 `link:` 代替 `file:` 可以保持符号链接，改源码后无需重装（刷新页面/重启即生效）。

## 配置 API Key

Key 解析顺序：

1. 面板内手动输入（会写入 `~/.dsh/.sophnet-state.json` 缓存）；
2. DSH 凭据：读取 `llm-pi-ai.providers.sophnet.apiKeyEnv` 指定的环境变量名（默认 `SOPHNET_API_KEY`），
   经 `credentials.resolve()` 解析（与 DSH 的 LLM 提供商共用同一份凭据）；
3. 进程环境变量；
4. 状态文件缓存。

即：只要你在 DSH 里能正常用 sophnet 模型（配好了 `SOPHNET_API_KEY`），插件无需额外配置。

## 宿主端路由

| 路由 | 说明 |
|---|---|
| `GET /sophnet-balance/status` | 状态探测（不发外部请求）：`{ enabled, provider, model, configured, envName }`，客户端每 20s 轮询 |
| `GET /sophnet-balance[?key=...]` | 查询余额：`{ ok, balance: { currentBalance, ... }, raw, provider }`；提供商非 sophnet 时返回 `{ ok: false, disabled: true }` |
| `GET /sophnet-usage[?begin=yyyy-MM-dd&end=yyyy-MM-dd&key=...]` | 查询用量：`{ ok, usage: { range, services, dates, summary: { tokens, cost, invokes }, byService: { tokens, cost, invokes, latency50/90/99 }, byDate: { tokens, ... } }, raw }`；日期参数兼容 `begin`/`end` 与 `beginTime`/`endTime`，缺省近 7 天 |

## 开发

- `index.js` — 宿主半端（Node），注册同源路由。
- `client.js` — 浏览器半端，`window.__ModuleLoader__.load(...)` 形态，随 `/plugins/dsh-sophnet-balance/client.js` 提供；修改客户端注册后需重启 `dsh web` 以刷新模块清单。
- 修改 `package.json` / `cordis.patch.yml` 后需要重启 `dsh web`。

## License

MIT