SystemTce/dify-skills

SKILL de Referência do Dify

Consulte informações de sintaxe, API, CLI e outras referências

Navegação Rápida

• Referência de Sintaxe DSL
• Referência da API
• Referência do SDK
• Referência da CLI
• Perguntas Frequentes

---

Referência de Sintaxe DSL

Estrutura DSL do Workflow

version: 0.0.1
graph:
  nodes:
    - id: node_id
      data:
        type: node_type
        # configuração do nó
  edges:
    - source: source_node_id
      target: target_node_id

Tipos de Nó

Tipo	Descrição	Campos Obrigatórios
start	Nó de início	variables
llm	Nó LLM	model, prompt_template
agent	Nó de Agente	agent_parameters
knowledge-retrieval	Recuperação de conhecimento	dataset_ids, query_variable_selector
http-request	Requisição HTTP	url, method, headers
code	Execução de código	code_type, code
tool	Nó de ferramenta	provider_type, tool_name
if-else	Ramificação condicional	conditions
iteration	Iteração	iterator_variable_name
loop	Loop	max_loop_count
answer	Nó de resposta	answer

Referência de Variáveis

# Variáveis de sistema
{{#sys.query#}}           # Consulta do usuário
{{#sys.files#}}           # Arquivos enviados
{{#sys.conversation_id#}} # ID da conversa

# Saída de nó
{{#node_id.output_field#}}

# Acesso a arrays
{{#items[0]#}}           # Primeiro elemento do array
{{#items[-1]#}}          # Último elemento do array

# Propriedades de objeto
{{#object.field#}}       # Propriedade de objeto

Exemplo Completo

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

      - id: classify
        data:
          type: question-classifier
          instruction: "Classificar pergunta do usuário"
          categories:
            - name: technical
              description: Pergunta técnica
            - name: general
              description: Pergunta geral

      - id: llm
        data:
          type: llm
          model:
            provider: openai
            name: gpt-4
          prompt_template:
            - role: system
              text: "Você é um assistente"
            - 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

---

Referência da API

Autenticação

Todas as requisições à API devem incluir a chave da API no cabeçalho:

Authorization: Bearer YOUR_API_KEY

Visão Geral dos Endpoints

API de Aplicações

Endpoint	Método	Descrição
/v1/chat-messages	POST	Enviar mensagem de chat
/v1/completions	POST	Completar texto
/v1/parameters	GET	Obter parâmetros da aplicação
/v1/file-upload	POST	Enviar arquivo

API de Workflows

Endpoint	Método	Descrição
/v1/workflows/run	POST	Executar workflow
/v1/workflows/run	GET	Obter status de execução
/v1/workflows/tasks	GET	Listar tarefas

API de Datasets

Endpoint	Método	Descrição
/v1/datasets	GET	Listar datasets
/v1/datasets	POST	Criar dataset
/v1/datasets/{id}/documents	GET	Listar documentos
/v1/datasets/{id}/retrieve	POST	Recuperar conhecimento

Formato de Requisição/Resposta

Requisição de Mensagem de Chat

{
  "query": "Consulta do usuário",
  "user": "user_123",
  "conversation_id": "ID de conversa opcional",
  "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
  }
}

Resposta de Mensagem de Chat

{
  "message_id": "msg_xxx",
  "conversation_id": "conv_xxx",
  "answer": "Conteúdo da resposta da IA",
  "metadata": {
    "usage": {
      "prompt_tokens": 100,
      "completion_tokens": 50,
      "total_tokens": 150
    },
    "retrieval_resources": [
      {
        "position": 1,
        "document_id": "doc_xxx",
        "content": "Conteúdo do documento relevante..."
      }
    ]
  }
}

Respostas de Erro

{
  "code": "invalid_api_key",
  "message": "Chave de API inválida",
  "status_code": 401
}

Códigos de erro comuns:

Código de Erro	Código HTTP	Descrição
invalid_api_key	401	Chave de API inválida
invalid_parameter	400	Parâmetro inválido
quota_exceeded	403	Cota excedida
rate_limit_exceeded	429	Limite de taxa excedido
internal_server_error	500	Erro interno do servidor

---

Referência do SDK

SDK Python

Instalação

pip install dify-client

Uso Básico

from dify_client import DifyClient

# Inicializar cliente
client = DifyClient(
    api_key="app-xxx",
    base_url="https://api.dify.ai/v1"
)

# Enviar mensagem de chat
response = client.chat.messages.create(
    query="Olá",
    user="user_123"
)
print(response.answer)

Resposta em Streaming

from dify_client import DifyClient

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

# Chat em streaming
for event in client.chat.messages.stream(
    query="Conte uma história",
    user="user_123"
):
    if event.event == "message":
        print(event.data.answer, end="")

Execução de Workflow

# Executar workflow
response = client.workflows.run(
    inputs={"query": "Teste"},
    user="user_123",
    response_mode="blocking"
)
print(response.data.output)

Referência de Classes do SDK

DifyClient

class DifyClient:
    def __init__(self, api_key: str, base_url: str = "https://api.dify.ai/v1"):
        """Inicializar cliente"""
        pass

    @property
    def chat(self) -> ChatClient:
        """Cliente de chat"""
        pass

    @property
    def workflows(self) -> WorkflowClient:
        """Cliente de workflows"""
        pass

    @property
    def datasets(self) -> DatasetClient:
        """Cliente de datasets"""
        pass

ChatClient

class ChatClient:
    def create(self, query: str, user: str, **kwargs) -> ChatMessage:
        """Enviar mensagem de chat (bloqueante)"""
        pass

    def stream(self, query: str, user: str, **kwargs) -> Iterator[ChatEvent]:
        """Enviar mensagem de chat (streaming)"""
        pass

---

Referência da CLI

Instalação

pip install dify-cli

Visão Geral dos Comandos

Comandos de Plugin

# Inicializar plugin
dify plugin init [options]

# Executar plugin
dify plugin run [options]

# Empacotar plugin
dify plugin package [options]

# Publicar plugin
dify plugin publish [options]

# Listar plugins instalados
dify plugin list

Comandos de Workflow

# Exportar workflow
dify workflow export <workflow_id> [options]

# Importar workflow
dify workflow import <file> [options]

# Validar workflow
dify workflow validate <file>

# Executar workflow
dify workflow run <workflow_id> --inputs '{}'

Comandos de Aplicação

# Listar aplicações
dify app list

# Obter informações da aplicação
dify app info <app_id>

# Implantar aplicação
dify app deploy <app_id>

Comandos de Variáveis de Ambiente

# Listar variáveis de ambiente
dify env list

# Definir variável de ambiente
dify env set <chave> <valor>

# Obter variável de ambiente
dify env get <chave>

# Deletar variável de ambiente
dify env delete <chave>

Descrição das Opções

Opção	Abreviação	Descrição	Valor Padrão
--api-key	-k	Chave da API	Variável de ambiente DIFY_API_KEY
--base-url	-b	URL base	https://api.dify.ai/v1
--output	-o	Formato de saída	json
--quiet	-q	Modo silencioso	false
--debug	-d	Modo de depuração	false

Exemplos de Uso

# Definir chave da API
export DIFY_API_KEY="app-xxx"

# Inicializar projeto de plugin
dify plugin init meu-plugin --template tool

# Executar plugin
dify plugin run --port 5000

# Exportar workflow
dify workflow export wf_xxx -o workflow.yaml

# Importar workflow
dify workflow import workflow.yaml

---

Perguntas Frequentes

Relacionadas à API

P: Como obter uma chave de API? R: No console do Dify, vá em Configurações -> API e crie uma.

P: Qual é o limite de frequência de requisições? R: O padrão é 60 requisições/minuto. É possível solicitar aumento.

P: Como lidar com respostas em streaming? R: Use response_mode=streaming e processe os eventos SSE.

Relacionadas a Workflows

P: Como referenciar variáveis? R: Use a sintaxe {{#node_id.field#}}.

P: Quais tipos de nó são suportados? R: Consulte a tabela de tipos de nó.

P: Como lidar com loops? R: Use nós iteration ou loop.

Relacionadas a Plugins

P: Como desenvolver um plugin personalizado? R: Consulte o SKILL 02-plugin.

P: Como o plugin obtém credenciais? R: Use self.runtime_credentials.

---

SKILLs Relacionados

• 01-workflow - Design de Workflow
• 02-plugin - Desenvolvimento de Plugin
• 05-integration - Extensão de Integração

---

Recursos Relacionados

• Documentação oficial do Dify
• Documentação da API do Dify
• GitHub do Dify

---

Informações da versão: v1.0.0 | Última atualização: 2026-03-05