Napkin Tools: DSH Tidewatch

English version

Плавающая карточка-прилив (tide gauge) для веб-интерфейса DeepSeek Harness. Она закрепляется рядом с полем ввода и сразу отвечает на три вопроса: какой тариф действует прямо сейчас, сколько осталось до следующей смены и сколько потратила текущая сессия.

Карточка следует языку интерфейса DeepSeek Harness (английский, китайский, русский), показывает официальные окна пик/вне пика в вашей собственной таймзоне и форматирует деньги, токены и время через Intl для активной локали.

Это форк проекта dsh-tidewatch авторства KhalilYamber (MIT), переработанный для международного использования: настоящий i18n вместо захардкоженного китайского, новый дизайн карточки и таблица окон в локальном времени. Математика биллинга и структура сессионной проекции взяты из оригинального проекта.

Оглавление

• Возможности
• Требования
• Установка
  • Обновление и удаление
  • Переход с оригинального 1.x
• Использование
• Окна пик и вне пика
• Модель биллинга
• Язык интерфейса
• Темы и официальные примитивы
• Структура проекта
• Поток данных
• Разработка и проверка
• Известные ограничения
• Благодарности
• Автор
• Поддержка
• Лицензия

Возможности

• Тариф с одного взгляда — индикатор состояния (янтарный для пика, зелёный для вне пика), название текущей фазы и живой отсчёт до следующей смены.
• Линия прилива — в шапке видно, какая часть текущей фазы уже прошла.
• Таблица окон в вашей таймзоне — официальные 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.

# Вариант 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. Не устанавливайте её и не судите по ней о текущем биллинге — используйте варианты выше.

Обновление и удаление

dsh plugin --profile web update dsh-tidewatch    # или повторно выполните add выше
dsh plugin --profile web list dsh-tidewatch      # установленная версия
dsh plugin --profile web remove dsh-tidewatch    # удаление

История релизов — в 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, конвертация курса)

Разработка и проверка

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 авторства KhalilYamber (MIT) — математика биллинга, модель ценовых эпох и структура сессионной проекции.
• Математика пик/вне пика и форма проекции адаптированы из dsh-cost-meter (MIT) и переписаны под минимальный размер.

Автор

Автор программы: Иван Ашихмин
Telegram для связи: https://t.me/proDreams

Программа создана в рамках проекта «Код на салфетке».

• Сайт: https://pressanybutton.ru/
• Telegram-канал: https://t.me/napkincode

Поддержка

Если вам нравится этот проект и вы хотите поддержать его дальнейшее развитие, рассмотрите возможность доната:

• Поддержать через YooMoney
• Поддержать через Tribute в Telegram
• Поддержать через нашего Telegram-бота

Ваша поддержка помогает проекту расти и улучшать будущие возможности!

Лицензия

Проект распространяется под лицензией MIT. Это производная работа от dsh-tidewatch авторства KhalilYamber; оба уведомления об авторских правах сохранены в файле LICENSE.