ワークスペース (Workspace)

ワークスペースは、すべての作業のルートディレクトリです。相対ファイルパスが解決される際の起点（基準フォルダ）となります。

設定ファイル (Config files)

エンジン設定は、griptape_nodes_config.json という名前のファイルに保存されます。以下の 3 つの場所が意味を持ちます：

ファイル	用途
`~/.config/griptape_nodes/griptape_nodes_config.json`	ユーザー設定 — このマシン全体に適用されるグローバル設定
`<project_dir>/griptape_nodes_config.json`	プロジェクト隣接設定 — プロジェクトファイルと一緒に配布される共有デフォルト設定
`<workspace_dir>/griptape_nodes_config.json`	ワークスペース設定 — アクティブプロジェクトに対するユーザー固有の上書き設定

設定の解決順序 (Config resolution order)

設定は以下の順序で解決されます（下にあるものが優先されます）：

組み込みデフォルト (Built-in defaults)
ユーザー設定 (~/.config/griptape_nodes/griptape_nodes_config.json)
プロジェクト隣接設定 (<project_dir>/griptape_nodes_config.json)
ワークスペース設定 (<workspace_dir>/griptape_nodes_config.json)
環境変数 (GTN_CONFIG_*)

ワークスペースディレクトリがプロジェクトディレクトリと同じである場合（自己完結型プロジェクト）、レイヤー 3 と 4 は同じファイルを指すため、1 回のみ読み込まれます。

ワークスペースの解決 (Workspace resolution)

プロジェクトが読み込まれる際、そのワークスペースディレクトリは 優先度の高い順 に以下のソースによって決定されます — 最初に値を供給したソースが採用されます：

プロジェクト自身の workspace_dir フィールド（後述のプロジェクト宣言のワークスペースおよび workspace_dir フィールドリファレンスを参照）
ユーザー設定内の project_workspaces エントリ（後述のプロジェクト別ワークスペース上書きを参照）
環境変数 GTN_CONFIG_WORKSPACE_DIRECTORY
プロジェクト隣接設定の workspace_directory キー
明示的な親プロジェクトチェーンを辿った、最も近い先祖の解決済みワークスペース
ユーザー設定のグローバル workspace_directory、存在しない場合はプロジェクトファイルを含むディレクトリ（自動デフォルト）

プロジェクトファイルが関与しない場合、ワークスペースはグローバル workspace_directory（またはエンジンの作業ディレクトリ直下の組み込み GriptapeNodes/ デフォルト）から取得されます。

プロジェクト別ワークスペース上書き (Per-project workspace overrides)

ユーザー設定の project_workspaces 設定は、プロジェクトファイルのパスをワークスペースディレクトリの上書き先に対応付けます。共有プロジェクトをマシンごとに異なるローカルワークスペースへと解決させたい場合に使用します。

{
  "project_workspaces": {
    "//NAS/Projects/ProjectA/griptape-nodes-project.yml": "/Users/collin/ProjectA/",
    "//NAS/Projects/ProjectB/griptape-nodes-project.yml": "/Users/collin/ProjectB/"
  }
}

キーはプロジェクトファイルへの解決済み絶対パスです。プロジェクトが読み込まれる際、その解決済みパスがキーと一致すると、対応する値がワークスペースディレクトリとして使用されます。

プロジェクト宣言のワークスペース (Project-declared workspace - workspace_dir)

プロジェクトは、プロジェクトファイル内の workspace_dir フィールドを介して自身のワークスペースディレクトリを指定できます。これは 最も優先度の高い ワークスペースソースです：ユーザー別の project_workspaces マッピング、GTN_CONFIG_WORKSPACE_DIRECTORY 環境変数、プロジェクト隣接設定、親からの継承、およびグローバルデフォルトを上書きします。

各ユーザーのマシンレベルの設定に関係なく、プロジェクトを常に固定のワークスペースへと解決させたい場合に使用します。project_workspaces（各ユーザーが自身の設定で指定する必要がある）とは異なり、workspace_dir はプロジェクトファイル内部に含まれるため、プロジェクトは自身のワークスペースを持ち運ぶことができます。

v1 プロジェクトを作成すると、作成 UI はその中に workspace_dir: "./" を書き込むため、デフォルトで v1 プロジェクトは自己完結型（ワークスペースは自身のフォルダ）になります。このフィールドを消去する（または省略する）と、プロジェクトは親からワークスペースを継承するかグローバルデフォルトへと戻ります。スキーマバージョンを参照してください。

値は単一のパスまたはプラットフォーム別マッピングのいずれかを指定できます：

# 単一のパス: 絶対パス、またはこのプロジェクトファイルのディレクトリに対する相対パス。
workspace_dir: "./workspace"

# またはプラットフォーム別マッピング。アクティブなプラットフォームのキーが使用され、未設定なら default にフォールバック。
workspace_dir:
  darwin: "/Volumes/fast/ProjectA"
  windows: "D:/ProjectA"
  default: "./workspace"

相対パスはプロジェクトファイルを含むディレクトリを起点として解決されるため（parent_project_path が解決されるのと同様）、workspace_dir: "./workspace" を使用するプロジェクトは移植性を維持できます：プロジェクトフォルダを移動またはコピーしてもワークスペースが追従します。ターゲットディレクトリに griptape_nodes_config.json が含まれている必要はありません — 空のディレクトリでも有効です。

完全なスキーマ、プラットフォーム別のフォールバックルール、および親プロジェクトでの挙動については、workspace_dir フィールドリファレンスを参照してください。

設定シナリオの例 (Example scenarios)

シナリオ 1: ソロ開発者、プロジェクトファイルなし

プロジェクトファイル、プロジェクト隣接設定、ワークスペース設定のいずれも存在しない場合。ワークスペースはユーザー設定または組み込みデフォルトから取得されます。

~/.config/griptape_nodes/
  griptape_nodes_config.json    <- workspace_directory: ~/GriptapeNodes

~/GriptapeNodes/                <- ワークスペース
  griptape_nodes_config.json    <- 任意のワークスペースレベルの上書き設定

シナリオ 2: 自己完結型の移植可能プロジェクト

プロジェクトと設定が同じディレクトリに存在する場合。ワークスペースは自動的にプロジェクトディレクトリへとデフォルト設定されます。フォルダを USB メモリや別のマシンに移動しても、変更は不要です。

/My_Indie_Short/
  griptape-nodes-project.yml
  griptape_nodes_config.json    <- プロジェクト隣接かつワークスペース設定 (同一ファイル)
  inputs/
  outputs/

シナリオ 3: 共有プロジェクト、ユーザー別ワークスペース

プロジェクトファイルが共有ネットワークドライブ上に存在する場合。各ユーザーはユーザー設定の project_workspaces を介して、それを自身のローカルワークスペースに対応付けます。各ユーザーのワークスペースには、個別のオーバーライド用に独自の griptape_nodes_config.json を配置できます。

//NAS/Projects/ProjectA/
  griptape-nodes-project.yml
  griptape_nodes_config.json    <- 共有スタジオデフォルト (モデルの優先設定など)

Collin のユーザー設定:

{
  "project_workspaces": {
    "//NAS/Projects/ProjectA/griptape-nodes-project.yml": "/Users/collin/ProjectA/"
  }
}

James のユーザー設定:

{
  "project_workspaces": {
    "//NAS/Projects/ProjectA/griptape-nodes-project.yml": "C:\\Projects\\ProjectA\\"
  }
}

各ユーザーはローカルワークスペースディレクトリに griptape_nodes_config.json を配置し、共有プロジェクト隣接設定よりも優先される個人用の上書き設定を行うことができます。

シナリオ 4: スタジオ指定のワークスペース

プロジェクト隣接設定で共有ワークスペースを設定している場合。project_workspaces エントリを持たないクリエイターは全員スタジオのデフォルトを取得します。共有ドライブ上のワークスペース設定に追加の共有設定を保持できます。

//NAS/Projects/ProjectA/
  griptape-nodes-project.yml
  griptape_nodes_config.json    <- workspace_directory: //NAS/Workspaces/ProjectA/

//NAS/Workspaces/ProjectA/
  griptape_nodes_config.json    <- 共有ワークスペースレベル設定

レンダーファームのマシンは、共有ファイルを一切変更することなく、GTN_CONFIG_WORKSPACE_DIRECTORY を介してワークスペースを上書きできます。

シナリオ 5: 共有エンジン設定のユーザーによる上書き

スタジオがプロジェクト隣接設定で log_level: "WARNING" を配布している場合。開発者がローカルで DEBUG を使用したいときは、ワークスペース設定に上書きを記述します — ワークスペース設定（レイヤー 4）はプロジェクト隣接設定（レイヤー 3）よりも優先されます。

/Users/dev/ProjectA/
  griptape_nodes_config.json    <- {"log_level": "DEBUG"}

シナリオ 6: 複数プロジェクト、異なるワークスペース

project_workspaces は、各共有プロジェクトを別々のローカルワークスペースに対応付けます。アクティブなプロジェクトを切り替えると、ワークスペースが切り替わり、ワークスペース設定が再読み込みされます。

{
  "project_workspaces": {
    "//NAS/ProjectA/griptape-nodes-project.yml": "/Users/dev/ProjectA/",
    "//NAS/ProjectB/griptape-nodes-project.yml": "/Users/dev/ProjectB/"
  }
}

シナリオ 7: ワークスペースの自動検出

Griptape Nodes は起動時にワークスペースディレクトリ内の griptape-nodes-project.yml を検索します。見つかった場合、プロジェクトは自動的に読み込まれます。これはシナリオ 2 と同じです — ワークスペースとプロジェクトディレクトリが同一であるため、単一の griptape_nodes_config.json がプロジェクト隣接設定とワークスペース設定の両方の役割を果たします。

シナリオ 8: プロジェクトが自身のワークスペースを固定

常に固定のワークスペースに解決されるべきプロジェクトは、workspace_dir を使用してそれを直接宣言するため、ユーザーごとの project_workspaces エントリは不要です。相対値を指定することで、マシン間での移植性を維持できます。

# griptape-nodes-project.yml
name: "ProjectA"
workspace_dir: "./workspace"

/ProjectA/
  griptape-nodes-project.yml    <- workspace_dir: ./workspace
  workspace/                    <- 解決されたワークスペース (必要に応じて作成される)

workspace_dir は最も優先度の高いソースであるため、project_workspaces マッピングや環境変数よりも優先されます。ProjectA/ フォルダをどこに移動しても、ワークスペースは常にその workspace/ サブディレクトリへと解決されます。

パスの解決方法 (How paths resolve)

ワークフロー内の相対ファイルパスは、ワークスペースディレクトリ を起点として解決されます。ワークスペースが /Users/you/workspace/ であり、シチュエーションマクロが outputs/render_001.png に解決される場合、最終的な絶対パスは /Users/you/workspace/outputs/render_001.png となります。

プロジェクトファイル内に記述された相対パスは、プロジェクト YAML を保持するフォルダを起点として解決されます。上記の workspace_dir: ./workspace の例が自身のワークスペースを見つけられるのはこの仕組みによるものです。

ライブラリは例外です：ライブラリはデフォルトでワークスペース相対の libraries ディレクトリ配下にインストールおよび解決されますが、プロジェクトはワークスペースとは無関係に、libraries_dir フィールドを使用してそれらを別の場所に移動（およびプロジェクトツリー全体で共有）できます。

プロジェクトベースディレクトリ（griptape-nodes-project.yml を含むフォルダ）は {project_dir} 組み込み変数として公開されますが、相対パスの解決基準としては使用されません。パス管理システムが絶対パスをマクロ形式へと逆マッピングする際、そのパスがプロジェクトフォルダ内にあり、かつ名前付きディレクトリの外側にある場合のフォールバックとして使用されます。

ワークスペースとプロジェクトファイル

Griptape Nodes の起動時、ワークスペースディレクトリ内の griptape-nodes-project.yml を検索します。見つかった場合、そのファイルがシステムデフォルトの上にマージされ、アクティブなプロジェクトテンプレートが生成されます。見つからない場合は、システムデフォルトが使用されます。

プロジェクトファイルとマージモデルの詳細についてはプロジェクトを参照してください。

まとめ (Summary)

設定	説明
`workspace_dir`	プロジェクト宣言のワークスペース；最も優先度の高いソース
`workspace_directory`	作業のルートディレクトリ
`project_workspaces`	ユーザー設定内のプロジェクト別ワークスペース上書き
`griptape-nodes-project.yml`	任意のプロジェクトテンプレートファイル
`<project_dir>/griptape_nodes_config.json`	プロジェクトと一緒に配布される任意の共有設定
`<workspace_dir>/griptape_nodes_config.json`	ユーザー固有の任意のワークスペース設定
`GTN_CONFIG_WORKSPACE_DIRECTORY`	環境変数による上書き（最高優先度）