diff --git a/README.md b/README.md index a116bc1..17f7313 100644 --- a/README.md +++ b/README.md @@ -1,34 +1,40 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/bytedance/deer-flow) · [上游 README](https://github.com/bytedance/deer-flow/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 + # 🦌 DeerFlow - 2.0 -English | [中文](./README_zh.md) | [日本語](./README_ja.md) | [Français](./README_fr.md) | [Русский](./README_ru.md) +[English](./README.md) | 中文 | [日本語](./README_ja.md) | [Français](./README_fr.md) | [Русский](./README_ru.md) [![Python](https://img.shields.io/badge/Python-3.12%2B-3776AB?logo=python&logoColor=white)](./backend/pyproject.toml) [![Node.js](https://img.shields.io/badge/Node.js-22%2B-339933?logo=node.js&logoColor=white)](./Makefile) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE) bytedance%2Fdeer-flow | Trendshift -> On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥 +> 2026 年 2 月 28 日，DeerFlow 2 发布后登上 GitHub Trending 第 1 名。非常感谢社区的支持，这是大家一起做到的。 -DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) is an open-source **super agent harness** that orchestrates **sub-agents**, **memory**, and **sandboxes** to do almost anything — powered by **extensible skills**. +DeerFlow（**D**eep **E**xploration and **E**fficient **R**esearch **Flow**）是一个开源的 **super agent harness**。它把 **sub-agents**、**memory** 和 **sandbox** 组织在一起，再配合可扩展的 **skills**，让 agent 可以完成几乎任何事情。 https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 > [!NOTE] -> **DeerFlow 2.0 is a ground-up rewrite.** It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the [`1.x` branch](https://github.com/bytedance/deer-flow/tree/main-1.x) — contributions there are still welcome. Active development has moved to 2.0. +> **DeerFlow 2.0 是一次彻底重写。** 它和 v1 没有共用代码。如果你要找的是最初的 Deep Research 框架，可以前往 [`1.x` 分支](https://github.com/bytedance/deer-flow/tree/main-1.x)。那里仍然欢迎贡献；当前的主要开发已经转向 2.0。 -## Official Website +## 官网 -Learn more and see **real demos** on our [**official website**](https://deerflow.tech). +想了解更多，或者直接看**真实演示**，可以访问[**官网**](https://deerflow.tech)。 -## Coding Plan from ByteDance Volcengine +## 字节跳动火山引擎方舟 Coding Plan -- We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow -- [Learn more](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow) -- [中国大陆地区的开发者请点击这里](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow) +- 我们推荐使用 Doubao-Seed-2.0-Code、DeepSeek v3.2 和 Kimi 2.5 运行 DeerFlow +- [现在就加入 Coding Plan](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow) +- [海外地区的开发者请点击这里](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow) ## InfoQuest -DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus--[InfoQuest (supports free online experience)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest) +DeerFlow 新近集成了 BytePlus 自研的智能搜索与抓取工具集——[InfoQuest（支持免费在线体验）](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest) ---- - -## Table of Contents +## 目录 - [🦌 DeerFlow - 2.0](#-deerflow---20) - - [Official Website](#official-website) - - [Coding Plan from ByteDance Volcengine](#coding-plan-from-bytedance-volcengine) + - [官网](#官网) + - [字节跳动火山引擎方舟 Coding Plan](#字节跳动火山引擎方舟-coding-plan) - [InfoQuest](#infoquest) - - [Table of Contents](#table-of-contents) - - [One-Line Agent Setup](#one-line-agent-setup) - - [Quick Start](#quick-start) - - [Configuration](#configuration) - - [Running the Application](#running-the-application) - - [Deployment Sizing](#deployment-sizing) - - [Option 1: Docker (Recommended)](#option-1-docker-recommended) - - [Option 2: Local Development](#option-2-local-development) - - [Advanced](#advanced) - - [Sandbox Mode](#sandbox-mode) + - [目录](#目录) + - [一句话交给 Coding Agent 安装](#一句话交给-coding-agent-安装) + - [快速开始](#快速开始) + - [配置](#配置) + - [运行应用](#运行应用) + - [部署建议与资源规划](#部署建议与资源规划) + - [方式一：Docker（推荐）](#方式一docker推荐) + - [方式二：本地开发](#方式二本地开发) + - [进阶配置](#进阶配置) + - [Sandbox 模式](#sandbox-模式) - [MCP Server](#mcp-server) - - [IM Channels](#im-channels) - - [LangSmith Tracing](#langsmith-tracing) - - [Langfuse Tracing](#langfuse-tracing) - - [Using Both Providers](#using-both-providers) - - [From Deep Research to Super Agent Harness](#from-deep-research-to-super-agent-harness) - - [Core Features](#core-features) - - [Skills \& Tools](#skills--tools) - - [Claude Code Integration](#claude-code-integration) + - [IM 渠道](#im-渠道) + - [LangSmith 链路追踪](#langsmith-链路追踪) + - [Langfuse 链路追踪](#langfuse-链路追踪) + - [同时使用两种追踪服务](#同时使用两种追踪服务) + - [从 Deep Research 到 Super Agent Harness](#从-deep-research-到-super-agent-harness) + - [核心特性](#核心特性) + - [Skills 与 Tools](#skills-与-tools) + - [Claude Code 集成](#claude-code-集成) - [Session Goals](#session-goals) - - [Manual Context Compaction](#manual-context-compaction) + - [手动上下文压缩](#手动上下文压缩) - [Sub-Agents](#sub-agents) - - [Sandbox \& File System](#sandbox--file-system) + - [Sandbox 与文件系统](#sandbox-与文件系统) - [Context Engineering](#context-engineering) - - [Long-Term Memory](#long-term-memory) - - [Recommended Models](#recommended-models) - - [Embedded Python Client](#embedded-python-client) - - [Scheduled Tasks](#scheduled-tasks) - - [Terminal Workbench (TUI)](#terminal-workbench-tui) - - [Documentation](#documentation) - - [⚠️ Security Notice](#️-security-notice) - - [Improper Deployment May Introduce Security Risks](#improper-deployment-may-introduce-security-risks) - - [Security Recommendations](#security-recommendations) - - [Contributing](#contributing) - - [License](#license) - - [Acknowledgments](#acknowledgments) - - [Key Contributors](#key-contributors) + - [长期记忆](#长期记忆) + - [推荐模型](#推荐模型) + - [内嵌 Python Client](#内嵌-python-client) + - [定时任务 (Scheduled Tasks)](#定时任务-scheduled-tasks) + - [终端工作台 (TUI)](#终端工作台-tui) + - [文档](#文档) + - [⚠️ 安全使用](#️-安全使用) + - [参与贡献](#参与贡献) + - [许可证](#许可证) + - [致谢](#致谢) + - [核心贡献者](#核心贡献者) - [Star History](#star-history) -## One-Line Agent Setup +## 一句话交给 Coding Agent 安装 -If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence: +如果你在用 Claude Code、Codex、Cursor、Windsurf 或其他 coding agent，可以直接把下面这句话发给它： ```text -Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md +如果还没 clone DeerFlow，就先 clone，然后按照 https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md 把它的本地开发环境初始化好 ``` -That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide. +这条提示词是给 coding agent 用的。它会在需要时先 clone 仓库，优先选择 Docker，完成初始化，并在结束时告诉你下一条启动命令，以及还缺哪些配置需要你补充。 -## Quick Start +## 快速开始 -### Configuration +### 配置 -1. **Clone the DeerFlow repository** +1. **克隆 DeerFlow 仓库** ```bash git clone https://github.com/bytedance/deer-flow.git cd deer-flow ``` -2. **Run the setup wizard** +2. **运行安装向导（推荐）** - From the project root directory (`deer-flow/`), run: + 在项目根目录（`deer-flow/`）执行： ```bash make setup ``` - This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution/safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal `config.yaml` and writes your keys to `.env`. Takes about 2 minutes. + 这会启动一个交互式向导，引导你选择 LLM provider、可选的 web 搜索工具，以及 sandbox 模式、bash 权限、文件写入等执行/安全偏好。它会生成一份最小化的 `config.yaml`，并把 API key 写入 `.env`，大约 2 分钟完成。 - The wizard also lets you configure an optional web search provider, or skip it for now. + 随时可以运行 `make doctor` 检查配置和系统环境，并获得可执行的修复建议。 + 如果你要提交本地安装、配置或运行问题，可以执行 `make support-bundle`。 + 命令会直接打印 reporter 下一步建议，并在 `.deer-flow/support-bundles/` 下生成 + `*-issue-summary.md`、面向 AI 辅助提 issue 的 `*-issue-draft.md`，以及可选证据 + zip。提交 GitHub issue 时，先把 `*-issue-summary.md` 粘贴到 issue 正文；如果由 + AI 助手代填 issue，就从 `*-issue-draft.md` 开始，并先替换所有 REQUIRED 占位符， + 不要编造未知事实。只有维护者要求证据包，或摘要不足以诊断时，再附上 zip。维护者 + 或 AI 辅助 triage 可以优先读取 `triage.json`；bundle 只包含脱敏后的诊断信息和 + 文件 manifest，不包含 `.env`、原始对话消息或用户文件内容；提交前仍建议自己快速 + 检查一遍。 - Run `make doctor` at any time to verify your setup and get actionable fix hints. - If you are opening a GitHub issue about a local setup or runtime problem, run - `make support-bundle`. The command prints reporter next steps, writes a - `*-issue-summary.md` file to paste into the issue, a `*-issue-draft.md` file - for AI-assisted issue filing, and an optional evidence zip under - `.deer-flow/support-bundles/`. If an AI assistant files the issue, start from - the draft and replace every REQUIRED placeholder instead of inventing missing - facts. Attach the zip only if a maintainer asks for it, or if the summary - alone is not enough. Maintainers and AI triage tools can start with - `triage.json`; the bundle includes redacted diagnostics and file manifests - only, and does not include `.env`, raw conversation messages, or user file - contents. - - > **Advanced / manual configuration**: If you prefer to edit `config.yaml` directly, run `make config` instead to copy the full template. See `config.example.yaml` for the complete reference including CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API, and more. + > **进阶 / 手动配置**：如果你更想直接编辑 `config.yaml`，可以改用 `make config` 复制完整的示例模板。完整参考见 `config.example.yaml`，其中包含 CLI-backed provider（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API 等更多配置。
- Manual model configuration examples + 手动模型配置示例 ```yaml models: @@ -170,13 +168,13 @@ That prompt is intended for coding agents. It tells the agent to clone the repo enable_thinking: true ``` - OpenRouter and similar OpenAI-compatible gateways should be configured with `langchain_openai:ChatOpenAI` plus `base_url`. If you prefer a provider-specific environment variable name, point `api_key` at that variable explicitly (for example `api_key: $OPENROUTER_API_KEY`). + OpenRouter 以及类似的 OpenAI 兼容网关，建议通过 `langchain_openai:ChatOpenAI` 配合 `base_url` 来配置。如果你更想用 provider 自己的环境变量名，也可以直接把 `api_key` 指向对应变量，例如 `api_key: $OPENROUTER_API_KEY`。 - To route OpenAI models through `/v1/responses`, keep using `langchain_openai:ChatOpenAI` and set `use_responses_api: true` with `output_version: responses/v1`. + 如果要让 OpenAI 模型走 `/v1/responses`，继续使用 `langchain_openai:ChatOpenAI`，并设置 `use_responses_api: true` 和 `output_version: responses/v1`。 - For vLLM 0.19.0, use `deerflow.models.vllm_provider:VllmChatModel`. For Qwen-style reasoning models, DeerFlow toggles reasoning with `extra_body.chat_template_kwargs.enable_thinking` and preserves vLLM's non-standard `reasoning` field across multi-turn tool-call conversations. Legacy `thinking` configs are normalized automatically for backward compatibility. Reasoning models may also require the server to be started with `--reasoning-parser ...`. If your local vLLM deployment accepts any non-empty API key, you can still set `VLLM_API_KEY` to a placeholder value. + 对于 vLLM 0.19.0，请使用 `deerflow.models.vllm_provider:VllmChatModel`。对于 Qwen 风格的推理模型，DeerFlow 通过 `extra_body.chat_template_kwargs.enable_thinking` 开关推理，并在多轮 tool-call 对话中保留 vLLM 非标准的 `reasoning` 字段。旧版 `thinking` 配置会自动规范化以保持向后兼容。推理模型可能还需要在启动 vLLM 服务时加上 `--reasoning-parser ...` 参数。如果你的本地 vLLM 部署接受任意非空 API key，可以把 `VLLM_API_KEY` 设为一个占位值。 - CLI-backed provider examples: + CLI-backed provider 配置示例： ```yaml models: @@ -195,16 +193,16 @@ That prompt is intended for coding agents. It tells the agent to clone the repo supports_thinking: true ``` - - Codex CLI reads `~/.codex/auth.json` - - Claude Code accepts `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_CREDENTIALS_PATH`, or `~/.claude/.credentials.json` - - ACP agent entries are separate from model providers — if you configure `acp_agents.codex`, point it at a Codex ACP adapter such as `npx -y @zed-industries/codex-acp` - - On macOS, export Claude Code auth explicitly if needed: + - Codex CLI 会读取 `~/.codex/auth.json` + - Claude Code 支持 `CLAUDE_CODE_OAUTH_TOKEN`、`ANTHROPIC_AUTH_TOKEN`、`CLAUDE_CODE_CREDENTIALS_PATH`，或 `~/.claude/.credentials.json` + - ACP agent 条目与 model provider 是分开配置的——如果你配置了 `acp_agents.codex`，请把它指向一个 Codex ACP 适配器，例如 `npx -y @zed-industries/codex-acp` + - 在 macOS 上，如有需要可显式导出 Claude Code 的认证信息： ```bash eval "$(python3 scripts/export_claude_code_oauth.py --print-export)" ``` - API keys can also be set manually in `.env` (recommended) or exported in your shell: + API key 也可以手动写入 `.env` 文件（推荐）或在 shell 中导出： ```bash OPENAI_API_KEY=your-openai-api-key @@ -213,177 +211,122 @@ That prompt is intended for coding agents. It tells the agent to clone the repo
-### Running the Application +### 运行应用 -#### Deployment Sizing +#### 部署建议与资源规划 -Use the table below as a practical starting point when choosing how to run DeerFlow: +可以先按下面的资源档位来选择 DeerFlow 的运行方式： -| Deployment target | Starting point | Recommended | Notes | +| 部署场景 | 起步配置 | 推荐配置 | 说明 | |---------|-----------|------------|-------| -| Local evaluation / `make dev` | 4 vCPU, 8 GB RAM, 20 GB free SSD | 8 vCPU, 16 GB RAM | Good for one developer or one light session with hosted model APIs. `2 vCPU / 4 GB` is usually not enough. | -| Docker development / `make docker-start` | 4 vCPU, 8 GB RAM, 25 GB free SSD | 8 vCPU, 16 GB RAM | Image builds, bind mounts, and sandbox containers need more headroom than pure local dev. | -| Long-running server / `make up` | 8 vCPU, 16 GB RAM, 40 GB free SSD | 16 vCPU, 32 GB RAM | Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads. | +| 本地体验 / `make dev` | 4 vCPU、8 GB 内存、20 GB SSD 可用空间 | 8 vCPU、16 GB 内存 | 适合单个开发者或单个轻量会话，且模型走外部 API。`2 核 / 4 GB` 通常跑不稳。 | +| Docker 开发 / `make docker-start` | 4 vCPU、8 GB 内存、25 GB SSD 可用空间 | 8 vCPU、16 GB 内存 | 镜像构建、源码挂载和 sandbox 容器都会比纯本地模式更吃资源。 | +| 长期运行服务 / `make up` | 8 vCPU、16 GB 内存、40 GB SSD 可用空间 | 16 vCPU、32 GB 内存 | 更适合共享环境、多 agent 任务、报告生成或更重的 sandbox 负载。 | -- These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately. -- Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments. -- If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier. +- 上面的配置只覆盖 DeerFlow 本身；如果你还要本机部署本地大模型，请单独为模型服务预留资源。 +- 持续运行的服务更推荐使用 Linux + Docker。macOS 和 Windows 更适合作为开发机或体验环境。 +- 如果 CPU 或内存长期打满，先降低并发会话或重任务数量，再考虑升级到更高一档配置。 -#### Option 1: Docker (Recommended) +#### 方式一：Docker（推荐） -**Development** (hot-reload, source mounts): +**开发模式**（支持热更新，挂载源码）： ```bash -make docker-init # Pull sandbox image (only once or when image updates) -make docker-start # Start services (auto-detects sandbox mode from config.yaml) +make docker-init # 拉取 sandbox 镜像（首次运行或镜像更新时执行） +make docker-start # 启动服务（会根据 config.yaml 自动判断 sandbox 模式） ``` -`make docker-start` starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`). +如果 `config.yaml` 使用的是 provisioner 模式（`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` 且配置了 `provisioner_url`），`make docker-start` 才会启动 `provisioner`。 -Docker builds use the upstream `uv` registry by default. If you need faster mirrors in restricted networks, export `UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple` and `NPM_REGISTRY=https://registry.npmmirror.com` before running `make docker-init` or `make docker-start`. - -Backend processes automatically pick up `config.yaml` changes on the next config access, so model metadata updates do not require a manual restart during development. - -> [!TIP] -> On Linux, if Docker-based commands fail with `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`, add your user to the `docker` group and re-login before retrying. See [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied) for the full fix. - -**Production** (builds images locally, mounts runtime config and data): +**生产模式**（本地构建镜像，并挂载运行期配置与数据）： ```bash -make up # Build images and start all production services -make down # Stop and remove containers +make up # 构建镜像并启动全部生产服务 +make down # 停止并移除容器 ``` -Access: http://localhost:2026 +> [!NOTE] +> 当前 Agent 运行时嵌入在 Gateway 中运行，`/api/langgraph/*` 会由 nginx 重写到 Gateway 的 LangGraph-compatible API。 -For persistent deployments, configure `database.backend` as `sqlite` or -`postgres`. The selected backend is shared by the LangGraph checkpointer, -LangGraph Store, and DeerFlow application data. The deprecated `checkpointer` -section, when present, overrides the first two for backward compatibility. +访问地址：http://localhost:2026 -The unified nginx endpoint is same-origin by default and does not emit browser CORS headers. If you run a split-origin or port-forwarded browser client, set `GATEWAY_CORS_ORIGINS` to comma-separated exact origins such as `http://localhost:3000`; the Gateway then applies the CORS allowlist and matching CSRF origin checks. +更完整的 Docker 开发说明见 [CONTRIBUTING.md](CONTRIBUTING.md)。 -> [!IMPORTANT] -> The Gateway still owns active run tasks in process, so production defaults to a single Gateway worker (`GATEWAY_WORKERS=1`). The Redis stream bridge (`stream_bridge.type: redis`) shares SSE delivery and `Last-Event-ID` replay across workers, with a rolling retained-buffer TTL (`stream_ttl_seconds`) as a cleanup safety net. Malformed reconnect IDs live-tail new events instead of replaying the retained buffer. It does not make run cancellation, request de-duplication, or IM channel state fully cross-worker by itself; use single-worker Gateway or explicit sticky routing/ownership before raising `GATEWAY_WORKERS`. +#### 方式二：本地开发 -See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide. +如果你更希望直接在本地启动各个服务： -#### Option 2: Local Development +前提：先完成上面的“配置”步骤（`make setup`）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`。可以用 `DEER_FLOW_PROJECT_ROOT` 显式指定项目根目录，也可以用 `DEER_FLOW_CONFIG_PATH` 指向某个具体配置文件。运行期状态默认写到项目根目录下的 `.deer-flow`，可用 `DEER_FLOW_HOME` 覆盖；skills 默认读取项目根目录下的 `skills/`，可用 `DEER_FLOW_SKILLS_PATH` 覆盖。启动前先运行 `make doctor` 校验配置。 +在 Windows 上，请使用 Git Bash 运行本地开发流程。基于 bash 的服务脚本不支持直接在原生 `cmd.exe` 或 PowerShell 中执行，且 WSL 也不保证可用，因为部分脚本依赖 Git for Windows 的 `cygpath` 等工具。 -If you prefer running services locally: - -Prerequisite: complete the "Configuration" steps above first (`make setup`). `make dev` requires a valid `config.yaml` in the project root. Set `DEER_FLOW_PROJECT_ROOT` to define that root explicitly, or `DEER_FLOW_CONFIG_PATH` to point at a specific config file. Runtime state defaults to `.deer-flow` under the project root and can be moved with `DEER_FLOW_HOME`; skills default to `skills/` under the project root and can be moved with `DEER_FLOW_SKILLS_PATH`. Run `make doctor` to verify your setup before starting. -On Windows, run the local development flow from Git Bash. Native `cmd.exe` and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as `cygpath`. - -1. **Check prerequisites**: +1. **检查依赖环境**： ```bash - make check # Verifies Node.js 22+, pnpm, uv, nginx + make check # 校验 Node.js 22+、pnpm、uv、nginx ``` -2. **Install dependencies**: +2. **安装依赖**： ```bash - make install # Install backend + frontend dependencies + pre-commit hooks + make install # 安装 backend + frontend 依赖 ``` -3. **(Optional) Pre-pull sandbox image**: +3. **（可选）预拉取 sandbox 镜像**： ```bash - # Recommended if using Docker/Container-based sandbox + # 如果使用 Docker / Container sandbox，建议先执行 make setup-sandbox ``` -4. **(Optional) Load sample memory data for local review**: - ```bash - python scripts/load_memory_sample.py - ``` - This copies the sample fixture into the default local runtime memory file so reviewers can immediately test `Settings > Memory`. - See [backend/docs/MEMORY_SETTINGS_REVIEW.md](backend/docs/MEMORY_SETTINGS_REVIEW.md) for the shortest review flow. - -5. **Start services**: +4. **启动服务**： ```bash make dev ``` -6. **Access**: http://localhost:2026 +5. **访问地址**：http://localhost:2026 -#### Startup Modes +### 进阶配置 +#### Sandbox 模式 -DeerFlow runs the agent runtime inside the Gateway API. Development mode enables hot-reload; production mode uses a pre-built frontend. +DeerFlow 支持多种 sandbox 执行方式： +- **本地执行**（直接在宿主机上运行 sandbox 代码） +- **Docker 执行**（在隔离的 Docker 容器里运行 sandbox 代码） +- **Docker + Kubernetes 执行**（通过 provisioner 服务在 Kubernetes Pod 中运行 sandbox 代码） -| | **Local Foreground** | **Local Daemon** | **Docker Dev** | **Docker Prod** | -|---|---|---|---|---| -| **Dev** | `./scripts/serve.sh --dev`
`make dev` | `./scripts/serve.sh --dev --daemon`
`make dev-daemon` | `./scripts/docker.sh start`
`make docker-start` | — | -| **Prod** | `./scripts/serve.sh --prod`
`make start` | `./scripts/serve.sh --prod --daemon`
`make start-daemon` | — | `./scripts/deploy.sh`
`make up` | +Docker 开发时，服务启动行为会遵循 `config.yaml` 里的 sandbox 模式。在 Local / Docker 模式下，不会启动 `provisioner`。 -| Action | Local | Docker Dev | Docker Prod | -|---|---|---|---| -| **Stop** | `./scripts/serve.sh --stop`
`make stop` | `./scripts/docker.sh stop`
`make docker-stop` | `./scripts/deploy.sh down`
`make down` | -| **Restart** | `./scripts/serve.sh --restart [flags]` | `./scripts/docker.sh restart` | — | - -Gateway owns `/api/langgraph/*` and translates those public LangGraph-compatible paths to its native `/api/*` routers behind nginx. - -#### Docker Production Deployment - -`deploy.sh` supports building and starting separately: - -```bash -# One-step (build + start) -deploy.sh - -# Two-step (build once, start later) -deploy.sh build # build all images -deploy.sh start # start pre-built images - -# Stop -deploy.sh down -``` - -### Advanced -#### Sandbox Mode - -DeerFlow supports multiple sandbox execution modes: -- **Local Execution** (runs sandbox code directly on the host machine) -- **Docker Execution** (runs sandbox code in isolated Docker containers) -- **Docker Execution with Kubernetes** (runs sandbox code in Kubernetes pods via provisioner service) - -For Docker development, service startup follows `config.yaml` sandbox mode. In Local/Docker modes, `provisioner` is not started. - -See the [Sandbox Configuration Guide](backend/docs/CONFIGURATION.md#sandbox) to configure your preferred mode. +如果要配置你自己的模式，参见 [Sandbox 配置指南](backend/docs/CONFIGURATION.md#sandbox)。 #### MCP Server -DeerFlow supports configurable MCP servers and skills to extend its capabilities. -For HTTP/SSE MCP servers, OAuth token flows are supported (`client_credentials`, `refresh_token`). -For stdio MCP servers, per-tool call timeouts can be configured with `tool_call_timeout`. -MCP routing hints can also prefer a specific MCP tool for matching requests without forbidding other tools. When `tool_search` defers MCP schemas, matching routing metadata can auto-promote up to `tool_search.auto_promote_top_k` deferred schemas before the model call. -See the [MCP Server Guide](backend/docs/MCP_SERVER.md) for detailed instructions. +DeerFlow 支持可配置的 MCP Server 和 skills，用来扩展能力。 +对于 HTTP/SSE MCP Server，还支持 OAuth token 流程（`client_credentials`、`refresh_token`）。 +详细说明见 [MCP Server 指南](backend/docs/MCP_SERVER.md)。 -#### IM Channels +#### IM 渠道 -DeerFlow supports receiving tasks from messaging apps. Channels auto-start when configured — no public IP required for any of them. +DeerFlow 支持从即时通讯应用接收任务。只要配置完成，对应渠道会自动启动，而且都不需要公网 IP。 -DeerFlow can also expose user-owned IM channel connections in the workspace UI. When `channel_connections` is enabled, logged-in users can bind Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, or WeCom from the sidebar / Settings > Channels. It reuses the existing outbound `channels.*` transports, so no public IP or provider callback URL is required. Incoming IM messages then run under the connected DeerFlow user account. See [IM Channel Connections](backend/docs/IM_CHANNEL_CONNECTIONS.md) for setup and security notes. +DeerFlow 还可以在 workspace UI 里暴露用户自有的 IM 渠道连接。启用 `channel_connections` 后，已登录用户可以从侧边栏 / Settings > Channels 绑定 Telegram、Slack、Discord、Feishu/Lark、DingTalk、WeChat 或 WeCom。它复用现有的 `channels.*` 出站传输，因此不需要公网 IP 或 provider 回调地址。入站 IM 消息会以所连接的 DeerFlow 用户身份运行。设置和安全注意事项参见 [IM Channel Connections](backend/docs/IM_CHANNEL_CONNECTIONS.md)。 -| Channel | Transport | Difficulty | +| 渠道 | 传输方式 | 上手难度 | |---------|-----------|------------| -| Telegram | Bot API (long-polling) | Easy | -| Slack | Socket Mode | Moderate | -| Feishu / Lark | WebSocket | Moderate | -| WeChat | Tencent iLink (long-polling) | Moderate | -| WeCom | WebSocket | Moderate | -| DingTalk | Stream Push (WebSocket) | Moderate | +| Telegram | Bot API（long-polling） | 简单 | +| Slack | Socket Mode | 中等 | +| Feishu / Lark | WebSocket | 中等 | +| WeChat | Tencent iLink（long-polling） | 中等 | +| 企业微信智能机器人 | WebSocket | 中等 | +| 钉钉 | Stream Push（WebSocket） | 中等 | -**Configuration in `config.yaml`:** +**`config.yaml` 中的配置示例：** ```yaml channels: - # LangGraph-compatible Gateway API base URL (default: http://localhost:8001/api) + # LangGraph-compatible Gateway API base URL（默认：http://localhost:8001/api） langgraph_url: http://localhost:8001/api - # Gateway API URL (default: http://localhost:8001) + # Gateway API URL（默认：http://localhost:8001） gateway_url: http://localhost:8001 - # Optional: global session defaults for all mobile channels + # 可选：所有移动端渠道共用的全局 session 默认值 session: - assistant_id: lead_agent # or a custom agent name; custom agents are routed via lead_agent + agent_name + assistant_id: lead_agent # 也可以填自定义 agent 名；渠道层会自动转换为 lead_agent + agent_name config: recursion_limit: 100 context: @@ -395,8 +338,8 @@ channels: enabled: true app_id: $FEISHU_APP_ID app_secret: $FEISHU_APP_SECRET - # domain: https://open.feishu.cn # China (default) - # domain: https://open.larksuite.com # International + # domain: https://open.feishu.cn # 国内版（默认） + # domain: https://open.larksuite.com # 国际版 wecom: enabled: true @@ -406,30 +349,17 @@ channels: slack: enabled: true bot_token: $SLACK_BOT_TOKEN # xoxb-... - app_token: $SLACK_APP_TOKEN # xapp-... (Socket Mode) - allowed_users: [] # empty = allow all + app_token: $SLACK_APP_TOKEN # xapp-...（Socket Mode） + allowed_users: [] # 留空表示允许所有人 telegram: enabled: true bot_token: $TELEGRAM_BOT_TOKEN - allowed_users: [] # empty = allow all + allowed_users: [] # 留空表示允许所有人 - wechat: - enabled: false - bot_token: $WECHAT_BOT_TOKEN - ilink_bot_id: $WECHAT_ILINK_BOT_ID - qrcode_login_enabled: true # optional: allow first-time QR bootstrap when bot_token is absent - allowed_users: [] # empty = allow all - 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 - - # Optional: per-channel / per-user session settings + # 可选：按渠道 / 按用户单独覆盖 session 配置 session: - assistant_id: mobile-agent # custom agent names are also supported here + assistant_id: mobile-agent # 这里同样支持自定义 agent 名 context: thinking_enabled: false users: @@ -441,21 +371,32 @@ channels: 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 缺失时允许首次扫码登录引导 + 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 ID of your DingTalk application - client_secret: $DINGTALK_CLIENT_SECRET # Client Secret of your DingTalk application - allowed_users: [] # empty = allow all - card_template_id: "" # Optional: AI Card template ID for streaming typewriter effect + client_id: $DINGTALK_CLIENT_ID # 钉钉开放平台 ClientId + client_secret: $DINGTALK_CLIENT_SECRET # 钉钉开放平台 ClientSecret + allowed_users: [] # 留空表示允许所有人 + card_template_id: "" # 可选：AI 卡片模板 ID，用于流式打字机效果 ``` -Notes: -- `assistant_id: lead_agent` calls the default LangGraph assistant directly. -- If `assistant_id` is set to a custom agent name, DeerFlow still routes through `lead_agent` and injects that value as `agent_name`, so the custom agent's SOUL/config takes effect for IM channels. -- IM channel workers call Gateway's LangGraph-compatible API internally and automatically attach process-local internal auth plus the CSRF cookie/header pair required for thread and run creation. -- Feishu/Lark now queues rapid follow-up messages per mapped DeerFlow `thread_id` instead of immediately surfacing the generic busy reply, and topic replies keep a per-message card with a compact source-message preview across queued/running/final patches. +说明： +- `assistant_id: lead_agent` 会直接调用默认的 LangGraph assistant。 +- 如果 `assistant_id` 填的是自定义 agent 名，DeerFlow 仍然会走 `lead_agent`，同时把该值注入为 `agent_name`，这样 IM 渠道也会生效对应 agent 的 SOUL 和配置。 -Set the corresponding API keys in your `.env` file: +在 `.env` 里设置对应的 API key： ```bash # Telegram @@ -473,93 +414,77 @@ FEISHU_APP_SECRET=your_app_secret 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 +# 钉钉 DINGTALK_CLIENT_ID=your_client_id DINGTALK_CLIENT_SECRET=your_client_secret ``` -**Telegram Setup** +**Telegram 配置** -1. Chat with [@BotFather](https://t.me/BotFather), send `/newbot`, and copy the HTTP API token. -2. Set `TELEGRAM_BOT_TOKEN` in `.env` and enable the channel in `config.yaml`. +1. 打开 [@BotFather](https://t.me/BotFather)，发送 `/newbot`，复制生成的 HTTP API token。 +2. 在 `.env` 中设置 `TELEGRAM_BOT_TOKEN`，并在 `config.yaml` 里启用该渠道。 -**Slack Setup** +**Slack 配置** -1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps) → Create New App → From scratch. -2. Under **OAuth & Permissions**, add Bot Token Scopes: `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `files:write`. -3. Enable **Socket Mode** → generate an App-Level Token (`xapp-…`) with `connections:write` scope. -4. Under **Event Subscriptions**, subscribe to bot events: `app_mention`, `message.im`. -5. Set `SLACK_BOT_TOKEN` and `SLACK_APP_TOKEN` in `.env` and enable the channel in `config.yaml`. +1. 前往 [api.slack.com/apps](https://api.slack.com/apps) 创建 Slack App：Create New App → From scratch。 +2. 在 **OAuth & Permissions** 中添加 Bot Token Scopes：`app_mentions:read`、`chat:write`、`im:history`、`im:read`、`im:write`、`files:write`。 +3. 启用 **Socket Mode**，生成带 `connections:write` 权限的 App-Level Token（`xapp-...`）。 +4. 在 **Event Subscriptions** 中订阅 bot events：`app_mention`、`message.im`。 +5. 在 `.env` 中设置 `SLACK_BOT_TOKEN` 和 `SLACK_APP_TOKEN`，并在 `config.yaml` 中启用该渠道。 -**Feishu / Lark Setup** +**Feishu / Lark 配置** -1. Create an app on [Feishu Open Platform](https://open.feishu.cn/) → enable **Bot** capability. -2. Add permissions: `im:message`, `im:message.p2p_msg:readonly`, `im:resource`. -3. Under **Events**, subscribe to `im.message.receive_v1` and select **Long Connection** mode. -4. Copy the App ID and App Secret. Set `FEISHU_APP_ID` and `FEISHU_APP_SECRET` in `.env` and enable the channel in `config.yaml`. +1. 在 [飞书开放平台](https://open.feishu.cn/) 创建应用，并启用 **Bot** 能力。 +2. 添加权限：`im:message`、`im:message.p2p_msg:readonly`、`im:resource`。 +3. 在 **事件订阅** 中订阅 `im.message.receive_v1`，连接方式选择 **长连接**。 +4. 复制 App ID 和 App Secret，在 `.env` 中设置 `FEISHU_APP_ID` 和 `FEISHU_APP_SECRET`，并在 `config.yaml` 中启用该渠道。 -**WeChat Setup** +**WeChat 配置** -1. Enable the `wechat` channel in `config.yaml`. -2. Either set `WECHAT_BOT_TOKEN` in `.env`, or set `qrcode_login_enabled: true` for first-time QR bootstrap. -3. When `bot_token` is absent and QR bootstrap is enabled, watch backend logs for the QR content returned by iLink and complete the binding flow. -4. After the QR flow succeeds, DeerFlow persists the acquired token under `state_dir` for later restarts. -5. For Docker Compose deployments, keep `state_dir` on a persistent volume so the `get_updates_buf` cursor and saved auth state survive restarts. +1. 在 `config.yaml` 中启用 `wechat` 渠道。 +2. 在 `.env` 中设置 `WECHAT_BOT_TOKEN`，或者把 `qrcode_login_enabled` 设为 `true` 以便首次扫码登录引导。 +3. 当 `bot_token` 缺失且启用了扫码引导时，留意后端日志里 iLink 返回的二维码内容，并完成绑定流程。 +4. 扫码流程成功后，DeerFlow 会把获取到的 token 持久化到 `state_dir`，便于后续重启复用。 +5. Docker Compose 部署时，请把 `state_dir` 放在持久化卷上，这样 `get_updates_buf` 游标和已保存的登录状态才能在重启后保留。 -**WeCom Setup** +**企业微信智能机器人配置** -1. Create a bot on the WeCom AI Bot platform and obtain the `bot_id` and `bot_secret`. -2. Enable `channels.wecom` in `config.yaml` and fill in `bot_id` / `bot_secret`. -3. Set `WECOM_BOT_ID` and `WECOM_BOT_SECRET` in `.env`. -4. Make sure backend dependencies include `wecom-aibot-python-sdk`. The channel uses a WebSocket long connection and does not require a public callback URL. -5. The current integration supports inbound text, image, and file messages. Final images/files generated by the agent are also sent back to the WeCom conversation. +1. 在企业微信智能机器人平台创建机器人，获取 `bot_id` 和 `bot_secret`。 +2. 在 `config.yaml` 中启用 `channels.wecom`，并填入 `bot_id` / `bot_secret`。 +3. 在 `.env` 中设置 `WECOM_BOT_ID` 和 `WECOM_BOT_SECRET`。 +4. 安装后端依赖时确保包含 `wecom-aibot-python-sdk`，渠道会通过 WebSocket 长连接接收消息，无需公网回调地址。 +5. 当前支持文本、图片和文件入站消息；agent 生成的最终图片/文件也会回传到企业微信会话中。 -**DingTalk Setup** +**钉钉配置** -1. Create a DingTalk application in the [DingTalk Developer Console](https://open.dingtalk.com/) and enable **Robot** capability. -2. Set the message receiving mode to **Stream Mode** in the robot configuration page. -3. Copy the `Client ID` and `Client Secret`, set `DINGTALK_CLIENT_ID` and `DINGTALK_CLIENT_SECRET` in `.env`, and enable the channel in `config.yaml`. -4. *(Optional)* To enable streaming AI Card replies (typewriter effect), create an **AI Card** template on the [DingTalk Card Platform](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card), then set `card_template_id` in `config.yaml` to the template ID. You also need to apply for the `Card.Streaming.Write` and `Card.Instance.Write` permissions. +1. 在 [钉钉开放平台](https://open.dingtalk.com/) 创建应用，并启用 **机器人** 能力。 +2. 在机器人配置页面设置消息接收模式为 **Stream模式**。 +3. 复制 `Client ID` 和 `Client Secret`，在 `.env` 中设置 `DINGTALK_CLIENT_ID` 和 `DINGTALK_CLIENT_SECRET`，并在 `config.yaml` 中启用该渠道。 +4. *（可选）* 如需开启流式 AI 卡片回复（打字机效果），请在[钉钉卡片平台](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card)创建 **AI 卡片**模板，然后在 `config.yaml` 中将 `card_template_id` 设为该模板 ID。同时需要申请 `Card.Streaming.Write` 和 `Card.Instance.Write` 权限。 +**命令** -When DeerFlow runs in Docker Compose, IM channels execute inside the `gateway` container. In that case, do not point `channels.langgraph_url` or `channels.gateway_url` at `localhost`; use container service names such as `http://gateway:8001/api` and `http://gateway:8001`, or set `DEER_FLOW_CHANNELS_LANGGRAPH_URL` and `DEER_FLOW_CHANNELS_GATEWAY_URL`. +渠道连接完成后，你可以直接在聊天窗口里和 DeerFlow 交互： -**Commands** - -Once a channel is connected, you can interact with DeerFlow directly from the chat: - -| Command | Description | +| 命令 | 说明 | |---------|-------------| -| `/new` | Start a new conversation | -| `/status` | Show current thread info | -| `/models` | List available models | -| `/memory` | View memory | -| `/help` | Show help | +| `/new` | 开启新对话 | +| `/status` | 查看当前 thread 信息 | +| `/models` | 列出可用模型 | +| `/memory` | 查看 memory | +| `/help` | 查看帮助 | -> Messages without a command prefix are treated as regular chat — DeerFlow creates a thread and responds conversationally. +> 没有命令前缀的消息会被当作普通聊天处理。DeerFlow 会自动创建 thread，并以对话方式回复。 -#### Request Trace Correlation +#### LangSmith 链路追踪 -Gateway request trace correlation is disabled by default so existing HTTP responses and log formats stay unchanged. To enable it, set: +DeerFlow 内置了 [LangSmith](https://smith.langchain.com) 集成，用于可观测性。启用后，所有 LLM 调用、agent 运行和工具执行都会被追踪，并在 LangSmith 仪表盘中展示。 -```yaml -logging: - enhance: - enabled: true - format: text -``` - -When enabled, every Gateway HTTP response includes `X-Trace-Id`, logs include `trace_id`, and Langfuse traces created by that request include `metadata.deerflow_trace_id` with the same value. - -#### LangSmith Tracing - -DeerFlow has built-in [LangSmith](https://smith.langchain.com) integration for observability. When enabled, all LLM calls, agent runs, and tool executions are traced and visible in the LangSmith dashboard. - -Add the following to your `.env` file: +在 `.env` 文件中添加以下配置： ```bash LANGSMITH_TRACING=true @@ -568,11 +493,11 @@ LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx LANGSMITH_PROJECT=xxx ``` -#### Langfuse Tracing +#### Langfuse 链路追踪 -DeerFlow also supports [Langfuse](https://langfuse.com) observability for LangChain-compatible runs. +DeerFlow 同样支持 [Langfuse](https://langfuse.com) 可观测性，适用于兼容 LangChain 的运行。 -Add the following to your `.env` file: +在 `.env` 文件中添加以下配置： ```bash LANGFUSE_TRACING=true @@ -581,75 +506,58 @@ LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx LANGFUSE_BASE_URL=https://cloud.langfuse.com ``` -If you are using a self-hosted Langfuse instance, set `LANGFUSE_BASE_URL` to your deployment URL. +如果你使用自托管的 Langfuse 实例，请将 `LANGFUSE_BASE_URL` 设置为你的部署地址。 -**Trace correlation fields.** Every agent run is annotated with Langfuse's reserved trace attributes so the Sessions and Users pages light up automatically: +**链路关联字段。** 每次 agent 运行都会标注 Langfuse 的保留追踪属性，这样 Sessions 和 Users 页面就能自动填充数据： -- `session_id` = LangGraph `thread_id` — groups every trace of the same conversation -- `user_id` = effective user from `get_effective_user_id()` (falls back to `default` in no-auth mode) -- `trace_name` = assistant id (defaults to `lead-agent`) -- `tags` = `[env:, model:]` (omitted when not set) -- `metadata.deerflow_trace_id` = DeerFlow request correlation id, matching `X-Trace-Id` when request trace correlation is enabled +- `session_id` = LangGraph 的 `thread_id`——将同一会话的所有 trace 归为一组 +- `user_id` = 来自 `get_effective_user_id()` 的有效用户（在无鉴权模式下回退为 `default`） +- `trace_name` = assistant id（默认为 `lead-agent`） +- `tags` = `[env:, model:]`（未设置时省略） +- `metadata.deerflow_trace_id` = DeerFlow 的请求关联 id，当启用请求链路关联（request trace correlation）时与 `X-Trace-Id` 一致 -These are injected into `RunnableConfig.metadata` at the graph invocation root for both the gateway path (`runtime/runs/worker.py::run_agent`) and the embedded path (`client.py::DeerFlowClient.stream`), so any LangChain-compatible callback can read them. Set `DEER_FLOW_ENV` (or `ENVIRONMENT`) to tag traces by deployment environment. +这些字段会在图（graph）调用的根部注入到 `RunnableConfig.metadata`，同时覆盖 gateway 路径（`runtime/runs/worker.py::run_agent`）和内嵌路径（`client.py::DeerFlowClient.stream`），因此任何兼容 LangChain 的 callback 都能读取到它们。设置 `DEER_FLOW_ENV`（或 `ENVIRONMENT`）可按部署环境为 trace 打标签。 -#### Using Both Providers +#### 同时使用两种追踪服务 -If both LangSmith and Langfuse are enabled, DeerFlow attaches both tracing callbacks and reports the same model activity to both systems. +如果同时启用 LangSmith 和 Langfuse，DeerFlow 会挂载两个追踪 callback，并将相同的模型活动上报到两个系统。 -If a provider is explicitly enabled but missing required credentials, or if its callback fails to initialize, DeerFlow fails fast when tracing is initialized during model creation and the error message names the provider that caused the failure. +如果某个 provider 被显式启用但缺少必要的凭据，或其 callback 初始化失败，DeerFlow 会在创建模型、初始化追踪时快速失败（fail fast），错误信息会指明导致失败的 provider。 -For Docker deployments, tracing is disabled by default. Set `LANGSMITH_TRACING=true` and `LANGSMITH_API_KEY` in your `.env` to enable it. +Docker 部署时，追踪默认关闭。在 `.env` 中设置 `LANGSMITH_TRACING=true` 和 `LANGSMITH_API_KEY` 即可启用。 -## From Deep Research to Super Agent Harness +## 从 Deep Research 到 Super Agent Harness -DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated. +DeerFlow 最初是一个 Deep Research 框架，后来社区把它一路推到了更远的地方。上线之后，开发者拿它去做的事情早就不止研究：搭数据流水线、生成演示文稿、快速起 dashboard、自动化内容流程，很多方向一开始连我们自己都没想到。 -That told us something important: DeerFlow wasn't just a research tool. It was a **harness** — a runtime that gives agents the infrastructure to actually get work done. +这让我们意识到一件事：DeerFlow 不只是一个研究工具。它更像一个 **harness**，一个真正让 agents 把事情做完的运行时基础设施。 -So we rebuilt it from scratch. +所以我们把它从头重做了一遍。 -DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks. +DeerFlow 2.0 不再是一个需要你自己拼装的 framework。它是一个开箱即用、同时又足够可扩展的 super agent harness。基于 LangGraph 和 LangChain 构建，默认就带上了 agent 真正会用到的关键能力：文件系统、memory、skills、sandbox 执行环境，以及为复杂多步骤任务做规划、拉起 sub-agents 的能力。 -Use it as-is. Or tear it apart and make it yours. +你可以直接拿来用，也可以拆开重组，改成你自己的样子。 -## Core Features +## 核心特性 -### Skills & Tools +### Skills 与 Tools -Skills are what make DeerFlow do *almost anything*. +Skills 是 DeerFlow 能做“几乎任何事”的关键。 -A standard Agent Skill is a structured capability module — a Markdown file that defines a workflow, best practices, and references to supporting resources. DeerFlow ships with built-in skills for research, report generation, slide creation, web pages, image and video generation, and more. But the real power is extensibility: add your own skills, replace the built-in ones, or combine them into compound workflows. +标准的 Agent Skill 是一种结构化能力模块，通常就是一个 Markdown 文件，里面定义了工作流、最佳实践，以及相关的参考资源。DeerFlow 自带一批内置 skills，覆盖研究、报告生成、演示文稿制作、网页生成、图像和视频生成等场景。真正有意思的地方在于它的扩展性：你可以加自己的 skills，替换内置 skills，或者把多个 skills 组合成复合工作流。 -Skills are loaded progressively — only when the task needs them, not all at once. This keeps the context window lean and makes DeerFlow work well even with token-sensitive models. +Skills 采用按需渐进加载，不会一次性把所有内容都塞进上下文。只有任务确实需要时才加载，这样能把上下文窗口控制得更干净，也更适合对 token 比较敏感的模型。 -Users can explicitly activate an enabled skill for a single turn by starting the request with `/skill-name`, for example `/data-analysis analyze uploads/foo.csv`. DeerFlow loads that skill's `SKILL.md` as hidden current-turn context while leaving the base prompt limited to skill metadata. Slash activation respects disabled skills, custom-agent skill whitelists, and existing channel commands such as `/new` and `/help`. +通过 Gateway 安装 `.skill` 压缩包时，DeerFlow 会接受标准的可选 frontmatter 元数据，比如 `version`、`author`、`compatibility`，不会把本来合法的外部 skill 拒之门外。 -When you install `.skill` archives through the Gateway, DeerFlow accepts standard optional frontmatter metadata such as `version`, `author`, and `compatibility` instead of rejecting otherwise valid external skills. +Tools 也是同样的思路。DeerFlow 自带一组核心工具：网页搜索、网页抓取、网页渲染截图、文件操作、bash 执行；同时也支持通过 MCP Server 和 Python 函数扩展自定义工具。你可以替换任何一项，也可以继续往里加。 -Skill installs and agent-managed skill edits run through **SkillScan**, a native deterministic safety scanner before the LLM-based skill scanner. Phase 1 runs offline with no Semgrep/OpenGrep dependency, blocks high-confidence `CRITICAL` findings such as private keys or shell execution, and passes warning findings to the LLM scanner for contextual review. Set `skill_scan.enabled: false` in `config.yaml` to disable only the deterministic analyzers; safe archive extraction and the LLM scanner still run. +Gateway 生成后续建议时，现在会先把普通字符串输出和 block/list 风格的富文本内容统一归一化，再去解析 JSON 数组响应，因此不同 provider 的内容包装方式不会再悄悄把建议吞掉。 -DeerFlow also ships with **skill-reviewer**, a public skill for read-only skill quality review. It uses the built-in `review_skill_package` tool to inspect installed skills, local packages, archives, or pasted `SKILL.md` content without activating the target skill, binding its secrets, executing its scripts, or installing it. The tool returns a compact, tag-neutralized JSON payload to the model context and keeps the full raw review payload in the tool artifact for programmatic consumers. The deterministic review core reuses DeerFlow parsing and SkillScan facts, emits versioned JSON contracts under `contracts/skill_review/`, and can be run from the backend CLI: +Web UI 支持从已完成的 assistant 回复分叉出一个新的主对话。新 thread 会从该回复对应的 checkpoint 开始，并尽力复制当前 thread 的工作区文件。 -```bash -cd backend -uv run python -m deerflow.skills.review.cli ../skills/public/data-analysis --format text --fail-on error --fail-on-incomplete -``` - -Tools follow the same philosophy. DeerFlow comes with a core toolset — web search, web fetch, rendered web capture, file operations, bash execution — and supports custom tools via MCP servers and Python functions. Swap anything. Add anything. - -Gateway-generated follow-up suggestions now normalize both plain-string model output and block/list-style rich content before parsing the JSON array response, so provider-specific content wrappers do not silently drop suggestions. - -The Web UI composer can polish draft input before sending. The rewrite runs as a short Gateway LLM request using the `input_polish` model configuration, keeps slash skill prefixes such as `/data-analysis`, and only replaces the local draft after the user clicks the polish button; it does not create a thread run or persist a message. - -The Web UI composer also supports browser-based voice dictation when the browser exposes the Web Speech API. The microphone button transcribes speech into the local draft only; DeerFlow receives only the transcribed text, while audio handling is delegated to the browser or operating system speech-recognition service according to that environment's policy. Users can review or edit the text before sending. - -Interrupted first-turn runs still persist a fallback conversation title, so stopping a streaming response does not leave the thread as "Untitled" after refresh. - -In the Web UI, completed assistant turns can be branched into a new main conversation. The new thread starts from that turn's checkpoint. Because workspace files are not checkpointed, the branch only receives a best-effort copy of the current workspace when you branch from the latest turn; branching from an older turn keeps just the restored message history so the branch never inherits files that were created in a later part of the conversation. - -``` -# Paths inside the sandbox container +```text +# sandbox 容器内的路径 /mnt/skills/public ├── research/SKILL.md ├── report-generation/SKILL.md @@ -658,116 +566,108 @@ In the Web UI, completed assistant turns can be branched into a new main convers └── image-generation/SKILL.md /mnt/skills/custom -└── your-custom-skill/SKILL.md ← yours +└── your-custom-skill/SKILL.md ← 你的 skill ``` -#### Claude Code Integration +#### Claude Code 集成 -The `claude-to-deerflow` skill lets you interact with a running DeerFlow instance directly from [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Send research tasks, check status, manage threads — all without leaving the terminal. +借助 `claude-to-deerflow` skill，你可以直接在 [Claude Code](https://docs.anthropic.com/en/docs/claude-code) 里和正在运行的 DeerFlow 实例交互。不用离开终端，就能下发研究任务、查看状态、管理 threads。 -**Install the skill**: +**安装这个 skill：** ```bash npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow ``` -Then make sure DeerFlow is running (default at `http://localhost:2026`) and use the `/claude-to-deerflow` command in Claude Code. +然后确认 DeerFlow 已经启动（默认地址是 `http://localhost:2026`），在 Claude Code 里使用 `/claude-to-deerflow` 命令即可。 -**What you can do**: -- Send messages to DeerFlow and get streaming responses -- Choose execution modes: flash (fast), standard, pro (planning), ultra (sub-agents) -- Check DeerFlow health, list models/skills/agents -- Manage threads and conversation history -- Upload files for analysis +**你可以做的事情包括：** +- 给 DeerFlow 发送消息，并接收流式响应 +- 选择执行模式：flash（更快）、standard、pro（规划模式）、ultra（sub-agents 模式） +- 检查 DeerFlow 健康状态，列出 models / skills / agents +- 管理 threads 和会话历史 +- 上传文件做分析 -**Environment variables** (optional, for custom endpoints): +**环境变量**（可选，用于自定义端点）： ```bash -DEERFLOW_URL=http://localhost:2026 # Unified proxy base URL +DEERFLOW_URL=http://localhost:2026 # 统一代理基地址 DEERFLOW_GATEWAY_URL=http://localhost:2026 # Gateway API DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph # LangGraph API ``` -See [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md) for the full API reference. +完整 API 说明见 [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md)。 + +Web UI 输入框支持浏览器侧语音听写。浏览器提供 Web Speech API 时，麦克风按钮会把语音转写为本地草稿；DeerFlow 只接收转写后的文本，音频处理交由浏览器或操作系统语音识别服务按其环境策略完成。用户可以在发送前继续检查和编辑文本。 ### Session Goals -Use `/goal ` to attach one active completion condition to the current thread. The goal is thread-scoped state, not a skill activation, so it stays active across turns until DeerFlow determines it has been satisfied or you clear it. +用 `/goal <完成条件>` 为当前 thread 绑定一个激活态的完成条件。这个 goal 是 thread 维度的状态，而不是技能激活，所以它会跨轮次持续生效，直到 DeerFlow 判定它已被满足、或者你手动清除它。 -Supported commands: +支持的命令： ```text /goal finish the implementation and make all tests pass -/goal # show the active goal -/goal clear # clear it +/goal # 查看当前激活的 goal +/goal clear # 清除它 ``` -After each Gateway-backed run, DeerFlow evaluates the visible conversation against the active goal with a non-thinking evaluator model. The evaluator must return a typed blocker (`missing_evidence`, `needs_user_input`, `run_failed`, `external_wait`, or `goal_not_met_yet`) plus visible evidence. DeerFlow only injects a hidden continuation when the latest assistant turn is durably checkpointed, the blocker is `goal_not_met_yet`, the thread did not change during evaluation, and the no-progress breaker has not fired. The safety cap defaults to 8 hidden continuations, and repeated identical non-progress evaluations stop after 2 attempts. `/goal clear` and any user-authored new input win over queued continuations. When the goal is satisfied, DeerFlow clears it automatically and publishes the updated thread state. +每次 Gateway 驱动的 run 结束后，DeerFlow 会用一个 non-thinking 的评估模型，把可见的对话内容拿去和激活的 goal 比对。评估模型必须返回一个带类型的 blocker（`missing_evidence`、`needs_user_input`、`run_failed`、`external_wait` 或 `goal_not_met_yet`），并附上可见证据。只有在最近一轮 assistant 回复已被持久化 checkpoint、blocker 是 `goal_not_met_yet`、评估期间 thread 没有变化、且无进展熔断器没有触发时，DeerFlow 才会注入一次 hidden continuation。安全上限默认是 8 次 hidden continuation；连续两次相同的无进展评估后就会停止。`/goal clear` 以及任何用户手动输入的新内容，优先级都高于排队中的 continuation。当 goal 被满足时，DeerFlow 会自动清除它，并发布更新后的 thread 状态。 -The Web UI shows the active goal above the composer. The same command is available from the TUI and supported IM channels. In the Web UI and supported IM channels, setting `/goal ` also starts a run with the condition as the task; status and clear commands only manage goal state. +Web UI 会在输入框上方展示当前激活的 goal。同样的命令在 TUI 和受支持的 IM 渠道里也可用。在 Web UI 和受支持的 IM 渠道里，设置 `/goal <完成条件>` 还会以该条件作为任务启动一次 run；状态查询和清除命令则只管理 goal 状态本身。 -### Manual Context Compaction +### 手动上下文压缩 -Use `/compact` in the Web UI composer to summarize older context for the current thread. DeerFlow keeps the full chat visible, but future model calls use the compacted summary plus recent messages. The command is ignored when there is not enough history to compact, and it is blocked while the thread has a run in flight. +在 Web UI 输入框中使用 `/compact`，可以把当前 thread 的早期上下文压缩成摘要。完整聊天记录仍会保留在界面上，但后续模型调用会基于压缩摘要和最近消息继续。当前历史不足时不会压缩；thread 正在运行任务时会阻止压缩。 ### Sub-Agents -Complex tasks rarely fit in a single pass. DeerFlow decomposes them. +复杂任务通常不可能一次完成，DeerFlow 会先拆解，再执行。 -The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output. Long-running sub-agents compact older history when summarization is enabled and re-inject the summary as guarded, hidden durable context before continuing, so recent assistant/tool activity remains grounded in the task. Provider/model request failures are reported as failed sub-agent tasks rather than successful results, so the lead agent and Web UI can react to them correctly. Collapsed sub-agent cards show the effective model and, when the provider returns usage metadata, a cumulative token total that updates after each completed sub-agent LLM call and persists after a reload. When token usage tracking is enabled, completed sub-agent usage is also attributed back to the dispatching step. +lead agent 可以按需动态拉起 sub-agents。每个 sub-agent 都有自己独立的上下文、工具和终止条件。只要条件允许，它们就会并行运行，返回结构化结果，最后再由 lead agent 汇总成一份完整输出。 -This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report — or a website — or a slide deck with generated visuals. One harness, many hands. +这也是 DeerFlow 能处理从几分钟到几小时任务的原因。比如一个研究任务，可以拆成十几个 sub-agents，分别探索不同方向，最后合并成一份报告，或者一个网站，或者一套带生成视觉内容的演示文稿。一个 harness，多路并行。 -### Sandbox & File System +### Sandbox 与文件系统 -DeerFlow doesn't just *talk* about doing things. It has its own computer. +DeerFlow 不只是“会说它能做”，它是真的有一台自己的“电脑”。 -Each task gets its own execution environment with a full filesystem view — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It can view images and, when configured safely, execute shell commands. +每个任务都运行在隔离的 Docker 容器里，里面有完整的文件系统，包括 skills、workspace、uploads、outputs。agent 可以读写和编辑文件，可以执行 bash 命令和代码，也可以查看图片。整个过程都在 sandbox 内完成，可审计、会隔离，不会在不同 session 之间互相污染。 -After each run, DeerFlow records a workspace change summary for the run-owned `workspace` and `outputs` directories. The Web UI shows a compact "files changed" badge on the assistant turn; opening it reveals created, modified, and deleted files with text diffs when safe to display. Uploads are excluded because they are user inputs, not agent-generated changes. Large, binary, or sensitive-looking files are shown as metadata only. +这就是“带工具的聊天机器人”和“真正有执行环境的 agent”之间的差别。 -With `AioSandboxProvider`, shell execution runs inside isolated containers. With `LocalSandboxProvider`, file tools still map to per-thread directories on the host, but host `bash` is disabled by default because it is not a secure isolation boundary. Re-enable host bash only for fully trusted local workflows. Host bash commands have a wall-clock timeout, and long-lived processes should be started in the background with output redirected to a workspace log. - -This is the difference between a chatbot with tool access and an agent with an actual execution environment. - -``` -# Paths inside the sandbox container +```text +# sandbox 容器内的路径 /mnt/user-data/ -├── uploads/ ← your files -├── workspace/ ← agents' working directory -└── outputs/ ← final deliverables +├── uploads/ ← 你的文件 +├── workspace/ ← agents 的工作目录 +└── outputs/ ← 最终交付物 ``` ### Context Engineering -**Isolated Sub-Agent Context**: Each sub-agent runs in its own isolated context. This means that the sub-agent will not be able to see the context of the main agent or other sub-agents. This is important to ensure that the sub-agent is able to focus on the task at hand and not be distracted by the context of the main agent or other sub-agents. +**隔离的 Sub-Agent Context**：每个 sub-agent 都在自己独立的上下文里运行。它看不到主 agent 的上下文，也看不到其他 sub-agents 的上下文。这样做的目的很直接，就是让它只聚焦当前任务，不被无关信息干扰。 -**Summarization**: Within a session, DeerFlow manages context aggressively — summarizing completed sub-tasks, offloading intermediate results to the filesystem, compressing what's no longer immediately relevant. This lets it stay sharp across long, multi-step tasks without blowing the context window. +**摘要压缩**：在单个 session 内，DeerFlow 会比较积极地管理上下文，包括总结已完成的子任务、把中间结果转存到文件系统、压缩暂时不重要的信息。这样在长链路、多步骤任务里，它也能保持聚焦，而不会轻易把上下文窗口打爆。 -**Strict Tool-Call Recovery**: When a provider or middleware interrupts a tool-call loop, DeerFlow now strips provider-level raw tool-call metadata on forced-stop assistant messages and injects placeholder tool results for dangling calls before the next model invocation. This keeps OpenAI-compatible reasoning models that strictly validate `tool_call_id` sequences from failing with malformed history errors. +### 长期记忆 -**Visible Tool-Run Completion**: For interactive turns, DeerFlow retries an empty post-tool final response once, then surfaces a visible error instead of reporting a silent successful run. +大多数 agents 会在对话结束后把一切都忘掉，DeerFlow 不一样。 -### Long-Term Memory +跨 session 使用时，DeerFlow 会逐步积累关于你的持久 memory，包括你的个人偏好、知识背景，以及长期沉淀下来的工作习惯。你用得越多，它越了解你的写作风格、技术栈和重复出现的工作流。memory 保存在本地，控制权也始终在你手里。 -Most agents forget everything the moment a conversation ends. DeerFlow remembers. +## 推荐模型 -Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you — your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control. +DeerFlow 对模型没有强绑定，只要实现了 OpenAI 兼容 API 的 LLM，理论上都可以接入。不过在下面这些能力上表现更强的模型，通常会更适合 DeerFlow： -Memory updates now skip duplicate fact entries at apply time, so repeated preferences and context do not accumulate endlessly across sessions. +- **长上下文窗口**（100k+ tokens），适合深度研究和多步骤任务 +- **推理能力**，适合自适应规划和复杂拆解 +- **多模态输入**，适合理解图片和视频 +- **稳定的 tool use 能力**，适合可靠的函数调用和结构化输出 -## Recommended Models +## 内嵌 Python Client -DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support: - -- **Long context windows** (100k+ tokens) for deep research and multi-step tasks -- **Reasoning capabilities** for adaptive planning and complex decomposition -- **Multimodal inputs** for image understanding and video comprehension -- **Strong tool-use** for reliable function calling and structured outputs - -## Embedded Python Client - -DeerFlow can be used as an embedded Python library without running the full HTTP services. The `DeerFlowClient` provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API. The HTTP Gateway also exposes `DELETE /api/threads/{thread_id}` to remove DeerFlow-managed local thread data after the LangGraph thread itself has been deleted: +DeerFlow 也可以作为内嵌的 Python 库使用，不必启动完整的 HTTP 服务。`DeerFlowClient` 提供了进程内的直接访问方式，覆盖所有 agent 和 Gateway 能力，返回的数据结构与 HTTP Gateway API 保持一致。HTTP Gateway 还提供 `DELETE /api/threads/{thread_id}`，用于在 LangGraph thread 本身被删除之后，清理 DeerFlow 托管的本地 thread 数据： ```python from deerflow.client import DeerFlowClient @@ -777,12 +677,12 @@ client = DeerFlowClient() # Chat response = client.chat("Analyze this paper for me", thread_id="my-thread") -# Streaming (LangGraph SSE protocol: values, messages-tuple, end) +# Streaming（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"]) -# Configuration & management — returns Gateway-aligned dicts +# 配置与管理：返回值与 Gateway 对齐的 dict models = client.list_models() # {"models": [...]} skills = client.list_skills() # {"skills": [...]} client.update_skill("web-search", enabled=True) @@ -792,113 +692,104 @@ client.get_goal("thread-1") # {"goal": {...}} or {"goal": None} client.clear_goal("thread-1") ``` -All dict-returning methods are validated against Gateway Pydantic response models in CI (`TestGatewayConformance`), ensuring the embedded client stays in sync with the HTTP API schemas. See `backend/packages/harness/deerflow/client.py` for full API documentation. +所有返回 dict 的方法都会在 CI 中通过 Gateway 的 Pydantic 响应模型校验（`TestGatewayConformance`），以确保内嵌 client 始终和 HTTP API schema 保持同步。完整 API 说明见 `backend/packages/harness/deerflow/client.py`。 -## Scheduled Tasks +## 定时任务 (Scheduled Tasks) -DeerFlow now includes a first-class scheduled-task MVP in the workspace. +DeerFlow 现在在 workspace 里内置了一个一等的定时任务（scheduled-task）MVP。 -Current MVP capabilities: +当前 MVP 能力： -- Manage tasks at `/workspace/scheduled-tasks` -- Choose whether each scheduled task reuses a thread or creates a fresh thread per run -- Support `once` and `cron` schedules -- Run background scheduled executions as non-interactive DeerFlow runs (`ask_clarification` is not exposed there) -- Use `skip` overlap behavior for due cron executions that collide with an active run on the same reused thread -- Pause, resume, trigger, inspect history, and delete tasks -- Execute scheduled work through the normal DeerFlow run lifecycle +- 在 `/workspace/scheduled-tasks` 管理任务 +- 每个定时任务可以选择复用同一个 thread，也可以选择每次运行新建一个 thread +- 支持 `once` 和 `cron` 两种调度方式 +- 后台定时执行以非交互式 DeerFlow run 运行（那里不会暴露 `ask_clarification`） +- 当到期的 cron 执行与同一复用 thread 上的活跃 run 冲突时，采用 `skip` 的重叠处理策略 +- 支持暂停、恢复、手动触发、查看历史和删除任务 +- 定时任务通过正常的 DeerFlow run 生命周期执行 -Current MVP limits: +当前 MVP 限制： -- No conversation-created `schedule_task` tool yet -- No text-only notification jobs -- No channel or GitHub dispatch targets -- No `interval` schedule type in this first cut +- 暂时还没有可在对话中创建任务的 `schedule_task` 工具 +- 没有纯文本通知任务 +- 没有渠道或 GitHub 分发目标 +- 第一版没有 `interval` 调度类型 -Enable background polling with `config.yaml -> scheduler.enabled`. Manual trigger uses the same scheduled-task resource and execution path. +通过 `config.yaml -> scheduler.enabled` 开启后台轮询。手动触发使用同样的 scheduled-task 资源和执行路径。 -## Terminal Workbench (TUI) +## 终端工作台 (TUI) -`deerflow` is a terminal-native workbench for people who live in the shell. It runs **embedded** over `DeerFlowClient` — no Gateway, frontend, nginx, or Docker required — while honoring the same `config.yaml`, checkpointer, skills, memory, MCP, and sandbox settings as the rest of DeerFlow. +`deerflow` 是一个面向终端用户的工作台，**内嵌**运行在 `DeerFlowClient` 之上——无需启动 Gateway、前端、nginx 或 Docker，同时沿用与 DeerFlow 其它部分相同的 `config.yaml`、checkpointer、技能、记忆、MCP 和沙箱配置。 ![DeerFlow TUI](docs/tui/tui-preview.svg) ```bash -uv pip install 'deerflow-harness[tui]' # optional 'textual' dependency +uv pip install 'deerflow-harness[tui]' # 可选的 'textual' 依赖 -deerflow # launch the terminal UI (TTY required) -deerflow --continue # resume the most recent thread -deerflow --resume THREAD # resume a thread by id -deerflow --print "summarize this repo" # headless one-shot answer to stdout -deerflow --json "hello" # headless newline-delimited StreamEvents +deerflow # 启动终端 UI（需要 TTY） +deerflow --continue # 恢复最近一次会话 +deerflow --resume THREAD # 按 id 恢复指定会话 +deerflow --print "总结一下这个仓库" # 无头模式，结果打印到 stdout +deerflow --json "hello" # 无头模式，输出按行分隔的 StreamEvent ``` -A keyboard-driven chat surface with a streaming transcript (Markdown-rendered answers), compact tool-activity cards, a `/` slash-command palette, `/goal` goal management, `/model` and `/threads` pickers, input history, and `Esc` / `Ctrl+C` interrupt. Sessions opened in the TUI also appear in the Web UI sidebar — it writes the shared thread store under the local default user, so terminal and web stay in sync **without running the Gateway**. +键盘驱动的对话界面：流式渲染的对话区（回答按 Markdown 渲染）、紧凑的工具活动卡片、`/` 斜杠命令面板、`/model` 与 `/threads` 选择器、输入历史，以及 `Esc` / `Ctrl+C` 打断。在 TUI 里开启的会话也会出现在 Web UI 侧边栏——它会以本地默认用户身份写入共享的会话存储，因此终端与网页保持同步，**无需运行 Gateway**。 -See [backend/docs/TUI.md](backend/docs/TUI.md) for the full guide. +完整说明见 [backend/docs/TUI.md](backend/docs/TUI.md)。 -## Documentation +## 文档 -- [Contributing Guide](CONTRIBUTING.md) - Development environment setup and workflow -- [Configuration Guide](backend/docs/CONFIGURATION.md) - Setup and configuration instructions -- [Architecture Overview](backend/CLAUDE.md) - Technical architecture details -- [Backend Architecture](backend/README.md) - Backend architecture and API reference +- [贡献指南](CONTRIBUTING.md) - 开发环境搭建与协作流程 +- [配置指南](backend/docs/CONFIGURATION.md) - 安装与配置说明 +- [架构概览](backend/CLAUDE.md) - 技术架构说明 +- [后端架构](backend/README.md) - 后端架构与 API 参考 -## ⚠️ Security Notice +## ⚠️ 安全使用 -### Improper Deployment May Introduce Security Risks +### 不恰当的部署可能导致安全风险 -DeerFlow has key high-privilege capabilities including **system command execution, resource operations, and business logic invocation**, and is designed by default to be **deployed in a local trusted environment (accessible only via the 127.0.0.1 loopback interface)**. If you deploy the agent in untrusted environments — such as LAN networks, public cloud servers, or other multi-endpoint accessible environments — without strict security measures, it may introduce security risks, including: +DeerFlow 具备**系统指令执行、资源操作、业务逻辑调用**等关键高权限能力，默认设计为**部署在本地可信环境（仅本机 127.0.0.1 回环访问）**。若您将 agent 部署至不可信局域网、公网云服务器等可被多终端访问的网络环境，且未采取严格的安全防护措施，可能导致安全风险，例如： -- **Unauthorized illegal invocation**: Agent functionality could be discovered by unauthorized third parties or malicious internet scanners, triggering bulk unauthorized requests that execute high-risk operations such as system commands and file read/write, potentially causing serious security consequences. -- **Compliance and legal risks**: If the agent is illegally invoked to conduct cyberattacks, data theft, or other illegal activities, it may result in legal liability and compliance risks. +- **未授权的非法调用**：agent 功能被未授权的第三方、公网恶意扫描程序探测到，进而发起批量非法调用请求，执行系统命令、文件读写等高危操作，可能导致安全后果。 +- **合规与法律风险**：若 agent 被非法调用用于实施网络攻击、信息窃取等违法违规行为，可能产生法律责任与合规风险。 -### Security Recommendations +### 安全使用建议 -**Note: We strongly recommend deploying DeerFlow in a local trusted network environment.** If you need cross-device or cross-network deployment, you must implement strict security measures, such as: +**注意：建议您将 DeerFlow 部署在本地可信的网络环境下。** 若您有跨设备、跨网络的部署需求，必须加入严格的安全措施。例如，采取如下手段： -- **IP allowlist**: Use `iptables`, or deploy hardware firewalls / switches with Access Control Lists (ACL), to **configure IP allowlist rules** and deny access from all other IP addresses. -- **Authentication gateway**: Configure a reverse proxy (e.g., nginx) and **enable strong pre-authentication**, blocking any unauthenticated access. -- **Network isolation**: Where possible, place the agent and trusted devices in the **same dedicated VLAN**, isolated from other network devices. -- **Stay updated**: Continue to follow DeerFlow's security feature updates. +- **设置访问 IP 白名单**：使用 `iptables`，或部署硬件防火墙 / 带访问控制（ACL）功能的交换机等，**配置规则设置 IP 白名单**，拒绝其他所有 IP 进行访问。 +- **前置身份验证**：配置反向代理（nginx 等），并**开启高强度的前置身份验证功能**，禁止无任何身份验证的访问。 +- **网络隔离**：若有可能，建议将 agent 和可信设备划分到**同一个专用 VLAN**，与其他网络设备做隔离。 +- **持续关注项目更新**：请持续关注 DeerFlow 项目的安全功能更新。 -## Contributing +## 参与贡献 -We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and guidelines. +欢迎参与贡献。开发环境、工作流和相关规范见 [CONTRIBUTING.md](CONTRIBUTING.md)。 -Regression coverage includes Docker sandbox mode detection and provisioner kubeconfig-path handling tests in `backend/tests/`. -Backend blocking-IO diagnostics are available from the repository root with -`make detect-blocking-io`: it statically scans backend business code for -blocking IO that may run on the backend event loop, prints a concise summary, -and writes complete JSON findings to `.deer-flow/blocking-io-findings.json`. -The JSON includes compact review records with `priority`, `location`, -`blocking_call`, `event_loop_exposure`, `reason`, and `code`. -Gateway artifact serving now forces active web content types (`text/html`, `application/xhtml+xml`, `image/svg+xml`) to download as attachments instead of inline rendering, reducing XSS risk for generated artifacts. +目前回归测试已经覆盖 Docker sandbox 模式识别，以及 `backend/tests/` 中 provisioner kubeconfig-path 处理相关测试。 -## License +## 许可证 -This project is open source and available under the [MIT License](./LICENSE). +本项目采用 [MIT License](./LICENSE) 开源发布。 -## Acknowledgments +## 致谢 -DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants. +DeerFlow 建立在开源社区大量优秀工作的基础上。所有让 DeerFlow 成为可能的项目和贡献者，我们都心怀感谢。毫不夸张地说，我们是站在巨人的肩膀上继续往前走。 -We would like to extend our sincere appreciation to the following projects for their invaluable contributions: +特别感谢以下项目带来的关键支持： -- **[LangChain](https://github.com/langchain-ai/langchain)**: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality. -- **[LangGraph](https://github.com/langchain-ai/langgraph)**: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows. +- **[LangChain](https://github.com/langchain-ai/langchain)**：它们提供的优秀框架支撑了我们的 LLM 交互与 chains，让整体集成和能力编排顺畅可用。 +- **[LangGraph](https://github.com/langchain-ai/langgraph)**：它们在多 agent 编排上的创新方式，是 DeerFlow 复杂工作流得以成立的重要基础。 -These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations. +这些项目体现了开源协作真正的力量，我们也很高兴能继续建立在这些基础之上。 -### Key Contributors +### 核心贡献者 -A heartfelt thank you goes out to the core authors of `DeerFlow`, whose vision, passion, and dedication have brought this project to life: +感谢 `DeerFlow` 的核心作者，是他们的判断、投入和持续推进，才让这个项目真正落地： - **[Daniel Walnut](https://github.com/hetaoBackend/)** - **[Henry Li](https://github.com/magiccube/)** -Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey. - ## Star History [![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)