05. 项目结构：从目录看懂 DeerFlow

先别细读源码

看源码前，先看目录。

目录能告诉你这个项目把问题怎么拆。DeerFlow 的目录里已经能看到它不是一个简单 demo，而是把 Agent 工程拆成了多层。

仓库根目录

从根目录看，重点先关注：

README.md
Makefile
config.example.yaml
backend/
web/
docker/
scripts/

• README.md：项目定位和使用入口；
• Makefile：常用开发命令；
• config.example.yaml：配置样例；
• backend/：后端和 Agent harness；
• web/：前端界面；
• docker/：容器化相关文件；
• scripts/：辅助脚本。

Gateway 路由

后端入口相关目录：

backend/app/gateway/routers/

当前能看到类似这些路由：

threads.py
runs.py
thread_runs.py
models.py
skills.py
mcp.py
memory.py
uploads.py
artifacts.py

这说明 API 层已经把 Agent 系统拆成很多资源，而不是只有一个聊天接口。

Harness 主体

最值得读的是：

backend/packages/harness/deerflow/

里面有：

agents/
community/
config/
guardrails/
mcp/
models/
persistence/
reflection/
runtime/
sandbox/
skills/
subagents/
tools/
tracing/
uploads/
utils/

这就是后面教程的主要地图。

你应该先看哪些目录

如果你想看执行链路：

runtime/
agents/
tools/
sandbox/

如果你想看二次开发：

tools/
skills/
subagents/
mcp/

如果你想看排错：

tracing/
runtime/events/
runtime/runs/

如果你想看文件产物：

uploads/
sandbox/
artifacts 相关路由

不建议的读法

不要从 utils/ 开始。

也不要随机打开某个 Agent 文件就开始读。没有执行链路时，很容易把每个文件都看成重点。

更好的顺序是：

Gateway 路由
|
runtime
|
Agent
|
tools / skills / subagents
|
sandbox / mcp / tracing

这一篇你要记住

DeerFlow 的目录已经把学习路线写出来了。

你不是要一次读完所有源码，而是要知道：遇到模型、工具、技能、子 Agent、沙盒、外部服务、追踪这些问题时，应该先去哪个目录。

下一篇追一次任务的完整执行链路。