1. 项目缘起当AI助手需要“亲手”操作你的邮箱最近在折腾一个挺有意思的项目核心目标很简单让我的AI助手WorkBuddy能够像真人一样在我的浏览器里登录网页版邮箱帮我自动处理邮件。听起来像是RPA机器人流程自动化的活儿但我想走一条更“原生”的路——不依赖那些封装好的、黑盒的自动化工具而是直接让AI通过浏览器底层的“遥控器”来操作。为什么会有这个需求日常工作中总有些重复性的邮件处理任务比如每天定时从特定发件人的邮件里提取报表附件、自动回复一些格式固定的询价邮件或者仅仅是帮我整理收件箱。市面上的自动化工具要么太“重”需要复杂的配置要么太“死板”无法应对网页布局的微小变化。而像WorkBuddy这类基于大语言模型的AI助手其优势在于能理解自然语言指令和网页的语义结构理论上可以更灵活、更智能地完成任务。但问题来了WorkBuddy本身是一个运行在某个环境可能是本地命令行、Web服务或桌面应用中的AI Agent它如何能“伸出手”去操控另一个独立的浏览器标签页呢这就是本项目的核心挑战也是乐趣所在。我选择的解决方案是Chrome DevTools Protocol。你可能在调试网页时用过Chrome开发者工具CDP就是驱动这套工具背后的那个协议。它允许外部程序通过WebSocket连接到一个正在运行的Chrome或Chromium浏览器实例然后发送一系列命令实现近乎所有你能在浏览器里手动完成的操作导航、点击、输入、执行JavaScript甚至监听网络请求和Console输出。而“本地模型”指的是什么这里指的是我本地部署的大语言模型比如通过Ollama运行的Llama 3、Qwen等。我希望WorkBuddy的“大脑”是这个本地模型由它来理解我的指令“查一下昨天客户张三的邮件把附件下载下来”并生成操作浏览器的具体步骤。这样所有数据邮件内容、登录凭证和思考过程都留在本地安全和隐私性更有保障。所以整个项目的蓝图就是WorkBuddyAI Agent 本地大模型决策大脑 CDP操作手臂 一个能安全、自动操作网页邮箱的智能工作伙伴。2. 核心武器库CDP与Puppeteer的深度解析要实现浏览器自动化光知道CDP这个概念还不够我们需要一个趁手的“武器”。直接裸写WebSocket消息去调用CDP是非常繁琐且容易出错的因此我们通常使用封装好的库。这里有几个主流选择PuppeteerGoogle官方出品对CDP的封装最完善API设计非常友好是Node.js生态下的首选。它启动的是一个无头或带界面的Chromium浏览器完全受控。Playwright由微软开发支持Chromium、Firefox和WebKit三大浏览器引擎API与Puppeteer类似但更现代跨浏览器特性好。Selenium老牌自动化测试框架支持语言和浏览器最广但相对于CDP原生方案它通常通过浏览器驱动来通信有时不够底层和高效。对于我们的项目——需要精细控制、且与本地AI深度集成——Puppeteer是更合适的选择。它提供的是对CDP的高级抽象让我们能用简单的JavaScript或Python等语言绑定代码完成复杂的浏览器交互。2.1 Puppeteer的核心能力与邮箱操作场景映射让我们具体看看Puppeteer如何对应到操作邮箱的每一个动作启动与连接puppeteer.launch()可以启动一个全新的浏览器实例。更关键的是我们也可以使用puppeteer.connect()连接到任何一个已经启动、并且开启了远程调试端口--remote-debugging-port9222的Chrome/Chromium。后者对于集成到现有工作流非常有用。页面导航page.goto(https://mail.example.com)直接跳转到邮箱登录页。元素定位与交互这是自动化的血肉。输入账号密码page.type(#username-input, myemailexample.com)和page.type(#password-input, myPassword123)。这里的关键是选择器#username-input需要替换为目标邮箱登录页的实际元素选择器。点击登录按钮page.click(#login-button)。等待页面跳转page.waitForNavigation()确保登录完成后再进行后续操作。读取页面内容AI需要“看到”页面内容才能做决策。page.content()获取整个页面的HTML。page.$eval(selector, el el.textContent)获取特定元素的文本。对于复杂的邮箱列表我们可能需要获取每一封邮件的发件人、主题、时间page.$$eval(.email-item, items items.map(i ({sender: i.querySelector(.sender).textContent, subject: i.querySelector(.subject).textContent})))。模拟复杂操作下载附件这通常是点击一个链接或按钮触发浏览器下载。Puppeteer可以监听response事件来捕获文件流或者更简单地通过page._client.send(Page.setDownloadBehavior, {behavior: allow, downloadPath: /path/to/save})这个CDP原始命令来设置下载路径注意这是一个实验性API可能需要特定版本的Puppeteer。滚动加载对于需要滚动加载更多邮件的页面可以使用page.evaluate(() window.scrollTo(0, document.body.scrollHeight))结合page.waitForFunction来模拟。键盘操作page.keyboard.press(Enter)模拟回车page.keyboard.type(Hello)模拟打字。注意直接使用page.type输入密码存在安全风险因为密码会明文出现在代码中。更佳实践是使用环境变量或者利用Puppeteer的page.evaluateOnNewDocument在页面加载前注入已保存的登录态如Cookie、LocalStorage实现“无密码”自动登录。这需要你先手动登录一次用工具导出浏览器存储的数据。2.2 为什么选择CDP而非传统RPA工具你可能会问用UiPath、影刀RPA这类图形化工具不是更简单吗它们也能录屏、抓取元素。这里有几个本质区别可编程性与灵活性CDPPuppeteer是纯代码驱动可以无缝嵌入到你的Node.js/Python AI项目中与本地模型的调用、逻辑判断形成一个完整的程序。而RPA工具往往是独立的桌面应用与其他系统集成需要额外的接口灵活性受限。精准度与稳定性CDP直接与浏览器内核通信操作基于DOM元素不依赖于屏幕坐标容易因窗口位置、分辨率变化而失效因此更加精准和稳定。性能与资源无头浏览器模式消耗资源相对较少适合在服务器后台长期运行。许多RPA工具需要运行完整的桌面环境。与AI的亲和度我们的AI模型本地LLM本质上是一个文本输入输出的系统。让AI输出一段操作浏览器的JavaScript/Python代码调用Puppeteer API比让它去理解如何配置一个图形化RPA工具的步骤要自然和直接得多。3. 大脑的配置让本地大模型“理解”浏览器操作WorkBuddy的核心智能来自于大语言模型。我们需要配置它使其不仅能聊天还能生成可执行的浏览器操作指令。这里以本地部署的Ollama Qwen2.5模型为例。3.1 设计给AI的“任务指令”模板我们不能简单地对AI说“去收一下邮件”。需要设计一个结构化的提示词Prompt引导AI将模糊的自然语言指令分解成具体的、可被Puppeteer执行的步骤序列。一个基础的指令模板可能长这样你是一个浏览器自动化助手。请根据用户请求生成一个可执行的Puppeteer操作序列。 当前浏览器状态已打开标签页页面URL是{current_url} 用户请求{user_request} 请按以下JSON格式输出你的操作计划 { thought: 简要分析用户意图和所需步骤, steps: [ { action: 动作类型如 navigate, click, type, waitForSelector, extract_text, evaluate, selector: CSS选择器如果是点击、输入等需要定位元素的操作, value: 输入的值或等待的时间ms, description: 步骤描述 } ] } 可用动作说明 - navigate: 跳转到新URL。selector留空value填目标URL。 - click: 点击元素。selector必填。 - type: 输入文本。selector必填value填要输入的字符串。 - waitForSelector: 等待某个元素出现。selector必填value可填超时时间默认5000。 - extract_text: 从元素提取文本。selector必填返回的文本会添加到上下文。 - evaluate: 执行自定义JavaScript代码。value填JS代码字符串。 请确保选择器尽可能精准且稳定。如果当前页面可能没有目标元素请在thought中说明并建议先进行导航或等待。例如用户请求是“登录我的网易邮箱”当前页面是about:blank。一个理想的AI输出可能是{ thought: 用户需要登录网易邮箱。我需要先导航到网易邮箱登录页然后定位账号和密码输入框进行输入最后点击登录按钮。, steps: [ {action: navigate, selector: , value: https://mail.163.com, description: 导航至网易邮箱登录页}, {action: waitForSelector, selector: #username, value: 5000, description: 等待账号输入框加载}, {action: type, selector: #username, value: your_email163.com, description: 输入邮箱账号}, {action: type, selector: #password, value: your_password, description: 输入密码}, {action: click, selector: .login-btn, description: 点击登录按钮}, {action: waitForSelector, selector: .navInbox, value: 10000, description: 等待收件箱加载完成确认登录成功} ] }3.2 集成Ollama本地模型接下来我们需要在WorkBuddy的后端可能是Node.js或Python服务中集成Ollama。Ollama提供了简单的REST API。// Node.js 示例调用Ollama生成操作步骤 const axios require(axios); async function askOllamaForPlan(userRequest, currentUrl) { const prompt ...; // 将上面的模板与 userRequest, currentUrl 拼接 try { const response await axios.post(http://localhost:11434/api/generate, { model: qwen2.5:7b, // 指定你本地拉取的模型 prompt: prompt, stream: false, options: { temperature: 0.1, // 低温度让输出更确定、更遵循格式 } }); const planText response.data.response; // 解析planText中的JSON部分 const planMatch planText.match(/\{[\s\S]*\}/); if (planMatch) { return JSON.parse(planMatch[0]); } else { throw new Error(AI未能返回有效的JSON计划); } } catch (error) { console.error(调用Ollama失败:, error); throw error; } }实操心得模型的选择和Prompt设计至关重要。较小的模型如7B可能对复杂指令和严格JSON格式的遵循能力较弱需要更精细的Prompt工程或者在输出后加入一个格式校验与修正的步骤。可以尝试在Prompt中提供更详细的例子Few-shot Learning。温度temperature参数设低一些如0.1可以减少输出的随机性让操作步骤更稳定。3.3 动态上下文管理AI不是神它需要知道当前浏览器处于什么状态。因此在每一轮交互中我们都需要将“当前页面URL”和“上一步执行的结果”比如提取到的邮件列表文本作为上下文连同新的用户请求一起喂给模型。这形成了一个闭环用户指令 - AI生成计划 - Puppeteer执行 - 获取新状态 - 更新上下文 - 等待下一条指令。例如当AI生成了“提取第一封邮件的发件人”的步骤并执行后我们将提取到的文本如“发件人张三 zhangsancompany.com ”反馈给AI。当用户下一条指令是“回复他”时AI就能在上下文中知道“他”指的是张三从而生成“点击回复按钮”和“在正文中输入...”的后续步骤。4. 工程化实践构建健壮的WorkBuddy邮箱助手将上述各部分组合起来我们需要构建一个稳定的服务。以下是核心架构模块和关键代码片段。4.1 项目结构与核心模块假设我们使用Node.js环境。workbuddy-mail-agent/ ├── config/ │ └── default.json # 配置文件邮箱凭证、模型地址、CDP端口等 ├── src/ │ ├── core/ │ │ ├── browser.js # Puppeteer浏览器管理启动、连接、页面池 │ │ └── cdp-client.js # 底层CDP客户端封装处理下载等特殊操作 │ ├── brain/ │ │ ├── llm-client.js # Ollama API客户端封装 │ │ └── prompt-engine.js # 提示词模板管理与组装 │ ├── skills/ │ │ └── email-skill.js # 邮箱操作技能的具体实现登录、读信、回复等 │ ├── orchestrator.js # 总调度器串联LLM、浏览器和技能 │ └── app.js # 主应用入口HTTP Server或CLI ├── logs/ # 日志目录 └── package.json4.2 核心流程代码剖析让我们看看调度器orchestrator.js的核心逻辑const BrowserManager require(./core/browser); const LLMClient require(./brain/llm-client); const EmailSkill require(./skills/email-skill); class Orchestrator { constructor() { this.browserManager new BrowserManager(); this.llmClient new LLMClient(); this.currentContext { url: about:blank, pageTitle: , extractedData: {} }; this.emailSkill new EmailSkill(); // 可以预加载一些邮箱站点的选择器配置 } async processCommand(userCommand) { // 1. 获取当前页面状态用于上下文 const page await this.browserManager.getActivePage(); this.currentContext.url page.url(); this.currentContext.pageTitle await page.title(); // 2. 调用LLM生成操作计划 const plan await this.llmClient.generatePlan( userCommand, this.currentContext, this.emailSkill.getSiteSpecificHints(this.currentContext.url) // 提供邮箱站点特定的提示 ); console.log(AI生成计划:, JSON.stringify(plan, null, 2)); // 3. 解释并执行计划中的每一步 const executionResults []; for (const step of plan.steps) { try { let result; switch (step.action) { case navigate: result await page.goto(step.value, { waitUntil: networkidle2 }); break; case click: await page.waitForSelector(step.selector, { timeout: step.value || 5000 }); await page.click(step.selector); break; case type: await page.waitForSelector(step.selector); // 先清空再输入更模拟真人操作 await page.click(step.selector, { clickCount: 3 }); await page.keyboard.press(Backspace); await page.type(step.selector, step.value); break; case extract_text: const text await page.$eval(step.selector, el el.textContent.trim()); result text; // 将提取的数据存入上下文供后续步骤使用 this.currentContext.extractedData[step.description] text; break; case evaluate: result await page.evaluate(step.value); break; // ... 处理其他动作 default: console.warn(未知动作: ${step.action}); } executionResults.push({ step: step.description, success: true, result }); // 步骤间加入短暂延迟模拟人类操作间隔避免被反爬机制识别 await page.waitForTimeout(300 Math.random() * 200); } catch (error) { console.error(步骤执行失败: ${step.description}, error); executionResults.push({ step: step.description, success: false, error: error.message }); // 这里可以加入错误处理逻辑比如让AI重新规划或执行备用方案 break; } } // 4. 执行完成后可以再次获取页面状态更新上下文为下一条指令做准备 this.currentContext.url page.url(); this.currentContext.pageTitle await page.title(); return { originalCommand: userCommand, aiPlan: plan, executionResults, finalContext: this.currentContext }; } }4.3 针对邮箱站点的特殊适配与反反爬策略网页邮箱如Gmail, Outlook, QQ Mail的DOM结构复杂且可能频繁变动直接写死选择器如#username非常脆弱。我们需要更健壮的策略多选择器回退在技能模块email-skill.js中为关键元素登录按钮、收件箱列表配置一组可能的选择器。执行时按顺序尝试。const LOGIN_BUTTON_SELECTORS [ input[typesubmit][value登录], button.login-btn, .signin-button, [data-testidlogin-submit] // 一些现代网站用的测试ID ];基于文本内容的定位如果CSS选择器都失效可以借助XPath按文本内容定位。//button[contains(text(), 登录)]。Puppeteer支持page.$x(xpath)。视觉与语义结合对于极度动态的页面可以结合AI进行“视觉理解”。将页面截图使用多模态模型如本地部署的LLaVA识别图中的按钮位置再通过page.mouse.click(x, y)模拟点击。但这更复杂属于进阶方案。模拟人类行为模式除了随机延迟还可以加入随机的鼠标移动轨迹page.mouse.move(x, y)以及在输入时模拟击键间隔的不均匀性。Cookie与存储持久化最根本的避免每次从头登录。使用puppeteer.launch的userDataDir参数指定一个用户数据目录浏览器会将Cookie、LocalStorage等持久化保存在这里。首次手动登录后后续启动即可保持登录状态。const browser await puppeteer.launch({ headless: false, // 首次登录时可设为false以便手动操作 userDataDir: ./user_data });5. 避坑指南从零到一实战中的典型问题在实际搭建和运行过程中我遇到了不少坑。这里分享几个最具代表性的问题和解决方案。5.1 浏览器启动与连接失败问题puppeteer.launch()卡住或报错Failed to launch the browser process!。排查依赖缺失Puppeteer自带的Chromium可能缺少某些系统库尤其是Linux服务器。错误信息通常会提示缺失什么如libatk-bridge-2.0.so.0。权限问题指定的userDataDir目录没有写入权限。端口占用使用connect模式时指定的CDP端口如9222被其他进程占用。解决根据系统安装缺失的库。对于Ubuntu/Debian常用命令是sudo apt-get install -y gconf-service libasound2 libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 libgcc1 libgconf-2-4 libgdk-pixbuf2.0-0 libglib2.0-0 libgtk-3-0 libnspr4 libpango-1.0-0 libpangocairo-1.0-0 libstdc6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 libxtst6 ca-certificates fonts-liberation libappindicator1 libnss3 lsb-release xdg-utils wget。这是一个较全的列表实际可能不需要全部。确保userDataDir路径存在且进程有读写权限。检查端口占用lsof -i:9222并杀掉占用进程或更换端口。5.2 元素定位不到或操作超时问题page.waitForSelector超时page.click失败。排查页面未加载完在操作前没有等待足够长时间元素尚未渲染。iframe嵌套目标元素在iframe内部需要先切换到对应的frame上下文。Shadow DOM现代Web组件可能使用Shadow DOM常规选择器无法穿透。动态ID/类名元素的ID或类名是JavaScript运行时生成的每次刷新都变化。解决使用更可靠的等待条件如page.waitForNavigation({ waitUntil: networkidle0 })网络空闲或page.waitForFunction(() document.readyState complete)。对于SPA单页应用networkidle0可能不适用可以等待特定元素出现。使用page.frames()找到目标iframe然后用frame.click(selector)操作。使用pierce选择器或element.shadowRoot属性。Puppeteer提供了page.$(pierce/#shadow-root .inner-element)这样的语法具体版本支持需查文档或者通过page.evaluateHandle执行JS来穿透Shadow DOM。使用更稳定的属性进行定位如name、># .env EMAIL_USERyour_emailexample.com EMAIL_APP_PASSWORDxxxx-xxxx-xxxx-xxxx # 建议使用邮箱服务商提供的应用专用密码密钥管理服务生产环境中使用Vault、AWS Secrets Manager等服务动态获取凭证。Cookie持久化如前所述通过userDataDir实现一次登录长期使用。这是最安全便捷的方式因为凭证本身密码不再需要被你的程序存储和传输而是由浏览器管理。无头模式的风险在无头模式下截图、录屏等功能依然可能泄露信息。确保运行环境安全并定期清理userDataDir中的敏感数据。6. 进阶优化与扩展思路当基础功能跑通后可以考虑以下方向让这个WorkBuddy邮箱助手变得更强大、更智能。6.1 实现更复杂的邮箱语义理解与操作目前的AI可能只擅长生成点击、输入等低级操作。我们可以训练或微调模型使其理解更高层次的邮箱语义意图识别用户说“把老板上周发的所有邮件找出来”模型应能识别出“搜索邮件”、“发件人老板”、“时间上周”等多个过滤条件并将其转化为Gmail搜索栏的输入词或调用邮箱的搜索API。操作抽象定义一套高级动作如archive_conversation(thread_id),forward_email(email_id, to_address, note)。让AI学习生成这些高级指令再由一个“技能执行层”将其翻译成底层的Puppeteer操作序列。这降低了AI的决策难度。多步骤任务规划用户指令“下载财务部本月所有报表附件并整理到一个Excel里”。这需要模型进行多步规划1) 登录邮箱2) 搜索“财务部”和“报表”3) 遍历邮件识别附件4) 下载所有附件5) 调用本地Python脚本将附件数据合并到Excel。这需要更强的规划能力和工具调用能力。6.2 集成其他本地AI能力附件内容理解下载的附件可能是PDF、Word或图片。可以集成本地的OCR库如Tesseract.js和多模态模型让WorkBuddy能“读懂”附件内容并根据内容进行更精细的分类或摘要。邮件内容摘要与分类对于大量邮件可以让本地模型对每一封邮件进行实时摘要和分类如“重要/普通”、“待处理/已归档”甚至自动生成回复草稿。自动化规则学习记录用户对邮件的常见操作如总是将来自某人的邮件标记为星标并移动到特定文件夹让模型学习并逐渐形成自动化规则实现个性化邮件管理。6.3 系统稳定性与可观测性操作日志与回放详细记录每一个AI生成的步骤和Puppeteer执行结果并保存关键步骤的页面截图。当出现错误时可以方便地回溯和诊断。心跳与恢复设计一个守护进程定期检查浏览器实例和AI服务是否健康。如果浏览器崩溃能自动重启并尝试恢复到之前的页面状态通过URL和Cookie。性能监控监控每个请求的端到端延迟从用户指令到操作完成以及本地模型的推理速度为优化提供数据支持。构建这样一个WorkBuddy邮箱助手是一个典型的AI Agent落地案例。它不仅仅是技术的堆砌更是对需求拆解、工具选型、异常处理和用户体验的综合考量。从最初的“能不能动”到后来的“稳不稳定”再到最后的“智不智能”每一步都充满了挑战和乐趣。希望这篇详细的实践记录能为你实现自己的自动化助手提供一份可靠的路线图。记住关键不是一步到位实现所有功能而是先搭建一个最小可行闭环然后在此基础上持续迭代和优化。