agentsope/agentsop-dify
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.
npx skills add https://github.com/agentsope/SkillAlchemy --skill agentsop-dify> 框架定位: "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]
> Dify 的核心价值是 "把 LLM 应用工程的脚手架打平"——auth、API、UI、向量库、模型 provider、日志、版本——而不是替代 LLM 编排框架本身的表达力。
判断公式:
[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]
| 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]
| 类别 | 节点 | 用途 |
|---|---|---|
| 基础 | 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 Operator, Document Extractor | 处理结构化数据 |
> "Dify's canvas includes LLM calls, knowledge retrieval, conditionals, HTTP requests, code nodes (Python/Node), Jinja transforms, iterators/loops, and aggregators." [legacy-docs.dify.ai/guides/workflow/node]
v1.0+ 引入插件系统，从 monolith → marketplace。 [dify.ai/blog/introducing-dify-plugins]
| 类型 | 用途 | 何时选它 |
|---|---|---|
| Models | 接入新模型 provider | 内置不支持的模型 |
| Tools | 给 agent / workflow 加能力 | 需要复用的领域工具 (Slack, Notion, 自家 API) |
| Agent Strategies | 自定义 reasoning loop | 想用 ToT / GoT / 自研推理 |
| Extensions | 轻量 HTTP webhook | 简单 API 接入，不需打包 |
| Bundles | 多插件打包 | 整套行业解决方案 |
决策: 一次性 = HTTP Request 节点；可复用 = Tool plugin；逻辑深 = Agent Strategy plugin。
RAG 流程: Ingest → Extract → Clean → Chunk → Embed → Index → Retrieve → Rerank → Augment [docs.dify.ai/en/guides/knowledge-base/readme]
三种构建方式:
向量库支持: 13+ (Qdrant 默认推荐, Weaviate, Milvus, Pinecone, PGVector, TiDB, Chroma…) [deepwiki.com/langgenius/dify-docs/8.3-vector-database-configuration]
检索策略:
> 官方建议: "Workflow/Chatflow are recommended for most use cases. Use the legacy basic types (Chatbot/Agent/Text Generator) only if preferring simplified interfaces over advanced features." [docs.dify.ai/en/use-dify/getting-started/key-concepts]
Cloud (推荐起步):
Self-host (Docker Compose) — 最常用:
git clone https://github.com/langgenius/dify
cd dify/docker
cp .env.example .env
docker compose up -d
关键环境变量:
VECTOR_STORE — 选 Qdrant / Weaviate / Milvus / Pinecone…PLUGIN_DAEMON_TIMEOUT=300 — 插件超时WORKFLOW_MAX_EXECUTION_TIME / HTTP_REQUEST_MAX_READ_TIMEOUT — 长链路必调{{var}} 抽出来——后续会成为 workflow 输入> "Dify provides a comprehensive RAG pipeline handling the full lifecycle from raw file upload through extraction, cleaning, segmentation, embedding, indexing, retrieval, and reranking." [pyshine.com/2026/04/20/Dify-Open-Source-LLM-App-Development-Platform]
构建顺序 (反直觉但重要):
反模式: 一上来就画 30+ 节点的复杂图。先线性跑通，再分支。
# 一个典型 Dify workflow 的 building blocks
inputs: # Start 节点变量 (text / number / file / select)
nodes:
- llm: # 调模型
model: gpt-4-turbo
prompt: "..."
memory: false # workflow 永远是 false
- knowledge_retrieval: # 查知识库
datasets: [kb_id_1, kb_id_2]
mode: hybrid
rerank: bge-rerank
- if_else: # 分支
conditions: [...]
- iteration: # 批处理列表
iterator: {{node.output}}
sub_workflow: [...]
- code: # Python/Node
code: "def main(x): return ..."
- http_request: # 调外部
method: POST
url: "..."
- agent: # 自主决策子节点 (1.9+)
strategy: react / function_calling / custom
tools: [...]
max_iterations: 5
outputs: # End / Answer 节点
{{node_id.var}} 跨节点引用sys.user_id, sys.conversation_id 等症状:
决策树:
节点数 < 20 且分支扁平
→ 留在 Dify, 优化命名 + 加 Note
节点数 20-40, 有可复用子流程
→ 拆 sub-workflow (打包成 Tool 给主流程调用)
节点数 > 40 或 大量 Code 节点
→ 信号: 业务逻辑已超出可视化优势
→ 把核心逻辑改写为 Python 服务, Dify 只做编排前端 + RAG
实操:
反模式: 在 Code 节点里写 200 行 Python——这是 "Dify 已不合适" 的信号。
症状:
判断公式:
| 信号 | 留 Dify | 切代码 |
|---|---|---|
| 团队非 100% 工程师 | ✅ | ❌ |
| 需要快速 UI / API / 认证 | ✅ | ❌ (得自己搭) |
| pause-and-wait | ❌ | ✅ (LangGraph 原生) |
| QPS > 10 / pod | ❌ | ✅ |
| 复杂状态 + 回滚 | ❌ | ✅ |
| RAG + 简单编排 | ✅ | — |
混合方案 (推荐): Dify 做前端 / RAG / 用户管理 / 监控；核心 agent 逻辑跑在 LangGraph 服务后端，Dify HTTP Request 节点调用。
> "Dify wins when you're building an LLM-powered SaaS, an internal product with multiple teams… Langflow is for teams that need power now and will need more later." [blog.elest.io/dify-vs-langflow-vs-flowise]
症状:
决策矩阵 [architjn.com/blog/dify-cloud-pricing-plans-free-tier-when-to-self-host]:
| 条件 | 选 Cloud | 选 Self-host |
|---|---|---|
| 团队 ≤ 3 人, 用量小 | ✅ ($59-159/mo 比养 DevOps 便宜) | ❌ |
| 合规 / 数据驻留 (金融、医疗) | ❌ | ✅ |
| 用量大 (millions of API calls) | ❌ (订阅成本超过 infra) | ✅ |
| Air-gapped / 内网部署 | ❌ | ✅ |
| 自定义 vector store / 模型 | 部分支持 | ✅ 完全控制 |
| 不想管 backup / scaling | ✅ | ❌ |
实操要点:
症状:
决策:
| 场景 | 用 Dify 内建 Knowledge | 用 External Knowledge |
|---|---|---|
| 单个 app 单个数据集 | ✅ 一键搞定 | ❌ over-kill |
| 多 app 共享同一份 KB | ✅ Dify KB 可被多 app 引用 | — |
| 极致 chunking / 实验性 retrieval | ❌ Dify 抽象有限 | ✅ |
| 已有自建 RAG 服务 | ❌ | ✅ Dify HTTP/External KB 接入 |
| 数据量 > 100M chunks | ❌ Dify 有 memory leak 风险 [memo.d.foundation/breakdown/dify] | ✅ |
| 需要 KG-RAG / hybrid + late interaction | ❌ | ✅ 或换 RAGFlow |
混合: Dify Knowledge 管常规文档；External Knowledge API 接你的自有 RAG 服务做长尾。
症状: 同一个需求，三种实现方式纠结。
决策原则 [zediot.com/blog/dify-difference-between-agent-and-workflow], [dify.ai/blog/dify-agent-node-introduction-when-workflows-learn-autonomous-reasoning]:
任务路径可预测、调试性优先
→ 显式 Workflow (写死分支)
任务路径不可预测、需 LLM 选工具
→ Workflow + Agent Node (1.9+)
[推荐!! 比纯 Agent app 更可控, 既享受自主性又有 workflow 外壳]
纯对话 + 工具调用、不需要复杂编排
→ Agent app (legacy)
混合: 主流程显式, 局部不确定路径
→ Workflow 主图 + 不确定段塞 Agent Node
> "The best systems combine both — workflows as orchestrators that delegate reasoning tasks to agents. This hybrid model provides both predictability and intelligence." [zediot.com/blog/dify-difference-between-agent-and-workflow]
反模式:
| 反模式 | 症状 | 修法 |
|---|---|---|
| 30+ 节点单图 | 卡顿 + 难调 [issue #28245] | 拆 sub-workflow / Tool |
| Code 节点写业务核心 | Code 节点 200+ 行 Python | 抽到外部微服务, Dify 用 HTTP 调用 |
| 不上 Knowledge Pipeline | 文档质量飘忽 | 用 1.9+ 的 pipeline 自定义 ingest |
| 没接 LLMOps | 上线后看不见 bad case | 接 Langfuse / Phoenix |
| DSL 不入 git | 改飞了无法回滚 | 导出 DSL → git, 用 dify-dsl-exporter 批量化 [github.com/linhai0872/dify-dsl-exporter] |
| legacy Chatbot/Agent app 长期演进 | 无法表达分支 / 后期被迫迁移 | 直接上 Chatflow / Workflow |
| workspace 共用 API key | 不同 app 计费混乱 | 已知限制, 暂用多 workspace 规避 |
| 不做 retrieval testing | RAG 召回质量差还不自知 | 上传后立刻用真实 query 在 Retrieval Testing 里跑 |
| stream 长任务 > 120s 不调超时 | Agent node 突然断开 [issue #27053] | 调 WORKFLOW_MAX_EXECUTION_TIME + 反代超时 |
PLUGIN_DAEMON_TIMEOUT| 框架 | 抽象层 | 上手 | 天花板 | 选它的硬触发 |
|---|---|---|---|---|
| Dify | 平台 (UI+API+RAG+Auth) | 几小时 | 中等 (DB-bound, 单图复杂度) | 全栈 + 多角色协作 + 快速上线 |
| Flowise | 节点编辑器 (薄层) | 几小时 | 低 (chatbot+RAG 为主) | 1GB RAM 最小部署、纯 chatbot |
| LangFlow | LangChain 可视化包 | 半天 | 高 (可导出代码) | 已用 LangChain，想加 UI |
| Coze (扣子) | 字节托管平台 | 小时 | 中等 (国内生态) | 国内市场 / 飞书集成 / 不要 self-host |
| RAGFlow | 专精 RAG 引擎 | 半天 | RAG 维度极高 | 文档解析 + KG-RAG 是核心 |
| n8n | 通用 workflow | 半天 | LLM 是 plugin | 400+ 非 AI 集成 + AI 是辅助 |
| LangGraph | 代码框架 | 几天 | 极高 | 需要状态机 / 中断 / 时间旅行 |
| LlamaIndex | RAG 框架 | 几天 | 极高 (数据侧) | RAG 是 P0 + 工程团队 |
| CrewAI | 多 agent 代码 | 半天 | 中 (角色编排) | 2-5 个角色协作 pipeline |
参考: [blog.elest.io/dify-vs-langflow-vs-flowise], [jimmysong.io/blog/open-source-ai-agent-workflow-comparison], [toolhalla.ai/blog/dify-vs-flowise-vs-langflow-2026]
此时: Dify 退到 "前端 + 监控 + RAG 仓库"，核心逻辑切到 LangGraph / 自研代码服务。
# 一个 "知识库问答 + 工具调用" 的最小 chatflow 骨架
app:
name: support-copilot
mode: advanced-chat # = chatflow
graph:
nodes:
- start: { variables: [{name: query, type: text}] }
- knowledge_retrieval:
dataset_ids: [kb_docs]
retrieval_mode: hybrid
top_k: 5
rerank_model: bge-reranker-v2
- llm:
model: gpt-4-turbo
prompt:
- role: system
content: "You are a support agent. Use the context to answer."
- role: user
content: "Context: {{knowledge_retrieval.result}}\n\nQ: {{start.query}}"
memory: { enabled: true, window: 10 } # chatflow 才有
- answer: { stream: true, content: "{{llm.text}}" }
features:
- annotation_reply: true
- moderation: openai-moderation
- conversation_variables: [user_tier]
Take agentsope/agentsop-dify from the repository into ~/.claude/skills for personal
use, or into .claude/skills inside a project.
The agent identifies a skill by the name field in its header. Two skills with the
same name cannot sit side by side — one of them will be ignored.