企业官网建设流程全解析

1. 为什么不让Agent直接“看屏幕点鼠标”：传统方案的三个死穴

我最早做桌面端Agent的时候，思路非常直白：截屏、把图片喂给多模态大模型、拿到坐标、再调用系统级鼠标键盘接口点过去。这套思路听起来很顺，真跑起来会发现每一步都在跟自己作对。先说第一个死穴：延迟不可控。一次“截图→识别→点击”的循环，顺利时3到5秒，复杂界面甚至到十秒以上。要在UI上连续完成七八个步骤，那种卡顿感就像在远程桌面里操作一台隔了半球的机器，旁边的用户早就等烦了。

第二个死穴是坐标空间的脆弱性。窗口位置一变、分辨率一换、系统缩放比例一调，之前标定好的坐标全部失效。更要命的是，Electron应用里大量内容都是网页渲染，按钮的位置取决于布局管线、动画、异步渲染，同一功能在页面不同状态下坐标可能完全不同。靠“颜色匹配+模板匹配”来找元素的做法，稍微换个皮肤就崩。

第三个死穴是反馈信号太弱。视觉方案点下一个按钮之后，到底操作成功没有？页面状态变了没有？只能再截一张图去对比差异，不仅慢，而且很容易把“按钮高亮”“loading动画”误判成状态变化。整个循环里没有一个可靠的、结构化的信号能告诉Agent“这一步执行清楚了，可以做下一步了”。

这三个死穴叠加在一起，我在某个内部BI工具上做的第一版Agent彻底翻车，十次操作大概只能稳定成功一半，剩下的全靠重试硬扛。

后来我开始转换思路：Electron应用的本质是什么？是一套Chromium内核包着一个桌面壳。Chromium前端开发者平时调试网页用什么？Chrome DevTools Protocol，也就是CDP。既然浏览器可以通过CDP被远程驱动，那Electron应用理论上也可以被同一套协议驱动——而且这种驱动方式能拿到页面里最完整的上下文，包括实时DOM状态、调用栈、本地存储、元素坐标和事件监听。这篇文章就围绕这条路线展开：如何让Agent通过CDP协议高效、稳定地操作Electron桌面应用，以及我把这套方案落地到真实项目里踩过哪些坑。

2. 让Electron打开调试之门：两个开关和一条启动参数

2.1 为什么Electron天然支持CDP

Electron的渲染进程就是Chromium，所以Chrome的远程调试能力它几乎全盘继承。差别只在于：Chrome浏览器默认关闭了远程调试端口，而Electron应用本身并没有暴露这个开关给普通用户。我们要做的第一步，就是找到让应用把调试服务开起来的方法。

最朴素的做法是启动应用时带上Chromium系的参数：

/path/to/your-app --remote-debugging-port=9222

Electron应用收到这个参数后，会把DevTools的WebSocket服务绑定在9222端口上。注意，这个端口默认只监听本机回环地址，外部机器访问不到，安全性上不会裸奔到局域网里，这一点后面还会细讲。

如果你的应用已经处于正常运行状态，不方便用命令行重启，可以在主进程代码入口处加上一行：

// Electron 主进程 const { app } = require('electron'); app.commandLine.appendSwitch('remote-debugging-port', '9222'); app.whenReady().then(() => { // 应用逻辑 });

commandLine.appendSwitch必须在app.whenReady()之前调用，否则不生效。这个方法对我后面接入Agent帮助很大——我可以让应用默认不开调试端口，只有检测到环境变量或者某个配置项时才动态打开，避免把调试能力暴露给生产环境的普通用户。

2.2 先验证端口有没有真正起来

参数加上之后，别急着写Agent代码。先验证端口是否真的可以访问，这一步更快也更稳：

curl http://127.0.0.1:9222/json/version

正常情况下会返回一段JSON，里面有Browser、Protocol-Version、webSocketDebuggerUrl等字段。再列一下当前应用里有哪些可调试的页面：

curl http://127.0.0.1:9222/json/list

这个接口返回的数组里，每个元素对应一个页面（Electron里的窗口或WebContents），包含id、title、url、webSocketDebuggerUrl等关键信息。Agent连接上webSocketDebuggerUrl之后，就能对那个具体的页面发号施令。

有一点要特别提醒：Electron应用通常会带一个主窗口，菜单、弹窗、子窗口都会映射成独立的target。如果你的应用里有隐藏的webContents、后台运行的Badge窗口，或者DevTools自己打开的调试面板，/json/list里会出现一堆条目，不要把Agent永远钉在第一个元素上，按url或title去匹配正确的页面，这个习惯要早点养成。

2.3 生产环境的“条件打开”策略

直接把--remote-debugging-port写死在生产代码里并不合适。原因很简单：用户只要开着应用，任何本机进程都可以连接调试端口操作界面，一些恶意脚本也能通过这个通道读取页面里的敏感状态。

更稳妥的方式是提供一个开关，比如读环境变量：

if (process.env.ENABLE_CDP === '1') { app.commandLine.appendSwitch('remote-debugging-port', '9222'); }

我在实际项目里还会加一个端口随机化的小逻辑，避免固定端口和用户机器上其他应用冲突：

const randomPort = 9200 + Math.floor(Math.random() * 500); app.commandLine.appendSwitch('remote-debugging-port', String(randomPort));

调试结束后把ENABLE_CDP关掉，应用就完全回归普通桌面软件状态。这套“按需开放”的思路，既能让Agent正常工作，又不会给终端用户带来额外的安全暴露面。

3. CDP里藏着Agent需要的四把钥匙：核心域与取舍

CDP协议内部划分了六十多个“域（Domain）”，每个域管理一类能力。对于Agent操作Electron应用来说，绝大多数域用不上，真正频繁打交道的是下面这四个核心域。我从使用频率和可靠性两个维度评估后，分别确认了它们各自的定位。

3.1 Runtime域：让Agent拥有“语言理解”能力

Runtime.evaluate是Agent手里最常用的一个方法。它可以让你在页面上下文中执行任意JavaScript表达式，并拿到返回值。这套机制相当于给Agent开了一条直接和页面对话的通道：

{ "id": 1, "method": "Runtime.evaluate", "params": { "expression": "document.title", "returnByValue": true } }

返回值里会包含result.value、result.type。也就是说，Agent可以随时问页面“你现在是什么状态”“这个输入框的值是什么”“列表里一共有多少条记录”。这种“语言式”的信息获取，和传统方案里靠图像识别去猜状态完全是两个维度。我经常让Agent执行一段JS，直接提取页面里的关键业务数据，比任何截图都准确。

注意returnByValue这个参数：如果设成false，返回的是对象引用（RemoteObject），Agent拿不到直接的JSON值；设成true，则会深拷贝一份可直接使用的值。实际使用中几乎总是设成true。另外，表达式里避免使用return关键字，直接写表达式本身即可，因为Runtime.evaluate执行的是表达式语义而不是函数体。

3.2 Page与DOM域：管理页面生命周期，读取真实结构

刚才提到的/json/list接口只能拿到页面列表，Page域则负责页面本身的生命周期管理。Agent在开始操作一个窗口之前，最好先调用Page.enable，这样能订阅到页面加载、导航、JavaScript弹窗等事件。比如点击一个按钮之后突然跳转到了新页面，Agent通过Page.frameNavigated事件就能感知到，而不靠猜。

DOM域用来读取页面结构树。两个常用方法是DOM.getDocument和DOM.querySelector。前者返回根节点ID，后者根据CSS选择器在文档中查找元素，返回nodeId。拿到nodeId之后，可以进一步调用DOM.getBoxModel获取元素在屏幕上的精确坐标。

不过对于Agent而言，我更建议优先使用Runtime.evaluate配合JavaScript去获取元素。原因后面会提：DOM域的方法是命令式的，每次查询都要维护节点映射，而Runtime.evaluate可以直接返回结构化的数据，配合JSON.stringify就能把一段复杂的页面状态打包出来。

3.3 Input域：模拟真实用户操作

这是Agent从“观察”跨入“行动”的通道。Input.dispatchMouseEvent和Input.dispatchKeyEvent分别模拟鼠标与键盘事件。鼠标事件需要坐标，坐标来自前面DOM域获取的BoxModel，或者通过getBoundingClientRect()计算得到：

{ "id": 2, "method": "Input.dispatchMouseEvent", "params": { "type": "mousePressed", "x": 410.0, "y": 282.0, "button": "left", "clickCount": 1 } }

之后还要发送一个mouseReleased事件，才能构成一次完整的点击。clickCount字段用于区分单击与双击，双击时先发送一次clickCount=1，再发送clickCount=2。 键盘输入方面，Input.insertText可以直接把一串文本插入到当前焦点元素，我通常用它处理中文输入，因为它不依赖系统输入法状态，稳定性比dispatchKeyEvent的单键模拟好得多。如果要触发回车、Tab这类功能键，就用dispatchKeyEvent发送keyDown和keyUp。

3.4 Accessibility域：给大模型更友好的“页面视野”

说到Agent接入AI大模型，这里值得单独提一下Accessibility.getPartialAXTree。这个方法返回的是页面的可访问性树，保留了对用户真正有语义的控件结构，过滤掉大量装饰性DOM节点。相比直接把一大段HTML塞给模型，AX树的token占用小得多，可读性也高很多。

在后续接入大模型规划操作路径时，我主力就是它，配合少量关键节点的坐标信息，可以在“看得见”和“看得懂”之间找到一个平衡点。这个方法唯一的缺点是在复杂页面上返回节点也很多，需要做一层裁剪，只保留包含name和role的节点。

4. 从零写一个最小可用的Agent：核心骨架与流程闭环

理论铺垫了一堆，下面进入实战部分。目标很明确：写一个Agent，让它打开某个Electron应用，找到输入框，填入关键词，点击搜索按钮，然后读取搜索结果。这套流程跑通之后，换到任何业务场景都只是“改选择器+改评价逻辑”的问题。

4.1 技术选型：TypeScript + ws库

我选择TypeScript搭配ws库来写Agent端。Electron应用暴露的调试端口本质是一个WebSocket服务，原生fetch接口搞不定双向通信，ws库是最成熟的选择。如果你更熟悉Python，websocket-client库也能完成同样的事情，核心逻辑一致。

先安装依赖（以Node.js环境为例）：

npm install ws npm install -D typescript @types/ws

然后定义一个最小化的CDP客户端封装：

import WebSocket from 'ws'; class CDPClient { private ws: WebSocket; private id = 0; private pending = new Map<number, { resolve: any; reject: any }>(); constructor(wsUrl: string) { this.ws = new WebSocket(wsUrl); this.ws.on('message', (data) => { const msg = JSON.parse(data.toString()); if (msg.id && this.pending.has(msg.id)) { const { resolve, reject } = this.pending.get(msg.id)!; this.pending.delete(msg.id); msg.error ? reject(new Error(msg.error.message)) : resolve(msg.result); } }); } send(method: string, params: object = {}) { const id = ++this.id; this.ws.send(JSON.stringify({ id, method, params })); return new Promise((resolve, reject) => { this.pending.set(id, { resolve, reject }); }); } }

这个封装是后续所有操作的基石。send方法返回Promise，Agent可以像调用本地异步函数一样等待页面响应。

4.2 连接目标页面：先拿target列表，再挑对的那个

应用启动后，首先要向HTTP接口请求页面列表，然后挑出目标页面。我的处理逻辑是：先看type字段为page的条目，再匹配url前缀，匹配失败就跑一次url中包含关键路径的宽松匹配。连接成功后把所有事件随便打点一下，避免WebSocket因为事件多了之后背压出问题。

async function connectToApp(debugPort: number, urlKeyword: string) { const list = await fetch(`http://127.0.0.1:${debugPort}/json/list`).then(r => r.json()); const target = list.find((t: any) => t.type === 'page' && t.url.includes(urlKeyword) ); if (!target) { throw new Error('未找到匹配的页面 target，请检查 urlKeyword 是否正确'); } const client = new CDPClient(target.webSocketDebuggerUrl); await client.send('Runtime.enable'); await client.send('Page.enable'); return client; }

一定要在连接之后先Runtime.enable。跳过这一步，很多Runtime域的事件和求值能力可能不会正常触发。

4.3 跑通一个完整的“定位-输入-点击-读取”流程

接下来写Agent的核心流程。这里我用一个常见的业务场景做演示：某个Electron应用里有一个搜索框，我想在里面输入“计算机视觉”，点搜索按钮，再读取下面的结果列表数量。

先通过Runtime.evaluate找到输入框，并且把焦点设置过去：

async function focusInput(client: CDPClient, selector: string) { const expr = ` (() => { const el = document.querySelector('${selector}'); if (!el) return { ok: false, message: '找不到输入框' }; el.focus(); return { ok: true }; })() `; const res = await client.send('Runtime.evaluate', { expression: expr, returnByValue: true }); return res.result.value; }

聚焦之后用Input.insertText输入文字：

async function typeText(client: CDPClient, text: string) { await client.send('Input.insertText', { text }); }

接下来点击搜索按钮。这里不直接派发坐标事件，而是先通过JS拿到按钮的中心坐标：

async function clickSelector(client: CDPClient, selector: string) { const expr = ` (() => { const el = document.querySelector('${selector}'); if (!el) return { ok: false, message: '找不到可点击元素' }; const rect = el.getBoundingClientRect(); return { ok: true, x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 }; })() `; const { result } = await client.send('Runtime.evaluate', { expression: expr, returnByValue: true }); const { ok, x, y } = result.value; if (!ok) return; // 处理找不到元素的情况 await client.send('Input.dispatchMouseEvent', { type: 'mousePressed', x, y, button: 'left', clickCount: 1 }); await client.send('Input.dispatchMouseEvent', { type: 'mouseReleased', x, y, button: 'left', clickCount: 1 }); }

最后读取结果区域里的条目数量：

async function getResultCount(client: CDPClient) { const expr = ` (() => { const items = document.querySelectorAll('.search-result-item'); return items.length; })() `; const { result } = await client.send('Runtime.evaluate', { expression: expr, returnByValue: true }); return result.value; }

把上面几个步骤串起来，加上延时等待页面渲染的部分，就是一个具备“操作闭环”的最小Agent。这里的延时等待其实不太优雅，更好的方案是用Runtime.evaluate去轮询某个条件，比如“存在某个元素”或“某个文案变成预期值”。我给这个轮询写了一个通用函数，核心就是循环执行evaluate，直到条件满足或者超时，比固定sleep几个毫秒靠谱得多。

5. 真实项目里的翻车现场：连接失败、元素失联与输入法陷阱

前面那段骨架代码跑通之后，我开始往更多业务场景里加功能，果然不出所料，问题一个接一个。下面记录的这几个坑，都是我真实调试时卡过很久的。

5.1 9222端口“看起来开了，但连不上”

有两次我碰到的现象是：curl http://127.0.0.1:9222/json/list完全正常，但Agent的WebSocket就是握手失败。排查了半天，才发现问题出在Electron应用启动了不止一个实例。旧实例占着9222端口，新实例启动时发现端口被占用，直接换了一个随机端口。/json/list看到的是旧实例的信息，Agent连的也是旧实例，而真正要操作的窗口在新实例里。

解决思路有两个。一是启动前用app.requestSingleInstanceLock()保证全局单实例，这是Electron官方推荐的做法。二是在Agent端做动态探测：先尝试9222，不通就扫描9200到9300区间，找到之后再用/json/list里的页面标题做二次校验。两个方案我用的是第一个，让应用自己保证唯一实例，Agent端的逻辑可以保持简单。

5.2 元素“刚刚还在，执行时却找不到”

页面上有一个异步组件，点击之后要等500毫秒才出现在DOM里。我在测试脚本里用固定延时，大部分时间能等到，但网络稍微波动一下，组件渲染变慢，元素就抓不到了。Runtime.evaluate返回ok: false，流程直接中断。

我后来把“等待元素出现”做成了一个标准的轮询原语，并入Agent框架：

async function waitForSelector(client: CDPClient, selector: string, timeoutMs = 5000) { const start = Date.now(); while (Date.now() - start < timeoutMs) { const res = await client.send('Runtime.evaluate', { expression: `!!document.querySelector('${selector}')`, returnByValue: true }); if (res.result.value === true) return true; await new Promise(r => setTimeout(r, 200)); } return false; }

轮询200毫秒一次，超时5秒。这个方案比固定延时抗抖动能力强得多，也让Agent具备了简单的“环境感知”能力。

5.3 中文输入变成乱码或直接没反应

Input.dispatchKeyEvent方式输入中文是个大坑，因为它模拟的是物理键盘事件，对非ASCII字符的支持非常依赖系统输入法状态。我在某次测试里用dispatchKeyEvent输入“计算机视觉”，结果页面上只出现了一个“计”字，后面全丢了。

后来换用Input.insertText，这个问题直接消失。insertText走的是Chromium的文本注入通道，相当于直接把字符串提交给当前焦点元素，不经过键盘映射和输入法。唯一要保证的是焦点已经正确落在目标输入框里，所以请务必在insertText之前先执行el.focus()。

5.4 沙盒与上下文隔离导致的夺权失败

Electron应用里如果开启了contextIsolation: true，页面的主世界和预加载脚本的世界是隔离的。通过CDP的Runtime.evaluate默认在主世界执行JS，这时页面里若依赖了预加载脚本注入的window.api，Agent直接调用会得到undefined。

解决方案是使用Runtime.evaluate的contextId参数，或者用Page.createIsolatedWorld创建一个与预加载脚本同级的独立世界。更简单的方案是：Agent不要依赖页面内部注入的API，而是只操作可见的DOM元素，把所有业务逻辑放在页面之外。我在架构上偏向后者，因为这样Agent和页面解耦得更干净。

5.5 后台最小化窗口的渲染挂起

Electron应用最小化或者完全被遮挡时，Chromium出于省电策略会暂停渲染。此时Runtime.evaluate还能执行，但getBoundingClientRect返回的坐标可能是过期或全零的，Input.dispatchMouseEvent即便发了也不生效。

处理方式有两种。一种是操作前调用Page.bringToFront，把窗口唤起。另一种是在Electron主进程里给webContents设置backgroundThrottling = false，后台窗口也保持渲染。前者适合Agent在用户不感知的情况下短暂操作应用，后者适合无人值守的自动化场景。我在做一个单据自动填充功能时两个方案都用了，效果稳定。

6. 把Agent接到大模型上：语义化指令与自主操作闭环

到目前为止的“Agent”，本质上还是一个通过CDP远程控制应用的工具。真正让它具备“智能”，关键一步是让大模型参与决策。这一段我分享的是我把整个系统升级成“大模型规划+CDP执行”两层架构的实践经验。

6.1 给大模型一份“结构化视野”而不是原始截图

一开始我尝试直接把页面截图传给多模态模型，让它输出坐标。结果模型给出的坐标往往有几十像素的偏差，而且页面稍微滚一下就对不上。后来我改成混合方案：

• 用Accessibility.getPartialAXTree抽取当前页面的语义控件树；
• 加上当前URL、标题、关键输入框的值；
• 再加上最近一次Agent操作是成功还是失败的标记。

这一份结构化上下文打包给模型，模型只需要输出“意图化的动作序列”，比如点击“搜索”、输入“计算机视觉”、等待结果出现。坐标换算和选择器定位全部由CDP执行层完成。拆分之后，模型的工作从“精确控制”降级为“意图决策”，准确率显著提高。

6.2 意图决策层与CDP执行层的循环设计

整个系统的循环如下：

1. Agent收集当前页面状态（AX树、URL、部分关键数据）；
2. 构造用户任务描述和可用工具清单，发送给大模型；
3. 模型返回一个结构化的动作指令；
4. CDP执行层解析指令，调用对应的操作（输入、点击、等待、读取）；
5. 执行结果反馈给模型；
6. 若任务未完成，回到第1步。

伪代码大致是这样：

while (!taskDone) { const snapshot = await capturePageSnapshot(client); const action = await llm.plan({ task: userTask, snapshot: snapshot, history: actionHistory }); if (action.type === 'click') { await clickSelector(client, action.selector); await waitForNetworkIdle(client); } else if (action.type === 'type') { await focusInput(client, action.selector); await typeText(client, action.text); } actionHistory.push(action); taskDone = await evaluateTaskCompletion(client, userTask); }

这里要特别注意给模型提供的工具描述要足够清晰，同时在执行层做严格的校验：动作的目标元素不存在时，绝不硬点；页面URL发生跳转时，上一轮的DOM引用全部作废。安全边界在这个循环里不是一句空话，而是每一步都要检查的硬约束。

6.3 token预算与执行效率的平衡

大模型决策流程里最容易忽视的是token消耗。AX树在复杂页面上可能输出几千个节点，直接发给模型会非常贵。我通常会把AX树裁剪到只保留两类节点：包含可点击属性的，以及包含输入属性的。实测下来，页面总体token消耗能下降70%左右，决策准确率反而更稳定，因为噪声更少。

另外一个经验是把“页面等待”从模型决策循环里拆出来。CDP执行层在点击按钮之后，直接调用waitForSelector等待目标要素出现，模型此时不需要参与。只有等待超时之后，才把异常情况反馈给模型，让它决定是重试、换选择器，还是报告失败。这相当于给Agent加了一层“肌肉记忆”层，只有遇到意外才让“大脑”介入。

7. 最后再分享一点关于这套方案的稳定性心得

把这套CDP驱动方案放到更多业务场景里跑了几个月之后，我最大的体会是：Agent系统的可靠性，不在于某个单点调用有多精准，而在于反馈闭环是否严密。传统截图方案反馈弱，所以每一步都像盲飞；CDP方案强就强在每一步操作后，Agent都能从页面里拿到结构化的、可信的状态信号。把“操作后的页面状态变化”作为每步是否成功的判断标准，整个系统的鲁棒性会上一个明显的台阶。

具体到工程落地，我建议所有准备接手这类项目的同学，先别急着接大模型。把CDP执行层打磨到“用固定脚本也能稳定跑完100轮”的程度，再引入大模型做意图决策也不迟。否则模型输出再聪明，执行层三天两头翻车，出来的结果依然没法看。

还有一个容易被忽略的细节：Electron升级版本时，CDP域的行为偶尔会有细微变化。上线前跑一遍全链路冒烟测试，比任何文档都靠谱。如果你打算在生产环境给用户开调试端口做自动化，一定要加环境变量开关和端口随机化，这一点前面已经强调过，但值得再说一次——因为一旦端口裸奔，任何本机进程都能读取应用里的敏感数据，这个代价不是省几行配置代码能弥补的。