gejiaju/dsh-balance

dsh-balance

DeepSeek Harness（DSH）插件：显示 DeepSeek API 余额，并判断当前是否为高峰时段。

English

功能

在设置页新增「余额与高峰」卡片：

• 余额 — 从官方 GET /user/balance 接口拉取账户余额（总额 / 赠金 / 充值，按币种展示）。
• 高峰时段 — 判断当前处于高峰还是**空闲（低谷）**计价时段，实时倒计时到下次切换，并展示后续切换时刻表。

默认策略与 DeepSeek 现行官方定价一致：

时区、高峰窗口、周末规则全部可配置——将来政策再变，改配置即可，无需发版。

安装

dsh plugin --profile web add dsh-balance

重启 dsh web（或桌面应用）后，打开「设置 → 余额与高峰」。普通 profile 无需配置 API Key：插件自动复用 Harness 凭据服务里保存的 DeepSeek 密钥（即「模型」页面填写的那一个），或回退到环境变量 DEEPSEEK_API_KEY。

需要 dsh web ≥ 0.1.0-rc.6（设置分区基础能力）。更老的主机上卡片不会出现，其余功能不受影响。

配置

所有字段均可选，默认值如上。可在「设置 → 插件 → 插件配置」页面修改，或写入 cordis.patch.yml：

- id: dsh-balance
  name: dsh-balance
  config:
    # apiKey: ""                      # 显式指定密钥；否则自动用凭据/环境变量
    # baseUrl: https://api.deepseek.com
    # timezone: Asia/Shanghai         # 窗口所在的 IANA 时区
    # refreshSeconds: 300             # 余额缓存 TTL（最小 10）
    # weekendOffPeak: true            # 周末全天按低谷价
    # peakWindows: [[9,12],[14,18]]   # [起始时,结束时] 或 [时,分,时,分]
    # offpeakRatio: 0.5               # 仅展示用：低谷价/高峰价

「插件配置」页暴露 timezone、weekendOffPeak、refreshSeconds、peakWindows 四个字段。apiKey 刻意留在插件配置里：密钥更合适的归属是 Harness 自身的凭据管理，而且那里配置的密钥会被自动使用。

HTTP 接口

仅同源访问。响应中永不出现 API Key，只有 sk-…abcd 形式的脱敏提示。

设计与优化

• 零运行时依赖、零构建步骤：只用 Node 内置能力（fetch、Intl、node:test）；客户端 bundle 是纯 JS 的 __ModuleLoader__ 工厂，安装即用、无需编译。
• 时区感知的高峰计算（纯 JS）：通过 Intl.DateTimeFormat 在指定 IANA 时区读取本地时间与星期，与宿主机时区无关，不引入时区数据库依赖。
• 余额缓存 + 单飞请求：TTL 缓存（默认 5 分钟），并发请求合并为一次；刷新失败时保留上次成功值（标记为过期展示），不会让卡片变空白。
• 无后台轮询：客户端按服务端缓存 TTL 轮询（最少 30s）并在本地走秒倒计时；服务端只在被访问时才请求余额接口。客户端每 30s 拉一次状态（服务端已缓存），倒计时在本地每秒走；服务端只在被访问时才请求余额接口。
• 默认安全：密钥不出现在日志、响应与错误信息中；错误分类明确（NO_KEY、INVALID_KEY、RATE_LIMITED、TIMEOUT、NETWORK、BAD_SHAPE）。
• 优雅降级：缺少 webServer / settings / credentials / schemastery 时，对应部分静默跳过，其余功能照常工作。

安全

密钥处理方式见 SECURITY.md（不落日志、不出现在响应中、只以脱敏形式展示）。可直接复制的配置示例见 examples/cordis.patch.yml。

测试

npm test          # 或 node --test
npm run check     # 全量语法检查 + 跑测试

共 41 个用例：高峰窗口边界（窗口起止、周末、时区无关性、自定义窗口）、余额客户端（错误分类、缓存、单飞、失败保留旧值）、以及基于桩宿主的路由端到端测试。

仓库结构

lib/index.js      cordis 插件入口（apply、配置装配）
lib/peak.js       纯函数：高峰/低谷判断 + 下次切换时刻（时区感知）
lib/balance.js    DeepSeek 余额客户端（TTL 缓存、单飞）
lib/keys.js       API Key 解析：配置 → 凭据 → 环境变量
lib/routes.js     HTTP 路由 + 状态组装
lib/settings.js   可选 settings 命名空间（GUI 配置字段）
lib/config.js     默认值、校验、包版本
client/client.js  设置分区 UI（纯 JS、免构建）
test/             node:test 单元 + 集成测试

License

MIT