dify-workflow-skills

What this skill does

# Dify Workflow DSL Builder

Build, edit, and validate Dify workflow DSL (Domain-Specific Language) files for creating AI-powered automation workflows.

This skill is based on the Dify open-source platform's workflow engine, which powers both Workflow apps and Advanced Chat apps with a React Flow-based visual editor.

## Architecture Overview

Dify workflows use a **queue-based, event-driven architecture** with:

### Backend (Python - Execution Engine)
- **GraphEngine**: Central orchestrator managing workflow execution
- **WorkerPool**: Thread pool for parallel node execution
- **VariablePool**: Centralized variable management across nodes
- **EdgeProcessor**: Handles conditional routing and branch selection
- **Graph Validator**: Ensures workflow integrity before execution

### Frontend (React/TypeScript - Visual Editor)
- **React Flow**: Canvas-based node graph editor
- **Zustand Store**: State management for nodes, edges, and viewport
- **WorkflowContext**: Provides workflow state to component tree
- **BaseNode**: Common wrapper for all node types with handles, headers, and interactions
- **Panel System**: Dynamic configuration panels for each node type
- **Hook Injection Pattern**: Decouples UI from execution logic (draft sync, workflow run)

### Integration Layer
- **workflow**: Core canvas engine (generic React Flow implementation)
- **workflow-app**: Application wrapper (business logic, API integration, lifecycle management)
- **Draft Management**: Auto-save with debouncing and `sendBeacon` for safety
  - Uses debounced sync to prevent excessive API calls
  - Cancels pending syncs on unmount to avoid race conditions
  - Tracks loaded state with `isWorkflowDataLoaded` flag
- **Features System**: Optional features (file upload, speech-to-text, citations) integrated with workflow
- **Trigger Status Management**: Separate store for tracking trigger node enable/disable state
  - Trigger nodes can be enabled or disabled independently
  - Status persists across workflow editor sessions
  - Used for webhook, schedule, and plugin triggers

## Core Capabilities

1. **Create new workflows** - Generate complete workflow YAML files from descriptions
2. **Edit existing workflows** - Add, modify, or remove nodes and connections
3. **Validate workflows** - Check DSL syntax and structure
4. **Design complex flows** - Build workflows with LLM nodes, code execution, branching, loops, and error handling
5. **Error handling strategies** - Implement fail-branch, retry, or default-value error handling

## Quick Reference

**Node Types**: See [references/node_types.md](references/node_types.md) for complete list including:
- **Core Flow**: start, end, answer
- **LLM & AI**: llm, agent, parameter-extractor
- **Logic & Control**: if-else, question-classifier, loop, iteration
- **Data Processing**: code, template-transform, variable-aggregator, assigner, list-operator, document-extractor
- **External Integration**: http-request, tool, knowledge-retrieval, knowledge-index, datasource
- **Advanced**: trigger-webhook, trigger-schedule, trigger-plugin, human-input

**Edge Types and Connections**: See [references/edge_types.md](references/edge_types.md) for:
- Source handle types (source, true/false, success-branch/fail-branch, loop)
- Edge data properties and validation rules
- Common connection patterns

**Node Positioning**: See [references/node_positioning.md](references/node_positioning.md) for:
- Canvas coordinate system and spacing guidelines
- Layout patterns (linear, branching, error handling, iteration)
- Position calculation formulas

**Common Node Properties**: All nodes support these internal properties (prefixed with `_`):
- `_runningStatus`: Current execution status (running, succeeded, failed)
- `_connectedSourceHandleIds`/`_connectedTargetHandleIds`: Connection tracking
- `_isSingleRun`: Single execution mode for debugging
- `_isCandidate`: Phantom node during connection drag
- `_children`: Child nodes for container types (iteration, loop)
- `_iterationLength`/`_iterationIndex`: Iteration state tracking
- `_loopLength`/`_loopIndex`: Loop state tracking
- `_retryIndex`: Current retry attempt
- `_waitingRun`: Queued for execution, human-input

**Workflow Structure**: See [references/workflow_structure.md](references/workflow_structure.md) for complete DSL format

**Edge Types**: See [references/edge_types.md](references/edge_types.md) for connection patterns and handle types

**Node Positioning**: See [references/node_positioning.md](references/node_positioning.md) for layout guidelines

**Templates**: Check [assets/](assets/) for example workflows

## Creating a New Workflow

### Step 1: Understand Requirements

Ask the user:
- What should the workflow do?
- What are the inputs and outputs?
- What processing steps are needed?
- Any conditional logic or error handling?

### Step 2: Design Node Flow

Plan the workflow structure:

1. **Start node** - Define input variables
2. **Processing nodes** - LLM, code, tools, etc.
3. **Control flow** - if-else for branching, loop for iteration
4. **Error handling** - Use fail-branch on code nodes
5. **Output aggregation** - variable-aggregator to merge branches
6. **End node** - Define outputs

### Step 3: Generate Node IDs

Use `scripts/generate_id.py` to create unique node IDs:

```bash
python3 scripts/generate_id.py 5  # Generate 5 unique IDs
```

Or generate in Python/JavaScript:
```python
# Python
import time
node_id = str(int(time.time() * 1000))
```

```javascript
// JavaScript (used in Dify frontend)
const nodeId = `${Date.now()}`
```

**Special ID patterns for container nodes**:
- Iteration/Loop start nodes: `${parentNodeId}start`
- Example: If iteration node ID is `1736668800000`, its start node ID is `1736668800000start`

### Step 4: Build the Workflow

Create the complete YAML structure with:
- Top-level metadata (kind, version, app)
- App section (name, description, icon)
- Workflow section with features and graph
- Nodes array with positions
- Edges array connecting nodes

**Template to use**: Start from `assets/simple_llm_workflow.yml` for basic flows

### Step 5: Validate

Check the workflow structure for common issues:
- All nodes have unique IDs
- All edges reference existing node IDs
- Start and end nodes exist
- Required fields are present
- Variable references use correct syntax: `{{#node_id.field#}}`

## Common Workflow Patterns

### Pattern 1: Simple LLM Flow

Start → LLM → End

**Use case**: Basic question answering, text generation

**Template**: `assets/simple_llm_workflow.yml`

### Pattern 2: Error Handling Flow

Start → Code (with fail-branch) → [Success → Aggregator] / [Fail → LLM Recovery → Retry → Aggregator] → End

**Use case**: Robust data processing with error recovery

**Template**: `assets/error_handling_workflow.yml`

**Key points**:
- Set `error_strategy: fail-branch` on code node
- Fail branch provides `error_message` and `error_type` variables
- Use variable-aggregator to merge success/fail branches
- Reference aggregator output in end node

### Pattern 3: Conditional Routing

Start → If-Else → [True → Handler A] / [False → Handler B] → Aggregator → End

**Use case**: Route requests based on content/type

**Template**: `assets/conditional_workflow.yml`

**Key points**:
- If-else has `true` and `false` sourceHandles
- Use comparison operators: contains, starts_with, is_empty, etc.
- Combine conditions with logical_operator: "and" or "or"

### Pattern 4: Loop Processing

Start → Loop → [Process Items] → Loop End → End

**Use case**: Iterative processing with break conditions

**Key points**:
- Set `loop_count` for maximum iterations
- Define `break_conditions` to exit early
- Loop maintains state across iterations

## Editing Existing Workflows

### Adding a Node

1. Read the existing workflow file
2. Generate a new unique node ID
3. Add node to `workflow.graph.nodes` array with:
   - Unique ID and position
   - Node type and configuration
   - Proper sourcePosition/targetPosition