From 21febe1cc960d4346a6c14d516b828039832c887 Mon Sep 17 00:00:00 2001 From: Emile Jouannet <123695416+Symbioose@users.noreply.github.com> Date: Wed, 25 Mar 2026 01:24:02 +0100 Subject: [PATCH] docs: add French translation of README (#1303) --- README.md | 2 +- README_fr.md | 562 +++++++++++++++++++++++++++++++++++++++++++++++++++ README_ja.md | 2 +- README_zh.md | 2 +- 4 files changed, 565 insertions(+), 3 deletions(-) create mode 100644 README_fr.md diff --git a/README.md b/README.md index c52f453..f9a42a5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # 🩌 DeerFlow - 2.0 -English | [äž­æ–‡](./README_zh.md) | [æ—„æœŹèȘž](./README_ja.md) +English | [äž­æ–‡](./README_zh.md) | [æ—„æœŹèȘž](./README_ja.md) | [Français](./README_fr.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) diff --git a/README_fr.md b/README_fr.md new file mode 100644 index 0000000..3aaefd0 --- /dev/null +++ b/README_fr.md @@ -0,0 +1,562 @@ +# 🩌 DeerFlow - 2.0 + +[English](./README.md) | [äž­æ–‡](./README_zh.md) | [æ—„æœŹèȘž](./README_ja.md) | Français + +[![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 + +[image](https://deerflow.tech) + +DĂ©couvrez-en plus et regardez des **dĂ©mos rĂ©elles** sur notre [**site officiel**](https://deerflow.tech). + +## 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) + - [InfoQuest](#infoquest) + - [Table des matiĂšres](#table-des-matiĂšres) + - [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) + - [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) + - [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Ă©) + - [Documentation](#documentation) + - [Contribuer](#contribuer) + - [Licence](#licence) + - [Remerciements](#remerciements) + - [Contributeurs principaux](#contributeurs-principaux) + - [Star History](#star-history) + +## 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. **GĂ©nĂ©rer les fichiers de configuration locaux** + + Depuis le rĂ©pertoire racine du projet (`deer-flow/`), exĂ©cutez : + + ```bash + make config + ``` + + Cette commande crĂ©e les fichiers de configuration locaux Ă  partir des templates fournis. + +3. **Configurer le(s) modĂšle(s) de votre choix** + + Éditez `config.yaml` et dĂ©finissez au moins un modĂšle : + + ```yaml + models: + - name: gpt-4 # Internal identifier + display_name: GPT-4 # Human-readable name + use: langchain_openai:ChatOpenAI # LangChain class path + model: gpt-4 # Model identifier for API + api_key: $OPENAI_API_KEY # API key (recommended: use env var) + max_tokens: 4096 # Maximum tokens per request + temperature: 0.7 # Sampling temperature + + - 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: $OPENAI_API_KEY # OpenRouter still uses the OpenAI-compatible field name here + 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 + ``` + + 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`. + + 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` + - L'endpoint Responses de Codex rejette actuellement `max_tokens` et `max_output_tokens`, donc `CodexChatModel` n'expose pas de limite de tokens par requĂȘte + - Claude Code accepte `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN_FILE_DESCRIPTOR`, `CLAUDE_CODE_CREDENTIALS_PATH`, ou en clair `~/.claude/.credentials.json` + - Sur macOS, DeerFlow ne sonde pas le Keychain automatiquement. Exportez l'auth Claude Code explicitement si nĂ©cessaire : + + ```bash + eval "$(python3 scripts/export_claude_code_oauth.py --print-export)" + ``` + +4. **DĂ©finir les clĂ©s API pour le(s) modĂšle(s) configurĂ©(s)** + + Choisissez l'une des mĂ©thodes suivantes : + +- Option A : Éditer le fichier `.env` Ă  la racine du projet (recommandĂ©) + + + ```bash + TAVILY_API_KEY=your-tavily-api-key + OPENAI_API_KEY=your-openai-api-key + # OpenRouter also uses OPENAI_API_KEY when your config uses langchain_openai:ChatOpenAI + base_url. + # Add other provider keys as needed + INFOQUEST_API_KEY=your-infoquest-api-key + ``` + +- Option B : Exporter les variables d'environnement dans votre shell + + ```bash + export OPENAI_API_KEY=your-openai-api-key + ``` + + Pour les providers basĂ©s sur un CLI : + - Codex CLI : `~/.codex/auth.json` + - Claude Code OAuth : handoff explicite via env/fichier ou `~/.claude/.credentials.json` + +- Option C : Éditer `config.yaml` directement (non recommandĂ© en production) + + ```yaml + models: + - name: gpt-4 + api_key: your-actual-api-key-here # Replace placeholder + ``` + +### 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 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 serveur d'agents LangGraph fonctionne actuellement via `langgraph dev` (le serveur CLI open source). + +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 config` et clĂ©s API des modĂšles). `make dev` nĂ©cessite un fichier de configuration valide (par dĂ©faut `config.yaml` Ă  la racine du projet ; modifiable via `DEER_FLOW_CONFIG_PATH`). + +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. + +| Canal | Transport | DifficultĂ© | +|---------|-----------|------------| +| Telegram | Bot API (long-polling) | Facile | +| Slack | Socket Mode | ModĂ©rĂ©e | +| Feishu / Lark | WebSocket | ModĂ©rĂ©e | + +**Configuration dans `config.yaml` :** + +```yaml +channels: + # LangGraph Server URL (default: http://localhost:2024) + langgraph_url: http://localhost:2024 + # 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 + + 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: [] # empty = allow all + + # 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 +``` + +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 +``` + +**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`. + +**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. + +## 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. + +### 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": [...]} +``` + +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. + +## 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 + +## 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://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date) diff --git a/README_ja.md b/README_ja.md index 517b74a..f54bf6c 100644 --- a/README_ja.md +++ b/README_ja.md @@ -1,6 +1,6 @@ # 🩌 DeerFlow - 2.0 -[English](./README.md) | [äž­æ–‡](./README_zh.md) | æ—„æœŹèȘž +[English](./README.md) | [äž­æ–‡](./README_zh.md) | æ—„æœŹèȘž | [Français](./README_fr.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) diff --git a/README_zh.md b/README_zh.md index 177806b..602ea78 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,6 +1,6 @@ # 🩌 DeerFlow - 2.0 -[English](./README.md) | äž­æ–‡ | [æ—„æœŹèȘž](./README_ja.md) +[English](./README.md) | äž­æ–‡ | [æ—„æœŹèȘž](./README_ja.md) | [Français](./README_fr.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)