POST /api/collections/:id/regenerate — (Пере)генерация коллекции

Сгенерировано из матриц + кода. Правки вносить в источники (docs/matrices/, server/routes/), не здесь.

Поле	Значение
HTTP	`POST /api/collections/:id/regenerate`
Auth	`—`
Scope токена	`read_write`
PG-функции	`api.create_collection_generation_attempt`, `api.finalize_collection_generation_attempt`
Таблицы	`collection_generation_attempt`, `collection`, `collection_block`, `collection_layer`, `collection_specialty`, `collection_edge`
SRM	SRM-328
RP (права)	—
Файл роута	`server/routes/collections.js`
Статус	done

Аргументы запроса (best-effort из хендлера; путь-параметры опущены):

Аргумент	Где	Заметка
`keep_block_ids`	body	подтвердить
`messages`	body	подтвердить
`mode`	body	подтвердить
`params`	body	подтвердить
`quality`	body	подтвердить

Коды ответов/ошибок (из хендлера): 400, 409, 500 (+ 200) — уточнить причины вручную

Для человека

Как открыть: орг-админ → раздел «Коллекции» → карточка коллекции → редактор → форма (пере)генерации. Один и тот же экран и при первом построении коллекции, и при последующих перегенерациях.

Это единая форма, которая строит содержимое коллекции — слои, блоки, специальности и связи между ними — из вашего текстового описания. В форме задают пожелания и рамки по каждой оси: сколько примерно слоёв, блоков, специальностей (можно указать «от» и «до», можно оставить пусто — продукт решит сам). Под капотом — тот же трёхэтапный конвейер, что и для проектов.

Что именно сделать, выбирается режимом:

С нуля — пересобрать коллекцию, полностью заменив прежнее содержимое.
Только блоки — пересобрать блоки и связи, оставив слои и специальности.
С сохранением — перегенерировать, но не трогать отмеченные вами блоки.
Предпросмотр — показать, что получилось бы, ничего не записывая в коллекцию. Удобно «примерить» параметры до того, как перезапишете содержимое.

Качество: Быстрое — один проход, дешевле и быстрее; Pro — режим повышенного качества (несколько вариантов и выбор лучшего), точнее, но дольше и дороже. Для коллекций по умолчанию включено Pro.

Кроме предпросмотра, все режимы показывают прогресс в реальном времени (потоковая генерация): этапы сменяют друг друга, слои, блоки и связи появляются по мере готовности.

Одновременно для одной коллекции идёт только одна перегенерация: если кто-то уже запустил её (в окне 10 минут), вы получите понятную ошибку и сможете попробовать позже. Если минимум по какой-то оси больше максимума — форма не пропустит. Форма обычно сразу подставляет параметры прошлого успешного прогона (см. последняя применённая генерация).

Кто может. Только администратор-владелец коллекции: орг-админ организации-владельца (или администратор платформы — для глобальных коллекций). Чужой орг-админ, сотрудник или наблюдатель права на перегенерацию не имеют.

Для агента

Запись — нужен токен со scope read_write (см. Конвенции). Управление коллекцией — операция администратора-владельца: вызов разрешён только site-admin’у или org-admin’у организации-владельца коллекции (owner_org_id); глобальные коллекции (owner_org_id IS NULL) — только site-admin. Иначе — 403.

Метод унифицированный: один эндпоинт и для первичной генерации, и для всех видов перегенерации. Поведение и формат ответа зависят от mode.

Тело запроса (JSON):

Поле	Тип	Обяз.	Назначение
`mode`	string	да	`initial` \| `blocks-only` \| `with-keep` \| `propose` (см. ниже)
`params`	object	да	Рамки по осям: `layers`, `blocks`, `specialties` — каждая `{ "min": int\|null, "max": int\|null }` (1–100). Любую границу можно оставить `null`. `min > max` → `400`
`messages`	array	да	История запроса к LLM: 1–10 элементов `{ "role": "user"\|"assistant", "content": string }` (`content` 1–50000 символов)
`quality`	string	нет	`pro` (по умолчанию для коллекций) или `fast` — Pro-режим
`keep_block_ids`	array	нет¹	id блоков, которые сохранить. Обязателен и непуст для `mode: with-keep`

¹ Только для with-keep. Лишние поля запрещены (схема строгая, additionalProperties: false).

Режимы и формат ответа. Это ключевое различие метода:

propose — предпросмотр без записи. Генерация прогоняется, в коллекцию ничего не пишется, ответ — обычный JSON (не поток). Используйте, чтобы «примерить» параметры.
initial, blocks-only, with-keep — applied-режимы: результат записывается в коллекцию, а ответ отдаётся как поток Server-Sent Events (Content-Type: text/event-stream). Соединение держится открытым до конца генерации. Контент-негоциация (Accept: text/markdown, ETag/304) к applied-режимам не применяется.

Пример запроса (applied, SSE):

curl -N -X POST https://specbuilder.vnimanie.ai/api/collections/a1b2c3d4-.../regenerate \
  -H "Authorization: Bearer tak_..." \
  -H "Content-Type: application/json" \
  -d '{"mode":"initial","quality":"pro","params":{"layers":{"min":3,"max":5},"blocks":{"min":null,"max":20},"specialties":{"min":null,"max":null}},"messages":[{"role":"user","content":"Коллекция для precision agriculture"}]}'

-N (--no-buffer) обязателен для applied-режимов — иначе curl придержит поток и события не будут видны в реальном времени.

Ответ 200 для propose (JSON, ничего не записано):

{
  "attempt_id": "f9e8d7c6-...",
  "result_summary": { "layers_count": 4, "blocks_count": 18, "specialties_count": 9 },
  "duration_ms": 14230
}

Поток событий (applied): каждое событие — строки event: <тип> и data: <json>, разделённые пустой строкой. По ходу приходят stage (смена этапа), granular-события layer / specialty / block / edge, а в pro — ещё quality_phase. В конце — done с attempt_id, result_summary, duration_ms; при сбое — error.

event: stage
data: {"stage":"decomposition","status":"started"}

event: block
data: {"id":"data-collection","name":"Сбор данных","layer_id":"FOUNDATION","default_specialties":["ml-engineer"]}

event: edge
data: {"source_id":"data-collection","target_id":"model-training"}

event: done
data: {"attempt_id":"f9e8d7c6-...","result_summary":{"layers_count":4,"blocks_count":18,"specialties_count":9},"duration_ms":51200}

Конкурентность. На одну коллекцию допускается одна applied-генерация одновременно. Если в окне 10 минут уже идёт другая попытка, applied-вызов завершится 409 до открытия потока (обычный JSON-ответ с ошибкой), а не повисшим SSE. propose под это окно не попадает. Прочие ошибки генерации отдаются как 500 (в applied-режиме — событием error в уже открытом потоке).

Параметры успешно применённого прогона можно прочитать позже через последнюю применённую генерацию — обычно для предзаполнения формы.

Связанные

Экраны: Редактор коллекции
Конвенции · Роли · Ошибки · Глоссарий