專案變數 (Project Variables)

專案設定檔中的 variables 區塊宣告歸屬於該專案的具名數值。它們加入與工作流程變數相同的 {VAR} 替換系統，可在節點參數值與巨集中隨處引用：

variables:
  shot_code:
    value: sc042
  frame_start:
    value: 1001
    type: int
  facility:
    value: mtl
    permission: read_only

欄位規範

欄位名稱	必填	預設值	說明
value	是	—	變數的實際數值。必須為字串或整數，且必須與所宣告的 type 型別精確相符。
type	否	str	可選 str 或 int。數值必須與型別相符 — 宣告 type: int 卻填寫帶引號的字串將觸發載入錯誤。
permission	否	read_write	read_write（讀寫）變數可在執行期動態修改（變更會自動寫回專案檔案保存）。read_only（唯讀）變數僅能透過手動編輯專案設定檔進行修改。write_only（僅寫）目前已被系統接納但尚未具備完整的讀取隱藏 — 詳見下文警示。

布林值 (Boolean) 與浮點數 (Float) 不支援作為專案變數。僅有字串與整數數值能夠參與 {VAR} 標籤替換。

write_only 尚未實現讀取限制

write_only 變數與 read_write 一樣接受執行期寫入，但引擎目前尚未在讀取介面中隱藏其明文 — 現階段在任何展示或替換數值之處，其行為皆與 read_write 完全相同。目前切勿使用它儲存敏感機密金鑰！ 讀取存取限制已規劃於未來的密鑰系統更新中；該功能正式上線後，write_only 數值才不會出現在讀取請求、選擇器與 {VAR} 替換中。

專案變數如何解析

變數採分層查找機制，發生命名衝突時距離調用端最近的層級勝出：

1. 工作流程（流程）變數 (Workflow flow variables) — 在工作流程編輯器中建立的變數
2. 專案變數 (Project variables) — 本區塊定義的變數，加上專案的內建變數與目錄
3. 全域變數 (Global variables)

在專案層級內部，系統內建變數與目錄名稱一律勝過同名的 variables: 條目。宣告名為 workspace_dir 或與目錄重名的變數會產生載入警告，且該變數永遠無法被成功解析 — 請務必挑選不同的名稱。

內建變數與目錄名稱屬於受保護的保留字：引擎拒絕將任何工作流程變數或全域變數建立或重新命名為這些保留名稱。

執行期動態寫入與持久化保存

read_write 權限的專案變數可在引擎運行期間動態修改 — 無論是透過變數面板操作，還是由負責設定變數的節點寫入。每次成功的修改皆會即時寫回實體專案設定檔中，重啟引擎後依然長久生效。

寫入操作會受到型別嚴格檢驗：嘗試向 int 變數賦予字串值會被系統明確報錯拒絕，絕不進行靜默型別強制轉換。

read_only 變數拒絕所有執行期寫入請求。若需修改，請手動編輯專案設定檔並重新載入專案。

巨集中的專案變數引用

專案變數完整參與路徑巨集的動態解析（例如在目錄的 path_macro 或情境規則的巨集中），其優先層級低於調用端傳入的變數，高於專案的 environment: 區塊：

1. 系統內建變數
2. 目錄名稱
3. 調用端傳入變數
4. 專案變數（本章節規範）
5. 專案自訂環境變數
6. Shell 環境變數

完整優先順序解析請參閱環境與內建變數 → 變數優先順序。

繼承模型 (Inheritance)

當專案宣告了父專案 (parent_project_path / parent_project_id) 時，變數按單一條目進行覆疊合併：

• 子專案中同名的條目會完全取代父專案的對應定義。
• 子專案中設為 null 的條目代表刪除 (Tombstone) 該繼承變數：

# 子專案 project.yml
variables:
  shot_code:
    value: sc099      # 覆寫父專案的 shot_code
  facility: null       # 徹底移除繼承而來的 facility 變數

• 子專案未提及的父專案變數則完整繼承保留。

在執行期刪除繼承而來的變數時，系統會自動在子專案設定檔中寫入 null 標記，確保該刪除在重新載入後依然維持生效。

variables 與 environment 的抉擇指南

兩者皆為專案作用域下的鍵值配置區塊，但服務於截然不同的受眾：

• variables 條目是引擎的一等公民變數：它們呈現在變數管理面板與下拉選取器中，具備明確型別與存取權限，支援執行期動態修改，並參與節點參數內部的 {VAR} 行內替換。
• environment 條目專為巨集動態組裝（路徑、代碼）與作業系統環境變數導出而設計。它們一律為字串型別，不支援執行期寫入，亦不會作為變數出現在編輯器 UI 中。

經驗法則：凡是創作者需要看見或動態修改的，定義為 variables；凡是純粹作為路徑巨集組裝管道的，放置於 environment。