diff --git a/AGENTS.md b/AGENTS.md
index 156e9e6ce..a5f86bd89 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -51,7 +51,7 @@ deer-flow/
├── docker/ # docker-compose files, nginx config, provisioner
├── skills/ # Agent skills: public/ (committed), custom/ (gitignored)
├── contracts/ # Cross-component JSON contracts (e.g. subagent status)
-├── scripts/ # Root orchestration scripts invoked by the Makefile (check, configure, doctor, support_bundle, serve, docker, deploy, setup_wizard)
+├── scripts/ # Root orchestration scripts invoked by the Makefile (check, configure, doctor, support_bundle, serve, nginx, docker, deploy, setup_wizard)
├── tests/ # Root-level tests (currently tests/skills/ — public skill tests)
└── docs/ # Cross-cutting docs, plans, and design notes
```
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
index ffa1ef093..ddfd3b2a9 100644
--- a/CODE_OF_CONDUCT.md
+++ b/CODE_OF_CONDUCT.md
@@ -106,7 +106,7 @@ Violating these terms may lead to a permanent ban.
### 4. Permanent Ban
**Community Impact**: Demonstrating a pattern of violation of community
-standards, including sustained inappropriate behavior, harassment of an
+standards, including sustained inappropriate behavior, harassment of an
individual, or aggression toward or disparagement of classes of individuals.
**Consequence**: A permanent ban from any sort of public interaction within
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7d7670223..07442c630 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -194,12 +194,13 @@ If you need to start services individually:
pnpm dev
```
-2. **Start nginx**:
+2. **Start nginx** (run from the repo root):
```bash
make nginx
- # or directly: nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'
```
+ This runs `scripts/nginx.sh`, which launches nginx in the foreground the same way `scripts/serve.sh` (used by `make dev` / `make start`) does: it pre-creates the `logs/` and `temp/` directories and uses the local dev config at `docker/nginx/nginx.local.conf`.
+
3. **Access the application**:
- Web Interface: http://localhost:2026
@@ -229,12 +230,11 @@ deer-flow/
│ ├── nginx.conf # Nginx config for Docker
│ └── nginx.local.conf # Nginx config for local dev
├── backend/ # Backend application
-│ ├── src/
+│ ├── packages/harness/ # deerflow-harness package (import: deerflow.*)
+│ │ └── deerflow/ # Agents, tools, sandbox, MCP, skills, config
+│ ├── app/ # FastAPI Gateway + IM channels (import: app.*)
│ │ ├── gateway/ # Gateway API and LangGraph-compatible runtime (port 8001)
-│ │ ├── agents/ # LangGraph agent runtime used by Gateway
-│ │ ├── mcp/ # Model Context Protocol integration
-│ │ ├── skills/ # Skills system
-│ │ └── sandbox/ # Sandbox execution
+│ │ └── channels/ # IM channel integrations
│ ├── docs/ # Backend documentation
│ └── Makefile # Backend commands
├── frontend/ # Frontend application
diff --git a/Makefile b/Makefile
index 2385005bb..ce761b31f 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,6 @@
# DeerFlow - Unified Development Environment
-.PHONY: help config config-upgrade check install setup doctor support-bundle detect-thread-boundaries detect-blocking-io dev dev-daemon start start-daemon stop up down clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
+.PHONY: help config config-upgrade check install setup doctor support-bundle detect-thread-boundaries detect-blocking-io dev dev-daemon start start-daemon nginx stop up down clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
BASH ?= bash
BACKEND_UV_RUN = cd backend && uv run
@@ -32,6 +32,7 @@ help:
@echo " make dev-daemon - Start dev services in background (daemon mode)"
@echo " make start - Start all services in production mode (optimized, no hot-reloading)"
@echo " make start-daemon - Start prod services in background (daemon mode)"
+ @echo " make nginx - Start nginx alone in the foreground (local dev config)"
@echo " make stop - Stop all running services"
@echo " make clean - Clean up processes and temporary files"
@echo ""
@@ -116,6 +117,10 @@ start-daemon:
@$(PYTHON) ./scripts/check.py
@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --prod --daemon
+# Start nginx alone in the foreground with the local dev config
+nginx:
+ @$(RUN_WITH_GIT_BASH) ./scripts/nginx.sh
+
# Stop all services
stop:
@$(RUN_WITH_GIT_BASH) ./scripts/serve.sh --stop
diff --git a/README_fr.md b/README_fr.md
index 04b010c2f..ef1a8d0fa 100644
--- a/README_fr.md
+++ b/README_fr.md
@@ -42,6 +42,7 @@ DeerFlow intègre désormais le toolkit de recherche et de crawling intelligent
- [🦌 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)
@@ -94,35 +95,46 @@ Ce prompt est destiné aux coding agents. Il leur demande de cloner le dépôt s
cd deer-flow
```
-2. **Générer les fichiers de configuration locaux**
+2. **Lancer l'assistant de configuration (recommandé)**
Depuis le répertoire racine du projet (`deer-flow/`), exécutez :
```bash
- make config
+ make setup
```
- Cette commande crée les fichiers de configuration locaux à partir des templates fournis.
+ 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.
-3. **Configurer le(s) modèle(s) de votre choix**
+ 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.
- Éditez `config.yaml` et définissez au moins un modèle :
+ > **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-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: 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: $OPENAI_API_KEY # OpenRouter still uses the OpenAI-compatible field name here
+ api_key: $OPENROUTER_API_KEY
base_url: https://openrouter.ai/api/v1
- name: gpt-5-responses
@@ -132,12 +144,26 @@ Ce prompt est destiné aux coding agents. Il leur demande de cloner le dépôt s
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
@@ -158,46 +184,22 @@ Ce prompt est destiné aux coding agents. Il leur demande de cloner le dépôt s
```
- 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 :
+ - 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)"
```
-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é)
-
+ Les clés API peuvent aussi être définies manuellement dans `.env` (recommandé) ou exportées dans votre shell :
```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
+ TAVILY_API_KEY=your-tavily-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
@@ -234,7 +236,8 @@ Voir [CONTRIBUTING.md](CONTRIBUTING.md) pour le guide complet de développement
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`).
+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
diff --git a/README_ja.md b/README_ja.md
index 849bb8454..ae106e42b 100644
--- a/README_ja.md
+++ b/README_ja.md
@@ -42,6 +42,7 @@ DeerFlowは、BytePlusが独自に開発したインテリジェント検索・
- [🦌 DeerFlow - 2.0](#-deerflow---20)
- [公式ウェブサイト](#公式ウェブサイト)
+ - [ByteDance Volcengine のコーディングプラン](#bytedance-volcengine-のコーディングプラン)
- [InfoQuest](#infoquest)
- [目次](#目次)
- [Coding Agent に一文でセットアップを依頼](#coding-agent-に一文でセットアップを依頼)
@@ -94,68 +95,103 @@ DeerFlow がまだ clone されていなければ先に clone してから、htt
cd deer-flow
```
-2. **ローカル設定ファイルの生成**
+2. **セットアップウィザードの実行（推奨）**
プロジェクトルートディレクトリ（`deer-flow/`）から以下を実行します：
```bash
- make config
+ make setup
```
- このコマンドは、提供されたテンプレートに基づいてローカル設定ファイルを作成します。
+ 対話式ウィザードが起動し、LLMプロバイダーの選択、オプションのWeb検索、そしてサンドボックスモード・bash権限・ファイル書き込みツールなどの実行/安全設定を順に案内します。最小構成の`config.yaml`を生成し、APIキーを`.env`に書き込みます。所要時間は約2分です。
-3. **使用するモデルの設定**
+ いつでも`make doctor`を実行して、設定を確認し、具体的な修正ヒントを得られます。
+ ローカルセットアップや実行時の問題についてGitHub issueを起票する場合は、`make support-bundle`を実行してください。このコマンドは報告者向けの次のステップを表示し、issueに貼り付けるための`*-issue-summary.md`ファイルと、AI支援でissueを起票するための`*-issue-draft.md`ファイルを書き出し、オプションで証跡zipを`.deer-flow/support-bundles/`以下に作成します。AIアシスタントがissueを起票する場合は、ドラフトを起点にして、不足している事実を創作するのではなく、すべてのREQUIREDプレースホルダーを置き換えてください。zipは、メンテナーから求められた場合、またはサマリーだけでは不十分な場合にのみ添付してください。メンテナーやAIトリアージツールは`triage.json`から確認を始められます。バンドルに含まれるのはリダクト済みの診断情報とファイルマニフェストのみで、`.env`、生の会話メッセージ、ユーザーファイルの内容は含まれません。
- `config.yaml`を編集し、少なくとも1つのモデルを定義します：
+ > **上級者向け / 手動設定**：`config.yaml`を直接編集したい場合は、代わりに`make config`を実行して完全なテンプレートをコピーしてください。CLI連携プロバイダー（Codex CLI、Claude Code OAuth）、OpenRouter、Responses APIなどを含む完全なリファレンスは`config.example.yaml`を参照してください。
+
+
+ 手動モデル設定の例
```yaml
models:
- - name: gpt-4 # 内部識別子
- display_name: GPT-4 # 表示名
- use: langchain_openai:ChatOpenAI # LangChainクラスパス
- model: gpt-4 # API用モデル識別子
- api_key: $OPENAI_API_KEY # APIキー（推奨：環境変数を使用）
- max_tokens: 4096 # リクエストあたりの最大トークン数
- temperature: 0.7 # サンプリング温度
+ - 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: $OPENAI_API_KEY # OpenRouterもここではOpenAI互換のフィールド名を使用
+ 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`）。
-4. **設定したモデルのAPIキーを設定**
+ OpenAIモデルを`/v1/responses`経由でルーティングするには、引き続き`langchain_openai:ChatOpenAI`を使用し、`use_responses_api: true`と`output_version: responses/v1`を設定してください。
- 以下のいずれかの方法を選択してください：
+ vLLM 0.19.0では`deerflow.models.vllm_provider:VllmChatModel`を使用してください。Qwen系のreasoningモデルでは、DeerFlowは`extra_body.chat_template_kwargs.enable_thinking`でreasoningを切り替え、マルチターンのツールコール会話にわたってvLLM独自の非標準`reasoning`フィールドを保持します。従来の`thinking`設定は後方互換性のため自動的に正規化されます。reasoningモデルはサーバー側で`--reasoning-parser ...`を付けて起動する必要がある場合もあります。ローカルのvLLMデプロイメントが空でない任意のAPIキーを受け付ける場合でも、`VLLM_API_KEY`にはプレースホルダー値を設定しておけます。
-- オプションA：プロジェクトルートの`.env`ファイルを編集（推奨）
-
- ```bash
- TAVILY_API_KEY=your-tavily-api-key
- OPENAI_API_KEY=your-openai-api-key
- # OpenRouterもlangchain_openai:ChatOpenAI + base_url使用時はOPENAI_API_KEYを使用します。
- # 必要に応じて他のプロバイダーキーを追加
- INFOQUEST_API_KEY=your-infoquest-api-key
- ```
-
-- オプションB：シェルで環境変数をエクスポート
-
- ```bash
- export OPENAI_API_KEY=your-openai-api-key
- ```
-
-- オプションC：`config.yaml`を直接編集（本番環境には非推奨）
+ CLI連携プロバイダーの例：
```yaml
models:
- - name: gpt-4
- api_key: your-actual-api-key-here # プレースホルダーを置換
+ - 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`を設定する場合は、`npx -y @zed-industries/codex-acp`のようなCodex ACPアダプターを指定してください
+ - macOSでは、必要に応じてClaude Codeの認証情報を明示的にエクスポートしてください：
+
+ ```bash
+ eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
+ ```
+
+ APIキーは`.env`で手動設定する（推奨）ことも、シェルでエクスポートすることもできます：
+
+ ```bash
+ OPENAI_API_KEY=your-openai-api-key
+ TAVILY_API_KEY=your-tavily-api-key
+ ```
+
+
+
### アプリケーションの実行
#### オプション1: Docker（推奨）
@@ -187,7 +223,8 @@ make down # コンテナを停止して削除
サービスをローカルで実行する場合：
-前提条件：上記の「設定」手順を先に完了してください（`make config`とモデルAPIキー）。`make dev`には有効な設定ファイルが必要です（デフォルトはプロジェクトルートの`config.yaml`。`DEER_FLOW_CONFIG_PATH`で上書き可能）。
+前提条件：上記の「設定」手順を先に完了してください（`make setup`）。`make dev`にはプロジェクトルートに有効な`config.yaml`が必要です。`DEER_FLOW_PROJECT_ROOT`でプロジェクトルートを明示的に指定するか、`DEER_FLOW_CONFIG_PATH`で特定の設定ファイルを指定できます。実行時の状態はデフォルトでプロジェクトルート直下の`.deer-flow`に書き込まれ、`DEER_FLOW_HOME`で移動できます。skillsはデフォルトでプロジェクトルート直下の`skills/`から読み込まれ、`DEER_FLOW_SKILLS_PATH`で移動できます。起動前に`make doctor`を実行して設定を確認してください。
+Windowsでは、ローカル開発フローはGit Bashから実行してください。bashベースのサービススクリプトはネイティブの`cmd.exe`やPowerShellではサポートされておらず、一部のスクリプトがGit for Windowsの`cygpath`などのユーティリティに依存しているため、WSLでの動作も保証されません。
1. **前提条件の確認**：
```bash
diff --git a/README_ru.md b/README_ru.md
index f1a4b9caa..6ee6d8239 100644
--- a/README_ru.md
+++ b/README_ru.md
@@ -44,6 +44,7 @@ DeerFlow интегрирован с инструментарием для ум
- [🦌 DeerFlow - 2.0](#-deerflow---20)
- [Официальный сайт](#официальный-сайт)
+ - [Coding Plan от ByteDance Volcengine](#coding-plan-от-bytedance-volcengine)
- [InfoQuest](#infoquest)
- [Содержание](#содержание)
- [Установка одной фразой для coding agent](#установка-одной-фразой-для-coding-agent)
@@ -96,35 +97,47 @@ DeerFlow интегрирован с инструментарием для ум
cd deer-flow
```
-2. **Сгенерировать локальные конфиги**
+2. **Запустить мастер настройки (рекомендуется)**
Из корня проекта (`deer-flow/`) запустите:
```bash
- make config
+ make setup
```
- Команда создаёт локальные конфиги на основе шаблонов.
+ Запустится интерактивный мастер, который поможет выбрать LLM-провайдера, опциональный веб-поиск и настройки выполнения/безопасности (режим sandbox, доступ к bash, инструменты записи файлов). Он сгенерирует минимальный `config.yaml` и запишет ключи в `.env`. Это занимает около 2 минут.
-3. **Настроить модель**
+ В любой момент запускайте `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` и задайте хотя бы одну модель:
+ > **Продвинутая / ручная настройка**: если вы предпочитаете редактировать `config.yaml` напрямую, выполните вместо этого `make config`, чтобы скопировать полный шаблон. Полный справочник — `config.example.yaml`, включая CLI-провайдеров (Codex CLI, Claude Code OAuth), OpenRouter, Responses API и многое другое.
+
+
+ Примеры ручной настройки моделей
```yaml
models:
- - name: gpt-4 # Внутренний идентификатор
- display_name: GPT-4 # Отображаемое имя
- use: langchain_openai:ChatOpenAI # Путь к классу LangChain
- model: gpt-4 # Идентификатор модели для API
- api_key: $OPENAI_API_KEY # API-ключ (рекомендуется: переменная окружения)
- max_tokens: 4096 # Максимальное количество токенов на запрос
- temperature: 0.7 # Температура сэмплирования
+ - 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: $OPENAI_API_KEY
+ api_key: $OPENROUTER_API_KEY
base_url: https://openrouter.ai/api/v1
- name: gpt-5-responses
@@ -134,9 +147,27 @@ DeerFlow интегрирован с инструментарием для ум
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`. Для CLI-провайдеров:
+ 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-провайдеров:
```yaml
models:
@@ -156,30 +187,22 @@ DeerFlow интегрирован с инструментарием для ум
```
- Codex CLI читает `~/.codex/auth.json`
- - Claude Code принимает `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_AUTH_TOKEN` или `~/.claude/.credentials.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 явно:
```bash
eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
```
-4. **Указать API-ключи**
-
- - **Вариант А**: файл `.env` в корне проекта (рекомендуется)
+ API-ключи также можно задать вручную в `.env` (рекомендуется) или экспортировать в оболочке:
```bash
- TAVILY_API_KEY=your-tavily-api-key
OPENAI_API_KEY=your-openai-api-key
- INFOQUEST_API_KEY=your-infoquest-api-key
+ TAVILY_API_KEY=your-tavily-api-key
```
- - **Вариант Б**: переменные окружения в терминале
-
- ```bash
- export OPENAI_API_KEY=your-openai-api-key
- ```
-
- - **Вариант В**: напрямую в `config.yaml` (не рекомендуется для продакшена)
+
### Запуск
@@ -206,6 +229,9 @@ make down # Остановить и удалить контейнеры
#### Вариант 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. **Проверить зависимости**:
```bash
make check # Проверяет Node.js 22+, pnpm, uv, nginx
diff --git a/README_zh.md b/README_zh.md
index c684de3fe..e3824eb23 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -26,10 +26,21 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
- [现在就加入 Coding Plan](https://www.volcengine.com/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
- [海外地区的开发者请点击这里](https://www.byteplus.com/en/activity/codingplan?utm_campaign=deer_flow&utm_content=deer_flow&utm_medium=devrel&utm_source=OWO&utm_term=deer_flow)
+## InfoQuest
+
+DeerFlow 新近集成了 BytePlus 自研的智能搜索与抓取工具集——[InfoQuest（支持免费在线体验）](https://docs.byteplus.com/en/docs/InfoQuest/What_is_Info_Quest)
+
+
+ 
+
+
## 目录
- [🦌 DeerFlow - 2.0](#-deerflow---20)
- [官网](#官网)
+ - [字节跳动火山引擎方舟 Coding Plan](#字节跳动火山引擎方舟-coding-plan)
- [InfoQuest](#infoquest)
- [目录](#目录)
- [一句话交给 Coding Agent 安装](#一句话交给-coding-agent-安装)
@@ -84,68 +95,111 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
cd deer-flow
```
-2. **生成本地配置文件**
+2. **运行安装向导（推荐）**
在项目根目录（`deer-flow/`）执行：
```bash
- make config
+ make setup
```
- 这个命令会基于示例模板生成本地配置文件。
+ 这会启动一个交互式向导，引导你选择 LLM provider、可选的 web 搜索工具，以及 sandbox 模式、bash 权限、文件写入等执行/安全偏好。它会生成一份最小化的 `config.yaml`，并把 API key 写入 `.env`，大约 2 分钟完成。
-3. **配置你要使用的模型**
+ 随时可以运行 `make doctor` 检查配置和系统环境，并获得可执行的修复建议。
+ 如果你要提交本地安装、配置或运行问题，可以执行 `make support-bundle`。
+ 命令会直接打印 reporter 下一步建议，并在 `.deer-flow/support-bundles/` 下生成
+ `*-issue-summary.md`、面向 AI 辅助提 issue 的 `*-issue-draft.md`，以及可选证据
+ zip。提交 GitHub issue 时，先把 `*-issue-summary.md` 粘贴到 issue 正文；如果由
+ AI 助手代填 issue，就从 `*-issue-draft.md` 开始，并先替换所有 REQUIRED 占位符，
+ 不要编造未知事实。只有维护者要求证据包，或摘要不足以诊断时，再附上 zip。维护者
+ 或 AI 辅助 triage 可以优先读取 `triage.json`；bundle 只包含脱敏后的诊断信息和
+ 文件 manifest，不包含 `.env`、原始对话消息或用户文件内容；提交前仍建议自己快速
+ 检查一遍。
- 编辑 `config.yaml`，至少定义一个模型：
+ > **进阶 / 手动配置**：如果你更想直接编辑 `config.yaml`，可以改用 `make config` 复制完整的示例模板。完整参考见 `config.example.yaml`，其中包含 CLI-backed provider（Codex CLI、Claude Code OAuth）、OpenRouter、Responses API 等更多配置。
+
+
+ 手动模型配置示例
```yaml
models:
- - name: gpt-4 # 内部标识
- display_name: GPT-4 # 展示名称
- use: langchain_openai:ChatOpenAI # LangChain 类路径
- model: gpt-4 # API 使用的模型标识
- api_key: $OPENAI_API_KEY # API key（推荐使用环境变量）
- max_tokens: 4096 # 单次请求最大 tokens
- temperature: 0.7 # 采样温度
+ - 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: $OPENAI_API_KEY # 这里 OpenRouter 依然沿用 OpenAI 兼容字段名
+ 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` 来配置。如果你更想用 provider 自己的环境变量名，也可以直接把 `api_key` 指向对应变量，例如 `api_key: $OPENROUTER_API_KEY`。
-4. **为已配置的模型设置 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`。对于 Qwen 风格的推理模型，DeerFlow 通过 `extra_body.chat_template_kwargs.enable_thinking` 开关推理，并在多轮 tool-call 对话中保留 vLLM 非标准的 `reasoning` 字段。旧版 `thinking` 配置会自动规范化以保持向后兼容。推理模型可能还需要在启动 vLLM 服务时加上 `--reasoning-parser ...` 参数。如果你的本地 vLLM 部署接受任意非空 API key，可以把 `VLLM_API_KEY` 设为一个占位值。
-- 方式 A：编辑项目根目录下的 `.env` 文件（推荐）
-
- ```bash
- TAVILY_API_KEY=your-tavily-api-key
- OPENAI_API_KEY=your-openai-api-key
- # 如果配置使用的是 langchain_openai:ChatOpenAI + base_url，OpenRouter 也会读取 OPENAI_API_KEY
- # 其他 provider 的 key 按需补充
- INFOQUEST_API_KEY=your-infoquest-api-key
- ```
-
-- 方式 B：在 shell 中导出环境变量
-
- ```bash
- export OPENAI_API_KEY=your-openai-api-key
- ```
-
-- 方式 C：直接编辑 `config.yaml`（不建议用于生产环境）
+ CLI-backed provider 配置示例：
```yaml
models:
- - name: gpt-4
- api_key: your-actual-api-key-here # 替换为真实 key
+ - 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 agent 条目与 model provider 是分开配置的——如果你配置了 `acp_agents.codex`，请把它指向一个 Codex ACP 适配器，例如 `npx -y @zed-industries/codex-acp`
+ - 在 macOS 上，如有需要可显式导出 Claude Code 的认证信息：
+
+ ```bash
+ eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
+ ```
+
+ API key 也可以手动写入 `.env` 文件（推荐）或在 shell 中导出：
+
+ ```bash
+ OPENAI_API_KEY=your-openai-api-key
+ TAVILY_API_KEY=your-tavily-api-key
+ ```
+
+
+
### 运行应用
#### 部署建议与资源规划
@@ -191,7 +245,7 @@ make down # 停止并移除容器
如果你更希望直接在本地启动各个服务：
-前提：先完成上面的“配置”步骤（`make config` 和模型 API key 配置）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`。可以用 `DEER_FLOW_PROJECT_ROOT` 显式指定项目根目录，也可以用 `DEER_FLOW_CONFIG_PATH` 指向某个具体配置文件。运行期状态默认写到项目根目录下的 `.deer-flow`，可用 `DEER_FLOW_HOME` 覆盖；skills 默认读取项目根目录下的 `skills/`，可用 `DEER_FLOW_SKILLS_PATH` 覆盖。
+前提：先完成上面的“配置”步骤（`make setup`）。`make dev` 需要有效配置文件，默认读取项目根目录下的 `config.yaml`。可以用 `DEER_FLOW_PROJECT_ROOT` 显式指定项目根目录，也可以用 `DEER_FLOW_CONFIG_PATH` 指向某个具体配置文件。运行期状态默认写到项目根目录下的 `.deer-flow`，可用 `DEER_FLOW_HOME` 覆盖；skills 默认读取项目根目录下的 `skills/`，可用 `DEER_FLOW_SKILLS_PATH` 覆盖。启动前先运行 `make doctor` 校验配置。
在 Windows 上，请使用 Git Bash 运行本地开发流程。基于 bash 的服务脚本不支持直接在原生 `cmd.exe` 或 PowerShell 中执行，且 WSL 也不保证可用，因为部分脚本依赖 Git for Windows 的 `cygpath` 等工具。
1. **检查依赖环境**：
@@ -199,21 +253,6 @@ make down # 停止并移除容器
make check # 校验 Node.js 22+、pnpm、uv、nginx
```
- 如果你要提交本地安装、配置或运行问题，可以执行：
-
- ```bash
- make support-bundle
- ```
-
- 命令会直接打印 reporter 下一步建议，并在 `.deer-flow/support-bundles/` 下生成
- `*-issue-summary.md`、面向 AI 辅助提 issue 的 `*-issue-draft.md`，以及可选证据
- zip。提交 GitHub issue 时，先把 `*-issue-summary.md` 粘贴到 issue 正文；如果由
- AI 助手代填 issue，就从 `*-issue-draft.md` 开始，并先替换所有 REQUIRED 占位符，
- 不要编造未知事实。只有维护者要求证据包，或摘要不足以诊断时，再附上 zip。维护者
- 或 AI 辅助 triage 可以优先读取 `triage.json`；bundle 只包含脱敏后的诊断信息和
- 文件 manifest，不包含 `.env`、原始对话消息或用户文件内容；提交前仍建议自己快速
- 检查一遍。
-
2. **安装依赖**：
```bash
make install # 安装 backend + frontend 依赖
diff --git a/SECURITY.md b/SECURITY.md
index 459654a0a..4345ecfcf 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,10 +2,10 @@
## Supported Versions
-As deer-flow doesn't provide an official release yet, please use the latest version for the security updates.
+As deer-flow doesn't provide an official release yet, please use the latest version to receive security updates.
Currently, we have two branches to maintain:
* main branch for deer-flow 2.x
-* main-1.x branch for deer-flow 1.x
+* main-1.x branch for deer-flow 1.x
## Reporting a Vulnerability
diff --git a/backend/AGENTS.md b/backend/AGENTS.md
index a310f317a..1aba52051 100644
--- a/backend/AGENTS.md
+++ b/backend/AGENTS.md
@@ -360,17 +360,16 @@ Proxied through nginx: `/api/langgraph/*` → Gateway LangGraph-compatible runti
- `tavily/` - Web search (5 results default) and web fetch (4KB limit)
- `jina_ai/` - Web fetch via Jina reader API with readability extraction
- `firecrawl/` - Web scraping via Firecrawl API
-- `image_search/` - Image search
+- `image_search/` - Image search via DuckDuckGo
- `aio_sandbox/` - Docker-based isolation (`AioSandboxProvider`)
-Additional providers also live here (`brave`, `browserless`, `crawl4ai`, `ddg_search`, `exa`, `fastcrw`, `groundroute`, `infoquest`, `searxng`, `serper`); see each subpackage for specifics.
+Additional providers also live here (`brave`, `browserless`, `crawl4ai`, `ddg_search`, `e2b_sandbox`, `exa`, `fastcrw`, `groundroute`, `infoquest`, `searxng`, `serper`); see each subpackage for specifics.
**ACP agent tools**:
- `invoke_acp_agent` - Invokes external ACP-compatible agents from `config.yaml`
- ACP launchers must be real ACP adapters. The standard `codex` CLI is not ACP-compatible by itself; configure a wrapper such as `npx -y @zed-industries/codex-acp` or an installed `codex-acp` binary
- Missing ACP executables now return an actionable error message instead of a raw `[Errno 2]`
- Each ACP agent uses a per-thread workspace at `{base_dir}/users/{user_id}/threads/{thread_id}/acp-workspace/`. The workspace is accessible to the lead agent via the virtual path `/mnt/acp-workspace/` (read-only). In docker sandbox mode, the directory is volume-mounted into the container at `/mnt/acp-workspace` (read-only); in local sandbox mode, path translation is handled by `tools.py`
-- `image_search/` - Image search via DuckDuckGo
### MCP System (`packages/harness/deerflow/mcp/`)
diff --git a/backend/CONTRIBUTING.md b/backend/CONTRIBUTING.md
index fb80615ba..9110dcd94 100644
--- a/backend/CONTRIBUTING.md
+++ b/backend/CONTRIBUTING.md
@@ -63,68 +63,42 @@ make dev
## Project Structure
```
-backend/src/
-├── agents/ # Agent system
-│ ├── lead_agent/ # Main agent implementation
-│ │ └── agent.py # Agent factory and creation
-│ ├── middlewares/ # Agent middlewares
-│ │ ├── thread_data_middleware.py
-│ │ ├── sandbox_middleware.py
-│ │ ├── title_middleware.py
-│ │ ├── uploads_middleware.py
-│ │ ├── view_image_middleware.py
-│ │ └── clarification_middleware.py
-│ └── thread_state.py # Thread state definition
-│
-├── gateway/ # FastAPI Gateway
-│ ├── app.py # FastAPI application
-│ └── routers/ # Route handlers
-│ ├── models.py # /api/models endpoints
-│ ├── mcp.py # /api/mcp endpoints
-│ ├── skills.py # /api/skills endpoints
-│ ├── artifacts.py # /api/threads/.../artifacts
-│ └── uploads.py # /api/threads/.../uploads
-│
-├── sandbox/ # Sandbox execution
-│ ├── __init__.py # Sandbox interface
-│ ├── local.py # Local sandbox provider
-│ └── tools.py # Sandbox tools (bash, file ops)
-│
-├── tools/ # Agent tools
-│ └── builtins/ # Built-in tools
-│ ├── present_file_tool.py
-│ ├── ask_clarification_tool.py
-│ └── view_image_tool.py
-│
-├── mcp/ # MCP integration
-│ └── manager.py # MCP server management
-│
-├── models/ # Model system
-│ └── factory.py # Model factory
-│
-├── skills/ # Skills system
-│ └── loader.py # Skills loader
-│
-├── config/ # Configuration
-│ ├── app_config.py # Main app config
-│ ├── extensions_config.py # Extensions config
-│ └── summarization_config.py
-│
-├── community/ # Community tools
-│ ├── tavily/ # Tavily web search
-│ ├── jina/ # Jina web fetch
-│ ├── firecrawl/ # Firecrawl scraping
-│ ├── fastcrw/ # fastCRW scraping (Firecrawl-compatible)
-│ ├── crawl4ai/ # Crawl4AI web fetch (self-hosted, no key)
-│ └── aio_sandbox/ # Docker sandbox
-│
-├── reflection/ # Dynamic loading
-│ └── __init__.py # Module resolution
-│
-└── utils/ # Utilities
- └── __init__.py
+backend/
+├── packages/harness/deerflow/ # deerflow-harness package (import: deerflow.*)
+│ ├── agents/ # Agent system
+│ │ ├── lead_agent/ # Main agent (agent.py factory, prompt.py)
+│ │ ├── middlewares/ # Agent middleware chain
+│ │ ├── memory/ # Memory extraction & storage
+│ │ └── thread_state.py # Thread state definition
+│ ├── sandbox/ # Sandbox execution
+│ │ ├── local/ # Local sandbox provider
+│ │ ├── sandbox.py # Abstract interface
+│ │ ├── tools.py # Sandbox tools (bash, file ops)
+│ │ └── middleware.py # Sandbox lifecycle
+│ ├── subagents/ # Subagent delegation
+│ ├── tools/builtins/ # Built-in tools
+│ ├── mcp/ # MCP integration
+│ ├── models/ # Model factory
+│ ├── skills/ # Skills system
+│ ├── config/ # Configuration system
+│ ├── runtime/ # Embedded run execution (RunManager, StreamBridge)
+│ ├── persistence/ # Checkpointer/store engines & schema migrations
+│ ├── guardrails/ # Pre-tool-call authorization providers
+│ ├── tracing/ # Tracer factory & trace metadata
+│ ├── uploads/ # Uploads manager
+│ ├── tui/ # Terminal UI (`deerflow` console script)
+│ ├── community/ # Community tools (tavily/, jina_ai/, firecrawl/, …)
+│ ├── reflection/ # Dynamic module loading
+│ └── utils/ # Utilities
+└── app/ # FastAPI Gateway + IM channels (import: app.*)
+ ├── gateway/ # Gateway API
+ │ ├── app.py # FastAPI application
+ │ └── routers/ # Route handlers (threads, models, mcp, skills, uploads, …)
+ └── channels/ # IM channel integrations (Feishu, Slack, Telegram, …)
```
+See [AGENTS.md](AGENTS.md) for the full module-by-module breakdown.
+
## Code Style
### Linting and Formatting
diff --git a/backend/README.md b/backend/README.md
index 13eb130f9..1e3c93c32 100644
--- a/backend/README.md
+++ b/backend/README.md
@@ -221,32 +221,41 @@ Sessions opened in the TUI appear in the Web UI sidebar (it writes the shared
```
backend/
-├── src/
-│ ├── agents/ # Agent system
-│ │ ├── lead_agent/ # Main agent (factory, prompts)
-│ │ ├── middlewares/ # 9 middleware components
-│ │ ├── memory/ # Memory extraction & storage
-│ │ └── thread_state.py # ThreadState schema
-│ ├── gateway/ # FastAPI Gateway API
-│ │ ├── app.py # Application setup
-│ │ └── routers/ # 6 route modules
-│ ├── sandbox/ # Sandbox execution
-│ │ ├── local/ # Local filesystem provider
-│ │ ├── sandbox.py # Abstract interface
-│ │ ├── tools.py # bash, ls, read/write/str_replace
-│ │ └── middleware.py # Sandbox lifecycle
-│ ├── subagents/ # Subagent delegation
-│ │ ├── builtins/ # general-purpose, bash agents
-│ │ ├── executor.py # Background execution engine
-│ │ └── registry.py # Agent registry
-│ ├── tools/builtins/ # Built-in tools
-│ ├── mcp/ # MCP protocol integration
-│ ├── models/ # Model factory
-│ ├── skills/ # Skill discovery & loading
-│ ├── config/ # Configuration system
-│ ├── community/ # Community tools & providers
-│ ├── reflection/ # Dynamic module loading
-│ └── utils/ # Utilities
+├── packages/harness/ # deerflow-harness package (import: deerflow.*)
+│ └── deerflow/
+│ ├── agents/ # Agent system
+│ │ ├── lead_agent/ # Main agent (factory, prompts)
+│ │ ├── middlewares/ # Middleware components
+│ │ ├── memory/ # Memory extraction & storage
+│ │ └── thread_state.py # ThreadState schema
+│ ├── sandbox/ # Sandbox execution
+│ │ ├── local/ # Local filesystem provider
+│ │ ├── sandbox.py # Abstract interface
+│ │ ├── tools.py # bash, ls, read/write/str_replace
+│ │ └── middleware.py # Sandbox lifecycle
+│ ├── subagents/ # Subagent delegation
+│ │ ├── builtins/ # general-purpose, bash agents
+│ │ ├── executor.py # Background execution engine
+│ │ └── registry.py # Agent registry
+│ ├── tools/builtins/ # Built-in tools
+│ ├── mcp/ # MCP protocol integration
+│ ├── models/ # Model factory
+│ ├── skills/ # Skill discovery & loading
+│ ├── config/ # Configuration system
+│ ├── runtime/ # Embedded run execution (RunManager, StreamBridge)
+│ ├── persistence/ # Checkpointer/store engines & schema migrations
+│ ├── guardrails/ # Pre-tool-call authorization providers
+│ ├── tracing/ # Tracer factory & trace metadata
+│ ├── uploads/ # Uploads manager
+│ ├── tui/ # Terminal UI (`deerflow` console script)
+│ ├── community/ # Community tools & providers
+│ ├── reflection/ # Dynamic module loading
+│ └── utils/ # Utilities
+├── app/ # FastAPI Gateway + IM channels (import: app.*)
+│ ├── gateway/ # Gateway API
+│ │ ├── app.py # Application setup
+│ │ └── routers/ # Route modules
+│ └── channels/ # IM channel integrations
├── docs/ # Documentation
├── tests/ # Test suite
├── langgraph.json # LangGraph graph registry for tooling/Studio compatibility
diff --git a/frontend/src/core/i18n/locales/en-US.ts b/frontend/src/core/i18n/locales/en-US.ts
index 86476d03d..ebefa05b9 100644
--- a/frontend/src/core/i18n/locales/en-US.ts
+++ b/frontend/src/core/i18n/locales/en-US.ts
@@ -252,10 +252,10 @@ export const enUS: Translations = {
// Workspace
workspace: {
officialWebsite: "DeerFlow's official website",
- githubTooltip: "DeerFlow on Github",
+ githubTooltip: "DeerFlow on GitHub",
settingsAndMore: "Settings and more",
visitGithub: "DeerFlow on GitHub",
- reportIssue: "Report a issue",
+ reportIssue: "Report an issue",
contactUs: "Contact us",
about: "About DeerFlow",
logout: "Log out",
diff --git a/frontend/src/core/i18n/locales/zh-CN.ts b/frontend/src/core/i18n/locales/zh-CN.ts
index 670897546..18e2f271e 100644
--- a/frontend/src/core/i18n/locales/zh-CN.ts
+++ b/frontend/src/core/i18n/locales/zh-CN.ts
@@ -238,9 +238,9 @@ export const zhCN: Translations = {
// Workspace
workspace: {
officialWebsite: "访问 DeerFlow 官方网站",
- githubTooltip: "访问 DeerFlow 的 Github 仓库",
+ githubTooltip: "访问 DeerFlow 的 GitHub 仓库",
settingsAndMore: "设置和更多",
- visitGithub: "在 Github 上查看 DeerFlow",
+ visitGithub: "在 GitHub 上查看 DeerFlow",
reportIssue: "报告问题",
contactUs: "联系我们",
about: "关于 DeerFlow",
diff --git a/scripts/nginx.sh b/scripts/nginx.sh
new file mode 100755
index 000000000..a7d685289
--- /dev/null
+++ b/scripts/nginx.sh
@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+#
+# nginx.sh — Start nginx alone in the foreground with the local dev config.
+#
+# Mirrors how scripts/serve.sh launches nginx (same prefix, config, and
+# pre-created directories) — keep the two in sync.
+#
+# Usage: make nginx (or ./scripts/nginx.sh from anywhere)
+
+set -e
+
+REPO_ROOT="$(builtin cd "$(dirname "${BASH_SOURCE[0]}")/.." >/dev/null 2>&1 && pwd -P)"
+cd "$REPO_ROOT"
+
+mkdir -p logs
+mkdir -p temp/client_body_temp temp/proxy_temp temp/fastcgi_temp temp/uwsgi_temp temp/scgi_temp
+
+exec nginx -g 'daemon off;' -c "$REPO_ROOT/docker/nginx/nginx.local.conf" -p "$REPO_ROOT"