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