scientisbo/dsh-codex-usage

dsh-codex-usage ·「Codex 用量」

Codex 订阅配额 + DeepSeek 余额聚合，一键并入 DeepSeek Harness 的用量面板。

一个 DeepSeek Harness (DSH) host 插件：只读、回环、带缓存的聚合接口
GET /api/dsh-usage/overview，把 Codex (ChatGPT 订阅) 的滚动配额窗口
和 DeepSeek 账户余额 收进同一个 JSON 里，供 UI 插件渲染。

Codex Usage — 一个 DeepSeek Harness host 插件，将你的 Codex
(ChatGPT) 订阅配额窗口和 DeepSeek 账户余额聚合到一个
仅限回环的 API 端点中。

这个插件是干什么的？

如果你在用 DeepSeek Harness + Codex 子代理（把日常工作委派给 Codex），
最怕的就是订阅额度不知不觉刷爆——Plus 账号是按 5 小时 / 7 天 / 每月
滚动窗口限流的。这个插件：

- 📊 查 Codex 订阅配额：通过锁定版 @openai/codex@0.147.0 的
app-server 协议读取 account/read + account/rateLimits/read，
得到 5h / 7d / month 三个滚动窗口的 已用百分比 + 重置倒计时；
- 💰 查 DeepSeek 余额：官方 api.deepseek.com/user/balance
（总余额 / 赠金 / 充值分列，自动按有余额的 USD 优先选币种）；
- 🔗 给 UI 一个聚合端点：一个 JSON、5 分钟缓存、?refresh=1 强制穿透，
前端只管渲染，不用碰任何密钥。

💡 有 ChatGPT Plus 账号？把它物尽其用。
配合 DSH 的 Codex 子代理（dsh-subagent-codex），日常写码、查资料、
跑测试都能交给 Codex 分担 DeepSeek 的 token 压力；本插件 + 配套的
DeepSeek 用量面板 就是你的“仪表盘”——
一边干活，一边盯着配额不超限。

安装（需要 DSH ≥ 0.1.1-rc.x、Node ≥ 22）

从本地目录安装（开发中）
dsh plugin --profile web add "file:/绝对路径/dsh-codex-usage"
或发布到 npm 后：
dsh plugin --profile web add dsh-codex-usage

安装后 dsh web 会自动通过 cordis.patch.yml 注册插件；浏览器里不必刷新服务端
以外的任何东西（UI 面板请看配套插件）。插件依赖的 @openai/codex@0.147.0
由 npm 自动安装，Codex 侧需已登录（codex login status 显示
Logged in using ChatGPT）。

接口

GET /api/dsh-usage/overview

| 查询参数 | 说明 |
| --- | --- |
| 无 | 命中 5 分钟内存缓存 |
| ?refresh=1 | 强制穿透缓存，刷新数据 |

响应示例：

{
"ok": true,
"updatedAt": 1787492831169,
"codex": {
"configured": true,
"windows": [
{ "label": "5h",    "usedPercent": 42.5, "resetIn": "3h20m", "resetsAt": 1787492831169 },
{ "label": "7d",    "usedPercent": 18.2, "resetIn": "5d",    "resetsAt": null },
{ "label": "month", "usedPercent": 61.0, "resetIn": "12d",   "resetsAt": null }
],
"error": null
},
"deepseek": { "balance": { "currency": "USD", "total": 12.66, "granted": 0, "toppedUp": 12.66 } },
"links": {
"codexUsage":    "https://codex.app/account/usage",
"deepseekUsage": "https://platform.deepseek.com/usage"
}
}

- window.label：5h / 7d / month 英文短标签，多语言由 UI 层翻译；
usedPercent 0–100；resetIn 给人读的倒计时，resetsAt 时间戳（无则 null）。
- Codex 未登录 / 网络异常时返回 codex.configured: false + 友好错误文本，不抛 500；
余额失败不影响 Codex 数据。

安全设计

- 回环-only：仅接受本机回环地址 + Host 头校验（127.x / ::1 / localhost），
外部请求一律 403；
- 只读 GET：不接收请求体、不写任何状态，仅两个只读上游调用；
- 密钥不出 DSH：DeepSeek 的 API Key 通过 DSH 的 credentials 服务解析
（~/.dsh/.credentials.yaml 的 DEEPSEEK_API_KEY ref 或同名环境变量），
不落盘、不写日志；Codex 配额走本机已登录的 ~/.codex，也不需要密钥。

可选配置

cordis.patch.yml 的 insert 条目加 config：

- insert:
- id: codex-usage
name: dsh-codex-usage
config:
apiKeyRef: DEEPSEEK_API_KEY        # 余额接口 API Key ref（默认）
codexUsageUrl: https://codex.app/account/usage     # 官方用量页链接（默认）
deepseekUsageUrl: https://platform.deepseek.com/usage
refreshMs: 300000                  # 缓存 TTL（默认 5 分钟）
timeoutMs: 30000                   # Codex app-server / 上游超时（默认 30s）

与 Codex 子代理的关系（别搞混）

- "用 Codex 干活"（把任务委派出去 / 发布 subagent）：这是官方插件
@deepseek-ai/dsh-subagent-codex 的事——一条命令装上：
dsh plugin --profile web add @deepseek-ai/dsh-subagent-codex，
之后 DSH 里出现 subagent_codex 工具，由它把任务交给 Codex 执行
（需 ChatGPT 账号先 codex login）。该插件由 deepseek-ai 官方维护，
不随本仓库分发；
- "看 Codex 用了多少"（本插件）：只通过 app-server 的 account/read +
account/rateLimits/read 读配额，不发布任何任务、不参与调用；
- 组合玩法：如果你想用 ChatGPT Plus 账号分担日常工作，先装官方子代理去
干活，再用本插件盯着配额——5h / 7d 滚动窗口用了多少、多久重置，
一目了然，不会刷爆限流。

搭配 DeepSeek 用量面板

数据是拿来看得舒服的。配套客户端插件
dsh-deepseek-usage：
一个简洁美观的浮动面板——侧边栏底部入口、余额徽标、今日/本月 token
与花费、Top 模型、每日热力图，并自带「Codex 订阅」区块消费本插件这个
/api/dsh-usage/overview 接口（缺端时静默隐藏）。

- 本插件提供数据（Codex 配额 + DeepSeek 余额）；
- 面板负责展示（界面、刷新按钮、5 分钟自动轮询）。

两者独立安装、独立更新，用同一个数据契约串联。

接口契约 / 致谢

account/rateLimits/read 等 app-server 方法为 Codex 插件协议；聚合口径参考
CodexBar、
DeepSeek 余额结构参考官方 /user/balance 文档。
DSH 插件骨架与回环护栏借鉴
@ychris12138/dsh-usage-stats（MIT）。

License

MIT