dify-chatflow-builder

---
name: dify-chatflow-builder
description: 用 Dify Chatflow / Workflow 搭建生产级多轮对话应用的方法与踩坑库，可配合对话逐步指导搭建。当用户说要搭一个 Dify 对话流、工作流或智能体，或需要设计状态机与多场景分诊、配置节点与变量、编写节点级提示词、排查运行报错、接入 HTTP / Swagger / MCP 接口与飞书、实现富媒体组件返回、优化响应延迟，或在对话流、工作流、Agent 三种形态之间选型时使用。
---

# Dify 对话流与工作流搭建

这份文档来自一套真实交付过的 Dify 模板：销售陪练、医院导诊、前台接待、机场航班查询、数字人大屏。所有内容都经过线上验证，踩过的坑按原样保留。

## 开工前先定三件事

**一、形态选型**
- 需要多轮、有状态、要闭环 → 对话流（Chatflow）
- 单次输入输出、被别的应用调用 → 工作流（Workflow）
- 需要模型自主决定调用哪些工具、路径不固定 → Agent 模式

判断标准详见 `references/architecture.md`。选错形态会导致后面所有配置白做。

**二、状态存哪里**
凡是跨轮次要保持的东西（当前模式、已收集信息、任务阶段），一律放**会话变量**。没有会话变量，每一轮都是全新的开始，必然串线。

**三、有没有外部系统**
要对接业务系统 → 走 `references/integration.md`
只有内部知识 → 走 `references/knowledge.md`
两者都没有 → 纯 Prompt 编排即可

## 五条核心原则

**1. 先定状态，再画线**
在画任何连线之前，先把会话变量和状态迁移图定下来。状态机的入口是开始节点后的第一个条件分支，出口是变量重置。没有状态机就开始拖节点，最后一定会遇到"进入某个场景后还在走别的分支"。

**2. 变量三处对齐**
每个变量都要确认：在哪里定义、在哪里赋值、在哪里被引用。三处任何一处缺失，下游就选不到这个变量，报错信息通常不会告诉你原因。

**3. 提示词按节点拆**
不要把一个完整角色人设复制到每个 LLM 节点。一个节点只做一件事，只保留这件事相关的人设片段。全量人设塞进去会导致模型行为互相冲突，表现为"答非所问"或"反复反问"。

**4. 接口走三段式**
外部接口一律拆成：参数提取（LLM）→ 请求（HTTP/工具节点）→ 数据清洗（代码执行）→ 播报（LLM）。让 LLM 直接吃原始返回是失控的起点。

**5. 先跑通主链路，再加分支**
先做一条最短的可用链路，验证变量、接口、输出都通了，再往上加场景。一次性画完四条分支，出问题时无法定位是哪一层坏了。

## 按任务查文档

| 你在做什么 | 读这个 |
|---|---|
| 选形态、设计状态机、多场景分诊 | `references/architecture.md` |
| 变量选不到、赋值不生效、作用域混乱 | `references/variables.md` |
| 某个节点怎么配、条件分支不生效 | `references/nodes.md` |
| 模型答非所问、反复反问、提取出 UNKNOWN | `references/prompt-design.md` |
| 知识库召不回来、检索结果不对 | `references/knowledge.md` |
| 分类器报错、意图分错、延迟高 | `references/intent-router.md` |
| 调接口报 401/403/404/405、数据清洗、飞书、MCP | `references/integration.md` |
| 图片/链接/地图/表单/文档前端不显示 | `references/rich-media.md` |
| 响应慢、数字人播报中断、等待体验差 | `references/latency-ux.md` |
| 私有化部署报错、DSL 跨环境异常 | `references/deploy-ops.md` |
| 节点命名、画布注释、交付与汇报 | `references/delivery.md` |
| 遇到具体报错，先查这里 | `references/errors.md` |

## 十个最高频的坑（速查）

1. **进入场景后还在走别的分支** → 没有用会话变量做状态门控，或退出时没重置变量
2. **条件分支里选不到上游变量** → 上游节点的输出变量没登记
3. **变量赋值选了"设置"却填不进变量** → 设置模式只接受纯文本，需要变量必须用覆盖模式或模板转换节点
4. **模型输出里出现 `[SUCCESS]` `[END]` 这类标记** → 标记没有被截断，直接透传给了前端
5. **LLM 提取字段全是 UNKNOWN / 未提供** → 上下文没清空、USER 输入没接、提示词缺范例
6. **知识库召回不到** → 用户口语和文档用词不一致，需要埋词或加问题优化节点
7. **接口 `data` 传进去多了一个空格** → 变量引用被写成了纯文本，检查引号与变量块
8. **403 / IP 白名单加了还不生效** → 出口 IP 与实际不符，或触发 WAF 特征拦截
9. **富媒体在前端显示成一段代码** → Agent 模式多过了一轮模型，格式被改写，改用对话流
10. **私有化环境本地上传正常、粘贴链接报错** → SSRF 拦截，需要在 `.env` 或 ssrf_proxy 加白名单

完整 152 条在 `references/errors.md`。先读索引定位分册，再按报错原文检索，不要整本通读。

## 交付规范

给团队或客户交付时，画布本身就是文档。执行 `references/delivery.md` 的规范：

- 节点命名统一为「节点类型 + 职责」，不要留 `LLM 3`、`代码执行 2`
- 画布四角放注释卡片：欢迎说明、参数解析、接口调用、话术播报
- 每个节点填一句短描述
- 交付物清单：交互链路图、协议定义、字段说明、验收清单

## 文档使用方式

- `SKILL.md` 是入口，读完就能判断该去哪一份 reference，不要一上来全读
- 每份 reference 内部按主题分节，只读相关小节
- `references/errors.md` 是索引页，真正条目在 `references/errors/` 下的 7 个分册
- `examples/minimal-chatflow.md` 是从零搭建的最小骨架，适合先跑通再加分支

## 边界

- 不负责 Dify 平台本身的安装部署，只处理应用层编排
- 不代替业务方确认接口契约，接口字段以对方文档为准
- 涉及真实用户数据的场景，提醒做脱敏和权限校验

• .gitignore 1 KB
• LICENSE 1 KB
• README.md 4 KB
• SKILL.md 6 KB