Спецификация «Академия» — контракт курса и геймификация (v1)

Цель: единый формат курсов (MD+frontmatter), который движок сайта собирает в интерактивный опыт с прогрессом и геймификацией. Вдохновлено: FastLMS (XP/уровни/стрейки/бейджи), FSRS (vibe-learn/Pamoja), markdown-courses-canvas (прогресс в localStorage), lecture-materials-assistant (один источник → много артефактов), microlearning-правила 2026 (fetch-03).

1. Структура курса

courses/academy/<slug>/
├── course.yaml          # манифест курса (обязателен)
├── lessons/
│   ├── 01-intro.md
│   └── ...
├── quizzes/
│   └── 01-intro.yaml    # квизы к урокам (опционально, но желательно)
├── flashcards/
│   └── 01-intro.yaml    # FSRS-карточки (опционально)
├── badges.yaml          # бейджи курса (опционально, есть дефолт)
├── assets/              # изображения/доски (опционально)
└── README.md            # для людей (анонс)

2. course.yaml — манифест

id: ai-agents-101          # уникальный slug
title: "Агентный ИИ: от чата к автономии"
subtitle: "Короткое описание одной строкой"
theme: terminal            # дизайн-пресет: terminal|lab|boardroom|policy|canvas
audience: "Разработчики и продуктовые роли"
age_group: 14+             # минимальный возраст
difficulty: 2              # 1..3 (новичок..продвинутый)
duration_days: 21          # планируемая длительность
est_hours: 8
news_anchor: "Copilot Workspace GA, Browser Actions, Managed Deep Agents (авг 2026)"
prereqs: "Базовое понимание ИИ-чатов"
modules:
  - id: m1
    title: "Агенты: что изменилось"
    lessons:
      - { file: lessons/01-intro.md, xp: 25, minutes: 5 }
      - { file: lessons/02-copilot-workspace.md, xp: 30, minutes: 8 }
gamification:               # приоритет выше дефолта движка
  level_names: ["Новобранец", "Практик", "Эксперт", "Мастер", "Грандмастер"]
  xp_levels: [0, 500, 2000, 5000, 10000]

3. Frontmatter урока (lessons/*.md)

---
title: "Что такое агент и чем он отличается от чата"
description: "Определение агента, память, инструменты, автономность."
order: 1
minutes: 5
xp: 25
objectives:
  - "Объяснить разницу между чат-ботом и агентом"
  - "Назвать 3 компонента агента (память, инструменты, цикл)"
quiz: "01-intro"        # ссылка на quizzes/01-intro.yaml
---

# Что такое агент

Тело урока (GFM). Правила:
- Абзацы ≤4 предложений, конкретика, примеры.
- Один навык на урок (microlearning, 3-7 мин).
- Интерактив: минимум одна врезка-действие «🛠 Попробуй: ...» каждые 60-90 сек.
- Врезки: `> 🧠 Запомни:` / `> 🛠 Попробуй:` / `> ⚠️ Ловушка:`.

## Квиз
<!-- Плашка-разделитель: движок подставит интерактивный квиз из quizzes/01-intro.yaml -->

4. quizzes/.yaml — квиз (контракт)

quiz: "01-intro"
title: "Проверка: агенты vs чат"
pass_score: 80
questions:
  - id: q1
    type: mc               # mc|truefalse|scenario|fill
    prompt: "Что отличает агента от чат-бота?"
    options:
      - "Наличие инструментов и цикла принятия решений"
      - "Более длинные ответы"
      - "Больше параметров"
      - "Быстрее отвечает"
    answer: 0
    explain: "Агент действует: планирует, зовёт инструменты, проверяет результат. Чат только отвечает."
    xp: 10
  - id: q2
    type: truefalse
    prompt: "Агент может обрабатывать ошибки и повторять попытку."
    answer: true
    explain: "Да, автономность включает самопроверку и восстановление после сбоев."
    xp: 10

5. Геймификация (движок сайта)

• XP: урок = xp из frontmatter, квиз = сумма xp вопросов при прохождении ≥ pass_score.
• Уровни: по xp_levels (дефолт FastLMS: 0/500/2000/5000/10000/25000). Названия из gamification.level_names или дефолт (Новичок/Ученик/Исследователь/Эксперт/Мастер/Грандмастер).
• Стрейк: серия дней с активностью (урок или квиз). Сброс при пропуске дня.
• Бейджи (дефолт, как в badges.yaml курса):
  • first-steps (1 урок), learner-10 (10 уроков), on-fire (3-дневный стрейк), week-warrior (7 дней), quiz-ace (100% квиз), course-graduate (весь курс).
• FSRS-флешкарты: повторение по алгоритму FSRS; карточки в flashcards/*.yaml (front, back, hints). Прогресс — в localStorage.
• Прогресс: localStorage (без бэкенда), экспорт/импорт JSON; пер-курс изоляция.

6. Валидация (scripts/quiz-check.py)

Проверяет перед публикацией:

• course.yaml существует и валиден (обязательные поля: id/title/theme/modules).
• Все lessons, на которые ссылается manifest, существуют, имеют frontmatter-контракт.
• Квизы: у каждого вопроса есть answer, у mc — options, везде есть explain.
• XP-сумма > 0. Порядок уроков уникален.
• news_anchor не пуст (требование «свежести»).

7. Требование свежести

Каждый курс обязан иметь news_anchor (событие недели) и last_review (дата). При каждом релизе новостей — обновлять news_anchor. Это ключ «не устареваем».