Deploy DeerFlow to Hugging Face Space

.dockerignore

@@ -0,0 +1,69 @@
+.env
+.dockerignore
+.git
+.gitignore
+docker/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.venv/
+
+# Web
+node_modules
+npm-debug.log
+.next
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Project specific
+conf.yaml
+web/
+docs/
+examples/
+assets/
+tests/
+*.log
+
+# Exclude directories not needed in Docker context
+# Frontend build only needs frontend/
+# Backend build only needs backend/
+scripts/
+logs/
+docker/
+frontend/.next
+frontend/node_modules
+backend/.venv
+backend/htmlcov
+backend/.coverage
+*.md
+!README.md
+!frontend/README.md
+!backend/README.md

.env.example

@@ -0,0 +1,13 @@
+# TAVILY API Key
+TAVILY_API_KEY=your-tavily-api-key
+
+# Jina API Key
+JINA_API_KEY=your-jina-api-key
+
+# Optional:
+# FIRECRAWL_API_KEY=your-firecrawl-api-key
+# VOLCENGINE_API_KEY=your-volcengine-api-key
+# OPENAI_API_KEY=your-openai-api-key
+# GEMINI_API_KEY=your-gemini-api-key
+# DEEPSEEK_API_KEY=your-deepseek-api-key
+# NOVITA_API_KEY=your-novita-api-key  # OpenAI-compatible, see https://novita.ai

.gitattributes

@@ -1,35 +1,61 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
+# Normalize line endings to LF for all text files
+* text=auto eol=lf
+
+# Shell scripts and makefiles must always use LF
+*.sh text eol=lf
+Makefile text eol=lf
+**/Makefile text eol=lf
+
+# Common config/source files
+*.yml text eol=lf
+*.yaml text eol=lf
+*.toml text eol=lf
+*.json text eol=lf
+*.md text eol=lf
+*.py text eol=lf
+*.ts text eol=lf
+*.tsx text eol=lf
+*.js text eol=lf
+*.jsx text eol=lf
+*.css text eol=lf
+*.scss text eol=lf
+*.html text eol=lf
+*.env text eol=lf
+
+# Windows scripts
+*.bat text eol=crlf
+*.cmd text eol=crlf
+
+# Binary assets
+*.png binary
+*.jpg binary
+*.jpeg binary
+*.gif binary
+*.webp binary
+*.ico binary
+*.pdf binary
+*.zip binary
+*.tar binary
+*.gz binary
+*.mp4 binary
+*.mov binary
+*.woff binary
+*.woff2 binary
+frontend/public/demo/threads/21cfea46-34bd-4aa6-9e1f-3009452fbeb9/user-data/outputs/doraemon-moe-comic.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/4f3e55ee-f853-43db-bfb3-7d1a411f03cb/user-data/outputs/darcy-proposal-reference.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/4f3e55ee-f853-43db-bfb3-7d1a411f03cb/user-data/outputs/darcy-proposal-video.mp4 filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/7f9dc56c-e49c-4671-a3d2-c492ff4dce0c/user-data/outputs/leica-nyc-candid.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/7f9dc56c-e49c-4671-a3d2-c492ff4dce0c/user-data/outputs/leica-paris-decisive-moment.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/7f9dc56c-e49c-4671-a3d2-c492ff4dce0c/user-data/outputs/leica-tokyo-night.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/90040b36-7eba-4b97-ba89-02c3ad47a8b9/user-data/outputs/american-woman-newyork.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/90040b36-7eba-4b97-ba89-02c3ad47a8b9/user-data/outputs/american-woman-shanghai.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/b83fbb2a-4e36-4d82-9de0-7b2a02c2092a/user-data/outputs/caren-hero.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/b83fbb2a-4e36-4d82-9de0-7b2a02c2092a/user-data/outputs/caren-ingredients.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/b83fbb2a-4e36-4d82-9de0-7b2a02c2092a/user-data/outputs/caren-lifestyle.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/demo/threads/b83fbb2a-4e36-4d82-9de0-7b2a02c2092a/user-data/outputs/caren-products.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/images/21cfea46-34bd-4aa6-9e1f-3009452fbeb9.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/images/3823e443-4e2b-4679-b496-a9506eae462b.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/images/4f3e55ee-f853-43db-bfb3-7d1a411f03cb.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/images/7cfa5f8f-a2f8-47ad-acbd-da7137baf990.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/images/ad76c455-5bf9-4335-8517-fc03834ab828.jpg filter=lfs diff=lfs merge=lfs -text
+frontend/public/images/d3e5adaf-084c-4dd5-9d29-94f1d6bccd98.jpg filter=lfs diff=lfs merge=lfs -text

.github/workflows/backend-unit-tests.yml

@@ -0,0 +1,39 @@
+name: Unit Tests
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+
+concurrency:
+  group: unit-tests-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  backend-unit-tests:
+    if: github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
+
+      - name: Install backend dependencies
+        working-directory: backend
+        run: uv sync --group dev
+
+      - name: Lint backend
+        working-directory: backend
+        run: make lint
+
+      - name: Run unit tests of backend
+        working-directory: backend
+        run: make test

.gitignore

@@ -0,0 +1,49 @@
+# DeerFlow docker image cache
+docker/.cache/
+# OS generated files
+.DS_Store
+*.local
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Python cache
+__pycache__/
+*.pyc
+*.pyo
+
+# Virtual environments
+.venv
+venv/
+
+# Environment variables
+.env
+
+# Configuration files
+config.yaml
+mcp_config.json
+extensions_config.json
+
+# IDE
+.idea/
+
+# Coverage report
+coverage.xml
+coverage/
+.deer-flow/
+.claude/
+skills/custom/*
+logs/
+log/
+
+# Local git hooks (keep only on this machine, do not push)
+.githooks/
+
+# pnpm
+.pnpm-store
+sandbox_image_cache.tar
+
+# ignore the legacy `web` folder
+web/

CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# Contributing to DeerFlow
+
+Thank you for your interest in contributing to DeerFlow! This guide will help you set up your development environment and understand our development workflow.
+
+## Development Environment Setup
+
+We offer two development environments. **Docker is recommended** for the most consistent and hassle-free experience.
+
+### Option 1: Docker Development (Recommended)
+
+Docker provides a consistent, isolated environment with all dependencies pre-configured. No need to install Node.js, Python, or nginx on your local machine.
+
+#### Prerequisites
+
+- Docker Desktop or Docker Engine
+- pnpm (for caching optimization)
+
+#### Setup Steps
+
+1. **Configure the application**:
+   ```bash
+   # Copy example configuration
+   cp config.example.yaml config.yaml
+
+   # Set your API keys
+   export OPENAI_API_KEY="your-key-here"
+   # or edit config.yaml directly
+   ```
+
+2. **Initialize Docker environment** (first time only):
+   ```bash
+   make docker-init
+   ```
+   This will:
+   - Build Docker images
+   - Install frontend dependencies (pnpm)
+   - Install backend dependencies (uv)
+   - Share pnpm cache with host for faster builds
+
+3. **Start development services**:
+   ```bash
+   make docker-start
+   ```
+   `make docker-start` reads `config.yaml` and starts `provisioner` only for provisioner/Kubernetes sandbox mode.
+
+   All services will start with hot-reload enabled:
+   - Frontend changes are automatically reloaded
+   - Backend changes trigger automatic restart
+   - LangGraph server supports hot-reload
+
+4. **Access the application**:
+   - Web Interface: http://localhost:2026
+   - API Gateway: http://localhost:2026/api/*
+   - LangGraph: http://localhost:2026/api/langgraph/*
+
+#### Docker Commands
+
+```bash
+# Build the custom k3s image (with pre-cached sandbox image)
+make docker-init
+# Start Docker services (mode-aware, localhost:2026)
+make docker-start
+# Stop Docker development services
+make docker-stop
+# View Docker development logs
+make docker-logs
+# View Docker frontend logs
+make docker-logs-frontend
+# View Docker gateway logs
+make docker-logs-gateway
+```
+
+#### Docker Architecture
+
+```
+Host Machine
+  ↓
+Docker Compose (deer-flow-dev)
+  ├→ nginx (port 2026) ← Reverse proxy
+  ├→ web (port 3000) ← Frontend with hot-reload
+  ├→ api (port 8001) ← Gateway API with hot-reload
+   ├→ langgraph (port 2024) ← LangGraph server with hot-reload
+   └→ provisioner (optional, port 8002) ← Started only in provisioner/K8s sandbox mode
+```
+
+**Benefits of Docker Development**:
+- ✅ Consistent environment across different machines
+- ✅ No need to install Node.js, Python, or nginx locally
+- ✅ Isolated dependencies and services
+- ✅ Easy cleanup and reset
+- ✅ Hot-reload for all services
+- ✅ Production-like environment
+
+### Option 2: Local Development
+
+If you prefer to run services directly on your machine:
+
+#### Prerequisites
+
+Check that you have all required tools installed:
+
+```bash
+make check
+```
+
+Required tools:
+- Node.js 22+
+- pnpm
+- uv (Python package manager)
+- nginx
+
+#### Setup Steps
+
+1. **Configure the application** (same as Docker setup above)
+
+2. **Install dependencies**:
+   ```bash
+   make install
+   ```
+
+3. **Run development server** (starts all services with nginx):
+   ```bash
+   make dev
+   ```
+
+4. **Access the application**:
+   - Web Interface: http://localhost:2026
+   - All API requests are automatically proxied through nginx
+
+#### Manual Service Control
+
+If you need to start services individually:
+
+1. **Start backend services**:
+   ```bash
+   # Terminal 1: Start LangGraph Server (port 2024)
+   cd backend
+   make dev
+
+   # Terminal 2: Start Gateway API (port 8001)
+   cd backend
+   make gateway
+
+   # Terminal 3: Start Frontend (port 3000)
+   cd frontend
+   pnpm dev
+   ```
+
+2. **Start nginx**:
+   ```bash
+   make nginx
+   # or directly: nginx -c $(pwd)/docker/nginx/nginx.local.conf -g 'daemon off;'
+   ```
+
+3. **Access the application**:
+   - Web Interface: http://localhost:2026
+
+#### Nginx Configuration
+
+The nginx configuration provides:
+- Unified entry point on port 2026
+- Routes `/api/langgraph/*` to LangGraph Server (2024)
+- Routes other `/api/*` endpoints to Gateway API (8001)
+- Routes non-API requests to Frontend (3000)
+- Centralized CORS handling
+- SSE/streaming support for real-time agent responses
+- Optimized timeouts for long-running operations
+
+## Project Structure
+
+```
+deer-flow/
+├── config.example.yaml      # Configuration template
+├── extensions_config.example.json  # MCP and Skills configuration template
+├── Makefile                 # Build and development commands
+├── scripts/
+│   └── docker.sh           # Docker management script
+├── docker/
+│   ├── docker-compose-dev.yaml  # Docker Compose configuration
+│   └── nginx/
+│       ├── nginx.conf      # Nginx config for Docker
+│       └── nginx.local.conf # Nginx config for local dev
+├── backend/                 # Backend application
+│   ├── src/
+│   │   ├── gateway/        # Gateway API (port 8001)
+│   │   ├── agents/         # LangGraph agents (port 2024)
+│   │   ├── mcp/            # Model Context Protocol integration
+│   │   ├── skills/         # Skills system
+│   │   └── sandbox/        # Sandbox execution
+│   ├── docs/               # Backend documentation
+│   └── Makefile            # Backend commands
+├── frontend/               # Frontend application
+│   └── Makefile            # Frontend commands
+└── skills/                 # Agent skills
+    ├── public/             # Public skills
+    └── custom/             # Custom skills
+```
+
+## Architecture
+
+```
+Browser
+  ↓
+Nginx (port 2026) ← Unified entry point
+  ├→ Frontend (port 3000) ← / (non-API requests)
+  ├→ Gateway API (port 8001) ← /api/models, /api/mcp, /api/skills, /api/threads/*/artifacts
+  └→ LangGraph Server (port 2024) ← /api/langgraph/* (agent interactions)
+```
+
+## Development Workflow
+
+1. **Create a feature branch**:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+2. **Make your changes** with hot-reload enabled
+
+3. **Test your changes** thoroughly
+
+4. **Commit your changes**:
+   ```bash
+   git add .
+   git commit -m "feat: description of your changes"
+   ```
+
+5. **Push and create a Pull Request**:
+   ```bash
+   git push origin feature/your-feature-name
+   ```
+
+## Testing
+
+```bash
+# Backend tests
+cd backend
+uv run pytest
+
+# Frontend tests
+cd frontend
+pnpm test
+```
+
+### PR Regression Checks
+
+Every pull request runs the backend regression workflow at [.github/workflows/backend-unit-tests.yml](.github/workflows/backend-unit-tests.yml), including:
+
+- `tests/test_provisioner_kubeconfig.py`
+- `tests/test_docker_sandbox_mode_detection.py`
+
+## Code Style
+
+- **Backend (Python)**: We use `ruff` for linting and formatting
+- **Frontend (TypeScript)**: We use ESLint and Prettier
+
+## Documentation
+
+- [Configuration Guide](backend/docs/CONFIGURATION.md) - Setup and configuration
+- [Architecture Overview](backend/CLAUDE.md) - Technical architecture
+- [MCP Setup Guide](MCP_SETUP.md) - Model Context Protocol configuration
+
+## Need Help?
+
+- Check existing [Issues](https://github.com/bytedance/deer-flow/issues)
+- Read the [Documentation](backend/docs/)
+- Ask questions in [Discussions](https://github.com/bytedance/deer-flow/discussions)
+
+## License
+
+By contributing to DeerFlow, you agree that your contributions will be licensed under the [MIT License](./LICENSE).

Dockerfile

@@ -0,0 +1,34 @@
+FROM python:3.12-slim
+
+ENV DEBIAN_FRONTEND=noninteractive \
+    PATH="/root/.local/bin:${PATH}" \
+    NODE_ENV=production \
+    SKIP_ENV_VALIDATION=1 \
+    NEXT_TELEMETRY_DISABLED=1 \
+    PORT=7860
+
+RUN apt-get update && \
+    apt-get install -y --no-install-recommends curl ca-certificates gnupg nginx build-essential git && \
+    mkdir -p /etc/apt/keyrings && \
+    curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg && \
+    echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_22.x nodistro main" > /etc/apt/sources.list.d/nodesource.list && \
+    apt-get update && \
+    apt-get install -y --no-install-recommends nodejs && \
+    npm install -g corepack && \
+    corepack enable && \
+    corepack prepare pnpm@10.26.2 --activate && \
+    curl -LsSf https://astral.sh/uv/install.sh | sh && \
+    apt-get clean && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+COPY . /app
+
+RUN cd /app/backend && uv sync --frozen && \
+    cd /app/frontend && pnpm install --frozen-lockfile && pnpm build && \
+    chmod +x /app/start-hf.sh && \
+    mkdir -p /app/logs /app/backend/.deer-flow/threads /app/backend/.deer-flow/artifacts
+
+EXPOSE 7860
+
+CMD ["/app/start-hf.sh"]

LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2025 Bytedance Ltd. and/or its affiliates
+Copyright (c) 2025-2026 DeerFlow Authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

Makefile

@@ -0,0 +1,267 @@
+# DeerFlow - Unified Development Environment
+
+.PHONY: help config check install dev stop clean docker-init docker-start docker-stop docker-logs docker-logs-frontend docker-logs-gateway
+
+help:
+	@echo "DeerFlow Development Commands:"
+	@echo "  make check           - Check if all required tools are installed"
+	@echo "  make install         - Install all dependencies (frontend + backend)"
+	@echo "  make setup-sandbox   - Pre-pull sandbox container image (recommended)"
+	@echo "  make dev             - Start all services (frontend + backend + nginx on localhost:2026)"
+	@echo "  make stop            - Stop all running services"
+	@echo "  make clean           - Clean up processes and temporary files"
+	@echo ""
+	@echo "Docker Development Commands:"
+	@echo "  make docker-init     - Build the custom k3s image (with pre-cached sandbox image)"
+	@echo "  make docker-start    - Start Docker services (mode-aware from config.yaml, localhost:2026)"
+	@echo "  make docker-stop     - Stop Docker development services"
+	@echo "  make docker-logs     - View Docker development logs"
+	@echo "  make docker-logs-frontend - View Docker frontend logs"
+	@echo "  make docker-logs-gateway - View Docker gateway logs"
+
+config:
+	@test -f config.yaml || cp config.example.yaml config.yaml
+	@test -f .env || cp .env.example .env
+	@test -f frontend/.env || cp frontend/.env.example frontend/.env
+
+# Check required tools
+check:
+	@echo "=========================================="
+	@echo "  Checking Required Dependencies"
+	@echo "=========================================="
+	@echo ""
+	@FAILED=0; \
+	echo "Checking Node.js..."; \
+	if command -v node >/dev/null 2>&1; then \
+		NODE_VERSION=$$(node -v | sed 's/v//'); \
+		NODE_MAJOR=$$(echo $$NODE_VERSION | cut -d. -f1); \
+		if [ $$NODE_MAJOR -ge 22 ]; then \
+			echo "  ✓ Node.js $$NODE_VERSION (>= 22 required)"; \
+		else \
+			echo "  ✗ Node.js $$NODE_VERSION found, but version 22+ is required"; \
+			echo "    Install from: https://nodejs.org/"; \
+			FAILED=1; \
+		fi; \
+	else \
+		echo "  ✗ Node.js not found (version 22+ required)"; \
+		echo "    Install from: https://nodejs.org/"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	echo "Checking pnpm..."; \
+	if command -v pnpm >/dev/null 2>&1; then \
+		PNPM_VERSION=$$(pnpm -v); \
+		echo "  ✓ pnpm $$PNPM_VERSION"; \
+	else \
+		echo "  ✗ pnpm not found"; \
+		echo "    Install: npm install -g pnpm"; \
+		echo "    Or visit: https://pnpm.io/installation"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	echo "Checking uv..."; \
+	if command -v uv >/dev/null 2>&1; then \
+		UV_VERSION=$$(uv --version | awk '{print $$2}'); \
+		echo "  ✓ uv $$UV_VERSION"; \
+	else \
+		echo "  ✗ uv not found"; \
+		echo "    Install: curl -LsSf https://astral.sh/uv/install.sh | sh"; \
+		echo "    Or visit: https://docs.astral.sh/uv/getting-started/installation/"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	echo "Checking nginx..."; \
+	if command -v nginx >/dev/null 2>&1; then \
+		NGINX_VERSION=$$(nginx -v 2>&1 | awk -F'/' '{print $$2}'); \
+		echo "  ✓ nginx $$NGINX_VERSION"; \
+	else \
+		echo "  ✗ nginx not found"; \
+		echo "    macOS:   brew install nginx"; \
+		echo "    Ubuntu:  sudo apt install nginx"; \
+		echo "    Or visit: https://nginx.org/en/download.html"; \
+		FAILED=1; \
+	fi; \
+	echo ""; \
+	if [ $$FAILED -eq 0 ]; then \
+		echo "=========================================="; \
+		echo "  ✓ All dependencies are installed!"; \
+		echo "=========================================="; \
+		echo ""; \
+		echo "You can now run:"; \
+		echo "  make install  - Install project dependencies"; \
+		echo "  make dev      - Start development server"; \
+	else \
+		echo "=========================================="; \
+		echo "  ✗ Some dependencies are missing"; \
+		echo "=========================================="; \
+		echo ""; \
+		echo "Please install the missing tools and run 'make check' again."; \
+		exit 1; \
+	fi
+
+# Install all dependencies
+install:
+	@echo "Installing backend dependencies..."
+	@cd backend && uv sync
+	@echo "Installing frontend dependencies..."
+	@cd frontend && pnpm install
+	@echo "✓ All dependencies installed"
+	@echo ""
+	@echo "=========================================="
+	@echo "  Optional: Pre-pull Sandbox Image"
+	@echo "=========================================="
+	@echo ""
+	@echo "If you plan to use Docker/Container-based sandbox, you can pre-pull the image:"
+	@echo "  make setup-sandbox"
+	@echo ""
+
+# Pre-pull sandbox Docker image (optional but recommended)
+setup-sandbox:
+	@echo "=========================================="
+	@echo "  Pre-pulling Sandbox Container Image"
+	@echo "=========================================="
+	@echo ""
+	@IMAGE=$$(grep -A 20 "# sandbox:" config.yaml 2>/dev/null | grep "image:" | awk '{print $$2}' | head -1); \
+	if [ -z "$$IMAGE" ]; then \
+		IMAGE="enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest"; \
+		echo "Using default image: $$IMAGE"; \
+	else \
+		echo "Using configured image: $$IMAGE"; \
+	fi; \
+	echo ""; \
+	if command -v container >/dev/null 2>&1 && [ "$$(uname)" = "Darwin" ]; then \
+		echo "Detected Apple Container on macOS, pulling image..."; \
+		container pull "$$IMAGE" || echo "⚠ Apple Container pull failed, will try Docker"; \
+	fi; \
+	if command -v docker >/dev/null 2>&1; then \
+		echo "Pulling image using Docker..."; \
+		docker pull "$$IMAGE"; \
+		echo ""; \
+		echo "✓ Sandbox image pulled successfully"; \
+	else \
+		echo "✗ Neither Docker nor Apple Container is available"; \
+		echo "  Please install Docker: https://docs.docker.com/get-docker/"; \
+		exit 1; \
+	fi
+
+# Start all services
+dev:
+	@echo "Stopping existing services if any..."
+	@-pkill -f "langgraph dev" 2>/dev/null || true
+	@-pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true
+	@-pkill -f "next dev" 2>/dev/null || true
+	@-nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true
+	@sleep 1
+	@-pkill -9 nginx 2>/dev/null || true
+	@-./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true
+	@sleep 1
+	@echo ""
+	@echo "=========================================="
+	@echo "  Starting DeerFlow Development Server"
+	@echo "=========================================="
+	@echo ""
+	@echo "Services starting up..."
+	@echo "  → Backend: LangGraph + Gateway"
+	@echo "  → Frontend: Next.js"
+	@echo "  → Nginx: Reverse Proxy"
+	@echo ""
+	@cleanup() { \
+		echo ""; \
+		echo "Shutting down services..."; \
+		pkill -f "langgraph dev" 2>/dev/null || true; \
+		pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true; \
+		pkill -f "next dev" 2>/dev/null || true; \
+		nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true; \
+		sleep 1; \
+		pkill -9 nginx 2>/dev/null || true; \
+		echo "Cleaning up sandbox containers..."; \
+		./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true; \
+		echo "✓ All services stopped"; \
+		exit 0; \
+	}; \
+	trap cleanup INT TERM; \
+	mkdir -p logs; \
+	echo "Starting LangGraph server..."; \
+	cd backend && NO_COLOR=1 uv run langgraph dev --no-browser --allow-blocking --no-reload > ../logs/langgraph.log 2>&1 & \
+	sleep 3; \
+	echo "✓ LangGraph server started on localhost:2024"; \
+	echo "Starting Gateway API..."; \
+	cd backend && uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001 > ../logs/gateway.log 2>&1 & \
+	sleep 3; \
+	if ! lsof -i :8001 -sTCP:LISTEN -t >/dev/null 2>&1; then \
+		echo "✗ Gateway API failed to start. Last log output:"; \
+		tail -30 logs/gateway.log; \
+		cleanup; \
+	fi; \
+	echo "✓ Gateway API started on localhost:8001"; \
+	echo "Starting Frontend..."; \
+	cd frontend && pnpm run dev > ../logs/frontend.log 2>&1 & \
+	sleep 3; \
+	echo "✓ Frontend started on localhost:3000"; \
+	echo "Starting Nginx reverse proxy..."; \
+	mkdir -p logs && nginx -g 'daemon off;' -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) > logs/nginx.log 2>&1 & \
+	sleep 2; \
+	echo "✓ Nginx started on localhost:2026"; \
+	echo ""; \
+	echo "=========================================="; \
+	echo "  DeerFlow is ready!"; \
+	echo "=========================================="; \
+	echo ""; \
+	echo "  🌐 Application: http://localhost:2026"; \
+	echo "  📡 API Gateway: http://localhost:2026/api/*"; \
+	echo "  🤖 LangGraph:   http://localhost:2026/api/langgraph/*"; \
+	echo ""; \
+	echo "  📋 Logs:"; \
+	echo "     - LangGraph: logs/langgraph.log"; \
+	echo "     - Gateway:   logs/gateway.log"; \
+	echo "     - Frontend:  logs/frontend.log"; \
+	echo "     - Nginx:     logs/nginx.log"; \
+	echo ""; \
+	echo "Press Ctrl+C to stop all services"; \
+	echo ""; \
+	wait
+
+# Stop all services
+stop:
+	@echo "Stopping all services..."
+	@-pkill -f "langgraph dev" 2>/dev/null || true
+	@-pkill -f "uvicorn src.gateway.app:app" 2>/dev/null || true
+	@-pkill -f "next dev" 2>/dev/null || true
+	@-nginx -c $(PWD)/docker/nginx/nginx.local.conf -p $(PWD) -s quit 2>/dev/null || true
+	@sleep 1
+	@-pkill -9 nginx 2>/dev/null || true
+	@echo "Cleaning up sandbox containers..."
+	@-./scripts/cleanup-containers.sh deer-flow-sandbox 2>/dev/null || true
+	@echo "✓ All services stopped"
+
+# Clean up
+clean: stop
+	@echo "Cleaning up..."
+	@-rm -rf logs/*.log 2>/dev/null || true
+	@echo "✓ Cleanup complete"
+
+# ==========================================
+# Docker Development Commands
+# ==========================================
+
+# Initialize Docker containers and install dependencies
+docker-init:
+	@./scripts/docker.sh init
+
+# Start Docker development environment
+docker-start:
+	@./scripts/docker.sh start
+
+# Stop Docker development environment
+docker-stop:
+	@./scripts/docker.sh stop
+
+# View Docker development logs
+docker-logs:
+	@./scripts/docker.sh logs
+
+# View Docker development logs
+docker-logs-frontend:
+	@./scripts/docker.sh logs --frontend
+docker-logs-gateway:
+	@./scripts/docker.sh logs --gateway

README.md

@@ -1,10 +1,318 @@
+# 🦌 DeerFlow - 2.0
+
+<a href="https://trendshift.io/repositories/14699" target="_blank"><img src="https://trendshift.io/api/badge/repositories/14699" alt="bytedance%2Fdeer-flow | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
+> On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥
+
+DeerFlow (**D**eep **E**xploration and **E**fficient **R**esearch **Flow**) is an open-source **super agent harness** that orchestrates **sub-agents**, **memory**, and **sandboxes** to do almost anything — powered by **extensible skills**.
+
+https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18
+
+> [!NOTE]
+> **DeerFlow 2.0 is a ground-up rewrite.** It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the [`1.x` branch](https://github.com/bytedance/deer-flow/tree/main-1.x) — contributions there are still welcome. Active development has moved to 2.0.
+
+## Official Website
+
+Learn more and see **real demos** on our official website.
+
+**[deerflow.tech](https://deerflow.tech/)**
+
 ---
-title: Deer Flow Gpt51
-emoji: 📚
-colorFrom: green
-colorTo: purple
-sdk: docker
-pinned: false
----
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+## Table of Contents
+
+- [🦌 DeerFlow - 2.0](#-deerflow---20)
+  - [Offiical Website](#offiical-website)
+  - [Table of Contents](#table-of-contents)
+  - [Quick Start](#quick-start)
+    - [Configuration](#configuration)
+    - [Running the Application](#running-the-application)
+      - [Option 1: Docker (Recommended)](#option-1-docker-recommended)
+      - [Option 2: Local Development](#option-2-local-development)
+    - [Advanced](#advanced)
+      - [Sandbox Mode](#sandbox-mode)
+      - [MCP Server](#mcp-server)
+  - [From Deep Research to Super Agent Harness](#from-deep-research-to-super-agent-harness)
+  - [Core Features](#core-features)
+    - [Skills \& Tools](#skills--tools)
+    - [Sub-Agents](#sub-agents)
+    - [Sandbox \& File System](#sandbox--file-system)
+    - [Context Engineering](#context-engineering)
+    - [Long-Term Memory](#long-term-memory)
+  - [Recommended Models](#recommended-models)
+  - [Documentation](#documentation)
+  - [Contributing](#contributing)
+  - [License](#license)
+  - [Acknowledgments](#acknowledgments)
+    - [Key Contributors](#key-contributors)
+  - [Star History](#star-history)
+
+## Quick Start
+
+### Configuration
+
+1. **Clone the DeerFlow repository**
+
+   ```bash
+   git clone https://github.com/bytedance/deer-flow.git
+   cd deer-flow
+   ```
+
+2. **Generate local configuration files**
+
+   From the project root directory (`deer-flow/`), run:
+
+   ```bash
+   make config
+   ```
+
+   This command creates local configuration files based on the provided example templates.
+
+3. **Configure your preferred model(s)**
+
+   Edit `config.yaml` and define at least one model:
+
+   ```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
+   ```
+
+  
+4. **Set API keys for your configured model(s)**
+
+   Choose one of the following methods:
+
+- Option A: Edit the `.env` file in the project root (Recommended)
+
+
+   ```bash
+   TAVILY_API_KEY=your-tavily-api-key
+   OPENAI_API_KEY=your-openai-api-key
+   # Add other provider keys as needed
+   ```
+
+- Option B: Export environment variables in your shell
+
+   ```bash
+   export OPENAI_API_KEY=your-openai-api-key
+   ```
+
+- Option C: Edit `config.yaml` directly (Not recommended for production)
+
+   ```yaml
+   models:
+     - name: gpt-4
+       api_key: your-actual-api-key-here  # Replace placeholder
+   ```
+
+### Running the Application
+
+#### Option 1: Docker (Recommended)
+
+The fastest way to get started with a consistent environment:
+
+1. **Initialize and start**:
+   ```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` now starts `provisioner` only when `config.yaml` uses provisioner mode (`sandbox.use: src.community.aio_sandbox:AioSandboxProvider` with `provisioner_url`).
+
+2. **Access**: http://localhost:2026
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed Docker development guide.
+
+#### Option 2: Local Development
+
+If you prefer running services locally:
+
+1. **Check prerequisites**:
+   ```bash
+   make check  # Verifies Node.js 22+, pnpm, uv, nginx
+   ```
+
+2. **(Optional) Pre-pull sandbox image**:
+   ```bash
+   # Recommended if using Docker/Container-based sandbox
+   make setup-sandbox
+   ```
+
+3. **Start services**:
+   ```bash
+   make dev
+   ```
+
+4. **Access**: http://localhost:2026
+
+### Advanced
+#### Sandbox Mode
+
+DeerFlow supports multiple sandbox execution modes:
+- **Local Execution** (runs sandbox code directly on the host machine)
+- **Docker Execution** (runs sandbox code in isolated Docker containers)
+- **Docker Execution with Kubernetes** (runs sandbox code in Kubernetes pods via provisioner service)
+
+For Docker development, service startup follows `config.yaml` sandbox mode. In Local/Docker modes, `provisioner` is not started.
+
+See the [Sandbox Configuration Guide](backend/docs/CONFIGURATION.md#sandbox) to configure your preferred mode.
+
+#### MCP Server
+
+DeerFlow supports configurable MCP servers and skills to extend its capabilities.
+For HTTP/SSE MCP servers, OAuth token flows are supported (`client_credentials`, `refresh_token`).
+See the [MCP Server Guide](backend/docs/MCP_SERVER.md) for detailed instructions.
+
+## From Deep Research to Super Agent Harness
+
+DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.
+
+That told us something important: DeerFlow wasn't just a research tool. It was a **harness** — a runtime that gives agents the infrastructure to actually get work done.
+
+So we rebuilt it from scratch.
+
+DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandboxed execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.
+
+Use it as-is. Or tear it apart and make it yours.
+
+## Core Features
+
+### Skills & Tools
+
+Skills are what make DeerFlow do *almost anything*.
+
+A standard Agent Skill is a structured capability module — a Markdown file that defines a workflow, best practices, and references to supporting resources. DeerFlow ships with built-in skills for research, report generation, slide creation, web pages, image and video generation, and more. But the real power is extensibility: add your own skills, replace the built-in ones, or combine them into compound workflows.
+
+Skills are loaded progressively — only when the task needs them, not all at once. This keeps the context window lean and makes DeerFlow work well even with token-sensitive models.
+
+Tools follow the same philosophy. DeerFlow comes with a core toolset — web search, web fetch, file operations, bash execution — and supports custom tools via MCP servers and Python functions. Swap anything. Add anything.
+
+```
+# 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
+```
+
+### Sub-Agents
+
+Complex tasks rarely fit in a single pass. DeerFlow decomposes them.
+
+The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output.
+
+This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report — or a website — or a slide deck with generated visuals. One harness, many hands.
+
+### Sandbox & File System
+
+DeerFlow doesn't just *talk* about doing things. It has its own computer.
+
+Each task runs inside an isolated Docker container with a full filesystem — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It executes bash commands and codes. It views images. All sandboxed, all auditable, zero contamination between sessions.
+
+This is the difference between a chatbot with tool access and an agent with an actual execution environment.
+
+```
+# Paths inside the sandbox container
+/mnt/user-data/
+├── uploads/          ← your files
+├── workspace/        ← agents' working directory
+└── outputs/          ← final deliverables
+```
+
+### Context Engineering
+
+**Isolated Sub-Agent Context**: Each sub-agent runs in its own isolated context. This means that the sub-agent will not be able to see the context of the main agent or other sub-agents. This is important to ensure that the sub-agent is able to focus on the task at hand and not be distracted by the context of the main agent or other sub-agents.
+
+**Summarization**: Within a session, DeerFlow manages context aggressively — summarizing completed sub-tasks, offloading intermediate results to the filesystem, compressing what's no longer immediately relevant. This lets it stay sharp across long, multi-step tasks without blowing the context window.
+
+### Long-Term Memory
+
+Most agents forget everything the moment a conversation ends. DeerFlow remembers.
+
+Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you — your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control.
+
+## Recommended Models
+
+DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:
+
+- **Long context windows** (100k+ tokens) for deep research and multi-step tasks
+- **Reasoning capabilities** for adaptive planning and complex decomposition
+- **Multimodal inputs** for image understanding and video comprehension
+- **Strong tool-use** for reliable function calling and structured outputs
+
+## Embedded Python Client
+
+DeerFlow can be used as an embedded Python library without running the full HTTP services. The `DeerFlowClient` provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API:
+
+```python
+from src.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": [...]}
+```
+
+All dict-returning methods are validated against Gateway Pydantic response models in CI (`TestGatewayConformance`), ensuring the embedded client stays in sync with the HTTP API schemas. See `backend/src/client.py` for full API documentation.
+
+## Documentation
+
+- [Contributing Guide](CONTRIBUTING.md) - Development environment setup and workflow
+- [Configuration Guide](backend/docs/CONFIGURATION.md) - Setup and configuration instructions
+- [Architecture Overview](backend/CLAUDE.md) - Technical architecture details
+- [Backend Architecture](backend/README.md) - Backend architecture and API reference
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, workflow, and guidelines.
+
+Regression coverage includes Docker sandbox mode detection and provisioner kubeconfig-path handling tests in `backend/tests/`.
+
+## License
+
+This project is open source and available under the [MIT License](./LICENSE).
+
+## Acknowledgments
+
+DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants.
+
+We would like to extend our sincere appreciation to the following projects for their invaluable contributions:
+
+- **[LangChain](https://github.com/langchain-ai/langchain)**: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
+- **[LangGraph](https://github.com/langchain-ai/langgraph)**: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.
+
+These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.
+
+### Key Contributors
+
+A heartfelt thank you goes out to the core authors of `DeerFlow`, whose vision, passion, and dedication have brought this project to life:
+
+- **[Daniel Walnut](https://github.com/hetaoBackend/)**
+- **[Henry Li](https://github.com/magiccube/)**
+
+Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey.
+
+## Star History
+
+[![Star History Chart](https://api.star-history.com/svg?repos=bytedance/deer-flow&type=Date)](https://star-history.com/#bytedance/deer-flow&Date)

SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+As deer-flow doesn't provide an offical release yet, please use the latest version for the security updates.
+Current we have two branches to maintain: 
+* main branch for deer-flow 2.x
+* main-1.x branch for deer-flow 1.x 
+
+## Reporting a Vulnerability
+
+Please go to https://github.com/bytedance/deer-flow/security to report the vulnerability you find.

backend/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.coverage
+.coverage.*
+.ruff_cache
+agent_history.gif
+static/browser_history/*.gif
+
+log/
+log/*
+
+# Virtual environments
+.venv
+venv/
+
+# User config file
+config.yaml
+
+# Langgraph
+.langgraph_api
+
+# Claude Code settings
+.claude/settings.local.json

backend/.python-version

@@ -0,0 +1 @@
+3.12

backend/.vscode/extensions.json

@@ -0,0 +1,3 @@
+{
+  "recommendations": ["charliermarsh.ruff"]
+}

backend/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+  "window.title": "${activeEditorShort}${separator}${separator}deer-flow/backend",
+  "[python]": {
+    "editor.formatOnSave": true,
+    "editor.codeActionsOnSave": {
+      "source.fixAll": "explicit",
+      "source.organizeImports": "explicit"
+    },
+    "editor.defaultFormatter": "charliermarsh.ruff"
+  }
+}

backend/AGENTS.md

@@ -0,0 +1,2 @@
+For the backend architeture and design patterns:
+@./CLAUDE.md

backend/CLAUDE.md

@@ -0,0 +1,441 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+DeerFlow is a LangGraph-based AI super agent system with a full-stack architecture. The backend provides a "super agent" with sandbox execution, persistent memory, subagent delegation, and extensible tool integration - all operating in per-thread isolated environments.
+
+**Architecture**:
+- **LangGraph Server** (port 2024): Agent runtime and workflow execution
+- **Gateway API** (port 8001): REST API for models, MCP, skills, memory, artifacts, and uploads
+- **Frontend** (port 3000): Next.js web interface
+- **Nginx** (port 2026): Unified reverse proxy entry point
+- **Provisioner** (port 8002, optional in Docker dev): Started only when sandbox is configured for provisioner/Kubernetes mode
+
+**Project Structure**:
+```
+deer-flow/
+├── Makefile                    # Root commands (check, install, dev, stop)
+├── config.yaml                 # Main application configuration
+├── extensions_config.json      # MCP servers and skills configuration
+├── backend/                    # Backend application (this directory)
+│   ├── Makefile               # Backend-only commands (dev, gateway, lint)
+│   ├── langgraph.json         # LangGraph server configuration
+│   ├── src/
+│   │   ├── agents/            # LangGraph agent system
+│   │   │   ├── lead_agent/    # Main agent (factory + system prompt)
+│   │   │   ├── middlewares/   # 10 middleware components
+│   │   │   ├── memory/        # Memory extraction, queue, prompts
+│   │   │   └── thread_state.py # ThreadState schema
+│   │   ├── gateway/           # FastAPI Gateway API
+│   │   │   ├── app.py         # FastAPI application
+│   │   │   └── routers/       # 6 route modules
+│   │   ├── sandbox/           # Sandbox execution system
+│   │   │   ├── local/         # Local filesystem provider
+│   │   │   ├── sandbox.py     # Abstract Sandbox interface
+│   │   │   ├── tools.py       # bash, ls, read/write/str_replace
+│   │   │   └── middleware.py  # Sandbox lifecycle management
+│   │   ├── subagents/         # Subagent delegation system
+│   │   │   ├── builtins/      # general-purpose, bash agents
+│   │   │   ├── executor.py    # Background execution engine
+│   │   │   └── registry.py    # Agent registry
+│   │   ├── tools/builtins/    # Built-in tools (present_files, ask_clarification, view_image)
+│   │   ├── mcp/               # MCP integration (tools, cache, client)
+│   │   ├── models/            # Model factory with thinking/vision support
+│   │   ├── skills/            # Skills discovery, loading, parsing
+│   │   ├── config/            # Configuration system (app, model, sandbox, tool, etc.)
+│   │   ├── community/         # Community tools (tavily, jina_ai, firecrawl, image_search, aio_sandbox)
+│   │   ├── reflection/        # Dynamic module loading (resolve_variable, resolve_class)
+│   │   ├── utils/             # Utilities (network, readability)
+│   │   └── client.py          # Embedded Python client (DeerFlowClient)
+│   ├── tests/                 # Test suite
+│   └── docs/                  # Documentation
+├── frontend/                   # Next.js frontend application
+└── skills/                     # Agent skills directory
+    ├── public/                # Public skills (committed)
+    └── custom/                # Custom skills (gitignored)
+```
+
+## Important Development Guidelines
+
+### Documentation Update Policy
+**CRITICAL: Always update README.md and CLAUDE.md after every code change**
+
+When making code changes, you MUST update the relevant documentation:
+- Update `README.md` for user-facing changes (features, setup, usage instructions)
+- Update `CLAUDE.md` for development changes (architecture, commands, workflows, internal systems)
+- Keep documentation synchronized with the codebase at all times
+- Ensure accuracy and timeliness of all documentation
+
+## Commands
+
+**Root directory** (for full application):
+```bash
+make check      # Check system requirements
+make install    # Install all dependencies (frontend + backend)
+make dev        # Start all services (LangGraph + Gateway + Frontend + Nginx)
+make stop       # Stop all services
+```
+
+**Backend directory** (for backend development only):
+```bash
+make install    # Install backend dependencies
+make dev        # Run LangGraph server only (port 2024)
+make gateway    # Run Gateway API only (port 8001)
+make test       # Run all backend tests
+make lint       # Lint with ruff
+make format     # Format code with ruff
+```
+
+Regression tests related to Docker/provisioner behavior:
+- `tests/test_docker_sandbox_mode_detection.py` (mode detection from `config.yaml`)
+- `tests/test_provisioner_kubeconfig.py` (kubeconfig file/directory handling)
+
+CI runs these regression tests for every pull request via [.github/workflows/backend-unit-tests.yml](../.github/workflows/backend-unit-tests.yml).
+
+## Architecture
+
+### Agent System
+
+**Lead Agent** (`src/agents/lead_agent/agent.py`):
+- Entry point: `make_lead_agent(config: RunnableConfig)` registered in `langgraph.json`
+- Dynamic model selection via `create_chat_model()` with thinking/vision support
+- Tools loaded via `get_available_tools()` - combines sandbox, built-in, MCP, community, and subagent tools
+- System prompt generated by `apply_prompt_template()` with skills, memory, and subagent instructions
+
+**ThreadState** (`src/agents/thread_state.py`):
+- Extends `AgentState` with: `sandbox`, `thread_data`, `title`, `artifacts`, `todos`, `uploaded_files`, `viewed_images`
+- Uses custom reducers: `merge_artifacts` (deduplicate), `merge_viewed_images` (merge/clear)
+
+**Runtime Configuration** (via `config.configurable`):
+- `thinking_enabled` - Enable model's extended thinking
+- `model_name` - Select specific LLM model
+- `is_plan_mode` - Enable TodoList middleware
+- `subagent_enabled` - Enable task delegation tool
+
+### Middleware Chain
+
+Middlewares execute in strict order in `src/agents/lead_agent/agent.py`:
+
+1. **ThreadDataMiddleware** - Creates per-thread directories (`backend/.deer-flow/threads/{thread_id}/user-data/{workspace,uploads,outputs}`)
+2. **UploadsMiddleware** - Tracks and injects newly uploaded files into conversation
+3. **SandboxMiddleware** - Acquires sandbox, stores `sandbox_id` in state
+4. **DanglingToolCallMiddleware** - Injects placeholder ToolMessages for AIMessage tool_calls that lack responses (e.g., due to user interruption)
+5. **SummarizationMiddleware** - Context reduction when approaching token limits (optional, if enabled)
+6. **TodoListMiddleware** - Task tracking with `write_todos` tool (optional, if plan_mode)
+7. **TitleMiddleware** - Auto-generates thread title after first complete exchange
+8. **MemoryMiddleware** - Queues conversations for async memory update (filters to user + final AI responses)
+9. **ViewImageMiddleware** - Injects base64 image data before LLM call (conditional on vision support)
+10. **SubagentLimitMiddleware** - Truncates excess `task` tool calls from model response to enforce `MAX_CONCURRENT_SUBAGENTS` limit (optional, if subagent_enabled)
+11. **ClarificationMiddleware** - Intercepts `ask_clarification` tool calls, interrupts via `Command(goto=END)` (must be last)
+
+### Configuration System
+
+**Main Configuration** (`config.yaml`):
+
+Setup: Copy `config.example.yaml` to `config.yaml` in the **project root** directory.
+
+Configuration priority:
+1. Explicit `config_path` argument
+2. `DEER_FLOW_CONFIG_PATH` environment variable
+3. `config.yaml` in current directory (backend/)
+4. `config.yaml` in parent directory (project root - **recommended location**)
+
+Config values starting with `$` are resolved as environment variables (e.g., `$OPENAI_API_KEY`).
+
+**Extensions Configuration** (`extensions_config.json`):
+
+MCP servers and skills are configured together in `extensions_config.json` in project root:
+
+Configuration priority:
+1. Explicit `config_path` argument
+2. `DEER_FLOW_EXTENSIONS_CONFIG_PATH` environment variable
+3. `extensions_config.json` in current directory (backend/)
+4. `extensions_config.json` in parent directory (project root - **recommended location**)
+
+### Gateway API (`src/gateway/`)
+
+FastAPI application on port 8001 with health check at `GET /health`.
+
+**Routers**:
+
+| Router | Endpoints |
+|--------|-----------|
+| **Models** (`/api/models`) | `GET /` - list models; `GET /{name}` - model details |
+| **MCP** (`/api/mcp`) | `GET /config` - get config; `PUT /config` - update config (saves to extensions_config.json) |
+| **Skills** (`/api/skills`) | `GET /` - list skills; `GET /{name}` - details; `PUT /{name}` - update enabled; `POST /install` - install from .skill archive |
+| **Memory** (`/api/memory`) | `GET /` - memory data; `POST /reload` - force reload; `GET /config` - config; `GET /status` - config + data |
+| **Uploads** (`/api/threads/{id}/uploads`) | `POST /` - upload files (auto-converts PDF/PPT/Excel/Word); `GET /list` - list; `DELETE /{filename}` - delete |
+| **Artifacts** (`/api/threads/{id}/artifacts`) | `GET /{path}` - serve artifacts; `?download=true` for file download |
+
+Proxied through nginx: `/api/langgraph/*` → LangGraph, all other `/api/*` → Gateway.
+
+### Sandbox System (`src/sandbox/`)
+
+**Interface**: Abstract `Sandbox` with `execute_command`, `read_file`, `write_file`, `list_dir`
+**Provider Pattern**: `SandboxProvider` with `acquire`, `get`, `release` lifecycle
+**Implementations**:
+- `LocalSandboxProvider` - Singleton local filesystem execution with path mappings
+- `AioSandboxProvider` (`src/community/`) - Docker-based isolation
+
+**Virtual Path System**:
+- Agent sees: `/mnt/user-data/{workspace,uploads,outputs}`, `/mnt/skills`
+- Physical: `backend/.deer-flow/threads/{thread_id}/user-data/...`, `deer-flow/skills/`
+- Translation: `replace_virtual_path()` / `replace_virtual_paths_in_command()`
+- Detection: `is_local_sandbox()` checks `sandbox_id == "local"`
+
+**Sandbox Tools** (in `src/sandbox/tools.py`):
+- `bash` - Execute commands with path translation and error handling
+- `ls` - Directory listing (tree format, max 2 levels)
+- `read_file` - Read file contents with optional line range
+- `write_file` - Write/append to files, creates directories
+- `str_replace` - Substring replacement (single or all occurrences)
+
+### Subagent System (`src/subagents/`)
+
+**Built-in Agents**: `general-purpose` (all tools except `task`) and `bash` (command specialist)
+**Execution**: Dual thread pool - `_scheduler_pool` (3 workers) + `_execution_pool` (3 workers)
+**Concurrency**: `MAX_CONCURRENT_SUBAGENTS = 3` enforced by `SubagentLimitMiddleware` (truncates excess tool calls in `after_model`), 15-minute timeout
+**Flow**: `task()` tool → `SubagentExecutor` → background thread → poll 5s → SSE events → result
+**Events**: `task_started`, `task_running`, `task_completed`/`task_failed`/`task_timed_out`
+
+### Tool System (`src/tools/`)
+
+`get_available_tools(groups, include_mcp, model_name, subagent_enabled)` assembles:
+1. **Config-defined tools** - Resolved from `config.yaml` via `resolve_variable()`
+2. **MCP tools** - From enabled MCP servers (lazy initialized, cached with mtime invalidation)
+3. **Built-in tools**:
+   - `present_files` - Make output files visible to user (only `/mnt/user-data/outputs`)
+   - `ask_clarification` - Request clarification (intercepted by ClarificationMiddleware → interrupts)
+   - `view_image` - Read image as base64 (added only if model supports vision)
+4. **Subagent tool** (if enabled):
+   - `task` - Delegate to subagent (description, prompt, subagent_type, max_turns)
+
+**Community tools** (`src/community/`):
+- `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 via DuckDuckGo
+
+### MCP System (`src/mcp/`)
+
+- Uses `langchain-mcp-adapters` `MultiServerMCPClient` for multi-server management
+- **Lazy initialization**: Tools loaded on first use via `get_cached_mcp_tools()`
+- **Cache invalidation**: Detects config file changes via mtime comparison
+- **Transports**: stdio (command-based), SSE, HTTP
+- **OAuth (HTTP/SSE)**: Supports token endpoint flows (`client_credentials`, `refresh_token`) with automatic token refresh + Authorization header injection
+- **Runtime updates**: Gateway API saves to extensions_config.json; LangGraph detects via mtime
+
+### Skills System (`src/skills/`)
+
+- **Location**: `deer-flow/skills/{public,custom}/`
+- **Format**: Directory with `SKILL.md` (YAML frontmatter: name, description, license, allowed-tools)
+- **Loading**: `load_skills()` scans directories, parses SKILL.md, reads enabled state from extensions_config.json
+- **Injection**: Enabled skills listed in agent system prompt with container paths
+- **Installation**: `POST /api/skills/install` extracts .skill ZIP archive to custom/ directory
+
+### Model Factory (`src/models/factory.py`)
+
+- `create_chat_model(name, thinking_enabled)` instantiates LLM from config via reflection
+- Supports `thinking_enabled` flag with per-model `when_thinking_enabled` overrides
+- Supports `supports_vision` flag for image understanding models
+- Config values starting with `$` resolved as environment variables
+
+### Memory System (`src/agents/memory/`)
+
+**Components**:
+- `updater.py` - LLM-based memory updates with fact extraction and atomic file I/O
+- `queue.py` - Debounced update queue (per-thread deduplication, configurable wait time)
+- `prompt.py` - Prompt templates for memory updates
+
+**Data Structure** (stored in `backend/.deer-flow/memory.json`):
+- **User Context**: `workContext`, `personalContext`, `topOfMind` (1-3 sentence summaries)
+- **History**: `recentMonths`, `earlierContext`, `longTermBackground`
+- **Facts**: Discrete facts with `id`, `content`, `category` (preference/knowledge/context/behavior/goal), `confidence` (0-1), `createdAt`, `source`
+
+**Workflow**:
+1. `MemoryMiddleware` filters messages (user inputs + final AI responses) and queues conversation
+2. Queue debounces (30s default), batches updates, deduplicates per-thread
+3. Background thread invokes LLM to extract context updates and facts
+4. Applies updates atomically (temp file + rename) with cache invalidation
+5. Next interaction injects top 15 facts + context into `<memory>` tags in system prompt
+
+**Configuration** (`config.yaml` → `memory`):
+- `enabled` / `injection_enabled` - Master switches
+- `storage_path` - Path to memory.json
+- `debounce_seconds` - Wait time before processing (default: 30)
+- `model_name` - LLM for updates (null = default model)
+- `max_facts` / `fact_confidence_threshold` - Fact storage limits (100 / 0.7)
+- `max_injection_tokens` - Token limit for prompt injection (2000)
+
+### Reflection System (`src/reflection/`)
+
+- `resolve_variable(path)` - Import module and return variable (e.g., `module.path:variable_name`)
+- `resolve_class(path, base_class)` - Import and validate class against base class
+
+### Config Schema
+
+**`config.yaml`** key sections:
+- `models[]` - LLM configs with `use` class path, `supports_thinking`, `supports_vision`, provider-specific fields
+- `tools[]` - Tool configs with `use` variable path and `group`
+- `tool_groups[]` - Logical groupings for tools
+- `sandbox.use` - Sandbox provider class path
+- `skills.path` / `skills.container_path` - Host and container paths to skills directory
+- `title` - Auto-title generation (enabled, max_words, max_chars, prompt_template)
+- `summarization` - Context summarization (enabled, trigger conditions, keep policy)
+- `subagents.enabled` - Master switch for subagent delegation
+- `memory` - Memory system (enabled, storage_path, debounce_seconds, model_name, max_facts, fact_confidence_threshold, injection_enabled, max_injection_tokens)
+
+**`extensions_config.json`**:
+- `mcpServers` - Map of server name → config (enabled, type, command, args, env, url, headers, oauth, description)
+- `skills` - Map of skill name → state (enabled)
+
+Both can be modified at runtime via Gateway API endpoints or `DeerFlowClient` methods.
+
+### Embedded Client (`src/client.py`)
+
+`DeerFlowClient` provides direct in-process access to all DeerFlow capabilities without HTTP services. All return types align with the Gateway API response schemas, so consumer code works identically in HTTP and embedded modes.
+
+**Architecture**: Imports the same `src/` modules that LangGraph Server and Gateway API use. Shares the same config files and data directories. No FastAPI dependency.
+
+**Agent Conversation** (replaces LangGraph Server):
+- `chat(message, thread_id)` — synchronous, returns final text
+- `stream(message, thread_id)` — yields `StreamEvent` aligned with LangGraph SSE protocol:
+  - `"values"` — full state snapshot (title, messages, artifacts)
+  - `"messages-tuple"` — per-message update (AI text, tool calls, tool results)
+  - `"end"` — stream finished
+- Agent created lazily via `create_agent()` + `_build_middlewares()`, same as `make_lead_agent`
+- Supports `checkpointer` parameter for state persistence across turns
+- `reset_agent()` forces agent recreation (e.g. after memory or skill changes)
+
+**Gateway Equivalent Methods** (replaces Gateway API):
+
+| Category | Methods | Return format |
+|----------|---------|---------------|
+| Models | `list_models()`, `get_model(name)` | `{"models": [...]}`, `{name, display_name, ...}` |
+| MCP | `get_mcp_config()`, `update_mcp_config(servers)` | `{"mcp_servers": {...}}` |
+| Skills | `list_skills()`, `get_skill(name)`, `update_skill(name, enabled)`, `install_skill(path)` | `{"skills": [...]}` |
+| Memory | `get_memory()`, `reload_memory()`, `get_memory_config()`, `get_memory_status()` | dict |
+| Uploads | `upload_files(thread_id, files)`, `list_uploads(thread_id)`, `delete_upload(thread_id, filename)` | `{"success": true, "files": [...]}`, `{"files": [...], "count": N}` |
+| Artifacts | `get_artifact(thread_id, path)` → `(bytes, mime_type)` | tuple |
+
+**Key difference from Gateway**: Upload accepts local `Path` objects instead of HTTP `UploadFile`. Artifact returns `(bytes, mime_type)` instead of HTTP Response. `update_mcp_config()` and `update_skill()` automatically invalidate the cached agent.
+
+**Tests**: `tests/test_client.py` (77 unit tests including `TestGatewayConformance`), `tests/test_client_live.py` (live integration tests, requires config.yaml)
+
+**Gateway Conformance Tests** (`TestGatewayConformance`): Validate that every dict-returning client method conforms to the corresponding Gateway Pydantic response model. Each test parses the client output through the Gateway model — if Gateway adds a required field that the client doesn't provide, Pydantic raises `ValidationError` and CI catches the drift. Covers: `ModelsListResponse`, `ModelResponse`, `SkillsListResponse`, `SkillResponse`, `SkillInstallResponse`, `McpConfigResponse`, `UploadResponse`, `MemoryConfigResponse`, `MemoryStatusResponse`.
+
+## Development Workflow
+
+### Test-Driven Development (TDD) — MANDATORY
+
+**Every new feature or bug fix MUST be accompanied by unit tests. No exceptions.**
+
+- Write tests in `backend/tests/` following the existing naming convention `test_<feature>.py`
+- Run the full suite before and after your change: `make test`
+- Tests must pass before a feature is considered complete
+- For lightweight config/utility modules, prefer pure unit tests with no external dependencies
+- If a module causes circular import issues in tests, add a `sys.modules` mock in `tests/conftest.py` (see existing example for `src.subagents.executor`)
+
+```bash
+# Run all tests
+make test
+
+# Run a specific test file
+PYTHONPATH=. uv run pytest tests/test_<feature>.py -v
+```
+
+### Running the Full Application
+
+From the **project root** directory:
+```bash
+make dev
+```
+
+This starts all services and makes the application available at `http://localhost:2026`.
+
+**Nginx routing**:
+- `/api/langgraph/*` → LangGraph Server (2024)
+- `/api/*` (other) → Gateway API (8001)
+- `/` (non-API) → Frontend (3000)
+
+### Running Backend Services Separately
+
+From the **backend** directory:
+
+```bash
+# Terminal 1: LangGraph server
+make dev
+
+# Terminal 2: Gateway API
+make gateway
+```
+
+Direct access (without nginx):
+- LangGraph: `http://localhost:2024`
+- Gateway: `http://localhost:8001`
+
+### Frontend Configuration
+
+The frontend uses environment variables to connect to backend services:
+- `NEXT_PUBLIC_LANGGRAPH_BASE_URL` - Defaults to `/api/langgraph` (through nginx)
+- `NEXT_PUBLIC_BACKEND_BASE_URL` - Defaults to empty string (through nginx)
+
+When using `make dev` from root, the frontend automatically connects through nginx.
+
+## Key Features
+
+### File Upload
+
+Multi-file upload with automatic document conversion:
+- Endpoint: `POST /api/threads/{thread_id}/uploads`
+- Supports: PDF, PPT, Excel, Word documents (converted via `markitdown`)
+- Files stored in thread-isolated directories
+- Agent receives uploaded file list via `UploadsMiddleware`
+
+See [docs/FILE_UPLOAD.md](docs/FILE_UPLOAD.md) for details.
+
+### Plan Mode
+
+TodoList middleware for complex multi-step tasks:
+- Controlled via runtime config: `config.configurable.is_plan_mode = True`
+- Provides `write_todos` tool for task tracking
+- One task in_progress at a time, real-time updates
+
+See [docs/plan_mode_usage.md](docs/plan_mode_usage.md) for details.
+
+### Context Summarization
+
+Automatic conversation summarization when approaching token limits:
+- Configured in `config.yaml` under `summarization` key
+- Trigger types: tokens, messages, or fraction of max input
+- Keeps recent messages while summarizing older ones
+
+See [docs/summarization.md](docs/summarization.md) for details.
+
+### Vision Support
+
+For models with `supports_vision: true`:
+- `ViewImageMiddleware` processes images in conversation
+- `view_image_tool` added to agent's toolset
+- Images automatically converted to base64 and injected into state
+
+## Code Style
+
+- Uses `ruff` for linting and formatting
+- Line length: 240 characters
+- Python 3.12+ with type hints
+- Double quotes, space indentation
+
+## Documentation
+
+See `docs/` directory for detailed documentation:
+- [CONFIGURATION.md](docs/CONFIGURATION.md) - Configuration options
+- [ARCHITECTURE.md](docs/ARCHITECTURE.md) - Architecture details
+- [API.md](docs/API.md) - API reference
+- [SETUP.md](docs/SETUP.md) - Setup guide
+- [FILE_UPLOAD.md](docs/FILE_UPLOAD.md) - File upload feature
+- [PATH_EXAMPLES.md](docs/PATH_EXAMPLES.md) - Path types and usage
+- [summarization.md](docs/summarization.md) - Context summarization
+- [plan_mode_usage.md](docs/plan_mode_usage.md) - Plan mode with TodoList

backend/CONTRIBUTING.md

@@ -0,0 +1,426 @@
+# Contributing to DeerFlow Backend
+
+Thank you for your interest in contributing to DeerFlow! This document provides guidelines and instructions for contributing to the backend codebase.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Code Style](#code-style)
+- [Making Changes](#making-changes)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Architecture Guidelines](#architecture-guidelines)
+
+## Getting Started
+
+### Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://docs.astral.sh/uv/) package manager
+- Git
+- Docker (optional, for Docker sandbox testing)
+
+### Fork and Clone
+
+1. Fork the repository on GitHub
+2. Clone your fork locally:
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/deer-flow.git
+   cd deer-flow
+   ```
+
+## Development Setup
+
+### Install Dependencies
+
+```bash
+# From project root
+cp config.example.yaml config.yaml
+
+# Install backend dependencies
+cd backend
+make install
+```
+
+### Configure Environment
+
+Set up your API keys for testing:
+
+```bash
+export OPENAI_API_KEY="your-api-key"
+# Add other keys as needed
+```
+
+### Run the Development Server
+
+```bash
+# Terminal 1: LangGraph server
+make dev
+
+# Terminal 2: Gateway API
+make gateway
+```
+
+## 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
+│   └── aio_sandbox/        # Docker sandbox
+│
+├── reflection/              # Dynamic loading
+│   └── __init__.py         # Module resolution
+│
+└── utils/                   # Utilities
+    └── __init__.py
+```
+
+## Code Style
+
+### Linting and Formatting
+
+We use `ruff` for both linting and formatting:
+
+```bash
+# Check for issues
+make lint
+
+# Auto-fix and format
+make format
+```
+
+### Style Guidelines
+
+- **Line length**: 240 characters maximum
+- **Python version**: 3.12+ features allowed
+- **Type hints**: Use type hints for function signatures
+- **Quotes**: Double quotes for strings
+- **Indentation**: 4 spaces (no tabs)
+- **Imports**: Group by standard library, third-party, local
+
+### Docstrings
+
+Use docstrings for public functions and classes:
+
+```python
+def create_chat_model(name: str, thinking_enabled: bool = False) -> BaseChatModel:
+    """Create a chat model instance from configuration.
+
+    Args:
+        name: The model name as defined in config.yaml
+        thinking_enabled: Whether to enable extended thinking
+
+    Returns:
+        A configured LangChain chat model instance
+
+    Raises:
+        ValueError: If the model name is not found in configuration
+    """
+    ...
+```
+
+## Making Changes
+
+### Branch Naming
+
+Use descriptive branch names:
+
+- `feature/add-new-tool` - New features
+- `fix/sandbox-timeout` - Bug fixes
+- `docs/update-readme` - Documentation
+- `refactor/config-system` - Code refactoring
+
+### Commit Messages
+
+Write clear, concise commit messages:
+
+```
+feat: add support for Claude 3.5 model
+
+- Add model configuration in config.yaml
+- Update model factory to handle Claude-specific settings
+- Add tests for new model
+```
+
+Prefix types:
+- `feat:` - New feature
+- `fix:` - Bug fix
+- `docs:` - Documentation
+- `refactor:` - Code refactoring
+- `test:` - Tests
+- `chore:` - Build/config changes
+
+## Testing
+
+### Running Tests
+
+```bash
+uv run pytest
+```
+
+### Writing Tests
+
+Place tests in the `tests/` directory mirroring the source structure:
+
+```
+tests/
+├── test_models/
+│   └── test_factory.py
+├── test_sandbox/
+│   └── test_local.py
+└── test_gateway/
+    └── test_models_router.py
+```
+
+Example test:
+
+```python
+import pytest
+from src.models.factory import create_chat_model
+
+def test_create_chat_model_with_valid_name():
+    """Test that a valid model name creates a model instance."""
+    model = create_chat_model("gpt-4")
+    assert model is not None
+
+def test_create_chat_model_with_invalid_name():
+    """Test that an invalid model name raises ValueError."""
+    with pytest.raises(ValueError):
+        create_chat_model("nonexistent-model")
+```
+
+## Pull Request Process
+
+### Before Submitting
+
+1. **Ensure tests pass**: `uv run pytest`
+2. **Run linter**: `make lint`
+3. **Format code**: `make format`
+4. **Update documentation** if needed
+
+### PR Description
+
+Include in your PR description:
+
+- **What**: Brief description of changes
+- **Why**: Motivation for the change
+- **How**: Implementation approach
+- **Testing**: How you tested the changes
+
+### Review Process
+
+1. Submit PR with clear description
+2. Address review feedback
+3. Ensure CI passes
+4. Maintainer will merge when approved
+
+## Architecture Guidelines
+
+### Adding New Tools
+
+1. Create tool in `src/tools/builtins/` or `src/community/`:
+
+```python
+# src/tools/builtins/my_tool.py
+from langchain_core.tools import tool
+
+@tool
+def my_tool(param: str) -> str:
+    """Tool description for the agent.
+
+    Args:
+        param: Description of the parameter
+
+    Returns:
+        Description of return value
+    """
+    return f"Result: {param}"
+```
+
+2. Register in `config.yaml`:
+
+```yaml
+tools:
+  - name: my_tool
+    group: my_group
+    use: src.tools.builtins.my_tool:my_tool
+```
+
+### Adding New Middleware
+
+1. Create middleware in `src/agents/middlewares/`:
+
+```python
+# src/agents/middlewares/my_middleware.py
+from langchain.agents.middleware import BaseMiddleware
+from langchain_core.runnables import RunnableConfig
+
+class MyMiddleware(BaseMiddleware):
+    """Middleware description."""
+
+    def transform_state(self, state: dict, config: RunnableConfig) -> dict:
+        """Transform the state before agent execution."""
+        # Modify state as needed
+        return state
+```
+
+2. Register in `src/agents/lead_agent/agent.py`:
+
+```python
+middlewares = [
+    ThreadDataMiddleware(),
+    SandboxMiddleware(),
+    MyMiddleware(),  # Add your middleware
+    TitleMiddleware(),
+    ClarificationMiddleware(),
+]
+```
+
+### Adding New API Endpoints
+
+1. Create router in `src/gateway/routers/`:
+
+```python
+# src/gateway/routers/my_router.py
+from fastapi import APIRouter
+
+router = APIRouter(prefix="/my-endpoint", tags=["my-endpoint"])
+
+@router.get("/")
+async def get_items():
+    """Get all items."""
+    return {"items": []}
+
+@router.post("/")
+async def create_item(data: dict):
+    """Create a new item."""
+    return {"created": data}
+```
+
+2. Register in `src/gateway/app.py`:
+
+```python
+from src.gateway.routers import my_router
+
+app.include_router(my_router.router)
+```
+
+### Configuration Changes
+
+When adding new configuration options:
+
+1. Update `src/config/app_config.py` with new fields
+2. Add default values in `config.example.yaml`
+3. Document in `docs/CONFIGURATION.md`
+
+### MCP Server Integration
+
+To add support for a new MCP server:
+
+1. Add configuration in `extensions_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@my-org/mcp-server"],
+      "description": "My MCP Server"
+    }
+  }
+}
+```
+
+2. Update `extensions_config.example.json` with the new server
+
+### Skills Development
+
+To create a new skill:
+
+1. Create directory in `skills/public/` or `skills/custom/`:
+
+```
+skills/public/my-skill/
+└── SKILL.md
+```
+
+2. Write `SKILL.md` with YAML front matter:
+
+```markdown
+---
+name: My Skill
+description: What this skill does
+license: MIT
+allowed-tools:
+  - read_file
+  - write_file
+  - bash
+---
+
+# My Skill
+
+Instructions for the agent when this skill is enabled...
+```
+
+## Questions?
+
+If you have questions about contributing:
+
+1. Check existing documentation in `docs/`
+2. Look for similar issues or PRs on GitHub
+3. Open a discussion or issue on GitHub
+
+Thank you for contributing to DeerFlow!

backend/Dockerfile

@@ -0,0 +1,28 @@
+# Backend Development Dockerfile
+FROM python:3.12-slim
+
+# Install system dependencies
+RUN apt-get update && apt-get install -y \
+    curl \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh
+ENV PATH="/root/.local/bin:$PATH"
+
+# Set working directory
+WORKDIR /app
+
+# Copy frontend source code
+COPY backend ./backend
+
+# Install dependencies with cache mount
+RUN --mount=type=cache,target=/root/.cache/uv \
+    sh -c "cd backend && uv sync"
+
+# Expose ports (gateway: 8001, langgraph: 2024)
+EXPOSE 8001 2024
+
+# Default command (can be overridden in docker-compose)
+CMD ["sh", "-c", "uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001"]

backend/Makefile

@@ -0,0 +1,17 @@
+install:
+	uv sync
+
+dev:
+	uv run langgraph dev --no-browser --allow-blocking --no-reload
+
+gateway:
+	uv run uvicorn src.gateway.app:app --host 0.0.0.0 --port 8001
+
+test:
+	PYTHONPATH=. uv run pytest tests/ -v
+
+lint:
+	uvx ruff check .
+
+format:
+	uvx ruff check . --fix && uvx ruff format .

backend/README.md

@@ -0,0 +1,355 @@
+# DeerFlow Backend
+
+DeerFlow is a LangGraph-based AI super agent with sandbox execution, persistent memory, and extensible tool integration. The backend enables AI agents to execute code, browse the web, manage files, delegate tasks to subagents, and retain context across conversations - all in isolated, per-thread environments.
+
+---
+
+## Architecture
+
+```
+                        ┌──────────────────────────────────────┐
+                        │          Nginx (Port 2026)           │
+                        │      Unified reverse proxy           │
+                        └───────┬──────────────────┬───────────┘
+                                │                  │
+              /api/langgraph/*  │                  │  /api/* (other)
+                                ▼                  ▼
+               ┌────────────────────┐  ┌────────────────────────┐
+               │ LangGraph Server   │  │   Gateway API (8001)   │
+               │    (Port 2024)     │  │   FastAPI REST         │
+               │                    │  │                        │
+               │ ┌────────────────┐ │  │ Models, MCP, Skills,   │
+               │ │  Lead Agent    │ │  │ Memory, Uploads,       │
+               │ │  ┌──────────┐  │ │  │ Artifacts              │
+               │ │  │Middleware│  │ │  └────────────────────────┘
+               │ │  │  Chain   │  │ │
+               │ │  └──────────┘  │ │
+               │ │  ┌──────────┐  │ │
+               │ │  │  Tools   │  │ │
+               │ │  └──────────┘  │ │
+               │ │  ┌──────────┐  │ │
+               │ │  │Subagents │  │ │
+               │ │  └──────────┘  │ │
+               │ └────────────────┘ │
+               └────────────────────┘
+```
+
+**Request Routing** (via Nginx):
+- `/api/langgraph/*` → LangGraph Server - agent interactions, threads, streaming
+- `/api/*` (other) → Gateway API - models, MCP, skills, memory, artifacts, uploads
+- `/` (non-API) → Frontend - Next.js web interface
+
+---
+
+## Core Components
+
+### Lead Agent
+
+The single LangGraph agent (`lead_agent`) is the runtime entry point, created via `make_lead_agent(config)`. It combines:
+
+- **Dynamic model selection** with thinking and vision support
+- **Middleware chain** for cross-cutting concerns (9 middlewares)
+- **Tool system** with sandbox, MCP, community, and built-in tools
+- **Subagent delegation** for parallel task execution
+- **System prompt** with skills injection, memory context, and working directory guidance
+
+### Middleware Chain
+
+Middlewares execute in strict order, each handling a specific concern:
+
+| # | Middleware | Purpose |
+|---|-----------|---------|
+| 1 | **ThreadDataMiddleware** | Creates per-thread isolated directories (workspace, uploads, outputs) |
+| 2 | **UploadsMiddleware** | Injects newly uploaded files into conversation context |
+| 3 | **SandboxMiddleware** | Acquires sandbox environment for code execution |
+| 4 | **SummarizationMiddleware** | Reduces context when approaching token limits (optional) |
+| 5 | **TodoListMiddleware** | Tracks multi-step tasks in plan mode (optional) |
+| 6 | **TitleMiddleware** | Auto-generates conversation titles after first exchange |
+| 7 | **MemoryMiddleware** | Queues conversations for async memory extraction |
+| 8 | **ViewImageMiddleware** | Injects image data for vision-capable models (conditional) |
+| 9 | **ClarificationMiddleware** | Intercepts clarification requests and interrupts execution (must be last) |
+
+### Sandbox System
+
+Per-thread isolated execution with virtual path translation:
+
+- **Abstract interface**: `execute_command`, `read_file`, `write_file`, `list_dir`
+- **Providers**: `LocalSandboxProvider` (filesystem) and `AioSandboxProvider` (Docker, in community/)
+- **Virtual paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
+- **Skills path**: `/mnt/skills` → `deer-flow/skills/` directory
+- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace`
+
+### Subagent System
+
+Async task delegation with concurrent execution:
+
+- **Built-in agents**: `general-purpose` (full toolset) and `bash` (command specialist)
+- **Concurrency**: Max 3 subagents per turn, 15-minute timeout
+- **Execution**: Background thread pools with status tracking and SSE events
+- **Flow**: Agent calls `task()` tool → executor runs subagent in background → polls for completion → returns result
+
+### Memory System
+
+LLM-powered persistent context retention across conversations:
+
+- **Automatic extraction**: Analyzes conversations for user context, facts, and preferences
+- **Structured storage**: User context (work, personal, top-of-mind), history, and confidence-scored facts
+- **Debounced updates**: Batches updates to minimize LLM calls (configurable wait time)
+- **System prompt injection**: Top facts + context injected into agent prompts
+- **Storage**: JSON file with mtime-based cache invalidation
+
+### Tool Ecosystem
+
+| Category | Tools |
+|----------|-------|
+| **Sandbox** | `bash`, `ls`, `read_file`, `write_file`, `str_replace` |
+| **Built-in** | `present_files`, `ask_clarification`, `view_image`, `task` (subagent) |
+| **Community** | Tavily (web search), Jina AI (web fetch), Firecrawl (scraping), DuckDuckGo (image search) |
+| **MCP** | Any Model Context Protocol server (stdio, SSE, HTTP transports) |
+| **Skills** | Domain-specific workflows injected via system prompt |
+
+### Gateway API
+
+FastAPI application providing REST endpoints for frontend integration:
+
+| Route | Purpose |
+|-------|---------|
+| `GET /api/models` | List available LLM models |
+| `GET/PUT /api/mcp/config` | Manage MCP server configurations |
+| `GET/PUT /api/skills` | List and manage skills |
+| `POST /api/skills/install` | Install skill from `.skill` archive |
+| `GET /api/memory` | Retrieve memory data |
+| `POST /api/memory/reload` | Force memory reload |
+| `GET /api/memory/config` | Memory configuration |
+| `GET /api/memory/status` | Combined config + data |
+| `POST /api/threads/{id}/uploads` | Upload files (auto-converts PDF/PPT/Excel/Word to Markdown) |
+| `GET /api/threads/{id}/uploads/list` | List uploaded files |
+| `GET /api/threads/{id}/artifacts/{path}` | Serve generated artifacts |
+
+---
+
+## Quick Start
+
+### Prerequisites
+
+- Python 3.12+
+- [uv](https://docs.astral.sh/uv/) package manager
+- API keys for your chosen LLM provider
+
+### Installation
+
+```bash
+cd deer-flow
+
+# Copy configuration files
+cp config.example.yaml config.yaml
+
+# Install backend dependencies
+cd backend
+make install
+```
+
+### Configuration
+
+Edit `config.yaml` in the project root:
+
+```yaml
+models:
+  - name: gpt-4o
+    display_name: GPT-4o
+    use: langchain_openai:ChatOpenAI
+    model: gpt-4o
+    api_key: $OPENAI_API_KEY
+    supports_thinking: false
+    supports_vision: true
+```
+
+Set your API keys:
+
+```bash
+export OPENAI_API_KEY="your-api-key-here"
+```
+
+### Running
+
+**Full Application** (from project root):
+
+```bash
+make dev  # Starts LangGraph + Gateway + Frontend + Nginx
+```
+
+Access at: http://localhost:2026
+
+**Backend Only** (from backend directory):
+
+```bash
+# Terminal 1: LangGraph server
+make dev
+
+# Terminal 2: Gateway API
+make gateway
+```
+
+Direct access: LangGraph at http://localhost:2024, Gateway at http://localhost:8001
+
+---
+
+## Project Structure
+
+```
+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
+├── docs/                       # Documentation
+├── tests/                      # Test suite
+├── langgraph.json              # LangGraph server configuration
+├── pyproject.toml              # Python dependencies
+├── Makefile                    # Development commands
+└── Dockerfile                  # Container build
+```
+
+---
+
+## Configuration
+
+### Main Configuration (`config.yaml`)
+
+Place in project root. Config values starting with `$` resolve as environment variables.
+
+Key sections:
+- `models` - LLM configurations with class paths, API keys, thinking/vision flags
+- `tools` - Tool definitions with module paths and groups
+- `tool_groups` - Logical tool groupings
+- `sandbox` - Execution environment provider
+- `skills` - Skills directory paths
+- `title` - Auto-title generation settings
+- `summarization` - Context summarization settings
+- `subagents` - Subagent system (enabled/disabled)
+- `memory` - Memory system settings (enabled, storage, debounce, facts limits)
+
+### Extensions Configuration (`extensions_config.json`)
+
+MCP servers and skill states in a single file:
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
+    },
+    "secure-http": {
+      "enabled": true,
+      "type": "http",
+      "url": "https://api.example.com/mcp",
+      "oauth": {
+        "enabled": true,
+        "token_url": "https://auth.example.com/oauth/token",
+        "grant_type": "client_credentials",
+        "client_id": "$MCP_OAUTH_CLIENT_ID",
+        "client_secret": "$MCP_OAUTH_CLIENT_SECRET"
+      }
+    }
+  },
+  "skills": {
+    "pdf-processing": {"enabled": true}
+  }
+}
+```
+
+### Environment Variables
+
+- `DEER_FLOW_CONFIG_PATH` - Override config.yaml location
+- `DEER_FLOW_EXTENSIONS_CONFIG_PATH` - Override extensions_config.json location
+- Model API keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `DEEPSEEK_API_KEY`, etc.
+- Tool API keys: `TAVILY_API_KEY`, `GITHUB_TOKEN`, etc.
+
+---
+
+## Development
+
+### Commands
+
+```bash
+make install    # Install dependencies
+make dev        # Run LangGraph server (port 2024)
+make gateway    # Run Gateway API (port 8001)
+make lint       # Run linter (ruff)
+make format     # Format code (ruff)
+```
+
+### Code Style
+
+- **Linter/Formatter**: `ruff`
+- **Line length**: 240 characters
+- **Python**: 3.12+ with type hints
+- **Quotes**: Double quotes
+- **Indentation**: 4 spaces
+
+### Testing
+
+```bash
+uv run pytest
+```
+
+---
+
+## Technology Stack
+
+- **LangGraph** (1.0.6+) - Agent framework and multi-agent orchestration
+- **LangChain** (1.2.3+) - LLM abstractions and tool system
+- **FastAPI** (0.115.0+) - Gateway REST API
+- **langchain-mcp-adapters** - Model Context Protocol support
+- **agent-sandbox** - Sandboxed code execution
+- **markitdown** - Multi-format document conversion
+- **tavily-python** / **firecrawl-py** - Web search and scraping
+
+---
+
+## Documentation
+
+- [Configuration Guide](docs/CONFIGURATION.md)
+- [Architecture Details](docs/ARCHITECTURE.md)
+- [API Reference](docs/API.md)
+- [File Upload](docs/FILE_UPLOAD.md)
+- [Path Examples](docs/PATH_EXAMPLES.md)
+- [Context Summarization](docs/summarization.md)
+- [Plan Mode](docs/plan_mode_usage.md)
+- [Setup Guide](docs/SETUP.md)
+
+---
+
+## License
+
+See the [LICENSE](../LICENSE) file in the project root.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.

backend/debug.py

@@ -0,0 +1,92 @@
+#!/usr/bin/env python
+"""
+Debug script for lead_agent.
+Run this file directly in VS Code with breakpoints.
+
+Usage:
+    1. Set breakpoints in agent.py or other files
+    2. Press F5 or use "Run and Debug" panel
+    3. Input messages in the terminal to interact with the agent
+"""
+
+import asyncio
+import logging
+import os
+import sys
+
+# Ensure we can import from src
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# Load environment variables
+from dotenv import load_dotenv
+from langchain_core.messages import HumanMessage
+
+from src.agents import make_lead_agent
+
+load_dotenv()
+
+# Configure logging
+logging.basicConfig(
+    level=logging.INFO,
+    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+)
+
+
+async def main():
+    # Initialize MCP tools at startup
+    try:
+        from src.mcp import initialize_mcp_tools
+
+        await initialize_mcp_tools()
+    except Exception as e:
+        print(f"Warning: Failed to initialize MCP tools: {e}")
+
+    # Create agent with default config
+    config = {
+        "configurable": {
+            "thread_id": "debug-thread-001",
+            "thinking_enabled": True,
+            "is_plan_mode": True,
+            # Uncomment to use a specific model
+            "model_name": "kimi-k2.5",
+        }
+    }
+
+    agent = make_lead_agent(config)
+
+    print("=" * 50)
+    print("Lead Agent Debug Mode")
+    print("Type 'quit' or 'exit' to stop")
+    print("=" * 50)
+
+    while True:
+        try:
+            user_input = input("\nYou: ").strip()
+            if not user_input:
+                continue
+            if user_input.lower() in ("quit", "exit"):
+                print("Goodbye!")
+                break
+
+            # Invoke the agent
+            state = {"messages": [HumanMessage(content=user_input)]}
+            result = await agent.ainvoke(state, config=config, context={"thread_id": "debug-thread-001"})
+
+            # Print the response
+            if result.get("messages"):
+                last_message = result["messages"][-1]
+                print(f"\nAgent: {last_message.content}")
+
+        except KeyboardInterrupt:
+            print("\nInterrupted. Goodbye!")
+            break
+        except Exception as e:
+            print(f"\nError: {e}")
+            import traceback
+
+            traceback.print_exc()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

backend/docs/API.md

@@ -0,0 +1,607 @@
+# API Reference
+
+This document provides a complete reference for the DeerFlow backend APIs.
+
+## Overview
+
+DeerFlow backend exposes two sets of APIs:
+
+1. **LangGraph API** - Agent interactions, threads, and streaming (`/api/langgraph/*`)
+2. **Gateway API** - Models, MCP, skills, uploads, and artifacts (`/api/*`)
+
+All APIs are accessed through the Nginx reverse proxy at port 2026.
+
+## LangGraph API
+
+Base URL: `/api/langgraph`
+
+The LangGraph API is provided by the LangGraph server and follows the LangGraph SDK conventions.
+
+### Threads
+
+#### Create Thread
+
+```http
+POST /api/langgraph/threads
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "metadata": {}
+}
+```
+
+**Response:**
+```json
+{
+  "thread_id": "abc123",
+  "created_at": "2024-01-15T10:30:00Z",
+  "metadata": {}
+}
+```
+
+#### Get Thread State
+
+```http
+GET /api/langgraph/threads/{thread_id}/state
+```
+
+**Response:**
+```json
+{
+  "values": {
+    "messages": [...],
+    "sandbox": {...},
+    "artifacts": [...],
+    "thread_data": {...},
+    "title": "Conversation Title"
+  },
+  "next": [],
+  "config": {...}
+}
+```
+
+### Runs
+
+#### Create Run
+
+Execute the agent with input.
+
+```http
+POST /api/langgraph/threads/{thread_id}/runs
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "input": {
+    "messages": [
+      {
+        "role": "user",
+        "content": "Hello, can you help me?"
+      }
+    ]
+  },
+  "config": {
+    "configurable": {
+      "model_name": "gpt-4",
+      "thinking_enabled": false,
+      "is_plan_mode": false
+    }
+  },
+  "stream_mode": ["values", "messages"]
+}
+```
+
+**Configurable Options:**
+- `model_name` (string): Override the default model
+- `thinking_enabled` (boolean): Enable extended thinking for supported models
+- `is_plan_mode` (boolean): Enable TodoList middleware for task tracking
+
+**Response:** Server-Sent Events (SSE) stream
+
+```
+event: values
+data: {"messages": [...], "title": "..."}
+
+event: messages
+data: {"content": "Hello! I'd be happy to help.", "role": "assistant"}
+
+event: end
+data: {}
+```
+
+#### Get Run History
+
+```http
+GET /api/langgraph/threads/{thread_id}/runs
+```
+
+**Response:**
+```json
+{
+  "runs": [
+    {
+      "run_id": "run123",
+      "status": "success",
+      "created_at": "2024-01-15T10:30:00Z"
+    }
+  ]
+}
+```
+
+#### Stream Run
+
+Stream responses in real-time.
+
+```http
+POST /api/langgraph/threads/{thread_id}/runs/stream
+Content-Type: application/json
+```
+
+Same request body as Create Run. Returns SSE stream.
+
+---
+
+## Gateway API
+
+Base URL: `/api`
+
+### Models
+
+#### List Models
+
+Get all available LLM models from configuration.
+
+```http
+GET /api/models
+```
+
+**Response:**
+```json
+{
+  "models": [
+    {
+      "name": "gpt-4",
+      "display_name": "GPT-4",
+      "supports_thinking": false,
+      "supports_vision": true
+    },
+    {
+      "name": "claude-3-opus",
+      "display_name": "Claude 3 Opus",
+      "supports_thinking": false,
+      "supports_vision": true
+    },
+    {
+      "name": "deepseek-v3",
+      "display_name": "DeepSeek V3",
+      "supports_thinking": true,
+      "supports_vision": false
+    }
+  ]
+}
+```
+
+#### Get Model Details
+
+```http
+GET /api/models/{model_name}
+```
+
+**Response:**
+```json
+{
+  "name": "gpt-4",
+  "display_name": "GPT-4",
+  "model": "gpt-4",
+  "max_tokens": 4096,
+  "supports_thinking": false,
+  "supports_vision": true
+}
+```
+
+### MCP Configuration
+
+#### Get MCP Config
+
+Get current MCP server configurations.
+
+```http
+GET /api/mcp/config
+```
+
+**Response:**
+```json
+{
+  "mcpServers": {
+    "github": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "***"
+      },
+      "description": "GitHub operations"
+    },
+    "filesystem": {
+      "enabled": false,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
+      "description": "File system access"
+    }
+  }
+}
+```
+
+#### Update MCP Config
+
+Update MCP server configurations.
+
+```http
+PUT /api/mcp/config
+Content-Type: application/json
+```
+
+**Request Body:**
+```json
+{
+  "mcpServers": {
+    "github": {
+      "enabled": true,
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_TOKEN": "$GITHUB_TOKEN"
+      },
+      "description": "GitHub operations"
+    }
+  }
+}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "MCP configuration updated"
+}
+```
+
+### Skills
+
+#### List Skills
+
+Get all available skills.
+
+```http
+GET /api/skills
+```
+
+**Response:**
+```json
+{
+  "skills": [
+    {
+      "name": "pdf-processing",
+      "display_name": "PDF Processing",
+      "description": "Handle PDF documents efficiently",
+      "enabled": true,
+      "license": "MIT",
+      "path": "public/pdf-processing"
+    },
+    {
+      "name": "frontend-design",
+      "display_name": "Frontend Design",
+      "description": "Design and build frontend interfaces",
+      "enabled": false,
+      "license": "MIT",
+      "path": "public/frontend-design"
+    }
+  ]
+}
+```
+
+#### Get Skill Details
+
+```http
+GET /api/skills/{skill_name}
+```
+
+**Response:**
+```json
+{
+  "name": "pdf-processing",
+  "display_name": "PDF Processing",
+  "description": "Handle PDF documents efficiently",
+  "enabled": true,
+  "license": "MIT",
+  "path": "public/pdf-processing",
+  "allowed_tools": ["read_file", "write_file", "bash"],
+  "content": "# PDF Processing\n\nInstructions for the agent..."
+}
+```
+
+#### Enable Skill
+
+```http
+POST /api/skills/{skill_name}/enable
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Skill 'pdf-processing' enabled"
+}
+```
+
+#### Disable Skill
+
+```http
+POST /api/skills/{skill_name}/disable
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Skill 'pdf-processing' disabled"
+}
+```
+
+#### Install Skill
+
+Install a skill from a `.skill` file.
+
+```http
+POST /api/skills/install
+Content-Type: multipart/form-data
+```
+
+**Request Body:**
+- `file`: The `.skill` file to install
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Skill 'my-skill' installed successfully",
+  "skill": {
+    "name": "my-skill",
+    "display_name": "My Skill",
+    "path": "custom/my-skill"
+  }
+}
+```
+
+### File Uploads
+
+#### Upload Files
+
+Upload one or more files to a thread.
+
+```http
+POST /api/threads/{thread_id}/uploads
+Content-Type: multipart/form-data
+```
+
+**Request Body:**
+- `files`: One or more files to upload
+
+**Response:**
+```json
+{
+  "success": true,
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/abc123/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf",
+      "markdown_file": "document.md",
+      "markdown_path": ".deer-flow/threads/abc123/user-data/uploads/document.md",
+      "markdown_virtual_path": "/mnt/user-data/uploads/document.md",
+      "markdown_artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.md"
+    }
+  ],
+  "message": "Successfully uploaded 1 file(s)"
+}
+```
+
+**Supported Document Formats** (auto-converted to Markdown):
+- PDF (`.pdf`)
+- PowerPoint (`.ppt`, `.pptx`)
+- Excel (`.xls`, `.xlsx`)
+- Word (`.doc`, `.docx`)
+
+#### List Uploaded Files
+
+```http
+GET /api/threads/{thread_id}/uploads/list
+```
+
+**Response:**
+```json
+{
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/abc123/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf",
+      "extension": ".pdf",
+      "modified": 1705997600.0
+    }
+  ],
+  "count": 1
+}
+```
+
+#### Delete File
+
+```http
+DELETE /api/threads/{thread_id}/uploads/{filename}
+```
+
+**Response:**
+```json
+{
+  "success": true,
+  "message": "Deleted document.pdf"
+}
+```
+
+### Artifacts
+
+#### Get Artifact
+
+Download or view an artifact generated by the agent.
+
+```http
+GET /api/threads/{thread_id}/artifacts/{path}
+```
+
+**Path Examples:**
+- `/api/threads/abc123/artifacts/mnt/user-data/outputs/result.txt`
+- `/api/threads/abc123/artifacts/mnt/user-data/uploads/document.pdf`
+
+**Query Parameters:**
+- `download` (boolean): If `true`, force download with Content-Disposition header
+
+**Response:** File content with appropriate Content-Type
+
+---
+
+## Error Responses
+
+All APIs return errors in a consistent format:
+
+```json
+{
+  "detail": "Error message describing what went wrong"
+}
+```
+
+**HTTP Status Codes:**
+- `400` - Bad Request: Invalid input
+- `404` - Not Found: Resource not found
+- `422` - Validation Error: Request validation failed
+- `500` - Internal Server Error: Server-side error
+
+---
+
+## Authentication
+
+Currently, DeerFlow does not implement authentication. All APIs are accessible without credentials.
+
+Note: This is about DeerFlow API authentication. MCP outbound connections can still use OAuth for configured HTTP/SSE MCP servers.
+
+For production deployments, it is recommended to:
+1. Use Nginx for basic auth or OAuth integration
+2. Deploy behind a VPN or private network
+3. Implement custom authentication middleware
+
+---
+
+## Rate Limiting
+
+No rate limiting is implemented by default. For production deployments, configure rate limiting in Nginx:
+
+```nginx
+limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
+
+location /api/ {
+    limit_req zone=api burst=20 nodelay;
+    proxy_pass http://backend;
+}
+```
+
+---
+
+## WebSocket Support
+
+The LangGraph server supports WebSocket connections for real-time streaming. Connect to:
+
+```
+ws://localhost:2026/api/langgraph/threads/{thread_id}/runs/stream
+```
+
+---
+
+## SDK Usage
+
+### Python (LangGraph SDK)
+
+```python
+from langgraph_sdk import get_client
+
+client = get_client(url="http://localhost:2026/api/langgraph")
+
+# Create thread
+thread = await client.threads.create()
+
+# Run agent
+async for event in client.runs.stream(
+    thread["thread_id"],
+    "lead_agent",
+    input={"messages": [{"role": "user", "content": "Hello"}]},
+    config={"configurable": {"model_name": "gpt-4"}},
+    stream_mode=["values", "messages"],
+):
+    print(event)
+```
+
+### JavaScript/TypeScript
+
+```typescript
+// Using fetch for Gateway API
+const response = await fetch('/api/models');
+const data = await response.json();
+console.log(data.models);
+
+// Using EventSource for streaming
+const eventSource = new EventSource(
+  `/api/langgraph/threads/${threadId}/runs/stream`
+);
+eventSource.onmessage = (event) => {
+  console.log(JSON.parse(event.data));
+};
+```
+
+### cURL Examples
+
+```bash
+# List models
+curl http://localhost:2026/api/models
+
+# Get MCP config
+curl http://localhost:2026/api/mcp/config
+
+# Upload file
+curl -X POST http://localhost:2026/api/threads/abc123/uploads \
+  -F "files=@document.pdf"
+
+# Enable skill
+curl -X POST http://localhost:2026/api/skills/pdf-processing/enable
+
+# Create thread and run agent
+curl -X POST http://localhost:2026/api/langgraph/threads \
+  -H "Content-Type: application/json" \
+  -d '{}'
+
+curl -X POST http://localhost:2026/api/langgraph/threads/abc123/runs \
+  -H "Content-Type: application/json" \
+  -d '{
+    "input": {"messages": [{"role": "user", "content": "Hello"}]},
+    "config": {"configurable": {"model_name": "gpt-4"}}
+  }'
+```

backend/docs/APPLE_CONTAINER.md

@@ -0,0 +1,238 @@
+# Apple Container Support
+
+DeerFlow now supports Apple Container as the preferred container runtime on macOS, with automatic fallback to Docker.
+
+## Overview
+
+Starting with this version, DeerFlow automatically detects and uses Apple Container on macOS when available, falling back to Docker when:
+- Apple Container is not installed
+- Running on non-macOS platforms
+
+This provides better performance on Apple Silicon Macs while maintaining compatibility across all platforms.
+
+## Benefits
+
+### On Apple Silicon Macs with Apple Container:
+- **Better Performance**: Native ARM64 execution without Rosetta 2 translation
+- **Lower Resource Usage**: Lighter weight than Docker Desktop
+- **Native Integration**: Uses macOS Virtualization.framework
+
+### Fallback to Docker:
+- Full backward compatibility
+- Works on all platforms (macOS, Linux, Windows)
+- No configuration changes needed
+
+## Requirements
+
+### For Apple Container (macOS only):
+- macOS 15.0 or later
+- Apple Silicon (M1/M2/M3/M4)
+- Apple Container CLI installed
+
+### Installation:
+```bash
+# Download from GitHub releases
+# https://github.com/apple/container/releases
+
+# Verify installation
+container --version
+
+# Start the service
+container system start
+```
+
+### For Docker (all platforms):
+- Docker Desktop or Docker Engine
+
+## How It Works
+
+### Automatic Detection
+
+The `AioSandboxProvider` automatically detects the available container runtime:
+
+1. On macOS: Try `container --version`
+   - Success → Use Apple Container
+   - Failure → Fall back to Docker
+
+2. On other platforms: Use Docker directly
+
+### Runtime Differences
+
+Both runtimes use nearly identical command syntax:
+
+**Container Startup:**
+```bash
+# Apple Container
+container run --rm -d -p 8080:8080 -v /host:/container -e KEY=value image
+
+# Docker
+docker run --rm -d -p 8080:8080 -v /host:/container -e KEY=value image
+```
+
+**Container Cleanup:**
+```bash
+# Apple Container (with --rm flag)
+container stop <id>  # Auto-removes due to --rm
+
+# Docker (with --rm flag)
+docker stop <id>     # Auto-removes due to --rm
+```
+
+### Implementation Details
+
+The implementation is in `backend/src/community/aio_sandbox/aio_sandbox_provider.py`:
+
+- `_detect_container_runtime()`: Detects available runtime at startup
+- `_start_container()`: Uses detected runtime, skips Docker-specific options for Apple Container
+- `_stop_container()`: Uses appropriate stop command for the runtime
+
+## Configuration
+
+No configuration changes are needed! The system works automatically.
+
+However, you can verify the runtime in use by checking the logs:
+
+```
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Detected Apple Container: container version 0.1.0
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using container: ...
+```
+
+Or for Docker:
+```
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Apple Container not available, falling back to Docker
+INFO:src.community.aio_sandbox.aio_sandbox_provider:Starting sandbox container using docker: ...
+```
+
+## Container Images
+
+Both runtimes use OCI-compatible images. The default image works with both:
+
+```yaml
+sandbox:
+  use: src.community.aio_sandbox:AioSandboxProvider
+  image: enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest  # Default image
+```
+
+Make sure your images are available for the appropriate architecture:
+- ARM64 for Apple Container on Apple Silicon
+- AMD64 for Docker on Intel Macs
+- Multi-arch images work on both
+
+### Pre-pulling Images (Recommended)
+
+**Important**: Container images are typically large (500MB+) and are pulled on first use, which can cause a long wait time without clear feedback.
+
+**Best Practice**: Pre-pull the image during setup:
+
+```bash
+# From project root
+make setup-sandbox
+```
+
+This command will:
+1. Read the configured image from `config.yaml` (or use default)
+2. Detect available runtime (Apple Container or Docker)
+3. Pull the image with progress indication
+4. Verify the image is ready for use
+
+**Manual pre-pull**:
+
+```bash
+# Using Apple Container
+container pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
+
+# Using Docker
+docker pull enterprise-public-cn-beijing.cr.volces.com/vefaas-public/all-in-one-sandbox:latest
+```
+
+If you skip pre-pulling, the image will be automatically pulled on first agent execution, which may take several minutes depending on your network speed.
+
+## Cleanup Scripts
+
+The project includes a unified cleanup script that handles both runtimes:
+
+**Script:** `scripts/cleanup-containers.sh`
+
+**Usage:**
+```bash
+# Clean up all DeerFlow sandbox containers
+./scripts/cleanup-containers.sh deer-flow-sandbox
+
+# Custom prefix
+./scripts/cleanup-containers.sh my-prefix
+```
+
+**Makefile Integration:**
+
+All cleanup commands in `Makefile` automatically handle both runtimes:
+```bash
+make stop   # Stops all services and cleans up containers
+make clean  # Full cleanup including logs
+```
+
+## Testing
+
+Test the container runtime detection:
+
+```bash
+cd backend
+python test_container_runtime.py
+```
+
+This will:
+1. Detect the available runtime
+2. Optionally start a test container
+3. Verify connectivity
+4. Clean up
+
+## Troubleshooting
+
+### Apple Container not detected on macOS
+
+1. Check if installed:
+   ```bash
+   which container
+   container --version
+   ```
+
+2. Check if service is running:
+   ```bash
+   container system start
+   ```
+
+3. Check logs for detection:
+   ```bash
+   # Look for detection message in application logs
+   grep "container runtime" logs/*.log
+   ```
+
+### Containers not cleaning up
+
+1. Manually check running containers:
+   ```bash
+   # Apple Container
+   container list
+
+   # Docker
+   docker ps
+   ```
+
+2. Run cleanup script manually:
+   ```bash
+   ./scripts/cleanup-containers.sh deer-flow-sandbox
+   ```
+
+### Performance issues
+
+- Apple Container should be faster on Apple Silicon
+- If experiencing issues, you can force Docker by temporarily renaming the `container` command:
+   ```bash
+   # Temporary workaround - not recommended for permanent use
+   sudo mv /opt/homebrew/bin/container /opt/homebrew/bin/container.bak
+   ```
+
+## References
+
+- [Apple Container GitHub](https://github.com/apple/container)
+- [Apple Container Documentation](https://github.com/apple/container/blob/main/docs/)
+- [OCI Image Spec](https://github.com/opencontainers/image-spec)

backend/docs/ARCHITECTURE.md

@@ -0,0 +1,464 @@
+# Architecture Overview
+
+This document provides a comprehensive overview of the DeerFlow backend architecture.
+
+## System Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────────┐
+│                              Client (Browser)                             │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                          Nginx (Port 2026)                               │
+│                    Unified Reverse Proxy Entry Point                      │
+│  ┌────────────────────────────────────────────────────────────────────┐  │
+│  │  /api/langgraph/*  →  LangGraph Server (2024)                      │  │
+│  │  /api/*            →  Gateway API (8001)                           │  │
+│  │  /*                →  Frontend (3000)                               │  │
+│  └────────────────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────┬────────────────────────────────────────┘
+                                  │
+          ┌───────────────────────┼───────────────────────┐
+          │                       │                       │
+          ▼                       ▼                       ▼
+┌─────────────────────┐ ┌─────────────────────┐ ┌─────────────────────┐
+│   LangGraph Server  │ │    Gateway API      │ │     Frontend        │
+│     (Port 2024)     │ │    (Port 8001)      │ │    (Port 3000)      │
+│                     │ │                     │ │                     │
+│  - Agent Runtime    │ │  - Models API       │ │  - Next.js App      │
+│  - Thread Mgmt      │ │  - MCP Config       │ │  - React UI         │
+│  - SSE Streaming    │ │  - Skills Mgmt      │ │  - Chat Interface   │
+│  - Checkpointing    │ │  - File Uploads     │ │                     │
+│                     │ │  - Artifacts        │ │                     │
+└─────────────────────┘ └─────────────────────┘ └─────────────────────┘
+          │                       │
+          │     ┌─────────────────┘
+          │     │
+          ▼     ▼
+┌──────────────────────────────────────────────────────────────────────────┐
+│                         Shared Configuration                              │
+│  ┌─────────────────────────┐  ┌────────────────────────────────────────┐ │
+│  │      config.yaml        │  │      extensions_config.json            │ │
+│  │  - Models               │  │  - MCP Servers                         │ │
+│  │  - Tools                │  │  - Skills State                        │ │
+│  │  - Sandbox              │  │                                        │ │
+│  │  - Summarization        │  │                                        │ │
+│  └─────────────────────────┘  └────────────────────────────────────────┘ │
+└──────────────────────────────────────────────────────────────────────────┘
+```
+
+## Component Details
+
+### LangGraph Server
+
+The LangGraph server is the core agent runtime, built on LangGraph for robust multi-agent workflow orchestration.
+
+**Entry Point**: `src/agents/lead_agent/agent.py:make_lead_agent`
+
+**Key Responsibilities**:
+- Agent creation and configuration
+- Thread state management
+- Middleware chain execution
+- Tool execution orchestration
+- SSE streaming for real-time responses
+
+**Configuration**: `langgraph.json`
+
+```json
+{
+  "agent": {
+    "type": "agent",
+    "path": "src.agents:make_lead_agent"
+  }
+}
+```
+
+### Gateway API
+
+FastAPI application providing REST endpoints for non-agent operations.
+
+**Entry Point**: `src/gateway/app.py`
+
+**Routers**:
+- `models.py` - `/api/models` - Model listing and details
+- `mcp.py` - `/api/mcp` - MCP server configuration
+- `skills.py` - `/api/skills` - Skills management
+- `uploads.py` - `/api/threads/{id}/uploads` - File upload
+- `artifacts.py` - `/api/threads/{id}/artifacts` - Artifact serving
+
+### Agent Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           make_lead_agent(config)                        │
+└────────────────────────────────────┬────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            Middleware Chain                              │
+│  ┌──────────────────────────────────────────────────────────────────┐   │
+│  │ 1. ThreadDataMiddleware  - Initialize workspace/uploads/outputs  │   │
+│  │ 2. UploadsMiddleware     - Process uploaded files               │   │
+│  │ 3. SandboxMiddleware     - Acquire sandbox environment          │   │
+│  │ 4. SummarizationMiddleware - Context reduction (if enabled)     │   │
+│  │ 5. TitleMiddleware       - Auto-generate titles                 │   │
+│  │ 6. TodoListMiddleware    - Task tracking (if plan_mode)         │   │
+│  │ 7. ViewImageMiddleware   - Vision model support                 │   │
+│  │ 8. ClarificationMiddleware - Handle clarifications              │   │
+│  └──────────────────────────────────────────────────────────────────┘   │
+└────────────────────────────────────┬────────────────────────────────────┘
+                                     │
+                                     ▼
+┌─────────────────────────────────────────────────────────────────────────┐
+│                              Agent Core                                  │
+│  ┌──────────────────┐  ┌──────────────────┐  ┌──────────────────────┐   │
+│  │      Model       │  │      Tools       │  │    System Prompt     │   │
+│  │  (from factory)  │  │  (configured +   │  │  (with skills)       │   │
+│  │                  │  │   MCP + builtin) │  │                      │   │
+│  └──────────────────┘  └──────────────────┘  └──────────────────────┘   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Thread State
+
+The `ThreadState` extends LangGraph's `AgentState` with additional fields:
+
+```python
+class ThreadState(AgentState):
+    # Core state from AgentState
+    messages: list[BaseMessage]
+
+    # DeerFlow extensions
+    sandbox: dict             # Sandbox environment info
+    artifacts: list[str]      # Generated file paths
+    thread_data: dict         # {workspace, uploads, outputs} paths
+    title: str | None         # Auto-generated conversation title
+    todos: list[dict]         # Task tracking (plan mode)
+    viewed_images: dict       # Vision model image data
+```
+
+### Sandbox System
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                           Sandbox Architecture                           │
+└─────────────────────────────────────────────────────────────────────────┘
+
+                      ┌─────────────────────────┐
+                      │    SandboxProvider      │ (Abstract)
+                      │  - acquire()            │
+                      │  - get()                │
+                      │  - release()            │
+                      └────────────┬────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                                         │
+              ▼                                         ▼
+┌─────────────────────────┐              ┌─────────────────────────┐
+│  LocalSandboxProvider   │              │  AioSandboxProvider     │
+│  (src/sandbox/local.py) │              │  (src/community/)       │
+│                         │              │                         │
+│  - Singleton instance   │              │  - Docker-based         │
+│  - Direct execution     │              │  - Isolated containers  │
+│  - Development use      │              │  - Production use       │
+└─────────────────────────┘              └─────────────────────────┘
+
+                      ┌─────────────────────────┐
+                      │        Sandbox          │ (Abstract)
+                      │  - execute_command()    │
+                      │  - read_file()          │
+                      │  - write_file()         │
+                      │  - list_dir()           │
+                      └─────────────────────────┘
+```
+
+**Virtual Path Mapping**:
+
+| Virtual Path | Physical Path |
+|-------------|---------------|
+| `/mnt/user-data/workspace` | `backend/.deer-flow/threads/{thread_id}/user-data/workspace` |
+| `/mnt/user-data/uploads` | `backend/.deer-flow/threads/{thread_id}/user-data/uploads` |
+| `/mnt/user-data/outputs` | `backend/.deer-flow/threads/{thread_id}/user-data/outputs` |
+| `/mnt/skills` | `deer-flow/skills/` |
+
+### Tool System
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                            Tool Sources                                  │
+└─────────────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────┐  ┌─────────────────────┐  ┌─────────────────────┐
+│   Built-in Tools    │  │  Configured Tools   │  │     MCP Tools       │
+│  (src/tools/)       │  │  (config.yaml)      │  │  (extensions.json)  │
+├─────────────────────┤  ├─────────────────────┤  ├─────────────────────┤
+│ - present_file      │  │ - web_search        │  │ - github            │
+│ - ask_clarification │  │ - web_fetch         │  │ - filesystem        │
+│ - view_image        │  │ - bash              │  │ - postgres          │
+│                     │  │ - read_file         │  │ - brave-search      │
+│                     │  │ - write_file        │  │ - puppeteer         │
+│                     │  │ - str_replace       │  │ - ...               │
+│                     │  │ - ls                │  │                     │
+└─────────────────────┘  └─────────────────────┘  └─────────────────────┘
+           │                       │                       │
+           └───────────────────────┴───────────────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   get_available_tools() │
+                      │   (src/tools/__init__)  │
+                      └─────────────────────────┘
+```
+
+### Model Factory
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Model Factory                                   │
+│                     (src/models/factory.py)                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+config.yaml:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ models:                                                                  │
+│   - name: gpt-4                                                         │
+│     display_name: GPT-4                                                 │
+│     use: langchain_openai:ChatOpenAI                                    │
+│     model: gpt-4                                                        │
+│     api_key: $OPENAI_API_KEY                                            │
+│     max_tokens: 4096                                                    │
+│     supports_thinking: false                                            │
+│     supports_vision: true                                               │
+└─────────────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   create_chat_model()   │
+                      │  - name: str            │
+                      │  - thinking_enabled     │
+                      └────────────┬────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   resolve_class()       │
+                      │  (reflection system)    │
+                      └────────────┬────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │   BaseChatModel         │
+                      │  (LangChain instance)   │
+                      └─────────────────────────┘
+```
+
+**Supported Providers**:
+- OpenAI (`langchain_openai:ChatOpenAI`)
+- Anthropic (`langchain_anthropic:ChatAnthropic`)
+- DeepSeek (`langchain_deepseek:ChatDeepSeek`)
+- Custom via LangChain integrations
+
+### MCP Integration
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          MCP Integration                                 │
+│                        (src/mcp/manager.py)                              │
+└─────────────────────────────────────────────────────────────────────────┘
+
+extensions_config.json:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ {                                                                        │
+│   "mcpServers": {                                                       │
+│     "github": {                                                         │
+│       "enabled": true,                                                  │
+│       "type": "stdio",                                                  │
+│       "command": "npx",                                                 │
+│       "args": ["-y", "@modelcontextprotocol/server-github"],           │
+│       "env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}                          │
+│     }                                                                   │
+│   }                                                                     │
+│ }                                                                       │
+└─────────────────────────────────────────────────────────────────────────┘
+                                   │
+                                   ▼
+                      ┌─────────────────────────┐
+                      │  MultiServerMCPClient   │
+                      │  (langchain-mcp-adapters)│
+                      └────────────┬────────────┘
+                                   │
+              ┌────────────────────┼────────────────────┐
+              │                    │                    │
+              ▼                    ▼                    ▼
+       ┌───────────┐        ┌───────────┐        ┌───────────┐
+       │  stdio    │        │   SSE     │        │   HTTP    │
+       │ transport │        │ transport │        │ transport │
+       └───────────┘        └───────────┘        └───────────┘
+```
+
+### Skills System
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                          Skills System                                   │
+│                       (src/skills/loader.py)                             │
+└─────────────────────────────────────────────────────────────────────────┘
+
+Directory Structure:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ skills/                                                                  │
+│ ├── public/                        # Public skills (committed)           │
+│ │   ├── pdf-processing/                                                 │
+│ │   │   └── SKILL.md                                                    │
+│ │   ├── frontend-design/                                                │
+│ │   │   └── SKILL.md                                                    │
+│ │   └── ...                                                             │
+│ └── custom/                        # Custom skills (gitignored)          │
+│     └── user-installed/                                                 │
+│         └── SKILL.md                                                    │
+└─────────────────────────────────────────────────────────────────────────┘
+
+SKILL.md Format:
+┌─────────────────────────────────────────────────────────────────────────┐
+│ ---                                                                      │
+│ name: PDF Processing                                                     │
+│ description: Handle PDF documents efficiently                            │
+│ license: MIT                                                            │
+│ allowed-tools:                                                          │
+│   - read_file                                                           │
+│   - write_file                                                          │
+│   - bash                                                                │
+│ ---                                                                      │
+│                                                                          │
+│ # Skill Instructions                                                     │
+│ Content injected into system prompt...                                   │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Request Flow
+
+```
+┌─────────────────────────────────────────────────────────────────────────┐
+│                         Request Flow Example                             │
+│                    User sends message to agent                           │
+└─────────────────────────────────────────────────────────────────────────┘
+
+1. Client → Nginx
+   POST /api/langgraph/threads/{thread_id}/runs
+   {"input": {"messages": [{"role": "user", "content": "Hello"}]}}
+
+2. Nginx → LangGraph Server (2024)
+   Proxied to LangGraph server
+
+3. LangGraph Server
+   a. Load/create thread state
+   b. Execute middleware chain:
+      - ThreadDataMiddleware: Set up paths
+      - UploadsMiddleware: Inject file list
+      - SandboxMiddleware: Acquire sandbox
+      - SummarizationMiddleware: Check token limits
+      - TitleMiddleware: Generate title if needed
+      - TodoListMiddleware: Load todos (if plan mode)
+      - ViewImageMiddleware: Process images
+      - ClarificationMiddleware: Check for clarifications
+
+   c. Execute agent:
+      - Model processes messages
+      - May call tools (bash, web_search, etc.)
+      - Tools execute via sandbox
+      - Results added to messages
+
+   d. Stream response via SSE
+
+4. Client receives streaming response
+```
+
+## Data Flow
+
+### File Upload Flow
+
+```
+1. Client uploads file
+   POST /api/threads/{thread_id}/uploads
+   Content-Type: multipart/form-data
+
+2. Gateway receives file
+   - Validates file
+   - Stores in .deer-flow/threads/{thread_id}/user-data/uploads/
+   - If document: converts to Markdown via markitdown
+
+3. Returns response
+   {
+     "files": [{
+       "filename": "doc.pdf",
+       "path": ".deer-flow/.../uploads/doc.pdf",
+       "virtual_path": "/mnt/user-data/uploads/doc.pdf",
+       "artifact_url": "/api/threads/.../artifacts/mnt/.../doc.pdf"
+     }]
+   }
+
+4. Next agent run
+   - UploadsMiddleware lists files
+   - Injects file list into messages
+   - Agent can access via virtual_path
+```
+
+### Configuration Reload
+
+```
+1. Client updates MCP config
+   PUT /api/mcp/config
+
+2. Gateway writes extensions_config.json
+   - Updates mcpServers section
+   - File mtime changes
+
+3. MCP Manager detects change
+   - get_cached_mcp_tools() checks mtime
+   - If changed: reinitializes MCP client
+   - Loads updated server configurations
+
+4. Next agent run uses new tools
+```
+
+## Security Considerations
+
+### Sandbox Isolation
+
+- Agent code executes within sandbox boundaries
+- Local sandbox: Direct execution (development only)
+- Docker sandbox: Container isolation (production recommended)
+- Path traversal prevention in file operations
+
+### API Security
+
+- Thread isolation: Each thread has separate data directories
+- File validation: Uploads checked for path safety
+- Environment variable resolution: Secrets not stored in config
+
+### MCP Security
+
+- Each MCP server runs in its own process
+- Environment variables resolved at runtime
+- Servers can be enabled/disabled independently
+
+## Performance Considerations
+
+### Caching
+
+- MCP tools cached with file mtime invalidation
+- Configuration loaded once, reloaded on file change
+- Skills parsed once at startup, cached in memory
+
+### Streaming
+
+- SSE used for real-time response streaming
+- Reduces time to first token
+- Enables progress visibility for long operations
+
+### Context Management
+
+- Summarization middleware reduces context when limits approached
+- Configurable triggers: tokens, messages, or fraction
+- Preserves recent messages while summarizing older ones

backend/docs/AUTO_TITLE_GENERATION.md

@@ -0,0 +1,256 @@
+# 自动 Thread Title 生成功能
+
+## 功能说明
+
+自动为对话线程生成标题，在用户首次提问并收到回复后自动触发。
+
+## 实现方式
+
+使用 `TitleMiddleware` 在 `after_agent` 钩子中：
+1. 检测是否是首次对话（1个用户消息 + 1个助手回复）
+2. 检查 state 是否已有 title
+3. 调用 LLM 生成简洁的标题（默认最多6个词）
+4. 将 title 存储到 `ThreadState` 中（会被 checkpointer 持久化）
+
+## ⚠️ 重要：存储机制
+
+### Title 存储位置
+
+Title 存储在 **`ThreadState.title`** 中，而非 thread metadata：
+
+```python
+class ThreadState(AgentState):
+    sandbox: SandboxState | None = None
+    title: str | None = None  # ✅ Title stored here
+```
+
+### 持久化说明
+
+| 部署方式 | 持久化 | 说明 |
+|---------|--------|------|
+| **LangGraph Studio (本地)** | ❌ 否 | 仅内存存储，重启后丢失 |
+| **LangGraph Platform** | ✅ 是 | 自动持久化到数据库 |
+| **自定义 + Checkpointer** | ✅ 是 | 需配置 PostgreSQL/SQLite checkpointer |
+
+### 如何启用持久化
+
+如果需要在本地开发时也持久化 title，需要配置 checkpointer：
+
+```python
+# 在 langgraph.json 同级目录创建 checkpointer.py
+from langgraph.checkpoint.postgres import PostgresSaver
+
+checkpointer = PostgresSaver.from_conn_string(
+    "postgresql://user:pass@localhost/dbname"
+)
+```
+
+然后在 `langgraph.json` 中引用：
+
+```json
+{
+  "graphs": {
+    "lead_agent": "src.agents:lead_agent"
+  },
+  "checkpointer": "checkpointer:checkpointer"
+}
+```
+
+## 配置
+
+在 `config.yaml` 中添加（可选）：
+
+```yaml
+title:
+  enabled: true
+  max_words: 6
+  max_chars: 60
+  model_name: null  # 使用默认模型
+```
+
+或在代码中配置：
+
+```python
+from src.config.title_config import TitleConfig, set_title_config
+
+set_title_config(TitleConfig(
+    enabled=True,
+    max_words=8,
+    max_chars=80,
+))
+```
+
+## 客户端使用
+
+### 获取 Thread Title
+
+```typescript
+// 方式1: 从 thread state 获取
+const state = await client.threads.getState(threadId);
+const title = state.values.title || "New Conversation";
+
+// 方式2: 监听 stream 事件
+for await (const chunk of client.runs.stream(threadId, assistantId, {
+  input: { messages: [{ role: "user", content: "Hello" }] }
+})) {
+  if (chunk.event === "values" && chunk.data.title) {
+    console.log("Title:", chunk.data.title);
+  }
+}
+```
+
+### 显示 Title
+
+```typescript
+// 在对话列表中显示
+function ConversationList() {
+  const [threads, setThreads] = useState([]);
+
+  useEffect(() => {
+    async function loadThreads() {
+      const allThreads = await client.threads.list();
+      
+      // 获取每个 thread 的 state 来读取 title
+      const threadsWithTitles = await Promise.all(
+        allThreads.map(async (t) => {
+          const state = await client.threads.getState(t.thread_id);
+          return {
+            id: t.thread_id,
+            title: state.values.title || "New Conversation",
+            updatedAt: t.updated_at,
+          };
+        })
+      );
+      
+      setThreads(threadsWithTitles);
+    }
+    loadThreads();
+  }, []);
+
+  return (
+    <ul>
+      {threads.map(thread => (
+        <li key={thread.id}>
+          <a href={`/chat/${thread.id}`}>{thread.title}</a>
+        </li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## 工作流程
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Client
+    participant LangGraph
+    participant TitleMiddleware
+    participant LLM
+    participant Checkpointer
+
+    User->>Client: 发送首条消息
+    Client->>LangGraph: POST /threads/{id}/runs
+    LangGraph->>Agent: 处理消息
+    Agent-->>LangGraph: 返回回复
+    LangGraph->>TitleMiddleware: after_agent()
+    TitleMiddleware->>TitleMiddleware: 检查是否需要生成 title
+    TitleMiddleware->>LLM: 生成 title
+    LLM-->>TitleMiddleware: 返回 title
+    TitleMiddleware->>LangGraph: return {"title": "..."}
+    LangGraph->>Checkpointer: 保存 state (含 title)
+    LangGraph-->>Client: 返回响应
+    Client->>Client: 从 state.values.title 读取
+```
+
+## 优势
+
+✅ **可靠持久化** - 使用 LangGraph 的 state 机制，自动持久化  
+✅ **完全后端处理** - 客户端无需额外逻辑  
+✅ **自动触发** - 首次对话后自动生成  
+✅ **可配置** - 支持自定义长度、模型等  
+✅ **容错性强** - 失败时使用 fallback 策略  
+✅ **架构一致** - 与现有 SandboxMiddleware 保持一致  
+
+## 注意事项
+
+1. **读取方式不同**：Title 在 `state.values.title` 而非 `thread.metadata.title`
+2. **性能考虑**：title 生成会增加约 0.5-1 秒延迟，可通过使用更快的模型优化
+3. **并发安全**：middleware 在 agent 执行后运行，不会阻塞主流程
+4. **Fallback 策略**：如果 LLM 调用失败，会使用用户消息的前几个词作为 title
+
+## 测试
+
+```python
+# 测试 title 生成
+import pytest
+from src.agents.title_middleware import TitleMiddleware
+
+def test_title_generation():
+    # TODO: 添加单元测试
+    pass
+```
+
+## 故障排查
+
+### Title 没有生成
+
+1. 检查配置是否启用：`get_title_config().enabled == True`
+2. 检查日志：查找 "Generated thread title" 或错误信息
+3. 确认是首次对话：只有 1 个用户消息和 1 个助手回复时才会触发
+
+### Title 生成但客户端看不到
+
+1. 确认读取位置：应该从 `state.values.title` 读取，而非 `thread.metadata.title`
+2. 检查 API 响应：确认 state 中包含 title 字段
+3. 尝试重新获取 state：`client.threads.getState(threadId)`
+
+### Title 重启后丢失
+
+1. 检查是否配置了 checkpointer（本地开发需要）
+2. 确认部署方式：LangGraph Platform 会自动持久化
+3. 查看数据库：确认 checkpointer 正常工作
+
+## 架构设计
+
+### 为什么使用 State 而非 Metadata？
+
+| 特性 | State | Metadata |
+|------|-------|----------|
+| **持久化** | ✅ 自动（通过 checkpointer） | ⚠️ 取决于实现 |
+| **版本控制** | ✅ 支持时间旅行 | ❌ 不支持 |
+| **类型安全** | ✅ TypedDict 定义 | ❌ 任意字典 |
+| **可追溯** | ✅ 每次更新都记录 | ⚠️ 只有最新值 |
+| **标准化** | ✅ LangGraph 核心机制 | ⚠️ 扩展功能 |
+
+### 实现细节
+
+```python
+# TitleMiddleware 核心逻辑
+@override
+def after_agent(self, state: TitleMiddlewareState, runtime: Runtime) -> dict | None:
+    """Generate and set thread title after the first agent response."""
+    if self._should_generate_title(state, runtime):
+        title = self._generate_title(runtime)
+        print(f"Generated thread title: {title}")
+        
+        # ✅ 返回 state 更新，会被 checkpointer 自动持久化
+        return {"title": title}
+    
+    return None
+```
+
+## 相关文件
+
+- [`src/agents/thread_state.py`](../src/agents/thread_state.py) - ThreadState 定义
+- [`src/agents/title_middleware.py`](../src/agents/title_middleware.py) - TitleMiddleware 实现
+- [`src/config/title_config.py`](../src/config/title_config.py) - 配置管理
+- [`config.yaml`](../config.yaml) - 配置文件
+- [`src/agents/lead_agent/agent.py`](../src/agents/lead_agent/agent.py) - Middleware 注册
+
+## 参考资料
+
+- [LangGraph Checkpointer 文档](https://langchain-ai.github.io/langgraph/concepts/persistence/)
+- [LangGraph State 管理](https://langchain-ai.github.io/langgraph/concepts/low_level/#state)
+- [LangGraph Middleware](https://langchain-ai.github.io/langgraph/concepts/middleware/)

backend/docs/CONFIGURATION.md

@@ -0,0 +1,238 @@
+# Configuration Guide
+
+This guide explains how to configure DeerFlow for your environment.
+
+## Configuration Sections
+
+### Models
+
+Configure the LLM models available to the agent:
+
+```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 (use env var)
+    max_tokens: 4096               # Max tokens per request
+    temperature: 0.7               # Sampling temperature
+```
+
+**Supported Providers**:
+- OpenAI (`langchain_openai:ChatOpenAI`)
+- Anthropic (`langchain_anthropic:ChatAnthropic`)
+- DeepSeek (`langchain_deepseek:ChatDeepSeek`)
+- Any LangChain-compatible provider
+
+For OpenAI-compatible gateways (for example Novita), keep using `langchain_openai:ChatOpenAI` and set `base_url`:
+
+```yaml
+models:
+  - name: novita-deepseek-v3.2
+    display_name: Novita DeepSeek V3.2
+    use: langchain_openai:ChatOpenAI
+    model: deepseek/deepseek-v3.2
+    api_key: $NOVITA_API_KEY
+    base_url: https://api.novita.ai/openai
+    supports_thinking: true
+    when_thinking_enabled:
+      extra_body:
+        thinking:
+          type: enabled
+```
+
+**Thinking Models**:
+Some models support "thinking" mode for complex reasoning:
+
+```yaml
+models:
+  - name: deepseek-v3
+    supports_thinking: true
+    when_thinking_enabled:
+      extra_body:
+        thinking:
+          type: enabled
+```
+
+### Tool Groups
+
+Organize tools into logical groups:
+
+```yaml
+tool_groups:
+  - name: web          # Web browsing and search
+  - name: file:read    # Read-only file operations
+  - name: file:write   # Write file operations
+  - name: bash         # Shell command execution
+```
+
+### Tools
+
+Configure specific tools available to the agent:
+
+```yaml
+tools:
+  - name: web_search
+    group: web
+    use: src.community.tavily.tools:web_search_tool
+    max_results: 5
+    # api_key: $TAVILY_API_KEY  # Optional
+```
+
+**Built-in Tools**:
+- `web_search` - Search the web (Tavily)
+- `web_fetch` - Fetch web pages (Jina AI)
+- `ls` - List directory contents
+- `read_file` - Read file contents
+- `write_file` - Write file contents
+- `str_replace` - String replacement in files
+- `bash` - Execute bash commands
+
+### Sandbox
+
+DeerFlow supports multiple sandbox execution modes. Configure your preferred mode in `config.yaml`:
+
+**Local Execution** (runs sandbox code directly on the host machine):
+```yaml
+sandbox:
+   use: src.sandbox.local:LocalSandboxProvider # Local execution
+```
+
+**Docker Execution** (runs sandbox code in isolated Docker containers):
+```yaml
+sandbox:
+   use: src.community.aio_sandbox:AioSandboxProvider # Docker-based sandbox
+```
+
+**Docker Execution with Kubernetes** (runs sandbox code in Kubernetes pods via provisioner service):
+
+This mode runs each sandbox in an isolated Kubernetes Pod on your **host machine's cluster**. Requires Docker Desktop K8s, OrbStack, or similar local K8s setup.
+
+```yaml
+sandbox:
+   use: src.community.aio_sandbox:AioSandboxProvider
+   provisioner_url: http://provisioner:8002
+```
+
+When using Docker development (`make docker-start`), DeerFlow starts the `provisioner` service only if this provisioner mode is configured. In local or plain Docker sandbox modes, `provisioner` is skipped.
+
+See [Provisioner Setup Guide](docker/provisioner/README.md) for detailed configuration, prerequisites, and troubleshooting.
+
+Choose between local execution or Docker-based isolation:
+
+**Option 1: Local Sandbox** (default, simpler setup):
+```yaml
+sandbox:
+  use: src.sandbox.local:LocalSandboxProvider
+```
+
+**Option 2: Docker Sandbox** (isolated, more secure):
+```yaml
+sandbox:
+  use: src.community.aio_sandbox:AioSandboxProvider
+  port: 8080
+  auto_start: true
+  container_prefix: deer-flow-sandbox
+
+  # Optional: Additional mounts
+  mounts:
+    - host_path: /path/on/host
+      container_path: /path/in/container
+      read_only: false
+```
+
+### Skills
+
+Configure the skills directory for specialized workflows:
+
+```yaml
+skills:
+  # Host path (optional, default: ../skills)
+  path: /custom/path/to/skills
+
+  # Container mount path (default: /mnt/skills)
+  container_path: /mnt/skills
+```
+
+**How Skills Work**:
+- Skills are stored in `deer-flow/skills/{public,custom}/`
+- Each skill has a `SKILL.md` file with metadata
+- Skills are automatically discovered and loaded
+- Available in both local and Docker sandbox via path mapping
+
+### Title Generation
+
+Automatic conversation title generation:
+
+```yaml
+title:
+  enabled: true
+  max_words: 6
+  max_chars: 60
+  model_name: null  # Use first model in list
+```
+
+## Environment Variables
+
+DeerFlow supports environment variable substitution using the `$` prefix:
+
+```yaml
+models:
+  - api_key: $OPENAI_API_KEY  # Reads from environment
+```
+
+**Common Environment Variables**:
+- `OPENAI_API_KEY` - OpenAI API key
+- `ANTHROPIC_API_KEY` - Anthropic API key
+- `DEEPSEEK_API_KEY` - DeepSeek API key
+- `NOVITA_API_KEY` - Novita API key (OpenAI-compatible endpoint)
+- `TAVILY_API_KEY` - Tavily search API key
+- `DEER_FLOW_CONFIG_PATH` - Custom config file path
+
+## Configuration Location
+
+The configuration file should be placed in the **project root directory** (`deer-flow/config.yaml`), not in the backend directory.
+
+## Configuration Priority
+
+DeerFlow searches for configuration in this order:
+
+1. Path specified in code via `config_path` argument
+2. Path from `DEER_FLOW_CONFIG_PATH` environment variable
+3. `config.yaml` in current working directory (typically `backend/` when running)
+4. `config.yaml` in parent directory (project root: `deer-flow/`)
+
+## Best Practices
+
+1. **Place `config.yaml` in project root** - Not in `backend/` directory
+2. **Never commit `config.yaml`** - It's already in `.gitignore`
+3. **Use environment variables for secrets** - Don't hardcode API keys
+4. **Keep `config.example.yaml` updated** - Document all new options
+5. **Test configuration changes locally** - Before deploying
+6. **Use Docker sandbox for production** - Better isolation and security
+
+## Troubleshooting
+
+### "Config file not found"
+- Ensure `config.yaml` exists in the **project root** directory (`deer-flow/config.yaml`)
+- The backend searches parent directory by default, so root location is preferred
+- Alternatively, set `DEER_FLOW_CONFIG_PATH` environment variable to custom location
+
+### "Invalid API key"
+- Verify environment variables are set correctly
+- Check that `$` prefix is used for env var references
+
+### "Skills not loading"
+- Check that `deer-flow/skills/` directory exists
+- Verify skills have valid `SKILL.md` files
+- Check `skills.path` configuration if using custom path
+
+### "Docker sandbox fails to start"
+- Ensure Docker is running
+- Check port 8080 (or configured port) is available
+- Verify Docker image is accessible
+
+## Examples
+
+See `config.example.yaml` for complete examples of all configuration options.

backend/docs/FILE_UPLOAD.md

@@ -0,0 +1,293 @@
+# 文件上传功能
+
+## 概述
+
+DeerFlow 后端提供了完整的文件上传功能，支持多文件上传，并自动将 Office 文档和 PDF 转换为 Markdown 格式。
+
+## 功能特性
+
+- ✅ 支持多文件同时上传
+- ✅ 自动转换文档为 Markdown（PDF、PPT、Excel、Word）
+- ✅ 文件存储在线程隔离的目录中
+- ✅ Agent 自动感知已上传的文件
+- ✅ 支持文件列表查询和删除
+
+## API 端点
+
+### 1. 上传文件
+```
+POST /api/threads/{thread_id}/uploads
+```
+
+**请求体：** `multipart/form-data`
+- `files`: 一个或多个文件
+
+**响应：**
+```json
+{
+  "success": true,
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
+      "markdown_file": "document.md",
+      "markdown_path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.md",
+      "markdown_virtual_path": "/mnt/user-data/uploads/document.md",
+      "markdown_artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.md"
+    }
+  ],
+  "message": "Successfully uploaded 1 file(s)"
+}
+```
+
+**路径说明：**
+- `path`: 实际文件系统路径（相对于 `backend/` 目录）
+- `virtual_path`: Agent 在沙箱中使用的虚拟路径
+- `artifact_url`: 前端通过 HTTP 访问文件的 URL
+
+### 2. 列出已上传文件
+```
+GET /api/threads/{thread_id}/uploads/list
+```
+
+**响应：**
+```json
+{
+  "files": [
+    {
+      "filename": "document.pdf",
+      "size": 1234567,
+      "path": ".deer-flow/threads/{thread_id}/user-data/uploads/document.pdf",
+      "virtual_path": "/mnt/user-data/uploads/document.pdf",
+      "artifact_url": "/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf",
+      "extension": ".pdf",
+      "modified": 1705997600.0
+    }
+  ],
+  "count": 1
+}
+```
+
+### 3. 删除文件
+```
+DELETE /api/threads/{thread_id}/uploads/{filename}
+```
+
+**响应：**
+```json
+{
+  "success": true,
+  "message": "Deleted document.pdf"
+}
+```
+
+## 支持的文档格式
+
+以下格式会自动转换为 Markdown：
+- PDF (`.pdf`)
+- PowerPoint (`.ppt`, `.pptx`)
+- Excel (`.xls`, `.xlsx`)
+- Word (`.doc`, `.docx`)
+
+转换后的 Markdown 文件会保存在同一目录下，文件名为原文件名 + `.md` 扩展名。
+
+## Agent 集成
+
+### 自动文件列举
+
+Agent 在每次请求时会自动收到已上传文件的列表，格式如下：
+
+```xml
+<uploaded_files>
+The following files have been uploaded and are available for use:
+
+- document.pdf (1.2 MB)
+  Path: /mnt/user-data/uploads/document.pdf
+
+- document.md (45.3 KB)
+  Path: /mnt/user-data/uploads/document.md
+
+You can read these files using the `read_file` tool with the paths shown above.
+</uploaded_files>
+```
+
+### 使用上传的文件
+
+Agent 在沙箱中运行，使用虚拟路径访问文件。Agent 可以直接使用 `read_file` 工具读取上传的文件：
+
+```python
+# 读取原始 PDF（如果支持）
+read_file(path="/mnt/user-data/uploads/document.pdf")
+
+# 读取转换后的 Markdown（推荐）
+read_file(path="/mnt/user-data/uploads/document.md")
+```
+
+**路径映射关系：**
+- Agent 使用：`/mnt/user-data/uploads/document.pdf`（虚拟路径）
+- 实际存储：`backend/.deer-flow/threads/{thread_id}/user-data/uploads/document.pdf`
+- 前端访问：`/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf`（HTTP URL）
+
+上传流程采用“线程目录优先”策略：
+- 先写入 `backend/.deer-flow/threads/{thread_id}/user-data/uploads/` 作为权威存储
+- 本地沙箱（`sandbox_id=local`）直接使用线程目录内容
+- 非本地沙箱会额外同步到 `/mnt/user-data/uploads/*`，确保运行时可见
+
+## 测试示例
+
+### 使用 curl 测试
+
+```bash
+# 1. 上传单个文件
+curl -X POST http://localhost:2026/api/threads/test-thread/uploads \
+  -F "files=@/path/to/document.pdf"
+
+# 2. 上传多个文件
+curl -X POST http://localhost:2026/api/threads/test-thread/uploads \
+  -F "files=@/path/to/document.pdf" \
+  -F "files=@/path/to/presentation.pptx" \
+  -F "files=@/path/to/spreadsheet.xlsx"
+
+# 3. 列出已上传文件
+curl http://localhost:2026/api/threads/test-thread/uploads/list
+
+# 4. 删除文件
+curl -X DELETE http://localhost:2026/api/threads/test-thread/uploads/document.pdf
+```
+
+### 使用 Python 测试
+
+```python
+import requests
+
+thread_id = "test-thread"
+base_url = "http://localhost:2026"
+
+# 上传文件
+files = [
+    ("files", open("document.pdf", "rb")),
+    ("files", open("presentation.pptx", "rb")),
+]
+response = requests.post(
+    f"{base_url}/api/threads/{thread_id}/uploads",
+    files=files
+)
+print(response.json())
+
+# 列出文件
+response = requests.get(f"{base_url}/api/threads/{thread_id}/uploads/list")
+print(response.json())
+
+# 删除文件
+response = requests.delete(
+    f"{base_url}/api/threads/{thread_id}/uploads/document.pdf"
+)
+print(response.json())
+```
+
+## 文件存储结构
+
+```
+backend/.deer-flow/threads/
+└── {thread_id}/
+    └── user-data/
+        └── uploads/
+            ├── document.pdf          # 原始文件
+            ├── document.md           # 转换后的 Markdown
+            ├── presentation.pptx
+            ├── presentation.md
+            └── ...
+```
+
+## 限制
+
+- 最大文件大小：100MB（可在 nginx.conf 中配置 `client_max_body_size`）
+- 文件名安全性：系统会自动验证文件路径，防止目录遍历攻击
+- 线程隔离：每个线程的上传文件相互隔离，无法跨线程访问
+
+## 技术实现
+
+### 组件
+
+1. **Upload Router** (`src/gateway/routers/uploads.py`)
+   - 处理文件上传、列表、删除请求
+   - 使用 markitdown 转换文档
+
+2. **Uploads Middleware** (`src/agents/middlewares/uploads_middleware.py`)
+   - 在每次 Agent 请求前注入文件列表
+   - 自动生成格式化的文件列表消息
+
+3. **Nginx 配置** (`nginx.conf`)
+   - 路由上传请求到 Gateway API
+   - 配置大文件上传支持
+
+### 依赖
+
+- `markitdown>=0.0.1a2` - 文档转换
+- `python-multipart>=0.0.20` - 文件上传处理
+
+## 故障排查
+
+### 文件上传失败
+
+1. 检查文件大小是否超过限制
+2. 检查 Gateway API 是否正常运行
+3. 检查磁盘空间是否充足
+4. 查看 Gateway 日志：`make gateway`
+
+### 文档转换失败
+
+1. 检查 markitdown 是否正确安装：`uv run python -c "import markitdown"`
+2. 查看日志中的具体错误信息
+3. 某些损坏或加密的文档可能无法转换，但原文件仍会保存
+
+### Agent 看不到上传的文件
+
+1. 确认 UploadsMiddleware 已在 agent.py 中注册
+2. 检查 thread_id 是否正确
+3. 确认文件确实已上传到 `backend/.deer-flow/threads/{thread_id}/user-data/uploads/`
+4. 非本地沙箱场景下，确认上传接口没有报错（需要成功完成 sandbox 同步）
+
+## 开发建议
+
+### 前端集成
+
+```typescript
+// 上传文件示例
+async function uploadFiles(threadId: string, files: File[]) {
+  const formData = new FormData();
+  files.forEach(file => {
+    formData.append('files', file);
+  });
+
+  const response = await fetch(
+    `/api/threads/${threadId}/uploads`,
+    {
+      method: 'POST',
+      body: formData,
+    }
+  );
+
+  return response.json();
+}
+
+// 列出文件
+async function listFiles(threadId: string) {
+  const response = await fetch(
+    `/api/threads/${threadId}/uploads/list`
+  );
+  return response.json();
+}
+```
+
+### 扩展功能建议
+
+1. **文件预览**：添加预览端点，支持在浏览器中直接查看文件
+2. **批量删除**：支持一次删除多个文件
+3. **文件搜索**：支持按文件名或类型搜索
+4. **版本控制**：保留文件的多个版本
+5. **压缩包支持**：自动解压 zip 文件
+6. **图片 OCR**：对上传的图片进行 OCR 识别

backend/docs/MCP_SERVER.md

@@ -0,0 +1,65 @@
+# MCP (Model Context Protocol) Configuration
+
+DeerFlow supports configurable MCP servers and skills to extend its capabilities, which are loaded from a dedicated `extensions_config.json` file in the project root directory.
+
+## Setup
+
+1. Copy `extensions_config.example.json` to `extensions_config.json` in the project root directory.
+   ```bash
+   # Copy example configuration
+   cp extensions_config.example.json extensions_config.json
+   ```
+   
+2. Enable the desired MCP servers or skills by setting `"enabled": true`.
+3. Configure each server’s command, arguments, and environment variables as needed.
+4. Restart the application to load and register MCP tools.
+
+## OAuth Support (HTTP/SSE MCP Servers)
+
+For `http` and `sse` MCP servers, DeerFlow supports OAuth token acquisition and automatic token refresh.
+
+- Supported grants: `client_credentials`, `refresh_token`
+- Configure per-server `oauth` block in `extensions_config.json`
+- Secrets should be provided via environment variables (for example: `$MCP_OAUTH_CLIENT_SECRET`)
+
+Example:
+
+```json
+{
+   "mcpServers": {
+      "secure-http-server": {
+         "enabled": true,
+         "type": "http",
+         "url": "https://api.example.com/mcp",
+         "oauth": {
+            "enabled": true,
+            "token_url": "https://auth.example.com/oauth/token",
+            "grant_type": "client_credentials",
+            "client_id": "$MCP_OAUTH_CLIENT_ID",
+            "client_secret": "$MCP_OAUTH_CLIENT_SECRET",
+            "scope": "mcp.read",
+            "refresh_skew_seconds": 60
+         }
+      }
+   }
+}
+```
+
+## How It Works
+
+MCP servers expose tools that are automatically discovered and integrated into DeerFlow’s agent system at runtime. Once enabled, these tools become available to agents without additional code changes.
+
+## Example Capabilities
+
+MCP servers can provide access to:
+
+- **File systems**
+- **Databases** (e.g., PostgreSQL)
+- **External APIs** (e.g., GitHub, Brave Search)
+- **Browser automation** (e.g., Puppeteer)
+- **Custom MCP server implementations**
+
+## Learn More
+
+For detailed documentation about the Model Context Protocol, visit:  
+https://modelcontextprotocol.io

backend/docs/MEMORY_IMPROVEMENTS.md

@@ -0,0 +1,281 @@
+# Memory System Improvements
+
+This document describes recent improvements to the memory system's fact injection mechanism.
+
+## Overview
+
+Two major improvements have been made to the `format_memory_for_injection` function:
+
+1. **Similarity-Based Fact Retrieval**: Uses TF-IDF to select facts most relevant to current conversation context
+2. **Accurate Token Counting**: Uses tiktoken for precise token estimation instead of rough character-based approximation
+
+## 1. Similarity-Based Fact Retrieval
+
+### Problem
+The original implementation selected facts based solely on confidence scores, taking the top 15 highest-confidence facts regardless of their relevance to the current conversation. This could result in injecting irrelevant facts while omitting contextually important ones.
+
+### Solution
+The new implementation uses **TF-IDF (Term Frequency-Inverse Document Frequency)** vectorization with cosine similarity to measure how relevant each fact is to the current conversation context.
+
+**Scoring Formula**:
+```
+final_score = (similarity × 0.6) + (confidence × 0.4)
+```
+
+- **Similarity (60% weight)**: Cosine similarity between fact content and current context
+- **Confidence (40% weight)**: LLM-assigned confidence score (0-1)
+
+### Benefits
+- **Context-Aware**: Prioritizes facts relevant to what the user is currently discussing
+- **Dynamic**: Different facts surface based on conversation topic
+- **Balanced**: Considers both relevance and reliability
+- **Fallback**: Gracefully degrades to confidence-only ranking if context is unavailable
+
+### Example
+Given facts about Python, React, and Docker:
+- User asks: *"How should I write Python tests?"*
+  - Prioritizes: Python testing, type hints, pytest
+- User asks: *"How to optimize my Next.js app?"*
+  - Prioritizes: React/Next.js experience, performance optimization
+
+### Configuration
+Customize weights in `config.yaml` (optional):
+```yaml
+memory:
+  similarity_weight: 0.6  # Weight for TF-IDF similarity (0-1)
+  confidence_weight: 0.4  # Weight for confidence score (0-1)
+```
+
+**Note**: Weights should sum to 1.0 for best results.
+
+## 2. Accurate Token Counting
+
+### Problem
+The original implementation estimated tokens using a simple formula:
+```python
+max_chars = max_tokens * 4
+```
+
+This assumes ~4 characters per token, which is:
+- Inaccurate for many languages and content types
+- Can lead to over-injection (exceeding token limits)
+- Can lead to under-injection (wasting available budget)
+
+### Solution
+The new implementation uses **tiktoken**, OpenAI's official tokenizer library, to count tokens accurately:
+
+```python
+import tiktoken
+
+def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
+    encoding = tiktoken.get_encoding(encoding_name)
+    return len(encoding.encode(text))
+```
+
+- Uses `cl100k_base` encoding (GPT-4, GPT-3.5, text-embedding-ada-002)
+- Provides exact token counts for budget management
+- Falls back to character-based estimation if tiktoken fails
+
+### Benefits
+- **Precision**: Exact token counts match what the model sees
+- **Budget Optimization**: Maximizes use of available token budget
+- **No Overflows**: Prevents exceeding `max_injection_tokens` limit
+- **Better Planning**: Each section's token cost is known precisely
+
+### Example
+```python
+text = "This is a test string to count tokens accurately using tiktoken."
+
+# Old method
+char_count = len(text)  # 64 characters
+old_estimate = char_count // 4  # 16 tokens (overestimate)
+
+# New method
+accurate_count = _count_tokens(text)  # 13 tokens (exact)
+```
+
+**Result**: 3-token difference (18.75% error rate)
+
+In production, errors can be much larger for:
+- Code snippets (more tokens per character)
+- Non-English text (variable token ratios)
+- Technical jargon (often multi-token words)
+
+## Implementation Details
+
+### Function Signature
+```python
+def format_memory_for_injection(
+    memory_data: dict[str, Any],
+    max_tokens: int = 2000,
+    current_context: str | None = None,
+) -> str:
+```
+
+**New Parameter**:
+- `current_context`: Optional string containing recent conversation messages for similarity calculation
+
+### Backward Compatibility
+The function remains **100% backward compatible**:
+- If `current_context` is `None` or empty, falls back to confidence-only ranking
+- Existing callers without the parameter work exactly as before
+- Token counting is always accurate (transparent improvement)
+
+### Integration Point
+Memory is **dynamically injected** via `MemoryMiddleware.before_model()`:
+
+```python
+# src/agents/middlewares/memory_middleware.py
+
+def _extract_conversation_context(messages: list, max_turns: int = 3) -> str:
+    """Extract recent conversation (user input + final responses only)."""
+    context_parts = []
+    turn_count = 0
+
+    for msg in reversed(messages):
+        if msg.type == "human":
+            # Always include user messages
+            context_parts.append(extract_text(msg))
+            turn_count += 1
+            if turn_count >= max_turns:
+                break
+
+        elif msg.type == "ai" and not msg.tool_calls:
+            # Only include final AI responses (no tool_calls)
+            context_parts.append(extract_text(msg))
+
+        # Skip tool messages and AI messages with tool_calls
+
+    return " ".join(reversed(context_parts))
+
+
+class MemoryMiddleware:
+    def before_model(self, state, runtime):
+        """Inject memory before EACH LLM call (not just before_agent)."""
+
+        # Get recent conversation context (filtered)
+        conversation_context = _extract_conversation_context(
+            state["messages"],
+            max_turns=3
+        )
+
+        # Load memory with context-aware fact selection
+        memory_data = get_memory_data()
+        memory_content = format_memory_for_injection(
+            memory_data,
+            max_tokens=config.max_injection_tokens,
+            current_context=conversation_context,  # ✅ Clean conversation only
+        )
+
+        # Inject as system message
+        memory_message = SystemMessage(
+            content=f"<memory>\n{memory_content}\n</memory>",
+            name="memory_context",
+        )
+
+        return {"messages": [memory_message] + state["messages"]}
+```
+
+### How It Works
+
+1. **User continues conversation**:
+   ```
+   Turn 1: "I'm working on a Python project"
+   Turn 2: "It uses FastAPI and SQLAlchemy"
+   Turn 3: "How do I write tests?"  ← Current query
+   ```
+
+2. **Extract recent context**: Last 3 turns combined:
+   ```
+   "I'm working on a Python project. It uses FastAPI and SQLAlchemy. How do I write tests?"
+   ```
+
+3. **TF-IDF scoring**: Ranks facts by relevance to this context
+   - High score: "Prefers pytest for testing" (testing + Python)
+   - High score: "Likes type hints in Python" (Python related)
+   - High score: "Expert in Python and FastAPI" (Python + FastAPI)
+   - Low score: "Uses Docker for containerization" (less relevant)
+
+4. **Injection**: Top-ranked facts injected into system prompt's `<memory>` section
+
+5. **Agent sees**: Full system prompt with relevant memory context
+
+### Benefits of Dynamic System Prompt
+
+- **Multi-Turn Context**: Uses last 3 turns, not just current question
+  - Captures ongoing conversation flow
+  - Better understanding of user's current focus
+- **Query-Specific Facts**: Different facts surface based on conversation topic
+- **Clean Architecture**: No middleware message manipulation
+- **LangChain Native**: Uses built-in dynamic system prompt support
+- **Runtime Flexibility**: Memory regenerated for each agent invocation
+
+## Dependencies
+
+New dependencies added to `pyproject.toml`:
+```toml
+dependencies = [
+    # ... existing dependencies ...
+    "tiktoken>=0.8.0",      # Accurate token counting
+    "scikit-learn>=1.6.1",  # TF-IDF vectorization
+]
+```
+
+Install with:
+```bash
+cd backend
+uv sync
+```
+
+## Testing
+
+Run the test script to verify improvements:
+```bash
+cd backend
+python test_memory_improvement.py
+```
+
+Expected output shows:
+- Different fact ordering based on context
+- Accurate token counts vs old estimates
+- Budget-respecting fact selection
+
+## Performance Impact
+
+### Computational Cost
+- **TF-IDF Calculation**: O(n × m) where n=facts, m=vocabulary
+  - Negligible for typical fact counts (10-100 facts)
+  - Caching opportunities if context doesn't change
+- **Token Counting**: ~10-100µs per call
+  - Faster than the old character-counting approach
+  - Minimal overhead compared to LLM inference
+
+### Memory Usage
+- **TF-IDF Vectorizer**: ~1-5MB for typical vocabulary
+  - Instantiated once per injection call
+  - Garbage collected after use
+- **Tiktoken Encoding**: ~1MB (cached singleton)
+  - Loaded once per process lifetime
+
+### Recommendations
+- Current implementation is optimized for accuracy over caching
+- For high-throughput scenarios, consider:
+  - Pre-computing fact embeddings (store in memory.json)
+  - Caching TF-IDF vectorizer between calls
+  - Using approximate nearest neighbor search for >1000 facts
+
+## Summary
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Fact Selection | Top 15 by confidence only | Relevance-based (similarity + confidence) |
+| Token Counting | `len(text) // 4` | `tiktoken.encode(text)` |
+| Context Awareness | None | TF-IDF cosine similarity |
+| Accuracy | ±25% token estimate | Exact token count |
+| Configuration | Fixed weights | Customizable similarity/confidence weights |
+
+These improvements result in:
+- **More relevant** facts injected into context
+- **Better utilization** of available token budget
+- **Fewer hallucinations** due to focused context
+- **Higher quality** agent responses

backend/docs/MEMORY_IMPROVEMENTS_SUMMARY.md

@@ -0,0 +1,260 @@
+# Memory System Improvements - Summary
+
+## 改进概述
+
+针对你提出的两个问题进行了优化：
+1. ✅ **粗糙的 token 计算**（`字符数 * 4`）→ 使用 tiktoken 精确计算
+2. ✅ **缺乏相似度召回** → 使用 TF-IDF + 最近对话上下文
+
+## 核心改进
+
+### 1. 基于对话上下文的智能 Facts 召回
+
+**之前**：
+- 只按 confidence 排序取前 15 个
+- 无论用户在讨论什么都注入相同的 facts
+
+**现在**：
+- 提取最近 **3 轮对话**（human + AI 消息）作为上下文
+- 使用 **TF-IDF 余弦相似度**计算每个 fact 与对话的相关性
+- 综合评分：`相似度(60%) + 置信度(40%)`
+- 动态选择最相关的 facts
+
+**示例**：
+```
+对话历史：
+Turn 1: "我在做一个 Python 项目"
+Turn 2: "使用 FastAPI 和 SQLAlchemy"
+Turn 3: "怎么写测试？"
+
+上下文: "我在做一个 Python 项目 使用 FastAPI 和 SQLAlchemy 怎么写测试？"
+
+相关度高的 facts:
+✓ "Prefers pytest for testing" (Python + 测试)
+✓ "Expert in Python and FastAPI" (Python + FastAPI)
+✓ "Likes type hints in Python" (Python)
+
+相关度低的 facts:
+✗ "Uses Docker for containerization" (不相关)
+```
+
+### 2. 精确的 Token 计算
+
+**之前**：
+```python
+max_chars = max_tokens * 4  # 粗糙估算
+```
+
+**现在**：
+```python
+import tiktoken
+
+def _count_tokens(text: str) -> int:
+    encoding = tiktoken.get_encoding("cl100k_base")  # GPT-4/3.5
+    return len(encoding.encode(text))
+```
+
+**效果对比**：
+```python
+text = "This is a test string to count tokens accurately."
+旧方法: len(text) // 4 = 12 tokens (估算)
+新方法: tiktoken.encode = 10 tokens (精确)
+误差: 20%
+```
+
+### 3. 多轮对话上下文
+
+**之前的担心**：
+> "只传最近一条 human message 会不会上下文不太够？"
+
+**现在的解决方案**：
+- 提取最近 **3 轮对话**（可配置）
+- 包括 human 和 AI 消息
+- 更完整的对话上下文
+
+**示例**：
+```
+单条消息: "怎么写测试？"
+→ 缺少上下文，不知道是什么项目
+
+3轮对话: "Python 项目 + FastAPI + 怎么写测试？"
+→ 完整上下文，能选择更相关的 facts
+```
+
+## 实现方式
+
+### Middleware 动态注入
+
+使用 `before_model` 钩子在**每次 LLM 调用前**注入 memory：
+
+```python
+# src/agents/middlewares/memory_middleware.py
+
+def _extract_conversation_context(messages: list, max_turns: int = 3) -> str:
+    """提取最近 3 轮对话（只包含用户输入和最终回复）"""
+    context_parts = []
+    turn_count = 0
+
+    for msg in reversed(messages):
+        msg_type = getattr(msg, "type", None)
+
+        if msg_type == "human":
+            # ✅ 总是包含用户消息
+            content = extract_text(msg)
+            if content:
+                context_parts.append(content)
+                turn_count += 1
+                if turn_count >= max_turns:
+                    break
+
+        elif msg_type == "ai":
+            # ✅ 只包含没有 tool_calls 的 AI 消息（最终回复）
+            tool_calls = getattr(msg, "tool_calls", None)
+            if not tool_calls:
+                content = extract_text(msg)
+                if content:
+                    context_parts.append(content)
+
+        # ✅ 跳过 tool messages 和带 tool_calls 的 AI 消息
+
+    return " ".join(reversed(context_parts))
+
+
+class MemoryMiddleware:
+    def before_model(self, state, runtime):
+        """在每次 LLM 调用前注入 memory（不是 before_agent）"""
+
+        # 1. 提取最近 3 轮对话（过滤掉 tool calls）
+        messages = state["messages"]
+        conversation_context = _extract_conversation_context(messages, max_turns=3)
+
+        # 2. 使用干净的对话上下文选择相关 facts
+        memory_data = get_memory_data()
+        memory_content = format_memory_for_injection(
+            memory_data,
+            max_tokens=config.max_injection_tokens,
+            current_context=conversation_context,  # ✅ 只包含真实对话内容
+        )
+
+        # 3. 作为 system message 注入到消息列表开头
+        memory_message = SystemMessage(
+            content=f"<memory>\n{memory_content}\n</memory>",
+            name="memory_context",  # 用于去重检测
+        )
+
+        # 4. 插入到消息列表开头
+        updated_messages = [memory_message] + messages
+        return {"messages": updated_messages}
+```
+
+### 为什么这样设计？
+
+基于你的三个重要观察：
+
+1. **应该用 `before_model` 而不是 `before_agent`**
+   - ✅ `before_agent`: 只在整个 agent 开始时调用一次
+   - ✅ `before_model`: 在**每次 LLM 调用前**都会调用
+   - ✅ 这样每次 LLM 推理都能看到最新的相关 memory
+
+2. **messages 数组里只有 human/ai/tool，没有 system**
+   - ✅ 虽然不常见，但 LangChain 允许在对话中插入 system message
+   - ✅ Middleware 可以修改 messages 数组
+   - ✅ 使用 `name="memory_context"` 防止重复注入
+
+3. **��该剔除 tool call 的 AI messages，只传用户输入和最终输出**
+   - ✅ 过滤掉带 `tool_calls` 的 AI 消息（中间步骤）
+   - ✅ 只保留：     - Human 消息（用户输入）
+     - AI 消息但无 tool_calls（最终回复）
+   - ✅ 上下文更干净，TF-IDF 相似度计算更准确
+
+## 配置选项
+
+在 `config.yaml` 中可以调整：
+
+```yaml
+memory:
+  enabled: true
+  max_injection_tokens: 2000  # ✅ 使用精确 token 计数
+
+  # 高级设置（可选）
+  # max_context_turns: 3  # 对话轮数（默认 3）
+  # similarity_weight: 0.6  # 相似度权重
+  # confidence_weight: 0.4  # 置信度权重
+```
+
+## 依赖变更
+
+新增依赖：
+```toml
+dependencies = [
+    "tiktoken>=0.8.0",      # 精确 token 计数
+    "scikit-learn>=1.6.1",  # TF-IDF 向量化
+]
+```
+
+安装：
+```bash
+cd backend
+uv sync
+```
+
+## 性能影响
+
+- **TF-IDF 计算**：O(n × m)，n=facts 数量，m=词汇表大小
+  - 典型场景（10-100 facts）：< 10ms
+- **Token 计数**：~100µs per call
+  - 比字符计数还快
+- **总开销**：可忽略（相比 LLM 推理）
+
+## 向后兼容性
+
+✅ 完全向后兼容：
+- 如果没有 `current_context`，退化为按 confidence 排序
+- 所有现有配置继续工作
+- 不影响其他功能
+
+## 文件变更清单
+
+1. **核心功能**
+   - `src/agents/memory/prompt.py` - 添加 TF-IDF 召回和精确 token 计数
+   - `src/agents/lead_agent/prompt.py` - 动态系统提示
+   - `src/agents/lead_agent/agent.py` - 传入函数而非字符串
+
+2. **依赖**
+   - `pyproject.toml` - 添加 tiktoken 和 scikit-learn
+
+3. **文档**
+   - `docs/MEMORY_IMPROVEMENTS.md` - 详细技术文档
+   - `docs/MEMORY_IMPROVEMENTS_SUMMARY.md` - 改进总结（本文件）
+   - `CLAUDE.md` - 更新架构说明
+   - `config.example.yaml` - 添加配置说明
+
+## 测试验证
+
+运行项目验证：
+```bash
+cd backend
+make dev
+```
+
+在对话中测试：
+1. 讨论不同主题（Python、React、Docker 等）
+2. 观察不同对话注入的 facts 是否不同
+3. 检查 token 预算是否被准确控制
+
+## 总结
+
+| 问题 | 之前 | 现在 |
+|------|------|------|
+| Token 计算 | `len(text) // 4` (±25% 误差) | `tiktoken.encode()` (精确) |
+| Facts 选择 | 按 confidence 固定排序 | TF-IDF 相似度 + confidence |
+| 上下文 | 无 | 最近 3 轮对话 |
+| 实现方式 | 静态系统提示 | 动态系统提示函数 |
+| 配置灵活性 | 有限 | 可调轮数和权重 |
+
+所有改进都实现了，并且：
+- ✅ 不修改 messages 数组
+- ✅ 使用多轮对话上下文
+- ✅ 精确 token 计数
+- ✅ 智能相似度召回
+- ✅ 完全向后兼容

backend/docs/PATH_EXAMPLES.md

@@ -0,0 +1,289 @@
+# 文件路径使用示例
+
+## 三种路径类型
+
+DeerFlow 的文件上传系统返回三种不同的路径，每种路径用于不同的场景：
+
+### 1. 实际文件系统路径 (path)
+
+```
+.deer-flow/threads/{thread_id}/user-data/uploads/document.pdf
+```
+
+**用途：**
+- 文件在服务器文件系统中的实际位置
+- 相对于 `backend/` 目录
+- 用于直接文件系统访问、备份、调试等
+
+**示例：**
+```python
+# Python 代码中直接访问
+from pathlib import Path
+file_path = Path("backend/.deer-flow/threads/abc123/user-data/uploads/document.pdf")
+content = file_path.read_bytes()
+```
+
+### 2. 虚拟路径 (virtual_path)
+
+```
+/mnt/user-data/uploads/document.pdf
+```
+
+**用途：**
+- Agent 在沙箱环境中使用的路径
+- 沙箱系统会自动映射到实际路径
+- Agent 的所有文件操作工具都使用这个路径
+
+**示例：**
+Agent 在对话中使用：
+```python
+# Agent 使用 read_file 工具
+read_file(path="/mnt/user-data/uploads/document.pdf")
+
+# Agent 使用 bash 工具
+bash(command="cat /mnt/user-data/uploads/document.pdf")
+```
+
+### 3. HTTP 访问 URL (artifact_url)
+
+```
+/api/threads/{thread_id}/artifacts/mnt/user-data/uploads/document.pdf
+```
+
+**用途：**
+- 前端通过 HTTP 访问文件
+- 用于下载、预览文件
+- 可以直接在浏览器中打开
+
+**示例：**
+```typescript
+// 前端 TypeScript/JavaScript 代码
+const threadId = 'abc123';
+const filename = 'document.pdf';
+
+// 下载文件
+const downloadUrl = `/api/threads/${threadId}/artifacts/mnt/user-data/uploads/${filename}?download=true`;
+window.open(downloadUrl);
+
+// 在新窗口预览
+const viewUrl = `/api/threads/${threadId}/artifacts/mnt/user-data/uploads/${filename}`;
+window.open(viewUrl, '_blank');
+
+// 使用 fetch API 获取
+const response = await fetch(viewUrl);
+const blob = await response.blob();
+```
+
+## 完整使用流程示例
+
+### 场景：前端上传文件并让 Agent 处理
+
+```typescript
+// 1. 前端上传文件
+async function uploadAndProcess(threadId: string, file: File) {
+  // 上传文件
+  const formData = new FormData();
+  formData.append('files', file);
+
+  const uploadResponse = await fetch(
+    `/api/threads/${threadId}/uploads`,
+    {
+      method: 'POST',
+      body: formData
+    }
+  );
+
+  const uploadData = await uploadResponse.json();
+  const fileInfo = uploadData.files[0];
+
+  console.log('文件信息：', fileInfo);
+  // {
+  //   filename: "report.pdf",
+  //   path: ".deer-flow/threads/abc123/user-data/uploads/report.pdf",
+  //   virtual_path: "/mnt/user-data/uploads/report.pdf",
+  //   artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/uploads/report.pdf",
+  //   markdown_file: "report.md",
+  //   markdown_path: ".deer-flow/threads/abc123/user-data/uploads/report.md",
+  //   markdown_virtual_path: "/mnt/user-data/uploads/report.md",
+  //   markdown_artifact_url: "/api/threads/abc123/artifacts/mnt/user-data/uploads/report.md"
+  // }
+
+  // 2. 发送消息给 Agent
+  await sendMessage(threadId, "请分析刚上传的 PDF 文件");
+
+  // Agent 会自动看到文件列表，包含：
+  // - report.pdf (虚拟路径: /mnt/user-data/uploads/report.pdf)
+  // - report.md (虚拟路径: /mnt/user-data/uploads/report.md)
+
+  // 3. 前端可以直接访问转换后的 Markdown
+  const mdResponse = await fetch(fileInfo.markdown_artifact_url);
+  const markdownContent = await mdResponse.text();
+  console.log('Markdown 内容：', markdownContent);
+
+  // 4. 或者下载原始 PDF
+  const downloadLink = document.createElement('a');
+  downloadLink.href = fileInfo.artifact_url + '?download=true';
+  downloadLink.download = fileInfo.filename;
+  downloadLink.click();
+}
+```
+
+## 路径转换表
+
+| 场景 | 使用的路径类型 | 示例 |
+|------|---------------|------|
+| 服务器后端代码直接访问 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+| Agent 工具调用 | `virtual_path` | `/mnt/user-data/uploads/file.pdf` |
+| 前端下载/预览 | `artifact_url` | `/api/threads/abc123/artifacts/mnt/user-data/uploads/file.pdf` |
+| 备份脚本 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+| 日志记录 | `path` | `.deer-flow/threads/abc123/user-data/uploads/file.pdf` |
+
+## 代码示例集合
+
+### Python - 后端处理
+
+```python
+from pathlib import Path
+from src.agents.middlewares.thread_data_middleware import THREAD_DATA_BASE_DIR
+
+def process_uploaded_file(thread_id: str, filename: str):
+    # 使用实际路径
+    base_dir = Path.cwd() / THREAD_DATA_BASE_DIR / thread_id / "user-data" / "uploads"
+    file_path = base_dir / filename
+
+    # 直接读取
+    with open(file_path, 'rb') as f:
+        content = f.read()
+
+    return content
+```
+
+### JavaScript - 前端访问
+
+```javascript
+// 列出已上传的文件
+async function listUploadedFiles(threadId) {
+  const response = await fetch(`/api/threads/${threadId}/uploads/list`);
+  const data = await response.json();
+
+  // 为每个文件创建下载链接
+  data.files.forEach(file => {
+    console.log(`文件: ${file.filename}`);
+    console.log(`下载: ${file.artifact_url}?download=true`);
+    console.log(`预览: ${file.artifact_url}`);
+
+    // 如果是文档，还有 Markdown 版本
+    if (file.markdown_artifact_url) {
+      console.log(`Markdown: ${file.markdown_artifact_url}`);
+    }
+  });
+
+  return data.files;
+}
+
+// 删除文件
+async function deleteFile(threadId, filename) {
+  const response = await fetch(
+    `/api/threads/${threadId}/uploads/${filename}`,
+    { method: 'DELETE' }
+  );
+  return response.json();
+}
+```
+
+### React 组件示例
+
+```tsx
+import React, { useState, useEffect } from 'react';
+
+interface UploadedFile {
+  filename: string;
+  size: number;
+  path: string;
+  virtual_path: string;
+  artifact_url: string;
+  extension: string;
+  modified: number;
+  markdown_artifact_url?: string;
+}
+
+function FileUploadList({ threadId }: { threadId: string }) {
+  const [files, setFiles] = useState<UploadedFile[]>([]);
+
+  useEffect(() => {
+    fetchFiles();
+  }, [threadId]);
+
+  async function fetchFiles() {
+    const response = await fetch(`/api/threads/${threadId}/uploads/list`);
+    const data = await response.json();
+    setFiles(data.files);
+  }
+
+  async function handleUpload(event: React.ChangeEvent<HTMLInputElement>) {
+    const fileList = event.target.files;
+    if (!fileList) return;
+
+    const formData = new FormData();
+    Array.from(fileList).forEach(file => {
+      formData.append('files', file);
+    });
+
+    await fetch(`/api/threads/${threadId}/uploads`, {
+      method: 'POST',
+      body: formData
+    });
+
+    fetchFiles(); // 刷新列表
+  }
+
+  async function handleDelete(filename: string) {
+    await fetch(`/api/threads/${threadId}/uploads/${filename}`, {
+      method: 'DELETE'
+    });
+    fetchFiles(); // 刷新列表
+  }
+
+  return (
+    <div>
+      <input type="file" multiple onChange={handleUpload} />
+
+      <ul>
+        {files.map(file => (
+          <li key={file.filename}>
+            <span>{file.filename}</span>
+            <a href={file.artifact_url} target="_blank">预览</a>
+            <a href={`${file.artifact_url}?download=true`}>下载</a>
+            {file.markdown_artifact_url && (
+              <a href={file.markdown_artifact_url} target="_blank">Markdown</a>
+            )}
+            <button onClick={() => handleDelete(file.filename)}>删除</button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## 注意事项
+
+1. **路径安全性**
+   - 实际路径（`path`）包含线程 ID，确保隔离
+   - API 会验证路径，防止目录遍历攻击
+   - 前端不应直接使用 `path`，而应使用 `artifact_url`
+
+2. **Agent 使用**
+   - Agent 只能看到和使用 `virtual_path`
+   - 沙箱系统自动映射到实际路径
+   - Agent 不需要知道实际的文件系统结构
+
+3. **前端集成**
+   - 始终使用 `artifact_url` 访问文件
+   - 不要尝试直接访问文件系统路径
+   - 使用 `?download=true` 参数强制下载
+
+4. **Markdown 转换**
+   - 转换成功时，会返回额外的 `markdown_*` 字段
+   - 建议优先使用 Markdown 版本（更易处理）
+   - 原始文件始终保留

backend/docs/README.md

@@ -0,0 +1,53 @@
+# Documentation
+
+This directory contains detailed documentation for the DeerFlow backend.
+
+## Quick Links
+
+| Document | Description |
+|----------|-------------|
+| [ARCHITECTURE.md](ARCHITECTURE.md) | System architecture overview |
+| [API.md](API.md) | Complete API reference |
+| [CONFIGURATION.md](CONFIGURATION.md) | Configuration options |
+| [SETUP.md](SETUP.md) | Quick setup guide |
+
+## Feature Documentation
+
+| Document | Description |
+|----------|-------------|
+| [FILE_UPLOAD.md](FILE_UPLOAD.md) | File upload functionality |
+| [PATH_EXAMPLES.md](PATH_EXAMPLES.md) | Path types and usage examples |
+| [summarization.md](summarization.md) | Context summarization feature |
+| [plan_mode_usage.md](plan_mode_usage.md) | Plan mode with TodoList |
+| [AUTO_TITLE_GENERATION.md](AUTO_TITLE_GENERATION.md) | Automatic title generation |
+
+## Development
+
+| Document | Description |
+|----------|-------------|
+| [TODO.md](TODO.md) | Planned features and known issues |
+
+## Getting Started
+
+1. **New to DeerFlow?** Start with [SETUP.md](SETUP.md) for quick installation
+2. **Configuring the system?** See [CONFIGURATION.md](CONFIGURATION.md)
+3. **Understanding the architecture?** Read [ARCHITECTURE.md](ARCHITECTURE.md)
+4. **Building integrations?** Check [API.md](API.md) for API reference
+
+## Document Organization
+
+```
+docs/
+├── README.md                  # This file
+├── ARCHITECTURE.md            # System architecture
+├── API.md                     # API reference
+├── CONFIGURATION.md           # Configuration guide
+├── SETUP.md                   # Setup instructions
+├── FILE_UPLOAD.md             # File upload feature
+├── PATH_EXAMPLES.md           # Path usage examples
+├── summarization.md           # Summarization feature
+├── plan_mode_usage.md         # Plan mode feature
+├── AUTO_TITLE_GENERATION.md   # Title generation
+├── TITLE_GENERATION_IMPLEMENTATION.md  # Title implementation details
+└── TODO.md                    # Roadmap and issues
+```

backend/docs/SETUP.md

@@ -0,0 +1,92 @@
+# Setup Guide
+
+Quick setup instructions for DeerFlow.
+
+## Configuration Setup
+
+DeerFlow uses a YAML configuration file that should be placed in the **project root directory**.
+
+### Steps
+
+1. **Navigate to project root**:
+   ```bash
+   cd /path/to/deer-flow
+   ```
+
+2. **Copy example configuration**:
+   ```bash
+   cp config.example.yaml config.yaml
+   ```
+
+3. **Edit configuration**:
+   ```bash
+   # Option A: Set environment variables (recommended)
+   export OPENAI_API_KEY="your-key-here"
+
+   # Option B: Edit config.yaml directly
+   vim config.yaml  # or your preferred editor
+   ```
+
+4. **Verify configuration**:
+   ```bash
+   cd backend
+   python -c "from src.config import get_app_config; print('✓ Config loaded:', get_app_config().models[0].name)"
+   ```
+
+## Important Notes
+
+- **Location**: `config.yaml` should be in `deer-flow/` (project root), not `deer-flow/backend/`
+- **Git**: `config.yaml` is automatically ignored by git (contains secrets)
+- **Priority**: If both `backend/config.yaml` and `../config.yaml` exist, backend version takes precedence
+
+## Configuration File Locations
+
+The backend searches for `config.yaml` in this order:
+
+1. `DEER_FLOW_CONFIG_PATH` environment variable (if set)
+2. `backend/config.yaml` (current directory when running from backend/)
+3. `deer-flow/config.yaml` (parent directory - **recommended location**)
+
+**Recommended**: Place `config.yaml` in project root (`deer-flow/config.yaml`).
+
+## Sandbox Setup (Optional but Recommended)
+
+If you plan to use Docker/Container-based sandbox (configured in `config.yaml` under `sandbox.use: src.community.aio_sandbox:AioSandboxProvider`), it's highly recommended to pre-pull the container image:
+
+```bash
+# From project root
+make setup-sandbox
+```
+
+**Why pre-pull?**
+- The sandbox image (~500MB+) is pulled on first use, causing a long wait
+- Pre-pulling provides clear progress indication
+- Avoids confusion when first using the agent
+
+If you skip this step, the image will be automatically pulled on first agent execution, which may take several minutes depending on your network speed.
+
+## Troubleshooting
+
+### Config file not found
+
+```bash
+# Check where the backend is looking
+cd deer-flow/backend
+python -c "from src.config.app_config import AppConfig; print(AppConfig.resolve_config_path())"
+```
+
+If it can't find the config:
+1. Ensure you've copied `config.example.yaml` to `config.yaml`
+2. Verify you're in the correct directory
+3. Check the file exists: `ls -la ../config.yaml`
+
+### Permission denied
+
+```bash
+chmod 600 ../config.yaml  # Protect sensitive configuration
+```
+
+## See Also
+
+- [Configuration Guide](docs/CONFIGURATION.md) - Detailed configuration options
+- [Architecture Overview](CLAUDE.md) - System architecture

backend/docs/TITLE_GENERATION_IMPLEMENTATION.md

@@ -0,0 +1,222 @@
+# 自动 Title 生成功能实现总结
+
+## ✅ 已完成的工作
+
+### 1. 核心实现文件
+
+#### [`src/agents/thread_state.py`](../src/agents/thread_state.py)
+- ✅ 添加 `title: str | None = None` 字段到 `ThreadState`
+
+#### [`src/config/title_config.py`](../src/config/title_config.py) (新建)
+- ✅ 创建 `TitleConfig` 配置类
+- ✅ 支持配置：enabled, max_words, max_chars, model_name, prompt_template
+- ✅ 提供 `get_title_config()` 和 `set_title_config()` 函数
+- ✅ 提供 `load_title_config_from_dict()` 从配置文件加载
+
+#### [`src/agents/title_middleware.py`](../src/agents/title_middleware.py) (新建)
+- ✅ 创建 `TitleMiddleware` 类
+- ✅ 实现 `_should_generate_title()` 检查是否需要生成
+- ✅ 实现 `_generate_title()` 调用 LLM 生成标题
+- ✅ 实现 `after_agent()` 钩子，在首次对话后自动触发
+- ✅ 包含 fallback 策略（LLM 失败时使用用户消息前几个词）
+
+#### [`src/config/app_config.py`](../src/config/app_config.py)
+- ✅ 导入 `load_title_config_from_dict`
+- ✅ 在 `from_file()` 中加载 title 配置
+
+#### [`src/agents/lead_agent/agent.py`](../src/agents/lead_agent/agent.py)
+- ✅ 导入 `TitleMiddleware`
+- ✅ 注册到 `middleware` 列表：`[SandboxMiddleware(), TitleMiddleware()]`
+
+### 2. 配置文件
+
+#### [`config.yaml`](../config.yaml)
+- ✅ 添加 title 配置段：
+```yaml
+title:
+  enabled: true
+  max_words: 6
+  max_chars: 60
+  model_name: null
+```
+
+### 3. 文档
+
+#### [`docs/AUTO_TITLE_GENERATION.md`](../docs/AUTO_TITLE_GENERATION.md) (新建)
+- ✅ 完整的功能说明文档
+- ✅ 实现方式和架构设计
+- ✅ 配置说明
+- ✅ 客户端使用示例（TypeScript）
+- ✅ 工作流程图（Mermaid）
+- ✅ 故障排查指南
+- ✅ State vs Metadata 对比
+
+#### [`BACKEND_TODO.md`](../BACKEND_TODO.md)
+- ✅ 添加功能完成记录
+
+### 4. 测试
+
+#### [`tests/test_title_generation.py`](../tests/test_title_generation.py) (新建)
+- ✅ 配置类测试
+- ✅ Middleware 初始化测试
+- ✅ TODO: 集成测试（需要 mock Runtime）
+
+---
+
+## 🎯 核心设计决策
+
+### 为什么使用 State 而非 Metadata？
+
+| 方面 | State (✅ 采用) | Metadata (❌ 未采用) |
+|------|----------------|---------------------|
+| **持久化** | 自动（通过 checkpointer） | 取决于实现，不可靠 |
+| **版本控制** | 支持时间旅行 | 不支持 |
+| **类型安全** | TypedDict 定义 | 任意字典 |
+| **标准化** | LangGraph 核心机制 | 扩展功能 |
+
+### 工作流程
+
+```
+用户发送首条消息
+  ↓
+Agent 处理并返回回复
+  ↓
+TitleMiddleware.after_agent() 触发
+  ↓
+检查：是否首次对话？是否已有 title？
+  ↓
+调用 LLM 生成 title
+  ↓
+返回 {"title": "..."} 更新 state
+  ↓
+Checkpointer 自动持久化（如果配置了）
+  ↓
+客户端从 state.values.title 读取
+```
+
+---
+
+## 📋 使用指南
+
+### 后端配置
+
+1. **启用/禁用功能**
+```yaml
+# config.yaml
+title:
+  enabled: true  # 设为 false 禁用
+```
+
+2. **自定义配置**
+```yaml
+title:
+  enabled: true
+  max_words: 8      # 标题最多 8 个词
+  max_chars: 80     # 标题最多 80 个字符
+  model_name: null  # 使用默认模型
+```
+
+3. **配置持久化（可选）**
+
+如果需要在本地开发时持久化 title：
+
+```python
+# checkpointer.py
+from langgraph.checkpoint.sqlite import SqliteSaver
+
+checkpointer = SqliteSaver.from_conn_string("checkpoints.db")
+```
+
+```json
+// langgraph.json
+{
+  "graphs": {
+    "lead_agent": "src.agents:lead_agent"
+  },
+  "checkpointer": "checkpointer:checkpointer"
+}
+```
+
+### 客户端使用
+
+```typescript
+// 获取 thread title
+const state = await client.threads.getState(threadId);
+const title = state.values.title || "New Conversation";
+
+// 显示在对话列表
+<li>{title}</li>
+```
+
+**⚠️ 注意**：Title 在 `state.values.title`，而非 `thread.metadata.title`
+
+---
+
+## 🧪 测试
+
+```bash
+# 运行测试
+pytest tests/test_title_generation.py -v
+
+# 运行所有测试
+pytest
+```
+
+---
+
+## 🔍 故障排查
+
+### Title 没有生成？
+
+1. 检查配置：`title.enabled = true`
+2. 查看日志：搜索 "Generated thread title"
+3. 确认是首次对话（1 个用户消息 + 1 个助手回复）
+
+### Title 生成但看不到？
+
+1. 确认读取位置：`state.values.title`（不是 `thread.metadata.title`）
+2. 检查 API 响应是否包含 title
+3. 重新获取 state
+
+### Title 重启后丢失？
+
+1. 本地开发需要配置 checkpointer
+2. LangGraph Platform 会自动持久化
+3. 检查数据库确认 checkpointer 工作正常
+
+---
+
+## 📊 性能影响
+
+- **延迟增加**：约 0.5-1 秒（LLM 调用）
+- **并发安全**：在 `after_agent` 中运行，不阻塞主流程
+- **资源消耗**：每个 thread 只生成一次
+
+### 优化建议
+
+1. 使用更快的模型（如 `gpt-3.5-turbo`）
+2. 减少 `max_words` 和 `max_chars`
+3. 调整 prompt 使其更简洁
+
+---
+
+## �� 下一步
+
+- [ ] 添加集成测试（需要 mock LangGraph Runtime）
+- [ ] 支持自定义 prompt template
+- [ ] 支持多语言 title 生成
+- [ ] 添加 title 重新生成功能
+- [ ] 监控 title 生成成功率和延迟
+
+---
+
+## 📚 相关资源
+
+- [完整文档](../docs/AUTO_TITLE_GENERATION.md)
+- [LangGraph Middleware](https://langchain-ai.github.io/langgraph/concepts/middleware/)
+- [LangGraph State 管理](https://langchain-ai.github.io/langgraph/concepts/low_level/#state)
+- [LangGraph Checkpointer](https://langchain-ai.github.io/langgraph/concepts/persistence/)
+
+---
+
+*实现完成时间: 2026-01-14*

backend/docs/TODO.md

@@ -0,0 +1,27 @@
+# TODO List
+
+## Completed Features
+
+- [x] Launch the sandbox only after the first file system or bash tool is called
+- [x] Add Clarification Process for the whole process
+- [x] Implement Context Summarization Mechanism to avoid context explosion
+- [x] Integrate MCP (Model Context Protocol) for extensible tools
+- [x] Add file upload support with automatic document conversion
+- [x] Implement automatic thread title generation
+- [x] Add Plan Mode with TodoList middleware
+- [x] Add vision model support with ViewImageMiddleware
+- [x] Skills system with SKILL.md format
+
+## Planned Features
+
+- [ ] Pooling the sandbox resources to reduce the number of sandbox containers
+- [ ] Add authentication/authorization layer
+- [ ] Implement rate limiting
+- [ ] Add metrics and monitoring
+- [ ] Support for more document formats in upload
+- [ ] Skill marketplace / remote skill installation
+
+## Resolved Issues
+
+- [x] Make sure that no duplicated files in `state.artifacts`
+- [x] Long thinking but with empty content (answer inside thinking process)

backend/docs/plan_mode_usage.md

@@ -0,0 +1,204 @@
+# Plan Mode with TodoList Middleware
+
+This document describes how to enable and use the Plan Mode feature with TodoList middleware in DeerFlow 2.0.
+
+## Overview
+
+Plan Mode adds a TodoList middleware to the agent, which provides a `write_todos` tool that helps the agent:
+- Break down complex tasks into smaller, manageable steps
+- Track progress as work progresses
+- Provide visibility to users about what's being done
+
+The TodoList middleware is built on LangChain's `TodoListMiddleware`.
+
+## Configuration
+
+### Enabling Plan Mode
+
+Plan mode is controlled via **runtime configuration** through the `is_plan_mode` parameter in the `configurable` section of `RunnableConfig`. This allows you to dynamically enable or disable plan mode on a per-request basis.
+
+```python
+from langchain_core.runnables import RunnableConfig
+from src.agents.lead_agent.agent import make_lead_agent
+
+# Enable plan mode via runtime configuration
+config = RunnableConfig(
+    configurable={
+        "thread_id": "example-thread",
+        "thinking_enabled": True,
+        "is_plan_mode": True,  # Enable plan mode
+    }
+)
+
+# Create agent with plan mode enabled
+agent = make_lead_agent(config)
+```
+
+### Configuration Options
+
+- **is_plan_mode** (bool): Whether to enable plan mode with TodoList middleware. Default: `False`
+  - Pass via `config.get("configurable", {}).get("is_plan_mode", False)`
+  - Can be set dynamically for each agent invocation
+  - No global configuration needed
+
+## Default Behavior
+
+When plan mode is enabled with default settings, the agent will have access to a `write_todos` tool with the following behavior:
+
+### When to Use TodoList
+
+The agent will use the todo list for:
+1. Complex multi-step tasks (3+ distinct steps)
+2. Non-trivial tasks requiring careful planning
+3. When user explicitly requests a todo list
+4. When user provides multiple tasks
+
+### When NOT to Use TodoList
+
+The agent will skip using the todo list for:
+1. Single, straightforward tasks
+2. Trivial tasks (< 3 steps)
+3. Purely conversational or informational requests
+
+### Task States
+
+- **pending**: Task not yet started
+- **in_progress**: Currently working on (can have multiple parallel tasks)
+- **completed**: Task finished successfully
+
+## Usage Examples
+
+### Basic Usage
+
+```python
+from langchain_core.runnables import RunnableConfig
+from src.agents.lead_agent.agent import make_lead_agent
+
+# Create agent with plan mode ENABLED
+config_with_plan_mode = RunnableConfig(
+    configurable={
+        "thread_id": "example-thread",
+        "thinking_enabled": True,
+        "is_plan_mode": True,  # TodoList middleware will be added
+    }
+)
+agent_with_todos = make_lead_agent(config_with_plan_mode)
+
+# Create agent with plan mode DISABLED (default)
+config_without_plan_mode = RunnableConfig(
+    configurable={
+        "thread_id": "another-thread",
+        "thinking_enabled": True,
+        "is_plan_mode": False,  # No TodoList middleware
+    }
+)
+agent_without_todos = make_lead_agent(config_without_plan_mode)
+```
+
+### Dynamic Plan Mode per Request
+
+You can enable/disable plan mode dynamically for different conversations or tasks:
+
+```python
+from langchain_core.runnables import RunnableConfig
+from src.agents.lead_agent.agent import make_lead_agent
+
+def create_agent_for_task(task_complexity: str):
+    """Create agent with plan mode based on task complexity."""
+    is_complex = task_complexity in ["high", "very_high"]
+
+    config = RunnableConfig(
+        configurable={
+            "thread_id": f"task-{task_complexity}",
+            "thinking_enabled": True,
+            "is_plan_mode": is_complex,  # Enable only for complex tasks
+        }
+    )
+
+    return make_lead_agent(config)
+
+# Simple task - no TodoList needed
+simple_agent = create_agent_for_task("low")
+
+# Complex task - TodoList enabled for better tracking
+complex_agent = create_agent_for_task("high")
+```
+
+## How It Works
+
+1. When `make_lead_agent(config)` is called, it extracts `is_plan_mode` from `config.configurable`
+2. The config is passed to `_build_middlewares(config)`
+3. `_build_middlewares()` reads `is_plan_mode` and calls `_create_todo_list_middleware(is_plan_mode)`
+4. If `is_plan_mode=True`, a `TodoListMiddleware` instance is created and added to the middleware chain
+5. The middleware automatically adds a `write_todos` tool to the agent's toolset
+6. The agent can use this tool to manage tasks during execution
+7. The middleware handles the todo list state and provides it to the agent
+
+## Architecture
+
+```
+make_lead_agent(config)
+  │
+  ├─> Extracts: is_plan_mode = config.configurable.get("is_plan_mode", False)
+  │
+  └─> _build_middlewares(config)
+        │
+        ├─> ThreadDataMiddleware
+        ├─> SandboxMiddleware
+        ├─> SummarizationMiddleware (if enabled via global config)
+        ├─> TodoListMiddleware (if is_plan_mode=True) ← NEW
+        ├─> TitleMiddleware
+        └─> ClarificationMiddleware
+```
+
+## Implementation Details
+
+### Agent Module
+- **Location**: `src/agents/lead_agent/agent.py`
+- **Function**: `_create_todo_list_middleware(is_plan_mode: bool)` - Creates TodoListMiddleware if plan mode is enabled
+- **Function**: `_build_middlewares(config: RunnableConfig)` - Builds middleware chain based on runtime config
+- **Function**: `make_lead_agent(config: RunnableConfig)` - Creates agent with appropriate middlewares
+
+### Runtime Configuration
+Plan mode is controlled via the `is_plan_mode` parameter in `RunnableConfig.configurable`:
+```python
+config = RunnableConfig(
+    configurable={
+        "is_plan_mode": True,  # Enable plan mode
+        # ... other configurable options
+    }
+)
+```
+
+## Key Benefits
+
+1. **Dynamic Control**: Enable/disable plan mode per request without global state
+2. **Flexibility**: Different conversations can have different plan mode settings
+3. **Simplicity**: No need for global configuration management
+4. **Context-Aware**: Plan mode decision can be based on task complexity, user preferences, etc.
+
+## Custom Prompts
+
+DeerFlow uses custom `system_prompt` and `tool_description` for the TodoListMiddleware that match the overall DeerFlow prompt style:
+
+### System Prompt Features
+- Uses XML tags (`<todo_list_system>`) for structure consistency with DeerFlow's main prompt
+- Emphasizes CRITICAL rules and best practices
+- Clear "When to Use" vs "When NOT to Use" guidelines
+- Focuses on real-time updates and immediate task completion
+
+### Tool Description Features
+- Detailed usage scenarios with examples
+- Strong emphasis on NOT using for simple tasks
+- Clear task state definitions (pending, in_progress, completed)
+- Comprehensive best practices section
+- Task completion requirements to prevent premature marking
+
+The custom prompts are defined in `_create_todo_list_middleware()` in `/Users/hetao/workspace/deer-flow/backend/src/agents/lead_agent/agent.py:57`.
+
+## Notes
+
+- TodoList middleware uses LangChain's built-in `TodoListMiddleware` with **custom DeerFlow-style prompts**
+- Plan mode is **disabled by default** (`is_plan_mode=False`) to maintain backward compatibility
+- The middleware is positioned before `ClarificationMiddleware` to allow todo management during clarification flows
+- Custom prompts emphasize the same principles as DeerFlow's main system prompt (clarity, action-oriented, critical rules)

backend/docs/summarization.md

@@ -0,0 +1,353 @@
+# Conversation Summarization
+
+DeerFlow includes automatic conversation summarization to handle long conversations that approach model token limits. When enabled, the system automatically condenses older messages while preserving recent context.
+
+## Overview
+
+The summarization feature uses LangChain's `SummarizationMiddleware` to monitor conversation history and trigger summarization based on configurable thresholds. When activated, it:
+
+1. Monitors message token counts in real-time
+2. Triggers summarization when thresholds are met
+3. Keeps recent messages intact while summarizing older exchanges
+4. Maintains AI/Tool message pairs together for context continuity
+5. Injects the summary back into the conversation
+
+## Configuration
+
+Summarization is configured in `config.yaml` under the `summarization` key:
+
+```yaml
+summarization:
+  enabled: true
+  model_name: null  # Use default model or specify a lightweight model
+
+  # Trigger conditions (OR logic - any condition triggers summarization)
+  trigger:
+    - type: tokens
+      value: 4000
+    # Additional triggers (optional)
+    # - type: messages
+    #   value: 50
+    # - type: fraction
+    #   value: 0.8  # 80% of model's max input tokens
+
+  # Context retention policy
+  keep:
+    type: messages
+    value: 20
+
+  # Token trimming for summarization call
+  trim_tokens_to_summarize: 4000
+
+  # Custom summary prompt (optional)
+  summary_prompt: null
+```
+
+### Configuration Options
+
+#### `enabled`
+- **Type**: Boolean
+- **Default**: `false`
+- **Description**: Enable or disable automatic summarization
+
+#### `model_name`
+- **Type**: String or null
+- **Default**: `null` (uses default model)
+- **Description**: Model to use for generating summaries. Recommended to use a lightweight, cost-effective model like `gpt-4o-mini` or equivalent.
+
+#### `trigger`
+- **Type**: Single `ContextSize` or list of `ContextSize` objects
+- **Required**: At least one trigger must be specified when enabled
+- **Description**: Thresholds that trigger summarization. Uses OR logic - summarization runs when ANY threshold is met.
+
+**ContextSize Types:**
+
+1. **Token-based trigger**: Activates when token count reaches the specified value
+   ```yaml
+   trigger:
+     type: tokens
+     value: 4000
+   ```
+
+2. **Message-based trigger**: Activates when message count reaches the specified value
+   ```yaml
+   trigger:
+     type: messages
+     value: 50
+   ```
+
+3. **Fraction-based trigger**: Activates when token usage reaches a percentage of the model's maximum input tokens
+   ```yaml
+   trigger:
+     type: fraction
+     value: 0.8  # 80% of max input tokens
+   ```
+
+**Multiple Triggers:**
+```yaml
+trigger:
+  - type: tokens
+    value: 4000
+  - type: messages
+    value: 50
+```
+
+#### `keep`
+- **Type**: `ContextSize` object
+- **Default**: `{type: messages, value: 20}`
+- **Description**: Specifies how much recent conversation history to preserve after summarization.
+
+**Examples:**
+```yaml
+# Keep most recent 20 messages
+keep:
+  type: messages
+  value: 20
+
+# Keep most recent 3000 tokens
+keep:
+  type: tokens
+  value: 3000
+
+# Keep most recent 30% of model's max input tokens
+keep:
+  type: fraction
+  value: 0.3
+```
+
+#### `trim_tokens_to_summarize`
+- **Type**: Integer or null
+- **Default**: `4000`
+- **Description**: Maximum tokens to include when preparing messages for the summarization call itself. Set to `null` to skip trimming (not recommended for very long conversations).
+
+#### `summary_prompt`
+- **Type**: String or null
+- **Default**: `null` (uses LangChain's default prompt)
+- **Description**: Custom prompt template for generating summaries. The prompt should guide the model to extract the most important context.
+
+**Default Prompt Behavior:**
+The default LangChain prompt instructs the model to:
+- Extract highest quality/most relevant context
+- Focus on information critical to the overall goal
+- Avoid repeating completed actions
+- Return only the extracted context
+
+## How It Works
+
+### Summarization Flow
+
+1. **Monitoring**: Before each model call, the middleware counts tokens in the message history
+2. **Trigger Check**: If any configured threshold is met, summarization is triggered
+3. **Message Partitioning**: Messages are split into:
+   - Messages to summarize (older messages beyond the `keep` threshold)
+   - Messages to preserve (recent messages within the `keep` threshold)
+4. **Summary Generation**: The model generates a concise summary of the older messages
+5. **Context Replacement**: The message history is updated:
+   - All old messages are removed
+   - A single summary message is added
+   - Recent messages are preserved
+6. **AI/Tool Pair Protection**: The system ensures AI messages and their corresponding tool messages stay together
+
+### Token Counting
+
+- Uses approximate token counting based on character count
+- For Anthropic models: ~3.3 characters per token
+- For other models: Uses LangChain's default estimation
+- Can be customized with a custom `token_counter` function
+
+### Message Preservation
+
+The middleware intelligently preserves message context:
+
+- **Recent Messages**: Always kept intact based on `keep` configuration
+- **AI/Tool Pairs**: Never split - if a cutoff point falls within tool messages, the system adjusts to keep the entire AI + Tool message sequence together
+- **Summary Format**: Summary is injected as a HumanMessage with the format:
+  ```
+  Here is a summary of the conversation to date:
+
+  [Generated summary text]
+  ```
+
+## Best Practices
+
+### Choosing Trigger Thresholds
+
+1. **Token-based triggers**: Recommended for most use cases
+   - Set to 60-80% of your model's context window
+   - Example: For 8K context, use 4000-6000 tokens
+
+2. **Message-based triggers**: Useful for controlling conversation length
+   - Good for applications with many short messages
+   - Example: 50-100 messages depending on average message length
+
+3. **Fraction-based triggers**: Ideal when using multiple models
+   - Automatically adapts to each model's capacity
+   - Example: 0.8 (80% of model's max input tokens)
+
+### Choosing Retention Policy (`keep`)
+
+1. **Message-based retention**: Best for most scenarios
+   - Preserves natural conversation flow
+   - Recommended: 15-25 messages
+
+2. **Token-based retention**: Use when precise control is needed
+   - Good for managing exact token budgets
+   - Recommended: 2000-4000 tokens
+
+3. **Fraction-based retention**: For multi-model setups
+   - Automatically scales with model capacity
+   - Recommended: 0.2-0.4 (20-40% of max input)
+
+### Model Selection
+
+- **Recommended**: Use a lightweight, cost-effective model for summaries
+  - Examples: `gpt-4o-mini`, `claude-haiku`, or equivalent
+  - Summaries don't require the most powerful models
+  - Significant cost savings on high-volume applications
+
+- **Default**: If `model_name` is `null`, uses the default model
+  - May be more expensive but ensures consistency
+  - Good for simple setups
+
+### Optimization Tips
+
+1. **Balance triggers**: Combine token and message triggers for robust handling
+   ```yaml
+   trigger:
+     - type: tokens
+       value: 4000
+     - type: messages
+       value: 50
+   ```
+
+2. **Conservative retention**: Keep more messages initially, adjust based on performance
+   ```yaml
+   keep:
+     type: messages
+     value: 25  # Start higher, reduce if needed
+   ```
+
+3. **Trim strategically**: Limit tokens sent to summarization model
+   ```yaml
+   trim_tokens_to_summarize: 4000  # Prevents expensive summarization calls
+   ```
+
+4. **Monitor and iterate**: Track summary quality and adjust configuration
+
+## Troubleshooting
+
+### Summary Quality Issues
+
+**Problem**: Summaries losing important context
+
+**Solutions**:
+1. Increase `keep` value to preserve more messages
+2. Decrease trigger thresholds to summarize earlier
+3. Customize `summary_prompt` to emphasize key information
+4. Use a more capable model for summarization
+
+### Performance Issues
+
+**Problem**: Summarization calls taking too long
+
+**Solutions**:
+1. Use a faster model for summaries (e.g., `gpt-4o-mini`)
+2. Reduce `trim_tokens_to_summarize` to send less context
+3. Increase trigger thresholds to summarize less frequently
+
+### Token Limit Errors
+
+**Problem**: Still hitting token limits despite summarization
+
+**Solutions**:
+1. Lower trigger thresholds to summarize earlier
+2. Reduce `keep` value to preserve fewer messages
+3. Check if individual messages are very large
+4. Consider using fraction-based triggers
+
+## Implementation Details
+
+### Code Structure
+
+- **Configuration**: `src/config/summarization_config.py`
+- **Integration**: `src/agents/lead_agent/agent.py`
+- **Middleware**: Uses `langchain.agents.middleware.SummarizationMiddleware`
+
+### Middleware Order
+
+Summarization runs after ThreadData and Sandbox initialization but before Title and Clarification:
+
+1. ThreadDataMiddleware
+2. SandboxMiddleware
+3. **SummarizationMiddleware** ← Runs here
+4. TitleMiddleware
+5. ClarificationMiddleware
+
+### State Management
+
+- Summarization is stateless - configuration is loaded once at startup
+- Summaries are added as regular messages in the conversation history
+- The checkpointer persists the summarized history automatically
+
+## Example Configurations
+
+### Minimal Configuration
+```yaml
+summarization:
+  enabled: true
+  trigger:
+    type: tokens
+    value: 4000
+  keep:
+    type: messages
+    value: 20
+```
+
+### Production Configuration
+```yaml
+summarization:
+  enabled: true
+  model_name: gpt-4o-mini  # Lightweight model for cost efficiency
+  trigger:
+    - type: tokens
+      value: 6000
+    - type: messages
+      value: 75
+  keep:
+    type: messages
+    value: 25
+  trim_tokens_to_summarize: 5000
+```
+
+### Multi-Model Configuration
+```yaml
+summarization:
+  enabled: true
+  model_name: gpt-4o-mini
+  trigger:
+    type: fraction
+    value: 0.7  # 70% of model's max input
+  keep:
+    type: fraction
+    value: 0.3  # Keep 30% of max input
+  trim_tokens_to_summarize: 4000
+```
+
+### Conservative Configuration (High Quality)
+```yaml
+summarization:
+  enabled: true
+  model_name: gpt-4  # Use full model for high-quality summaries
+  trigger:
+    type: tokens
+    value: 8000
+  keep:
+    type: messages
+    value: 40  # Keep more context
+  trim_tokens_to_summarize: null  # No trimming
+```
+
+## References
+
+- [LangChain Summarization Middleware Documentation](https://docs.langchain.com/oss/python/langchain/middleware/built-in#summarization)
+- [LangChain Source Code](https://github.com/langchain-ai/langchain)

backend/docs/task_tool_improvements.md

@@ -0,0 +1,174 @@
+# Task Tool Improvements
+
+## Overview
+
+The task tool has been improved to eliminate wasteful LLM polling. Previously, when using background tasks, the LLM had to repeatedly call `task_status` to poll for completion, causing unnecessary API requests.
+
+## Changes Made
+
+### 1. Removed `run_in_background` Parameter
+
+The `run_in_background` parameter has been removed from the `task` tool. All subagent tasks now run asynchronously by default, but the tool handles completion automatically.
+
+**Before:**
+```python
+# LLM had to manage polling
+task_id = task(
+    subagent_type="bash",
+    prompt="Run tests",
+    description="Run tests",
+    run_in_background=True
+)
+# Then LLM had to poll repeatedly:
+while True:
+    status = task_status(task_id)
+    if completed:
+        break
+```
+
+**After:**
+```python
+# Tool blocks until complete, polling happens in backend
+result = task(
+    subagent_type="bash",
+    prompt="Run tests",
+    description="Run tests"
+)
+# Result is available immediately after the call returns
+```
+
+### 2. Backend Polling
+
+The `task_tool` now:
+- Starts the subagent task asynchronously
+- Polls for completion in the backend (every 2 seconds)
+- Blocks the tool call until completion
+- Returns the final result directly
+
+This means:
+- ✅ LLM makes only ONE tool call
+- ✅ No wasteful LLM polling requests
+- ✅ Backend handles all status checking
+- ✅ Timeout protection (5 minutes max)
+
+### 3. Removed `task_status` from LLM Tools
+
+The `task_status_tool` is no longer exposed to the LLM. It's kept in the codebase for potential internal/debugging use, but the LLM cannot call it.
+
+### 4. Updated Documentation
+
+- Updated `SUBAGENT_SECTION` in `prompt.py` to remove all references to background tasks and polling
+- Simplified usage examples
+- Made it clear that the tool automatically waits for completion
+
+## Implementation Details
+
+### Polling Logic
+
+Located in `src/tools/builtins/task_tool.py`:
+
+```python
+# Start background execution
+task_id = executor.execute_async(prompt)
+
+# Poll for task completion in backend
+while True:
+    result = get_background_task_result(task_id)
+
+    # Check if task completed or failed
+    if result.status == SubagentStatus.COMPLETED:
+        return f"[Subagent: {subagent_type}]\n\n{result.result}"
+    elif result.status == SubagentStatus.FAILED:
+        return f"[Subagent: {subagent_type}] Task failed: {result.error}"
+
+    # Wait before next poll
+    time.sleep(2)
+
+    # Timeout protection (5 minutes)
+    if poll_count > 150:
+        return "Task timed out after 5 minutes"
+```
+
+### Execution Timeout
+
+In addition to polling timeout, subagent execution now has a built-in timeout mechanism:
+
+**Configuration** (`src/subagents/config.py`):
+```python
+@dataclass
+class SubagentConfig:
+    # ...
+    timeout_seconds: int = 300  # 5 minutes default
+```
+
+**Thread Pool Architecture**:
+
+To avoid nested thread pools and resource waste, we use two dedicated thread pools:
+
+1. **Scheduler Pool** (`_scheduler_pool`):
+   - Max workers: 4
+   - Purpose: Orchestrates background task execution
+   - Runs `run_task()` function that manages task lifecycle
+
+2. **Execution Pool** (`_execution_pool`):
+   - Max workers: 8 (larger to avoid blocking)
+   - Purpose: Actual subagent execution with timeout support
+   - Runs `execute()` method that invokes the agent
+
+**How it works**:
+```python
+# In execute_async():
+_scheduler_pool.submit(run_task)  # Submit orchestration task
+
+# In run_task():
+future = _execution_pool.submit(self.execute, task)  # Submit execution
+exec_result = future.result(timeout=timeout_seconds)  # Wait with timeout
+```
+
+**Benefits**:
+- ✅ Clean separation of concerns (scheduling vs execution)
+- ✅ No nested thread pools
+- ✅ Timeout enforcement at the right level
+- ✅ Better resource utilization
+
+**Two-Level Timeout Protection**:
+1. **Execution Timeout**: Subagent execution itself has a 5-minute timeout (configurable in SubagentConfig)
+2. **Polling Timeout**: Tool polling has a 5-minute timeout (30 polls × 10 seconds)
+
+This ensures that even if subagent execution hangs, the system won't wait indefinitely.
+
+### Benefits
+
+1. **Reduced API Costs**: No more repeated LLM requests for polling
+2. **Simpler UX**: LLM doesn't need to manage polling logic
+3. **Better Reliability**: Backend handles all status checking consistently
+4. **Timeout Protection**: Two-level timeout prevents infinite waiting (execution + polling)
+
+## Testing
+
+To verify the changes work correctly:
+
+1. Start a subagent task that takes a few seconds
+2. Verify the tool call blocks until completion
+3. Verify the result is returned directly
+4. Verify no `task_status` calls are made
+
+Example test scenario:
+```python
+# This should block for ~10 seconds then return result
+result = task(
+    subagent_type="bash",
+    prompt="sleep 10 && echo 'Done'",
+    description="Test task"
+)
+# result should contain "Done"
+```
+
+## Migration Notes
+
+For users/code that previously used `run_in_background=True`:
+- Simply remove the parameter
+- Remove any polling logic
+- The tool will automatically wait for completion
+
+No other changes needed - the API is backward compatible (minus the removed parameter).

backend/langgraph.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://langgra.ph/schema.json",
+  "dependencies": [
+    "."
+  ],
+  "env": ".env",
+  "graphs": {
+    "lead_agent": "src.agents:make_lead_agent"
+  }
+}

backend/pyproject.toml

@@ -0,0 +1,35 @@
+[project]
+name = "deer-flow"
+version = "0.1.0"
+description = "LangGraph-based AI agent system with sandbox execution capabilities"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "agent-sandbox>=0.0.19",
+    "dotenv>=0.9.9",
+    "fastapi>=0.115.0",
+    "httpx>=0.28.0",
+    "kubernetes>=30.0.0",
+    "langchain>=1.2.3",
+    "langchain-deepseek>=1.0.1",
+    "langchain-mcp-adapters>=0.1.0",
+    "langchain-openai>=1.1.7",
+    "langgraph>=1.0.6",
+    "langgraph-cli[inmem]>=0.4.11",
+    "markdownify>=1.2.2",
+    "markitdown[all,xlsx]>=0.0.1a2",
+    "pydantic>=2.12.5",
+    "python-multipart>=0.0.20",
+    "pyyaml>=6.0.3",
+    "readabilipy>=0.3.0",
+    "sse-starlette>=2.1.0",
+    "tavily-python>=0.7.17",
+    "firecrawl-py>=1.15.0",
+    "tiktoken>=0.8.0",
+    "uvicorn[standard]>=0.34.0",
+    "ddgs>=9.10.0",
+    "duckdb>=1.4.4",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.0.0", "ruff>=0.14.11"]

backend/ruff.toml

@@ -0,0 +1,10 @@
+line-length = 240
+target-version = "py312"
+
+[lint]
+select = ["E", "F", "I", "UP"]
+ignore = []
+
+[format]
+quote-style = "double"
+indent-style = "space"

backend/src/agents/__init__.py

@@ -0,0 +1,4 @@
+from .lead_agent import make_lead_agent
+from .thread_state import SandboxState, ThreadState
+
+__all__ = ["make_lead_agent", "SandboxState", "ThreadState"]

backend/src/agents/lead_agent/__init__.py

@@ -0,0 +1,3 @@
+from .agent import make_lead_agent
+
+__all__ = ["make_lead_agent"]

backend/src/agents/lead_agent/agent.py

@@ -0,0 +1,303 @@
+import logging
+
+from langchain.agents import create_agent
+from langchain.agents.middleware import SummarizationMiddleware, TodoListMiddleware
+from langchain_core.runnables import RunnableConfig
+
+from src.agents.lead_agent.prompt import apply_prompt_template
+from src.agents.middlewares.clarification_middleware import ClarificationMiddleware
+from src.agents.middlewares.dangling_tool_call_middleware import DanglingToolCallMiddleware
+from src.agents.middlewares.memory_middleware import MemoryMiddleware
+from src.agents.middlewares.subagent_limit_middleware import SubagentLimitMiddleware
+from src.agents.middlewares.thread_data_middleware import ThreadDataMiddleware
+from src.agents.middlewares.title_middleware import TitleMiddleware
+from src.agents.middlewares.uploads_middleware import UploadsMiddleware
+from src.agents.middlewares.view_image_middleware import ViewImageMiddleware
+from src.agents.thread_state import ThreadState
+from src.config.app_config import get_app_config
+from src.config.summarization_config import get_summarization_config
+from src.models import create_chat_model
+from src.sandbox.middleware import SandboxMiddleware
+
+logger = logging.getLogger(__name__)
+
+
+def _resolve_model_name(requested_model_name: str | None) -> str:
+    """Resolve a runtime model name safely, falling back to default if invalid. Returns None if no models are configured."""
+    app_config = get_app_config()
+    default_model_name = app_config.models[0].name if app_config.models else None
+    if default_model_name is None:
+        raise ValueError(
+            "No chat models are configured. Please configure at least one model in config.yaml."
+        )
+
+    if requested_model_name and app_config.get_model_config(requested_model_name):
+        return requested_model_name
+
+    if requested_model_name and requested_model_name != default_model_name:
+        logger.warning(f"Model '{requested_model_name}' not found in config; fallback to default model '{default_model_name}'.")
+    return default_model_name
+
+
+def _create_summarization_middleware() -> SummarizationMiddleware | None:
+    """Create and configure the summarization middleware from config."""
+    config = get_summarization_config()
+
+    if not config.enabled:
+        return None
+
+    # Prepare trigger parameter
+    trigger = None
+    if config.trigger is not None:
+        if isinstance(config.trigger, list):
+            trigger = [t.to_tuple() for t in config.trigger]
+        else:
+            trigger = config.trigger.to_tuple()
+
+    # Prepare keep parameter
+    keep = config.keep.to_tuple()
+
+    # Prepare model parameter
+    if config.model_name:
+        model = config.model_name
+    else:
+        # Use a lightweight model for summarization to save costs
+        # Falls back to default model if not explicitly specified
+        model = create_chat_model(thinking_enabled=False)
+
+    # Prepare kwargs
+    kwargs = {
+        "model": model,
+        "trigger": trigger,
+        "keep": keep,
+    }
+
+    if config.trim_tokens_to_summarize is not None:
+        kwargs["trim_tokens_to_summarize"] = config.trim_tokens_to_summarize
+
+    if config.summary_prompt is not None:
+        kwargs["summary_prompt"] = config.summary_prompt
+
+    return SummarizationMiddleware(**kwargs)
+
+
+def _create_todo_list_middleware(is_plan_mode: bool) -> TodoListMiddleware | None:
+    """Create and configure the TodoList middleware.
+
+    Args:
+        is_plan_mode: Whether to enable plan mode with TodoList middleware.
+
+    Returns:
+        TodoListMiddleware instance if plan mode is enabled, None otherwise.
+    """
+    if not is_plan_mode:
+        return None
+
+    # Custom prompts matching DeerFlow's style
+    system_prompt = """
+<todo_list_system>
+You have access to the `write_todos` tool to help you manage and track complex multi-step objectives.
+
+**CRITICAL RULES:**
+- Mark todos as completed IMMEDIATELY after finishing each step - do NOT batch completions
+- Keep EXACTLY ONE task as `in_progress` at any time (unless tasks can run in parallel)
+- Update the todo list in REAL-TIME as you work - this gives users visibility into your progress
+- DO NOT use this tool for simple tasks (< 3 steps) - just complete them directly
+
+**When to Use:**
+This tool is designed for complex objectives that require systematic tracking:
+- Complex multi-step tasks requiring 3+ distinct steps
+- Non-trivial tasks needing careful planning and execution
+- User explicitly requests a todo list
+- User provides multiple tasks (numbered or comma-separated list)
+- The plan may need revisions based on intermediate results
+
+**When NOT to Use:**
+- Single, straightforward tasks
+- Trivial tasks (< 3 steps)
+- Purely conversational or informational requests
+- Simple tool calls where the approach is obvious
+
+**Best Practices:**
+- Break down complex tasks into smaller, actionable steps
+- Use clear, descriptive task names
+- Remove tasks that become irrelevant
+- Add new tasks discovered during implementation
+- Don't be afraid to revise the todo list as you learn more
+
+**Task Management:**
+Writing todos takes time and tokens - use it when helpful for managing complex problems, not for simple requests.
+</todo_list_system>
+"""
+
+    tool_description = """Use this tool to create and manage a structured task list for complex work sessions.
+
+**IMPORTANT: Only use this tool for complex tasks (3+ steps). For simple requests, just do the work directly.**
+
+## When to Use
+
+Use this tool in these scenarios:
+1. **Complex multi-step tasks**: When a task requires 3 or more distinct steps or actions
+2. **Non-trivial tasks**: Tasks requiring careful planning or multiple operations
+3. **User explicitly requests todo list**: When the user directly asks you to track tasks
+4. **Multiple tasks**: When users provide a list of things to be done
+5. **Dynamic planning**: When the plan may need updates based on intermediate results
+
+## When NOT to Use
+
+Skip this tool when:
+1. The task is straightforward and takes less than 3 steps
+2. The task is trivial and tracking provides no benefit
+3. The task is purely conversational or informational
+4. It's clear what needs to be done and you can just do it
+
+## How to Use
+
+1. **Starting a task**: Mark it as `in_progress` BEFORE beginning work
+2. **Completing a task**: Mark it as `completed` IMMEDIATELY after finishing
+3. **Updating the list**: Add new tasks, remove irrelevant ones, or update descriptions as needed
+4. **Multiple updates**: You can make several updates at once (e.g., complete one task and start the next)
+
+## Task States
+
+- `pending`: Task not yet started
+- `in_progress`: Currently working on (can have multiple if tasks run in parallel)
+- `completed`: Task finished successfully
+
+## Task Completion Requirements
+
+**CRITICAL: Only mark a task as completed when you have FULLY accomplished it.**
+
+Never mark a task as completed if:
+- There are unresolved issues or errors
+- Work is partial or incomplete
+- You encountered blockers preventing completion
+- You couldn't find necessary resources or dependencies
+- Quality standards haven't been met
+
+If blocked, keep the task as `in_progress` and create a new task describing what needs to be resolved.
+
+## Best Practices
+
+- Create specific, actionable items
+- Break complex tasks into smaller, manageable steps
+- Use clear, descriptive task names
+- Update task status in real-time as you work
+- Mark tasks complete IMMEDIATELY after finishing (don't batch completions)
+- Remove tasks that are no longer relevant
+- **IMPORTANT**: When you write the todo list, mark your first task(s) as `in_progress` immediately
+- **IMPORTANT**: Unless all tasks are completed, always have at least one task `in_progress` to show progress
+
+Being proactive with task management demonstrates thoroughness and ensures all requirements are completed successfully.
+
+**Remember**: If you only need a few tool calls to complete a task and it's clear what to do, it's better to just do the task directly and NOT use this tool at all.
+"""
+
+    return TodoListMiddleware(system_prompt=system_prompt, tool_description=tool_description)
+
+
+# ThreadDataMiddleware must be before SandboxMiddleware to ensure thread_id is available
+# UploadsMiddleware should be after ThreadDataMiddleware to access thread_id
+# DanglingToolCallMiddleware patches missing ToolMessages before model sees the history
+# SummarizationMiddleware should be early to reduce context before other processing
+# TodoListMiddleware should be before ClarificationMiddleware to allow todo management
+# TitleMiddleware generates title after first exchange
+# MemoryMiddleware queues conversation for memory update (after TitleMiddleware)
+# ViewImageMiddleware should be before ClarificationMiddleware to inject image details before LLM
+# ClarificationMiddleware should be last to intercept clarification requests after model calls
+def _build_middlewares(config: RunnableConfig, model_name: str | None):
+    """Build middleware chain based on runtime configuration.
+
+    Args:
+        config: Runtime configuration containing configurable options like is_plan_mode.
+
+    Returns:
+        List of middleware instances.
+    """
+    middlewares = [ThreadDataMiddleware(), UploadsMiddleware(), SandboxMiddleware(), DanglingToolCallMiddleware()]
+
+    # Add summarization middleware if enabled
+    summarization_middleware = _create_summarization_middleware()
+    if summarization_middleware is not None:
+        middlewares.append(summarization_middleware)
+
+    # Add TodoList middleware if plan mode is enabled
+    is_plan_mode = config.get("configurable", {}).get("is_plan_mode", False)
+    todo_list_middleware = _create_todo_list_middleware(is_plan_mode)
+    if todo_list_middleware is not None:
+        middlewares.append(todo_list_middleware)
+
+    # Add TitleMiddleware
+    middlewares.append(TitleMiddleware())
+
+    # Add MemoryMiddleware (after TitleMiddleware)
+    middlewares.append(MemoryMiddleware())
+
+    # Add ViewImageMiddleware only if the current model supports vision.
+    # Use the resolved runtime model_name from make_lead_agent to avoid stale config values.
+    app_config = get_app_config()
+    model_config = app_config.get_model_config(model_name) if model_name else None
+    if model_config is not None and model_config.supports_vision:
+        middlewares.append(ViewImageMiddleware())
+
+    # Add SubagentLimitMiddleware to truncate excess parallel task calls
+    subagent_enabled = config.get("configurable", {}).get("subagent_enabled", False)
+    if subagent_enabled:
+        max_concurrent_subagents = config.get("configurable", {}).get("max_concurrent_subagents", 3)
+        middlewares.append(SubagentLimitMiddleware(max_concurrent=max_concurrent_subagents))
+
+    # ClarificationMiddleware should always be last
+    middlewares.append(ClarificationMiddleware())
+    return middlewares
+
+
+def make_lead_agent(config: RunnableConfig):
+    # Lazy import to avoid circular dependency
+    from src.tools import get_available_tools
+
+    thinking_enabled = config.get("configurable", {}).get("thinking_enabled", True)
+    requested_model_name = config.get("configurable", {}).get("model_name") or config.get("configurable", {}).get("model")
+    model_name = _resolve_model_name(requested_model_name)
+    if model_name is None:
+        raise ValueError(
+            "No chat model could be resolved. Please configure at least one model in "
+            "config.yaml or provide a valid 'model_name'/'model' in the request."
+        )
+    is_plan_mode = config.get("configurable", {}).get("is_plan_mode", False)
+    subagent_enabled = config.get("configurable", {}).get("subagent_enabled", False)
+    max_concurrent_subagents = config.get("configurable", {}).get("max_concurrent_subagents", 3)
+
+    app_config = get_app_config()
+    model_config = app_config.get_model_config(model_name) if model_name else None
+    if thinking_enabled and model_config is not None and not model_config.supports_thinking:
+        logger.warning(f"Thinking mode is enabled but model '{model_name}' does not support it; fallback to non-thinking mode.")
+        thinking_enabled = False
+
+    logger.info(
+        "thinking_enabled: %s, model_name: %s, is_plan_mode: %s, subagent_enabled: %s, max_concurrent_subagents: %s",
+        thinking_enabled,
+        model_name,
+        is_plan_mode,
+        subagent_enabled,
+        max_concurrent_subagents,
+    )
+
+    # Inject run metadata for LangSmith trace tagging
+    if "metadata" not in config:
+        config["metadata"] = {}
+    config["metadata"].update(
+        {
+            "model_name": model_name or "default",
+            "thinking_enabled": thinking_enabled,
+            "is_plan_mode": is_plan_mode,
+            "subagent_enabled": subagent_enabled,
+        }
+    )
+
+    return create_agent(
+        model=create_chat_model(name=model_name, thinking_enabled=thinking_enabled),
+        tools=get_available_tools(model_name=model_name, subagent_enabled=subagent_enabled),
+        middleware=_build_middlewares(config, model_name=model_name),
+        system_prompt=apply_prompt_template(subagent_enabled=subagent_enabled, max_concurrent_subagents=max_concurrent_subagents),
+        state_schema=ThreadState,
+    )

backend/src/agents/lead_agent/prompt.py

@@ -0,0 +1,391 @@
+from datetime import datetime
+
+from src.skills import load_skills
+
+
+def _build_subagent_section(max_concurrent: int) -> str:
+    """Build the subagent system prompt section with dynamic concurrency limit.
+
+    Args:
+        max_concurrent: Maximum number of concurrent subagent calls allowed per response.
+
+    Returns:
+        Formatted subagent section string.
+    """
+    n = max_concurrent
+    return f"""<subagent_system>
+**🚀 SUBAGENT MODE ACTIVE - DECOMPOSE, DELEGATE, SYNTHESIZE**
+
+You are running with subagent capabilities enabled. Your role is to be a **task orchestrator**:
+1. **DECOMPOSE**: Break complex tasks into parallel sub-tasks
+2. **DELEGATE**: Launch multiple subagents simultaneously using parallel `task` calls
+3. **SYNTHESIZE**: Collect and integrate results into a coherent answer
+
+**CORE PRINCIPLE: Complex tasks should be decomposed and distributed across multiple subagents for parallel execution.**
+
+**⛔ HARD CONCURRENCY LIMIT: MAXIMUM {n} `task` CALLS PER RESPONSE. THIS IS NOT OPTIONAL.**
+- Each response, you may include **at most {n}** `task` tool calls. Any excess calls are **silently discarded** by the system — you will lose that work.
+- **Before launching subagents, you MUST count your sub-tasks in your thinking:**
+  - If count ≤ {n}: Launch all in this response.
+  - If count > {n}: **Pick the {n} most important/foundational sub-tasks for this turn.** Save the rest for the next turn.
+- **Multi-batch execution** (for >{n} sub-tasks):
+  - Turn 1: Launch sub-tasks 1-{n} in parallel → wait for results
+  - Turn 2: Launch next batch in parallel → wait for results
+  - ... continue until all sub-tasks are complete
+  - Final turn: Synthesize ALL results into a coherent answer
+- **Example thinking pattern**: "I identified 6 sub-tasks. Since the limit is {n} per turn, I will launch the first {n} now, and the rest in the next turn."
+
+**Available Subagents:**
+- **general-purpose**: For ANY non-trivial task - web research, code exploration, file operations, analysis, etc.
+- **bash**: For command execution (git, build, test, deploy operations)
+
+**Your Orchestration Strategy:**
+
+✅ **DECOMPOSE + PARALLEL EXECUTION (Preferred Approach):**
+
+For complex queries, break them down into focused sub-tasks and execute in parallel batches (max {n} per turn):
+
+**Example 1: "Why is Tencent's stock price declining?" (3 sub-tasks → 1 batch)**
+→ Turn 1: Launch 3 subagents in parallel:
+- Subagent 1: Recent financial reports, earnings data, and revenue trends
+- Subagent 2: Negative news, controversies, and regulatory issues
+- Subagent 3: Industry trends, competitor performance, and market sentiment
+→ Turn 2: Synthesize results
+
+**Example 2: "Compare 5 cloud providers" (5 sub-tasks → multi-batch)**
+→ Turn 1: Launch {n} subagents in parallel (first batch)
+→ Turn 2: Launch remaining subagents in parallel
+→ Final turn: Synthesize ALL results into comprehensive comparison
+
+**Example 3: "Refactor the authentication system"**
+→ Turn 1: Launch 3 subagents in parallel:
+- Subagent 1: Analyze current auth implementation and technical debt
+- Subagent 2: Research best practices and security patterns
+- Subagent 3: Review related tests, documentation, and vulnerabilities
+→ Turn 2: Synthesize results
+
+✅ **USE Parallel Subagents (max {n} per turn) when:**
+- **Complex research questions**: Requires multiple information sources or perspectives
+- **Multi-aspect analysis**: Task has several independent dimensions to explore
+- **Large codebases**: Need to analyze different parts simultaneously
+- **Comprehensive investigations**: Questions requiring thorough coverage from multiple angles
+
+❌ **DO NOT use subagents (execute directly) when:**
+- **Task cannot be decomposed**: If you can't break it into 2+ meaningful parallel sub-tasks, execute directly
+- **Ultra-simple actions**: Read one file, quick edits, single commands
+- **Need immediate clarification**: Must ask user before proceeding
+- **Meta conversation**: Questions about conversation history
+- **Sequential dependencies**: Each step depends on previous results (do steps yourself sequentially)
+
+**CRITICAL WORKFLOW** (STRICTLY follow this before EVERY action):
+1. **COUNT**: In your thinking, list all sub-tasks and count them explicitly: "I have N sub-tasks"
+2. **PLAN BATCHES**: If N > {n}, explicitly plan which sub-tasks go in which batch:
+   - "Batch 1 (this turn): first {n} sub-tasks"
+   - "Batch 2 (next turn): next batch of sub-tasks"
+3. **EXECUTE**: Launch ONLY the current batch (max {n} `task` calls). Do NOT launch sub-tasks from future batches.
+4. **REPEAT**: After results return, launch the next batch. Continue until all batches complete.
+5. **SYNTHESIZE**: After ALL batches are done, synthesize all results.
+6. **Cannot decompose** → Execute directly using available tools (bash, read_file, web_search, etc.)
+
+**⛔ VIOLATION: Launching more than {n} `task` calls in a single response is a HARD ERROR. The system WILL discard excess calls and you WILL lose work. Always batch.**
+
+**Remember: Subagents are for parallel decomposition, not for wrapping single tasks.**
+
+**How It Works:**
+- The task tool runs subagents asynchronously in the background
+- The backend automatically polls for completion (you don't need to poll)
+- The tool call will block until the subagent completes its work
+- Once complete, the result is returned to you directly
+
+**Usage Example 1 - Single Batch (≤{n} sub-tasks):**
+
+```python
+# User asks: "Why is Tencent's stock price declining?"
+# Thinking: 3 sub-tasks → fits in 1 batch
+
+# Turn 1: Launch 3 subagents in parallel
+task(description="Tencent financial data", prompt="...", subagent_type="general-purpose")
+task(description="Tencent news & regulation", prompt="...", subagent_type="general-purpose")
+task(description="Industry & market trends", prompt="...", subagent_type="general-purpose")
+# All 3 run in parallel → synthesize results
+```
+
+**Usage Example 2 - Multiple Batches (>{n} sub-tasks):**
+
+```python
+# User asks: "Compare AWS, Azure, GCP, Alibaba Cloud, and Oracle Cloud"
+# Thinking: 5 sub-tasks → need multiple batches (max {n} per batch)
+
+# Turn 1: Launch first batch of {n}
+task(description="AWS analysis", prompt="...", subagent_type="general-purpose")
+task(description="Azure analysis", prompt="...", subagent_type="general-purpose")
+task(description="GCP analysis", prompt="...", subagent_type="general-purpose")
+
+# Turn 2: Launch remaining batch (after first batch completes)
+task(description="Alibaba Cloud analysis", prompt="...", subagent_type="general-purpose")
+task(description="Oracle Cloud analysis", prompt="...", subagent_type="general-purpose")
+
+# Turn 3: Synthesize ALL results from both batches
+```
+
+**Counter-Example - Direct Execution (NO subagents):**
+
+```python
+# User asks: "Run the tests"
+# Thinking: Cannot decompose into parallel sub-tasks
+# → Execute directly
+
+bash("npm test")  # Direct execution, not task()
+```
+
+**CRITICAL**:
+- **Max {n} `task` calls per turn** - the system enforces this, excess calls are discarded
+- Only use `task` when you can launch 2+ subagents in parallel
+- Single task = No value from subagents = Execute directly
+- For >{n} sub-tasks, use sequential batches of {n} across multiple turns
+</subagent_system>"""
+
+
+SYSTEM_PROMPT_TEMPLATE = """
+<role>
+You are DeerFlow 2.0, an open-source super agent.
+</role>
+
+{memory_context}
+
+<thinking_style>
+- Think concisely and strategically about the user's request BEFORE taking action
+- Break down the task: What is clear? What is ambiguous? What is missing?
+- **PRIORITY CHECK: If anything is unclear, missing, or has multiple interpretations, you MUST ask for clarification FIRST - do NOT proceed with work**
+{subagent_thinking}- Never write down your full final answer or report in thinking process, but only outline
+- CRITICAL: After thinking, you MUST provide your actual response to the user. Thinking is for planning, the response is for delivery.
+- Your response must contain the actual answer, not just a reference to what you thought about
+</thinking_style>
+
+<clarification_system>
+**WORKFLOW PRIORITY: CLARIFY → PLAN → ACT**
+1. **FIRST**: Analyze the request in your thinking - identify what's unclear, missing, or ambiguous
+2. **SECOND**: If clarification is needed, call `ask_clarification` tool IMMEDIATELY - do NOT start working
+3. **THIRD**: Only after all clarifications are resolved, proceed with planning and execution
+
+**CRITICAL RULE: Clarification ALWAYS comes BEFORE action. Never start working and clarify mid-execution.**
+
+**MANDATORY Clarification Scenarios - You MUST call ask_clarification BEFORE starting work when:**
+
+1. **Missing Information** (`missing_info`): Required details not provided
+   - Example: User says "create a web scraper" but doesn't specify the target website
+   - Example: "Deploy the app" without specifying environment
+   - **REQUIRED ACTION**: Call ask_clarification to get the missing information
+
+2. **Ambiguous Requirements** (`ambiguous_requirement`): Multiple valid interpretations exist
+   - Example: "Optimize the code" could mean performance, readability, or memory usage
+   - Example: "Make it better" is unclear what aspect to improve
+   - **REQUIRED ACTION**: Call ask_clarification to clarify the exact requirement
+
+3. **Approach Choices** (`approach_choice`): Several valid approaches exist
+   - Example: "Add authentication" could use JWT, OAuth, session-based, or API keys
+   - Example: "Store data" could use database, files, cache, etc.
+   - **REQUIRED ACTION**: Call ask_clarification to let user choose the approach
+
+4. **Risky Operations** (`risk_confirmation`): Destructive actions need confirmation
+   - Example: Deleting files, modifying production configs, database operations
+   - Example: Overwriting existing code or data
+   - **REQUIRED ACTION**: Call ask_clarification to get explicit confirmation
+
+5. **Suggestions** (`suggestion`): You have a recommendation but want approval
+   - Example: "I recommend refactoring this code. Should I proceed?"
+   - **REQUIRED ACTION**: Call ask_clarification to get approval
+
+**STRICT ENFORCEMENT:**
+- ❌ DO NOT start working and then ask for clarification mid-execution - clarify FIRST
+- ❌ DO NOT skip clarification for "efficiency" - accuracy matters more than speed
+- ❌ DO NOT make assumptions when information is missing - ALWAYS ask
+- ❌ DO NOT proceed with guesses - STOP and call ask_clarification first
+- ✅ Analyze the request in thinking → Identify unclear aspects → Ask BEFORE any action
+- ✅ If you identify the need for clarification in your thinking, you MUST call the tool IMMEDIATELY
+- ✅ After calling ask_clarification, execution will be interrupted automatically
+- ✅ Wait for user response - do NOT continue with assumptions
+
+**How to Use:**
+```python
+ask_clarification(
+    question="Your specific question here?",
+    clarification_type="missing_info",  # or other type
+    context="Why you need this information",  # optional but recommended
+    options=["option1", "option2"]  # optional, for choices
+)
+```
+
+**Example:**
+User: "Deploy the application"
+You (thinking): Missing environment info - I MUST ask for clarification
+You (action): ask_clarification(
+    question="Which environment should I deploy to?",
+    clarification_type="approach_choice",
+    context="I need to know the target environment for proper configuration",
+    options=["development", "staging", "production"]
+)
+[Execution stops - wait for user response]
+
+User: "staging"
+You: "Deploying to staging..." [proceed]
+</clarification_system>
+
+{skills_section}
+
+{subagent_section}
+
+<working_directory existed="true">
+- User uploads: `/mnt/user-data/uploads` - Files uploaded by the user (automatically listed in context)
+- User workspace: `/mnt/user-data/workspace` - Working directory for temporary files
+- Output files: `/mnt/user-data/outputs` - Final deliverables must be saved here
+
+**File Management:**
+- Uploaded files are automatically listed in the <uploaded_files> section before each request
+- Use `read_file` tool to read uploaded files using their paths from the list
+- For PDF, PPT, Excel, and Word files, converted Markdown versions (*.md) are available alongside originals
+- All temporary work happens in `/mnt/user-data/workspace`
+- Final deliverables must be copied to `/mnt/user-data/outputs` and presented using `present_file` tool
+</working_directory>
+
+<response_style>
+- Clear and Concise: Avoid over-formatting unless requested
+- Natural Tone: Use paragraphs and prose, not bullet points by default
+- Action-Oriented: Focus on delivering results, not explaining processes
+</response_style>
+
+<citations>
+- When to Use: After web_search, include citations if applicable
+- Format: Use Markdown link format `[citation:TITLE](URL)`
+- Example: 
+```markdown
+The key AI trends for 2026 include enhanced reasoning capabilities and multimodal integration
+[citation:AI Trends 2026](https://techcrunch.com/ai-trends).
+Recent breakthroughs in language models have also accelerated progress
+[citation:OpenAI Research](https://openai.com/research).
+```
+</citations>
+
+<critical_reminders>
+- **Clarification First**: ALWAYS clarify unclear/missing/ambiguous requirements BEFORE starting work - never assume or guess
+{subagent_reminder}- Skill First: Always load the relevant skill before starting **complex** tasks.
+- Progressive Loading: Load resources incrementally as referenced in skills
+- Output Files: Final deliverables must be in `/mnt/user-data/outputs`
+- Clarity: Be direct and helpful, avoid unnecessary meta-commentary
+- Including Images and Mermaid: Images and Mermaid diagrams are always welcomed in the Markdown format, and you're encouraged to use `![Image Description](image_path)\n\n` or "```mermaid" to display images in response or Markdown files
+- Multi-task: Better utilize parallel tool calling to call multiple tools at one time for better performance
+- Language Consistency: Keep using the same language as user's
+- Always Respond: Your thinking is internal. You MUST always provide a visible response to the user after thinking.
+</critical_reminders>
+"""
+
+
+def _get_memory_context() -> str:
+    """Get memory context for injection into system prompt.
+
+    Returns:
+        Formatted memory context string wrapped in XML tags, or empty string if disabled.
+    """
+    try:
+        from src.agents.memory import format_memory_for_injection, get_memory_data
+        from src.config.memory_config import get_memory_config
+
+        config = get_memory_config()
+        if not config.enabled or not config.injection_enabled:
+            return ""
+
+        memory_data = get_memory_data()
+        memory_content = format_memory_for_injection(memory_data, max_tokens=config.max_injection_tokens)
+
+        if not memory_content.strip():
+            return ""
+
+        return f"""<memory>
+{memory_content}
+</memory>
+"""
+    except Exception as e:
+        print(f"Failed to load memory context: {e}")
+        return ""
+
+
+def get_skills_prompt_section() -> str:
+    """Generate the skills prompt section with available skills list.
+
+    Returns the <skill_system>...</skill_system> block listing all enabled skills,
+    suitable for injection into any agent's system prompt.
+    """
+    skills = load_skills(enabled_only=True)
+
+    try:
+        from src.config import get_app_config
+
+        config = get_app_config()
+        container_base_path = config.skills.container_path
+    except Exception:
+        container_base_path = "/mnt/skills"
+
+    if not skills:
+        return ""
+
+    skill_items = "\n".join(
+        f"    <skill>\n        <name>{skill.name}</name>\n        <description>{skill.description}</description>\n        <location>{skill.get_container_file_path(container_base_path)}</location>\n    </skill>" for skill in skills
+    )
+    skills_list = f"<available_skills>\n{skill_items}\n</available_skills>"
+
+    return f"""<skill_system>
+You have access to skills that provide optimized workflows for specific tasks. Each skill contains best practices, frameworks, and references to additional resources.
+
+**Progressive Loading Pattern:**
+1. When a user query matches a skill's use case, immediately call `read_file` on the skill's main file using the path attribute provided in the skill tag below
+2. Read and understand the skill's workflow and instructions
+3. The skill file contains references to external resources under the same folder
+4. Load referenced resources only when needed during execution
+5. Follow the skill's instructions precisely
+
+**Skills are located at:** {container_base_path}
+
+{skills_list}
+
+</skill_system>"""
+
+
+def apply_prompt_template(subagent_enabled: bool = False, max_concurrent_subagents: int = 3) -> str:
+    # Get memory context
+    memory_context = _get_memory_context()
+
+    # Include subagent section only if enabled (from runtime parameter)
+    n = max_concurrent_subagents
+    subagent_section = _build_subagent_section(n) if subagent_enabled else ""
+
+    # Add subagent reminder to critical_reminders if enabled
+    subagent_reminder = (
+        "- **Orchestrator Mode**: You are a task orchestrator - decompose complex tasks into parallel sub-tasks. "
+        f"**HARD LIMIT: max {n} `task` calls per response.** "
+        f"If >{n} sub-tasks, split into sequential batches of ≤{n}. Synthesize after ALL batches complete.\n"
+        if subagent_enabled
+        else ""
+    )
+
+    # Add subagent thinking guidance if enabled
+    subagent_thinking = (
+        "- **DECOMPOSITION CHECK: Can this task be broken into 2+ parallel sub-tasks? If YES, COUNT them. "
+        f"If count > {n}, you MUST plan batches of ≤{n} and only launch the FIRST batch now. "
+        f"NEVER launch more than {n} `task` calls in one response.**\n"
+        if subagent_enabled
+        else ""
+    )
+
+    # Get skills section
+    skills_section = get_skills_prompt_section()
+
+    # Format the prompt with dynamic skills and memory
+    prompt = SYSTEM_PROMPT_TEMPLATE.format(
+        skills_section=skills_section,
+        memory_context=memory_context,
+        subagent_section=subagent_section,
+        subagent_reminder=subagent_reminder,
+        subagent_thinking=subagent_thinking,
+    )
+
+    return prompt + f"\n<current_date>{datetime.now().strftime('%Y-%m-%d, %A')}</current_date>"

backend/src/agents/memory/__init__.py

@@ -0,0 +1,44 @@
+"""Memory module for DeerFlow.
+
+This module provides a global memory mechanism that:
+- Stores user context and conversation history in memory.json
+- Uses LLM to summarize and extract facts from conversations
+- Injects relevant memory into system prompts for personalized responses
+"""
+
+from src.agents.memory.prompt import (
+    FACT_EXTRACTION_PROMPT,
+    MEMORY_UPDATE_PROMPT,
+    format_conversation_for_update,
+    format_memory_for_injection,
+)
+from src.agents.memory.queue import (
+    ConversationContext,
+    MemoryUpdateQueue,
+    get_memory_queue,
+    reset_memory_queue,
+)
+from src.agents.memory.updater import (
+    MemoryUpdater,
+    get_memory_data,
+    reload_memory_data,
+    update_memory_from_conversation,
+)
+
+__all__ = [
+    # Prompt utilities
+    "MEMORY_UPDATE_PROMPT",
+    "FACT_EXTRACTION_PROMPT",
+    "format_memory_for_injection",
+    "format_conversation_for_update",
+    # Queue
+    "ConversationContext",
+    "MemoryUpdateQueue",
+    "get_memory_queue",
+    "reset_memory_queue",
+    # Updater
+    "MemoryUpdater",
+    "get_memory_data",
+    "reload_memory_data",
+    "update_memory_from_conversation",
+]

backend/src/agents/memory/prompt.py

@@ -0,0 +1,261 @@
+"""Prompt templates for memory update and injection."""
+
+from typing import Any
+
+try:
+    import tiktoken
+
+    TIKTOKEN_AVAILABLE = True
+except ImportError:
+    TIKTOKEN_AVAILABLE = False
+
+# Prompt template for updating memory based on conversation
+MEMORY_UPDATE_PROMPT = """You are a memory management system. Your task is to analyze a conversation and update the user's memory profile.
+
+Current Memory State:
+<current_memory>
+{current_memory}
+</current_memory>
+
+New Conversation to Process:
+<conversation>
+{conversation}
+</conversation>
+
+Instructions:
+1. Analyze the conversation for important information about the user
+2. Extract relevant facts, preferences, and context with specific details (numbers, names, technologies)
+3. Update the memory sections as needed following the detailed length guidelines below
+
+Memory Section Guidelines:
+
+**User Context** (Current state - concise summaries):
+- workContext: Professional role, company, key projects, main technologies (2-3 sentences)
+  Example: Core contributor, project names with metrics (16k+ stars), technical stack
+- personalContext: Languages, communication preferences, key interests (1-2 sentences)
+  Example: Bilingual capabilities, specific interest areas, expertise domains
+- topOfMind: Multiple ongoing focus areas and priorities (3-5 sentences, detailed paragraph)
+  Example: Primary project work, parallel technical investigations, ongoing learning/tracking
+  Include: Active implementation work, troubleshooting issues, market/research interests
+  Note: This captures SEVERAL concurrent focus areas, not just one task
+
+**History** (Temporal context - rich paragraphs):
+- recentMonths: Detailed summary of recent activities (4-6 sentences or 1-2 paragraphs)
+  Timeline: Last 1-3 months of interactions
+  Include: Technologies explored, projects worked on, problems solved, interests demonstrated
+- earlierContext: Important historical patterns (3-5 sentences or 1 paragraph)
+  Timeline: 3-12 months ago
+  Include: Past projects, learning journeys, established patterns
+- longTermBackground: Persistent background and foundational context (2-4 sentences)
+  Timeline: Overall/foundational information
+  Include: Core expertise, longstanding interests, fundamental working style
+
+**Facts Extraction**:
+- Extract specific, quantifiable details (e.g., "16k+ GitHub stars", "200+ datasets")
+- Include proper nouns (company names, project names, technology names)
+- Preserve technical terminology and version numbers
+- Categories:
+  * preference: Tools, styles, approaches user prefers/dislikes
+  * knowledge: Specific expertise, technologies mastered, domain knowledge
+  * context: Background facts (job title, projects, locations, languages)
+  * behavior: Working patterns, communication habits, problem-solving approaches
+  * goal: Stated objectives, learning targets, project ambitions
+- Confidence levels:
+  * 0.9-1.0: Explicitly stated facts ("I work on X", "My role is Y")
+  * 0.7-0.8: Strongly implied from actions/discussions
+  * 0.5-0.6: Inferred patterns (use sparingly, only for clear patterns)
+
+**What Goes Where**:
+- workContext: Current job, active projects, primary tech stack
+- personalContext: Languages, personality, interests outside direct work tasks
+- topOfMind: Multiple ongoing priorities and focus areas user cares about recently (gets updated most frequently)
+  Should capture 3-5 concurrent themes: main work, side explorations, learning/tracking interests
+- recentMonths: Detailed account of recent technical explorations and work
+- earlierContext: Patterns from slightly older interactions still relevant
+- longTermBackground: Unchanging foundational facts about the user
+
+**Multilingual Content**:
+- Preserve original language for proper nouns and company names
+- Keep technical terms in their original form (DeepSeek, LangGraph, etc.)
+- Note language capabilities in personalContext
+
+Output Format (JSON):
+{{
+  "user": {{
+    "workContext": {{ "summary": "...", "shouldUpdate": true/false }},
+    "personalContext": {{ "summary": "...", "shouldUpdate": true/false }},
+    "topOfMind": {{ "summary": "...", "shouldUpdate": true/false }}
+  }},
+  "history": {{
+    "recentMonths": {{ "summary": "...", "shouldUpdate": true/false }},
+    "earlierContext": {{ "summary": "...", "shouldUpdate": true/false }},
+    "longTermBackground": {{ "summary": "...", "shouldUpdate": true/false }}
+  }},
+  "newFacts": [
+    {{ "content": "...", "category": "preference|knowledge|context|behavior|goal", "confidence": 0.0-1.0 }}
+  ],
+  "factsToRemove": ["fact_id_1", "fact_id_2"]
+}}
+
+Important Rules:
+- Only set shouldUpdate=true if there's meaningful new information
+- Follow length guidelines: workContext/personalContext are concise (1-3 sentences), topOfMind and history sections are detailed (paragraphs)
+- Include specific metrics, version numbers, and proper nouns in facts
+- Only add facts that are clearly stated (0.9+) or strongly implied (0.7+)
+- Remove facts that are contradicted by new information
+- When updating topOfMind, integrate new focus areas while removing completed/abandoned ones
+  Keep 3-5 concurrent focus themes that are still active and relevant
+- For history sections, integrate new information chronologically into appropriate time period
+- Preserve technical accuracy - keep exact names of technologies, companies, projects
+- Focus on information useful for future interactions and personalization
+
+Return ONLY valid JSON, no explanation or markdown."""
+
+
+# Prompt template for extracting facts from a single message
+FACT_EXTRACTION_PROMPT = """Extract factual information about the user from this message.
+
+Message:
+{message}
+
+Extract facts in this JSON format:
+{{
+  "facts": [
+    {{ "content": "...", "category": "preference|knowledge|context|behavior|goal", "confidence": 0.0-1.0 }}
+  ]
+}}
+
+Categories:
+- preference: User preferences (likes/dislikes, styles, tools)
+- knowledge: User's expertise or knowledge areas
+- context: Background context (location, job, projects)
+- behavior: Behavioral patterns
+- goal: User's goals or objectives
+
+Rules:
+- Only extract clear, specific facts
+- Confidence should reflect certainty (explicit statement = 0.9+, implied = 0.6-0.8)
+- Skip vague or temporary information
+
+Return ONLY valid JSON."""
+
+
+def _count_tokens(text: str, encoding_name: str = "cl100k_base") -> int:
+    """Count tokens in text using tiktoken.
+
+    Args:
+        text: The text to count tokens for.
+        encoding_name: The encoding to use (default: cl100k_base for GPT-4/3.5).
+
+    Returns:
+        The number of tokens in the text.
+    """
+    if not TIKTOKEN_AVAILABLE:
+        # Fallback to character-based estimation if tiktoken is not available
+        return len(text) // 4
+
+    try:
+        encoding = tiktoken.get_encoding(encoding_name)
+        return len(encoding.encode(text))
+    except Exception:
+        # Fallback to character-based estimation on error
+        return len(text) // 4
+
+
+def format_memory_for_injection(memory_data: dict[str, Any], max_tokens: int = 2000) -> str:
+    """Format memory data for injection into system prompt.
+
+    Args:
+        memory_data: The memory data dictionary.
+        max_tokens: Maximum tokens to use (counted via tiktoken for accuracy).
+
+    Returns:
+        Formatted memory string for system prompt injection.
+    """
+    if not memory_data:
+        return ""
+
+    sections = []
+
+    # Format user context
+    user_data = memory_data.get("user", {})
+    if user_data:
+        user_sections = []
+
+        work_ctx = user_data.get("workContext", {})
+        if work_ctx.get("summary"):
+            user_sections.append(f"Work: {work_ctx['summary']}")
+
+        personal_ctx = user_data.get("personalContext", {})
+        if personal_ctx.get("summary"):
+            user_sections.append(f"Personal: {personal_ctx['summary']}")
+
+        top_of_mind = user_data.get("topOfMind", {})
+        if top_of_mind.get("summary"):
+            user_sections.append(f"Current Focus: {top_of_mind['summary']}")
+
+        if user_sections:
+            sections.append("User Context:\n" + "\n".join(f"- {s}" for s in user_sections))
+
+    # Format history
+    history_data = memory_data.get("history", {})
+    if history_data:
+        history_sections = []
+
+        recent = history_data.get("recentMonths", {})
+        if recent.get("summary"):
+            history_sections.append(f"Recent: {recent['summary']}")
+
+        earlier = history_data.get("earlierContext", {})
+        if earlier.get("summary"):
+            history_sections.append(f"Earlier: {earlier['summary']}")
+
+        if history_sections:
+            sections.append("History:\n" + "\n".join(f"- {s}" for s in history_sections))
+
+    if not sections:
+        return ""
+
+    result = "\n\n".join(sections)
+
+    # Use accurate token counting with tiktoken
+    token_count = _count_tokens(result)
+    if token_count > max_tokens:
+        # Truncate to fit within token limit
+        # Estimate characters to remove based on token ratio
+        char_per_token = len(result) / token_count
+        target_chars = int(max_tokens * char_per_token * 0.95)  # 95% to leave margin
+        result = result[:target_chars] + "\n..."
+
+    return result
+
+
+def format_conversation_for_update(messages: list[Any]) -> str:
+    """Format conversation messages for memory update prompt.
+
+    Args:
+        messages: List of conversation messages.
+
+    Returns:
+        Formatted conversation string.
+    """
+    lines = []
+    for msg in messages:
+        role = getattr(msg, "type", "unknown")
+        content = getattr(msg, "content", str(msg))
+
+        # Handle content that might be a list (multimodal)
+        if isinstance(content, list):
+            text_parts = [p.get("text", "") for p in content if isinstance(p, dict) and "text" in p]
+            content = " ".join(text_parts) if text_parts else str(content)
+
+        # Truncate very long messages
+        if len(str(content)) > 1000:
+            content = str(content)[:1000] + "..."
+
+        if role == "human":
+            lines.append(f"User: {content}")
+        elif role == "ai":
+            lines.append(f"Assistant: {content}")
+
+    return "\n\n".join(lines)

backend/src/agents/memory/queue.py

@@ -0,0 +1,191 @@
+"""Memory update queue with debounce mechanism."""
+
+import threading
+import time
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+from src.config.memory_config import get_memory_config
+
+
+@dataclass
+class ConversationContext:
+    """Context for a conversation to be processed for memory update."""
+
+    thread_id: str
+    messages: list[Any]
+    timestamp: datetime = field(default_factory=datetime.utcnow)
+
+
+class MemoryUpdateQueue:
+    """Queue for memory updates with debounce mechanism.
+
+    This queue collects conversation contexts and processes them after
+    a configurable debounce period. Multiple conversations received within
+    the debounce window are batched together.
+    """
+
+    def __init__(self):
+        """Initialize the memory update queue."""
+        self._queue: list[ConversationContext] = []
+        self._lock = threading.Lock()
+        self._timer: threading.Timer | None = None
+        self._processing = False
+
+    def add(self, thread_id: str, messages: list[Any]) -> None:
+        """Add a conversation to the update queue.
+
+        Args:
+            thread_id: The thread ID.
+            messages: The conversation messages.
+        """
+        config = get_memory_config()
+        if not config.enabled:
+            return
+
+        context = ConversationContext(
+            thread_id=thread_id,
+            messages=messages,
+        )
+
+        with self._lock:
+            # Check if this thread already has a pending update
+            # If so, replace it with the newer one
+            self._queue = [c for c in self._queue if c.thread_id != thread_id]
+            self._queue.append(context)
+
+            # Reset or start the debounce timer
+            self._reset_timer()
+
+        print(f"Memory update queued for thread {thread_id}, queue size: {len(self._queue)}")
+
+    def _reset_timer(self) -> None:
+        """Reset the debounce timer."""
+        config = get_memory_config()
+
+        # Cancel existing timer if any
+        if self._timer is not None:
+            self._timer.cancel()
+
+        # Start new timer
+        self._timer = threading.Timer(
+            config.debounce_seconds,
+            self._process_queue,
+        )
+        self._timer.daemon = True
+        self._timer.start()
+
+        print(f"Memory update timer set for {config.debounce_seconds}s")
+
+    def _process_queue(self) -> None:
+        """Process all queued conversation contexts."""
+        # Import here to avoid circular dependency
+        from src.agents.memory.updater import MemoryUpdater
+
+        with self._lock:
+            if self._processing:
+                # Already processing, reschedule
+                self._reset_timer()
+                return
+
+            if not self._queue:
+                return
+
+            self._processing = True
+            contexts_to_process = self._queue.copy()
+            self._queue.clear()
+            self._timer = None
+
+        print(f"Processing {len(contexts_to_process)} queued memory updates")
+
+        try:
+            updater = MemoryUpdater()
+
+            for context in contexts_to_process:
+                try:
+                    print(f"Updating memory for thread {context.thread_id}")
+                    success = updater.update_memory(
+                        messages=context.messages,
+                        thread_id=context.thread_id,
+                    )
+                    if success:
+                        print(f"Memory updated successfully for thread {context.thread_id}")
+                    else:
+                        print(f"Memory update skipped/failed for thread {context.thread_id}")
+                except Exception as e:
+                    print(f"Error updating memory for thread {context.thread_id}: {e}")
+
+                # Small delay between updates to avoid rate limiting
+                if len(contexts_to_process) > 1:
+                    time.sleep(0.5)
+
+        finally:
+            with self._lock:
+                self._processing = False
+
+    def flush(self) -> None:
+        """Force immediate processing of the queue.
+
+        This is useful for testing or graceful shutdown.
+        """
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+
+        self._process_queue()
+
+    def clear(self) -> None:
+        """Clear the queue without processing.
+
+        This is useful for testing.
+        """
+        with self._lock:
+            if self._timer is not None:
+                self._timer.cancel()
+                self._timer = None
+            self._queue.clear()
+            self._processing = False
+
+    @property
+    def pending_count(self) -> int:
+        """Get the number of pending updates."""
+        with self._lock:
+            return len(self._queue)
+
+    @property
+    def is_processing(self) -> bool:
+        """Check if the queue is currently being processed."""
+        with self._lock:
+            return self._processing
+
+
+# Global singleton instance
+_memory_queue: MemoryUpdateQueue | None = None
+_queue_lock = threading.Lock()
+
+
+def get_memory_queue() -> MemoryUpdateQueue:
+    """Get the global memory update queue singleton.
+
+    Returns:
+        The memory update queue instance.
+    """
+    global _memory_queue
+    with _queue_lock:
+        if _memory_queue is None:
+            _memory_queue = MemoryUpdateQueue()
+        return _memory_queue
+
+
+def reset_memory_queue() -> None:
+    """Reset the global memory queue.
+
+    This is useful for testing.
+    """
+    global _memory_queue
+    with _queue_lock:
+        if _memory_queue is not None:
+            _memory_queue.clear()
+        _memory_queue = None