@goodandready/dsh-clinebot 0.3.7 → 0.3.9

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to `@goodandready/dsh-clinebot` will be documented in this f
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.9] - 2026-09-15
+
+### Added
+- **Stale-While-Revalidate (SWR) Quota Caching**: Integrated SWR caching into `fetchUsageLimits` with a 20-second TTL. Instantaneous (<2ms) responses on `/dsh-clinebot/status` and `/dsh-clinebot/usage` with background revalidation.
+- **Smart Quota-Aware Failover**: Account rotation automatically skips exhausted accounts (>=95% 5h usage) and selects the account with the lowest `percentUsed`. Supports auto-recovery once `resetsAt` timestamp is reached.
+- **One-Click In-App Updater (`/dsh-clinebot/update`)**: Added canonical DSH updater endpoint (`lib/updater.js`) validating loopback origin, same-origin, and `x-dsh-plugin-update` header for safe in-app upgrades.
+- **Complete Chinese Localization (`zh`)**: Added comprehensive native Chinese dictionary (67+ translation keys) to `lib/client.js`.
+- **DSH Canon Compliance**: Cleanly separated external Russian translation (supplied via `dsh-russian-lang`), and normalized all slash command outputs to canonical English.
+
+### Fixed
+- **Code Deduplication**: Eliminated duplicate credential and account pool helper functions between `lib/index.js` and `lib/cline-client.js`.
+- **Network Keep-Alive & Cloudflare Handling**: Enforced persistent keep-alive connections on outbound requests and improved error extraction on HTML challenge responses.
+
+## [0.3.8] - 2026-09-12
+
+### Added
+- **Stale-While-Revalidate (SWR) Network Probe** (Issue #18): Introduced in-memory SWR caching (`probeCache`) with 25s TTL for host health probes (`probeHealth`), reducing settings card status endpoint latency from ~500ms to <1ms on repeated calls while revalidating asynchronously in the background.
+- **HTTP Keep-Alive Connection Reuse**: Added persistent `keepalive: true` connection options across all HTTP calls (`probeHealth`, `smokeChat`, `fetchUsageLimits`) to eliminate recurrent TCP/TLS handshakes to `api.cline.bot`.
+- **Auto-Failover Account Rotation**: Implemented `rotateToNextAccount` to automatically rotate active accounts in the configured pool when encountering HTTP 429 rate limits or 100% quota exhaustion, instantly synchronizing DSH `llm-pi-ai` credentials without restarting.
+- **Accurate Token Telemetry**: Extracted real usage metrics (`prompt_tokens`, `completion_tokens`, `total_tokens`) from chat completion responses, replacing static estimation counters.
+- **Expanded Slash-Commands**: Extended `/cline` chat command with `/cline test [model]` (live smoke verification), `/cline ping` (real-time host connectivity test), and `/cline rotate` (manual failover).
+- **Curated Models Catalog Expansion**: Added Claude 3.7 Sonnet (Hybrid Reasoning), GPT-4.5 Preview, o3-mini, Gemini 2.5 Pro / Flash, and Qwen 2.5 Coder 32B to the official `CLINE_MODELS` catalogue.
+- **Debounced Model Picker Toggles**: Added 280ms debounce for model exclusion persistence in `lib/client.js`, providing 0ms UI checkbox responsiveness and preventing network request thrashing.
+
 ## [0.3.7] - 2026-09-10
 
 ### Fixed

package/README.md

@@ -18,10 +18,20 @@
 
 <p align="center">
   <a href="README.md"><b>🇬🇧 English</b></a> •
-  <a href="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
-  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</b></a>
+  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
+      <br><br>
+      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -37,6 +47,9 @@ Integrating ClinePass into DeepSeek Harness (DSH) natively poses key challenges:
 4. **Credential Security**: Storing API keys directly in plain settings is insecure.
 
 **`@goodandready/dsh-clinebot`** provides a complete solution:
+* 🚀 **One-Click In-App Updater**: Upgrade `@goodandready/dsh-clinebot` directly from the DSH UI or trigger secure loopback updates via `/dsh-clinebot/update`.
+* ⚡ **SWR Quota & Health Caching**: Instantaneous response time (<2ms) on status queries with background revalidation.
+* 🔀 **Smart Quota-Aware Failover**: Automatic multi-account rotation skipping exhausted accounts and recovering when `resetsAt` is reached.
 * 🖥️ **Dedicated Settings Page**: Full-width page in DSH Settings (`Settings → ClineBot`).
 * 🔄 **Dynamic Subscription Model Sync**: Automatically pulls real models included in your ClinePass plan directly from `GET /api/v1/users/me/plan` with one-click DSH provider sync.
 * ⚠️ **Quota Exhaustion Alerts**: Real-time visual warning banners when 5-hour rolling limit reaches 80% (warning) and 95% (exhausted), complete with countdown to reset.

package/README.ru.md

@@ -0,0 +1,199 @@
+# 📦 @goodandready/dsh-clinebot
+
+<div align="center">
+
+<h3>Нативное подключение провайдера ClineBot / ClinePass для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.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-clinebot.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/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="Все проекты автора"></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>
+
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
+      <br><br>
+      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+**ClinePass** (`https://cline.bot`) — сервис единой фиксированной подписки (\$9.99/мес), предоставляющий разработчикам повышенные лимиты (в 2–5 раз выше стандартных) на передовые open-weights модели программирования и рассуждений через единый OpenAI-совместимый интерфейс (`https://api.cline.bot/api/v1`).
+
+Интеграция ClinePass в DeepSeek Harness (DSH) напрямую сопряжена со следующими сложностями:
+1. **Отсутствие эндпоинта `/v1/models`**: запрос `GET /v1/models` к `api.cline.bot` возвращает `404 Not Found`, из-за чего динамический поиск моделей в DSH падает или оставляет список пустым.
+2. **Специфический формат идентификаторов**: моделям требуется обязательный префикс `cline-pass/` (например, `cline-pass/deepseek-v4-flash`, `cline-pass/kimi-k3`).
+3. **Отслеживание лимитов**: 5-часовые и недельные скользящие окна расхода токенов требуют прозрачной визуализации в интерфейсе.
+4. **Безопасность ключей**: хранение API-токенов в открытых конфигурациях небезопасно.
+
+Плагин **`@goodandready/dsh-clinebot`** решает эти задачи «из коробки»:
+* 🚀 **Обновление в один клик**: Обновление плагина прямо из интерфейса DSH или через защищённый loopback-эндпоинт `/dsh-clinebot/update`.
+* ⚡ **SWR-кэширование квот и здоровья**: Мгновенный ответ (<2 мс) на запросы статуса с фоновым обновлением данных без блокировки UI.
+* 🔀 **Smart Quota-Aware Failover**: Интеллектуальная ротация аккаунтов с обходом исчерпанных лимитов и авто-восстановлением при наступлении `resetsAt`.
+* 🖥️ **Отдельная страница в Настройках**: собственная полноэкранная страница в меню Настроек DSH (`Настройки → ClineBot`).
+* 🔄 **Динамическая синхронизация моделей подписки**: автоматическое получение реального списка моделей из `GET /api/v1/users/me/plan` и мгновенное обновление провайдера DSH в один клик.
+* ⚠️ **Предупреждения об исчерпании квоты**: баннеры предупреждения при достижении 80% (внимание) и 95% (исчерпано) 5-часового лимита с таймером сброса.
+* 📈 **Метрики сессии**: учет количества запросов, расчетных токенов (Prompt / Completion), задержки и времени последнего вызова.
+* 📊 **Дашборд лимитов подписки (Usage)**: наглядные прогресс-бары расхода 5-часового и недельного скользящего окна из официального API `GET /users/me/plan/usage-limits`.
+* 🔑 **Сохранение ключа прямо из UI**: поле ввода ключа с маскировкой; сохранение напрямую в системный сервис `credentials` (`~/.dsh/.credentials.yaml`) без ручной правки файлов на сервере.
+* 🎯 **Управление моделями в пикере**: включение/выключение отображения конкретных моделей в диалогах чата.
+* 💬 **Слэш-команда `/cline` в чате**: просмотр остатка квот, предупреждений, статистики сессии, задержки и активной модели прямо из чата.
+
+---
+
+## 🏛️ Архитектура
+
+```mermaid
+graph LR
+    subgraph UI [Интерфейс DSH]
+        Page["Отдельная страница (Настройки -> ClineBot)"]
+        QuotaBar["Прогресс-бары 5h и недельного лимита + Баннер предупреждений"]
+        KeyInput["Ввод и сохранение API-ключа"]
+        ModelPick["Динамическая синхронизация моделей и пикер"]
+        StatsCard["Метрики и статистика текущей сессии"]
+    end
+
+    subgraph PluginHost [Хост-часть dsh-clinebot]
+        HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
+        ClientCore["lib/cline-client.js"]
+        ModelCatalog["lib/models.js (Встроенные + Динамические из плана)"]
+        SlashCmd["Слэш-команда: /cline"]
+    end
+
+    subgraph DSHCore [Сервисы DSH]
+        Credentials["Сервис credentials (~/.dsh/.credentials.yaml)"]
+        PiAi["Настройки: llm-pi-ai.providers.clinebot"]
+    end
+
+    subgraph Upstream [Сервер Cline]
+        ClinePass["api.cline.bot/api/v1/chat/completions"]
+        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
+        ClinePlan["api.cline.bot/api/v1/users/me/plan"]
+    end
+
+    Page -->|GET /status & /usage| HttpEndpoints
+    KeyInput -->|POST /save-key| HttpEndpoints
+    ModelPick -->|POST /models/sync| HttpEndpoints
+    HttpEndpoints --> Credentials
+    HttpEndpoints --> ClientCore
+    ClientCore --> ModelCatalog
+    HttpEndpoints -->|Атомарная мутация| PiAi
+    ClientCore -->|Чат| ClinePass
+    ClientCore -->|Квоты| ClineQuota
+    ClientCore -->|Тарифный план| ClinePlan
+```
+
+---
+
+## ✨ Структура модулей и возможности
+
+* **`lib/models.js`**: каталог встроенных моделей ClinePass (11 моделей) и парсер моделей подписки (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
+* **`lib/cline-client.js`**:
+  * `fetchUsageLimits`: параллельный опрос `GET /users/me/plan/usage-limits`, `GET /users/me/plan` и `GET /users/me` с кэшированием в памяти.
+  * `sessionStats` / `recordSessionRequest`: счетчики сессии (запросы, токены, задержка, время).
+  * `saveCredentialKey`: атомарная запись ключей в `~/.dsh/.credentials.yaml`.
+  * `smokeChat`: замер задержки и тестовый пинг с фиксацией статистики.
+  * `buildPiAiProvider`: генерация конфигурации провайдера для `llm-pi-ai` (`api: 'openai-completions'`).
+* **`lib/index.js`**: сервис Cordis, регистрация системных маршрутов (включая `/dsh-clinebot/models/sync`), расчет порогов предупреждения квоты и слэш-команды `/cline`.
+* **`lib/client.js`**: полнофункциональный раздел настроек (`settings.section`, order 28) с баннерами предупреждений, карточкой статистики сессии, кнопкой синхронизации моделей плана и аккордеоном плагина (`settings.plugin.item`).
+
+---
+
+## 📦 Установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-clinebot
+```
+
+Перезапустите экземпляр DeepSeek Harness и обновите вкладку в браузере.
+
+---
+
+## 💬 Слэш-команда `/cline` в чате
+
+В любой сессии чата введите команду `/cline` для проверки остатка лимитов, предупреждений и статистики:
+
+```text
+### 🤖 ClinePass Status (ClinePass ($9.99/mo))
+* Пинг хоста: ✅ 210 мс
+* Активный ключ: CLINEBOT_API_KEY (credentials)
+* Модель по умолчанию: `cline-pass/deepseek-v4-flash`
+
+⏱ 5-часовое окно: [████░░░░░░] 42% (сброс: 18:00)
+📅 Недельное окно: [██████░░░░] 60% (сброс: 08.09)
+* Аккаунт: `developer@example.com`
+
+📈 Статистика текущей сессии:
+* Запросов: 14 вызовов
+* Токены: ~8,450 (Промпт: 6,100 | Ответ: 2,350)
+* Задержка последнего ответа: 210 мс
+```
+
+---
+
+## ⚙️ Таблица конфигурации (`settings.yaml`)
+
+```yaml
+dsh-clinebot:
+  enabled: true
+  baseUrl: https://api.cline.bot/api/v1
+  apiKeyEnv: CLINEBOT_API_KEY
+  defaultModel: cline-pass/deepseek-v4-flash
+  timeoutMs: 15000
+  smokeTimeoutMs: 25000
+  enabledModels:
+    - cline-pass/deepseek-v4-flash
+    - cline-pass/deepseek-v4-pro
+    - cline-pass/kimi-k3
+    - cline-pass/qwen3.7-max
+  dynamicModels: []
+```
+
+### Параметры конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|
+| `enabled` | `boolean` | `true` | Включение моста провайдера ClineBot |
+| `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | Базовый URL OpenAI-совместимого API ClinePass |
+| `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Имя переменной / ключа в хранилище credentials |
+| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Модель, выбираемая по умолчанию |
+| `timeoutMs` | `number` | `15000` | Таймаут HTTP-запросов (мс) |
+| `smokeTimeoutMs` | `number` | `25000` | Таймаут тестового пинга (мс) |
+| `enabledModels` | `array` | `[...]` | Список моделей, активных в селекторе чата |
+| `dynamicModels` | `array` | `[]` | Динамические модели, автоматически синхронизированные из тарифа |
+
+---
+
+## 🧪 Тестирование
+
+Запуск автоматического набора тестов:
+
+```bash
+npm test
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/README.zh.md

@@ -0,0 +1,201 @@
+# 📦 @goodandready/dsh-clinebot
+
+<div align="center">
+
+<h3>适用于 DeepSeek Harness 的 ClineBot / ClinePass 原生模型提供商伴侣插件</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-clinebot"><img src="https://img.shields.io/npm/v/@goodandready/dsh-clinebot.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-clinebot.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/作者所有开源项目-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="所有项目"></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>
+
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。
+      <br><br>
+      🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。
+    </td>
+  </tr>
+</table>
+
+</div>
+
+---
+
+## ⚡ 概述与解决的核心痛点
+
+**ClinePass** (`https://cline.bot`) 是一项固定月费（\$9.99/月）的高性价比订阅服务，为开发者提供主流开源代码模型与推理模型 2–5 倍的高并发调用限额，统一通过 OpenAI 兼容接口 (`https://api.cline.bot/api/v1`) 提供服务。
+
+在将 ClinePass 接入 DeepSeek Harness (DSH) 时存在以下挑战：
+1. **缺失 `/v1/models` 接口**：`api.cline.bot` 的 `GET /v1/models` 会直接返回 `404 Not Found`，导致动态模型同步失败或模型列表为空。
+2. **专属模型前缀**：所有模型 ID 均需前缀 `cline-pass/`（如 `cline-pass/deepseek-v4-flash`, `cline-pass/kimi-k3`）。
+3. **用量额度监控**：5 小时滑动窗口与每周限额需要清晰直观的可视化进度监控。
+4. **安全凭据隔离**：禁止在明文配置中直接填写密钥。
+
+**`@goodandready/dsh-clinebot`** 完美解决以上痛点：
+* 🚀 **应用内一键更新**：直接在 DSH 界面检查并升级插件，或通过受保护的 `/dsh-clinebot/update` 进行本地安全更新。
+* ⚡ **SWR 配额与健康状态缓存**：状态查询毫秒级响应（<2ms），并在后台静默更新，不阻塞前端渲染。
+* 🔀 **智能配额故障转移 (Smart Failover)**：多账号池自动轮询，避开耗尽账号并在 `resetsAt` 到达后自动恢复。
+* 🖥️ **专属设置大页**：在 DSH 设置中提供全宽独立页面（`设置 → ClineBot`）。
+* 🔄 **订阅模型动态同步**：从官方 `GET /api/v1/users/me/plan` 自动提取真实包含模型，一键原子级同步至 DSH 提供商配置，无需等待插件更新。
+* ⚠️ **额度耗尽实时预警**：当 5 小时滑动窗口达到 80%（警告黄色）和 95%（即将耗尽红色）时展示醒目预警横幅与重置倒计时。
+* 📈 **会话统计与指标看板**：实时追踪请求调用次数、预估 Token（Prompt / Completion）、最近延迟及最后调用时间。
+* 📊 **实时用量仪表盘**：调用官方 `GET /users/me/plan/usage-limits` API，实时渲染 5 小时与每周额度进度条及重置倒计时。
+* 🔑 **界面直存密钥**：在 UI 中直接粘贴 API 密钥，通过 `ctx.credentials.set()` 自动安全保存至 `~/.dsh/.credentials.yaml`。
+* 🎯 **模型选择器管理**：支持勾选开启/关闭特定模型在聊天选择器中的显示。
+* 💬 **聊天斜杠指令 `/cline`**：在任意聊天框快速查询当前配额、预警横幅、会话指标统计、网络延迟与活跃模型。
+
+---
+
+## 🏛️ 架构设计
+
+```mermaid
+graph LR
+    subgraph UI [DSH Web 前端界面]
+        Page["独立配置页 (设置 -> ClineBot)"]
+        QuotaBar["5小时与每周额度进度条 + 额度预警横幅"]
+        KeyInput["API 密钥直填与安全保存"]
+        ModelPick["模型动态同步与选择器管控"]
+        StatsCard["会话指标监控看板"]
+    end
+
+    subgraph PluginHost [dsh-clinebot 宿主运行环境]
+        HttpEndpoints["API 路由: /api/plugins/dsh-clinebot/*"]
+        ClientCore["lib/cline-client.js"]
+        ModelCatalog["lib/models.js (内置精选 + 动态订阅解析)"]
+        SlashCmd["斜杠指令: /cline"]
+    end
+
+    subgraph DSHCore [DSH 核心系统服务]
+        Credentials["凭据存储服务 (~/.dsh/.credentials.yaml)"]
+        PiAi["模型注册: llm-pi-ai.providers.clinebot"]
+    end
+
+    subgraph Upstream [Cline 官方云端]
+        ClinePass["api.cline.bot/api/v1/chat/completions"]
+        ClineQuota["api.cline.bot/api/v1/users/me/plan/usage-limits"]
+        ClinePlan["api.cline.bot/api/v1/users/me/plan"]
+    end
+
+    Page -->|GET /status & /usage| HttpEndpoints
+    KeyInput -->|POST /save-key| HttpEndpoints
+    ModelPick -->|POST /models/sync| HttpEndpoints
+    HttpEndpoints --> Credentials
+    HttpEndpoints --> ClientCore
+    ClientCore --> ModelCatalog
+    HttpEndpoints -->|原子级写入| PiAi
+    ClientCore -->|模型对话| ClinePass
+    ClientCore -->|额度查询| ClineQuota
+    ClientCore -->|套餐信息| ClinePlan
+```
+
+---
+
+## ✨ 核心模块与功能
+
+* **`lib/models.js`**：管理 11 款官方精选内置模型以及套餐模型动态解析器（`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`）。
+* **`lib/cline-client.js`**：
+  * `fetchUsageLimits`：高效并发轮询 `GET /users/me/plan/usage-limits`、`GET /users/me/plan` 与 `GET /users/me` 并进行内存缓存。
+  * `sessionStats` / `recordSessionRequest`：内存级会话度量记录器（请求次数、Token 估算、延迟、时间戳）。
+  * `saveCredentialKey`：将密钥安全写入 `~/.dsh/.credentials.yaml`。
+  * `smokeChat`：毫秒级网络探活与非流式延迟测试，并记录会话指标。
+  * `buildPiAiProvider`：构建 DSH `llm-pi-ai` 兼容的服务商定义 (`api: 'openai-completions'`)。
+* **`lib/index.js`**：Cordis 插件主生命周期服务，注册后端 REST API 路由（含 `/dsh-clinebot/models/sync`）、额度预警计算与 `/cline` 聊天斜杠指令。
+* **`lib/client.js`**：前端设置面板（`settings.section` 序号 28），内含预警横幅、会话指标卡片、一键模型同步按钮及插件折叠卡片。
+
+---
+
+## 📦 快速安装
+
+在 DeepSeek Harness Web 配置中安装：
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-clinebot
+```
+
+重启 DeepSeek Harness 实例并刷新浏览器页面。
+
+---
+
+## 💬 聊天斜杠指令 `/cline`
+
+在任何聊天会话中输入 `/cline` 即可即时检查配额、预警状态与会话指标：
+
+```text
+### 🤖 ClinePass Status (ClinePass ($9.99/mo))
+* 响应延迟: ✅ 210 ms
+* 活跃密钥: CLINEBOT_API_KEY (credentials)
+* 默认模型: `cline-pass/deepseek-v4-flash`
+
+⏱ 5 小时窗口: [████░░░░░░] 42% (重置时间: 18:00)
+📅 每周窗口:   [██████░░░░] 60% (重置时间: 09月08日)
+* 绑定账号: `developer@example.com`
+
+📈 当前会话统计:
+* 请求次数: 14 次
+* Token 估算: ~8,450 (Prompt: 6,100 | Completion: 2,350)
+* 最近延迟: 210 ms
+```
+
+---
+
+## ⚙️ 配置项参考 (`settings.yaml`)
+
+```yaml
+dsh-clinebot:
+  enabled: true
+  baseUrl: https://api.cline.bot/api/v1
+  apiKeyEnv: CLINEBOT_API_KEY
+  defaultModel: cline-pass/deepseek-v4-flash
+  timeoutMs: 15000
+  smokeTimeoutMs: 25000
+  enabledModels:
+    - cline-pass/deepseek-v4-flash
+    - cline-pass/deepseek-v4-pro
+    - cline-pass/kimi-k3
+    - cline-pass/qwen3.7-max
+  dynamicModels: []
+```
+
+### 配置参数说明
+
+| 参数项 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `enabled` | `boolean` | `true` | 是否启用 ClineBot 桥接插件 |
+| `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI 兼容接口地址 |
+| `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | 凭据管理系统中的密钥名称 |
+| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | 默认选中的模型 ID |
+| `timeoutMs` | `number` | `15000` | HTTP 请求超时时间（毫秒） |
+| `smokeTimeoutMs` | `number` | `25000` | 探活测试超时时间（毫秒） |
+| `enabledModels` | `array` | `[...]` | 允许在聊天下拉框中显示的可用模型列表 |
+| `dynamicModels` | `array` | `[]` | 从官方套餐中自动同步的动态模型列表 |
+
+---
+
+## 🧪 测试
+
+运行自动化测试套件：
+
+```bash
+npm test
+```
+
+---
+
+## 📄 许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.ru.md

@@ -17,11 +17,21 @@
 </p>
 
 <p align="center">
-  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <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>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>Если вам нравится этот плагин, поставьте ему звезду на GitHub</strong> — это покажет мне, что плагин вам полезен, и будет мотивировать меня развивать его дальше.
+      <br><br>
+      🐛 <strong>Если вы нашли баг или хотите предложить новый функционал</strong>, создайте issue на GitHub на любом языке — я рассмотрю ваше предложение и реализую полезные идеи в одной из следующих версий плагина.
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -37,6 +47,9 @@
 4. **Безопасность ключей**: хранение API-токенов в открытых конфигурациях небезопасно.
 
 Плагин **`@goodandready/dsh-clinebot`** решает эти задачи «из коробки»:
+* 🚀 **Обновление в один клик**: Обновление плагина прямо из интерфейса DSH или через защищённый loopback-эндпоинт `/dsh-clinebot/update`.
+* ⚡ **SWR-кэширование квот и здоровья**: Мгновенный ответ (<2 мс) на запросы статуса с фоновым обновлением данных без блокировки UI.
+* 🔀 **Smart Quota-Aware Failover**: Интеллектуальная ротация аккаунтов с обходом исчерпанных лимитов и авто-восстановлением при наступлении `resetsAt`.
 * 🖥️ **Отдельная страница в Настройках**: собственная полноэкранная страница в меню Настроек DSH (`Настройки → ClineBot`).
 * 🔄 **Динамическая синхронизация моделей подписки**: автоматическое получение реального списка моделей из `GET /api/v1/users/me/plan` и мгновенное обновление провайдера DSH в один клик.
 * ⚠️ **Предупреждения об исчерпании квоты**: баннеры предупреждения при достижении 80% (внимание) и 95% (исчерпано) 5-часового лимита с таймером сброса.

package/docs/README.zh.md

@@ -17,11 +17,21 @@
 </p>
 
 <p align="center">
-  <a href="../README.md"><b>🇬🇧 English</b></a> •
+  <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>
 
+<table align="center">
+  <tr>
+    <td align="center">
+      ⭐ <strong>如果您喜欢这个插件，请在 GitHub 上为它点亮 Star</strong> — 这能让我知道插件对您有用，并鼓励我继续开发和维护它。
+      <br><br>
+      🐛 <strong>如果您发现 Bug 或希望增加功能</strong>，请使用任意语言在 GitHub 上提交 Issue — 我会评估您的建议，并在后续版本中实现有价值的改进。
+    </td>
+  </tr>
+</table>
+
 </div>
 
 ---
@@ -37,6 +47,9 @@
 4. **安全凭据隔离**：禁止在明文配置中直接填写密钥。
 
 **`@goodandready/dsh-clinebot`** 完美解决以上痛点：
+* 🚀 **应用内一键更新**：直接在 DSH 界面检查并升级插件，或通过受保护的 `/dsh-clinebot/update` 进行本地安全更新。
+* ⚡ **SWR 配额与健康状态缓存**：状态查询毫秒级响应（<2ms），并在后台静默更新，不阻塞前端渲染。
+* 🔀 **智能配额故障转移 (Smart Failover)**：多账号池自动轮询，避开耗尽账号并在 `resetsAt` 到达后自动恢复。
 * 🖥️ **专属设置大页**：在 DSH 设置中提供全宽独立页面（`设置 → ClineBot`）。
 * 🔄 **订阅模型动态同步**：从官方 `GET /api/v1/users/me/plan` 自动提取真实包含模型，一键原子级同步至 DSH 提供商配置，无需等待插件更新。
 * ⚠️ **额度耗尽实时预警**：当 5 小时滑动窗口达到 80%（警告黄色）和 95%（即将耗尽红色）时展示醒目预警横幅与重置倒计时。

package/docs/design/DESIGN.md

@@ -18,7 +18,7 @@ The plugin consists of two runtime boundaries conforming to DSH authoring standa
 * Injects `['slots', 'locale', 'settingsScope']`.
 * Slots strictly and exclusively into `settings.plugin.item` (`key: NS`, `locale: NS`). Standalone top-level `settings.section` registration is omitted to maintain clean primary navigation in DSH and prevent side-list pollution.
 * Uses `refreshMirrorUntilVisible(ctx)` to invalidate and re-read the client settings mirror until the namespace is reported ready by the host.
-* Registers localized `en` and `ru` dictionaries with duplicate-safe guards (`ctx.locale.register()`).
+* Registers localized `en` and `zh` dictionaries with duplicate-safe guards (`ctx.locale.register()`), while Russian translation is modularly supplied by `dsh-russian-lang`.
 * Reactive binding via `((ctx?.get && ctx.get('lanSettings')) || ctx?.settingsScope).bind({ namespace: NS })` with `useSyncExternalStore` guarding against `unavailable` / `loading` snapshot states. Form mutations write directly to `scope.set()`.
 * Uses native design tokens (`--dsw-alias-...`) with full dark/light theme support.
 * Injects isolated style tag tagged with `data-dsh-plugin="dsh-clinebot"`.
@@ -72,3 +72,17 @@ graph LR
 * **Reasoning Effort Support**: Models declaring `reasoningEfforts: ['low', 'medium', 'high', 'max']` expose native thinking controls within the DSH model picker, accompanied by UI badges (`🧠 Reasoning`).
 * **Offline Cold-Start Cache**: Discovered plan models are serialized locally to `modelsCachePath` (`~/.dsh/clinebot-models-cache.json`), ensuring models remain immediately available on cold boot even if the upstream network or Cline API is temporarily unavailable.
 
+
+## 6. Performance, Resilience & Telemetry (v0.3.8)
+* **Stale-While-Revalidate (SWR) Network Probing**: `probeHealth()` utilizes an in-memory SWR cache (`probeCache`) with 25s TTL. Repeated `/status` queries return instantaneously (<1ms latency) with fresh host availability, asynchronously refreshing network latency in the background without blocking the client UI thread.
+* **HTTP Keep-Alive Connection Reuse**: Outbound fetch calls to `api.cline.bot` enforce persistent connection keepalive (`keepalive: true`), eliminating recurrent TLS handshake and TCP connection establishment latency.
+* **Auto-Failover Account Rotation**: When an active account encounters HTTP 429 (Rate Limit) or 100% quota depletion, `rotateToNextAccount()` automatically selects the next configured account in the pool, applies the update to DSH settings, and re-synchronizes credentials in `llm-pi-ai` in real time.
+* **Accurate Token Telemetry**: Real usage metadata (`prompt_tokens`, `completion_tokens`, `total_tokens`) is parsed directly from chat completion responses and tracked in session telemetry (`sessionStats`).
+* **Expanded Slash Commands**: Slash command `/cline` supports `/cline test [model]` (smoke test with latency, response and token metrics), `/cline ping` (real-time host connectivity test), and `/cline rotate` (round-robin active account rotation).
+* **Debounced Model Selection**: Model exclusion checkboxes in `lib/client.js` utilize immediate optimistic UI rendering paired with a 280ms debounced persistence layer, ensuring smooth interaction without request thrashing.
+
+## 7. Stability, SWR Quotas, Smart Failover & One-Click In-App Updater (v0.3.9)
+* **SWR Quota Caching (`fetchUsageLimits`)**: In-memory Stale-While-Revalidate caching for Cline usage limits (20s TTL). Returns quota statistics (<2ms) immediately on `/status` requests while refreshing quota windows in the background.
+* **Smart Quota-Aware Failover**: Account failover evaluates cached rolling limits (5-hour window), automatically prioritizing accounts with the lowest `percentUsed` and respecting `resetsAt` timestamps for automatic account recovery.
+* **One-Click In-App Updater (`/dsh-clinebot/update`)**: Integrates host-side one-click updater (`lib/updater.js`) with security verification (`isTrustedUpdateRequest`: loopback validation, same-origin checks, `x-dsh-plugin-update: 1` header). Allows seamless in-place updates from DSH UI.
+* **Canonical DSH Localization Standard**: Source code complies with canonical DSH standards (English base canon, complete Chinese `zh` locale registration in client, external Russian translation provided by `dsh-russian-lang`). All slash command responses and system logs are localized to English.