Wegent/improve startup and fix chat flash

.github/workflows/e2e-tests.yml

@@ -8,7 +8,7 @@ on:
 env:
   # Next.js rewrites /api/* to ${NEXT_PUBLIC_API_URL}/api/*, so only set the base URL
   NEXT_PUBLIC_API_URL: http://localhost:8000
-  # Use pymysql driver (installed via requirements.txt)
+  # Use pymysql driver (installed via pyproject.toml)
   DATABASE_URL: mysql+pymysql://root:123456@localhost:3306/task_manager
   REDIS_URL: redis://localhost:6379
   ENVIRONMENT: development
@@ -53,13 +53,14 @@ jobs:
         with:
           python-version: '3.11'
           cache: 'pip'
-          cache-dependency-path: backend/requirements.txt
+          cache-dependency-path: backend/pyproject.toml
 
       - name: Install backend dependencies
         working-directory: backend
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          source $HOME/.cargo/env
+          uv sync
 
       - name: Set up Node.js
         uses: actions/setup-node@v4

.github/workflows/test.yml

@@ -36,23 +36,25 @@ jobs:
       - name: Cache Python dependencies
         uses: actions/cache@v3
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('backend/requirements.txt') }}
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-${{ hashFiles('backend/pyproject.toml') }}
           restore-keys: |
-            ${{ runner.os }}-pip-
+            ${{ runner.os }}-uv-
 
       - name: Install dependencies
         working-directory: ./backend
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          source $HOME/.cargo/env
+          uv sync --dev
 
       - name: Run backend tests
         working-directory: ./backend
         env:
           PYTHONPATH: ${{ github.workspace }}
         run: |
-          pytest tests/ --cov=app --cov-report=xml --cov-report=term-missing -v
+          source $HOME/.cargo/env
+          uv run pytest tests/ --cov=app --cov-report=xml --cov-report=term-missing -v
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3
@@ -78,24 +80,25 @@ jobs:
       - name: Cache Python dependencies
         uses: actions/cache@v3
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-executor-${{ hashFiles('executor/requirements.txt') }}
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-executor-${{ hashFiles('executor/pyproject.toml') }}
           restore-keys: |
-            ${{ runner.os }}-pip-executor-
+            ${{ runner.os }}-uv-executor-
 
       - name: Install dependencies
         working-directory: ./executor
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install pytest pytest-asyncio pytest-cov pytest-mock
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          source $HOME/.cargo/env
+          uv sync --dev
 
       - name: Run executor tests
         working-directory: ./executor
         env:
           PYTHONPATH: ${{ github.workspace }}:${{ github.workspace }}/executor
         run: |
-          pytest tests/ --cov=agents --cov-report=xml --cov-report=term-missing -v
+          source $HOME/.cargo/env
+          uv run pytest tests/ --cov=agents --cov-report=xml --cov-report=term-missing -v
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3
@@ -120,17 +123,17 @@ jobs:
       - name: Cache Python dependencies
         uses: actions/cache@v3
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-executor-manager-${{ hashFiles('executor_manager/requirements.txt') }}
+          path: ~/.cache/uv
+          key: ${{ runner.os }}-uv-executor-manager-${{ hashFiles('executor_manager/pyproject.toml') }}
           restore-keys: |
-            ${{ runner.os }}-pip-executor-manager-
+            ${{ runner.os }}-uv-executor-manager-
 
       - name: Install dependencies
         working-directory: ./executor_manager
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          pip install pytest pytest-asyncio pytest-cov pytest-mock
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          source $HOME/.cargo/env
+          uv sync --dev
 
       - name: Run executor manager tests
         working-directory: ./executor_manager
@@ -140,7 +143,8 @@ jobs:
           PYTHONUNBUFFERED: "1"
           PYTHONFAULTHANDLER: "1"
         run: |
-          pytest tests/ --cov=executors --cov-report=xml --cov-report=term-missing -v -s
+          source $HOME/.cargo/env
+          uv run pytest tests/ --cov=executors --cov-report=xml --cov-report=term-missing -v -s
 
       - name: Upload coverage to Codecov
         uses: codecov/codecov-action@v3
@@ -157,10 +161,10 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      - name: Set up Python 3.9
+      - name: Set up Python 3.10
         uses: actions/setup-python@v5
         with:
-          python-version: '3.9'
+          python-version: '3.10'
 
       - name: Install dependencies
         working-directory: ./shared
@@ -293,8 +297,9 @@ jobs:
       - name: Install backend dependencies
         working-directory: ./backend
         run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
+          curl -LsSf https://astral.sh/uv/install.sh | sh
+          source $HOME/.cargo/env
+          uv sync
 
       - name: Install shared module
         run: |
@@ -327,6 +332,7 @@ jobs:
       - name: Install wegent dependencies
         working-directory: ./wegent-cli
         run: |
+          python -m pip install --upgrade pip
           pip install -r requirements.txt
           pip install pytest pytest-cov
 

AGENTS.md

@@ -56,9 +56,11 @@ docker-compose up -d
 **Backend:**
 ```bash
 cd backend
-python3 -m venv venv && source venv/bin/activate
-pip install -r requirements.txt
-uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+./start.sh
+# Or manually with uv:
+# uv sync
+# source .venv/bin/activate
+# uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 ```
 
 **Frontend:**
@@ -71,8 +73,12 @@ npm run dev
 **Executor / Executor Manager:**
 ```bash
 cd executor  # or executor_manager
-pip install -r requirements.txt
-python main.py
+./start.sh
+# Or manually with uv:
+# uv sync
+# source .venv/bin/activate
+# python main.py  # for executor
+# uvicorn main:app --host 0.0.0.0 --port 8001  # for executor_manager
 ```
 
 ---

CONTRIBUTING.md

@@ -42,7 +42,7 @@ Wegent is an AI agent management platform based on Kubernetes-style CRD design,
 - Docker >= 20.10
 - Docker Compose >= 2.0
 - Node.js >= 18.0 (for frontend development)
-- Python >= 3.9 (for backend development)
+- Python >= 3.10 (for backend development)
 - Git
 
 ### Quick Start
@@ -77,7 +77,8 @@ npm run dev
 
 ```bash
 cd backend
-pip install -r requirements.txt
+./start.sh
+# Or manually: uv sync && source .venv/bin/activate
 # Configure environment variables
 export DATABASE_URL="mysql://user:password@localhost/wegent"
 uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
@@ -87,8 +88,8 @@ uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
 
 ```bash
 cd executor
-pip install -r requirements.txt
-python main.py
+./start.sh
+# Or manually: uv sync && source .venv/bin/activate && python main.py
 ```
 
 ## 🏗️ Project Architecture
@@ -111,7 +112,7 @@ Wegent/
 │   │   ├── models/    # Data models
 │   │   ├── schemas/   # Pydantic schemas
 │   │   └── services/  # Business logic
-│   └── requirements.txt
+│   └── pyproject.toml # Dependencies
 ├── executor/          # Task executor
 ├── executor_manager/  # Executor manager
 ├── shared/           # Shared utilities and models
@@ -353,7 +354,7 @@ All tests run automatically via GitHub Actions on:
 - All pull requests
 
 The test suite includes:
-- Backend tests (Python 3.9, 3.10)
+- Backend tests (Python 3.10, 3.11, 3.12)
 - Executor tests
 - Executor Manager tests
 - Shared utilities tests

README.md

@@ -3,7 +3,7 @@
 
 English | [简体中文](README_zh.md)
 
-[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.68+-green.svg)](https://fastapi.tiangolo.com)
 [![Next.js](https://img.shields.io/badge/Next.js-15+-black.svg)](https://nextjs.org)
 [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://docker.com)
@@ -232,8 +232,8 @@ wegent/
 1. **Backend Development**
    ```bash
    cd backend
-   pip install -r requirements.txt
-   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+   ./start.sh
+   # Or manually: uv sync && source .venv/bin/activate && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
    ```
 
 2. **Frontend Development**

README_zh.md

@@ -3,7 +3,7 @@
 
 [English](README.md) | 简体中文
 
-[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://python.org)
+[![Python](https://img.shields.io/badge/python-3.10+-blue.svg)](https://python.org)
 [![FastAPI](https://img.shields.io/badge/FastAPI-0.68+-green.svg)](https://fastapi.tiangolo.com)
 [![Next.js](https://img.shields.io/badge/Next.js-15+-black.svg)](https://nextjs.org)
 [![Docker](https://img.shields.io/badge/docker-ready-blue.svg)](https://docker.com)
@@ -234,8 +234,8 @@ wegent/
 1. **后端开发**
    ```bash
    cd backend
-   pip install -r requirements.txt
-   uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
+   ./start.sh
+   # 或手动执行: uv sync && source .venv/bin/activate && uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
    ```
 
 2. **前端开发**

backend/README.md

@@ -3,19 +3,57 @@ SPDX-FileCopyrightText: 2025 Weibo, Inc.
 
 SPDX-License-Identifier: Apache-2.0
 -->
+### Quick Start (Recommended)
 
-### Installation Steps
+Use the one-click startup script with uv for automatic setup:
+
+```bash
+cd backend
+./start.sh
+```
+
+The script will automatically:
+- Check Python version (3.10+ required)
+- Install uv if not present (fast Python package manager)
+- Install dependencies with uv
+- Configure environment variables
+- Check database and Redis connections
+- Set PYTHONPATH
+- Start the development server
+
+**Custom Port Usage:**
+```bash
+# Use custom backend port
+./start.sh --port 8080
+
+# Use custom database and Redis ports
+./start.sh --port 8080 --db-port 3307 --redis-port 6380
+
+# View all options
+./start.sh --help
+```
+
+**Port Validation:**
+- The script validates all port numbers (1-65535)
+- Checks if ports are already in use
+- Provides clear error messages with troubleshooting hints
+
+### Manual Installation Steps (uv-based)
+
+If you prefer manual setup:
+
+**Prerequisites:**
+- Python 3.10+
+- [uv](https://github.com/astral-sh/uv) installed
 
 1. Clone the repository
 ```bash
 cd backend
 ```
 
-2. Create virtual environment and install dependencies
+2. Install dependencies with uv
 ```bash
-python3 -m venv venv
-source venv/bin/activate  # Windows: venv\Scripts\activate
-pip install -r requirements.txt
+uv sync
 ```
 
 3. Configure environment variables
@@ -33,6 +71,7 @@ mysql -u root -p -e "CREATE DATABASE IF NOT EXISTS task_manager CHARACTER SET ut
 # Or manually run:
 alembic upgrade head
 ```
+```
 
 **Database Migration System:**
 - Wegent uses Alembic for database schema version control
@@ -73,8 +112,14 @@ alembic revision --autogenerate -m "description"
 
 For detailed migration documentation, see `alembic/README`.
 
-5. Run development server
+5. Set PYTHONPATH and run development server
 ```bash
+# From project root (Wegent directory)
+export PYTHONPATH=$(pwd):$PYTHONPATH
+
+# Navigate to backend and start
+cd backend
+source .venv/bin/activate  # Activate uv's virtual environment
 uvicorn app.main:app --reload
 ```