ビルドパイプライン

プロジェクトを ColdBox アプリケーションへと変換する、固定されたフェーズの並び。

ビルドパイプライン

bxAgents build は固定されたフェーズの並びを一度だけ実行し、ただの ColdBox アプリケーションを生成します。ここで行われることはリクエスト時には二度と実行されません - それがビルド時組み立ての意義そのものです。このページでは BuildPipeline.bx が各フェーズを実行する順序どおりに解説します。

flowchart TD
    A["1 · Resolve config<br/><small>AgentConfigResolver</small>"] --> B["2 · Discover<br/><small>ProjectDiscoverer</small>"]
    B --> C{"3 · Validate<br/><small>ProjectValidator</small>"}
    C -->|"any error"| X["Build throws.<br/>.build/app is never written or touched"]
    C -->|"clean<br/><small>warnings never block</small>"| D["4 · Generate"]
    D --> D1["1 Interceptors"] --> D2["2 Gateways"] --> D3["3 MCP"] --> D4["4 Router"]
    D4 --> D5["5 Web UI"] --> D6["6 Core app skeleton"] --> D7["7 Tools/skills copy"] --> D8["8 Scheduler"]
    D8 --> E["5 · Normalize + write<br/><small>ManifestNormalizer</small>"]
    E --> F[".build/manifest.json<br/>+ .build/app - a plain ColdBox application"]

    style C fill:#fff3cd,stroke:#856404
    style X fill:#f8d7da,stroke:#721c24
    style F fill:#d4edda,stroke:#155724

検証はゲートです。フェイルファストせずすべてのエラーを収集し、クリーンな結果が返るまでは何も生成されません。

(.bxa へのパッケージングは意図的に分離されたステップです - デプロイとシークレット 参照 - そのため、高速な build → 確認 → 再度 build というループが、不要なパッケージングのコストを一切払わずに済みます。)

1. config の解決

AgentConfigResolver が Agent.bx を読み込み、configure() とアクティブな環境のオーバーライドメソッドを呼び出したうえで、存在すれば boxlang.json/boxlang-{env}.json/miniserver.json/miniserver-{env}.json を深いマージで取り込みます。これにより、以降のすべてのフェーズが参照する、単一の解決済み config 構造体が生成されます。

2. 発見 (Discover)

ProjectDiscoverer がプロジェクトルートを走査し、すべてのコンベンションフォルダ (models/、tools/、skills/、subagents/、gateways/、mcp/、interceptors/、modules/) を生の { name, path, type } エントリとして列挙します。schedules/ だけは例外で、エントリの一覧ではなく単一の hasScheduler/schedulerPath のペアです。これは、BX Agents が定義する config エントリの集合ではなく、実際の ColdBox スケジューラファイルを 1 つ保持するだけだからです。この段階では純粋な発見のみで、ファイル内容の解釈はまだ行われません。

3. 検証 (Validate)

ProjectValidator はすべてのバリデータを実行し、(フェイルファストせずに) すべてのエラーと警告を収集します。重複したツール/スキル/モデル/サブエージェント名、サブエージェントツリー全体にわたるエージェント name の重複 (see subagents/)、循環したサブエージェント/モジュール参照、2 種類のゲートウェイエントリ形状、リモート MCP config の完全性、モデル/プロバイダーの妥当性などです。エラーが 1 つでも収集された場合、ビルドはここで即座に例外を投げます - .build/app は一切書き込まれず、触れられもしません。警告 (例えば Scheduler.bx を持たない schedules/ フォルダ) はビルドをブロックしません。

4. 生成 (Generate)

検証がクリーンな場合にのみ到達します。順序は以下の通りです。

1. インターセプター - InterceptorSplitter が agent スコープのインターセプターを .build/app/interceptors にコピーし、runtime スコープのものは別の .build/runtime-interceptors ディレクトリにコピーします。
2. ゲートウェイ - GatewayGenerator がチャネルアダプタエントリ向けに aiGatewayRegistry().register(...) 文を出力し、(いずれかが type: "http" であれば) .build/app/handlers/Gateway.bx を書き込みます。エントリのいずれかが push 型ゲートウェイ (例えば type: "telegram") であれば、.build/app/interceptors/GatewaySessionBootstrap.bx も書き込み、(すべての push 型ゲートウェイをまとめた) 単一の bx-ai GatewaySession をプロジェクトのルートエージェントに配線します。
3. MCP - McpGenerator がローカルの mcp/* サーバーを .build/app/mcp にコピーし、その mcpServer(...).registerTool(...) の登録文を出力します。
4. ルーター - RouterGenerator が .build/app/config/Router.bx を書き込みます。公開エントリごとに 1 つの route(path).toAi(...)/toMCP(...)、加えて http タイプのチャネルゲートウェイが存在する場合は 3 つの固定ゲートウェイ Webhook ルートも書き込みます。
5. Web UI - WebUiGenerator が exposes: "webui" エントリごとに実行され、静的な <path>/index.html、handlers/ChatUi.bx (20 個のアクションを持つ API)、models/ChatDb.bx (SQLite ストアとその前方向専用マイグレーション)、interceptors/WebUiSchema.bx (どのリクエストが最初にデータベースへ触れるかに関わらず、起動時にマイグレーションを行う)、そして apiKeyEnvVar が設定されている場合に限り interceptors/WebUiAuthGate.bx を書き込みます。これは解決済みのデータベース config を返し、次のステップがそれを必要とします。
6. コアアプリスケルトン - ColdBoxAppGenerator が Application.bx、config/ColdBox.bx、config/WireBox.bx、agent/GeneratedAgentFactory.bx、index.bxm を書き込み、これまでに集められたすべての文 (ゲートウェイ登録、MCP 登録、そして tools/ にファイルが 1 つでもあればシンプルな aiToolRegistry().scan("tools") 呼び出し) を Application.bx の onApplicationStart() に、そして (生成されていれば) フェーズ 1 の GatewaySessionBootstrap.bx を config/ColdBox.bx が参照する interceptors リストに、それぞれ差し込みます。生成されるすべてのエージェントは今や常にチェックポインターを受け取ります (withCheckpointer(...) - プロジェクトが checkpointer config を宣言しておらず、クラス自身も設定していない場合は cache バックエンドの aiMemory() がデフォルトになります)。これがないと、cli 以外のどのゲートウェイを通した human-in-the-loop 承認フローも完全に壊れてしまいます。config/WireBox.bx は、固定されたルートの "GeneratedAgent" エイリアスだけでなく、ツリー内のすべてのエージェント (ルート + すべてのサブエージェント) をそれぞれの宣言された name でマッピングします - see schedules/。webui 公開を持つプロジェクトでは、セッション管理も有効化し、SQLite データソースを登録し (this.datasource によりアプリのデフォルトとして命名)、onApplicationStart() でデータベースの親ディレクトリを作成し (SQLite はファイルは作成しますがそれを収めるフォルダは作成しません)、config/ColdBox.bx で qb のグラマーを固定します。
7. ツール/スキルのコピー - ToolsSkillsCopier が .build/app/tools と .build/app/skills を消去し、あなたのプロジェクト自身のフォルダからそのまま書き直します。
8. スケジューラ - SchedulerGenerator が、存在すれば schedules/Scheduler.bx をそのまま .build/app/config/Scheduler.bx にコピーします - 生成は行われません。あなた自身が書いた実際の ColdBox コードだからです。

5. マニフェストの正規化と書き込み

ManifestNormalizer が、発見データと解決済み config データから、正規で内容ハッシュ付きの内部マニフェストを生成し、パイプラインがそれを .build/manifest.json に書き込みます。

冪等性

変更のないプロジェクトを再ビルドすると、マニフェストのファイルごとの内容ハッシュに至るまで、バイト単位で同一の出力が生成されます - この組み立てコストをビルド時に一度だけ払い、その作業をリクエスト処理へ一切先送りしないという、この仕組み全体の意義そのものです。