ПРОЕКТ / ПРОФИЛЬ ВЫПОЛНЕНИЯ
Устройство профиля проекта
Профиль связывает ваш проект с общим движком конвейера: указывает, где работать, как подготовить окружение, какие проверки выполнить и как сдать результат.
Настроить профиль с агентом
Откройте чат с рабочей папкой вашего проекта и скопируйте промпт ниже. Он подходит для нового профиля и доработки существующего: агент изучит проект, проверит доступных исполнителей и настроит профиль с учётом ваших ответов.
Рекомендации по проверкам и приёмке собраны в отдельном разделе.
Настрой профиль этого проекта для конвейеров GrigDesk.
Изучи документацию текущей установленной версии GrigDesk: подключение проекта, контракт профиля и штатный образец pipeline-sample. Найди фактический каталог профилей и проверь, есть ли уже профиль этого проекта. Сохрани существующие настройки.
Прочитай рекомендации для профилей и маршрутов: /ru/docs/projects/recommendations/. Учти их при настройке проверок окружения, инструкций ревью и аудита, доказательств приёмки и возвратов. В итоговом отчёте укажи, как они применены к этому проекту и что ещё не проверено.
Изучи репозитории, стек и правила проекта. Определи команды сборки и профильных тестов, подготовку окружения и способ проверить результат. Предложи режим isolated или shared, нужные маршруты, разрешённые команды и способ сдачи. Уточни у меня то, чего нельзя выяснить из кода и настроек.
Выясни, какие исполнители поддерживаются этой установкой и какие готовы к работе: проверь адаптеры, нужные CLI или встроенный runtime, состояние авторизации и каталоги моделей. Список адаптеров сам по себе не доказывает готовность. Для исходной установки используй engine/bin/factory runners; для готового комплекта найди соответствующую команду в документации установленной версии. Покажи доступные варианты и предложи основного исполнителя, необязательный резерв, модели и поддерживаемый уровень рассуждения для ролей маршрута. Уточни мои предпочтения по скорости, качеству и расходам. Если не хватает авторизации или зависимостей, объясни, что нужно подготовить.
Создай или доработай локальный профиль; для нового используй pipeline-sample, если он подходит. Настрой репозитории, окружение, проверки и команды редактора. Исполнителей и модели меняй штатным CLI с учётом текущей ревизии настроек. Проверь конфигурацию и связанные маршруты, затем выполни проверку готовности хоста без отправки заданий моделям. Реальный пилот согласуй со мной отдельно.
В конце покажи файлы и настройки, выбранных исполнителей и модели, результаты проверок и оставшиеся шаги. Секреты и ключи не включай в отчёт и репозиторий проекта.Начальный порядок подключения описан в руководстве проекта. Ниже — справочник для чтения и ручной настройки профиля: окружение, исполнители и модели, проверки готовности. Примеры используют условный проект с backend и frontend; команды на странице не выполняются автоматически.
Профиль, маршрут, узел и попытка
| Понятие | За что отвечает |
|---|---|
| Профиль | Репозитории, окружение, ограничения, проверки, исполнители и доступные маршруты проекта. |
| Маршрут | Этапы работы, инструкции, переходы, возвраты и решения человека. |
| Узел | Отдельный агент, доверенная команда, ворота человека или отображаемый статус. |
| Попытка | Конкретное выполнение задачи с закреплённой версией маршрута и контрактом окружения. |
Один профиль может обслуживать несколько репозиториев и несколько маршрутов. Запись в разделе «Проекты» хранит паспорт проекта; одного её создания недостаточно для настройки исполняемого профиля.
Из каких файлов состоит профиль
profiles/<name>/
profile.sh
runners.env
graph.json
dashboard.env
routes/
editor-capabilities.json
...
up.sh / down.sh / status.sh
...| Файл | Назначение |
|---|---|
profile.sh | Доверенные переменные и функции проекта: код, окружение, ограничения, команды и сдача. |
runners.env | Основные и резервные исполнители, семейства моделей, версии и усилие рассуждения. |
graph.json | Возможности профиля, в том числе включение протокола route-v2. |
dashboard.env | Настройки панели: пути репозиториев, имена контейнеров и команда таймера. |
routes/ | При управлении скриптом — исходники маршрутов, инструкции и скрипт публикации. При управлении редактором исходником служит его черновик. |
routes/editor-capabilities.json | Доступные редактору команды профиля и дополнительные секции контекста. |
up.sh, down.sh, status.sh | Проектные скрипты подготовки, удаления и диагностики изолированной песочницы, если она нужна. |
| Обёртки тестов и вспомогательные скрипты | Команды конкретного стека: запуск тестов, проверка данных, подготовка окружения. Их имена задаёт проект. |
Четыре корневых файла образуют профиль запуска. Содержимое профиля — локальная конфигурация; оно не поставляется автоматически вместе с движком. Каталог profiles может быть ссылкой на папку данных установки.
Где хранятся настройки
| Параметр | Что задаёт |
|---|---|
FACTORY_PROFILES_DIR | Явный каталог профилей; движку нужен абсолютный физический путь без компонентов-ссылок. |
GRIGDESK_ROUTES_DIR | Хранилище опубликованных маршрутов; по умолчанию ~/.factory/routes. |
GRIGDESK_ROUTES_AUTHORING_DIR | Черновики редактора; по умолчанию каталог опубликованных маршрутов с суффиксом .authoring. |
GRIGDESK_FACTORY_PROFILE | Профиль по умолчанию для сервера; не создаёт и не настраивает его. |
Исходники routes/ внутри профиля и опубликованные версии — разные данные. Правка файла инструкции ещё не меняет маршрут, который возьмёт новый запуск.
Как проходит запуск
- Триаж читает исходные репозитории, сведения о проекте и правила продукта.
- Политика предлагает маршрут по роду работы и глубине; окончательный выбор делает человек.
- Движок закрепляет выбранный маршрут и контракт окружения в попытке.
- Профиль готовит изолированную песочницу либо проверяет существующее общее окружение.
- Для каждого узла движок вызывает агента, доверенную команду или ожидает решение человека.
- Если маршрут предусматривает сдачу, завершающий узел выполняет разрешённые действия.
Окружение, порядок работы и выбор модели настраиваются отдельно. Например, замена модели ревью не требует менять переходы маршрута.
profile.sh: контекст и триаж
Это исполняемый Bash-файл. Его чтение не должно поднимать стенд или выполнять другие подготовительные действия: сервер читает профиль и при оценке задачи, и при открытии формы.
| Параметр | Назначение |
|---|---|
PROFILE_NAME | Идентификатор профиля, совпадающий с именем каталога. |
PROFILE_CTX | Текст о стеке и особенностях проекта для триажа. |
PROFILE_AGENT_CWD | Базовый рабочий каталог для потребителей профиля. При выполнении маршрута движок использует workspace первого репозитория. |
PROFILE_AGENT_DIRS | Дополнительные пути через пробел. Для выполнения маршрута доступ формируется из закреплённых рабочих каталогов. |
PROFILE_SERVICE_HOST | Имя или адрес сервиса без схемы и порта; по умолчанию 127.0.0.1. Укажите localhost, если приложение различает эти адреса. |
PROFILE_TRIAGE_REPOS | Пары ключ:/абсолютный/source через пробел: исходные репозитории для триажа. |
PROFILE_TRIAGE_MARKERS | Проектные признаки риска: например, массовые миграции, списания или изменение прав доступа. Это сведения для оценки задачи. |
PROFILE_TRIAGE_RULES | Пары ключ:относительный/файл с правилами продукта; ключ должен быть объявлен в репозиториях триажа. |
PROFILE_TRIAGE_ROUTES | Соответствие род:глубина=routeId, например feature:light=small. Целевой маршрут должен существовать в каталоге. |
PROFILE_LOOP_MAX_ROUNDS | Потолок передач в режиме петли: 1–300, по умолчанию 20. На обычные маршруты не влияет. |
PROFILE_CTX помогает оценить задачу. Обязательные правила агентов выполнения отдельно возвращает profile_project_context(): это JSON с массивами stack и guardrails.
Функции, которые вызывает движок
Такая функция называется хуком. Обычно она возвращает данные через stdout, диагностику — через stderr, а ненулевым кодом сообщает об отказе.
| Хук | Что сообщает или выполняет |
|---|---|
profile_workspace_mode() | Явно выбирает isolated или shared. |
profile_repositories(TASK) | Возвращает репозитории в формате имя<TAB>source<TAB>workspace; первый задаёт основной рабочий каталог. |
profile_project_context() | Возвращает стек и ограничения, закрепляемые в попытке. |
profile_source_branch(TASK, REPO) | Возвращает ветку рабочего дерева задачи; база создания ветки задаётся отдельно. |
profile_container(TASK) | Возвращает имя стенда или контейнера; сам его не запускает. |
profile_stand_alive(TASK) | Проверяет готовность существующего стенда без создания или удаления ресурсов. |
profile_route_command(...) | Сопоставляет разрешённый commandId с доверенной реализацией и возвращает JSON-вердикт. Нужен для командных узлов. |
profile_delivery_targets(TASK) | Задаёт целевые ветки сдачи по репозиториям, если маршрут содержит ship. |
profile_delivery_actions(TASK) | Добавляет разрешённые действия сдачи; поддерживаемый пример — task-comment. |
profile_slots() | Показывает диапазон и занятость слотов; сам по себе слот не резервирует. |
TASK — номер задачи, REPO — имя репозитория. Первые шесть хуков обязательны для исполняемого профиля. Условные требования и точные сигнатуры дополнительных хуков описаны в контракте профиля.
Состав проверки profile_stand_alive определяет профиль. Успешный health не заменяет проверку пользовательского сценария.
Окружение задачи
| Свойство | isolated | shared |
|---|---|---|
| Код | Отдельные рабочие деревья задачи. | Существующие рабочие копии. |
| Подготовка | Профильный up.sh TASK и проверка готовности. | Проверка готового окружения. |
| Ресурсы | Состав и распределение определяет профиль. | Профиль объявляет занятые ресурсы; аренда защищает их до завершения или отказа от попытки, включая ожидание человека. |
| Удаление | Только принадлежащие задаче ресурсы. | Внешнее окружение не удаляется. |
В shared дополнительно обязательны profile_service_ports, profile_exclusive_resources и profile_instrumentation_restored. Подробности — в описании общего окружения.
Для проекта с backend и frontend песочница может создавать два worktree, два контейнера и отдельные схемы данных. При этом сами серверы MySQL, ClickHouse и Redis могут оставаться общими. isolated не означает отдельную виртуальную машину или выделенный сервер БД.
Номер задачи обычно определяет имена веток и ресурсов, а свободный индекс слота — порты и другие ограниченные ресурсы. Это разные значения. Формулы портов, наборы данных, схемы БД и настройки тестового входа принадлежат скриптам конкретного профиля.
Профиль должен подготовить согласованное окружение тестов. Зависимости копируют без общих inode: запись кэша одной задачи не должна менять зависимости соседней. Созданный при подготовке t<TASK>.env — результат работы lifecycle, а не файл для ручного перенастраивания запущенной попытки.
Проверить готовность окружения
Настройте проверку не только HTTP-адреса, но и процессов, связей и пользовательского сценария, от которых зависит задача. Подробные правила — в рекомендациях по готовности окружения.
Команды ниже проверяют конфигурацию и готовность хоста; проверку поведения приложения задайте отдельно в профиле и маршруте.
Структурную проверку запускают из исходной установки GrigDesk, заменив <name> именем профиля:
engine/bin/factory-check <name> --quickПосле настройки исполнителя и авторизации — проверку хоста:
RUN_HOST_PREFLIGHT=1 engine/bin/factory-check <name> --host-preflightЭти проверки не отправляют задачу модели. Для готового комплекта используйте команды проверки из инструкции своей установленной версии; реальные задачи запускаются отдельно.
Права, проверки и время
| Настройка или хук | Назначение |
|---|---|
PROFILE_AGENT_ALLOW, PROFILE_AGENT_DENY | Массивы дополнительных разрешений и запретов команд. Разрешение не отменяет запрет. |
profile_stage_agent_allow(RUN_KEY) | Дополнительные разрешения конкретной роли; команды публикации можно выдавать только SHIP. |
profile_stage_result_check(TASK, RUN_KEY) | Ранняя проверка сдаваемого результата, пока агент ещё может его исправить. |
profile_route_node_evidence_check(...) | Доверенная проверка доказательств после завершения исполнителя. |
profile_route_volatile_paths(TASK) | Допустимые untracked-артефакты проверок; отслеживаемые Git-файлы остаются под защитой. |
profile_timeout_class(CLASS) | Переопределяет время класса узла в секундах. |
Дефолты движка: planning, standard, review, delivery, check — 30 минут; test, build — 60; diagnostic, browser — 90. Профиль может, например, увеличить planning до часа. Смотрите фактический класс узла: название REVIEW не обязывает его использовать класс review.
Инструкция «проверь за 15 минут» и технический timeout — разные ограничения. Поле budgetClass само по себе не задаёт лимит токенов или расходов.
Машинные проверки удобно выполнять командными узлами. Например, VERIFY запускает тесты и статику, REVIEW анализирует код и может иметь право на ограниченные исправления, а RECHECK повторяет проверки после этих исправлений. Для command-узлов модель не выбирается, даже если в runners.env сохранились настройки одноимённой роли.
runners.env: исполнители и модели
Файл содержит пары KEY=VALUE без export, кавычек и shell-подстановок. Меняйте его через CLI factory profile … runner/model …: запись атомарна, ревизия защищает от перезаписи параллельного изменения.
| Ключ | Назначение |
|---|---|
RUNNERS_SCHEMA | Версия формата, сейчас 1. |
CONFIG_REVISION | Ревизия настроек исполнителей; это не версия маршрута. |
RUNNERS_COVERAGE=required | Требует проверки совместимости политики с доступными исполнителями хоста. |
PROJECT_RUNNER_PRIMARY | Основной исполнитель проекта. |
PROJECT_RUNNER_FAILOVER | Упорядоченный резерв через запятую; пусто — резерва нет. |
STAGE_<RUN_KEY>_PRIMARY | Основной исполнитель роли, например BUILD или REVIEW. |
STAGE_<RUN_KEY>_FAILOVER | Собственный резерв этой роли. При заданном stage primary отсутствие значения не наследует резерв проекта. |
MODEL_DEFAULT_<PROVIDER>_* | Модельные значения по умолчанию для поставщика. |
MODEL_<RUN_KEY>_<PROVIDER>_* | Переопределения модельных полей роли. |
RUNNER_<PROVIDER>_AUTH_PROFILE | Необязательная метка учётного контекста; не пароль и не путь к файлу авторизации. |
Приоритет назначения исполнителя: узел задачи → вся задача → роль профиля → проект. Переопределение заменяет пару primary/failover целиком. Семейство и усилие выбранного исполнителя разрешаются отдельно, по модельным полям.
Поля модели
| Суффикс | Смысл |
|---|---|
FAMILY | Семейство из каталога исполнителя. |
VERSION | Версия внутри семейства; latest выбирает совместимую стабильную модель. |
VARIANT | Вариант модели; auto — вариант по умолчанию. |
EFFORT | Уровень рассуждения, поддерживаемый выбранной моделью и исполнителем. |
EXACT | Точный ID модели, сильнее поиска по семейству, версии и варианту. |
FAMILY_FAILOVER | Резервное семейство того же поставщика при соответствующем лимите. |
Каждое поле наследуется независимо: непустое значение роли → DEFAULT данного поставщика. latest не фиксирует точный ID модели навсегда. Резерв поставщика и резервное семейство одного поставщика — разные механизмы.
Пример фрагмента настроек для чтения:
STAGE_BUILD_PRIMARY=codex
STAGE_BUILD_FAILOVER=glm
MODEL_DEFAULT_CODEX_EFFORT=high
MODEL_BUILD_CODEX_EFFORT=xhighBUILD назначен Codex с резервом GLM. У Codex усилие этой роли — xhigh, остальные неуточнённые роли наследуют high. Семейство и версию задают другие ключи; выбирайте их из каталога установленных исполнителей. Фрагмент не является полным профилем.
Если задать STAGE_AUDIT_PRIMARY=glm и не задать его failover, AUDIT останется без резерва, даже если у проекта есть общий резерв Codex. Продуктовый отказ проверки сам по себе не означает, что задачу нужно повторить другой моделью.
CLI-примеры и проверка хоста — в настройке исполнителей.
Параметры маршрута и узла
| Поле | Что определяет |
|---|---|
bootstrap | Нужна ли отдельная разведка: required или skip. skip не отменяет подготовку окружения. |
entry, sequence.main, sequence.tail | Точку входа, основной порядок и завершающую часть. Переходы всё равно задаются явно. |
executor | Тип узла: agent, command, gate или status. |
runKey | Роль для выбора исполнителя и модели; маршрут не содержит provider, model, effort. |
commandId | ID команды для доверенного диспетчера профиля, а не произвольную shell-строку. |
prompt.blocks, prompt.requiredContext | Блоки инструкции и нужные секции контекста. |
policy.filesystem | state-only — без правки кода; workspace-write — работа с кодом; transactional-write — контролируемая временная инструментация. |
policy.browser | Независимое разрешение браузера: forbid по умолчанию или allow. |
policy.timeoutClass, policy.budgetClass | Класс времени и метку класса бюджета. |
fanout | Возможность нескольких исполнителей внутри узла, максимум и допустимость последовательной работы. Параллельный режим допускается для agent с state-only. |
retry.noResult | Число повторов без принятого результата. |
retry.productFailure | Повторы самого узла при продуктовом отказе. |
retry.providerFailure | Повторы и стратегию при отказе поставщика. |
on | Переходы по исходам: дальше, назад, остановка или разрешённая эскалация. |
onFailure | Переходы по владельцу проблемы: build, tests, plan, environment, human. |
У agent и command исходы — done, skipped, failed, exhausted; у ворот — approved, rejected. Возврат rewind сбрасывает непрерывный участок от цели до текущего узла. Повтор узла и возврат к автору — разные действия; положительный retry.productFailure несовместим с возвратом по failed. У command все retry нулевые.
Пример: четыре маршрута одного проекта
Для веб-приложения с backend и frontend можно организовать такую лестницу. Это пример проектного решения; названия и состав маршрутов не являются обязательными предустановками GrigDesk.
| Маршрут | Последовательность |
|---|---|
small | BUILD → VERIFY → REVIEW → RECHECK → BROWSER → приёмка человека → SHIP. |
feature | PLAN → SKEPTIC → утверждение плана → TESTS → BUILD → VERIFY → BROWSER → AUDIT → приёмка человека → SHIP. |
fix | REPRO → DIAGNOSE → BUILD → VERIFY → REVIEW → RECHECK → BROWSER → приёмка человека → SHIP. |
debug | REPRO → INSTRUMENT → DIAGNOSE → HYPOSKEPTIC → PROOF → TRANSLATOR → принятие причины → TESTS → BUILD → VERIFY → REVIEW → RECHECK → MEASURE → BROWSER → приёмка человека → SHIP. |
small работает без отдельного плана, но выполняет постановку целиком. feature добавляет план, критику, утверждение и тесты до реализации. fix начинает с воспроизведения дефекта. debug требует доказать причину до исправления и измерить результат после.
Для такого примера карта триажа может выглядеть так:
PROFILE_TRIAGE_ROUTES="feature:light=small feature:mid=small feature:full=feature
debug:light=fix debug:mid=fix debug:full=debug"У всех четырёх можно задать bootstrap: skip и поручить карту задачи первому агенту. Приёмку в браузере можно сделать обязательной: skipped останавливает процесс у человека. В feature VERIFY может проверять снимок тестов этапа TESTS, а в коротких маршрутах — тесты из diff. Эти правила задаются самим профилем и опубликованным маршрутом.
Назначения моделей тоже остаются выбором проекта. Например, план, диагноз и реализацию можно поручить Codex, а скептика, ревью и аудит — GLM. Overrides и резерв могут изменить исполнителя, поэтому разные поставщики у автора и проверяющего не гарантируются одним только общим правилом профиля.
Панель и сдача результата
dashboard.env отвечает за отображение проекта, а не за назначение моделей:
| Параметр | Назначение |
|---|---|
FACTORY_BE_ROOT, FACTORY_FE_ROOT | Корни репозиториев для панели; не заменяют profile_repositories. |
FACTORY_MYSQL_CONTAINER, FACTORY_REDIS_CONTAINER | Контейнеры данных для диагностических сведений. |
FACTORY_SANDBOX_PREFIX | Запасной префикс имён контейнеров песочницы. |
FACTORY_STAND_CONTAINER, FACTORY_STAND_FE_CONTAINER | Явные шаблоны имён; {task} заменяется номером задачи. |
FACTORY_STAND_URL | URL постоянного стенда; не заменяет адрес песочницы задачи. |
FACTORY_TIMER_CMD | Команда трекера времени. |
FACTORY_TASK_BASE_URL | База ссылок на задачи внешнего трекера. |
Канонический завершающий узел ship включает контракт сдачи. Действия определяются проектом и разрешениями попытки. В примере с PR это commit, push ветки задачи и создание или обновление PR в ветку из profile_delivery_targets. Дополнительное task-comment разрешает комментарий трекера со ссылками.
Наличие SHIP само по себе не обещает слияние PR или выкладку. Маршрут без ship имеет delivery.mode=disabled; сдача остаётся ручной.
Когда применяются изменения
| Что меняется | Когда начинает действовать |
|---|---|
| Инструкции, узлы, ворота, переходы, retry и политика узлов | После проверки и публикации новой версии. Начатые попытки сохраняют прежний маршрут. |
| Исполнитель, семейство модели, версия, effort | После CLI-изменения и совместимой проверки хоста, при следующем решении о запуске; работающий процесс не переключается посреди хода. |
Репозитории, режим, ветки, сервисы и profile_project_context() | Это закреплённый контракт попытки. Несовпадение может заблокировать продолжение. |
| Доверенные хуки и lifecycle-скрипты | Живой код профиля должен сохранять совместимость со старыми закреплёнными маршрутами. |
Публикация маршрута не перепривязывает окружение существующей попытки. Отдельная debug-настройка профиля меняет детализацию диагностики, а не исполнителя или права агента.
После настройки выполните проверки готовности профиля. Они не отправляют задание модели. Структурная проверка и проверка хоста не заменяют пробный подъём окружения и приёмку реальной задачи.
Далее: настроить этапы и исполнителей.