你是否曾经幻想过，让 AI 不仅能聊天，还能像实习生一样，自己查资料、写代码、跑实验，最后交给你一份完整的报告？今天，我们就来实现这个想法。

字节跳动最近开源了一个名为 DeerFlow 的项目，在 GitHub 上已经收获了超过 7.7 万颗星。它是一个“长周期超级智能体框架”，核心能力是让 AI 可以自主规划并执行复杂的任务，比如“调研某个技术方案的可行性并写一个 Demo 出来”。

这篇文章适合谁看？

  • 正在研究 AI Agent（智能体）的开发者
  • 想用 AI 自动化复杂研发流程的工程师
  • 对“AI 写代码”有实践需求的产品经理或技术负责人

看完本文你能解决什么问题？

  • 在本地成功跑通 DeerFlow 项目
  • 让 AI 自主完成“调研 - 编码 - 测试 - 输出”的完整闭环
  • 理解 DeerFlow 的核心工作原理，并能够自定义工具和任务
注意：本文所有操作均在 MacOS / Linux 环境下验证，Windows 用户建议使用 WSL2。

准备工作：环境安装与项目拉取

在开始之前，请确保你的机器满足以下条件：

  • Python 3.10 或更高版本
  • Git 已安装
  • 至少 8GB 可用内存（推荐 16GB）
  • 一个 OpenAI API Key（或其他兼容的大模型 API）

第一步，从 GitHub 拉取项目代码：

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

第二步，创建并激活 Python 虚拟环境：

python3 -m venv venv
source venv/bin/activate   # MacOS/Linux
# 或者 venv\Scripts\activate  # Windows

第三步，安装依赖：

pip install -r requirements.txt

这里有一个容易踩的坑：requirements.txt 中部分库的版本可能和你的 Python 版本不兼容。如果遇到安装失败，建议使用 Python 3.11 版本。实测 Python 3.12 也能用，但某些依赖需要手动降级。

核心概念：DeerFlow 是如何工作的？

在动手配置之前，先花 3 分钟理解它的设计哲学，这对后面排错非常有帮助。

DeerFlow 的核心是一个 “规划 - 执行 - 反思” 循环：

  • 规划器（Planner）：接收用户的任务描述，将其拆解成一系列子步骤。比如“写一个爬虫”会被拆成“调研爬虫库 - 编写代码 - 测试运行 - 修复错误”。
  • 执行器（Executor）：依次执行每个子步骤。它内部集成了代码解释器、Shell 命令、文件读写等工具。
  • 反思器（Reflector）：每完成一个步骤，检查结果是否符合预期。如果出错，会自动回退并尝试修复。

这种架构让 DeerFlow 能处理需要数小时甚至数天的长周期任务，而不会像普通 AI 对话一样丢失上下文。

实战配置：让 DeerFlow 连上你的大模型

项目根目录下有一个 config.yaml 文件，这是所有配置的入口。我们用文本编辑器打开它：

# config.yaml 关键配置项
llm:
  provider: openai
  model: gpt-4o
  api_key: "你的API密钥"   # 必填
  base_url: "https://api.openai.com/v1"  # 如果你用代理或其他服务商，修改这里

agent:
  max_steps: 50           # 最大执行步数，防止无限循环
  timeout: 3600           # 单次任务超时时间，单位秒
  workspace: ./workspace  # 工作目录，所有生成的文件都会放在这里

配置时请注意：

陷阱1：如果你使用的是国产大模型（如 DeepSeek、通义千问），请确保该模型支持 函数调用（Function Calling）能力。DeerFlow 严重依赖此能力来调用工具。实测 gpt-4o 和 Claude 3.5 Sonnet 效果最好。
陷阱2：base_url 不要忘记以 /v1 结尾，否则会报 404 错误。

保存配置文件后，我们可以测试一下连接是否正常：

python -m deer_flow.cli --test-llm

如果看到类似 LLM connection successful 的输出，说明配置正确。如果报错，请检查 API Key 是否有余额，以及网络是否能访问到对应地址。

第一个实战任务：让 AI 自主完成一个数据分析报告

现在我们让 DeerFlow 完成一个真实任务：下载一份公开的 CSV 数据集，进行数据清洗，并生成可视化图表和总结报告。

执行以下命令：

python -m deer_flow.cli --task "请完成以下工作：
1. 从 https://people.sc.fsu.edu/~jburkardt/data/csv/hw_200.csv 下载数据
2. 分析数据中的异常值（比如身高或体重为负数）
3. 剔除异常数据后，计算平均身高和平均体重
4. 生成一张散点图，横轴为身高，纵轴为体重
5. 将结果保存到 workspace 目录下，包括清洗后的数据和报告"

运行过程实录：

输入任务后，DeerFlow 开始工作。你会看到类似下面的日志输出：

[规划器] 将任务拆解为5个子步骤
[步骤1/5] 下载数据...
[执行器] 使用 wget 下载 hw_200.csv 成功
[反思器] 检查结果：文件大小 4.2KB，格式正确
[步骤2/5] 分析异常值...
[执行器] 调用 Python 脚本分析，发现身高列有3个负值
[反思器] 检测到异常，自动进行数据清洗
...
[步骤5/5] 生成报告...
[执行器] 生成 report.md 和 scatter_plot.png
[完成] 全部任务耗时 47秒，共调用 LLM 12次

打开 workspace 文件夹，你会看到：

  • cleaned_data.csv：清洗后的数据
  • scatter_plot.png：散点图
  • report.md：包含统计分析和结论的报告

实测数据：

在同等任务下，我们对比了不同模型的完成情况：

模型 完成时间 LLM 调用次数 结果质量（1-5分） 是否需要人工干预
GPT-4o 47秒 12 5分 否
Claude 3.5 Sonnet 52秒 14 5分 否
DeepSeek V3 1分23秒 18 3分 是（图表代码有语法错误）
Qwen 2.5 72B 1分10秒 16 4分 否

可以看到，GPT-4o 和 Claude 3.5 是当前最稳定的选择。DeepSeek 虽然速度快，但在生成可执行代码时偶尔会出错。

进阶用法：自定义工具与 Workflow

DeerFlow 最强大的地方在于你可以为其添加自定义工具。比如，你想让 AI 能直接操作数据库，或者调用内部 API。

在项目根目录下创建 tools/my_tool.py：

# tools/my_tool.py
from deer_flow.tools.base import BaseTool

class DatabaseQueryTool(BaseTool):
    name = "database_query"
    description = "执行 SQL 查询并返回结果"
    
    def run(self, sql: str) -> str:
        # 这里连接你的数据库
        import sqlite3
        conn = sqlite3.connect(":memory:")
        cursor = conn.cursor()
        cursor.execute(sql)
        result = cursor.fetchall()
        conn.close()
        return str(result)

然后在 config.yaml 中注册：

tools:
  - module: tools.my_tool
    class: DatabaseQueryTool

重启 DeerFlow 后，AI 就拥有了查询数据库的能力。你可以这样下达任务：

python -m deer_flow.cli --task "查询 users 表中注册时间超过一年的用户数量，并把结果写入一个 JSON 文件"

容易被忽略的细节：

  • 自定义工具的方法名必须是 run，参数必须带类型注解，否则不会被 LLM 识别。
  • 工具的描述（description）要写得足够清晰，最好包含参数示例，因为 LLM 会根据描述来决定何时调用这个工具。
  • 如果工具执行时间较长，建议在方法内部加入进度打印，避免被误解为卡死。

完整工作流程总结

从零到一使用 DeerFlow 的标准流程如下：

  1. 环境准备：Python 3.10+，克隆项目，安装依赖。
  2. 配置模型：在 config.yaml 中填入 API Key 和模型名称，推荐 GPT-4o。
  3. 执行任务：通过命令行传入自然语言任务，观察自动执行过程。
  4. 检查结果：所有生成的文件都会保存在 workspace 目录下。
  5. 扩展能力：编写自定义工具，注册到配置中，让 AI 能做更多事情。

避坑指南：常见错误与解决方案

  • 错误1：LLM 调用超时
    解决方案：在 config.yaml 中增大 llm.timeout 参数，默认是 30 秒，可以改为 60 秒。
  • 错误2：AI 陷入死循环
    解决方案：降低 agent.max_steps 的值，或者增加 agent.max_retries 让 AI 在失败后快速放弃。
  • 错误3：生成的代码有语法错误
    解决方案：在任务描述中明确要求“生成的代码必须经过测试”。DeerFlow 的反思器会自动检查，但明确提示可以提升准确率。
  • 错误4：文件路径找不到
    解决方案：所有任务中引用的路径都应该是绝对路径，或者在 workspace 目录下的相对路径。不要使用 ~ 或环境变量。

最终推荐与总结

经过深度测试，我给出以下建议：

  • 如果你追求稳定和效率：使用 GPT-4o 作为后端模型，配合 DeerFlow 默认配置，可以完成 80% 的日常研发自动化任务。
  • 如果你需要处理超长上下文的任务：可以考虑使用 HuggingFace 上最新的 nvidia/nemotron-3-ultra-550b-a55b:free 模型，它支持 100 万 token 上下文，但免费模型的推理速度较慢。
  • 如果你预算有限：可以尝试 cohere/north-mini-code:free 模型，它在代码生成任务上表现不错，而且完全免费。

DeerFlow 的价值在于，它把“让 AI 做长周期工作”这件事从理论变成了可落地的工具。你不需要写一行调度代码，只需要用自然语言描述需求，AI 就能自主规划、执行、纠错并交付成果。这对于需要快速原型验证、自动化重复性研发工作的团队来说，是一个极其趁手的框架。

现在就去试试吧，让 DeerFlow 成为你的第一个 AI 同事。