@goodandready/dsh-clinebot 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,27 @@ 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.0] - 2026-09-05
+
+### Added
+- **Dynamic Subscription Models Sync**: Added integration with official ClinePass plan endpoint (`GET /api/v1/users/me/plan` -> `features.included`). Models available under the user's subscription plan are parsed dynamically, mapped with fallback IDs, and synced directly to DSH provider configuration without requiring manual updates.
+- **Strict Real Provider Catalog**: Replaced manual custom model entry forms with one-click dynamic synchronization (`POST /dsh-clinebot/models/sync` and UI sync button), eliminating out-of-sync manual model entries and guaranteeing 100% provider alignment.
+- **Rolling Window Quota Exhaustion Warnings**: Added real-time threshold detection and prominent UI warning banners when the 5-hour rolling limit reaches 80% (warning, amber) and 95% (exhausted, red), complete with dynamic countdowns to reset.
+- **Session Metrics & Usage Tracking**: Added in-memory session telemetry displaying total requests executed, estimated prompt/completion/total tokens, last roundtrip latency, and timestamp of the last request in a dedicated UI metrics card.
+- **Extended `/cline` Slash-Command**: Slash-command now outputs quota warning banners and active session metrics (total calls, tokens, last request) alongside rolling window progress bars.
+- **Canonical Deployment Script**: Added `deploy.sh` script conforming to dhsplugins standard for automated profile installation and service restart (Issue #3).
+
+### Fixed
+- **Slot Registration Smell**: Fixed dual unconditional slot registration: plugin card now registers primarily in `settings.plugin.item`, with graceful fallback to `settings.section` if not declared (Issue #5).
+- **Settings Snapshot Status & Reactivity**: Integrated reactive `ctx.settingsScope` binding with `useSyncExternalStore`, checking snapshot status (`ready`, `loading`, `unavailable`) and propagating edits via `scope.set()` (Issue #6).
+- **Slot Locales**: Attached `locale: NS` to slot options and registered localized dictionaries with `ctx.locale.register()` (Issue #7).
+- **Button Hover State**: Fixed CSS button hover visibility regression on primary action buttons.
+
+## [0.2.1] - 2026-09-05
+
+### Fixed
+- **Client Bundle Inject Compatibility**: Resolved client-side inject bundle loading for DSH web profile runtime.
+
 ## [0.2.0] - 2026-09-04
 
 ### Added

package/README.md

@@ -13,13 +13,13 @@
 
 <!-- Author Showcase Link -->
 <p align="center">
-  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="All Projects"></a>
+  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/All_Author_Projects-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&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>
+  <a href="docs/README.ru.md"><b>🇷🇺 Русский</b></a> •
+  <a href="docs/README.zh.md"><b>🇨🇳 中文说明</b></a>
 </p>
 
 </div>
@@ -38,11 +38,13 @@ Integrating ClinePass into DeepSeek Harness (DSH) natively poses key challenges:
 
 **`@goodandready/dsh-clinebot`** provides a complete solution:
 * 🖥️ **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.
+* 📈 **Session Metrics Telemetry**: Live dashboard tracking request counts, token consumption estimates, latency, and last-request timestamp.
 * 📊 **Live Quota Dashboard**: Visual progress bars for 5-hour rolling limits and weekly windows from the official `GET /users/me/plan/usage-limits` API.
 * 🔑 **In-UI Key Storage**: Paste your API key directly in the UI; it is saved securely via `ctx.credentials.set()` into `~/.dsh/.credentials.yaml`.
 * 🎯 **Model Picker Management**: Granular checkboxes to choose which models appear in the chat picker.
-* ➕ **Add Custom Models**: Add newly released ClinePass models directly from the UI without waiting for plugin updates.
-* 💬 **Slash-Command `/cline`**: Check quota, limits, latency, and active model directly from the DSH chat console.
+* 💬 **Slash-Command `/cline`**: Check quota, limits, warnings, session metrics, latency, and active model directly from the DSH chat console.
 
 ---
 
@@ -52,15 +54,16 @@ Integrating ClinePass into DeepSeek Harness (DSH) natively poses key challenges:
 graph LR
     subgraph UI [DSH Web Interface]
         Page["Dedicated Page (Settings -> ClineBot)"]
-        QuotaBar["5-Hour & Weekly Progress Bars"]
+        QuotaBar["5-Hour & Weekly Progress Bars & Warning Banner"]
         KeyInput["Direct Key Paste & Save"]
-        ModelPick["Model Picker Controls & Custom Models"]
+        ModelPick["Dynamic Model Sync & Picker Controls"]
+        StatsCard["Session Metrics Telemetry"]
     end
 
     subgraph PluginHost [dsh-clinebot Host Runtime]
         HttpEndpoints["API: /api/plugins/dsh-clinebot/*"]
         ClientCore["lib/cline-client.js"]
-        ModelCatalog["lib/models.js (Curated + Custom)"]
+        ModelCatalog["lib/models.js (Curated + Dynamic Plan)"]
         SlashCmd["Command: /cline"]
     end
 
@@ -72,17 +75,19 @@ graph LR
     subgraph Upstream [Cline Cloud]
         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 /register & /models| HttpEndpoints
+    ModelPick -->|POST /models/sync| HttpEndpoints
     HttpEndpoints --> Credentials
     HttpEndpoints --> ClientCore
     ClientCore --> ModelCatalog
     HttpEndpoints -->|Atomic Mutate| PiAi
     ClientCore -->|Chat| ClinePass
     ClientCore -->|Usage Limits| ClineQuota
+    ClientCore -->|Plan Features| ClinePlan
 ```
 
 ---
@@ -90,16 +95,17 @@ graph LR
 ## ✨ Features & Module Breakdown
 
 * **`lib/models.js`**:
-  Manages the curated catalog (11 built-in models) and user-added custom models (`getAllModels`, `validateCustomModel`).
+  Manages the curated catalog (11 built-in models) and dynamically parses subscription plan models (`parsePlanIncludedModels`, `getAllModels`, `getDynamicModels`).
 * **`lib/cline-client.js`**:
-  * `fetchUsageLimits`: queries `GET /users/me/plan/usage-limits` and `GET /users/me` with in-memory caching.
+  * `fetchUsageLimits`: queries `GET /users/me/plan/usage-limits`, `GET /users/me/plan`, and `GET /users/me` with in-memory caching.
+  * `sessionStats` / `recordSessionRequest`: in-memory telemetry recording requests count, tokens, latency, and timestamps.
   * `saveCredentialKey`: writes credentials directly into `~/.dsh/.credentials.yaml`.
-  * `smokeChat`: tests latency via non-streaming ping.
+  * `smokeChat`: tests latency via non-streaming ping and updates session metrics.
   * `buildPiAiProvider`: builds the DSH `llm-pi-ai` structure (`api: 'openai-completions'`).
 * **`lib/index.js`**:
-  Cordis service module managing routes, credentials, and registering the `/cline` slash command.
+  Cordis service module managing routes (including `POST /dsh-clinebot/models/sync`), quota warnings threshold evaluation, credentials, and registering the `/cline` slash command.
 * **`lib/client.js`**:
-  Full-featured dedicated Settings section (`settings.section`, order 28) and plugin accordion (`settings.plugin.item`).
+  Full-featured dedicated Settings section (`settings.section`, order 28) with live quota bars, exhaustion warning banner, session metrics telemetry card, one-click plan sync button, and plugin accordion (`settings.plugin.item`).
 
 ---
 
@@ -109,27 +115,36 @@ graph LR
 dsh plugin --profile web add @goodandready/dsh-clinebot
 ```
 
+Restart your DeepSeek Harness instance and refresh the browser.
+
 ---
 
 ## 💬 Slash-Command `/cline`
 
-From any DSH chat session, type `/cline` to inspect quota:
+From any DSH chat session, type `/cline` to inspect quota, warning alerts, and session telemetry:
 
 ```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`
+* Latency: ✅ 210 ms
+* Active Key: CLINEBOT_API_KEY (credentials)
+* Default Model: `cline-pass/deepseek-v4-flash`
+
+⏱ 5-Hour Window: [████░░░░░░] 42% (resets: 18:00)
+📅 Weekly Window: [██████░░░░] 60% (resets: Sep 8)
+* Account: `developer@example.com`
+
+📈 Session Metrics:
+* Requests: 14 calls
+* Tokens: ~8,450 (Prompt: 6,100 | Completion: 2,350)
+* Last Latency: 210 ms
 ```
 
 ---
 
 ## ⚙️ Configuration Reference (`settings.yaml`)
 
+Configure options in `settings.yaml` or directly inside the Web UI:
+
 ```yaml
 dsh-clinebot:
   enabled: true
@@ -143,7 +158,30 @@ dsh-clinebot:
     - cline-pass/deepseek-v4-pro
     - cline-pass/kimi-k3
     - cline-pass/qwen3.7-max
-  customModels: []
+  dynamicModels: []
+```
+
+### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `enabled` | `boolean` | `true` | Enable or disable the ClineBot provider bridge |
+| `baseUrl` | `string` | `"https://api.cline.bot/api/v1"` | ClinePass OpenAI-compatible base URL |
+| `apiKeyEnv` | `string` | `"CLINEBOT_API_KEY"` | Environment variable / credentials key name |
+| `defaultModel` | `string` | `"cline-pass/deepseek-v4-flash"` | Default selected model ID |
+| `timeoutMs` | `number` | `15000` | HTTP request timeout in milliseconds |
+| `smokeTimeoutMs` | `number` | `25000` | Smoke test latency ping timeout |
+| `enabledModels` | `array` | `[...]` | List of models exposed in the DSH chat picker |
+| `dynamicModels` | `array` | `[]` | Dynamic models automatically synced from the official plan |
+
+---
+
+## 🧪 Testing
+
+Run the automated test suite:
+
+```bash
+npm test
 ```
 
 ---

package/docs/README.ru.md

@@ -0,0 +1,186 @@
+# 📦 @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>
+
+</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 (`Настройки → 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/docs/README.zh.md

@@ -0,0 +1,188 @@
+# 📦 @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>
+
+</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 设置中提供全宽独立页面（`设置 → 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/design/DESIGN.md

@@ -0,0 +1,63 @@
+# Design Contract: `@goodandready/dsh-clinebot`
+
+## 1. Executive Summary
+`@goodandready/dsh-clinebot` is a companion plugin for DeepSeek Harness (DSH) enabling native integration of the **ClineBot / ClinePass** subscription provider. Because ClinePass is an OpenAI-compatible endpoint whose `GET /v1/models` returns `404 Not Found`, dynamic discovery is impossible. This plugin acts as the bridge: delivering a curated catalog of open-weights models, securely resolving credentials, exposing health and smoke tests, and mutating the DSH `llm-pi-ai` provider registry.
+
+## 2. Architecture & Cordis Lifecycles
+The plugin consists of two runtime boundaries conforming to DSH authoring standards:
+
+### 2.1 Host Runtime (`lib/index.js`, `lib/cline-client.js`, `lib/models.js`, `lib/http.js`)
+* **Cordis Service Registration**: Injects `['settings', 'webServer', 'credentials']`.
+* **Credential Isolation**: The plugin NEVER stores plain API keys in its configuration. The setting `apiKeyEnv` holds the credential identifier (default: `CLINEBOT_API_KEY`), resolved via `ctx.credentials.resolve()` or `process.env`.
+* **State Synchronization**: Mutates the core `llm-pi-ai` settings space (`op: 'set', path: ['providers', 'clinebot']`) when enabled or registered.
+
+### 2.2 Client Runtime (`lib/client.js`)
+* Self-registering module via `window.__ModuleLoader__.load({ id: '@goodandready/dsh-clinebot', factory })`.
+* Injects `['slots', 'locale', 'settingsScope']`.
+* Slots into `settings.plugin.item` (primary) with `key: NS` and `locale: NS`, and graceful fallback to `settings.section` if not declared.
+* Registers localized `en` and `ru` dictionaries via `ctx.locale.register()`.
+* Reactive binding via `ctx.settingsScope.bind({ namespace: NS })` with `useSyncExternalStore` guarding against `unavailable` / `loading` snapshot states.
+* Uses native design tokens (`--dsw-alias-...`) with full dark/light theme support.
+
+```mermaid
+graph LR
+    subgraph Client [DSH Web Interface]
+        UI[Settings Card: ClineBot]
+        SmokeBtn[Smoke Test Button]
+        RegBtn[Register in DSH Models]
+    end
+
+    subgraph Host [DSH Node.js Runtime]
+        API["HTTP API: /api/plugins/dsh-clinebot/*"]
+        ClientHelper["lib/cline-client.js"]
+        Catalog["lib/models.js (Static 11 Models)"]
+        CredService[DSH Credentials Service]
+        PiAiSettings["DSH Settings: llm-pi-ai"]
+    end
+
+    subgraph Remote [Cline Service]
+        ClineAPI["api.cline.bot/api/v1"]
+    end
+
+    UI -->|GET /status| API
+    SmokeBtn -->|POST /smoke| API
+    RegBtn -->|POST /register| API
+    API --> CredService
+    API --> ClientHelper
+    ClientHelper --> Catalog
+    API -->|Mutate| PiAiSettings
+    ClientHelper -->|POST /chat/completions| ClineAPI
+```
+
+## 3. UI/UX Contract
+* **Badges**:
+  * Host connectivity: `Host online (<ms>)` (green) / `Host unreachable` (red).
+  * Credential presence: `Key ✓ (credentials|env)` (green) / `Key missing` (amber).
+  * Registration status: `DSH Registered` (green) / `Not Registered` (amber).
+* **Model Picker**: Interactive checklist of all 11 official models with multi-select and vision capability indicators.
+* **Non-destructive actions**: Unregister cleanly removes the provider entry from DSH without touching other providers or configurations.
+
+## 4. Security & Isolation
+* CSRF / Cross-site protection: All mutating routes (`/register`, `/unregister`, `/smoke`, `/models`) validate `isTrustedSettingsRequest(req)` (`Sec-Fetch-Site !== 'cross-site'`).
+* Body size limits: Request payloads are strictly capped at 256 KB.
+* Sensitive credential data is never returned across the HTTP API (only `{ present: boolean, source: string, envName: string }`).