@goodandready/dsh-cost-meter 0.7.4 → 0.7.5

package/README.md

@@ -1,78 +1,134 @@
-# dsh-cost-meter
+# 📦 @goodandready/dsh-cost-meter
 
-Чип стоимости сессии в шапке диалога DeepSeek Harness: живой расход по токенам,
-текущий тариф (пик / не-пик), обратный отсчёт до его смены и карточка настроек.
+<div align="center">
 
-```
-● ≈ ₽8.55  0:17     ← чип в conversation.session.header.utilities
-```
+<h3>Live Session Cost Chip, Peak/Off-Peak Tariff Switcher & Token Pricing for DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-cost-meter"><img src="https://img.shields.io/npm/v/@goodandready/dsh-cost-meter.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-cost-meter.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>
+
+<!-- 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="GoodAndReady Showcase"></a>
+</p>
 
-По клику раскрывается панель: тарифная таблица за 1M токенов в двух колонках
-(не-пик / пик, активная выделена), окна пика в UTC и итог за сессию с разбивкой по моделям.
+<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>
+</p>
 
-## Возможности
+</div>
 
-- **Живой подсчёт расхода**: инкрементальный расчёт токенов и стоимости прямо во время стриминга ответа.
-- **Двухуровневые тарифы**: поддержка официальной сетки DeepSeek (пик / не-пик) и скидочных окон OpenRouter.
-- **Provider-aware маршрутизация**: раздельная тарификация для прямых моделей DeepSeek и хостинга моделей через OpenRouter.
-- **Учёт по получасовым слотам UTC**: исторические траты фиксируются по ставке слота и не пересчитываются задним числом.
-- **Карточка настроек в UI**: нативная карточка в `settings.plugin.item` для настройки валюты, курса USD и таймзоны.
-- **Полная двуязычная локализация**: интерфейс чипа, панели и настроек на русском и английском языках (`ctx.locale`).
+---
 
-## Откуда берутся цифры
+## ⚡ Overview & The Problem
 
-**Токены** — из собственной проекции сессии `costByModel`, которую плагин
-регистрирует тем же механизмом, что и штатный `@deepseek-ai/dsh-token-meter`.
-В журнале есть всё нужное: `request/header` несёт `config: {provider, model}`,
-а usage приходит следом за тем же шагом, поэтому каждая выборка относится к
-модели, которая её заработала.
+AI development and agentic coding consume large volumes of tokens across prompt generation, reasoning, and context caches. Without continuous financial feedback, developers risk unexpected billing spikes, missing off-peak discount windows, or failing to identify runaway subagent expenses.
+
+**`@goodandready/dsh-cost-meter`** embeds a high-precision cost telemetry chip directly into the DeepSeek Harness conversation header (`conversation.session.header.utilities`):
+
+```text
+● ≈ $0.12  0:17     ← Live session cost chip with tariff countdown
+```
 
-Накопление идёт не одной кучей, а по **получасовым слотам суток UTC**: расход
-фиксируется по ставке, действовавшей в момент трат, и переключение тарифа не
-пересчитывает уже потраченное. Все реальные окна выровнены по получасу, так что
-слот воспроизводит ставку точно.
+Clicking the chip expands an interactive breakdown modal displaying 1M token rate tables across peak and off-peak tiers, active UTC window status, and per-model session expenditure summaries.
+
+---
+
+## 🏛️ Architecture
+
+```mermaid
+graph TD
+    subgraph StreamTelemetry ["DeepSeek Harness Runtime"]
+        Req["LLM Request / Header<br/>(provider, model)"]
+        StreamHook["Incremental Streaming Chunks"]
+        Proj["costByModel Projection<br/>(30-min UTC Slots)"]
+    end
+
+    subgraph PricingCatalog ["Tariff Resolution Engine"]
+        Manual["Manual Config Rates<br/>(settings.yaml: prices)"]
+        DeepSeekTier["DeepSeek Official Tier<br/>(Peak vs Off-Peak 50% discount)"]
+        OpenRouterTier["OpenRouter API Catalog<br/>(Cached Daily)"]
+    end
+
+    subgraph UI ["User Interface Surfaces"]
+        Chip["Header Cost Chip<br/>(Active tariff + countdown)"]
+        Modal["Breakdown Drawer<br/>(Rates per 1M, UTC windows, model table)"]
+        Settings["Settings Card<br/>(Currency, USD rate, timezones)"]
+    end
+
+    Req --> Proj
+    StreamHook --> Proj
+    Proj --> Chip
+    PricingCatalog --> Proj
+    Manual --> PricingCatalog
+    DeepSeekTier --> PricingCatalog
+    OpenRouterTier --> PricingCatalog
+    Chip --> Modal
+```
 
-Сессионный слот отдаёт компоненту `useProjection`, поэтому значения обновляются
-прямо во время стрима, без опроса.
+---
 
-**Цены** берутся из трёх источников, в таком порядке:
+## ✨ Features & Key Capabilities
 
-1. **Ручные `prices`** из конфига — для подписок и локальных моделей.
-2. **Provider-aware каталог**:
-   - Если указан провайдер `openrouter`, ставки берутся из каталога OpenRouter (даже для моделей `deepseek/*`).
-   - Для прямых моделей DeepSeek применяется официальная зашитая тарифная сетка: пик 01:00–04:00 и 06:00–10:00 UTC, вне окон — льготная ставка 50%.
-3. **Каталог OpenRouter** (`https://openrouter.ai/api/v1/models`, без ключа) —
-   для всех остальных моделей. Каталог кэшируется на диск в runtime-директории профиля и обновляется раз в сутки.
+1. **Incremental Streaming Telemetry**: Computes prompt, completion, and cache read/write tokens in real-time without polling or UI stutter.
+2. **Dual-Tier Tariff Engine**: Official DeepSeek peak windows (01:00–04:00 and 06:00–10:00 UTC) with automatic 50% off-peak discount detection.
+3. **UTC Half-Hour Slot Immutability**: Historical session expenditure is permanently anchored to the rate active at the moment of execution.
+4. **Provider-Aware Routing**: Distinguishes direct provider connections from hosted gateways (e.g. OpenRouter vs native endpoints).
+5. **Interactive UI Modal & Settings**: Custom currency symbols (`$`, `€`, `₽`, `¥`), exchange rates, and timezone configurations.
 
-Если модель не нашлась нигде, виджет пишет «тариф ?», а в разбивке сессии выводит `не указана стоимость`.
+---
 
-## Установка
+## 📦 Installation
 
 ```bash
 dsh plugin --profile web add @goodandready/dsh-cost-meter
 ```
 
-## Настройки
+Restart your DeepSeek Harness instance and refresh the browser.
+
+---
+
+## ⚙️ Configuration Reference (`settings.yaml`)
+
+```yaml
+dsh-cost-meter:
+  currency: "$"
+  usdRate: 1.0
+  displayTimeZone: "UTC"
+  useOpenRouter: true
+  prices: {}
+  modelMap: {}
+```
+
+### Configuration Parameters
+
+| Parameter | Type | Default | Description |
+|:---|:---|:---|:---|
+| `currency` | `string` | `"$"` | Display currency symbol or code |
+| `usdRate` | `number` | `1.0` | Exchange rate multiplier from USD |
+| `displayTimeZone` | `string` | `"UTC"` | Timezone for window schedule formatting (e.g. `Europe/London`, `Asia/Shanghai`) |
+| `useOpenRouter` | `boolean` | `true` | Fetch OpenRouter public catalog for fallback models |
+| `prices` | `object` | `{}` | Custom override rates per 1M tokens `{ prompt, completion, cacheRead?, cacheWrite? }` |
+| `modelMap` | `object` | `{}` | Model alias mappings `{ "alias": "target-model" }` |
 
-Плагин регистрирует секцию конфигурации `dsh-cost-meter`:
+---
 
-| Параметр | По умолчанию | Описание |
-|---|---|---|
-| `currency` | `₽` | Символ или код валюты для отображения |
-| `usdRate` | `90` | Множитель пересчёта долларовых цен в валюту отображения |
-| `displayTimeZone` | `UTC` | Таймзона для отображения окон в панели (например, `Europe/Moscow`) |
-| `useOpenRouter` | `true` | Загружать ли каталог цен OpenRouter для сторонних моделей |
-| `prices` | `{}` | Ручные ставки за 1M токенов `{ prompt, completion, cacheRead?, cacheWrite? }` |
-| `modelMap` | `{}` | Алиасы моделей `{ "alias": "target-model" }` |
+## 🧪 Testing
 
-## Тестирование
+Run the automated test suite:
 
 ```bash
 npm test
 ```
 
-Включает проверку контрактных инвариантов публичного пакета и регрессионные тесты проекции и тарификации (`test/projection-lifecycle.test.mjs`).
+---
 
-## Лицензия
+## 📄 License
 
-MIT
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.ru.md

@@ -0,0 +1,134 @@
+# 📦 @goodandready/dsh-cost-meter
+
+<div align="center">
+
+<h3>Чип стоимости сессии, переключатель пиковых тарифов и мониторинг расходов токенов для DeepSeek Harness</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-cost-meter"><img src="https://img.shields.io/npm/v/@goodandready/dsh-cost-meter.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-cost-meter.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>
+
+---
+
+## ⚡ Обзор и решаемая проблема
+
+Разработка с помощью ИИ-агентов и генерация кода требуют активного потребления токенов (промпты, рассуждения, контекстный кэш). Без непрерывного финансового контроля разработчики рискуют столкнуться с перерасходом бюджета или упустить окна 50% скидок внепикового тарифа.
+
+**`@goodandready/dsh-cost-meter`** встраивает компактный высокоточный телеметрический чип прямо в заголовок диалога DeepSeek Harness (`conversation.session.header.utilities`):
+
+```text
+● ≈ ₽8.55  0:17     ← Чип стоимости сессии в шапке с обратным отсчётом тарифа
+```
+
+По клику открывается интерактивная панель: тарифная сетка за 1M токенов (не-пик / пик с подсветкой активного режима), статус окон в UTC и детальная разбивка расходов текущей сессии по моделям.
+
+---
+
+## 🏛️ Архитектура
+
+```mermaid
+graph TD
+    subgraph StreamTelemetry ["Рантайм DeepSeek Harness"]
+        Req["Запрос LLM / Заголовок<br/>(provider, model)"]
+        StreamHook["Потоковые инкрементальные чанки"]
+        Proj["Проекция costByModel<br/>(30-минутные слоты UTC)"]
+    end
+
+    subgraph PricingCatalog ["Движок тарификации"]
+        Manual["Пользовательские цены<br/>(settings.yaml: prices)"]
+        DeepSeekTier["Сетка DeepSeek<br/>(Пик / 50% скидка не-пик)"]
+        OpenRouterTier["Каталог OpenRouter<br/>(Ежедневный кэш)"]
+    end
+
+    subgraph UI ["Интерфейс пользователя"]
+        Chip["Чип стоимости в шапке<br/>(Тариф + таймер смены)"]
+        Modal["Модальное окно разбивки<br/>(Ставки за 1M, окна UTC, модели)"]
+        Settings["Карточка настроек<br/>(Валюта, курс USD, таймзона)"]
+    end
+
+    Req --> Proj
+    StreamHook --> Proj
+    Proj --> Chip
+    PricingCatalog --> Proj
+    Manual --> PricingCatalog
+    DeepSeekTier --> PricingCatalog
+    OpenRouterTier --> PricingCatalog
+    Chip --> Modal
+```
+
+---
+
+## ✨ Ключевые возможности
+
+1. **Живой расчёт во время стриминга**: расчёт стоимости инкрементально обновляется в реальном времени прямо во время генерации ответа.
+2. **Двухуровневая сетка тарифов**: официальные пиковые окна DeepSeek (01:00–04:00 и 06:00–10:00 UTC) со скидкой 50% во внепиковое время.
+3. **Иммутабельность получасовых слотов UTC**: исторические расходы сессии фиксируются по ставке слота и не пересчитываются задним числом при смене тарифа.
+4. **Provider-aware тарификация**: раздельный учёт для прямых подключений DeepSeek и шлюзов OpenRouter.
+5. **Гибкая настройка валюты**: поддержка пользовательских символов валют (`₽`, `$`, `€`, `¥`), курсов конвертации и таймзон.
+
+---
+
+## 📦 Установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-cost-meter
+```
+
+Перезапустите экземпляр DeepSeek Harness и обновите страницу в браузере.
+
+---
+
+## ⚙️ Таблица конфигурации (`settings.yaml`)
+
+```yaml
+dsh-cost-meter:
+  currency: "₽"
+  usdRate: 90.0
+  displayTimeZone: "Europe/Moscow"
+  useOpenRouter: true
+  prices: {}
+  modelMap: {}
+```
+
+### Параметры конфигурации
+
+| Параметр | Тип | По умолчанию | Описание |
+|:---|:---|:---|:---|
+| `currency` | `string` | `"₽"` | Символ или код валюты для отображения |
+| `usdRate` | `number` | `90.0` | Множитель пересчёта долларовых цен в валюту отображения |
+| `displayTimeZone` | `string` | `"UTC"` | Таймзона для отображения окон в панели |
+| `useOpenRouter` | `boolean` | `true` | Загружать ли каталог цен OpenRouter для сторонних моделей |
+| `prices` | `object` | `{}` | Ручные ставки за 1M токенов `{ prompt, completion, cacheRead?, cacheWrite? }` |
+| `modelMap` | `object` | `{}` | Алиасы моделей `{ "alias": "target-model" }` |
+
+---
+
+## 🧪 Тестирование
+
+Запуск набора юнит-тестов:
+
+```bash
+npm test
+```
+
+---
+
+## 📄 Лицензия
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/docs/README.zh.md

@@ -0,0 +1,134 @@
+# 📦 @goodandready/dsh-cost-meter
+
+<div align="center">
+
+<h3>面向 DeepSeek Harness 的会话实时花费计费芯片、波峰/波谷阶梯电价与 Token 监控插件</h3>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@goodandready/dsh-cost-meter"><img src="https://img.shields.io/npm/v/@goodandready/dsh-cost-meter.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-cost-meter.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>
+
+---
+
+## ⚡ 概述与核心痛点
+
+在使用智能体与大语言模型编程时，模型推理、长上下文以及缓存读写会产生大量 Token 消耗。如果缺乏实时的财务监控，开发者容易错过官方 50% 闲时折扣窗口，或因死循环导致账单超出预算。
+
+**`@goodandready/dsh-cost-meter`** 在 DeepSeek Harness 会话顶部工具栏（`conversation.session.header.utilities`）无缝嵌入高精度花费微件芯片：
+
+```text
+● ≈ ¥0.85  0:17     ← 会话顶部实时花费芯片与换价倒计时
+```
+
+点击芯片可展开交互式详情面板：按每 1M Token 展示峰谷两档费率表格（高亮显示当前激活档位）、UTC 优惠时间段状态以及各模型在当前会话中的累计消费明细。
+
+---
+
+## 🏛️ 架构设计
+
+```mermaid
+graph TD
+    subgraph StreamTelemetry ["DSH 流式遥测运行时"]
+        Req["LLM 请求 / 报头<br/>(provider, model)"]
+        StreamHook["增量流式分片 Hook"]
+        Proj["costByModel 会话投影<br/>(半小时 UTC 时隙)"]
+    end
+
+    subgraph PricingCatalog ["费率解析引擎"]
+        Manual["自定义费率配置<br/>(settings.yaml: prices)"]
+        DeepSeekTier["DeepSeek 官方费率<br/>(高峰 / 闲时 50% 折扣)"]
+        OpenRouterTier["OpenRouter 公开目录<br/>(每日自动缓存)"]
+    end
+
+    subgraph UI ["用户交互界面"]
+        Chip["顶部花费芯片<br/>(实时计费 + 换价倒计时)"]
+        Modal["消费明细抽屉面板<br/>(1M 单价表, UTC 时段, 模型清单)"]
+        Settings["设置卡片<br/>(币种符号, 汇率, 时区)"]
+    end
+
+    Req --> Proj
+    StreamHook --> Proj
+    Proj --> Chip
+    PricingCatalog --> Proj
+    Manual --> PricingCatalog
+    DeepSeekTier --> PricingCatalog
+    OpenRouterTier --> PricingCatalog
+    Chip --> Modal
+```
+
+---
+
+## ✨ 核心特性
+
+1. **增量流式实时计算**：在模型打字生成过程中毫秒级更新 Prompt、Completion 和 Cache 费用，无轮询无卡顿。
+2. **两级阶梯电价引擎**：支持 DeepSeek 官方高峰时段（UTC 01:00–04:00 与 06:00–10:00）及闲时 50% 优惠折扣自动匹配。
+3. **UTC 半小时时隙不可变性**：历史消费严格锁定在消耗发生时刻的时隙费率，切换费率不溯及既往。
+4. **服务商智能路由**：精准区分直连 DeepSeek 服务商与 OpenRouter 等代理网关。
+5. **多币种与本地化**：支持自定义货币符号（`¥`, `$`, `€`, `₽`）、汇率换算与显示时区。
+
+---
+
+## 📦 快速安装
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-cost-meter
+```
+
+重启 DeepSeek Harness 实例并刷新浏览器页面。
+
+---
+
+## ⚙️ 配置项说明 (`settings.yaml`)
+
+```yaml
+dsh-cost-meter:
+  currency: "¥"
+  usdRate: 7.2
+  displayTimeZone: "Asia/Shanghai"
+  useOpenRouter: true
+  prices: {}
+  modelMap: {}
+```
+
+### 配置参数列表
+
+| 参数项 | 类型 | 默认值 | 说明 |
+|:---|:---|:---|:---|
+| `currency` | `string` | `"¥"` | 显示的货币符号或代码 |
+| `usdRate` | `number` | `7.2` | 美元到目标货币的换算汇率 |
+| `displayTimeZone` | `string` | `"Asia/Shanghai"` | 界面中优惠时间段显示的参考时区 |
+| `useOpenRouter` | `boolean` | `true` | 是否加载 OpenRouter 价格表作为备用 |
+| `prices` | `object` | `{}` | 自定义每 1M Token 的费率覆盖 |
+| `modelMap` | `object` | `{}` | 模型别名映射表 |
+
+---
+
+## 🧪 自动化测试
+
+运行单元测试套件：
+
+```bash
+npm test
+```
+
+---
+
+## 📄 许可证
+
+MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-cost-meter",
-  "version": "0.7.4",
+  "version": "0.7.5",
   "description": "DeepSeek Harness plugin: a session cost chip in the conversation header - live token usage by bucket, peak/off-peak tariff, and a countdown to the next tariff switch.",
   "type": "module",
   "main": "lib/index.js",