第 1 章：开篇 —— 为什么 DeerFlow 值得读

本章不急着钻进函数，而是先回答三个问题：DeerFlow 是什么、它解决的难点是什么、阅读它时应该抓住哪条主线。

一句话定义

DeerFlow 2.1 是一个以 LangGraph 为执行内核、以可配置 Harness 为能力层、以 Gateway 为可靠运行时、同时提供 Web/TUI/IM 多入口的全栈超级 Agent 系统。

这个定义里有四个容易混淆的角色：

角色	负责什么	不负责什么
LangGraph	模型—工具循环、状态图、检查点语义	业务 API、前端、沙箱实现
Harness (`deerflow.*`)	Agent 组装、工具、中间件、沙箱、记忆、子代理	HTTP 会话与浏览器 UI
Gateway (`app.*`)	运行准入、SSE、鉴权、线程与运行持久化	Agent 的领域能力实现
Frontend	对话、任务、产物、配置的交互与流状态折叠	Agent 执行和持久化仲裁

因此，把 DeerFlow 简化成“LangGraph 示例”会漏掉真正有价值的部分。模型会调用工具只是起点；生产系统还要回答：同一线程能否并发运行？断线后事件从哪里续？工具写出的文件如何安全交给用户？子代理取消时怎样收尾？摘要以后旧对话是否还能显示？

它的三个身份

1. 可直接运行的 Agent 产品

默认栈有 Web 聊天、文件上传、Artifact 面板、计划/Todo、持久记忆、自定义 Agent、定时任务和多种 IM 渠道。Nginx 将公网入口统一在 :2026，前端和 Gateway 留在内部网络。

2. 可嵌入的 Agent Harness

backend/packages/harness 是单独的 Python 包 deerflow-harness。它暴露 create_deerflow_agent()、make_lead_agent() 和 DeerFlowClient，意味着开发者可以复用 Agent 组装能力，而不必搬走整个 Web 产品。

3. 一套“产品化 Agent”工程样本

源码规模大约是 Harness + Gateway 12.4 万行 Python、前端 5.6 万行 TypeScript/TSX。值得读的不是行数，而是大量真实故障反推出来的边界：

工具 schema 太多时延迟注册，而不是全部塞给模型；
流式事件可重放，但保留窗口缺口必须显式通知前端；
ThreadState 的字段不是普通字典，而是带 reducer 的并发状态通道；
本地沙箱也要经过虚拟路径映射，不能把宿主路径直接暴露给模型；
摘要会删除活跃上下文中的消息，但不能删除 UI 历史和关键动态提醒；
角色授权既在组装期缩小工具集合，也在执行期再次裁决。

核心数字

指标	基线快照中的值	意义
包版本	2.1.0	本教程的源码分析基线
Python 要求	≥ 3.12	Harness 与 Gateway 的运行基线
前端	Next.js 16 + React 19	App Router 的状态型聊天应用
LangGraph	1.2.x	Agent 与 checkpoint 的底层语义
统一入口	`127.0.0.1:2026`	默认仅回环监听，减少误暴露
Gateway / Frontend	`8001` / `3000`	容器内部服务端口
可选 Provisioner	`8002`	远程或 K8s 沙箱供应入口
默认子代理并发上限	3	防止一次模型输出无限扇出

贯穿全书的两条主线

主线 A：一条用户消息的旅程

主线 B：能力如何被约束

DeerFlow 的能力不是“把所有工具放进列表”。每个能力都要依次通过：配置启用、Agent allowlist、角色授权、技能策略、延迟工具晋升、运行时 guardrail、沙箱路径与资源限制。理解这条过滤链，才能真正理解系统的安全边界。

源码锚点

backend/packages/harness/pyproject.toml：Harness 包与依赖
backend/pyproject.toml：Gateway 应用依赖
frontend/package.json：前端技术栈
docker/docker-compose.yaml：生产服务拓扑

下一章先把仓库压成一张可以装进脑海的地图。

第 1 章：开篇 —— 为什么 DeerFlow 值得读 ​

一句话定义 ​

它的三个身份 ​

1. 可直接运行的 Agent 产品 ​

2. 可嵌入的 Agent Harness ​

3. 一套“产品化 Agent”工程样本 ​

核心数字 ​

贯穿全书的两条主线 ​

主线 A：一条用户消息的旅程 ​

主线 B：能力如何被约束 ​

推荐阅读顺序 ​

源码锚点 ​