vektor-math-lab

«Вектор» — учебный прототип по математике для 5–6 классов: ИИ-наставник ведёт ребёнка по теме, показывает дроби на картинках и подстраивает маршрут под темп ученика. Статический сайт для GitHub Pages.

Запуск

• Локально: python3 -m http.server 8000 в папке проекта и открыть http://localhost:8000. Можно и просто открыть index.html.
• GitHub Pages: Settings → Pages → Source: Deploy from a branch, ветка main, папка / (root). Сайт появится по адресу https://<логин>.github.io/vektor-math-lab/.
• Подключить ИИ: на сайте открыть «Настройки» → «ИИ-наставник» → «Мой ключ OpenRouter» → вставить ключ → «Проверить подключение».

Сборка не нужна. Прогресс хранится в localStorage браузера.

Как устроен интерфейс (для детей 10–12 лет)

• Один путь вместо выбора. Главная — путь из 9 тем. Большая кнопка «Продолжить» всегда ведёт к следующему шагу: уроку, тренировке, проверке или повторению.
• Меню из 4 пунктов: Путь, Все темы, Награды, Профиль. Отчёт для учителя и диагностика — в разделе «Для взрослых».
• Шаги темы: «Узнать → Потренироваться → Проверить себя» с отметками ✓, а под ними строка «Что делать сейчас».
• Ответ — клеточками дроби: сверху числитель, снизу знаменатель, слева клеточка «целые» — только в задачах на смешанные числа. Клавиша «/» переводит курсор вниз.
• Подсказки — прямо под задачей, со счётчиком. После ответа — крупная плашка «Верно!» или «Пока не так» и одна главная кнопка.
• Кнопка «← К пути» в каждом уроке, короткое знакомство с интерфейсом при первом входе (повторить можно в профиле), тихие звуки на ответы (выключаются в профиле).
• Если ИИ не отвечает, урок не останавливается: наставник повторяет запрос и продолжает по конспекту.
• Стили: «Тетрадь», «Орбита», «Стикеры», «Пиксель».

Что умеет

• Маршрут по разделу «Обыкновенные дроби»: 9 тем по федеральной рабочей программе 2025.
• Урок с наставником. Наставник ведёт тему по шагам: цель → наглядная модель → правило → пример вместе с учеником → задача на понимание → частые ошибки. В ответах рисует дроби: [[полоска 3/5]], [[круг 3/8]], [[прямая 3/4]], [[сравнить 1/3 1/5]], [[прямоугольник 2/3 3/4]], [[смешанное 2 1/3]].
• Лаборатория дробей: числитель, знаменатель и «разрезать ещё» — дробь сразу видна на полоске, круге и числовой прямой.
• Тренировка с генерируемыми задачами, подсказками по одной и чатом с наставником. Наставник знает задачу и ответ ученика, но не называет ответ — ведёт наводящими вопросами. Верность ответа всегда проверяет код.
• Адаптивный темп. По каждой задаче учитываются: решено ли с первой попытки, сколько подсказок открыто, сколько времени ушло. Отсюда:
  • уровень задач по теме 1–3 растёт после двух чистых быстрых решений и снижается после двух ошибок подряд;
  • общий темп — быстрый / обычный / бережный — меняет норму тренировки (2 / 3 / 5 задач), сложность и подробность объяснений наставника;
  • быстрым ученикам предлагается сразу перейти к проверке, бережному темпу — первая подсказка открывается сама;
  • если проверка не сдана дважды, маршрут предлагает сначала повторить базовую тему.
• Распознавание типичных ошибок («сложил знаменатели» и т. п.) с объяснением ученику и счётчиком для учителя.
• Проверка из 4 задач (зачёт от 3 верных) и повторение через 1, 3 и 7 дней.
• Геймификация без давления. Звёзды за каждую решённую задачу (+3 сам с первой попытки, +2 с подсказкой, +1 за упорство после ошибок), цель дня (3 / 5 / 10 задач), серия дней подряд, 12 достижений и 5 званий от «Новичка» до «Гроссмейстера дробей». Ошибки звёзд не отнимают. Конфетти — только когда тема освоена или получено достижение.
• Диагностика, карта знаний, отчёт для преподавателя (темп, уровень задач, подсказки, ошибки, звёзды и серия), четыре стиля оформления.
• На телефоне — нижнее меню и кнопки «/», «пробел», «−» для ввода дробей.

Запуск на Vercel + Supabase (рабочий вариант пилота)

Сайт — статический (Vercel), данные и логика входа — в Supabase. Публичный ключ и адрес базы лежат в config.js.

База. В Supabase → SQL Editor по очереди выполнить supabase/schema.sql, supabase/test.sql, supabase/admin.sql, supabase/teacher.sql, supabase/pulse.sql, supabase/ai.sql, supabase/pilot_report.sql. Расход ИИ в долларах по дням — select * from vk_ai_cost;, дневной бюджет — vk_settings.ai.usd_day (по умолчанию $3). Демо для сцены — docs/demo.md. Серверная функция наставника — supabase/functions/tutor, секрет OPENROUTER_API_KEY (Edge Functions → Secrets).

Администрирование — в SQL Editor:

Что	Команда
Создать 80 профилей и получить пароли	select * from vk_seed(80, '5А:1-28,5Б:29-56,5В:57-80');
Раздать профили по классам	select vk_assign('5А', 1, 28);
Контрольный класс (только тест)	select vk_class_group('5Б', 'control');
Учитель	select vk_teacher('uchitel', 'пароль', 'Имя', '5А,5Б'); (5-й параметр true — видит всех)
Новый пароль ученику	select vk_reset('ученик17');
Выключить / включить ИИ, лимиты	select vk_ai_set(false); · select vk_ai_set(true, 30, 3000);
Расход ИИ по дням	select * from vk_ai_report;
Обезличенная выгрузка	select * from vk_export_events; · select * from vk_export_tests; → Export CSV
Стереть данные ученика по заявлению родителя	select vk_wipe_student('ученик17');

Кабинет учителя — teacher.html (вход — ссылка на экране входа ученика):

• первым экраном — «Нужна помощь сейчас»: кто застрял, на какой теме, какая типичная ошибка и сколько минут;
• таблица класса: 9 тем, строка «Освоили тему», «Решено сегодня», баллы тестов, сортировка и фильтры «В сети», «Нужна помощь», «Не входили»; обновляется каждые 20 секунд без сброса прокрутки, в шапке — время обновления или «нет связи»;
• карточка ученика по нажатию: частые ошибки, последние ответы, подсказки, сигналы ИИ, новый пароль с бумажкой для печати;
• «Тесты»: открытие только с подтверждением, счётчик «сдали / пишут / не начали»;
• «Логины и подписи»: имена учеников к логинам (хранятся только в браузере учителя, на сервер не уходят), новые бумажки для класса;
• контрольный класс показывается отдельно — только статус тестов; на телефоне вместо таблицы — карточки.

Тест до и после. Две формы по 18 заданий (supabase/test.sql), класс получает форму по жребию, после — другую. Ответы проверяет база, в браузер правильные ответы не попадают. Формы нужно вычитать методисту до пилота.

Запуск на Бегете с входом по логинам (запасной вариант)

С сервером сайт показывает экран входа, а прогресс каждого ученика хранится в базе: можно сесть за любой компьютер. Без сервера (GitHub Pages, файл с диска) всё работает как раньше.

1. В панели Бегета: «Сайты» → привязать домен; «MySQL» → создать базу (запомнить имя, пользователя, пароль). PHP 8.1 или новее.
2. Залить содержимое репозитория в папку сайта (public_html) — через «Файловый менеджер» или FTP. Папка server/ не нужна.
3. Скопировать api/config.example.php в api/config.local.php и вписать данные базы.
4. Создать профили — в «SSH-консоли» Бегета, в папке сайта:

   php api/tools/seed.php --count=80 --site=https://ваш-домен.ru --classes="5А:1-28,5Б:29-56,5В:57-80"
   php api/tools/seed.php --teacher=uchitel --teacher-name="Мария Ивановна" --teacher-classes="5А,5Б,5В"
   

   Команда печатает пароль учителя и кладёт в api/tools/out/ два файла: slips_….html — бумажки (12 на лист A4, открыть в браузере и распечатать) и logins_….csv — список для учителя. Скачайте их и удалите с сервера: в базе пароли хранятся только как хеш.
5. Новый пароль ученику, если потерял бумажку: php api/tools/seed.php --reset=ученик17 (прогресс сохранится).

Логины — ученик1…ученик80, пароль — слово и 4 цифры (зоолог5679). Регистр и пробелы не важны, на английской раскладке подсказка «Смени язык». 5 ошибок подряд блокируют вход на 5 минут. Кнопка «Выйти» — вверху; на общем компьютере выход сам через 20 минут бездействия. Без интернета ответы копятся в браузере и уходят, когда связь вернётся.

ИИ-наставник: DeepSeek через OpenRouter

Без подключения наставник работает по конспекту: ведёт урок по методичке и отвечает на простые вопросы. Чтобы он отвечал на любые вопросы, есть два способа (Настройки → ИИ-наставник):

1. Ключ в браузере — для себя и для проверки. Создайте ключ на openrouter.ai, поставьте лимит расходов и вставьте его в настройках. Ключ хранится только в localStorage этого браузера. Никогда не коммитьте ключ в репозиторий — сайт на GitHub Pages публичный.
2. Свой прокси — для детей и для всех остальных пользователей. Ключ лежит на сервере, ребёнок его не видит.

   cd server
   npx wrangler login
   npx wrangler secret put OPENROUTER_API_KEY   # вставьте ключ OpenRouter
   npx wrangler deploy                          # получите адрес вида https://vektor-tutor.<имя>.workers.dev
   

   В server/wrangler.toml укажите адрес своего сайта в ALLOWED_ORIGINS. Прокси принимает запросы только с него, пропускает только модели из ALLOWED_MODELS и ограничивает длину ответа. Адрес воркера вставьте в настройках «Вектора».

Модель по умолчанию — deepseek/deepseek-v4-flash (на октябрь 2026 ≈ $0.014 / $0.35 за миллион входящих / исходящих токенов, то есть порядка 10–15 центов на тысячу ответов). Список моделей: https://openrouter.ai/deepseek.

Структура

• content/fractions.js — методички и генераторы задач (уровни 1–3).
• content/check.js — проверка ответов: дроби, смешанные числа, знаки сравнения.
• content/visuals.js — рисунки дробей, теги картинок для наставника, лаборатория.
• content/adaptive.js — модель ученика: темп, уровень задач, норма тренировки.
• content/tutor.js — ИИ-наставник: промпт по методичке, OpenRouter со стримингом, офлайн-режим.
• content/game.js — звёзды, звания, цель дня, серия дней, достижения.
• app.js — экраны и прогресс; style.css, skins.css — оформление.
• server/ — прокси для Cloudflare Workers.
• tests/ — автотесты (см. ниже).

Схема данных (localStorage)

Ключ	Что хранит
vektor-progress-v3	progress — % по каждой теме; meta[темa] — тренировка, уровень задач, ошибки, подсказки, время, даты повторения, проваленные проверки; attempts — последние 60 попыток (для расчёта темпа); diag — диагностика; settings — имя и стиль объяснений; days — дни занятий
vektor-ai	режим наставника (off / key / proxy), ключ OpenRouter или адрес прокси, модель
vektor-progress-v3 → game	звёзды, полученные достижения, цель дня и задачи за сегодня, серия дней, счётчики для достижений
vektor-skin	выбранный стиль оформления

Переписка с наставником в браузере не сохраняется — живёт до перезагрузки страницы.

Как устроено занятие

Урок с наставником ──► Тренировка ──► Проверка (4 задачи, зачёт от 3) ──► Повторение через 1, 3, 7 дней
      ▲                    │  ошибка → подсказка / наставник
      │                    │  2 чистых быстрых решения → задачи сложнее
      │                    │  2 ошибки подряд → задачи проще
      └── проверка не сдана дважды → сначала повторить базовую тему

Тесты

node tests/generators.test.js      # 27 000 задач: свой ответ принимается, ошибки распознаются
node tests/tutor.test.js           # отрисовка ответов, теги картинок, промпт, темп
node tests/worker.test.mjs         # прокси: белые списки, лимиты, CORS
node tests/game.test.js            # звёзды, цель дня, серия, достижения
python tests/e2e_scenarios.py      # 61 сценарий в браузере (нужен playwright), OpenRouter подменён
python tests/server_scenarios.py   # PHP-вариант: вход, прогресс на сервере, работа без сети (нужен php с pdo_sqlite)
python tests/supabase_scenarios.py # Supabase-вариант: 45 сценариев — вход, тест до/после, кабинет, ИИ через сервер (нужны Postgres и bun)

Как добавить тему

Добавьте объект в массив topics в content/fractions.js (или новый файл раздела) с полями id, title, goal, requires, explain, mistakes, generate(lv) и запустите тесты. Наставник автоматически возьмёт методичку темы в свой промпт.