1. 为什么需要让 AI Agent 借用真实浏览器1.1 编码 Agent 的能力边界在哪里过去一年我一直在折腾各种编码 Agent从命令行里的代码补全到能自主规划任务的智能体踩过的坑不算少。有一个问题反复出现Agent 能读代码、能写代码、能跑测试但它看不到浏览器里到底发生了什么。你让它改一个前端登录逻辑它改完代码然后呢它没法自己打开页面点一下按钮没法确认登录态是不是真的生效了更没法验证一个需要已登录会话才能访问的接口返回了什么。这个断层很要命。现代 Web 开发里大量逻辑依赖真实的浏览器环境Cookie、LocalStorage、Session、CSRF Token、前端路由状态、WebSocket 连接。编码 Agent 在纯文本世界里再聪明一旦碰到这些就只能靠人去当眼睛和手。我试过让 Agent 生成一段 Playwright 脚本去模拟登录结果光是处理验证码和二次验证就折腾了半天而且每次跑都要重新登录效率极低。Tencent BrowserSkill 这个项目要解决的就是这个断层。它的核心思路很直接既然你本地已经有一个登录好的浏览器为什么不让 Agent 直接借用它不是模拟登录不是重新开一个无头浏览器而是通过一个本地桥接层让编码 Agent 能够操作你那个已经登录了各种账号的真实浏览器。1.2 本地桥接到底桥的是什么本地桥这个词听起来抽象拆开看就清楚了。桥的两端一端是编码 Agent比如跑在终端里的某个智能体进程另一端是你本地的真实浏览器Chrome、Edge 之类。中间需要一个协议层让 Agent 能发送指令打开某个 URL、点击某个元素、读取页面内容、执行 JS浏览器能返回结果。为什么强调本地因为整个通信不经过任何远程服务器。Agent 和浏览器都在你自己的机器上桥接层也是本地进程。这意味着你的登录态、Cookie、页面数据都不会离开你的设备。对于处理内部系统、需要登录的企业应用来说这一点是刚需。我之前用过的某些云端浏览器方案光是把登录态同步上去这一步就让人不放心。SSP 在这个项目里是一个关键词我理解它是这套桥接机制里的会话或协议标识。具体到实现层面它可能承担着会话保持、权限校验或者消息路由的职责。不管具体定义如何它的存在说明这套桥接不是简单的端口转发而是有一套结构化的会话管理在里面。1.3 谁最适合用这套方案不是所有人都需要这个。如果你只是写写后端接口、跑跑单元测试那普通的编码 Agent 足够了。但如果你符合下面几种情况这套东西的价值会非常明显做前端开发需要频繁验证页面交互和登录态维护需要登录才能访问的内部管理系统想让 Agent 帮忙做重复性的页面操作做自动化测试但不想每次都在脚本里硬编码登录流程研究 AI Agent 与真实环境交互想找一个可落地的本地桥接参考实现我自己的使用场景是第二种和第四种。公司内部有个运营后台每天要导出几份报表流程固定但必须登录。以前要么手动点要么写个脆弱的脚本。有了这套桥接Agent 可以直接复用我浏览器里已有的登录态把打开报表页、选日期、点导出这套动作交给它。2. 核心机制拆解Agent 如何看见并操作浏览器2.1 通信链路的三层结构把这套桥接拆开大致是三层。最上层是 Agent 侧它需要一套工具接口把我想做什么翻译成桥接层能理解的指令。中间层是本地桥接服务负责接收指令、转发给浏览器、再把结果回传。最下层是浏览器侧的扩展或注入脚本它真正执行 DOM 操作、读取页面状态。为什么要有中间层不让 Agent 直接跟浏览器扩展通信我理解有两个原因。一是解耦Agent 不需要知道浏览器扩展的具体通信方式只需要调用统一的接口。二是安全边界中间层可以做权限控制比如限制 Agent 只能访问某些域名或者只能执行只读操作。这在让 Agent 操作真实浏览器时很重要毕竟它动的是你登录了网银和邮箱的同一个浏览器。实际部署时中间层通常是一个本地 HTTP 服务或者 WebSocket 服务监听在 127.0.0.1 的某个端口。浏览器扩展通过这个端口注册自己Agent 也通过这个端口发送指令。整个链路不出本机。2.2 浏览器侧是怎么被借用的浏览器侧的实现方式直接决定了这套方案的可用性。常见的有两种路子一种是浏览器扩展一种是调试协议注入。扩展方式的优点是稳定、权限清晰扩展可以声明自己需要哪些权限用户安装时能看到。缺点是能力受扩展 API 限制有些底层操作做不了。调试协议方式比如通过 DevTools Protocol能力更强能做的事情更多但需要浏览器以特定参数启动而且对用户来说门槛更高。从我实际使用的体感来看如果目标是借用已登录浏览器扩展方式更合适。因为你的日常浏览器本来就是正常启动的装个扩展就能用不需要为了 Agent 专门改启动参数。调试协议方式更适合自动化测试场景那里本来就可以控制浏览器启动方式。这里有个关键细节扩展怎么知道 Agent 想操作哪个标签页如果浏览器开了几十个标签Agent 发一条点击登录按钮的指令它点哪个页面的所以桥接层需要一套标签页管理机制Agent 在操作前要先附着到某个标签页上后续指令都针对这个标签页。这跟 Playwright 里的 page 概念类似。2.3 已登录态是怎么被复用的这是整个项目最核心的价值点。已登录态本质上就是浏览器里的一组 Cookie 和存储数据。Agent 借用浏览器不是把这些数据复制出来而是直接在浏览器上下文里执行操作。所以登录态是原地复用不需要导出导入。具体来说当 Agent 让浏览器打开一个需要登录的页面时浏览器带着自己已有的 Cookie 发请求服务器认为这是已登录用户返回正常页面。Agent 看到的就是登录后的内容。整个过程 Agent 不接触 Cookie 本身它只是操作浏览器浏览器自己带着登录态去请求。这样做的好处是安全。Agent 拿不到你的 Cookie也就没法把登录态泄露出去。它只能在你授权的浏览器里做你允许它做的事。当然前提是桥接层的权限控制做到位不能让 Agent 随便访问任何页面。我实测下来这套机制对单点登录SSO场景特别友好。公司内部系统走 SSO登录一次之后多个子系统都通了。Agent 借用浏览器时这些子系统它都能访问不需要单独配置。2.4 SSP 在会话管理中的角色SSP 这个词在项目里出现我倾向于把它理解为会话状态协议或者类似的会话标识机制。为什么需要它因为 Agent 和浏览器之间的交互不是一次性的而是一个有状态的会话。举个例子Agent 要完成导出报表这个任务它需要打开报表页、等待加载、选择日期范围、点击导出、等待下载完成。这一系列操作必须在一个会话里完成中间不能断。如果每次操作都是独立的那第二次操作时页面状态可能已经变了。SSP 可能就是用来标识和维持这个会话的。Agent 发起一个会话拿到一个会话标识后续所有操作都带着这个标识桥接层根据标识找到对应的浏览器标签页和上下文。会话结束时释放资源。这套机制保证了操作的连续性和状态的一致性。3. 从零搭建本地桥接的实操过程3.1 环境准备与前置检查动手之前先把环境理清楚。你需要的东西不多但每一样都要确认到位。一个日常使用的浏览器Chrome 或 Edge 都行版本不要太老一个能跑本地服务的运行时Node.js 或者 Python 都可以一个编码 Agent能调用外部工具或 HTTP 接口的那种本地端口不被占用桥接服务默认端口要确认没冲突我建议先用一个干净的浏览器配置文件来测试不要一上来就用你登录了所有账号的主浏览器。等跑通了确认权限控制没问题再切到主浏览器。这个习惯能帮你避免很多意外。检查端口占用的命令很简单# macOS / Linux lsof -i :端口号 # Windows netstat -ano | findstr :端口号如果端口被占用要么换端口要么把占用进程处理掉。桥接服务的端口最好固定因为浏览器扩展和 Agent 都要连它端口变了就得改配置。3.2 桥接服务的启动与配置桥接服务是整个链路的中枢。启动它之前先看配置文件。通常会有这么几个关键项配置项作用建议值listen_host监听地址127.0.0.1只允许本机listen_port监听端口选一个不常用的高位端口allowed_origins允许的 Agent 来源按需限制不要用通配max_sessions最大并发会话数根据机器性能一般 3-5 够用session_timeout会话超时时间300 秒左右避免僵尸会话listen_host一定要是 127.0.0.1不要用 0.0.0.0。用 0.0.0.0 意味着局域网内其他机器也能连进来这是安全隐患。桥接服务只服务本机没必要对外暴露。启动命令根据实现不同而不同Node.js 项目一般是node bridge-server.js --config ./config.json启动后看日志确认服务在监听、没有报错。如果日志里出现waiting for browser extension之类的字样说明服务起来了在等浏览器扩展连接。3.3 浏览器扩展的安装与连接扩展的安装方式取决于你拿到的是打包好的 crx 还是源码。源码的话在浏览器扩展管理页打开开发者模式选择加载已解压的扩展程序指向扩展目录。安装后扩展图标应该出现在工具栏。点一下看它有没有显示已连接到本地桥接服务。如果显示未连接检查几件事桥接服务是不是在跑、端口对不对、扩展配置里的端口跟服务端是否一致。连接成功后扩展通常会显示当前可操作的标签页列表。这时候你可以试着从桥接服务的调试接口发一条测试指令比如获取当前活动标签页的标题看能不能拿到结果。这一步通了说明链路是通的。注意扩展的权限申请要仔细看。如果它申请了读取所有网站数据这类权限你要清楚这意味着什么。理想情况下扩展应该只在你明确授权的域名上工作而不是全量读取。3.4 Agent 侧的工具接入Agent 侧需要一套工具定义把桥接服务的能力暴露给 Agent。常见的做法是定义几个函数Agent 通过调用这些函数来操作浏览器。核心工具大概有这些browser_open(url)打开指定 URLbrowser_click(selector)点击元素browser_type(selector, text)输入文本browser_read(selector)读取元素内容browser_execute(script)执行 JS 脚本browser_screenshot()截图把这些工具注册到 Agent 的工具列表里Agent 就能在需要的时候调用。关键是工具的描述要写清楚让 Agent 知道什么时候该用哪个。比如browser_read的描述里要说明它返回的是元素的文本内容如果元素不存在会返回错误。我踩过的一个坑是工具描述太简略Agent 不知道该先打开页面再读取结果直接调browser_read导致失败。后来在描述里加了使用前需确保目标页面已打开的提示成功率明显提升。3.5 一个完整的实操案例自动导出报表拿我自己的场景举例。目标是让 Agent 自动从内部后台导出昨天的销售报表。第一步Agent 调用browser_open打开报表页面。因为浏览器已经登录页面直接显示报表界面不需要登录流程。第二步Agent 调用browser_read读取页面上的日期选择器确认当前选中的日期。然后调用browser_click和browser_type把日期改成昨天。第三步Agent 调用browser_click点击导出按钮。这里有个细节导出按钮点击后可能触发下载也可能弹出一个确认框。Agent 需要能处理这两种情况。我当时的做法是让 Agent 先截图看看点击后的页面状态再决定下一步。第四步等待下载完成。这一步比较麻烦因为浏览器下载是异步的。我的做法是让 Agent 轮询下载目录看有没有新文件出现。或者更简单点让桥接层监听下载事件下载完成后通知 Agent。整个流程跑下来从打开页面到文件落地大概十几秒。比手动操作快而且可以定时跑。关键是它复用了我的登录态不需要在脚本里存任何凭证。4. 实操中踩过的坑与排查技巧4.1 元素定位失败的几种典型情况Agent 操作浏览器最容易出问题的就是元素定位。页面上元素找不到后面的操作全白搭。我遇到过的原因有这么几类第一类是页面还没加载完。Agent 打开页面后立刻去找元素但 DOM 还没渲染出来。解决办法是加等待或者让 Agent 先读取页面状态确认加载完成再操作。桥接层最好提供一个等待元素出现的能力比固定 sleep 靠谱。第二类是元素在 iframe 里。很多后台系统用 iframe 嵌套页面Agent 在主文档里找元素当然找不到。这种情况需要先切换到对应的 iframe 上下文。桥接层要支持 frame 切换Agent 也要知道什么时候该切。第三类是元素是动态生成的选择器不稳定。比如用随机 ID 或者会变的 class。这种情况只能靠更稳定的选择器比如基于文本内容或者相对位置。我一般建议 Agent 优先用文本内容定位比 CSS 选择器稳。第四类是元素被遮挡。页面上有弹窗或者遮罩层元素虽然存在但点不到。Agent 需要先处理遮挡比如关闭弹窗再操作目标元素。4.2 登录态失效与重新认证虽然复用登录态很方便但登录态会过期。Agent 操作到一半突然跳到登录页后面的步骤全乱。这种情况怎么处理我的做法是让 Agent 在关键操作前先检查当前页面是不是登录页。如果是就暂停任务通知人工处理。不要试图让 Agent 自动重新登录因为登录往往涉及验证码、短信验证这些 Agent 处理不了的东西。另一个思路是让桥接层维护一个登录态健康检查定期访问一个需要登录的轻量接口看返回是不是 401。如果是提前告警而不是等 Agent 任务跑到一半才发现。提示对于登录态频繁失效的系统可以考虑在浏览器里保持一个长期活动的标签页定期刷新维持会话活跃。但这要看你访问的系统的会话策略有些系统就是会定时踢人没办法。4.3 并发操作导致的会话混乱如果你同时让多个 Agent 任务操作同一个浏览器很容易乱。比如任务 A 打开了页面 X任务 B 把标签页切到了页面 Y任务 A 再操作时就找不到自己的页面了。解决办法是会话隔离。每个 Agent 任务分配独立的标签页任务之间不共享标签页。桥接层要维护哪个会话对应哪个标签页的映射Agent 的指令只作用于自己会话的标签页。如果标签页不够用可以考虑用浏览器的多窗口或者干脆开多个浏览器实例。但多实例会带来登录态同步的问题因为每个实例的 Cookie 是独立的。这个取舍要看具体场景。4.4 常见问题速查表现象可能原因排查方向扩展显示未连接桥接服务没启动或端口不对检查服务进程和端口配置指令发出无响应会话已超时或标签页已关闭查看会话状态重新建立会话元素找不到页面未加载完或在 iframe 内加等待检查 frame 上下文点击无效元素被遮挡或不可交互截图查看页面状态处理遮挡登录态丢失会话过期或被其他操作踢出检查登录页人工重新登录下载文件找不到下载路径不对或未完成确认下载目录等待下载完成这张表是我自己遇到问题时总结的基本覆盖了八成以上的常见故障。遇到问题先对照这张表排查能省不少时间。4.5 权限控制与安全边界让 Agent 操作真实浏览器安全是绕不开的。我的原则是最小权限。Agent 只能访问它任务需要的域名只能做它任务需要的操作。具体实现上桥接层可以维护一个域名白名单。Agent 发起的browser_open如果目标域名不在白名单里直接拒绝。这样即使 Agent 被诱导去访问恶意页面也访问不了。操作类型也可以限制。比如只读任务就只开放browser_read和browser_screenshot不开browser_click和browser_type。需要写操作的任务再单独授权。还有一点Agent 执行的 JS 脚本要小心。browser_execute能力很强但也很危险。如果 Agent 能执行任意 JS它就能读取页面上的任何数据包括敏感信息。我的做法是限制 JS 执行的范围或者干脆不开放这个能力只提供结构化的操作接口。5. 这套方案还能怎么扩展5.1 多浏览器与多配置文件支持目前这套方案主要针对单个浏览器实例。但实际使用中你可能需要同时操作多个浏览器或者同一个浏览器的多个配置文件比如工作和个人分开。扩展的方向是让桥接层支持多个浏览器连接。每个浏览器扩展注册时带上自己的标识Agent 在发起会话时指定用哪个浏览器。这样就能实现任务 A 用工作浏览器任务 B 用个人浏览器。多配置文件的支持稍微复杂点因为不同配置文件的扩展是独立的。但原理一样每个扩展实例注册自己桥接层统一管理。5.2 与自动化测试框架的结合这套桥接机制其实可以跟 Playwright、Puppeteer 这类框架结合。框架负责测试逻辑和断言桥接层负责提供已登录的浏览器环境。这样测试脚本就不需要处理登录了直接跑业务逻辑。我试过把桥接层封装成一个 Playwright 的自定义 browser provider让 Playwright 以为它在控制一个普通浏览器实际上背后是已登录的真实浏览器。这样测试代码几乎不用改就能复用登录态。5.3 任务编排与定时执行单个 Agent 任务跑通之后自然会想到把多个任务串起来定时执行。比如每天早上自动导出报表、检查系统状态、发送汇总邮件。这需要一个任务编排层。可以用现成的 workflow 引擎也可以自己写个简单的调度器。关键是要处理好任务之间的依赖和失败重试。一个任务失败了不能影响后面的任务同时要能通知到人。我现在用的是最土的办法一个 cron 定时触发一个脚本脚本里按顺序调用 Agent 完成任务。简单但够用。等任务多了再考虑上正经的编排工具。5.4 从编码 Agent 到通用 Agent 的延伸这套桥接最初是为编码 Agent 设计的但它的能力不限于编码。任何需要操作浏览器的 Agent 都能用。比如做数据采集的 Agent、做客服自动回复的 Agent、做内容发布的 Agent。我最近在试的一个场景是让 Agent 帮忙处理后台的审批流程。每天有一堆待审批的条目规则明确的 Agent 自动批规则模糊的留给我人工处理。Agent 通过桥接操作审批页面我只需要处理它筛出来的少数条目。效率提升很明显。这个方向的想象空间很大。核心在于一旦 Agent 能操作真实浏览器它就能接入几乎所有基于 Web 的系统不管这些系统有没有 API。这对于那些没有开放接口的老系统来说等于给它们加了一层自动化能力。5.5 性能与稳定性的持续优化跑得久了性能和稳定性问题会逐渐暴露。我遇到过的有长时间运行后内存增长、频繁操作导致浏览器卡顿、网络波动导致指令超时。内存问题一般是会话没正确释放。每个会话结束后要确保清理干净标签页关掉、监听器移除、缓存清空。我加了一个会话回收机制超过一定时间没活动的会话自动清理内存增长就控制住了。浏览器卡顿通常是操作太频繁。Agent 连续快速点击、输入浏览器渲染跟不上。解决办法是在操作之间加适当的间隔或者让 Agent 等待页面稳定后再进行下一步。不要追求极限速度稳定比快重要。网络波动导致的超时需要桥接层有重试机制。指令发出去没响应等一会儿重试而不是直接失败。重试次数和间隔要合理避免雪崩。这套东西我前后折腾了小半年从最初跑个 demo 都费劲到现在能稳定支撑日常的自动化任务。中间踩的坑基本都写在上面的排查表里了。如果你也在做类似的事情希望这些经验能帮你少走点弯路。最想说的是别一上来就追求大而全先把一个最简单的场景跑通比如打开页面读取标题然后再逐步加功能。每一步都验证过再往下走比一口气搭完再调试要快得多。