變數與資料引用概覽¶

工作流程 (Workflow) 是一連串接力的步驟。很多時候，後面的步驟需要用到前面步驟產生的東西——例如把使用者問的問題，交給 AI 回答。這一章要教你的，就是怎麼把資料從一個步驟「接」到下一個步驟。

先用看診理解「步驟怎麼接力」¶

你應該有過看診的經驗，整個流程其實是一場接力：

掛號櫃台寫下你的基本資料和主訴。
護理師量了血壓、體溫，寫進你的病歷夾。
報到區的 AI 分診助理讀你填的主訴，建議先掛哪一科，也寫進病歷夾。
醫師翻開病歷夾，看到前面的主訴、血壓和分診建議，做出診斷、寫下處方。
藥師讀病歷夾上的處方，把藥配好給你。

關鍵在於：沒有人需要重講一次前面發生的事。大家靠的是同一份病歷夾——前一站把結果寫上去，後一站翻開讀。這份一路跟著你跑、人人都能讀寫的病歷夾，就是整場接力能成立的原因。

對照到平台：三個詞¶

工作流程運作的方式，跟看診幾乎一模一樣。把上面的畫面換成平台術語，三個地基概念就懂了：

看診裡的東西	平台術語	是什麼
一次看診的流程（掛號 → 量血壓 → 看診 → 領藥）	工作流程 (Workflow)	一連串接力的步驟
跟著你跑、人人讀寫的病歷夾	狀態 (State)	共用資料區：每一步把產出寫上去，後面的步驟讀得到
醫師說「把剛剛量的血壓調出來」	變數引用	從狀態裡把某一欄「叫出來」用——也就是這一章在教的事

你不用會寫程式

接下來你會看到 { } 這種東西（那叫 JSON，是給電腦看的格式）。你不用自己寫——你只要在畫面上勾選、填欄位，平台會幫你產生這些底層定義。本章出現的 JSON 片段，都是給你看懂平台幫你產生了什麼，不是要你手動打字輸入。

走一遍：後面的步驟怎麼「取用」前面寫的資料¶

把鏡頭拉近，看資料在步驟之間到底怎麼被取用。輪到醫師看診時，病歷夾上已經有前面各站寫好的欄位：

┌─ 病歷夾（狀態）──────────────────────────┐
│                                            │
│  主訴 = 頭痛、發燒                         │  ← 掛號寫的
│  血壓 = 120/80                            │  ← 護理師寫的
│  體溫 = 38.5°C                            │  ← 護理師寫的
│                                            │
└──────────────────────────────────────────┘

醫師看診需要用到前面的資料，但他不會重新問你一次血壓——而是翻開病歷夾，指名把「血壓」這一欄調出來看。這個「指名某一欄、把它的內容叫出來用」的動作，就是變數引用。

診斷完，醫師把結果寫回病歷夾，於是多了兩欄：

┌─ 病歷夾（狀態）──────────────────────────┐
│                                            │
│  主訴 = 頭痛、發燒                         │
│  血壓 = 120/80                            │
│  體溫 = 38.5°C                            │
│  診斷 = 流感                              │  ← 醫師寫的
│  處方 = 退燒藥                            │  ← 醫師寫的
│                                            │
└──────────────────────────────────────────┘

最後一站藥師，同樣翻病歷夾、指名把「處方」這一欄調出來配藥。整場接力，每一步都是同一個節奏：從病歷夾指名調出需要的欄位（讀）→ 做事 → 把產出寫回病歷夾。

平台上的工作流程一模一樣：某一步要用到前面步驟的產出，就從狀態裡把那一欄「叫出來」。這一章接下來教的，就是怎麼把那一欄指出來。

幾種情況、幾種寫法¶

依你想做的事，選一種語法。先認得它「長什麼樣」就好，怎麼用各有專頁：

你想做什麼	用哪一種	你會看到的長相	畫面上在哪	看哪頁
把前一步的資料，接到這一步	JSONPath	`$.`	欄位標籤右側一個要把滑鼠移上去才浮現的「JSONPath」開關；打開後欄位變成路徑框	JSONPath 語法
套一段罐頭文字（中間帶變數）	Template	`{{ }}`	直接打在文字任務的「樣板」欄位裡，沒有開關	Template 語法
資料太大（例如整份長文件，超過狀態約 256 KB 的上限）	外部記憶體（置物櫃）	`.%`	畫面上沒有入口，要在編輯器的「程式碼」檢視手寫定義	外部記憶體
想把一份設定值集中放一處、多條流程共用	「變數」資源（也用 `.%`）	`.%`	同上，畫面上沒有入口	變數 (Variable)

第一次讀，照順序就好

側邊欄這一章由上到下共七頁，建議這樣讀：

概覽（本頁）— 先建立「狀態＝病歷夾」的概念。
JSONPath 語法 — 最常用，九成情況靠它，一定要看。
Template 語法 — 要套帶變數的罐頭文字時看。
變數 (Variable) — 想把設定值集中放一處、多條流程共用時看。
外部記憶體 — 資料太大塞不進狀態時看。
進階：Path Parameters — 除錯「為什麼下一步抓到空的」時回來看。
進階：外部記憶體語法 — .% 的完整格式，需要手寫定義時才看。

帶「進階：」前綴的最後兩頁第一次可以直接跳過。本頁最下方的「速查表」是給已經學會、回來查語法的人用的。

側邊欄有兩個都叫「變數」的項目，差別是什麼？

這一章的 「變數 (Variable)」 講的是「怎麼在工作流程裡引用變數資源的內容」（.% 語法）。
「資源」章的 「變數」 講的是「怎麼在平台上建立與管理一筆變數資源」（表單操作與截圖，見變數）。

先看資源章建立一筆變數，再回這一章學怎麼引用它。

速查表¶

這一段是給「看得懂 JSON、想快速對照語法」的人回頭查用的，第一次讀請直接略過。下面出現的 field.$、.%、{{ }} 都是平台在底層產生的長相——正常在畫面上操作時不必自己打；只有在看編輯器「程式碼」檢視的定義、或要手寫定義時才會直接碰到它們。

何時使用	語法	範例
存取工作流程資料	`$.` 搭配 `.$` 後綴	`"field.$": "$.input_value"`
載入資源／大型資料	`.%`（只有這一個沒有畫面入口，必須在「程式碼」檢視手寫）	`"field.%": {"type": "variable", "id": "var-id", "jsonpath": "$"}`
渲染文字／Prompt	`{{ }}`	`Hello {{ name }}!`

常見模式¶

引用工作流程的輸入欄位：

{ "query.$": "$.user_question" }

引用前一個任務的輸出（路徑開頭是那個任務的 ResultPath）：

{ "documents.$": "$.RetrievalActionResult.docs" }

載入一筆「變數」資源的內容：

{ "api_config.%": { "type": "variable", "id": "var-api-settings", "jsonpath": "$" } }

在「文字」任務的「樣板」欄位裡套變數：

回答此問題：{{ question }}

要避免的常見錯誤¶

以下兩種只有在手寫定義（編輯器「程式碼」檢視）時才會發生；在畫面上用「JSONPath 開關」操作的話，平台會幫你寫對。

❌ 欄位名稱遺漏 .$ 後綴

{ "query": "$.user_question" }

✅ 正確：{ "query.$": "$.user_question" }

❌ 把資料路徑直接串進字串裡（平台不支援字串拼接）

{ "url": "https://api.example.com/$.user_id" }

✅ 正確：先把完整網址組好再整個引用——{ "url.$": "$.full_api_url" }

了解更多¶

JSONPath 語法 - 把前一步的資料接過來（最常用）
Template 語法 - 套用帶變數的罐頭文字
變數 (Variable) - 在流程裡引用一筆「變數」資源的內容
外部記憶體 - 資料太大時放到「置物櫃」
進階：Path Parameters - 資料如何流經任務（除錯時看）
進階：外部記憶體語法 - .% 的完整參考格式