GUI Agent Specialist 是 OSS Agent Lab 中的一个专家模块，用于在本地契约测试中模拟 alibaba/page-agent 接口的一小部分行为。给定一条指令和 URL 字符串，它会生成登录表单夹具、返回动作状态记录，并对提供的表单数据应用简单的验证令牌。
用途 该模块主要用于本地契约测试，帮助开发者在不打开浏览器、不修改任何页面或远程服务的情况下，演练 GUI Agent 的检测、操作与表单响应管线。它适合需要验证 GUI 自动化契约、测试元素检测与交互状态映射、以及检查表单验证逻辑的场景。
主要能力
- gui_automation：使用夹具数据演练检测/操作/表单响应管线。
- web_interaction：将 click、type、hover、focus 或 clear 映射为合成状态。
- element_detection：使用描述词过滤内置元素目录。
- form_filling：应用本地字段规则并返回合成的就绪标志。
工具与参数
- detect_elements：生成并过滤登录表单夹具。参数为 url（必填，目标页面的完整 URL）和 description（可选，用于过滤检测元素的语义提示，默认 None）。无副作用。
- interact_element：为元素 ID 返回合成动作状态。参数为 element_id（必填，来自 detect_elements 的稳定元素 ID）、action（可选，"click" | "type" | "hover" | "focus" | "clear"，默认 "click"）、value（可选，当 action="type" 时必填，为要输入的文本）。无副作用。
- fill_form：对字段-值对应用本地验证规则。参数为 url（必填，承载表单页面的完整 URL）和 form_data（必填，字段标签到值的映射）。无副作用。
使用方式 前置条件：在本地 OSS Agent Lab 检出中使用 Python 3.11+，并运行 pip install -e .。仅提供测试专用值，不要在表单输入中放入真实密码、令牌或个人数据。
管线流程：SpecialistRequest → detect_elements(url, description) → interact_element(element_id, action, value?) → 当 parameters 中存在 form_data 时 → fill_form(url, form_data) → SpecialistResponse(result={detection, interaction, form?})。当 request.intent.parameters 中存在非空 form_data 键时触发表单填写。
操作说明：提供 URL 字符串和范围明确的自然语言元素描述；先调用检测再交互，且仅使用返回的合成元素 ID；仅使用非敏感测试数据进行表单填写；将所有元素、动作、时序和就绪字段报告为模拟结果。
示例 Python API： from agents.specialists.gui_agent.agent import GuiAgentSpecialist from oss_agent_lab.contracts import Intent, Query, SpecialistRequest
specialist = GuiAgentSpecialist()
request = SpecialistRequest( intent=Intent( action="click", domain="web_interaction", confidence=0.95, parameters={"url": "https://example.com/login", "description": "sign in button"}, ), query=Query(user_input="click the sign in button"), specialist_name="gui_agent", )
response = await specialist.execute(request) print(response.result["interaction"]["element_state"])
CLI： oss-lab run gui_agent "click the sign in button on https://example.com/login"
表单填写示例： request = SpecialistRequest( intent=Intent( action="fill_form", domain="gui_automation", confidence=0.90, parameters={ "url": "https://example.com/signup", "form_data": {"email": "user@example.com", "password": "s3cr3t"}, }, ), query=Query(user_input="fill the signup form"), specialist_name="gui_agent", )
response = await specialist.execute(request) print(response.result["form"]["submit_ready"])
独立元素检测示例： from agents.specialists.gui_agent.tools import detect_elements
result = detect_elements( url="https://example.com/login", description="email field", ) print(result["elements"]) print(f"Found {result['element_count']} element(s)")
输出示例： { "url": "https://example.com/login", "description": "sign in button", "detection": { "elements": [ {"id": "elem-a1b2c3d4", "type": "button", "text": "Sign in", "selector": "button[type='submit']"} ], "page_title": "Page at example.com — detected via page-agent (sign_in_button)", "element_count": 1 }, "interaction": { "success": true, "action_performed": "click", "element_state": "clicked", "response_time_ms": 42.5 }, "form": { "fields_filled": 2, "success": true, "validation_errors": [], "submit_ready": true } }
适用场景 适用于本地契约测试、GUI 自动化管线的模拟验证、元素检测与交互状态映射的单元测试，以及表单验证逻辑的离线检查。
限制 当前实现从不打开 URL，不联系页面或服务，不进行网络或浏览器操作，因此不会重试网络或浏览器操作。认证：无。不要输入实时凭据；表单值会被回显到合成状态中，仅适合非敏感测试数据。错误处理：拒绝空 URL 或元素 ID 值以及不支持的动作；type 动作需要 value；报告表单验证错误时不会声称远程表单已更改。该本地专家是模拟器，不是嵌入的 page-agent 运行时。