/agentsop-dify

name: agentsop-dify
version: 1.0.0
description: SOP for building LLM applications on Dify — visual workflow + chatflow + agent + RAG knowledge base + plugin marketplace + observability, self-hostable. Use when shipping LLM apps fast with a "no-code to pro-code" gradient, especially when non-engineers need to co-author the flow.
domain: llm-application-platform
framework: Dify
framework_version: ">=1.0, current 1.14.x (May 2026)"
trigger_keywords:
  - "Dify workflow"
  - "Dify chatflow"
  - "Dify agent"
  - "Dify knowledge base"
  - "visual LLM workflow"
  - "self-host LLM platform"
  - "low-code AI app"
  - "Dify plugin"
  - "Dify DSL"
  - "LLMOps platform"
when_to_use:
  - "shipping an internal LLM app (Q&A bot, doc-grounded copilot, content pipeline) in days not weeks"
  - "team has a mix of PMs / ops / engineers and needs a shared visual artifact (chatflow / workflow canvas)"
  - "need RAG + tools + monitoring + auth + web UI + API in one box (vs. assembling from libraries)"
  - "enterprise asks for self-hostable, on-prem, air-gapped LLM platform with multi-tenant workspaces"
  - "prototype-to-production gradient: start visual, drop into Code/Python nodes when needed"
when_not_to_use:
  - "high-throughput production (>10 QPS per pod) — Dify hits a known per-node DB-query bottleneck [memo.d.foundation/breakdown/dify]"
  - "sub-second latency / real-time streaming pipelines — workflow engine overhead dominates"
  - "human-in-the-loop with pause-and-wait-for-user semantics — not supported as of v1.14 [github.com/langgenius/dify/issues/21455]"
  - "model training / fine-tuning workflows — Dify is inference + orchestration only"
  - "your team is 100% engineers already shipping LangChain/LangGraph in code — Dify's visual layer is overhead, not leverage"
  - "deeply custom retrieval (graph RAG, late interaction, hand-tuned chunking) — RAGFlow or a raw stack wins [sider.ai/blog/ai-tools/dify-vs-ragflow]"

Dify SOP — LLM Application Platform, Visual-First with Code Escape Hatches

> 框架定位: "An open-source platform for building agentic workflows" — visual workflow + RAG + agent + monitoring + deploy in one box, self-hostable. [docs.dify.ai/en/introduction], [github.com/langgenius/dify]

> "Dify is the only tool that gives you data ingestion, RAG, an API, and a polished, shareable web UI in one click." [learnwithparam.com/blog/batteries-included-rag-platforms-dify-ragflow-onyx]

---

1. 何时激活 (When to Activate)

1.1 直接信号 (Direct triggers)

• 用户说 "我需要个 LLM 应用 / 客服 bot / 知识库问答 / 文档处理流"，且**希望几天内交付**
• 用户说 "我们在用 Dify / 自己部署了 Dify / 想自己 host LLM 平台"
• 团队**有非工程师参与**编排逻辑（PM / 运营 / 业务方画 chatflow）
• 需要**一站式**：模型管理 + RAG + 工具调用 + 用户访问 + API + 监控 + 评估
• 需要**多租户 / workspace 权限**（典型 SaaS / 企业内多团队场景） [blog.elest.io/dify-vs-langflow-vs-flowise]

1.2 反向信号 (Skip Dify when)

• **高吞吐**: 单 pod ~10 QPS 上限，每个 workflow 节点单独打 DB [memo.d.foundation/breakdown/dify]
• **实时低延迟**: workflow 引擎开销 + 同步 DB 调用，sub-second 场景不适用
• **需要 pause-and-wait-for-user**: 审批流 / 用户多步交互 → Dify workflow 不支持，issue #21455 已关 "not planned"
• **纯工程团队 + 已有 LangChain/LangGraph 投入**: Dify 的可视化层成为负担而非杠杆
• **训练 / 微调 workflow**: Dify 是 inference + orchestration，不碰训练
• **极致 RAG**: 需要 KG-RAG、deep parsing、混合检索调优 → **RAGFlow** 更专 [sider.ai/blog/ai-tools/dify-vs-ragflow]
• **AI 代码已经能写**: 业内已有声音 "既然在 Dify 里也要写 Python，何不直接 Python？" [zhuanlan.zhihu.com/p/1947389040702781389]

1.3 心智门槛 (Mental check)

> Dify 的核心价值是 **"把 LLM 应用工程的脚手架打平"**——auth、API、UI、向量库、模型 provider、日志、版本——而不是替代 LLM 编排框架本身的表达力。

判断公式:

• 如果你的瓶颈是 **"组装周边设施"** → 用 Dify
• 如果你的瓶颈是 **"逻辑表达力 / 状态管理 / 极致性能"** → 用 LangGraph / 直接代码

---

2. 核心心智模型 (Mental Model)

2.1 五层架构 (The 5-layer stack)

[Studio]        ← Visual canvas (workflow / chatflow / agent / chatbot / text-gen)
   ↓ 编排
[Apps]          ← 5 种 app 类型，全部跑在统一 Graph Engine 上
   ↓ 依赖
[Knowledge]     ← RAG pipeline (ingest → chunk → embed → index → retrieve → rerank)
   ↓ + 调用
[Tools/Plugins] ← Marketplace: Models / Tools / Agent Strategies / Extensions / Bundles
   ↓ 观察
[Monitoring]    ← 内建 logs + 外接 LangSmith / Langfuse / Arize Phoenix / Opik

参考: [docs.dify.ai/en/introduction], [dify.ai/blog/dify-plugin-system-design-and-implementation]

2.2 五种 App 类型 — 选哪个？

| App Type | 触发模型 | 记忆 | 编排方式 | 典型场景 | |---|---|---|---|---| | **Chatbot** (legacy) | 多轮对话 | 内置 | 单 prompt + tools | 简单客服、FAQ bot | | **Agent** (legacy) | 多轮对话 | 内置 | ReAct / FC 自主决策 | 自治工具使用、多步推理 | | **Text Generator** (legacy) | 单次调用 | 无 | 单 prompt | 文案生成、翻译 | | **Workflow** | 单次调用 / 批处理 | **无** | 可视化 DAG | API 后端、批量任务、ETL | | **Chatflow** | 每轮对话触发整图 | **有** (conversation vars) | 可视化 DAG + 对话状态 | 复杂对话流、guided dialogue |

**核心决策树**:

有对话上下文需求？
├─ 是 ─→ Chatflow (复杂逻辑) 或 Chatbot/Agent (简单)
└─ 否 ─→ Workflow (复杂逻辑) 或 Text Generator (单 prompt)

需要 LLM 自主选择工具 / 多步推理？
├─ 是 ─→ Agent app  或  Workflow + Agent Node (推荐, 1.9+)
└─ 否 ─→ Workflow / Chatflow + 显式节点编排

参考: [docs.dify.ai/en/use-dify/getting-started/key-concepts], [hellodify.com/en/docs/workflow/workflow-chatflow-difference], [zediot.com/blog/dify-difference-between-agent-and-workflow]

> "Workflow behaves more like a script… each Workflow run is a completely fresh start. Chatflow… is a robot that can interact with users in a loop." [hellodify.com/en/docs/workflow/workflow-chatflow-difference]

2.3 Graph Engine = "graphon"

• 自研 DAG 执行引擎，所有 app 类型底层一套
• v1.9+ 重写为 **queue-based scheduling**: 任务统一入队、调度器管依赖与并行 [github.com/langgenius/dify/discussions/26138]
• 节点有标准签名：输入变量 → 处理 → 输出变量
• 支持：partial run、step debugging、stream-stitch across nodes、pause/terminate commands

2.4 节点目录 (Node taxonomy)

| 类别 | 节点 | 用途 | |---|---|---| | **基础** | Start, End, Answer | 入口 / 出口 | | **LLM** | LLM, Question Classifier, Parameter Extractor | 调模型 | | **RAG** | Knowledge Retrieval | 查知识库 | | **逻辑** | IF/ELSE, Iteration, Loop, Variable Assigner, Variable Aggregator | 控制流 | | **代码** | Code (Python/Node.js), Template (Jinja2) | 自定义逻辑 | | **外部** | HTTP Request, Tool, Agent Node | 调外部 / 子 agent | | **数据** | List Ope