dsh-codex-usage

dsh-codex-usage

English | 简体中文

一个为 DeepSeek Harness Web UI 打造的精致 OpenAI Codex 套餐用量指示器。

该插件保留标准的 Settings 齿轮图标和标签，同时在最右侧添加一个上下文计量器样式的圆环。圆环内含 OpenAI 标志，并会在鼠标悬停或键盘聚焦时打开详细的配额面板。

功能

• 原生风格的用量圆环，采用与对话上下文计量器相同的 28 px 几何尺寸和 DSH 设计令牌。
• 展示每个 Codex 限额分组的完整配额详情：滚动窗口、已用百分比、重置时间、套餐类型、credits、支出控制和重置 credits。
• 默认每五分钟轮询一次，可通过 bundle row 配置。
• 鼠标悬停时获取新鲜数据，并具有 250 ms 防抖、单个进行中的请求、共享的五分钟轮询缓存、较短的强制悬停缓存和失败节流。
• 保留最近一次成功数据作为回退，因此临时的提供商或网络故障不会清除有用数据。
• 浏览器中不存放凭据：OAuth 和凭据刷新仍在官方 Codex app-server 进程内完成。
• 仅限回环的 API 路由，以及会移除 email、IDs、tokens 和未知提供商字段的 allowlist normalizer。
• 支持 Windows、macOS 和 Linux 命令启动，包括 Windows npm PowerShell shims。

要求

• Node.js 20 或更新版本
• pnpm 10
• DeepSeek Harness 0.1.2-alpha.2 或兼容版本
• 具有稳定 app-server API 的较新 OpenAI Codex CLI（已使用 Codex CLI 0.149.0 测试）
• Codex 已使用 ChatGPT 套餐登录（运行 codex login）

从此 checkout 安装

构建软件包：

pnpm install
pnpm run check

从此目录将其添加到 DSH profile：

dsh plugin --profile web add .
dsh --profile web --dump-config
dsh web

开发期间，只有在运行 pnpm run dev 并重新构建插件输出时，Host 更改才会热重载。浏览器客户端更改需要重新构建，然后刷新现有 Web 页面。client bundle 由 DSH 的 client-module system 加载；既不需要也不应使用单独的 Vite server。

使用以下命令移除：

dsh plugin --profile web remove dsh-codex-usage

安装 packed artifact

tarball 已包含预构建的 Host 和 lazy-CJS client artifacts，从而避免安装时的构建批准：

pnpm pack
dsh plugin --profile web add ./dsh-codex-usage-0.1.8.tgz

对于 Git-host 安装，pnpm 10 要求 profile 允许此软件包的 prepare script。请固定一个 commit，并严格遵循 DSH/pnpm 输出的 allowBuilds 指令。

配置

全部四个字段都可在 Settings → Plugins → Codex usage 中使用。更改会先在本地暂存，直到执行 Save；它们通过 DSH Settings 持久化，保存的设置/profile patch 会实时生效，无需重启。profile row 仍作为已保存用户覆盖项之下的基础配置。

bundle 会插入以下 row：

- id: codex-usage
  name: dsh-codex-usage
  config:
    refreshIntervalMs: 300000
    hoverRefreshMinAgeMs: 30000
    requestTimeoutMs: 15000
    codexCommand: codex

如需更改 composition-layer base，请在 profile 的 cordis.patch.yml 中覆盖整个 row。后续 layers 会替换一个 row 的完整 config value；已保存的 Settings UI values 会覆盖该 base。

工作原理

1. Host plugin 注入 DSH 的 webServer service，并注册 GET /api/plugins/codex-usage。
2. 首次读取时，它会启动一个托管的 codex app-server --listen stdio:// process。
3. 它执行 initialize / initialized，然后调用稳定 methods account/rateLimits/read 和 account/read。
4. strict normalizer 仅向 loopback browser route 返回配额数据。
5. browser 在 sidebar.footer.action 中注册一个独立 action，在 Settings row 的右边缘预留空间，并保持内置 Settings button 及其行为不变。
6. browser 按配置的 cadence 进行轮询，并在 250 ms 悬停防抖后请求一次合并刷新。

client artifact 并非普通的 browser ESM。tsdown.config.ts 会生成 DSH 所需的 lazy-CJS registration。React 和 DSH UI packages 保持 external，并通过 DSH 的 client module table 解析，从而防止重复的 React runtimes。

安全与隐私

• 插件绝不会读取 ~/.codex/auth.json，也绝不会直接处理 OAuth tokens。
• Codex 负责 credential storage、keyring support、token refresh 和 account selection。
• Web route 仅接受来自 loopback clients 的 GET，并拒绝跨站 Origin、Referer 和 Fetch Metadata signals。
• 响应会省略 email、account/workspace IDs、user IDs、access tokens、refresh tokens、raw provider payloads 和 unknown fields。
• 错误状态仅保留 normalized last-good snapshot。
• provider route 不可配置，从而避免形成任意 authenticated proxy。

开发

pnpm run typecheck
pnpm run test
pnpm run build
pnpm run pack:check

default suite 会跳过 live provider test。当 Codex 已安装并登录时运行该测试：

$env:CODEX_LIVE = '1'
pnpm exec vitest run tests/codex-live.spec.ts

参考资料

• DSH：创建第一个插件
• DSH：打包和安装
• DSH：添加 settings card
• DSH：Client modules
• Codex app-server 文档
• Codex rate-limit response
• Codex snapshot type

许可证

MIT