# 🩌 DeerFlow - 2.0 [English](./README.md) | [äž­æ–‡](./README_zh.md) | [æ—„æœŹèȘž](./README_ja.md) | Français | [РуссĐșĐžĐč](./README_ru.md) | [PortuguĂȘs](./README_pt.md) | [한ꔭ얎](./README_ko.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 > Le 28 fĂ©vrier 2026, DeerFlow a dĂ©crochĂ© la 🏆 1re place sur GitHub Trending suite au lancement de la version 2. Un immense merci Ă  notre incroyable communautĂ© — c'est grĂące Ă  vous ! đŸ’ȘđŸ”„ DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) est un **super agent harness** open source qui orchestre des **sub-agents**, de la **mĂ©moire** et des **sandboxes** pour accomplir pratiquement n'importe quelle tĂąche — le tout propulsĂ© par des **skills extensibles**. https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 > [!NOTE] > **DeerFlow 2.0 est une rĂ©Ă©criture complĂšte.** Il ne partage aucun code avec la v1. Si vous cherchez le framework Deep Research original, il est maintenu sur la [branche `1.x`](https://github.com/bytedance/deer-flow/tree/main-1.x) — les contributions y sont toujours les bienvenues. Le dĂ©veloppement actif a migrĂ© vers la 2.0. ## Site officiel DĂ©couvrez-en plus et regardez des **dĂ©mos rĂ©elles** sur notre [**site officiel**](https://deerflow.tech). ## Projets associĂ©s image - [**LLM Space**](https://github.com/deer-flow/llm-space) - DĂ©couvrez notre arme secrĂšte derriĂšre DeerFlow — un outil de bureau pour prototyper des idĂ©es d'agents, inspecter chaque Ă©tape du harness, rejouer les Ă©checs et tester les performances. ## Coding Plan de ByteDance Volcengine - Nous recommandons fortement d'utiliser Doubao-Seed-2.0-Code, DeepSeek v3.2 et Kimi 2.5 pour exĂ©cuter DeerFlow - [En savoir plus](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) - [DĂ©veloppeurs en Chine continentale, cliquez ici](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow) ## InfoQuest DeerFlow intĂšgre dĂ©sormais le toolkit de recherche et de crawling intelligent dĂ©veloppĂ© par BytePlus — [InfoQuest (essai gratuit en ligne)](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest) InfoQuest_banner --- ## Table des matiĂšres - [🩌 DeerFlow - 2.0](#-deerflow---20) - [Site officiel](#site-officiel) - [Coding Plan de ByteDance Volcengine](#coding-plan-de-bytedance-volcengine) - [InfoQuest](#infoquest) - [Table des matiĂšres](#table-des-matiĂšres) - [Installation en une phrase pour un coding agent](#installation-en-une-phrase-pour-un-coding-agent) - [DĂ©marrage rapide](#dĂ©marrage-rapide) - [Configuration](#configuration) - [Lancer l'application](#lancer-lapplication) - [Option 1 : Docker (recommandĂ©)](#option-1--docker-recommandĂ©) - [Option 2 : DĂ©veloppement local](#option-2--dĂ©veloppement-local) - [AvancĂ©](#avancĂ©) - [Mode Sandbox](#mode-sandbox) - [Serveur MCP](#serveur-mcp) - [Canaux de messagerie](#canaux-de-messagerie) - [Traçage LangSmith](#traçage-langsmith) - [Traçage Langfuse](#traçage-langfuse) - [Utiliser les deux fournisseurs](#utiliser-les-deux-fournisseurs) - [Du Deep Research au Super Agent Harness](#du-deep-research-au-super-agent-harness) - [FonctionnalitĂ©s principales](#fonctionnalitĂ©s-principales) - [Skills et outils](#skills-et-outils) - [IntĂ©gration Claude Code](#intĂ©gration-claude-code) - [Objectifs de session (Session Goals)](#objectifs-de-session-session-goals) - [Sub-Agents](#sub-agents) - [Sandbox et systĂšme de fichiers](#sandbox-et-systĂšme-de-fichiers) - [Context Engineering](#context-engineering) - [MĂ©moire Ă  long terme](#mĂ©moire-Ă -long-terme) - [ModĂšles recommandĂ©s](#modĂšles-recommandĂ©s) - [Client Python intĂ©grĂ©](#client-python-intĂ©grĂ©) - [Projets](#projets) - [TĂąches planifiĂ©es (Scheduled Tasks)](#tĂąches-planifiĂ©es-scheduled-tasks) - [Atelier terminal (TUI)](#atelier-terminal-tui) - [Documentation](#documentation) - [⚠ Avertissement de sĂ©curitĂ©](#-avertissement-de-sĂ©curitĂ©) - [Contribuer](#contribuer) - [Licence](#licence) - [Remerciements](#remerciements) - [Contributeurs principaux](#contributeurs-principaux) - [Star History](#star-history) ## Installation en une phrase pour un coding agent Si vous utilisez Claude Code, Codex, Cursor, Windsurf ou un autre coding agent, vous pouvez simplement lui envoyer cette phrase : ```text Aide-moi Ă  cloner DeerFlow si nĂ©cessaire, puis Ă  initialiser son environnement de dĂ©veloppement local en suivant https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md ``` Ce prompt est destinĂ© aux coding agents. Il leur demande de cloner le dĂ©pĂŽt si nĂ©cessaire, de privilĂ©gier Docker quand il est disponible, puis de s'arrĂȘter avec la commande exacte pour lancer DeerFlow et la liste des configurations encore manquantes. ## DĂ©marrage rapide ### Configuration 1. **Cloner le dĂ©pĂŽt DeerFlow** ```bash git clone https://github.com/bytedance/deer-flow.git cd deer-flow ``` 2. **Lancer l'assistant de configuration (recommandĂ©)** Depuis le rĂ©pertoire racine du projet (`deer-flow/`), exĂ©cutez : ```bash make setup ``` Cette commande lance un assistant interactif qui vous guide dans le choix d'un fournisseur LLM, d'une recherche web optionnelle et des prĂ©fĂ©rences d'exĂ©cution/sĂ©curitĂ© (mode sandbox, accĂšs bash, outils d'Ă©criture de fichiers). Il gĂ©nĂšre un `config.yaml` minimal et Ă©crit vos clĂ©s dans `.env`. Comptez environ 2 minutes. ExĂ©cutez `make doctor` Ă  tout moment pour vĂ©rifier votre configuration et obtenir des pistes de correction concrĂštes. Si vous ouvrez une issue GitHub Ă  propos d'un problĂšme de configuration ou d'exĂ©cution en local, exĂ©cutez `make support-bundle`. La commande affiche les prochaines Ă©tapes pour le rapporteur, Ă©crit un fichier `*-issue-summary.md` Ă  coller dans l'issue, un fichier `*-issue-draft.md` destinĂ© au dĂ©pĂŽt d'issue assistĂ© par IA, ainsi qu'un zip de preuves optionnel sous `.deer-flow/support-bundles/`. Si un assistant IA dĂ©pose l'issue, partez du brouillon et remplacez chaque placeholder REQUIRED au lieu d'inventer les informations manquantes. N'attachez le zip que si un mainteneur le demande, ou si le rĂ©sumĂ© seul ne suffit pas. Les mainteneurs et les outils de triage IA peuvent commencer par `triage.json` ; le bundle ne contient que des diagnostics expurgĂ©s et des manifestes de fichiers, et n'inclut ni `.env`, ni les messages bruts des conversations, ni le contenu des fichiers de l'utilisateur. > **Configuration avancĂ©e / manuelle** : si vous prĂ©fĂ©rez Ă©diter `config.yaml` directement, exĂ©cutez plutĂŽt `make config` pour copier le template complet. Voir `config.example.yaml` pour la rĂ©fĂ©rence complĂšte, y compris les providers basĂ©s sur un CLI (Codex CLI, Claude Code OAuth), OpenRouter, l'API Responses, et plus encore.
Exemples de configuration manuelle des modĂšles ```yaml 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: opper-claude-sonnet-4-6 display_name: Claude Sonnet 4.6 (Opper) use: langchain_openai:ChatOpenAI model: claude-sonnet-4-6 api_key: $OPPER_API_KEY base_url: https://api.opper.ai/v3/compat - 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 et les passerelles compatibles OpenAI similaires doivent ĂȘtre configurĂ©s avec `langchain_openai:ChatOpenAI` et `base_url`. Si vous prĂ©fĂ©rez utiliser un nom de variable d'environnement propre au fournisseur, pointez `api_key` vers cette variable explicitement (par exemple `api_key: $OPENROUTER_API_KEY`). Pour router les modĂšles OpenAI via `/v1/responses`, continuez d'utiliser `langchain_openai:ChatOpenAI` et dĂ©finissez `use_responses_api: true` avec `output_version: responses/v1`. Pour vLLM 0.19.0, utilisez `deerflow.models.vllm_provider:VllmChatModel`. Pour les modĂšles de raisonnement de type Qwen, DeerFlow active le raisonnement via `extra_body.chat_template_kwargs.enable_thinking` et prĂ©serve le champ non standard `reasoning` de vLLM au fil des conversations multi-tours avec appels d'outils. Les anciennes configurations `thinking` sont normalisĂ©es automatiquement pour assurer la rĂ©trocompatibilitĂ©. Les modĂšles de raisonnement peuvent aussi exiger que le serveur soit dĂ©marrĂ© avec `--reasoning-parser ...`. Si votre dĂ©ploiement vLLM local accepte n'importe quelle clĂ© API non vide, vous pouvez tout de mĂȘme dĂ©finir `VLLM_API_KEY` avec une valeur factice. Exemples de providers basĂ©s sur un CLI : ```yaml 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 lit `~/.codex/auth.json` - Claude Code accepte `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_CREDENTIALS_PATH`, ou `~/.claude/.credentials.json` - Les entrĂ©es d'agents ACP sont distinctes des providers de modĂšles — si vous configurez `acp_agents.codex`, pointez-le vers un adaptateur Codex ACP tel que `npx -y @zed-industries/codex-acp` - Sur macOS, exportez l'auth Claude Code explicitement si nĂ©cessaire : ```bash eval "$(python3 scripts/export_claude_code_oauth.py --print-export)" ``` Les clĂ©s API peuvent aussi ĂȘtre dĂ©finies manuellement dans `.env` (recommandĂ©) ou exportĂ©es dans votre shell : ```bash OPENAI_API_KEY=your-openai-api-key TAVILY_API_KEY=your-tavily-api-key ```
### Lancer l'application #### Option 1 : Docker (recommandĂ©) **DĂ©veloppement** (hot-reload, montage des sources) : ```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-start` ne lance `provisioner` que si `config.yaml` utilise le mode provisioner (`sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider` avec `provisioner_url`). Les utilisateurs qui lancent Compose directement peuvent ajouter `--profile provisioner` Ă  la commande dev pour le mĂȘme mode ; la stack par dĂ©faut ne nĂ©cessite pas Kubernetes. Les processus backend rĂ©cupĂšrent automatiquement les changements dans `config.yaml` au prochain accĂšs Ă  la configuration, donc les mises Ă  jour de mĂ©tadonnĂ©es des modĂšles ne nĂ©cessitent pas de redĂ©marrage manuel en dĂ©veloppement. > [!TIP] > Sous Linux, si les commandes Docker Ă©chouent avec `permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock`, ajoutez votre utilisateur au groupe `docker` et reconnectez-vous avant de rĂ©essayer. Voir [CONTRIBUTING.md](CONTRIBUTING.md#linux-docker-daemon-permission-denied) pour la solution complĂšte. **Production** (build des images en local, montage de la config et des donnĂ©es) : ```bash make up # Build images and start all production services make down # Stop and remove containers ``` > [!NOTE] > Le runtime d'agent s'exĂ©cute actuellement dans la Gateway. nginx rĂ©Ă©crit `/api/langgraph/*` vers l'API compatible LangGraph servie par la Gateway. AccĂšs : http://localhost:2026 Voir [CONTRIBUTING.md](CONTRIBUTING.md) pour le guide complet de dĂ©veloppement avec Docker. #### Option 2 : DĂ©veloppement local Si vous prĂ©fĂ©rez lancer les services en local : PrĂ©requis : complĂ©tez d'abord les Ă©tapes de « Configuration » ci-dessus (`make setup`). `make dev` nĂ©cessite un fichier `config.yaml` valide Ă  la racine du projet. DĂ©finissez `DEER_FLOW_PROJECT_ROOT` pour indiquer explicitement cette racine, ou `DEER_FLOW_CONFIG_PATH` pour pointer vers un fichier de configuration prĂ©cis. L'Ă©tat d'exĂ©cution est Ă©crit par dĂ©faut dans `.deer-flow` sous la racine du projet et peut ĂȘtre dĂ©placĂ© avec `DEER_FLOW_HOME` ; les skills sont lus par dĂ©faut depuis `skills/` sous la racine du projet et peuvent ĂȘtre dĂ©placĂ©s avec `DEER_FLOW_SKILLS_PATH`. ExĂ©cutez `make doctor` pour vĂ©rifier votre configuration avant de dĂ©marrer. Sous Windows, exĂ©cutez le flux de dĂ©veloppement local depuis Git Bash. Les shells natifs `cmd.exe` et PowerShell ne sont pas pris en charge pour les scripts de service basĂ©s sur bash, et WSL n'est pas garanti car certains scripts dĂ©pendent d'utilitaires de Git for Windows comme `cygpath`. 1. **VĂ©rifier les prĂ©requis** : ```bash make check # Verifies Node.js 22+, pnpm, uv, nginx ``` 2. **Installer les dĂ©pendances** : ```bash make install # Install backend + frontend dependencies ``` 3. **(Optionnel) PrĂ©-tĂ©lĂ©charger l'image sandbox** : ```bash # Recommended if using Docker/Container-based sandbox make setup-sandbox ``` 4. **DĂ©marrer les services** : ```bash make dev ``` 5. **AccĂšs** : http://localhost:2026 ### AvancĂ© #### Mode Sandbox DeerFlow supporte plusieurs modes d'exĂ©cution sandbox : - **ExĂ©cution locale** (exĂ©cute le code sandbox directement sur la machine hĂŽte) - **ExĂ©cution Docker** (exĂ©cute le code sandbox dans des conteneurs Docker isolĂ©s) - **ExĂ©cution Docker avec Kubernetes** (exĂ©cute le code sandbox dans des pods Kubernetes via le service provisioner) En dĂ©veloppement Docker, le dĂ©marrage des services suit le mode sandbox dĂ©fini dans `config.yaml`. En mode Local/Docker, `provisioner` n'est pas dĂ©marrĂ©. Voir le [Guide de configuration Sandbox](backend/docs/CONFIGURATION.md#sandbox) pour configurer le mode de votre choix. #### Serveur MCP DeerFlow supporte des serveurs MCP et des skills configurables pour Ă©tendre ses capacitĂ©s. Pour les serveurs MCP HTTP/SSE, les flux de tokens OAuth sont supportĂ©s (`client_credentials`, `refresh_token`). Voir le [Guide MCP Server](backend/docs/MCP_SERVER.md) pour les instructions dĂ©taillĂ©es. #### Canaux de messagerie DeerFlow peut recevoir des tĂąches depuis des applications de messagerie. Les canaux dĂ©marrent automatiquement une fois configurĂ©s — aucune IP publique n'est requise. DeerFlow peut aussi exposer des connexions de canaux IM appartenant Ă  l'utilisateur dans l'UI du workspace. Quand `channel_connections` est activĂ©, les utilisateurs connectĂ©s peuvent lier Telegram, Slack, Discord, Feishu/Lark, DingTalk, WeChat, WeCom, QQ ou Buzz depuis la barre latĂ©rale / Settings > Channels. Cela rĂ©utilise les transports sortants `channels.*` existants, donc aucune IP publique ni URL de callback provider n'est requise. Les messages IM entrants s'exĂ©cutent ensuite sous le compte utilisateur DeerFlow connectĂ©. Voir [IM Channel Connections](backend/docs/IM_CHANNEL_CONNECTIONS.md) pour la configuration et les notes de sĂ©curitĂ©. | Canal | Transport | DifficultĂ© | |---------|-----------|------------| | Telegram | Bot API (long-polling) | Facile | | Slack | Socket Mode | ModĂ©rĂ©e | | Feishu / Lark | WebSocket | ModĂ©rĂ©e | | WeChat | Tencent iLink (long-polling) | ModĂ©rĂ©e | | WeCom | WebSocket | ModĂ©rĂ©e | | DingTalk | Stream Push (WebSocket) | ModĂ©rĂ©e | | QQ | WebSocket (texte : messages privĂ©s et mentions de groupe) | ModĂ©rĂ©e | | Buzz | Relais Nostr (WebSocket, NIP-42) | ModĂ©rĂ©e | **Configuration dans `config.yaml` :** ```yaml channels: # LangGraph-compatible Gateway API base URL (default: http://localhost:8001/api) langgraph_url: http://localhost:8001/api # Gateway API URL (default: http://localhost:8001) gateway_url: http://localhost:8001 # Optional: global session defaults for all mobile channels session: assistant_id: lead_agent config: recursion_limit: 100 context: thinking_enabled: true is_plan_mode: false subagent_enabled: false 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 # xoxb-... app_token: $SLACK_APP_TOKEN # xapp-... (Socket Mode) allowed_users: [] # empty = allow all telegram: enabled: true bot_token: $TELEGRAM_BOT_TOKEN allowed_users: [] # identifiants numĂ©riques, pas de @pseudo ; vide = tout le monde autorisĂ© # Optional: per-channel / per-user session settings session: assistant_id: mobile_agent context: thinking_enabled: false users: "123456789": assistant_id: vip_agent config: recursion_limit: 150 context: thinking_enabled: true subagent_enabled: true wechat: enabled: false bot_token: $WECHAT_BOT_TOKEN ilink_bot_id: $WECHAT_ILINK_BOT_ID qrcode_login_enabled: true # optionnel : autorise le bootstrap QR Ă  la premiĂšre utilisation quand bot_token est absent allowed_users: [] # vide = tout le monde autorisĂ© 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 depuis DingTalk Open Platform client_secret: $DINGTALK_CLIENT_SECRET # ClientSecret depuis DingTalk Open Platform allowed_users: [] # vide = tout le monde autorisĂ© card_template_id: "" # Optionnel : ID de modĂšle AI Card pour l'effet machine Ă  Ă©crire en streaming ``` DĂ©finissez les clĂ©s API correspondantes dans votre fichier `.env` : ```bash # 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 ``` **Configuration Telegram** 1. Ouvrez une conversation avec [@BotFather](https://t.me/BotFather), envoyez `/newbot`, et copiez le token HTTP API. 2. DĂ©finissez `TELEGRAM_BOT_TOKEN` dans `.env` et activez le canal dans `config.yaml`. **Configuration Slack** 1. CrĂ©ez une Slack App sur [api.slack.com/apps](https://api.slack.com/apps) → Create New App → From scratch. 2. Dans **OAuth & Permissions**, ajoutez les Bot Token Scopes : `app_mentions:read`, `chat:write`, `im:history`, `im:read`, `im:write`, `files:write`. 3. Activez le **Socket Mode** → gĂ©nĂ©rez un App-Level Token (`xapp-
`) avec le scope `connections:write`. 4. Dans **Event Subscriptions**, abonnez-vous aux bot events : `app_mention`, `message.im`. 5. DĂ©finissez `SLACK_BOT_TOKEN` et `SLACK_APP_TOKEN` dans `.env` et activez le canal dans `config.yaml`. **Configuration Feishu / Lark** 1. CrĂ©ez une application sur [Feishu Open Platform](https://open.feishu.cn/) → activez la capacitĂ© **Bot**. 2. Ajoutez les permissions : `im:message`, `im:message.p2p_msg:readonly`, `im:resource`. 3. Dans **Events**, abonnez-vous Ă  `im.message.receive_v1` et sĂ©lectionnez le mode **Long Connection**. 4. Copiez l'App ID et l'App Secret. DĂ©finissez `FEISHU_APP_ID` et `FEISHU_APP_SECRET` dans `.env` et activez le canal dans `config.yaml`. **Configuration WeChat** 1. Activez le canal `wechat` dans `config.yaml`. 2. Soit dĂ©finissez `WECHAT_BOT_TOKEN` dans `.env`, soit mettez `qrcode_login_enabled: true` pour le bootstrap QR Ă  la premiĂšre utilisation. 3. Quand `bot_token` est absent et que le bootstrap QR est activĂ©, surveillez les logs du backend pour le contenu du QR renvoyĂ© par iLink et complĂ©tez le flux de binding. 4. Une fois le flux QR rĂ©ussi, DeerFlow persiste le token acquis sous `state_dir` pour les redĂ©marrages ultĂ©rieurs. 5. Pour les dĂ©ploiements Docker Compose, gardez `state_dir` sur un volume persistant afin que le curseur `get_updates_buf` et l'Ă©tat d'auth sauvegardĂ© survivent aux redĂ©marrages. **Configuration WeCom** 1. CrĂ©ez un bot sur la plateforme WeCom AI Bot et obtenez le `bot_id` et le `bot_secret`. 2. Activez `channels.wecom` dans `config.yaml` et renseignez `bot_id` / `bot_secret`. 3. DĂ©finissez `WECOM_BOT_ID` et `WECOM_BOT_SECRET` dans `.env`. 4. Assurez-vous que les dĂ©pendances du backend incluent `wecom-aibot-python-sdk`. Le canal utilise une connexion longue WebSocket et ne nĂ©cessite pas d'URL de callback publique. 5. L'intĂ©gration actuelle prend en charge les messages entrants texte, image et fichier. Les images/fichiers finaux gĂ©nĂ©rĂ©s par l'agent sont aussi renvoyĂ©s dans la conversation WeCom. **Configuration DingTalk** 1. CrĂ©ez une application sur [DingTalk Open Platform](https://open.dingtalk.com/) et activez la capacitĂ© **Robot**. 2. Dans la page de configuration du robot, dĂ©finissez le mode de rĂ©ception des messages sur **Stream**. 3. Copiez le `Client ID` et le `Client Secret`. DĂ©finissez `DINGTALK_CLIENT_ID` et `DINGTALK_CLIENT_SECRET` dans `.env` et activez le canal dans `config.yaml`. 4. *(Optionnel)* Pour activer les rĂ©ponses en streaming AI Card (effet machine Ă  Ă©crire), crĂ©ez un modĂšle **AI Card** sur la [plateforme de cartes DingTalk](https://open.dingtalk.com/document/dingstart/typewriter-effect-streaming-ai-card), puis dĂ©finissez `card_template_id` dans `config.yaml` avec l'ID du modĂšle. Vous devez Ă©galement demander les permissions `Card.Streaming.Write` et `Card.Instance.Write`. **Commandes** Une fois un canal connectĂ©, vous pouvez interagir avec DeerFlow directement depuis le chat : | Commande | Description | |---------|-------------| | `/new` | DĂ©marrer une nouvelle conversation | | `/status` | Afficher les infos du thread en cours | | `/models` | Lister les modĂšles disponibles | | `/memory` | Consulter la mĂ©moire | | `/help` | Afficher l'aide | > Les messages sans prĂ©fixe de commande sont traitĂ©s comme du chat classique — DeerFlow crĂ©e un thread et rĂ©pond de maniĂšre conversationnelle. #### Traçage LangSmith DeerFlow intĂšgre nativement [LangSmith](https://smith.langchain.com) pour l'observabilitĂ©. Une fois activĂ©, tous les appels LLM, les exĂ©cutions d'agents et les exĂ©cutions d'outils sont tracĂ©s et visibles dans le tableau de bord LangSmith. Ajoutez les lignes suivantes Ă  votre fichier `.env` : ```bash LANGSMITH_TRACING=true LANGSMITH_ENDPOINT=https://api.smith.langchain.com LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx LANGSMITH_PROJECT=xxx ``` #### Traçage Langfuse DeerFlow prend Ă©galement en charge l'observabilitĂ© via [Langfuse](https://langfuse.com) pour les exĂ©cutions compatibles LangChain. Ajoutez les lignes suivantes Ă  votre fichier `.env` : ```bash LANGFUSE_TRACING=true LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx LANGFUSE_BASE_URL=https://cloud.langfuse.com ``` Si vous utilisez une instance Langfuse auto-hĂ©bergĂ©e, dĂ©finissez `LANGFUSE_BASE_URL` sur l'URL de votre dĂ©ploiement. **Champs de corrĂ©lation des traces.** Chaque exĂ©cution d'agent est annotĂ©e avec les attributs de trace rĂ©servĂ©s de Langfuse afin que les pages Sessions et Users se remplissent automatiquement : - `session_id` = `thread_id` de LangGraph — regroupe toutes les traces d'une mĂȘme conversation - `user_id` = utilisateur effectif issu de `get_effective_user_id()` (revient Ă  `default` en mode sans authentification) - `trace_name` = assistant id (par dĂ©faut `lead-agent`) - `tags` = `[env:, model:]` (omis lorsqu'ils ne sont pas dĂ©finis) - `metadata.deerflow_trace_id` = id de corrĂ©lation de requĂȘte DeerFlow, toujours identique Ă  l'en-tĂȘte de rĂ©ponse `X-Trace-Id` renvoyĂ© par la mĂȘme requĂȘte (`logging.enhance.enabled` contrĂŽle uniquement si cet id est Ă©crit dans les logs) Ces champs sont injectĂ©s dans `RunnableConfig.metadata` Ă  la racine de l'invocation du graphe, Ă  la fois pour le chemin gateway (`runtime/runs/worker.py::run_agent`) et le chemin embarquĂ© (`client.py::DeerFlowClient.stream`), de sorte que tout callback compatible LangChain puisse les lire. DĂ©finissez `DEER_FLOW_ENV` (ou `ENVIRONMENT`) pour Ă©tiqueter les traces par environnement de dĂ©ploiement. #### Utiliser les deux fournisseurs Si LangSmith et Langfuse sont tous deux activĂ©s, DeerFlow attache les deux callbacks de traçage et rapporte la mĂȘme activitĂ© de modĂšle aux deux systĂšmes. Si un fournisseur est explicitement activĂ© mais qu'il manque les identifiants requis, ou si son callback Ă©choue Ă  s'initialiser, DeerFlow Ă©choue immĂ©diatement (fail fast) lors de l'initialisation du traçage Ă  la crĂ©ation du modĂšle, et le message d'erreur indique le fournisseur Ă  l'origine de l'Ă©chec. Pour les dĂ©ploiements Docker, le traçage est dĂ©sactivĂ© par dĂ©faut. DĂ©finissez `LANGSMITH_TRACING=true` et `LANGSMITH_API_KEY` dans votre `.env` pour l'activer. ## Du Deep Research au Super Agent Harness DeerFlow a dĂ©marrĂ© comme un framework de Deep Research — et la communautĂ© s'en est emparĂ©e. Depuis le lancement, les dĂ©veloppeurs l'ont poussĂ© bien au-delĂ  de la recherche : construction de pipelines de donnĂ©es, gĂ©nĂ©ration de prĂ©sentations, mise en place de dashboards, automatisation de workflows de contenu. Des usages qu'on n'avait jamais anticipĂ©s. Ça nous a rĂ©vĂ©lĂ© quelque chose d'important : DeerFlow n'Ă©tait pas qu'un simple outil de recherche. C'Ă©tait un **harness** — un runtime qui donne aux agents l'infrastructure nĂ©cessaire pour vraiment accomplir du travail. On l'a donc reconstruit de zĂ©ro. DeerFlow 2.0 n'est plus un framework Ă  assembler soi-mĂȘme. C'est un super agent harness — clĂ© en main et entiĂšrement extensible. Construit sur LangGraph et LangChain, il embarque tout ce dont un agent a besoin out of the box : un systĂšme de fichiers, de la mĂ©moire, des skills, une exĂ©cution sandboxĂ©e, et la capacitĂ© de planifier et de lancer des sub-agents pour les tĂąches complexes et multi-Ă©tapes. Utilisez-le tel quel. Ou dĂ©montez-le et faites-en le vĂŽtre. ## FonctionnalitĂ©s principales ### Skills et outils Les skills sont ce qui permet Ă  DeerFlow de faire *pratiquement n'importe quoi*. Un Agent Skill standard est un module de capacitĂ© structurĂ© — un fichier Markdown qui dĂ©finit un workflow, des bonnes pratiques et des rĂ©fĂ©rences vers des ressources associĂ©es. DeerFlow est livrĂ© avec des skills intĂ©grĂ©s pour la recherche, la gĂ©nĂ©ration de rapports, la crĂ©ation de prĂ©sentations, les pages web, la gĂ©nĂ©ration d'images et de vidĂ©os, et bien plus. Mais la vraie force rĂ©side dans l'extensibilitĂ© : ajoutez vos propres skills, remplacez ceux fournis, ou combinez-les en workflows composites. Les skills sont chargĂ©s progressivement — uniquement quand la tĂąche le nĂ©cessite, pas tous en mĂȘme temps. Ça permet de garder la fenĂȘtre de contexte lĂ©gĂšre et de bien fonctionner mĂȘme avec des modĂšles sensibles au nombre de tokens. Quand vous installez des archives `.skill` via le Gateway, DeerFlow accepte les mĂ©tadonnĂ©es frontmatter optionnelles standard comme `version`, `author` et `compatibility`, plutĂŽt que de rejeter des skills externes par ailleurs valides. Les outils suivent la mĂȘme philosophie. DeerFlow est livrĂ© avec un ensemble d'outils de base — recherche web, fetch de pages web, opĂ©rations sur les fichiers, exĂ©cution bash — et supporte les outils custom via des serveurs MCP et des fonctions Python. Remplacez n'importe quoi. Ajoutez n'importe quoi. Les suggestions de suivi gĂ©nĂ©rĂ©es par le Gateway normalisent dĂ©sormais aussi bien la sortie texte brut du modĂšle que le contenu riche au format bloc/liste avant de parser la rĂ©ponse en tableau JSON, de sorte que les wrappers de contenu propres Ă  chaque provider ne suppriment plus silencieusement les suggestions. ``` # Paths inside the sandbox container /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 ← yours ``` #### IntĂ©gration Claude Code Le skill `claude-to-deerflow` vous permet d'interagir avec une instance DeerFlow en cours d'exĂ©cution directement depuis [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Envoyez des tĂąches de recherche, vĂ©rifiez le statut, gĂ©rez les threads — le tout sans quitter le terminal. **Installer le skill** : ```bash npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow ``` Assurez-vous ensuite que DeerFlow tourne (par dĂ©faut sur `http://localhost:2026`) et utilisez la commande `/claude-to-deerflow` dans Claude Code. **Ce que vous pouvez faire** : - Envoyer des messages Ă  DeerFlow et recevoir des rĂ©ponses en streaming - Choisir le mode d'exĂ©cution : flash (rapide), standard, pro (planification), ultra (sub-agents) - VĂ©rifier la santĂ© de DeerFlow, lister les modĂšles/skills/agents - GĂ©rer les threads et l'historique des conversations - Upload des fichiers pour analyse **Variables d'environnement** (optionnel, pour des endpoints custom) : ```bash DEERFLOW_URL=http://localhost:2026 # Unified proxy base URL DEERFLOW_GATEWAY_URL=http://localhost:2026 # Gateway API DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph # LangGraph API ``` Voir [`skills/public/claude-to-deerflow/SKILL.md`](skills/public/claude-to-deerflow/SKILL.md) pour la rĂ©fĂ©rence API complĂšte. ### Objectifs de session (Session Goals) Utilisez `/goal ` pour attacher une condition de complĂ©tion active au thread courant. Le goal est un Ă©tat de portĂ©e thread, pas une activation de skill — il reste actif entre les tours jusqu'Ă  ce que DeerFlow dĂ©termine qu'il a Ă©tĂ© satisfait, ou jusqu'Ă  ce que vous le supprimiez. Commandes prises en charge : ```text /goal finish the implementation and make all tests pass /goal # afficher le goal actif /goal clear # le supprimer ``` AprĂšs chaque exĂ©cution menĂ©e par la Gateway, DeerFlow Ă©value la conversation visible, y compris les appels d'outils de l'assistant et leurs rĂ©sultats abrĂ©gĂ©s, par rapport au goal actif Ă  l'aide d'un modĂšle Ă©valuateur non-thinking. Un rĂ©sultat d'outil rĂ©ussi ne suffit pas Ă  satisfaire un goal, et lorsque l'assistant a dĂ» deviner une information manquante ou ambiguĂ«, l'Ă©valuateur renvoie `needs_user_input`. L'Ă©valuateur doit renvoyer un blocker typĂ© (`missing_evidence`, `needs_user_input`, `run_failed`, `external_wait` ou `goal_not_met_yet`) accompagnĂ© de preuves visibles. DeerFlow n'injecte une hidden continuation que si le dernier tour assistant est durablement checkpointĂ©, que le blocker est `goal_not_met_yet`, que le thread n'a pas changĂ© durant l'Ă©valuation et que le disjoncteur de non-progression n'a pas dĂ©clenchĂ©. Le plafond de sĂ©curitĂ© est de 8 hidden continuations par dĂ©faut, et les Ă©valuations identiques de non-progression s'arrĂȘtent aprĂšs 2 tentatives rĂ©pĂ©tĂ©es. `/goal clear` ainsi que toute nouvelle saisie utilisateur ont prioritĂ© sur les continuations en file d'attente. Lorsque le goal est satisfait, DeerFlow le supprime automatiquement et publie l'Ă©tat mis Ă  jour du thread. Le Web UI affiche le goal actif au-dessus de la zone de saisie. La mĂȘme commande est disponible depuis le TUI et les canaux IM pris en charge. Dans le Web UI et les canaux IM pris en charge, dĂ©finir `/goal ` lance aussi une exĂ©cution avec la condition comme tĂąche ; les commandes de statut et de suppression ne gĂšrent que l'Ă©tat du goal lui-mĂȘme. ### Sub-Agents Les tĂąches complexes tiennent rarement en une seule passe. DeerFlow les dĂ©compose. L'agent principal peut lancer des sub-agents Ă  la volĂ©e — chacun avec son propre contexte dĂ©limitĂ©, ses outils et ses conditions d'arrĂȘt. Les sub-agents s'exĂ©cutent en parallĂšle quand c'est possible, remontent des rĂ©sultats structurĂ©s, et l'agent principal synthĂ©tise le tout en une sortie cohĂ©rente. C'est comme ça que DeerFlow gĂšre les tĂąches qui prennent de quelques minutes Ă  plusieurs heures : une tĂąche de recherche peut se dĂ©ployer en une dizaine de sub-agents, chacun explorant un angle diffĂ©rent, puis converger vers un seul rapport — ou un site web — ou un jeu de slides avec des visuels gĂ©nĂ©rĂ©s. Un seul harness, de nombreuses mains. ### Sandbox et systĂšme de fichiers DeerFlow ne se contente pas de *parler* de faire les choses. Il dispose de son propre ordinateur. Chaque tĂąche s'exĂ©cute dans un conteneur Docker isolĂ© avec un systĂšme de fichiers complet — skills, workspace, uploads, outputs. L'agent lit, Ă©crit et Ă©dite des fichiers. Il exĂ©cute des commandes bash et du code. Il visualise des images. Le tout sandboxĂ©, le tout auditable, zĂ©ro contamination entre les sessions. C'est la diffĂ©rence entre un chatbot avec accĂšs Ă  des outils et un agent dotĂ© d'un vĂ©ritable environnement d'exĂ©cution. ``` # Paths inside the sandbox container /mnt/user-data/ ├── uploads/ ← your files ├── workspace/ ← agents' working directory └── outputs/ ← final deliverables ``` ### Context Engineering **Contexte isolĂ© des Sub-Agents** : chaque sub-agent s'exĂ©cute dans son propre contexte isolĂ©. Il ne peut voir ni le contexte de l'agent principal, ni celui des autres sub-agents. L'objectif est de garantir que chaque sub-agent reste concentrĂ© sur sa tĂąche sans ĂȘtre parasitĂ© par des informations non pertinentes. **RĂ©sumĂ©** : au sein d'une session, DeerFlow gĂšre le contexte de maniĂšre agressive — en rĂ©sumant les sous-tĂąches terminĂ©es, en dĂ©chargeant les rĂ©sultats intermĂ©diaires vers le systĂšme de fichiers, en compressant ce qui n'est plus immĂ©diatement pertinent. Ça lui permet de rester efficace sur des tĂąches longues et multi-Ă©tapes sans faire exploser la fenĂȘtre de contexte. ### MĂ©moire Ă  long terme La plupart des agents oublient tout dĂšs qu'une conversation se termine. DeerFlow, lui, se souvient. D'une session Ă  l'autre, DeerFlow construit une mĂ©moire persistante de votre profil, de vos prĂ©fĂ©rences et de vos connaissances accumulĂ©es. Plus vous l'utilisez, mieux il vous connaĂźt — votre style d'Ă©criture, votre stack technique, vos workflows rĂ©currents. La mĂ©moire est stockĂ©e localement et reste sous votre contrĂŽle. Les mises Ă  jour de la mĂ©moire ignorent dĂ©sormais les entrĂ©es de faits en double au moment de l'application, de sorte que les prĂ©fĂ©rences et le contexte rĂ©pĂ©tĂ©s ne s'accumulent plus indĂ©finiment entre les sessions. ## ModĂšles recommandĂ©s DeerFlow est agnostique en termes de modĂšle — il fonctionne avec n'importe quel LLM implĂ©mentant l'API compatible OpenAI. Cela dit, il offre de meilleures performances avec des modĂšles qui supportent : - **De longues fenĂȘtres de contexte** (100k+ tokens) pour la recherche approfondie et les tĂąches multi-Ă©tapes - **Des capacitĂ©s de raisonnement** pour la planification adaptative et la dĂ©composition de tĂąches complexes - **Des entrĂ©es multimodales** pour la comprĂ©hension d'images et de vidĂ©os - **Un usage fiable des outils (tool use)** pour des appels de fonctions et des sorties structurĂ©es fiables ## Client Python intĂ©grĂ© DeerFlow peut ĂȘtre utilisĂ© comme bibliothĂšque Python intĂ©grĂ©e sans lancer l'ensemble des services HTTP. Le `DeerFlowClient` fournit un accĂšs direct in-process Ă  toutes les capacitĂ©s d'agent et de Gateway, en retournant les mĂȘmes schĂ©mas de rĂ©ponse que l'API HTTP Gateway. Le HTTP Gateway expose Ă©galement `DELETE /api/threads/{thread_id}` pour supprimer les donnĂ©es de thread locales gĂ©rĂ©es par DeerFlow aprĂšs la suppression du thread LangGraph : ```python 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") ``` Toutes les mĂ©thodes retournant des dicts sont validĂ©es en CI contre les modĂšles de rĂ©ponse Pydantic du Gateway (`TestGatewayConformance`), garantissant que le client intĂ©grĂ© reste synchronisĂ© avec les schĂ©mas de l'API HTTP. Voir `backend/packages/harness/deerflow/client.py` pour la documentation API complĂšte. ## Projets Les projets regroupent des conversations liĂ©es sous un nom partagĂ©, des instructions et une Ă©tagĂšre de documents. Une conversation rejoint un projet au moment de sa crĂ©ation (lorsqu'un projet est sĂ©lectionnĂ©) ou plus tard via le menu de dĂ©placement. Les exĂ©cutions ne modifient jamais l'appartenance : l'envoi d'un message ne peut pas affecter ou rĂ©affecter une conversation. DĂ©placer une conversation hors d'un projet la laisse non affectĂ©e jusqu'Ă  ce qu'elle soit Ă  nouveau explicitement dĂ©placĂ©e. Le dĂ©placement d'une conversation actualise son rattachement dans l'en-tĂȘte ainsi que les listes de projets, y compris lorsqu'une requĂȘte de mĂ©tadonnĂ©es plus ancienne est encore en cours. Les projets exigent les tables et colonnes de base de donnĂ©es actuelles. Une base de donnĂ©es estampillĂ©e `0019_thread_incarnations` issue de l'ancien dĂ©ploiement basĂ© sur 0018 est rejetĂ©e au dĂ©marrage si le schĂ©ma des projets est absent. Suivez la [procĂ©dure de rĂ©cupĂ©ration hors ligne de la base de donnĂ©es](docs/database-forward-revision-recovery.md) avant de dĂ©marrer ce build sur cette base. ### Instructions de projet Chaque projet stocke des instructions en forme libre — contexte, conventions et contraintes s'appliquant Ă  toutes les conversations du projet — modifiables dans l'onglet Instructions de la page du projet, avec un compteur d'octets en direct. Lorsqu'une exĂ©cution dĂ©marre sur un thread membre, le Gateway fige une seule fois l'Ă©tat actuel du projet et rend les instructions sous forme d'un bloc `` bornĂ©, propre Ă  cette requĂȘte et rĂ©servĂ© Ă  cette exĂ©cution : le bloc n'entre jamais dans le prompt systĂšme ni dans l'historique persistĂ©, et chaque nouvelle exĂ©cution voit les derniĂšres instructions enregistrĂ©es. Les instructions sont plafonnĂ©es Ă  `projects.instructions_max_bytes` octets UTF-8 (par dĂ©faut 8192, plage 256–262144) ; les caractĂšres multioctets comptent pour leur longueur en octets UTF-8. Les instructions trop longues sont rejetĂ©es avec un `422` Ă  l'Ă©criture et ne sont jamais tronquĂ©es silencieusement. ### ÉtagĂšre de documents Chaque projet dispose d'une Ă©tagĂšre de documents pour les fichiers partagĂ©s par l'ensemble du projet, gĂ©rĂ©e depuis la section Documents de la page du projet : - **TĂ©lĂ©verser** un fichier (bouton ou glisser-dĂ©poser, un fichier par requĂȘte). Les limites de taille de l'Ă©tagĂšre rĂ©utilisent `uploads.max_file_size` (par dĂ©faut 50 Mio) ; re-tĂ©lĂ©verser un contenu identique renvoie l'entrĂ©e existante au lieu de crĂ©er un doublon. - **Lister** les entrĂ©es avec leur nom, taille, date de modification et provenance (tĂ©lĂ©versĂ©es vs. enregistrĂ©es depuis une conversation), et prĂ©visualiser ou tĂ©lĂ©charger n'importe quelle entrĂ©e. - **Enregistrer dans le projet** depuis un fichier de thread : le navigateur en lecture seule des fichiers de conversation sous l'Ă©tagĂšre liste les tĂ©lĂ©versements et sorties des threads membres, chacun avec une action « Enregistrer dans le projet ». - **Joindre Ă  un thread** : copier un fichier de l'Ă©tagĂšre vers les tĂ©lĂ©versements d'un thread via le pipeline d'ingestion normal, pour que la conversation puisse l'utiliser directement. Les exĂ©cutions sur les threads membres reçoivent Ă©galement un index `` bornĂ©, rendu Ă  chaque exĂ©cution Ă  partir de l'instantanĂ© figĂ© (limitĂ© par `projects.shelf_index_max_entries` et `projects.shelf_index_max_bytes`), et l'agent peut parcourir l'Ă©tagĂšre et lire les documents avec les outils `list_project_documents` et `read_project_document`. ### SĂ©mantique de lecture des projets archivĂ©s Archiver un projet gĂšle les Ă©critures mais conserve les lectures. Les threads d'un projet archivĂ© s'exĂ©cutent toujours et reçoivent toujours les instructions du projet et l'index de l'Ă©tagĂšre, et l'Ă©tagĂšre reste entiĂšrement lisible : listage, prĂ©visualisation/tĂ©lĂ©chargement, navigateur de fichiers de conversation et jonction Ă  un thread continuent de fonctionner. Les tĂ©lĂ©versements, l'enregistrement dans le projet et le dĂ©placement de fichiers individuels de l'Ă©tagĂšre vers la corbeille exigent un projet actif, et un document mis Ă  la corbeille ne peut pas ĂȘtre restaurĂ© dans un projet archivĂ©. La suppression d'un projet archivĂ© reste possible et dĂ©place toute son Ă©tagĂšre vers la corbeille. ### Corbeille Supprimer un document de l'Ă©tagĂšre le dĂ©place vers la corbeille au lieu de l'effacer : l'entrĂ©e conserve ses octets et un instantanĂ© de son projet d'origine pendant `projects.trash_retention_days` (par dĂ©faut 30) avant que le balayage de rĂ©tention puisse la purger dĂ©finitivement. La page `/workspace/trash` — accessible depuis la section Documents de la page du projet et l'en-tĂȘte Projets de la barre latĂ©rale — liste les documents mis Ă  la corbeille avec leur projet d'origine et la rĂ©tention restante, avec des actions Restaurer et Supprimer dĂ©finitivement par entrĂ©e, plus une action Vider la corbeille qui supprime dĂ©finitivement tous les documents de la corbeille — immĂ©diatement, et non aprĂšs la fenĂȘtre de rĂ©tention ; la fenĂȘtre ne fait que borner la durĂ©e pendant laquelle une entrĂ©e peut y rester avant que le balayage de rĂ©tention ne la rĂ©cupĂšre. La restauration renvoie le document Ă  son projet d'origine, ou Ă  un projet de votre choix lorsque l'origine a disparu ou est archivĂ©e ; si la cible contient dĂ©jĂ  un fichier actif identique, les entrĂ©es fusionnent. La suppression d'un projet dĂ©place toute son Ă©tagĂšre vers la corbeille en une seule Ă©tape. ## TĂąches planifiĂ©es (Scheduled Tasks) DeerFlow inclut dĂ©sormais un MVP de tĂąches planifiĂ©es (scheduled-task) de premier niveau dans le workspace. CapacitĂ©s actuelles du MVP : - GĂ©rer les tĂąches depuis `/workspace/scheduled-tasks` - Choisir si chaque tĂąche planifiĂ©e rĂ©utilise un thread ou crĂ©e un nouveau thread Ă  chaque exĂ©cution - Prendre en charge les planifications `once`, `cron` et `interval` - ExĂ©cuter les tĂąches planifiĂ©es en arriĂšre-plan comme des exĂ©cutions DeerFlow non interactives (`ask_clarification` n'y est pas exposĂ©) - Utiliser le comportement de chevauchement `skip` pour les exĂ©cutions cron dues qui entrent en collision avec une exĂ©cution active sur le mĂȘme thread rĂ©utilisĂ© - Mettre en pause, reprendre, dĂ©clencher, inspecter l'historique et supprimer les tĂąches - ExĂ©cuter le travail planifiĂ© via le cycle de vie d'exĂ©cution normal de DeerFlow Limites actuelles du MVP : - Pas de tĂąches de notification en texte seul - Pas de cibles de dispatch canal ou GitHub Activez le polling en arriĂšre-plan avec `config.yaml -> scheduler.enabled`. Le dĂ©clenchement manuel utilise la mĂȘme ressource scheduled-task et le mĂȘme chemin d'exĂ©cution. ### Cycle de vie, plafonds de sĂ©curitĂ© et conditions d'arrĂȘt - La page des tĂąches et l'API REST (`POST` / `PATCH /api/scheduled-tasks`) acceptent un objectif par exĂ©cution (`goal_objective`), un plafond de sĂ©curitĂ© (`max_runs`, `end_at`) et une condition d'arrĂȘt (`stop_condition`). Envoyer `null` dans un PATCH efface l'un de ces quatre champs ; un `end_at` sans dĂ©calage UTC est une heure locale dans le fuseau de la tĂąche. - La condition d'arrĂȘt est la rĂšgle « arrĂȘte-toi quand 
 » de l'utilisateur. Elle est stockĂ©e dans un champ dĂ©diĂ© (migration `0031`), jamais dans les instructions de la tĂąche. DeerFlow ne l'ajoute au message d'une exĂ©cution qu'au moment oĂč celle-ci dĂ©marre, en lui demandant d'appeler `stop_scheduled_task` lorsque la rĂšgle est remplie. Lorsque `scheduler.tool_enabled` est activĂ©, chaque exĂ©cution planifiĂ©e peut mettre en pause sa propre planification, que la tĂąche ait Ă©tĂ© crĂ©Ă©e dans une conversation ou sur la page des tĂąches ; sinon, l'exĂ©cution signale simplement que la rĂšgle est remplie. - Les tĂąches avec objectif crĂ©Ă©es sur la page des tĂąches sont dĂ©sormais Ă©valuĂ©es comme celles crĂ©Ă©es dans une conversation, et leurs exĂ©cutions reçoivent aussi les notes enregistrĂ©es et la rĂ©fĂ©rence Ă  l'exĂ©cution prĂ©cĂ©dente. - La reprise calcule la prochaine exĂ©cution Ă  partir de maintenant : une longue pause ne dĂ©clenche jamais d'exĂ©cution de rattrapage. Une tĂąche ponctuelle dont l'heure est passĂ©e renvoie `422 once_time_passed` et demande une nouvelle heure. Reprendre une tĂąche active ne change rien ; mettre en pause une tĂąche terminĂ©e renvoie `409 task_finished`. - `max_runs` compte les exĂ©cutions automatiques sur toute la vie de la tĂąche ; les exĂ©cutions d'essai ne comptent jamais. RĂ©activer une tĂąche dont le plafond est atteint (reprise, ou PATCH qui rĂ©arme la planification d'une tĂąche terminĂ©e) renvoie `409 limits_exhausted`, sauf si la mĂȘme requĂȘte renouvelle la limite Ă©puisĂ©e : un nombre d'exĂ©cutions Ă©puisĂ© demande un `max_runs` plus Ă©levĂ© ou `null`, une heure de fin dĂ©passĂ©e demande un `end_at` plus tardif ou `null` (repousser `end_at` seul ne relance pas une tĂąche dont `max_runs` est Ă©puisĂ©). `POST /api/scheduled-tasks/{task_id}/resume` accepte pour cela un corps facultatif `{"max_runs": 
, "end_at": 
}` (`null` supprime un plafond). Un PATCH qui ne change que le plafond d'une tĂąche terminĂ©e l'enregistre et la laisse terminĂ©e. - Les Ă©checs de vĂ©rification de l'objectif (Ă©valuateur en Ă©chec, ou conversation modifiĂ©e pendant la vĂ©rification) ne comptent pas pour la pause automatique aprĂšs trois Ă©checs et ne remettent pas le compteur Ă  zĂ©ro. Modifier l'objectif, les instructions ou la condition d'arrĂȘt, ou ajouter une note, repart d'un nouveau compte ; la reprise le conserve. - Tant que le planificateur de ce processus Gateway ne tourne pas, la crĂ©ation d'une tĂąche (y compris la duplication) renvoie `409 scheduler_not_running`. `GET /api/features` expose `scheduled_tasks.available`, `running`, `tool_enabled` et `min_interval_seconds`. - Les erreurs de `/api/scheduled-tasks*` ont la forme `{"detail": {"code", "message", "params"}}` ; voir [`backend/docs/API.md`](backend/docs/API.md#scheduled-tasks) et `contracts/scheduled_task_errors_contract.json`. - Les crĂ©neaux d'exĂ©cution sont partagĂ©s Ă©quitablement entre les propriĂ©taires des tĂąches : un mĂȘme propriĂ©taire peut avoir au plus `scheduler.max_concurrent_runs_per_user` exĂ©cutions planifiĂ©es en dĂ©marrage ou en cours Ă  la fois (2 par dĂ©faut, jamais plus que `max_concurrent_runs` ; `0` dĂ©sactive ce plafond par propriĂ©taire), et la file d'attente est vidĂ©e propriĂ©taire par propriĂ©taire, si bien que l'arriĂ©rĂ© de l'un ne retarde jamais l'exĂ©cution d'un autre. Une exĂ©cution qui attend plus longtemps que `scheduler.queue_timeout_seconds` est ignorĂ©e, et l'historique indique qu'elle a attendu trop longtemps un crĂ©neau libre. - Avec `channel_connections.enabled: true`, les mises Ă  jour des tĂąches planifiĂ©es sont envoyĂ©es aux identitĂ©s IM connectĂ©es du propriĂ©taire, uniquement sur les applications qui gĂšrent l'envoi proactif (WeCom aujourd'hui) ; les paramĂštres indiquent pour chaque application si les mises Ă  jour y sont envoyĂ©es. Chaque occurrence envoie au plus un message (exĂ©cution terminĂ©e, en Ă©chec ou objectif non atteint, pause automatique, pause par l'agent, fin de la tĂąche), mis en file dans la mĂȘme transaction que le rĂ©sultat, donc une seule fois mĂȘme aprĂšs une reprise sur panne. Le message se lit seul, dans la langue de votre interface web (sinon `channel_connections.notification_locale`), sans identifiants ni liens. Les essais manuels simples et les exĂ©cutions interrompues ne notifient pas. ### CrĂ©er des planifications dans une conversation Activez `scheduler.enabled: true` et `scheduler.tool_enabled: true`, puis redĂ©marrez le Gateway. Un tour interactif autorisĂ© peut alors utiliser `schedule_task` pour crĂ©er, modifier, lister, mettre en pause, reprendre ou supprimer des tĂąches, lancer une exĂ©cution d'essai ou enregistrer une note. Par exemple : « Chaque jour ouvrĂ© Ă  9 h, vĂ©rifie release-checklist.md et dis-moi ce qui n'est pas cochĂ© ; arrĂȘte-toi quand tout est cochĂ©. » Dans l'application web, le rĂ©sultat s'affiche sous forme de carte mise Ă  jour en direct (planification, condition d'arrĂȘt, boutons) et l'agent rĂ©pond en une ou deux phrases ; dans les messageries (IM) et les autres tours hors web, il dĂ©crit en texte la planification, la prochaine exĂ©cution et la condition d'arrĂȘt. - **TĂąches gĂ©rĂ©es par une conversation.** Celles qui y ont Ă©tĂ© crĂ©Ă©es et, dans une conversation d'exĂ©cution (le chat oĂč une exĂ©cution planifiĂ©e a publiĂ© son rĂ©sultat), la tĂąche de cette exĂ©cution : « mets-la en pause » ou « passe-la Ă  10 h » y fonctionnent aussi. Cela ne vaut que pour les messages que vous envoyez ; une exĂ©cution planifiĂ©e ne peut que mettre en pause sa propre planification avec `stop_scheduled_task`. - **Une modification garde la tĂąche.** Changer l'horaire, les instructions, l'objectif, la condition d'arrĂȘt ou le plafond de sĂ©curitĂ© est un `update` de la mĂȘme tĂąche : son identifiant et son historique sont conservĂ©s. `resume` relance une tĂąche en pause ou terminĂ©e, sans exĂ©cution de rattrapage. Si le plafond est atteint, l'agent demande comment renouveler la limite Ă©puisĂ©e (relever `max_runs` ou le supprimer ; repousser `end_at` ou le supprimer), puis l'envoie avec la reprise. - **Fuseau horaire.** Un fuseau que vous nommez l'emporte. Sinon, une nouvelle tĂąche utilise le fuseau du navigateur que l'application web envoie avec chaque message (`context.client_timezone`, lu uniquement pour cela), et le rĂ©sultat indique le fuseau retenu. Les intervalles et les heures ponctuelles avec dĂ©calage UTC n'en ont pas besoin ; pour un cron ou une heure locale ponctuelle sans fuseau connu (par exemple depuis une messagerie), l'agent pose la question. Une modification garde le fuseau enregistrĂ© ; le fuseau du navigateur ne change jamais une tĂąche existante. - **OĂč apparaissent les rĂ©sultats.** Chaque exĂ©cution publie son rĂ©sultat dans un nouveau chat intitulĂ© « {tĂąche} · {heure locale} », ou dans le chat d'origine lorsque la tĂąche s'y exĂ©cute. Quand le planning est mis en pause par l'agent, mis en pause automatiquement ou se termine, le chat d'origine affiche une ligne Ă  l'endroit oĂč en Ă©tait la conversation, avec un lien vers cette exĂ©cution ou vers la tĂąche ; rien d'autre n'y est renvoyĂ©. La ligne reste aprĂšs la suppression de la tĂąche. Le chat d'exĂ©cution affiche les instructions de la tĂąche dans un bloc repliĂ© « Instructions de la tĂąche » sous l'en-tĂȘte de l'exĂ©cution. - **Langue.** L'agent rĂ©dige le titre, les instructions et la condition d'arrĂȘt dans votre langue, et les exĂ©cutions planifiĂ©es rĂ©pondent dans la langue des instructions. - **Essai.** Demandez-le directement, par exemple « Run it now » ou « ć…ˆè·‘äž€æŹĄć§ » ; le bouton **Run once now** de la carte fait de mĂȘme. Un simple « yes », une mention de la tĂąche ou une demande citĂ©e ou conditionnelle ne lance pas d'exĂ©cution payante. Un essai ne compte pas dans `max_runs`. ## Atelier terminal (TUI) `deerflow` est un atelier natif terminal pour ceux qui vivent dans le shell. Il s'exĂ©cute de maniĂšre **intĂ©grĂ©e** sur `DeerFlowClient` — pas besoin de Gateway, de frontend, de nginx ou de Docker — tout en honorant les mĂȘmes `config.yaml`, checkpointer, skills, mĂ©moire, MCP et sandbox que le reste de DeerFlow. ![DeerFlow TUI](docs/tui/tui-preview.svg) ```bash uv pip install 'deerflow-harness[tui]' # dĂ©pendance optionnelle 'textual' deerflow # lancer l'UI terminal (TTY requis) deerflow --continue # reprendre le thread le plus rĂ©cent deerflow --resume THREAD # reprendre un thread par id deerflow --print "summarize this repo" # rĂ©ponse one-shot headless vers stdout deerflow --json "hello" # StreamEvents sĂ©parĂ©s par saut de ligne en mode headless ``` Une surface de chat pilotĂ©e au clavier avec un transcript en streaming (rĂ©ponses rendues en Markdown), des cartes d'activitĂ© d'outils compactes, une palette de commandes slash `/`, la gestion des goal via `/goal`, des sĂ©lecteurs `/model` et `/threads`, l'historique de saisie, et l'interruption via `Esc` / `Ctrl+C`. Les sessions ouvertes dans le TUI apparaissent aussi dans la barre latĂ©rale du Web UI — elles Ă©crivent dans le magasin de threads partagĂ© sous l'utilisateur local par dĂ©faut, donc le terminal et le web restent synchronisĂ©s **sans lancer la Gateway**. Voir [backend/docs/TUI.md](backend/docs/TUI.md) pour le guide complet. ## Documentation - [Guide de contribution](CONTRIBUTING.md) - Mise en place de l'environnement de dĂ©veloppement et workflow - [Guide de configuration](backend/docs/CONFIGURATION.md) - Instructions d'installation et de configuration - [Vue d'ensemble de l'architecture](backend/CLAUDE.md) - DĂ©tails de l'architecture technique - [Architecture backend](backend/README.md) - Architecture backend et rĂ©fĂ©rence API ## ⚠ Avertissement de sĂ©curitĂ© ### Un dĂ©ploiement inappropriĂ© peut introduire des risques de sĂ©curitĂ© DeerFlow dispose de capacitĂ©s clĂ©s Ă  hauts privilĂšges, notamment **l'exĂ©cution de commandes systĂšme, les opĂ©rations sur les ressources et l'invocation de logique mĂ©tier**. Il est conçu par dĂ©faut pour ĂȘtre **dĂ©ployĂ© dans un environnement local de confiance (accessible uniquement via l'interface de loopback 127.0.0.1)**. Si vous dĂ©ployez l'agent dans des environnements non fiables — tels que des rĂ©seaux LAN, des serveurs cloud publics ou d'autres environnements accessibles depuis plusieurs terminaux — sans mesures de sĂ©curitĂ© strictes, cela peut introduire des risques, notamment : - **Invocation non autorisĂ©e** : les fonctionnalitĂ©s de l'agent pourraient ĂȘtre dĂ©couvertes par des tiers non autorisĂ©s ou des scanners malveillants, dĂ©clenchant des requĂȘtes non autorisĂ©es en masse qui exĂ©cutent des opĂ©rations Ă  haut risque (commandes systĂšme, lecture/Ă©criture de fichiers), pouvant causer de graves consĂ©quences. - **Risques juridiques et de conformitĂ©** : si l'agent est utilisĂ© illĂ©galement pour mener des cyberattaques, du vol de donnĂ©es ou d'autres activitĂ©s illicites, cela peut entraĂźner des responsabilitĂ©s juridiques et des risques de conformitĂ©. ### Recommandations de sĂ©curitĂ© **Note : nous recommandons fortement de dĂ©ployer DeerFlow dans un environnement rĂ©seau local de confiance.** Si vous avez besoin d'un dĂ©ploiement multi-appareils ou multi-rĂ©seaux, vous devez mettre en place des mesures de sĂ©curitĂ© strictes, par exemple : - **Liste blanche d'IP** : utilisez `iptables`, ou dĂ©ployez des pare-feux matĂ©riels / commutateurs avec ACL, pour **configurer des rĂšgles de liste blanche d'IP** et refuser l'accĂšs Ă  toutes les autres adresses IP. - **Passerelle d'authentification** : configurez un proxy inverse (ex. nginx) et **activez une authentification forte en amont**, bloquant tout accĂšs non authentifiĂ©. - **Isolation rĂ©seau** : si possible, placez l'agent et les appareils de confiance dans le **mĂȘme VLAN dĂ©diĂ©**, isolĂ© des autres Ă©quipements rĂ©seau. - **Restez informĂ©** : continuez Ă  suivre les mises Ă  jour de sĂ©curitĂ© du projet DeerFlow. ## Contribuer Les contributions sont les bienvenues ! Consultez [CONTRIBUTING.md](CONTRIBUTING.md) pour la mise en place de l'environnement de dĂ©veloppement, le workflow et les conventions. La couverture de tests de rĂ©gression inclut la dĂ©tection du mode sandbox Docker et les tests de gestion du kubeconfig-path du provisioner dans `backend/tests/`. ## Licence Ce projet est open source et disponible sous la [Licence MIT](./LICENSE). ## Remerciements DeerFlow est construit sur le travail remarquable de la communautĂ© open source. Nous sommes profondĂ©ment reconnaissants envers tous les projets et contributeurs dont les efforts ont rendu DeerFlow possible. Nous nous tenons vĂ©ritablement sur les Ă©paules de gĂ©ants. Nous tenons Ă  exprimer notre sincĂšre gratitude aux projets suivants pour leurs contributions inestimables : - **[LangChain](https://github.com/langchain-ai/langchain)** : leur excellent framework propulse nos interactions LLM et nos chaĂźnes, permettant une intĂ©gration et des fonctionnalitĂ©s fluides. - **[LangGraph](https://github.com/langchain-ai/langgraph)** : leur approche innovante de l'orchestration multi-agents a Ă©tĂ© dĂ©terminante pour les workflows sophistiquĂ©s de DeerFlow. Ces projets illustrent le pouvoir transformateur de la collaboration open source, et nous sommes fiers de bĂątir sur leurs fondations. ### Contributeurs principaux Un grand merci aux auteurs principaux de `DeerFlow`, dont la vision, la passion et le dĂ©vouement ont donnĂ© vie Ă  ce projet : - **[Daniel Walnut](https://github.com/hetaoBackend/)** - **[Henry Li](https://github.com/magiccube/)** Votre engagement sans faille et votre expertise sont le moteur du succĂšs de DeerFlow. Nous sommes honorĂ©s de vous avoir Ă  la barre de cette aventure. ## Star History [![Star History Chart](https://star-history.dera.page/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.dera.page/#bytedance/deer-flow&Date)