---
## ⚡ 概述与核心痛点
### 🚀 v0.8.10 版本新特性（流并发加固与状态自动修剪）
- **杜绝并发计数泄漏**：在 `try ... finally` 中强制释放流并发占用，防止在正常完成或客户端中断时密钥被永久锁定。
- **探测抗网络抖动重试**：在 `probeModels` 中遇到套接字网络临时错误时自动重试一次，避免密钥被误判损坏。
- **内存与过期状态自动清理**：在定期清理周期中自动清除已删除密钥的内部映射记录。
### 🚀 v0.8.9 版本新特性（智能路由与界面升级）
- **前瞻性限流防护 (Proactive Rate-Limit Guard)**：根据 `x-ratelimit-remaining-*` 和 `Retry-After` 响应头在触发 429 错误前自动预冷密钥。
- **自愈恢复 (Self-Healing / Auto-Unbreak)**：通过免费的 `/models` 接口进行定期后台探测，自动恢复处于 `broken` 状态的密钥，无需消耗聊天代币。
- **延迟感知路由 (Latency-Aware Routing)**：可选路由策略：`round-robin`（轮询）、`least-loaded`（并发负载最低）与 `lowest-latency`（p95 延迟最低）。
- **`dsh-clinebot` 风格界面升级**：支持带进度提示的批量“测试所有密钥”（Test All Keys）、实时事件流折叠抽屉（Live Event Stream）及配额重置倒计时徽标。
- **原生中英文双语支持**：内置英文（`en`）与中文（`zh`）用户界面词典。
### 🛠️ v0.8.0 版本新特性（稳定性）
- **🔌 熔断器**：连续失败后快速失败（`CIRCUIT_OPEN`），半开探测自动恢复。
- **🕒 单调时钟**：冷却/熔断使用进程单调时间，NTP 校时不会颠倒剩余时间。
- **📮 非阻塞 Webhook**：有界队列 + backoff，轮换不等待 HTTP。
- **🧱 原子写文件**：损坏 JSON 不会覆盖既有状态。
- **🧹 克隆路由 GC**：清理孤儿自动路由。
- **🧭 错误分类**：408/425/429/5xx、套接字与 gRPC 的 switch/surface/soft。
- **📡 Status**：提供商 `circuit` + `meta`。
- **🧪 Smoke**：429 → 切换密钥 → 成功。
### 🛠️ v0.7.33 版本新特性 (稳定性与问题修复)
- **🔍 修复密钥探测 BaseURL 解析**：`resolveBaseUrl` 现已支持从密钥 ref 反查归属提供商池，恢复在线模型连通性探测。
- **🛡️ 防御级联无限递归**：在跨提供商故障转移中增加递归深度防护，彻底杜绝循环级联导致的堆栈溢出。
- **🕒 纠正 PST 太平洋时间配额重置**：修复 UTC-8 时区偏移符号，确保日配额在太平洋时间午夜准时重置。
- **🧹 定时器生命周期自动回收**：将金丝雀探测与自愈定时器纳入 Cordis 效应生命周期，消除热重载遗留孤儿定时器。
- **⚡ 负载均衡超时锁自动释放**：`pickLeastLoaded` 算法现已检测过期连接锁，确保最小连接调度不发生偏移。
- **🌐 完整中文界面本地化**：为 React 设置面板补充全部 `zh` 语言包，实现标准的三语（英/俄/中）无缝对齐。
### 🚀 v0.7.31 版本新特性
- **⚡ O(1) 令牌桶累加器**：将速率限制计算升级为 O(1) 时间复杂度与零内存分配，并支持响应头自适应同步。
- **🛡️ 软/硬故障分级退避**：区分临时网络抖动（502/503/超时获得 10 秒平缓冷却）与硬性配额超限（指数退避倍增）。
- **⏳ 惩罚衰减（Penalty Decay）**：持续稳定运行的密钥每小时自动平减一次失败惩罚系数。
- **🎲 冷却抖动（Jitter）**：为解锁时间添加 ±12.5% 随机离散度，彻底消除上游惊群效应。
- **🎯 定向金丝雀探测**：支持针对具体目标模型进行轻量级单 Token 连通性探测。
- **📊 TTFT 百分位数（p50 / p95 / p99）**：在高精健康度指标中计算首字延迟百分位数。
- **🔔 Webhook 警报聚合摘要**：在 5 秒窗口内将突发告警合并为单一结构化事件摘要，支持 Telegram/Discord/Slack。
- **🧹 30 天用量压缩**：自动清理超过 30 天的历史统计数据，保障长期运行内存上限。
- **✨ 乐观 UI 与快速筛选标签**：一键重置即时生效，密钥列表新增 `全部`、`就绪`、`冷却中`、`故障` 状态筛选胶囊。
在高吞吐量自主智能体运行、多子智能体并行执行与多轮工具调用场景下，API 极易触发上游服务商的速率限制（HTTP 429 Too Many Requests、RPM/TPM 耗尽、每日配额限制或网络抖动）。在原生的 DeepSeek Harness 中，单个密钥耗尽会导致整个智能体执行链路崩溃，破坏会话的 Replay 状态并要求人工干预。
**`dsh-key-rotation`** 基于 Cordis 微内核架构构建，提供了无缝透明的 **API 密钥池轮换、客户端预判限流（Token Bucket）与跨提供商故障转移（Failover Cascade）** 解决方案。
与修改模型提供商 ID 的传统网关代理不同，`dsh-key-rotation` 通过运行时拦截 `ctx.credentials.resolve` 与 `llm/stream` 钩子工作：
* **保持提供商身份一致**：仅切换底层解析的 API 密钥，维持 `pi-ai` 多轮会话与工具状态 100% 一致。
* **令牌桶预判限流**：在发起网络请求前预先跳过已饱和的密钥，彻底消除重试网络延迟。
* **最小连接数并发控制**：动态均衡各密钥的 In-Flight 并发流，防止并发突发拥塞。
* **金丝雀自愈与级联**：通过轻量 Sandbox 探测探活冷却密钥，密钥全耗尽时自动级联到备用提供商。
---
## 🏗️ 架构与请求生命周期
```mermaid
graph LR
subgraph ClientLayer ["客户端与智能体层"]
UserMsg["用户 / 智能体消息"] --> Adapter["pi-ai 模型适配器"]
end
subgraph RotationEngine ["dsh-key-rotation 核心引擎"]
Adapter --> StreamHook["llm/stream 拦截器"]
StreamHook --> BucketCheck{"Token Bucket\nRPM / TPM 校验"}
BucketCheck -->|未超限| ConcurrencyCheck{"并发跟踪器\n最小连接数"}
BucketCheck -->|已超限| NextKey1["选取下一可用密钥"]
ConcurrencyCheck -->|有空闲槽位| KeyResolver["ctx.credentials.resolve"]
ConcurrencyCheck -->|槽位已满| NextKey1
KeyResolver --> ActiveKey["活跃密钥 (执行中)"]
ActiveKey -.->|HTTP 429 / Quota / 错误| Failover["即时故障转移"]
Failover --> BackoffCalc["指数退避与隔离"]
Failover --> NextKey2["重试下一密钥 (零 Token 丢失)"]
Failover -.->|所有密钥均在冷却中| CascadeEngine["跨提供商级联"]
BackoffCalc --> QuotaWindow["日历重置 / 午夜对齐窗口"]
BackoffCalc --> CanaryProbe["金丝雀探针 (Sandbox Ping)"]
CanaryProbe -->|探活成功| PoolReady["恢复至就绪池"]
end
subgraph UpstreamLayer ["上游服务商端点"]
ActiveKey --> UpstreamAPI["主要提供商 API"]
CascadeEngine --> FallbackAPI["备用提供商 API"]
end
style ClientLayer fill:#1e1e2e,stroke:#89b4fa,stroke-width:2px,color:#cdd6f4
style RotationEngine fill:#181825,stroke:#cba6f7,stroke-width:2px,color:#cdd6f4
style UpstreamLayer fill:#11111b,stroke:#a6e3a1,stroke-width:2px,color:#cdd6f4
```
---
## ✨ 核心功能详解
### 🔄 1. 透明轮换与即时故障转移
* **维持提供商标识一致**：轮换仅替换底层解析的凭证引用，不改变 Provider ID，彻底避免 `INVALID_REPLAY_STATE` 异常。
* **零 Token 丢失重试**：在首个内容块发出前发生错误时，无感重试并切换至池中下一个健康密钥。
* **全状态码支持**：支持 `QUOTA`、`RATE_LIMIT`、`SERVER`、`TIMEOUT`、`TRANSPORT`、`EMPTY_RESPONSE`、`UNKNOWN_MODEL`、`AUTH` 等。
* **正则消息模式分类**：内置 `SWITCHABLE_MESSAGE_PATTERN` 正则引擎，自动识别 SDK 抛出的非结构化配额与限流异常。
* **非流式安全防护**：通过 `agent/request-error` 生命周期钩子保护 Embeddings 及 Batch 调用。
### ⏱️ 2. 预判限流与并发控制
* **Token Bucket 令牌桶 (`lib/bucket.js`)**：滑动窗口跟踪每分钟请求数 (`rpmLimit`) 与 Token 数 (`tpmLimit`)，预先拦截超限密钥。
* **最小连接负载均衡 (`lib/concurrency.js`)**：实时追踪每把密钥的活跃流数量 (`inFlight`)，执行 `maxConcurrency` 限制。
* **死锁自动释放**：针对网络异常中断连接，超时 5 分钟自动清理占用计数。
### 🛡️ 3. 自动愈合与跨提供商级联
* **跨提供商故障转移级联 (`lib/cascade.js`)**：主提供商密钥全部冷却时，自动级联路由到备用提供商池。
* **沙箱密钥探测 (`lib/sandbox.js`)**：按需对密钥执行 `/models` 探测后再回到轮换；空闲冷却由 self-heal sweep 解除。
* **配额日历重置对齐 (`lib/quota-window.js`)**：支持 `midnight_utc`、`midnight_pst` 与 `rolling_24h` 配额刷新窗口。
* **自适应指数退避 (`lib/pool.js`)**：连续失败使冷却时间呈指数递增（基准 → ×2 → ×4 → 上限 ×8）。
### 📊 4. 统计分析与多平台交互式 Webhook
* **交互式 Webhook (`lib/webhook.js`)**：向 **Telegram**、**Discord**、**Slack** 推送带交互按钮的富文本警报，可在移动聊天中一键重置冷却或暂停提供商。
* **使用量与成本报表 (`lib/usage-report.js`)**：按日统计各密钥请求数与预估成本，支持一键导出 CSV/JSON (`GET /dsh-key-rotation/usage-report`)。
* **延迟 SLO 监控 (`lib/histogram.js`)**：记录首字延迟（TTFT）与健康度评分 (`0..100`)。
---
## 🖥️ Web GUI 控制台 (**设置 → 密钥轮换**)
| 功能 | 说明 |
|---|---|
| **顶部状态栏微件** | DSH 顶栏实时健康徽章：🟢 正常 \| 🟡 存在冷却 \| 🔴 密钥池耗尽，点击弹出快速操作面板。 |
| **一键健康矩阵** | 运行全量密钥与模型并行沙箱测试，直观展示 HTTP 状态码与 TTFT 首字延迟。 |
| **一键凭证录入** | 点击添加自动生成规范名称（`
