deer-flow/README_ru.md

🦌 DeerFlow - 2.0

English | 中文 | 日本語 | Français | Русский | Português

28 февраля 2026 года DeerFlow занял 🏆 #1 в GitHub Trending после релиза версии 2. Спасибо огромное нашему сообществу — всё благодаря вам! 💪🔥

DeerFlow (Deep Exploration and Efficient Research Flow) — open-source Super Agent Harness, который управляет Sub-Agents, Memory и Sandbox для решения почти любой задачи. Всё на основе расширяемых Skills.

https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18

Note

DeerFlow 2.0 — проект переписан с нуля. Общего кода с v1 нет. Если нужен оригинальный Deep Research фреймворк — он живёт в ветке 1.x, туда тоже принимают контрибьюты. Активная разработка идёт в 2.0.

Официальный сайт

Больше информации и живые демо на официальном сайте.

Родственные проекты

• LLM Space - Познакомьтесь с нашим секретным оружием за DeerFlow — настольный инструмент для прототипирования идей агентов, проверки каждого шага харнесса, воспроизведения сбоев и тестирования производительности.

Coding Plan от ByteDance Volcengine

• Рекомендуем Doubao-Seed-2.0-Code, DeepSeek v3.2 и Kimi 2.5 для запуска DeerFlow
• Подробнее
• Для разработчиков из материкового Китая

InfoQuest

DeerFlow интегрирован с инструментарием для умного поиска и краулинга от BytePlus — InfoQuest (есть бесплатный онлайн-доступ)

---

Содержание

• 🦌 DeerFlow - 2.0
  • Официальный сайт
  • Coding Plan от ByteDance Volcengine
  • InfoQuest
  • Содержание
  • Установка одной фразой для coding agent
  • Быстрый старт
    • Конфигурация
    • Запуск
      • Вариант 1: Docker (рекомендуется)
      • Вариант 2: Локальная разработка
    • Дополнительно
      • Режим Sandbox
      • MCP-сервер
      • Мессенджеры
      • Трассировка LangSmith
      • Трассировка Langfuse
      • Использование обоих провайдеров
  • От Deep Research к Super Agent Harness
  • Core Features
    • Skills & Tools
      • Интеграция с Claude Code
    • Цели сессии (Session Goals)
    • Sub-Agents
    • Sandbox & файловая система
    • Context Engineering
    • Long-Term Memory
  • Рекомендуемые модели
  • Встроенный Python-клиент
  • Проекты
  • Запланированные задачи (Scheduled Tasks)
  • Терминальная панель (TUI)
  • Документация
  • ⚠️ Безопасность
  • Участие в разработке
  • Лицензия
  • Благодарности
    • Ключевые контрибьюторы
  • История звёзд

Установка одной фразой для coding agent

Если вы используете Claude Code, Codex, Cursor, Windsurf или другой coding agent, просто отправьте ему эту фразу:

Если DeerFlow еще не клонирован, сначала клонируй его, а затем подготовь локальное окружение разработки по инструкции https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md

Этот prompt предназначен для coding agent. Он просит агента при необходимости сначала клонировать репозиторий, предпочесть Docker, если он доступен, и в конце вернуть точную команду запуска и список недостающих настроек.

Быстрый старт

Конфигурация

1. Склонировать репозиторий DeerFlow

   git clone https://github.com/bytedance/deer-flow.git
   cd deer-flow
   

2. Запустить мастер настройки (рекомендуется)

   Из корня проекта (deer-flow/) запустите:

   make setup
   

   Запустится интерактивный мастер, который поможет выбрать LLM-провайдера, опциональный веб-поиск и настройки выполнения/безопасности (режим sandbox, доступ к bash, инструменты записи файлов). Он сгенерирует минимальный config.yaml и запишет ключи в .env. Это занимает около 2 минут.

   В любой момент запускайте make doctor, чтобы проверить конфигурацию и получить конкретные подсказки по исправлению. Если вы открываете GitHub issue о проблеме с локальной установкой или работой системы, выполните make support-bundle. Команда выводит дальнейшие шаги для автора отчёта, создаёт файл *-issue-summary.md, который нужно вставить в issue, файл *-issue-draft.md для оформления issue с помощью AI и, опционально, zip-архив с диагностикой в .deer-flow/support-bundles/. Если issue оформляет AI-ассистент, он должен начать с черновика и заменить каждый плейсхолдер REQUIRED, а не выдумывать недостающие факты. Прикладывайте zip-архив только если его запросит мейнтейнер или если одной сводки недостаточно. Мейнтейнеры и AI-инструменты триажа могут начинать с triage.json; архив содержит только очищенную от чувствительных данных диагностику и манифесты файлов и не включает .env, исходные сообщения диалогов или содержимое пользовательских файлов.

   Продвинутая / ручная настройка: если вы предпочитаете редактировать config.yaml напрямую, выполните вместо этого make config, чтобы скопировать полный шаблон. Полный справочник — config.example.yaml, включая CLI-провайдеров (Codex CLI, Claude Code OAuth), OpenRouter, Responses API и многое другое.

   Примеры ручной настройки моделей

   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. Если вы предпочитаете имя переменной окружения, специфичное для провайдера, укажите его в api_key явно (например, api_key: $OPENROUTER_API_KEY).

   Чтобы направить модели OpenAI через /v1/responses, продолжайте использовать langchain_openai:ChatOpenAI и задайте use_responses_api: true вместе с output_version: responses/v1.

   Для vLLM 0.19.0 используйте deerflow.models.vllm_provider:VllmChatModel. Для reasoning-моделей в стиле Qwen DeerFlow переключает режим рассуждений через extra_body.chat_template_kwargs.enable_thinking и сохраняет нестандартное поле reasoning vLLM в многоходовых диалогах с вызовами инструментов. Устаревшие конфигурации thinking автоматически нормализуются для обратной совместимости. Reasoning-моделям также может потребоваться запуск сервера с флагом --reasoning-parser .... Если ваш локальный vLLM принимает любой непустой API-ключ, всё равно задайте VLLM_API_KEY со значением-заглушкой.

   Примеры CLI-провайдеров:

   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-агентов настраиваются отдельно от провайдеров моделей — если вы настраиваете acp_agents.codex, укажите в нём Codex ACP-адаптер, например npx -y @zed-industries/codex-acp
   • На macOS при необходимости экспортируйте аутентификацию Claude Code явно:

   eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
   

   API-ключи также можно задать вручную в .env (рекомендуется) или экспортировать в оболочке:

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

Запуск

Вариант 1: Docker (рекомендуется)

Разработка (hot-reload, монтирование исходников):

make docker-init    # Загрузить образ Sandbox (один раз или при обновлении)
make docker-start   # Запустить сервисы

Продакшен (собирает образы локально):

make up     # Собрать образы и запустить все сервисы
make down   # Остановить и удалить контейнеры

Tip

На Linux при ошибке permission denied для Docker daemon добавьте пользователя в группу docker и перелогиньтесь. Подробнее в CONTRIBUTING.md.

Адрес: http://localhost:2026

Вариант 2: Локальная разработка

Предварительное условие: сначала выполните шаги раздела «Конфигурация» выше (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. Нативные оболочки cmd.exe и PowerShell не поддерживаются для сервисных скриптов на bash, а работа в WSL не гарантируется, поскольку некоторые скрипты зависят от утилит Git for Windows, таких как cygpath.

1. Проверить зависимости:

   make check  # Проверяет Node.js 22+, pnpm, uv, nginx
   

2. Установить зависимости:

   make install
   

3. (Опционально) Загрузить образ Sandbox заранее:

   make setup-sandbox
   

4. Запустить сервисы:

   make dev
   

5. Адрес: http://localhost:2026

Дополнительно

Режим Sandbox

DeerFlow поддерживает несколько режимов выполнения:

• Локальное выполнение — код запускается прямо на хосте
• Docker — код выполняется в изолированных Docker-контейнерах
• Docker + Kubernetes — выполнение в Kubernetes-подах через provisioner

Подробнее в руководстве по конфигурации Sandbox.

MCP-сервер

DeerFlow поддерживает настраиваемые MCP-серверы для расширения возможностей. Для HTTP/SSE MCP-серверов поддерживаются OAuth-токены (client_credentials, refresh_token). Подробнее в руководстве по MCP-серверу.

Мессенджеры

DeerFlow принимает задачи прямо из мессенджеров. Каналы запускаются автоматически при настройке, публичный IP не нужен.

DeerFlow может также предоставлять в workspace UI пользовательские подключения IM-каналов. Когда включён channel_connections, вошедшие в систему пользователи могут привязать Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, WeCom, QQ или Buzz из боковой панели / Settings > Channels. Это переиспользует существующие исходящие транспорты channels.*, поэтому публичный IP или URL обратного вызова провайдера не требуются. Входящие IM-сообщения выполняются от имени подключённого пользователя DeerFlow. Настройки и вопросы безопасности описаны в IM Channel Connections.

Канал	Транспорт	Сложность
Telegram	Bot API (long-polling)	Просто
Slack	Socket Mode	Средне
Feishu / Lark	WebSocket	Средне
WeChat	Tencent iLink (long-polling)	Средне
WeCom	WebSocket	Средне
DingTalk	Stream Push (WebSocket)	Средне
QQ	WebSocket (текст: личные сообщения и упоминания в группе)	Средняя
Buzz	Nostr relay (WebSocket, NIP-42)	Средняя

Конфигурация в config.yaml:

channels:
  feishu:
    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

  wecom:
    enabled: true
    bot_id: $WECOM_BOT_ID
    bot_secret: $WECOM_BOT_SECRET

  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN
    app_token: $SLACK_APP_TOKEN
    allowed_users: []

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # числовые ID пользователей, не @username; пусто = разрешить всем

  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # опционально: разрешить первичную загрузку через QR-код при отсутствии 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             # ClientId с DingTalk Open Platform
    client_secret: $DINGTALK_CLIENT_SECRET     # ClientSecret с DingTalk Open Platform
    allowed_users: []                          # пусто = разрешить всем
    card_template_id: ""                       # Опционально: ID шаблона AI Card для потокового эффекта печатной машинки

Ключи API в .env:

# Telegram
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

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

# Feishu / Lark
FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_app_secret

# WeChat 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
DINGTALK_CLIENT_ID=your_client_id
DINGTALK_CLIENT_SECRET=your_client_secret

Настройка Telegram

1. Напишите @BotFather, отправьте /newbot и скопируйте HTTP API-токен.
2. Укажите TELEGRAM_BOT_TOKEN в .env и включите канал в config.yaml.

Настройка WeChat

1. Включите канал wechat в config.yaml.
2. Либо задайте WECHAT_BOT_TOKEN в .env, либо установите qrcode_login_enabled: true для первичной загрузки через QR-код.
3. Когда bot_token отсутствует и загрузка через QR включена, следите за логами бэкенда — там появится QR-контент, возвращённый iLink, — и завершите процесс привязки.
4. После успешного прохождения QR-процесса DeerFlow сохраняет полученный токен в state_dir для последующих перезапусков.
5. Для развёртываний Docker Compose держите state_dir на постоянном томе, чтобы курсор get_updates_buf и сохранённое состояние аутентификации переживали перезапуски.

Настройка WeCom

1. Создайте бота на платформе WeCom AI Bot и получите bot_id и bot_secret.
2. Включите channels.wecom в config.yaml и заполните bot_id / bot_secret.
3. Задайте WECOM_BOT_ID и WECOM_BOT_SECRET в .env.
4. Убедитесь, что зависимости бэкенда включают wecom-aibot-python-sdk. Канал использует долговременное WebSocket-соединение и не требует публичного URL обратного вызова.
5. Текущая интеграция поддерживает входящие текстовые сообщения, изображения и файлы. Итоговые изображения/файлы, сгенерированные агентом, также отправляются обратно в диалог WeCom.

Настройка DingTalk

1. Создайте приложение на DingTalk Open Platform и включите возможность Робот.
2. На странице настроек робота установите режим приёма сообщений на Stream.
3. Скопируйте Client ID и Client Secret. Укажите DINGTALK_CLIENT_ID и DINGTALK_CLIENT_SECRET в .env и включите канал в config.yaml.
4. (Опционально) Для включения потоковых ответов AI Card (эффект печатной машинки) создайте шаблон AI Card на платформе карточек DingTalk, затем укажите card_template_id в config.yaml с ID шаблона. Также необходимо запросить разрешения Card.Streaming.Write и Card.Instance.Write.

Доступные команды

Команда	Описание
/new	Начать новый диалог
/status	Показать информацию о текущем треде
/models	Список доступных моделей
/memory	Просмотреть память
/help	Показать справку

Сообщения без команды воспринимаются как обычный чат — DeerFlow создаёт тред и отвечает.

Трассировка LangSmith

DeerFlow имеет встроенную интеграцию с LangSmith для наблюдаемости. При включении все вызовы LLM, запуски агентов и выполнения инструментов отслеживаются и отображаются в дашборде LangSmith.

Добавьте в файл .env в корне проекта:

LANGSMITH_TRACING=true
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=deer-flow

LANGSMITH_ENDPOINT по умолчанию https://api.smith.langchain.com и может быть переопределён при необходимости. Устаревшие переменные LANGCHAIN_* (LANGCHAIN_TRACING_V2, LANGCHAIN_API_KEY и т.д.) также поддерживаются для обратной совместимости; LANGSMITH_* имеет приоритет, когда заданы обе.

Трассировка Langfuse

DeerFlow также поддерживает наблюдаемость через Langfuse для запусков, совместимых с LangChain.

Добавьте в файл .env:

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 в качестве URL вашего развёртывания.

Поля корреляции трасс. Каждый запуск агента аннотируется зарезервированными атрибутами трассировки Langfuse, поэтому страницы Sessions и Users заполняются автоматически:

• session_id = thread_id LangGraph — группирует все трассы одного диалога
• 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, всегда совпадающий с заголовком ответа X-Trace-Id того же запроса (logging.enhance.enabled управляет только тем, выводится ли этот идентификатор в логи)

Эти поля внедряются в RunnableConfig.metadata в корне вызова графа как для gateway-пути (runtime/runs/worker.py::run_agent), так и для встроенного пути (client.py::DeerFlowClient.stream), поэтому любой LangChain-совместимый callback может их прочитать. Установите DEER_FLOW_ENV (или ENVIRONMENT) для тегирования трасс по среде развёртывания.

Использование обоих провайдеров

Если и LangSmith, и Langfuse включены, DeerFlow подключает оба callback'а трассировки и отправляет одну и ту же активность модели в обе системы.

Если провайдер явно включён, но отсутствуют необходимые учётные данные, или если его callback не может инициализироваться, DeerFlow завершает работу с ошибкой (fail fast) при инициализации трассировки во время создания модели, а сообщение об ошибке указывает провайдера, вызвавшего сбой.

В Docker-развёртываниях трассировка отключена по умолчанию. Установите LANGSMITH_TRACING=true и LANGSMITH_API_KEY в .env для включения.

От Deep Research к Super Agent Harness

DeerFlow начинался как фреймворк для Deep Research, и сообщество вышло далеко за эти рамки. После запуска разработчики строили пайплайны, генерировали презентации, поднимали дашборды, автоматизировали контент. То, чего мы не ожидали.

Стало понятно: DeerFlow не просто research-инструмент. Это harness: runtime, который даёт агентам необходимую инфраструктуру.

Поэтому мы переписали всё с нуля.

DeerFlow 2.0 — это Super Agent Harness «из коробки». Batteries included, полностью расширяемый. Построен на LangGraph и LangChain. По умолчанию есть всё, что нужно агенту: файловая система, memory, skills, sandbox-выполнение и возможность планировать и запускать sub-agents для сложных многошаговых задач.

Используйте как есть. Или разберите и переделайте под себя.

Core Features

Skills & Tools

Skills — это то, что позволяет DeerFlow делать почти что угодно.

Agent Skill — это структурированный модуль: Markdown-файл с описанием воркфлоу, лучших практик и ссылок на ресурсы. DeerFlow поставляется со встроенными skills для ресёрча, генерации отчётов, слайдов, веб-страниц, изображений и видео. Но главное — расширяемость: добавляйте свои skills, заменяйте встроенные или собирайте из них составные воркфлоу.

Skills загружаются по мере необходимости, только когда задача их требует. Это держит контекстное окно чистым.

# Пути внутри контейнера sandbox
/mnt/skills/public
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md

/mnt/skills/custom
└── your-custom-skill/SKILL.md      ← ваш skill

Интеграция с Claude Code

Skill claude-to-deerflow позволяет работать с DeerFlow прямо из Claude Code. Отправляйте задачи, проверяйте статус, управляйте тредами, не выходя из терминала.

Установка скилла:

npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

Что можно делать:

• Отправлять сообщения в DeerFlow и получать потоковые ответы
• Выбирать режимы выполнения: flash (быстро), standard, pro (planning), ultra (sub-agents)
• Проверять статус DeerFlow, просматривать модели, скиллы, агентов
• Управлять тредами и историей диалога
• Загружать файлы для анализа

Полный справочник API в skills/public/claude-to-deerflow/SKILL.md.

Цели сессии (Session Goals)

Используйте /goal <условие завершения>, чтобы привязать к текущему треду одно активное условие завершения. Цель — это состояние уровня треда, а не активация навыка, поэтому она остаётся активной между ходами, пока DeerFlow не сочтёт её выполненной или пока вы её не очистите.

Поддерживаемые команды:

/goal finish the implementation and make all tests pass
/goal              # показать активную цель
/goal clear        # очистить её

После каждого запуска, выполненного через Gateway, DeerFlow оценивает видимый диалог, включая вызовы инструментов ассистента и сокращённые результаты инструментов, относительно активной цели с помощью non-thinking модели-оценщика. Одного успешного результата инструмента недостаточно для выполнения цели, а если ассистенту пришлось угадывать недостающую или неоднозначную информацию, оценщик возвращает needs_user_input. Оценщик должен вернуть типизированный блокер (missing_evidence, needs_user_input, run_failed, external_wait или goal_not_met_yet) с видимыми доказательствами. DeerFlow добавляет hidden continuation только тогда, когда последний ход assistant сохранён в чекпоинте, блокер имеет тип goal_not_met_yet, тред не изменился во время оценки и счётчик отсутствия прогресса не сработал. Предел безопасности по умолчанию — 8 hidden continuation, а повторяющиеся одинаковые оценки без прогресса останавливаются после 2 попыток. /goal clear и любой новый ввод от пользователя имеют приоритет над continuation в очереди. Когда цель выполнена, DeerFlow очищает её автоматически и публикует обновлённое состояние треда.

Веб-интерфейс показывает активную цель над полем ввода. Та же команда доступна из TUI и поддерживаемых IM-каналов. В веб-интерфейсе и поддерживаемых IM-каналах установка /goal <условие завершения> также запускает выполнение с условием в качестве задачи; команды статуса и очистки только управляют состоянием цели.

Sub-Agents

Сложные задачи редко решаются за один проход. DeerFlow их декомпозирует.

Lead agent запускает sub-agents на лету, каждый со своим изолированным контекстом, инструментами и условиями завершения. Sub-agents работают параллельно, возвращают структурированные результаты, а lead agent собирает всё в единый итог.

Вот как DeerFlow справляется с задачами на минуты и часы: research-задача разветвляется в дюжину sub-agents, каждый копает свой угол, потом всё сходится в один отчёт, или сайт, или слайддек со сгенерированными визуалами. Один harness, много рук.

Sandbox & файловая система

DeerFlow не просто говорит о том, что умеет что-то делать. У него есть собственный компьютер.

Каждая задача выполняется внутри изолированного Docker-контейнера с полной файловой системой: skills, workspace, uploads, outputs. Агент читает, пишет и редактирует файлы. Выполняет bash-команды и пишет код. Смотрит на изображения. Всё изолировано, всё прозрачно, никакого пересечения между сессиями.

Это разница между чатботом с доступом к инструментам и агентом с реальной средой выполнения.

# Пути внутри контейнера sandbox
/mnt/user-data/
├── uploads/          ← ваши файлы
├── workspace/        ← рабочая директория агентов
└── outputs/          ← результаты

Context Engineering

Изолированный контекст: каждый sub-agent работает в своём контексте и не видит контекст главного агента или других sub-agents. Агент фокусируется на своей задаче.

Управление контекстом: внутри сессии DeerFlow агрессивно сжимает контекст и суммирует завершённые подзадачи, выгружает промежуточные результаты в файловую систему, сжимает то, что уже не актуально. На длинных многошаговых задачах контекстное окно не переполняется.

Long-Term Memory

Большинство агентов забывают всё, когда диалог заканчивается. DeerFlow помнит.

DeerFlow сохраняет ваш профиль, предпочтения и накопленные знания между сессиями. Чем больше используете, тем лучше он вас знает: стиль, технологический стек, повторяющиеся воркфлоу. Всё хранится локально и остаётся под вашим контролем.

Рекомендуемые модели

DeerFlow работает с любым LLM через OpenAI-совместимый API. Лучше всего — с моделями, которые поддерживают:

• Большое контекстное окно (100k+ токенов) — для deep research и многошаговых задач
• Reasoning capabilities — для адаптивного планирования и сложной декомпозиции
• Multimodal inputs — для работы с изображениями и видео
• Strong tool-use — для надёжного вызова функций и структурированных ответов

Встроенный Python-клиент

DeerFlow можно использовать как Python-библиотеку прямо в коде — без запуска HTTP-сервисов. DeerFlowClient даёт доступ ко всем возможностям агента и Gateway, возвращает те же схемы ответов, что и HTTP Gateway API. HTTP Gateway также предоставляет DELETE /api/threads/{thread_id} для удаления локальных данных треда, управляемых DeerFlow, после того как сам LangGraph thread был удалён:

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

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

# Streaming (LangGraph SSE protocol: 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
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")

Проекты

Проекты группируют связанные диалоги под общим именем, инструкциями и полкой документов.

Диалог присоединяется к проекту в момент создания (когда выбран проект) или позже через меню перемещения. Запуски никогда не изменяют членство: отправка сообщения не может назначить или переназначить диалог. Перемещение диалога из проекта оставляет его без назначения, пока он не будет явно перемещён снова.

Перемещение диалога обновляет его принадлежность в заголовке, а также списки проектов, в том числе когда старый запрос метаданных ещё выполняется.

Проектам требуются актуальные таблицы и столбцы базы данных. База данных с меткой 0019_thread_incarnations от старого развёртывания на основе 0018 отклоняется при запуске, если схема проектов отсутствует. Перед запуском этой сборки на такой базе следуйте процедуре автономного восстановления базы данных.

Инструкции проекта

Каждый проект хранит инструкции в свободной форме — контекст, соглашения и ограничения, применимые ко всем диалогам проекта; они редактируются на вкладке Instructions страницы проекта с живым счётчиком байтов. Когда запуск начинается на потоке-участнике, Gateway один раз фиксирует текущее состояние проекта и рендерит инструкции в виде ограниченного блока <project>, действующего только в рамках этого запроса и этого запуска: блок никогда не попадает в системный промпт и в сохранённую историю, и каждый новый запуск видит последние сохранённые инструкции. Инструкции ограничены projects.instructions_max_bytes байтами UTF-8 (по умолчанию 8192, диапазон 256–262144); многобайтовые символы считаются по их длине в байтах UTF-8. Слишком длинные инструкции отклоняются с ошибкой 422 при записи и никогда не обрезаются молча.

Полка документов

У каждого проекта есть полка документов для файлов, общих для всего проекта; она управляется в разделе Documents страницы проекта:

• Загрузить файл (кнопкой или перетаскиванием, один файл за запрос). Ограничения размера полки переиспользуют uploads.max_file_size (по умолчанию 50 МиБ); повторная загрузка идентичного содержимого возвращает существующую запись вместо создания дубликата.
• Просмотреть записи с именем, размером, временем изменения и происхождением (загружено напрямую или сохранено из диалога), а также предпросмотреть или скачать любую запись.
• Сохранить в проект из файла потока: браузер файлов диалогов только для чтения под полкой перечисляет загрузки и результаты потоков-участников, у каждой записи есть действие «Сохранить в проект».
• Прикрепить к потоку: скопировать файл с полки в загрузки потока через обычный конвейер приёма, чтобы диалог мог работать с ним напрямую.

Запуски на потоках-участниках также получают ограниченный индекс <documents>, рендеримый для каждого запуска из зафиксированного снимка (ограничен projects.shelf_index_max_entries и projects.shelf_index_max_bytes), а агент может постранично обходить полку и читать документы инструментами list_project_documents и read_project_document.

Семантика чтения архивированных проектов

Архивация проекта замораживает записи, но сохраняет чтения. Потоки архивированного проекта по-прежнему запускаются и по-прежнему получают инструкции проекта и индекс полки, а полка остаётся полностью читаемой: просмотр списка, предпросмотр/скачивание, браузер файлов диалогов и прикрепление к потоку продолжают работать. Загрузка, сохранение в проект и перемещение отдельных файлов полки в корзину требуют активного проекта, а удалённый в корзину документ нельзя восстановить в архивированный проект. Удаление архивированного проекта остаётся доступным и перемещает всю его полку в корзину.

Корзина

Удаление документа с полки перемещает его в корзину, а не стирает: запись сохраняет своё содержимое и снимок исходного проекта в течение projects.trash_retention_days (по умолчанию 30) до того, как очистка по сроку хранения сможет удалить её безвозвратно. Страница /workspace/trash — доступная из раздела Documents страницы проекта и из заголовка «Проекты» на боковой панели — перечисляет документы в корзине с их исходным проектом и оставшимся сроком хранения, с действиями «Восстановить» и «Удалить навсегда» для каждой записи, а также действием «Очистить корзину», которое безвозвратно удаляет все документы в корзине — немедленно, а не по истечении срока хранения; срок лишь ограничивает, как долго запись может там находиться, прежде чем очистка её заберёт. Восстановление возвращает документ в его исходный проект или в выбранный вами проект, если исходный удалён или архивирован; если в целевом проекте уже есть идентичный активный файл, записи объединяются. Удаление проекта за один шаг перемещает всю его полку в корзину.

Запланированные задачи (Scheduled Tasks)

Теперь в DeerFlow есть первоклассный MVP запланированных задач (scheduled-task) в workspace.

Текущие возможности MVP:

• Управление задачами на /workspace/scheduled-tasks
• Выбор: каждая запланированная задача переиспользует тред или создаёт новый тред для каждого запуска
• Поддержка расписаний once, cron и interval
• Фоновые запланированные запуски выполняются как неинтерактивные запуски DeerFlow (ask_clarification там не предоставляется)
• При совпадении наступившего cron-запуска с активным запуском на том же переиспользуемом треде применяется поведение перекрытия skip
• Приостановка, возобновление, ручной запуск, просмотр истории и удаление задач
• Запланированные задачи выполняются через стандартный жизненный цикл запуска DeerFlow

Текущие ограничения MVP:

• Нет заданий с текстовыми уведомлениями
• Нет каналов или целей отправки GitHub

Включите фоновый опрос через config.yaml -> scheduler.enabled. Ручной запуск использует тот же ресурс и путь выполнения scheduled-task.

Жизненный цикл, страховочные лимиты и условия остановки

• Страница задач и REST API (POST / PATCH /api/scheduled-tasks) принимают цель для каждого запуска (goal_objective), страховочный лимит (max_runs, end_at) и условие остановки (stop_condition). null в PATCH очищает любое из этих четырёх полей; end_at без смещения UTC трактуется как местное время в часовом поясе задачи.
• Условие остановки — это правило пользователя «остановиться, когда …». Оно хранится в отдельном поле (миграция 0031) и никогда не попадает в инструкции задачи. DeerFlow добавляет его к сообщению запуска только при старте этого запуска и просит вызвать stop_scheduled_task, когда правило выполнено. Пока включён scheduler.tool_enabled, каждый запланированный запуск может приостановить своё расписание, где бы ни была создана задача — в диалоге или на странице задач; если он выключен, запуск лишь сообщает, что правило выполнено.
• Задачи с целью, созданные на странице задач, теперь проверяются так же, как созданные в диалоге, а их запуски тоже получают сохранённые заметки и ссылку на предыдущий запуск.
• Возобновление считает следующий запуск от текущего момента, поэтому долгая пауза не приводит к догоняющему запуску. Для разовой задачи, время которой прошло, возвращается 422 once_time_passed — нужно задать новое время. Возобновление активной задачи ничего не меняет; приостановка завершённой задачи возвращает 409 task_finished.
• max_runs — общее число автоматических запусков за всё время жизни задачи; пробные запуски не учитываются. Повторное включение задачи с исчерпанным лимитом (возобновление или PATCH, который заново включает расписание завершённой задачи) возвращает 409 limits_exhausted, если тот же запрос не обновляет исчерпанный лимит: при исчерпанном числе запусков нужен больший max_runs или null, при прошедшем времени окончания — более поздний end_at или null (перенос одного end_at не возобновляет задачу с исчерпанным max_runs). Для этого POST /api/scheduled-tasks/{task_id}/resume принимает необязательное тело {"max_runs": …, "end_at": …} (null снимает лимит). PATCH, меняющий только лимит завершённой задачи, сохраняет его, а задача остаётся завершённой.
• Сбои проверки цели (ошибка оценщика или изменение диалога во время проверки) не засчитываются в автоматическую паузу после трёх промахов подряд и не сбрасывают счётчик. Изменение цели, инструкций или условия остановки, а также новая заметка начинают отсчёт заново; возобновление его сохраняет.
• Пока планировщик этого процесса Gateway не работает, создание задачи (включая дублирование) возвращает 409 scheduler_not_running. GET /api/features сообщает scheduled_tasks.available, running, tool_enabled и min_interval_seconds.
• Ошибки /api/scheduled-tasks* имеют вид {"detail": {"code", "message", "params"}}; см. backend/docs/API.md и contracts/scheduled_task_errors_contract.json.

Создание расписаний в диалоге

Установите scheduler.enabled: true и scheduler.tool_enabled: true и перезапустите Gateway. После этого авторизованный интерактивный ход может через schedule_task создавать, изменять, просматривать, приостанавливать, возобновлять и удалять задачи, запускать пробный запуск и сохранять заметки. Например: «Каждый будний день в 9:00 проверяй release-checklist.md и сообщай, что ещё не отмечено; остановись, когда всё отмечено». В веб-приложении результат показывается живой карточкой с расписанием, условием остановки и кнопками, а агент отвечает одним-двумя предложениями; в мессенджерах (IM) и других ходах вне веба агент описывает расписание, следующий запуск и условие остановки текстом.

• Какими задачами управляет диалог. Задачами, созданными в нём, а в диалоге запуска (чате, куда запланированный запуск опубликовал результат) — ещё и задачей этого запуска: там тоже работают «приостанови это» или «перенеси на 10:00». Это относится только к вашим сообщениям; сам запланированный запуск может лишь приостановить своё расписание через stop_scheduled_task.
• Изменение сохраняет задачу. Смена времени, инструкций, цели, условия остановки или страховочного лимита — это update той же задачи, поэтому её ID и история запусков сохраняются. resume возобновляет приостановленную или завершённую задачу без догоняющего запуска. Если лимит исчерпан, агент спрашивает, как обновить исчерпанный лимит (увеличить или снять max_runs; перенести или снять end_at), и передаёт это вместе с возобновлением.
• Часовой пояс. Названный вами пояс имеет приоритет. Иначе новая задача использует часовой пояс браузера, который веб-приложение отправляет с каждым сообщением (context.client_timezone, читается только для этого), и в результате указано, какой пояс выбран. Интервалам и разовым моментам со смещением UTC пояс не нужен; для cron или локального разового времени без известного пояса (например, из мессенджера) агент спросит. При изменении сохраняется прежний пояс; пояс браузера никогда не меняет существующую задачу.
• Где появляются результаты. Каждый запуск публикует результат в новом чате с названием «{задача} · {местное время}» или в исходном чате, если задача выполняется в нём. Больше ничего в исходный диалог не отправляется. Чат запуска показывает инструкции задачи свёрнутым блоком «Инструкции задачи» под заголовком запуска.
• Язык. Агент пишет название, инструкции и условие остановки на вашем языке, а запланированные запуски отвечают на языке инструкций.
• Пробный запуск. Попросите прямо, например «Run it now» или «先跑一次吧»; кнопка Run once now на карточке делает то же самое. Простое «yes», упоминание задачи, цитата или условная просьба не запускают платное выполнение. Пробный запуск не учитывается в max_runs.

Терминальная панель (TUI)

deerflow — это нативная терминальная панель для тех, кто живёт в шелле. Она работает встроенной поверх DeerFlowClient — без Gateway, фронтенда, nginx или Docker — и при этом учитывает те же настройки config.yaml, checkpointer, skills, memory, MCP и sandbox, что и остальной DeerFlow.

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"                       # автономный режим, StreamEvents с разделением новой строкой

Интерфейс чата с управлением с клавиатуры: потоковый транскрипт (ответы рендерятся в Markdown), компактные карточки активности инструментов, палитра слэш-команд /, управление целями /goal, селекторы /model и /threads, история ввода, а также прерывание через Esc / Ctrl+C. Сессии, открытые в TUI, также появляются в боковой панели веб-интерфейса — TUI пишет в общее хранилище тредов под локальным пользователем по умолчанию, поэтому терминал и веб остаются синхронизированными без запуска Gateway.

Полное руководство — в backend/docs/TUI.md.

Документация

• Руководство по участию — настройка среды разработки, воркфлоу и гайдлайны
• Руководство по конфигурации — инструкции по настройке
• Обзор архитектуры — технические детали
• Архитектура бэкенда — бэкенд и справочник API

⚠️ Безопасность

Неправильное развёртывание может привести к угрозам безопасности

DeerFlow обладает ключевыми высокопривилегированными возможностями, включая выполнение системных команд, операции с ресурсами и вызов бизнес-логики. По умолчанию он рассчитан на развёртывание в локальной доверенной среде (доступ только через loopback-адрес 127.0.0.1). Если вы разворачиваете агент в недоверенных средах — локальных сетях, публичных облачных серверах или других окружениях, доступных с нескольких устройств — без строгих мер безопасности, это может привести к следующим угрозам:

• Несанкционированные вызовы: функциональность агента может быть обнаружена неавторизованными третьими лицами или вредоносными сканерами, что приведёт к массовым несанкционированным запросам с выполнением высокорисковых операций (системные команды, чтение/запись файлов) и серьёзным последствиям для безопасности.
• Юридические и compliance-риски: если агент будет незаконно использован для кибератак, кражи данных или других противоправных действий, это может повлечь юридическую ответственность и compliance-риски.

Рекомендации по безопасности

Примечание: настоятельно рекомендуем развёртывать DeerFlow только в локальной доверенной сети. Если вам необходимо развёртывание через несколько устройств или сетей, обязательно реализуйте строгие меры безопасности, например:

• Белый список IP-адресов: используйте iptables или аппаратные межсетевые экраны / коммутаторы с ACL, чтобы настроить правила белого списка IP и заблокировать доступ со всех остальных адресов.
• Шлюз аутентификации: настройте обратный прокси (nginx и др.) и включите строгую предварительную аутентификацию, запрещающую любой доступ без авторизации.
• Сетевая изоляция: по возможности разместите агент и доверенные устройства в одном выделенном VLAN, изолированном от остальной сети.
• Следите за обновлениями: регулярно отслеживайте обновления безопасности проекта DeerFlow.

Участие в разработке

Приветствуем контрибьюторов! Настройка среды разработки, воркфлоу и гайдлайны — в CONTRIBUTING.md.

Лицензия

Проект распространяется под лицензией MIT.

Благодарности

DeerFlow стоит на плечах open-source сообщества. Спасибо всем проектам и разработчикам, чья работа сделала его возможным.

Отдельная благодарность:

• LangChain — фреймворк для взаимодействия с LLM и построения цепочек.
• LangGraph — многоагентная оркестрация, на которой держатся сложные воркфлоу DeerFlow.

Ключевые контрибьюторы

Авторы DeerFlow, без которых проекта бы не было:

• Daniel Walnut
• Henry Li

История звёзд