不懂代码也能做 Agent：Dify 从建库到上线全流程

很多教程教你拖几个节点就说”完成了”，但拖完的流程往往一问就露馅。这篇文章按真实交付顺序走一遍：先想清楚 Agent 要回答什么，再建知识库，再串流程，最后做验收。

第一步：先把问题列出来，而不是先打开 Dify

在空白画布前最容易犯的错是”先搭结构”。请先做这件朴素的事：收集 30 个真实用户问题，写在表格里，标上”能直接回答 / 需要查资料 / 需要查系统 / 需要转人工”。这一个动作决定了后面 80% 的设计。

以电商售后 Agent 为例，问题会自然分堆：

• 直接回答：运费规则、发货时间 → 知识库
• 查资料：某型号保修条款 → 知识库 + 文件
• 查系统：我的订单到哪了 → 必须调 API（HTTP 请求节点）
• 转人工：投诉、退款争议 → 条件分支 + 人工节点

分堆之后你会发现，很多”看起来要 Agent”的需求其实只需要一个检索问答，不要为了用工具而用工具。

第二步：建知识库，切块参数别用默认值

Dify 的”通用分段”默认按字符切，中文场景下很容易把一句话切成两半。建议：

• 分段标识符：用 \n\n（空行）而不是标点符号。文档结构（标题、段落）通常比句子更有语义。
• 最大分段长度：500 左右。太短丢上下文，太长召回不准。
• 分段重叠：50～80，防止跨段的定义被截断。
• 索引方式：混合检索（向量 + 关键词）。纯向量在型号、订单号、专有名词上经常失效，关键词检索能兜住。
• Rerank 模型：一定要开。它能把 top-20 里真正相关的那几条顶上来，效果差异非常明显。

一个实用技巧：在每段开头拼上文档标题。Dify 有”父文档元数据”相关设置，但更稳的做法是在上传前把标题写进正文第一行，检索时这段就自带身份。

第三步：串工作流，把”变量”想清楚

工作流里出问题最多的地方是变量类型对不上。几个硬规则：

1. 开始节点只放真正需要用户填的东西。用户 ID、渠道这些从会话变量或请求头拿。
2. 知识库检索节点输出是数组，直接塞进 LLM 节点的”上下文”没问题，但如果要自己拼 prompt，需要用模板语法把它 join 起来。
3. 条件分支判断字符串，先判空再比较。空值参与比较是分支走错的头号原因。
4. HTTP 请求节点必须设超时和失败分支。没有失败分支，接口一抖整个 Agent 就沉默。

一个最小可用的流程结构：

开始 → 意图分类（LLM）→ 条件分支
  ├─ 规则类问题 → 知识库检索 → LLM 生成（带引用）
  ├─ 订单查询   → HTTP 查订单 → LLM 组织语言
  └─ 其他       → 转人工

意图分类这一步不要省。让一个 LLM 节点先做三分类，比让主 LLM”自己看着办”稳定得多，而且分类结果可以直接写进日志用于分析。

第四步：提示词里必须写死的三件事

• 无答案时的行为：明确写”如果检索内容中没有答案，回复『这个问题我需要帮你转接人工』，不要推测”。不写这句，Agent 一定会编。
• 引用格式：要求它标注来自哪份文档，方便用户核对，也方便你定位知识库缺口。
• 语气与长度：给个正面例子和反面例子各一句，比写十行形容词有效。

第五步：验收，别看感觉看数据

上线前跑一遍你第一步收集的 30 个问题，记录三项：

检查项	通过标准
命中正确知识	80% 以上
无编造	抽 10 条逐句核对，0 条编造
分支正确	100%（分错就是逻辑 bug）

不通过的题目按”知识库缺内容 / 切块不对 / 提示词不到位 / 流程分支错”归因，改完重跑。这一轮通常会花掉整个项目一半时间，但它决定上线后你会不会被骂。

上线之后

留两个观测点：未命中问题清单（用户问了但库里没有的）和转人工率。前者每周补进知识库，后者突然升高往往意味着某次知识库更新把内容改坏了。Dify 的日志页能直接看到对话记录，按天抽查十条，比任何仪表盘都真实。

低代码工具降低了门槛，但没有降低工程要求。区别只在于：以前你写代码去处理边角情况，现在你在节点和提示词里处理。