# @goodandready/dsh-subscriptions 中文文档

规范地址：https://npmcn.com/package/%40goodandready/dsh-subscriptions/

版本：0\.8\.1
npm 元数据更新时间：2026-11-16T16:21:37.474Z
中文译文更新时间：2026-11-16T19:11:55.270Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40goodandready/dsh-subscriptions
原文对照：https://npmcn.com/package/%40goodandready/dsh-subscriptions/?lang=original
项目主页：https://github.com/GooDAnDReaDY/dsh-subscriptions
源码仓库：https://github.com/GooDAnDReaDY/dsh-subscriptions

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：1.5 MB，164 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=22\.19\.0
- 运行依赖：2 个
- peer 依赖：@deepseek-ai/cordis ^4\.0\.1，@deepseek-ai/dsh-llm ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/schemastery ^3\.18\.4，@deepseek-ai/dsh-settings ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/dsh-credentials ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1，@deepseek-ai/dsh-host-webserver ^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1
- 首次发布：2026-08-21T12:03:49.769Z
- 最新版本发布：2026-11-16T16:21:37.040Z
- 近 30 天下载量：23935（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：224（近 12 个月 224 个）

## 中文简介

使用 ChatGPT Codex, Claude, Grok, Antigravity, Kimi, GLM, Cursor, Kiro, 副驾驶, Quen, ERNIE, Spark, JetBrains, Persplexity, Replit, 以及 Cody 订阅作为 DeepSeek Harness LLM 供应商通过 OAuth 提供.

## 安装

```sh
npm install @goodandready/dsh-subscriptions
```

也可以使用：`pnpm add @goodandready/dsh-subscriptions`、`yarn add @goodandready/dsh-subscriptions`、`bun add @goodandready/dsh-subscriptions`

## README

# 📦 @goodandready/dsh-subscriptions

### DeepSeek Harness 个人 AI 订阅桥接、多账号池轮换与零泄漏 OAuth 插件

[![npm version](https://img.shields.io/npm/v/@goodandready/dsh-subscriptions.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b)](https://www.npmjs.com/package/@goodandready/dsh-subscriptions) [![license](https://img.shields.io/badge/License-MIT-10b981.svg?style=for-the-badge&color=10b981&labelColor=064e3b)](https://npmcn.com/package/%40goodandready/dsh-subscriptions/LICENSE) [![DSH Plugin](https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065)](https://github.com/topics/dsh-plugin) [![Node version](https://img.shields.io/badge/Node-22%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03)](https://nodejs.org/)

[![作者全部项目](https://img.shields.io/badge/%E4%BD%9C%E8%80%85%E5%85%A8%E9%83%A8%E9%A1%B9%E7%9B%AE-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e)](https://goodandready.app/)

[**🇬🇧 English**](https://npmcn.com/package/%40goodandready/dsh-subscriptions/README.md) • [**🇷🇺 Русский**](https://npmcn.com/package/%40goodandready/dsh-subscriptions/README.ru.md) • [**🇨🇳 中文说明**](https://npmcn.com/package/%40goodandready/dsh-subscriptions/README.zh.md)

* * *

## ⚡ 插件概览

**`dsh-subscriptions`** 将您现有的付费个人 AI 订阅无缝接入 **DeepSeek Harness**，作为第一类模型服务商。

无需为日常智能体任务支付昂贵的 API 按量计费。本插件支持标准 OAuth PKCE 鉴权、**单服务商多账号池动态轮换**（遭遇 429 限流时自动秒切可用账号）、**前置配额平滑切换**，并通过**进程内 Cordis 服务 (`ctx.subscriptions`)** 赋能 [`dsh-image-gen`](https://github.com/GooDAnDReaDY/dsh-image-gen) 与 [`dsh-grok-xsearch`](https://github.com/GooDAnDReaDY/dsh-grok-xsearch) 等插件，实现 Token 零网络泄漏。

```mermaid
graph LR
    subgraph DSHCore [DeepSeek Harness 对话流]
        Agent[🤖 智能体任务执行] --> Router{服务商路由器}
    end

    subgraph SubscriptionsCore [dsh-subscriptions 调度核心]
        Router --> Pool{多账号负载池}
        Pool -->|账号 1| Acc1[👤 主账号: 活跃中]
        Pool -->|账号 2| Acc2[👤 副账号: 待命中]
        Pool -->|账号 3| Acc3[👤 备用账号: 冷却中]
        Acc1 -->|HTTP 429 / 配额耗尽| Rotate[智能配额与冷却轮换器]
        Rotate -->|流量平滑切换| Acc2
    end

    subgraph VendorBridges [4 大服务商桥接适配]
        Acc1 --> B1[ChatGPT / Codex 后端]
        Acc1 --> B2[Claude Pro / Max 协议]
        Acc1 --> B3[xAI / Grok 订阅]
        Acc1 --> B4[Google Cloud Code Assist / Antigravity]
    end

    subgraph EcosystemBridge [Cordis 进程内共享: ctx.subscriptions]
        Pool --> ImgGen[dsh-image-gen: 订阅零成本生图]
        Pool --> XSearch[dsh-grok-xsearch: X 社交搜索]
    end

    style DSHCore fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
    style SubscriptionsCore fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
    style VendorBridges fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
    style EcosystemBridge fill:#181825,stroke:#f38ba8,stroke-width:2px,color:#cdd6f4
```

* * *

## ✨ 核心功能

### 支持的 16 个内置订阅供应商

| 供应商 | 订阅级别 | 协议 |
| --- | --- | --- |
| `codex` | ChatGPT Plus / Pro | 流式响应、工具调用、图像生成 |
| `claude` | Claude Pro / Max | 原生 Messages 协议、用量跟踪 |
| `grok` | xAI / X Premium | 实时推理、计费检查 |
| `antigravity` | Google Cloud Code Assist | 流式生成 |
| `kimi` | Moonshot Kimi | OAuth Device Flow 登录（`auth.kimi.com`）、OpenAI 兼容聊天 |
| `glm` | Z.ai GLM Coding Plan | GLM 编码端点（`api.z.ai`）、实时配额监控 |
| `cursor` | Cursor | Cursor 后端（`api2.cursor.sh`）、用量面板解析 |
| `kiro` | AWS Kiro | Kiro 桌面 OAuth（`app.kiro.dev`）、流式输出 |
| `copilot` | GitHub Copilot | GitHub Device Flow 登录、Copilot 聊天补全 |
| `qwen` | 阿里 Qwen（DashScope） | OpenAI 兼容端点、API Key 认证 |
| `ernie` | 百度 ERNIE（千帆） | OAuth2 令牌刷新（API Key + Secret Key） |
| `spark` | 讯飞星火 | OpenAI 兼容 HTTP API |
| `jetbrains` | JetBrains AI Assistant | JetBrains AI 中继（`api.jetbrains.ai`） |
| `perplexity` | Perplexity Pro | Sonar 模型目录（`api.perplexity.ai`） |
| `replit` | Replit Core | Replit AI API、connect-token 认证 |
| `cody` | Sourcegraph Cody Pro | Sourcegraph API、access-token 认证 |

### 多账号轮换与限流保护

-   每个供应商可挂多个账号（如 `CODEX_OAUTH_1`、`CODEX_OAUTH_2`）。
-   遇到 429/配额耗尽自动切换到下一个健康账号；支持按剩余量提前切换和动态冷却恢复。
-   **轮换决策追踪与路由解释 (#517)**：实时同步记录账号选择、轮换切换、失败原因与级联回退的完整决策链路（无需事后推导），并在 WebUI 遥测与诊断报告中可视化展示。
-   **动态模型目录与配额可用性 (#507)**：基于账号池计算模型综合可用性（单个账号隔离不影响具备可用账号的模型），展示上下文窗口、能力标签（视觉、工具、推理、编码、快速）及动态配额倒计时。

### 安全与无头登录

-   OAuth 令牌绝不通过 HTTP API 返回，也不在 Web 界面渲染；仅存放于宿主加密凭据存储。
-   **回环自动回调 (`autoLoopback`)**：供应商重定向为回环地址（如 Codex `:1455`）时，插件自动启动临时本地服务器接收回调，无需手动粘贴链接。
-   **设备码登录**：完全无浏览器的主机上，点击 **Device login**，在任意设备打开 `https://auth.openai.com/codex/device` 输入短码即可完成 PKCE 授权。

### 账号级代理

-   每个账号可配置独立代理（`http://`、`https://`、`socks5://`）；令牌刷新、供应商检查、模型请求均走该代理。
-   账号卡片内的 **Check proxy** 按钮一键检测代理延迟。

### 本地 Ollama 网关与无缝回退

-   **原生 provider (`ollama`)**：本地 Ollama 可达时（`ollamaBaseUrl`，默认 `http://127.0.0.1:11434`），自动出现在 DSH 原生模型选择器中（模型来自 `/api/tags`），无需密钥。
-   **无缝配额回退 (`ollamaFallback`，默认开启)**：某供应商的所有账号耗尽或不可达且尚未输出任何内容时，对话自动切换到本地模型（`ollamaFallbackModel` 或 `/api/tags` 第一个模型），并记录到请求历史（`kind: fallback`）。
-   免费（$0）应急通道：无网络、无配额也能用。

### Effort、Verbosity 与 Fast Mode

-   **推理力度 (Effort)**：Codex 模型从实时目录上报支持的力度等级，原生选择器校验后以 `reasoning.effort` 传入 `/responses` 协议；Grok 按自身目录过滤转发。
-   **详略程度 (`codexVerbosity`)**：`low`/`medium`/`high` 以 `text.verbosity` 传给 Codex 推理模型；留空为协议默认。
-   **Fast Mode (`codexFastMode`)**：每次 Codex 请求携带 `service_tier: priority`（1.5x 速度计费档）；启用时活动订阅芯片显示 `⚡`。

### 按模型家族的冷却与模型过滤

-   **Reasoning 与 Standard 分离**：推理模型（claude `*thinking*`、grok `*reasoning*`、全部 codex 模型）触发 429 时，只冷却该账号的 reasoning 家族——同账号的 standard 模型立即可用；旧版冷却仍按整账号生效。
-   **隐藏过时模型 (`hideDeprecatedModels`)**：从原生选择器中过滤 `test`/`preview`/`dev`/`alpha`/`beta`/`legacy` 模型 id（同时作用于实时目录与静态回退）。

### 隐私模式与诊断报告

-   **`privacyMask`**：一个开关即可在整个界面隐藏个人数据（邮箱显示为 `j***n@example.com`），服务端遮蔽，适合屏幕共享。
-   **匿名诊断报告**：设置卡片内一键生成（插件/运行时版本、系统、各供应商健康状态、HTTP 状态聚合、最近错误与耗时、非敏感配置）并自动复制到剪贴板；令牌、邮箱、凭据名与代理地址严格排除。
-   同区块提供问题追踪器链接，便于提交 issue。

### 隔离管理、动态额度重置倒计时与应用内弹窗提醒

-   **手动隔离管理（暂停与预热探测）**：支持在设置面板的账户卡片中一键暂停隔离活跃账户（`POST /dsh-subscriptions/quarantine/park`），或立即触发真实上游预热微探测（`probeWarmup`）并在验证成功后即时解除隔离（`POST /dsh-subscriptions/quarantine/probe`）。
-   **动态额度重置倒计时**：在顶部会话栏 `SubsPill` 和账户卡片中秒级动态更新，精准展示滚动配额窗口（`five_hour`、`seven_day`、`primary_window`）的剩余解锁时间。
-   **应用内即时弹窗提醒（Toast）**：当账户进入隔离、健康恢复解除隔离或额度达到预警线时，在聊天界面弹出轻量级浮动提醒。通过 `enableToasts: true` 控制。 enableQueue: true # 账户并发请求排队与限流 accountMaxConcurrency: 2 # 单账户最大并行活跃流 maxQueueSize: 20 # 队列最大等待深度 queueTimeoutMs: 30000 # 队列最大等待超时时间（毫秒）
-   **自动化 Webhook 告警集成**：通过 `notifyQuarantineEntered` 与 `notifyQuarantineReleased` 自动向外部通知系统派发隔离生命周期事件。

### 🩺 服务商鉴权诊断、网络延迟 RTT 指标、动态模型同步与客户端轻量化

-   **服务商错误诊断系统 (#543)**: 智能分析与解读服务商连接和鉴权失败原因（Cloudflare 403 / 地区限制、令牌过期、会话失效、模型权限不足、用量配额耗尽），并在卡片中直接展示修复建议。
-   **延迟 RTT 指标与快速 Ping 测试 (#542)**: 实时测量至服务商 API 的网络往返时间，支持色彩标记状态徽章（🟢 <250ms, 🟡 <750ms, 🔴 >750ms）及独立 POST /dsh-subscriptions/ping 接口。
-   **动态模型列表同步 (#541)**: 账户卡片一键「同步模型」按钮，直接从服务商 /v1/models 接口获取最新及账号专享模型，无需等待插件版本更新。
-   **客户端包体积优化 (#540)**: 将 lib/client.js 体积从 217.3 KiB 缩减至 199 KiB 以下（距离 256 KiB DSH Store 门禁阈值预留超 57 KiB 安全冗余空间）。

### 🛡️ 弹性容灾、故障诊断与跨服务商回退

-   **跨服务商级联故障转移与优先级排序 (#536)**: 支持自定义跨服务商回退顺序，可在 WebUI 中通过 ▲/▼ 交互调整优先级。
-   **一键链路测试与延迟检测 (#536)**: 在账户列表或状态弹窗中一键发起探活并显示往返延迟。
-   **冷却倒计时与就绪通知 (#536)**: 实时展示受限账户恢复倒计时，解除冷却时自动弹出就绪通知。
-   **主动 OAuth 令牌心跳 (#536)**: 提前预刷即将过期的访问令牌，避免用户请求时产生额外等待。
-   **最近错误环形日志审查 (#536)**: 内存保存最近 20 条已脱敏的运行错误，支持在 Diagnostics 中查看与清空。

### Antigravity 分档思考模型、工具回放哨兵与流式自愈

-   **Gemini 3 工具回放哨兵 (#534)**：在重建的工具调用中注入 `thoughtSignature: 'skip_thought_signature_validator'`，彻底解决多轮工具调用历史重放时 Gemini 3 的校验失败问题。
-   **分档 Flash 模型与思考档位 (#534)**：将 `gemini-3.8-flash-tiered` 与 `3.7` 自动解析展开为 High/Medium/Low 档位选择，并在调用时自动组装 `thinkingConfig.thinkingLevel`。
-   **流式空响应自愈与账号轮换 (#534)**：引入 30 秒 SSE 空闲超时保护与空响应检测，在未输出前自动重试一次，失败时通过 `EMPTY_RESPONSE` / `TIMEOUT` 自动轮换至下一个可用账号。

### xAI Grok RFC 8628 设备码授权流支持

-   **RFC 8628 设备码授权流 (GH #17, #532)**：为 xAI Grok 新增原生设备码登录授权支持。彻底解决 xAI 针对 CLI 客户端标识返回 Grok Build 验证码页面且不触发回环重定向回调导致的死锁问题。直接在槽位卡片展示用户授权码，并自动在后台轮询兑换会话令牌。

### Claude 账户级计费归因隔离与动态轮次索引

-   **按账户隔离 `cc_turn_index` 与 `cch` (#530)**：将 Claude Code 计费归因状态（会话哈希 `cch` 与递增轮次 `cc_turn_index`）按 `accountId` 隔离在有界模块级映射表中，彻底消除 `globalThis` 跨订阅账户状态混用问题。
-   **动态计算 `cc_prompt_index` 与禁用开关**：根据多轮对话消息历史自动计算从 0 开始的 `cc_prompt_index`，并支持通过环境变量 `CLAUDE_CODE_ATTRIBUTION_HEADER=0` 或 `disableBillingHeader: true` 禁用归因头注入。

### Antigravity 客户端密钥架构与无感 CLI 令牌刷新

-   **配置架构密钥字段 (`antigravityClientSecret`)**：支持用户在设置中自定义配置 Google Cloud OAuth 客户端密钥（Client Secret），公共接口自动脱敏掩码 (`••••••`)，彻底解决机密型 OAuth 客户端刷新令牌被拒的问题。
-   **CLI 令牌零配置平滑刷新**：内置官方 Gemini / Antigravity CLI 客户端的公共应用凭据 (`Google Gemini CLI Client ID` / `Google Gemini CLI Client Secret`)，使通过 `📥 从 CLI 导入` 的会话能够持久无限刷新，不再出现 1 小时后失效问题。
-   **Windows 凭据管理器自动发现**：原生支持在 `win32` 系统下自动检测 Windows 凭据管理器中的 `gemini:antigravity` 目标，直接完成 CLI 会话导入。
-   **清晰明确的错误指引**：在缺少密钥或上游凭据异常时抛出指引性错误，替代原始的 HTTP 400 提示。

### HTTP API 路由

| 路由 | 方法 | 用途 |
| --- | --- | --- |
| `/dsh-subscriptions/diagnostics` | GET | 匿名诊断报告（无密钥、无令牌、无代理地址） |
| `/dsh-subscriptions/proxy-check` | POST | 检测槽位代理到供应商基础地址的延迟 |
| `/dsh-subscriptions/oauth/device/start` | POST | 发起 Codex 设备码登录（返回用户码与验证地址） |
| `/dsh-subscriptions/oauth/device/poll` | POST | 轮询设备码授权状态 |
| `/dsh-subscriptions/quarantine/park` | POST | 将指定账户临时暂停隔离（支持 `durationMs` 与 `reason`） |
| `/dsh-subscriptions/quarantine/probe` | POST | 立即执行健康预热探测或提前解除账户隔离 |
| `/dsh-subscriptions/alerts` | GET | 获取近期应用内告警与通知列表 |

* * *

## 📦 安装指南

```bash
dsh plugin --profile web add @goodandready/dsh-subscriptions
```

* * *

## ⚙️ 配置参考（`settings.yaml`）

```yaml
dsh-subscriptions:
  switchAtRemaining: 1
  cooldownMs: 60000
  autoLoopback: true        # 自动监听本地回调端口并捕获 OAuth 令牌
  privacyMask: false        # 在 Web UI 中脱敏邮箱和账号标识符
  ollamaBaseUrl: http://127.0.0.1:11434  # 本地 Ollama 网关地址
  ollamaFallback: true      # 订阅全部耗尽时无缝降级到本地模型
  ollamaFallbackModel: ''   # 降级模型（为空默认使用 /api/tags 中的第一个）
  hideDeprecatedModels: false # 过滤测试/预览/废弃模型
  codexVerbosity: ''        # low | medium | high
  codexFastMode: false      # 优先使用 1.5x 速率服务档位
  composerQuota: 'off'      # 输入框配额指示器: off | percent | bar | forecast
  composerQuotaDisplay: 'hidden' # 状态栏配额范围: current | hidden
  sidebarQuotaDisplay: 'off' # 侧边栏底部配额显示: off | auto | always
  showSpeedToggle: false    # 在输入栏显示 Codex 极速模式按钮
  showSubsPill: false       # 在对话标题栏显示 SUBS 订阅胶囊
  enableToasts: true        # 隔离与配额事件的实时弹窗通知
  enableQueue: true         # 有界并发队列，防止瞬时并发触发 429
  accountMaxConcurrency: 2  # 单账号最大并发活动请求数
  maxQueueSize: 20          # 队列最大等待深度
  queueTimeoutMs: 30000     # 队列等待超时时间（毫秒）
  accounts:
    codex:
      - ref: CODEX_OAUTH_1
        label: "Work Pro Account"
      - ref: CODEX_OAUTH_2
        label: "Personal Plus Account"
    claude:
      - ref: CLAUDE_OAUTH_1
        label: "Claude Max"
    grok:
      - ref: GROK_OAUTH_1
        label: "X Premium"
```

* * *

### 自定义供应商与主机信任

-   `customVendors.authUrl`、`tokenUrl` 和 `baseUrl` 必须使用 `https://`。明文 `http://` 仅允许用于回环主机（`localhost`、`127.0.0.1`、`::1`）。
-   Grok `baseUrl` 覆盖只能指向 `api.x.ai`、`grok.com` / `*.grok.com` 或回环主机；其他主机会以 `GROK_UNTRUSTED_HOST` 拒绝，避免 bearer 令牌离开可信的 xAI 基础设施。
-   Antigravity CLI 导入必须配置 `antigravityClientSecret`；内置默认值已移除。
-   `copilotCliPath` 必须指向 `copilot`、`github-copilot-cli` 或 `copilot-cli` 可执行文件；自定义包装器请重命名。
-   凭据备份使用 `/dsh-subscriptions/vault/export` 和 `/vault/import`；旧路由 `/export`、`/import`、`/export-backup`、`/import-backup` 已移除。
-   错误缓冲区和诊断报告会在存储或返回前脱敏 bearer 令牌、API 密钥、JWT 和 `key=value` 凭据。

## 🧠 Claude 自适应思考与推理深度控制

支持 Anthropic 自适应思考 (`thinking: { type: "adaptive" }`) 及推理深度调节 (`output_config: { effort }`):

-   **模型支持**: 针对 Opus 4.6+、Opus 4.7+、Opus 5 (`low`, `medium`, `high`, `xhigh`, `max`) 及 Sonnet 4.6+、Sonnet 5 (`low`, `medium`, `high`) 自动提供对应推理级别。
-   **安全降级**: 不支持自适应思考的模型（如 Haiku、Fable、4.5 及更早版本）保持原始请求，防止出现 400 Bad Request 错误。
-   **动态目录**: 模型列表自动暴露 `reasoning.efforts`，供 DeepSeek Harness 界面选择。

* * *

## 🌐 完整双语支持 (EN / ZH) 与单账户健康探活

-   **原生双语支持**: 内置 UI 字典全面提供英语 (`en`) 与简体中文 (`zh`) 翻译，所有服务商获取令牌指引均具备中英双语版。
-   **解耦外部翻译**: 俄语等其他语种由独立语言包插件（如 `dsh-russian-lang`）在运行时翻译，插件源码保持纯净零硬编码。
-   **单账户实时探活与延迟测量**: 槽位中的“检测”按钮实时测量对应订阅账户的双向响应延迟 (`latencyMs`) 与健康状态。

* * *

## 🚀 一键插件自更新与稳定性强化

-   **宿主端一键更新**: 挂载于 `/dsh-subscriptions/update` 的就地更新机制，自动对比 npm registry 最新版本并通过宿主 DSH CLI 执行单飞安装 (`dsh plugin add`)。
-   **安全与来源防护**: 更新接口严格校验环回地址（支持 IPv4 `127.0.0.1`、IPv6 `::1`、`localhost`）、`x-dsh-plugin-update` 请求头及同源策略，阻断未授权跨站调用。
-   **状态栏徽章与更新按钮**: 设置面板顶部状态栏显示当前插件版本，有新版本时提示告警徽章并提供一键更新按钮与重启提示。
-   **网络超时熔断**: 配额检测与冒烟测试增加 15 秒超时信号保护 (`AbortSignal.timeout(15_000)`)，防止外部服务商接口故障导致请求挂起。
-   **参数容错与逻辑去重**: 状态接口兼容 `provider || vendor` 与 `index || accountIndex` 参数别名，并消除 `lib/accounts.js` 中的重复配额通知循环。

* * *

* * *

## 🛡️ Token 用量规范化与会话投影修复

-   **会话投影崩溃修复 (GitHub #4)**：修复了使用 ChatGPT Codex 及其他流式模型时，首次回复后会话损坏、刷新页面报错 `received NaN, expected number on uncachedInputTokens and outputTokens` 且无法加载的问题。
-   **全格式通用 TokenUsage 转换**：在所有流式传输通道（`codexResponsesStream`、`openaiChatStream`、`anthropicStream`、`googleStream`）中引入统一的 `toTokenUsage()` 转换逻辑，将各服务商的原始用量数据标准化为 DSH 规范的 `TokenUsage` 接口（`inputTokens`、`outputTokens`、`cacheReadTokens`、`cacheWriteTokens`、`reasoningTokens`、`totalTokens`）。
-   **严格非负整数保底与独立缓存计算**：对所有 token 计数实施严格的非负整数约束（保底为 `0`，杜绝 `NaN` 与 `undefined`）。针对将缓存合并计入总 prompt 的供应商自动执行拆分，确保输入 token 数的准确性。
-   **适配器层纵深防御**：在 `SubscriptionAdapter` 中新增用量数据过滤与净化机制，从根源上阻止异常用量流入 DSH 会话持久化与状态恢复流程。

* * *

## 🔒 OAuth Client ID 校验保护与控制台地址更新

-   **Google OAuth Client ID 校验保护 (GitHub #2)**：uildAuthorizeUrl 和 ntigravity.authorizeUrl 严格要求非空 clientId。未配置时服务端返回明确的 HTTP 400 (missing\_client\_id)，前端界面提示用户在插件设置中填写 ntigravityClientId 或使用“📥 从 CLI 导入”，避免浏览器跳转至 Google OAuth 400 报错页面。
-   **配置架构新增密钥项**：在插件 Config 架构中新增 ntigravityClientSecret，方便用户在设置中配置客户端密钥，并在公共接口中自动脱敏脱密。
-   **智谱 GLM 控制台地址迁移 (GitHub #3)**：将智谱 GLM 授权与 API Key 获取链接更新为最新控制台有效路由 ([https://bigmodel.cn/usercenter/proj-mgmt/apikeys](https://bigmodel.cn/usercenter/proj-mgmt/apikeys))，彻底解决因服务商控制台路由调整导致的 404 错误。

* * *

## 🛡️ 稳定性与代码质量强化

-   **结构化异常降级**: 全面移除运行时空 catch 块，统一采用带诊断日志的 `bestEffort` 安全兜底机制。
-   **原生上下文日志**: 所有日志统一接入 Cordis 规范子系统 `ctx.logger('subscriptions')`。
-   **外部网络超时保护**: 为所有模型商 API 网络调用（`listModels`、`fetchFor`、`quotaFetch`、`jsonTokenRequest`）建立 `fetchWithTimeout` 与 `AbortSignal.timeout` 超时熔断保护。
-   **设计系统主题对齐**: 将 `client.js` 中的静态样式硬编码替换为 DeepSeek Harness 原生 CSS 主题令牌（`--dsw-alias-*`、`color-mix`），彻底消除独立的 `rgba` 颜色。
-   **客户端依赖注入显式化**: 在 `package.json` 清单中显式声明前端所需平台注入项（`@deepseek-ai/dsh-client-locale` 与 `@deepseek-ai/dsh-client-ui-slots`）。
-   **公开仓库卫生规范**: 将内部研发指令与计划文件移出 Git 跟踪并加入 `.gitignore`，确保公开版本干净无私有残余。

* * *

## 🔌 HTTP API

插件在 DSH Web 服务器上注册以下 55 个精确路由。除特别说明外，接受同源或 loopback 请求；写入操作必须携带与 Host 匹配的 `Origin` 或 `Referer`（#782）。响应均为 JSON（除非另有说明）。

### 核心与状态

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/dsh-subscriptions/status` | 全局状态、配置的槽位、活跃用量与额度 |
| GET | `/dsh-subscriptions/health` | 供监控使用的深度健康检查报告（#745）；公开 GET |
| GET | `/dsh-subscriptions/metrics` | Prometheus 文本指标（#744）；仅 loopback 或同源 |
| GET | `/dsh-subscriptions/models` | 当前活跃订阅的增强模型目录 |
| POST | `/dsh-subscriptions/heartbeat/run` | 触发一次额度与健康状态刷新；返回 `{ok, refreshed}`（#968） |
| GET | `/dsh-subscriptions/subscriptions` | 仅限 localhost 的自适应 HTML 订阅概览表格（#1021） |
| GET | `/dsh-subscriptions/telemetry` | 请求计数聚合、平均延迟与成功率 |
| GET | `/dsh-subscriptions/usage` | 面向外部配额插件的额度快照与调用账本（#687） |
| POST | `/dsh-subscriptions/smoke` | 针对活跃供应商发起合成连通性测试请求 |
| GET | `/dsh-subscriptions/ping` | 轻量级往返网络延迟检测 |
| GET | `/dsh-subscriptions/instructions` | 动态供应商连接操作指引（#540） |
| GET | `/dsh-subscriptions/alerts` | 应用内近期警报与通知列表 |

### 账号、轮换与推理

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET/PUT | `/dsh-subscriptions/config` | 配置架构读取与原子化更新 |
| POST | `/dsh-subscriptions/check` | 校验账号凭据并从供应商 API 获取最新配额 |
| POST | `/dsh-subscriptions/logout` | 断开指定账号槽位并清除存储的凭据 |
| GET | `/dsh-subscriptions/discover-local` | 扫描发现宿主机上已登录的本地 CLI 会话 |
| POST | `/dsh-subscriptions/import-local` | 将发现的本地 CLI 凭据导入账号槽位 |
| POST | `/dsh-subscriptions/import-token` | 手动导入刷新令牌或 API 密钥 |
| POST | `/dsh-subscriptions/accounts/sync-models` | 从上游供应商拉取并同步可用模型列表 |
| POST | `/dsh-subscriptions/accounts/switch-organization` | 为 Codex 账号切换活跃组织 |
| POST | `/dsh-subscriptions/quarantine/park` | 手动将账号置入隔离状态（支持 durationMs 与 reason） |
| POST | `/dsh-subscriptions/quarantine/probe` | 执行预热探测或立即解除账号隔离 |
| GET/POST | `/dsh-subscriptions/reset-credits` | 查看、准备并消费 Codex 额度重置信用点 |
| GET | `/dsh-subscriptions/routing/trace` | 实时路由决策审计日志与原因统计（#1028） |
| GET/POST/DEL | `/dsh-subscriptions/session-reasoning` | 会话级推理思考预算与档位覆盖管理 |
| GET/POST | `/dsh-subscriptions/speed` | 会话级 Codex 极速模式（fast-tier）开关 |

### 统计分析、经济价值与并发

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/dsh-subscriptions/analytics` | 缓存命中率、24小时请求分桶、热力图与额度耗尽预测 |
| GET | `/dsh-subscriptions/analytics/savings` | 交付价值估算、提示词缓存节省费用与多周期 ROI 报告（#1029） |
| GET | `/dsh-subscriptions/queue` | 实时并发队列深度与活跃并发请求监控（#518） |
| GET | `/dsh-subscriptions/history` | 历史请求明细与耗时账本 |

### OAuth 与设备码授权

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/dsh-subscriptions/oauth/start` | 发起浏览器 OAuth 授权登录流程 |
| GET | `/dsh-subscriptions/oauth/callback` | OAuth 本地回环端口回调监听服务（#1019） |
| POST | `/dsh-subscriptions/oauth/complete` | 提交重定向 URL 或授权码完成登录绑定 |
| POST | `/dsh-subscriptions/oauth/device/start` | 发起 RFC 8628 设备码授权（Codex、Grok、Copilot） |
| POST | `/dsh-subscriptions/oauth/device/poll` | 轮询设备码授权确认状态 |
| GET | `/dsh-subscriptions/oauth/headless-info` | 无头服务器远程连接所需的 SSH 隧道命令与 SVG 二维码 |
| GET | `/dsh-subscriptions/oauth/headless-redirect` | 引导浏览器直连上游供应商授权登录页 |

### 加密保管库与同步

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET/POST | `/dsh-subscriptions/vault/snapshots` | 查看或手动创建本地加密拉取前快照（#734） |
| POST | `/dsh-subscriptions/vault/snapshots/restore` | 从快照安全恢复账号凭据，支持失败自动回滚（#1003, #1022） |
| POST | `/dsh-subscriptions/vault/export` | 导出可移植加密备份归档文件 |
| POST | `/dsh-subscriptions/vault/import` | 导入并解密便携式备份归档文件 |
| GET | `/dsh-subscriptions/vault/sync/status` | 远程 Git 保管库同步状态检查 |
| POST | `/dsh-subscriptions/vault/sync/push` | 将本地加密快照推送到远程保管库 |
| POST | `/dsh-subscriptions/vault/sync/pull` | 从远程保管库拉取并应用快照 |

### 诊断与实用工具

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| GET | `/dsh-subscriptions/diagnostics` | 匿名化系统与健康诊断报告（严格排除所有私密凭据） |
| POST | `/dsh-subscriptions/diagnostics/errors/clear` | 清理近期错误缓冲区 |
| POST | `/dsh-subscriptions/diagnostic-wizard` | 自动化故障排查向导 |
| POST | `/dsh-subscriptions/webhook/test` | 测试向配置的 Webhook 发送探活事件 |
| POST | `/dsh-subscriptions/proxy-check` | 检测代理到供应商上游网关的连接延迟 |
| GET | `/dsh-subscriptions/sources` | 列出活跃上下文源与集成状态 |
| POST | `/dsh-subscriptions/provider-packs/validate` | 校验第三方自定义供应商扩展包规范 |

## 🌐 本地化

插件源语言仅为英语。俄语及其他翻译由独立的语言插件（如俄化插件）在运行时对注册的本地化键进行翻译，包本身不内置翻译（Changed in 0.6.1）。

* * *

## 📄 开源协议

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

## 常见问题

### @goodandready/dsh-subscriptions 是什么？

使用 ChatGPT Codex, Claude, Grok, Antigravity, Kimi, GLM, Cursor, Kiro, 副驾驶, Quen, ERNIE, Spark, JetBrains, Persplexity, Replit, 以及 Cody 订阅作为 DeepSeek Harness LLM 供应商通过 OAuth 提供\.

### 如何安装 @goodandready/dsh-subscriptions？

在项目目录运行 npm install @goodandready/dsh-subscriptions，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@deepseek-ai/cordis（^4\.0\.1）、@deepseek-ai/dsh-llm（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/schemastery（^3\.18\.4）、@deepseek-ai/dsh-settings（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/dsh-credentials（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）、@deepseek-ai/dsh-host-webserver（^0\.1\.7-rc\.2 \|\| ^0\.2\.0-rc\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 dsh-subscriptions，可以用 npx dsh-subscriptions 直接运行。

### @goodandready/dsh-subscriptions 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/goodandready\_\_dsh-subscriptions 是否存在。

### @goodandready/dsh-subscriptions 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @goodandready/dsh-subscriptions 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @goodandready/dsh-subscriptions 可以商用吗？

@goodandready/dsh-subscriptions 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @goodandready/dsh-subscriptions 的下载量有多少？

根据 npm 官方下载统计，@goodandready/dsh-subscriptions 在 2026/10/17 – 2026/11/15 这 30 天内被下载 23,935 次，日均约 798 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @goodandready/dsh-subscriptions 还在维护吗？

最新版本 0\.8\.1 发布于 2026/11/17（今天）；至今共发布 224 个版本，其中过去 12 个月发布了 224 个；首次发布于 2026/08/21。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

