ディレクトリ (Directories)

ディレクトリは、論理名から実際のファイルシステムパスへのマッピングです。あらゆる場所に outputs/renders のようなパスをハードコードする代わりに、論理名（outputs）を割り当て、マクロ内でその名前を使用します。将来出力先を変更したくなった場合でも、1 か所のディレクトリ定義を更新するだけで済みます。

デフォルトディレクトリ

システムデフォルトでは、以下の 6 つのディレクトリが定義されています：

名前	デフォルトパス	説明
`inputs`	`inputs`	プロジェクトに取り込まれたファイル（アップロード、コピー、ダウンロード）。
`outputs`	`outputs`	ワークフロー実行中にノードによって生成されたファイル。
`temp`	`temp`	一時スクラッチファイル。実行の合間に安全に削除できます。
`griptape-nodes-previews`	`.griptape-nodes-previews`	生成されたプレビュー/サムネイルアセット。元のファイル階層を反映します。
`griptape-nodes-metadata`	`.griptape-nodes-metadata`	プロジェクトファイルのサイドカーメタデータ。元のファイル階層を反映します。
`griptape-nodes-thumbnails`	`.griptape-nodes-thumbnails`	UI 上に表示されるワークフローのサムネイル画像。

すべてのデフォルトパスは相対パスであり、プロジェクトのベースディレクトリを起点として解決されます。

マクロ内でのディレクトリ名の使用

ディレクトリ名は、任意のマクロ内で変数として利用できます。マクロが解決される際、プロジェクトシステムはディレクトリ名をその設定されたパスへと自動置換します：

テンプレート: {outputs}/{file_name_base}.{file_extension}
             ↓
解決後:     outputs/my_image.png

ユーザー自身がディレクトリ変数の値を指定する必要はありません — ディレクトリ定義から値が自動供給されます。ディレクトリ名は予約名 (reserved) です：ディレクトリと同名の変数を渡そうとすると、曖昧さを防ぐためにシステムがエラーを返します。

ディレクトリパスのカスタマイズ

griptape-nodes-project.yml 内でディレクトリのパスを上書きします：

project_template_schema_version: "0.1.0"
name: "My Project"

directories:
  outputs:
    path_macro: "renders/final"

これで、任意のマクロ内の {outputs} が、outputs ではなく renders/final に解決されるようになります。

ディレクトリの説明文 (description)

各ディレクトリ定義には、オプションで description（そのディレクトリの用途や利用方法を説明する人間可読テキスト）を記述できます。説明文は GUI のプロジェクト管理画面などのプロジェクトディレクトリを表示するツール上で表示され、手動編集されたプロジェクト YAML を理解しやすくします。

directories:
  outputs:
    path_macro: "renders/final"
    description: "クライアントへの納品準備が整った最終レンダリング成果物。"

description は任意であり、デフォルトは null です。ベースまたは親テンプレートから継承した説明文を消去したい場合は、オーバーレイで null を指定します：

directories:
  outputs:
    description: null

新しいディレクトリの追加

デフォルトには存在しない新しいディレクトリを追加できます：

directories:
  deliverables:
    path_macro: "client_deliverables"

追加すると、任意のマクロ内で {deliverables} が使用可能になります。

マクロを含むディレクトリパス

path_macro フィールドは、チルダ（~）展開、マクロ構文、および環境変数の参照をサポートしています：

directories:
  downloads:
    path_macro: "~/Downloads"

これにより、実行されるマシンに関係なく、downloads ディレクトリが現在のユーザーの Downloads フォルダに対応付けられます。

directories:
  outputs:
    path_macro: "$OUTPUT_BASE/renders"

環境（またはプロジェクトの environment セクション）に $OUTPUT_BASE が設定されている場合、パス解決時に置換されます。

ディレクトリパス内で組み込み変数を参照することも可能です：

directories:
  outputs:
    path_macro: "{workflow_dir}/renders"

これにより、outputs ディレクトリがプロジェクトベースディレクトリではなく、現在のワークフローの場所に対する相対パスになります。

プラットフォーム別のパス指定 (Per-platform paths)

OS ごとに適切なパスが異なる場合、ディレクトリの path_macro は単一の文字列（全環境共通）だけでなく、プラットフォームごとのマッピングとして記述できます。Linux、macOS、Windows を使用するコラボレーター間でワークスペースを共有しており、OS ごとに異なる絶対パスを指定する必要がある場合に便利です。

directories:
  scratch:
    path_macro:
      linux: "/mnt/fast-scratch"
      darwin: "/Volumes/scratch"
      windows: "D:/scratch"
      default: "{workspace_dir}/scratch"

解決時、エンジンは現在のプラットフォーム（linux、darwin、または windows）に一致するエントリを選択します。該当するプラットフォームのキーが未設定の場合、default にフォールバックします。プロジェクトのバリデーションを通過するには、4 つのキーのうち少なくとも 1 つが指定されている必要があります。

directories:
  models:
    path_macro:
      darwin: "~/Library/Caches/models"
      default: "{workspace_dir}/.models"

プラットフォーム別の値でも文字列形式と同じ構文がサポートされており、チルダ展開、環境変数、マクロが同様に動作します。

オーバーレイのマージにおいて、このマッピングはアトミック（不可分）に扱われます：子テンプレートがプラットフォーム別マッピングを提供した場合、キーごとにマージされるのではなく、親の path_macro 全体が完全に置き換わります。特定のプラットフォームの値を維持しつつ別のプラットフォームを上書きしたい場合は、保持したいすべてのキーを再記述してください。

予約名 (Reserved names)

ディレクトリ名は変数名前空間全体で予約されています。マクロ呼び出し時にユーザー指定の変数としてディレクトリ名を使用することはできません（試みるとシステムがエラーを返します）。これにより、変数名の衝突によってディレクトリパスが誤って上書きされるのを防ぎます。

組み込み変数（project_dir、workspace_dir、workflow_name、workflow_dir、static_files_dir）も予約されており、上書きできません。環境と組み込み変数を参照してください。