Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 fengxiangdebaozi
|
cb2edeadb4 | ||
|
董宏凯
|
309c864096 | ||
|
董宏凯
|
7a5753b3ed | ||
|
董宏凯
|
3e8b9cf2d9 | ||
|
董宏凯
|
d23d871878 | ||
|
吉鑫升
|
3f2aefdcd8 |
No files matched your search
Generated
+10
@@ -0,0 +1,10 @@
|
||||
# 默认忽略的文件
|
||||
/shelf/
|
||||
/workspace.xml
|
||||
# 基于编辑器的 HTTP 客户端请求
|
||||
/httpRequests/
|
||||
# 已忽略包含查询文件的默认文件夹
|
||||
/queries/
|
||||
# Datasource local storage ignored files
|
||||
/dataSources/
|
||||
/dataSources.local.xml
|
||||
Generated
+8
@@ -0,0 +1,8 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<module type="WEB_MODULE" version="4">
|
||||
<component name="NewModuleRootManager">
|
||||
<content url="file://$MODULE_DIR$" />
|
||||
<orderEntry type="inheritedJdk" />
|
||||
<orderEntry type="sourceFolder" forTests="false" />
|
||||
</component>
|
||||
</module>
|
||||
Generated
+8
@@ -0,0 +1,8 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="ProjectModuleManager">
|
||||
<modules>
|
||||
<module fileurl="file://$PROJECT_DIR$/.idea/deerflow-server-master.iml" filepath="$PROJECT_DIR$/.idea/deerflow-server-master.iml" />
|
||||
</modules>
|
||||
</component>
|
||||
</project>
|
||||
Generated
+6
@@ -0,0 +1,6 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="PrettierConfiguration">
|
||||
<option name="myConfigurationMode" value="AUTOMATIC" />
|
||||
</component>
|
||||
</project>
|
||||
Generated
+6
@@ -0,0 +1,6 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project version="4">
|
||||
<component name="VcsDirectoryMappings">
|
||||
<mapping directory="" vcs="Git" />
|
||||
</component>
|
||||
</project>
|
||||
@@ -0,0 +1,672 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## Project Overview
|
||||
|
||||
DeerFlow is a full-stack AI agent system combining:
|
||||
- **Frontend**: React/Vite web interface for interactive agent conversations
|
||||
- **Backend**: LangGraph-based agent runtime with sandbox execution, persistent memory, and subagent delegation
|
||||
|
||||
This is a monorepo with frontend and backend components running in parallel.
|
||||
|
||||
---
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
┌────────────────────────────────────────────────────────┐
|
||||
│ DeerFlow Application │
|
||||
├────────────────────────────────────────────────────────┤
|
||||
│ Nginx (Port 2026) │
|
||||
│ (Unified reverse proxy) │
|
||||
└─────────────────┬──────────────────┬──────────────────┘
|
||||
│ │
|
||||
/api/langgraph/* (Gateway) / (Frontend + /api/*)
|
||||
│ │
|
||||
┌──────▼──────────┐ ┌─────────▼────────────┐
|
||||
│ Gateway API │ │ Frontend Web UI │
|
||||
│ (Port 8001) │ │ (Port 3000) │
|
||||
│ │ │ │
|
||||
│ - LangGraph │ │ - React 19 + Vite │
|
||||
│ - FastAPI │ │ - TypeScript │
|
||||
│ - Tools │ │ - Tailwind CSS │
|
||||
│ - Memory │ │ │
|
||||
└─────────────────┘ └──────────────────────┘
|
||||
│
|
||||
┌───────▼──────────────────┐
|
||||
│ Agent Runtime (LangGraph)│
|
||||
│ ┌──────────────────────┐ │
|
||||
│ │ Lead Agent │ │
|
||||
│ │ ┌────────────────┐ │ │
|
||||
│ │ │ Middlewares │ │ │
|
||||
│ │ │ (10 total) │ │ │
|
||||
│ │ └────────────────┘ │ │
|
||||
│ │ ┌────────────────┐ │ │
|
||||
│ │ │ Tools │ │ │
|
||||
│ │ │ - Sandbox │ │ │
|
||||
│ │ │ - MCP │ │ │
|
||||
│ │ │ - Built-in │ │ │
|
||||
│ │ │ - Subagents │ │ │
|
||||
│ │ └────────────────┘ │ │
|
||||
│ └──────────────────────┘ │
|
||||
└───────────────────────────┘
|
||||
```
|
||||
|
||||
**Request Routing**:
|
||||
- `/api/langgraph/*` → Gateway (LangGraph runtime)
|
||||
- `/api/*` (other) → Gateway (FastAPI REST endpoints)
|
||||
- `/` → Frontend (React web interface)
|
||||
|
||||
---
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
deerflow-server-master/
|
||||
├── CLAUDE.md # This file (root guidance)
|
||||
├── .gitignore # Git ignore rules
|
||||
│
|
||||
├── frontend-web/ # React/Vite web interface
|
||||
│ ├── package.json # Frontend dependencies
|
||||
│ ├── package-lock.json
|
||||
│ ├── vite.config.ts # Vite bundler config
|
||||
│ ├── tsconfig.json # TypeScript config
|
||||
│ ├── tailwind.config.ts # Tailwind CSS config
|
||||
│ ├── postcss.config.js # PostCSS config
|
||||
│ ├── index.html # HTML entry point
|
||||
│ └── src/
|
||||
│ ├── App.tsx # Root component
|
||||
│ ├── main.tsx # React DOM mount
|
||||
│ ├── components/
|
||||
│ │ ├── ai-elements/ # Agent UI components (message, artifact, plan, etc.)
|
||||
│ │ ├── landing/ # Landing page components
|
||||
│ │ ├── ui/ # Base UI components (shadcn/ui styled)
|
||||
│ │ ├── workspace/ # Main workspace interface
|
||||
│ │ ├── query-client-provider.tsx
|
||||
│ │ └── theme-provider.tsx
|
||||
│ ├── hooks/ # Custom React hooks
|
||||
│ ├── lib/ # Utilities (HTTP client, formatting)
|
||||
│ ├── pages/ # Route pages
|
||||
│ └── styles/ # Global CSS
|
||||
│
|
||||
└── offline-backend-20260512/backend/ # Python FastAPI + LangGraph backend
|
||||
├── CLAUDE.md # Detailed backend guidance
|
||||
├── README.md # Backend documentation
|
||||
├── Makefile # Backend commands
|
||||
├── pyproject.toml # Python dependencies + workspace
|
||||
├── langgraph.json # LangGraph Studio configuration
|
||||
│
|
||||
├── packages/harness/ # deerflow-harness: Publishable agent framework
|
||||
│ ├── pyproject.toml
|
||||
│ └── deerflow/
|
||||
│ ├── agents/ # LangGraph agent system
|
||||
│ ├── sandbox/ # Code execution isolation
|
||||
│ ├── subagents/ # Task delegation system
|
||||
│ ├── tools/ # Tool ecosystem
|
||||
│ ├── models/ # LLM model factory
|
||||
│ ├── mcp/ # Model Context Protocol integration
|
||||
│ ├── skills/ # Skills discovery & loading
|
||||
│ ├── config/ # Configuration system
|
||||
│ ├── community/ # Community tools (Tavily, Jina, Firecrawl)
|
||||
│ ├── reflection/ # Dynamic module loading
|
||||
│ └── client.py # Embedded DeerFlowClient
|
||||
│
|
||||
├── app/ # Unpublished application code
|
||||
│ ├── gateway/ # FastAPI Gateway API
|
||||
│ │ ├── app.py # FastAPI application
|
||||
│ │ └── routers/ # REST endpoints
|
||||
│ └── channels/ # IM integrations (Feishu, Slack, Telegram, DingTalk)
|
||||
│
|
||||
├── tests/ # Comprehensive test suite
|
||||
├── docs/ # Detailed documentation
|
||||
└── .deer-flow/ # Runtime directory (created at startup)
|
||||
├── agents/ # Custom agent definitions
|
||||
├── users/ # Per-user data
|
||||
│ └── {user_id}/
|
||||
│ ├── memory.json # Memory system
|
||||
│ ├── threads/ # Per-thread data
|
||||
│ └── agents/ # Per-agent memory
|
||||
└── threads/ # Thread-specific workspace (legacy)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Setup & Installation
|
||||
|
||||
### Prerequisites
|
||||
|
||||
- Node.js 18+ and pnpm
|
||||
- Python 3.12+
|
||||
- uv package manager
|
||||
- API keys for LLM providers (OpenAI, Anthropic, etc.)
|
||||
|
||||
### Quick Start (Full Application)
|
||||
|
||||
```bash
|
||||
cd offline-backend-20260512/backend
|
||||
|
||||
# Install all dependencies
|
||||
make install
|
||||
|
||||
# Create config from template
|
||||
cp config.example.yaml config.yaml
|
||||
|
||||
# Set your API keys
|
||||
export OPENAI_API_KEY="your-key-here"
|
||||
# ... other API keys as needed
|
||||
|
||||
# Start all services
|
||||
make dev
|
||||
```
|
||||
|
||||
Access at: **http://localhost:2026**
|
||||
|
||||
---
|
||||
|
||||
## Development Commands
|
||||
|
||||
### Full Application (from backend directory)
|
||||
|
||||
```bash
|
||||
make install # Install frontend + backend dependencies
|
||||
make dev # Start Gateway + Frontend + Nginx (port 2026)
|
||||
make gateway # Run Gateway API only (port 8001)
|
||||
make test # Run all tests
|
||||
make lint # Lint code
|
||||
make format # Format code with ruff
|
||||
```
|
||||
|
||||
### Frontend Only (from frontend-web directory)
|
||||
|
||||
```bash
|
||||
pnpm install # Install frontend dependencies
|
||||
pnpm dev # Start Vite dev server (port 3000)
|
||||
pnpm build # Build for production
|
||||
pnpm preview # Preview production build
|
||||
pnpm typecheck # TypeScript type checking
|
||||
```
|
||||
|
||||
### Backend Only (from backend directory)
|
||||
|
||||
```bash
|
||||
make install # Install dependencies
|
||||
make dev # Run Gateway API with auto-reload (port 8001)
|
||||
make gateway # Run Gateway API (no reload)
|
||||
make test # Run tests
|
||||
make lint # Check code style
|
||||
make format # Auto-format code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Architecture Highlights
|
||||
|
||||
### Frontend (`frontend-web/`)
|
||||
|
||||
- **Framework**: React 19 with TypeScript
|
||||
- **Bundler**: Vite for fast dev/build
|
||||
- **Styling**: Tailwind CSS + shadcn/ui components
|
||||
- **State Management**: React Query (TanStack Query) + local state
|
||||
- **Routing**: React Router v7
|
||||
- **Key Libraries**:
|
||||
- `@xyflow/react` - Node/edge visualization for agent workflows
|
||||
- `codemirror` - Code editing with language support
|
||||
- `sonner` - Toast notifications
|
||||
- `motion` - Animation library
|
||||
- `katex` - Math rendering
|
||||
- `remark-gfm` + `rehype` - Markdown processing
|
||||
|
||||
**Main Components**:
|
||||
- `components/ai-elements/` - Agent-specific UI (message, artifact, plan, canvas, etc.)
|
||||
- `components/ui/` - Reusable shadcn/ui-style components
|
||||
- `components/workspace/` - Main workspace interface
|
||||
- `components/landing/` - Public landing page
|
||||
|
||||
### Backend (`offline-backend-20260512/backend/`)
|
||||
|
||||
The backend is split into two layers:
|
||||
|
||||
1. **Harness** (`packages/harness/deerflow/`)
|
||||
- Publishable agent framework package
|
||||
- Contains: agents, sandbox, tools, models, MCP, skills, config
|
||||
- Import prefix: `from deerflow.*`
|
||||
- Can be published as `deerflow-harness` PyPI package
|
||||
|
||||
2. **App** (`app/`)
|
||||
- Unpublished application code
|
||||
- Contains: FastAPI Gateway API, IM channel integrations
|
||||
- Import prefix: `from app.*`
|
||||
- **Boundary rule**: App imports Harness, but Harness never imports App
|
||||
|
||||
**Key Systems**:
|
||||
- **Lead Agent** - Single LangGraph agent with 10 middleware components
|
||||
- **Sandbox** - Per-thread isolated execution (local filesystem or Docker)
|
||||
- **Subagents** - Background task delegation with 3-concurrent limit
|
||||
- **Memory** - LLM-powered persistent context across conversations
|
||||
- **Tools** - Sandbox (bash, read/write), MCP, community (web search), built-in (clarification, image view)
|
||||
- **Skills** - Domain-specific workflows injected via system prompt
|
||||
- **MCP** - Model Context Protocol server integration
|
||||
|
||||
**For detailed backend architecture, see `offline-backend-20260512/backend/CLAUDE.md`**
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
### Main Configuration (`config.yaml`)
|
||||
|
||||
Place in project root (same level as this file). See `offline-backend-20260512/backend/config.example.yaml` for full template.
|
||||
|
||||
Key sections:
|
||||
- `models` - LLM configurations (OpenAI, Anthropic, etc.) with thinking/vision flags
|
||||
- `tools` - Tool definitions with module paths
|
||||
- `sandbox` - Execution environment provider
|
||||
- `skills` - Skills directory paths
|
||||
- `memory` - Memory system (enabled, storage, debounce)
|
||||
- `title` - Auto-title generation
|
||||
- `summarization` - Context summarization
|
||||
- `subagents` - Task delegation (enabled/disabled)
|
||||
|
||||
Config values starting with `$` are resolved as environment variables (e.g., `$OPENAI_API_KEY`).
|
||||
|
||||
### Extensions Configuration (`extensions_config.json`)
|
||||
|
||||
Place in project root. Configures MCP servers and skill states:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"github": {
|
||||
"enabled": true,
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-github"],
|
||||
"env": {"GITHUB_TOKEN": "$GITHUB_TOKEN"}
|
||||
}
|
||||
},
|
||||
"skills": {
|
||||
"pdf-processing": {"enabled": true}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Environment Variables
|
||||
|
||||
```bash
|
||||
# LLM API Keys
|
||||
export OPENAI_API_KEY="sk-..."
|
||||
export ANTHROPIC_API_KEY="sk-ant-..."
|
||||
|
||||
# Tool API Keys
|
||||
export TAVILY_API_KEY="tvly-..."
|
||||
export GITHUB_TOKEN="ghp_..."
|
||||
|
||||
# Configuration paths
|
||||
export DEER_FLOW_CONFIG_PATH="./config.yaml"
|
||||
export DEER_FLOW_EXTENSIONS_CONFIG_PATH="./extensions_config.json"
|
||||
|
||||
# Tracing (optional)
|
||||
export LANGSMITH_TRACING=true
|
||||
export LANGSMITH_API_KEY="lsv2_pt_..."
|
||||
export LANGSMITH_PROJECT="myproject"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Important Development Guidelines
|
||||
|
||||
### Documentation Updates
|
||||
|
||||
**CRITICAL**: Always update relevant documentation after code changes:
|
||||
- Update `offline-backend-20260512/backend/README.md` for user-facing changes
|
||||
- Update `offline-backend-20260512/backend/CLAUDE.md` for internal changes
|
||||
- Keep documentation synchronized with code
|
||||
|
||||
### Testing
|
||||
|
||||
**Test-Driven Development (TDD) is mandatory** for backend:
|
||||
```bash
|
||||
cd offline-backend-20260512/backend
|
||||
|
||||
# Run all tests
|
||||
make test
|
||||
|
||||
# Run specific test
|
||||
PYTHONPATH=. uv run pytest tests/test_<feature>.py -v
|
||||
```
|
||||
|
||||
Frontend testing is lighter-weight but should be done for critical components.
|
||||
|
||||
### Code Style
|
||||
|
||||
- **Backend**: `ruff` (line length: 240, Python 3.12+, double quotes)
|
||||
- **Frontend**: TypeScript with eslint/prettier defaults
|
||||
|
||||
### Architecture Boundaries
|
||||
|
||||
The **Harness ↔ App boundary** (enforced by CI tests):
|
||||
```python
|
||||
# ✅ Allowed (App → Harness)
|
||||
from deerflow.agents import make_lead_agent
|
||||
|
||||
# ❌ Forbidden (Harness → App)
|
||||
from app.gateway.routers import ... # This will fail CI tests
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Features
|
||||
|
||||
### 1. Sandbox Execution
|
||||
|
||||
Per-thread isolated code execution with virtual path mapping:
|
||||
- **Local**: Filesystem-based execution (default)
|
||||
- **Docker**: Aio sandbox provider for complete isolation
|
||||
- **Tools**: `bash`, `ls`, `read_file`, `write_file`, `str_replace`
|
||||
- **Paths**: `/mnt/user-data/{workspace,uploads,outputs}` → thread-specific physical directories
|
||||
|
||||
### 2. Persistent Memory
|
||||
|
||||
LLM-powered context retention across conversations:
|
||||
- Automatic extraction of facts and preferences
|
||||
- Structured storage with confidence scoring
|
||||
- Debounced updates to minimize LLM calls
|
||||
- Injected into agent system prompt for context awareness
|
||||
|
||||
See `offline-backend-20260512/backend/docs/memory-improvements.md` for details.
|
||||
|
||||
### 3. Subagent Delegation
|
||||
|
||||
Background task execution with concurrent limits:
|
||||
- Built-in agents: `general-purpose` (full toolset) and `bash` (commands)
|
||||
- Max 3 concurrent subagents per turn
|
||||
- 15-minute timeout per task
|
||||
- Real-time status updates via SSE
|
||||
|
||||
### 4. Tool Ecosystem
|
||||
|
||||
Modular tool system supporting multiple providers:
|
||||
- **Sandbox tools**: Code execution in isolated environments
|
||||
- **Built-in tools**: `ask_clarification`, `view_image`, `present_files`
|
||||
- **MCP tools**: Any Model Context Protocol server (stdio, SSE, HTTP)
|
||||
- **Community tools**: Tavily (web search), Jina (web fetch), Firecrawl (scraping)
|
||||
- **Skills**: Domain-specific workflows loaded from SKILL.md files
|
||||
|
||||
### 5. Model Context Protocol (MCP)
|
||||
|
||||
Integrate external tools and services:
|
||||
- **Transports**: stdio, SSE, HTTP (with OAuth support)
|
||||
- **Configuration**: `extensions_config.json` for server setup
|
||||
- **Runtime updates**: Changes detected and reloaded automatically
|
||||
|
||||
### 6. Plan Mode
|
||||
|
||||
TodoList middleware for complex multi-step tasks:
|
||||
- Controlled via runtime config: `is_plan_mode = True`
|
||||
- Provides `write_todos` tool for task tracking
|
||||
- Real-time task status updates
|
||||
|
||||
See `offline-backend-20260512/backend/docs/plan_mode_usage.md`.
|
||||
|
||||
### 7. Vision Support
|
||||
|
||||
For models with `supports_vision: true`:
|
||||
- `ViewImageMiddleware` processes images automatically
|
||||
- `view_image_tool` added to agent toolset
|
||||
- Images converted to base64 and injected into state
|
||||
|
||||
### 8. File Upload
|
||||
|
||||
Multi-file upload with automatic document conversion:
|
||||
- Supports: PDF, PPT, Excel, Word documents
|
||||
- Auto-conversion via `markitdown`
|
||||
- Endpoint: `POST /api/threads/{thread_id}/uploads`
|
||||
- Files stored in thread-isolated directories
|
||||
|
||||
See `offline-backend-20260512/backend/docs/FILE_UPLOAD.md`.
|
||||
|
||||
### 9. IM Channel Integration
|
||||
|
||||
External messaging platform bridges:
|
||||
- **Supported**: Feishu, Slack, Telegram, DingTalk
|
||||
- **Architecture**: Channels use `langgraph-sdk` HTTP client
|
||||
- **Streaming**: Feishu updates single card in place; Slack/Telegram use `wait()` response
|
||||
- See `offline-backend-20260512/backend/app/channels/` for implementation
|
||||
|
||||
### 10. Context Summarization
|
||||
|
||||
Automatic conversation compression when approaching token limits:
|
||||
- Configurable trigger types: tokens, messages, or token fraction
|
||||
- Keeps recent messages while summarizing older ones
|
||||
- See `offline-backend-20260512/backend/docs/summarization.md`.
|
||||
|
||||
---
|
||||
|
||||
## Middleware Chain (Backend)
|
||||
|
||||
The agent runtime executes 18 middleware components in strict order:
|
||||
|
||||
1. **ThreadDataMiddleware** - Per-thread isolated directories
|
||||
2. **UploadsMiddleware** - Inject uploaded files
|
||||
3. **SandboxMiddleware** - Acquire sandbox environment
|
||||
4. **DanglingToolCallMiddleware** - Handle incomplete tool responses
|
||||
5. **LLMErrorHandlingMiddleware** - Normalize provider errors
|
||||
6. **GuardrailMiddleware** - Tool call authorization (optional)
|
||||
7. **SandboxAuditMiddleware** - Security audit logging
|
||||
8. **ToolErrorHandlingMiddleware** - Convert exceptions to error messages
|
||||
9. **SummarizationMiddleware** - Context reduction (optional)
|
||||
10. **TodoListMiddleware** - Task tracking (optional, plan mode)
|
||||
11. **TokenUsageMiddleware** - Token tracking (optional)
|
||||
12. **TitleMiddleware** - Auto-generate conversation titles
|
||||
13. **MemoryMiddleware** - Queue for async memory updates
|
||||
14. **ViewImageMiddleware** - Inject vision image data (conditional)
|
||||
15. **DeferredToolFilterMiddleware** - Hide deferred tools (optional)
|
||||
16. **SubagentLimitMiddleware** - Enforce concurrent subagent limit (optional)
|
||||
17. **LoopDetectionMiddleware** - Detect and break tool-call loops
|
||||
18. **ClarificationMiddleware** - Interrupt on clarification requests (must be last)
|
||||
|
||||
See `offline-backend-20260512/backend/CLAUDE.md` for detailed middleware descriptions.
|
||||
|
||||
---
|
||||
|
||||
## Common Workflows
|
||||
|
||||
### Adding a New Tool
|
||||
|
||||
1. Define tool in `packages/harness/deerflow/tools/` or `packages/harness/deerflow/community/`
|
||||
2. Add to `config.yaml` `tools` section with module path
|
||||
3. Write unit tests in `backend/tests/`
|
||||
4. Update `CLAUDE.md` with tool description
|
||||
5. Test via `make test`
|
||||
|
||||
### Creating a Custom Agent
|
||||
|
||||
1. Add agent metadata to database (`agents` table)
|
||||
2. Create agent directory: `.deer-flow/agents/{agent_id}/SOUL.md`
|
||||
3. Define agent behavior via SOUL.md frontmatter
|
||||
4. Access via Gateway API: `GET /api/agents/{id}`
|
||||
|
||||
### Configuring MCP Servers
|
||||
|
||||
1. Add server to `extensions_config.json`:
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-server": {
|
||||
"enabled": true,
|
||||
"type": "stdio",
|
||||
"command": "npx",
|
||||
"args": ["-y", "my-mcp-package"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Restart Gateway API - MCP tools auto-loaded via lazy initialization
|
||||
3. Tools available immediately in agent toolset
|
||||
|
||||
### Testing in Development
|
||||
|
||||
```bash
|
||||
# Backend unit tests
|
||||
cd offline-backend-20260512/backend
|
||||
make test
|
||||
|
||||
# Run specific test
|
||||
PYTHONPATH=. uv run pytest tests/test_memory_updater.py -v
|
||||
|
||||
# Frontend development
|
||||
cd frontend-web
|
||||
pnpm dev # Access at http://localhost:3000
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Port Mapping
|
||||
|
||||
| Service | Port | Purpose |
|
||||
|---------|------|---------|
|
||||
| **Frontend** | 3000 | React development server |
|
||||
| **Gateway API** | 8001 | FastAPI REST endpoints + LangGraph runtime |
|
||||
| **LangGraph Server** | 2024 | Raw LangGraph protocol (used internally) |
|
||||
| **Nginx** | 2026 | Unified reverse proxy (public entry point) |
|
||||
| **Provisioner** | 8002 | Kubernetes sandbox provisioner (optional, Docker dev only) |
|
||||
|
||||
---
|
||||
|
||||
## Important Files & References
|
||||
|
||||
### Backend Architecture
|
||||
- `offline-backend-20260512/backend/CLAUDE.md` - Detailed backend guidance
|
||||
- `offline-backend-20260512/backend/README.md` - User-facing backend documentation
|
||||
- `offline-backend-20260512/backend/docs/ARCHITECTURE.md` - Deep-dive architecture
|
||||
- `offline-backend-20260512/backend/docs/API.md` - Gateway API reference
|
||||
- `offline-backend-20260512/backend/docs/CONFIGURATION.md` - Config schema
|
||||
|
||||
### Frontend Components
|
||||
- `frontend-web/src/components/ai-elements/` - Agent UI components
|
||||
- `frontend-web/src/components/ui/` - Reusable UI components
|
||||
- `frontend-web/src/components/workspace/` - Main workspace
|
||||
|
||||
### Configuration
|
||||
- `config.example.yaml` - Backend configuration template
|
||||
- `extensions_config.json` - MCP servers and skills
|
||||
- `offline-backend-20260512/backend/langgraph.json` - LangGraph Studio config
|
||||
|
||||
### Testing
|
||||
- `offline-backend-20260512/backend/tests/` - Test suite
|
||||
- Regression tests: `test_docker_sandbox_mode_detection.py`, `test_provisioner_kubeconfig.py`, `test_harness_boundary.py`
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Port Already in Use
|
||||
|
||||
If a port is already in use, kill the process:
|
||||
```bash
|
||||
# Find process on port (e.g., 8001)
|
||||
lsof -i :8001
|
||||
|
||||
# Kill process
|
||||
kill -9 <PID>
|
||||
```
|
||||
|
||||
### Configuration Issues
|
||||
|
||||
1. Verify `config.yaml` exists in project root
|
||||
2. Run: `make config-upgrade` to auto-merge missing fields
|
||||
3. Check `config_version` in `config.yaml` matches `config.example.yaml`
|
||||
|
||||
### Memory System Issues
|
||||
|
||||
Check memory state:
|
||||
```bash
|
||||
# List memory files
|
||||
ls -la offline-backend-20260512/backend/.deer-flow/users/
|
||||
|
||||
# Reload memory
|
||||
curl -X POST http://localhost:8001/api/memory/reload
|
||||
```
|
||||
|
||||
### Test Failures
|
||||
|
||||
Ensure the test dependency boundary is not violated:
|
||||
```bash
|
||||
# Run boundary test specifically
|
||||
cd offline-backend-20260512/backend
|
||||
PYTHONPATH=. uv run pytest tests/test_harness_boundary.py -v
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Technology Stack
|
||||
|
||||
### Frontend
|
||||
- **React** 19 - UI framework
|
||||
- **TypeScript** - Type safety
|
||||
- **Vite** - Fast bundler
|
||||
- **Tailwind CSS** - Utility-first styling
|
||||
- **React Router** - Client routing
|
||||
- **TanStack Query** - Data fetching
|
||||
- **XYFlow** - Graph visualization
|
||||
- **CodeMirror** - Code editor
|
||||
- **Shiki** - Syntax highlighting
|
||||
- **Remark/Rehype** - Markdown processing
|
||||
|
||||
### Backend
|
||||
- **LangGraph** 1.0.6+ - Agent orchestration framework
|
||||
- **LangChain** 1.2.3+ - LLM abstractions and tools
|
||||
- **FastAPI** 0.115.0+ - REST API framework
|
||||
- **Uvicorn** - ASGI server
|
||||
- **Python 3.12+** - Programming language
|
||||
- **uv** - Fast Python package manager
|
||||
- **Ruff** - Linting and formatting
|
||||
- **Pytest** - Testing framework
|
||||
- **langchain-mcp-adapters** - Model Context Protocol support
|
||||
- **markitdown** - Document conversion
|
||||
- **Tavily/Jina/Firecrawl** - Web tools
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
1. Create a feature branch from `master`
|
||||
2. Make changes and write tests
|
||||
3. Run linting and tests:
|
||||
```bash
|
||||
make lint
|
||||
make test
|
||||
```
|
||||
4. Update relevant CLAUDE.md and README.md files
|
||||
5. Create a pull request
|
||||
|
||||
### CI/CD
|
||||
|
||||
GitHub Actions runs:
|
||||
- Backend unit tests (including harness boundary test)
|
||||
- Linting checks
|
||||
- Type checking
|
||||
|
||||
All must pass before merging to `master`.
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
For issues and feature requests:
|
||||
- Check the detailed docs in `offline-backend-20260512/backend/docs/`
|
||||
- Review existing tests for usage examples
|
||||
- Ask Claude Code for help with `/help` command
|
||||
|
||||
---
|
||||
|
||||
## License & Attribution
|
||||
|
||||
See LICENSE file in project root.
|
||||
|
||||
For more details on specific systems, see:
|
||||
- Backend: `offline-backend-20260512/backend/CLAUDE.md`
|
||||
- Backend architecture: `offline-backend-20260512/backend/docs/ARCHITECTURE.md`
|
||||
- Frontend: Components in `frontend-web/src/components/`
|
||||
@@ -0,0 +1,4 @@
|
||||
# 本地开发：直连 Gateway（与 offline-backend-20260512/backend 默认端口一致）
|
||||
# 修改端口时请同步改这里，并重启 `npm run dev`
|
||||
VITE_BACKEND_BASE_URL=http://127.0.0.1:8001/
|
||||
VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
|
||||
@@ -0,0 +1,7 @@
|
||||
# 复制为 .env 或 .env.development 后按需修改（Vite 仅暴露以 VITE_ 开头的变量）
|
||||
#
|
||||
# Gateway 根地址（REST：`/api/models`、`/api/threads/...` 等）
|
||||
VITE_BACKEND_BASE_URL=http://127.0.0.1:8001
|
||||
#
|
||||
# LangGraph SDK 的 apiUrl：须指向带 `/api` 的前缀，以便请求落在 `/api/threads`、`/api/assistants` 等路由上
|
||||
VITE_LANGGRAPH_BASE_URL=http://127.0.0.1:8001/api
|
||||
@@ -0,0 +1,104 @@
|
||||
# DeerFlow Gateway 本地启停说明
|
||||
|
||||
后端目录：`offline-backend-20260512/backend`（下文简称 **backend 目录**）。
|
||||
|
||||
默认监听：**`http://0.0.0.0:8001`**（本机访问可用 `http://127.0.0.1:8001`）。
|
||||
|
||||
---
|
||||
|
||||
## 前置条件
|
||||
|
||||
1. 已安装 **Python 3.12+** 与 **[uv](https://github.com/astral-sh/uv)**。
|
||||
2. 在 **backend 目录** 下存在 **`config.yaml`**（可从项目文档中的示例自行整理；仓库内 `config.yaml` 通常被 git 忽略）。
|
||||
3. 若 `config.yaml` 里模型使用 **`$OPENAI_API_KEY`** 等形式，必须在环境中提供对应变量，否则启动时配置解析会失败。
|
||||
|
||||
---
|
||||
|
||||
## 启动（Windows PowerShell）
|
||||
|
||||
在 **backend 目录** 打开终端，执行：
|
||||
|
||||
```powershell
|
||||
cd f:\react01\deeflow\deerflow-server-master\offline-backend-20260512\backend
|
||||
|
||||
# 依赖（首次或依赖变更后）
|
||||
uv sync
|
||||
|
||||
# 建议的环境变量（可按需增删）
|
||||
$env:PYTHONPATH = "."
|
||||
$env:OPENAI_API_KEY = "你的真实 API Key"
|
||||
$env:DEER_FLOW_AUTH_DISABLED = "true"
|
||||
$env:CORS_ORIGINS = "http://localhost:5173,http://localhost:3000"
|
||||
|
||||
# 开发模式：代码变更自动重载
|
||||
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001 --reload
|
||||
```
|
||||
|
||||
无热重载（更接近生产单次进程）：
|
||||
|
||||
```powershell
|
||||
$env:PYTHONPATH = "."
|
||||
$env:OPENAI_API_KEY = "你的真实 API Key"
|
||||
uv run uvicorn app.gateway.app:app --host 0.0.0.0 --port 8001
|
||||
```
|
||||
|
||||
**验证**：浏览器或命令行访问 `http://127.0.0.1:8001/health`，应返回 JSON 且含 `"status":"healthy"`。API 文档：`http://127.0.0.1:8001/docs`。
|
||||
|
||||
---
|
||||
|
||||
## 启动（macOS / Linux，可选）
|
||||
|
||||
若已安装 `make` 且 Makefile 可用，在 **backend 目录**：
|
||||
|
||||
```bash
|
||||
export OPENAI_API_KEY="你的真实 API Key"
|
||||
make install # 等价 uv sync
|
||||
make dev # 带 --reload，端口 8001
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 停止（暂停）服务
|
||||
|
||||
「暂停」在本地开发里一般指 **结束 Gateway 进程**，而不是挂起进程。
|
||||
|
||||
### 方式一：前台运行时（推荐）
|
||||
|
||||
在运行 `uvicorn` 的终端窗口按 **`Ctrl + C`**，等待进程退出即可。
|
||||
|
||||
### 方式二：需释放 8001 端口（Windows）
|
||||
|
||||
在 **管理员或普通** PowerShell 中：
|
||||
|
||||
```powershell
|
||||
# 查看占用 8001 的监听进程 PID
|
||||
Get-NetTCPConnection -LocalPort 8001 -State Listen -ErrorAction SilentlyContinue |
|
||||
Select-Object -ExpandProperty OwningProcess -Unique
|
||||
|
||||
# 结束指定 PID（将 <PID> 换成上一步输出的数字；若有多个可多次执行）
|
||||
Stop-Process -Id <PID> -Force
|
||||
```
|
||||
|
||||
使用 `--reload` 时可能存在 **父进程（监视）+ 子进程（工作进程）**；若端口仍被占用，对查到的多个 PID 分别 `Stop-Process`，或关闭对应终端会话。
|
||||
|
||||
### 方式三：macOS / Linux
|
||||
|
||||
```bash
|
||||
# 若已知 uvicorn 在前台，仍用 Ctrl+C
|
||||
|
||||
# 或按端口查杀（示例）
|
||||
lsof -i :8001
|
||||
kill <PID>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 常见问题
|
||||
|
||||
| 现象 | 处理 |
|
||||
|------|------|
|
||||
| `Environment variable OPENAI_API_KEY not found` | 设置 `$env:OPENAI_API_KEY`（PowerShell）或写入 `.env` 后重启（项目会加载 dotenv）。 |
|
||||
| `Address already in use` / 端口占用 | 先按上文 **停止** 释放 8001，再启动。 |
|
||||
| 前端跨域失败 | 将前端实际地址加入 `CORS_ORIGINS`（逗号分隔多个）。 |
|
||||
|
||||
更完整的配置说明见同目录下的 [SETUP.md](SETUP.md) 与 [CONFIGURATION.md](CONFIGURATION.md)。
|
||||
Generated
+2
@@ -745,6 +745,7 @@ version = "0.1.0"
|
||||
source = { virtual = "." }
|
||||
dependencies = [
|
||||
{ name = "bcrypt" },
|
||||
{ name = "croniter" },
|
||||
{ name = "deerflow-harness" },
|
||||
{ name = "dingtalk-stream" },
|
||||
{ name = "email-validator" },
|
||||
@@ -778,6 +779,7 @@ dev = [
|
||||
[package.metadata]
|
||||
requires-dist = [
|
||||
{ name = "bcrypt", specifier = ">=4.0.0" },
|
||||
{ name = "croniter", specifier = ">=6.2.2" },
|
||||
{ name = "deerflow-harness", editable = "packages/harness" },
|
||||
{ name = "deerflow-harness", extras = ["postgres"], marker = "extra == 'postgres'", editable = "packages/harness" },
|
||||
{ name = "dingtalk-stream", specifier = ">=0.24.3" },
|
||||
|
||||
Reference in new issue
Block a user