我們團(tuán)隊(duì)最近在做一個(gè)“批量流程自動(dòng)化”的內(nèi)部項(xiàng)目核心訴求是讓一個(gè)Agent能夠像人一樣操作我們公司某款Electron桌面客戶端自動(dòng)完成錄入、查詢、導(dǎo)出這一連串動(dòng)作。最開始想的是圖像識(shí)別加模擬鍵鼠試了幾天發(fā)現(xiàn)全是坑窗口一遮擋坐標(biāo)就偏、高分屏DPI縮放直接讓點(diǎn)擊位置漂移、頁面元素稍微變個(gè)樣式腳本就崩。后來我想到Electron的底層其實(shí)是Chromium既然瀏覽器可以通過CDP協(xié)議被人遠(yuǎn)程控制那Electron桌面應(yīng)用理論上也應(yīng)該可以。折騰了兩周最終用CDP協(xié)議打通了一條完全不同的路子——不依賴坐標(biāo)、不依賴圖像識(shí)別直接通過協(xié)議精準(zhǔn)操作應(yīng)用內(nèi)的DOM元素。這篇文章就把我從零摸到可用的整個(gè)過程、代碼和踩過的坑完整記錄下來希望能給正在做Agent自動(dòng)化操作桌面應(yīng)用的朋友一些參考。剛開始接觸CDP協(xié)議時(shí)我以為它只能調(diào)試網(wǎng)頁但它的能力邊界其實(shí)遠(yuǎn)超“F12開發(fā)者工具”的范疇。依賴DOM和運(yùn)行時(shí)求值我們不僅能在Electron應(yīng)用內(nèi)讀取任意頁面數(shù)據(jù)、觸發(fā)點(diǎn)擊和輸入事件還能調(diào)用應(yīng)用內(nèi)已經(jīng)暴露的接口、監(jiān)聽網(wǎng)絡(luò)請(qǐng)求、攔截響應(yīng)甚至直接操作應(yīng)用內(nèi)部狀態(tài)。這對(duì)Agent來說是個(gè)巨大優(yōu)勢(shì)它可以像真實(shí)用戶在頁面上完成操作又不用依賴脆弱的視覺算法穩(wěn)定性高出一個(gè)數(shù)量級(jí)。1. 項(xiàng)目思路為什么選擇CDP方案操作Electron應(yīng)用1.1 桌面應(yīng)用自動(dòng)化的三條技術(shù)路線對(duì)比在動(dòng)手之前我認(rèn)真比較過市面上主流的桌面自動(dòng)化方案大致分成三類。第一類是傳統(tǒng)鍵鼠模擬工具這類方案的思路是記住屏幕上的固定位置然后通過調(diào)用系統(tǒng)接口移動(dòng)鼠標(biāo)、執(zhí)行點(diǎn)擊和鍵盤輸入。優(yōu)點(diǎn)是通用性強(qiáng)幾乎什么軟件都能驅(qū)動(dòng)缺點(diǎn)是穩(wěn)定性極度依賴窗口狀態(tài)。窗口一移動(dòng)、一最小化、一被遮擋整個(gè)腳本就廢了。再加上高DPI環(huán)境下屏幕坐標(biāo)系會(huì)縮放同一個(gè)按鈕在不同分辨率屏幕上的位置完全不同維護(hù)成本很高。第二類是圖像識(shí)別方案原理是持續(xù)截屏然后在截圖中用模板匹配或深度學(xué)習(xí)找目標(biāo)元素。這種方案在游戲自動(dòng)化領(lǐng)域用得比較多因?yàn)橛螒颦h(huán)境里沒有其他控制通道。但在偏辦公類的Electron應(yīng)用里它的問題是性能開銷大、識(shí)別有延遲、而且對(duì)UI微調(diào)過于敏感。換個(gè)按鈕圓角、改個(gè)圖標(biāo)配色識(shí)別準(zhǔn)確率就會(huì)斷崖式下降。第三類就是我要說的CDP協(xié)議方案核心思路是Electron應(yīng)用本質(zhì)上跑著一個(gè)完整的Chromium實(shí)例Chromium天然支持遠(yuǎn)程調(diào)試協(xié)議那我們完全可以繞過屏幕坐標(biāo)直接通過協(xié)議讀寫應(yīng)用內(nèi)DOM、派發(fā)事件、求值JS代碼。這個(gè)方案的好處是穩(wěn)定性極高元素位置隨便變、窗口隨便移動(dòng)都不影響腳本因?yàn)樗僮鞯氖琼撁鎯?nèi)部的對(duì)象結(jié)構(gòu)而不是屏幕上的像素坐標(biāo)。1.2 CDP方案解決的核心痛點(diǎn)選擇CDP最直接的原因是它解決了我們項(xiàng)目里兩個(gè)最難纏的問題。第一個(gè)問題是“窗口遮擋”。我們的Agent需要并發(fā)處理多個(gè)任務(wù)經(jīng)常會(huì)在多個(gè)應(yīng)用窗口之間切換傳統(tǒng)鍵鼠方案一旦遇到后臺(tái)窗口被遮擋就完全束手無策。而CDP方案操作的是頁面內(nèi)部結(jié)構(gòu)根本不需要窗口處于前臺(tái)甚至窗口最小化了它照樣能執(zhí)行點(diǎn)擊和輸入。這個(gè)特性對(duì)我們來說至關(guān)重要意味著Agent可以同時(shí)“操作”多個(gè)實(shí)例而不用管哪個(gè)窗口在最上面。第二個(gè)問題是“元素定位精度”。用了CDP之后定位一個(gè)輸入框就是一句document.querySelector(#username)的事情穩(wěn)定到不管CSS怎么改都能找到。如果元素加了>[客戶端] ---HTTP GET /json/list--- [Electron應(yīng)用調(diào)試服務(wù)] ---targetId列表--- [客戶端] ---WebSocket連接 ws://...--- [Electron應(yīng)用調(diào)試服務(wù)] ---發(fā)送命令 {id:1,method:DOM.enable}--- [客戶端] ---收到結(jié)果 {id:1,result:{}}---日常使用中90%的命令都是單向請(qǐng)求響應(yīng)模式。協(xié)議里也有事件推送機(jī)制比如頁面加載完成、DOM節(jié)點(diǎn)更新、控制臺(tái)輸出這些都會(huì)主動(dòng)推給客戶端這點(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ì)暴露出來。具體來說在啟動(dòng)Electron應(yīng)用的時(shí)候加上--remote-debugging-port9222Electron主進(jìn)程就會(huì)在9222端口開啟一個(gè)調(diào)試服務(wù)。這個(gè)調(diào)試服務(wù)不僅能發(fā)現(xiàn)所有已經(jīng)打開的窗口還能讓外部客戶端通過CDP協(xié)議和這些窗口的渲染進(jìn)程建立實(shí)時(shí)通信通道。這里有個(gè)Electron特有的坑要特別注意Electron應(yīng)用可能有多個(gè)窗口而每個(gè)窗口在CDP協(xié)議里都是一個(gè)獨(dú)立的Target。所以連接時(shí)要先通過HTTP接口拿到所有Target列表再根據(jù)title或url字段篩選出我們要操作的那個(gè)窗口而不是默認(rèn)連接第一個(gè)。有一點(diǎn)值得說明Electron渲染進(jìn)程和普通Chrome頁面在CDP層面上幾乎沒有區(qū)別原本為瀏覽器自動(dòng)化設(shè)計(jì)的工具和庫在Electron應(yīng)用上都能無縫使用。這意味著生態(tài)里現(xiàn)成的Node.js庫、Python客戶端在這一場(chǎng)景下都能用。2.3 協(xié)議中Agent操作高頻依賴的能力域CDP協(xié)議按功能劃分了幾十個(gè)模塊做Agent操作時(shí)不需要所有模塊全用熟練掌握下面幾個(gè)就夠覆蓋95%以上的場(chǎng)景了。Runtime域用來在頁面上下文里執(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ì)象模型的查詢和操作。DOM.getDocument拿到文檔根節(jié)點(diǎn)、DOM.querySelector從根節(jié)點(diǎn)往下找目標(biāo)元素、DOMDebugger用來調(diào)試監(jiān)聽等。但我們實(shí)際項(xiàng)目里更多是用Runtime.evaluate直接跑document.querySelector來代替DOM域接口因?yàn)檫@樣寫起來更自然而且要獲取的上下文信息更直接。Input域是模擬用戶輸入的關(guān)鍵模塊。Input.dispatchMouseEvent可以派發(fā)鼠標(biāo)按下、釋放、移動(dòng)事件Input.dispatchKeyEvent派發(fā)鍵盤事件。這套接口模擬的是系統(tǒng)輸入層的事件觸發(fā)的行為比直接調(diào)用JS的element.click()更接近真實(shí)用戶操作會(huì)觸發(fā)完整的鼠標(biāo)懸停、激活、焦點(diǎn)切換等狀態(tài)流。Page域用來管理系統(tǒng)頁面狀態(tài)。Page.navigate跳轉(zhuǎn)導(dǎo)航、Page.reload刷新頁面、Page.captureScreenshot截圖以及Page.setDeviceMetricsOverride模擬設(shè)備尺寸等。對(duì)Agent自動(dòng)操作桌面應(yīng)用來說Page.captureScreenshot在出了問題時(shí)抓現(xiàn)場(chǎng)特別有用。Network域能攔截和查看網(wǎng)絡(luò)請(qǐng)求。Agent在操作過程中可能需要等待某個(gè)接口返回后才能繼續(xù)下一步這個(gè)域可以監(jiān)聽請(qǐng)求響應(yīng)作為操作完成與否的判據(jù)。這些模塊組合起來就能構(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)用第一步是讓應(yīng)用以調(diào)試模式啟動(dòng)。最簡(jiǎn)單的做法是在應(yīng)用入口文件里通過app.commandLine.appendSwitch添加參數(shù)也可以直接在終端啟動(dòng)命令后面拼接參數(shù)。在終端里啟動(dòng)的命令是這樣的./your-electron-app --remote-debugging-port9222不過這種方式有個(gè)不方便的地方如果Electron應(yīng)用的啟動(dòng)是通過雙擊桌面圖標(biāo)完成的那命令行參數(shù)就傳不進(jìn)去。我們項(xiàng)目里的做法是在Electron主進(jìn)程代碼里強(qiáng)制開啟調(diào)試端口這樣不管用戶怎么啟動(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連接的來源域名。我們一開始連接時(shí)一直報(bào)403錯(cuò)誤找了好幾輪才發(fā)現(xiàn)是這個(gè)配置問題。本地自動(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)用可以通過環(huán)境變量來指定端口號(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è)下來單機(jī)跑幾十個(gè)實(shí)例沒有性能瓶頸主要卡在內(nèi)存和CPU資源上。3.3 確認(rèn)調(diào)試服務(wù)已就緒應(yīng)用啟動(dòng)之后需要用命令行驗(yàn)證一下調(diào)試服務(wù)是否正常開啟。瀏覽器打開或curl請(qǐng)求下面這個(gè)地址curl http://127.0.0.1:9222/json/version如果一切正常會(huì)返回一段JSON里面包含Browser版本號(hào)、webSocketDebuggerUrl和chrome-version這些關(guān)鍵信息。再訪問/json/list就能看到當(dāng)前應(yīng)用打開的每個(gè)頁面窗口的詳細(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手寫一個(gè)CDP客戶端4.1 建立WebSocket連接我選擇用Node.js寫客戶端因?yàn)镋lectron應(yīng)用前端本身就是JavaScript環(huán)境而且Node.js的WebSocket生態(tài)非常成熟。項(xiàng)目里用的庫是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ù)尤其頁面復(fù)雜時(shí)DOM.getDocument接口返回的序列化結(jié)果可能達(dá)到幾十MB。不調(diào)大這個(gè)參數(shù)消息一超過限制WebSocket就會(huì)靜默斷開排查起來讓人非常抓狂。4.2 常用命令封裝連接建立后我會(huì)把高頻操作封裝成一個(gè)個(gè)獨(dú)立方法這樣Agent邏輯層寫起來就像調(diào)用本地函數(shù)一樣自然。class CDPClient { // 獲取文檔樹 async getDocument() { const result await this.send(DOM.getDocument, { depth: -1 }) return result.root } // 通過選擇器查找元素節(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(頁面執(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è)需要說清楚的關(guān)鍵細(xì)節(jié)頁面里的getBoundingClientRect()拿到的是CSS像素坐標(biāo)而Input.dispatchMouseEvent默認(rèn)按物理像素解釋兩者在非100%縮放比下會(huì)不一致。Electron應(yīng)用頁面里如果設(shè)置了zoomFactor或系統(tǒng)DPI縮放坐標(biāo)就會(huì)偏移。穩(wěn)妥的做法是在連接建立后先讀取設(shè)備的縮放比例然后把坐標(biāo)手動(dòng)換算過去。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)擊偏移問題。4.3 完整操作流程示例下面給一個(gè)Agent自動(dòng)登錄并執(zhí)行查詢的完整代碼示例這里模擬的場(chǎng)景是打開某個(gè)客戶管理桌面應(yīng)用自動(dòng)登錄、跳轉(zhuǎn)到客戶列表頁、輸入關(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(客戶管理)) if (!target) { throw new Error(未找到目標(biāo)窗口請(qǐng)檢查應(yīng)用是否已打開客戶管理界面) } const client new CDPClient(target.webSocketDebuggerUrl) await client.connect() // 啟用相關(guān)域 await client.send(Runtime.enable) await client.send(Page.enable) // 1. 等待頁面加載完成 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(查詢到客戶數(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è)流程跑起來之后我第一感受是整個(gè)過程實(shí)在太流暢了。沒有惱人的坐標(biāo)計(jì)算沒有脆弱到讓人崩潰的截圖比對(duì)每個(gè)步驟都像在寫前端測(cè)試用例。更關(guān)鍵的是調(diào)試體驗(yàn)有了質(zhì)的飛升——CDP協(xié)議自帶的DevTools界面能實(shí)時(shí)看到Agent當(dāng)前操作到了頁面什么位置出問題的時(shí)候打開開發(fā)者工具立刻就能看清頁面真實(shí)狀態(tài)。5. 更省力的做法用Puppeteer庫連接現(xiàn)成的Electron實(shí)例5.1 Puppeteer.connect怎樣復(fù)用已有應(yīng)用人肉手寫WebSocket客戶端的好處是靈活可控所有細(xì)節(jié)都捏在自己手里但日常業(yè)務(wù)開發(fā)我更建議直接選用成熟庫——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代碼寫起來完全不需要關(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)頁面 const targetPage pages.find((page) page.title().includes(客戶管理)) // 現(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)說明一個(gè)參數(shù)defaultViewport: null這個(gè)必須顯式設(shè)置。因?yàn)镻uppeteer默認(rèn)會(huì)給頁面套一個(gè)800x600的視口如果不關(guān)掉它頁面布局會(huì)和正常桌面應(yīng)用完全不一樣——某些元素會(huì)被折疊到響應(yīng)式布局的移動(dòng)端形態(tài)里點(diǎn)擊定位全都亂套。連Electron應(yīng)用時(shí)一定要保持應(yīng)用原有的桌面視口。5.2 和手寫客戶端的選型對(duì)比Puppeteer庫本身還是一層殼它和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)輪詢DOM查詢、page.evaluate對(duì)應(yīng)運(yùn)行時(shí)求值。該封裝的都封裝好了調(diào)用體驗(yàn)確實(shí)比純手寫友好很多。但封裝也意味著控制粒度變粗。如果你需要深度定制協(xié)議行為——比如攔截特定網(wǎng)絡(luò)請(qǐng)求、獲取HTTP響應(yīng)的原始頭部、監(jiān)聽復(fù)雜的底層事件流——Puppeteer提供的接口可能又成了阻礙這時(shí)候就得靠page._client().send(Network.getResponseBody)這類半私有接口或者干脆自己建WebSocket連接。兩個(gè)方案我給出的適用建議是業(yè)務(wù)邏輯快速驗(yàn)證、Agent原型搭建直接用Puppeteer庫開發(fā)效率最高需要深度定制協(xié)議行為、集成到生產(chǎn)環(huán)境的Agent底座里手寫一個(gè)薄客戶端更可控因?yàn)槊總€(gè)連接狀態(tài)、每條命令的結(jié)果都由你自己管理。我們團(tuán)隊(duì)最終的生產(chǎn)實(shí)現(xiàn)是兩者結(jié)合外部用Puppeteer做交互編排關(guān)鍵底層節(jié)點(diǎn)通過手寫CDP客戶端做定制擴(kuò)展。各有各擅長(zhǎng)的地方。5.3 連接時(shí)的常見坑Puppeteer連接Electron實(shí)例時(shí)有幾個(gè)點(diǎn)是經(jīng)常踩到的。Puppeteer庫的版本是一個(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í)別的問題Electron應(yīng)用經(jīng)常會(huì)彈出子窗口、加載iframe、開DevTools面板這些都會(huì)在Target列表里多出噪點(diǎn)。找目標(biāo)窗口時(shí)一定要用title字段做精確匹配甚至通過URL特征過濾避免連到DevTools或隱藏的后臺(tái)窗口上。6. 實(shí)戰(zhàn)中的棘手問題和排查方法6.1 WebSocket連接被403拒絕這個(gè)問題的主要原因是前面提到的remote-allow-origins校驗(yàn)。Chrome從某個(gè)版本開始對(duì)WebSocket連接有了來源校驗(yàn)?zāi)J(rèn)拒絕來自非DevTools前端的連接。Node.js的WebSocket客戶端發(fā)起的握手請(qǐng)求沒有合法的Origin來源會(huì)被服務(wù)端攔下。解決辦法是在Electron主進(jìn)程啟動(dòng)參數(shù)里加上--remote-allow-origins*放開來源限制。如果安全要求比較高也可以把這行參數(shù)改為只允許可信來源但本地自動(dòng)化場(chǎng)景直接放開是最高效的。6.2 獲取不到任何Target列表/json/list接口返回空數(shù)組的原因通常是Electron應(yīng)用沒有渲染出頁面窗口。Electron應(yīng)用如果創(chuàng)建了后臺(tái)隱藏窗口或者頁面還在加載過程中窗口還沒注冊(cè)到調(diào)試服務(wù)Target列表就可能短暫為空。處理方案是等待幾秒再刷新列表并過濾掉type不為page的空條目。還有一種原因是Electron應(yīng)用開啟了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è)下來這個(gè)方法能穩(wěn)定觸發(fā)React的onChange和Vue的v-model更新。這個(gè)技巧在做Agent自動(dòng)化時(shí)幾乎天天用是繞不開的核心技能。6.4 點(diǎn)擊事件不觸發(fā)通過Input.dispatchMouseEvent派發(fā)鼠標(biāo)事件時(shí)有個(gè)細(xì)節(jié)容易被忽略坐標(biāo)必須換算成相對(duì)視口的坐標(biāo)不能用頁面的絕對(duì)坐標(biāo)。如果頁面發(fā)生過滾動(dòng)絕對(duì)坐標(biāo)點(diǎn)擊的位置就和視覺上的位置對(duì)不上。另一個(gè)原因是某些按鈕是通過CSS偽元素覆蓋來實(shí)現(xiàn)點(diǎn)擊的鼠標(biāo)事件雖然派發(fā)了但事件被覆蓋層攔截掉底層按鈕收不到。這種情況可以先讓Agent檢查一下目標(biāo)元素在視口中的位置有沒有被其他元素遮擋如果有遮擋就先把遮擋元素移開或隱藏再點(diǎn)擊。6.5 執(zhí)行過程中頁面跳轉(zhuǎn)過快頁面跳轉(zhuǎn)導(dǎo)航時(shí)CDP連接會(huì)自動(dòng)隨著頁面Target的更新而重建此時(shí)之前建立的連接可能失效。處理邏輯是監(jiān)聽Page.frameNavigated事件一旦發(fā)現(xiàn)主框架導(dǎo)航完成就重新獲取文檔樹和上下文。我之前寫過一個(gè)輪詢waitForSelector邏輯也遇到過這個(gè)坑后面加了導(dǎo)航監(jiān)聽和重建邏輯后就徹底穩(wěn)定了。Agent在操作過程中還會(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ù)流程做的組合比如“登錄流程”、“查詢流程”、“導(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) { /* 輪詢等待文本出現(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)聽close事件后暫停當(dāng)前任務(wù)按指數(shù)退避策略重新獲取Target列表并重新建立連接。這個(gè)過程可能失敗幾次但重試個(gè)三五次一般都能恢復(fù)。業(yè)務(wù)層面更復(fù)雜也是經(jīng)驗(yàn)所在。舉個(gè)例子Agent剛點(diǎn)完“提交訂單”按鈕WebSocket斷了重新連上后這個(gè)訂單到底提交成功沒有頁面狀態(tài)是什么這時(shí)候需要有一個(gè)“操作驗(yàn)證”環(huán)節(jié)檢查頁面上的成功提示或狀態(tài)流轉(zhuǎn)判斷操作是否生效。如果沒生效再按當(dāng)前頁面狀態(tài)重新定位元素或重新執(zhí)行流程。這個(gè)補(bǔ)償邏輯是個(gè)復(fù)雜的業(yè)務(wù)問題但反過來也說明Agent自動(dòng)化不能只依賴底層連接更要在業(yè)務(wù)層建立可觀測(cè)、可恢復(fù)的機(jī)制。7.3 并發(fā)控制的策略我們項(xiàng)目后面從單實(shí)例擴(kuò)展到了多實(shí)例并發(fā)并發(fā)控制踩過的坑也很有參考價(jià)值。CDP連接本身是異步的WebSocket消息可以亂序到達(dá)但CDP協(xié)議要求命令響應(yīng)必須按發(fā)送順序返回嗎其實(shí)不要求每條命令靠id字段關(guān)聯(lián)所以說多實(shí)例并發(fā)CDP線程是安全的。真正要注意的是共享資源。Electron應(yīng)用實(shí)例之間如果共享同一個(gè)本地?cái)?shù)據(jù)庫文件或同一份用戶配置目錄并發(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)、敲擊鍵盤、看著屏幕判斷結(jié)果。而CDP方案本質(zhì)上是直接讀寫系統(tǒng)內(nèi)部的對(duì)象模型相當(dāng)于跳過了模擬路徑直接針對(duì)應(yīng)用的真實(shí)語義結(jié)構(gòu)來操作。這種轉(zhuǎn)變帶來的穩(wěn)定性提升不用多說更深遠(yuǎn)的意義是讓Agent開始具備更準(zhǔn)的“結(jié)構(gòu)理解”。它能知道頁面上有一個(gè)輸入框叫#phone它的占位符提示是什么它當(dāng)前是否可編輯它的值是否符合校驗(yàn)規(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è)試框架它們各有語法糖但核心思路和CDP是一致的——通過協(xié)議操作DOM。Electron應(yīng)用如果直接用CDP做測(cè)試優(yōu)勢(shì)是彈窗、系統(tǒng)對(duì)話框、原生菜單都還能繞過但業(yè)務(wù)功能回歸測(cè)試效率提升直接就是數(shù)量級(jí)的。RPA工具廠商也越來越多考慮在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í)在沒有調(diào)試端口才fallback到圖像識(shí)別。8.3 對(duì)未來AI Agent的啟示我在做這個(gè)項(xiàng)目的過程中有一個(gè)明顯的體感CDP協(xié)議對(duì)AI Agent來說就像給了它一雙免疫屏幕干擾的精準(zhǔn)手柄。未來的終端Agent如果要真正具備操作任意軟件完成復(fù)雜任務(wù)的能力應(yīng)用層協(xié)議通道會(huì)比視覺識(shí)別更可靠也更容易和AI的能力鏈打通?，F(xiàn)在已經(jīng)有智能Agent框架嘗試通過CDP協(xié)議讓大模型直接控制Electron應(yīng)用了大模型輸出意圖Agent框架將其翻譯為CDP命令序列腳本執(zhí)行操作結(jié)果回傳給模型判斷下一步動(dòng)作。這套鏈路一旦跑通AI離真正意義上對(duì)桌面軟件的自主操作就更近了一步。9. 最后的一點(diǎn)心得整套方案做下來我最大的感受是技術(shù)的核心壁壘往往不在API調(diào)用本身而在于對(duì)底層協(xié)議信息的理解深度。CDP文檔洋洋灑灑幾十個(gè)域真正打開能力空間的其實(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)決策而不是無腦按時(shí)間線執(zhí)行能省掉大量排查爛攤子的時(shí)間測(cè)試環(huán)境里跑通了先別急著上生產(chǎn)先把異常場(chǎng)景的截圖、日志、記錄全鏈路鋪好出了事才能快速止血操作多實(shí)例時(shí)務(wù)必隔離數(shù)據(jù)目錄和長(zhǎng)期會(huì)話資源否則并發(fā)一上來就各種靈異現(xiàn)象。如果你計(jì)劃在自己的Electron應(yīng)用上做Agent操作我的建議是最快路徑是先啟動(dòng)應(yīng)用加上調(diào)試端口用Puppeteer連上去寫一個(gè)最小Demo把元素定位、事件派發(fā)、數(shù)據(jù)提取跑通再逐步疊加復(fù)雜場(chǎng)景。先把鏈路打通有了真實(shí)手感再談封裝和工程化。CDP這條路一旦走通Agent操作桌面應(yīng)用就不再是卑微的坐標(biāo)游戲而是一場(chǎng)徹底的結(jié)構(gòu)化對(duì)話。