Template 語法¶

Template 語法（{{ }}）就像 Word 的合併列印：你先寫好一段罐頭文字，中間挖幾個空格放變數名（用雙大括號框起來），平台執行時會把每個空格換成真正的值。例如「親愛的 {{ 病人姓名 }}，提醒您 {{ 看診日期 }} 的回診…」。

想讓 AI（大型語言模型）讀到動態內容？那不是這頁

這頁的 {{ }} 主要給 Text Action（文字） 用。如果你的目標是「把使用者的問題等動態內容帶進 AI 的提示詞」，目前平台的大型語言模型步驟走的是 JSONPath 語法（勾「JSONPath」核取方塊），不是 {{ }}。先確認你要的是哪一種，再往下讀，才不會用錯。

語法格式¶

親愛的 {{ patient_name }}，

您 {{ appointment_date }} 的看診結果為「{{ diagnosis }}」。

關鍵特性： 變數包含在雙大括號 {{ variable_name }} 中。

何處使用 Template 語法¶

Template 語法主要用於：

Text Action（文字） - 用於變數替換的 Template 渲染

在 Text Action（文字）的設定面板上，你會看到「樣板」欄位填 {{ }} 文字、底下「樣板變數」表格用 JSONPath（.$）把狀態裡的值接到每個變數名：

文字任務的「樣板」與「樣板變數」欄位

對於大多數其他 Action 欄位，使用帶有 .$ 後綴的 JSONPath 語法。

大型語言模型步驟目前的實際做法不是 {{ }}

在目前的平台介面上，大型語言模型步驟的內容區塊（提示詞）走的是「自訂提示詞（純文字）＋勾『JSONPath』核取方塊（產生 text.$）」這套，看不到 {{ }} 模板與「Template Variables」這組欄位的明顯入口。因此，本頁的 {{ }} Template 用法，請以 Text Action（文字） 為準來理解；想在大型語言模型的提示詞裡帶入動態值，請改用 JSONPath 語法（勾「JSONPath」核取方塊）。

基本使用¶

簡單變數替換¶

Template：

Welcome, {{ name }}!

Workflow 輸入：

{
  "name": "Alice"
}

輸出：

Welcome, Alice!

多個變數¶

Template：

Order #{{ order_id }} for {{ customer_name }} is {{ status }}.
Total: ${{ amount }}

Workflow 輸入：

{
  "order_id": "12345",
  "customer_name": "Bob",
  "status": "shipped",
  "amount": "99.99"
}

輸出：

Order #12345 for Bob is shipped.
Total: $99.99

實用範例¶

範例 1：使用 Text Action 的回診提醒 Email¶

Text Action 設定：

Template：

親愛的 {{ patient_name }}：

感謝您今日的看診，以下是本次的後續安排。

看診資訊：
- 分診建議科別：{{ department }}
- 醫師診斷：{{ diagnosis }}
- 回診日期：{{ followup_date }}

祝您早日康復，
OO 診所

Workflow 輸入：

{
  "patient_name": "王小明",
  "department": "家醫科",
  "diagnosis": "流感",
  "followup_date": "2026-06-23"
}

輸出：

{
  "text": "親愛的 王小明：\n\n感謝您今日的看診，以下是本次的後續安排。\n\n看診資訊：\n- 分診建議科別：家醫科\n- 醫師診斷：流感\n- 回診日期：2026-06-23\n\n祝您早日康復，\nOO 診所"
}

範例 2：動態 Prompt（概念示意）¶

此範例為概念示意，非大型語言模型步驟的實際操作

以下用 {{ role }}、{{ question }} 的寫法是為了示意「模板＋變數」的概念。但如前面所述，目前平台的大型語言模型步驟內容區塊並沒有 {{ }} ＋ Template Variables 的入口；要在提示詞裡帶入動態值，實際做法是勾「JSONPath」核取方塊（產生 text.$，見 JSONPath 語法）。若你要的是純文字模板渲染，請改用 Text Action（文字）。

示意設定：

System Message：

你是一位「{{ role }}」，專長是「{{ domain }}」。
請根據病人主訴，建議最合適的就診科別，語氣保持 {{ tone }}。

User Message：

{{ question }}

其他資訊：
{{ additional_context }}

Workflow 輸入：

{
  "role": "AI 分診助理",
  "domain": "一般內科與家醫科分診",
  "tone": "親切",
  "question": "我頭痛又發燒，該看哪一科？",
  "additional_context": "病人體溫 38.5°C、血壓 120/80。"
}

LLM 收到：

System：

你是一位「AI 分診助理」，專長是「一般內科與家醫科分診」。
請根據病人主訴，建議最合適的就診科別，語氣保持 親切。

User：

我頭痛又發燒，該看哪一科？

其他資訊：
病人體溫 38.5°C、血壓 120/80。

範例 3：結合前一個 Action 輸出¶

Workflow 設定：

LLM Action 生成摘要（輸出在 $.LLMActionResult.text）
Text Action 建立格式化報告

Text Action Template：

# Analysis Report

## Summary
{{ summary }}

## Recommendations
Based on the analysis, we recommend:
{{ recommendations }}

## Next Steps
{{ next_steps }}

---
Generated: {{ timestamp }}

Text Action 的 Template Variables 設定：

{
  "summary.$": "$.LLMActionResult.text",
  "recommendations.$": "$.workflow_input.recommendations",
  "next_steps.$": "$.workflow_input.next_steps",
  "timestamp.$": "$.workflow_input.timestamp"
}

注意： Template Variables 欄位使用 JSONPath 語法（.$）從 Workflow 狀態提取值，然後這些值使用 {{ }} 替換到 Template 中。

存取巢狀資料¶

在 Template Variables 中使用 JSONPath¶

要在 Template 中使用巢狀資料，首先使用 JSONPath 在 Template Variables 欄位中提取它。

Workflow 狀態：

{
  "user": {
    "profile": {
      "name": "Alice",
      "email": "alice@example.com"
    }
  }
}

Template Variables：

{
  "name.$": "$.user.profile.name",
  "email.$": "$.user.profile.email"
}

Template：

User: {{ name }}
Email: {{ email }}

進階 Jinja2 功能（進階／選讀）¶

這一節屬進階選讀

以下 {% if %}、{% for %}、| upper 等是 Jinja2 模板的程式化語法，對沒有程式背景的使用者門檻較高。新手不需要先學會這些——日常的變數替換用前面的 {{ 變數 }} 就夠了。真的需要條件或迴圈時，建議先做一個最小的例子在平台上實際跑一次確認結果，再逐步加複雜度；不確定時請工程同事協助。

條件渲染¶

Hello {{ name }},

{% if is_premium %}
Thank you for being a premium member!
{% else %}
Consider upgrading to premium for exclusive benefits.
{% endif %}

迴圈¶

Your orders:
{% for order in orders %}
- Order #{{ order.id }}: {{ order.status }}
{% endfor %}

過濾器¶

Name: {{ name | upper }}
Date: {{ date | default('Not specified') }}
Price: {{ price | round(2) }}

注意： 這些進階功能由 Jinja2 支援。測試你的 Template 以確保它們在你的 Workflow 中按預期運作。

結合其他語法¶

Template 通常與 JSONPath 和 External Memory 語法一起使用：

範例 Workflow：

從 Variable Resource 載入 Template：

{
  "email_template.%": {
    "type": "variable",
    "id": "var-templates",
    "jsonpath": "$.welcome_email"
  }
}

將 Template 傳遞給 Text Action：
Template: $.load_config.email_template

Template Variables:

{
  "name.$": "$.user.name",
  "company.$": "$.load_config.company_name"
}

這允許你：

在 Variable Resource 中儲存 Template（.%）
從 Workflow 狀態引用 Template 和資料（.$）
使用 Template 語法渲染最終文字（{{ }}）

最佳實踐¶

保持 Template 可讀性：

使用適當的格式和縮排
為複雜邏輯新增註解
將長 Template 拆分為多個部分

驗證變數存在：

確保提供所有 Template 變數
對可選值使用 Jinja2 預設值：{{ optional | default('N/A') }}
使用不同輸入測試 Template

用於文字內容：

電子郵件內容和通知
報告生成
格式化訊息
LLM Prompt 和指示

不要用於結構化資料：

對於 JSON/XML 生成或資料整形，改用 Pass Action 或程式碼（Code）Action
Template 用於人類可讀的文字
避免在 Template 中進行複雜的資料操作

「資料轉換（Transformation）」已棄用

舊版文件可能會推薦「資料轉換（Transformation）」Action 來做資料整形，但平台已將它標示為「資料轉換 (已棄用)」。新流程請改用 Pass Action 或 程式碼（Code）Action 來準備／整形資料。

常見錯誤¶

❌ 在非 Template 欄位中使用 Template 語法

{
  "url": "https://api.example.com/users/{{ user_id }}"  // 錯誤！
}

✅ 對動態欄位使用 JSONPath

{
  "url.$": "$.api_url"  // 正確
}

❌ 忘記提供 Template 變數

Template：

Hello {{ name }}, your balance is {{ balance }}

Template Variables：

{
  "name.$": "$.user.name"
  // 遺漏 balance！
}

✅ 提供所有變數或使用預設值

{
  "name.$": "$.user.name",
  "balance.$": "$.account.balance"
}

或在 Template 中：

Hello {{ name }}, your balance is {{ balance | default('N/A') }}

❌ Template 中的複雜邏輯

{% if status == 'active' and balance > 1000 and tier == 'premium' %}
  {% for item in recent_purchases %}
    {% if item.category in preferred_categories %}
      ...complex logic...
    {% endif %}
  {% endfor %}
{% endif %}

✅ 先用 Pass / 程式碼 Action 準備資料

使用 Pass Action 或程式碼（Code）Action 準備簡化的資料，然後使用簡單的 Template 邏輯。（「資料轉換（Transformation）」已棄用，請改用前述替代。）

何時使用 Template 語法¶

使用 {{ }} 語法當：

✅ 渲染人類可讀的文字
✅ 生成電子郵件、報告或通知
✅ 使用動態內容建構 LLM Prompt
✅ 建立格式化訊息

不要使用 {{ }} 當：

❌ 在 Action 欄位中引用資料 → 使用 JSONPath 語法
❌ 存取持久性設定 → 使用 External Memory 語法
❌ 建構結構化資料 → 使用 Pass Action 或程式碼（Code）Action（「資料轉換」已棄用）

Template 語法¶

語法格式¶

何處使用 Template 語法¶

基本使用¶

簡單變數替換¶

多個變數¶

實用範例¶

範例 1：使用 Text Action 的回診提醒 Email¶

範例 2：動態 Prompt（概念示意）¶

範例 3：結合前一個 Action 輸出¶

存取巢狀資料¶

在 Template Variables 中使用 JSONPath¶

進階 Jinja2 功能（進階／選讀）¶

條件渲染¶

迴圈¶

過濾器¶

結合其他語法¶

最佳實踐¶

常見錯誤¶

何時使用 Template 語法¶

相關主題¶