コンテンツにスキップ
AggregaAggrega
言語の選択: 日本語
このページは機械翻訳されています。英語の原文を読む。

設定

aggrega が設定をどこから読み込むか、またある設定をどのファイルに書くかについて説明します。

シンプルなケース

ファイルは 2 つで、ほとんどのプロジェクトはそれ以外に何も必要としません。

プロジェクト内の 1 つのファイルは .aggrega-config.yaml という名前で、プロジェクトルートに置かれます。このファイルには このプロジェクトのビルド方法を記述します。どのディレクトリがベンダリングされたカタログコンテンツを保持するか、どのプラグインが どのターゲットをレンダリングするか、どの lint ルールを緩和するか、ローカルキャッシュをどこに置くか、です。このファイルはコミットされるため、 プロジェクトをクローンしたチームメイトも同じ方法でビルドできます。

その workspace: ブロックが、ディレクトリをプロジェクトルートとして示すものです。

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

このブロックが保持するのはルートを定義するカタログディレクトリだけで、その他の設定はすべてその横の トップレベルに置きます。カタログコンテンツをベンダリングしないプロジェクトでも、ブロックは空のまま workspace: {} と記述します。ブロックが存在すること自体が目印だからです。

マシン上の 1 つのグローバルファイルは ~/.config/aggrega/config.yaml にあります。Windows では、 APPDATA 環境変数が示すディレクトリ内の aggrega\config.yaml です。そのマシン上のすべてのワークスペースは このファイルを通じて解決され、このファイルには 特定のプロジェクトではなくマシンに属する 設定を記述します。プル元のレジストリとそれぞれの署名信頼ポリシー、コンパイル済みモジュールストアの 最大サイズ、インストールしたコマンド拡張プラグインです。これらはどこで作業していても 同じなので、一度だけ宣言することに意味があります。このファイルは存在すれば自動的に読み込まれ、 存在しなくても何も壊れません。

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

aggrega config init はこのグローバルファイルを書き出し、レジストリをそれが公開する 署名信頼ポリシーとともに登録し、ファイルがマシン上のどこにあるか、マシン全体のキャッシュが どこに保持されるかを示します。aggrega config show は現在適用されている設定を表示し、 aggrega config show --origin は各設定をどのファイル(またはどの環境変数)が決定したかを 示します。

シークレットは設定ではありません。 レジストリのパスワードや署名用 ID トークンが どちらのファイルのフィールドになることもありません。これらは必要な時点で環境変数またはフラグで 指定します。environment-variables.md を参照してください。

ローカルエンティティの読み込み元

独自のカタログコンテンツ(Component、Feature、Recipe、ライブラリ種別のいずれか)を持つプロジェクトには、 そのコンテンツの置き場所を示す方法が 2 つあり、1 つ目はまったく設定を 必要としません。

プロジェクトルートの catalog ディレクトリは、何かが指定しているかどうかに関係なく読み込まれます。 エンティティを <project>/catalog/ 以下に置けば、カタログを読み込むすべてのコマンドがそれを読み込みます。 workspace: ブロックが空のプロジェクトでも同様です。カタログディレクトリは再帰的に読み込まれるため、 その中のサブディレクトリの構成は自由です。

workspace.catalog_dirs に列挙したディレクトリも読み込まれ、しかも先に読み込まれます。 このリストは順序付きの検索スタックです。ある ID を最初に宣言したディレクトリがその ID を所有し、 後のディレクトリにある同じ ID はシャドウされます。catalog は列挙したすべてのディレクトリの後に読み込まれます。ただし、 列挙したディレクトリがすでにそれを含む場合は、そのディレクトリの一部として読み込まれます。したがって、 ディレクトリを列挙すると既存の内容を置き換えるのではなく追加することになります。コマンドラインで繰り返し指定できる --catalog <dir> はその両方より先に読み込まれ、そこで指定した相対パスは、どの設定ファイルも宣言していないため、 コマンドを実行したディレクトリを基準に解決されます。複数回指定された ディレクトリ(コマンドラインとリストの両方、またはリストに 2 回)は、最初に指定された位置で 1 回だけ読み込まれるため、 その中の何かが自分自身によってシャドウされたと報告されることはありません。シャドウは常に、異なる 2 つの ファイルが 1 つの ID を宣言することを指します。1 つのディレクトリの 2 通りの表記、リンクを経由したパス、そして 大文字小文字を区別しないファイルシステムでの大文字小文字が異なる表記は、いずれも同じ 1 つのディレクトリを指します。列挙した別のディレクトリの 内側にあるディレクトリも、独立したエントリとして読み込まれます。Release ごとに カタログのバリアントを持つプロジェクトでは、代わりに各 Release に独自のリストを与えることができます。 Release に独自のカタログディレクトリを与えるを参照してください。

ディレクトリを列挙することが、プロジェクト外に置かれたエンティティを読み込む方法です。 列挙したディレクトリは どこにあっても構いません(隣接するチェックアウト、他のプロジェクトと共有するディレクトリなど)。それ自体がシンボリックリンクであっても、 その場所で読み込まれます。それ以外の手段ではそこまで届きません。プロジェクト内から 外部を指すリンクは辿られず、プロジェクト外のファイルをパスで指定するドキュメントは拒否されます。 そのため、外部に置かれたエンティティには、それを保持するディレクトリを列挙し、エンティティを 名前で指定することで到達します。プロジェクト外の列挙したディレクトリはそれ自体が独立したルートなので、その配下から 外部を指すリンクも読み込まれません。ワークスペース境界にルール全体が記載されています。

列挙するディレクトリはディレクトリでなければなりません。 何も存在しない、またはファイルやどこにも通じないリンクがある列挙パスは、カタログを読み込むすべてのコマンドによって、何かが読み書きされる前に拒否されます。プル、ビルド、検証、検査、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

ディレクトリを作成するか、エントリを削除してください。プロジェクトが列挙している隣接チェックアウトを含めずに取得したプロジェクトのコピーはそのエントリを削除し、そのチェックアウトが提供するはずだったものをレジストリから解決します。Release 独自のエントリが列挙するディレクトリ、パイプラインが所有する設定ファイルまたはグローバルファイルが追加するディレクトリ、そして AGGREGA_CATALOG_DIRS が持つディレクトリについても同様で、最後の場合、拒否はファイルの代わりにその変数を示します。設定自体は引き続き読み込まれるため、カタログを読み込まないコマンドは引き続き実行されます。存在しない --catalog ディレクトリは 1 つのコマンドのために入力されたものであり、aggrega build はそのディレクトリを示して拒否します。存在するが読み取れない列挙ディレクトリは、カタログ全体を読み込むコマンドによって、そのディレクトリを示して拒否されます。

リストを空として記述すると、このプロジェクトにはローカルカタログがまったくないことを表します。これは catalog の読み込みも止める唯一の書き方です。

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

キーを省略するのは別の意味になります。リストの省略は通常のケースであり、catalog は引き続き読み込まれます。

ビルド、プル、検証、または aggrega inspect が、使用した名前に該当するエンティティを見つけられない場合は、このプロジェクトがローカルエンティティをどこから読み込むか、指定したエンティティが読み込まれるようにするには何を変更すればよいかを示します。空のリストを記述した場合は、そのようなことは何も示しません。ローカルカタログを読み込まないことはそこで宣言した内容であり、変更を提案することはその宣言に反論することになるからです。また、その名前を宣言するドキュメントが読み込まれて拒否された場合も示しません。そのドキュメントはすでにカタログが読み込む場所にあるため、レポートは代わりにドキュメントが違反している内容(行と制約)を示し、移動しても何も解決しません。宣言する名前すら読み取れないほど形式が不正なドキュメントは、使用した名前と照合できないため、この説明は引き続き示されます。さらに、そのドキュメントが Aggrega の apiVersion を宣言している場合、Release のビルド、プル、または検証は、開くべきファイルである可能性があるため、説明と並べてそのドキュメントをパーサー自身の理由とともに示します。エンティティを見つけたものの受け入れられなかった失敗(lockfile が固定しているバージョンでレジストリが別のバイト列を提供している、エンティティが持つファイルを読み取れない、など)もエンティティの欠落ではなく、それ自体の対処法だけを報告します。

プルまたはプッシュがエンティティを固定するかどうか

Recipe または FeatureRecipe は、読み込む入力(完全に記述されたリモートの source:、 artifacts エントリがインポートするファイル、隣にある source: のファイル)の固定情報を隣の entity.lock に保持し、その記録は エンティティ作成者の手順である aggrega pin で行います。デフォルトでは、pull も push もその手順を実行しません。プルは lock が固定していないエンティティで停止し、プッシュはその公開を拒否します。 コマンドごとに 1 つずつある 2 つのキーにより、その手順の実行をそのコマンドのデフォルトにできます。

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

各キーはそれぞれのコマンドだけを制御し、それ以外には影響しません。また各コマンドの --pin-sources は 自身のキーを両方向に上書きします。--pin-sources=false は、固定するよう設定されたプロジェクトで 1 回の実行だけその手順を無効にします。自身の lockfile を埋めるビルドはプルであり、 pin_sources_at_pull に従います。これらのキーはグローバルファイルではなくプロジェクトファイルに置きます。 プロジェクトのプルが固定情報を記録するかどうかはそのプロジェクトのポリシーであり、クローンしたチームメイトも 同じ結果を得るべきだからです。pin_sources_at_pull は、他者の固定されていないカタログを利用するプロジェクトが、 プルのたびに停止する代わりに一度だけ固定情報を記録する方法でもあります。

どのプラグインがケイパビリティをレンダリングするか

Recipe は、レンダリングに使うケイパビリティを capability: helm のように指定し、そのケイパビリティを提供するプラグインがレンダリングを行います。あるケイパビリティを提供するプラグインがちょうど 1 つであれば、設定は不要です。複数ある場合は、plugins.providers のエントリがプラグインの識別子によってどれを使うかを指定します。

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

pull はエントリを解決し、選んだプラグインを Release のロックファイルに記録します。build はロックファイルに記録されたものを通じてレンダリングするため、ここでの編集は次の pull で反映されます。

uri はプラグインをその識別子 provider/<name> で指定し、公開されている場所で指定することはありません。 aggrega plugin add provider <query> --capability <capability> はエントリをこの形で、バージョンなしで書き込みます。エントリはどのプラグインがケイパビリティを提供するかを選び、バージョンは Recipe がピン留めしたもの、なければ利用可能な最も高いものとなり、ロックファイルには pull が選んだものが記録されます。コンパイラが内蔵するプラグインはコンパイラ自身のバージョンで提供されるため、そうしたプラグインのエントリに書かれたバージョンは、それがまさにそのバージョンである場合にのみ解決されます。uri がレジストリの場所(oci://hub.aggrega.ai/plugin/provider/helm)であるエントリはどのプラグインの識別子も指定しておらず、ファイルの読み込み時に、そのエントリと書くべき形を示して拒否されます。

エントリはプロジェクト全体に対して一度だけ書かれますが、build は 1 つの Release に対して行われます。 そのため、この Release が要求しないケイパビリティのエントリも有効であり(プロジェクト内の別の Release がそれを読みます)、何も報告されません。各 build と各 aggrega validate --release が検査するのは、Recipe がそのケイパビリティを要求するかどうかにかかわらず、すべてのエントリであり、エントリが指定する内容に基づいて検査します。

  • 指定したプラグインがそのケイパビリティを提供しないエントリは、build を停止させ、検証に失敗します。 pull はプラグインを指定するすべてのエントリを解決し、解決できないものは拒否します。そのため、エントリが一度 pull を経れば、build はそのプラグインを保持しており、何を提供するかを把握しています。build がまだ保持していないプラグインを指定するエントリは、pull がそれを取得した時点で判定されます。 メッセージには、エントリ、プラグイン、 そのプラグインが実際に提供するもの、そして 1 回の編集で届く綴りがあればそれが示されます。これは helm を hlem とするようなタイプミスがとる形です。
  • build が読むどのプラグインも提供しないケイパビリティのみを指定するエントリは警告となり、 build は続行します。それを提供するプラグインは、この build からは見えない別の Release だけが読むものかもしれません。また、プラグインを指定しないエントリは、それがなくてもケイパビリティの解決で選ばれないものを何も選びません。

ここでのケイパビリティにコロンが含まれることはありません。 コロンを含むものは、ファイルの読み込み時に拒否されます。Recipe の capability: は、最後のコロンまでをケイパビリティ、その後ろをバージョンピンとして読まれるため、helm:1.0.0 をキーとするエントリは決して参照されません。バージョンは代わりにプラグイン側(uri: provider/helm:1.0.0)か Recipe でピン留めします。

どのインポーターがソースをドラフトに変換するか

aggrega import は、ソースの形式を公開しているインポーターにソースを渡します。これはカタログ内のものか、コンパイラのコアインポーターのいずれかで、Langflow フローであれば import:langflow です。その形式を公開するインポーターがちょうど 1 つであれば、設定は不要です。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 は、相対パスの指す先で説明するとおりファイルシステムのパスとして読まれ、インポーターを指定しません。

エントリの働きは、指定したインポーターが import の求める形式を公開しているかどうかによって決まります。

  • 公開している場合:そのインポーターが実行されます。 uri が指定するバージョンで、カタログ内でほかにいくつのインポーターがその形式を公開していても実行され、 エントリの with.sources と with.settings が渡されます。エントリは、カタログが 1 つの形式について 2 つの発行元のインポーターを連携させているワークスペースが、どちらを使うかを指定する方法です。
  • 公開していない場合(別の形式のインポーター、別の種類のプラグイン、あるいはカタログにもコンパイラにも存在しないものを指定している場合):そのエントリはその import に関与しません。 何も選ばず、その with はどのインポーターにも渡されません。エントリの設定は指定したインポーターにしか届かないため、形式ごとに 1 つのインポーターをアタッチするワークスペースは、一方の設定が他方に届くことなく、それぞれを設定できます。

その形式を公開するインポーターが複数あり、どれか 1 つだけがアタッチされていない場合(どれもアタッチされていない、またはエントリが 2 つを指定している場合)、import は拒否され、選択できなかったインポーターが示されます。その形式を公開するインポーターを指定していても、カタログ内のどのバージョンも満たさないバージョン(カタログが保持しない厳密なバージョン、またはどのバージョンも該当しない範囲)を指定しているエントリも、別のバージョンで代わりに実行されることはなく、そのバージョンを示して拒否されます。:latest のようにバージョンとして成り立たないものは、不正な形式として拒否されます。コンパイラのコアインポーターのいずれかの Plugin エンティティで、カタログフォルダ内で横にモジュールがないものは候補になりません。コンパイラ自身のバージョンでは代わりにコアインポーターが実行され、それ以外のバージョンでは、エントリがちょうどそのバージョンを指定している場合か、実行可能な同名のインポーターがその形式を公開していない場合にのみ、そのエンティティは候補として残ります。これは独自のインポーターと並んでどれが実行されるかで説明しているとおりです。

各インポーターは 1 つのエントリでアタッチされます。 1 つのインポーターを指定する 2 つのエントリ(同じ識別子で、同じバージョンでも異なるバージョンでも)は、どのコマンドが読む場合でも設定の読み込み時に拒否され、両方のエントリとそれらが書かれたファイルが示されます。この規則はリストに寄与するすべてのファイルにわたります。グローバルファイルのエントリ、プロジェクトのファイルのエントリ、importer_append 下のエントリ、パイプラインの .aggrega-config-append-ci.yaml のエントリがすべて数えられるため、インポーターを新しいバージョンに移すには、その 1 つのエントリのバージョンを変更します。aggrega plugin add importer は、書き込むファイルの plugins.importer リストがすでにそのインポーターを指定している場合、まさにそれを行います。2 つ目を追加するのではなく、エントリの位置と with を保ったまま、そのエントリを解決したバージョンに移します。ほかのリストは読まないため、importer_append 下やパイプラインの .aggrega-config-append-ci.yaml でアタッチされたインポーターは、このコマンドによって 2 回目のアタッチがなされ、その組は設定の読み込み時に拒否されます。そのようなエントリは、書かれている場所でバージョンを変更してください。 uri がファイルシステムのパスであるエントリはインポーターを指定せず、比較されません。また、plugins.governance と plugins.linter のリストはこの規則の対象外です。1 つのプラグインをそれぞれ独自の with で複数回アタッチできます。

import が読み取りに使うパーサーにはエントリは不要です。 インポーターはソースを(形式を指定しない import はその形式の認識を)、ソースの構文に対応するパーサーを通じて読みます。それは、その構文に対してカタログが提供するパーサーであり、カタログがパーサーを提供しない構文については、JSON をはじめとするコンパイラ自体が持つパーサーです。そのため、カタログにパーサーがないワークスペースでも、何も設定せずに Langflow や Flowise のフローを import できます。パーサーをアタッチするリストはありません。ある構文に対してカタログが提供するパーサーが使われ、1 つの構文を提供する異なる名前の 2 つは、 A parse or import format is advertised by more than one plugin(解析またはインポートの形式が複数のプラグインによって公開されています) で説明するとおり拒否されます。

何もない状態から始める

インストール直後の aggrega にはどちらのファイルもありませんが、これは壊れた状態ではなく動作する状態です。すべての設定は組み込みのデフォルトにフォールバックし、コマンドは実行されます。欠けているのは、カタログコンテンツを pull するレジストリと、どの署名を受け入れるかを定めるトラストポリシーであり、まさにそれを 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 のようにポートが後に続く単一の名前。
  • 127.0.0.1 のような IPv4 アドレス、または [::1] のように角括弧で囲んだ IPv6 アドレス。

いずれも任意の :port を付けられ、それ以外は何も付けません。スキーム、パス、認証情報、空白、大文字はいずれも含めません。ポートのない単一の名前はレジストリホストではありません。それはカタログエンティティの名前の最初のセグメント(core/web-api の core)の形であり、この二つを互いに取り違えて読むことがあってはならないためです。

# <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 を示して拒否され、registries[].host としての registry.example.com/charts も同様です(これはパスを持ちません)。ポート 443 は HTTPS で到達するホストのデフォルトポートであるため、hub.aggrega.ai:443 も同様に hub.aggrega.ai を示して拒否されます。一方、localhost やその他のループバックアドレスは平文の HTTP で到達し、そこでは 443 は通常のポートであるため、localhost:443 は書かれたとおりに受け付けられます。空の default_registry はデフォルトレジストリを指定しません。

default_registry はリポジトリパスを持つことができます。 多くのレジストリは、すべてのリポジトリをオーナーやプロジェクトの下に保持します(ghcr.io/<owner>、Harbor では <host>/<project>)。そのようなレジストリをデフォルトレジストリとする場合は、ホストの後にそのパスを続けて書きます。

# <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 に公開し、core/api-server を解決する pull は同じ場所から取得します。そのため、公開時に付与された署名もそこで見つかります。パスは OCI distribution の文法におけるリポジトリパスです。小文字と数字からなる 1 つ以上のセグメントを / でつないだもので、セグメント内は .、_、__、またはダッシュで区切ることができ、タグ、ダイジェスト、末尾の / は持ちません。

パスは、レジストリの信頼のされ方には決して関与しません。 適用されるポリシーを持つ registries エントリ、aggrega login が保存する認証情報、署名要件、信頼されたアイデンティティは、いずれもホストだけで決まります。そのため、上記の ghcr.io のエントリは ghcr.io/acme およびそのホスト上の他のすべてのパスを管理し、パスをどう綴ってもそれを越えることはできません。エントリの host: 自体はパスを持ちません。パスの前のホストが別の綴りで書かれている場合は、書くべき場所を示して拒否されます(GHCR.io/acme と https://ghcr.io/acme は ghcr.io/acme を示します)。また、ホストの後に続くものがリポジトリパスでない場合は、それが続くホストを示して拒否されます。

default_registry は代わりにエントリを指定することもできます。 registries の下にあるエントリの name: として書くと、そのエントリの 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 から来たものでも、一回の aggrega push や aggrega push-artifact の送信先を指定する --registry フラグから来たものでも、同じ文言で拒否されます。このフラグはホストを指定し、それが指示する公開はリポジトリパスなしでそのホストに配置されます。パスは 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 は、コミットされたファイルやエクスポートされた変数で有効にされている場合に、その一回の実行に限り無効にします。値だけを読むレイヤーでは「off」と「指定なし」を区別できないため、すべてのコマンドがフラグのデフォルトを要求したかのように見え、設定済みの値を打ち消す方法がまったくなくなってしまいます。

以上が、単一のマシン上の単一のプロジェクトにおけるモデルの全体です。以下の内容はすべて、これでは収まらなくなったプロジェクトのためのものです。

2 つのファイルを超えて

これらの仕組みは、より大きな構成のために用意されています。関連するプロジェクトをまとめたモノレポ、独自の設定を追加するパイプライン、複数のプロジェクトが拡張する共有カタログなどです。その仕組みが解決する問題を抱えたときに利用してください。

プロジェクト内の複数の設定ファイル

プロジェクトルートからコマンドを実行するディレクトリまでのすべての .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

1 つのファイルがベースのリストとその対応設定の両方を設定している場合、そのファイルの値は、ベースのリストの後ろに追加エントリを続けたものになります。

対応設定を書ける場所について、workspace: ブロックは例外です。このブロックを持つファイルは自身のディレクトリをプロジェクトルートとするため、サブプロジェクトのファイルに workspace.catalog_dirs_append を書くと、外側のプロジェクトに追加するのではなく、独自のプロジェクトを開始してしまいます。カタログディレクトリの対応設定は、グローバルファイルとプロジェクトのルートファイルの間で合成されます。

plugins.cli リストはそれ自体でファイル間を合成し、対応設定はありません。グローバルファイルで宣言したコマンド拡張はすべてのプロジェクトでそのコマンドを登録し、プロジェクトで宣言したものはそのプロジェクトでのみ登録し、両方がともに登録されます。各エントリは 1 つのプラグインを固定します。解決する uri と、aggrega plugin add cli が検証したバイト列の digest で、sha256: の後に小文字の 16 進数 64 桁を続けて書きます。それ以外の表記のダイジェストは解決したバイト列のハッシュと一致することがないため、ファイルの読み込み時にファイルとエントリを示して拒否されます。

Release に独自のカタログディレクトリを与える

プロジェクトは、複数のカタログのバリエーションを並べて保持できます。ターゲットごとに 1 つずつ、それぞれが同じ Components を異なるプロバイダー向けにレンダリングする Recipes を持ち、各 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 を指定でき、ここで指定することがプロジェクトからそれに到達する方法です。ワークスペースの境界で説明するように、それを指すプロジェクト内のリンクは無視されずに読み込まれます。その下の 2 つのキーは、workspace: ブロックでの意味と同じで、その 1 つの 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> は、その 1 回の実行について、引き続き Release のディレクトリより先に検索されます。また、使用した名前でエンティティが見つからない場合、そのエンティティを含むディレクトリを列挙する場所として、その Release のエントリが示されます。

存在しないファイルを指定したエントリは、設定の読み込み時にエントリとファイルを示して拒否されます。したがって、Release の名前を変更すると、エントリも合わせて名前を変更するまですべてのコマンドが停止します。これにより、Release が何の通知もなくワークスペースのリストに対してビルドされることを防いでいます。エントリが列挙するディレクトリは、ワークスペースのリストが指定するディレクトリと同様に、ディレクトリでなければなりません。ディレクトリでないものは、その Release のカタログを読み込むすべてのコマンドによって、エントリとその行を示して拒否されます。

特定の Release に関係しない処理は、引き続きワークスペースのリストを読み込みます。カタログ全体の lint や検証、名前によるエンティティの検索、単独で検査される Aggregate、エディタによるワークスペースのエンティティの一覧表示などです。AGGREGA_CATALOG_DIRS はワークスペースのリストを設定し、ここのエントリには影響しません。また、パイプラインが所有する設定ファイルはマップをまったく読み込みません。

パイプラインが所有する設定ファイル

.aggrega-config-append-ci.yaml という名前のファイルを、探索が訪れる任意のディレクトリで、手書きのファイルの横に置くことができます。これは別のファイルになっているため、自動化されたパイプラインが、人が書いた内容に一切触れることなく、このファイルを所有して丸ごと上書きできます。

このファイルは追加専用です。上記の 5 つのリスト設定に対するエントリは解決済みのリストに連結されます。何かを削除したりスカラー値を上書きしたりすることはできません。このファイルに書かれたスカラーやマップのキーには追加としての意味がないため、黙って適用されるのではなく、無視されて警告で示されます。また、プロジェクトルートを示すこともないため、ディレクトリにこのファイルを置くと、プロジェクトの開始位置を移動させずにアタッチメントを追加できます。

相対パスが指す場所

相対ファイルシステムパスは、それを宣言したファイルのディレクトリを基準に解決されます。プロジェクトルートを基準にするのでも、コマンドを実行したディレクトリを基準にするのでもありません。 これは二度読む価値のあるルールです。プロジェクト相対に見えるパスが別の場所に解決されても、ビルドは意図しない内容に対して成功してしまうからです。

このルールは workspace.catalog_dirs、workspace.releases の下にキーとして置かれる Release ファイルと各エントリが列挙するディレクトリ、plugins.governance または plugins.linter のアタッチメントにおけるローカルファイルシステムパス(ディスク上の .wasm ファイルを指す uri と、そのアタッチメントの with.sources の下の各エントリ)、そして plugins.importer アタッチメントの with.sources の下の各エントリに適用されます。3 つのリストのいずれでも、コロンを含まずレジストリを指さない uri(./lint/api-rules.wasm も importer/agent-flows も同様)はそのようなパスです。一方、プラグインをその識別子で指す uri はコロンの後にバージョンを持ち(importer/agent-flows:1.2.0)、書かれたとおりにそのまま扱われます。importer アタッチメントの uri は、どの importer がソースをドラフトに変換するかで説明するとおり、アタッチする importer を指します。インポートは、そこに書かれたパスからモジュールを読み込みません。 このルールは append コンパニオンの下のエントリにも適用され、それぞれはマージがたまたま終わるファイルではなく、自身を宣言したファイルを基準にします。さらに 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 は、コマンドをどこから実行してもプロジェクトルートを基準に解釈されるため、キャッシュは実行場所ごとではなく 1 つのディレクトリになります。絶対値は 設定の読み込み時に拒否されます。
  • AGGREGA_CATALOG_DIRS は環境変数から来るもので宣言ファイルをまったく持たないため、 絶対パスを指定してください。
  • mcp.listen は書かれたとおりに扱われ、これには unix:<path> 形式のファイルシステムパスも含まれます。同じアドレスは aggrega mcp --listen からも渡され、こちらは 宣言ファイルを持たないため、設定側の表記だけを基準付けすると、1 つの文字列が出所によって 2 つの 異なる場所を指すことになります。ソケットには絶対パスを指定してください。

ストアが共有される 1 つの設定

ほとんどすべての設定は、作業中のプロジェクトに属するものを制御します。どのディレクトリを通じてカタログの内容を解決するか、どのプラグインがターゲットをレンダリングするか、内容をどれだけ厳格に判定するか、デーモンのインメモリキャッシュがどこまで大きくなってよいか、といったものです。プロジェクトのファイルにある値はそのプロジェクト自身のものを制御するため、注意すべき点はありません。

compiled_module_cache.max_bytes は唯一の例外です。上限を設ける対象がプロジェクトごとではないためです。 コンパイル済みのプラグインコードは、マシン上のすべてのプロジェクトが再利用する単一のディレクトリに保持されるため、あるプラグインはプロジェクトごとではなく一度だけコンパイルされます。上限そのものは他の設定と同様に解決されます(プロジェクトのファイルに書けば、そのプロジェクトではその値が優先されます)が、ストアのサイズは 1 つしかなく、有効なサイズは直近のビルドのものです。異なる上限を設定した 2 つのプロジェクトは交互に有効になり、低い上限は、もう一方のプロジェクトがコストをかけてコンパイルしたコードを破棄します。

そのため、ビルドするすべてに対して 1 つの答えを持たせたい場合はグローバルファイルに置き、1 回のビルドがコンパイルする量より大きくしておいてください。aggrega cache status はストアが現在保持している内容を報告し、 aggrega config show --origin は、実行中の上限が実際にどのファイルから来たかを示します。

他者がアクセスするサーバーの設定

aggrega mcp は Model Context Protocol を話します。自分のマシンでは、クライアントがそれを サブプロセスとして起動し、標準入出力を介して通信します。これがデフォルトであり、この形態に関係する設定は、デフォルトのままの mcp.transport と mcp.announce_tools だけです。 mcp ブロックの残りは、mcp.transport: http が選択するもう一方の形態のためのものです。つまり、ホスト上で長時間動作する 1 つのプロセスに、そのキーボードの前にいない呼び出し元が 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> は 1 回の実行に対して同じことを行い、すべてのフラグがすべてのファイルより優先されるのと同様に、キーより優先されます。

mcp.listen はリスナーがバインドする場所を指定するだけで、何も選択しません。 host:port アドレスまたは unix:<path> ソケットを指定します。1 回の実行では aggrega mcp --listen <address> がこれより優先されます。 http が選択され、どちらからもアドレスが与えられない場合、何かがバインドされる前に起動が拒否されます。 stdio が選択されている場合、入力された --listen は拒否され、このキーだけが指定するアドレスは使われません。 サーバーはそのことをエラーストリームに 1 行で出力し、このファイルと mcp.transport: http を示します。そのため、 他者がアクセスするサーバーは上記のとおり両方のキーを設定し、そのファイルが対象とするディレクトリから起動されたクライアントは、引き続き自身のストリームを介してサーバーにアクセスします。unix: パスは基準付けされず、書かれたとおりに扱われます。 相対パスが指す場所を参照してください。

mcp.tls.cert_file と mcp.tls.key_file はプロセス内に TLS を組み込みます。 両方を設定すると、リスナーは 自ら HTTPS を提供します。両方を省略するとプレーンテキストで提供し、これはループバックまたは Unix ソケットでのみ受け入れられます。これは、前段のプロキシが証明書を保持してプロセスに転送する場合に使う形態です。それ以外のアドレスでのプレーンテキストのリスナーは、何かがバインドされる前に この 2 つのキーを示して拒否され、2 つのうち一方だけを設定した場合も同様です。どちらもファイルシステムパスであり、 上記のルールに従います。相対パスはそれを宣言したファイルのディレクトリを基準に解決されるため、 そのファイルの隣にコミットされた証明書は、サーバーがどこから起動されても見つかります。証明書がプロジェクトの外で管理される場合は、 絶対パスで記述してください。

mcp.authorization.issuer と mcp.authorization.resource は、呼び出し元が提示するトークンを誰が発行するか、そしてトークンの発行対象となるリソースとしてこのサーバーが何と呼ばれるかを示します。 http トランスポートが選ばれている場合は両方とも必須であり、これらがなければリスナーは何もバインドする前に拒否されます。エンドポイントへのすべてのリクエストには bearer トークンのチャレンジが返され、行き先を示さないチャレンジにはクライアントが対応できないためです。スキームとホストを含む完全なアドレスを書きます。issuer はその認可サーバーが自身の識別子として示すとおりに、resource は呼び出し元が実際に到達するアドレスとして書きます。前段にプロキシがある場合は、このプロセスがバインドするアドレスではなく、そのプロキシが提示するホストです。両方とも、リスナーが提供する OAuth protected-resource メタデータドキュメントで、資格情報を求めることなく公開されます。クライアントはトークンの取得先を知るためにこのドキュメントを参照します。どちらも秘密情報は保持しません。トークンはそれを提示するリクエストで届き、設定ファイルに書かれることはありません。issuer は、認可サーバーがこのマシン上(localhost、127.0.0.1 または ::1)で動作する場合を除き https アドレスです。その他のホスト上の素の http issuer を指定したリスナーは、キーや呼び出し元をどの方法で読み取るかにかかわらず、何もバインドする前に拒否されます。すべてのクライアントはトークンを取得するために issuer へ送られるため、素の http では認可コードとトークンが保護されないままネットワークを通過し、キーもそこから読み取られる場合は、その経路上にいる誰もがキーを差し替えられるからです。

mcp.authorization.jwks_file は、トークンの検証に用いるキーを保持するファイルを指定します。キーを認可サーバーから読み取る代わりに使います。省略すると、サーバーはその認可サーバーのメタデータを well-known アドレスから読み取り、そこで公開されている jwks_uri に従います。ネットワークにアクセスできるワークスペースではこれが行われます。このキーのアドレスには issuer と同じ規則が適用され、いずれかの読み取りがリダイレクトされる先のアドレスにも同じ規則が適用されます。別のホスト上の素の http のアドレスには問い合わせず、それらのキーを必要とするトークンには、認可サーバーがメタデータとキーを https で公開するまで 503 が返されます。設定すると認可サーバーには一切接続しません。これは offline: true を宣言するワークスペースに必要なものであり、そのようなワークスペースは、この設定がファイルを指定していない限り、リスナーがバインドする前に拒否されます。これはパスであり、上記の規則に従います。相対パスはそれを宣言したファイルのディレクトリを基準に解決されるため、そのファイルの隣にコミットされたキーセットは、サーバーをどこから起動しても見つかります。このファイルが保持するのは公開検証キーであり、認可サーバーが公開するものです。署名するものも秘密のものも含みません。

mcp.allowed_origins は、リクエストが Origin ヘッダーを持つ場合にのみ参照されます。実際には、ブラウザが送信したことを意味します。提供するオリジンをここに列挙します。列挙されていないオリジンを示すリクエストは拒否され、そのヘッダーを持たないリクエストはそれにかかわらず処理されます。ブラウザではないクライアントはそのヘッダーを送らないため、エントリは不要です。エントリはヘッダーと完全一致で比較されるため、ブラウザが送るとおりに書きます。小文字のスキーム、://、小文字のホスト、そしてポートがスキームのデフォルトでない場合に限り : とポートを続け(https://studio.example.com、または自分のマシンで提供するページなら http://localhost:3000)、パスや末尾の / は付けません。それ以外の形のエントリは決して一致しないため、このファイルの読み込み時にそのエントリを示して拒否されます。

mcp.limits は、1 つの呼び出し元が要求できる範囲を制限します。1 つのリクエストボディの最大サイズ、同時に実行されるリクエスト数、1 つの呼び出し元が 1 分間に送信できるリクエスト数です。3 つとも常に有効であり、制限を解除する値はありません。3 つ目の requests_per_minute は呼び出し元ごとに個別に数えられるため、ある呼び出し元が大量に送信しても他の呼び出し元には影響しません。

mcp.authorization.trusted_proxy は、ここでトークンを検査する代わりに、前段のプロキシから呼び出し元を読み取ります。 principal_header に、そのプロキシが呼び出し元を示すために使うヘッダーを設定し、必要に応じて scopes_header に、その呼び出し元のスコープを運ぶヘッダーを設定します。どちらも X-Forwarded-User のような HTTP ヘッダー名です。英字、数字、ハイフン、およびヘッダー名に使えるその他のいくつかの文字からなり、空白やコロンは含みません。それ以外の形の名前はどのリクエストも運べないため、このファイルの読み込み時にそのキーを示して拒否されます。このモードではトークンは一切読み取られず、principal ヘッダーのないリクエストは拒否されます。このときヘッダーが資格情報のすべてとなるため、他の何者もそれを設定できない場合にのみ信頼できます。mcp.listen がループバックまたは Unix ソケットでない限り、プロセスはバインドする前に拒否されます。ブロックを省略すると、このサーバーが自らトークンを検査します。これがデフォルトです。principal_header が空のブロックは、そのデフォルトとして読まれるのではなく拒否されます。

mcp.deny_reach は、このデプロイメントからある種類の到達範囲を取り除きます。 サーバーが行うすべての操作は、自身の効果がどこまで及ぶかを宣言します。読み取りやレンダリングを行い何も残さない操作は none、このプロセスが提供するワークスペース内に書き込む操作は workspace、公開、署名、取り下げを行う操作は registry、ホスト上のすべてのワークスペースが共有するものを変更する操作は machine です。ここで種類を指定すると、その種類に到達するすべてのツールが取り除かれます。そのツールは、呼び出し元のトークンが何を持っていても、すべての呼び出し元のツール一覧から消え、呼び出しはこの設定を示して拒否されます。したがってこれは呼び出し元ではなくデプロイメントの制限であり、どの資格情報でも解除できません。読み取りだけを提供するサーバーは、ここに書き込みを行う 3 つの種類を列挙し、そうするとトークンがすべてのスコープを持つ呼び出し元のためであっても公開できなくなります。省略するとデフォルトとなり、このデプロイメントは呼び出し元のスコープが許すものをすべて提供します。4 つのいずれでもない値は、無視されるのではなく、このファイルの読み込み時に拒否されます。machine の種類のものは、この設定にかかわらず HTTP では一切提供されないため、それを指定しても受け入れられ、何も変わりません。種類とそれを許可するスコープについては aggrega-mcp.md で説明しています。

mcp.announce_tools はサーバーが告知するものを絞り込みます。これは上記のキーとは異なる制限です。 このサーバーが告知するツールを、ツール一覧が報告するとおりの綴りで指定すると、まさにそれらが告知されます。指定から外れたツールはすべての呼び出し元のツール一覧から消え、それでも名前で呼び出された場合はこの設定を示して拒否されます。キーを省略する(デフォルト)と、サーバーが持つすべてのツールが告知されます。空のリストを書くと何も告知されません。したがってこの 2 つの書き方は異なる意味を持ち、デフォルトが補われることはありません。deny_reach との違いは、それぞれが何を取り除くかにあります。deny_reach は機能を取り除きます。取り除かれた種類の操作はここでは一切提供されず、どの資格情報でも元に戻せません。announce_tools が取り除くのは告知だけです。外されたツールはサーバーが依然として持つ機能であり、これが応えるのは、登録するツールの数に上限を設けるクライアントです。この上限は、接続しているすべてのサーバーにまたがる場合もあります。両方が設定されている場合は取り除きが優先されるため、取り除かれた種類のツールは、このキーでどう指定しても消えたままです。どのツールにも該当しない名前があると、要求よりも狭い提供範囲のまま進めるのではなく、サーバーは何も提供する前に停止し、実際に持つツールを一覧表示します。http トランスポートが起動するリスナーを設定するここでの他のキーとは異なり、このキーはサーバーがどのトランスポートで通信していても読み取られます。絞り込みの対象となるクライアントは通常、自身の標準入出力を介してプロセスを起動したクライアントだからです。詳細は aggrega-mcp.md で説明しています。

mcp.health.listen は、liveness チェックと readiness チェックを専用のアドレスに置きます。 mcp.listen の 2 つの形式のいずれかでアドレスを指定すると、2 つ目のリスナーがそこで GET /healthz に応答し(プロセスが起動した時点から 200)、GET /readyz に応答します(ワークスペースが解決されエンドポイントがバインドされるまでは 503、それ以降は 200)。これにより、プロセスが実際に呼び出しに応答できるようになるまで、バランサーがトラフィックを保留できます。省略すると、どちらのチェックもどこにも応答されません。これらのチェックは mcp.listen が指定するアドレスでは決して応答されず、そこでは提供していないすべてのパスと同じく 404 が返されます。そこでのプローブは、他のすべてを拒否するリスナーを認証なしで読み取ることになるためです。mcp.listen と異なり、このアドレスは制限されず、拒否されるアドレスもありません。このプロセスの隣にあるスーパーバイザーが到達するループバックまたは Unix ソケットを指定してください。また、選んだアドレスに到達できるものは何でも、この 2 つの応答を読み取れることに注意してください。

schema/other/aggrega-config.md に、これらの各キーとそのデフォルト(ある場合)が記載されています。

プロジェクトルートが認識されるその他の方法

--workspace-root <path>、またはそれに対応する AGGREGA_WORKSPACE_ROOT は、ルートを直接指定し、探索を省略します。指定するフォルダーは存在していなければなりません。何も指さないパスやファイルを指すパスは、コマンドが他の処理を行う前に拒否され、その拒否メッセージには 2 つのうちどちらが値を与えたかが示され、与えられたとおりの値が引用されます。それ以外の場合、探索は作業ディレクトリから上方向にたどり、アンカーの種類は近さではなく互いの間の優先順位で順位付けされます。

  • workspace: ブロックを持つ .aggrega-config.yaml は、どの深さにあっても無条件に優先されます。 探索は下記の種類のマーカーを通過した後もそれを探して上り続けるため、上位で明示的にマークされたルートは、その下にある偶発的なマーカーに常に優先します。
  • それがない場合、以下のマーカーのうち最も近いものがルートを定めます。 同じディレクトリ内では次の順に優先されます。.aggrega/ ディレクトリ、次に aggregate*.yaml、次に release*.yaml、次に manifest*.yaml です。
  • どれにも当てはまらない場合は、作業ディレクトリが使われます — コマンドは起動を拒否せずに実行されます。結果がワークスペースに依存するコマンド — ワークスペースのドキュメントを読み書きする、アーティファクトキャッシュを読み取るか埋める、またはワークスペースを提供するコマンド — は、標準エラーに 1 回警告を出します: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/ ディレクトリ自体が上記のマーカーの 1 つであるため、そこにキャッシュを書き込むと、かつて何かがそこで取得されたというだけでフォルダーがワークスペースになってしまいます。キャッシュを埋める処理を行うコマンド(aggrega pull、依存関係を先に解決するビルド、aggrega registry update、レジストリからのコマンド拡張プラグインの追加)は、何かを取得する前に拒否され、そのフォルダーと 2 つの解決方法が示されます。--workspace-root または AGGREGA_WORKSPACE_ROOT でワークスペースを指定するか、フォルダーに workspace: ブロックを持つ .aggrega-config.yaml を置くかです。aggrega pin、および Recipe または FeatureRecipe の aggrega push(隣の entity.lock が記録するピンに従います)は、エンティティが完全に書き出すリモートソース、つまりピン留めやピンの比較で取得されるものだけでキャッシュを埋めます。これらは、そのようなソースを取得することになる場合、取得する前に同じように拒否されます。そのようなソースを持たないエンティティ(ソースがまったくないもの、ローカルのもの、各 Release が座標を埋めるもの)は、他の場所と同様にそこでピン留めまたは公開されます。そこでのビルドは拒否されませんが、ロックファイルがピン留めしていてキャッシュにもう存在しない外部入力は、修復のために再取得されません。レンダリングには、オフライン姿勢の場合と同様に、その入力の代わりに同じ文が渡され、それが報告されます。artifact_cache_dir がキャッシュをどこに置くかはここでは関係ありません。そのディレクトリは見つかったルートに結合されるためです。読み取りのみを行うコマンドは引き続き応答します。

この最後のフォールバックには 1 つの例外があります。ルートが何によっても指定されず、作業ディレクトリが何もアンカーしない場合、1 つの Release または 1 つのエンティティドキュメントを対象とし、そのファイルを絶対パスで指定するコマンドは、ファイルがあるフォルダーから上方向にたどってルートを再度探索し、見つかったものを使います。つまり、そのファイルが属するワークスペース、またはいずれもない場合はそのフォルダーです。対象となるファイルは、aggrega build と aggrega pull では --release が指定するファイル、aggrega validate、aggrega lint、aggrega inspect では与えられた Release、またはそれ以外の場合は与えられたファイル、aggrega pin、aggrega push、aggrega edit-document では与えられたドキュメントです。そのため、プロジェクトの外からビルドされたプロジェクトの Release は、コマンドがプロジェクト内で実行されたときと同様にプロジェクト自身の設定を読み取り、コマンドが出力する設定の警告もそのワークスペースのものになります。ファイル自身のフォルダーも何もアンカーしない場合、そのフォルダーがコマンドの通知に示されるフォルダーとなり、キャッシュが書き込まれないフォルダーとなります。相対パスはコマンドを実行したディレクトリを基準に読み取られ、何も変わりません。また、指定されたルート、またはそれ自体がワークスペース内にある作業ディレクトリは、そのまま使われます。アシスタントサーバーは、Release またはドキュメントを絶対パスで指定する呼び出しに同じ規則を適用します。

workspace: ブロックでルートをマークするのが明示的な選択であり、推奨される方法です。ファイルやディレクトリのマーカーは、それを宣言していないプロジェクトでもビルドできるようにするためのものです。

グローバルファイルを明示的に指定する

グローバルレイヤーは次の順序で解決されます。

  1. --config <path>(呼び出しごとの形式)。
  2. AGGREGA_CONFIG 環境変数。
  3. デフォルトの場所: Windows では APPDATA 環境変数が指すディレクトリ内の aggrega\config.yaml、それ以外では XDG_CONFIG_HOME が指すディレクトリ内の aggrega/config.yaml で、なければ ~/.config/aggrega/config.yaml にフォールバックします。

最初の 2 つは明示的なファイルを指定するため、存在しないパスは暗黙のフォールバックではなく明示的なエラーになります。特定のファイルを求めたからです。設定を読み取るコマンドは、パスで終わる 1 文を出力して停止するため、そのパスをコピーできます。aggrega config init は例外です。そのファイルを作成することがこのコマンドの目的であるため、指定されたファイルを作成し、その旨を出力します。デフォルトの場所は、ファイルがあれば読み込まれ、なければ何も出力せずにスキップされます。どのファイルが解決されても、プロジェクトのファイルは引き続きその上に重ねられます。

これらのいずれも解決されない場合(ファイルが指定されておらず、デフォルトの場所の読み取り元となる変数も設定されていない場合)、グローバルファイルに書き込むコマンドは停止し、設定すべきものを示します。 環境変数に、プラットフォームごとに各場所の読み取り元となる変数が記載されています。

この選択は、設定を書き込むコマンドの書き込み先も決めます。--config <path> を付けて実行したコマンドは、そのファイルから設定を読み取り、同じファイルに変更を適用するため、あるコマンドが書き込んだ内容を次のコマンドが読み戻すことになります。

コマンドがデフォルトで 2 つのファイルのどちらに書き込むかは、設定の性質によって決まります。レジストリなどのマシン全体のツール設定はグローバルファイルに書き込まれ、プロバイダーのバインディングやソケットのアタッチメントなどビルドに関わる設定は、プロジェクトにコミットされたファイルに書き込まれるため、プロジェクトとともに移動します。--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 ブロックが設定するサーバー。