Источник пакетов — это git-репозиторий или директория на узле MAIster, в которой MAIster ищет Flow-пакеты. Проект никогда не работает с «головой» ветки: он закрепляет одну установленную версию, а каждый прогон записывает точную ревизию, с которой стартовал. На этой странице описан весь цикл: от собственного репозитория до закреплённой версии в проекте и обратно.

​
Что потребуется

  • Роль глобального администратора, чтобы регистрировать источники, устанавливать ревизии и выдавать доверие.
  • Права администратора проекта, чтобы подключать, обновлять, откатывать и отключать пакеты в проекте.
  • Для git-источника: узел MAIster клонирует репозиторий своими учётными данными (SSH-ключ, credential helper или авторизованный gh либо glab). MAIster не запрашивает учётные данные репозитория в интерфейсе.
  • Для публикации форка обратно в виде pull request: CLI провайдера (gh или glab) и токен узла, например GH_TOKEN или GITLAB_TOKEN, в окружении веб-процесса. Без них MAIster отправит ветку и покажет ссылку на сравнение.

​
Раскладка репозитория с пакетами

MAIster находит пакеты, сканируя packages/*/maister-package.yaml в ветке по умолчанию источника. Каждая директория пакета самодостаточна:
Минимальный манифест:
Правила, нарушение которых ломает установку:
  • name — имя пакета; с него начинаются теги версий.
  • Каждый flows[].id совпадает с name внутри flow.yaml этого Flow.
  • Пути относительные и не выходят за пределы директории пакета.
  • Шаблоны MCP в mcps[] содержат только ссылки env:NAME, никогда значения секретов.
  • В манифесте нет поля версии. Версия — только git-тег.
Один репозиторий может содержать много пакетов; так устроен встроенный репозиторий maister-plugins. Репозиторий с единственным манифестом в корне обнаруживается только при регистрации как локальный источник-директория (см. ниже). Формат манифеста Flow описан в справочнике по манифесту Flow.

​
Версии через git-теги

  • Помечайте каждый выпуск тегом <name>/vX.Y.Z, например my-flows/v1.0.0. Пакеты одного репозитория версионируются и выпускаются независимо.
  • MAIster читает манифест из ветки по умолчанию, поэтому пакет должен быть в неё влит, чтобы его нашли. Список тегов определяет, какие версии можно установить.
  • Установка разрешает тег в коммит. Установленная ревизия неизменяема: перенос или удаление тега потом ничего не меняет в уже установленном, а прогон сохраняет ревизию, с которой стартовал.
  • Flow объявляет минимальную версию движка в compat.engine_min. Ревизия вне диапазона движка узла остаётся доступной для просмотра, но её нельзя включить или запустить.
Выпуск версии:
После этого обновите источник в MAIster, чтобы новая версия появилась.

​
Регистрация источника

  1. Откройте Настройки → Источники пакетов. Та же панель доступна через Flow Studio → Источники.
  2. Нажмите Добавить источник.
  3. Заполните форму:
  4. Нажмите Обновить. MAIster получит список тегов репозитория и просканирует packages/* в ветке по умолчанию. Найденные пакеты появятся под источником вместе с доступными для установки версиями.
Источник обновляется автоматически при старте веб-процесса, если его снимок старше MAISTER_PACKAGE_DISCOVERY_STALE_HOURS (по умолчанию 24 часа). После отправки нового тега обновите источник вручную. Встроенный источник https://github.com/maister-dev/maister-plugins регистрируется при первом запуске и помечен как Встроенный. Его можно выключить или удалить. MAISTER_DEFAULT_PACKAGE_SOURCES задаёт список источников, которые установка регистрирует при старте; пустое значение не регистрирует ничего.

​
Локальные источники-директории

Источник типа local указывает на абсолютный путь на узле MAIster, где лежит либо maister-package.yaml в корне, либо раскладка packages/*. Тегов у него нет: версия каждого пакета — это дайджест его текущего содержимого, он отображается как local-<digest>. Обновить перечитывает директорию и помечает подключения, содержимое которых изменилось, как имеющие обновление. Локальные источники доверены политикой, потому что зарегистрировать их может только глобальный администратор. Используйте их для быстрой итерации на рабочей копии, а для всего общего — git-источник и теги.

​
Установка версии

  1. В списке пакетов источника выберите версию и нажмите установить.
  2. MAIster клонирует тег, проверяет манифест пакета и каждый входящий Flow, записывает разрешённый коммит и сохраняет файлы. Ничего из пакета на этом этапе не исполняется: setup.sh и команды MCP запускаются только после выдачи доверия.
  3. Ревизия появляется в списке Установленные ревизии пакетов. Один тег устанавливается один раз и используется всеми проектами, которые его подключают.
Признаки ошибки:
  • Ошибка манифеста (неверная схема, id Flow не совпадает с именем в flow.yaml, небезопасный путь, неверная ссылка env:): ничего не установлено. Исправьте пакет и отправьте новый тег.
  • Ошибка клонирования: проверьте URL, учётные данные узла и наличие тега в удалённом репозитории.
  • Несовместимость движка: ревизия сохранена и доступна для просмотра, но её нельзя включить или запустить. Опубликуйте версию, диапазон движка которой включает этот MAIster.

​
Доверие к ревизии

Доверие состоит из двух частей. Логическое доверие решает, можно ли вообще запускать Flow ревизии. Доверие к исполнению решает, можно ли выполнять на узле её скрипты setup.sh и команды MCP. Чтобы выдать доверие, откройте Проверка доверия у ревизии, изучите состав (Flow, агенты, навыки, шаблоны MCP, сценарии и setup.sh) и подтвердите. Решение действует во всех проектах, к которым подключена эта ревизия; диалог показывает, сколько их. После подтверждения MAIster выполняет setup.sh каждого входящего Flow; сбой скрипта помечает ревизию как неудачную, и запуски отклоняются, пока не установлена исправленная версия. Доверие выдаётся на ревизию. Новая версия требует отдельной проверки, даже из того же источника. Держите в MAISTER_TRUSTED_FLOW_SOURCE_PREFIXES только репозитории, которые контролируете.

​
Подключение к проекту и закрепление версии

  1. Откройте Проект → Пакеты и нажмите Подключить.
  2. Выберите установленную ревизию. Диалог показывает её состав: Flow, агенты, навыки, требования MCP, ограничения, схемы и сценарии.
  3. Подтвердите. Подключение добавляет Flow пакета в проект и записывает закреплённую версию в maister.yaml репозитория:
  4. Когда ревизия доверена, Включить делает её версией для новых запусков. Ревизия, доверенная политикой, включается сразу.
  5. Привяжите слоты раннеров и требования MCP во вкладках проекта до запуска задачи.
Закреплённая версия принадлежит одному проекту. Другие проекты хранят свои версии, той же или другой, а одна установленная ревизия обслуживает их все. Если репозиторий регистрируется с уже заполненным packages[] в maister.yaml, MAIster устанавливает и подключает эти версии при регистрации, поэтому проект можно воссоздать на другой установке из одного git. Предупреждение о записи означает, что подключение сохранено, а maister.yaml обновить не удалось; поправьте версию вручную. Подключение отклоняется, если id Flow из пакета совпадает с отдельной записью flows[] или если id MCP или ограничения уже предоставлен другим подключённым пакетом.

​
Обновление, откат и переключение версий

  • Когда для подключённого пакета найден новый тег, подключение показывает доступное обновление. Нажмите Обновить, чтобы открыть Предпросмотр обновления: добавленные, удалённые и изменённые Flow, агенты, навыки и шаблоны MCP, а также предупреждения вида «перестанет работать здесь» для агента, подключённого в этом проекте. Подтвердите, чтобы перевести проект на новую ревизию. Уже идущие прогоны сохраняют свою закреплённую ревизию; меняются только новые запуски.
  • Откатить показывает установленные ревизии вместе со ссылками на активные прогоны. Выбор одной из них возвращает включённую ревизию проекта назад; более новая ревизия остаётся установленной.
  • Проекты независимы. Два проекта могут сколь угодно долго работать на разных версиях, и перевод одного никак не затрагивает другой. Чтобы выровнять проект с версией, которую использует другой проект, обновите или откатите его на эту ревизию.
  • Отключить пакет нельзя, пока от его ревизии зависит активный прогон.

​
Доработка локальной версии

Установленные ревизии неизменяемы, поэтому изменения идут через локальный пакет во Flow Studio:
  1. Откройте установленный пакет во Flow Studio и нажмите Форкнуть для редактирования. MAIster копирует ревизию в локальный пакет с именем <name>-local и сохраняет связь с исходной ревизией. Кастомизировать создаёт свежую копию, если форк уже есть; Новый локальный пакет начинает с нуля.
  2. Отредактируйте пакет в редакторе Studio и зафиксируйте изменения коммитом. Коммит проверяет изменённые Flow, манифест, агентов, навыки и схемы и отклоняет некорректное содержимое.
  3. Нажмите Зафиксировать версию. Срез устанавливается как неизменяемая ревизия с меткой local-<digest>. Диалог может сразу перевести на новый срез проекты, уже подключённые к срезу этого пакета; по умолчанию не переводит ни один.
  4. Подключите срез в Проект → Пакеты как любую другую ревизию (у него метка локальный срез) и подтвердите доверие к исполнению.
Если форк сохранил имя исходного пакета, его нельзя подключить рядом с исходным в одном проекте. Переименуйте его в манифесте, зафиксируйте коммит и зафиксируйте версию заново.

​
Выбор версии при запуске

Когда проект закрепил пакет, у которого появился новый срез, или у локального пакета есть ещё не срезанные правки, диалог запуска предлагает выбор:

​
Синхронизация форка с исходным пакетом

Сравнить с исходным показывает пофайловые расхождения между форком и его исходной ревизией. Когда исходный пакет выпускает новый тег, нажмите Синхронизировать с исходным, выберите версию и подтвердите Установить и синхронизировать. MAIster установит тег и выполнит трёхстороннее слияние между базой форка, вашими изменениями и новой ревизией. Конфликтные файлы перечисляются для разрешения в редакторе; завершите синхронизацию из баннера или прервите её, чтобы вернуть рабочую копию к последнему коммиту. MAIster никогда не перезаписывает историю форка.

​
Публикация форка обратно в источник

Нажмите Опубликовать в редакторе локального пакета, выберите Целевой источник (предлагаются только зарегистрированные git-источники) и подтвердите. MAIster отправляет зафиксированное состояние в ветку maister/<package> и, если доступны CLI провайдера и токен, открывает или обновляет pull request в базовую ветку публикации источника; иначе показывает ветку и ссылку на сравнение. Если удалённая ветка ушла вперёд относительно форка, публикация останавливается с сообщением Исходная ветка ушла вперёд — сначала синхронизируйтесь: синхронизируйтесь с исходным, разрешите конфликты и опубликуйте снова. Публикация никогда не делает force-push.

​
Признаки ошибки

  • Обновление источника деградировало: MAIster показывает последний снимок. Проверьте URL, учётные данные узла и наличие packages/* в ветке по умолчанию.
  • Версия не в списке: тега нет в удалённом репозитории или он не начинается с имени пакета из манифеста. Отправьте тег и обновите источник.
  • Запуск отклонён из-за доверия: ревизия не доверена или её setup.sh завершился с ошибкой. Проверьте и выдайте доверие либо установите исправленную версию.
  • Подключение отклонено: id Flow, MCP или ограничения совпадает с уже подключённым в проекте содержимым.
  • Отключение отклонено: активный прогон всё ещё использует ревизию. Дождитесь завершения или прервите прогон.
  • Публикация отклонена: цель не является зарегистрированным git-источником, имя ветки некорректно или исходная ветка ушла вперёд.

​
Связанные страницы