鏈接：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 交互（窗口/元素）將深入解析界面元素的智能識別技術。