前言¶
高吞吐量的智能體工作流、並行子代理集羣和多輪工具調用，不可避免地會觸及上游 API 的速率限制（HTTP 429、RPM/TPM 空耗、每日配額或突發中斷）。在標準的 DeepSeek Harness 部署中，單一的 API Key 耗盡會導致整個智能體執行鏈斷裂，需要手動干預並破壞會話的重放狀態。
dsh-key-rotation 是一個原生基於 Cordis 微內核架構構建的企業級、透明的 API Key 池化、預判速率限制和跨提供商故障轉移引擎。
功能概覽¶
該插件爲每個提供商維護獨立的 Key 池，並在配額/速率限制錯誤時自動切換至下一個 Key。
- API Key 旋轉：按提供商管理密鑰池，自動創建克隆路由。
- 預判速率限制：在發送網絡請求前跳過已限流的 Key。
- 跨提供商故障轉移：當整個 Key 池耗盡時，平滑升級至備用提供商。
- 熔斷機制：連續失敗後開啓熔斷，請求快速失敗直至冷卻。
- Webhook 通知：支持聚合報警，便於監控。
- 自愈能力：定期後臺探測，自動恢復故障 Key。
- 延遲感知路由：支持
round-robin、least-loaded（併發數）和lowest-latency（P95 延遲）策略。 - 原生雙語支持：內置英文和中文 UI 字典。
核心機制¶
與會改變提供商標識的簡單路由代理不同，該插件在運行時鉤入 ctx.credentials.resolve 並攔截 llm/stream。
- 會話一致性：提供商身份保持不變，確保智能體重放狀態、多輪調用和工具模式描述 100% 一致。
- 併發控制：通過
least-loaded策略平衡 Key 之間的活躍流，防止突發飽和。使用確定性的try ... finally塊確保零併發泄漏。 - 錯誤分類與處理：對 408、425、429、5xx、Socket 和 gRPC 錯誤進行顯式分類處理。
- 軟硬退避：區分臨時基礎設施故障（軟退避）和硬性配額錯誤（指數退避）。
- 速率限制計算：使用 O(1) 時間複雜度和零分配內存的 Token Bucket 算法。
資源與狀態管理¶
- 內存管理：採用 30 天滾動窗口數據修剪，自動清理過時 Key 並限制內存增長。
- 時鐘安全：冷卻和熔斷持續時間使用進程單調時鐘，防止 NTP 調整導致剩餘時間倒退。
- 狀態安全：原子 I/O 輔助工具確保崩潰安全寫入；損壞的 JSON 不會覆蓋之前的內存狀態。
- 零阻塞：Webhook 通知通過有界隊列和退避機制處理，流旋轉永遠不會在 Webhook HTTP 上阻塞。
總結¶
該插件解決了智能體開發中因 API Key 限制導致的單點故障問題，提供了企業級的穩定性保障和可視化管理界面。
- 目錄地址：https://www.skillhub.cn/plugins/GooDAnDReaDY/dsh-key-rotation
- GitHub：https://github.com/GooDAnDReaDY/dsh-key-rotation
- 許可證：MIT
- Node 版本要求：>=18
