[自动化Adapt] GUI交互(窗口/元素) | 系统配置 | 非侵入式定制化

原创已于 2025-08-04 16:41:34 修改 · 659 阅读

15 ·

CC 4.0 BY-SA版权

文章标签：

#自动化 #交互 #microsoft

于 2025-08-04 14:57:22 首次发布

软件测试 & 自动化同时被 2 个专栏收录

20 篇文章

订阅专栏

AI底层&生态

12 篇文章

订阅专栏

第三章：GUI交互（窗口/元素）

各位OpenAdapt探索者，欢迎回来~

在第一章：录制引擎中，我们揭示了OpenAdapt如何通过"眼睛和耳朵"捕捉所有操作细节。接着在第二章：数据模型中，我们了解了这些原始信息如何被组织成特定的"表单"或"蓝图"进行存储。

现在让我们深入探讨更基础的核心功能：OpenAdapt如何真正理解屏幕上发生的事件。

仅仅知道鼠标点击的位置是不够的，它需要准确识别我们点击的对象及其在计算机中的位置层级。

这就是GUI交互（窗口/元素）组件存在的意义。

何为GUI交互（窗口/元素）？

想象训练机器人操作物理环境时需要的认知能力：

“当前处于哪个空间？”（厨房、客厅还是卧室？）
“该空间包含哪些物体？”（桌子、椅子、电灯开关？）
“需要操作物体的哪个具体部位？”（杯子的把手、遥控器的按钮？）

OpenAdapt的**GUI交互（窗口/元素）**组件正是为计算机图形界面打造的智能"视觉触觉系统"，其核心功能包括：

窗口识别（空间定位）：准确识别当前屏幕上的活动应用程序窗口。无论是网页浏览器、文档编辑器、即时通讯软件还是文件管理器，都能获取窗口标题、唯一ID、屏幕位置及尺寸等关键上下文信息。
元素识别（对象定位）：深入窗口内部，精准定位交互元素。区分提交按钮、搜索框、超链接或复选框等控件类型，解析其功能定位与空间坐标。

为何如此重要？

以典型场景点击"下一步"按钮为例说明：

若OpenAdapt仅记录鼠标在(500, 300)坐标的点击，这种自动化非常脆弱——窗口位置变化或按钮微调都会导致回放失败！

但当系统记录为"在谷歌浏览器窗口内点击’下一步’按钮"，即使窗口位移或按钮位置微调

OpenAdapt仍能智能定位目标元素。这种上下文感知能力大幅提升了自动化的可靠性与健壮性。

该组件为OpenAdapt提供了录制时的环境感知能力与回放时的精准定位能力。

GUI交互的工作原理

与直接操作的录制引擎不同，该组件作为录制引擎的后台模块持续静默运行。当开始录制操作时，系统即启动实时环境监测。

还记得第一章提到的"上下文检查器"和第二章的WindowEvent、BrowserEvent模型吗？其底层实现正依赖于此组件

完整工作流程如下：

持续窗口监测：系统周期性询问操作系统：“当前活动窗口是什么？名称、位置、尺寸几何？”
用户交互触发（如点击）：当鼠标点击发生时，系统立即追问：“光标当前位置覆盖的交互元素是什么？按钮、文本框还是图片？其名称与功能角色？”
数据整合存储：收集的窗口标题、元素名称、类型及位置等信息，将与ActionEvent（如点击动作）共同存储，并生成独立的WindowEvent和BrowserEvent数据库条目。

GUI交互数据采集流程：

在这里插入图片描述

代码层解析

OpenAdapt需要与不同操作系统（Windows/macOS/Linux）交互以获取GUI详情。各平台实现方式迥异，为此系统在openadapt/window目录采用了智能架构：

openadapt/window/__init__.py：该文件作为通用适配层，提供标准化函数接口，自动选择平台专属实现。核心代码：

import sys

# 动态加载平台适配模块
if sys.platform == "darwin":
    from . import _macos as impl  # macOS实现
elif sys.platform == "win32":
    from . import _windows as impl  # Windows实现
elif sys.platform.startswith("linux"):
    from . import _linux as impl  # Linux实现
else:
    raise Exception(f"不支持的平台: {sys.platform}")

def get_active_window_data(include_window_data: bool = True) -> dict | None:
    """获取活动窗口数据（标题、坐标、尺寸、ID）"""
    state = impl.get_active_window_state(include_window_data)
    return 
    {
        "title": state.get("title"),
        "left": state.get("left"),
        "top": state.get("top"),
        "width": state.get("width"),
        "height": state.get("height"),
        "window_id": state.get("window_id"),
        "state": state,  # 原始平台数据
    }

def get_active_element_state(x: int, y: int) -> dict | None:
    """获取指定坐标(x,y)的活动元素状态"""
    return impl.get_active_element_state(x, y)

平台专属实现（以Windows为例）：_windows.py通过pywinauto库与系统交互：

import pywinauto  # Windows GUI自动化库

def get_active_window_state(read_window_data: bool = True) -> dict:
    """获取Windows活动窗口状态"""
    app = pywinauto.application.Application(backend="uia").connect(active_only=True)
    active_window = app.top_window()  # 获取顶层活动窗口
    
    meta = active_window.get_properties()  # 提取窗口属性
    return {
        "title": meta.get("texts", [""])[0],
        "left": meta["rectangle"].left,
        "top": meta["rectangle"].top,
        "width": meta["rectangle"].width(),
        "height": meta["rectangle"].height(),
        "window_id": meta["control_id"],
        "meta": meta,  # 原始属性数据
    }

def get_active_element_state(x: int, y: int) -> dict:
    """获取Windows指定坐标元素状态"""
    active_window = get_active_window()
    active_element = active_window.from_point(x, y)  # 坐标元素查询
    return active_element.get_properties()  # 返回元素属性集

信息采集类型说明

系统采集的环境信息可分为两大维度：

类别	具体信息示例	重要性
窗口上下文	窗口标题（如"谷歌浏览器-维基百科"）、窗口ID、坐标(left,top)、尺寸(width,height)、进程ID	确定交互所处的应用程序环境，保障OpenAdapt能准确定位目标窗口
元素上下文	元素名称（如"提交按钮"）、角色类型（如"AXButton"）、边界框坐标、文本框内容、复选框状态	精确定位窗口内的交互元素，使回放操作不再依赖固定坐标，提升对界面变化的适应能力

这些结构化数据最终注入WindowEvent和BrowserEvent模型，并与ActionEvent建立关联，形成完整的操作叙事链。

总结

本章揭示了**GUI交互（窗口/元素）**组件如何成为OpenAdapt在计算机屏幕上的"视觉触觉系统"。

通过理解操作发生的窗口环境与具体元素对象，而非单纯记录坐标数据，OpenAdapt实现了智能化的自适应自动化。这种对图形界面的深度理解，正是系统实现可靠自动化的重要基石。

接下来我们将探索如何通过配置系统定制OpenAdapt的行为模式。

下一章：系统配置

第四章：系统配置

欢迎回到OpenAdapt探索之旅！在第一章：录制引擎中，我们了解了OpenAdapt如何"观察"和"记录"用户操作。接着在第二章：数据模型中，我们目睹了原始数据如何被结构化存储。最后，通过第三章：GUI交互（窗口/元素），我们深入理解了系统如何解析屏幕交互元素。

现在假设我们需要调整OpenAdapt的默认行为：可能需要录制操作视频，或是配置专属AI服务密钥。

难道每次调整都需要修改核心代码？

当然不必！这正是系统配置组件的价值所在。

何为系统配置？

将OpenAdapt的系统配置视为其"控制中枢"，集中管理所有可调参数。这些参数控制着从隐私设置、存储路径到AI模型选择等核心行为。

必要性分析

类比智能手机设置：普通用户无需开发技能即可修改壁纸、连接WiFi或设置闹钟。系统配置组件为OpenAdapt提供同等级别的易用性，主要解决**非侵入式定制化需求**：

灵活适配：根据个性化需求调整系统行为
零编码门槛：无需编程基础即可完成功能调校
参数一致性：全局统一的配置管理中心
更新友好：系统升级不丢失用户配置

典型用例：启用操作视频录制。该功能非默认启用，通过配置系统即可快速开启。

配置修改指南（可视化方式）

OpenAdapt提供基于Web的控制面板进行可视化配置，推荐大多数用户使用。

启动控制面板命令：

python -m openadapt.app.dashboard.run

浏览器访问控制面板后，在"设置"模块可调整各项参数。以视频录制为例，进入"录制与回放"分区，将"录制视频"选项切换为启用状态。

底层实现层面，所有配置变更将持久化至config.json文件，该文件位于OpenAdapt安装目录的data文件夹。

配置文件体系

系统维护两个核心配置文件：

config.defaults.json：包含初始默认配置，禁止直接修改
config.json：用户自定义配置存储位置。初次启动时自动从默认配置克隆，后续所有变更均保存于此

系统启动时优先加载默认配置，随后合并用户配置。当参数冲突时，用户配置具有更高优先级，确保个性化设置始终生效。

配置系统核心实现：`config.py`解析

深入openadapt/config.py文件，剖析配置管理机制。

配置蓝本：`Config`类

该Python类作为配置系统的核心蓝本，完整定义所有可配置参数及其类型（布尔值/字符串/整型等）与默认值。借助pydantic-settings库实现结构化配置管理与类型校验。

简化代码示例：

# 摘自openadapt/config.py（简化版）

from pydantic_settings import BaseSettings  # 配置管理神器

class Config(BaseSettings):
    """OpenAdapt配置中心"""

    # 录制回放参数
    RECORD_VIDEO: bool  # 是否启用视频录制
    RECORD_IMAGES: bool  # 是否保存屏幕截图
    RECORD_BROWSER_EVENTS: bool  # 是否记录浏览器事件

    # API密钥管理
    OPENAI_API_KEY: str = "<OPENAI_API_KEY>"  # OpenAI服务密钥
    REPLICATE_API_TOKEN: str = ""  # Replicate平台令牌

    # 数据库配置
    DATABASE_FILE_PATH: str  # 数据库文件路径

    # 隐私保护
    SCRUB_ENABLED: bool = False  # 敏感信息擦除开关
    SCRUB_CHAR: str = "*"  # 擦除替换字符

此代码定义了参数结构。例如RECORD_VIDEO: bool声明该参数为布尔类型，OPENAI_API_KEY设置默认占位值。

配置加载顺序策略

通过settings_customise_sources方法明确定义配置加载优先级：

class Config(BaseSettings):
    # ...（参数定义略）...

    @classmethod
    def settings_customise_sources(
        cls: Type["Config"],
        settings_cls: type[BaseSettings],
        init_settings: PydanticBaseSettingsSource,
        env_settings: PydanticBaseSettingsSource,
        dotenv_settings: PydanticBaseSettingsSource,
        file_secret_settings: PydanticBaseSettingsSource,
    ) -> tuple[PydanticBaseSettingsSource, ...]:
        """定义配置源加载顺序
        
        优先级排序：
        1. 运行时传入参数（最高）
        2. 用户配置文件config.json
        3. 默认配置文件config.defaults.json（最低）
        """
        return (
            init_settings,  # 运行时参数
            get_json_config_settings_source(CONFIG_FILE_PATH)(settings_cls),  # 用户配置
            get_json_config_settings_source(CONFIG_DEFAULTS_FILE_PATH)(settings_cls),  # 默认配置
        )

动态配置更新：LazyConfig机制

为确保实时获取最新配置（即便在运行中修改config.json），系统采用LazyConfig代理类实现动态加载：

class LazyConfig:
    """支持配置热更新的代理类"""

    def __init__(self) -> None:
        self._config = Config()  # 初始配置加载

    def __getattr__(self, key: str) -> Any:
        # 属性访问时触发配置重载
        if key.startswith("_"):  # 跳过内部属性
            return self.__dict__[key]
        self._config = Config()  # 重新加载配置
        return self._config.__getattribute__(key)

# 全局配置访问入口
config = LazyConfig()

配置持久化实现

用户配置变更通过persist_config函数写入磁盘：

def persist_config(new_config: Config) -> None:
    """配置持久化存储"""
    config_variables = new_config.model_dump()  # 配置对象转字典
    
    with open(CONFIG_FILE_PATH, "w") as f:
        json.dump(config_variables, f, indent=4)  # 美化格式写入

    # 全局配置即时更新
    global config
    config._config = new_config

配置变更数据流

在这里插入图片描述

控制面板通过SettingsAPI（定义于openadapt/app/dashboard/api/settings.py及前端openadapt/app/dashboard/app/settings/utils.ts）与配置管理器交互，实现配置的读写操作。

当录制引擎等功能模块需要参数时，直接向配置管理器请求最新值。

主要配置类别

系统配置按功能划分为多个管理维度：

配置类别	功能范围	典型参数示例
`api_keys`	第三方AI服务认证密钥	`OPENAI_API_KEY`, `REPLICATE_API_TOKEN`
`scrubbing`	隐私数据保护功能	`SCRUB_ENABLED`, `SCRUB_CHAR`
`record_and_replay`	录制与回放行为控制	`RECORD_VIDEO`, `REPLAY_STRIP_ELEMENT_STATE`
`general`	系统通用设置与用户体验优化	`APP_DARK_MODE`, `UNIQUE_USER_ID`