DeerFlow 2.0 深度指南：从 Deep Research 到可扩展的 SuperAgent Harness 的实践路线图

2026-09-06 19:03:22作者：冯爽妲Honey

An 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

DeerFlow 是一个开源的超级智能体哈尼斯（SuperAgent Harness），它将子代理（subagent）、内存（memory）、沙箱（sandbox）与可扩展技能融为一体，用于处理需要数分钟到数小时的深度研究、代码实现与内容创作任务。本文基于仓库根目录的 README_ja.md（日语版项目主页）为核心骨架，结合后端源码与配置文件，为你完整梳理 DeerFlow 2.0 的架构脉络、快速上手流程、六大核心功能原理，并给出可直接复制的配置清单与命令。

阅读本文后，你将能够：独立完成 DeerFlow 2.0 的本地/Docker 部署与模型接入；掌握沙箱模式、IM 渠道、追踪体系等进阶配置的底层字段含义；理解“技能–目标–子代理–内存”如何协作构成可运行的长程任务执行引擎，并能够通过嵌入式 Python 客户端 DeerFlowClient 与终端 TUI 以编程与交互方式驱动整套系统。

一、DeerFlow 是什么：从 Deep Research 到 SuperAgent Harness

DeerFlow 全称 Deep Exploration and Efficient Research Flow，最初是一个深度研究（Deep Research）框架。随着社区将其用于数据管道构建、幻灯片生成、仪表盘上线与内容工作流自动化等远超“搜索调研”的场景，它被证明本质上不是一个研究工具，而是一个 “哈尼斯（Harness）”——即为真实干活（getting work done）的智能体提供基础设施的运行时。

正因如此，DeerFlow 2.0 是一次“从零开始的完全重写”。根据 README_ja.md 的声明，2.0 与 v1 不共享任何代码，原 1.x 深度研究框架仍单独维护，当前开发已全部迁移到 2.0。重写后的定位是：

“不再是把组件拼接起来的框架，而是电池全含（batteries-included）、完全可扩展的超级智能体哈尼斯。”

它构建在 LangGraph 与 LangChain 之上，开箱即用地提供：文件系统、内存、技能、沙箱执行环境，以及面向复杂多步任务的规划与子代理生成能力。技术栈要求（见 backend/pyproject.toml 与 Makefile）：

组件	版本要求
Python	3.12+
Node.js	22+
包管理	pnpm、uv（前端、后端依赖分别管理）
Web 服务器	nginx（`make dev` 需要）

从源码结构看，后端被划分为多个高内聚模块，印证了“哈尼斯”而非“单体框架”的定位：gateway 服务层、IM 渠道接入层、调度任务模块、子代理批量执行模块，以及承载核心运行时逻辑的 backend/packages/harness/deerflow 包（内含 agents、sandbox、skills、subagents、tracing、memory 等子包），前端则在 frontend/src 中提供工作台（Workspace）UI。

二、快速上手：一条命令完成初始配置

2.1 克隆仓库与运行 setup 向导

官方推荐的初始路径是从项目根目录执行 Makefile 目标：

git clone https://gitcode.com/GitHub_Trending/de/deer-flow.git
cd deer-flow
make setup

make setup 会启动一个交互式向导（实现位于 scripts/wizard，包含 providers 枚举、分步引导 steps、终端 UI 与配置文件 writer），依次引导你完成：

选择 LLM Provider；
决定是否启用可选 Web 搜索；
设置 沙箱模式、bash 权限、文件写入工具等执行/安全策略。

随后向导会生成一份最小可用 config.yaml，并将 API 密钥写入 .env，全程约 2 分钟。

2.2 使用 `make doctor` 自检与 `make support-bundle` 提交问题

任何时刻都可运行 make doctor 校验配置并给出具体的修正提示。
本地安装或运行遇到问题时，若需在 GitHub issue 中上报，请运行 make support-bundle。它会输出面向报告者的后续步骤，生成可粘贴进 issue 的 *-issue-summary.md 摘要文件、供 AI 辅助提交 issue 的 *-issue-draft.md 草稿文件，并（可选）在 .deer-flow/support-bundles/ 下创建证据 zip。注意：zip 仅在维护者要求或摘要不足以定位问题时才附加；AI 提交时应以草稿为起点，替换全部 REQUIRED 占位符而非虚构缺失事实。包中只包含脱敏的诊断信息与文件清单（可先从 triage.json 入手核查），绝不包含 .env、原始对话消息或用户文件内容。

2.3 手动配置：`make config` 复制完整模板

对高级用户而言，可跳过向导，改用 make config 将 config.example.yaml 完整模板复制为本地 config.yaml 后直接编辑。模板约 2800 行（config_version: 40），涵盖全部可选项。API 密钥推荐写入 .env（也可以 shell 环境变量导出）：

OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key

路径与环境变量约定（详见 config.example.yaml 头部注释）：默认读取项目根目录 config.yaml；可用 DEER_FLOW_PROJECT_ROOT 显式指定项目根、DEER_FLOW_CONFIG_PATH 指定具体配置文件；运行态数据默认写入项目根下 .deer-flow/（可用 DEER_FLOW_HOME 迁移）；技能默认从项目根 skills/ 读取（可用 DEER_FLOW_SKILLS_PATH 迁移）。

2.4 模型配置详解（手动配置示例）

以下 YAML 节选自 README_ja 提供的手动模型示例，展示了标准 OpenAI 兼容模型、OpenRouter、Responses API 与 vLLM 推理模型的写法（所有字段均可直接用 $ENV_VAR 引用环境变量）：

models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY

  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

  - 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

  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true

要点解读：

OpenRouter / 各类 OpenAI 兼容网关：统一使用 langchain_openai:ChatOpenAI + base_url 指向其 /v1 端点；如需沿用某个厂商自定义环境变量名，可在 api_key 中显式写 $OPENROUTER_API_KEY 之类。
OpenAI Responses API 路由：仍使用 ChatOpenAI，但需追加 use_responses_api: true 与 output_version: responses/v1。
vLLM 推理模型：use 指向 deerflow.models.vllm_provider:VllmChatModel（对应仓库源码 backend/packages/harness/deerflow/models/vllm_provider.py）。对 Qwen 系推理模型，DeerFlow 通过 extra_body.chat_template_kwargs.enable_thinking 在多轮工具调用会话中保留 vLLM 非标准的 reasoning 字段；旧版 thinking 配置会被自动归一化以保持后向兼容；服务端可能需以 --reasoning-parser ... 启动。若本地 vLLM 接受任意非空 key，VLLM_API_KEY 亦可填占位值。
CLI 集成型 Provider（见 config.example.yaml 与源码 models/openai_codex_provider.py、models/claude_provider.py）：

models:
  - name: gpt-5.4
    display_name: GPT-5.4 (Codex CLI)
    use: deerflow.models.openai_codex_provider:CodexChatModel
    model: gpt-5.4
    supports_thinking: true
    supports_reasoning_effort: true

  - name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true

Codex CLI 读取 ~/.codex/auth.json；
Claude Code 支持 CLAUDE_CODE_OAUTH_TOKEN、ANTHROPIC_AUTH_TOKEN、CLAUDE_CODE_CREDENTIALS_PATH 或 ~/.claude/.credentials.json 中的任一凭据；
ACP 智能体条目与模型 Provider 相互独立——若要配置 acp_agents.codex，应指定类似 npx -y @zed-industries/codex-acp 的 Codex ACP 适配器；
macOS 下可显式导出 Claude Code 凭据：eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"。

在 config.example.yaml 的 models 区块还可看到更丰富的进阶字段：context_window（提示 + 补全的总容量，驱动聊天界面“上下文已用百分比”指标，并供基于比例的摘要触发策略使用）、supports_thinking / supports_vision / supports_reasoning_effort 能力位、timeout / max_retries、以及 per-model pricing（如 currency: CNY、按每百万 token 计价的 input_per_million 等，用于控制台实时成本展示；混用多种货币会关闭成本统计以防求和无意义）。多厂商聚合网关（如 Volcengine Coding Plan 的 /api/coding/v3 端点）可用一把 key 接入 GLM / DeepSeek / Kimi / MiniMax 等多个模型，此时需按模型逐一标注其 thinking / vision 支持情况。

三、运行应用：Docker（推荐）与本地开发双轨制

3.1 选项 1：Docker

开发环境（热重载 + 源码挂载）：

make docker-init    # 拉取沙箱镜像（首次或镜像更新时执行一次）
make docker-start   # 启动服务（根据 config.yaml 自动探测沙箱模式）

make docker-start 仅在 config.yaml 采用 provisioner 模式（sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider 且配置了 provisioner_url）时才拉起 provisioner；本地 / Docker 模式下不会启动它。

生产环境（本地构建镜像、挂载运行时配置与数据）：

make up     # 构建镜像并启动全部生产服务
make down   # 停止并删除容器

当前智能体运行时（Agent runtime）运行于 Gateway 内部，nginx 会将 /api/langgraph/* 重写转发到 Gateway 的 LangGraph-compatible API。统一访问入口：http://localhost:2026。更完整的 Docker 开发说明见 CONTRIBUTING.md。

3.2 选项 2：本地开发

前置条件：先完成上文 make setup（make dev 需要项目根存在有效 config.yaml）。

make check     # 校验 Node.js 22+、pnpm、uv、nginx
make install   # 安装后端 + 前端依赖
make setup-sandbox   # （可选）预拉取沙箱镜像，使用 Docker/容器沙箱时推荐
make dev

随后访问 http://localhost:2026。启动前可运行 make doctor 复查配置。Windows 注意：本地开发流程须在 Git Bash 中执行——基于 bash 的服务脚本不受原生 cmd.exe / PowerShell 支持，且部分脚本依赖 Git for Windows 的 cygpath 等工具，WSL 下亦不保证可用。

四、进阶配置：沙箱、MCP 与 IM 渠道

4.1 沙箱运行模式（Sandbox Modes）

DeerFlow 支持三种沙箱执行模式：

本地执行（Local）：直接在宿主机上执行沙箱代码；
Docker 执行：在隔离的 Docker 容器内执行沙箱代码；
Kubernetes 上的 Docker 执行：经 provisioner 服务在 Kubernetes Pod 中执行沙箱代码。

配置细节与字段语义可查 backend/docs/CONFIGURATION.md。config.example.yaml 中默认启用的是本地 Provider：

sandbox:
  use: deerflow.sandbox.local:LocalSandboxProvider
  # 宿主 bash 默认禁用——LocalSandboxProvider 并非 shell 访问的安全隔离边界，
  # 仅在完全可信的单用户本地工作流中启用
  allow_host_bash: false
  # 工具输出截断阈值（字符），bash 采用中段截断（头部+尾部），read_file/ls 采用头部截断
  bash_output_max_chars: 20000
  read_file_output_max_chars: 50000
  ls_output_max_chars: 20000
  # 单条宿主 bash 命令最长挂钟时间（秒），超时即整组终止，避免 agent 回合被阻塞前台命令挂死
  bash_command_timeout: 600

而容器型 AIO Sandbox（Docker / Apple Container）的推荐写法如下（节选自 config.example.yaml，注释中的关键点一并整理）：

sandbox:
  use: deerflow.community.aio_sandbox:AioSandboxProvider
  # image: <registry>/.../all-in-one-sandbox:1.11.0   # 显式固定版本（多架构，x86_64/arm64 皆可）
  # port: 8080                                        # 沙箱容器基础端口（默认 8080）
  # replicas: 3                                       # 并发容器上限（默认 3，超出后按 LRU 驱逐）
  # container_prefix: deer-flow-sandbox
  # network:                                          # 出站网络策略：open | isolated | allowlist
  #   mode: allowlist
  #   allow_domains: [pypi.org, files.pythonhosted.org, registry.npmjs.org, github.com]
  #   approval: prompt                                # deny | prompt
  #   temporary_grant_ttl: 300
  #   proxy_image: ghcr.io/bytedance/deer-flow-sandbox-network-proxy:latest
  # mounts:
  #   - host_path: /path/on/host
  #     container_path: /home/user/shared
  #     read_only: false

额外注意事项（均出自模板注释）：

macOS 上优先使用 Apple Container（若可用），否则退回 Docker；
官方默认镜像的 :latest 标签被冻结在缺失 /v1/bash/* 路由的旧 digest 上，推荐显式固定版本（如 1.11.0）；自定义镜像应继承默认镜像或实现同一套 AIO sandbox HTTP API；
网络限制模式（isolated / allowlist）需要 Docker Engine 28+，且 Apple Container 与 provisioner 模式不支持；私有/回环/链路本地/组播/云元数据地址始终被拒绝；
多 Gateway 实例 / worker 共享同一容器后端时（负载均衡部署、Docker Compose）必须配置 Redis 型容器所有权（type: redis）；Docker Compose 已设置 DEER_FLOW_STREAM_BRIDGE_REDIS_URL 时会据此自动推断。安装可选依赖：cd backend && uv sync --all-packages --extra redis。

4.2 MCP 服务器

DeerFlow 支持用可配置的 MCP 服务器与技能扩展能力；HTTP/SSE 型 MCP 服务器支持 OAuth token 流（client_credentials、refresh_token）。完整接入步骤见 backend/docs/MCP_SERVER.md。

4.3 IM 渠道接入：从移动端直接驱动 DeerFlow

DeerFlow 支持从即时通讯应用直接收发任务，渠道会在配置时自动启动，且均无需公网 IP / 回调 URL。除渠道侧推送外，工作台 UI 还可让登录用户通过 channel_connections（侧边栏 / Settings > Channels）自助绑定 Telegram、Slack、Discord、飞书/Lark、钉钉、微信、企业微信（实现细节见 backend/docs/IM_CHANNEL_CONNECTIONS.md）。

各渠道传输方式与接入难度概览：

渠道	传输方式	难度
Telegram	Bot API（长轮询）	简单
Slack	Socket Mode	中等
飞书 / Lark	WebSocket	中等
微信	Tencent iLink（长轮询）	中等
企业微信 WeCom	WebSocket	中等
钉钉	Stream Push（WebSocket）	中等

config.yaml 示例（完整结构见 README_ja 及 backend/docs/IM_CHANNEL_CONNECTIONS.md）：

channels:
  # LangGraph-compatible Gateway API base URL（默认 http://localhost:8001/api）
  langgraph_url: http://localhost:8001/api
  # Gateway API URL（默认 http://localhost:8001）
  gateway_url: http://localhost:8001

  # 可选：所有移动端渠道的全局会话默认值
  session:
    assistant_id: lead_agent
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: false

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # 空 = 允许所有人

    # 可选：按渠道/用户覆盖会话配置
    session:
      assistant_id: mobile_agent
      context:
        thinking_enabled: false
      users:
        "123456789":
          assistant_id: vip_agent
          config:
            recursion_limit: 150
          context:
            thinking_enabled: true
            subagent_enabled: true

  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # 可选：无 bot_token 时允许首次 QR 引导登录
    allowed_users: []
    polling_timeout: 35
    state_dir: ./.deer-flow/wechat/state
    max_inbound_image_bytes: 20971520
    max_outbound_image_bytes: 20971520
    max_inbound_file_bytes: 52428800
    max_outbound_file_bytes: 52428800

  dingtalk:
    enabled: true
    client_id: $DINGTALK_CLIENT_ID
    client_secret: $DINGTALK_CLIENT_SECRET
    allowed_users: []
    card_template_id: ""           # 可选：流式打字机效果的 AI 卡片模板 ID

渠道凭据写进 .env：

# Telegram
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# 飞书 / Lark
FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_app_secret

# 微信 iLink
WECHAT_BOT_TOKEN=your_ilink_bot_token
WECHAT_ILINK_BOT_ID=your_ilink_bot_id

# 企业微信 WeCom
WECOM_BOT_ID=your_bot_id
WECOM_BOT_SECRET=your_bot_secret

# 钉钉
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

各渠道激活要点（取自 README_ja 官方步骤，便于按渠道核对）：

Telegram：与 @BotFather 对话发送 /newbot 取得 HTTP API Token → 写入 .env 并启用渠道。
Slack：在 api.slack.com/apps 新建应用 → OAuth & Permissions 添加 Bot 作用域 app_mentions:read、chat:write、im:history、im:read、im:write、files:write → 启用 Socket Mode 并生成带 connections:write 的 App-Level Token（xapp-…）→ Event Subscriptions 订阅 app_mention、message.im。
飞书 / Lark：开放平台创建应用并启用“机器人”能力 → 添加权限 im:message、im:message.p2p_msg:readonly、im:resource → 事件中订阅 im.message.receive_v1 并选择长连接模式 → 复制 App ID / Secret。注意按地区选择 domain（国内 open.feishu.cn / 国际 open.larksuite.com）。
微信：写入 WECHAT_BOT_TOKEN 或开启 qrcode_login_enabled: true 走首次扫码引导 → 无 token 时在后端日志观察 iLink 返回的二维码内容完成绑定 → 成功后 DeerFlow 把取得的 token 持久化到 state_dir 供后续重启复用。Docker Compose 部署时须把 state_dir 放到持久卷上，保证 get_updates_buf 游标与已保存的认证状态不因重启丢失。
企业微信 WeCom：创建 AI Bot 取得 bot_id / bot_secret → 确认后端依赖含 wecom-aibot-python-sdk；该渠道走 WebSocket 长连接，无需公网回调。当前集成支持入站文本/图片/文件消息，agent 生成的最终图片/文件也会回传会话。
钉钉：开放平台创建应用并启用“机器人” → 消息接收模式设为 Stream 模式 → 复制 Client ID / Secret；若想启用流式 AI 卡片打字机回复，需在卡片平台创建 AI 卡片模板并把 ID 填入 card_template_id，同时申请 Card.Streaming.Write、Card.Instance.Write 权限。

渠道内可用命令：连接后直接在聊天中即可对话——不带命令前缀的消息按普通会话处理，DeerFlow 会创建线程并以会话形式回复。

命令	说明
`/new`	开始新会话
`/status`	查看当前线程信息
`/models`	列出可用模型
`/memory`	查看记忆
`/help`	显示帮助

五、可观测性：LangSmith 与 Langfuse 追踪

5.1 LangSmith

DeerFlow 内置 LangSmith 可观测性。启用后所有 LLM 调用、智能体执行与工具执行都会被追踪并展示在 LangSmith 控制台：

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=xxx

5.2 Langfuse

Langfuse 针对 LangChain 兼容执行同样受支持：

LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com

自托管 Langfuse 时把 LANGFUSE_BASE_URL 指向自己的部署地址。

5.3 追踪关联字段：一次请求串联起 Langfuse 页面

每次智能体执行都会被赋予 Langfuse 保留的 trace 属性，因此 Sessions / Users 页面会自动填充（README_ja 给出完整映射）：

session_id = LangGraph 的 thread_id——把同一会话的全部 trace 分组；
user_id = get_effective_user_id() 得到的有效用户（无认证模式下回退为 default）；
trace_name = assistant id（默认 lead-agent）；
tags = [env:<DEER_FLOW_ENV>, model:<model_name>]（未设置则省略）；
metadata.deerflow_trace_id = DeerFlow 请求关联 id，始终与同一次请求返回的 X-Trace-Id 响应头一致（logging.enhance.enabled 只控制该 id 是否进入日志）。

这些元数据在两条路径上都被注入图调用的 RunnableConfig.metadata 根上——gateway 路径（runtime/runs/worker.py::run_agent）与嵌入式路径（client.py::DeerFlowClient.stream）——因此任意 LangChain 兼容回调都可读取。设置 DEER_FLOW_ENV（或 ENVIRONMENT）可为不同部署环境打 trace 标签。

5.4 同时启用双 Provider

两者同时启用时，DeerFlow 会挂接两套 callback，把同一份模型活动同时上报两个系统。若某 provider 显式启用却缺少凭据，或对应 callback 初始化失败，DeerFlow 会在模型创建阶段的追踪初始化处快速失败（fail fast），错误信息中会点名失败方。Docker 部署默认不开启追踪，需在 .env 设置 LANGSMITH_TRACING=true 与 LANGSMITH_API_KEY 激活。

六、核心功能机制深度解析

6.1 技能与工具：让 DeerFlow“几乎什么都能做”

技能是 DeerFlow 可扩展性的关键。一个标准技能是结构化功能模块——用 Markdown 定义工作流、最佳实践与支撑资源引用（SKILL.md）。仓库内置了大量技能（见 skills/public，含 deep-research、image-generation、ppt-generation、video-generation、music-generation、podcast-generation、skill-creator、find-skills 等），真正的力量在于可扩展性：可以添加自研技能、替换内置技能、组合成复合工作流。

关键机制：

渐进式加载：技能只在任务需要时才加载，不会一次全量注入，从而保持上下文窗口精简，让对 token 敏感的小模型也能顺畅运行。
Frontmatter 元数据：经 Gateway 安装 .skill 归档时，接受 version、author、compatibility 等可选标准元数据，不会拒绝合法的外部技能（校验工具相关可参考 tests/skills 与 scripts/skill_review_waivers.py）。
工具即插即换：核心工具集包括 Web 搜索、Web 抓取、文件操作与 bash 执行；并支持用 MCP 服务器或 Python 函数扩展自定义工具。Gateway 生成的跟进建议（follow-up suggestions）会在解析 JSON 数组响应前归一化“纯字符串模型输出”与“块/列表式富文本”两种形态，从而避免厂商特有内容包装导致建议被静默丢弃。

仓库级技能挂载路径示意（沙箱容器内部视角）：

/mnt/skills/public
├── deep-research/SKILL.md
├── image-generation/SKILL.md
├── ppt-generation/SKILL.md
└── video-generation/SKILL.md

/mnt/skills/custom
└── your-custom-skill/SKILL.md      ← 你的自定义技能

说明：README_ja 所列目录树为概览示意，实际内置技能集以 skills/public 当前内容为准（技能目录与示例树可能随版本演进调整）。

Claude Code 集成：终端内直接驱动 DeerFlow

借助 claude-to-deerflow 技能，可在 Claude Code 中直接与运行中的 DeerFlow 实例对话——提交研究任务、查看状态、管理线程，全程不离开终端。

安装：npx skills add 指向本仓库的 claude-to-deerflow 技能（运行时先确保 DeerFlow 已启动，默认 http://localhost:2026），随后在 Claude Code 中使用 /claude-to-deerflow 命令。该技能支持：

发送消息并获取流式响应；
选择执行模式：flash（快速）、standard、pro（规划）、ultra（子代理）；
健康检查与模型/技能/智能体列表；
线程与会话历史管理；
上传文件供分析。

可选环境变量（自定义端点时）：

DEERFLOW_URL=http://localhost:2026            # 统一代理 base URL
DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API

完整 API 参考见 skills/public/claude-to-deerflow/SKILL.md。

6.2 Session Goals：让长程任务具备“完成标准”

/goal <完成条件> 给当前线程绑定唯一激活的完成条件。目标是线程作用域的状态而非技能开关，因此在 DeerFlow 判定其已满足或你主动清除之前，它会跨多个回合持续生效：

/goal finish the implementation and make all tests pass
/goal              # 查看激活中的目标
/goal clear        # 清除目标

机制要点（README_ja 结合实现语义描述）：

每个 Gateway 驱动的 run 之后，DeerFlow 用非思考型评估模型对照激活目标审查可见对话；评估模型须返回类型化 blocker（missing_evidence、needs_user_input、run_failed、external_wait、goal_not_met_yet）与可见证据；
仅当最近 assistant 回合已落盘到耐久性检查点、blocker 为 goal_not_met_yet、评估期间线程未变化、且 no-progress 熔断未触发时，才注入 hidden continuation；
安全上限默认 8 次 hidden continuation；同一非进展评估重复会提早（2 次）停止；
/goal clear 与用户手写的新输入都优先于队列中的 continuation；
目标达成后自动清除并发布更新后的线程状态。

Web UI 会在输入框上方展示激活中的目标；同样命令在 TUI 与受支持的 IM 渠道也可用。在 Web UI 与受支持渠道中，/goal <完成条件> 会把该条件作为任务启动一次 run；查看状态/清除类命令只管理目标状态（相关后台支撑模块可从 backend/tests 中的 test_goal_* 测试族追踪到，例如 goal runtime 与 goal worker）。

6.3 子代理：复杂任务的“分解—并行—汇合”

复杂任务无法单线完成，DeerFlow 会把它们拆解：lead agent（主代理）在飞行中按需生成子代理，每个子代理拥有独立的上下文、工具与终止条件；子代理尽量并行执行并向主代理汇报结构化结果，最后由主代理整合为一致产出。这正是它能够处理“耗时数分钟到数小时任务”的机理：例如一个研究任务被展开成十几个子代理，各自探索不同角度，再收敛到一份报告——或一个网站、一组带生成视觉的幻灯片。“一个哈尼斯，多双手。”

6.4 沙箱与文件系统：不只是“说”，而是“拥有自己的电脑”

每个任务运行在带完整文件系统的隔离容器中，覆盖技能、工作区、上传与输出；代理可读写/编辑文件、执行 bash、写代码、查看图片——全部在沙箱内完成、全部可审计、会话间零污染。这正是“带工具访问的聊天机器人”与“拥有真实执行环境的代理”的本质区别。沙箱内典型目录结构：

/mnt/user-data/
├── uploads/          ← 你的文件
├── workspace/        ← 代理的工作目录
└── outputs/          ← 最终产出物

6.5 上下文工程：对抗长任务中的上下文爆炸

隔离的子代理上下文：每个子代理在独立上下文中运行，看不到主代理或其他子代理的上下文，从而专注当前任务、避免分心（也天然抑制跨代理提示注入面）。
摘要化（Summarization）：会话内主动管理上下文——为已完成的子任务生成摘要、把中间结果下放到文件系统、压缩不再直接相关的内容，使超长多步任务全程保持“锐度”而不撑爆窗口。相关触发策略（如基于 context_window 比例的 fraction 型摘要触发）配置见 config.example.yaml 的 summarization 区块及 backend/docs 下 summarization.md、CONTEXT_* 相关说明。

6.6 长期记忆：会话结束不代表遗忘

大多数代理在会话结束后会忘记一切，DeerFlow 会跨会话累积关于你的档案、偏好与知识库——越用越了解你的写作风格、技术栈与惯用工作流。记忆本地存储、归你掌控。此外，记忆更新在应用时会跳过重复的事实条目，避免偏好与上下文跨会话无限累积（对应测试见 backend/tests 中 test_memory_* 系列；记忆模块位于 backend/packages/harness/deerflow 的 memory 相关目录）。

七、推荐模型特征

DeerFlow 与模型解耦——凡是实现 OpenAI 兼容 API 的 LLM 均可接入；但具备以下能力的模型可获得最佳效果：

长上下文窗口（≥ 10 万 token）：面向深度研究与多步任务；
推理（reasoning）能力：支撑自适应规划与复杂任务拆解；
多模态输入：支持图像/视频理解；
强大的工具调用：可靠的函数调用与结构化输出。

八、嵌入式 Python 客户端：免 HTTP 服务的进程内编程

DeerFlow 也可作为嵌入式 Python 库使用而无需运行完整 HTTP 服务。DeerFlowClient 提供对所有智能体与 Gateway 能力的进程内直连，且返回与 HTTP Gateway API 相同的响应模式；HTTP Gateway 还额外开放 DELETE /api/threads/{thread_id}，用于在 LangGraph 线程本身被删除后清理 DeerFlow 管理下的本地线程数据。

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# 聊天
response = client.chat("Analyze this paper for me", thread_id="my-thread")

# 流式（LangGraph SSE 协议：values、messages-tuple、end）
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

# 配置与管理 —— 返回 Gateway 兼容 dict
models = client.list_models()        # {"models": [...]}
skills = client.list_skills()        # {"skills": [...]}
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}
client.set_goal("thread-1", "finish the implementation and make all tests pass")
client.get_goal("thread-1")       # {"goal": {...}} or {"goal": None}
client.clear_goal("thread-1")

从源码看，这些方法与 README_ja 的示例一一对应：client.py 中 chat、stream、list_models、list_skills、update_skill、upload_files、get_goal / set_goal / clear_goal 均已实现（set_goal / get_goal 约在 client.py 一带，stream 在约 L722，chat 在约 L1107）。所有返回 dict 的方法都会在 CI 中与 Gateway Pydantic 响应模型做一致性校验（TestGatewayConformance），确保嵌入式客户端与 HTTP API 模式保持同步。完整 API 文档可直接阅读 backend/packages/harness/deerflow/client.py。

九、调度任务（Scheduled Tasks）

工作台内置了一等公民的调度任务 MVP，当前能力与边界如下。

MVP 现有能力：

在 /workspace/scheduled-tasks 管理任务；
每个调度任务可选择复用线程或每次执行新建线程；
支持 once 与 cron 两类调度；
后台调度执行以非交互式 DeerFlow run 运行（此处不开放 ask_clarification）；
对复用的同一线程上、与活跃 run 冲突的到期 cron 执行，采用 skip 重叠行为；
可暂停、恢复、手动触发、查看历史与删除任务；
调度工作走常规 DeerFlow run 生命周期。

MVP 当前限制：

尚不能在会话中通过 schedule_task 工具创建任务；
无纯文本通知任务；
无渠道 / GitHub dispatch 目标；
首版无 interval 调度类型。

启用方式：config.yaml -> scheduler.enabled: true；手动触发走同一套调度任务资源与执行路径。模板中的完整字段（见 config.example.yaml 的 scheduler 区块）包括 poll_interval_seconds（默认 5）、lease_seconds（默认 120，租约感知的多实例恢复可经 multi_instance: true 开启）、max_concurrent_runs（默认 3）、queue_timeout_seconds、min_once_delay_seconds、recursion_limit（默认 1000）。更深的实现与测试可从 backend/tests 的 test_scheduled_task_* 系列与 backend/app/scheduler 模块追踪。

十、终端工作台（TUI）：给“住在 shell 里”的人

deerflow 是终端原生工作台。它内嵌运行于 DeerFlowClient 之上，不需要 Gateway、前端、nginx 或 Docker，但依然遵循 DeerFlow 其余部分同一套 config.yaml、checkpointer、技能、记忆、MCP 与沙箱配置。

安装与用法：

uv pip install 'deerflow-harness[tui]'        # 可选 'textual' 依赖

deerflow                                      # 启动终端 UI（需 TTY）
deerflow --continue                           # 续接最近线程
deerflow --resume THREAD                      # 按 ID 续接线程
deerflow --print "summarize this repo"        # 无头一次性问答，输出到 stdout
deerflow --json  "hello"                       # 无头输出换行分隔的 StreamEvent

体验要点：支持 Markdown 渲染的流式转录、紧凑的工具活动卡片、/ 斜杠命令面板、/goal 目标管理、/model 与 /threads 选择器、输入历史，以及 Esc / Ctrl+C 中断的键盘驱动聊天界面。在 TUI 打开的会话同样会出现在 Web UI 侧边栏——它把线程写入本地默认用户名下的共享线程存储，因此无需运行 Gateway，终端与网页即可同步。完整指南见 backend/docs/TUI.md。

十一、安全部署注意事项

DeerFlow 具备执行系统命令、操作资源、调用业务逻辑等高权限能力，默认按“仅部署在本地可信环境（仅允许 127.0.0.1 回环访问）”设计。若在不可信局域网、公网云服务器或多端点可达的网络中部署而不加防护，可能带来两类风险：

未授权非法调用：高权限能力被第三方或恶意扫描器发现，导致批量越权请求执行系统命令 / 读写文件等高危操作；
合规与法律风险：代理被滥用从事网络攻击、数据窃取等非法行为时，可能引发法律责任。

官方建议：强烈推荐仅在本地可信网络部署；确需跨设备 / 跨网络部署时，至少落实以下防护：

配置 IP 白名单：用 iptables、硬件防火墙或带 ACL 的交换机拒绝其他所有 IP 访问；
前置认证：配置反向代理（如 nginx）并强制强认证，拦截未认证访问；
网络隔离：尽量将代理与可信设备放在同一专用 VLAN 并与其他网络设备隔离；
持续跟进更新：持续关注 DeerFlow 安全功能的版本更新。

十二、文档地图与社区

仓库内与该 README 配套的中英文与多语言主页可直接互跳：English README、中文 README、日本語 README、Français、Русский。深入阅读建议按需选取：

配置指南：完整的 setup 与配置步骤；
架构总览：技术架构细节；
后端架构与 API 参考：Gateway API 与后端内部结构；
IM 渠道连接说明：渠道自助绑定的安全注意与配置；
MCP 服务器指南：MCP 扩展接入；
TUI 完整指南：终端工作台进阶用法；
贡献指南：开发环境搭建与工作流。

回归测试覆盖（包括 Docker 沙箱模式检测、provisioner kubeconfig 路径处理等）位于 backend/tests；项目以 MIT License 开源。DeerFlow 建立在 LangChain（LLM 交互与链）与 LangGraph（多代理编排）之上，核心作者与完整贡献者名单见 README_ja 的致谢章节。