# Napkin Tools: DSH Tidewatch
[](https://t.me/press_any_button)
[](https://t.me/writeanynotes)
## [English version](./README.md)
Плавающая карточка-прилив (**tide gauge**) для веб-интерфейса DeepSeek Harness. Она закрепляется рядом с полем ввода и
сразу отвечает на три вопроса: какой тариф действует прямо сейчас, сколько осталось до следующей смены и сколько
потратила текущая сессия.
Карточка следует языку интерфейса DeepSeek Harness (английский, китайский, русский), показывает официальные окна
пик/вне пика **в вашей собственной таймзоне** и форматирует деньги, токены и время через `Intl` для активной локали.
> Это форк проекта [dsh-tidewatch](https://github.com/KhalilYamber/dsh-tidewatch) авторства KhalilYamber (MIT),
> переработанный для международного использования: настоящий i18n вместо захардкоженного китайского, новый дизайн
> карточки и таблица окон в локальном времени. Математика биллинга и структура сессионной проекции взяты из
> оригинального проекта.
## Оглавление
- [Возможности](#возможности)
- [Требования](#требования)
- [Установка](#установка)
- [Обновление и удаление](#обновление-и-удаление)
- [Переход с оригинального 1.x](#переход-с-оригинального-1x)
- [Использование](#использование)
- [Окна пик и вне пика](#окна-пик-и-вне-пика)
- [Модель биллинга](#модель-биллинга)
- [Язык интерфейса](#язык-интерфейса)
- [Темы и официальные примитивы](#темы-и-официальные-примитивы)
- [Структура проекта](#структура-проекта)
- [Поток данных](#поток-данных)
- [Разработка и проверка](#разработка-и-проверка)
- [Известные ограничения](#известные-ограничения)
- [Благодарности](#благодарности)
- [Автор](#автор)
- [Поддержка](#поддержка)
- [Лицензия](#лицензия)
## Возможности
- **Тариф с одного взгляда** — индикатор состояния (янтарный для пика, зелёный для вне пика), название текущей фазы
и живой отсчёт до следующей смены.
- **Линия прилива** — в шапке видно, какая часть текущей фазы уже прошла.
- **Таблица окон в вашей таймзоне** — официальные UTC-окна, разложенные по вашему календарному дню, с отметкой текущей
строки; сам тариф всегда определяется по UTC (официальное определение).
- **Правило выходных** — суббота и воскресенье (календарные дни UTC) считаются по цене вне пика весь день, поэтому
таблица сворачивается в одну строку на весь день.
- **Цены активного тарифа** — промах и попадание кэша на входе, а также цена вывода за 1M токенов для текущей фазы.
- **Токены сессии** — ввод, кэш (чтение + запись), вывод и рассуждения, отформатированные по локали.
- **Стоимость по моделям** — разверните строку стоимости сессии, чтобы увидеть токены и стоимость каждой модели; итог
равен сумме частей.
- **Юани или доллары** — по умолчанию валюта следует языку интерфейса (китайский → CNY, иначе USD); переключение в один
клик и запоминается.
- **Настоящий i18n** — карточка следует языку DeepSeek Harness, содержит словари английского, китайского и русского
языков и сама предлагает русский язык в списке языков.
- **Интеграция с оболочкой** — читает токены темы `--dsw-*` (светлая и тёмная) и предпочитает официальные примитивы
`StateDot`, `Tag`, `Tooltip` и `useDismissOnOutsidePointer`, откатываясь к встроенным реализациям, если оболочка их
не предоставляет.
- **Доступность с клавиатуры** — бейдж и строки-раскрывашки являются настоящими кнопками с фокус-рамками, состояниями
`aria-expanded` / `aria-pressed` и ролью `progressbar` у линии прилива.
## Требования
- Node.js ≥ 20.
- DeepSeek Harness со сборкой, в которой есть команда `dsh plugin` (профиль `web`).
- Больше ничего: таблицы цен встроены, а самому плагину не нужны ни API-ключ, ни доступ в сеть.
## Установка
> Бейдж отображается в веб-интерфейсе, поэтому устанавливать нужно в профиль `web`.
```sh
# Вариант 1: последний main (рекомендуется; следит за репозиторием)
dsh plugin --profile web add github:proDreams/dsh-tidewatch
# Вариант 2: закреплённый тег релиза (воспроизводимая установка)
dsh plugin --profile web add github:proDreams/dsh-tidewatch#v2.0.0
# Вариант 3: тарбол из GitHub-релиза (закреплённый и удобный для офлайна)
dsh plugin --profile web add https://github.com/proDreams/dsh-tidewatch/releases/download/v2.0.0/dsh-tidewatch-2.0.0.tgz
# Локальная директория (для разработки)
dsh plugin --profile web add link:/path/to/dsh-tidewatch
```
После установки перезапустите `dsh web` — справа от поля ввода появится бейдж.
> **npm-пакет `dsh-tidewatch` нам не принадлежит.** В npm лежит только старая копия, опубликованная первоначальным
> автором (1.0.6 от 2026-08-22), с устаревшими ценами и правилами, а этот форк сознательно живёт вне npm. Не
> устанавливайте её и не судите по ней о текущем биллинге — используйте варианты выше.
### Обновление и удаление
```sh
dsh plugin --profile web update dsh-tidewatch # или повторно выполните add выше
dsh plugin --profile web list dsh-tidewatch # установленная версия
dsh plugin --profile web remove dsh-tidewatch # удаление
```
История релизов — в [CHANGELOG.md](CHANGELOG.md).
### Переход с оригинального 1.x
Версия **2.0.0** добавляет i18n-слой, таблицу окон в локальном времени и новый дизайн карточки. Сам биллинг не
изменился.
О двух более ранних исправлениях стоит знать, если вы пользовались оригинальным плагином до 1.1.2:
- **1.1.2 — биллинг V4 Pro.** Официальная сноска (2) на странице цен и запись в changelog от 2026-09-10 заявляют, что
API V4 Pro продолжает работать после 2026-09-14 **с неизменным способом оплаты** (если что-то изменится, об этом
сообщат отдельно). Более ранняя сборка следовала трактовке из новостной страницы и с 2026-09-14 04:00 UTC
направляла `deepseek-v4-pro` на цену Flash, из-за чего вызовы pro **занижались** примерно в 4.4 раза (промах кэша),
7.3 раза (попадание кэша) и 3.3 раза (вывод). Граница смены цены `V4_PRO_RETIRE_BOUNDARY` снова стала
sentinel-значением, поэтому pro всегда считается по собственному прайсу; ветка маршрутизации сохранена — в неё нужно
лишь вписать дату, когда появится официальная.
- **1.1.1 — три ценовые эпохи.** Биллинг начал выбирать тариф по собственному времени вызова, а сессионная проекция
`costUsage` получила `stateVersion` 4. После обновления сохранённые сессии один раз переигрываются, и вызовы с
2026-08-16 по 2026-09-10 восстанавливаются по **первому** расписанию пика (до этого они считались по новым, более
низким ценам). На живой биллинг это не влияет.
## Использование
- Бейдж закрепляется справа от поля ввода и выравнивается с ним по вертикали. Если окно слишком узкое, он переезжает
над полем ввода и никогда не перекрывает ни поле, ни встроенную строку статистики.
- Клик по бейджу разворачивает и сворачивает панель: таблица окон, цены активного тарифа, разбивка токенов и
переключатель валюты.
- Клик по строке **«Стоимость сессии»** разворачивает разбивку стоимости по моделям.
- Переключатель валюты применяется сразу и запоминается; юани показываются с 2 знаками, доллары — с 4.
- Развёрнутая панель никогда не выходит за пределы свободного места над бейджем: её бюджет по высоте измеряется от самого
бейджа, поэтому на маленьком экране она не закрывает поле ввода.
## Окна пик и вне пика
DeepSeek ввёл тарификацию по времени суток 2026-08-17:
| Окно (UTC) | Пекинское время | Тариф |
|---|---|---|
| 01:00 – 04:00 | 09:00 – 12:00 | пик |
| 04:00 – 06:00 | 12:00 – 14:00 | вне пика |
| 06:00 – 10:00 | 14:00 – 18:00 | пик |
| 10:00 – следующие 01:00 | 18:00 – следующие 09:00 | вне пика |
Цена вне пика вдвое ниже цены пика. Карточка определяет тариф по **UTC**-окнам (официальное определение), а таблицу
рисует в таймзоне смотрящего.
**Правило выходных (с 2026-08-23)**: суббота и воскресенье (календарные дни UTC) считаются по цене вне пика весь день,
без переключения; следующее переключение приходится на первое окно пика в понедельник.
## Модель биллинга
- Единица: доллары США за 1M токенов (по официальной странице цен). Стоимость = промах ввода × cacheMiss + вывод ×
output + (чтение кэша + запись кэша) × cacheHit; «вывод» уже включает токены рассуждений.
- **Три ценовые эпохи**, выбираемые по собственному времени вызова (историческая корректность; тарифы перечислены в
порядке попадание кэша / промах кэша / вывод):
| Эпоха | Диапазон (UTC) | Тарифы `deepseek-flash` |
|---|---|---|
| Базовая цена | до 2026-08-16 16:00 | 0.0028 / 0.14 / 0.28 |
| Первое расписание пика | 2026-08-16 16:00 – 2026-09-10 04:00 | пик 0.014 / 0.44 / 1.32, вне пика — половина |
| Новые цены V4.1 Flash | с 2026-09-10 04:00 | пик 0.006 / 0.3 / 1.2, вне пика — половина |
- Каждый вызов считается по тарифу **своего момента события**, поэтому суммы не «плывут» ни на переключении фаз, ни на
смене цен.
- В учёте сумма хранится в долларах. Панель показывает юани по фиксированному курсу 6.67 (совпадает с официальным
прайсом в юанях) либо доллары напрямую.
## Язык интерфейса
Карточка — обычный гражданин DeepSeek Harness: она регистрирует пространство имён `tidewatch` и берёт весь текст из
переводчика фреймворка, поэтому смена языка интерфейса в **Настройки → Язык** сразу переключает и карточку.
| Язык | Статус |
|---|---|
| Английский | встроен (`en`) — язык-фоллбек всей цепочки |
| Китайский (упрощённый) | встроен (`zh`) |
| Русский | встроен (`ru`) и добавляется плагином в список языков |
- DeepSeek Harness поставляет только `zh` и `en`, поэтому русский язык плагин добавляет в список сам. Для остальных
плагинов русский разрешается через английский фоллбек.
- На оболочке без сервиса локалей карточка ориентируется на язык браузера, а не на один захардкоженный язык.
- Текст никогда не собирается из кусочков: каждая строка — это шаблон с `{placeholder}`, принадлежащий языку, а тесты
падают, если словари разойдутся по набору ключей.
## Темы и официальные примитивы
Карточка следует теме DeepSeek Harness через переменные `--dsw-*`, а каждый её собственный токен имеет фоллбек под
схему, поэтому она остаётся корректной и на хосте без слоя темы.
- Поддерживаются и светлая, и тёмная темы; единственный насыщенный цвет — акцент фазы (янтарный или зелёный).
- Цифры набраны моно-шрифтом оболочки с табличными цифрами, поэтому панель читается как прибор.
- Фронтенд предпочитает официальные общие примитивы — `StateDot`, `Tag`, `Tooltip` и `useDismissOnOutsidePointer` — и
откатывается к встроенным реализациям, если в таблице модулей оболочки их нет.
## Структура проекта
```
dsh-tidewatch
├── package.json # манифест dsh.bundle.patch + dsh.client.platform
├── cordis.patch.yml # строка патча бандла
├── scripts/build.sh # сборка: проверка синтаксиса + junction для zod
├── lib/
│ ├── pricing.js # чистые функции: окна, isPeakHour/peakPhaseAt, три ценовые эпохи, costOf
│ ├── index.js # хост: сессионная проекция costUsage (счёт по времени события)
│ └── client.js # браузер: карточка-прилив и словари i18n (бандл __ModuleLoader__)
├── docs/PORTING.md # заметки по адаптации под другие хосты
└── test/verify.mjs # самопроверка чистых модулей (node test/verify.mjs)
```
## Поток данных
```
блоки usage от вызовов модели (события assistant/chunk, assistant/message)
│ lib/index.js: сессионная проекция costUsage (валидация zod-схемой)
▼
корзины токенов + стоимость в USD (тариф по времени события)
│ useProjection('costUsage') (браузер)
▼
lib/client.js: отрисовка карточки (посекундный отсчёт, форматирование Intl, конвертация курса)
```
## Разработка и проверка
```sh
DSH_CHECKOUT=<корень исходников харнесса> bash scripts/build.sh # проверка синтаксиса + junction для zod
node test/verify.mjs # 70 проверок: математика пика, биллинг, i18n, таймзоны
```
Набор тестов материализует настоящий клиентский бандл с заглушкой React и фейковым контекстом плагина, поэтому проверяет
именно поставляемые словари, цепочку фоллбеков, форматирование по локали и таблицу окон по таймзонам, а не их копию.
## Известные ограничения
- **Цены встроены** и покрывают три эпохи (базовая цена / первое расписание пика / новые цены V4.1 Flash); для V4-Pro
используются официальные цены от 2026-08-17. Согласно сноске (2) на официальной странице цен и записи в changelog от
2026-09-10, V4 Pro продолжает обслуживаться после 2026-09-14 **с неизменным способом оплаты**, поэтому pro всегда
считается по собственному прайсу, а `V4_PRO_RETIRE_BOUNDARY` остаётся sentinel-значением до официальной даты.
**При официальном изменении цен обновите вручную оба места — `lib/pricing.js` (биллинг) и константу
`DISPLAY_PRICES` в `lib/client.js` (отображение) — и сохраните вытесненные тарифы как ещё одну историческую эпоху.**
- **Имена моделей**: актуальное — `deepseek-flash` (V4.1 Flash); алиасы `deepseek-v4-flash`,
`deepseek-v4-flash-vision-exp` и `deepseek-v4.1-flash` считаются по текущей цене flash (см. `MODEL_ALIASES`).
- **Тариф определяется строго по UTC** (официальное определение); таблица окон — только отображение в локальном времени.
- **Юани считаются по фиксированному курсу** (6.67 USD → CNY, совпадает с официальным прайсом в юанях), а не по живому
курсу.
## Благодарности
- Оригинальный проект: [dsh-tidewatch](https://github.com/KhalilYamber/dsh-tidewatch) авторства **KhalilYamber** (MIT) —
математика биллинга, модель ценовых эпох и структура сессионной проекции.
- Математика пик/вне пика и форма проекции адаптированы из
[dsh-cost-meter](https://github.com/Han-1413141/dsh-cost-meter) (MIT) и переписаны под минимальный размер.
## Автор
Автор программы: Иван Ашихмин
Telegram для связи: [https://t.me/proDreams](https://t.me/proDreams)
Программа создана в рамках проекта «Код на салфетке».
- Сайт: [https://pressanybutton.ru/](https://pressanybutton.ru/)
- Telegram-канал: [https://t.me/napkincode](https://t.me/napkincode)
## Поддержка
Если вам нравится этот проект и вы хотите поддержать его дальнейшее развитие, рассмотрите возможность доната:
- [Поддержать через YooMoney](https://yoomoney.ru/to/41001431694461)
- [Поддержать через Tribute в Telegram](https://t.me/tribute/app?startapp=dyds)
- [Поддержать через нашего Telegram-бота](https://t.me/napkincode_bot?start=donate)
Ваша поддержка помогает проекту расти и улучшать будущие возможности!
## Лицензия
Проект распространяется под лицензией **MIT**. Это производная работа от dsh-tidewatch авторства KhalilYamber;
оба уведомления об авторских правах сохранены в файле [LICENSE](LICENSE).