100 lines
3.8 KiB
Markdown
100 lines
3.8 KiB
Markdown
|
# CLAUDE.md
|
||
|
|
|
||
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||
|
|
|
||
|
|
## Project Overview
|
||
|
|
|
||
|
|
AI Chat Room (AI聊天室) is a multi-agent collaborative discussion platform. Users configure AI providers, create agents with different roles, and let them discuss in chat rooms to reach consensus.
|
||
|
|
|
||
|
|
**Stack:** FastAPI (Python 3.11+) backend + React 18 (TypeScript) frontend + MongoDB database. Real-time communication via WebSockets.
|
||
|
|
|
||
|
|
## Development Commands
|
||
|
|
|
||
|
|
### Docker (Recommended)
|
||
|
|
```bash
|
||
|
|
# Start all services
|
||
|
|
docker-compose up -d
|
||
|
|
|
||
|
|
# Rebuild after changes
|
||
|
|
docker-compose up -d --build
|
||
|
|
|
||
|
|
# View logs
|
||
|
|
docker-compose logs -f backend
|
||
|
|
docker-compose logs -f frontend
|
||
|
|
```
|
||
|
|
|
||
|
|
### Backend (Local)
|
||
|
|
```bash
|
||
|
|
cd backend
|
||
|
|
python -m venv venv
|
||
|
|
venv\Scripts\activate # Windows: activate, Linux/Mac: source venv/bin/activate
|
||
|
|
pip install -r requirements.txt
|
||
|
|
python main.py
|
||
|
|
```
|
||
|
|
|
||
|
|
Backend runs on http://localhost:8000 - API docs at http://localhost:8000/docs
|
||
|
|
|
||
|
|
### Frontend (Local)
|
||
|
|
```bash
|
||
|
|
cd frontend
|
||
|
|
npm install
|
||
|
|
npm run dev # Development server (Vite)
|
||
|
|
npm run build # Production build (tsc && vite build)
|
||
|
|
```
|
||
|
|
|
||
|
|
Frontend runs on http://localhost:3000
|
||
|
|
|
||
|
|
## Architecture
|
||
|
|
|
||
|
|
### Backend Structure
|
||
|
|
- **[adapters/](backend/adapters/)** - AI provider integrations using Adapter pattern
|
||
|
|
- `base_adapter.py` - Abstract base class with `ChatMessage`, `AdapterResponse`, `BaseAdapter`
|
||
|
|
- Each adapter implements `chat()`, `chat_stream()`, `test_connection()`
|
||
|
|
- Supported: OpenRouter, Zhipu (智谱), MiniMax, Kimi, DeepSeek, Gemini, Ollama, LLM Studio
|
||
|
|
- **[models/](backend/models/)** - Beanie ODM documents for MongoDB
|
||
|
|
- **[services/](backend/services/)** - Business logic layer
|
||
|
|
- `discussion_engine.py` - Core multi-agent discussion orchestration
|
||
|
|
- `consensus_manager.py` - Moderator agent evaluates if consensus reached
|
||
|
|
- `message_router.py` - WebSocket message routing
|
||
|
|
- **[routers/](backend/routers/)** - FastAPI route handlers (providers, agents, chatrooms, discussions)
|
||
|
|
- **[utils/](backend/utils/)** - encryption.py (API keys), proxy_handler.py, rate_limiter.py
|
||
|
|
|
||
|
|
### Frontend Structure
|
||
|
|
- **[src/stores/](frontend/src/stores/)** - Zustand state management
|
||
|
|
- **[src/services/](frontend/src/services/)** - API client and WebSocket client
|
||
|
|
- **[src/pages/](frontend/src/pages/)** - Dashboard, ProviderConfig, AgentManagement, ChatRoom, DiscussionHistory
|
||
|
|
- **[src/components/](frontend/src/components/)** - Reusable UI components using Ant Design
|
||
|
|
|
||
|
|
### Key Data Flow
|
||
|
|
1. User creates agents (role + system prompt) and assigns AI providers
|
||
|
|
2. Chat room created with selected agents + optional moderator
|
||
|
|
3. Discussion started: `discussion_engine.py` orchestrates turn-based agent interactions
|
||
|
|
4. Each round: agents receive context and decide whether to speak (role relevance)
|
||
|
|
5. Moderator agent periodically checks for consensus via `consensus_manager.py`
|
||
|
|
6. WebSocket streams messages in real-time to frontend
|
||
|
|
|
||
|
|
### Adding New AI Providers
|
||
|
|
1. Create new adapter in `backend/adapters/` inheriting from `BaseAdapter`
|
||
|
|
2. Implement async methods: `chat()`, `chat_stream()`, `test_connection()`
|
||
|
|
3. Register in `backend/adapters/__init__.py`
|
||
|
|
|
||
|
|
## Configuration
|
||
|
|
|
||
|
|
Environment variables in `.env`:
|
||
|
|
- `MONGODB_URL` - MongoDB connection string
|
||
|
|
- `MONGODB_DB` - Database name (default: ai_chatroom)
|
||
|
|
- `SECRET_KEY` - JWT signing key
|
||
|
|
- `ENCRYPTION_KEY` - 32-byte key for API key encryption
|
||
|
|
- `DEFAULT_HTTP_PROXY` / `DEFAULT_HTTPS_PROXY` - Proxy for overseas APIs
|
||
|
|
|
||
|
|
Backend config in [backend/config.py](backend/config.py) - Pydantic Settings with defaults.
|
||
|
|
|
||
|
|
## Important Notes
|
||
|
|
|
||
|
|
- All async/await - Python async functions throughout backend
|
||
|
|
- API keys encrypted at rest using `cryptography` Fernet
|
||
|
|
- WebSocket heartbeat every 30s (`WS_HEARTBEAT_INTERVAL`)
|
||
|
|
- CORS origins configured in settings for local development
|
||
|
|
- MongoDB indexes created automatically by Beanie on startup
|
||
|
|
- Chinese language UI (README and comments in Chinese)
|