Dify DSL Writer (Two-Phase: Mermaid → DSL)

Purpose

Produce correct, maintainable Dify DSL from ambiguous natural-language requirements by first converging on an explicit step graph.

When to use

Use this skill when the user asks to:

• “根据需求写/生成 Dify 工作流 DSL / Chatflow DSL”
• “把业务流程变成 Dify workflow/chatflow”
• “先画流程图再生成 Dify DSL”

Do not use this skill for:

• Pure conversion between existing chatflow/workflow YAML (use dify-dsl-converter instead)
• UI/UX design not related to Dify DSL graphs

Operating principle (must follow)

Always follow a strict two-phase workflow:

1. Phase A (Analysis → Mermaid file)

• Analyze the user’s requirements.
• Derive an executable workflow step list and decision points.
• Output a Mermaid flowchart to a markdown file.
• Ask the user to confirm or request edits.

2. Phase B (Confirmed steps → Dify DSL YAML)

• Only after user confirmation, map the Mermaid steps to Dify nodes.
• Generate either Workflow DSL (app.mode: workflow) or Chatflow DSL (app.mode: advanced-chat).

Phase A — Requirement intake and step derivation

A1. Decide target app mode

Determine the target:

• Workflow when the user wants a single-pass automation or batch job (outputs returned by an end node).
• Chatflow when the user wants multi-turn conversation with memory (outputs returned by an answer node).

If ambiguous, ask one short question:

• “最终要的是 Dify Workflow（一次执行）还是 Chatflow（多轮对话）？”

A2. Extract the minimal executable spec

Extract, explicitly list:

• Inputs (fields users will provide): text, files, IDs, options.
• Outputs: what should be returned at the end (result fields).
• External dependencies: dataset IDs, API endpoints, tool/plugin names, auth.
• Branching conditions and fallbacks.
• Error handling expectations.

If any of these are missing, ask focused questions (prefer ≤5 at a time). Use the intake template in references/requirement_intake.md.

A3. Produce a step list

Produce:

• Step list with unique step IDs (S1, S2, …)
• For each step: purpose, inputs consumed, outputs produced
• Identify decision nodes (D1, D2, …) with clear condition text

A4. Write Mermaid to a markdown file

Create a markdown file containing:

• Title
• Assumptions
• Mermaid flowchart TD block
• “Nodes dictionary” table mapping Mermaid nodes → intended Dify node type (tentative)

File naming convention (default):

• dify-design/<app_name>-steps.mmd.md

If the user provides a specific path, follow it.

Use templates from references/mermaid_templates.md.

A5. Confirmation gate

After writing the Mermaid file, ask for confirmation:

• “请确认流程图是否正确：节点、分支条件、输入输出、异常兜底。”

Do not generate Dify YAML before confirmation.

Phase B — Map confirmed steps to Dify DSL

B1. Choose node types

Map steps to Dify nodes using references/node_types.md:

• Input collection → start
• LLM generation → llm
• RAG → knowledge-retrieval
• Intent routing → question-classifier
• Branching → if-else (or classifier branches)
• API call → http-request
• Deterministic logic → code
• String shaping → template-transform
• Join/merge outputs → variable-aggregator
• Final output → end (workflow) or answer (chatflow)

B2. Define variables and selectors

Rules:

• Start input variables live under start.data.variables.
• Reference variables with {{#node_id.output#}}.
• Use value_selector: [node_id, output_name] in end outputs.

B3. Build a clean graph

Rules:

• Use stable, readable node ids: start, route, llm_main, rag, api_call, end.
• Ensure every non-terminal node has at least one outgoing edge.
• Ensure there is exactly one terminal node (end in workflow, answer in chatflow).
• Assign simple positions (grid) for readability.

B4. Produce DSL YAML file(s)

Default output location conventions (follow user preference if provided):

• Workflow DSL: dify-workflow/<app_name>-workflow.yml
• Chatflow DSL: dify-chatflow/<app_name>.yml

If the user wants both, generate chatflow first and optionally produce workflow by conversion using the existing converter script.

B5. Quick validation checklist

Before finishing, verify:

• kind: app, version: 0.1.0 (or keep existing if user asked to integrate)
• app.mode is correct
• Graph has nodes and edges
• All edges.source/target refer to real node IDs
• Workflow uses end with outputs, Chatflow uses answer with answer text
• No conversation_variables in workflow mode

Bundled references

Load these files when needed:

• references/dify_dsl_schema.md — top-level schema and common node examples
• references/node_types.md — node type capabilities and configuration hints
• references/dsl_skeletons.md — minimal copy/paste YAML starters for workflow/chatflow
• references/requirement_intake.md — requirement questions and extraction checklist
• references/mermaid_templates.md — Mermaid templates and style conventions