前言¶
在 DeepSeek Harness（DSH）里接多条模型路由时，开发者常常要一边对话一边确认：这次请求走的是哪条线路、账户或 API Key 还剩多少、自建或中转有没有超出预期。官方 Host 负责路由与凭证，但界面上并不总能一眼看到「当前会话」对应的订阅状态。社区插件 dsh-subscription-balance（维护者 yanboyang97，SkillHub 分类为模型推理）针对这一问题：在 Web UI 中汇总当前对话所用来源的余额或配额，并对 Host 已检测到的每个 provider 提供本地用量；在配置了价目表时还可做费用估算。下文按安装、界面入口与数据口径说明用法。
这是什么¶
dsh-subscription-balance 是面向 DSH Web 界面的社区插件（README 明确标注 Unofficial，与 DeepSeek、Moonshot AI、OpenAI 无隶属或背书关系）。当前 package 版本为 1.6.0，许可证 MIT。它依赖带 Web UI 的 DeepSeek Harness，版本范围在 engines.dsh 中声明为 >=0.2.2-rc.1 <0.3.0，超出范围时 DSH 会拒绝安装或启动该插件。
同一套 Host 快照驱动三处展示：
- Sidebar chip：当前对话所用来源（或可固定的来源）。
- Composer pill：当前屏幕上会话的作用域读数；点击打开详情面板。
- Settings → Subscription balance：全部来源、显示模式、检测到的 provider 目录及数据口径说明。
打开设置页：侧栏底部的齿轮（或应用内 Settings 快捷方式）→ 左侧导航选择 Subscription balance（紧挨 General 之后，带钱包图标）。这是独立设置分区，不是 Settings → Plugins 下的子页。
核心功能¶
各来源展示什么¶
- Kimi Code（Coding Plan）：展示 provider 返回的各个配额窗口（如 5 小时、周、月总量、月 code 等及新增 key），含已用比例与重置时间；数据来自官方接口读数，不做估算。
- DeepSeek 付费 API：账户钱包与 API Key 余额分开展示（充值与赠送额度拆分）；账户路由与 API Key 路由不混用。
- OpenAI：标准
OPENAI_API_KEY无法读取余额或组织费用。插件仍会识别该 provider、统计本地 token 用量，并链到 OpenAI usage/costs 页面。对官方直连 OpenAI，内置公开标准档价目（含短/长上下文档），便于本地估算。若配置了OPENAI_ADMIN_KEY，则调用组织费用 API 显示当日组织成本；未配置时卡片内提供 Configure key 入口及创建组织 admin key 的链接，页面不会用推理 Key 去做该读数。 - 其他 provider：由 Host LLM 注册表自动发现；无 balance 适配器时显示「no balance adapter yet」，不借用其他 provider 的余额，仅统计本地 usage（请求数、token、按模型拆分）。在
pricing.<routeId>或pricing.<family>有配置时可做本地费用估算。 - 本地估算：有价目表的 API provider 可做本地估算；DeepSeek 自带官方 CNY 峰谷价表，OpenAI 官方直连自带公开 USD 标准价。无价目时只显示 token，不虚构金额。估算处处标注 Estimate，不等同于账单。
插件不向页面返回凭证明文，也不把 Key 写入插件配置；与 Settings → Models 一样，经 Host 凭证库只写保存。对只回报比例的配额接口，不会伪造绝对 token 数。
任意 provider（含手动添加的路由）¶
列表每次刷新都从 Host 读取，而非硬编码表：
llm.listProviders()列出可服务请求的路由。llm.listModels(route)列出各路由模型，在 Settings 里新增的模型无需改插件即可出现。llm-pi-ai设置文档提供通过 Add model provider 创建的路由的显示名、endpoint 与模型列表。
路由分类依据 route id、settings namespace 或 endpoint 主机（如 api.deepseek.com、api.kimi.com、api.openai.com），显示名仅是兜底，避免把名为 my-openai-proxy 的中继误当作 OpenAI 查询或计价。Settings 中增删改 provider 后，Host 的 llm/adapters-updated、llm/models-updated、settings/document-updated 会刷新目录。
跟随当前对话与固定来源¶
默认模式 Follow current conversation：Composer pill 根据 Session 的 modelSelection 显示对应来源；侧栏 chip 同步。切换 Composer 中的模型时，pill、chip 与「Current conversation」卡片会更新。在面板或 Settings 的 Display 中可固定某一来源（如 Kimi Code、DeepSeek 账户等）；固定后换对话不变。该固定偏好是插件写入浏览器存储的唯一值。
刷新策略¶
侧栏 chip 或 Composer pill 打开详情后可 Refresh now；Settings → Subscription balance → Refresh；Settings → Price table → Check for updates 仅重读价目来源，不丢弃已缓存余额。页面每 15 秒轮询 Host 缓存；Host 默认 refreshSeconds 为 60，仅在数据陈旧时重查。刷新失败保留上次成功读数并标为陈旧，不会用零覆盖确切数字。
数据来源一览¶
| 来源 | 端点 / 服务 | 精确度 |
|---|---|---|
| Kimi Code | GET https://api.kimi.com/coding/v1/usages（KIMI_CODING_API_KEY） |
Provider 上报配额 |
| DeepSeek 账户 | Host ctx.deepseekAccount.getBalance |
官方余额 |
| DeepSeek API Key | GET https://api.deepseek.com/user/balance |
官方余额 |
| OpenAI 组织 | GET https://api.openai.com/v1/organization/costs（OPENAI_ADMIN_KEY） |
官方组织费用 |
| OpenAI 本地 | 本 profile 的 assistant/message 会话事件 |
本地 token，非余额 |
| 其他路由 | Host LLM 注册表 + llm-pi-ai 文档 |
仅本地 token；有 pricing.<routeId> 时可估价 |
| 本地估算 | 会话用量 × pricing 表 |
估算，非账单 |
Kimi 用量接口为未公开文档 API；插件泛化解析 usages.*，并在新旧字段不一致时告警。本地估算不包含其他客户端、直连 API、Search/Fetch 费用、无最终 usage 的中止请求等。
安装与启用¶
环境须满足上述 DSH 版本且启用 Web UI。插件以后台 Host 进程权限运行 provider 调用与凭证写入；安装前建议自行审阅 GitHub 仓库 源码与 MIT 许可证。
从 npm 安装¶
dsh plugin add dsh-subscription-balance
安装后需重启 DSH（仅刷新 Web 页面不够），再打开 Settings → Subscription balance。
从插件市场索引安装¶
在 Plugins → Discover → Add index source 添加：
https://raw.githubusercontent.com/yanboyang97/dsh-subscription-balance/main/market/index.json
再从卡片安装；市场会在兼容性检查后安装 dsh-subscription-balance@<version>。
本地目录或 tarball¶
本地 checkout（路径按你本机仓库位置调整）：
dsh plugin add ./subscription-balance
自 tarball（示例版本与 pack 产物名以你实际为准）：
npm pack
dsh plugin add ./dsh-subscription-balance-1.6.0.tgz
典型用法¶
- 完成安装并重启 Host 后，用侧栏齿轮进入 Settings → Subscription balance，确认检测到的 provider 目录与当前凭证状态（仅显示是否已配置，不显示 Key 值）。
- 日常对话中观察 Composer pill 与 Sidebar chip：默认跟随当前会话模型；需要盯某一账户时，在 Display 中固定来源。
- 需要最新余额或配额时，在 chip、pill 详情或 Settings 页点击 Refresh；价目更新用 Price table → Check for updates。
- OpenAI 组织费用：在 OpenAI 卡片按提示配置
OPENAI_ADMIN_KEY（经POST /dsh-subscription-balance/credentials.json写入 Host 凭证库）；缺 Key 时使用本地用量与公开价表估算。 - 自建或中转路由：在 Settings → Models → Add model provider 添加后，插件自动列入目录；若无 balance 适配器，查看 token 用量，必要时在
pricing中补充该routeId的价目以启用本地估算。
适用场景与注意¶
适合：在 DSH Web 中同时使用 DeepSeek、Kimi Code、OpenAI 及多条自定义路由，希望在对话界面直接看到余额/配额或本地用量与估价的开发者与智能体搭建者。
注意：
- 社区目录 SkillHub 与 DeepSeek / 幻方无官方从属；插件同样为社区作品。
- Provider 调用仅在 Host 侧发起，凭证不出 Host；但仍会以本机 DSH 配置中的 Key 访问第三方 API，请遵循各平台服务条款（README 对 Kimi 未公开 API 等有专门说明）。
- Kimi、OpenAI 组织费用等端点可能变更；失败时界面展示错误并保留上次成功读数。
- 本地估算依赖价表版本与
PRICE_VERSION等数据，调价后需更新插件、pricingSource或手动pricing覆盖。
结尾¶
dsh-subscription-balance 把「当前对话用哪条订阅」和「Host 里还有哪些线路、用了多少」收到同一套 UI：能查官方余额的 provider 走真实接口，其余走本地用量与可选估价，并避免把凭证或估算冒充账单。进一步了解可访问目录页 yanboyang97/dsh-subscription-balance 与仓库 github.com/yanboyang97/dsh-subscription-balance。
