human-in-the-loop

Human in the Loop

Слой одноразовых интерфейсов между владельцем и агентом. Агент описывает, что владельцу нужно посмотреть и решить, скрипт собирает автономную HTML-страницу, владелец отвечает в браузере в любом порядке и возвращает JSON. Страницу не пишут руками: только spec.json и scripts/build.py.

$SKILL ниже означает папку этого файла.

Когда брать

• Документ на утверждение: спека, PRD, КП, план. Статус по разделам, правка текста на месте, ответы на открытые вопросы.
• Выбор из вариантов по нескольким вопросам сразу, у каждого вопроса варианты агента и свой ответ.
• Разметка эталона вслепую: владелец отвечает, ответы модели лежат в отдельном файле и на страницу не попадают, потом score.py считает совпадение.
• Оценка предложений по шкале.

Если вопрос один или два, спрашивай в чате.

Цикл

1. Spec. Собери spec.json (формат: references/spec-format.md). Для Markdown-документа есть заготовка: python3 $SKILL/scripts/from_markdown.py doc.md --options options.json -o spec.json (разделы ## и ### становятся блоками с правкой, раздел «Открытые вопросы» становится вопросами с вариантами из options.json). Для слепой разметки скрытые ответы клади в отдельный sidecar.json, в spec.json их быть не должно.
2. Страница. python3 $SKILL/scripts/build.py spec.json -o page.html собирает и открывает страницу. Клади spec и страницу рядом с проектом (например в private/), не в scratchpad, чтобы владелец мог вернуться. Скажи владельцу одной строкой, что открыто и что от него нужно.
3. Владелец отвечает и вставляет в чат JSON (кнопка «Скопировать JSON для агента»). В JSON только то, что он тронул: status, comment, markdown_old/markdown_new, answers, notes, плюс decision и general_comment.
4. Агент применяет ответы по полю task из JSON и отчитывается: что изменил, что осталось. Пустой decision при наличии кнопок решения значит, что решение не принято: переспроси, не считай документ утвержденным. Для разметки: сохрани JSON и запусти python3 $SKILL/scripts/score.py labels.json sidecar.json --spec spec.json. Расхождения покажи владельцу списком, ошибки разметки не исправляй сам.

Если spec изменился, страница пересобирается с новой версией, старые ответы в браузере к ней не применяются.

Проверка

python3 $SKILL/tests/selftest.py [папка] собирает оба примера из examples/, проходит их в headless Chromium и проверяет выгрузки. Запускай после любой правки шаблона или скриптов.