dsh-codex-usage：DeepSeek Harness 的 Codex 配额与余额聚合插件

前言¶

DeepSeek Harness (DSH) 用户若将 Codex 作为子代理使用，需关注 ChatGPT Plus 的滚动配额（5h/7d/month）。本插件为 DSH host 插件，通过聚合接口将 Codex 配额与 DeepSeek 余额展示在同一 JSON 下，方便统一监控。

核心功能¶

• 读取 Codex 订阅配额 (5h/7d/month)
• 查询 DeepSeek 账户余额
• 提供回环-only 聚合接口 GET /api/dsh-usage/overview
• 通过 DSH 凭据服务管理 DeepSeek API Key

安装¶

依赖 DSH >= 0.1.1-rc.x 和 Node >= 22。安装命令如下：

dsh plugin --profile web add dsh-codex-usage

安装后，dsh web 会自动通过 cordis.patch.yml 注册插件。插件依赖的 @openai/codex@0.147.0 由 npm 自动安装，使用前需确保 Codex 侧已登录（执行 codex login status 检查）。

接口说明¶

插件提供回环-only 聚合接口 GET /api/dsh-usage/overview。

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

响应结构：
- ok: 是否成功
- updatedAt: 数据更新时间戳
- codex: Codex 配额信息
- configured: Codex 是否配置正确
- windows: 滚动窗口数组，包含 label (5h/7d/month)、usedPercent (已用百分比)、resetIn (重置倒计时)、resetsAt (重置时间戳)
- error: 错误信息
- deepseek: DeepSeek 余额信息
- balance: 包含 currency (币种)、total (总余额)、granted (赠金)、toppedUp (充值)
- links: 官方用量页链接

配置¶

可在 cordis.patch.yml 中添加 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                   # 超时时间 (默认 30s)

注意事项¶

• 仅接受回环地址请求 (127.x / ::1 / localhost)，外部请求一律 403。
• 仅支持 GET 请求，不接收请求体，不写入状态。
• 数据缓存时间为 5 分钟 (默认 refreshMs: 300000)。
• Codex 侧需已登录，否则 codex.configured 为 false。

与 Codex 子代理的关系¶

• 官方子代理（@deepseek-ai/dsh-subagent-codex）：负责把任务委派给 Codex 执行。
• 本插件：负责读取配额数据，不参与任务调度。

建议组合使用：先安装官方子代理干活，再安装本插件监控配额，避免额度刷爆。