我重新看了一遍Dify，决定把RuyiDify做成一门实战课

OK，OK，大家好，欢迎大家来到大鹏 AI 教育，我是张大鹏。

这几天我做了一件事：重新把 Dify 看了一遍。

不是那种“打开官网，看几张截图，读一遍功能介绍”的看法。我是把 GitHub 上的 RuyiDify 仓库拉下来，真的去看它的目录、看它的前后端分层、看它把 Agent、RAG、Workflow、模型管理和部署这些东西放在了什么位置。

看完以后，我心里有一个很明确的判断：

这件事可以做成一门课。

而且不是那种“教你点几个按钮搭一个应用”的工具课，而是一门真正围绕智能体工程交付展开的实战课。

我这次重新看 Dify，脑子里其实一直有三个问题：

• 🧭它能不能作为主线项目：不是做一两个小案例，而是撑起一门完整课程。
• 🛠️它有没有真实工程复杂度：能不能讲清前端、后端、Agent、RAG、部署这些真实问题。
• 📚它能不能沉淀成长期资产：课程、实战仓库、模板、交付方案，能不能顺着一条线长出来。

我为什么突然重新看 Dify

这几年我做 AI 课程，有一个感受越来越强烈。

很多人学 AI，最开始都很兴奋。

• 🤖 今天搭一个聊天机器人。
• 📚 明天接一个知识库。
• 🔁 后天试一下工作流。
• ✅ 每一步看起来都有结果，界面也能跑，回答也能出来。

但再往后走，就卡住了。

卡在哪里？

卡在“我会用”，但“我不知道它里面怎么运转”。

这些问题只靠点界面是解决不了的：

• 🧩知识库问答：为什么有时候答得准，有时候又一本正经地胡说？
• 🧰Agent 工具调用：为什么有时候能调用工具，有时候就停在原地？
• 🧪工作流节点：为什么 Demo 里很顺，一到真实资料就各种边界问题？
• 🧯线上交付：为什么本机能跑，换一台机器就开始报错？

所以我一直想找一个项目，把“会用 AI 工具”和“会交付 AI 系统”之间这段路讲清楚。

这就是我重新看 Dify 的原因。

我打开 RuyiDify 时，先看的不是功能

我没有先去看它能不能搭一个漂亮应用。

我先看的，是项目骨架。

RuyiDify 仓库一打开，我看到的是一个完整的大项目，而不是一个薄薄的 Demo。

我先看的是这些关键目录：

• 🧠api：后端 API。项目说明里写得很清楚，后端是 Python Flask 应用，而且按领域驱动和清晰架构来组织。
• 🖥️web：前端 Web。Next.js、TypeScript、React，不是几页简单表单。
• 🧑‍💻dify-agent：智能体后端服务，专门处理 agent 的管理和执行。
• 🐳docker：容器化部署配置，说明这个项目不是只准备在开发机上玩。
• 🧰cli：命令行相关能力，后续很适合做自动化和工程化延伸。
• 📦packages、sdks、e2e、docs：配套包、SDK、端到端测试和文档，说明它有完整生态的影子。

这些目录摆在一起，我马上就知道，这不是一个适合“十分钟速成”的项目。

它更适合做长期拆解。

也正因为这样，它适合做课。

真正打动我的，是它的工程味

我看一个开源项目适不适合做教学，通常不只看它火不火。

火当然重要，但火不代表适合教。

我一般会从这几个角度判断：

• 🔥火不火：这决定学员有没有兴趣，但不是唯一标准。
• 🧱结构稳不稳：结构太散，讲起来就容易变成资料堆砌。
• 🧪深度够不够：工程深度不够，就只能做小实验。
• 🧭路线清不清：如果不能拆成阶段和章节，再好的项目也不好教。

Dify 打动我的地方，是它已经有很明显的工程味。

比如后端api/AGENTS.md里有一条要求：改后端代码之前，要读周围的 docstring 和注释，因为这些说明本身就是规格的一部分。

这句话我很喜欢。

因为我见过太多初学者改项目，上来就是搜关键词，找到一个函数，改两行，跑一下能过，就觉得完成了。

在真实系统里，这种改法很危险。

一个接口背后可能连着租户隔离、数据库事务、异步任务、外部存储、模型调用和日志。你只看眼前两行代码，很容易把系统改坏。

Dify 的后端规则里，有几类边界特别值得讲：

• 🧾控制器边界：控制器负责解析输入、调用服务、返回响应，不应该塞业务逻辑。
• 🧩服务层边界：服务层协调仓储、Provider 和后台任务，不能散成一堆临时调用。
• 🏢租户边界：查询和写入都要注意tenant_id，这是真实 SaaS 系统绕不开的问题。
• ⏱️异步边界：Celery 和 Redis 不是装饰品，很多 AI 任务本来就不是同步小接口能扛住的。
• ⚙️配置边界：配置要走统一入口，不能想起一个环境变量就随手读一个。

它不是在教你写一个接口，而是在提醒你：AI 应用一旦进入产品级，就不是“调一下大模型”这么简单。

这正是我想讲给学员听的东西。

前端也不是“把页面画出来”这么简单

然后我去看web/AGENTS.md。

前端这边同样让我确认了一件事：Dify 不是一个只有页面的项目，它是一个真正的产品。

前端规则里，我看到的是另一种复杂度：

• 🌐文案国际化：用户可见文案要走 i18n，不是随手写死在页面里。
• 🧱组件体系：overlay 组件要使用统一的@langgenius/dify-ui。
• 🎨设计资产：图标、设计 token、圆角映射都有统一约定。
• 🧠状态管理：本地状态、Jotai、feature store、本地持久化，各有各的位置。

我特别注意到 Agent V2 那一段。

它要求 Agent V2 和旧的 workflow Agent 分开，不要混用旧数据形态；后端调用要走生成的 contracts 和consoleQuery、consoleClient；不要手写 REST helper，不要手写 API 类型。

这背后其实是一个很典型的真实产品问题：

• 🧬旧能力还在：legacy workflow Agent 不能说删就删。
• 🌱新能力要长出来：Agent V2 要有自己的目录、契约和状态模型。
• 🔌中间不能乱接：不能为了快，随手写一个 REST helper 绕过去。
• 🧯以后还要维护：今天乱接一下，后面课程、二开和升级都会付利息。

这不是写一个 React 组件就能解决的问题。

如果我把 RuyiDify 做成课，我一定不会只讲“这个按钮怎么写”。我会讲为什么这个状态应该归这个模块，为什么这个接口不能随手手写，为什么 Agent V2 不能和旧 Agent 混在一起。

这些判断，才是工程能力。

我最想拆的，是 dify-agent

看完整体结构以后，我对dify-agent这个目录很感兴趣。

现在大家都在说智能体。

但很多时候，智能体被讲得太玄了：会规划、会调用工具、会自己完成任务。

我更关心真实执行链路。

我最想拆的问题有这些：

• 🚀一次 agent run 怎么开始：用户点下去以后，后端到底创建了什么？
• 📡事件怎么返回前端：流式输出、状态变化、错误事件怎么传回来？
• 🧰工具失败怎么办：工具调用不是永远成功，失败路径必须讲清楚。
• 📚知识库怎么参与：知识库、模型、工具和用户输入到底怎么组合？
• 🧩前后端怎么对齐：前端配置的 Agent V2，最后怎么变成后端的一次执行？

这些问题不拆源码，是讲不扎实的。

所以 RuyiDify 对我来说，不只是一个 Dify 二开仓库。它更像一个智能体工程实验台。

我可以带大家从界面走到后端，从配置走到执行，从“我点了运行”走到“系统到底跑了什么”。

这条路，才是我真正想教的。

我也得承认，现在只是起点

这里我也要讲实话。

我看了课程资料目录：

我新建了一套课程资料骨架，名字叫“如意 Dify 智能体开发实战”。

现在这个目录下面已经有几个文件夹：

• 📘中文版
• 🗂️资料
• ❓常见问题
• 🧯错误日志

但它还只是骨架。

也就是说，这门新课还没有正式长出章节内容。

这件事不能吹。

但它不是从零开始。

但它不是从零开始，我已经有几类资产可以接上：

• 📚旧课程资料：我之前已经整理过一套“大鹏 Dify 开发 AI 智能体”课程资料，里面有 10 章内容，从大模型到 AI Agent、Dify 开发流程、部署环境、功能应用、工作流节点，到几个具体 Agent 案例和云端知识库。
• 🧪配套实战仓库：我还准备了 DapengDifyCourse 实战仓库，已经按chapter01到chapter10建好结构。
• 🔍真实测试线索：第 10 章写了云端知识库 API 的真实测试脚本路线，用来走通建库、传文档、等待索引、召回测试这一整套流程。
• 🧱新课程骨架：如意 Dify 智能体开发实战目录已经在，但章节还没正式长出来。

所以我现在要做的，不是凭空发明一门课。

我是在已有课程资产、已有实战仓库和现在这个 RuyiDify 源码主线之间，重新拉一条更硬的路线。

我对新旧路线的区分是：

• 🧑‍🏫旧路线：学会用 Dify 做智能体。
• 🧑‍🔧新路线：读懂 Dify，二开 Dify，用 Dify 交付智能体项目。

我不会一上来就改代码

很多人做二开，第一反应是换 Logo、改标题、换颜色。

这些事可以做，但我不想一上来就做。

如果一上来就换皮，很容易给自己一种错觉：好像项目已经变成自己的了。

但真正的二开，不是把名字改掉。

真正的二开，是知道哪里能改，哪里不能乱改；知道需求应该落在前端、后端、agent 执行层，还是只需要改配置；知道怎么跟上游保持关系，而不是改两周以后再也同步不回去。

所以 RuyiDify 的第一阶段，我准备做得慢一点：

• 🔎先读源码：把api、web、dify-agent、docker这些关键层看清楚。
• ▶️先跑通：不靠想象，能运行的地方尽量真实运行。
• 📝先记录：把路径、命令、错误、判断都留下来。
• 🛠️再二开：知道系统边界以后，再开始做品牌化、课程化和功能改造。

这四步听起来笨，但我现在越来越相信，做长期项目，笨办法反而最稳。

这门课最后想训练什么能力

如果你只是想知道 Dify 怎么创建应用，网上已经有很多教程。

但我想做的不是这个。

我想训练的是四层能力。

这四层能力，我准备这样拆：

• 🧑‍💻第一层，会用：你能用 Dify 搭出工作流、知识库和 Agent。
• 🧠第二层，会解释：你能讲清一次提问从前端到后端，再到模型、知识库和结果返回，中间经过了哪些模块。
• 🛠️第三层，会修改：你知道一个需求该改哪里，知道为什么不能随手绕过现有架构。
• 📦第四层，会交付：你能部署、能测试、能写文档、能记录错误日志，能把一个 Demo 变成别人真的能使用的东西。

RuyiDify 这门课，我想训练的就是这四层能力。

为什么我觉得这件事值得做

我做课程这么久，越来越不喜欢纯知识点列表。

知识点当然要有，但如果没有主线项目，学完很容易散。

一个好的主线项目，我觉得至少要满足几件事：

• 🧱有真实复杂度：不是三五个文件就讲完。
• 🧭有清楚边界：能拆成章节，能分阶段推进。
• 🔁能反复复用：课程、博客、实战仓库、模板都能围绕它长出来。
• 🚀能继续交付：学完以后不是只停在课堂里，还能往产品和服务上走。

RuyiDify 正好有这个潜力：

• 🧩底座成熟：背后是 Dify，能讲 Workflow、RAG、Agent、模型管理、部署和二开。
• 📚课程资产已有基础：旁边有我已经整理过的 Dify 课程资料和实战仓库。
• 🛒商业延展明确：后面还能继续接模板市场、行业智能体和企业知识库项目。

它现在还只是起点。

但我愿意从这个起点开始。

接下来，我会把每一步都做成能留下证据的东西：看过哪些文件，跑过哪些命令，踩过哪些坑，改过哪些地方，为什么这么改。

然后再把这些真实记录，整理成一门课。

不是教大家跟着我点界面。

而是带大家一起从 Dify 走到 RuyiDify，从会用智能体，走到会造智能体。