链接：https://github.com/OpenAdaptAI/OpenAdapt/wiki/OpenAdapt-Architecture-(draft)

---

docs：OpenAdapt

OpenAdapt 是一个开源项目，旨在 记录 和 回放 用户在计算机上的交互行为。

它如同智能助手般 观察 我们的操作（鼠标点击、键盘输入、屏幕变化），并将这些行为存储为结构化 *数据模型*。

通过 任务自动化 技术，这些记录数据可以被重新执行，并利用 *AI* 驱动的策略来适应不同场景。

该项目特别注重 隐私保护，允许从记录中擦除敏感信息。

架构

章节

1. 录制引擎
2. 数据模型
3. GUI 交互（窗口/元素）
4. 配置管理
5. 事件处理与合并
6. 数据库管理
7. 隐私擦除
8. 回放策略
9. AI 模型驱动

---

第一章：录制引擎

欢迎进入 OpenAdapt 的奇妙世界~

本章将解析 OpenAdapt 实现计算机任务自动化的核心组件——录制引擎。

该组件如同系统的感官系统，实时捕捉用户在计算机上的所有交互行为。

录制引擎的核心价值

设想我们需要教机器人烘焙蛋糕，单纯的口头指导远不如亲自演示每个操作步骤。OpenAdapt 的录制引擎正是通过 全维度行为捕捉 来实现类似的教学过程：

1. 行为复现基础
   记录鼠标轨迹、键盘输入、屏幕变化等原始数据，为自动化回放建立数据基石

2. 环境上下文感知
   同步捕获窗口状态、浏览器元素等环境信息，确保操作场景的可还原性

3. 多模态数据融合
   整合视觉（屏幕截图）、操作（键鼠事件）、语义（浏览器元素）等多维度信息

快速入门指南

通过终端命令启动录制流程：

python -m openadapt.record "打开浏览器并点击按钮"

操作演示完成后，使用 Ctrl+C（Windows/Linux）或 Cmd+C（macOS）终止录制。

系统将自动保存结构化录制数据至数据库。

多维感知子系统

视觉采集模块

# 摘自 openadapt/record.py
def read_screen_events(event_q, terminate_processing, recording, started_event):logger.info("启动屏幕事件读取器")while not terminate_processing.is_set():# 获取当前屏幕截图screenshot = utils.take_screenshot()  # 注入事件队列event_q.put(Event(utils.get_timestamp(), "screen", screenshot))

关键技术：

• 跨平台屏幕捕获（Windows/macOS/Linux）
• 可配置采样频率（默认 30fps）
• 智能差分压缩（仅存储帧间差异）

输入监控模块

# 键盘事件监听实现
def read_keyboard_events(event_q, terminate_processing, recording, started_event):keyboard_listener = keyboard.Listener(on_press=partial(on_press, event_q),  # 按键按下事件on_release=partial(on_release, event_q)  # 按键释放事件)# 鼠标事件捕获逻辑
def read_mouse_events(event_q, terminate_processing, recording, started_event):mouse_listener = mouse.Listener(on_move=partial(on_move, event_q),  # 移动轨迹on_click=partial(on_click, event_q),  # 点击事件on_scroll=partial(on_scroll, event_q)  # 滚轮操作)

数据精度控制：

• 鼠标坐标的屏幕坐标系映射
• 事件时间戳的微秒级同步
• 输入设备类型的自动识别

窗口状态追踪

# 窗口事件处理流程
def read_window_events(event_q, terminate_processing, recording, started_event):prev_window_data = {}while not terminate_processing.is_set():window_data = window.get_active_window_data()  # 获取窗口元数据if window_data != prev_window_data:event_q.put(Event(utils.get_timestamp(), "window", window_data))

核心元数据包含：

{"window_id": 0xCAFEBABE,"title": "Chrome浏览器 - 示例网站","geometry": [1280, 720, 1920, 1080],"process_id": 114514,"executable_path": "/Applications/Google Chrome.app"
}

浏览器深度监控

通过 Chrome 扩展实现网页元素级监控：

// chrome_extension/content.js
chrome.runtime.sendMessage(
{type: "element_click",data: {xpath: "//button[@id='submit']",innerText: "提交表单",boundingRect: { x: 320, y: 240, width: 80, height: 40 }}
});

扩展程序功能矩阵：

• DOM 元素语义化解析
• 动态内容变更监听
• 跨域 iframe 穿透处理

跨域 iframe 穿透 ：通过技术手段绕过浏览器同源策略，实现跨域 iframe 与父页面或子页面之间的数据交互或操作。

常见方法包括：

• postMessage：通过 window.postMessage 实现安全跨域通信。
• document.domain：主域相同时可设置相同 document.domain 实现共享。
• 代理页面：借助同源中间页作为桥梁转发数据。
• CORS 头部：服务端配置 Access-Control-Allow-Origin 允许特定域访问。

数据处理流水线

关键处理阶段：

1. 时空对齐
   采用 NTP 时间同步协议，确保跨设备事件时序一致性

2. 上下文关联
   建立操作事件与屏幕状态、窗口环境的映射关系

3. 语义增强
   对浏览器元素添加 XPath、CSS 选择器等可编程标识

NTP（网络时间协议）: 一种让计算机时钟与标准时间源保持一致的协议，就像自动校准手表一样。

事件类型体系

事件类型	数据结构示例	应用场景
屏幕帧	{timestamp: 162083.12, format: "PNG"}	操作回放可视化
鼠标点击	{x: 640, y: 360, button: "left"}	点击位置分析
键盘输入	{key: "Enter", modifiers: ["Shift"]}	表单自动填写
窗口切换	{title: "Untitled - Notepad"}	多应用工作流录制
浏览器DOM事件	{xpath: "//input[@name='email']"}	网页元素精准定位

总结

通过本指南，我们深入理解了 OpenAdapt 录制引擎的多维度感知能力。该组件不仅实现了基础操作记录，更通过环境上下文捕获和语义增强，为智能自动化奠定了数据基础。

值得关注的技术演进方向：

1. 基于 WebAssembly 的前端行为录制
2. 图形界面元素的 AI 语义识别
3. 分布式设备的协同录制

下一章：数据模型将解析如何将这些原始事件转化为可编程的自动化指令。

---

第二章：数据模型

在第一章：录制引擎中，我们了解到 OpenAdapt 通过"感官系统"持续捕捉计算机操作行为。本章将解析这些原始数据如何通过 数据模型 实现结构化组织。

数据模型的核心作用

数据模型如同 结构化模板，为 OpenAdapt 采集的各类信息提供标准化存储格式。

这种设计可类比烹饪食谱的结构化记录：

* **菜品名称**："巧克力曲奇"
* **原料配比**：- 面粉：2 杯- 砂糖：1 杯
* **制作步骤**：1. 混合黄油与砂糖2. 加入鸡蛋

数据模型为计算机操作记录赋予同等严谨的结构化特征，实现三大核心价值：

1. 高效存储
   规范化数据结构便于数据库持久化

2. 精准检索
   明确的字段定义确保操作回放时能快速定位关联信息

3. 语义理解
   结构化存储为开发者提供清晰的语义解析基础

核心数据模型

1. 录制记录模型（Recording）

此模型记录自动化任务的元数据，相当于操作记录的"档案袋"：

# 数据库模式定义（简化）
op.create_table("recording",sa.Column("id", sa.Integer(), primary_key=True),  # 唯一标识sa.Column("timestamp", sa.Integer()),  # 录制开始时间戳sa.Column("monitor_width", sa.Integer()),  # 屏幕分辨率宽度sa.Column("platform", sa.String()),  # 操作系统类型sa.Column("task_description", sa.Text())  # 任务描述文本
)

关键字段说明：

• monitor_width/height：确保跨设备回放时的屏幕坐标映射
• platform：记录操作系统差异（Windows/macOS/Linux）
• 外键关联：通过 id 字段与下级模型建立层级关系

2. 操作事件模型（ActionEvent）

记录原子级用户交互行为，构成自动化回放的基础单元：

class ActionEvent(db.Base):__tablename__ = "action_event"id = sa.Column(sa.Integer, primary_key=True)name = sa.Column(sa.String(50))  # 事件类型（点击/按键等）mouse_x = sa.Column(sa.Float)    # 屏幕X坐标mouse_y = sa.Column(sa.Float)    # 屏幕Y坐标key_char = sa.Column(sa.String)  # 输入字符（区分大小写）recording_id = sa.Column(sa.ForeignKey("recording.id"))  # 外键关联

事件类型矩阵：

事件类型	记录参数	应用场景
鼠标点击	(x,y)坐标，按键类型	界面元素交互记录
键盘输入	字符编码，功能键状态	表单填写流程记录
滚轮操作	滚动方向，滚动量	页面导航行为记录

3. 屏幕快照模型（Screenshot）

存储视觉上下文信息，提供操作回放的画面基准：

class Screenshot(db.Base):png_data = sa.Column(sa.LargeBinary)  # PNG格式二进制数据timestamp = sa.Column(sa.Float)       # 精确到毫秒的时间戳recording_id = sa.Column(sa.ForeignKey("recording.id"))

技术特性：

• 采用无损压缩的 PNG 格式存储
• 时间戳与操作事件精确对齐
• 支持差分存储优化（仅记录帧间变化）

4. 窗口状态模型（WindowEvent）

记录图形界面环境上下文，确保跨应用操作的准确性：

{"window_id": 0x7FEEBEEF,"title": "Untitled - TextEdit","geometry": [0, 0, 1920, 1080],"process_path": "/Applications/TextEdit.app"
}

关联作用：

• 通过 window_id 识别特定应用程序窗口
• geometry 字段记录窗口位置尺寸
• 与操作事件的时间戳联动，还原完整操作场景

5. 浏览器事件模型（BrowserEvent）

增强网页环境语义理解，存储 DOM 层级信息：

class BrowserEvent(db.Base):message = sa.Column(sa.JSON)  # 结构化网页数据# 示例数据
{"xpath": "//button[@id='submit']","innerHTML": "<span>提交</span>","css_selector": "#login-form > input.email"
}

数据价值：

• 通过 XPath/CSS 选择器精准定位元素
• 记录动态 DOM 变更实现智能等待
• 支持 iframe 嵌套等复杂结构解析

数据关联架构

关联机制说明：

1. 时间维度对齐
   采用高精度计时器（QueryPerformanceCounter）确保毫秒级同步

2. 空间坐标映射
   基于屏幕DPI和分辨率自动换算坐标体系

3. 上下文绑定
   通过外键关联实现操作事件与环境状态的动态绑定

数据处理

关键技术：

• 零拷贝队列：采用 multiprocessing.Queue 实现进程间高效通信
• 异步I/O：使用 aiosqlite 实现非阻塞数据库写入
• 数据分片：将数据按类型拆分到不同存储节点，实现并行处理，提升效率。

AIOSQLite

一个 Python 库，基于 SQLite 数据库的异步（asyncio）封装。

它允许在异步程序（如 FastAPI、Tornado）中高效操作 SQLite 数据库，避免传统同步接口导致的阻塞问题。

核心特点 ：

• 异步支持：通过 asyncio 实现非阻塞的数据库操作，适合高并发场景。
• 轻量易用：保留 SQLite 的简洁性，提供类似 aiohttp 的异步语法。
• 兼容性：底层仍使用标准 SQLite，但通过线程池处理同步调用，确保异步协程不阻塞事件循环。

应用场景 ：

适用于需要异步读写 SQLite 的 Web 后端、爬虫或实时数据处理程序。

总结

通过本章学习，我们深入理解了 OpenAdapt 如何通过结构化数据模型实现操作记录的精准还原。当前架构已支持：

1. 多平台环境适配
2. 毫秒级事件同步
3. 跨应用场景记录

未来演进方向：

1. 基于 WebAssembly 的模型优化
2. 操作语义的向量化编码
3. 分布式录制集群支持

下一章：GUI 交互（窗口/元素）将深入解析界面元素的智能识别技术。