@goodandready/dsh-key-rotation 0.7.30 → 0.7.32

package/README.ru.md

@@ -0,0 +1,254 @@
+# 📦 @goodandready/dsh-key-rotation
+
+<div align="center">
+
+<h3>Прозрачная ротация API-ключей, предиктивный контроль лимитов и межпровайдерный каскадный failover для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-key-rotation"><img src="https://img.shields.io/npm/v/@goodandready/dsh-key-rotation.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-key-rotation.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- Обязательная кнопка перехода на витрину всех проектов -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/🌐_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+### 🛠️ Что нового в версии 0.7.32 (Хотфикс и повышение стабильности)
+- **🔍 Исправление проверки ключей**: Функция `resolveBaseUrl` теперь сопоставляет ref ключа с его пулом, восстанавливая работу живого тестирования моделей.
+- **🛡️ Защита от зацикливания каскада**: Устранена возможность переполнения стека при взаимных кольцевых цепочках failover.
+- **🕒 Точный сброс квот по PST**: Исправлен знак часового смещения UTC-8 для корректного сброса лимитов в полночь по тихоокеанскому времени.
+- **🧹 Очистка таймеров в жизненном цикле**: Таймеры `canaryTimer` и `selfHealTimer` переведены на эффекты Cordis, исключая утечки при горячей перезагрузке.
+- **⚡ Сброс зависших блокировок**: Алгоритм `pickLeastLoaded` теперь учитывает протухшие блокировки при выборе наименее нагруженного ключа.
+- **🌐 Полная китайская локализация**: Добавлен словарь `zh` в веб-интерфейс настроек для соблюдения стандарта трёх языков (EN/RU/ZH).
+
+
+### 🚀 Что нового в версии 0.7.31
+- **⚡ $O(1)$ Накопитель TokenBucket**: Оптимизация математики лимитов до $O(1)$ по времени и без аллокаций памяти с адаптивной синхронизацией по заголовкам.
+- **🛡️ Разделение Soft / Hard сбоев**: Кратковременные сетевые сбои (502/503/таймауты) получают короткий 10-секундный кулдаун без штрафного удвоения.
+- **⏳ Затухание штрафов (Penalty Decay)**: Стабильно работающие ключи автоматически снижают штрафной множитель 1 раз в час.
+- **🎲 Джиттер кулдауна**: Случайный разброс $\pm 12.5\%$ времени разблокировки предотвращает наплыв запросов на апстрим.
+- **🎯 Адресное зондирование модели**: Опция целевого микро-пробинга моделей в Canary Prober.
+- **📊 Перцентили задержки TTFT (p50 / p95 / p99)**: Расчет высокоточных перцентилей задержки первого токена в метриках здоровья.
+- **🔔 Дайджест вебхук-алертов**: Группировка серии быстрых сбоев за 5-секундное окно в единый сводный отчет для Telegram, Discord и Slack.
+- **🧹 30-дневная компактизация**: Автоматическая очистка истории старше 30 дней для защиты от утечек памяти.
+- **✨ Оптимистичный UI и фильтры**: Мгновенный отклик кнопок сброса и статус-пилюли (`Все`, `Готовы`, `В кулдауне`, `С ошибками`) над списком ключей.
+
+
+При активной работе автономных агентов, параллельном запуске субагентов и циклических вызовах инструментов запросы неизбежно упираются в ограничения провайдеров (ошибки HTTP 429 Too Many Requests, исчерпание суточных квот или временные сбои на стороне апстрима). В стандартной конфигурации DeepSeek Harness исчерпание одного API-ключа полностью блокирует цепочку рассуждений агента, ломает сохранённое состояние диалога (Replay State) и требует ручного вмешательства администратора.
+
+**`dsh-key-rotation`** реализует отказоустойчивую корпоративную архитектуру **пулов API-ключей с предиктивным контролем лимитов (Token Bucket) и каскадным переключением на резервных провайдеров**, нативно интегрированную в микроядро Cordis.
+
+В отличие от внешних прокси-маршрутизаторов, подменяющих идентификаторы моделей, `dsh-key-rotation` работает на уровне перехвата `ctx.credentials.resolve` и хука `llm/stream`:
+* **Идентичность провайдера остаётся неизменной**: Внутреннее Replay-состояние агента `pi-ai` и контекст инструментов остаются на 100% консистентными.
+* **Предиктивный Token Bucket**: Перегруженные ключи пропускаются **до** выполнения сетевого запроса, устраняя задержку на сетевой ретрай.
+* **Балансировка Least-Connections**: Запросы равномерно распределяются по свободным ключам с контролем параллелизма (`maxConcurrency`).
+* **Автономное самовосстановление и каскад**: Фоновые canary-зонды проверяют заблокированные ключи, а при полном исчерпании пула запрос бесшовно передаётся запасному провайдеру.
+
+---
+
+## 🏗️ Архитектура и жизненный цикл запроса
+
+```mermaid
+graph LR
+    subgraph ClientLayer ["Уровень клиента и агента"]
+        UserMsg["Сообщение агента / пользователя"] --> Adapter["Адаптер модели pi-ai"]
+    end
+
+    subgraph RotationEngine ["Ядро dsh-key-rotation"]
+        Adapter --> StreamHook["Перехватчик llm/stream"]
+        StreamHook --> BucketCheck{"Token Bucket\nПроверка RPM / TPM"}
+        BucketCheck -->|В пределах нормы| ConcurrencyCheck{"Трекер параллелизма\nLeast-Connections"}
+        BucketCheck -->|Лимит исчерпан| NextKey1["Выбор следующего здорового ключа"]
+        ConcurrencyCheck -->|Слот свободен| KeyResolver["ctx.credentials.resolve"]
+        ConcurrencyCheck -->|Слот занят| NextKey1
+        
+        KeyResolver --> ActiveKey["Активный ключ (в работе)"]
+        
+        ActiveKey -.->|HTTP 429 / Quota / Ошибка| Failover["Мгновенный failover"]
+        Failover --> BackoffCalc["Экспоненциальный бэкофф и карантин"]
+        Failover --> NextKey2["Повтор со следующим ключом (без потери токенов)"]
+        Failover -.->|Все ключи в кулдауне| CascadeEngine["Межпровайдерный каскад"]
+        
+        BackoffCalc --> QuotaWindow["Календарный сброс / Полночь UTC/PST"]
+        BackoffCalc --> CanaryProbe["Active Canary-зонд (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. Прозрачная ротация и мгновенный Failover
+* **Сохранение сессии агента**: Ротация подменяет только физический API-токен, оставляя неизменным ID провайдера. Исключает падения `INVALID_REPLAY_STATE` в мульти-инструментальных сценариях.
+* **Бесшовный повтор до отдачи чанков**: Если ключ падает с ошибкой до начала генерации первого токена, запрос прозрачно перенаправляется на следующий доступный ключ.
+* **Полный спектр кодов переключения**: Авто-переключение при ошибках `QUOTA`, `RATE_LIMIT`, `SERVER`, `TIMEOUT`, `TRANSPORT`, `EMPTY_RESPONSE`, `UNKNOWN_MODEL`, `AUTH` и `INVALID`.
+* **Интеллектуальный парсер текста ошибок**: Регулярные выражения (`SWITCHABLE_MESSAGE_PATTERN`) распознают текстовые сообщения об исчерпании лимитов, которые SDK провайдеров выбрасывают как неструктурированные исключения.
+* **Защита нестриминговых вызовов**: Синхронные операции (эмбеддинги, батч-оценки) защищены хуком `agent/request-error`.
+
+### ⏱️ 2. Предиктивный Token Bucket и контроль параллелизма
+* **Token Bucket / Leaky Bucket (`lib/bucket.js`)**: Скользящее минутное окно отслеживания запросов (`rpmLimit`) и токенов (`tpmLimit`). Блокирует исчерпанный ключ **до** отправки запроса в сеть, исключая потерю времени на сетевой 429.
+* **Балансировщик Least-Connections (`lib/concurrency.js`)**: Отслеживает активные in-flight соединения на каждом ключе (`inFlight`). Равномерно распределяет параллельную нагрузку и соблюдает лимит `maxConcurrency`.
+* **Авто-очистка зависших блокировок**: При аварийном разрыве сетевых соединений счетчики соединений автоматически очищаются через 5 минут.
+
+### 🛡️ 3. Автономное самовосстановление и каскадный Failover
+* **Межпровайдерный каскад (`lib/cascade.js`)**: При исчерпании всех ключей выбранного провайдера запрос автоматически каскадируется на настроенного резервного провайдера (`cascade: [{ provider, model }]`).
+* **Active Canary Prober (`lib/canary.js`)**: Перед выводом ключа из кулдауна плагин выполняет легкий фоновый зонд (`/models` probe через `SandboxRunner`), защищая боевой трафик от повторных сбоев.
+* **Календарный сброс квот (`lib/quota-window.js`)**: Учитывает окна сброса суточных квот провайдеров (`midnight_utc`, `midnight_pst`, `rolling_24h`), снимая карантин ровно в момент обновления лимитов у апстрима.
+* **Экспоненциальный бэкофф (`lib/pool.js`)**: Повторные сбои на ключе прогрессивно увеличивают время кулдауна (базовое → ×2 → ×4 → максимум ×8).
+
+### 🎯 4. Маршрутизация по моделям и гео-регионам
+* **Модельные подпулы (`lib/pool.js`)**: Назначение выделенных ключей под конкретные модели (например, отдельные ключи для тяжелых reasoning-моделей и дешевые ключи для утилит).
+* **Тегирование ключей**: Метки приоритета (`production`, `background`, `eval`) для разделения квот между интерактивными и фоновыми задачами.
+* **Гео-роутинг (`lib/region.js`)**: Маршрутизация запросов через оптимальные региональные эндпоинты.
+
+### 📊 5. Телеметрия, аналитика и интерактивные вебхуки
+* **Интерактивные вебхуки (`lib/webhook.js`)**: Отправка форматированных алертов с кнопками действий в **Telegram** (Inline Keyboards), **Discord** (Action Rows) и **Slack** (Block Kit). Администратор может сбросить кулдаун или отключить провайдер прямо из мессенджера.
+* **Отчеты об использовании и расходах (`lib/usage-report.js`)**: Учет суточного числа запросов и расчетной стоимости по каждому ключу с экспортом в CSV/JSON (`GET /dsh-key-rotation/usage-report`).
+* **Гистограмма задержек SLO (`lib/histogram.js`)**: Измерение времени до первого токена (TTFT) и расчет индекса здоровья пула (`0..100`).
+* **Автоматические инциденты (`lib/incident.js`)**: Создание issue в GitHub при масштабных системных сбоях провайдеров.
+* **Shadow-трафик (`lib/shadow.js`)**: Теневое дублирование процента запросов для тестирования альтернативных провайдеров.
+
+---
+
+## 🖥️ Панель управления в Web GUI
+
+Управление доступно в разделе **Настройки → Ротация ключей** или через быстрый виджет в шапке.
+
+| Элемент интерфейса | Описание |
+|---|---|
+| **Виджет в шапке / статусбаре** | Компактный статус: 🟢 `Все в норме` \| 🟡 `Есть ключи в кулдауне` \| 🔴 `Пул исчерпан` с быстрым всплывающим меню. |
+| **Матрица здоровья (1-Click Matrix)** | Интерактивная таблица "Health Matrix" с параллельным зондированием всех ключей, моделей и отображением задержки TTFT. |
+| **Быстрое добавление ключей** | Добавление ключа в 1 клик с автогенерацией имени (`<PROVIDER>_API_KEY`, `_2`, `_3`) и маскировкой. |
+| **Живые бейджи статуса** | Индикаторы: `Используется`, `Готов`, `Остывает` (с живым таймером обратного отсчета) и `Не найден`. |
+| **Приоритет ключей** | Кнопки <kbd>↑</kbd> и <kbd>↓</kbd> для настройки точного порядка перебора в пуле. |
+| **Чекбоксы кодов ошибок** | Наглядные переключатели условий срабатывания ротации. |
+| **Детектор утечек секретов** | Валидация форматов токенов (`lib/keycheck.js`) и защита от случайной вставки приватных SSH/RSA-ключей. |
+| **Импорт из `.env`** | Массовая загрузка пар `KEY=value` из файлов конфигурации. |
+| **Отмена действий (5 сек)** | Всплывающая плашка отмены при случайном удалении ключа или пула. |
+| **График активности** | Наглядная статистика запросов и динамики использования ключей. |
+
+---
+
+## 🔒 Безопасность и хранение секретов
+
+* **Никаких открытых секретов в конфигурации**: В настройках плагина хранятся только имена переменных окружения (например, `PROVIDER_API_KEY`).
+* **Защищённое хранилище хоста**: Реальные значения ключей сохраняются в `$DSH_HOME/.credentials.yaml` сервисом `Credentials`.
+* **Маскировка в браузере (5 символов)**: Браузер получает только последние 5 символов ключа для визуального отличия.
+* **Ограничение Loopback**: Все управляющие маршруты (`GET /status`, `PUT /key`, `POST /reset`, `POST /test-matrix`) строго проверяют loopback-происхождение запроса (`isTrustedBridgeRequest`).
+
+---
+
+## 📦 Установка
+
+```bash
+# Установка через менеджер плагинов DSH (профиль web):
+dsh plugin --profile web add @goodandready/dsh-key-rotation
+
+# Или напрямую из GitHub:
+dsh plugin --profile web add github:GooDAnDReaDY/dsh-key-rotation
+```
+
+> [!IMPORTANT]
+> После установки перезапустите веб-сервис DeepSeek Harness и обновите вкладку браузера:
+> ```bash
+> systemctl --user restart dsh-web
+> ```
+
+---
+
+## ⚙️ Пример конфигурации (`settings.yaml`)
+
+```yaml
+dsh-key-rotation:
+  switchCodes:
+    - QUOTA
+    - RATE_LIMIT
+    - SERVER
+    - TIMEOUT
+    - TRANSPORT
+    - EMPTY_RESPONSE
+    - UNKNOWN_MODEL
+    - AUTH
+  cooldownMs: 60000
+  canaryProbing: true
+  concurrencyLimit: 5
+  quotaResetWindow:
+    type: midnight_utc
+    hour: 0
+  cascade:
+    - provider: backup-provider-id
+      model: your-backup-model-id
+  webhookUrl: "https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>"
+  providers:
+    - provider: your-primary-provider
+      rpmLimit: 60
+      tpmLimit: 100000
+      keys:
+        - PRIMARY_API_KEY
+        - PRIMARY_API_KEY_2
+        - PRIMARY_API_KEY_BACKUP
+    - provider: secondary-provider
+      keys:
+        - SECONDARY_API_KEY
+        - SECONDARY_API_KEY_2
+```
+
+### Таблица параметров
+
+| Параметр | Тип | По умолчанию | Описание |
+|---|---|---|---|
+| `switchCodes` | `string[]` | `[QUOTA, RATE_LIMIT, ...]` | Список кодов ошибок, инициирующих немедленный переход на следующий ключ. |
+| `cooldownMs` | `number` | `60000` (1 мин) | Базовая длительность нахождения ключа в карантине (в мс). |
+| `canaryProbing` | `boolean` | `true` | Фоновая проверка ключа canary-зондом перед возвратом из карантина. |
+| `concurrencyLimit` | `number` | `0` (отключено) | Лимит одновременных активных запросов на ключ (0 = без ограничений). |
+| `quotaResetWindow` | `object` | `null` | Календарное расписание сброса квот (`midnight_utc`, `midnight_pst`, `rolling_24h`). |
+| `cascade` | `array` | `[]` | Цепочка резервных провайдеров при исчерпании всех ключей основного пула. |
+| `webhookUrl` | `string` | `""` | URL вебхука для интерактивных алертов в Telegram, Discord или Slack. |
+| `providers` | `array` | `[]` | Список определений пулов `{ provider, keys, rpmLimit, tpmLimit, modelPools }`. |
+
+---
+
+## 🔌 Справочник HTTP Bridge API
+
+Все служебные маршруты требуют локальной авторизации (`127.0.0.1` / `::1`) и проверки Same-Origin:
+
+| Маршрут | Метод | Описание |
+|---|---|---|
+| `/dsh-key-rotation/status` | `GET` | Текущий снимок состояния здоровья, активных ключей и кулдаунов. |
+| `/dsh-key-rotation/config` | `GET` / `PUT` | Чтение и изменение активных параметров ротации и пулов провайдеров. |
+| `/dsh-key-rotation/key` | `PUT` / `DELETE` | Добавление, обновление или удаление ключей в хранилище и пуле. |
+| `/dsh-key-rotation/reset` | `POST` | Мгновенный сброс всех кулдаунов и возврат ключей в статус `ready`. |
+| `/dsh-key-rotation/test-matrix` | `POST` | Запуск параллельного тестирования всей матрицы ключей и моделей. |
+| `/dsh-key-rotation/usage-report` | `GET` | Получение сводного отчета использования в формате JSON или CSV (`?format=csv`). |
+| `/dsh-key-rotation/webhook-callback`| `POST` | Обработка интерактивных действий от кнопок в Telegram/Slack. |
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md

@@ -0,0 +1,215 @@
+# 📦 @goodandready/dsh-key-rotation
+
+<div align="center">
+
+<h3>适用于 DeepSeek Harness 的企业级无感 API 密钥轮换、预判限流与跨提供商故障转移引擎</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-key-rotation"><img src="https://img.shields.io/npm/v/@goodandready/dsh-key-rotation.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-key-rotation.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
+  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
+</p>
+
+<!-- 展厅链接 -->
+<p align="center">
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/🌐_DSH_Hub-goodandready.app-ff4500.svg?style=for-the-badge&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
+</p>
+
+<p align="center">
+  <a href="README.md"><b>🇬🇧 English</b></a> •
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
+</p>
+
+</div>
+
+---
+
+## ⚡ 概述与核心痛点
+
+### 🛠️ v0.7.32 版本新特性 (稳定性与问题修复)
+- **🔍 修复密钥探测 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/canary.js`)**：密钥出冷却期前，自动发起轻量探测验证上游可用性，避免影响用户真实请求。
+* **配额日历重置对齐 (`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`)。
+* **影子流量测试 (`lib/shadow.js`)**：支持配置百分比的流量镜像复制以评估次要提供商。
+
+---
+
+## 🖥️ Web GUI 控制台 (**设置 → 密钥轮换**)
+
+| 功能 | 说明 |
+|---|---|
+| **顶部状态栏微件** | DSH 顶栏实时健康徽章：🟢 正常 \| 🟡 存在冷却 \| 🔴 密钥池耗尽，点击弹出快速操作面板。 |
+| **一键健康矩阵** | 运行全量密钥与模型并行沙箱测试，直观展示 HTTP 状态码与 TTFT 首字延迟。 |
+| **一键凭证录入** | 点击添加自动生成规范名称（`<PROVIDER>_API_KEY`, `_2`, `_3`），悬停显示尾号。 |
+| **实时状态徽章** | 实时显示：`使用中`、`就绪`、`冷却中`（带倒计时）以及 `凭证未找到`。 |
+| **拖拽与顺序调整** | 使用 <kbd>↑</kbd> 和 <kbd>↓</kbd> 按钮调整轮换优先级。 |
+| **密钥泄漏探测器** | 实时校验输入格式（`sk-...` 等），防止误贴私钥或无关 Token。 |
+| **批量 `.env` 导入** | 支持文件导入解析并自动填充至对应提供商池。 |
+| **5 秒撤销栏** | 误删密钥或提供商时提供 5 秒快速撤销操作。 |
+
+---
+
+## 🔒 安全性与凭证存储
+
+* **配置零明文**：插件配置仅保存环境变量引用名（如 `MY_PROVIDER_API_KEY`）。
+* **宿主安全存储**：真实密钥持久化保存在 `$DSH_HOME/.credentials.yaml`。
+* **前台 5 字符脱敏**：前端仅展示密钥后 5 位字符进行视觉区分。
+* **环回安全隔离**：管理接口严格限制来自本地同源请求 (`isTrustedBridgeRequest`)。
+
+---
+
+## 📦 安装指南
+
+```bash
+# 通过 DSH 插件管理器安装 (Web Profile):
+dsh plugin --profile web add @goodandready/dsh-key-rotation
+
+# 或直接从 GitHub 安装:
+dsh plugin --profile web add github:GooDAnDReaDY/dsh-key-rotation
+```
+
+> [!IMPORTANT]
+> 安装后请重启 DSH Web 服务并刷新浏览器页面：
+> ```bash
+> systemctl --user restart dsh-web
+> ```
+
+---
+
+## ⚙️ 配置示例 (`settings.yaml`)
+
+```yaml
+dsh-key-rotation:
+  switchCodes:
+    - QUOTA
+    - RATE_LIMIT
+    - SERVER
+    - TIMEOUT
+    - TRANSPORT
+    - EMPTY_RESPONSE
+    - UNKNOWN_MODEL
+    - AUTH
+  cooldownMs: 60000
+  canaryProbing: true
+  concurrencyLimit: 5
+  quotaResetWindow:
+    type: midnight_utc
+    hour: 0
+  cascade:
+    - provider: backup-provider-id
+      model: your-backup-model-id
+  webhookUrl: "https://api.telegram.org/bot<TOKEN>/sendMessage?chat_id=<CHAT_ID>"
+  providers:
+    - provider: your-primary-provider
+      rpmLimit: 60
+      tpmLimit: 100000
+      keys:
+        - PRIMARY_API_KEY
+        - PRIMARY_API_KEY_2
+        - PRIMARY_API_KEY_BACKUP
+    - provider: secondary-provider
+      keys:
+        - SECONDARY_API_KEY
+        - SECONDARY_API_KEY_2
+```
+
+---
+
+## 📄 开源许可
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/cordis.patch.yml

@@ -1,7 +1,7 @@
-# dsh-key-rotation bundle layer.
-# Registers the virtual provider route "rotation"; the adapter delegates each
-# request to the configured clone routes of the matching backend and rotates
-# them on switchable failures (QUOTA / RATE_LIMIT / ...).
-- insert:
-    - id: dsh-key-rotation
+# dsh-key-rotation bundle layer.
+# Registers the virtual provider route "rotation"; the adapter delegates each
+# request to the configured clone routes of the matching backend and rotates
+# them on switchable failures (QUOTA / RATE_LIMIT / ...).
+- insert:
+    - id: dsh-key-rotation
       name: '@goodandready/dsh-key-rotation'

package/lib/agent-budget.js

@@ -1,68 +1,68 @@
-// lib/agent-budget.js — per-agent rate cap.
-// ponytail: in-memory counter per (agent, window), thread-safe-ish via timer map.
-
-export const AGENT_BUDGET_DEFAULT_WINDOW_MS = 3600_000; // 1h
-export const AGENT_BUDGET_DEFAULT_LIMIT = 0;             // 0 = disabled
-export const AGENT_BUDGET_MAX = 50000;                  // hard ceiling per agent
-
-export class AgentBudget {
-  constructor({ windowMs = AGENT_BUDGET_DEFAULT_WINDOW_MS, limit = AGENT_BUDGET_DEFAULT_LIMIT } = {}) {
-    const w = Number.isFinite(windowMs) && windowMs > 0 ? Math.floor(windowMs) : AGENT_BUDGET_DEFAULT_WINDOW_MS;
-    const l = Number.isFinite(limit) && limit >= 0 ? Math.min(AGENT_BUDGET_MAX, Math.floor(limit)) : 0;
-    this._windowMs = w;
-    this._limit = l;
-    this._state = new Map(); // agent -> { hits: number[], windowStart: epochMs }
-  }
-
-  isEnabled() {
-    return this._limit > 0;
-  }
-
-  // Decide if request from this agent is allowed. Returns { allowed, remaining, resetAt }.
-  // Records the hit only when allowed.
-  check(agentId, now = Date.now()) {
-    if (!this.isEnabled()) return { allowed: true, remaining: Infinity, resetAt: null };
-    if (!agentId || typeof agentId !== 'string') return { allowed: false, remaining: 0, resetAt: now };
-    let s = this._state.get(agentId);
-    if (!s) {
-      s = { hits: [], windowStart: now };
-      this._state.set(agentId, s);
-    }
-    // Window: prune hits older than windowStart + windowMs
-    const cutoff = now - this._windowMs;
-    while (s.hits.length > 0 && s.hits[0] < cutoff) s.hits.shift();
-    s.windowStart = s.hits.length ? s.hits[0] : now;
-    if (s.hits.length >= this._limit) {
-      const resetAt = s.hits[0] + this._windowMs;
-      return { allowed: false, remaining: 0, resetAt };
-    }
-    s.hits.push(now);
-    return { allowed: true, remaining: this._limit - s.hits.length, resetAt: now + this._windowMs };
-  }
-
-  // Reset single agent or all
-  reset(agentId) {
-    if (agentId) this._state.delete(agentId);
-    else this._state.clear();
-  }
-
-  // Inspect-only: return remaining without recording.
-  peek(agentId, now = Date.now()) {
-    if (!this.isEnabled()) return { remaining: Infinity, resetAt: null };
-    const s = this._state.get(agentId);
-    if (!s) return { remaining: this._limit, resetAt: null };
-    const cutoff = now - this._windowMs;
-    let count = 0;
-    for (let i = 0; i < s.hits.length; i++) {
-      if (s.hits[i] >= cutoff) count += 1;
-    }
-    const oldest = s.hits[0];
-    return { remaining: this._limit - count, resetAt: oldest ? oldest + this._windowMs : null };
-  }
-
-  snapshot() {
-    const out = {};
-    for (const [k, v] of this._state) out[k] = { hits: v.hits.length };
-    return out;
-  }
-}
+// lib/agent-budget.js — per-agent rate cap.
+// ponytail: in-memory counter per (agent, window), thread-safe-ish via timer map.
+
+export const AGENT_BUDGET_DEFAULT_WINDOW_MS = 3600_000; // 1h
+export const AGENT_BUDGET_DEFAULT_LIMIT = 0;             // 0 = disabled
+export const AGENT_BUDGET_MAX = 50000;                  // hard ceiling per agent
+
+export class AgentBudget {
+  constructor({ windowMs = AGENT_BUDGET_DEFAULT_WINDOW_MS, limit = AGENT_BUDGET_DEFAULT_LIMIT } = {}) {
+    const w = Number.isFinite(windowMs) && windowMs > 0 ? Math.floor(windowMs) : AGENT_BUDGET_DEFAULT_WINDOW_MS;
+    const l = Number.isFinite(limit) && limit >= 0 ? Math.min(AGENT_BUDGET_MAX, Math.floor(limit)) : 0;
+    this._windowMs = w;
+    this._limit = l;
+    this._state = new Map(); // agent -> { hits: number[], windowStart: epochMs }
+  }
+
+  isEnabled() {
+    return this._limit > 0;
+  }
+
+  // Decide if request from this agent is allowed. Returns { allowed, remaining, resetAt }.
+  // Records the hit only when allowed.
+  check(agentId, now = Date.now()) {
+    if (!this.isEnabled()) return { allowed: true, remaining: Infinity, resetAt: null };
+    if (!agentId || typeof agentId !== 'string') return { allowed: false, remaining: 0, resetAt: now };
+    let s = this._state.get(agentId);
+    if (!s) {
+      s = { hits: [], windowStart: now };
+      this._state.set(agentId, s);
+    }
+    // Window: prune hits older than windowStart + windowMs
+    const cutoff = now - this._windowMs;
+    while (s.hits.length > 0 && s.hits[0] < cutoff) s.hits.shift();
+    s.windowStart = s.hits.length ? s.hits[0] : now;
+    if (s.hits.length >= this._limit) {
+      const resetAt = s.hits[0] + this._windowMs;
+      return { allowed: false, remaining: 0, resetAt };
+    }
+    s.hits.push(now);
+    return { allowed: true, remaining: this._limit - s.hits.length, resetAt: now + this._windowMs };
+  }
+
+  // Reset single agent or all
+  reset(agentId) {
+    if (agentId) this._state.delete(agentId);
+    else this._state.clear();
+  }
+
+  // Inspect-only: return remaining without recording.
+  peek(agentId, now = Date.now()) {
+    if (!this.isEnabled()) return { remaining: Infinity, resetAt: null };
+    const s = this._state.get(agentId);
+    if (!s) return { remaining: this._limit, resetAt: null };
+    const cutoff = now - this._windowMs;
+    let count = 0;
+    for (let i = 0; i < s.hits.length; i++) {
+      if (s.hits[i] >= cutoff) count += 1;
+    }
+    const oldest = s.hits[0];
+    return { remaining: this._limit - count, resetAt: oldest ? oldest + this._windowMs : null };
+  }
+
+  snapshot() {
+    const out = {};
+    for (const [k, v] of this._state) out[k] = { hits: v.hits.length };
+    return out;
+  }
+}