部署和二次开发

DeerFlow 是一个既能开箱即用，又支持深度二次开发的超级智能体 harness（不是简单的智能体，而是一个可编排的智能体运行时平台）。

---

一、开箱即用：直接拿来就能用的场景

DeerFlow 2.0 被定位为 “batteries included, fully extensible” — — 它内置了一个智能体所需的全部能力，无需额外组装即可运行使用。

开箱即用的具体过程：

1. 环境准备

   git clone https://github.com/bytedance/deer-flow.git
   cd deer-flow
   make config              # 生成配置文件模板
   

2. 配置模型与服务
   编辑 config.yaml 和 .env，至少配置一个 LLM（例如 OpenAI）：

   models:
     - name: gpt-4
       display_name: GPT-4
       use: langchain_openai:ChatOpenAI
       model: gpt-4
       api_key: $OPENAI_API_KEY   # 对应 .env 中的 OPENAI_API_KEY=sk-...
       max_tokens: 4096
       temperature: 0.7
   

   如需联网搜索，还需配置 TAVILY_API_KEY、INFOQUEST_API_KEY 等。

3. 启动所有服务

   make dev  # 启动 LangGraph 网关、前端、Nginx 反向代理（默认端口：3000）
   

4. 使用方式

   • 网页界面：访问 http://localhost:3000，直接通过聊天对话提交任务（如“帮我研究最新的 AI Agent 框架”“生成一份关于气候变化的报告”等）。
   • 即时通讯渠道：在配置好 Telegram/Slack/Feishu 后，向机器人发送指令（如 /new 开启对话，随后发送任务描述）。
   • 内置技能直接调用：无需任何代码，即可使用官方提供的技能：
     • deep-research：深度研究任务
     • report-generation：生成结构化报告
     • slide-creation：自动生成幻灯片
     • web-page：制作网页
     • image-generation、video-generation：多模态内容生成

   例如，在聊天框中输入：

   “请研究 2026 年多模态大模型的发展趋势，并生成一份 10 页的 PDF 报告”
   系统会自动调用研究、报告生成等技能，输出可下载的成果。

✅ 此时，你实际上是在使用一个“可编程的 AI 助手”，它具备联网、长期记忆、沙箱执行、子代理协同等能力，无需写一行代码。

---

二、二次开发：将 DeerFlow 作为框架进行定制扩展

虽然开箱即用已很强大，但 DeerFlow 的核心设计是 “可插拔、可扩展、可嵌入” —— 它不绑定具体使用场景，而是提供统一的底层能力，供开发者在其上构建专属智能体。

二次开发的典型过程（按深度递进）：

1. 最轻量级：新增自定义技能（无需修改代码）

技能是 DeerFlow 扩展的最基本单元，使用 Markdown 编写。

步骤：

1. 创建技能目录：

   mkdir -p skills/custom/my-analyzer
   

2. 编写技能文件 skills/custom/my-analyzer/SKILL.md：

   ---
   name: my-analyzer
   description: 自定义数据分析技能，支持 CSV 统计与可视化
   license: MIT
   allowed-tools: [bash, web_search, view_image]
   ---
   
   # My Analyzer Skill
   
   这个技能可以：
   - 下载并分析 CSV 文件
   - 使用 Python 进行统计计算
   - 生成简单的图表并返回给用户
   
   ## 工作流程
   1. 接收用户提供的数据源链接或上传文件
   2. 验证文件格式（仅支持 .csv）
   3. 使用 pandas 计算描述性统计量
   4. 生成柱状图或折线图（如适用）
   5. 返回文本摘要 + 图像文件
   
   ## 示例调用
   “分析这个销售数据文件：https://example.com/sales.csv”
   

3. 安装技能
   通过 Gateway API 安装（无需重启）：

   curl -X POST http://localhost:8001/api/skills/install \
        -F "file=@skills/custom/my-analyzer.skill"  # 先打包为 .skill 文件
   

   或直接放入 skills/custom/ 目录后重启服务。

4. 使用
   在聊天中直接调用：

   “请使用 my-analyzer 技能分析附件中的数据”

✅ 零后端代码修改，纯配置式扩展。技能可以共享、版本化，甚至上传到社区。

2. 中等程度：通过 MCP 添加外部工具或模型能力

如果你想让智能体使用你的内部 API、专有模型或特殊工具（如内部知识库查询、企业系统调用），无需改动 DeerFlow 核心，只需配置 MCP（Model Context Protocol）服务器。

步骤：

1. 编写一个符合 MCP 标准的服务（可基于官方 SDK 用 Python/Node.js 开发），例如：
   • 提供一个 query_internal_db 工具
   • 暴露一个 get_company_policy 资源
2. 在 extensions_config.json 中注册该 MCP 服务器：

   {
     "mcpServers": {
       "internal-tools": {
         "enabled": true,
         "type": "sse",
         "url": "http://localhost:9000/mcp",
         "description": "内部企业工具集合"
       }
     }
   }
   

3. 重启服务或通过 API 更新配置：

   curl -X PUT http://localhost:8001/api/mcp/config \
        -H "Content-Type: application/json" \
        -d @extensions_config.json
   

4. 在聊天中自然调用：

   “查询客户 ACME Corp 去年的采购政策”
   系统会自动路由到你的 MCP 服务。

✅ 无需触碰 DeerFlow 代码，即可将任何外部服务“插入”智能体能力中。

3. 深度定制：修改核心逻辑或嵌入到自己的系统中

如果你想改变智能体的推理流程、记忆模型、或将 DeerFlow 作为库嵌入到现有应用（如你自己的 SaaS 平台），则需要深入后端。

常见场景：

• 替换记忆存储为 Redis 或自定义数据库
• 改变子代理调度策略（例如基于优先级或成本）
• 在企业SSO环境下重构鉴权模式
• 将 DeerFlow 能力嵌入到内部员工助手或客服系统

过程：

1. 熟悉架构
   重点阅读：backend/CLAUDE.md（架构蓝图）、backend/packages/harness/deerflow/ 核心模块。

2. 关键可扩展点：

   • 模型工厂：models/factory.py — — 支持自定义 LLM 提供者
   • 工具系统：tools/ 和 community/ — — 添加新工具或替换实现
   • 中间件链：agents/lead_agent/agent.py — — 插入自定义逻辑（如日志、审计、成本控制）
   • 记忆系统：agents/memory/ — — 替换存储后端或事实抽提逻辑
   • 沙箱提供者：sandbox/ — — 添加新的执行环境（如 Wasm、GPU 集群）
   • 嵌入式客户端：client.py — — 直接在自己的 Python 服务中调用 DeerFlow 能力

3. 示例：嵌入到自己的 FastAPI 应用

   from deerflow.client import DeerFlowClient
   
   client = DeerFlowClient()  # 自动读取 config.yaml
   
   # 在自己的接口中调用
   @app.post("/analyze")
   async def analyze(request: Request):
       data = await request.json()
       response = client.chat(
           message=data["query"],
           thread_id=data.get("thread_id", "default")
       )
       return {"result": response}
   

4. 前端二次开发（可选）
   修改 frontend/src/ 下的组件、路由或状态逻辑，例如：

   • 添加新的聊天模板 UI
   • 对接企业内部设计系统
   • 开发专用的 artifact 查看器（如医学影像、CAD 文件）

⚠️ 注意：深度定制需谨慎，建议优先通过技能、MCP、配置实现需求；仅当这些方式无法满足时，再考虑修改核心代码。

---

三、总结：开箱即用 vs 二次开发的定位

---

最终建议

• 如果你只想用 AI 做事（如写报告、做研究、生成 PPT）：
  按照 开箱即用流程 走，半小时内就能开始使用。无需关心任何代码。

• 如果你想构建自己的智能体产品或内部工具：
  将 DeerFlow 作为 底层 harness：

  1. 先用内置技能验证核心能力是否符合预期
  2. 按需通过 技能系统 或 MCP 添加专业能力
  3. 只有在上述方式无法满足时，才考虑深度定制核心代码
  4. 考虑使用 嵌入式客户端 将其能力集成到你现有的产品中

DeerFlow 的真正价值在于：它不是一个“死”的智能体，而是一个你可以像搭积木一样构建专属智能体的平台——既能立即使用，也能无限进化。

落地企业智能体底层框架

理论上完全可以直接使用 DeerFlow 作为企业智能体的底层框架，仅通过丰富自定义 skills 和对接 MCP 服务，就能最快速地实现符合企业特定需求的智能体。这是 DeerFlow 2.0 的核心设计理念——“batteries included, fully extensible”。

以下是从企业落地角度的详细说明和建议：

---

✅ 为什么 DeerFlow 适合作为企业智能体框架？

---

🚀 企业级智能体快速实施路径（推荐步骤）

第一阶段：验证基础能力（1天内）

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow
make config          # 生成 config.yaml 模板
# 编辑 .env 填入至少一个 LLM API Key（如 OPENAI_API_KEY）
make dev             # 启动所有服务

→ 访问 http://localhost:3000，测试内置技能（如 deep-research、report-generation）是否正常工作。
→ 目标：确认框架核心（对话、记忆、工具调用、沙箱）在企业网络中可用。

第二阶段：丰富企业专有 Skills（1-2 周）

无需改动任何后端代码，仅通过添加 Markdown 技能文件即可扩展能力。

示例：内部知识库查询 Skill

# skills/custom/internal-knowledge/SKILL.md
---
name: internal-knowledge
description: 查询企业内部知识库（如 Confluence、SharePoint 或自建 Wiki）
license: Internal
allowed-tools: [web_search, bash]  # 可根据实际工具调整
---

# Internal Knowledge Query Skill

这个技能能够：
1. 接收用户的自然语言查询（如“最近的假期政策是什么？”）
2. 转换为知识库搜索语句
3. 调用内部搜索 API（或网页抓取）
4. 返回答案并标注来源

## 工作流程
1. 解析用户意图，生成搜索关键词
2. 调用 `web_search` 工具（若已通过 MCP 对接内部搜索服务）
   - 或直接使用 `bash` 调用内部 CLI 工具
3. 过滤并总结结果
4. 返回格式化答案

## 示例调用
“查询项目 DeerFlow 的最新里程碑”

→ 将文件放入 skills/custom/internal-knowledge/ 目录
→ 在 extensions_config.json 中启用该技能：

{
  "skills": {
    "internal-knowledge": { "enabled": true }
  }
}

→ 重启服务或通过 PUT /api/skills 接口热更新
→ 在聊天中直接说：请使用 internal-knowledge 技能查询 XX 的政策

✅ 此过程无需编译、无需重启（热更新可用）、无需触碰核心框架，业务方或实习生即使只懂 Markdown 和基本 bash 也能贡献能力。

第三阶段：对接企业核心系统（通过 MCP，2-4 周）

无需改动 DeerFlow 核心代码，仅需提供一个标准的 MCP 服务器即可将内部系统能力“插入”智能体。

示例：对接内部财务系统

1. 开发一个 MCP 服务器（使用官方 SDK，支持 Python/Node.js）：
   • 提供工具：query_expense_report, get_budget_approval_status
   • 提供资源：finance://policies/travel, finance://reports/monthly/{id}
   • 认证方式：使用 client_credentials OAuth 流，读取企业内部 token 服务
2. 在 extensions_config.json 中注册：

   {
     "mcpServers": {
       "finance-system": {
         "enabled": true,
         "type": "sse",
         "url": "https://internal-api.company.com/mcp/finance",
         "env": {
           "CLIENT_ID": "$FINANCE_CLIENT_ID",
           "CLIENT_SECRET": "$FINANCE_CLIENT_SECRET"
         },
         "description": "内部财务系统 MCP 接口"
       }
     }
   }
   

3. 通过 Gateway API 更新配置（无需重启）：

   curl -X PUT http://localhost:8001/api/mcp/config \
        -H "Content-Type: application/json" \
        -d @extensions_config.json
   

4. 在聊天中自然使用：

   “查询去年第四季度市场部的预算使用情况”
   “显示员工 ID 12345 的差旅报销审批状态”

✅ MCP 是双向标准协议，企业内部系统只需实现一次 MCP 服务器，即可同时为 DeerFlow、以及未来其他兼容 MCP 的 AI 平台提供能力。

第四阶段：企业级部署与治理（持续）

• 使用 make up 生产部署（Docker Compose 或 K8s）
• 通过 config.yaml 和 extensions_config.json 进行环境隔离（dev/test/prod）
• 使用 skills/custom/ 和私有 MCP 服务器实现多租户或业务线隔离
• 通过审计日志（后端 stdout + 可接入 ELK）追踪智能体行为
• 如需更深度定制（如改变记忆模型、推理核心），再考虑动哈密层（但通常前三阶段已能满足 80%+ 企业场景）

---

⚠️ 需要警惕的边界情况（何时可能需要更深度定制）

💡 经验法则：
90%+ 的企业智能体需求（知识助手、报告生成、流程自动化、数据查询等）都可以仅通过 skills + MCP 实现，
只有当你需要改变“智能体如何思考”时，才需要动核心代码。
而即使是思考逻辑的定制，也往往可以通过「在 skills 中嵌入复杂逻辑脚本」或「MCP 工具返回结构化决策建议」来间接实现。

---

📈 企业落地的预期收益

---

✅ 最终结论

对于企业来说，DeerFlow 不是一个“现成的智能体产品”，而是一个“智能体操作系统” —— 它提供了生产级的运行时、安全沙箱、记忆系统、工具编排和扩展机制。
只要你的企业需求可以表述为：

• “我想让智能体能够调用某个内部能力”
• “我想让智能体能够理解和使用某种企业专有格式的数据”
• “我想让智能体在特定流程中按照一定步骤执行”

那么你只需通过编写 skills/custom/.../SKILL.md 和/或对接一到多个 MCP 服务器，就能在不碰一行 DeerFlow 核心代码的前提下，快速构建出符合企业具体业务的智能体。

这正是 DeerFlow 设计者所说的：

“Use it as-is. Or tear it apart and make it yours.”
在企业场景中，“use it as-is + add your own skills/MCP” 才是最常见、最推荐、也最成功的路径。

---

沙箱模式

在DeerFlow中：

• Local模式 = 不启用Docker，智能体的命令直接在宿主机上执行
• Docker模式 = 启用Docker，智能体的命令在隔离的Docker容器中执行

两种模式下，沙箱的核心作用都是通过路径翻译机制严格限制智能体只能访问特定目录（如 /mnt/user-data/{uploads,workspace,outputs} 和 /mnt/skills）。智能体在两种模式下看到的"文件世界"结构是完全相同的——它根本无法看到宿主机或容器中的其他任何目录。

因此：

• Local模式的主要作用 = 提供一致的、受限的文件系统视图（通过路径翻译），但不提供操作系统层面的隔离
• Docker模式的作用 = 在Local模式的基础上，额外增加操作系统层面的隔离（进程、网络、用户命名空间等），并可以施加资源限制（CPU、内存等）

🔒 沙箱的工作原理（无论Local还是Docker模式）

DeerFlow 的沙箱不是简单地"在哪里运行"，而是通过路径翻译机制来控制智能体能看到什么：

1. 智能体永远只看到虚拟路径

智能体内部只能访问这些固定的虚拟路径：

/mnt/user-data/
├── uploads/          ← 你上传的文件
├── workspace/        ← 智能体的工作目录（可读写）
├── outputs/          ← 最终交付物（只能写入这里）
└── /mnt/skills/      ← 技能目录（只读）

2. 这些虚拟路径会被翻译到实际路径

无论是Local还是Docker模式，系统都会把虚拟路径映射到宿主机上的实际目录：

• 在Local模式下（默认）：

  虚拟路径 /mnt/user-data/workspace  →  实际路径 backend/.deer-flow/threads/{thread_id}/user-data/workspace
  

• 在Docker模式下：

  虚拟路径 /mnt/user-data/workspace  →  容器内路径 /mnt/user-data/workspace  →  宿主机实际路径 backend/.deer-flow/threads/{thread_id}/user-data/workspace
  

  （通过Docker卷挂载实现）

3. 关键安全保证：智能体看不到其他任何东西

• 智能体根本无法访问如 /etc、/root、/home 等系统目录
• 即使在Docker容器中运行，智能体也只能看到被挂载的那几个特定目录（通过 replace_virtual_path() 机制强制限制）
• 路径翻译发生在每一次文件操作时（如 read_file、write_file、bash 命令执行前）

✅ 因此，无论沙箱模式是Local还是Docker，智能体看到的"环境"始终是一样的：只能访问被明确授权的 uploads、workspace、outputs、skills 目录。

---

🐳 Docker沙箱的额外作用

虽然智能体看到的文件视图相同，但Docker沙箱提供了额外的隔离层：

📌 重要：即使在Local模式下，由于路径翻译机制，智能体也不能随意读取/写入宿主机的任意文件——它只能操作被映射的那几个目录。Docker沙箱只是在此基础上添加了操作系统层面的隔离。

---

⚙️ 如何选择沙箱模式（via config.yaml)

在项目根目录的 config.yaml 中配置：

sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider  # Docker模式（生产推荐）
  # 或者：
  # use: deerflow.harness.deerflow.sandbox.local.LocalSandboxProvider  # Local模式（开发调试）

开发/调试阶段**：建议用 LocalSandboxProvider（更快，无需Docker启动延迟）

💡 企业落地建议

1. 默认开启Docker沙箱（在 config.yaml 中设置 sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider）
2. 通过资源限制增强安全：在 aio_sandbox 的配置中（通常在 extensions_config.json 或通过环境变量）设置容器的CPU/内存上限，防止异常代码耗尽资源
3. 审计沙箱日志：后端会记录所有沙箱操作（如bash命令、文件读写），可用于安全审计
4. 永远不要相信智能体代码：沙箱的存在正是假设智能体可能执行恶意或错误代码——它的职责是确保即使如此，也只能在被授权的“小盒子”里活动

AIO Sandbox

它是 AI 的“全能工具箱”，如果你不用 AIO Sandbox，想让 deer-flow 的智能体具备同样的能力，你需要自己写 Dockerfile 去安装以下所有东西：

Playwright/Chrome：用于 AI 上网查资料。 VNC Server：让你能实时看到 AI 正在点的网页。 VSCode Server：让 AI 写完代码后，你可以直接在浏览器里打开编辑器查看。 Jupyter Kernel：让 AI 能像数据科学家一样运行 Python 代码块。 MCP Servers：提供标准化的接口，让 AI 能够“感知”到这些工具。 AIO Sandbox 把这些零散的工具全部打包并调优好了。 AIO Sandbox 把这些零散的工具全部打包并调优好了。

在 deer-flow 中的具体工作流：

1. 宿主机 (你的 Mac)：运行 deer-flow 的 Python 代码。
2. 容器引擎 (Colima/Docker)：启动一个名为 aio-sandbox 的容器。
3. 连接：deer-flow 通过网络端口（通常是 8080）发送指令给沙箱：“帮我用浏览器打开百度并截图”。
4. 执行：沙箱内部完成操作，把结果回传给 deer-flow。

---

Backlinks

• 从Deer-flow学习LangGraph企业最佳实践 (learning)