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

Огляд CLI

CLI aggrega — це точка входу компілятора. Кожна взаємодія з Aggrega — компіляція сутності Aggregate у придатні до розгортання артефакти, перегляд каталогу або IR, розв’язання та фіксація залежностей, публікація сутностей каталогу, перевірка коректності за допомогою validate, перевірка домовленостей щодо публікації за допомогою lint та обслуговування IDE — виконується через підкоманду aggrega. Цей набір розділів описує прапорці, вхідні та вихідні дані кожної підкоманди.

aggrega validate і aggrega lint — це взаємодоповнювальні засоби перевірки, що віддзеркалюють три області дії одне одного: увесь каталог, замикання залежностей сутності Release або одну сутність. aggrega validate перевіряє коректність (схему, стовпи, розв’язання посилань, extends, здатність провайдера щодо типів вхідних даних і — для сутності, що рендериться, — ізольований рендеринг); aggrega lint перевіряє домовленості щодо публікації (іменування, відповідність каталогів категоріям, префікси анотацій і розмір підвищення версії). Жодна з команд не створює артефактів; використовуйте validate, щоб відповісти на питання «чи це коректно?», і lint, щоб відповісти на питання «чи відповідає це дисципліні публікації каталогу?».

aggrega build дотримується принципу єдиної точки входу: сутність Release — єдиний вхід компіляції. aggrega build --release release.yaml зчитує вказівники aggregate: і manifest: сутності Release, щоб знайти решту топології, і створює вивід для кожної межі в dist/: іменована межа рендериться в оголошений нею directory: або в dist/boundaries/<boundary-name>/, якщо вона його не оголошує; сутність Release, що оголошує верхньорівневий components: замість іменованих меж, рендериться пласко в dist/. Кожен компонент, що міститься в топології, має належати одній із цих меж, а компонент, якого не містить жодна з них, зупиняє збірку: компонент потрапляє до межі або тому, що його названо в components: цієї межі під ідентифікатором, який він має після сплощення вкладених сутностей Aggregates, або тому, що він міститься у вкладеній сутності Aggregate, яку межа підключає через aggregates:. Компонент, що не потрапляє до межі жодним зі способів, рендерився б поза всіма межами, які оголошує Release, не отримуючи ні розташування виводу, ні хвилі синхронізації, ні анотацій, ні власного infra:, тож збірка зупиняється й називає цей компонент, а не створює артефакти, до яких конфігурацію меж сутності Release так і не було застосовано. Те саме відношення перевіряється і з боку Release: запис межі, що називає компонент, якого немає в топології, нічого не конфігурує, тому він також зупиняє збірку, а діагностика повідомляє ідентифікатор, до якого звертався запис. aggrega pull так само приймає Release як вхід; aggrega inspect приймає будь-яку сутність — ім’я в каталозі, файл сутності, посилання на реєстр або Release; aggrega push приймає сутність каталогу; aggrega validate і aggrega lint приймають сутність каталогу, сутність Release (через --release) або весь каталог; aggrega serve працює як довготривалий процес. На сторінці глобальних прапорців описано прапорці, що застосовуються до всіх підкоманд.

Що реліз може змінити в командах, прапорцях та інструментах асистента — і чого патч-реліз ніколи не змінює, — описано в розділі Сумісність.

Довідник за командами

  • aggrega build — основна команда компіляції. Читає вказівник на сутність Release, розв’язує сутності Aggregate і Manifest, на які він посилається, і видає скомпільовані артефакти для кожної межі.
  • aggrega inspect — зручне для читання подання будь-якої сутності: сутності каталогу за ім’ям, файлу сутності за шляхом, опублікованої сутності, прочитаної безпосередньо з її реєстру, або повністю розв’язаної сутності Release, граф IR якої --ir-graph записує як JSON, а замикання залежностей якої виводить --closure.
  • aggrega pull — розв’язати залежності сутності Release і записати lock-файл для цієї сутності Release, що фіксує кожну залежність; кешувати сутності каталогу та вихідні артефакти.
  • aggrega push — опублікувати сутність каталогу в реєстрі OCI, за потреби підписавши її під час публікації.
  • aggrega sign — підписати один або кілька вже опублікованих артефактів і приєднати кожен підпис як OCI referrer.
  • aggrega auth token — інтерактивно отримати токен ідентичності OIDC і вивести його в stdout, щоб пройти автентифікацію один раз для пакета безключових підписувань.
  • aggrega registry — керувати реєстрами, відомими робочому простору, і їхньою політикою довіри до підписів: додавати, переглядати й вилучати записи, а також створювати локальний індекс для пошуку опублікованих метаданих каталогу за допомогою registry update.
  • aggrega search — шукати в локальному індексі налаштованих реєстрів опубліковані сутності каталогу та плагіни CLI, які можна встановити, за довільним текстовим запитом і необов’язковими фасетними фільтрами.
  • aggrega validate — перевірити коректність (схему, опори, розв’язання посилань, extends, підтримку видів вхідних даних, ізольований рендеринг) для всього каталогу, замикання залежностей сутності Release (--release) або однієї сутності.
  • aggrega lint — перевірити домовленості щодо публікації для всього каталогу, замикання залежностей сутності Release (--release) або однієї сутності; --pre-publish додає перевірку зміни версії з урахуванням реєстру.
  • aggrega serve — довготривалий демон «компілятор як сервіс» (JSON-RPC через stdin/stdout) для інтеграції з IDE.
  • aggrega version — вивести версію CLI; -o json видає машинозчитуваний об’єкт.
  • aggrega get-schema — вивести канонічну JSON Schema для виду сутності або контракту; --list перелічує всі види. Це авторитетна форма, за якою слід створювати файл.
  • aggrega scaffold — вивести початковий документ для виду сутності, побудований зі схеми цього виду: обов’язкові поля, де фіксовані заповнено, а скрізь, де потрібне значення, стоїть заповнювач. Під час створення чернетки файл не записується; перенаправте вивід куди потрібно. З --example команда натомість записує один із готових до запуску прикладів документації в новий каталог, а --example --list перелічує їх.
  • aggrega mcp — запустити сервер Model Context Protocol через стандартні введення й виведення або через HTTP, щоб клієнт із підтримкою MCP став помічником зі створення, обізнаним з Aggrega. Див. Створення файлів Aggrega.
  • aggrega skills — встановлює навичку, яка вчить AI-асистента встановлювати й використовувати Aggrega, у теку навичок цього асистента — для одного проєкту або, з --global, для всіх ваших проєктів.
  • aggrega cache — перегляд і обслуговування кешів на диску: виведення їхнього вмісту, звільнення записів кешу артефактів, на які не посилається жоден lock-файл, скорочення кешу скомпільованих модулів до обмеження розміру або повне очищення всіх кешів.
  • aggrega config — перегляд і керування конфігурацією, яку читає Aggrega: показ чинних налаштувань і того, який рівень визначив кожне з них, створення робочої конфігурації та фіксація критичних для збірки налаштувань у робочому просторі.
  • aggrega deprecate — додавання підписаної позначки про застарілість до вже опублікованого артефакту.
  • aggrega edit-document — застосування до документа одного обмеженого структурованого редагування зі збереженням кожного байта, якого воно не торкається.
  • aggrega explain — пояснення умови зупинки, яку позначає код.
  • aggrega import — перетворення стороннього опису джерела на чернеткові файли для створення в Aggrega.
  • aggrega login — автентифікація в реєстрі OCI та збереження облікових даних, які пред’являють push, pull і lint --pre-publish.
  • aggrega logout — видалення збережених облікових даних реєстру.
  • aggrega pin — запис закріплень вмісту для зовнішніх вхідних даних сутності в entity.lock поруч із нею.
  • aggrega plugin — виведення списку плагінів Wasm, які може розв’язати CLI, додавання або видалення прив’язки робочого простору та перевірка гостьового модуля перед його публікацією.
  • aggrega push-artifact — публікація самостійного артефакту даних, наприклад пакета документації, у реєстрі OCI в його просторі імен docs/.
  • Конфігурація — у якому файлі має бути налаштування і як поєднуються рівні. Почніть звідси: розділ відкривається двома файлами, потрібними більшості проєктів, а механізми, до яких вдається більший проєкт, описує далі.
  • Глобальні прапорці — прапорці, спільні для підкоманд (корінь робочого простору, глобальний файл конфігурації, кольоровий і простий доступний вивід та офлайн-режим). Офлайн-режим доступний також як налаштування конфігурації та змінна середовища — див. Конфігурація, схему конфігурації і змінні середовища.
  • Межа робочого простору — що лежить усередині робочого простору, як символьне посилання, що веде за його межі, впливає на кожен вид шляху, які шляхи навмисно виходять назовні і що робити, коли такий шлях відхилено.
КомандаОпис
aggrega authКерувати ідентичністю для підписування
aggrega buildСкомпілювати Aggregate і Release в артефакти, рідні для провайдера, у dist/ у корені робочого простору
aggrega cacheПереглядати й обслуговувати кеші на диску
aggrega configПереглядати й керувати конфігурацією робочого простору
aggrega deprecateПриєднати підписану позначку застарілості до вже опублікованого артефакту
aggrega edit-documentЗастосувати до документа одне обмежене структуроване редагування, зберігши кожен байт, якого воно не торкається
aggrega explainПояснити умову зупинки, яку позначає код
aggrega get-schemaВивести JSON Schema для виду сутності або контракту
aggrega importПеретворити сторонній опис джерела на чернетки файлів Aggrega
aggrega inspectПереглянути сутність каталогу за назвою, файл сутності за шляхом або опубліковану сутність за посиланням на реєстр
aggrega lintПеревірити домовленості щодо публікації в каталозі для всього каталогу, сутності Release або однієї сутності
aggrega loginАвтентифікуватися в реєстрі OCI і зберегти облікові дані
aggrega logoutВилучити збережені облікові дані реєстру
aggrega mcpЗапустити сервер Model Context Protocol через стандартні введення й виведення або через HTTP для інтеграції з ШІ-помічниками
aggrega pinЗаписати фіксації вмісту для зовнішніх вхідних даних сутності в entity.lock поруч із нею
aggrega pluginПереглянути плагіни Wasm, які може розв’язати CLI
aggrega pullРозв’язати залежності каталогу й джерел у кеш і записати lock-файл для сутності Release
aggrega pushЗапакувати й опублікувати сутність каталогу в реєстрі OCI
aggrega push-artifactОпублікувати окремий артефакт даних (наприклад, пакет документації) в реєстрі OCI
aggrega registryКерувати реєстрами та їхньою політикою довіри до підписів
aggrega scaffoldСтворити початковий документ для виду сутності або записати готовий до запуску приклад у новий каталог
aggrega searchШукати в локальному індексі налаштованих реєстрів
aggrega serveПрацювати як довготривалий «компілятор як сервіс» через JSON-RPC 2.0 на stdin/stdout
aggrega signПідписати один або кілька вже опублікованих артефактів і приєднати їхні підписи
aggrega skillsВстановити навичку Aggrega в AI-асистента
aggrega validateПеревірити коректність для всього каталогу, сутності Release або однієї сутності
aggrega versionВивести версію CLI aggrega

Позиційні аргументи та код завершення

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

Нерозпізнана команда також підказує, як знайти плагін CLI з такою назвою. Відповідь береться з локального індексу типового реєстру, який будує aggrega registry update і читає aggrega search, тож вона повертається одразу, а помилково введене слово ніколи не надсилається до реєстру — ні онлайн, ні офлайн. Якщо індекс містить плагін CLI з такою назвою, повідомлення називає команду aggrega plugin add cli <name>, яка його встановлює. Якщо індекс не містить жодного, воно називає пошук, який його шукає, aggrega search <name> --kind plugin --plugin-type cli. Якщо індекс ще не побудовано, воно називає aggrega plugin add cli <name>, яка шукає плагін за цією назвою в реєстрі й відмовляє, якщо жодного не опубліковано. Будь-яка з цих команд містить назву, взяту в лапки для оболонки там, де це потрібно.

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

Хід виконання і як довго команда чекає на реєстр

Команда, яка чекає, повідомляє, на що вона чекає. Щоразу, коли команда чекає на реєстр, на завантаження або на першу компіляцію плагіна, вона показує цей крок у стандартному потоці помилок, так само як aggrega build і aggrega pull показують свої: у терміналі — рядок із назвою кроку, анімованим індикатором і часом, який він уже зайняв, позначений галочкою після завершення кроку й залишений без галочки, якщо крок завершився невдало; у терміналі, який не може перемальовувати рядок на місці, або з --plain — по одному рядку на крок у момент його завершення, із його часом. Якщо стандартний потік помилок не є терміналом, нічого не показується, і те, що команда виводить у стандартний потік виводу, у жодному разі не змінюється. Крок показується лише доти, доки команда справді на нього чекає, тож запуск, обслужений із кешу, не показує нічого, а компіляція плагіна показується лише тоді, коли вона триває достатньо довго, щоб бути справжньою компіляцією, а не взятою з кешу.

Команди, які показують свої кроки в такий спосіб, крім команди кожного встановленого плагіна CLI:

aggrega config init, aggrega deprecate, aggrega explain, aggrega import, aggrega inspect, aggrega lint, aggrega plugin add, aggrega plugin gen-catalog, aggrega plugin run-local, aggrega plugin sync, aggrega push, aggrega push-artifact, aggrega registry add, aggrega scaffold, aggrega sign, aggrega validate

Жоден запит не чекає на сервер безкінечно. Запит чекає щонайбільше 30 секунд, поки сервер почне відповідь після того, як запит надіслано повністю, і щонайбільше 30 секунд на наступну частину відповіді, яка вже надходить. Сервер, який змушує запит чекати довше, відхиляється з кодом E0376, що називає сервер і час очікування. Обмежено лише очікування: завантаження чи вивантаження, яке продовжує просуватися, триває стільки, скільки потрібно. Helm-чарт, який source: сутності Recipe отримує через HTTPS, підлягає лише першому з двох очікувань, а про його спливання повідомляється власними словами мережевої бібліотеки, а не під кодом E0376. Запит, який команда й так повторює в разі тайм-ауту, — читання під час aggrega registry update, запис під час публікації — повторюється до того, як буде повідомлено про відмову.

Обхід повного переліку репозиторіїв реєстру завершується протягом п’яти хвилин. Деякі реєстри збирають усі репозиторії, які вони містять, ще до того, як відповісти на запит переліку, тому на кожну сторінку переліку чекають стільки, скільки може тривати обхід, а не 30 секунд; перелік, який не завершився через п’ять хвилин, зупиняється й відхиляється з кодом E0377. aggrega plugin add обходить перелік лише тоді, коли жоден плагін не має точно тієї назви, яку йому передано, щоб знайти такий, назва якого її містить, тож якщо вказати точну назву плагіна, очікування на обхід ніколи не виникає.

На реєстр, який просить сповільнитися, команда чекає, доки він не проситиме про це п’ять хвилин без перерви. Команда чекає стільки, скільки просить такий реєстр, надсилає йому менше запитів одночасно й показує очікування разом з рештою свого прогресу; реєстр, який протягом п’яти хвилин не відповідає нічим, крім «сповільніться», відхиляється з кодом E0378. Як це відбувається, описано в розділі Реєстр, який просить сповільнитися.

Усі три обмеження фіксовані; немає жодного параметра, який би їх змінював.

Шляхи, які ви вводите, і межа робочого простору

Шлях, який ви вводите в командному рядку, — --release, --catalog, --output-dir, файл для перевірки, лінтингу, закріплення чи публікації, --workspace-root — використовується там, куди він веде, усередині робочого простору чи поза ним, через будь-яке посилання на шляху. Те, що команда потім читає й записує від власного імені, обмежено робочим простором, хоч би хто її запускав: вона не читає конфігураційних файлів робочого простору, документа каталогу, документа поруч із сутністю Release чи lock-файлу сутності Release через посилання, що веде за межі робочого простору, не переходить шляхом, який Release або Manifest виводить за його межі, і не записує свій вивід, свій lock-файл чи свій кеш через таке посилання. Каталог, який ви вказуєте поза робочим простором, обмежено так само щодо того, що лежить у ньому, а Release, яку ви вказуєте поза робочим простором, має доступ лише до файлів у власному каталозі. aggrega edit-document — єдина команда, введений шлях якої також обмежено: вона редагує лише документ, що міститься в робочому просторі. Межа робочого простору описує це правило, шляхи, що навмисно виходять за межі, і спосіб усунення кожної відмови.

Пошук в індексі каталогу

aggrega search [query] шукає опубліковані сутності в усіх реєстрах, відомих робочому простору. Необов’язковий [query] — це підрядок без урахування регістру, який зіставляється з назвою та описом кожної сутності. Фільтри за фасетами звужують набір результатів:

  • --kind обмежує пошук одним або кількома видами сутностей (component, feature, recipe, featurerecipe, workload, plugin); його можна повторювати, він не враховує регістр, а види поєднуються через АБО.
  • -l/--selector фільтрує за мітками каталогу сутності. Категорія — це мітка, а не окремий прапорець: -l component.aggrega.ai/category=datastore.
  • --capability і --plugin-type фільтрують плагіни за оголошеною можливістю або типом сокета; --capability можна повторювати, і значення поєднуються через АБО.
  • --registry обмежує пошук одним реєстром за хостом або зручним псевдонімом; за замовчуванням пошук виконується в усіх налаштованих реєстрах.
  • --limit обмежує кількість результатів.
  • -o/--output вибирає формат виводу: table (за замовчуванням, зручний для читання людиною), json (машинозчитуваний масив) або names (лише ідентифікатори, по одному в рядку).

Пошук завжди читає локальний індекс — офлайн-знімок, який створює та оновлює aggrega registry update. Він не звертається до мережі й нічого не завантажує на вимогу. Якщо індексу немає, команда завершується з помилкою й пропонує спершу виконати aggrega registry update. Кожен запуск виводить у стандартний потік помилок рядок актуальності «last updated» для кожного реєстру, тож вивід json і names у стандартному потоці виводу лишається чистим для скриптів.

Автодоповнення в оболонці

aggrega completion <shell> виводить у stdout скрипт автодоповнення для bash, zsh, fish або powershell. Скрипт генерується з актуального дерева команд CLI в момент запуску, тому він завжди відображає команди й прапорці того бінарного файлу, який його створив, — немає статичного файлу, який довелося б генерувати заново в міру розвитку CLI.

Щоб спробувати автодоповнення в поточному сеансі, нічого не встановлюючи, завантажте скрипт безпосередньо через source:

Terminal window
source <(aggrega completion bash)

Щоб установити автодоповнення назавжди, запишіть скрипт у розташування, яке ваша оболонка зчитує під час запуску.

bash

Автодоповнення в Bash залежить від пакета bash-completion; установіть його через менеджер пакетів вашої ОС, якщо його ще немає.

Terminal window
# Linux
aggrega completion bash > /etc/bash_completion.d/aggrega
# macOS (Homebrew)
aggrega completion bash > $(brew --prefix)/etc/bash_completion.d/aggrega

zsh

Якщо автодоповнення у вашій оболонці ще не ввімкнено, увімкніть його один раз:

Terminal window
echo "autoload -U compinit; compinit" >> ~/.zshrc

Потім запишіть скрипт автодоповнення в каталог, що входить до вашого fpath:

Terminal window
# Linux
aggrega completion zsh > "${fpath[1]}/_aggrega"
# macOS (Homebrew)
aggrega completion zsh > $(brew --prefix)/share/zsh/site-functions/_aggrega

fish

Terminal window
aggrega completion fish > ~/.config/fish/completions/aggrega.fish

powershell

Додайте згенерований скрипт у кінець свого профілю PowerShell, щоб він завантажувався в кожному сеансі:

Terminal window
aggrega completion powershell >> $PROFILE

Запустіть нову оболонку, щоб установлене автодоповнення набуло чинності.