Dify Orchestrator (Self-Hosted)

Fokussierter Skill fuer den operativen Umgang mit einer self-hosted Dify-Instanz: Apps, Datasets, Prompts, Uploads, Retrieval-Checks und Machbarkeitsbewertung.

Arbeitsbereich: Instanzbetrieb und Dify-Management Nicht zustaendig: Workflow-DSL authoring oder Import-Editing. Dafuer den Skill ../dify-workflow/SKILL.md verwenden.

Trigger Conditions

Use when:

• Creating, listing, inspecting, or deleting Dify apps
• Updating prompts for chat/completion style apps
• Creating or linking datasets
• Uploading files into datasets
• Searching an existing knowledge base
• Running a health check on a self-hosted Dify setup
• Checking whether a requested Dify feature is supported on the deployed version

Scope Boundaries

Nutze diesen Skill fuer:

• App-Orchestrierung
• Prompt- und Dataset-Operationen
• Knowledge-Base-Management
• Management-API und Console-API Ablaufe
• Betriebsnahe Entscheidungen und Machbarkeitspruefung

Nutze dify-workflow fuer:

• Workflow-DSL schreiben oder editieren
• Node-/Edge-Strukturen aendern
• Import-/Export-basierte Workflow-Migration
• YAML-Validierung fuer Workflow-Dateien

Expert Domains

Dieser Skill soll langfristig ein echter self-hosted-Dify-Experte fuer diese Bereiche werden:

• App-Typen und ihre Einsatzgrenzen
• Prompt-, Dataset- und Knowledge-Base-Operationen
• self-hosted API-/Console-/Management-Abgrenzung
• Feature-Machbarkeit gegen aktuelle Docs und Releases
• Plugin-/Provider-Aussagen nur mit belastbarer Quelle oder Instanztest

Rapid Triage

Bleibe in dify, wenn der User vor allem nach diesen Dingen fragt:

• "Erstelle oder aendere eine App"
• "Verknuepfe ein Dataset"
• "Passe den Prompt an"
• "Pruefe Retrieval oder die Knowledge Base"
• "Ist Feature X in meiner Dify-Version verfuegbar?"

Das sind in der Regel Management-Operationen an App, Prompt oder Dataset, nicht Workflow-DSL-Aenderungen.

Wechsle zu dify-workflow, sobald mindestens eines davon zutrifft:

• der User liefert exportiertes Workflow-JSON/YAML
• es geht um Nodes, Edges, Handles, Branches oder Variablen-Syntax
• der Fehler liegt beim Import oder in der DSL-Struktur
• der Wunsch laesst sich nur per Workflow-Edit statt per Management-Operation loesen

Operating Principles

1. Version first: Vor riskanten Aussagen Release Notes und offizielle Dify-Doku pruefen.
2. Management before DSL: Wenn das Ziel per App-/Dataset-/Prompt-Operation loesbar ist, nicht unnötig in Workflow-DSL abtauchen.
3. Export before workflow edits: Sobald die Anfrage Workflow-JSON/YAML betrifft, an dify-workflow uebergeben.
4. Secrets stay out of content: Keine API-Keys in Prompts, Beispielen, Logs oder Skill-Doku.
5. Least surprise: Vor destruktiven Schritten den Impact klar benennen.

Available MCP Tools

Der kanonische MCP-Server liegt unter /Users/alexanderschneider/mcp-servers/dify-manager.

App Management

dify-manager:list_dify_apps({limit: 20})
dify-manager:create_dify_app({name, mode, description, icon})
dify-manager:get_dify_app({app_id})
dify-manager:update_dify_prompt({app_id, system_prompt, opening_statement})
dify-manager:delete_dify_app({app_id})

Dataset And Knowledge Base

dify-manager:list_dify_datasets({limit: 20})
dify-manager:create_dify_dataset({name, description, indexing_technique, doc_form})
dify-manager:link_dataset_to_app({app_id, dataset_id})
dify-manager:add_document_to_dataset({dataset_id, file_path, indexing_technique, doc_form})
dify-manager:search_knowledge_base({query, dataset_names, limit, score_threshold})

Monitoring

dify-manager:get_dify_stats()

Expert References

• references/app_types.md: belastbare Regeln fuer Chatbot, Text Generator, Agent, Chatflow und Workflow
• references/app_type_decision_guide.md: Entscheidungslogik und Anti-Patterns fuer die App-Typ-Auswahl
• references/plugins_and_providers.md: workspace-scoped Plugins, Provider-Logik, self-hosted OAuth und Trigger-Besonderheiten
• references/version_notes.md: aktuelle Versionssignale fuer Plugin-System, Trigger und Workflow-Engine
• references/knowledge_retrieval.md: aktuelle Retrieval-Regeln fuer Knowledge Bases, Rerank, Top K und self-hosted Bildsuche
• references/self_hosted_operations.md: Betriebsregeln fuer API-/Console-Trennung, Secrets, Smoke-Checks und Trigger-/OAuth-Realitaet
• references/plugin_integration_patterns.md: Datasources, Agent Strategies, Trigger und Extensions als Integrationsmuster

Preflight Checklist

Vor jeder Schreib- oder Loeschoperation kurz verifizieren:

1. Ist klar, welcher Endpunkt betroffen ist: DIFY_MGMT_API_URL, DIFY_API_URL oder DIFY_CONSOLE_API_URL?
2. Passt die geplante Operation zum App-Typ und zur API-Oberflaeche?
3. Sind App-ID, Dataset-ID oder Dateipfad gegen den Ist-Zustand geprueft?
4. Ist bei potenziell destruktiven Schritten wie delete_dify_app(...) der Impact klar benannt?
5. Gibt es direkt danach einen lesenden Check oder Smoke-Check?

Loeschoperationen nie sofort ausfuehren: erst Impact benennen, dann ausdrueckliche Bestaetigung einholen, danach den Smoke-Check planen.

Self-Hosted Operations Discipline

1. Management-, Runtime- und Console-Pfade nicht vermischen.
2. Secrets nur als lokale Konfiguration oder Secret-Store denken, nie als Skill-Inhalt.
3. Nach App-, Prompt-, Dataset- oder Trigger-Aenderungen immer einen lesenden Folge-Check oder Smoke-Check nennen.
4. Cloud-Komfort nie stillschweigend fuer self-hosted annehmen.

External Verification

Bei unsicheren oder versionsabhaengigen Fragen:

1. Offizielle Dify-Doku pruefen
2. GitHub Releases von langgenius/dify pruefen
3. Erst dann konkrete Aussage oder Umsetzungsplan geben

Typische Kandidaten fuer Verifikation:

• neue Features
• Limits oder Storage-Verhalten
• Plugin-/Provider-Support
• Console-API-Verhalten
• Unterschiede zwischen Chat, Completion, Workflow, Advanced Chat

Primaerquellen und Ausbau-Backlog liegen unter ../../../research/.

Recommended Interaction Pattern

Phase 1: Request Triage

Frueh unterscheiden:

• Geht es um App-/Dataset-Verwaltung? Dann hier bleiben.
• Geht es um Workflow-DSL? Dann zu dify-workflow.
• Geht es um Versions-/Feature-Fragen? Erst Docs/Release Notes pruefen.

Praktische Handover-Formulierung:

Das ist keine reine App- oder Dataset-Operation mehr. Ich wechsle auf `dify-workflow`, weil hier eine Workflow-DSL-Aenderung mit export-first, minimalem Edit und erfolgreichem Re-Import auf derselben Zielinstanz noetig ist.

Phase 2: Current State Check

Vor Aenderungen nach Bedarf:

1. list_dify_apps()
2. list_dify_datasets()
3. get_dify_stats()
4. get_dify_app(app_id) bei bestehenden Apps

Phase 3: Safe Execution

• Kleine Schritte statt Massenmutation
• IDs und Namen vor Schreiboperationen verifizieren
• Bei Batch-Operationen Fortschritt und Anzahl nennen
• Bei potenziell destruktiven Schritten explizit warnen

Phase 4: Verification

Nach Aenderungen:

• App-/Dataset-Zustand erneut lesen
• Falls Prompt geaendert wurde: App-Details oder UI-Test empfehlen
• Falls Uploads erfolgt sind: Retrieval oder UI-Pruefung empfehlen

Minimaler Abschluss pro Schreiboperation:

1. Zielobjekt erneut lesen
2. IDs/Namen gegen Erwartung pruefen
3. naechsten operativen Smoke-Check nennen

Common Tasks

New Chat Assistant

1. Anwendungsfall klaeren
2. Als New Chat Assistant behandeln und create_dify_app(...) ausfuehren
3. optional create_dify_dataset(...)
4. link_dataset_to_app(...)
5. update_dify_prompt(...)
6. Upload- und Testschritte nennen

Health Check

1. get_dify_stats()
2. list_dify_apps()
3. list_dify_datasets()
4. Probleme benennen:
   • leere Datasets
   • unverknuepfte Datasets
   • alte oder inaktive Apps
   • Prompt-Duplikate

Knowledge Base Check

1. Ziel-Dataset identifizieren
2. optional Datei per add_document_to_dataset(...) hochladen
3. search_knowledge_base(...) mit realistischen Queries ausfuehren
4. Retrieval-Qualitaet und naechste Schritte zusammenfassen

Retrieval Triage

1. Query, Ziel-Knowledge-Base und Retrieval-Settings getrennt betrachten.
2. Bei mehreren Knowledge Bases nicht blind eine einzige Ursache annehmen.
3. Top K, Score Threshold, Rerank und Metadatenfilter als eigene Hebel behandeln.
4. Bei bildbasiertem Retrieval self-hosted Limits und multimodale Knowledge Bases mitdenken.

Feature Feasibility Check

1. Gewuenschtes Feature konkret benennen
2. App-Typ und Dify-Bereich klaeren: Chatbot, Text Generator, Agent, Chatflow, Workflow, Plugin oder Provider
3. Offizielle Doku und Releases pruefen
4. Keine blinde Zusage machen, bevor die Quellenlage klar ist
5. Aussage klar markieren:
   • bestaetigt
   • nicht bestaetigt
   • aus Quellen nur indirekt ableitbar

Self-Hosted Operations Triage

1. Vor jeder risikohaften Aussage erst klaeren, welche Oberflaeche wirklich betroffen ist.
2. Trigger-/OAuth-Themen immer mit Domain, Callback, TRIGGER_URL und Admin-Rechten denken.
3. Secrets, Delete-Impact und Smoke-Checks in jeder operativen Antwort mitfuehren.

App-Type Triage

1. Mehrturnige, speichernde, dialogische Logik eher als Chatflow denken.
2. Einmalige Automation oder Batch-Logik eher als Workflow denken.
3. Chatbot, Text Generator und Agent gegen die aktuelle Produktlogik pruefen, statt sie reflexartig als beste Wahl anzunehmen.
4. Unterschiede fuer Memory, Startvariablen, Answer und End aus references/app_types.md ziehen.
5. Anti-Patterns und vereinfachte Oberflaechen mit references/app_type_decision_guide.md abfedern.

Plugin And Provider Triage

1. Plugins als workspace-scoped Komponenten denken.
2. Nicht so tun, als seien Provider fest eingebaut; Modelle und Tools sind plugin-basiert.
3. Bei self-hosted Trigger- oder OAuth-Fragen aktiv nach Admin-Rechten, Domain und Callback-Setup denken.
4. Vor Aussagen zu Plugin-Verfuegbarkeit oder Upgrade-Verhalten Doku, Releases und offizielle Plugin-Quellen pruefen.
5. Datasources, Agent Strategies, Trigger und Extensions bewusst auseinanderhalten.

Version-Sensitive Feature Triage

1. Trigger, Event-Driven-Workflows und neue Engine-/Knowledge-Funktionen nicht pauschal als ueberall vorhanden zusagen.
2. Release-Kontext aktiv nennen, wenn ein Feature juenger oder besonders aenderungsanfällig ist.
3. Bei self-hosted immer zwischen "in Dify-Doku beschrieben" und "auf deiner Instanz sicher verfuegbar" unterscheiden.

Prompt Guidance

Wenn ein Prompt neu erstellt oder ueberarbeitet wird, strukturiere ihn mindestens nach:

• Rolle
• Geltungsbereich
• Antwortstil
• Sicherheitsregeln
• Fallback-Verhalten

Kurzes Muster:

Du bist [Rolle].
Antworte nur im Rahmen von [Scope].
Stil: [kurz/praezise/freundlich/...].
Wenn Informationen fehlen oder die Antwort unsicher ist, sage das klar.

Safety Notes

• update_dify_prompt(...) funktioniert nicht fuer alle App-Typen gleich; bei Workflow-/Advanced-Chat-Faellen keine falsche Sicherheit suggerieren.
• Keine geheimen Zugangsdaten in Skill-Beispielen oder Testdaten verwenden.
• Grosse Dataset-Uploads schrittweise angehen und danach Retrieval pruefen.
• Loeschoperationen nur nach klarer Bestatigung ausfuehren.
• Loeschoperationen immer mit Impact-Hinweis und nachfolgendem Smoke-Check rahmen.
• Keine Workflow-Loesungen vorschlagen, wenn eine reine Management-Operation ausreicht.

Useful References

• Dify Docs: https://docs.dify.ai/
• GitHub Repository: https://github.com/langgenius/dify
• Releases: https://github.com/langgenius/dify/releases