前言¶
高吞吐量的智能体工作流、并行子代理集群和多轮工具调用，不可避免地会触及上游 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
