Формат папки курса
Справочник формата v1 — файлы курса, поля работы и критерия, способы проверки, разметка шагов и тестов, темы, настройки курса, правила проверки.
Курс как код — это папка: файлы Markdown с шапкой YAML, по файлу на работу, тест и тему. Её пишет человек в редакторе или его агент, она лежит в репозитории или на диске и приходит на платформу через «Источники». Здесь — сам формат: что где лежит и какие поля бывают.
Пометка «скоро»
Формат описан целиком, версия 1. Где стоит «скоро», платформа это пока не читает: формат уже такой, можно писать по нему заранее.
Папка
course.yaml настройки курса и откуда что берётся
disputa.yaml где лежат файлы и уровни правил проверки
roles.md роли команды
works/03-brif-produkta.md работа 3
works/03-brif-produkta/tests/ тесты курса к работе 3 (скоро)
quizzes/04-letuchka.md тест 4
quizzes/04-letuchka.gift или тот же тест в GIFT
quizzes/04-letuchka.yaml шапка теста в GIFT
topics/rekomendacii.md тема проекта на весь курс
topics/brif-produkta/a.md вариант работы brif-produkta
lessons/01-vvedenie.md лекция или семинар, слайды Marp
themes/sii.css своя тема лекций, CSS Marp
materials/rpd.md материал основы курса: ссылка или своя методичка
course.json или весь курс одним файломЧего в папке нет, то не меняется: нет roles.md — роли курса не трогаются. Файл, который не читается, пропускается с причиной, остальные приходят. Работа со сломанным файлом в разборе не пропадает: там видны путь к файлу и причина, а в курсе работа остаётся как была, пока файл не поправят.
Работа
Файл works/<номер>-<ключ>.md. Номер в имени задаёт порядок: 03-brif-produkta.md — работа 3. Поля и критерии — в шапке между ---, шаги — в теле.
---
# yaml-language-server: $schema=https://disputa.ru/schema/v1/work.json
version: 1
title: Бриф продукта
mission: Зачем эта работа и что участник поймёт
points: 10
criteria:
- key: metric
text: Описана метрика успеха и способ её подсчёта
role: product
check: { type: llm, find: метрика успеха, good: измерима, bad: общие слова }
ask: Почему эта метрика?
expect: Связь метрики с задачей пользователя
---
## Подготовка
### Соберите бриф {#brif}
Текст шага.Ключ работы — остаток имени файла: brif-produkta. По нему работа сопоставляется с курсом, поэтому переставить работы — значит поменять номера в именах, а не завести их заново: в разборе у работ поменяется «номер», отметки «правлено здесь» и варианты останутся при своей работе. Задать явно — key в шапке. Переименовать файл можно: тот же номер и похожее содержимое (то же название или хотя бы половина общих критериев) — это та же работа под новым ключом. В разборе у неё изменится «ключ (имя файла)», строка курса останется прежней — со сдачами, вердиктами, вариантами и отметками «правлено здесь»; откат вернёт прежний ключ. У работ, которые завели до ключей, ключ взят из названия — первое чтение папки предложит ключ из имени файла. Непохожая работа под тем же номером — новая, а прежняя «нет в источнике»: иначе чужая работа легла бы на сдачи прежней.
Версия формата: version: 1 в шапке, нет — значит 1. Файл другой версии пропускается с причиной. Схема: строка yaml-language-server с адресом схемы — с ней VS Code (расширение YAML) и другие редакторы подсказывают поля и подчёркивают опечатку ещё до проверки. Схемы: work, quiz, lesson, topic, variant, course, roles, disputa — https://disputa.ru/schema/v1/<имя>.json. fmt ставит строку сам.
Поля работы
| Поле | Что это | По умолчанию |
|---|---|---|
number | номер работы, 1–99 | из имени файла |
title | название; без него не опубликовать | — |
mission | зачем работа, одной-двумя фразами | — |
brief | задание целиком | — |
href | где задание лежит у курса: страница сайта, файл | — |
weeks | недели курса, строкой | — |
points | баллы за работу, 0–1000 | 10 |
gradingMode | points — баллами, pass_fail — зачётом | points |
passShare | доля, с которой работа зачтена | — |
required | без неё итога нет | false |
category | категория итога: строка ведомости со своим бюджетом | — |
assessment | criteria — по критериям, holistic — по описанию результата | criteria |
reviewKind | talk — приёмка разговором, written — письменно | talk |
submitKind | pull_request, commit, file, url, none | pull_request |
submitBy | person — каждый сам, group — команда | person |
submitFields | поля сдачи рядом с PR: key, label, kind (url или text), required, hint | — |
sessionCard | карточка приёмки для ведущего: тайминг, на что смотреть | — |
links | доп. ссылки участнику «почитать к работе»: title, url, about | — |
variantRule | как раздаются варианты: list_number, random, choice | — |
criteria | критерии, ниже | — |
Вариант работы — отдельный файл в topics/<ключ работы>/, а в работе остаётся только variantRule, см. Темы проектов и варианты. Список variants в шапке (key, title, body, reference) тоже читается, пока в папке нет topics/.
Критерий
| Поле | Что это |
|---|---|
key | стабильный ключ: по нему приходят вердикты и считается история |
text | что должно быть сделано |
role | к какой роли команды; нет — к каждому |
appliesTo | each, role или group — вся команда; обычно выводится сам |
group | группа критериев в карточке |
weight | вес, 0–100, по умолчанию 1 |
check | способ проверки, ниже |
ask | вопрос к приёмке |
expect | что засчитываем за ответ |
redFlag | признак, что артефакт есть, а понимания нет |
visibility | когда участник видит вердикт: visible, after_due, staff |
Не пишите в критерии путь к файлу и нижнюю границу «не меньше N»: агент ищет артефакт по смыслу, а счёт подменяет суть. Верхняя граница («одна страница») допустима.
Способы проверки
check | Поля | Кто решает |
|---|---|---|
command | run, expect: exit_zero или output_matches с pattern | код, по выводу команды в песочнице |
files | find: какой артефакт искать по смыслу | агент |
structure | find, count, schema: чего и сколько в артефакте | агент |
http | urlFrom: team.prodUrl, team.repoUrl или field с field; expect: status_2xx | код |
llm | find, good, bad: что искать, закрыт если, не закрыт если | модель по уликам |
human | how: как проверить | человек на приёмке |
Автотесты (скоро)
Тесты курса — тот же command, только с отчётом: доля прошедших тестов даёт долю веса критерия.
criteria:
- key: api-tests
text: Эндпоинты отвечают по контракту
check:
type: command
setup: pip install -r requirements.txt
run: pytest tests/ --junitxml=report.xml
report: junit # junit, gradescope или prairielearn
tests: "test_api_*" # какие тесты отчёта относятся к критерию
visibility: after_dueТесты лежат рядом с работой, в works/<работа>/tests/, и кладутся в песочницу к копии работы. Скрытые тесты агент, который смотрит работу, не видит: их убирают из песочницы до разведки. Импорт из GitHub Classroom (autograding.json), затем из Gradescope и PrairieLearn.
Шаги
Тело работы — шаги, та же разметка, что в редакторе шагов:
## Подготовка этап, держится до следующего
Зачем этот этап.
### Поставьте Python {#python} шаг: заголовок и ключ
Текст шага, `код`, [ссылка](https://example.com), списки.
? Вопрос «Проверь себя»
- [x] верный вариант → почему
- [ ] неверный
> проверка: README.md
[Готово]
---
### Следующий шагШаг опознаётся по ключу {#ключ}, а без него — по заголовку ###. Ставьте ключ, если заголовок будут править: отметки участников держатся за ключ.
Тест
Файл quizzes/<номер>-<ключ>.md: шапка как у работы, вопросы — в теле. Номер и ключ — из имени, как у работы; нумерация у работ и тестов общая.
---
title: Летучка 4
category: mini-tests
lesson: evaluation
quiz: { open: button, minutes: 10, attempts: 1 }
---
Код или картинка перед вопросом видны вместе с ним.
? (2) Какая метрика подходит? {#metric}
- [x] Recall@k → ищем, нашлось ли нужное
- [ ] BLEU {#bleu}
> разбор: почему так
---
? Столица Франции
= Париж? (2)— баллы вопроса, по умолчанию 1;{#ключ}— ключ вопроса или варианта. Ответы держатся за ключи, поэтому варианты можно переставлять.- [x]— верный,- [ ]— неверный, после→— почему. Несколько[x]— выбор нескольких.= ответ— короткий ответ: принимаемые варианты, без учёта регистра и «ё».> разбор:— виден вместе с ответами.---— следующая страница.
Настройки теста — поле quiz:
| Поле | Что это | По умолчанию |
|---|---|---|
open | button — открывает преподаватель, schedule — по окну, due — до срока | button |
minutes | минут на попытку | без лимита |
attempts | сколько попыток | 1 |
count | какая в зачёт: best или last | best |
reveal | когда видны ответы: closed, submitted, manual | closed |
shuffle | свой порядок у каждого | true |
sample | N случайных вопросов из набора | все |
partial | несколько верных: all — всё или ничего, partial — частично | all |
code | вход по коду с экрана | false |
grace | запас на сеть после конца времени, секунд | 30 |
По какой лекции — lesson. Ключ занятия, по которому тест: lesson: evaluation для lessons/03-evaluation.md. У участника тест стоит сразу после этой лекции и её работы. Без lesson тест встанет по номеру, и проверка курса это отметит, если в курсе есть занятия.
Порядок у участника
У участника лекции, работы и тесты идут одним списком в сайдбаре:
- занятия — по своим номерам;
- работа — после последнего занятия, которое к ней готовит (
workу занятия); - тест — сразу после лекции, по которой он (
lessonу теста), после её работ: лекция, её чекпоинт, летучка по ней.
Номер работы только называет её и задаёт место в ведомости. Связи — по ключам, поэтому лекции можно переставлять и перенумеровывать: тест и работа уходят за своей лекцией. Поменяли ключ занятия (имя файла после номера) — поправьте lesson у тестов и work-связи, иначе проверка покажет «тест ссылается на лекцию, которой нет». В курсе без занятий порядок — по номерам.
Тест в GIFT
Тест можно положить файлом quizzes/04-letuchka.gift в формате Moodle GIFT, и он так и останется в GIFT. Номер и ключ — из имени, как у .md. Шапки у GIFT нет: она в quizzes/04-letuchka.yaml рядом, с теми же полями, что шапка .md (title, points, category, quiz). Без .yaml у теста нет названия, и проверка курса об этом скажет. Настройки теста без .yaml — умолчания летучки.
// летучка 4
Код перед вопросом виден вместе с ним.
::metric::Какая метрика подходит для поиска? {
=Recall@k#ищем, нашлось ли нужное
~BLEU#это про перевод
####Считаем по нужным
}
::golden::Набор эталонных ответов называется? {=golden set =эталонный набор}
::tf::Recall@k зависит от k {TRUE#Подумайте, что такое k#Да}::имя::— ключ вопроса, без него ключ — номер вопроса (q3). Ключ варианта — его текст.=— верный,~— неверный,#после варианта — «почему»,####— разбор.- Несколько верных — веса без
=:~%50%. Верные — варианты с весом больше нуля; сами веса не переносятся, частичный балл задаётpartial. Несколько=в вопросе с вариантами~— ошибка: в Moodle так верен любой из них, у нас верный один. Без~это короткий ответ, и все=принимаются. - Верно-неверно —
{T}или{FALSE}, у нас это вопрос с вариантами «Верно» и «Неверно». Отзывы как в Moodle: первый#— при неверном ответе, второй — при верном. - Короткий ответ —
{=Париж =Paris}. Отзыв#у такого ответа не переносится: общий разбор пишут после####. - Описание — текст без
{}— становится текстом перед следующим вопросом. Описание в конце файла, без вопроса после, — ошибка. - Пустая строка разделяет вопросы,
//— комментарий,$CATEGORYпропускается. Буквальные~ = # { } :пишутся через\, перенос строки внутри вопроса —\n. - Выгрузку из Moodle можно класть как есть:
[html]переводится в текст, пустой#у коротких ответов пропускается. Картинки и оформление блоков кода из[html]не переносятся: разбор называет их замечанием у вопроса.
Соответствие, числовой вопрос, пропущенное слово и эссе платформа не читает. Файл с таким вопросом пропускается с причиной и номером вопроса, тест в курсе остаётся как был.
Когда платформа будет записывать курс в репозиторий (скоро), тест останется в GIFT. Чего в GIFT нет — баллы вопроса не 1, страница, ключ варианта не из текста, — платформа пишет служебным комментарием перед вопросом, как сам Moodle пишет // question: при выгрузке:
// disputa: points 2, page 2, keys 2=recall 3=mrr
::metric::Какая метрика подходит для поиска? {…}page — с этого вопроса и дальше, пока строка не сменит страницу. keys — ключи вариантов по их номеру в вопросе, с 1: 2=recall — у второго варианта ключ recall; пишутся только ключи, которые не выводятся из текста варианта. Номера, которого в вопросе нет, или повтор — ошибка на месте вопроса. Moodle такой комментарий пропускает, платформа читает. Вопросы, которые не правили, и ваши комментарии запись не трогает.
Занятие
Файл lessons/<номер>-<ключ>.md: лекция или семинар. Номер и ключ — из имени, как у работы; занятие сверяется по ключу. В шапке — title, kind (lecture или seminar, по умолчанию lecture), about, plan, outcome, links (доп. ссылки участнику, как у работы), materials (прежнее текстовое поле), work (ключ работы, к которой занятие готовит: у участника работа встанет после него), minutes (минут речи) и hidden (занятие курса, которое участникам не показывают). Тело — слайды Marp, между слайдами ---. Слайды файлом PDF пока загружаются не из репозитория, а на странице занятия, см. Слайды PDF.
---
title: Замер качества
kind: lecture
work: model-i-zamer
minutes: 40
marp: true
paginate: true
---
# Замер качества
---
## Эталонный наборДирективы Marp пишутся в ту же шапку: Marp берёт их только из первой шапки, а поля занятия пропускает, поэтому файл открывается в Marp как есть. Директивы — из списка Marp: marp, theme, style, size, math, lang, headingDivider, paginate, header, footer, class, color, background…, transition и поля метаданных description, author, keywords, url, image. title у Marp и у занятия одно и то же. Незнакомое поле проверка назовёт замечанием: так опечатка в поле занятия не станет молча «директивой». Число слайдов платформа считает сама. Работа в work ищется по ключу в той же версии курса; нет такой — занятие без работы.
Занятия приходят на разбор строкой на занятие, если у источника отмечены «Занятия». Занятие, которого нет в источнике, остаётся в курсе: к нему могли быть привязаны занятия потока.
Какие критерии разбирает слайд
Слайд отмечает критерии работы из work, которые он разбирает, меткой <!-- criteria: ключ, ключ -->. Это как > критерии: у шага работы и как метки покрытия требований в коде. Ключи — у критериев этой работы.
## Эталонный набор
- Вопросы с заранее известными ответами
- Кто писал ответы и кто их проверял
<!-- criteria: golden -->
<!-- Главная ошибка: мерить на тех же примерах, на которых подбирали промпт. -->На слайде и в речи докладчика метки нет. Руками её писать не обязательно: в виде «Слайды» на странице занятия она ставится галочкой у критерия. По меткам считается «критерии 4 из 6»: критерий, который разбирает другое занятие к той же работе, тоже разобран.
Поменялась формулировка критерия после отметки, и отметка «устарела», пока вы не подтвердите «Разбирает новую». Разбор источника узнал переименование критерия, и метки слайдов идут за новым ключом сами. Метку с ключом, которого у работы нет, или у занятия без work проверка назовёт замечанием lesson-criterion-unknown.
Тема лекций
Файл themes/<имя>.css: своя тема слайдов, CSS темы Marp. Имя файла и есть имя темы, его пишут в шапке занятия строкой theme: sii. Название для людей лежит в первом комментарии строкой @title. Своих тем на курс до пяти, встроенные (disputa, default, gaia, uncover) в предел не входят, и с них удобно начинать через @import.
/*
* @theme sii
* @title Тема курса
*/
@import 'default';
section { background-color: #fcfbfa; color: #26211f; }
section a, section strong { color: #1069da; }
section.invert { background-color: #26211f; color: #fcfbfa; }Внешних адресов в теме нет: @import только встроенной темы, url() только строкой data:. Иначе лекция ходила бы за шрифтами и картинками на чужие серверы у каждого участника. Такой файл не читается, проверка покажет его ошибкой. Шрифт 'Golos Text' платформа вшивает сама. Контраст текста и акцента ниже 4,5:1 проверка отмечает предупреждением theme-contrast.
Тема висит на курсе, а не на версии, как темы проектов: приходит сразу, без разбора, и правка меняет оформление у всех занятий с ней. Есть в папке хоть один файл в themes/, значит папка и есть список тем: удалённый файл снимает тему, а опубликованные версии рисуются ею дальше. Нет themes/, и темы курса не трогаются, их ведут на платформе в «Курс → Темы лекций». Темы идут вместе с разделом «Занятия». Занятие с темой, которой нет ни в themes/, ни среди встроенных, проверка отметит lesson-theme-missing: Marp покажет его стандартной темой.
Основа курса
Файл materials/<ключ>.md: из чего строятся лекции. Это своя методичка, ключевая статья, документация, РПД. В шапке название, ссылка (url: адрес http(s) или путь файла в репозитории курса), строка «зачем» (about), занятия и работы ключами (lessons, works) и show, если участникам его надо показать. Тело файла — своя методичка в Markdown, участник читает её в Disputa. Нужна ссылка или текст, можно и то и другое.
---
title: Эталонный набор
about: что включить и что отложить до конца
lessons: [ zamer ]
works: [ model ]
show: true
---
# Эталонный набор
Вопросы с известными ответами, отложенная выборка…По умолчанию основу видят только автор и помощник. С show: true участник видит материал у связанных работ («К работе N» в «Материалах») и занятий. Основа висит на курсе, а не на версии, как темы лекций: приходит сразу, без разбора. Есть в папке хоть один файл в materials/, значит папка и есть вся основа: удалённый файл снимает материал. Нет materials/, и основу ведут на платформе в «Курс → Материалы». Основа идёт вместе с разделом «Занятия».
Поправили материал после того, как сверяли с ним лекцию, и у лекции появится «лекция отстаёт», пока автор не нажмёт «Лекция сверена». Связку с занятием или работой, которых в курсе нет, проверка назовёт замечанием material-link-unknown.
Доп. ссылки «почитать» к одному занятию или работе в основу не кладут: это поле links в шапке самого занятия или работы.
links:
- { title: Recall@k простыми словами, url: "https://example.com/recall", about: перед семинаром }Роли
roles.md — роли команды строками или списком в шапке:
- product: Продукт
- ml: ML-инженерЗа что роль отвечает и можно ли занять её вдвоём — списком в шапке:
---
roles:
- key: product
title: Продукт
about: Бриф, метрика успеха и голос пользователя
- key: ml
title: ML-инженер
duplicable: true
---about видят участник и проверяющий; duplicable: true — роль можно занять двоим, состав команды это не нарушит. Не указано — описания нет, роль на одного.
Критерий с role должен ссылаться на объявленную роль.
Темы проектов и варианты
Раздел topics/: topics/<адрес>.md — тема на весь курс, topics/<ключ работы>/<ключ варианта>.md — вариант работы. Имя файла — адрес темы или ключ варианта. Темы и варианты идут по имени файла, и variantRule: list_number раздаёт варианты в этом порядке. У варианта в шапке title и reference, описание — тело.
---
version: 1
title: Рекомендации для книжного магазина
code: T-07
details: { difficulty: 2, data: открытый датасет }
reference: | # эталон: видят только агент и штаб
…
---
Описание темы для студентов.Темы курса не ждут новой версии курса и разбора: если у источника отмечены «Темы проектов», правка приходит в каталог сразу. По умолчанию этот раздел не берётся. Варианты идут с работой: они на разборе вместе с ней.
Есть в папке хоть один файл в topics/ — папка и есть каталог: удалённый файл убирает тему, у работы ровно те варианты, что лежат в её папке. Команда, которая тему уже взяла, сохраняет свою копию. Нет topics/ — темы и варианты курса не трогаются.
У раздела один источник: пока «Темы проектов» берутся из репозитория, адрес каталога тем на сайте не читается. Задали адрес снова — раздел вернётся к нему. Эталон в открытом репозитории проверка назовёт ошибкой (скоро).
Настройки курса
course.yaml в корне — настройки курса, которые поток берёт по умолчанию, и откуда какой раздел приходит.
# yaml-language-server: $schema=https://disputa.ru/schema/v1/course.json
version: 1
title: Системы ИИ
team: { size: 4, min: 3 } # team: false — курс без команд
topics: { kinds: [catalog, own, partner], seats: 2 }
grading:
aggregation: sum
extras: [{ key: exam, title: Экзамен, max: 40 }] # строки итога от человека
admitPoints: 35 # допуск: столько за семестр
requireAll: true # и все обязательные работы
latePenalty: true # считать штраф за опоздание
late: { kind: steps, steps: [...] }
sources:
works: this # этот репозиторий
quizzes: this
lessons: https://site.example/course # адрес
roles: here # ведётся на платформеteam— размер команды «от и до»,false— курс без команд;topics— виды тем (kinds), сколько команд берут одну тему каталога (seats), правила (rules) и поля заявки своей темы (brief).grading— как складывается итог:aggregation(sum,weighted,bundles), категории (categories), строки итога с баллом от человека (extras,bonus: true— поверх шкалы), допуск по баллам за семестр без экзамена (admitPoints), все ли обязательные работы нужны (requireAll, по умолчанию да), посещаемость (attendance) и считать ли штраф (latePenalty). Форма контроля и перевод в отметку вуза задаются на потоке.late— штраф за опоздание.sources— у каждого раздела свой источник:this— этот репозиторий,here— ведётся на платформе, адрес — сайт курса. Нетsources— весь курс из этой папки. Разделы —course,works,quizzes,lessons,roles,topics.
Настройки приходят на разбор одной строкой «Настройки курса», если у источника отмечено «Оценивание и команды». Есть course.yaml в папке — раздел при подключении отмечен сам, снять можно; нет файла — не отмечен. Если файл есть, а раздел ведётся здесь, проверка и разбор об этом говорят: «course.yaml не применяется». Чего в course.yaml нет, то по умолчанию: команда из 4 человек, итог — сумма без категорий, без штрафа. Название курса, если оно есть, меняется сразу, а не с публикацией: оно у курса, а не у версии. Раздел, который sources отдал другому источнику или платформе, из этой папки не берётся, даже если файлы в ней есть. Показ sources в «Источниках» — скоро.
Поток может переопределить размер команды, виды тем и схему итога у себя: сроки, модули и люди ведутся на платформе, а не в файлах. Токены и подключения в файл не пишутся.
Раскладка файлов и уровни правил
disputa.yaml в корне папки курса задаёт уровни правил проверки (rules) и, если файлы лежат не там, где по умолчанию, говорит, где их искать: раздел → маска с одной * на месте имени работы. labs/03-model/README.md по маске labs/*/README.md — это работа 3 с ключом model; остальное в labs/ — материалы работ, их платформа не читает. Раздел с маской из своей папки по умолчанию не читается. Маски есть у works, quizzes (шапка теста в GIFT — .yaml рядом) и lessons; check, fmt, diff, push и чтение репозитория идут по ним:
version: 1
works: { files: "labs/*/README.md" }
lessons: { files: "slides/*.md" }
rules: { no-lower-bound: off, ask-missing: error }Весь курс одним файлом
Вместо файлов можно положить course.json — документ курса с теми же полями.
Проверка курса
Курс проверяется на платформе — disputa version check --course <курс> или кнопка в редакторе — и у вас без сети: disputa content check [папка]. Правила одни и те же. Ошибка не даёт опубликовать, предупреждение подсказывает.
| Правило | Уровень | Что ловит |
|---|---|---|
file-invalid | ошибка | файл не читается: YAML, шапка, шаги, вопросы или поля |
file-skipped | предупреждение | файл без номера в имени или шапка теста без теста рядом |
field-unknown | предупреждение | незнакомое поле в шапке работы, критерия или занятия, чаще всего опечатка |
gift-html-cut | предупреждение | из [html] в GIFT срезаны картинка или оформление кода |
section-elsewhere | предупреждение | файл раздела, который sources: в course.yaml отдал платформе или другому источнику: правка в нём не применится |
course-empty | ошибка | в курсе нет ни одной работы |
work-no-title | ошибка | работа без названия |
work-no-criteria | ошибка | работа по критериям без критериев |
role-unknown | ошибка | критерий ссылается на роль, которой нет |
quiz-empty | ошибка | тест без вопросов |
ask-missing | предупреждение | у критерия нет вопроса к приёмке |
quiz-no-explain | предупреждение | у вопроса нет разбора |
llm-no-signs | предупреждение | у оценки моделью нет признаков |
no-hard-path | предупреждение | путь к файлу в критерии |
no-lower-bound | предупреждение | «не меньше N» в критерии |
link-broken | ошибка | битая относительная ссылка или якорь; только check по папке: файл ищется на диске, внешние адреса не проверяются |
public-repo-answers | ошибка | в открытом репозитории то, что видят только проверяющие: признаки проверки, expect, redFlag, скрытые критерии, sessionCard, ответы тестов, эталоны, solutions/; одна находка на файл |
Проверка папки без сети — disputa content check [папка]: без входа, у вас, в агенте и в CI на каждом PR. Находка — строкой, как у ESLint:
works/03-model.md:4:5 warn no-hard-path путь к файлу в критерии: работа 3, metric
works/04-bad.md:2:16 error file-invalid шапка не читается: …--json — то же конвертом со schemaVersion: 1, --sarif — для пометок прямо в PR на GitHub. Код выхода 1 — есть ошибки, 0 — ошибок нет (предупреждения не роняют CI), 2 — не прочитать саму папку или disputa.yaml. Уровни правил меняются в disputa.yaml в папке курса — rules: { ask-missing: error, no-lower-bound: off }; file-invalid и role-unknown не выключаются. Открыт ли репозиторий, check без сети не знает: это говорит public: true в disputa.yaml или флаг --public (--no-public — закрыт), флаг главнее — видимость меняют в настройках репозитория без коммита. В GitHub Actions флаг берётся из события: disputa content check --sarif ${{ github.event.repository.private && '--no-public' || '--public' }}. Ни поля, ни флага — public-repo-answers молчит. Курс, открытый нарочно, выключает правило: rules: { public-repo-answers: off }. Новое правило приходит предупреждением: ошибкой оно станет только с новой версией формата. Почему правило есть, с плохим и хорошим примером, — disputa content rule explain no-hard-path, все правила с уровнями этой папки — disputa content rule list.
Один вид папки — disputa content fmt [папка]: тот же курс, записанный так, как его пишет платформа: поля шапки в постоянном порядке, без значений по умолчанию, короткие наборы в строку (check: { type: llm }), имена файлов 03-ключ.md. fmt --check ничего не меняет и отвечает кодом 1, если папка не в одном виде, — для CI. Не трогает файлы, которые не читаются, файлы с незнакомыми полями (их поправит check) и шапки с комментариями: шапку fmt пишет заново и комментарий потерял бы. GIFT пишется поверх себя: нетронутые вопросы и комментарии остаются.
Что изменит папка — disputa content diff [папка] --course sii-2026: тот же разбор, что после отправки, но без снимка, курс не меняется — как terraform plan. ~ — изменится, + — новое, - — нет в папке, ! — спор с правкой на платформе. Опасная правка — ⚠ под строкой: убран критерий, по которому уже есть вердикты, или сменился способ его проверки; у работы, которую уже сдают, меняются баллы или способ сдачи и оценки. Опубликованная версия заморожена, но это заденет потоки, которые переведёте на новую; разбор на платформе показывает то же «Осторожно». Код 2 — есть изменения, 0 — нет, 1 — сбой (папка не читается — сначала check).
Курс папкой и обратно — в «Источниках» есть «Скачать папкой» (zip того же вида), а из терминала — disputa content clone sii-2026 выгружает курс папкой sii-2026/ в том виде, в каком её пишет fmt, и кладёт отметку базы .disputa/base.json (курс, версия, последний принятый снимок, хэш каждого раздела и файла; токена в ней нет; .disputa/ — в .gitignore). Поправили — disputa content diff показывает, что изменится, disputa content push из папки присылает её на разбор; курс берётся из отметки базы или --course. С --data команда работает как раньше: disputa content push sii-2026 --data @course.json.
С чего начать — disputa content init [папка]: course.yaml и disputa.yaml со строкой схемы, папки разделов, .disputa/ в .gitignore, в корне репозитория — проверка курса на каждом PR (.github/workflows/disputa-course.yml) и .pre-commit-config.yaml с check и fmt --check. Версия CLI в них закреплена: новое правило не уронит проверку, пока вы её не обновите. Что уже есть, init не трогает. Что поменялось — disputa content status: свои правки после выгрузки по отметке базы (без сети) и разделы, которые за это время поменялись на платформе.
Токен для CI — в «Источниках», «Настроить» у источника: умеет только прислать снимок этого курса на разбор, применить или опубликовать им нельзя. Кладут в секреты репозитория как DISPUTA_TOKEN, в CI — npx disputa content push course/ --course <курс>. Личный токен в CI не нужен: он ломается с уходом человека, а пока не сломался, действует всеми его правами. Отозвать — там же.
Следом появятся:
disputa course test # прогнать проверку на эталонных решениях (скоро)Курс как код
Как вести курс в репозитории или на своём сайте и присылать его на платформу документом, как разобрать пришедшие изменения и как правки на платформе уживаются с источником.
Сигналы
Где курс просит правки по всем его потокам. Критерии, сроки, шаги, потоки и вопросы с приёмок, пороги и отчёт потока.