https://kkucherenkov.github.io/projects/Recent content in Проекты on Kirill's homepageHugoru<a href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank" rel="noopener">CC BY-NC 4.0</a>https://kkucherenkov.github.io/projects/course_shelf/Mon, 01 Jan 0001 00:00:00 +0000https://kkucherenkov.github.io/projects/course_shelf/<h2 id="для-чего">Для чего</h2> <p>Курсы с Udemy и Coursera, записи конференций и воркшопов часто лежат на диске обычными папками. Course Shelf сканирует такую папку и собирает из неё каталог курсов, секций и уроков. Каталог открывается в браузере и в мобильном приложении. Файлы остаются на месте: Course Shelf их не копирует и не перекодирует.</p> <h2 id="библиотека">Библиотека</h2> <ul> <li><strong>Каталог из структуры папок.</strong> Папки и имена файлов задают курсы, секции и порядок уроков. Скан привязывает к урокам субтитры и материалы, которые лежат рядом с видео.</li> <li><strong><code>course.json</code> для точной настройки.</strong> Файл в папке курса задаёт названия, порядок уроков и метаданные поверх того, что вывел скан.</li> <li><strong>Метаданные из сети.</strong> Скраперы берут обложки, описания, авторов и теги с Udemy, Coursera и YouTube. Для других сайтов подходят декларативные определения скраперов и общий разбор schema.org и OpenGraph.</li> <li><strong>Пересканирование курса.</strong> Один курс обновляется без прогона всей библиотеки.</li> </ul> <h2 id="просмотр">Просмотр</h2> <ul> <li><strong>Стриминг без перекодирования.</strong> Видео идёт по HTTP с byte-range, перемотка срабатывает сразу.</li> <li><strong>Прогресс.</strong> Плеер запоминает позицию, продолжает с неё и переходит к следующему уроку. После 90% урок отмечается пройденным.</li> <li><strong>Главная</strong> показывает начатые уроки, свежие поступления, завершённые курсы и статистику просмотра за неделю.</li> <li><strong>Каталог с фильтрами</strong> по статусу, библиотеке, длительности и автору. Фильтры хранятся в адресной строке, и ссылка открывает ту же выборку.</li> <li><strong>Заметки и закладки.</strong> К каждому уроку можно вести заметку в Markdown и ставить закладки на нужную секунду. Заметки видит только их автор.</li> </ul> <h2 id="транскрипты-и-поиск">Транскрипты и поиск</h2> <ul> <li><strong>Локальная расшифровка.</strong> whisper.cpp расшифровывает уроки без субтитров на том же сервере, без облачных API.</li> <li><strong>Поиск</strong> находит курсы и отдельные уроки одним запросом и показывает фрагмент с найденным местом. На десктопе он открывается командной палитрой.</li> <li><strong>Транскрипт рядом с плеером.</strong> Ссылка с <code>?t=</code> открывает урок на нужной секунде.</li> <li><strong>Квизы.</strong> Вопросы по уроку генерирует LLM: локальный llama.cpp или модель через OpenRouter.</li> </ul> <h2 id="мобильное-приложение">Мобильное приложение</h2> <ul> <li><strong>Flutter-клиент</strong> для iOS и Android с тем же каталогом.</li> <li><strong>Загрузки.</strong> Уроки скачиваются с докачкой после обрыва и хранятся на устройстве в зашифрованном виде.</li> <li><strong>Офлайн.</strong> Позиция, заметки и закладки сохраняются на устройстве и уходят на сервер, когда появляется связь. Если на сервере прогресс новее, остаётся серверная версия.</li> </ul> <h2 id="несколько-пользователей">Несколько пользователей</h2> <ul> <li><strong>Доступ по выдаче.</strong> Роли USER и ADMIN, доступ выдаётся на библиотеку целиком или на отдельный курс.</li> <li><strong>Администрирование.</strong> Сводка по инстансу, управление пользователями и вход от имени пользователя, чтобы увидеть его каталог.</li> <li><strong>Бэкап.</strong> Одна кнопка запускает <code>pg_dump</code> и отдаёт ссылку на архив. Медиафайлы в бэкап не входят: Course Shelf ими не владеет.</li> </ul> <h2 id="под-капотом">Под капотом</h2> <p>Монорепо из трёх приложений: бэкенд на NestJS, веб на Nuxt и клиент на Flutter. Контракт API описан один раз, в OpenAPI 3.1 и AsyncAPI 3.0, и клиенты для TypeScript и Dart генерируются из него. Бэкенд отклоняет запросы, которых нет в спецификации, а CI падает, если код разошёлся с контрактом. События скана и фоновых задач приходят в клиенты через Centrifugo. Интерфейс переведён на русский и английский.</p>https://kkucherenkov.github.io/projects/coriolis/Mon, 01 Jan 0001 00:00:00 +0000https://kkucherenkov.github.io/projects/coriolis/<h2 id="для-чего">Для чего</h2> <p>Coriolis: The Third Horizon — научно-фантастическая ролевая игра от Free League в духе «Тысячи и одной ночи». Приложение заменяет бумажные листы и держит партию в общем состоянии: броски, очки Тьмы и чат видят все участники сессии. Фанатский проект, с издателем не связан.</p> <h2 id="для-игроков">Для игроков</h2> <ul> <li><strong>Лист персонажа</strong> по правилам Coriolis: иконы, концепция, происхождение, характеристики от 1 до 5, общие и продвинутые навыки, таланты, снаряжение, состояния, нагрузка, критические травмы.</li> <li><strong>Броски.</strong> Пул D6 с перебросом: шестёрки дают успехи, единицы при перебросе приносят мастеру очки Тьмы.</li> <li><strong>Публичная ссылка на лист</strong> только для чтения, с отдельной настройкой для заметок мастера. Ссылку можно отозвать.</li> <li><strong>Экспорт в JSON</strong> листов, кораблей и истории.</li> <li><strong>Офлайн.</strong> Чтение работает везде. Правки веб сохраняет в очередь ServiceWorker, мобильное приложение — в кэш Hive, и обе очереди уходят на сервер при появлении сети.</li> </ul> <h2 id="для-мастера">Для мастера</h2> <ul> <li><strong>Листы кораблей</strong>: 20 классов, модули, посты экипажа, корпус, энергия, сигнатура, броня, неисправности.</li> <li><strong>Игровые сессии</strong>: приглашение одной ссылкой, роли участников, архив и трекер очков Тьмы с историей.</li> <li><strong>NPC и энкаунтеры</strong>: готовые и свои NPC, конструктор энкаунтеров с инициативой, раундами и ходами.</li> <li><strong>Общий стол в реальном времени.</strong> Броски, очки Тьмы и чат расходятся по участникам через Centrifugo. В чате есть сообщения на всю сессию, личный шёпот, блокировка и системные сообщения.</li> </ul> <h2 id="под-капотом">Под капотом</h2> <p>Три клиента на одном бэкенде: Nuxt-SPA, приложение на Flutter для iOS и Android и бэкенд на NestJS с Postgres, Redis и Centrifugo. API описан в OpenAPI и AsyncAPI, клиенты для TypeScript и Dart генерируются из спецификации, CI падает при расхождении. Интерфейс переведён на английский, русский, украинский и греческий, паритет ключей проверяет CI. Телеметрия идёт через OpenTelemetry в Grafana, ошибки — в Sentry.</p>https://kkucherenkov.github.io/projects/burkmak/Mon, 01 Jan 0001 00:00:00 +0000https://kkucherenkov.github.io/projects/burkmak/<h2 id="для-чего">Для чего</h2> <p>Статьи, отложенные на потом, теряются по вкладкам и закладкам. burkmak собирает их в одну библиотеку на своём сервере, извлекает текст без рекламы и отправляет на читалку Kobo без правки прошивки. Выделения и заметки уходят в Obsidian.</p> <h2 id="сохранение">Сохранение</h2> <ul> <li><strong>Откуда угодно.</strong> Ссылка сохраняется из веба, мобильного приложения, share-меню Android или букмарклета в браузере.</li> <li><strong>Метаданные в фоне.</strong> Заголовок, сайт, описание и картинка появляются без перезагрузки страницы, по SSE.</li> <li><strong>Текст сразу.</strong> Статья извлекается при сохранении, и ридер, OPDS и Kobo получают её готовой.</li> <li><strong>Порядок.</strong> Теги, статусы (непрочитано, прочитано, в архиве) и избранное. У каждого пользователя своя библиотека.</li> </ul> <h2 id="чтение">Чтение</h2> <ul> <li><strong>Ридер на Readability.</strong> Статья без рекламы и обвеса. Копия остаётся, даже если оригинал удалят.</li> <li><strong>Картинки</strong> кэшируются на своём сервере.</li> <li><strong>Полнотекстовый поиск</strong> по заголовку, адресу и тексту статьи на SQLite FTS5.</li> <li><strong>Выделения</strong> цветом и заметки к ним.</li> <li><strong>Светлая и тёмная тема.</strong></li> </ul> <h2 id="kobo">Kobo</h2> <ul> <li><strong>OPDS-каталог</strong> с обложками, пагинацией и поиском. Статьи скачиваются в EPUB и KEPUB, каталог добавляется на обычную Kobo через настройки.</li> <li><strong>Нативная синхронизация</strong> по протоколу магазина Kobo. Читалка забирает новые статьи при подключении, а статус прочтения возвращается обратно: дочитанная на Kobo статья становится прочитанной в burkmak, а архивированная в приложении исчезает с устройства. Нужен HTTPS. Протокол проверен на полной симуляции, проверка на живом устройстве впереди.</li> </ul> <h2 id="obsidian">Obsidian</h2> <ul> <li><strong>Экспорт в Markdown.</strong> API отдаёт статью заметкой с источником, метаданными, выделениями и заметками. Повторный экспорт обновляет ту же заметку.</li> <li><strong>Плагин для Obsidian</strong> синхронизирует экспорт в хранилище.</li> </ul> <h2 id="под-капотом">Под капотом</h2> <p>Бэкенд на NestJS с SQLite, веб на Nuxt, мобильный клиент на Flutter. Фоновые задачи выполняет воркер поверх базы, события в клиенты идут по SSE, внешних сервисов нет: локальный стек — два контейнера. API описан в OpenAPI, клиенты для TypeScript и Dart генерируются из спецификации.</p>https://kkucherenkov.github.io/projects/todoer/Mon, 01 Jan 0001 00:00:00 +0000https://kkucherenkov.github.io/projects/todoer/<h2 id="для-чего">Для чего</h2> <p>Личные задачи, проекты, приоритеты и теги в духе Todoist и Things, но на своём сервере. Главное требование — офлайн: каждый клиент держит полную реплику и отвечает на вопрос «что сегодня» без сети.</p> <h2 id="что-работает">Что работает</h2> <ul> <li><strong>Синхронизация.</strong> Один эндпоинт <code>POST /api/v1/sync</code> принимает операции и отдаёт изменения. Конфликты решаются по полям, побеждает последняя запись. Удалённые записи чистятся, а клиент с устаревшим курсором получает свежий снапшот.</li> <li><strong>CLI.</strong> Команды <code>todoer add</code>, <code>list</code> и <code>outbox</code> работают с локальной репликой в SQLite. Операция сначала встаёт в очередь и сохраняет свой id при повторах, поэтому повторный <code>add</code> не создаёт дубль.</li> <li><strong>Для скриптов и агентов.</strong> Вывод в <code>--json</code> и коды возврата, по которым можно ветвиться: код 5 означает, что сервер недоступен и операция ждёт в очереди.</li> </ul> <h2 id="в-планах">В планах</h2> <ul> <li>Проекты и теги из быстрого ввода, повторяющиеся задачи.</li> <li>Представления: список, канбан, календарь.</li> <li>Веб-клиент и приложение на Flutter.</li> <li>Трекер привычек во второй версии.</li> </ul> <h2 id="под-капотом">Под капотом</h2> <p>NestJS 11, Prisma и Postgres 18. REST-CRUD нет: любая запись идёт через протокол синхронизации. Контракт описан в OpenAPI, и <code>express-openapi-validator</code> проверяет его в обе стороны. Репозиторий создан из шаблона <a href="../shipyard/">project-skeleton</a>.</p>https://kkucherenkov.github.io/projects/split_monkey/Mon, 01 Jan 0001 00:00:00 +0000https://kkucherenkov.github.io/projects/split_monkey/<h2 id="для-чего">Для чего</h2> <p>Тренажёры вроде monkeytype меряют скорость и точность, но не знают, на какой клавиатуре идёт набор. После переезда на split этого мало: нужно видеть перекос между руками, медленные пальцы и цену работы со слоями. Split Monkey знает физическую раскладку и keymap клавиатуры и считает статистику в этом разрезе. Целевое железо — Lily58 с QMK, настроенной через Vial.</p> <h2 id="тренажёр">Тренажёр</h2> <ul> <li><strong>Режимы как у monkeytype:</strong> на время (15, 30, 60 секунд) и на число слов (10, 25, 50), с пунктуацией или без.</li> <li><strong>Скорость, точность и ровность темпа</strong> считаются так же, как в monkeytype, и цифры можно сравнивать.</li> <li><strong>Клавиатура под текстом.</strong> Под строкой нарисована Lily58 целиком: клавиша следующего символа обведена, нажатая подсвечивается. Если символ живёт на слое, подсвечиваются и активатор слоя, и сама клавиша.</li> <li><strong>Раскладка из Vial.</strong> Keymap загружается файлом <code>.vil</code>. Символы, которых на клавиатуре нет, в текст не попадают.</li> </ul> <h2 id="аналитика">Аналитика</h2> <ul> <li><strong>Баланс рук</strong> и доля чередования.</li> <li><strong>SFB:</strong> биграммы одним пальцем и их цена в миллисекундах.</li> <li><strong>Пальцы и клавиши:</strong> нажатия, ошибки, медианная задержка.</li> <li><strong>Цена слоя:</strong> насколько символы на слое медленнее базового.</li> <li><strong>История забегов</strong> с графиками динамики и профилем слабых мест по последним забегам.</li> </ul> <h2 id="как-считает">Как считает</h2> <p>Браузер видит только результат работы прошивки: слой и mod-tap разрешаются внутри клавиатуры. Тренажёр восстанавливает физический путь каждого символа по загруженному keymap, выбирает путь с меньшим числом нажатий и учитывает, что заглавную букву левой руки набирают правым Shift. Разрез по слоям выводится из этого пути, остальные метрики измеряются по нажатым клавишам. Задержки агрегируются медианой, чтобы одна пауза на раздумье не искажала картину.</p>https://kkucherenkov.github.io/projects/shipyard/Mon, 01 Jan 0001 00:00:00 +0000https://kkucherenkov.github.io/projects/shipyard/<h2 id="для-чего">Для чего</h2> <p>Правила, по которым проект живёт с агентами, обычно копируются из репозитория в репозиторий и расходятся. Shipyard выносит их в две части: плагин Claude Code с навыками и шаблон репозитория с файлами процесса. Исправление в навыке приходит во все проекты через <code>/plugin update</code>.</p> <h2 id="плагин-shipyard">Плагин shipyard</h2> <p>Шесть навыков, каждый срабатывает в свой момент:</p> <ul> <li><strong>task-stack</strong> ведёт стек задач: перед задачей крупнее однострочного фикса, при блокировке и при выпуске.</li> <li><strong>lane-discipline</strong> разводит параллельных агентов, чтобы их работа не пересекалась.</li> <li><strong>ci-gates</strong> отличает зелёный PR от того, что только выглядит зелёным, и находит обязательные проверки, которые не запустились.</li> <li><strong>issue-bookkeeping</strong> сверяет задачи в трекере с тем, что ушло в main.</li> <li><strong>deploy-verify</strong> выкатывает релиз на хост и проверяет, какая версия там работает.</li> <li><strong>release-audit</strong> проводит аудит продукта перед релизом.</li> </ul> <p>Команда <code>/bootstrap</code> один раз настраивает свежий репозиторий из шаблона: заполняет плейсхолдеры, пишет первый ADR и открывает первую задачу.</p>