使用者介面自動化 - AgentBay

本文介紹無影 AgentBay SDK 在案頭環境中的雲電腦使用者介面自動化功能，包括滑鼠操作、鍵盤操作和螢幕操作。

概述

Computer Use模組提供強大的雲電腦使用者介面自動化功能，包括：

滑鼠操作 - 精確控制點擊、移動、拖拽和滾動。
鍵盤操作 - 輸入文本和發送按鍵組合。
螢幕操作 - 截取螢幕快照並擷取螢幕資訊。

建立會話

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
# 使用 windows_latest 或 linux_latest
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

滑鼠操作

點擊操作

click_mouse() 方法支援多種點擊類型。可以使用 MouseButton 枚舉確保型別安全。支援以下按鈕類型：

MouseButton.LEFT
MouseButton.RIGHT
MouseButton.MIDDLE
MouseButton.DOUBLE_LEFT

from agentbay.computer import MouseButton

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# 左鍵點擊
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.LEFT)
if result.success:
    print("左鍵點擊成功")
# 輸出: 左鍵點擊成功

# 右鍵點擊
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.RIGHT)
if result.success:
    print("右鍵點擊成功")
# 輸出: 右鍵點擊成功

# 中鍵點擊
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.MIDDLE)
if result.success:
    print("中鍵點擊成功")
# 輸出: 中鍵點擊成功

# 左鍵雙擊
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.DOUBLE_LEFT)
if result.success:
    print("左鍵雙擊成功")
# 輸出: 左鍵雙擊成功

agent_bay.delete(session)

移動滑鼠

將滑鼠游標移動至指定座標。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.move_mouse(x=600, y=400)
if result.success:
    print("滑鼠移動成功")
# 輸出: 滑鼠移動成功

agent_bay.delete(session)

滑鼠拖拽

使用 MouseButton 枚舉，將滑鼠從一個點拖拽至另一個點，支援以下按鈕類型：

MouseButton.LEFT
MouseButton.RIGHT
MouseButton.MIDDLE

from agentbay.computer import MouseButton

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# 左鍵拖拽
result = session.computer.drag_mouse(
    from_x=100, 
    from_y=100, 
    to_x=200, 
    to_y=200, 
    button=MouseButton.LEFT
)
if result.success:
    print("拖拽操作成功")
# 輸出: 拖拽操作成功

agent_bay.delete(session)

滾輪滾動

使用 ScrollDirection 枚舉，在特定座標處滾動滑鼠滾輪。支援以下方向：

ScrollDirection.UP
ScrollDirection.DOWN
ScrollDirection.LEFT
ScrollDirection.RIGHT

from agentbay.computer import ScrollDirection

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# 向上滾動
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.UP, amount=3)
if result.success:
    print("向上滾動成功")
# 輸出: 向上滾動成功

# 向下滾動
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.DOWN, amount=5)
if result.success:
    print("向下滾動成功")
# 輸出: 向下滾動成功

agent_bay.delete(session)

擷取游標位置

import json

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.get_cursor_position()
if result.success:
    cursor_data = json.loads(result.data)
    print(f"游標位於 x={cursor_data['x']}, y={cursor_data['y']}")
# 輸出: 游標位於 x=512, y=384

agent_bay.delete(session)

鍵盤操作

文本輸入

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.input_text("Hello AgentBay!")
if result.success:
    print("文本輸入成功")
# 輸出: 文本輸入成功

agent_bay.delete(session)

按鍵動作

按鍵組合輸入，支援修飾鍵。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# 按下 Ctrl+A 全選
result = session.computer.press_keys(keys=["Ctrl", "a"])
if result.success:
    print("按鍵動作成功")
# 輸出: 按鍵動作成功

# 按下 Ctrl+C 複製
result = session.computer.press_keys(keys=["Ctrl", "c"])
if result.success:
    print("複製命令已發送")
# 輸出: 複製命令已發送

agent_bay.delete(session)

釋放按鍵

當按鍵hold=True時，雲電腦將持續按住該鍵位，相關操作完成後需要釋放按鍵，避免與其它按鍵動作衝突。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# 按住 Ctrl 鍵
session.computer.press_keys(keys=["Ctrl"], hold=True)

# ... 執行其他動作 ...

# 釋放 Ctrl 鍵
result = session.computer.release_keys(keys=["Ctrl"])
if result.success:
    print("按鍵釋放成功")
# 輸出: 按鍵釋放成功

agent_bay.delete(session)

螢幕操作

截圖

截取當前螢幕快照。截圖儲存到雲端儲存中並返回下載URL。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"截圖URL: {screenshot_url}")
# 輸出: 截圖URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***

agent_bay.delete(session)

擷取螢幕尺寸

import json

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.get_screen_size()
if result.success:
    screen_data = json.loads(result.data)
    print(f"螢幕寬度: {screen_data['width']}")
    print(f"螢幕高度: {screen_data['height']}")
    print(f"DPI縮放因子: {screen_data['dpiScalingFactor']}")
# 輸出：螢幕寬度：1024
# 輸出：螢幕高度：768
# 輸出：DPI縮放因子：1.0

agent_bay.delete(session)

故障排除

常見問題

"Tool not found"錯誤。
- 確保使用的是雲電腦鏡像 (windows_latest 或 linux_latest)。
如何處理截圖產生後返回的下載連結（URL）。
- 截圖將自動儲存至雲端儲存中 (OSS)。
- result.data 包含下載URL，而不是映像資料。
- 可使用該URL下載截圖。