@orangemust/dify-dsl-builder

dify-dsl-builder

CLI tool and TypeScript library for reading, manipulating, and writing Dify DSL YAML files (app.yml).

Installation

npm install -g @orangemust/dify-dsl-builder

Or use via npx without installing:

npx dify-dsl-cli <command> ...

For LLM Agents

Fetch the guides to understand the tool:

curl -s https://raw.githubusercontent.com/mack-peng/dify-dsl-builder/main/docs/guide/installation.md
curl -s https://raw.githubusercontent.com/mack-peng/dify-dsl-builder/main/docs/guide/patch.md

Prefer the YAML Patch system over writing TypeScript code for DSL modifications.

CLI Commands

Inspect

dify-dsl-cli info <file>                 # node/edge counts by type
dify-dsl-cli flow <file> [--short]       # workflow topology tree
dify-dsl-cli find <file> <text>          # search across all node content
dify-dsl-cli node show <file> <id>       # dump full node data
dify-dsl-cli node show <file> <id> --json  # machine-readable JSON
dify-dsl-cli node list <file> [type]     # tabular overview, optional type filter
dify-dsl-cli edge list <file> [node-id]  # edge table
dify-dsl-cli path <file> <from> <to>     # shortest path between nodes

Verify

dify-dsl-cli diff <yml1> <yml2>          # semantic diff (nodes, edges, prompts, conditions)
dify-dsl-cli roundtrip <in> [out]        # parse → save, verify fidelity
dify-dsl-cli validate <file>             # Ruby DSL validator (requires Ruby runtime)

Apply Patches

dify-dsl-cli apply <patch.yml> -i <in> -o <out>   # 17 patch operations + auto-validation

Atomic Modify (in-place)

dify-dsl-cli remove           <file> <id>
dify-dsl-cli node set-title    <file> <id> <title>
dify-dsl-cli node set-desc     <file> <id> <desc>
dify-dsl-cli node set-prompt   <file> <id> <role> <replace> <with>
dify-dsl-cli node set-code     <file> <id[,id2,...]> <replace> <with>
dify-dsl-cli node set-condition <file> <id> <case_id> <field> <value>
dify-dsl-cli edge add          <file> <src> <tgt> [handle]
dify-dsl-cli edge remove       <file> <src> <tgt> [handle]

Completion App Commands

Supports completion apps without workflow/graph (top-level model_config). info, find, diff, roundtrip, validate are all compatible with both modes.

dify-dsl-cli completion show             <file>                # pre_prompt、model、input form
dify-dsl-cli completion set-prompt       <file> <text|@file>   # Replace entire pre_prompt
dify-dsl-cli completion replace          <file> <search> <with> # Substring/regex replace in pre_prompt
dify-dsl-cli completion set-param        <file> <name> <value> # model.completion_params.<name> (auto type inference)
dify-dsl-cli completion remove-param     <file> <name>
dify-dsl-cli completion set-model        <file> <provider> <name> [mode]
dify-dsl-cli completion set-max-tokens   <file> <number>
dify-dsl-cli completion set-temperature  <file> <number>
dify-dsl-cli completion add-input        <file> <variable> <label> [required]
dify-dsl-cli completion remove-input     <file> <variable>
dify-dsl-cli completion set-label        <file> <variable> <label>

set-prompt supports @file syntax to read prompt text from a file (useful for long prompts, avoids shell escaping issues):

dify-dsl-cli completion set-prompt app.yml @prompt.txt
dify-dsl-cli completion set-max-tokens app.yml 2048
dify-dsl-cli completion set-temperature app.yml 0.6

Examples

# Understand the workflow
dify-dsl-cli flow app.yml
dify-dsl-cli find app.yml "temperature"    # find all mentions of a keyword
dify-dsl-cli node show app.yml "llm-001"   # inspect a specific LLM node

# Apply a YAML patch
dify-dsl-cli apply my-patch.yml -i app.yml -o patched.yml

# Quick inline modification
dify-dsl-cli node set-title app.yml "node-42" "New Title"
dify-dsl-cli node set-condition app.yml "if-1" "true" "value" 420

# Verify changes
dify-dsl-cli diff app.yml patched.yml

YAML Patch System

Declaratively modify Dify DSL via YAML patch files. 18 operations — see full guide at docs/guide/patch.md.

description: My patch
steps:
  - set-title: { id: "node-1", value: "New Title" }
  - remove-node: { id: "node-old" }
  - add-edge: { source: "new-node", target: "answer-node" }
  - set-prompt:
      id: "llm-1"
      role: "system"
      replace: "old text"
      with: "new text"
      replaceAll: true
  - update-condition:
      id: "if-else-1"
      case_id: "true"
      field: "value"
      value: 420
  - remove-classifier-class:
      classifier: "cls-1"
      id: "deprecated-class"

Library API

import { DifyDSL } from "@orangemust/dify-dsl-builder";
import * as fs from "fs";

const dsl = DifyDSL.parse(fs.readFileSync("app.yml", "utf-8"));

// CRUD — O(1) lookups
const node = dsl.getNode("node-id");
const llms = dsl.findByType("llm");
dsl.getPrevIds("node-id");
dsl.getNextIds("node-id");

dsl.addEdge("source-id", "target-id");
dsl.removeNode("old-node-id");  // auto-removes related edges

// Serialize
fs.writeFileSync("output.yml", dsl.toYAML());

Full API reference: docs/guide/installation.md

Node Types

Type string	Class	Key methods
start	StartNode	addVariable(v), removeVariable(n)
answer	AnswerNode	setAnswer(tpl), addVariableRef(id,f)
llm	LLMNode	setModel(p,n), setTemperature(t), addPromptMessage(m)
code	CodeNode	setCode(lang,code), addVariable(v), addOutput(name,type)
knowledge-retrieval	KnowledgeNode	addDataset(id), setQuerySelector(id,f)
if-else	IfElseNode	addCase(c), updateCondition(caseId,idx,patch)
template-transform	TemplateNode	setTemplate(tpl), addVariable(v)
variable-aggregator	AggregatorNode	addSource(id,f), removeSource(id)
iteration	IterationNode	addChild(n), removeChild(id), setIterator(id,f)
tool	ToolNode	setPlugin(id,uid), setToolParam(k,v)
question-classifier	ClassifierNode	addClass(c), setModel(p,n)
http-request	HTTPNode	setMethod(m), setUrl(u), setBody(type,data)
document-extractor	DocNode	setVariableSelector(id,field)

License

MIT