SophNet 余额监控 caijiachen34/dsh-sophnet-balance

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

方式 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：

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 脚本，一般不会触发。

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

在本仓库（插件源码目录）外任意目录执行：
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