v5.0-C 移动端AI分析(提示词+截图分析API+步骤验证+测试脚本生成)

Author: zcj220

src/api/routes.py

@@ -791,6 +791,60 @@ async def close_mobile_session(session_id: str) -> dict:
         except Exception as e:
             return {"message": f"关闭时出错: {e}"}
 
+    @router.post("/mobile/session/{session_id}/analyze", tags=["手机测试"])
+    async def mobile_analyze(session_id: str, req: dict = None) -> dict:
+        """截图并用AI分析手机当前页面。
+
+        Body (可选):
+            context: 额外上下文描述
+            expected: 预期结果（用于步骤验证模式）
+        """
+        ctrl = _mobile_sessions.get(session_id)
+        if not ctrl:
+            raise HTTPException(status_code=404, detail="会话不存在")
+        if not ai_client:
+            raise HTTPException(status_code=503, detail="AI客户端未配置")
+
+        req = req or {}
+        try:
+            # 截图
+            path = await ctrl.screenshot("ai_analyze")
+
+            # AI分析
+            from src.core.prompts import (
+                SYSTEM_MOBILE_ANALYZER,
+                PROMPT_MOBILE_ANALYZE,
+                PROMPT_MOBILE_VERIFY_STEP,
+            )
+
+            context = req.get("context", "用户手机当前屏幕")
+            expected = req.get("expected", "")
+
+            if expected:
+                prompt = PROMPT_MOBILE_VERIFY_STEP.format(
+                    expected=expected,
+                    action_description=req.get("action_description", ""),
+                )
+            else:
+                prompt = PROMPT_MOBILE_ANALYZE.format(context=context)
+
+            analysis = ai_client.analyze_screenshot(
+                image_path=str(path),
+                prompt=prompt,
+                system_prompt=SYSTEM_MOBILE_ANALYZER,
+            )
+
+            import base64 as b64mod
+            img_b64 = b64mod.b64encode(path.read_bytes()).decode()
+
+            return {
+                "screenshot_path": str(path),
+                "screenshot_base64": img_b64,
+                "analysis": analysis,
+            }
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"分析失败: {e}")
+
     @router.get("/mobile/sessions", tags=["手机测试"])
     async def list_mobile_sessions() -> dict:
         """列出所有活跃的手机测试会话。"""

src/core/prompts.py

@@ -387,3 +387,91 @@
 1. 从HTML中提取所有可交互元素（表单、按钮、链接等），生成 elements 映射
 2. 根据页面功能设计测试场景
 3. 输出完整的 testpilot.json（JSON格式）"""
+
+
+# ── 移动端截图分析（v5.0）────────────────────────────
+
+SYSTEM_MOBILE_ANALYZER = """你是 TestPilot AI 的移动端视觉分析引擎。
+你的任务是分析手机App截图，识别UI元素、检测Bug、评估用户体验。
+
+你必须严格按照以下JSON格式返回，不要包含任何其他文字：
+
+```json
+{
+  "app_name": "识别到的应用名称",
+  "screen_type": "页面类型(首页/登录/列表/详情/设置/弹窗/其他)",
+  "elements": [
+    {"type": "button", "text": "按钮文字", "position": "位置描述"},
+    {"type": "input", "text": "输入框提示", "position": "位置描述"},
+    {"type": "text", "text": "文本内容", "position": "位置描述"}
+  ],
+  "issues": [
+    {"severity": "high/medium/low", "description": "问题描述", "suggestion": "修复建议"}
+  ],
+  "ux_score": 8,
+  "ux_comments": "用户体验评价",
+  "matches_expected": true,
+  "confidence": 0.95
+}
+```
+
+移动端特有的检查项：
+1. 触摸目标是否足够大（至少44x44dp）
+2. 文字大小是否适合手机阅读（不小于12sp）
+3. 是否有适配刘海屏/底部导航栏
+4. 滚动内容是否有合理边距
+5. 弹窗/Toast是否遮挡关键内容
+6. 深色/浅色模式是否正常
+7. 横竖屏切换后布局是否正常
+8. 加载状态是否有骨架屏或loading提示"""
+
+PROMPT_MOBILE_ANALYZE = """请分析这张手机App截图：
+
+{context}
+
+请识别页面类型、可交互元素、潜在问题，并给出UX评分（1-10分）。"""
+
+PROMPT_MOBILE_VERIFY_STEP = """请验证这张手机截图是否符合预期：
+
+预期结果：{expected}
+操作描述：{action_description}
+
+请判断截图是否符合预期，返回JSON格式结果。"""
+
+SYSTEM_MOBILE_TEST_GENERATOR = """你是 TestPilot AI 的移动端测试脚本生成引擎。
+你的任务是根据手机App截图和描述，生成结构化的移动端测试步骤。
+
+你必须严格按照以下JSON格式返回：
+
+```json
+{
+  "test_name": "测试名称",
+  "platform": "android",
+  "steps": [
+    {
+      "step": 1,
+      "action": "tap",
+      "target": "//android.widget.Button[@text='登录']",
+      "value": "",
+      "description": "点击登录按钮",
+      "expected": "弹出登录对话框"
+    }
+  ]
+}
+```
+
+支持的 action 类型（移动端）：
+- tap: 点击元素（target为xpath/id/accessibility_id）
+- input: 输入文本（target为选择器，value为文本）
+- swipe: 滑动（target为方向up/down/left/right，value为距离）
+- long_press: 长按（target为选择器）
+- back: 返回（target为空）
+- screenshot: 截图验证（target为空）
+- navigate: 打开Activity或URL（target为Activity名或URL）
+- wait: 等待元素出现（target为选择器）
+
+选择器格式：
+- xpath: //android.widget.Button[@text='确定']
+- id: id:com.example.app:id/btn_login
+- accessibility_id: accessibility_id:登录按钮
+- class: class:android.widget.EditText"""