Перейти до вмісту
AggregaAggrega
Обрати мову: Українська
Цю сторінку перекладено машинним способом. Читати оригінал англійською.

Конфігурація

Звідки aggrega зчитує свої налаштування і в який файл слід помістити те чи інше налаштування.

Простий випадок

Два файли, і більшості проєктів більше нічого не потрібно.

Один файл у вашому проєкті з назвою .aggrega-config.yaml, розташований у корені проєкту. Він описує, як збирається цей проєкт: які каталоги містять вендорований вміст каталогу, які плагіни рендерять які цілі, які правила лінтера послаблено, де розміщено локальний кеш. Його комітять, тож колега, який клонує проєкт, збирає його так само.

Саме його блок workspace: позначає каталог як корінь проєкту:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs:
- ./catalog
auto_pull: true

Блок містить лише каталоги каталогу, що визначають корінь; усі інші налаштування розміщено на верхньому рівні поруч із ним. Проєкт, який не вендорує вмісту каталогу, однаково записує блок, порожній — workspace: {}, — бо саме наявність блоку є позначкою.

Один глобальний файл на вашому комп’ютері: ~/.config/aggrega/config.yaml, а у Windows — aggrega\config.yaml у каталозі, який задає змінна середовища APPDATA. Через нього розв’язується кожен робочий простір на цьому комп’ютері, і він містить налаштування, що належать комп’ютерові, а не якомусь одному проєкту: реєстри, з яких ви завантажуєте, і політику довіри до підписів для кожного з них, наскільки може зрости сховище скомпільованих модулів, а також будь-який встановлений вами плагін розширення команд. Вони однакові, хоч би де ви працювали, тож сенс у тому, щоб оголосити їх один раз. Файл завантажується автоматично, якщо він є, і нічого не ламається, якщо його немає.

~/.config/aggrega/config.yaml
registries:
- host: hub.aggrega.ai
signing:
required: true

aggrega config init записує цей глобальний файл за вас, реєструючи реєстр разом із політикою довіри до підписів, яку він оголошує, і повідомляє, де файл розташовано на вашому комп’ютері і де зберігаються загальносистемні кеші. aggrega config show виводить те, що діє зараз, а aggrega config show --origin повідомляє, який файл — або яка змінна середовища — визначив кожне налаштування.

Секрети не є конфігурацією. Пароль реєстру й токен ідентичності для підпису ніколи не є полями жодного з файлів; їх передають змінною середовища або прапорцем у момент, коли вони потрібні. Див. environment-variables.md.

Звідки читаються локальні сутності

Проєкт, який зберігає власний вміст каталогу — сутність Component, Feature, Recipe чи один із бібліотечних видів, — має два способи вказати, де цей вміст розміщено, і перший не потребує жодної конфігурації.

Каталог catalog у корені проєкту читається незалежно від того, чи щось його називає. Покладіть сутність у <project>/catalog/, і кожна команда, що завантажує каталог, прочитає її, зокрема в проєкті, чий блок workspace: порожній. Каталог читається рекурсивно, тож як розташовувати підкаталоги в ньому — вирішуєте ви.

Каталоги, перелічені в workspace.catalog_dirs, теж читаються, причому першими. Список є впорядкованим стеком пошуку: перший каталог, що оголошує ідентичність, володіє нею, а та сама ідентичність у пізнішому каталозі затіняється. catalog читається після всього переліченого — хіба що перелічений каталог уже містить його, і тоді він читається як частина цього каталогу, — тож перелічення каталогу доповнює наявне, а не замінює його. Повторюваний --catalog <dir> у командному рядку читається раніше за обидва, а відносний шлях, заданий там, розв’язується відносно каталогу, з якого ви запустили команду, оскільки жоден файл конфігурації його не оголошував. Каталог, названий більше одного разу — у командному рядку й у списку або двічі в списку, — читається один раз, на місці, де його було названо вперше, тож нічого в ньому не вважається затіненим самим собою: затінення — це завжди два різні файли, що оголошують одну ідентичність. Два написання одного каталогу, шлях до нього через посилання і — у файловій системі, що не розрізняє регістр, — написання в іншому регістрі називають той самий каталог. Каталог усередині іншого переліченого каталогу однаково читається як окремий запис. Проєкт, що тримає варіант каталогу для кожної сутності Release, може натомість дати кожній Release власний список — див. Власні каталоги каталогу для сутності Release.

Перелічення каталогу — це спосіб, у який проєкт читає сутності, що зберігаються поза ним. Перелічений каталог може бути будь-де — сусідній checkout, каталог, спільний з іншими проєктами, — і читається там, де він є, навіть якщо сам є символьним посиланням. Більше ніщо так далеко не сягає: посилання всередині проєкту, що веде деінде, не читається, а документ, що називає файл поза проєктом за шляхом, відхиляється, тож до сутності, яка зберігається деінде, доходять через перелічення каталогу, що її містить, і називаючи сутність за її ім’ям. Перелічений каталог поза проєктом є окремим коренем, тож посилання під ним, що веде за його межі, теж не читається. Межа робочого простору викладає правило повністю.

Перелічена директорія має бути директорією. Перелічений шлях, де нічого не існує або де розташований файл чи посилання, що веде в нікуди, відхиляється ще до того, як щось буде прочитано чи записано, кожною командою, що читає каталог, — pull, збиранням, валідацією, інспекцією, lint, а також тими самими операціями, запущеними з редактора через aggrega serve або з асистента через aggrega mcp, — тож збирання ніколи не виконується з меншою кількістю каталогів, ніж ви перелічили. Відмова називає запис у тому вигляді, як його написано, шлях, у який його розв’язано, файл конфігурації та рядок, що його перелічують, і список, у якому він міститься:

<project>/.aggrega-config.yaml:4: the `workspace.catalog_dirs` entry "../shared/aggrega-catalog" names <directory>, which does not exist; create that directory, or remove the entry: workspace configuration is invalid

Створіть директорію або видаліть запис: копія проєкту, взята без сусіднього checkout, який він перелічує, видаляє цей запис і розв’язує з реєстру те, що надав би checkout. Те саме стосується директорії, яку перелічує власний запис сутності Release, директорії, яку додає файл конфігурації, що належить вашому конвеєру, або глобальний файл, і директорії, яку містить змінна AGGREGA_CATALOG_DIRS, яку відмова називає замість файлу. Сама конфігурація все одно завантажується, тож команда, яка не читає жодного каталогу, все одно виконується. Директорію --catalog, якої не існує, було введено для однієї команди, і aggrega build відхиляє її, називаючи директорію. Перелічену директорію, яка існує, але не може бути прочитана, відхиляють команди, що завантажують увесь каталог, називаючи її.

Записати список порожнім — означає сказати, що цей проєкт не має локального каталогу взагалі, і це єдине написання, яке зупиняє й читання catalog:

# <project>/.aggrega-config.yaml
workspace:
catalog_dirs: []

Пропустити ключ — це інше твердження: пропущений список — звичайний випадок, і catalog усе одно читається.

Збирання, pull, валідація чи aggrega inspect, що не знаходить сутності під використаним вами ім’ям, повідомляє, звідки цей проєкт читає локальні сутності і що змінити, щоб названу вами було прочитано. Нічого такого не повідомляється, якщо ви записали порожній список: не читати локального каталогу — це те, що ви там оголосили, і пропозиція це змінити означала б сперечатися з вами. Не повідомляється цього й тоді, коли документ, що оголошує це ім’я, було прочитано й відхилено: цей документ уже лежить там, звідки читає каталог, тож звіт натомість називає, що документ порушує, — рядок і обмеження, — а переміщення нічого б не виправило. Документ, настільки пошкоджений, що оголошене в ньому ім’я взагалі не вдається прочитати, неможливо зіставити з використаним вами ім’ям, тож пояснення все одно надається, — а якщо цей документ оголошує apiVersion Aggrega, збирання, pull чи валідація сутності Release називає його поруч із поясненням, з причиною, яку назвав сам парсер, бо це може бути саме той файл, який слід відкрити. Збій, за якого сутність знайдено, але не вдалося її прийняти — реєстр тепер віддає інші байти під версією, яку закріплює ваш lockfile, файл, який несе сутність, не вдається прочитати, — теж не є відсутньою сутністю, і він повідомляє лише власний спосіб виправлення.

Чи закріплює pull або push сутність

Recipe або FeatureRecipe містить закріплення для вхідних даних, які читає, — віддаленого source:, записаного повністю, файлу, який імпортує запис artifacts, файлів source: поруч, — у entity.lock поруч із собою, а записувати їх — крок автора сутності, aggrega pin. За замовчуванням ні pull, ні push не виконують цього кроку: pull зупиняється на сутності, яку її lock не закріплює, а push відмовляється її публікувати. Два ключі, по одному на команду, роблять виконання кроку типовою поведінкою цієї команди:

# <project>/.aggrega-config.yaml
workspace: {}
pin_sources_at_pull: true
pin_sources_at_push: true

Кожен ключ керує своєю командою і нічим іншим, і --pin-sources кожної команди перевизначає її власний ключ в обидва боки — --pin-sources=false вимикає крок на один запуск у проєкті, налаштованому на закріплення. Збирання, що заповнює власний lockfile, є pull і дотримується pin_sources_at_pull. Ці ключі належать до файлу проєкту, а не до глобального: чи записують pull проєкту закріплення — це політика цього проєкту, і колега, який його клонує, має отримати ту саму відповідь. pin_sources_at_pull також дає змогу проєкту, що використовує чужий незакріплений каталог, записати ці закріплення один раз, а не зупинятися на кожному pull.

Який плагін рендерить можливість

Сутність Recipe називає можливість, через яку вона рендериться, — capability: helm, — і рендерить її плагін, що обслуговує цю можливість. Якщо можливість обслуговує рівно один плагін, нічого налаштовувати не потрібно. Якщо таких плагінів кілька, запис plugins.providers вказує, який саме, за ідентичністю плагіна:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
providers:
- capability: helm
uri: provider/helm

Pull розв’язує запис і фіксує вибраний плагін у lock-файлі сутності Release, а збірка рендерить через те, що зафіксовано в lock-файлі, тож зміна тут набуває чинності під час наступного pull.

uri називає плагін за його ідентичністю, provider/<name>, і ніколи — за місцем, де його опубліковано. aggrega plugin add provider <query> --capability <capability> створює запис саме в такій формі, без версії: запис обирає, який плагін обслуговує можливість, версією є та, яку закріплює сутність Recipe, а інакше найвища доступна, а lock-файл фіксує ту, яку вибрав pull. Плагін, вбудований у компілятор, обслуговується у власній версії компілятора, тож версія, записана в записі для такого плагіна, розв’язується лише тоді, коли це саме ця версія. Запис, чий uri є розташуванням у реєстрі — oci://hub.aggrega.ai/plugin/provider/helm, — не називає ідентичності жодного плагіна, і його відхиляють під час завантаження файлу, називаючи запис і форму, яку слід написати.

Записи пишуться один раз для всього проєкту, тоді як збірка стосується однієї сутності Release, тож запис для можливості, якої ця сутність Release ніколи не запитує, допустимий — його читає інша сутність Release у проєкті — і ні про що не повідомляється. Натомість кожна збірка і кожен aggrega validate --release перевіряють кожен запис, незалежно від того, чи запитує його можливість якась сутність Recipe, за тим, що запис називає:

  • Запис, що називає плагін, який не обслуговує його можливість, зупиняє збірку і не проходить валідацію. Pull розв’язує кожен запис, що називає плагін, і відхиляє той, який не може розв’язати, тож щойно запис пройшов через pull, збірка має його плагін і знає, що він обслуговує; запис, що називає плагін, якого збірка ще не має, оцінюється, щойно pull його завантажить. Повідомлення називає запис, плагін, що цей плагін насправді обслуговує, і написання на відстані одного редагування, якщо таке є, — саме такий вигляд має друкарська помилка на кшталт hlem замість helm.
  • Запис, що називає лише можливість, яку не обслуговує жоден плагін, прочитаний збіркою, є попередженням, і збірка продовжується. Плагін, що її обслуговує, може читати лише інша сутність Release, якої ця збірка не бачить, а запис, що не називає плагіна, не вибирає нічого, чого розв’язання можливості не вибрало б і без нього.

Можливість тут ніколи не містить двокрапки, а таку, що містить, відхиляють під час завантаження файлу. capability: сутності Recipe читається як можливість до останньої двокрапки і закріплення версії після неї, тож запис із ключем helm:1.0.0 ніколи не вдалося б знайти. Натомість закріпіть версію на плагіні — uri: provider/helm:1.0.0 — або в сутності Recipe.

Який імпортер перетворює джерело на чернетки

aggrega import передає джерело імпортеру, який оголошує формат цього джерела, — імпортеру з вашого каталогу або одному з базових імпортерів компілятора, import:langflow для потоку Langflow. Якщо формат оголошує рівно один імпортер, нічого налаштовувати не потрібно. Запис plugins.importer підключає імпортер, називаючи його у своєму uri за ідентичністю та версією, і передає йому те, що міститься під with:

# <project>/.aggrega-config.yaml
workspace: {}
plugins:
importer:
- uri: importer/agent-flows:1.2.0
with:
settings:
target_namespace: payments

aggrega plugin add importer записує uri саме в такій формі. Версія точна — :1.2.0 — або діапазон — :^1.2.0 для найвищої версії, не нижчої за вказану, у межах тієї самої мажорної. Пишіть одне або інше: у цьому списку uri без двокрапки читається як шлях у файловій системі, як описано в Куди вказує відносний шлях, і не називає жодного імпортера.

Дія запису залежить від того, чи оголошує імпортер, який він називає, формат, що його запитує імпорт:

  • Оголошує: запускається саме цей імпортер у версії, яку називає uri, скільки б інших імпортерів у каталозі не оголошували цей формат, і йому передаються with.sources і with.settings запису. Запис — це спосіб, яким робочий простір, чий каталог об’єднує імпортери двох видавців для одного формату, вказує, який із них він використовує.
  • Не оголошує — він називає імпортер іншого формату, плагін іншого виду або щось, чого немає ні у вашому каталозі, ні в компіляторі: запис не бере участі в цьому імпорті. Він нічого не вибирає, а його with не передається жодному імпортеру. Налаштування запису доходять лише до імпортера, який він називає, тож робочий простір, що підключає по одному імпортеру на формат, налаштовує кожен так, що налаштування одного не доходять до іншого.

Якщо формат оголошують кілька імпортерів і жоден окремий із них не підключено — не підключено жодного або записи називають два з них, — імпорт відхиляється з переліком імпортерів, між якими не вдалося вибрати. Запис, що називає імпортер, який оголошує формат, у версії, якій не відповідає жодна його версія в каталозі, — точна версія, якої в каталозі немає, або діапазон, у який не потрапляє жодна з його версій, — також відхиляється з зазначенням версії, а не запускає замість неї іншу версію; а те, що взагалі не є версією, як-от :latest, відхиляється як некоректне. Сутність Plugin одного з базових імпортерів компілятора, поруч із якою в її теці каталогу немає модуля, не є кандидатом: у власній версії компілятора замість неї працює базовий імпортер, а в будь-якій іншій версії сутність залишається кандидатом лише тоді, коли запис називає саме цю версію або коли жоден імпортер із її назвою, здатний працювати, не оголошує формат, як описано в розділі Який із них виконується поруч із вашими власними імпортерами.

Кожен імпортер підключається одним записом. Два записи, що називають один імпортер — ту саму ідентичність в одній версії чи у двох, — відхиляються під час завантаження конфігурації, хоч би яка команда її читала, із зазначенням обох записів і файлів, у яких їх написано. Правило охоплює кожен файл, що додає щось до списку: запис у глобальному файлі, запис у файлі проєкту, запис під importer_append і запис у .aggrega-config-append-ci.yaml конвеєра — усі враховуються, тож перехід імпортера на нову версію означає зміну версії в його єдиному записі. aggrega plugin add importer робить саме це, якщо список plugins.importer файлу, який вона записує, уже називає імпортер: вона переводить цей запис на розв’язану версію, зберігаючи місце запису та його with, а не додає другий. Інших списків вона не читає, тож імпортер, підключений під importer_append або в .aggrega-config-append-ci.yaml конвеєра, команда підключає вдруге, і пара відхиляється під час завантаження конфігурації; змінюйте версію такого запису там, де його написано. Запис, чий uri є шляхом у файловій системі, не називає імпортера і не порівнюється, а на списки plugins.governance і plugins.linter правило не поширюється: один плагін можна підключати до них кілька разів, щоразу з власним with.

Парсерам, через які читає імпорт, запис не потрібен. Імпортер читає своє джерело — а імпорт, що не називає формату, розпізнає його — через парсер для синтаксису джерела: той, що його ваш каталог надає для цього синтаксису, а для синтаксису, для якого ваш каталог парсера не надає, — той, що має сам компілятор, серед них JSON. Тож робочий простір, чий каталог не містить парсера, імпортує потік Langflow або Flowise без жодних налаштувань. Жоден список не підключає парсер: використовується парсер, який ваш каталог надає для синтаксису, а два парсери з різними назвами, що обслуговують один синтаксис, відхиляються, як описано в A parse or import format is advertised by more than one plugin (Формат розбору або імпорту оголошує більш ніж один плагін).

Початок з нуля

Щойно встановлений aggrega не має жодного з файлів, і це робочий стан, а не зламаний: кожне налаштування повертається до вбудованого типового значення, і команди працюють. Бракує лише реєстру, з якого завантажувати вміст каталогу, разом із політикою довіри, яка визначає, які підписи приймати, — саме це й записує aggrega config init.

Знати це заздалегідь не обов’язково. Команда, яка читає свою конфігурацію і ніде не знаходить файлу, повідомляє про це один раз у стандартний потік помилок і називає aggrega config init як спосіб його створити. Це порада, а не збій: стандартний вивід не змінюється, від вас нічого не вимагається, а код виходу такий, який команда повідомила б і так. Повідомлення виводиться, лише коли стандартний потік помилок є терміналом, тож воно доходить до вас за клавіатурою і ніколи не накопичується в журналі конвеєра. Щойно з’являється будь-який із файлів — файл вашого проєкту або глобальний, — воно зникає.

Щоб заповнити глобальний файл офіційним хабом і політикою довіри, яку цей хаб оголошує:

Terminal window
aggrega config init

Передайте --registry <host>, щоб заповнити його іншим реєстром, --workspace, щоб записати запис у файл цього проєкту замість глобального, і --dry-run, щоб побачити вміст, який було б записано, нічого не створюючи. aggrega-config.md описує команду повністю.

Як записується хост реєстру

Кожен registries[].host називає хост реєстру. Так само й default_registry — за яким може йти шлях до репозиторію, — якщо тільки він не називає натомість один із цих записів (див. нижче). Хост записується як сам хост, в одному написанні, під яким зберігається політика довіри реєстру:

  • ім’я хоста в нижньому регістрі, що містить крапку, як-от registry.example.com;
  • localhost або одне ім’я, за яким іде порт, як-от registry:5000;
  • адреса IPv4, як-от 127.0.0.1, або адреса IPv6 у квадратних дужках, як-от [::1];

кожне з необов’язковим :port і нічим іншим — без схеми, без шляху, без облікових даних, без пробілів і без великих літер. Одне ім’я без порту не є хостом реєстру, бо саме такий вигляд має перший сегмент імені сутності каталогу — core у core/web-api, — і ці два ніколи не можна сплутати одне з одним.

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: registry.example.com
registries:
- host: registry.example.com
signing:
required: true

Написання є частиною політики. Запис registries застосовується до хоста, який називає його host:, а вбудована вимога підпису офіційного хабу застосовується до hub.aggrega.ai, тож хост, записаний будь-як інакше, досяг би потрібного реєстру, але оминув би написану для нього політику. Натомість його відхиляють під час завантаження конфігурації, і відмова називає написання, яке слід використати: HUB.AGGREGA.AI і https://registry.example.com відхиляються із зазначенням hub.aggrega.ai і registry.example.com, і так само registry.example.com/charts як registries[].host, який не містить шляху. Порт 443 є типовим портом хоста, доступного через HTTPS, тож hub.aggrega.ai:443 відхиляється так само, із зазначенням hub.aggrega.ai. До localhost та інших loopback-адрес натомість звертаються через звичайний HTTP, де 443 — звичайний порт, тож localhost:443 приймається як записано. Порожній default_registry не називає жодного типового реєстру.

default_registry може містити шлях до репозиторію. Багато реєстрів зберігають кожен репозиторій під власником або проєктом — ghcr.io/<owner>, <host>/<project> у Harbor, — і типовий реєстр на одному з них записується як хост, за яким іде цей шлях:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: ghcr.io/acme
registries:
- host: ghcr.io
signing:
required: true

Шлях — це місце, де публікують і звідки завантажують. Через це типове значення aggrega push публікує core/api-server версії 1.0.0 за адресою ghcr.io/acme/component/core/api-server:1.0.0, а pull, що розв’язує core/api-server, завантажує його з того самого місця, тож підпис, долучений під час публікації, теж знаходиться там. Шлях — це шлях до репозиторію в граматиці розповсюдження OCI: один або кілька сегментів із малих літер і цифр, з’єднаних /, які всередині сегмента можуть розділятися ., _, __ або дефісами, без тегу, дайджесту чи кінцевого /.

Шлях ніколи не впливає на те, як реєстру довіряють. Запис registries, чия політика застосовується, облікові дані, які зберігає aggrega login, вимога підпису та довірені ідентичності знаходяться лише за хостом, тож запис для ghcr.io вище керує ghcr.io/acme і кожним іншим шляхом на цьому хості, і жодне написання шляху не може його обійти; сам host: запису не містить шляху. Хост, записаний в іншому написанні перед шляхом, відхиляється із зазначенням адреси, яку слід записати, — GHCR.io/acme і https://ghcr.io/acme називають ghcr.io/acme, — а те, що йде після хоста, якщо це не шлях до репозиторію, відхиляється із зазначенням хоста, за яким воно йде.

default_registry натомість може називати запис. Записаний як name: запису під registries, він означає host: цього запису. Тоді публікація, pull, перевірка підписів і кожне налаштування довіри окремого реєстру використовують цей хост, і жоден вміст не завантажується з хоста, написаного так само, як ім’я:

# <project>/.aggrega-config.yaml
workspace: {}
default_registry: local
registries:
- name: local
host: 127.0.0.1:5000

Ім’я зіставляється раніше за написання хоста, так само як його зіставляє прапорець --registry, тож значення, що є name: запису, означає цей запис, навіть якщо воно також написане як хост. Ім’я, яке мають два записи, відхиляється як неоднозначне із зазначенням обох хостів. Запис може бути в будь-якому з файлів — default_registry проєкту може називати запис, оголошений у глобальному файлі, — бо ім’я читається один раз, щодо записів, чинних після прочитання всіх файлів і середовища. Значення, що не є ні ім’ям запису, ні хостом реєстру — окремо чи зі шляхом до репозиторію, — відхиляється, і відмова повідомляє, що виправить будь-що з цих двох. Ім’я, за яким іде шлях, як-от local/acme, також відхиляється: ім’я означає хост свого запису, а не місце під ним, тож відмова називає два написання, які слід використати натомість, — local або хост запису, за яким іде шлях, 127.0.0.1:5000/acme. Видалення запису за допомогою aggrega registry remove залишає default_registry таким, як його записано, тож типове значення, що називало видалений запис, після цього нічого не називає і відхиляється, доки його не переписати.

Кожен рівень дотримується того самого написання. Значення відхиляється тими самими словами, звідки б воно не надійшло: з файлу конфігурації, з AGGREGA_DEFAULT_REGISTRY чи з прапорця --registry, що називає призначення одного aggrega push або aggrega push-artifact. Цей прапорець називає хост, і публікація, яку він спрямовує, потрапляє на цей хост без шляху до репозиторію: шлях належить default_registry. aggrega registry add і aggrega config init --registry також перевіряють на це переданий їм хост; вони також приймають посилання замість нього і записують запис під хостом, який називає посилання. Відмова з файлу називає файл і ключ; відмова із середовища називає змінну. Схема задає форму хоста як шаблон для registries[].host і не задає жодної для default_registry, значенням якого може бути ім’я будь-якого запису, — тож редактор, що читає лише схему, не позначає помилково написане типове значення, і відхиляє його саме завантаження конфігурації.

Хост оцінюється лише за написанням, і шлях так само. Чи розв’язується ім’я, чи відповідає там реєстр і чи існує на ньому шлях, під час завантаження конфігурації не перевіряється.

Що що перевизначає

CLI flag > environment variable > configuration file > built-in default

Прапорець — найявніший сигнал з усіх, і він безумовно перемагає. Змінна середовища перевизначає закомічений файл, і саме це дає конвеєру змогу змінити налаштування, не редагуючи відстежуваний файл. Змінна, яку не задано — або задано як порожній рядок, — передає рішення нижчому рівню, а не стирає налаштоване значення. Між двома файлами файл вашого проєкту перемагає глобальний.

Прапорець перемагає тим, що його введено, а не значенням, яке він несе, і для налаштування «так чи ні» саме в цьому різниця між придатним верхнім рівнем і його відсутністю. --offline вмикає цей режим для одного запуску; --offline=false вимикає його для одного запуску, коли закомічений файл або експортована змінна його ввімкнули. Рівень, що читав би лише значення, не міг би відрізнити «вимкнено» від «не згадано», тож кожна команда виглядала б так, ніби запитала типове значення прапорця, і взагалі не було б способу скасувати налаштоване значення.

Це вся модель для одного проєкту на одній машині. Усе, що нижче, існує для проєктів, які з неї виростають.

За межами двох файлів

Ці механізми створено для складніших структур — монорепозиторію пов’язаних проєктів, конвеєра, що додає власні налаштування, спільного каталогу, який розширюють кілька проєктів. Звертайтеся до механізму тоді, коли у вас є проблема, яку він розв’язує.

Кілька файлів конфігурації всередині проєкту

Кожен .aggrega-config.yaml від кореня проєкту до каталогу, у якому виконується команда, робить свій внесок, і ближчий файл перевизначає дальший. Тож підпроєкт може мати власний файл, що коригує оголошене в корені, не повторюючи його.

Корінь позначає лише файл із блоком workspace:. Файл без нього все одно додає свої налаштування — він просто не робить свій каталог коренем проєкту, і саме це не дає файлу налаштувань підпроєкту перевизначити, де починається проєкт.

Передавання --workspace-root змінює і це, а не лише пропускає виявлення: збирається тільки власний файл конфігурації названого кореня, тож файли в каталогах під ним нічого не додають. Завдяки цьому конфігурація закріпленого кореня однакова, звідки б не запускалася команда.

Кожен зібраний так файл читається зсередини проєкту. Файл, що є символічним посиланням, яке веде за межі проєкту, — або лежить у каталозі, до якого дісталися через таке посилання, — не читається, і кожна команда, що читає конфігурацію, зупиняється на ньому, називаючи посилання, а не конфігурує проєкт з решти файлів; те саме стосується файлу конвеєра, описаного нижче. Нечисленні команди, які її ніколи не читають, як-от aggrega version і aggrega help, виконуються з попередженням, що називає посилання. Мовний сервер редактора та інструменти асистента читають конфігурацію так само й однаково запускаються над таким проєктом, щоб його можна було переглянути: їхні переліки сутностей Release і сутностей відповідають, прочитані без жодної конфігурації, і називають цей файл серед непрочитаних посилань, тоді як кожен інший запит, який визначає конфігурація, зупиняється на ньому, називаючи посилання. Конфігурацію, що зберігається поза проєктом, можна прочитати, вказавши її як глобальний файл, як описано в розділі Явне зазначення глобального файлу. Див. Межа робочого простору.

Розширення списку замість заміни

Налаштування зі значенням-списком поводиться як будь-яке інше: значення ближчого файлу замінює значення дальшого. Якщо ви хочете додати до оголошеного у зовнішньому файлі, а не переписати його, використовуйте супутнє налаштування додавання поряд із ним:

налаштування-списокйого супутнє налаштування додавання
workspace.catalog_dirscatalog_dirs_append
plugins.governancegovernance_append
plugins.linterlinter_append
plugins.importerimporter_append
plugins.providersproviders_append

Записи в супутньому налаштуванні приєднуються до визначеного списку на кожному рівні, а не затіняють його, тож підпроєкт додає лінтер до того, що вже оголосив корінь:

# <project>/services/api/.aggrega-config.yaml
plugins:
linter_append:
- uri: ./lint/api-rules.wasm

Якщо один файл задає і базовий список, і його супутнє налаштування, значенням цього файлу є базовий список, за яким ідуть додані записи.

Блок workspace: — виняток щодо того, де можна записати супутнє налаштування. Файл із цим блоком позначає власний каталог як корінь проєкту, тож файл підпроєкту, який записав би workspace.catalog_dirs_append, започаткував би власний проєкт, а не доповнив би охопний. Супутнє налаштування каталогів каталогу поєднується між вашим глобальним файлом і кореневим файлом проєкту.

Список plugins.cli сам поєднується між файлами й не має супутнього налаштування: розширення команд, оголошене в глобальному файлі, реєструє свою команду в кожному проєкті, оголошене в проєкті — лише там, а разом реєструються обидва. Кожен запис закріплює один плагін: uri, який він визначає, і digest байтів, перевірених aggrega plugin add cli, записаний як sha256: і 64 шістнадцяткові цифри в нижньому регістрі. Дайджест в іншому написанні ніколи не збігся б із дайджестом визначених байтів, тож його відхиляють під час завантаження файлу, називаючи файл і запис.

Власні каталоги каталогу для сутності Release

Проєкт може тримати кілька варіантів каталогу поруч — по одному на ціль, кожен із Recipes, що рендерять ті самі Components для іншого провайдера, — і збирати кожну сутність Release з одним із них. Назвіть кожну сутність Release у workspace.releases і задайте їй власні catalog_dirs:

# <project>/.aggrega-config.yaml
workspace:
releases:
release-compose.yaml:
catalog_dirs:
- ./catalog-compose
release-helm.yaml:
catalog_dirs:
- ./catalog-helm

Кожен ключ — це файл Release, записаний відносно файлу конфігурації, що його називає. Ключ — як build.authoring_release — може називати сутність Release поза проєктом, і саме так проєкт до неї дістається: посилання всередині проєкту, що веде до неї, читається, а не пропускається, як описано в розділі Межа робочого простору. Два ключі під ним означають те саме, що й у блоці workspace:, з областю дії лише на цю сутність Release:

  • catalog_dirs замінює список робочого простору для цієї сутності Release. Порядок пошуку, каталог catalog, що читається після нього, і значення порожнього списку такі самі, як для власного списку робочого простору.
  • catalog_dirs_append читається після списку сутності Release. Запис, що містить лише catalog_dirs_append, зберігає список робочого простору й доповнює його.

Сутність Release, не названа в мапі, читає власний workspace.catalog_dirs робочого простору. Сутність Release, названа в мапі, читає власні каталоги, хоч би як її збирали — aggrega build чи aggrega pull у терміналі, редактор через aggrega serve, асистент через aggrega mcp, — тож жодному з них не потрібен прапорець, щоб знайти свій каталог. --catalog <dir> у командному рядку все одно шукається перед каталогами сутності Release для цього одного виклику. А пошук, що не знаходить сутності за вжитим вами ім’ям, називає запис цієї сутності Release як місце, де слід указати каталог, що її містить.

Запис, що називає неіснуючий файл, відхиляється під час завантаження конфігурації з зазначенням запису й файлу. Тому перейменування сутності Release зупиняє кожну команду, доки запис не перейменують разом із нею, замість того щоб сутність Release мовчки збиралася зі списком робочого простору. Директорія, яку перелічує запис, має бути директорією, як і та, яку називає список робочого простору: ту, що нею не є, відхиляє кожна команда, яка читає каталог цієї сутності Release, із зазначенням запису та його рядка.

Те, що не стосується жодної окремої сутності Release, і далі читає список робочого простору: лінтинг чи валідація всього каталогу, пошук сутності за іменем, окремо перевірена сутність Aggregate і перелік сутностей робочого простору в редакторі. AGGREGA_CATALOG_DIRS задає список робочого простору й не впливає на жоден запис тут, а файл конфігурації, яким володіє ваш конвеєр, мапу взагалі не читає.

Файл конфігурації, яким володіє ваш конвеєр

Файл із назвою .aggrega-config-append-ci.yaml може лежати поруч із написаним вручну файлом у будь-якому каталозі, який відвідує обхід. Це окремий файл, тож автоматизований конвеєр може володіти ним і перезаписувати його цілком, ніколи не торкаючись того, що написала людина.

Він лише доповнює. Його записи для п’яти наведених вище налаштувань-списків приєднуються до визначених списків; він не може нічого вилучити чи перевизначити скалярне значення. Скалярний ключ або ключ мапи в ньому не має сенсу доповнення, тож його ігнорують і називають у попередженні, а не мовчки застосовують. Він також ніколи не позначає корінь проєкту, тож додавання такого файлу в каталог додає під’єднання, не змінюючи місця, де починається проєкт.

Куди вказує відносний шлях

Відносний шлях у файловій системі розв’язується відносно каталогу файлу, який його оголосив, — не відносно кореня проєкту і не відносно каталогу, з якого ви запустили команду. Це правило варто прочитати двічі, бо шлях, який виглядає відносним до проєкту, розв’язується деінде, і збирання все одно завершується успішно — але з вмістом, якого ви не мали на увазі.

Воно стосується workspace.catalog_dirs, файлів сутностей Release, заданих ключами в workspace.releases, і каталогів, які перелічує кожен запис, локальних шляхів файлової системи в під’єднанні plugins.governance або plugins.linter — uri, що називає файл .wasm на диску, і кожного запису в with.sources цього під’єднання — а також кожного запису в with.sources під’єднання plugins.importer. В усіх трьох списках uri без двокрапки, що не називає реєстру, — і importer/agent-flows, і ./lint/api-rules.wasm — є саме таким шляхом, тоді як uri, що називає плагін за його ідентичністю, містить версію після двокрапки, importer/agent-flows:1.2.0, і залишається точно таким, як написано. uri під’єднання імпортера називає імпортер, який воно під’єднує, як описано в розділі Який імпортер перетворює джерело на чернетки; імпорт не читає жодного модуля зі шляху, записаного там. Правило стосується й записів у супутніх ключах додавання, і кожен із них прив’язується до власного файлу, що його оголосив, а не до файлу, на якому випадково закінчується злиття. І воно стосується mcp.tls.cert_file, mcp.tls.key_file і mcp.authorization.jwks_file, тож файл поруч із тим, що його називає, знаходиться, звідки б не запускали сервер.

Отже, за такої структури:

myproject/
├── .aggrega-config.yaml
└── services/
├── .aggrega-config.yaml
└── catalog/

і ./catalog, записаного в кореневому файлі, шлях називає myproject/catalog. Записаний у services/.aggrega-config.yaml, той самий текст називає myproject/services/catalog. Абсолютний шлях залишається точно таким, як написано, як і посилання на реєстр, наприклад oci://hub.aggrega.ai/plugins/helm:1.0.0.

Ці налаштування навмисно не дотримуються цього правила, бо не мають файлу, що їх оголосив, до якого можна прив’язатися, або тому, що кожен, хто їх читає, розв’язує їх деінде:

  • artifact_cache_dir тлумачиться відносно кореня проєкту, звідки б не запускалася команда, тож кеш — це один каталог, а не по одному на кожне місце запуску. Абсолютне значення відхиляється під час завантаження конфігурації.
  • AGGREGA_CATALOG_DIRS надходить із середовища й узагалі не має файлу, що його оголосив, тож вказуйте в ньому абсолютні шляхи.
  • mcp.listen береться точно таким, як написано, і це стосується й шляху файлової системи у формі unix:<path>. Та сама адреса надходить і з aggrega mcp --listen, що не має файлу, який її оголосив, тож прив’язування лише сконфігурованого запису змусило б один рядок називати два різні місця залежно від того, звідки він надійшов. Задавайте для сокета абсолютний шлях.

Одне налаштування, сховище якого спільне

Майже кожне налаштування керує чимось, що належить проєкту, з яким ви працюєте, — через які каталоги він розв’язує вміст каталогу, які плагіни рендерять його цілі, наскільки суворо оцінюється його вміст, до якого розміру можуть зростати кеші демона в пам’яті. Значення у файлі проєкту керує власним об’єктом цього проєкту, і стежити тут нема за чим.

compiled_module_cache.max_bytes — єдиний виняток, бо те, що воно обмежує, не належить окремому проєкту. Скомпільований код плагінів зберігається в одному каталозі, який повторно використовує кожен проєкт на вашій машині, тож плагін компілюється один раз, а не один раз на проєкт. Саме обмеження розв’язується, як будь-яке інше налаштування, — запишіть його у файлі проєкту, і для цього проєкту переважить це значення, — але сховище все одно має лише один розмір, і чинний розмір — той, що з останнього збирання. Два проєкти, які обмежують його по-різному, діють по черзі, і нижче обмеження відкидає скомпільований код, за який заплатив інший проєкт.

Тож розміщуйте його в глобальному файлі, коли хочете однієї відповіді для всього, що ви збираєте, і тримайте його вище того, що компілює одне збирання. aggrega cache status повідомляє, що наразі містить сховище, а aggrega config show --origin показує, з якого файлу насправді походить обмеження, з яким ви працюєте.

Налаштування для сервера, до якого звертаються інші

aggrega mcp працює за протоколом Model Context Protocol. На вашій власній машині клієнт запускає його як підпроцес і спілкується з ним через стандартні введення й виведення, що є типовим варіантом, і єдині налаштування, які читає ця конфігурація, — це mcp.transport, залишене типовим, і mcp.announce_tools. Решта блоку mcp призначена для іншого варіанта, який обирає mcp.transport: http: один довготривалий процес на хості, до якого через HTTP звертаються ті, хто не сидить за його клавіатурою.

# <project>/.aggrega-config.yaml
mcp:
transport: http
listen: 127.0.0.1:7777
authorization:
issuer: https://login.example.com
resource: https://mcp.example.com/mcp
allowed_origins:
- https://studio.example.com
limits:
max_concurrent_requests: 32
deny_reach:
- registry
announce_tools:
- list-entities
- get-schema
- validate
- build
health:
listen: 127.0.0.1:7778

Транспорт обирає саме mcp.transport. http запускає слухача; stdio, типовий варіант, працює через стандартні введення й виведення, чого й очікує клієнт-підпроцес. Будь-яке інше значення відхиляється під час завантаження цього файлу. aggrega mcp --transport <stdio|http> робить те саме для одного запуску й переважає ключ, так само як кожен прапорець переважає кожен файл.

mcp.listen називає, де прив’язується цей слухач, і нічого не обирає. Задайте адресу host:port або сокет unix:<path>; aggrega mcp --listen <address> переважає його для одного запуску. Якщо обрано http, а адреси немає ні з того, ні з іншого джерела, запуск відхиляється до будь-якого прив’язування. Якщо обрано stdio, введений --listen відхиляється, а адреса, яку називає лише цей ключ, залишається невикористаною — сервер повідомляє про це одним рядком у своєму потоці помилок, називаючи цей файл і mcp.transport: http. Тож сервер, до якого звертаються інші, задає обидва ключі, як вище, а клієнт, запущений із каталогу, який охоплює цей файл, усе одно звертається до сервера через власні потоки. Шлях unix: береться як написано, а не прив’язується — див. Куди вказує відносний шлях.

mcp.tls.cert_file і mcp.tls.key_file вбудовують TLS у процес. Задайте обидва, і слухач сам обслуговує HTTPS. Пропустіть обидва, і він обслуговує відкритий текст, що приймається лише на loopback або на Unix-сокеті — варіант для випадку, коли проксі попереду тримає сертифікат і пересилає запити процесу. Слухач із відкритим текстом на будь-якій іншій адресі відхиляється до будь-якого прив’язування з назвою цих двох ключів, як і випадок, коли задано один із двох без іншого. Обидва є шляхами файлової системи й дотримуються правила вище: відносний розв’язується відносно каталогу файлу, що його оголосив, тож сертифікат, закомічений поруч із цим файлом, знаходиться, звідки б не запускали сервер. Записуйте їх абсолютними, якщо сертифікатом керують поза проєктом.

mcp.authorization.issuer і mcp.authorization.resource визначають, хто видає токени, які пред’являють клієнти, і як цей сервер називається як ресурс, для якого їх видано. Обидва обов’язкові, щойно обрано транспорт http, і без них слухач відхиляється ще до прив’язки, бо на кожен запит до кінцевої точки надходить виклик bearer-токена, а виклик, що не вказує, куди звернутися, клієнт не може виконати. Записуйте повні адреси разом зі схемою та хостом: видавця — точно так, як цей сервер авторизації сам вказує свій ідентифікатор, а ресурс — як адресу, до якої насправді звертаються ваші клієнти: хост, який показує проксі попереду, якщо він є, а не адресу, до якої прив’язується цей процес. Обидва значення публікуються без запиту облікових даних у документі метаданих захищеного ресурсу OAuth, який обслуговує слухач; саме там клієнт шукає, де отримати токен. Жоден із них не містить нічого секретного: токен надходить разом із запитом, що його пред’являє, і ніколи не записується у файл конфігурації. Видавець має адресу https, якщо сервер авторизації не працює на цій машині — localhost, 127.0.0.1 або ::1, — а слухач, що вказує простий видавець http на будь-якому іншому хості, відхиляється ще до прив’язки, хоч би як він зчитував свої ключі та своїх клієнтів: кожного клієнта спрямовують до видавця по токен, тож через простий http його код авторизації та токен перетинали б мережу без захисту, а якщо звідти ж зчитуються й ключі, будь-хто на цьому шляху міг би їх підмінити.

mcp.authorization.jwks_file вказує файл із ключами, якими перевіряються токени, замість зчитувати їх із сервера авторизації. Якщо його не вказати, сервер зчитує метадані того сервера за його well-known адресою і переходить за опублікованим там jwks_uri; так і працює робочий простір із доступом до мережі. Адреса ключів підпадає під те саме правило, що й видавець, як і будь-яка адреса, на яку перенаправлено будь-яке з цих зчитувань: до адреси з простим http на іншому хості звернення ніколи не відбувається, а на токен, якому потрібні ці ключі, надходить відповідь 503, доки сервер авторизації не опублікує свої метадані та ключі через https. Якщо його вказати, до сервера авторизації ніколи не звертаються — саме це потрібно робочому простору, що оголошує offline: true, і такий робочий простір відхиляється до прив’язки слухача, якщо цей ключ не вказує файл. Це шлях, і він підпадає під правило вище: відносний шлях розв’язується відносно каталогу файлу, що його оголосив, тож набір ключів, закомічений поруч із цим файлом, знаходиться, звідки б не запускали сервер. Файл містить публічні ключі перевірки, які й публікує сервер авторизації, — нічого, що підписує, і нічого секретного.

mcp.allowed_origins враховується лише тоді, коли запит містить заголовок Origin, що на практиці означає, що його надіслав браузер. Перелічіть там джерела, які ви обслуговуєте; запит, що вказує джерело, якого немає в переліку, відхиляється, а запит без такого заголовка обслуговується за будь-яких умов. Клієнт, що не є браузером, такого заголовка не надсилає й запису не потребує. Запис порівнюється із заголовком точно, тож пишіть його так, як його надсилає браузер: схема в нижньому регістрі, ://, хост у нижньому регістрі та : із портом лише тоді, коли порт не є типовим для схеми, — https://studio.example.com або http://localhost:3000 для сторінки, що обслуговується на вашій машині, — без шляху і без кінцевого /. Запис будь-якої іншої форми ніколи не збігся б, тому відхиляється під час завантаження цього файлу з зазначенням запису.

mcp.limits обмежує те, що може запитати один клієнт — наскільки великим може бути тіло одного запиту, скільки запитів виконується одночасно і скільки запитів один клієнт може надіслати за хвилину. Усі три обмеження діють завжди; жодне не має значення, що його знімає. Третє, requests_per_minute, рахується для кожного клієнта окремо, тож інтенсивні запити одного клієнта нічого не коштують іншому.

mcp.authorization.trusted_proxy визначає клієнта за проксі попереду, замість перевіряти токен тут. Задайте в principal_header заголовок, яким цей проксі повідомляє, хто є клієнтом, і за потреби в scopes_header — заголовок з областями доступу цього клієнта. Обидва є назвами HTTP-заголовків, як-от X-Forwarded-User, — літери, цифри, дефіси та кілька інших символів, допустимих у назві заголовка, без пробілів і двокрапок, — а назва будь-якої іншої форми відхиляється під час завантаження цього файлу з зазначенням ключа, бо жоден запит не міг би її містити. У цьому режимі токен не зчитується взагалі, а запит без заголовка принципала відхиляється. Оскільки тоді заголовок є єдиним обліковим даним, йому можна довіряти лише там, де ніщо інше не може його задати: процес відхиляється до прив’язки, якщо mcp.listen не є loopback-адресою або Unix-сокетом. Якщо блок не вказати, сервер сам перевіряє токени, і це типова поведінка; блок із порожнім principal_header відхиляється, а не трактується як типова поведінка.

mcp.deny_reach вилучає з цього розгортання певний вид досяжності. Кожна операція, яку виконує сервер, оголошує, як далеко сягають її власні наслідки: none — для операції, що читає або рендерить і нічого по собі не залишає, workspace — для операції, що записує всередині робочого простору, який обслуговує цей процес, registry — для операції, що публікує, підписує або відкликає, і machine — для операції, що змінює спільне для всіх робочих просторів на хості. Зазначення виду тут вилучає кожен інструмент, що його досягає: інструмента немає в списку інструментів жодного клієнта, хоч би що містив токен цього клієнта, а виклик його відхиляється з посиланням на цей параметр. Тож це межа розгортання, а не клієнта, і жодні облікові дані її не знімають: сервер, призначений лише для читання, перелічує тут три записувальні види й тоді не може публікувати навіть для клієнта, токен якого містить усі області доступу. Якщо параметр не вказати (це типова поведінка), розгортання надає все, що дозволяють області доступу його клієнтів. Значення, що не є одним із чотирьох, відхиляється під час завантаження цього файлу, а не пропускається. Нічого виду machine через HTTP не надається, хоч би що тут було вказано, тож його зазначення приймається й нічого не змінює; aggrega-mcp.md описує види та області доступу, що їх дозволяють.

mcp.announce_tools звужує те, що оголошує сервер, і це інша межа, ніж ключ вище. Назвіть інструменти, які оголошує цей сервер, так, як їх подає список інструментів, і оголошено буде саме їх: пропущеного інструмента немає в списку інструментів жодного клієнта, а якщо його все ж викликати за назвою, виклик відхиляється з посиланням на цей параметр. Якщо ключ не вказати (типова поведінка), оголошується кожен інструмент, що його має сервер; якщо записати порожній список, не оголошується жоден, тож ці два записи — різні твердження, і жодне типове значення за вас не підставляється. Від deny_reach його відрізняє те, що саме кожен із них забирає. deny_reach забирає можливість: операції вилученого виду тут не надаються взагалі, і жодні облікові дані їх не повертають. announce_tools забирає лише оголошення — пропущені ним інструменти лишаються можливостями сервера, — і відповідає він на потреби клієнта, що обмежує кількість інструментів, які реєструє, іноді для всіх серверів, до яких він підключений одночасно. Якщо задано обидва, перемагає вилучення, тож інструмент вилученого виду лишається відсутнім, хоч би як його називав цей ключ. Назва, якій не відповідає жоден інструмент, зупиняє сервер, перш ніж він щось обслужить, із переліком наявних інструментів, замість залишити вам поверхню, вужчу за ту, яку ви просили. На відміну від інших ключів тут, що налаштовують слухач, який запускає транспорт http, він зчитується за будь-якого транспорту сервера, бо клієнт, для якого існує звуження, зазвичай саме той, що запустив процес через власні стандартні введення й виведення; aggrega-mcp.md описує решту.

mcp.health.listen виносить перевірки живучості й готовності на окрему адресу. Задайте адресу в будь-якій із двох форм mcp.listen, і другий слухач відповідатиме там на GET /healthz — 200 з моменту запуску процесу — і на GET /readyz — 503, доки робочий простір не розв’язано й кінцеву точку не прив’язано, і 200 відтоді, що дає змогу балансувальнику притримувати трафік, доки процес не зможе справді відповісти на виклик. Якщо ключ пропустити, жодна з перевірок ніде не відповідає. На адресі, яку називає mcp.listen, вони не відповідають ніколи: там вони отримують 404, як і кожен шлях, який вона не обслуговує, бо проба там була б неавтентифікованим читанням слухача, що відхиляє все інше. На відміну від mcp.listen, ця адреса не обмежена й жодна адреса для неї не відхиляється — спрямуйте її на loopback або Unix-сокет, до яких дістається супервізор поруч із цим процесом, і зважте, що будь-хто, хто може дістатися обраної вами адреси, може прочитати ці дві відповіді.

schema/other/aggrega-config.md наводить кожен із цих ключів разом зі значенням за замовчуванням, якщо воно є.

Інші способи розпізнавання кореня проєкту

--workspace-root <path> або відповідна змінна AGGREGA_WORKSPACE_ROOT прямо називає корінь і пропускає виявлення. Названа тека мусить існувати: шлях, що не вказує ні на що або вказує на файл, відхиляється, перш ніж команда зробить будь-що інше, і відмова називає, яке з двох джерел надало значення, та цитує його так, як його задано. Інакше виявлення йде вгору від робочого каталогу, а види якорів ранжуються між собою, а не за близькістю:

  • Файл .aggrega-config.yaml з блоком workspace: перемагає безумовно, на якій би глибині він не лежав. Обхід продовжує підніматися в його пошуках навіть після того, як мине маркер описаного нижче виду, тож явно позначений корінь вище завжди переважає випадковий маркер під ним.
  • Якщо такого немає, корінь закріплює найближчий із цих маркерів, а в межах одного каталогу вони ранжуються в такому порядку: каталог .aggrega/, потім aggregate*.yaml, потім release*.yaml, потім manifest*.yaml.
  • Якщо нічого не знайдено, використовується робочий каталог — команди виконуються, а не відмовляються запускатися. Команда, результат якої залежить від робочого простору, — та, що читає або записує документи робочого простору, читає або заповнює його кеш артефактів чи обслуговує його, — один раз виводить попередження в стандартний потік помилок: warning: <folder> is not inside an Aggrega workspace. To make it one, run: aggrega config init --workspace. Команда, результат якої не залежить від того, яка тека є коренем, нічого не повідомляє, навіть якщо читає конфігурацію: серед них aggrega version, aggrega config show, aggrega plugin list, aggrega registry list, aggrega explain і aggrega login. aggrega config capture, робота якої — записувати власний файл конфігурації робочого простору, у такій теці нічого не записує й завершується з помилкою, яка про це повідомляє.

У такій теці нічого не записується в кеш артефактів. Каталог .aggrega/ сам є одним із наведених вище маркерів, тож кеш, записаний там, зробив би теку робочим простором лише тому, що колись у ній щось завантажили. Команда, робота якої наповнює кеш, — aggrega pull, збірка, що спершу розв’язує свої залежності, aggrega registry update, додавання плагіна-розширення команд із реєстру, — відхиляється, перш ніж щось завантажить, і називає теку та два виходи: назвати робочий простір через --workspace-root або AGGREGA_WORKSPACE_ROOT чи додати до теки .aggrega-config.yaml з блоком workspace:. aggrega pin і aggrega push для сутності Recipe або FeatureRecipe, яка звіряється з фіксаціями, записаними в entity.lock поруч із нею, наповнюють кеш лише віддаленими джерелами, які сутність повністю виписує і які завантажуються під час їх фіксації або порівняння фіксації: вони відхиляються так само там, де мали б завантажити таке джерело, ще до завантаження. Сутність без такого джерела — зовсім без джерела, з локальним джерелом або з джерелом, координати якого заповнює кожна сутність Release, — фіксується чи публікується там так само, як деінде. Збірка там не відхиляється, але зовнішній вхід, який фіксує її lock-файл і якого кеш більше не містить, не завантажується повторно для відновлення: рендеринг отримує те саме речення замість цього входу, так само як отримує речення офлайн-режиму, і повідомляє про нього. Те, куди artifact_cache_dir поміщає кеш, тут нічого не змінює, бо каталог приєднується до знайденого кореня. Команди, що лише читають, і далі відповідають.

Цей останній запасний варіант має один виняток. Коли корінь ніщо не назвало, а робочий каталог нічого не закріплює, команда щодо однієї сутності Release або одного документа сутності, яка називає цей файл абсолютним шляхом, знову виявляє корінь, ідучи вгору від теки, де лежить файл, і використовує все, що знайде: робочий простір, до якого належить файл, або, якщо не знайдено нічого, саму цю теку. Цей файл — той, який називає --release у aggrega build і aggrega pull; сутність Release, передана aggrega validate, aggrega lint і aggrega inspect, або інакше переданий їм файл; і документ, переданий aggrega pin, aggrega push і aggrega edit-document. Тож сутність Release проєкту, зібрана ззовні проєкту, читає власну конфігурацію проєкту, як і тоді, коли команда виконується всередині нього, а попередження конфігурації, які виводить команда, належать цьому робочому простору. Якщо власна тека файлу теж нічого не закріплює, саме цю теку називає повідомлення команди і саме в ній не записується кеш. Відносний шлях читається відносно каталогу, у якому ви запускаєте команду, і нічого не змінює, а названий корінь або робочий каталог, який сам лежить у робочому просторі, використовується як є. Сервер асистента застосовує те саме правило до виклику, що називає свою сутність Release або документ абсолютним шляхом.

Позначення кореня блоком workspace: — явний вибір, якому варто надавати перевагу; маркери-файли й маркери-каталоги дають змогу зібрати навіть проєкт, який його не оголосив.

Явне зазначення глобального файлу

Глобальний шар розв’язується в такому порядку:

  1. --config <path> — форма для окремого виклику.
  2. Змінна середовища AGGREGA_CONFIG.
  3. Розташування за замовчуванням: у Windows — aggrega\config.yaml у каталозі, який називає змінна середовища APPDATA, а деінде — aggrega/config.yaml у каталозі, який називає XDG_CONFIG_HOME, із запасним варіантом ~/.config/aggrega/config.yaml.

Перші два називають явний файл, тож неіснуючий шлях — це гучна помилка, а не тихий перехід до запасного варіанта: ви просили конкретний файл. Команда, що читає свою конфігурацію, зупиняється з одним реченням, яке закінчується шляхом, щоб ви могли його скопіювати. aggrega config init є винятком, бо створення цього файлу — її призначення: вона створює названий файл і повідомляє про це. Розташування за замовчуванням завантажується, коли файл там є, і тихо пропускається, коли його немає. Хоч який файл розв’яжеться, файли вашого проєкту все одно накладаються поверх нього.

Коли жоден із цих варіантів не розв’язується — жоден файл не названо, а змінні, з яких читається розташування за замовчуванням, не задано, — команда, що записує глобальний файл, зупиняється й називає, що слід задати. Змінні середовища наводять для кожної платформи змінні, з яких читається кожне розташування.

Цей вибір також визначає, куди записує команда, що змінює конфігурацію. Команда, запущена з --config <path>, читає конфігурацію з цього файлу й застосовує свою зміну до того самого файлу, тож те, що записує одна команда, наступна прочитає назад.

До якого з двох файлів команда записує за замовчуванням, залежить від природи налаштування: загальномашинні інструменти, як-от реєстр, ідуть у глобальний файл, а налаштування, що беруть участь у збірці, як-от прив’язка провайдера чи під’єднання сокета, — у закомічений файл проєкту, тож вони переміщуються разом із проєктом. Щоб змінити це, передайте --global або --workspace, і команда виведе файл, у який записала.

Див. також

  • aggrega-config.md — команди aggrega config, які створюють початкову конфігурацію, переглядають і фіксують її.
  • environment-variables.md — кожна змінна з префіксом AGGREGA_ і те, де передаються секрети.
  • global-flags.md — --config, --workspace-root та інші прапорці, які приймає кожна підкоманда.
  • schema/other/aggrega-config.md — кожен ключ конфігурації, його тип і значення за замовчуванням.
  • aggrega-cache.md — що насправді містить artifact_cache_dir.
  • workspace-boundary.md — які шляхи залишаються всередині робочого простору і як каталоги та файли, які називає ця конфігурація, виходять за його межі.
  • aggrega-mcp.md — сервер, який налаштовує блок mcp.