multi-env-isolator（多环境隔离器）

Multi-Environment Isolator

Generate isolated dev/test/prod environments for uvicorn/FastAPI projects with frontend support (Vue/React) with one command.

What This Skill Does

This skill solves a common problem in multi-agent AI teams: developers, testers, and production users stepping on each other's toes. It generates a complete environment isolation setup so that:

• Valina (Developer) can freely break things on ports 8000/3000 without affecting anyone
• Choco (Tester) can validate releases on ports 8001/3001 with isolated test data and Playwright tests
• Production stays stable on ports 8002/4173, untouched by dev/test activity

Each environment gets its own config file, startup scripts (backend + frontend), database, media storage, and Playwright test configuration — completely isolated from the others.

What Gets Generated

Running the setup script creates this structure inside the target project:

your-project/
├── .env.dev              # Dev config: DEBUG=True, hot reload, no rate limit
├── .env.test             # Test config: rate limiting enabled, QA settings
├── .env.prod             # Prod config: DEBUG=False, secure CORS, multi-worker
├── scripts/
│   # Backend scripts
│   ├── start-backend-dev.sh    # Starts dev server on port 8000 with --reload
│   ├── start-backend-test.sh   # Starts test server on port 8001
│   └── start-backend-prod.sh   # Starts prod server on port 8002 with auto workers
│   # Frontend scripts (Vue/React)
│   ├── start-frontend-dev.sh   # Starts dev frontend on port 3000
│   ├── start-frontend-test.sh  # Starts test frontend on port 3001
│   └── start-frontend-prod.sh  # Starts prod frontend on port 4173 (preview)
│   # Test scripts
│   └── run-playwright-tests.sh # Runs Playwright E2E tests on test environment
├── data/
│   ├── dev/              # Dev database + media uploads (safe to delete)
│   │   └── media/
│   ├── test/             # Test database + media uploads
│   │   └── media/
│   └── prod/             # Prod database + media uploads (back this up!)
│       └── media/
├── docs/
│   └── MULTI_ENV_SETUP.md  # Auto-generated setup guide for the team
├── cloud_docs/frontend/
│   └── playwright.config.ts  # Playwright test config (if frontend exists)
└── .gitignore            # Updated to exclude .env.* and data/

How to Use

Step 1: Run the setup script

python3 scripts/setup_envs.py /path/to/your-project \
  --name "Your Project Name" \
  --dev-backend-port 8000 \
  --dev-frontend-port 3000 \
  --test-backend-port 8001 \
  --test-frontend-port 3001 \
  --prod-backend-port 8002 \
  --prod-frontend-port 4173 \
  --dev-user "Valina" \
  --test-user "Choco" \
  --app-module "server.main:app" \
  --frontend-dir "cloud_docs/frontend"

All flags except --name are optional and have sensible defaults.

Step 2: Start environments

# For Valina (Development)
./scripts/start-dev.sh        # Starts both backend (8000) and frontend (3000)

# For Choco (Testing)
./scripts/start-test.sh       # Starts both backend (8001) and frontend (3001)
./scripts/run-playwright-tests.sh  # Runs E2E tests

# For Production
./scripts/start-prod.sh       # Starts both backend (8002) and frontend (4173)

Step 2: Customize configs

Edit the generated .env.dev, .env.test, .env.prod files to add project-specific settings like API keys, external service URLs, etc.

Step 3: Start an environment

# For development (hot reload enabled)
./scripts/start-dev.sh

# For testing
./scripts/start-test.sh

# For production
./scripts/start-prod.sh

Each script loads its own .env.* file, uses its own port, and writes to its own data/ subdirectory.

Command Reference

python3 scripts/setup_envs.py <project_dir> --name <name> [options]

Environment Differences at a Glance

Recommended Git Branch Strategy

For teams using this setup:

main ──────────── Production (start-prod.sh) - Ports 8002/4173
  ├── release/* ── Testing (start-test.sh + run-playwright-tests.sh) - Ports 8001/3001
  └── feature/* ── Development (start-dev.sh) - Ports 8000/3000

1. Valina (Developer) works on feature/*, deploys to dev environment (8000/3000)
2. Merge to release/*, Choco (Tester) validates on test environment (8001/3001)
3. Choco runs Playwright tests: ./scripts/run-playwright-tests.sh
4. Tester approves, merge to main, deploy to production (8002/4173)

Parallel Development and Testing

Key benefit: Valina and Choco can work simultaneously without conflicts!

Time  | Valina (Dev)              | Choco (Test)
------|---------------------------|---------------------------
14:00 | start-dev.sh (8000/3000)  | -
14:05 | Continue coding...        | start-test.sh (8001/3001)
14:10 | Continue coding...        | run-playwright-tests.sh
14:20 | Continue coding...        | Tests pass! Report results
14:25 | Continue coding...        | stop-test.sh

No port conflicts! No data interference! ✅

Important Notes

• Existing files are not overwritten. If .env.dev already exists, the script skips it and prints a warning. Safe to re-run.
• Backend startup scripts are uvicorn-specific. The generated start-backend-*.sh scripts use uvicorn commands. For other frameworks, modify the scripts after generation.
• Frontend scripts support Vue/React. The generated start-frontend-*.sh scripts use npm run dev and npm run preview. For Vite projects, they work out of the box.
• Production JWT secret must be changed. The generated .env.prod has a placeholder JWT_SECRET. Replace it with a strong random value before going live.
• Back up production data. The data/prod/ directory contains the production database. Set up regular backups.
• Playwright tests require Node.js. The test script requires Playwright to be installed: npm install -D @playwright/test
• Test data cleanup. After running Playwright tests, consider cleaning up test data to keep the test environment clean.

Detailed Config Reference

For all environment variables and troubleshooting: read references/config-options.md