v0.2.0: Two-phase Planning, GPT-5 Responses API & Enhanced Execution

Author: mmmay0722

.python-version

@@ -0,0 +1 @@
+3.11

README.md

@@ -92,11 +92,16 @@ git clone https://github.com/MigoXLab/webqa-agent.git
 cd webqa-agent
 ```
 
-Install Python >= 3.10 and run the following commands:
+1. Recommended: Install dependencies with [uv](https://github.com/astral-sh/uv) (Python>=3.11):
 
 ```bash
-pip install -r requirements.txt
-playwright install
+uv sync
+```
+
+2. Install Chromium browser:
+
+```bash
+uv run playwright install chromium
 ```
 
 Performance Analysis - Lighthouse (Optional)
@@ -124,9 +129,25 @@ nuclei -version        # Verify successful installation
 After configuring `config/config.yaml` (refer to "Usage > Test Configuration"), run:
 
 ```bash
-python webqa-agent.py
+uv run python webqa-agent.py
 ```
 
+### 🖥️ Visual Web Interface
+
+WebQA Agent provides a user-friendly visual interface powered by Gradio.
+
+```bash
+# Install Gradio
+uv add "gradio>5.44.0"
+# Launch the Web UI
+uv run python app.py
+
+# Launch with Chinese interface
+GRADIO_LANGUAGE=zh-CN uv run python app.py
+```
+
+Access the interface at http://localhost:7860.
+
 ## Usage
 
 ### Test Configuration
@@ -192,14 +213,14 @@ UX (User Experience) testing focuses on usability and user-friendliness. Uses mu
 
 ### 🧠 Recommended Models
 
-Based on our testing, these models work well with WebQA Agent:
+The following models have been adapted and verified, and are recommended:
 
-| Model                             | Key Strengths               | Notes                           |
-|-----------------------------------|-----------------------------|---------------------------------|
-| **gpt-4.1-2025-04-14** ⭐         | High accuracy & reliability | **Best choice**                 |
-| **gpt-4.1-mini-2025-04-14**       | Cost-effective              | **Economical and practical**    |
-| **qwen3-vl-235b-a22b-instruct**   | Open-source, GPT-4.1 level  | **Best for on-premise**         |
-| **doubao-seed-1-6-vision-250815** | Vision capabilities         | **Excellent web understanding** |
+| Model                             | Recommendation              |
+|-----------------------------------|-----------------------------|
+| **gpt-4.1-2025-04-14**            | High accuracy and reliability |
+| **gpt-4.1-mini-2025-04-14**       | Economical and practical |
+| **qwen3-vl-235b-a22b-instruct**   | Open-source model, preferred for on-premise |
+| **doubao-seed-1-6-vision-250815** | Good web understanding, supports visual recognition |
 
 
 ### View Results

README_zh-CN.md

@@ -23,7 +23,7 @@
 
 <p align="center">
   体验Demo 🤗<a href="https://huggingface.co/spaces/mmmay0722/WebQA-Agent">HuggingFace</a> | 🚀<a href="https://modelscope.cn/studios/mmmmei22/WebQA-Agent/summary">ModelScope</a><br>
-  加入我们 🎮<a href="https://discord.gg/K5TtkVcx">Discord</a> | 💬<a href="https://aicarrier.feishu.cn/docx/NRNXdIirXoSQEHxhaqjchUfenzd">微信群</a>
+  加入我们 🎮<a href="https://discord.gg/fG5QAxYyNr">Discord</a> | 💬<a href="https://aicarrier.feishu.cn/docx/NRNXdIirXoSQEHxhaqjchUfenzd">微信群</a>
 </p>
 
 <p align="center"><a href="README.md">English</a> · <a href="README_zh-CN.md">简体中文</a></p>
@@ -92,20 +92,23 @@ git clone https://github.com/MigoXLab/webqa-agent.git
 cd webqa-agent
 ```
 
-安装 Python >= 3.10，运行以下命令：
+1. 推荐使用 [uv](https://github.com/astral-sh/uv) 安装依赖（Python>=3.11）：
 
 ```bash
-pip install -r requirements.txt
-playwright install
+uv sync
+```
+
+2. 安装 Chromium 浏览器：
 
+```bash
+uv run playwright install chromium
 ```
 
 性能分析 - Lighthouse 安装（可选）
 
 ```bash
-# 需要 Node.js >= 18.0.0 package.json
+# 需要 Node.js >= 18.0.0
 npm install
-
 ```
 
 安全扫描 - Nuclei 安装（可选）
@@ -124,12 +127,28 @@ nuclei -version        # 验证安装成功
 
 ```
 
-参考“使用说明 > 测试配置”进行 `config/config.yaml` 配置后，运行下方命令。
+参考"使用说明 > 测试配置"进行 `config/config.yaml` 配置后，运行下方命令。
 
 ```bash
-python webqa-agent.py
+uv run python webqa-agent.py
 ```
 
+### 🖥️ 可视化 Web 界面
+
+WebQA Agent 提供了基于 Gradio 的可视化界面，操作更加便捷。
+
+```bash
+# 安装 Gradio
+uv add "gradio>5.44.0"
+# 启动 Web UI
+uv run python app.py
+
+# 启动中文界面
+GRADIO_LANGUAGE=zh-CN uv run python app.py
+```
+
+访问地址：http://localhost:7860。
+
 ## 使用说明
 
 ### 测试配置
@@ -195,14 +214,14 @@ UX（用户体验）评估关注网页可用性与友好性。采用多模态分
 
 ### 🧠 推荐模型
 
-基于实际测试结果，以下模型表现较好，推荐使用：
+以下模型经过适配与验证，推荐使用：
 
-| 模型                                | 核心优势         | 使用建议       |
-|-----------------------------------|--------------|------------|
-| **gpt-4.1-2025-04-14** ⭐          | 高准确性与可靠性     | **最佳选择**   |
-| **gpt-4.1-mini-2025-04-14**       | 性价比高         | **经济实用**   |
-| **qwen3-vl-235b-a22b-instruct**   | 媲美gpt-4.1，开源 | **私有部署首选** |
-| **doubao-seed-1-6-vision-250815** | 支持视觉识别       | **网页理解优异** |
+| 模型                                | 推荐理由 |
+|-----------------------------------|------|
+| **gpt-4.1-2025-04-14**            | 准确性与可靠性较高 |
+| **gpt-4.1-mini-2025-04-14**       | 经济实用，性价比高 |
+| **qwen3-vl-235b-a22b-instruct**   | 开源模型，私有部署首选 |
+| **doubao-seed-1-6-vision-250815** | 网页理解较优异，支持视觉识别 |
 
 ### 查看结果
 

app.py

@@ -27,6 +27,24 @@ def get_gradio_language():
 
 # Import and launch Gradio application
 if __name__ == "__main__":
+    # Check Gradio installation and version
+    try:
+        import gradio
+    except ImportError:
+        print("❌ Error: Gradio is not installed.")
+        print("Please install Gradio: uv add \"gradio>5.44.0\"")
+        sys.exit(1)
+
+    try:
+        from packaging import version
+        required_gradio_version = "5.44.0"
+        if version.parse(gradio.__version__) <= version.parse(required_gradio_version):
+            print(f"❌ Error: Gradio version {gradio.__version__} is installed, but > {required_gradio_version} is required.")
+            print(f"Please upgrade Gradio: uv add \"gradio>{required_gradio_version}\"")
+            sys.exit(1)
+    except ImportError:
+        pass  # packaging not found, skip version check
+
     try:
         from app_gradio.demo_gradio import create_gradio_interface, queue_manager, process_queue
         import threading
@@ -36,7 +54,7 @@ def get_gradio_language():
         print("📱 Interface will start at http://localhost:7860")
         print(f"🌐 Interface language: {GRADIO_LANGUAGE}")
         print("💡 Tip: Set environment variable GRADIO_LANGUAGE=en-US for English or GRADIO_LANGUAGE=zh-CN for Chinese")
-        print("⚠️  Note: Please ensure all dependencies are installed (pip install -r requirements.txt)")
+        print("⚠️  Note: Please ensure all dependencies are installed (uv sync)")
         print("🔍 Checking Playwright browser dependencies...")
 
         async def _check_playwright():

config/config.yaml.example

@@ -27,6 +27,11 @@ llm_config: # LLM configuration, currently only supports OpenAI SDK compatible f
   temperature: 0.1   # Optional, default 0.1
   # top_p: 0.9       # Optional, if not set, this parameter will not be passed
   # max_tokens: 8192  # Optional, maximum output tokens (supports generating more test cases)
+  # GPT-5 family reasoning & text verbosity configuration (optional)
+  # reasoning:
+  #   effort: none    # none | low | medium | high (gpt-5.1 defaults to 'none' for low-latency)
+  # text:
+  #   verbosity: medium  # low | medium | high (default 'medium')
 
 browser_config:
   viewport: {"width": 1280, "height": 720}

package.json

@@ -1,7 +1,7 @@
 {
   "name": "webqa-agent",
-  "version": "0.1.0",
-  "description": "WebQA Agent - 全自动网页评估测试",
+  "version": "0.2.0",
+  "description": "WebQA Agent is an autonomous web browser agent that audits performance, functionality & UX for engineers and vibe-coding creators.",
   "dependencies": {
     "chrome-launcher": "^1.2.0",
     "lighthouse": "^12.8.1"

pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "webqa-agent"
+version = "0.2.0"
+description = "WebQA Agent is an autonomous web browser agent that audits performance, functionality & UX for engineers and vibe-coding creators."
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "html2text>=2025.4.15",
+    "jinja2>=3.1.6",
+    "langchain==0.3.26",
+    "langchain-core==0.3.68",
+    "langchain-openai==0.3.27",
+    "langgraph==0.5.1",
+    "langgraph-checkpoint==2.1.0",
+    "openai>=1.93.0",
+    "pillow==11.3.0",
+    "playwright==1.52.0",
+    "pydantic==2.9.2",
+    "pytest>=8.4.1",
+    "pytest-asyncio>=1.3.0",
+    "python-dotenv>=1.1.1",
+    "pyyaml>=6.0.2",
+    "requests>=2.32.4",
+    "typing-extensions==4.14.0",
+]

requirements.txt

@@ -1,15 +1,17 @@
-html2text
-jinja2
-langchain
-langchain-openai
-langgraph
-openai
+html2text==2025.4.15
+jinja2==3.1.6
+langchain==0.3.26
+langchain-core==0.3.68
+langchain-openai==0.3.27
+langgraph==0.5.1
+langgraph-checkpoint==2.1.0
+openai==1.93.0
+pillow==11.3.0
 playwright==1.52.0
-pydantic
-pytest
-pytest-asyncio
-python-dotenv
-requests
-pillow
-gradio
-pyyaml
+pydantic==2.9.2
+pytest==8.4.1
+pytest-asyncio==1.3.0
+python-dotenv==1.1.1
+requests==2.32.4
+pyyaml==6.0.2
+typing-extensions==4.14.0

tests/mocks/action_mocks.json

@@ -336,56 +336,53 @@
       "actions": [
         {
           "type": "Scroll",
-          "locate": null,
-          "param": {
-            "direction": "down",
-            "scrollType": "untilBottom",
-            "distance": null
-          }
+          "locate": {"id": "1"},
+          "param": null
         },
         {
           "type": "Scroll",
-          "locate": null,
-          "param": {
-            "direction": "up",
-            "scrollType": "untilTop",
-            "distance": null
-          }
+          "locate": {"id": "2"},
+          "param": null
         }
       ],
-      "id_map": {}
+      "id_map": {
+        "1": {
+          "id": 100,
+          "tagName": "footer",
+          "isInViewport": false,
+          "selector": "footer#site-footer",
+          "xpath": "//*[@id=\"site-footer\"]",
+          "center_y": 2000
+        },
+        "2": {
+          "id": 101,
+          "tagName": "header",
+          "isInViewport": false,
+          "selector": "header#site-header",
+          "xpath": "//*[@id=\"site-header\"]",
+          "center_y": 50
+        }
+      }
     },
     {
       "url": "https://arxiv.org/list/astro-ph/new",
       "actions": [
         {
           "type": "Scroll",
-          "locate": null,
-          "param": {
-            "direction": "down",
-            "scrollType": "once"
-          }
-        },
-        {
-          "type": "Scroll",
-          "locate": null,
-          "param": {
-            "direction": "down",
-            "scrollType": "once",
-            "distance": 400
-          }
-        },
-        {
-          "type": "Scroll",
-          "locate": null,
-          "param": {
-            "direction": "up",
-            "scrollType": "once",
-            "distance": 200
-          }
+          "locate": {"id": "1"},
+          "param": null
         }
       ],
-      "id_map": {}
+      "id_map": {
+        "1": {
+          "id": 200,
+          "tagName": "section",
+          "isInViewport": false,
+          "selector": "section.results",
+          "xpath": "//section[@class='results']",
+          "center_y": 1500
+        }
+      }
     }
   ],
   "SelectDropdown": [