Developer Guide · 03
Development Environment Setup
3.1 Backend
bash
# Create virtual environment
python -m venv venv
venv\Scripts\activate # Windows
source venv/bin/activate # Linux/macOS
# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp .env.example .env
# Edit .env — set at least ANTHROPIC_API_KEY or OPENAI_API_KEY
# Generate registration codes (first deploy)
python generate_keys.py
# Start (dev mode with hot reload)
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reloadAPI documentation: http://localhost:8000/docs (Swagger UI).
Tip: The cross-platform launcher
python launcher.py [--dev]in the project root automatically detects old instances, port conflicts, and manages both processes. See §13 for details.
3.2 Frontend
bash
cd frontend
npm install
npm run dev # Vite dev server → http://localhost:3000 (recommended)
npm run build # Production build → dist/
npm run preview # Preview production build
npm run legacy # Legacy Express server (serves static files from dist/)Vite dev proxy rules (vite.config.ts):
| Path | Target | Notes |
|---|---|---|
/api/* | localhost:8000 | All FastAPI APIs |
/s/* | localhost:8000 | Consumer chat page |
/wc/* | localhost:8000 | WeChat landing page |
/media_resources/* | localhost:8000 | Logo/icon static resources |
SSE requests automatically set Accept: text/event-stream and disable proxy buffering.
Vite multi-entry: rollupOptions.input declares both main and service-chat entries, building to dist/index.html and dist/service-chat.html respectively.
3.3 One-click Start
bash
# Windows
start_local.bat
# Linux/macOS
./start_local.sh
# Both equivalent to: python launcher.py