test-env-setup

测试环境自动准备（test-env-setup）

使命：让「说一句话就能开始测试」成为现实。 在测试智能体开始执行任何测试用例之前，自动完成所有环境准备工作。 若环境不可修复，输出明确的人工干预指引，不静默失败。

知识导航表

激活后立即执行

Step 0  【读取项目配置】
        先尝试读取 .cursor/test-config.md（项目专属配置）
        IF 不存在：使用智能推断（见后文「自动推断逻辑」）

Step 1  【后端服务健康检查 + 自动启动】

        1.1 检查服务是否在目标端口响应：
        ```bash
        curl -s --max-time 3 http://localhost:[PORT]/health 2>/dev/null
        ```
        
        IF 响应正常（含 "ok" 或 HTTP 200）：
          → 输出「✅ 后端服务正常（端口 [PORT]）」
          → 跳到 Step 2
        
        IF 无响应：
          1.2 检查是否有进程占用端口：
          ```bash
          lsof -i :[PORT] 2>/dev/null | head -5
          ```
          
          IF 有进程但未响应 → kill 并重启：
          ```bash
          pkill -f "uvicorn.*[PORT]" 2>/dev/null || true
          pkill -f "node.*[PORT]" 2>/dev/null || true
          sleep 2
          ```
          
          1.3 自动启动服务（根据技术栈）：
          
          FastAPI/Python 项目：
          ```bash
          cd [项目根目录]
          # 激活虚拟环境（优先 .venv，其次 venv，其次系统 Python）
          PYTHON=$([ -f .venv/bin/python ] && echo .venv/bin/python || \
                   [ -f venv/bin/python ] && echo venv/bin/python || \
                   echo python3)
          # 后台启动，日志写入 /tmp/test-backend.log
          nohup $PYTHON -m uvicorn backend.app.main:app \
            --host 0.0.0.0 --port [PORT] --workers 1 \
            > /tmp/test-backend.log 2>&1 &
          echo "启动PID: $!"
          ```
          
          Node.js/Next.js 项目：
          ```bash
          cd [项目根目录]
          nohup npm run dev > /tmp/test-frontend.log 2>&1 &
          ```
          
          1.4 等待服务就绪（最多 30 秒）：
          ```bash
          for i in $(seq 1 10); do
            sleep 3
            curl -s http://localhost:[PORT]/health && echo "✅ 服务就绪" && break
            echo "等待中... ($i/10)"
          done
          ```
          
          IF 30 秒后仍无响应：
          → 读取启动日志诊断：cat /tmp/test-backend.log | tail -20
          → 输出错误信息和诊断建议
          → 停止，输出：「❌ 后端服务无法自动启动，需要人工检查」
          → 附上日志内容供人工排查

Step 2  【数据库连接验证】
        ```bash
        # 通过服务健康端点间接验证 DB
        curl -s http://localhost:[PORT]/config-check 2>/dev/null | python3 -c "
        import sys, json
        d = json.load(sys.stdin)
        print('DB:', '✅' if d.get('db_configured') else '❌')
        " 2>/dev/null || echo "config-check 端点不可用（跳过DB验证）"
        ```
        
        IF DB 未连接（db_configured=false）：
          → 尝试启动数据库（如有 docker-compose）：
          ```bash
          docker-compose -f docker-compose.dev.yml up -d postgres 2>/dev/null || true
          sleep 5
          ```
          → 重新检查
          IF 仍然无法连接 → 输出「❌ 数据库连接失败，需要人工检查」

Step 3  【测试账号验证 + 自动创建（完整 Persona 体系）】
        
        需要创建以下 4 类测试人格账号（Personas）：
        
        ```python
        # 测试 Persona 定义（从 test-config.md 读取，以下为默认值）
        PERSONAS = [
            # admin：管理员，生成邀请码
            {"phone": "10000000001", "password": "admin2026",
             "role": "admin",    "handle": "test_admin", "display_name": "测试管理员"},