SystemTce/dify-skills

Dify 參考資料 SKILL

查詢語法、API、CLI 等參考資訊

快速導覽

• DSL 語法參考
• API 參考
• SDK 參考
• CLI 參考
• 常見問題

---

DSL 語法參考

工作流程 DSL 結構

version: 0.0.1
graph:
  nodes:
    - id: node_id
      data:
        type: node_type
        # 節點配置
  edges:
    - source: source_node_id
      target: target_node_id

節點類型

類型	說明	必填欄位
start	開始節點	variables
llm	LLM 節點	model, prompt_template
agent	Agent 節點	agent_parameters
knowledge-retrieval	知識檢索	dataset_ids, query_variable_selector
http-request	HTTP 請求	url, method, headers
code	程式碼執行	code_type, code
tool	工具節點	provider_type, tool_name
if-else	條件分支	conditions
iteration	疊代	iterator_variable_name
loop	迴圈	max_loop_count
answer	回應節點	answer

變數引用

# 系統變數
{{#sys.query#}}           # 使用者查詢
{{#sys.files#}}           # 上傳的檔案
{{#sys.conversation_id#}} # 對話 ID

# 節點輸出
{{#node_id.output_field#}}

# 陣列存取
{{#items[0]#}}           # 陣列第一個元素
{{#items[-1]#}}          # 陣列最後一個元素

# 物件屬性
{{#object.field#}}       # 物件屬性

完整範例

workflow:
  graph:
    nodes:
      - id: start
        data:
          type: start
          variables:
            - name: query
              type: text
              required: true

      - id: classify
        data:
          type: question-classifier
          instruction: "分類使用者問題"
          categories:
            - name: technical
              description: 技術問題
            - name: general
              description: 一般問題

      - id: llm
        data:
          type: llm
          model:
            provider: openai
            name: gpt-4
          prompt_template:
            - role: system
              text: "你是個助手"
            - role: user
              text: "{{#start.query#}}"
          context:
            enabled: false

      - id: answer
        data:
          type: answer
          answer: "{{#llm.text#}}"

    edges:
      - source: start
        target: classify
      - source: classify
        target: llm
        source_handle: general
      - source: llm
        target: answer

---

API 參考

認證

所有 API 請求需要在 Header 中攜帶 API Key：

Authorization: Bearer YOUR_API_KEY

端點概覽

應用 API

端點	方法	說明
/v1/chat-messages	POST	傳送聊天訊息
/v1/completions	POST	文字補全
/v1/parameters	GET	取得應用參數
/v1/file-upload	POST	檔案上傳

工作流程 API

端點	方法	說明
/v1/workflows/run	POST	執行工作流程
/v1/workflows/run	GET	取得執行狀態
/v1/workflows/tasks	GET	取得任務列表

資料集 API

端點	方法	說明
/v1/datasets	GET	列出資料集
/v1/datasets	POST	建立資料集
/v1/datasets/{id}/documents	GET	列出文件
/v1/datasets/{id}/retrieve	POST	檢索知識

請求/回應格式

聊天訊息請求

{
  "query": "使用者查詢",
  "user": "user_123",
  "conversation_id": "可選的對話ID",
  "response_mode": "blocking | streaming",
  "files": [
    {
      "type": "image",
      "transfer_method": "remote_url",
      "url": "https://example.com/image.jpg"
    }
  ],
  "retrieval_model": {
    "query": "{{#sys.query#}}",
    "top_k": 3
  }
}

聊天訊息回應

{
  "message_id": "msg_xxx",
  "conversation_id": "conv_xxx",
  "answer": "AI 回覆內容",
  "metadata": {
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 50,
      "total_tokens": 150
    },
    "retrieval_resources": [
      {
        "position": 1,
        "document_id": "doc_xxx",
        "content": "相關文件內容..."
      }
    ]
  }
}

錯誤回應

{
  "code": "invalid_api_key",
  "message": "Invalid API key",
  "status_code": 401
}

常見錯誤碼：

錯誤碼	HTTP 狀態碼	說明
invalid_api_key	401	API Key 無效
invalid_parameter	400	參數錯誤
quota_exceeded	403	配額超出
rate_limit_exceeded	429	速率限制
internal_server_error	500	伺服器錯誤

---

SDK 參考

Python SDK

安裝

pip install dify-client

基本用法

from dify_client import DifyClient

# 初始化客戶端
client = DifyClient(
    api_key="app-xxx",
    base_url="https://api.dify.ai/v1"
)

# 傳送聊天訊息
response = client.chat.messages.create(
    query="你好",
    user="user_123"
)
print(response.answer)

串流回應

from dify_client import DifyClient

client = DifyClient(api_key="app-xxx")

# 串流聊天
for event in client.chat.messages.stream(
    query="講個故事",
    user="user_123"
):
    if event.event == "message":
        print(event.data.answer, end="")

工作流程執行

# 執行工作流程
response = client.workflows.run(
    inputs={"query": "測試"},
    user="user_123",
    response_mode="blocking"
)
print(response.data.output)

SDK 類別參考

DifyClient

class DifyClient:
    def __init__(self, api_key: str, base_url: str = "https://api.dify.ai/v1"):
        """初始化客戶端"""
        pass

    @property
    def chat(self) -> ChatClient:
        """聊天客戶端"""
        pass

    @property
    def workflows(self) -> WorkflowClient:
        """工作流程客戶端"""
        pass

    @property
    def datasets(self) -> DatasetClient:
        """資料集客戶端"""
        pass

ChatClient

class ChatClient:
    def create(self, query: str, user: str, **kwargs) -> ChatMessage:
        """傳送聊天訊息（阻塞）"""
        pass

    def stream(self, query: str, user: str, **kwargs) -> Iterator[ChatEvent]:
        """傳送聊天訊息（串流）"""
        pass

---

CLI 參考

安裝

pip install dify-cli

指令概覽

外掛指令

# 初始化外掛
dify plugin init [options]

# 執行外掛
dify plugin run [options]

# 打包外掛
dify plugin package [options]

# 發佈外掛
dify plugin publish [options]

# 列出已安裝外掛
dify plugin list

工作流程指令

# 匯出工作流程
dify workflow export <workflow_id> [options]

# 匯入工作流程
dify workflow import <file> [options]

# 驗證工作流程
dify workflow validate <file>

# 執行工作流程
dify workflow run <workflow_id> --inputs '{}'

應用程式指令

# 列出應用程式
dify app list

# 取得應用程式資訊
dify app info <app_id>

# 部署應用程式
dify app deploy <app_id>

環境變數指令

# 列出環境變數
dify env list

# 設定環境變數
dify env set <key> <value>

# 取得環境變數
dify env get <key>

# 刪除環境變數
dify env delete <key>

選項說明

選項	簡寫	說明	預設值
--api-key	-k	API Key	環境變數 DIFY_API_KEY
--base-url	-b	基礎 URL	https://api.dify.ai/v1
--output	-o	輸出格式	json
--quiet	-q	靜默模式	false
--debug	-d	除錯模式	false

使用範例

# 設定 API Key
export DIFY_API_KEY="app-xxx"

# 初始化外掛專案
dify plugin init my-plugin --template tool

# 執行外掛
dify plugin run --port 5000

# 匯出工作流程
dify workflow export wf_xxx -o workflow.yaml

# 匯入工作流程
dify workflow import workflow.yaml

---

常見問題

API 相關

Q: 如何取得 API Key？ A: 在 Dify 控制台 -> 設定 -> API 中建立。

Q: 請求頻率限制是多少？ A: 預設 60 請求/分鐘，可申請提升。

Q: 如何處理串流回應？ A: 使用 response_mode=streaming，解析 SSE 事件。

工作流程相關

Q: 如何引用變數？ A: 使用 {{#node_id.field#}} 語法。

Q: 支援哪些節點類型？ A: 詳見節點類型表格。

Q: 如何處理迴圈？ A: 使用 iteration 或 loop 節點。

外掛相關

Q: 如何開發自訂外掛？ A: 參考 02-plugin SKILL。

Q: 外掛如何取得憑證？ A: 使用 self.runtime_credentials。

---

相關 SKILL

• 01-workflow - 工作流程設計
• 02-plugin - 外掛開發
• 05-integration - 整合擴充

---

相關資源

• Dify 官方文件
• Dify API 文件
• Dify GitHub

---

版本資訊: v1.0.0 | 最後更新: 2026-03-05