ワークフロー変数 (Workflow Variables)
変数 (Variable) は、特定の 1 つのノードではなくフロー全体に属する名前付きの値です。一度定義すれば、テキストフィールド内で {variable_name} を使用したインライン参照を含め、その値が必要な場所のどこからでも読み書きできます。
マクロパス変数との違い
マクロ は、プロジェクトシステムがファイルパス（{outputs}/{file_name_base}.{file_extension} など）を構築するために使用するテンプレート構文です。一方、ワークフロー変数は、ユーザーが作成しワークフロー内のノードパラメータ間で再利用する値です。両システムは内部で同じ {name} / {name:spec} 構文やフォーマット仕様を共有しており、テキストフィールドで { を入力した際には、プロジェクトマクロ（workspace_dir や workflow_name など）も自作の変数と並んで表示されます。しかし、マクロパステンプレートがファイル名の構築方法を記述するのに対し、ワークフロー変数は実行中に定義・変更される値です。ファイルの保存パスを構築したい場合は、マクロ を参照してください。
変数を使用する場面
ワークフロー内の 3 つのプロンプトフィールドすべてで、同一のクライアント名を使用する必要があるとします。1 つのデータ供給元ノードから必要なすべてのフィールドへ線を配線することも可能ですが、キャンバスが配線で散らかってしまい、配線を引っ張る代わりにフィールドへ値を直接入力したい場合に対応できません。
変数を使用すれば、接続線を一切引かずにこの問題を解決できます：一度変数を設定すれば、任意の数のテキストパラメータ内で {project_name} として参照できます。変数の値を変更すると、それを参照しているすべてのフィールドが次回の実行時に新しい値を自動的に取得します。
変数の作成
ノードライブラリの Variables カテゴリには、変数の作成と管理を行うためのノード群が用意されています：
- Create Variable — 名前、型、および初期値を指定して変数を作成します。現在のフロー内に同名の変数がすでに存在する場合は更新します。任意の出力をその
value入力に接続すると、接続された型に基づいて変数の型が自動推論されます。 - Set Variable — 変数の値を設定します。変数がまだ存在しない場合は新しく作成します。
variable_nameフィールドはスコープ内にある既存変数のドロップダウンになっており、Create new variable を選択すると名前入力欄が表示されます。 - Set Variables from Data — 辞書 (dict)、JSON/YAML 文字列、またはキーと値のペアのリストから、複数の変数を一度に一括生成します。すでに設定データや API レスポンスなどの JSON ブロブが存在し、キーごとに 1 つずつ Set Variable ノードを配線する手間を省きたい場合に便利です。
- Get Variable — 変数の現在値を通常のノード出力として読み出します。インラインの
{name}置換をサポートしていないノードへの配線に使用します。 - Has Variable — 変数が存在するかどうかをブール値で確認し、条件分岐に利用します（例: フローの初回実行時のみ変数を作成するなど）。
Create Variable および Set Variable は、常にそのノードが属するフロー内に変数を作成します（後述のフロースコープ）。現時点では、グローバル変数を直接作成するノードはありません。これらのノードの Advanced にある scope 設定は、既存の変数をどこから検索するかを制御するものであり、新しい変数が作成される場所を制御するものではありません。
これらのノードは、操作する変数を「一度解決したら終わり」の値ではなく、ライブ状態として扱います。Create Variable はワークフローまたはノードが実行されるたびに自身を強制的に未解決状態に戻すため、常に現在の value を再適用します。Get Variable、Set Variable、および Has Variable は、解決状態が要求されるたびに実際の現在の変数値を確認し、前回の読み書き時の値と一致しなくなった場合は自身を未解決としてマークします。そのため、手動で再実行しなくても、他の場所（別の Set Variable ノードや別のフロー）で行われた変更を即座に検知できます。
スコープ (Scopes)
変数のすべてのリクエスト（作成、取得、設定、一覧）は scope（スコープ）を受け取り、検索対象の範囲を制御します：
| スコープ | 動作 |
|---|---|
hierarchical（デフォルト） |
現在のフローを検索し、次にルートフローに至るまでの各親フローを順に検索し、最後にグローバル変数を検索します。最初に一致したものが適用されます。 |
current_flow_only |
ノードが配置されているフローのみを検索します。親フローやグローバル変数は完全に無視されます。 |
global_only |
グローバル変数（どのフローにも所有されていない変数）のみを検索します。 |
all |
すべてのフローのすべての変数を対象とします。単一の値の解決ではなく、主にピッカーやリストへの一覧表示（列挙）用です。 |
ほとんどのケースでは hierarchical が最適です：最上位のフローで project_name を一度定義すれば、その内部にネストされたすべてのサブフローから再宣言なしで {project_name} を参照できます。ネストされたフローが独自の project_name を定義した場合、そのネストされた定義が内部のすべてに対して親の定義をシャドウ（隠蔽）します。親の値は変更されず、ネストされたフローを抜けると再び親の値が有効になります。
簡単に言えば、読み取り箇所に最も近い定義が優先され、フロースコープの変数がグローバル変数よりも優先されます。
変数の型 (Variable types)
変数の type は、通常のノードパラメータと同じ型ラベル（str、int、float、bool、json、画像型など）を持ちます。Create Variable および Set Variable は、value 入力に接続されたデータから型を自動推論します。value を未接続のままノードにリテラル値を直接入力する場合を除き、手動で型を指定する必要はありません。
テキストフィールドの {name} トークンにインライン置換できるのは、str または int の値を保持する変数のみです（bool は不可。後述の テキストフィールドでのインライン置換 を参照）。他の型（JSON、画像、リストなど）を保持する変数も Get Variable / Set Variable を通じて正常に機能しますが、画像をテキストとしてインライン展開する適切な方法がないため、テキストフィールドにそのまま埋め込むことはできません。
実行中の値の設定と読み取り
ノードを使わずにエンジンのリクエスト API を直接スクリプトから呼び出す場合、関連するリクエストは CreateVariableRequest、GetVariableValueRequest、および SetVariableValueRequest です（それぞれ name と lookup_scope を受け取ります）。SetVariableValueRequest は、その変数を参照している下流の解決済みノードをすべて未解決状態に戻すため、編集途中で変数を変更した場合でも、古い値から計算された結果が正しく無効化されます。
インライン置換の場合、通常の変数検索の上にさらに 1 つのレイヤーが追加されます：ノードが実行される際、エンジンはパラメータ値内のすべての {name} トークンを、ワークフロー変数とプロジェクトの読み取り専用マクロ値（workspace_dir、workflow_name、および任意のプロジェクトテンプレートディレクトリ）をマージしたセットと照合して解決します。名前が衝突した場合は、自作のワークフロー変数が優先されます。このマージ機構により、片方がプロジェクトから提供され、もう片方が自作の変数である場合でも、テキストフィールド内で {workflow_name} と {project_name} を並べて記述できます。
テキストフィールドでのインライン置換
対応している任意のテキストパラメータ内で { を入力すると、現在スコープ内にあるすべての変数とプロジェクトマクロが提供元ごとにグループ分けされた変数ピッカーが表示されます：
リストから選択するか、自身で名前を入力して波括弧を閉じます（例: {project_name}）。実行時にその値がインライン置換されます。名前がスコープ内の何にも一致しない場合、誤入力によって誤った値がサイレントに生成されるのを防ぐため、トークンはそのままテキスト内に残されます（後述するオプショナルトークンの場合は自動的に削除されます）。
波括弧を含むテキストをトークンとして解釈せず、そのままプレーンテキストとして通過させたい場合は、Set Variable Substitution ノードを使用してワークフローごとにこのインライン置換の挙動を無効化できます。
フォーマット指定子 (Format specs)
トークンには、コロン : の後ろにフォーマット指定子を記述でき、左から右へと順次適用されます。これは マクロ → 文字列の変換 で完全に文書化されている仕様と同一の構文です：
| 指定子 | 結果 |
|---|---|
:lower |
すべて小文字 (lowercase) |
:upper |
すべて大文字 (UPPERCASE) |
:title |
単語の先頭を大文字 (Title Case) |
:snake |
スネークケース (snake_case) |
:pascal |
パスカルケース (PascalCase) |
:camel |
キャメルケース (camelCase) |
:screaming_snake |
大文字スネークケース (SCREAMING_SNAKE_CASE) |
:slug |
URL セーフなスラッグ (url-safe-slug) |
:dot |
ドットケース (dot.case) |
:abbrev |
各単語の先頭文字 (Abbreviation) |
:trim |
前後の空白文字を除去 (Trim) |
{project_name} → "Autumn Campaign"
{project_name:lower} → "autumn campaign"
{project_name:slug} → "autumn-campaign"
{project_name:snake:upper} → "AUTUMN_CAMPAIGN"
マクロから引き継がれ、ここでも同様に機能する 2 つの構文：
- オプショナルマーカー
?—{project_name?}は、変数が見つからない場合にトークン文字列をそのまま残すのではなく、空文字列として展開します。変数が未設定の場合に文の一部を安全に省略したい場合に便利です。 - デフォルト値
|default—{project_name|untitled}は、project_nameがスコープ内に存在しない場合にuntitledを代入します。
数値のゼロ埋め（:03）、シーケンススロット（{###}）、および先頭セパレータ（:^prefix）も同じエンジンで解析され、テキストフィールド内でも技術的には有効ですが、これらは主に連番カウンター付きのファイル名を構築するためのものです。それらの挙動が必要な場合は マクロ を参照してください。通常のテキスト置換においては、上記の文字列変換およびオプショナル/デフォルト構文で一般的なケースをすべてカバーできます。
具体例: 複数のプロンプトでプロジェクト名を共有する
コンセプトアートを生成するワークフローにおいて、複数のプロンプト入力フィールドで同じプロジェクト名を使用したいとします。
- フローの最上位付近に Create Variable ノードを配置します。
variable_nameをproject_nameに設定し、valueに直接Autumn Campaignと入力します（リテラル値の場合は配線不要です）。variable_typeは自動推論されるstrのままにします。 -
プロンプト生成ノードのテキストフィールドに以下のように記述します：
A cinematic key art poster for {project_name}, dramatic lighting, wide shot -
フロー内の別のプロンプトフィールドに以下のように記述します：
Concept sketch, {project_name:slug} style guide, muted palette -
フローを一度実行します。両方のプロンプトが「Autumn Campaign」（または入力した文字列）を取得し、2 つ目のプロンプトでは slug 指定子が適用されて
autumn-campaignとして展開されます。
新しい実行でプロジェクトを変更したい場合は、Create Variable ノード上の値を編集する（または別のデータ供給元を接続する）だけです。配線をやり直すことなく、{project_name} を参照しているすべてのフィールドが次回のフロー実行時に一括更新されます。