用量统计与 OAuth 网关 lninghaha/dsh-hub-oauth-gateway

dsh-hub-oauth-gateway

v1.13.4 · 原名 dsh-usage-stats

面向 DeepSeek Harness Web 的本地优先用量中心。 Token、估算成本、账户余额、订阅配额、趋势、预测、提醒与导出——外加编码订阅 OAuth（Grok Build、Codex、Kimi Code、Claude Code）、可选回环 API 网关，以及可选的本机认证/用量监控。不要把 token 粘贴进聊天。

CI
License
Contributions welcome

English · 中文版 · 日本語 · 한국어 · Português (BR) · Español · Français · Deutsch · Русский

升级： 按 docs/01-install.md 的版本化步骤操作。Hub 1.13.4 与 Subscription 0.8.5 共用已验证的 DSH 0.1.1-rc.2 契约，并精确固定 dsh-coding-oauth-core@0.1.2 与 undici@7.29.0。保留 profile、配置和凭据文件，在同一个 Web profile 中更新两个插件，再重启一次现有 DSH Web 进程。Core 仍是共享 npm 依赖，不是需要单独安装的 DSH 插件。已发布的 dsh-coding-oauth-core@0.1.2（含 helper 与 subpath exports）从 npm 消费；Hub 仍保留 vendor/dsh-coding-oauth-core 作为后续发版源。

项目更名

最初发布名为 dsh-usage-stats。自 1.1.0 起包名与仓库为 dsh-hub-oauth-gateway。请先移除旧 entry 再重新安装。本地数据文件与内部 Cordis 插件 id 不变，历史统计得以保留。

| | 请用这个 | 仍然可用 / 不变 |
| npm（推荐） | dsh plugin --profile web add dsh-hub-oauth-gateway | 旧 npm 包名不再更新 |
| GitHub / 开发 | dsh-hub-oauth-gateway | — |
| Cordis 插件 id | usage-stats | 不变 |
| SQLite 数据库 | ${DSH_HOME}/storages/usage-stats-v1.sqlite | 不变 |
| CLI | dsh-hub-oauth | dsh-hub-grok-build（别名）。Subscription 拥有的 dsh-coding-oauth / dsh-grok-build 不属于本包 |

版本历史见 CHANGELOG.md。

特性

- Quick Peek + Full Dashboard —— 悬浮小窗（或侧栏按钮）；概览 / 趋势 / 账户 / 明细 / 本机页签；today / 7d / 30d / month；上一周期对比；手动刷新。
- 分栏设置 —— Settings → 用量中心：显示 / 订阅账号 / 网关 / 能力 / 供应商 / 费用。
- 预设与模块编排 —— Minimal、Quota、Cost、Analyst；自定义模块顺序；密度、动效、供应商别名与颜色。
- 活动热力图 —— 配置时区下 370 天日历 + streak。
- 本地历史 —— 按 (session, turn, step) 投影到 SQLite；后写覆盖，不累计放大。
- 成本估算 —— 用户维护的每百万 Token 价格与覆盖率；缺失价格绝不当作免费。
- 订阅费用账本 —— 本地订阅/充值；货币一致时可显示回本倍数。
- 趋势与预测 —— 小时/日/周/月桶；有界线性外推为独立序列。
- 账户与配额适配器 —— 余额、窗口、重置时间、陈旧/上次成功、软提醒（无硬阻断、不外发通知）。
- CSV / JSON 导出 —— 过滤、日序列或打包；可选会话脱敏；电子表格公式注入防护。
- 编码订阅 OAuth —— Grok Build、Codex、Kimi Code、Claude Code（设备码 / 浏览器 / PKCE 粘贴）；配置 oauthDevice.copilotClientId 后可选 GitHub Copilot LLM 路由；多账号存储（最多 8）与可选 codingOAuth.pool（off | priority | quota_aware）；Claude Code 导入走 Import Claude Code（macOS Keychain Claude Code-credentials 或文件回退；preview → commit；覆盖仍需确认）；模型标注 (OAuth)；单向 CLI 凭据拉取。
- 可选回环 API 网关 —— 默认关闭的 OpenAI/Anthropic 兼容服务，仅供本机工具。
- OpenCode Go — 在账户与模型下以独立供应商 coding-opencode-go 连接（与 DSH 原生 opencode-go 隔离）。外部工具使用 coding-opencode-go/（过渡期仍接受 opencode-go/）与对应协议，并发送稳定会话标识。本地网关密钥与上游凭据分开；缺少会话标识会明确失败。若旧版插件配置仍在原生槽，可在账户卡片迁移。
- 可选能力 —— Codex 搜索 / 图像 / 用量 / Fast 与 Grok Imagine 默认关闭，打开后立即生效。
- 可选本机监控 —— 只读 CLI 认证快照与跨工具 Token 扫描（从不读取对话内容）。
- 可选供应商状态页探测 —— 白名单公开 Statuspage GET（默认关；无凭据；与用量主路径隔离）。
- 中英文界面 —— 复用 DSH locale 服务。

产品调研：docs/research/usage-analytics-landscape.md。架构：docs/02-architecture.md。

产品截图

在 DeepSeek Harness Web 安装本插件后截取（全新隔离 profile 下本地历史为空属正常）。

悬浮 HUD —— 今日指标与多账户配额芯片

用量速览 —— 紧凑 2×2 KPI，一键进入完整仪表盘

完整仪表盘 —— 时间范围、页签、刷新与 CSV / JSON 导出

设置 → 用量中心 —— 显示 / 订阅账号 / 网关 / 能力 / 供应商 / 费用

本插件解决的问题

| 你搜到 / 看到的 | 实际坏在哪 | 本插件怎么处理 |
| 用量 / 成本 / 配额散落在各 CLI 与供应商 | 没有统一的本地历史与带覆盖率的成本视图 | SQLite 投影 + 价格规则 + 账户适配器，集中在用量中心 |
| 想在 DSH 用 SuperGrok / ChatGPT Plus / Kimi Code / Claude Pro，又不想再买 API | 内置路由多为按量 API-key | 本地 OAuth 路由与现有 API-key 供应商共存 |
| 本轮运行失败 API key is invalid / AUTH | GUI 把所有 AUTH 都显示成这句；OAuth access token 会过期 | 编码 OAuth 路由主动刷新并对 AUTH 重试 |
| 想用 OpenAI/Anthropic 兼容工具对接订阅会话 | 没有安全的本机桥 | 可选回环网关（不是公网中继） |
| OpenCode Go: MissingSessionID | Missing stable conversation ID | DSH: use Accounts & Models; external tools: provide x-opencode-session. See migration. |
| 想要 Token Monitor 风格的 CLI 状态，又不想贴密钥 | 手工翻文件或粘贴到聊天 | 可选 localMonitor / localUsage，硬化白名单路径 |

快速开始

1. 安装当前 npm 发布版到 web profile
dsh plugin --profile web add dsh-hub-oauth-gateway

2. 自行选择时机重启常驻 DSH Web 进程官方 dsh web 是启动 web profile 的 CLI 别名，不是服务单元名。
请使用这台机器实际配置的进程管理器重启现有进程。

然后打开 设置 → 用量中心。订阅账号 / 网关 / 能力按需登录或打开开关。完整安装选项（npx 安装器、GitHub tarball、代理）见 docs/01-install.md。

目录

- 项目更名
- 特性
- 产品截图
- 本插件解决的问题
- 快速开始
- 要求
- 安装
- 使用
- 设置页
- 编码 OAuth
- 本地 API 网关
- 可选能力
- 运行配置
- 凭据
- 数据与迁移
- 隐私与安全
- 架构
- 文档
- 贡献
- 许可证

要求

- DeepSeek Harness Web，已验证 @deepseek-ai/dsh 0.1.1-rc.2（精确 BOM）。0.1.5-rc.1 等未验证候选仅记在 compatibility/dsh-bom.json，见 docs/01-install.md。
- Node.js ^22.19.0 || >=24.0.0
- DSH Web 后端保持回环；可通过受控本机 HTTPS 反向代理向已认证私网提供完整 Web。不要单独暴露插件 API，也不要无认证发布到公网。

安装

dsh plugin --profile web add dsh-hub-oauth-gateway
dsh plugin --profile web update dsh-hub-oauth-gateway
dsh plugin --profile web remove dsh-hub-oauth-gateway

无插件管理器时可用兼容安装器：npx --yes dsh-hub-oauth-gateway-install。GitHub /path/to/.tgz 与本地开发安装见 docs/01-install.md。安装后通过测试机实际配置的进程管理器重启现有 DSH Web 进程，再刷新 http://127.0.0.1:3080；DSH 官方不提供统一的服务单元名。

使用

1. 默认点悬浮用量小窗（或在 设置 → 显示 → 入口形态 改回侧栏按钮）打开 Quick Peek；设置页也可打开速览 / 完整仪表盘。
2. Full Dashboard 用顶部页签切换概览 / 趋势 / 账户 / 明细 / 本机，并选择时间范围、指标与 provider/model 维度。
3. 点刷新才会立即投影用量并刷新账户；普通 GET 只读本地快照。
4. 在 设置 → 用量中心 调整显示、订阅账号、网关、能力、供应商与费用。
5. 成本始终是估算——关注 coverage；未定价 Token 不是免费。

CLI：dsh-hub-oauth login [--pkce] | import | status | logout（dsh-hub-grok-build 为别名）。

设置页

设置 → 用量中心 六个顶部标签：显示、订阅账号、网关、能力、供应商、费用。已登录供应商卡片默认折叠。「供应商」页卡片内可直接维护认证——保存/清除 API Key、Copilot 设备授权、按供应商刷新；OAuth 卡片一键跳转「订阅账号」登录/拉取。

编码 OAuth

在 订阅账号 登录 Grok Build、Codex、Kimi Code 或 Claude Code（远程/无头优先设备码；浏览器/PKCE 可粘贴授权码或完整回调 URL）。已认证模型以 (OAuth) 出现在选择器。

每个 provider 凭据文件可存多个 AuthDocument v2 账号（最多 8）。用订阅账号页的控件可添加、设默认或删除账号。已登录卡片可显示 Usage Center 缓存配额条（仅 GET；无快照时隐藏）。

Import Claude Code 走 preview → commit（可能时用 accountMode: add）。macOS 优先 Keychain Claude Code-credentials，其它平台用白名单文件路径。覆盖写入仍需显式确认。

可选粘性路由：同一 provider 有两个及以上账号时，可将 codingOAuth.pool.mode 设为 priority 或 quota_aware。默认 off。细节见 docs/03-configuration.md。

GitHub Copilot LLM 路由（github-copilot-oauth）在配置 oauthDevice.copilotClientId 之前保持失败关闭。

白名单内官方 CLI OAuth 文件只读发现。同步是显式单向 拉取（发现 → 预览 → 确认），不是自动导入，也不写官方 CLI 文件。

本地 API 网关

默认关闭。启用后在独立 node:http 监听器（非 DSH web 端口）上提供 GET /healthz、GET /v1/models、POST /v1/chat/completions、POST /v1/responses、POST /v1/messages，复用已登录 OAuth 会话。bind 仅 YAML；非回环 bind 必须有 Bearer key。不是远程中继。细节见 docs/01-install.md。

在账户与模型下以独立供应商 coding-opencode-go 连接（与 DSH 原生 opencode-go 隔离）。外部工具使用 coding-opencode-go/（过渡期仍接受 opencode-go/）与对应协议，并发送稳定会话标识。本地网关密钥与上游凭据分开；缺少会话标识会明确失败。若旧版插件配置仍在原生槽，可在账户卡片迁移。 Migration / 迁移.

可选能力

七项开关默认关闭，打开后立即生效：codexSearch、codexImages、codexImageEdits、codexUsage、codexFast、grokImagineImage、grokImagineVideo。Codex Fast / 私有端点与 Grok Imagine 在打开前保持失败关闭。打开 codexFast 后，会话选择器使用已有的 codex-oauth-fast 路由（能力页有 Standard/Fast 提示）。该路由仅在 live catalog 列出 priority 资格模型后出现，不是第二套 Fast 栈。见 docs/01-install.md 与 docs/03-configuration.md。

运行配置

在现有 Cordis entry 下合并 config，不要新增第二个 entry：

~/.dsh/profiles/web/cordis.patch.yml
- insert:
- id: usage-stats
name: dsh-hub-oauth-gateway
config:
refresh:
usageSeconds: 30
accountMinutes: 5
accountConcurrency: 3
timeoutMs: 15000
retention:
usageDays: 730
accountSnapshotDays: 180
preserveDeletedSessions: true
pricing:
baseCurrency: USD
accounts:
monitors: {}
oauthDevice:
copilotClientId: YOUR_PUBLIC_OAUTH_CLIENT_ID
codingOAuth:
enabled: true
pool:
mode: off
switchMargin: 2
localMonitor:
enabled: false
localUsage:
enabled: false
intervalMinutes: 30
statusProbes:
enabled: false

完整字段、monitor、代理与价格导入：docs/03-configuration.md 与 docs/01-install.md。旧根级 config.monitors 映射到 config.accounts.monitors（不要同时配置）。

凭据

- 经 DSH credential seam 存储；浏览器只收到 configured / source / writable 元数据，永不收到值。
- 本地 CLI 导入（Claude、Codex、Gemini、Grok、Amp）不在日志暴露绝对路径。
- Copilot 设备流把 device code 留在服务端；浏览器只持有随机 flow ID。启用前须配置自己的公共 OAuth client ID。
- 编码 OAuth 文件：$DSH_HOME/.grok-build-auth.json、.codex-oauth-auth.json、.kimi-code-oauth-auth.json、.claude-code-oauth-auth.json，以及配置 Copilot 时的 .github-copilot-oauth-auth.json（0600、原子写）。任何 HTTP 状态、日志或 UI 都不得返回 token。

数据与迁移

${DSH_HOME:-~/.dsh}/storages/usage-stats-v1.sqlite

目录 0700、主文件 0600、WAL。默认保留 730 天 usage facts、180 天账户快照。首次启动迁移与回滚：docs/04-migration-v1.md。

隐私与安全

- 默认要求回环 peer + 回环 Host。受信任 HTTPS 反向代理必须满足完整 owner policy：trusted peer、精确 HTTPS Origin 与匹配的公网 Host、owner proof、同源 Fetch Metadata，变更请求还需 CSRF；仅转发 forwarded headers 不会授予访问权，策略不完整时 fail closed。
- 普通 GET 只读本地；带凭据刷新为显式 POST 或调度。
- monitor 默认 HTTPS、禁止 URL 内嵌凭据、手动 redirect、限制大小、连接前 DNS pinning。
- SQLite 不含凭据、prompt、response、cwd 或供应商原始响应。
- 统计与估算不是账单。仅监测你拥有或获授权的账户与 endpoint。

威胁模型与报告：.github/SECURITY.md。

架构

flowchart LR
subgraph DSH["DSH Harness Web"]
UI[设置 / Peek / 仪表盘] --> API[usage-stats v1 API]
UI --> OAuthUI[订阅账号 / 网关 / 能力]
end
API --> SQLite[(本地 SQLite)]
API --> Adapters[账户适配器]
OAuthUI --> CodingOAuth[coding-oauth 路由]
CodingOAuth --> Creds["$DSH_HOME/-oauth-auth.json"]
CodingOAuth --> LLM[LLM OAuth 路由]
LLM --> Providers[Grok / Codex / Kimi / Claude / Copilot]

细节：docs/02-architecture.md · 中文。OAuth 归因：docs/oauth-provenance.md。

文档

| 文档 | 用途 |
| docs/01-install.md | 安装、代理、网关、能力、故障排查 |
| CHANGELOG.md | 版本历史 |
| docs/00-project-rules.md | 发布分层、版本、发版循环 |
| docs/02-architecture.md | 内部架构 · 中文 |
| docs/03-configuration.md | 运行配置参考 |
| docs/04-migration-v1.md | 1.0 数据迁移 |
| docs/05-dsh-alpha-smoke.md | 未验证 DSH 候选宿主的隔离冒烟（0.1.2-alpha.*、0.1.5-rc.1） |
| catalog/ | Desktop Market Path A 目录源（catalog-source.json、v1/plugins.json）；不在 npm 包 files 白名单内 |
| .github/CONTRIBUTING.md | 贡献指南 |
| .github/SECURITY.md | 安全策略 |

贡献

在 Cursor Cloud / 本仓库云工作区用声明的 Node.js 与 pnpm 验证即可（Docker sandbox 可选，非强制）。DSH 冒烟使用隔离 DSH_HOME。见 .github/CONTRIBUTING.md。不要在 issue、PR、截图或日志中提交密钥、prompt 或个人路径。

若语言切换行缺少你的语言，欢迎 PR 一份 README 翻译。

许可证

MIT · 参见 NOTICE。独立社区项目，不暗示供应商背书。编码 OAuth 相关部分按要求保留 Apache-2.0 归因（LICENSES/Apache-2.0.txt）。