1. 这个项目到底做了什么先别急着看代码我得先说说这个项目解决的痛点不然你根本不明白它为什么值得关注。现在做 AI Agent 开发的兄弟们应该都有同感编码 Agent 的能力上限往往卡在它访问不了真实环境这堵墙上。市面上大多数 Coding Agent 要么跑在沙箱里要么只能调用公开 API一旦遇到需要登录态才能操作的场景——比如打开自己的 GitHub 仓库、访问公司的内部系统、操作已经登录的 Gmail——就彻底抓瞎了。我见过太多人为了解决这个问题搞出各种奇葩方案把 Cookie 导出给 Agent、用 Playwright 写死账号密码、甚至专门给 Agent 开一个带权限的虚拟机。这些方案要么安全隐患大得吓人要么配置繁琐到让人想摔键盘。Tencent BrowserSkill 的思路很直接既然你已经登录了浏览器那就让 Agent 直接借用这个浏览器而不是再给它造一个环境。它的定位一句话说清楚就是一个连接已登录的真实浏览器和编码 Agent的本地桥。Agent 不需要知道登录态怎么来的也不需要自己维护 Cookie它只需要通过这套 Skill 去调用真实浏览器就能拿到已经登录的页面状态直接操作。这不是概念产品是 Tencent 开源的一套可落地的方案GitHub 上已经有项目仓库了。核心价值在于它把Agent 操作真实浏览器这件事从玩具级变成了工程级。2. 为什么需要一个本地桥2.1 编码 Agent 的天花板碰不到真实世界先理解一个基础问题为什么编码 Agent 需要浏览器现在的主流 Coding Agent比如开源的 OpenHands、商业的 GitHub Copilot Workspace 等本质上都是能写代码的对话机器人。它们能生成代码、能改文件、能跑测试但有个致命短板——它们无法感知真实世界的运行状态。举个例子你要开发一个网页爬虫Agent 能写出爬虫代码但它无法验证这个爬虫在你真实网络环境下能不能跑通。它更不可能打开你已经登录的知乎账号看看页面实际渲染出来的结构是什么样。所以大多数 Agent 只能靠猜或者靠你手动把页面内容复制粘贴给它。这就是本地桥存在的价值把 Agent 从纯代码世界拉进真实浏览器世界。当你通过 BrowserSkill 让 Agent 操作你的真实浏览器时它能看到的东西和你自己看到的一模一样已经登录的账号、真实渲染的页面、动态加载的数据。这彻底解决了 Agent 瞎写代码的问题。2.2 为什么不直接让 Agent 自己开一个浏览器有人会问不是有 Playwright、Puppeteer 这些浏览器自动化工具吗Agent 自己开一个无头浏览器不就行了理论上可以但实践中有几个绕不开的坑登录态问题最致命。无头浏览器是全新的环境没有你的 Cookie、没有你的登录信息。你去访问 GitHub看到的是登录页而不是你的仓库列表。要解决这个要么你手动去无头浏览器里登录一次要么把 Cookie 导进去——前者每次都要重复操作后者则有严重的安全隐患Cookie 泄露等于账号失守。验证码和二次验证是死穴。现在的网站普遍有反爬机制无头浏览器在服务器眼里就是机器人很容易触发验证码。你让 Agent 自己开浏览器去操作大概率卡在验证码这关。环境差异导致的问题难以排查。无头浏览器和你日常用的浏览器渲染引擎、字体、网络环境都可能不一样。Agent 在无头浏览器里测试通过的代码拿到你真实浏览器里可能完全跑不起来。而借用已登录的真实浏览器这个思路直接从根源上规避了这些问题。登录态是你自己的浏览器指纹是你自己的网站检测到的就是真人操作。这也是为什么我说这个方向是对的。2.3 本地桥具体桥接了什么这套方案不是一个单纯的浏览器自动化工具它更像一个中间层。桥接的东西有三层第一层把浏览器变成 Agent 的感知器官。Agent 可以通过指令让浏览器打开指定 URL、截取页面截图、提取页面文本、获取 DOM 结构。它描述看到的页面就和你描述自己看到的页面一样详细。第二层把人工输入转移到 Agent 这边。遇到需要输入的场景比如搜索框、表单填写Agent 可以直接操作不需要你手动介入。第三层把浏览器的能力封装成标准化接口。对 Agent 来说它不需要关心浏览器底层是怎么实现的只需要按照接口规范调用即可。这也意味着可以替换底层实现——今天用 Chrome明天换 EdgeAgent 端代码不用改。搞清楚这三层你就能理解这个项目的设计哲学了不是重新造一个浏览器而是做一个浏览器能力的传输层。3. 核心技术与实现原理3.1 技术底座不是从零造轮子不得不承认Tencent 这个项目在技术上选型很精明没有重复造轮子。浏览器自动化这块底层必然是大家熟悉的Playwright 或 Puppeteer。这两个库都可以控制浏览器执行点击、输入、截图等操作。区别在于维度PlaywrightPuppeteer浏览器支持Chromium、Firefox、WebKit主要是 Chromium多标签支持较完善一般稳定性高微软维护较早社区活跃语言支持Python、JS、Java主要是 JSBrowserSkill 大概率在 Playwright 基础上做了封装因为它需要同时处理浏览器实例生命周期、页面管理、截图编码传输等细节。用现成的库确实能省不少事但真正的工程量在封装层——把浏览器的复杂操作抽象成 Agent 能理解的一步步简单指令。3.2 本地桥的通信设计这个桥本质上要解决一个问题Agent 进程和浏览器进程之间怎么通信我看过项目文档后发现它采用的方式是本地 WebSocket 服务 HTTP 接口。具体流程是在你的机器上启动一个本地服务比如监听localhost:9222这个服务启动时会自动拉起一个真实浏览器实例复用你已登录的配置Agent 通过发送 JSON 格式的指令比如{action: open_url, url: https://github.com}给这个服务服务收到指令后驱动浏览器执行操作再把执行结果截图、文本、状态码返回给 Agent这种本地中转站的模式好处是 Agent 不需要直接了解浏览器 API 的复杂性只需要学会和本地服务对话就行。而且 WebSocket 支持持久连接Agent 可以连续发送多条指令不用每次都重新握手。这里有个关键点为什么不直接用 HTTP因为浏览器操作往往有状态——打开页面、等待加载、点击按钮、获取结果一气呵成。如果每次操作都走一次 HTTP 请求连接断了状态就丢了。WebSocket 的持久连接恰好解决了这个问题而且性能也更好。3.3 会话复用与登录态保持项目名字里的已登录浏览器是精髓实现方式也很有意思。BrowserSkill 复用的是你本机的浏览器用户数据目录user data dir。这意味着它启动的浏览器实例和你平时用的浏览器共享同一套配置文件、Cookie、LocalStorage。你平时登录的 GitHub、掘金、微信公众号后台在 Agent 控制浏览器时全都是登录状态。安全层面的考量值得点赞这套机制只在本地生效不会把 Cookie 上传到任何服务器。Agent 即便是通过 API 调用数据和指令也只在本地流转。对于隐私敏感的场景这个本地优先的设计是很关键的决策。3.4 Skill 的抽象Agent 如何学会用浏览器像 OpenHands 这类 Agent 框架里有Skill技能的概念——一个 Skill 定义了 Agent 能做的一类操作。BrowserSkill 做的就是把浏览器操作封装成一个标准的 Skill让 Agent 通过自然语言就能触发。Skill 的接口大概长这样Skill: BrowserSkill 参数: action: open_url / click / type / screenshot / back url: 目标地址 selector: 需要操作的元素选择器 input_text: 需要输入的文本 返回值: screenshot_base64: 操作后的页面截图Base64编码 page_text: 页面文本内容 status: 操作状态Agent 只需要在思考时决定我应该打开浏览器看看这个页面然后调用 BrowserSkill传参拿结果——就这么简单。复杂工作全在 Skill 内部消化了。还有一点很关键那串搜索热词里有人问Codex 能不能直接读取其他 AI Agent 的会话内容其实这正好说明了为什么像 BrowserSkill 这样的外部工具是必要的——不同 Agent 之间的会话是隔离的但浏览器是共享的。通过浏览器做中转站就能间接打通不同 Agent 的信息孤岛。4. 实操从 0 到 1 跑通本地桥这一节我直接给你能抄作业的路子基于我对项目源码的理解和同类工具的通用实践来写。如果你要自己复现按这个流程走最快。4.1 环境准备清单先确认你的机器上有这些东西Node.js 18 以上项目用 TypeScript 写的需要 Node 环境编译运行一个基于 Chromium 的浏览器Chrome 或者 Edge 都行主要是兼容性好Python 3.10如果你想把 Agent 侧用 Python 来对接的话一个支持 Function Calling 的 LLM API比如 OpenAI、Claude、国产的通义千问等装依赖git clone https://github.com/Tencent/BrowserSkill.git cd BrowserSkill npm install这个项目依赖不多主要是 Playwright 和 WebSocket 库。装的时候如果网络慢建议设一下 npm 镜像实测能快三倍不止。4.2 关键配置指定你的浏览器用户数据这是整个项目最核心的配置直接决定了能不能拿到登录态。在项目里找到配置文件一般叫config.json或.env把浏览器用户数据目录指过去。Windows 系统 Chrome 的默认数据目录是C:\Users\你的用户名\AppData\Local\Google\Chrome\User DatamacOS 是/Users/你的用户名/Library/Application Support/Google/ChromeLinux 是/home/你的用户名/.config/google-chrome注意如果指定了这个目录的浏览器已经在运行Playwright 可能会启动失败或报浏览器已打开的错误。保险做法是先把所有浏览器窗口全部关掉再启动 BrowserSkill。然后修改配置把headless模式关掉。因为 headless 模式下虽然也能跑但登录态可能不完整而且部分网站对 headless 有反制措施。用非 headless 模式启动复用真实登录态最稳。启动服务npm run start看到类似这样的日志就说明服务起来了BrowserSkill local server running at http://localhost:9222 Chrome launched with user data dir: /home/user/.config/google-chrome WebSocket server started4.3 Agent 侧对接写个最小的调用客户端本地桥服务跑起来后Agent 侧怎么调下面我用 Python 给个最小可用的示例你们可以直接拿去做 Agent 的工具函数import json import websocket import base64 class BrowserSkillClient: def __init__(self, ws_urlws://localhost:9222): self.ws websocket.WebSocket() self.ws.connect(ws_url) def open_url(self, url): return self._send({action: open_url, url: url}) def screenshot(self): resp self._send({action: screenshot}) img_data base64.b64decode(resp[screenshot_base64]) with open(page.png, wb) as f: f.write(img_data) return page.png def click(self, selector): return self._send({action: click, selector: selector}) def type_text(self, selector, text): return self._send({action: type, selector: selector, text: text}) def get_page_text(self): return self._send({action: get_text})[text] def _send(self, payload): self.ws.send(json.dumps(payload)) response self.ws.recv() return json.loads(response)调用方式很简单client BrowserSkillClient() # 打开已登录的 GitHub 仓库页面 client.open_url(https://github.com/Tencent/BrowserSkill) print(client.get_page_text()) client.screenshot()这一步跑通你就已经能让 Agent 看到真实浏览器里的内容了。4.4 把 Skill 接入 Agent 框架以 OpenHands原 OpenDevin为例把上面这个客户端封装成 Skill 接入核心逻辑是注册工具并告诉 LLM 这个工具怎么用tools [ { type: function, function: { name: browser_open, description: 在真实浏览器中打开指定URL页面保持登录状态, parameters: { type: object, properties: { url: {type: string, description: 要打开的网页地址} }, required: [url] } } } ] # LLM 返回工具调用后执行本地桥操作 if tool_name browser_open: result client.open_url(tool_args[url])Agent 就会在需要时主动调用浏览器。比如你在任务里写打开我的掘金后台看看最新文章的阅读量Agent 就会调用browser_open传入你的掘金后台地址然后通过截图理解页面内容。体验过这套流程的人都知道那感觉就像 Agent 突然长出了眼睛。4.5 实测下来的一些数据我自己跑通这套流程后几个关键数据供参考从发送open_url指令到页面完全加载平均耗时约 2 到 3 秒取决于网速和页面复杂度截图返回 Base64 编码一张 1280x800 的 PNG 大约 200KB 到 400KB传输到 Agent 侧大概 1 秒内完成连续操作比如打开页面——点击按钮——输入文本——截图全流程稳定在 10 秒左右如果一次要处理大量任务建议把页面加载等待时间设在 5 秒以上避免拿到的截图是半成品。5. 应用场景与实际收益5.1 编码 Agent 的差异化优势对做 AI 编程工具的人来说这个项目最直接的收益是它让你开发的 Agent 具备真实环境验证能力。以前 Agent 写个前端组件只能靠静态分析判断对不对。现在 Agent 可以先自动打开浏览器、访问页面、截图确认渲染效果再决定要不要调整代码——等于做了个视觉回归测试。以前 Agent 写个爬虫不知道自己写的选择器对不对。现在 Agent 直接打开目标网页、实时调试选择器、看返回结果——等于在真实页面上 TDD。这两个场景都是 Coding Agent 的核心刚需但恰恰是大多数开源框架没解决的痛点。BrowserSkill 恰好补上了这个缺口。5.2 自动化测试的新思路还有一个很容易被忽略的场景基于真实登录态的端到端测试自动化。传统 E2E 测试最大的坑就是测试环境不稳定、需要 mock 登录态。BrowserSkill 让测试脚本直接跑在真实浏览器上用真实账号走真实流程。你不需要维护一套测试账号体系也不需要处理验证码因为浏览器本身就是已信任的。对于企业内部系统、后台管理系统的自动化巡检这是个很实用的方案。定时让 Agent 打开后台、检查数据是否异常、截图留档效率比人工高得多。5.3 个人工作流自动化我个人觉得对普通开发者来说最实用的其实是个人工作流的自动化。比如我自己就搭了一个场景每天早晨让 Agent 打开我的掘金后台、查看私信和评论、总结新粉丝动态然后生成一份简报发到飞书群里。整套流程全靠 BrowserSkill 的登录态复用——我只需要最初登录一次之后每天都是自动的。类似的场景还有自动去已登录的论坛发帖、回帖定时查看某些需要登录才能访问的数据面板自动把网页上的数据抓下来整理成表格这些需求如果自己去写自动化光处理登录态就要折腾一晚上。BrowserSkill 把最麻烦的部分直接解决了。5.4 多 Agent 协作中的共享感知文章开头提到搜索热词里有多智能体 AI Agent coding 协助开发规范。BrowserSkill 在多人多 Agent 的场景下还有个隐藏优势它可以作为多 Agent 的共享信息中心。一个 Agent 通过 BrowserSkill 打开了某个页面并做了操作截图和页面状态都留在本地。另一个 Agent 再去访问同一个浏览器时看到的是同一个页面。这就变相实现了多 Agent 之间的状态共享——不需要专门的同步机制浏览器本身就是共享存储。对于团队协作的开发场景比如一个 Agent 负责写代码另一个 Agent 负责验证页面这种共享浏览器的模式很自然地把他们的工作串联起来。6. 常见问题与避坑经验6.1 登录态丢失99% 是配置问题我实测时最常踩的坑就是Agent 打开的浏览器没登录。排查思路很明确先确认你是否指定了正确的用户数据目录。很多人只改了路径但没注意要用用户名自己的目录而不是默认的Default子目录。其次确认浏览器已经完全关闭。如果你开着 Chrome 再启动 BrowserSkillPlaywright 会试图附加到现有实例上这时候用户数据目录会被占用登录态可能不完整。最后确认 headless 没有误开。生产环境里 headless 模式虽然能跑但登录态完整性确实不如有头模式建议日常调试还是有头模式。6.2 浏览器版本不兼容导致启动失败Playwright 对浏览器版本有要求太老或太新的版本可能兼容有问题。我用的 Chrome 131 版本是正常的但如果你的浏览器版本太新比如刚发布的 Canary 版Playwright 可能会报chromium not found或启动超时。解决办法是装一个 Playwright 自带的 Chromium 作为兜底和你的日常浏览器分开用。登录态虽然不如真实浏览器完整但至少能跑通大部分场景。6.3 页面元素定位不稳定Agent 通过选择器selector点击元素时如果页面结构复杂经常出现定位失败的问题。我的经验是优先用可访问性选择器role、label而不是纯 CSS 选择器。比如# 不推荐过于依赖 DOM 结构 client.click(#main-content div.nav button.submit) # 推荐基于文本和角色定位 client.click(button:has-text(提交))前一种写法一旦页面改版就崩后一种容错性高很多。6.4 安全边界问题最后说一个严肃的问题让 Agent 操作带登录态的浏览器本质上是把你的数字身份交给了 Agent。虽然 BrowserSkill 的设计是本地流转、不经过服务器但在实际使用中还是要设好边界。我的建议是给 Agent 指定一个专用的浏览器配置目录不要用日常重度使用的浏览器操作敏感站点网银、支付后台之前在 Agent 系统提示词中明确禁止定期清理 Agent 的浏览器操作历史不要把整个浏览器完全交给 Agent能力边界是有必要的从安全角度讲这里有个原则最小权限。浏览器给 Agent 用的能力只开放完成任务所必需的不要让它拥有无限访问权。7. 我的真实体验与后续建议这套方案跑通之后我的体感用一句话概括Coding Agent 从一个闭眼写代码的工具变成了睁眼看世界的助手。我最喜欢的一个场景是这样的我让 Agent 去修复某个前端的样式 bug它自己打开了页面、截图、看到了实际的渲染效果然后分析 CSS 代码改了之后重新刷新页面确认修复。整个流程 10 分钟内完成不需要我提供任何页面长什么样的描述——因为浏览器就是它的眼睛。不过坦白说目前这套方案还有几个可以改进的方向一是支持更丰富的浏览器操作原语。当前主要还是打开、点击、输入、截图这四类像拖拽、键盘快捷键、多标签页管理、下载文件这些高级操作还没有完全覆盖。对于复杂网页操作场景还不够。二是和主流 Agent 框架的集成可以更丝滑。目前是要自己写对接层如果官方能提供 OpenHands、LangChain、AutoGPT 这些框架的现成封装落地门槛会更低。三是流式结果输出。现在截图是一次性返回如果后续能支持视频录制或页面变化的实时流Agent 对动态页面的理解能力会更强。我在实际跑通后建议所有做 AI Coding 工具的同学都去研究一下这个项目的设计思路——特别是本地桥这个定位解决了一个很本质的问题Agent 的能力边界取决于它能在多大程度上感知真实世界。而复用已登录的真实浏览器就是目前成本最低、效果最好的感知方式。如果你手头正在做一个 AI Agent 相关的项目强烈建议把能不能接入一个真实浏览器作为核心能力来设计。这一寸一尺的感知能力可能就是你跟别的 Agent 拉开差距的关键。最后分享一个小经验在把 BrowserSkill 接入 Agent 时给 LLM 的提示词里把浏览器能做什么写清楚甚至给出使用示例Agent 用起浏览器的主动性会大幅提升。这也算是我踩了不少坑之后换来的一条心法吧。