視窗管理 - AgentBay

本文介紹使用無影 AgentBay SDK 對雲電腦進行視窗管理的相關能力。如何控制視窗狀態、位置以及焦點，並與雲環境中的桌面視窗進行互動。

概述

Computer Use模組為案頭環境提供全面的視窗管理功能，包括：

視窗發現 - 列出並尋找系統中的視窗。
視窗狀態控制 - 最大化、最小化、恢複與關閉視窗。
視窗定位 - 調整視窗大小與重新置放。
焦點管理 - 控制視窗焦點與啟用狀態。
案頭自動化 - 構建複雜的案頭自動化工作流程。

建立會話

建立具有案頭環境的會話。

import os
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY 環境變數是必需的")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="linux_latest")
result = agent_bay.create(params)

if result.success:
    session = result.session
    print(f"會話已建立: {session.session_id}")
else:
    print(f"建立會話失敗: {result.error_message}")
    exit(1)

列出視窗

擷取案頭環境中所有可用視窗的資訊。

result = session.computer.list_root_windows(timeout_ms=5000)

if result.success:
    windows = result.windows
    print(f"找到 {len(windows)} 個視窗")
    # 執行結果: 找到 0 個視窗 (當沒有開啟視窗時)
    # 或: 找到 5 個視窗 (當應用程式正在運行時)
    
    for window in windows:
        print(f"標題: {window.title}")
        # 執行結果: 標題: Google Chrome
        print(f"視窗ID: {window.window_id}")
        # 執行結果: 視窗ID: 12345678
        print(f"進程: {window.pname if window.pname else 'N/A'}")
        # 執行結果: 進程: chrome
        print(f"PID: {window.pid if window.pid else 'N/A'}")
        # 執行結果: PID: 9876
        print(f"位置: ({window.absolute_upper_left_x}, {window.absolute_upper_left_y})")
        # 執行結果: 位置: (100, 50)
        print(f"尺寸: {window.width}x{window.height}")
        # 執行結果: 尺寸: 1280x720
        print(f"子視窗: {len(window.child_windows)}")
        # 執行結果: 子視窗: 0
        print("---")
else:
    print(f"列出視窗時出錯：{result.error_message}")

參數:

timeout_ms (int, 可選): 逾時時間（毫秒）。預設為 3000。

視窗對象屬性:

window_id (int): 視窗的唯一識別碼。
title (str): 視窗標題/解說文字。
absolute_upper_left_x (Optional[int]): 視窗左上方的X座標。
absolute_upper_left_y (Optional[int]): 視窗左上方的Y座標。
width (Optional[int]): 視窗寬度（像素）。
height (Optional[int]): 視窗高度（像素）。
pid (Optional[int]): 擁有該視窗的進程ID。
pname (Optional[str]): 擁有該視窗的進程名稱。
child_windows (List[Window]): 子視窗列表。

視窗控制操作

控制視窗狀態和位置。

啟用視窗

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    activate_result = session.computer.activate_window(window_id)
    # 執行結果: 視窗啟用成功
    
    if activate_result.success:
        print("視窗啟用成功")
    else:
        print(f"啟用視窗失敗: {activate_result.error_message}")

已最大化的視窗

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    maximize_result = session.computer.maximize_window(window_id)
    # 執行結果: 視窗最大化成功
    
    if maximize_result.success:
        print("視窗最大化成功")
    else:
        print(f"視窗最大化失敗: {maximize_result.error_message}")

已最小化的視窗

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    minimize_result = session.computer.minimize_window(window_id)
    # 執行結果: 視窗最小化成功
    
    if minimize_result.success:
        print("視窗最小化成功")
    else:
        print(f"視窗最小化失敗: {minimize_result.error_message}")

恢複視窗

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    restore_result = session.computer.restore_window(window_id)
    # 執行結果: 視窗恢複成功
    
    if restore_result.success:
        print("視窗恢複成功")
    else:
        print(f"視窗恢複失敗: {restore_result.error_message}")

調整視窗大小

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    resize_result = session.computer.resize_window(window_id, 800, 600)
    # 執行結果: 視窗調整為 800x600
    
    if resize_result.success:
        print("視窗調整為 800x600")
    else:
        print(f"視窗大小調整失敗: {resize_result.error_message}")

全屏視窗

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    fullscreen_result = session.computer.fullscreen_window(window_id)
    # 執行結果: 視窗設定為全屏
    
    if fullscreen_result.success:
        print("視窗設定為全屏")
    else:
        print(f"設定全屏失敗: {fullscreen_result.error_message}")

關閉視窗

# 注意: 使用時需謹慎，因為它會永久關閉視窗
result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    close_result = session.computer.close_window(window_id)
    
    if close_result.success:
        print("視窗關閉成功")
    else:
        print(f"關閉視窗失敗: {close_result.error_message}")

完整的視窗控制函數

import time

def control_window(session, window_id):
    print(f"控制視窗ID: {window_id}")
    
    try:
        session.computer.activate_window(window_id)
        print("視窗已啟用")
    except Exception as e:
        print(f"啟用失敗: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.maximize_window(window_id)
        print("視窗已最大化")
    except Exception as e:
        print(f"最大化失敗: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.minimize_window(window_id)
        print("視窗已最小化")
    except Exception as e:
        print(f"最小化失敗: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.restore_window(window_id)
        print("視窗已恢複")
    except Exception as e:
        print(f"恢複失敗: {e}")
    
    try:
        session.computer.resize_window(window_id, 800, 600)
        print("視窗調整為 800x600")
    except Exception as e:
        print(f"大小調整失敗: {e}")

windows = session.computer.list_root_windows()
if windows.success and windows.windows:
    control_window(session, windows.windows[0].window_id)

焦點管理

控制系統焦點行為以防止焦點被搶佔。

try:
    session.computer.focus_mode(True)
    # 執行結果: 焦點模式啟用 - 視窗不會搶佔焦點
    print("焦點模式啟用 - 視窗不會搶佔焦點")
except Exception as e:
    print(f"啟用焦點模式失敗: {e}")

try:
    session.computer.focus_mode(False)
    # 執行結果: 焦點模式禁用
    print("焦點模式禁用")
except Exception as e:
    print(f"禁用焦點模式失敗: {e}")

參數:

on (bool): True 啟用焦點模式，False 禁用焦點模式。

擷取使用中視窗

擷取當前使用中視窗的資訊。

# 注意: 如果當前沒有使用中視窗可能會失敗
result = session.computer.get_active_window(timeout_ms=5000)

if result.success:
    active_window = result.window
    # 當視窗處於活動狀態時的執行結果:
    # 使用中視窗:
    #   標題: Google Chrome
    #   視窗ID: 87654321
    #   進程: chrome
    #   PID: 4321
    #   位置: (0, 0)
    #   尺寸: 1920x1080
    print(f"使用中視窗:")
    print(f"  標題: {active_window.title}")
    print(f"  視窗ID: {active_window.window_id}")
    print(f"  進程: {active_window.pname}")
    print(f"  PID: {active_window.pid}")
    print(f"  位置: ({active_window.absolute_upper_left_x}, {active_window.absolute_upper_left_y})")
    print(f"  尺寸: {active_window.width}x{active_window.height}")
else:
    # 當沒有視窗處於活動狀態時的執行結果:
    # 擷取使用中視窗失敗: 響應錯誤 (如果沒有視窗處於活動狀態時的預期結果)
    print(f"擷取使用中視窗失敗: {result.error_message}")

參數:

timeout_ms (int, 可選): 逾時時間（毫秒）。預設為 3000。

完整工作流程樣本

展示如何啟動應用程式並控制其視窗的完整樣本。

import os
import time
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY 環境變數是必需的")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="linux_latest")
result = agent_bay.create(params)

if not result.success:
    print(f"建立會話失敗: {result.error_message}")
    exit(1)

session = result.session
print(f"會話已建立: {session.session_id}")
# 執行結果: 會話已建立: session-04bdwfj7u688ec96t

print("步驟 1: 尋找已安裝的應用程式...")
apps_result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)
# 執行結果: 找到 76 個應用程式

if not apps_result.success:
    print(f"擷取應用程式失敗: {apps_result.error_message}")
    agent_bay.delete(session)
    exit(1)

target_app = None
for app in apps_result.data:
    if "chrome" in app.name.lower():
        target_app = app
        break

if not target_app:
    print("未找到 Google Chrome")
    agent_bay.delete(session)
    exit(1)

print(f"找到應用程式: {target_app.name}")
# 執行結果: 找到應用程式: Google Chrome

print("步驟 2: 啟動應用程式...")
start_result = session.computer.start_app(target_app.start_cmd)

if not start_result.success:
    print(f"啟動應用程式失敗: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"應用程式已啟動，共啟動 {len(start_result.data)} 個進程")
# 執行結果: 應用程式已啟動，共啟動 6 個進程

print("步驟 3: 等待應用程式視窗載入...")
time.sleep(5)

print("步驟 4: 尋找應用程式視窗...")
windows_result = session.computer.list_root_windows()

if not windows_result.success:
    print(f"列出視窗失敗: {windows_result.error_message}")
    agent_bay.delete(session)
    exit(1)

app_window = None
for window in windows_result.windows:
    if target_app.name.lower() in window.title.lower():
        app_window = window
        break

if not app_window and windows_result.windows:
    app_window = windows_result.windows[0]
    print("使用第一個可用視窗")

if app_window:
    print(f"找到視窗: {app_window.title}")
    # 執行結果: 找到視窗: Welcome to Google Chrome
    
    print("步驟 5: 控制視窗...")
    try:
        session.computer.activate_window(app_window.window_id)
        print("視窗已啟用")
        # 執行結果: 視窗已啟用
        
        time.sleep(1)
        session.computer.maximize_window(app_window.window_id)
        print("視窗已最大化")
        # 執行結果: 視窗已最大化
        
        time.sleep(1)
        session.computer.resize_window(app_window.window_id, 1024, 768)
        print("視窗調整為 1024x768")
        # 執行結果: 視窗調整為 1024x768
        
    except Exception as e:
        print(f"視窗控制失敗: {e}")

print("清理會話...")
agent_bay.delete(session)
print("工作流程完成!")
# 執行結果: 會話刪除成功

API 參考

視窗管理器方法

方法	參數	傳回值	描述
`list_root_windows()`	`timeout_ms: int = 3000`	`WindowListResult`	列出所有根視窗
`get_active_window()`	`timeout_ms: int = 3000`	`WindowInfoResult`	擷取當前使用中視窗
`activate_window()`	`window_id: int`	`BoolResult`	啟用視窗
`maximize_window()`	`window_id: int`	`BoolResult`	已最大化的視窗
`minimize_window()`	`window_id: int`	`BoolResult`	已最小化的視窗
`restore_window()`	`window_id: int`	`BoolResult`	恢複視窗
`close_window()`	`window_id: int`	`BoolResult`	關閉視窗
`fullscreen_window()`	`window_id: int`	`BoolResult`	使視窗全屏
`resize_window()`	`window_id: int`<br/>`width: int`<br/>`height: int`	`BoolResult`	調整視窗大小
`focus_mode()`	`on: bool`	`BoolResult`	切換焦點模式

傳回型別

WindowListResult

success (bool): 操作是否成功。
windows (List[Window]): 視窗對象列表。
error_message (str): 如果操作失敗則返回錯誤訊息。
request_id (str): 唯一請求標識符。

Window

window_id (int): 視窗的唯一識別碼。
title (str): 視窗標題/解說文字。
absolute_upper_left_x (Optional[int]): 左上方的X座標。
absolute_upper_left_y (Optional[int]): 左上方的Y座標。
width (Optional[int]): 視窗寬度（像素）。
height (Optional[int]): 視窗高度（像素）。
pid (Optional[int]): 擁有該視窗的進程ID。
pname (Optional[str]): 擁有該視窗的進程名稱。
child_windows (List[Window]): 子視窗列表。

WindowInfoResult

success (bool): 操作是否成功。
window (Window): 視窗對象。
error_message (str): 如果操作失敗則返回錯誤訊息。
request_id (str): 唯一請求標識符。

BoolResult

success (bool): 操作是否成功。
data (bool): 操作結果資料。
error_message (str): 如果操作失敗則返回錯誤訊息。
request_id (str): 唯一請求標識符。