DeerFlow Backend 深入解析LangGraph 驱动的超长任务 SuperAgent 后端架构与实践指南【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow本指南以仓库 backend/README.md 为主体脉络系统讲解 DeerFlow 后端的整体架构、核心组件Lead Agent、中间件链、沙箱、子代理、记忆系统、工具生态、Gateway API 与 IM 渠道、安装运行、配置体系、可观测性与开发规约并结合 config.example.yaml 与deerflow-harness源码佐证底层实现。读完你将掌握请求如何从 Nginx 路由到 Gateway 与内嵌 Agent 运行时、九层中间件如何协同支撑每轮对话、如何配置模型/沙箱/记忆/扩展以及如何在本仓库中开发、迁移与测试。一、整体架构与请求路由DeerFlow 是一个基于LangGraph的 AI SuperAgent支持沙箱内执行代码、浏览网页、管理文件、向子代理委派任务、在对话间保留持久记忆并且所有执行都发生在按线程隔离的环境中。后端由内嵌运行时与 API 网关共同构成。从 backend/README.md 的架构示意可以还原出如下拓扑┌──────────────────────────────────────┐ │ Nginx (Port 2026) │ │ Unified reverse proxy │ └───────┬──────────────────┬───────────┘ │ /api/langgraph/* │ /api/* (other) rewritten to /api/* │ ▼ ┌────────────────────────────────────────┐ │ Gateway API (8001) │ │ FastAPI REST agent runtime │ │ │ │ Models, MCP, Skills, Memory, Uploads, │ │ Artifacts, Threads, Runs, Streaming │ │ │ │ ┌────────────────────────────────────┐ │ │ │ Lead Agent │ │ │ │ Middleware Chain, Tools, Subagents │ │ │ └────────────────────────────────────┘ │ └────────────────────────────────────────┘前端Next.js、后端网关FastAPI与 LangGraph 兼容 API 统一由 Nginx端口 2026反向代理汇聚内部路由规则如下/api/langgraph/*→ 重写为/api/*后进入 Gateway 的 LangGraph 兼容 API负责 agent 交互、线程threads、流式输出streaming/api/*其余请求→ Gateway API负责模型、MCP、技能、记忆、产物、上传以及线程本地数据清理/非 API 请求→ 前端 Next.js Web 界面。对应源码可以进一步阅读 gateway 路由模块含models.py、mcp.py、skills.py、memory.py、threads.py、runs.py、uploads.py、artifacts.py、channels.py等。需要留意的是langgraph.json位于 backend/langgraph.json并不是默认服务入口——脚本与 Docker 部署走的是 Gateway 内嵌运行时该文件仅为 LangGraph 工具链、Studio 或直接使用 LangGraph Server 时保留的兼容入口。二、核心组件逐个拆解2.1 Lead Agent唯一的 LangGraph 主 Agent后端运行时只有一个 LangGraph Agent即lead_agent通过make_lead_agent(config)工厂创建实现位于 agents/lead_agent/agent.py其提示词与图装配见 lead_agent 与 agents/factory.py。它聚合了五类能力动态模型选择支持 thinking思考与 vision视觉能力开关中间件链承载横切关注点共 9 个中间件见下节工具系统沙箱工具、MCP 工具、社区工具与内置工具子代理委派支持并行任务执行系统提示词注入技能、记忆上下文与工作目录指引。models[*]中以supports_thinking/supports_vision标记模型能力模型工厂与 providers 集中在 models。2.2 中间件链严格顺序的九层横切逻辑中间件按严格顺序执行每一层负责一个关注点。README 给出的对照表如下#MiddlewarePurpose1ThreadDataMiddleware为每个线程创建隔离目录workspace、uploads、outputs2UploadsMiddleware将新上传的文件注入会话上下文3SandboxMiddleware获取用于代码执行的沙箱环境4SummarizationMiddleware接近 token 上限时压缩上下文可选5TodoListMiddleware在 plan 模式中跟踪多步任务可选6TitleMiddleware首轮交互后根据用户原始请求自动生成会话标题纯附件消息回退为New Conversation7MemoryMiddleware将会话排队供异步记忆抽取8ViewImageMiddleware为支持视觉的模型注入图像数据条件性9ClarificationMiddleware拦截澄清请求并中断执行必须位于最后上述中间件的源码实现位于 agents/middlewares例如 memory_middleware.py、summarization_middleware.py、clarification_middleware.py沙箱生命周期中间件则在 sandbox/middleware.py。需要指出的是从仓库源码结构看中间件远不止 9 个——README 所列是主链路上顺序执行的核心横切层另有 dangling_tool_call_middleware.py、loop_detection_middleware.py、llm_error_handling_middleware.py、skill_tool_policy_middleware.py、terminal_response_middleware.py 等安全/健壮性中间件共同组成完整运行链。2.3 沙箱系统按线程隔离的执行环境沙箱提供按线程隔离的执行能力并通过虚拟路径翻译把“虚拟路径”映射到“线程专属物理目录”抽象接口execute_command、read_file、write_file、list_dir定义于 sandbox/sandbox.py两个 ProviderLocalSandboxProvider直接使用宿主机文件系统见 sandbox/local与AioSandboxProvider基于 Docker位于community/。异步运行时路径使用异步沙箱生命周期钩子使启动、就绪轮询与释放都不会阻塞事件循环AioSandboxProvider在 acquire/reuse 时会校验 active-cache 与 warm-pool 中的容器丢弃确认死亡的条目从而在容器意外退出后仍能为线程提供全新沙箱同时保持get()为纯内存查找。后端健康检查失败会被当作“状态未知”而非“死亡”发现阶段无法确认的容器不会被采纳acquire 会回退为创建而非报错。虚拟路径/mnt/user-data/{workspace,uploads,outputs}→ 线程专属物理目录技能路径/mnt/skills→deer-flow/skills/目录技能加载递归发现skills/{public,custom}下的嵌套SKILL.md并保留嵌套容器路径SkillScan在安装及 agent 管理的技能写入时先于 LLM 技能扫描器执行原生离线确定性扫描CRITICAL级发现会阻断警告级发现进入 LLM 上下文文件写入安全str_replace按(sandbox.id, path)串行化 read-modify-write使隔离沙箱即使虚拟路径相同也保持并发工具集合bash、ls、read_file、write_file、str_replace。其中write_file默认覆盖并在末尾提供append选项LocalSandboxProvider下bash默认禁用该 Provider 不是 shell 访问的安全隔离边界如需隔离的 shell 访问应改用AioSandboxProvider。工具实现见 sandbox/tools.py。沙箱还支持额外的宿主目录挂载mounts、工具输出截断上限以及单条 bash 命令的最大墙钟时间见后文配置。macOS 上 AIO Sandbox 优先使用 Apple Container可用时其他平台使用 Docker。2.4 子代理系统异步并发委派子代理让 Lead Agent 通过task()工具把任务异步委派给后台运行的专业 Agent内置 Agentgeneral-purpose完整工具集与bash命令专家仅在具备 shell 访问时暴露并发限制每轮最多 3 个子代理subagent_runtime.max_running默认为 3单个内置子代理默认超时 1800 秒30 分钟另有max_queued、admission_policyqueue/reject与queue_timeout_seconds描述进程级执行容量执行方式后台线程池执行并带状态跟踪与 SSE 事件调用流Agent 调用task()工具 → executor 在后台运行子代理 → 轮询直至完成 → 返回结果。实现集中于 subagents内置定义见 subagents/builtins执行引擎为executor.py注册表为registry.py。内置默认 max_turnsgeneral-purpose150、bash60config.yaml可对单类 Agent 覆盖超时、轮数与 token 预算也可定义custom_agents自定义提示词、工具白名单、技能白名单与模型自定义 Agent 经task工具与内置类型并列可用。所有子代理默认继承 Lead Agent 的模型可在subagents.agents.name.model中覆盖须匹配models:中已定义的名称。作为确定性兜底max_total_per_run默认 6合法范围 1–50限制单次 Lead Agent run 内允许委派子代理的总次数。2.5 记忆系统LLM 驱动的跨会话持久上下文记忆机制由 LLM 驱动把对话中提炼的用户画像、事实与偏好持久化用于后续会话注入自动抽取分析会话提取用户背景、事实与偏好作用域安全写入中间件抽取仅存储持久、描述性的用户级事实全局摘要同样要求描述性权威当作用域元数据缺失或属于任务/项目本地作用域时矛盾移除与合并事实会 fail closed原子替换与替换绑定的矛盾移除只有在替换通过作用域/置信度门槛、去重与事实数量裁剪后才执行结构化存储用户上下文工作/个人/置顶、历史以及带置信度分数的事实防抖更新批量聚合更新以最小化 LLM 调用可配置等待时间系统提示词注入Top 事实 上下文注入 Agent 提示词Run 级记忆身份GET /api/threads/{thread_id}/runs/{run_id}/events?event_typescontext:memory返回生效隐藏记忆块的 SHA-256 身份而无需把记忆文本复制进事件存储读取失败策略严格后端策略含历史fail_closed会停止当前轮次包括 5 秒异步注入截止线fail-open 读取在无新上下文时继续超时处理不等待空闲 worker——超时读仍可能占用其 worker 直到后端返回存储介质JSON 文件基于 mtime 的缓存失效。实现位于 agents/memory。记忆后端可插拔memory.manager_class支持已注册后端名如deermem/mem0/noop或指向MemoryManager子类的点分路径后端私有参数经memory.backend_config透传含storage_path、model、debounce_seconds、max_facts、fact_confidence_threshold、max_injection_tokens、token 计数方式以及 staleness 定期清理参数组等。2.6 工具生态CategoryToolsSandboxbash、ls、read_file、write_file、str_replaceBuilt-inpresent_files、ask_clarification、view_image、task子代理委派CommunityTavily网页搜索、Jina AI网页抓取、Crawl4AI网页抓取、Firecrawl爬取、fastCRW爬取、DuckDuckGo图片搜索MCP任意 Model Context Protocol 服务器stdio、SSE、HTTP 传输Skills经系统提示词注入的领域专属工作流内置工具源码见 tools/builtins社区工具与第三方 Provider 位于deerflow.community模块树例如web_search工具在 config.example.yaml 中同时提供了 DuckDuckGo、SearXNG、Serper、Serply、Brave、Tavily、InfoQuest、腾讯云、Exa、Firecrawl、GroundRoute、fastCRW 等多个可选实现默认启用免 API key 的 DuckDuckGo 后端。tool_groupsweb、file:read、file:write、bash、browser、knowledge用于工具组织与访问控制tools的每条定义都包含name、group与use模块路径。2.7 Gateway API前端集成的 REST 端点Gateway 是承载 REST 端点的 FastAPI 应用应用装配见 gateway/app.py。README 列出的核心路由包括RoutePurposeGET /api/models列出可用 LLM 模型GET/PUT /api/mcp/config管理 MCP 服务器配置POST /api/mcp/cache/reset重置 MCP 工具缓存使其下次使用时重新加载GET/PUT /api/skills列出与管理技能POST /api/skills/install从.skill归档安装技能GET /api/memory读取记忆数据POST /api/memory/reload强制重载记忆GET /api/memory/config记忆配置GET /api/memory/status组合配置 数据GET /api/threads/{id}/runs/{run_id}/events单次 run 的调试/审计事件event_typescontext:memory过滤出有效记忆身份POST /api/threads/{id}/uploads上传文件自动把 PDF/PPT/Excel/Word 转成 Markdown拒绝目录路径同一请求内重复文件名自动重命名GET /api/threads/{id}/uploads/list列出已上传文件DELETE /api/threads/{id}在 LangGraph 线程删除后清理 DeerFlow 管理的本地线程数据意外失败记录在服务端并返回通用 500 详情GET /api/threads/{id}/artifacts/{path}提供生成的产物文件2.8 IM 渠道IM 桥接支持飞书Feishu、Slack 与 TelegramSlack 与 Telegram 仍走最终runs.wait()响应路径飞书改为经runs.stream([messages-tuple, values])流式返回在渠道管理器内部串行化同线程的快速连续回合并按源消息原位更新单张线程内卡片。飞书卡片更新时DeerFlow 为每条入站消息保存运行中卡片的message_id持续 patch 同一卡片直至 run 结束从而保留既有OK/DONE反应流当既有飞书主题内出现后续消息而上一轮仍在运行时后续消息会等待映射到的 DeerFlowthread_id并在该精确源消息上收到排队/运行卡片且保留紧凑的源消息引用块以区分快速连问。Discord 在入站消息处理让出控制权之前注册每个“输入中”指示器循环并在渠道停止后拒绝启动新的 typing 任务typing 任务归属 Discord 专属事件循环正常关闭会在关闭客户端前于该循环上调度有界取消、等待与映射清理从而串行化主线程与 Discord 线程的注册/清理同时避免关闭挂起与跨循环RuntimeError。三、快速上手安装、配置与运行3.1 环境要求Python 3.12uv包管理器README 与 Makefile 均以 uv 为依赖安装载体所选 LLM Provider 的 API key3.2 安装步骤cd deer-flow # 复制配置文件 cp config.example.yaml config.yaml # 安装后端依赖 cd backend make installMakefile 与 pyproject.toml 承载依赖与常用开发命令容器化构建见 backend/Dockerfile。3.3 最小配置与 API key编辑项目根目录的config.yaml以 config.example.yaml 为蓝本。README 给出了两个 OpenAI 示例条目models: - name: gpt-4o display_name: GPT-4o use: langchain_openai:ChatOpenAI model: gpt-4o api_key: $OPENAI_API_KEY supports_thinking: false supports_vision: true - name: gpt-5-responses display_name: GPT-5 (Responses API) use: langchain_openai:ChatOpenAI model: gpt-5 api_key: $OPENAI_API_KEY use_responses_api: true output_version: responses/v1 supports_vision: true然后导出对应的 API keyexport OPENAI_API_KEYyour-api-key-here3.4 模型配置要点结合 config.example.yaml 深入config.example.yaml中的注释还揭示了模型条目更完整的语义部署前建议逐项核对use的格式为包名.子包.模块:类名/变量名按模块路径引用 Provider 类。若 Provider 模块缺失DeerFlow 会返回带安装指引的可操作错误例如提示uv add langchain-google-genai。max_tokens是每次调用的输出上限context_window是提示词 补全的总上下文容量驱动 UI 的实时“% context used”指示并供给summarization.trigger的fraction类型触发器解析阈值。第三方 OpenAI 兼容模型没有内置 profile不设置context_window时 fraction 触发器会降级丢弃并告警而不是使 Agent 构建崩溃。支持添加pricing块单一币种按每百万 token 计价在控制台展示真实成本。使用需 thinking 的厂商模型时推荐用补丁 Provider 保留 reasoning 字段跨多轮工具调用回放例如 DeepSeek 用deerflow.models.patched_deepseek:PatchedChatDeepSeekpatched_deepseek.py、MiMo 用PatchedChatMiMo、StepFun 用PatchedChatStepFun、MiniMax 用PatchedChatMiniMax、OpenAI 兼容网关用PatchedChatOpenAIAnthropic 开启 thinking 时必须同时配置when_thinking_enabled.thinking.budget_tokens最小 1024 且须小于max_tokens否则会静默回退到非 thinking 模式。Ollama 请使用langchain_ollama:ChatOllama原生 Provider其/v1/chat/completions兼容端点不会把 reasoning 作为独立字段返回本地/容器地址在 Docker 部署时应写host.docker.internal。配置值以$开头时解析为环境变量。3.5 启动运行完整应用项目根目录执行make dev # 启动 Gateway Frontend Nginx访问地址http://localhost:2026仅后端backend 目录执行# Gateway API 内嵌 Agent 运行时 make devGateway 直连地址http://localhost:8001终端工作台TUI——无需任何服务的内嵌运行时终端 UIuv pip install deerflow-harness[tui] # 可选 textual 依赖 deerflow # 启动 TUI deerflow --print summarize this repo # 无头单次执行 deerflow --recursion-limit 250 --print run a longer taskTUI 中打开的会话会出现在 Web UI 侧边栏它把共享的threads_meta存储写入本地默认用户之下详见 backend/docs/TUI.md。四、工程目录结构与 langgraph.json 的角色deerflow-harness是打包为 Python 库的核心运行时以deerflow.*导入目录结构如下摘自 README 并经源码核对backend/ ├── packages/harness/ # deerflow-harness 包import: deerflow.* │ └── deerflow/ │ ├── agents/ # Agent 系统 │ │ ├── lead_agent/ # 主 Agent工厂、提示词 │ │ ├── middlewares/ # 中间件组件 │ │ ├── memory/ # 记忆抽取与存储 │ │ └── thread_state.py # ThreadState schema │ ├── sandbox/ # 沙箱执行 │ │ ├── local/ # 本地文件系统 Provider │ │ ├── sandbox.py # 抽象接口 │ │ ├── tools.py # bash、ls、read/write/str_replace │ │ └── middleware.py # 沙箱生命周期 │ ├── subagents/ # 子代理委派 │ │ ├── builtins/ # general-purpose、bash agents │ │ ├── executor.py # 后台执行引擎 │ │ └── registry.py # Agent 注册表 │ ├── tools/builtins/ # 内置工具 │ ├── mcp/ # MCP 协议集成 │ ├── models/ # 模型工厂 │ ├── skills/ # 技能发现与加载 │ ├── config/ # 配置系统 │ ├── runtime/ # 内嵌 run 执行RunManager、StreamBridge │ ├── persistence/ # Checkpointer/store 引擎与 schema 迁移 │ ├── guardrails/ # 工具调用前授权 Provider │ ├── tracing/ # Tracer 工厂与 trace 元数据 │ ├── uploads/ # 上传管理器 │ ├── tui/ # 终端 UIdeerflow console 脚本 │ ├── community/ # 社区工具与 Provider │ ├── reflection/ # 动态模块加载 │ └── utils/ # 工具函数 ├── app/ # FastAPI Gateway IM 渠道import: app.* │ ├── gateway/ # Gateway API │ │ ├── app.py # 应用装配 │ │ └── routers/ # 路由模块 │ └── channels/ # IM 渠道集成 ├── docs/ # 文档 ├── tests/ # 测试套件 ├── langgraph.json # LangGraph 图注册表供工具链/Studio 兼容 ├── pyproject.toml # Python 依赖 ├── Makefile # 开发命令 └── Dockerfile # 容器构建如需启动可选的独立开发服务器并打开其 Studio 地址cd backend uv run langgraph dev --allow-blocking需在backend/下运行以便 CLI 发现langgraph.json。要点该内存态服务器仅面向开发与测试而非生产部署--allow-blocking允许 DeerFlow 在本地 Studio 请求期间执行同步配置与图工厂装配并非生产设置本地 Studio 认证与已注册图发现自动处理无需自定义连接头。Assistant 归属/来源由服务器盖章常规 assistant 版本选择仍然可用。在锁定本地运行时加载持久化开发存储前DeerFlow 会修复遗留 assistant 行与版本历史防止旧元数据重新激活仅服务端权限或被运行时启动清理丢弃。依赖变更后需执行uv sync该兼容路径要求声明的 LangGraph 运行时版本并在持久化存储契约不符时告警。这一基于文件的 custom-app 加载路径已被后端回归测试套件覆盖。五、配置体系详解5.1 主配置 config.yaml放在项目根目录以$开头的值解析为环境变量。核心小节如下models— 带类路径、API key、thinking/vision 标志的 LLM 配置tools— 带模块路径与分组的工具定义tool_groups— 逻辑工具分组sandbox— 执行环境 Providerskills— 技能目录路径title— 自动标题生成设置summarization— 上下文摘要设置subagents— 子代理系统启/停memory— 记忆系统设置enabled、storage、debounce、facts 上限其他顶层键详见 config.example.yamlconfig_versionschema 变更时递增旧配置可运行make config-upgrade合并新字段、log_level、token_usage、token_budget每 run 硬性 token 上限可设置 warn/hard-stop 阈值、max_recursion_limit对客户端提交的 recursion_limit 硬性封顶超出被钳制到该上限非法/非正值回退服务端默认 100、uploads应用级上传限制与文档转换开关如auto_convert_documents: false与pdf_converter: auto、skill_scan、verification结果回执等。沙箱小节默认选择本地沙箱直接宿主执行并明确关闭宿主 bashsandbox: use: deerflow.sandbox.local:LocalSandboxProvider allow_host_bash: false # 仅对完全可信的单用户本地工作流开启 bash_output_max_chars: 20000 read_file_output_max_chars: 50000 ls_output_max_chars: 20000 bash_command_timeout: 600容器化 AIO Sandbox 版本则切换为deerflow.community.aio_sandbox:AioSandboxProvider并支持容器镜像钉版、replicas默认 3最近最少使用驱逐、出站网络策略open/isolated/allowlist受限模式要求 Docker Engine 28私有/回环/链路本地/组播/云元数据地址始终被拒、thread_data_mounts、环境变量注入、跨实例容器所有权多 Gateway 实例共享一个容器后端时须设置ownership.type: redis等高级项。完整的参数注释见 config.example.yaml。标题生成默认开启max_words: 6、max_chars: 60model_name: null使用快速本地回退设置模型名则改用 LLM 生成。摘要配置支持多触发条件OR 逻辑按 token 数默认 32000、消息数或模型输入上限比例fraction以及摘要后保留策略默认保留最近 10 条消息。详见 config.example.yaml。5.2 扩展配置 extensions_config.jsonMCP 服务器与技能状态统一放在单个文件中仓库根目录的 extensions_config.example.json 提供模板。README 给出的完整示例{ mcpServers: { github: { enabled: true, type: stdio, command: npx, args: [-y, modelcontextprotocol/server-github], env: {GITHUB_TOKEN: $GITHUB_TOKEN} }, secure-http: { enabled: true, type: http, url: https://api.example.com/mcp, oauth: { enabled: true, token_url: https://auth.example.com/oauth/token, grant_type: client_credentials, client_id: $MCP_OAUTH_CLIENT_ID, client_secret: $MCP_OAUTH_CLIENT_SECRET } }, postgres: { enabled: false, type: stdio, command: npx, args: [-y, modelcontextprotocol/server-postgres, postgresql://localhost/mydb], description: PostgreSQL database access, routing: { mode: prefer, priority: 50, keywords: [orders, users, SQL, database, table] }, tools: { query: { routing: { priority: 100, keywords: [query database, orders table, metrics] } } } } }, skills: { pdf-processing: {enabled: true} } }routing会向 Agent 提示词注入“软性”MCP 偏好让模型在匹配请求时优先选用配置好的 MCP 工具但并不禁止其他工具。当tool_search.enabledtrue推迟deferMCP schema 时命中的 routing 元数据可在模型调用前把最多tool_search.auto_promote_top_k个被推迟的 schema 自动提升。5.3 环境变量DEER_FLOW_CONFIG_PATH— 覆盖 config.yaml 位置DEER_FLOW_EXTENSIONS_CONFIG_PATH— 覆盖 extensions_config.json 位置模型 API keyOPENAI_API_KEY、ANTHROPIC_API_KEY、DEEPSEEK_API_KEY等工具 API keyTAVILY_API_KEY、GITHUB_TOKEN等结合 config.example.yaml 注释还常见DEER_FLOW_PROJECT_ROOT显式指定项目根、DEER_FLOW_HOME运行时数据目录默认项目根下的.deer-flow、DEER_FLOW_DATE_TIMEZONE注入 Agent 的会话日期时区、DEER_FLOW_SKILLS_PATH、DEER_FLOW_STREAM_BRIDGE_REDIS_URL等。六、可观测性LangSmith / Langfuse / 双 ProviderDeerFlow 内置 LangSmith 集成。启用后所有 LLM 调用、Agent 运行、工具执行与中间件处理都会被追踪并显示在 LangSmith 控制台。配置方式写在项目根.env中LANGSMITH_TRACINGtrue LANGSMITH_ENDPOINThttps://api.smith.langchain.com LANGSMITH_API_KEYlsv2_pt_xxxxxxxxxxxxxxxx LANGSMITH_PROJECTxxx兼容旧变量LANGCHAIN_TRACING_V2、LANGCHAIN_API_KEY、LANGCHAIN_PROJECT、LANGCHAIN_ENDPOINT仍受支持两者同时设置时LANGSMITH_*优先。Langfuse追踪面向 LangChain 兼容的运行LANGFUSE_TRACINGtrue LANGFUSE_PUBLIC_KEYpk-lf-xxxxxxxxxxxxxxxx LANGFUSE_SECRET_KEYsk-lf-xxxxxxxxxxxxxxxx LANGFUSE_BASE_URLhttps://cloud.langfuse.com自托管 Langfuse 时把LANGFUSE_BASE_URL指向你的 Langfuse 主机即可。双 Provider 行为若同时启用 LangSmith 与 LangfuseDeerFlow 会初始化并挂接两个 callback同一份运行数据同时上报两套系统。若某个 Provider 被显式启用但凭据缺失或 callback 无法初始化DeerFlow 会在模型创建期间初始化追踪时报错而不会静默禁用追踪。Docker 环境docker-compose.yaml默认关闭追踪LANGSMITH_TRACINGfalse请在.env中设置LANGSMITH_TRACINGtrue与/或LANGFUSE_TRACINGtrue及对应凭据后启用容器化部署的追踪。相关工厂与元数据实现在 deerflow/tracing。七、开发命令、Schema 迁移与测试7.1 Make 目标make install # 安装依赖 make dev # 运行 Gateway API 内嵌 Agent 运行时安全 reload端口 8001 make gateway # 运行 Gateway API不 reload端口 8001 make lint # 运行 linterruff make format # 格式化代码ruff make detect-blocking-io # 盘点可能阻塞后端事件循环的 blocking IO make migrate-rev MSG... # 针对实时 ORM 模型自动生成新 alembic revision注意make dev会预创建并把DEER_FLOW_HOME默认backend/.deer-flow与backend/sandbox从 Uvicorn 的 reload 监视器中排除。应使用该目标而非裸uvicorn --reloadAgent 任务会在DEER_FLOW_HOME下写 Python 与其他运行时文件监视该目录会在 run 进行中重启 Gateway。7.2 Schema 迁移DeerFlow 的应用表runs、threads_meta、feedback、users、run_events以及channel_*表由 alembic 管理。Gateway 启动时通过bootstrap_schema(engine, backend...)自动执行alembic upgrade head因此生产环境操作者不需要手动运行 alembic。Bootstrap 并发安全跨进程使用 Postgres advisory lock单 SQLite 进程内使用每引擎asyncio.Lock并且对已存在 schema空 / 遗留 / 已版本化幂等。修改 ORM 模型后把变更作为新 revision 提交到packages/harness/deerflow/persistence/migrations/versions/make migrate-rev MSGadd foo column to runs该目标调用 backend/scripts/_autogen_revision.py它会在head新建一个临时 SQLite 并与实时模型做 diff因此干净的 checkout 无需预置./data/deerflow.db。提交前请审查生成的文件并把裸的op.add_column/op.drop_column换成 migrations/_helpers.py 中的幂等辅助函数。项目刻意不提供make migrate/make migrate-stamp——Gateway 启动是唯一执行路径从而杜绝运维误操作。完整设计见 backend/CLAUDE.md。7.3 代码风格Linter/Formatterruff行长上限240 字符Python3.12带类型注解引号双引号缩进4 空格对应配置见 backend/ruff.toml 与 backend/pyproject.toml。7.4 测试# 默认离线后端测试套件排除实时外部 API 与 blocking-I/O 测试 make test # 严格 blocking-I/O 套件 make test-blocking-io # 显式真实 API 的 DeerFlowClient 集成套件 make test-live实时套件需要合法的根级config.yaml与 API 凭据可能产生 API 费用或创建本地沙箱、产物与文件因此不在默认测试或 CI 中运行。直接以 pytest 调用 backend/tests/test_client_live.py 还需设置DEER_FLOW_RUN_LIVE_TESTS1。make detect-blocking-io对后端业务代码做静态扫描找出可能运行在事件循环上且未被测试覆盖的 blocking IO向人工审查输出简洁汇总并把完整 JSON 发现写入仓库根目录.deer-flow/blocking-io-findings.json无论从仓库根还是backend/调用。JSON 发现同时包含宽泛 IO 分类与审查导向字段priority、location、blocking_call、event_loop_exposure、reason、code。priority是由操作类型决定的确定性审查排序并非 bug 证明同文件裸名调用按函数名解析因此同一文件内重名的辅助函数可能保守地多报异步可达性。后端测试套件位于 backend/tests覆盖客户端合约如 test_client.py、test_client_e2e.py、记忆test_memory_*系列、沙箱test_aio_sandbox_*、test_local_sandbox_*系列、运行事件流等可作为各模块行为的活文档。八、技术栈README 声明的依赖基线以 backend/pyproject.toml 与 backend/uv.lock 为准LangGraph1.0.6— Agent 框架与多 Agent 编排LangChain1.2.3— LLM 抽象与工具系统FastAPI0.115.0— Gateway REST APIlangchain-mcp-adapters— Model Context Protocol 支持agent-sandbox— 沙箱化代码执行markitdown— 多格式文档转换tavily-python / firecrawl-py— 网页搜索与爬取九、延伸阅读配置指南架构细节API 参考文件上传路径示例上下文摘要Plan 模式安装指南中文版后端说明仓库根 LICENSE 与 CONTRIBUTING【免费下载链接】deer-flowAn open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.项目地址: https://gitcode.com/GitHub_Trending/de/deer-flow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考