議+Electron桌面應(yīng)用自動(dòng)化：原理、實(shí)踐與踩坑指南)
我們團(tuán)隊(duì)最近在做一個(gè)“批量流程自動(dòng)化”的內(nèi)部項(xiàng)目核心訴求是讓一個(gè)Agent能夠像人一樣操作我們公司某款Electron桌面客戶(hù)端自動(dòng)完成錄入、查詢(xún)、導(dǎo)出這一連串動(dòng)作。最開(kāi)始想的是圖像識(shí)別加模擬鍵鼠試了幾天發(fā)現(xiàn)全是坑窗口一遮擋坐標(biāo)就偏、高分屏DPI縮放直接讓點(diǎn)擊位置漂移、頁(yè)面元素稍微變個(gè)樣式腳本就崩。后來(lái)我想到Electron的底層其實(shí)是Chromium既然瀏覽器可以通過(guò)CDP協(xié)議被人遠(yuǎn)程控制那Electron桌面應(yīng)用理論上也應(yīng)該可以。折騰了兩周最終用CDP協(xié)議打通了一條完全不同的路子——不依賴(lài)坐標(biāo)、不依賴(lài)圖像識(shí)別直接通過(guò)協(xié)議精準(zhǔn)操作應(yīng)用內(nèi)的DOM元素。這篇文章就把我從零摸到可用的整個(gè)過(guò)程、代碼和踩過(guò)的坑完整記錄下來(lái)希望能給正在做Agent自動(dòng)化操作桌面應(yīng)用的朋友一些參考。剛開(kāi)始接觸CDP協(xié)議時(shí)我以為它只能調(diào)試網(wǎng)頁(yè)但它的能力邊界其實(shí)遠(yuǎn)超“F12開(kāi)發(fā)者工具”的范疇。依賴(lài)DOM和運(yùn)行時(shí)求值我們不僅能在Electron應(yīng)用內(nèi)讀取任意頁(yè)面數(shù)據(jù)、觸發(fā)點(diǎn)擊和輸入事件還能調(diào)用應(yīng)用內(nèi)已經(jīng)暴露的接口、監(jiān)聽(tīng)網(wǎng)絡(luò)請(qǐng)求、攔截響應(yīng)甚至直接操作應(yīng)用內(nèi)部狀態(tài)。這對(duì)Agent來(lái)說(shuō)是個(gè)巨大優(yōu)勢(shì)它可以像真實(shí)用戶(hù)在頁(yè)面上完成操作又不用依賴(lài)脆弱的視覺(jué)算法穩(wěn)定性高出一個(gè)數(shù)量級(jí)。1. 項(xiàng)目思路為什么選擇CDP方案操作Electron應(yīng)用1.1 桌面應(yīng)用自動(dòng)化的三條技術(shù)路線對(duì)比在動(dòng)手之前我認(rèn)真比較過(guò)市面上主流的桌面自動(dòng)化方案大致分成三類(lèi)。第一類(lèi)是傳統(tǒng)鍵鼠模擬工具這類(lèi)方案的思路是記住屏幕上的固定位置然后通過(guò)調(diào)用系統(tǒng)接口移動(dòng)鼠標(biāo)、執(zhí)行點(diǎn)擊和鍵盤(pán)輸入。優(yōu)點(diǎn)是通用性強(qiáng)幾乎什么軟件都能驅(qū)動(dòng)缺點(diǎn)是穩(wěn)定性極度依賴(lài)窗口狀態(tài)。窗口一移動(dòng)、一最小化、一被遮擋整個(gè)腳本就廢了。再加上高DPI環(huán)境下屏幕坐標(biāo)系會(huì)縮放同一個(gè)按鈕在不同分辨率屏幕上的位置完全不同維護(hù)成本很高。第二類(lèi)是圖像識(shí)別方案原理是持續(xù)截屏然后在截圖中用模板匹配或深度學(xué)習(xí)找目標(biāo)元素。這種方案在游戲自動(dòng)化領(lǐng)域用得比較多因?yàn)橛螒颦h(huán)境里沒(méi)有其他控制通道。但在偏辦公類(lèi)的Electron應(yīng)用里它的問(wèn)題是性能開(kāi)銷(xiāo)大、識(shí)別有延遲、而且對(duì)UI微調(diào)過(guò)于敏感。換個(gè)按鈕圓角、改個(gè)圖標(biāo)配色識(shí)別準(zhǔn)確率就會(huì)斷崖式下降。第三類(lèi)就是我要說(shuō)的CDP協(xié)議方案核心思路是Electron應(yīng)用本質(zhì)上跑著一個(gè)完整的Chromium實(shí)例Chromium天然支持遠(yuǎn)程調(diào)試協(xié)議那我們完全可以繞過(guò)屏幕坐標(biāo)直接通過(guò)協(xié)議讀寫(xiě)應(yīng)用內(nèi)DOM、派發(fā)事件、求值JS代碼。這個(gè)方案的好處是穩(wěn)定性極高元素位置隨便變、窗口隨便移動(dòng)都不影響腳本因?yàn)樗僮鞯氖琼?yè)面內(nèi)部的對(duì)象結(jié)構(gòu)而不是屏幕上的像素坐標(biāo)。1.2 CDP方案解決的核心痛點(diǎn)選擇CDP最直接的原因是它解決了我們項(xiàng)目里兩個(gè)最難纏的問(wèn)題。第一個(gè)問(wèn)題是“窗口遮擋”。我們的Agent需要并發(fā)處理多個(gè)任務(wù)經(jīng)常會(huì)在多個(gè)應(yīng)用窗口之間切換傳統(tǒng)鍵鼠方案一旦遇到后臺(tái)窗口被遮擋就完全束手無(wú)策。而CDP方案操作的是頁(yè)面內(nèi)部結(jié)構(gòu)根本不需要窗口處于前臺(tái)甚至窗口最小化了它照樣能執(zhí)行點(diǎn)擊和輸入。這個(gè)特性對(duì)我們來(lái)說(shuō)至關(guān)重要意味著Agent可以同時(shí)“操作”多個(gè)實(shí)例而不用管哪個(gè)窗口在最上面。第二個(gè)問(wèn)題是“元素定位精度”。用了CDP之后定位一個(gè)輸入框就是一句document.querySelector(#username)的事情穩(wěn)定到不管CSS怎么改都能找到。如果元素加了>[客戶(hù)端] ---HTTP GET /json/list--- [Electron應(yīng)用調(diào)試服務(wù)] ---targetId列表--- [客戶(hù)端] ---WebSocket連接 ws://...--- [Electron應(yīng)用調(diào)試服務(wù)] ---發(fā)送命令 {id:1,method:DOM.enable}--- [客戶(hù)端] ---收到結(jié)果 {id:1,result:{}}---日常使用中90%的命令都是單向請(qǐng)求響應(yīng)模式。協(xié)議里也有事件推送機(jī)制比如頁(yè)面加載完成、DOM節(jié)點(diǎn)更新、控制臺(tái)輸出這些都會(huì)主動(dòng)推給客戶(hù)端這點(diǎn)在我們后面做動(dòng)態(tài)等待的時(shí)候會(huì)很關(guān)鍵。2.2 為什么Electron應(yīng)用天然支持CDPElectron應(yīng)用之所以能直接用CDP協(xié)議控制根本原因是它本身就是基于Chromium外殼的。Electron官方其實(shí)屏蔽了一部分Chromium的調(diào)試能力但只要我們啟動(dòng)的時(shí)候加上一個(gè)遠(yuǎn)程調(diào)試端口參數(shù)完整的CDP功能就會(huì)暴露出來(lái)。具體來(lái)說(shuō)在啟動(dòng)Electron應(yīng)用的時(shí)候加上--remote-debugging-port9222Electron主進(jìn)程就會(huì)在9222端口開(kāi)啟一個(gè)調(diào)試服務(wù)。這個(gè)調(diào)試服務(wù)不僅能發(fā)現(xiàn)所有已經(jīng)打開(kāi)的窗口還能讓外部客戶(hù)端通過(guò)CDP協(xié)議和這些窗口的渲染進(jìn)程建立實(shí)時(shí)通信通道。這里有個(gè)Electron特有的坑要特別注意Electron應(yīng)用可能有多個(gè)窗口而每個(gè)窗口在CDP協(xié)議里都是一個(gè)獨(dú)立的Target。所以連接時(shí)要先通過(guò)HTTP接口拿到所有Target列表再根據(jù)title或url字段篩選出我們要操作的那個(gè)窗口而不是默認(rèn)連接第一個(gè)。有一點(diǎn)值得說(shuō)明Electron渲染進(jìn)程和普通Chrome頁(yè)面在CDP層面上幾乎沒(méi)有區(qū)別原本為瀏覽器自動(dòng)化設(shè)計(jì)的工具和庫(kù)在Electron應(yīng)用上都能無(wú)縫使用。這意味著生態(tài)里現(xiàn)成的Node.js庫(kù)、Python客戶(hù)端在這一場(chǎng)景下都能用。2.3 協(xié)議中Agent操作高頻依賴(lài)的能力域CDP協(xié)議按功能劃分了幾十個(gè)模塊做Agent操作時(shí)不需要所有模塊全用熟練掌握下面幾個(gè)就夠覆蓋95%以上的場(chǎng)景了。Runtime域用來(lái)在頁(yè)面上下文里執(zhí)行任意JavaScript代碼這算是整個(gè)協(xié)議最核心的入口。Runtime.evaluate可以執(zhí)行表達(dá)式并返回結(jié)果Runtime.callFunctionOn可以在指定對(duì)象上調(diào)用函數(shù)。Agent的很多操作本質(zhì)上就是組合各種JS代碼去實(shí)現(xiàn)。DOM域負(fù)責(zé)文檔對(duì)象模型的查詢(xún)和操作。DOM.getDocument拿到文檔根節(jié)點(diǎn)、DOM.querySelector從根節(jié)點(diǎn)往下找目標(biāo)元素、DOMDebugger用來(lái)調(diào)試監(jiān)聽(tīng)等。但我們實(shí)際項(xiàng)目里更多是用Runtime.evaluate直接跑document.querySelector來(lái)代替DOM域接口因?yàn)檫@樣寫(xiě)起來(lái)更自然而且要獲取的上下文信息更直接。Input域是模擬用戶(hù)輸入的關(guān)鍵模塊。Input.dispatchMouseEvent可以派發(fā)鼠標(biāo)按下、釋放、移動(dòng)事件Input.dispatchKeyEvent派發(fā)鍵盤(pán)事件。這套接口模擬的是系統(tǒng)輸入層的事件觸發(fā)的行為比直接調(diào)用JS的element.click()更接近真實(shí)用戶(hù)操作會(huì)觸發(fā)完整的鼠標(biāo)懸停、激活、焦點(diǎn)切換等狀態(tài)流。Page域用來(lái)管理系統(tǒng)頁(yè)面狀態(tài)。Page.navigate跳轉(zhuǎn)導(dǎo)航、Page.reload刷新頁(yè)面、Page.captureScreenshot截圖以及Page.setDeviceMetricsOverride模擬設(shè)備尺寸等。對(duì)Agent自動(dòng)操作桌面應(yīng)用來(lái)說(shuō)Page.captureScreenshot在出了問(wèn)題時(shí)抓現(xiàn)場(chǎng)特別有用。Network域能攔截和查看網(wǎng)絡(luò)請(qǐng)求。Agent在操作過(guò)程中可能需要等待某個(gè)接口返回后才能繼續(xù)下一步這個(gè)域可以監(jiān)聽(tīng)請(qǐng)求響應(yīng)作為操作完成與否的判據(jù)。這些模塊組合起來(lái)就能構(gòu)建一個(gè)完整的自動(dòng)化操作閉環(huán)定位元素、讀取狀態(tài)、執(zhí)行交互、驗(yàn)證結(jié)果、異常兜底。3. 環(huán)境準(zhǔn)備啟動(dòng)帶調(diào)試端口的Electron應(yīng)用3.1 修改Electron應(yīng)用啟動(dòng)方式要讓CDP協(xié)議能連上Electron應(yīng)用第一步是讓?xiě)?yīng)用以調(diào)試模式啟動(dòng)。最簡(jiǎn)單的做法是在應(yīng)用入口文件里通過(guò)app.commandLine.appendSwitch添加參數(shù)也可以直接在終端啟動(dòng)命令后面拼接參數(shù)。在終端里啟動(dòng)的命令是這樣的./your-electron-app --remote-debugging-port9222不過(guò)這種方式有個(gè)不方便的地方如果Electron應(yīng)用的啟動(dòng)是通過(guò)雙擊桌面圖標(biāo)完成的那命令行參數(shù)就傳不進(jìn)去。我們項(xiàng)目里的做法是在Electron主進(jìn)程代碼里強(qiáng)制開(kāi)啟調(diào)試端口這樣不管用戶(hù)怎么啟動(dòng)應(yīng)用調(diào)試服務(wù)都會(huì)自動(dòng)掛在預(yù)設(shè)端口上。// main.js const { app } require(electron) app.commandLine.appendSwitch(remote-debugging-port, 9222) app.commandLine.appendSwitch(remote-allow-origins, *) app.whenReady().then(() { // 正常啟動(dòng)應(yīng)用邏輯 })這里有一個(gè)安全相關(guān)的設(shè)置需要格外注意remote-allow-origins參數(shù)如果你不主動(dòng)設(shè)置新版Chromium會(huì)默認(rèn)校驗(yàn)WebSocket連接的來(lái)源域名。我們一開(kāi)始連接時(shí)一直報(bào)403錯(cuò)誤找了好幾輪才發(fā)現(xiàn)是這個(gè)配置問(wèn)題。本地自動(dòng)化場(chǎng)景直接設(shè)為*通配符就行但如果在公網(wǎng)環(huán)境使用一定要收緊這個(gè)配置。3.2 多實(shí)例運(yùn)行時(shí)的端口規(guī)劃我們的Agent要支持并發(fā)操作多個(gè)Electron實(shí)例所以統(tǒng)一的固定端口滿足不了需求。解決方法是讓每個(gè)應(yīng)用實(shí)例啟動(dòng)時(shí)自動(dòng)分配一個(gè)獨(dú)立端口然后把端口號(hào)傳給Agent調(diào)度器。Electron應(yīng)用可以通過(guò)環(huán)境變量來(lái)指定端口號(hào)const debugPort process.env.DEBUG_PORT || 9222 app.commandLine.appendSwitch(remote-debugging-port, debugPort)調(diào)度端為每個(gè)實(shí)例動(dòng)態(tài)分配可用端口#!/bin/bash BASE_PORT9400 for i in {1..5} do CURRENT_PORT$((BASE_PORT i)) DEBUG_PORT$CURRENT_PORT ./your-electron-app echo Instance $i started on port $CURRENT_PORT done這樣多個(gè)實(shí)例就能并行跑在各自獨(dú)立的調(diào)試端口上Agent可以針對(duì)每個(gè)端口各建一條CDP連接互不干擾。實(shí)測(cè)下來(lái)單機(jī)跑幾十個(gè)實(shí)例沒(méi)有性能瓶頸主要卡在內(nèi)存和CPU資源上。3.3 確認(rèn)調(diào)試服務(wù)已就緒應(yīng)用啟動(dòng)之后需要用命令行驗(yàn)證一下調(diào)試服務(wù)是否正常開(kāi)啟。瀏覽器打開(kāi)或curl請(qǐng)求下面這個(gè)地址curl http://127.0.0.1:9222/json/version如果一切正常會(huì)返回一段JSON里面包含Browser版本號(hào)、webSocketDebuggerUrl和chrome-version這些關(guān)鍵信息。再訪問(wèn)/json/list就能看到當(dāng)前應(yīng)用打開(kāi)的每個(gè)頁(yè)面窗口的詳細(xì)信息了。[ { description: , devtoolsFrontendUrl: /devtools/inspector.html?ws127.0.0.1:9222/devtools/page/xxxxx, id: A8C1E992F502CF11B6E9C56F33756D2A, title: 工作臺(tái), type: page, url: file:///app/index.html, webSocketDebuggerUrl: ws://127.0.0.1:9222/devtools/page/A8C1E992F502CF11B6E9C56F33756D2A } ]我這里會(huì)重點(diǎn)看webSocketDebuggerUrl字段它是后續(xù)建立WebSocket連接的入口。而title字段幫我們從多個(gè)窗口里挑出要控制的那一個(gè)。4. 核心實(shí)操用Node.js手寫(xiě)一個(gè)CDP客戶(hù)端4.1 建立WebSocket連接我選擇用Node.js寫(xiě)客戶(hù)端因?yàn)镋lectron應(yīng)用前端本身就是JavaScript環(huán)境而且Node.js的WebSocket生態(tài)非常成熟。項(xiàng)目里用的庫(kù)是ws它輕量穩(wěn)定在NPM上可以直接安裝。npm install ws創(chuàng)建一個(gè)cdp-client.js文件先實(shí)現(xiàn)最基礎(chǔ)的連接邏輯const WebSocket require(ws) class CDPClient { constructor(wsUrl) { this.wsUrl wsUrl this.ws null this.callbacks new Map() this.eventHandlers new Map() this.commandId 0 } connect() { return new Promise((resolve, reject) { this.ws new WebSocket(this.wsUrl, { maxPayload: 256 * 1024 * 1024 }) this.ws.on(open, () { console.log([CDP] WebSocket connected) resolve() }) this.ws.on(message, (data) { const msg JSON.parse(data.toString()) if (msg.id) { const callback this.callbacks.get(msg.id) if (callback) { this.callbacks.delete(msg.id) if (msg.error) { callback.reject(new Error(msg.error.message)) } else { callback.resolve(msg.result) } } } else { // 事件消息 const handlers this.eventHandlers.get(msg.method) if (handlers) { handlers.forEach((handler) handler(msg.params)) } } }) this.ws.on(error, (err) { console.error([CDP] WebSocket error:, err.message) reject(err) }) this.ws.on(close, () { console.log([CDP] WebSocket closed) }) }) } send(method, params {}) { return new Promise((resolve, reject) { const id this.commandId this.callbacks.set(id, { resolve, reject }) this.ws.send(JSON.stringify({ id, method, params })) }) } on(method, handler) { if (!this.eventHandlers.has(method)) { this.eventHandlers.set(method, []) } this.eventHandlers.get(method).push(handler) } }這個(gè)實(shí)現(xiàn)里藏了一個(gè)特別重要的細(xì)節(jié)maxPayload參數(shù)一定要調(diào)大。Chromium的CDP服務(wù)端默認(rèn)消息大小限制很低但我們的自動(dòng)化場(chǎng)景里經(jīng)常要一次傳輸大量DOM數(shù)據(jù)尤其頁(yè)面復(fù)雜時(shí)DOM.getDocument接口返回的序列化結(jié)果可能達(dá)到幾十MB。不調(diào)大這個(gè)參數(shù)消息一超過(guò)限制WebSocket就會(huì)靜默斷開(kāi)排查起來(lái)讓人非常抓狂。4.2 常用命令封裝連接建立后我會(huì)把高頻操作封裝成一個(gè)個(gè)獨(dú)立方法這樣Agent邏輯層寫(xiě)起來(lái)就像調(diào)用本地函數(shù)一樣自然。class CDPClient { // 獲取文檔樹(shù) async getDocument() { const result await this.send(DOM.getDocument, { depth: -1 }) return result.root } // 通過(guò)選擇器查找元素節(jié)點(diǎn)ID async querySelector(nodeId, selector) { const result await this.send(DOM.querySelector, { nodeId, selector }) return result.nodeId } // 執(zhí)行JavaScript表達(dá)式 async evaluate(expression, awaitPromise true) { const result await this.send(Runtime.evaluate, { expression, awaitPromise, returnByValue: true }) if (result.exceptionDetails) { throw new Error(頁(yè)面執(zhí)行JS出錯(cuò): result.exceptionDetails.text) } return result.result.value } // 模擬鼠標(biāo)點(diǎn)擊基于元素中心坐標(biāo) async clickBySelector(selector) { const expr (() { const el document.querySelector(${selector}) if (!el) return null const rect el.getBoundingClientRect() return { x: rect.left rect.width / 2, y: rect.top rect.height / 2, text: el.innerText } })() const { x, y } await this.evaluate(expr) if (x null) return false await this.send(Input.dispatchMouseEvent, { type: mousePressed, x: Math.round(x), y: Math.round(y), button: left, clickCount: 1 }) await this.send(Input.dispatchMouseEvent, { type: mouseReleased, x: Math.round(x), y: Math.round(y), button: left, clickCount: 1 }) return true } }這里關(guān)于點(diǎn)擊坐標(biāo)有個(gè)需要說(shuō)清楚的關(guān)鍵細(xì)節(jié)頁(yè)面里的getBoundingClientRect()拿到的是CSS像素坐標(biāo)而Input.dispatchMouseEvent默認(rèn)按物理像素解釋兩者在非100%縮放比下會(huì)不一致。Electron應(yīng)用頁(yè)面里如果設(shè)置了zoomFactor或系統(tǒng)DPI縮放坐標(biāo)就會(huì)偏移。穩(wěn)妥的做法是在連接建立后先讀取設(shè)備的縮放比例然后把坐標(biāo)手動(dòng)換算過(guò)去。async getDeviceMetrics() { const metrics await this.send(Page.getLayoutMetrics) const { cssScaleFactor } metrics return { scaleFactor: cssScaleFactor, viewportWidth: metrics.cssLayoutViewport.clientWidth, viewportHeight: metrics.cssLayoutViewport.clientHeight } }拿到cssScaleFactor之后凡是需要派發(fā)鼠標(biāo)事件的坐標(biāo)統(tǒng)統(tǒng)用x / scaleFactor換算后再發(fā)給CDP服務(wù)端就能徹底規(guī)避縮放導(dǎo)致的點(diǎn)擊偏移問(wèn)題。4.3 完整操作流程示例下面給一個(gè)Agent自動(dòng)登錄并執(zhí)行查詢(xún)的完整代碼示例這里模擬的場(chǎng)景是打開(kāi)某個(gè)客戶(hù)管理桌面應(yīng)用自動(dòng)登錄、跳轉(zhuǎn)到客戶(hù)列表頁(yè)、輸入關(guān)鍵字搜索、提取搜索結(jié)果。const CDPClient require(./cdp-client) async function getTargetList(baseUrl) { const res await fetch(http://127.0.0.1:9222/json/list) const targets await res.json() return targets.filter((t) t.type page) } async function startAgent() { const targets await getTargetList(http://127.0.0.1:9222) const target targets.find((t) t.title.includes(客戶(hù)管理)) if (!target) { throw new Error(未找到目標(biāo)窗口請(qǐng)檢查應(yīng)用是否已打開(kāi)客戶(hù)管理界面) } const client new CDPClient(target.webSocketDebuggerUrl) await client.connect() // 啟用相關(guān)域 await client.send(Runtime.enable) await client.send(Page.enable) // 1. 等待頁(yè)面加載完成 await client.send(Page.reload) await waitForPageLoad(client) // 2. 自動(dòng)填充登錄表單 await client.evaluate( document.querySelector(#username).value admin document.querySelector(#password).value 123456 ) // 觸發(fā)React/Vue框架的input事件 await client.evaluate( const input document.querySelector(#username) input.dispatchEvent(new Event(input, { bubbles: true })) ) await client.clickBySelector(.login-btn) // 3. 等待登錄跳轉(zhuǎn) await waitForSelector(client, .customer-list-page, 10000) // 4. 輸入搜索關(guān)鍵字 await client.evaluate( const searchInput document.querySelector(#search-input) const nativeInputValueSetter Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, value).set nativeInputValueSetter.call(searchInput, 張三) searchInput.dispatchEvent(new Event(input, { bubbles: true })) ) await client.clickBySelector(.search-button) // 5. 提取搜索結(jié)果表格數(shù)據(jù) const rows await client.evaluate( (() { const items [] document.querySelectorAll(.customer-table tbody tr).forEach((tr) { items.push({ name: tr.querySelector(.col-name).innerText, phone: tr.querySelector(.col-phone).innerText, status: tr.querySelector(.col-status).innerText }) }) return items })() ) console.log(查詢(xún)到客戶(hù)數(shù)據(jù):, JSON.stringify(rows, null, 2)) // 6. 截圖留檔 const screenshot await client.send(Page.captureScreenshot, { format: png }) require(fs).writeFileSync(result.png, Buffer.from(screenshot.data, base64)) client.ws.close() } async function waitForPageLoad(client) { return new Promise((resolve) { const timer setTimeout(() resolve(), 10000) client.on(Page.loadEventFired, () { clearTimeout(timer) resolve() }) }) } async function waitForSelector(client, selector, timeout 5000) { const start Date.now() while (Date.now() - start timeout) { const exists await client.evaluate(!!document.querySelector(${selector})) if (exists) return true await new Promise((r) setTimeout(r, 200)) } throw new Error(等待超時(shí): 未找到元素 ${selector}) } startAgent().catch((err) { console.error(Agent執(zhí)行出錯(cuò):, err) process.exit(1) })這個(gè)流程跑起來(lái)之后我第一感受是整個(gè)過(guò)程實(shí)在太流暢了。沒(méi)有惱人的坐標(biāo)計(jì)算沒(méi)有脆弱到讓人崩潰的截圖比對(duì)每個(gè)步驟都像在寫(xiě)前端測(cè)試用例。更關(guān)鍵的是調(diào)試體驗(yàn)有了質(zhì)的飛升——CDP協(xié)議自帶的DevTools界面能實(shí)時(shí)看到Agent當(dāng)前操作到了頁(yè)面什么位置出問(wèn)題的時(shí)候打開(kāi)開(kāi)發(fā)者工具立刻就能看清頁(yè)面真實(shí)狀態(tài)。5. 更省力的做法用Puppeteer庫(kù)連接現(xiàn)成的Electron實(shí)例5.1 Puppeteer.connect怎樣復(fù)用已有應(yīng)用人肉手寫(xiě)WebSocket客戶(hù)端的好處是靈活可控所有細(xì)節(jié)都捏在自己手里但日常業(yè)務(wù)開(kāi)發(fā)我更建議直接選用成熟庫(kù)——Puppeteer生態(tài)就是其中一個(gè)相當(dāng)省力的選擇。Puppeteer有個(gè)很實(shí)用的能力不只能自己?jiǎn)?dòng)瀏覽器還能連接一個(gè)已經(jīng)在運(yùn)行的Chromium實(shí)例。這個(gè)模式和我們?cè)贓lectron里用CDP的場(chǎng)景簡(jiǎn)直是天作之合Electron應(yīng)用自己?jiǎn)?dòng)Puppeteer負(fù)責(zé)連上去控制它。這樣Agent代碼寫(xiě)起來(lái)完全不需要關(guān)心WebSocket底層細(xì)節(jié)。const puppeteer require(puppeteer) async function attachToElectron() { const browser await puppeteer.connect({ browserURL: http://127.0.0.1:9222, defaultViewport: null }) const pages await browser.pages() console.log(發(fā)現(xiàn)窗口數(shù)量:, pages.length) // 找到目標(biāo)頁(yè)面 const targetPage pages.find((page) page.title().includes(客戶(hù)管理)) // 現(xiàn)在可以用Page對(duì)象做一切操作了 await targetPage.type(#username, admin) await targetPage.click(.login-btn) await targetPage.waitForSelector(.customer-list-page, { timeout: 10000 }) const data await targetPage.evaluate(() { return document.querySelector(.customer-info).innerText }) console.log(獲取到數(shù)據(jù):, data) }需要重點(diǎn)說(shuō)明一個(gè)參數(shù)defaultViewport: null這個(gè)必須顯式設(shè)置。因?yàn)镻uppeteer默認(rèn)會(huì)給頁(yè)面套一個(gè)800x600的視口如果不關(guān)掉它頁(yè)面布局會(huì)和正常桌面應(yīng)用完全不一樣——某些元素會(huì)被折疊到響應(yīng)式布局的移動(dòng)端形態(tài)里點(diǎn)擊定位全都亂套。連Electron應(yīng)用時(shí)一定要保持應(yīng)用原有的桌面視口。5.2 和手寫(xiě)客戶(hù)端的選型對(duì)比Puppeteer庫(kù)本身還是一層殼它和CDP的關(guān)系可以理解成這樣Puppeteer的API把CDP復(fù)雜的協(xié)議細(xì)節(jié)全部包裝成了緊湊方法page.click對(duì)應(yīng)點(diǎn)擊坐標(biāo)計(jì)算、page.waitForSelector對(duì)應(yīng)輪詢(xún)DOM查詢(xún)、page.evaluate對(duì)應(yīng)運(yùn)行時(shí)求值。該封裝的都封裝好了調(diào)用體驗(yàn)確實(shí)比純手寫(xiě)友好很多。但封裝也意味著控制粒度變粗。如果你需要深度定制協(xié)議行為——比如攔截特定網(wǎng)絡(luò)請(qǐng)求、獲取HTTP響應(yīng)的原始頭部、監(jiān)聽(tīng)復(fù)雜的底層事件流——Puppeteer提供的接口可能又成了阻礙這時(shí)候就得靠page._client().send(Network.getResponseBody)這類(lèi)半私有接口或者干脆自己建WebSocket連接。兩個(gè)方案我給出的適用建議是業(yè)務(wù)邏輯快速驗(yàn)證、Agent原型搭建直接用Puppeteer庫(kù)開(kāi)發(fā)效率最高需要深度定制協(xié)議行為、集成到生產(chǎn)環(huán)境的Agent底座里手寫(xiě)一個(gè)薄客戶(hù)端更可控因?yàn)槊總€(gè)連接狀態(tài)、每條命令的結(jié)果都由你自己管理。我們團(tuán)隊(duì)最終的生產(chǎn)實(shí)現(xiàn)是兩者結(jié)合外部用Puppeteer做交互編排關(guān)鍵底層節(jié)點(diǎn)通過(guò)手寫(xiě)CDP客戶(hù)端做定制擴(kuò)展。各有各擅長(zhǎng)的地方。5.3 連接時(shí)的常見(jiàn)坑Puppeteer連接Electron實(shí)例時(shí)有幾個(gè)點(diǎn)是經(jīng)常踩到的。Puppeteer庫(kù)的版本是一個(gè)關(guān)鍵變量不同大版本的connect實(shí)現(xiàn)細(xì)節(jié)會(huì)有差異。舊版本可能走舊握手流程新版本對(duì)協(xié)議版本的要求也不同。建議優(yōu)先使用當(dāng)前最新的穩(wěn)定版本遇到握手失敗先查版本兼容。連接超時(shí)和環(huán)境變量也要注意默認(rèn)情況下Puppeteer連不上會(huì)很快就報(bào)錯(cuò)可以手動(dòng)加大超時(shí)參數(shù)。同時(shí)檢查啟動(dòng)Electron應(yīng)用的環(huán)境變量里是否設(shè)置了影響Chromium網(wǎng)絡(luò)棧的參數(shù)。還有一個(gè)窗口識(shí)別的問(wèn)題Electron應(yīng)用經(jīng)常會(huì)彈出子窗口、加載iframe、開(kāi)DevTools面板這些都會(huì)在Target列表里多出噪點(diǎn)。找目標(biāo)窗口時(shí)一定要用title字段做精確匹配甚至通過(guò)URL特征過(guò)濾避免連到DevTools或隱藏的后臺(tái)窗口上。6. 實(shí)戰(zhàn)中的棘手問(wèn)題和排查方法6.1 WebSocket連接被403拒絕這個(gè)問(wèn)題的主要原因是前面提到的remote-allow-origins校驗(yàn)。Chrome從某個(gè)版本開(kāi)始對(duì)WebSocket連接有了來(lái)源校驗(yàn)?zāi)J(rèn)拒絕來(lái)自非DevTools前端的連接。Node.js的WebSocket客戶(hù)端發(fā)起的握手請(qǐng)求沒(méi)有合法的Origin來(lái)源會(huì)被服務(wù)端攔下。解決辦法是在Electron主進(jìn)程啟動(dòng)參數(shù)里加上--remote-allow-origins*放開(kāi)來(lái)源限制。如果安全要求比較高也可以把這行參數(shù)改為只允許可信來(lái)源但本地自動(dòng)化場(chǎng)景直接放開(kāi)是最高效的。6.2 獲取不到任何Target列表/json/list接口返回空數(shù)組的原因通常是Electron應(yīng)用沒(méi)有渲染出頁(yè)面窗口。Electron應(yīng)用如果創(chuàng)建了后臺(tái)隱藏窗口或者頁(yè)面還在加載過(guò)程中窗口還沒(méi)注冊(cè)到調(diào)試服務(wù)Target列表就可能短暫為空。處理方案是等待幾秒再刷新列表并過(guò)濾掉type不為page的空條目。還有一種原因是Electron應(yīng)用開(kāi)啟了GPU加速導(dǎo)致的啟動(dòng)異常渲染進(jìn)程崩潰或者卡在初始化階段。用app.disableHardwareAcceleration()關(guān)掉GPU加速再試如果恢復(fù)了就把這個(gè)配置加到生產(chǎn)啟動(dòng)參數(shù)里。6.3 React/Vue框架輸入框值不生效直接給輸入框設(shè)置value屬性然后dispatch事件這是最經(jīng)典的框架綁定失效場(chǎng)景。React或者Vue的受控組件會(huì)維護(hù)自己的內(nèi)部狀態(tài)直接設(shè)置DOM的value屬性框架狀態(tài)完全感知不到表單提交的時(shí)候值始終是空的。解決辦法是用原生屬性描述符的方式觸發(fā)框架的setterconst nativeInputValueSetter Object.getOwnPropertyDescriptor( window.HTMLInputElement.prototype, value ).set nativeInputValueSetter.call(input, 目標(biāo)值) input.dispatchEvent(new Event(input, { bubbles: true }))實(shí)測(cè)下來(lái)這個(gè)方法能穩(wěn)定觸發(fā)React的onChange和Vue的v-model更新。這個(gè)技巧在做Agent自動(dòng)化時(shí)幾乎天天用是繞不開(kāi)的核心技能。6.4 點(diǎn)擊事件不觸發(fā)通過(guò)Input.dispatchMouseEvent派發(fā)鼠標(biāo)事件時(shí)有個(gè)細(xì)節(jié)容易被忽略坐標(biāo)必須換算成相對(duì)視口的坐標(biāo)不能用頁(yè)面的絕對(duì)坐標(biāo)。如果頁(yè)面發(fā)生過(guò)滾動(dòng)絕對(duì)坐標(biāo)點(diǎn)擊的位置就和視覺(jué)上的位置對(duì)不上。另一個(gè)原因是某些按鈕是通過(guò)CSS偽元素覆蓋來(lái)實(shí)現(xiàn)點(diǎn)擊的鼠標(biāo)事件雖然派發(fā)了但事件被覆蓋層攔截掉底層按鈕收不到。這種情況可以先讓Agent檢查一下目標(biāo)元素在視口中的位置有沒(méi)有被其他元素遮擋如果有遮擋就先把遮擋元素移開(kāi)或隱藏再點(diǎn)擊。6.5 執(zhí)行過(guò)程中頁(yè)面跳轉(zhuǎn)過(guò)快頁(yè)面跳轉(zhuǎn)導(dǎo)航時(shí)CDP連接會(huì)自動(dòng)隨著頁(yè)面Target的更新而重建此時(shí)之前建立的連接可能失效。處理邏輯是監(jiān)聽(tīng)Page.frameNavigated事件一旦發(fā)現(xiàn)主框架導(dǎo)航完成就重新獲取文檔樹(shù)和上下文。我之前寫(xiě)過(guò)一個(gè)輪詢(xún)waitForSelector邏輯也遇到過(guò)這個(gè)坑后面加了導(dǎo)航監(jiān)聽(tīng)和重建邏輯后就徹底穩(wěn)定了。Agent在操作過(guò)程中還會(huì)遇到子框架的多層嵌套。定位元素前先確認(rèn)這個(gè)元素是主文檔里的還是iframe里的如果是iframe內(nèi)的元素Runtime.evaluate的計(jì)算上下文要切換成對(duì)應(yīng)的executionContextId不然JS代碼執(zhí)行時(shí)找不到元素。7. 工程化實(shí)踐Agent工具的封裝思路7.1 命令層級(jí)的拆解到這一步CDP連接和基本操作已經(jīng)跑通了。但生產(chǎn)環(huán)境里的Agent不能是系列零散腳本需要工程化地去封裝。我按職責(zé)拆分成了三個(gè)層級(jí)從底層往上依次是連接層、能力層、場(chǎng)景層。連接層負(fù)責(zé)管理WebSocket生命周期、多實(shí)例連接池、斷線重連。能力層基于CDP協(xié)議封裝了元素定位、文本操作、事件派發(fā)、數(shù)據(jù)提取這些通用原子能力。場(chǎng)景層則是根據(jù)具體業(yè)務(wù)流程做的組合比如“登錄流程”、“查詢(xún)流程”、“導(dǎo)出流程”每個(gè)流程都是一串能力層動(dòng)作的有序編排。class AgentConnector { constructor() { this.connections new Map() } async connectInstance(instanceId, port) { const targets await this.getTargets(port) const target targets.find((t) t.title.includes(主窗口)) const client new CDPClient(target.webSocketDebuggerUrl) await client.connect() this.connections.set(instanceId, client) return client } } class ElementActions { constructor(client) { this.client client } async fill(selector, value) { await this.client.evaluate( (() { const el document.querySelector(${selector}) const setter Object.getOwnPropertyDescriptor( window.HTMLInputElement.prototype, value).set setter.call(el, ${value}) el.dispatchEvent(new Event(input, { bubbles: true })) })() ) } async waitText(selector, text, timeout 5000) { /* 輪詢(xún)等待文本出現(xiàn) */ } }7.2 斷線重連與操作補(bǔ)償Electron應(yīng)用理論上不會(huì)頻繁重啟但運(yùn)行幾天后內(nèi)存占用上升、渲染進(jìn)程卡死也是常事。Agent底座必須具備斷線檢測(cè)和自動(dòng)重連能力。我的實(shí)現(xiàn)里把“斷線重連”分成了兩層WebSocket層面的自動(dòng)重連和業(yè)務(wù)操作層面的冪等補(bǔ)償。WebSocket層面監(jiān)聽(tīng)close事件后暫停當(dāng)前任務(wù)按指數(shù)退避策略重新獲取Target列表并重新建立連接。這個(gè)過(guò)程可能失敗幾次但重試個(gè)三五次一般都能恢復(fù)。業(yè)務(wù)層面更復(fù)雜也是經(jīng)驗(yàn)所在。舉個(gè)例子Agent剛點(diǎn)完“提交訂單”按鈕WebSocket斷了重新連上后這個(gè)訂單到底提交成功沒(méi)有頁(yè)面狀態(tài)是什么這時(shí)候需要有一個(gè)“操作驗(yàn)證”環(huán)節(jié)檢查頁(yè)面上的成功提示或狀態(tài)流轉(zhuǎn)判斷操作是否生效。如果沒(méi)生效再按當(dāng)前頁(yè)面狀態(tài)重新定位元素或重新執(zhí)行流程。這個(gè)補(bǔ)償邏輯是個(gè)復(fù)雜的業(yè)務(wù)問(wèn)題但反過(guò)來(lái)也說(shuō)明Agent自動(dòng)化不能只依賴(lài)底層連接更要在業(yè)務(wù)層建立可觀測(cè)、可恢復(fù)的機(jī)制。7.3 并發(fā)控制的策略我們項(xiàng)目后面從單實(shí)例擴(kuò)展到了多實(shí)例并發(fā)并發(fā)控制踩過(guò)的坑也很有參考價(jià)值。CDP連接本身是異步的WebSocket消息可以亂序到達(dá)但CDP協(xié)議要求命令響應(yīng)必須按發(fā)送順序返回嗎其實(shí)不要求每條命令靠id字段關(guān)聯(lián)所以說(shuō)多實(shí)例并發(fā)CDP線程是安全的。真正要注意的是共享資源。Electron應(yīng)用實(shí)例之間如果共享同一個(gè)本地?cái)?shù)據(jù)庫(kù)文件或同一份用戶(hù)配置目錄并發(fā)操作就可能出現(xiàn)文件鎖沖突。我的處理是給每個(gè)實(shí)例分配獨(dú)立的數(shù)據(jù)目錄--user-data-dir/tmp/app-instance-1徹底隔離各自狀態(tài)。這一點(diǎn)在部署時(shí)要格外重視不然跑著跑著某個(gè)實(shí)例就玄學(xué)崩潰。8. 這套方案對(duì)Agent行業(yè)的實(shí)際價(jià)值8.1 從“模擬人”走向“操作對(duì)象”傳統(tǒng)桌面自動(dòng)化軟件的核心思路是想方設(shè)法模擬人的行為——移動(dòng)鼠標(biāo)、敲擊鍵盤(pán)、看著屏幕判斷結(jié)果。而CDP方案本質(zhì)上是直接讀寫(xiě)系統(tǒng)內(nèi)部的對(duì)象模型相當(dāng)于跳過(guò)了模擬路徑直接針對(duì)應(yīng)用的真實(shí)語(yǔ)義結(jié)構(gòu)來(lái)操作。這種轉(zhuǎn)變帶來(lái)的穩(wěn)定性提升不用多說(shuō)更深遠(yuǎn)的意義是讓Agent開(kāi)始具備更準(zhǔn)的“結(jié)構(gòu)理解”。它能知道頁(yè)面上有一個(gè)輸入框叫#phone它的占位符提示是什么它當(dāng)前是否可編輯它的值是否符合校驗(yàn)規(guī)則——這些信息都能通過(guò)一條Runtime.evaluate命令拿到。這個(gè)信息量比單純靠屏幕像素猜目標(biāo)高出好幾個(gè)維度是所有智能決策的基礎(chǔ)。8.2 對(duì)測(cè)試自動(dòng)化和RPA領(lǐng)域的啟發(fā)這個(gè)思路對(duì)自動(dòng)化測(cè)試行業(yè)同樣有很強(qiáng)的參考價(jià)值。傳統(tǒng)UI自動(dòng)化測(cè)試主流方案是各種測(cè)試框架它們各有語(yǔ)法糖但核心思路和CDP是一致的——通過(guò)協(xié)議操作DOM。Electron應(yīng)用如果直接用CDP做測(cè)試優(yōu)勢(shì)是彈窗、系統(tǒng)對(duì)話框、原生菜單都還能繞過(guò)但業(yè)務(wù)功能回歸測(cè)試效率提升直接就是數(shù)量級(jí)的。RPA工具廠商也越來(lái)越多考慮在Electron應(yīng)用上提供CDP通道。既然應(yīng)用是基于Web技術(shù)構(gòu)建的最自然的自動(dòng)化路徑就是Web自動(dòng)化協(xié)議本身而不是做圖像識(shí)別這種吃力不討好的兜底方案?，F(xiàn)在很多RPA產(chǎn)品對(duì)接Electron應(yīng)用都是優(yōu)先走CDP路線實(shí)在沒(méi)有調(diào)試端口才fallback到圖像識(shí)別。8.3 對(duì)未來(lái)AI Agent的啟示我在做這個(gè)項(xiàng)目的過(guò)程中有一個(gè)明顯的體感CDP協(xié)議對(duì)AI Agent來(lái)說(shuō)就像給了它一雙免疫屏幕干擾的精準(zhǔn)手柄。未來(lái)的終端Agent如果要真正具備操作任意軟件完成復(fù)雜任務(wù)的能力應(yīng)用層協(xié)議通道會(huì)比視覺(jué)識(shí)別更可靠也更容易和AI的能力鏈打通?，F(xiàn)在已經(jīng)有智能Agent框架?chē)L試通過(guò)CDP協(xié)議讓大模型直接控制Electron應(yīng)用了大模型輸出意圖Agent框架將其翻譯為CDP命令序列腳本執(zhí)行操作結(jié)果回傳給模型判斷下一步動(dòng)作。這套鏈路一旦跑通AI離真正意義上對(duì)桌面軟件的自主操作就更近了一步。9. 最后的一點(diǎn)心得整套方案做下來(lái)我最大的感受是技術(shù)的核心壁壘往往不在API調(diào)用本身而在于對(duì)底層協(xié)議信息的理解深度。CDP文檔洋洋灑灑幾十個(gè)域真正打開(kāi)能力空間的其實(shí)是理解它的消息模型、事件機(jī)制、上下文限制這些細(xì)節(jié)決定了你能否在復(fù)雜業(yè)務(wù)場(chǎng)景里穩(wěn)定運(yùn)行。具體到這個(gè)方案幾件事值得再做擴(kuò)展連接池和斷線重連已經(jīng)是穩(wěn)定運(yùn)行的基石建議任何Agent項(xiàng)目都優(yōu)先做好這一層每步操作之后都加一層狀態(tài)校驗(yàn)用返回值驅(qū)動(dòng)決策而不是無(wú)腦按時(shí)間線執(zhí)行能省掉大量排查爛攤子的時(shí)間測(cè)試環(huán)境里跑通了先別急著上生產(chǎn)先把異常場(chǎng)景的截圖、日志、記錄全鏈路鋪好出了事才能快速止血操作多實(shí)例時(shí)務(wù)必隔離數(shù)據(jù)目錄和長(zhǎng)期會(huì)話資源否則并發(fā)一上來(lái)就各種靈異現(xiàn)象。如果你計(jì)劃在自己的Electron應(yīng)用上做Agent操作我的建議是最快路徑是先啟動(dòng)應(yīng)用加上調(diào)試端口用Puppeteer連上去寫(xiě)一個(gè)最小Demo把元素定位、事件派發(fā)、數(shù)據(jù)提取跑通再逐步疊加復(fù)雜場(chǎng)景。先把鏈路打通有了真實(shí)手感再談封裝和工程化。CDP這條路一旦走通Agent操作桌面應(yīng)用就不再是卑微的坐標(biāo)游戲而是一場(chǎng)徹底的結(jié)構(gòu)化對(duì)話。 CDP協(xié)議+Electron桌面應(yīng)用自動(dòng)化：原理、實(shí)踐與踩坑指南
我們團(tuán)隊(duì)最近在做一個(gè)“批量流程自動(dòng)化”的內(nèi)部項(xiàng)目核心訴求是讓一個(gè)Agent能夠像人一樣操作我們公司某款Electron桌面客戶(hù)端自動(dòng)完成錄入、查詢(xún)、導(dǎo)出這一連串動(dòng)作。最開(kāi)始想的是圖像識(shí)別加模擬鍵鼠試了幾天發(fā)現(xiàn)全是坑窗口一遮擋坐標(biāo)就偏、高分屏DPI縮放直接讓點(diǎn)擊位置漂移、頁(yè)面元素稍微變個(gè)樣式腳本就崩。后來(lái)我想到Electron的底層其實(shí)是Chromium既然瀏覽器可以通過(guò)CDP協(xié)議被人遠(yuǎn)程控制那Electron桌面應(yīng)用理論上也應(yīng)該可以。折騰了兩周最終用CDP協(xié)議打通了一條完全不同的路子——不依賴(lài)坐標(biāo)、不依賴(lài)圖像識(shí)別直接通過(guò)協(xié)議精準(zhǔn)操作應(yīng)用內(nèi)的DOM元素。這篇文章就把我從零摸到可用的整個(gè)過(guò)程、代碼和踩過(guò)的坑完整記錄下來(lái)希望能給正在做Agent自動(dòng)化操作桌面應(yīng)用的朋友一些參考。剛開(kāi)始接觸CDP協(xié)議時(shí)我以為它只能調(diào)試網(wǎng)頁(yè)但它的能力邊界其實(shí)遠(yuǎn)超“F12開(kāi)發(fā)者工具”的范疇。依賴(lài)DOM和運(yùn)行時(shí)求值我們不僅能在Electron應(yīng)用內(nèi)讀取任意頁(yè)面數(shù)據(jù)、觸發(fā)點(diǎn)擊和輸入事件還能調(diào)用應(yīng)用內(nèi)已經(jīng)暴露的接口、監(jiān)聽(tīng)網(wǎng)絡(luò)請(qǐng)求、攔截響應(yīng)甚至直接操作應(yīng)用內(nèi)部狀態(tài)。這對(duì)Agent來(lái)說(shuō)是個(gè)巨大優(yōu)勢(shì)它可以像真實(shí)用戶(hù)在頁(yè)面上完成操作又不用依賴(lài)脆弱的視覺(jué)算法穩(wěn)定性高出一個(gè)數(shù)量級(jí)。1. 項(xiàng)目思路為什么選擇CDP方案操作Electron應(yīng)用1.1 桌面應(yīng)用自動(dòng)化的三條技術(shù)路線對(duì)比在動(dòng)手之前我認(rèn)真比較過(guò)市面上主流的桌面自動(dòng)化方案大致分成三類(lèi)。第一類(lèi)是傳統(tǒng)鍵鼠模擬工具這類(lèi)方案的思路是記住屏幕上的固定位置然后通過(guò)調(diào)用系統(tǒng)接口移動(dòng)鼠標(biāo)、執(zhí)行點(diǎn)擊和鍵盤(pán)輸入。優(yōu)點(diǎn)是通用性強(qiáng)幾乎什么軟件都能驅(qū)動(dòng)缺點(diǎn)是穩(wěn)定性極度依賴(lài)窗口狀態(tài)。窗口一移動(dòng)、一最小化、一被遮擋整個(gè)腳本就廢了。再加上高DPI環(huán)境下屏幕坐標(biāo)系會(huì)縮放同一個(gè)按鈕在不同分辨率屏幕上的位置完全不同維護(hù)成本很高。第二類(lèi)是圖像識(shí)別方案原理是持續(xù)截屏然后在截圖中用模板匹配或深度學(xué)習(xí)找目標(biāo)元素。這種方案在游戲自動(dòng)化領(lǐng)域用得比較多因?yàn)橛螒颦h(huán)境里沒(méi)有其他控制通道。但在偏辦公類(lèi)的Electron應(yīng)用里它的問(wèn)題是性能開(kāi)銷(xiāo)大、識(shí)別有延遲、而且對(duì)UI微調(diào)過(guò)于敏感。換個(gè)按鈕圓角、改個(gè)圖標(biāo)配色識(shí)別準(zhǔn)確率就會(huì)斷崖式下降。第三類(lèi)就是我要說(shuō)的CDP協(xié)議方案核心思路是Electron應(yīng)用本質(zhì)上跑著一個(gè)完整的Chromium實(shí)例Chromium天然支持遠(yuǎn)程調(diào)試協(xié)議那我們完全可以繞過(guò)屏幕坐標(biāo)直接通過(guò)協(xié)議讀寫(xiě)應(yīng)用內(nèi)DOM、派發(fā)事件、求值JS代碼。這個(gè)方案的好處是穩(wěn)定性極高元素位置隨便變、窗口隨便移動(dòng)都不影響腳本因?yàn)樗僮鞯氖琼?yè)面內(nèi)部的對(duì)象結(jié)構(gòu)而不是屏幕上的像素坐標(biāo)。1.2 CDP方案解決的核心痛點(diǎn)選擇CDP最直接的原因是它解決了我們項(xiàng)目里兩個(gè)最難纏的問(wèn)題。第一個(gè)問(wèn)題是“窗口遮擋”。我們的Agent需要并發(fā)處理多個(gè)任務(wù)經(jīng)常會(huì)在多個(gè)應(yīng)用窗口之間切換傳統(tǒng)鍵鼠方案一旦遇到后臺(tái)窗口被遮擋就完全束手無(wú)策。而CDP方案操作的是頁(yè)面內(nèi)部結(jié)構(gòu)根本不需要窗口處于前臺(tái)甚至窗口最小化了它照樣能執(zhí)行點(diǎn)擊和輸入。這個(gè)特性對(duì)我們來(lái)說(shuō)至關(guān)重要意味著Agent可以同時(shí)“操作”多個(gè)實(shí)例而不用管哪個(gè)窗口在最上面。第二個(gè)問(wèn)題是“元素定位精度”。用了CDP之后定位一個(gè)輸入框就是一句document.querySelector(#username)的事情穩(wěn)定到不管CSS怎么改都能找到。如果元素加了>[客戶(hù)端] ---HTTP GET /json/list--- [Electron應(yīng)用調(diào)試服務(wù)] ---targetId列表--- [客戶(hù)端] ---WebSocket連接 ws://...--- [Electron應(yīng)用調(diào)試服務(wù)] ---發(fā)送命令 {id:1,method:DOM.enable}--- [客戶(hù)端] ---收到結(jié)果 {id:1,result:{}}---日常使用中90%的命令都是單向請(qǐng)求響應(yīng)模式。協(xié)議里也有事件推送機(jī)制比如頁(yè)面加載完成、DOM節(jié)點(diǎn)更新、控制臺(tái)輸出這些都會(huì)主動(dòng)推給客戶(hù)端這點(diǎn)在我們后面做動(dòng)態(tài)等待的時(shí)候會(huì)很關(guān)鍵。2.2 為什么Electron應(yīng)用天然支持CDPElectron應(yīng)用之所以能直接用CDP協(xié)議控制根本原因是它本身就是基于Chromium外殼的。Electron官方其實(shí)屏蔽了一部分Chromium的調(diào)試能力但只要我們啟動(dòng)的時(shí)候加上一個(gè)遠(yuǎn)程調(diào)試端口參數(shù)完整的CDP功能就會(huì)暴露出來(lái)。具體來(lái)說(shuō)在啟動(dòng)Electron應(yīng)用的時(shí)候加上--remote-debugging-port9222Electron主進(jìn)程就會(huì)在9222端口開(kāi)啟一個(gè)調(diào)試服務(wù)。這個(gè)調(diào)試服務(wù)不僅能發(fā)現(xiàn)所有已經(jīng)打開(kāi)的窗口還能讓外部客戶(hù)端通過(guò)CDP協(xié)議和這些窗口的渲染進(jìn)程建立實(shí)時(shí)通信通道。這里有個(gè)Electron特有的坑要特別注意Electron應(yīng)用可能有多個(gè)窗口而每個(gè)窗口在CDP協(xié)議里都是一個(gè)獨(dú)立的Target。所以連接時(shí)要先通過(guò)HTTP接口拿到所有Target列表再根據(jù)title或url字段篩選出我們要操作的那個(gè)窗口而不是默認(rèn)連接第一個(gè)。有一點(diǎn)值得說(shuō)明Electron渲染進(jìn)程和普通Chrome頁(yè)面在CDP層面上幾乎沒(méi)有區(qū)別原本為瀏覽器自動(dòng)化設(shè)計(jì)的工具和庫(kù)在Electron應(yīng)用上都能無(wú)縫使用。這意味著生態(tài)里現(xiàn)成的Node.js庫(kù)、Python客戶(hù)端在這一場(chǎng)景下都能用。2.3 協(xié)議中Agent操作高頻依賴(lài)的能力域CDP協(xié)議按功能劃分了幾十個(gè)模塊做Agent操作時(shí)不需要所有模塊全用熟練掌握下面幾個(gè)就夠覆蓋95%以上的場(chǎng)景了。Runtime域用來(lái)在頁(yè)面上下文里執(zhí)行任意JavaScript代碼這算是整個(gè)協(xié)議最核心的入口。Runtime.evaluate可以執(zhí)行表達(dá)式并返回結(jié)果Runtime.callFunctionOn可以在指定對(duì)象上調(diào)用函數(shù)。Agent的很多操作本質(zhì)上就是組合各種JS代碼去實(shí)現(xiàn)。DOM域負(fù)責(zé)文檔對(duì)象模型的查詢(xún)和操作。DOM.getDocument拿到文檔根節(jié)點(diǎn)、DOM.querySelector從根節(jié)點(diǎn)往下找目標(biāo)元素、DOMDebugger用來(lái)調(diào)試監(jiān)聽(tīng)等。但我們實(shí)際項(xiàng)目里更多是用Runtime.evaluate直接跑document.querySelector來(lái)代替DOM域接口因?yàn)檫@樣寫(xiě)起來(lái)更自然而且要獲取的上下文信息更直接。Input域是模擬用戶(hù)輸入的關(guān)鍵模塊。Input.dispatchMouseEvent可以派發(fā)鼠標(biāo)按下、釋放、移動(dòng)事件Input.dispatchKeyEvent派發(fā)鍵盤(pán)事件。這套接口模擬的是系統(tǒng)輸入層的事件觸發(fā)的行為比直接調(diào)用JS的element.click()更接近真實(shí)用戶(hù)操作會(huì)觸發(fā)完整的鼠標(biāo)懸停、激活、焦點(diǎn)切換等狀態(tài)流。Page域用來(lái)管理系統(tǒng)頁(yè)面狀態(tài)。Page.navigate跳轉(zhuǎn)導(dǎo)航、Page.reload刷新頁(yè)面、Page.captureScreenshot截圖以及Page.setDeviceMetricsOverride模擬設(shè)備尺寸等。對(duì)Agent自動(dòng)操作桌面應(yīng)用來(lái)說(shuō)Page.captureScreenshot在出了問(wèn)題時(shí)抓現(xiàn)場(chǎng)特別有用。Network域能攔截和查看網(wǎng)絡(luò)請(qǐng)求。Agent在操作過(guò)程中可能需要等待某個(gè)接口返回后才能繼續(xù)下一步這個(gè)域可以監(jiān)聽(tīng)請(qǐng)求響應(yīng)作為操作完成與否的判據(jù)。這些模塊組合起來(lái)就能構(gòu)建一個(gè)完整的自動(dòng)化操作閉環(huán)定位元素、讀取狀態(tài)、執(zhí)行交互、驗(yàn)證結(jié)果、異常兜底。3. 環(huán)境準(zhǔn)備啟動(dòng)帶調(diào)試端口的Electron應(yīng)用3.1 修改Electron應(yīng)用啟動(dòng)方式要讓CDP協(xié)議能連上Electron應(yīng)用第一步是讓?xiě)?yīng)用以調(diào)試模式啟動(dòng)。最簡(jiǎn)單的做法是在應(yīng)用入口文件里通過(guò)app.commandLine.appendSwitch添加參數(shù)也可以直接在終端啟動(dòng)命令后面拼接參數(shù)。在終端里啟動(dòng)的命令是這樣的./your-electron-app --remote-debugging-port9222不過(guò)這種方式有個(gè)不方便的地方如果Electron應(yīng)用的啟動(dòng)是通過(guò)雙擊桌面圖標(biāo)完成的那命令行參數(shù)就傳不進(jìn)去。我們項(xiàng)目里的做法是在Electron主進(jìn)程代碼里強(qiáng)制開(kāi)啟調(diào)試端口這樣不管用戶(hù)怎么啟動(dòng)應(yīng)用調(diào)試服務(wù)都會(huì)自動(dòng)掛在預(yù)設(shè)端口上。// main.js const { app } require(electron) app.commandLine.appendSwitch(remote-debugging-port, 9222) app.commandLine.appendSwitch(remote-allow-origins, *) app.whenReady().then(() { // 正常啟動(dòng)應(yīng)用邏輯 })這里有一個(gè)安全相關(guān)的設(shè)置需要格外注意remote-allow-origins參數(shù)如果你不主動(dòng)設(shè)置新版Chromium會(huì)默認(rèn)校驗(yàn)WebSocket連接的來(lái)源域名。我們一開(kāi)始連接時(shí)一直報(bào)403錯(cuò)誤找了好幾輪才發(fā)現(xiàn)是這個(gè)配置問(wèn)題。本地自動(dòng)化場(chǎng)景直接設(shè)為*通配符就行但如果在公網(wǎng)環(huán)境使用一定要收緊這個(gè)配置。3.2 多實(shí)例運(yùn)行時(shí)的端口規(guī)劃我們的Agent要支持并發(fā)操作多個(gè)Electron實(shí)例所以統(tǒng)一的固定端口滿足不了需求。解決方法是讓每個(gè)應(yīng)用實(shí)例啟動(dòng)時(shí)自動(dòng)分配一個(gè)獨(dú)立端口然后把端口號(hào)傳給Agent調(diào)度器。Electron應(yīng)用可以通過(guò)環(huán)境變量來(lái)指定端口號(hào)const debugPort process.env.DEBUG_PORT || 9222 app.commandLine.appendSwitch(remote-debugging-port, debugPort)調(diào)度端為每個(gè)實(shí)例動(dòng)態(tài)分配可用端口#!/bin/bash BASE_PORT9400 for i in {1..5} do CURRENT_PORT$((BASE_PORT i)) DEBUG_PORT$CURRENT_PORT ./your-electron-app echo Instance $i started on port $CURRENT_PORT done這樣多個(gè)實(shí)例就能并行跑在各自獨(dú)立的調(diào)試端口上Agent可以針對(duì)每個(gè)端口各建一條CDP連接互不干擾。實(shí)測(cè)下來(lái)單機(jī)跑幾十個(gè)實(shí)例沒(méi)有性能瓶頸主要卡在內(nèi)存和CPU資源上。3.3 確認(rèn)調(diào)試服務(wù)已就緒應(yīng)用啟動(dòng)之后需要用命令行驗(yàn)證一下調(diào)試服務(wù)是否正常開(kāi)啟。瀏覽器打開(kāi)或curl請(qǐng)求下面這個(gè)地址curl http://127.0.0.1:9222/json/version如果一切正常會(huì)返回一段JSON里面包含Browser版本號(hào)、webSocketDebuggerUrl和chrome-version這些關(guān)鍵信息。再訪問(wèn)/json/list就能看到當(dāng)前應(yīng)用打開(kāi)的每個(gè)頁(yè)面窗口的詳細(xì)信息了。[ { description: , devtoolsFrontendUrl: /devtools/inspector.html?ws127.0.0.1:9222/devtools/page/xxxxx, id: A8C1E992F502CF11B6E9C56F33756D2A, title: 工作臺(tái), type: page, url: file:///app/index.html, webSocketDebuggerUrl: ws://127.0.0.1:9222/devtools/page/A8C1E992F502CF11B6E9C56F33756D2A } ]我這里會(huì)重點(diǎn)看webSocketDebuggerUrl字段它是后續(xù)建立WebSocket連接的入口。而title字段幫我們從多個(gè)窗口里挑出要控制的那一個(gè)。4. 核心實(shí)操用Node.js手寫(xiě)一個(gè)CDP客戶(hù)端4.1 建立WebSocket連接我選擇用Node.js寫(xiě)客戶(hù)端因?yàn)镋lectron應(yīng)用前端本身就是JavaScript環(huán)境而且Node.js的WebSocket生態(tài)非常成熟。項(xiàng)目里用的庫(kù)是ws它輕量穩(wěn)定在NPM上可以直接安裝。npm install ws創(chuàng)建一個(gè)cdp-client.js文件先實(shí)現(xiàn)最基礎(chǔ)的連接邏輯const WebSocket require(ws) class CDPClient { constructor(wsUrl) { this.wsUrl wsUrl this.ws null this.callbacks new Map() this.eventHandlers new Map() this.commandId 0 } connect() { return new Promise((resolve, reject) { this.ws new WebSocket(this.wsUrl, { maxPayload: 256 * 1024 * 1024 }) this.ws.on(open, () { console.log([CDP] WebSocket connected) resolve() }) this.ws.on(message, (data) { const msg JSON.parse(data.toString()) if (msg.id) { const callback this.callbacks.get(msg.id) if (callback) { this.callbacks.delete(msg.id) if (msg.error) { callback.reject(new Error(msg.error.message)) } else { callback.resolve(msg.result) } } } else { // 事件消息 const handlers this.eventHandlers.get(msg.method) if (handlers) { handlers.forEach((handler) handler(msg.params)) } } }) this.ws.on(error, (err) { console.error([CDP] WebSocket error:, err.message) reject(err) }) this.ws.on(close, () { console.log([CDP] WebSocket closed) }) }) } send(method, params {}) { return new Promise((resolve, reject) { const id this.commandId this.callbacks.set(id, { resolve, reject }) this.ws.send(JSON.stringify({ id, method, params })) }) } on(method, handler) { if (!this.eventHandlers.has(method)) { this.eventHandlers.set(method, []) } this.eventHandlers.get(method).push(handler) } }這個(gè)實(shí)現(xiàn)里藏了一個(gè)特別重要的細(xì)節(jié)maxPayload參數(shù)一定要調(diào)大。Chromium的CDP服務(wù)端默認(rèn)消息大小限制很低但我們的自動(dòng)化場(chǎng)景里經(jīng)常要一次傳輸大量DOM數(shù)據(jù)尤其頁(yè)面復(fù)雜時(shí)DOM.getDocument接口返回的序列化結(jié)果可能達(dá)到幾十MB。不調(diào)大這個(gè)參數(shù)消息一超過(guò)限制WebSocket就會(huì)靜默斷開(kāi)排查起來(lái)讓人非常抓狂。4.2 常用命令封裝連接建立后我會(huì)把高頻操作封裝成一個(gè)個(gè)獨(dú)立方法這樣Agent邏輯層寫(xiě)起來(lái)就像調(diào)用本地函數(shù)一樣自然。class CDPClient { // 獲取文檔樹(shù) async getDocument() { const result await this.send(DOM.getDocument, { depth: -1 }) return result.root } // 通過(guò)選擇器查找元素節(jié)點(diǎn)ID async querySelector(nodeId, selector) { const result await this.send(DOM.querySelector, { nodeId, selector }) return result.nodeId } // 執(zhí)行JavaScript表達(dá)式 async evaluate(expression, awaitPromise true) { const result await this.send(Runtime.evaluate, { expression, awaitPromise, returnByValue: true }) if (result.exceptionDetails) { throw new Error(頁(yè)面執(zhí)行JS出錯(cuò): result.exceptionDetails.text) } return result.result.value } // 模擬鼠標(biāo)點(diǎn)擊基于元素中心坐標(biāo) async clickBySelector(selector) { const expr (() { const el document.querySelector(${selector}) if (!el) return null const rect el.getBoundingClientRect() return { x: rect.left rect.width / 2, y: rect.top rect.height / 2, text: el.innerText } })() const { x, y } await this.evaluate(expr) if (x null) return false await this.send(Input.dispatchMouseEvent, { type: mousePressed, x: Math.round(x), y: Math.round(y), button: left, clickCount: 1 }) await this.send(Input.dispatchMouseEvent, { type: mouseReleased, x: Math.round(x), y: Math.round(y), button: left, clickCount: 1 }) return true } }這里關(guān)于點(diǎn)擊坐標(biāo)有個(gè)需要說(shuō)清楚的關(guān)鍵細(xì)節(jié)頁(yè)面里的getBoundingClientRect()拿到的是CSS像素坐標(biāo)而Input.dispatchMouseEvent默認(rèn)按物理像素解釋兩者在非100%縮放比下會(huì)不一致。Electron應(yīng)用頁(yè)面里如果設(shè)置了zoomFactor或系統(tǒng)DPI縮放坐標(biāo)就會(huì)偏移。穩(wěn)妥的做法是在連接建立后先讀取設(shè)備的縮放比例然后把坐標(biāo)手動(dòng)換算過(guò)去。async getDeviceMetrics() { const metrics await this.send(Page.getLayoutMetrics) const { cssScaleFactor } metrics return { scaleFactor: cssScaleFactor, viewportWidth: metrics.cssLayoutViewport.clientWidth, viewportHeight: metrics.cssLayoutViewport.clientHeight } }拿到cssScaleFactor之后凡是需要派發(fā)鼠標(biāo)事件的坐標(biāo)統(tǒng)統(tǒng)用x / scaleFactor換算后再發(fā)給CDP服務(wù)端就能徹底規(guī)避縮放導(dǎo)致的點(diǎn)擊偏移問(wèn)題。4.3 完整操作流程示例下面給一個(gè)Agent自動(dòng)登錄并執(zhí)行查詢(xún)的完整代碼示例這里模擬的場(chǎng)景是打開(kāi)某個(gè)客戶(hù)管理桌面應(yīng)用自動(dòng)登錄、跳轉(zhuǎn)到客戶(hù)列表頁(yè)、輸入關(guān)鍵字搜索、提取搜索結(jié)果。const CDPClient require(./cdp-client) async function getTargetList(baseUrl) { const res await fetch(http://127.0.0.1:9222/json/list) const targets await res.json() return targets.filter((t) t.type page) } async function startAgent() { const targets await getTargetList(http://127.0.0.1:9222) const target targets.find((t) t.title.includes(客戶(hù)管理)) if (!target) { throw new Error(未找到目標(biāo)窗口請(qǐng)檢查應(yīng)用是否已打開(kāi)客戶(hù)管理界面) } const client new CDPClient(target.webSocketDebuggerUrl) await client.connect() // 啟用相關(guān)域 await client.send(Runtime.enable) await client.send(Page.enable) // 1. 等待頁(yè)面加載完成 await client.send(Page.reload) await waitForPageLoad(client) // 2. 自動(dòng)填充登錄表單 await client.evaluate( document.querySelector(#username).value admin document.querySelector(#password).value 123456 ) // 觸發(fā)React/Vue框架的input事件 await client.evaluate( const input document.querySelector(#username) input.dispatchEvent(new Event(input, { bubbles: true })) ) await client.clickBySelector(.login-btn) // 3. 等待登錄跳轉(zhuǎn) await waitForSelector(client, .customer-list-page, 10000) // 4. 輸入搜索關(guān)鍵字 await client.evaluate( const searchInput document.querySelector(#search-input) const nativeInputValueSetter Object.getOwnPropertyDescriptor(window.HTMLInputElement.prototype, value).set nativeInputValueSetter.call(searchInput, 張三) searchInput.dispatchEvent(new Event(input, { bubbles: true })) ) await client.clickBySelector(.search-button) // 5. 提取搜索結(jié)果表格數(shù)據(jù) const rows await client.evaluate( (() { const items [] document.querySelectorAll(.customer-table tbody tr).forEach((tr) { items.push({ name: tr.querySelector(.col-name).innerText, phone: tr.querySelector(.col-phone).innerText, status: tr.querySelector(.col-status).innerText }) }) return items })() ) console.log(查詢(xún)到客戶(hù)數(shù)據(jù):, JSON.stringify(rows, null, 2)) // 6. 截圖留檔 const screenshot await client.send(Page.captureScreenshot, { format: png }) require(fs).writeFileSync(result.png, Buffer.from(screenshot.data, base64)) client.ws.close() } async function waitForPageLoad(client) { return new Promise((resolve) { const timer setTimeout(() resolve(), 10000) client.on(Page.loadEventFired, () { clearTimeout(timer) resolve() }) }) } async function waitForSelector(client, selector, timeout 5000) { const start Date.now() while (Date.now() - start timeout) { const exists await client.evaluate(!!document.querySelector(${selector})) if (exists) return true await new Promise((r) setTimeout(r, 200)) } throw new Error(等待超時(shí): 未找到元素 ${selector}) } startAgent().catch((err) { console.error(Agent執(zhí)行出錯(cuò):, err) process.exit(1) })這個(gè)流程跑起來(lái)之后我第一感受是整個(gè)過(guò)程實(shí)在太流暢了。沒(méi)有惱人的坐標(biāo)計(jì)算沒(méi)有脆弱到讓人崩潰的截圖比對(duì)每個(gè)步驟都像在寫(xiě)前端測(cè)試用例。更關(guān)鍵的是調(diào)試體驗(yàn)有了質(zhì)的飛升——CDP協(xié)議自帶的DevTools界面能實(shí)時(shí)看到Agent當(dāng)前操作到了頁(yè)面什么位置出問(wèn)題的時(shí)候打開(kāi)開(kāi)發(fā)者工具立刻就能看清頁(yè)面真實(shí)狀態(tài)。5. 更省力的做法用Puppeteer庫(kù)連接現(xiàn)成的Electron實(shí)例5.1 Puppeteer.connect怎樣復(fù)用已有應(yīng)用人肉手寫(xiě)WebSocket客戶(hù)端的好處是靈活可控所有細(xì)節(jié)都捏在自己手里但日常業(yè)務(wù)開(kāi)發(fā)我更建議直接選用成熟庫(kù)——Puppeteer生態(tài)就是其中一個(gè)相當(dāng)省力的選擇。Puppeteer有個(gè)很實(shí)用的能力不只能自己?jiǎn)?dòng)瀏覽器還能連接一個(gè)已經(jīng)在運(yùn)行的Chromium實(shí)例。這個(gè)模式和我們?cè)贓lectron里用CDP的場(chǎng)景簡(jiǎn)直是天作之合Electron應(yīng)用自己?jiǎn)?dòng)Puppeteer負(fù)責(zé)連上去控制它。這樣Agent代碼寫(xiě)起來(lái)完全不需要關(guān)心WebSocket底層細(xì)節(jié)。const puppeteer require(puppeteer) async function attachToElectron() { const browser await puppeteer.connect({ browserURL: http://127.0.0.1:9222, defaultViewport: null }) const pages await browser.pages() console.log(發(fā)現(xiàn)窗口數(shù)量:, pages.length) // 找到目標(biāo)頁(yè)面 const targetPage pages.find((page) page.title().includes(客戶(hù)管理)) // 現(xiàn)在可以用Page對(duì)象做一切操作了 await targetPage.type(#username, admin) await targetPage.click(.login-btn) await targetPage.waitForSelector(.customer-list-page, { timeout: 10000 }) const data await targetPage.evaluate(() { return document.querySelector(.customer-info).innerText }) console.log(獲取到數(shù)據(jù):, data) }需要重點(diǎn)說(shuō)明一個(gè)參數(shù)defaultViewport: null這個(gè)必須顯式設(shè)置。因?yàn)镻uppeteer默認(rèn)會(huì)給頁(yè)面套一個(gè)800x600的視口如果不關(guān)掉它頁(yè)面布局會(huì)和正常桌面應(yīng)用完全不一樣——某些元素會(huì)被折疊到響應(yīng)式布局的移動(dòng)端形態(tài)里點(diǎn)擊定位全都亂套。連Electron應(yīng)用時(shí)一定要保持應(yīng)用原有的桌面視口。5.2 和手寫(xiě)客戶(hù)端的選型對(duì)比Puppeteer庫(kù)本身還是一層殼它和CDP的關(guān)系可以理解成這樣Puppeteer的API把CDP復(fù)雜的協(xié)議細(xì)節(jié)全部包裝成了緊湊方法page.click對(duì)應(yīng)點(diǎn)擊坐標(biāo)計(jì)算、page.waitForSelector對(duì)應(yīng)輪詢(xún)DOM查詢(xún)、page.evaluate對(duì)應(yīng)運(yùn)行時(shí)求值。該封裝的都封裝好了調(diào)用體驗(yàn)確實(shí)比純手寫(xiě)友好很多。但封裝也意味著控制粒度變粗。如果你需要深度定制協(xié)議行為——比如攔截特定網(wǎng)絡(luò)請(qǐng)求、獲取HTTP響應(yīng)的原始頭部、監(jiān)聽(tīng)復(fù)雜的底層事件流——Puppeteer提供的接口可能又成了阻礙這時(shí)候就得靠page._client().send(Network.getResponseBody)這類(lèi)半私有接口或者干脆自己建WebSocket連接。兩個(gè)方案我給出的適用建議是業(yè)務(wù)邏輯快速驗(yàn)證、Agent原型搭建直接用Puppeteer庫(kù)開(kāi)發(fā)效率最高需要深度定制協(xié)議行為、集成到生產(chǎn)環(huán)境的Agent底座里手寫(xiě)一個(gè)薄客戶(hù)端更可控因?yàn)槊總€(gè)連接狀態(tài)、每條命令的結(jié)果都由你自己管理。我們團(tuán)隊(duì)最終的生產(chǎn)實(shí)現(xiàn)是兩者結(jié)合外部用Puppeteer做交互編排關(guān)鍵底層節(jié)點(diǎn)通過(guò)手寫(xiě)CDP客戶(hù)端做定制擴(kuò)展。各有各擅長(zhǎng)的地方。5.3 連接時(shí)的常見(jiàn)坑Puppeteer連接Electron實(shí)例時(shí)有幾個(gè)點(diǎn)是經(jīng)常踩到的。Puppeteer庫(kù)的版本是一個(gè)關(guān)鍵變量不同大版本的connect實(shí)現(xiàn)細(xì)節(jié)會(huì)有差異。舊版本可能走舊握手流程新版本對(duì)協(xié)議版本的要求也不同。建議優(yōu)先使用當(dāng)前最新的穩(wěn)定版本遇到握手失敗先查版本兼容。連接超時(shí)和環(huán)境變量也要注意默認(rèn)情況下Puppeteer連不上會(huì)很快就報(bào)錯(cuò)可以手動(dòng)加大超時(shí)參數(shù)。同時(shí)檢查啟動(dòng)Electron應(yīng)用的環(huán)境變量里是否設(shè)置了影響Chromium網(wǎng)絡(luò)棧的參數(shù)。還有一個(gè)窗口識(shí)別的問(wèn)題Electron應(yīng)用經(jīng)常會(huì)彈出子窗口、加載iframe、開(kāi)DevTools面板這些都會(huì)在Target列表里多出噪點(diǎn)。找目標(biāo)窗口時(shí)一定要用title字段做精確匹配甚至通過(guò)URL特征過(guò)濾避免連到DevTools或隱藏的后臺(tái)窗口上。6. 實(shí)戰(zhàn)中的棘手問(wèn)題和排查方法6.1 WebSocket連接被403拒絕這個(gè)問(wèn)題的主要原因是前面提到的remote-allow-origins校驗(yàn)。Chrome從某個(gè)版本開(kāi)始對(duì)WebSocket連接有了來(lái)源校驗(yàn)?zāi)J(rèn)拒絕來(lái)自非DevTools前端的連接。Node.js的WebSocket客戶(hù)端發(fā)起的握手請(qǐng)求沒(méi)有合法的Origin來(lái)源會(huì)被服務(wù)端攔下。解決辦法是在Electron主進(jìn)程啟動(dòng)參數(shù)里加上--remote-allow-origins*放開(kāi)來(lái)源限制。如果安全要求比較高也可以把這行參數(shù)改為只允許可信來(lái)源但本地自動(dòng)化場(chǎng)景直接放開(kāi)是最高效的。6.2 獲取不到任何Target列表/json/list接口返回空數(shù)組的原因通常是Electron應(yīng)用沒(méi)有渲染出頁(yè)面窗口。Electron應(yīng)用如果創(chuàng)建了后臺(tái)隱藏窗口或者頁(yè)面還在加載過(guò)程中窗口還沒(méi)注冊(cè)到調(diào)試服務(wù)Target列表就可能短暫為空。處理方案是等待幾秒再刷新列表并過(guò)濾掉type不為page的空條目。還有一種原因是Electron應(yīng)用開(kāi)啟了GPU加速導(dǎo)致的啟動(dòng)異常渲染進(jìn)程崩潰或者卡在初始化階段。用app.disableHardwareAcceleration()關(guān)掉GPU加速再試如果恢復(fù)了就把這個(gè)配置加到生產(chǎn)啟動(dòng)參數(shù)里。6.3 React/Vue框架輸入框值不生效直接給輸入框設(shè)置value屬性然后dispatch事件這是最經(jīng)典的框架綁定失效場(chǎng)景。React或者Vue的受控組件會(huì)維護(hù)自己的內(nèi)部狀態(tài)直接設(shè)置DOM的value屬性框架狀態(tài)完全感知不到表單提交的時(shí)候值始終是空的。解決辦法是用原生屬性描述符的方式觸發(fā)框架的setterconst nativeInputValueSetter Object.getOwnPropertyDescriptor( window.HTMLInputElement.prototype, value ).set nativeInputValueSetter.call(input, 目標(biāo)值) input.dispatchEvent(new Event(input, { bubbles: true }))實(shí)測(cè)下來(lái)這個(gè)方法能穩(wěn)定觸發(fā)React的onChange和Vue的v-model更新。這個(gè)技巧在做Agent自動(dòng)化時(shí)幾乎天天用是繞不開(kāi)的核心技能。6.4 點(diǎn)擊事件不觸發(fā)通過(guò)Input.dispatchMouseEvent派發(fā)鼠標(biāo)事件時(shí)有個(gè)細(xì)節(jié)容易被忽略坐標(biāo)必須換算成相對(duì)視口的坐標(biāo)不能用頁(yè)面的絕對(duì)坐標(biāo)。如果頁(yè)面發(fā)生過(guò)滾動(dòng)絕對(duì)坐標(biāo)點(diǎn)擊的位置就和視覺(jué)上的位置對(duì)不上。另一個(gè)原因是某些按鈕是通過(guò)CSS偽元素覆蓋來(lái)實(shí)現(xiàn)點(diǎn)擊的鼠標(biāo)事件雖然派發(fā)了但事件被覆蓋層攔截掉底層按鈕收不到。這種情況可以先讓Agent檢查一下目標(biāo)元素在視口中的位置有沒(méi)有被其他元素遮擋如果有遮擋就先把遮擋元素移開(kāi)或隱藏再點(diǎn)擊。6.5 執(zhí)行過(guò)程中頁(yè)面跳轉(zhuǎn)過(guò)快頁(yè)面跳轉(zhuǎn)導(dǎo)航時(shí)CDP連接會(huì)自動(dòng)隨著頁(yè)面Target的更新而重建此時(shí)之前建立的連接可能失效。處理邏輯是監(jiān)聽(tīng)Page.frameNavigated事件一旦發(fā)現(xiàn)主框架導(dǎo)航完成就重新獲取文檔樹(shù)和上下文。我之前寫(xiě)過(guò)一個(gè)輪詢(xún)waitForSelector邏輯也遇到過(guò)這個(gè)坑后面加了導(dǎo)航監(jiān)聽(tīng)和重建邏輯后就徹底穩(wěn)定了。Agent在操作過(guò)程中還會(huì)遇到子框架的多層嵌套。定位元素前先確認(rèn)這個(gè)元素是主文檔里的還是iframe里的如果是iframe內(nèi)的元素Runtime.evaluate的計(jì)算上下文要切換成對(duì)應(yīng)的executionContextId不然JS代碼執(zhí)行時(shí)找不到元素。7. 工程化實(shí)踐Agent工具的封裝思路7.1 命令層級(jí)的拆解到這一步CDP連接和基本操作已經(jīng)跑通了。但生產(chǎn)環(huán)境里的Agent不能是系列零散腳本需要工程化地去封裝。我按職責(zé)拆分成了三個(gè)層級(jí)從底層往上依次是連接層、能力層、場(chǎng)景層。連接層負(fù)責(zé)管理WebSocket生命周期、多實(shí)例連接池、斷線重連。能力層基于CDP協(xié)議封裝了元素定位、文本操作、事件派發(fā)、數(shù)據(jù)提取這些通用原子能力。場(chǎng)景層則是根據(jù)具體業(yè)務(wù)流程做的組合比如“登錄流程”、“查詢(xún)流程”、“導(dǎo)出流程”每個(gè)流程都是一串能力層動(dòng)作的有序編排。class AgentConnector { constructor() { this.connections new Map() } async connectInstance(instanceId, port) { const targets await this.getTargets(port) const target targets.find((t) t.title.includes(主窗口)) const client new CDPClient(target.webSocketDebuggerUrl) await client.connect() this.connections.set(instanceId, client) return client } } class ElementActions { constructor(client) { this.client client } async fill(selector, value) { await this.client.evaluate( (() { const el document.querySelector(${selector}) const setter Object.getOwnPropertyDescriptor( window.HTMLInputElement.prototype, value).set setter.call(el, ${value}) el.dispatchEvent(new Event(input, { bubbles: true })) })() ) } async waitText(selector, text, timeout 5000) { /* 輪詢(xún)等待文本出現(xiàn) */ } }7.2 斷線重連與操作補(bǔ)償Electron應(yīng)用理論上不會(huì)頻繁重啟但運(yùn)行幾天后內(nèi)存占用上升、渲染進(jìn)程卡死也是常事。Agent底座必須具備斷線檢測(cè)和自動(dòng)重連能力。我的實(shí)現(xiàn)里把“斷線重連”分成了兩層WebSocket層面的自動(dòng)重連和業(yè)務(wù)操作層面的冪等補(bǔ)償。WebSocket層面監(jiān)聽(tīng)close事件后暫停當(dāng)前任務(wù)按指數(shù)退避策略重新獲取Target列表并重新建立連接。這個(gè)過(guò)程可能失敗幾次但重試個(gè)三五次一般都能恢復(fù)。業(yè)務(wù)層面更復(fù)雜也是經(jīng)驗(yàn)所在。舉個(gè)例子Agent剛點(diǎn)完“提交訂單”按鈕WebSocket斷了重新連上后這個(gè)訂單到底提交成功沒(méi)有頁(yè)面狀態(tài)是什么這時(shí)候需要有一個(gè)“操作驗(yàn)證”環(huán)節(jié)檢查頁(yè)面上的成功提示或狀態(tài)流轉(zhuǎn)判斷操作是否生效。如果沒(méi)生效再按當(dāng)前頁(yè)面狀態(tài)重新定位元素或重新執(zhí)行流程。這個(gè)補(bǔ)償邏輯是個(gè)復(fù)雜的業(yè)務(wù)問(wèn)題但反過(guò)來(lái)也說(shuō)明Agent自動(dòng)化不能只依賴(lài)底層連接更要在業(yè)務(wù)層建立可觀測(cè)、可恢復(fù)的機(jī)制。7.3 并發(fā)控制的策略我們項(xiàng)目后面從單實(shí)例擴(kuò)展到了多實(shí)例并發(fā)并發(fā)控制踩過(guò)的坑也很有參考價(jià)值。CDP連接本身是異步的WebSocket消息可以亂序到達(dá)但CDP協(xié)議要求命令響應(yīng)必須按發(fā)送順序返回嗎其實(shí)不要求每條命令靠id字段關(guān)聯(lián)所以說(shuō)多實(shí)例并發(fā)CDP線程是安全的。真正要注意的是共享資源。Electron應(yīng)用實(shí)例之間如果共享同一個(gè)本地?cái)?shù)據(jù)庫(kù)文件或同一份用戶(hù)配置目錄并發(fā)操作就可能出現(xiàn)文件鎖沖突。我的處理是給每個(gè)實(shí)例分配獨(dú)立的數(shù)據(jù)目錄--user-data-dir/tmp/app-instance-1徹底隔離各自狀態(tài)。這一點(diǎn)在部署時(shí)要格外重視不然跑著跑著某個(gè)實(shí)例就玄學(xué)崩潰。8. 這套方案對(duì)Agent行業(yè)的實(shí)際價(jià)值8.1 從“模擬人”走向“操作對(duì)象”傳統(tǒng)桌面自動(dòng)化軟件的核心思路是想方設(shè)法模擬人的行為——移動(dòng)鼠標(biāo)、敲擊鍵盤(pán)、看著屏幕判斷結(jié)果。而CDP方案本質(zhì)上是直接讀寫(xiě)系統(tǒng)內(nèi)部的對(duì)象模型相當(dāng)于跳過(guò)了模擬路徑直接針對(duì)應(yīng)用的真實(shí)語(yǔ)義結(jié)構(gòu)來(lái)操作。這種轉(zhuǎn)變帶來(lái)的穩(wěn)定性提升不用多說(shuō)更深遠(yuǎn)的意義是讓Agent開(kāi)始具備更準(zhǔn)的“結(jié)構(gòu)理解”。它能知道頁(yè)面上有一個(gè)輸入框叫#phone它的占位符提示是什么它當(dāng)前是否可編輯它的值是否符合校驗(yàn)規(guī)則——這些信息都能通過(guò)一條Runtime.evaluate命令拿到。這個(gè)信息量比單純靠屏幕像素猜目標(biāo)高出好幾個(gè)維度是所有智能決策的基礎(chǔ)。8.2 對(duì)測(cè)試自動(dòng)化和RPA領(lǐng)域的啟發(fā)這個(gè)思路對(duì)自動(dòng)化測(cè)試行業(yè)同樣有很強(qiáng)的參考價(jià)值。傳統(tǒng)UI自動(dòng)化測(cè)試主流方案是各種測(cè)試框架它們各有語(yǔ)法糖但核心思路和CDP是一致的——通過(guò)協(xié)議操作DOM。Electron應(yīng)用如果直接用CDP做測(cè)試優(yōu)勢(shì)是彈窗、系統(tǒng)對(duì)話框、原生菜單都還能繞過(guò)但業(yè)務(wù)功能回歸測(cè)試效率提升直接就是數(shù)量級(jí)的。RPA工具廠商也越來(lái)越多考慮在Electron應(yīng)用上提供CDP通道。既然應(yīng)用是基于Web技術(shù)構(gòu)建的最自然的自動(dòng)化路徑就是Web自動(dòng)化協(xié)議本身而不是做圖像識(shí)別這種吃力不討好的兜底方案?，F(xiàn)在很多RPA產(chǎn)品對(duì)接Electron應(yīng)用都是優(yōu)先走CDP路線實(shí)在沒(méi)有調(diào)試端口才fallback到圖像識(shí)別。8.3 對(duì)未來(lái)AI Agent的啟示我在做這個(gè)項(xiàng)目的過(guò)程中有一個(gè)明顯的體感CDP協(xié)議對(duì)AI Agent來(lái)說(shuō)就像給了它一雙免疫屏幕干擾的精準(zhǔn)手柄。未來(lái)的終端Agent如果要真正具備操作任意軟件完成復(fù)雜任務(wù)的能力應(yīng)用層協(xié)議通道會(huì)比視覺(jué)識(shí)別更可靠也更容易和AI的能力鏈打通?，F(xiàn)在已經(jīng)有智能Agent框架?chē)L試通過(guò)CDP協(xié)議讓大模型直接控制Electron應(yīng)用了大模型輸出意圖Agent框架將其翻譯為CDP命令序列腳本執(zhí)行操作結(jié)果回傳給模型判斷下一步動(dòng)作。這套鏈路一旦跑通AI離真正意義上對(duì)桌面軟件的自主操作就更近了一步。9. 最后的一點(diǎn)心得整套方案做下來(lái)我最大的感受是技術(shù)的核心壁壘往往不在API調(diào)用本身而在于對(duì)底層協(xié)議信息的理解深度。CDP文檔洋洋灑灑幾十個(gè)域真正打開(kāi)能力空間的其實(shí)是理解它的消息模型、事件機(jī)制、上下文限制這些細(xì)節(jié)決定了你能否在復(fù)雜業(yè)務(wù)場(chǎng)景里穩(wěn)定運(yùn)行。具體到這個(gè)方案幾件事值得再做擴(kuò)展連接池和斷線重連已經(jīng)是穩(wěn)定運(yùn)行的基石建議任何Agent項(xiàng)目都優(yōu)先做好這一層每步操作之后都加一層狀態(tài)校驗(yàn)用返回值驅(qū)動(dòng)決策而不是無(wú)腦按時(shí)間線執(zhí)行能省掉大量排查爛攤子的時(shí)間測(cè)試環(huán)境里跑通了先別急著上生產(chǎn)先把異常場(chǎng)景的截圖、日志、記錄全鏈路鋪好出了事才能快速止血操作多實(shí)例時(shí)務(wù)必隔離數(shù)據(jù)目錄和長(zhǎng)期會(huì)話資源否則并發(fā)一上來(lái)就各種靈異現(xiàn)象。如果你計(jì)劃在自己的Electron應(yīng)用上做Agent操作我的建議是最快路徑是先啟動(dòng)應(yīng)用加上調(diào)試端口用Puppeteer連上去寫(xiě)一個(gè)最小Demo把元素定位、事件派發(fā)、數(shù)據(jù)提取跑通再逐步疊加復(fù)雜場(chǎng)景。先把鏈路打通有了真實(shí)手感再談封裝和工程化。CDP這條路一旦走通Agent操作桌面應(yīng)用就不再是卑微的坐標(biāo)游戲而是一場(chǎng)徹底的結(jié)構(gòu)化對(duì)話。