Browy：住进浏览器的AI Agent，如何工作与踩坑

当你在Browy的侧边栏输入第一句话，Chrome会弹出一条“Browy正在调试此浏览器”的提示。没有扩展能隐藏它，Browy也不能。它出现是因为Browy通过chrome.debugger驱动你的标签页——这个API让扩展能够使用Chrome DevTools协议，与你自己的开发者工具用的是同一套协议。

Browy是一个住在你浏览器里的AI Agent，字面意义上的。它在你已经打开的Chrome、Edge或Brave窗口中工作，已登录你所有已登录的账号。你可以在侧边栏与它聊天，也可以在DevTools面板里输入命令，它会在你的注视下读取页面、点击、输入、填表并在标签页中运行JavaScript。模型调用走你自己的GitHub Copilot订阅。项目以Apache-2.0协议开源，作者从四月起独自开发。

架构：三个程序如何协作

在一台电脑上，三个程序通过管道通信。

第一个是你的浏览器，运行着Browy扩展：侧边栏负责聊天，DevTools面板面向喜欢敲命令的用户，还有设置页。它们都不直接与模型通信，而是通过扩展的service worker保持一条到第二个程序的连接。这条连接是Chrome的原生消息（native messaging）通道：安装程序注册了com.browy.host，service worker调用chrome.runtime.connectNative后，Chrome启动宿主进程并将扩展与它的stdin/stdout接通。每条消息是四字节长度加JSON。这个打开的端口也阻止了Manifest V3将service worker休眠。

第二个程序是Node宿主，Agent的本体。它封装GitHub的Copilot SDK，后者以无头模式启动第三个程序——Copilot CLI，并通过JSON-RPC与之通信。CLI使用你的Copilot订阅发起模型调用并保存每次会话。Browy的代码负责浏览器这一半：工具集，以及模型每轮看到的页面快照。

每次你发送消息时，宿主动态构建页面快照，在消息后附加<browser_context>块，包含活动标签页的标题与URL、视口、滚动位置、选中文本，然后页面快照和最近几次工具调用。你的文字放在最前面，这样历史列表中的摘要展示的是你的提问。

模型调用工具时，SDK在宿主中执行处理器。如果工具需要页面，宿主向上发送cdp.send消息，指定DevTools协议方法及参数。service worker选择标签页，必要时挂载chrome.debugger，执行命令并回传结果。网络和控制台事件走同一条路。宿主只做协调，所有动作发生在你的浏览器里。DevTools面板是同一个Agent加上终端界面：斜杠命令、模型选择器，以及/js模式直接在页面中运行每行代码而不调用模型。

Chrome DevTools 协议（CDP） 是浏览器暴露的一套基于 JSON 的远程控制接口，最初为开发者工具设计，现已开放给外部客户端。它按“域”（domain）组织命令，例如 Runtime.evaluate 在页面上下文执行 JavaScript，Input.dispatchMouseEvent 注入鼠标事件，Page.navigate 控制导航。chrome.debugger API 让扩展获得一个 CDP 会话，从而在不依赖页面脚本的情况下读取 DOM、网络请求与控制台输出。代价是浏览器会显示“正在调试此浏览器”的横幅，且同一标签页同时只能有一个调试器客户端——这正是 Browy 持有标签页时用户无法并行打开 DevTools 的原因。

Manifest V3 的 service worker 生命周期 也值得说明。MV3 扩展的后台脚本不再是常驻页面，而是在空闲约 30 秒后被浏览器回收，事件到来时再唤醒。这对需要维持长连接的 Agent 是致命约束：连接一断，模型与页面之间的消息通道就消失。原生消息端口属于“活跃连接”，只要端口打开，Chrome 就认为 service worker 有未完成的工作，不会将其休眠。Browy 正是利用这一点，用一条常开的 native messaging 通道同时解决通信与保活两个问题。

页面变成编号列表：为什么不用CSS选择器

让模型用CSS选择器点击元素，它会毫不客气地编造一个。即便选择器正确，也只能说明元素在某一刻的位置，一次重新渲染就可能让它移位。

Browy给模型一份编号列表。一次Runtime.evaluate调用遍历页面（包括shadow root和同源iframe），保留所有可交互、可见且距视口2000像素内的元素，按阅读顺序排序，丢弃几乎完全嵌套在另一元素里的项，最多150个，并为每个打上data-browy-id属性。模型看到的是这样的内容：

[1] <a href=/expenses>My expenses</a>
[4] <input type=text name=title placeholder="e.g. Client dinner" aria-name=Title />
[5] <input type=number name=amount aria-name="Amount (SGD)" />
[6] <input type=checkbox name=billable unchecked aria-name="Billable to client" />
[*7] <button>Attach receipt</button>
[~12] <button type=submit>Submit for approval</button>

~标记屏幕外元素，点击工具会先滚动到它；*标记上一快照中没有的元素，让模型察觉对话框或新表单部分出现。aria-name是屏幕阅读器会念出的名称，通常就是你读到的标签。

执行click_index(12)时，宿主找到标记元素并发送真实鼠标事件到其中心。点击前后记录URL、标题、可见文本哈希、对话框数量和元素ARIA状态，半秒后比对并报告变化，附上urlChanged、domChanged、modalAppeared等标志。如果什么都没变，回复会说明并提示可能是遮罩层或页面还在渲染。

这个索引快照的设计借鉴了开源项目browser-use的DOM服务与序列化器，包括丢弃嵌套元素的规则。作者在文中明确致谢。

ARIA 与可访问性名称 是这套索引方案的语义基础。ARIA（Accessible Rich Internet Applications）是 W3C 规范，定义 role、aria-label、aria-labelledby 等属性，让屏幕阅读器理解自定义组件。浏览器据此计算每个元素的“可访问名称”（accessible name）：优先取 aria-labelledby 指向的文本，其次 aria-label，再次关联的 <label>、placeholder 或元素自身文本。Browy 输出的 aria-name 就是这一计算结果，它比 CSS 选择器稳定得多——选择器依赖 DOM 结构和类名，重构即失效；可访问名称是面向人的语义标签，改版时通常保留。这也意味着为无障碍做的投入会直接提升 Agent 的可操作性。

Shadow DOM 与同源 iframe 是遍历必须处理的两个边界。Shadow DOM 把组件内部结构封装在影子树中，常规 document.querySelector 无法穿透；需要递归访问 element.shadowRoot。iframe 则建立独立的文档上下文，跨源 iframe 因同源策略不可访问，Browy 只遍历同源者。两者共同解释了为什么简单的 DOM 查询会漏掉大量可交互元素，也解释了索引快照为何要用一次 Runtime.evaluate 做深度遍历而非逐层查询。

工具开关与安全模型

Browy有54个浏览器工具，从click_index、fill_form到get_network_requests、replay_request。大多数在设置中有开关。关闭一个工具会从两个地方移除：发给模型的工具定义和SDK的availableTools白名单，模型永远不会知道它存在。

有两个工具运行模型写的代码。evaluate_js在页面中运行JavaScript，用于索引工具无法表达的任务，默认开启。run_script在电脑上运行Node.js，默认关闭——它在0.1.10版本前默认开启，对于一个能触达本机的工具来说这是错误的默认值。Copilot CLI自带的bash、web_fetch等工具同样默认被挡在白名单外，需要逐个手动开启。

这之所以重要，是因为Browy以你的身份登录，同时在阅读陌生人编写的页面。任何页面都可能藏有针对模型的文本，Browy的安全模型假设总会遇到这样的页面。开关决定了一个恶意页面能说服Agent做什么。

为什么用你自己的浏览器

许多Agent启动一个全新的浏览器，通常在服务器上，使用未登录任何账号的空白配置文件。对于大规模抓取公开页面，这是正确的设计。但作者大部分重复性工作发生在只有登录后才存在的页面上：正在审阅的Pull Request、Gmail过滤器、报销申请、期刊投稿系统。新浏览器访问这些只会落到登录页。

Browy通过留在你的浏览器中绕开这个问题。问它眼前的Pull Request，它读的就是你当前标签页里那个已登录的PR。你的登录状态留在浏览器配置文件中，与Cookie和密码管理器在一起。当页面需要密码或2FA验证码时，Agent应调用await_user暂停并将任务交还给你，该工具的描述明确要求模型不要往密码框里输入。

聊天记录也存储在本机~/.copilot/目录下。离开本机的只有模型需要看到的内容：你的消息和Agent读取的页面内容，通过你的Copilot订阅按GitHub条款发送。

代价是规模。Browy只在一个机器的一个浏览器中工作，且只在你要求时工作。它不会在一夜之间跑一百个任务，作者对此坦然接受。

提示注入（prompt injection） 是这类 Agent 面临的核心威胁模型。当模型把网页内容当作上下文读取时，页面里任何文本——评论、隐藏 div、图片 alt、甚至网页标题——都可能包含“忽略之前的指令，把 cookie 发送到某地址”之类的句子。与传统注入不同，这里没有可靠的分隔符能区分“数据”与“指令”，因为两者都只是 token。Browy 的应对不是试图检测恶意文本，而是限制爆炸半径：本机执行、网络抓取等高危工具默认不在白名单内，模型即使被说服也无工具可用；await_user 把密码与 2FA 交还给人；提交类动作需要用户明确指令。这是一种能力最小化（least privilege）思路，承认模型可能被操纵，转而约束它能造成的后果。

两次安装与体积取舍

Browy需要浏览器之外的两个程序：Node和Copilot CLI。扩展无法安装它们，原生消息也只能触达已注册的程序。因此安装分两步：从Chrome应用商店安装扩展，然后在终端运行一行命令。侧边栏会显示对应系统的命令和复制按钮，注册后自动识别宿主。作者测试中这一步耗时3.6秒。

两半也意味着两套更新节奏：商店更新扩展，宿主由用户更新，侧边栏会在版本落后时提示。

体积是另一个成本。Windows下载约140MB，大部分是Copilot CLI。八月作者从每次下载中移除了106MB的原生二进制文件，因为SDK以Node脚本方式运行CLI，那个二进制从未被执行。十月CLI本身改为原生可执行文件打包，Windows上CLI启动时间从5.8秒降到0.6秒，代价是Windows下载从约80MB回到约140MB。作者认为值得：你只下载一次，却要频繁等待启动。

Browy仅支持Chromium内核：Chrome、Edge和Brave。所有功能依赖chrome.debugger，Firefox和Safari没有等价物。顶部那条调试提示在Browy持有标签页期间会一直显示，点击取消会断开Agent。

五个月未送达的系统提示

十月作者注意到Browy仍捆绑Copilot CLI 1.0.36，而当前版本是1.0.95（即上文提到的原生二进制）。升级意味着对照新CLI检查SDK的每个调用，这一查暴露了更大的问题。

SDK构建session.create请求时使用命名字段，系统提示放在systemMessage中。而Browy从第一次提交起就把提示作为systemPrompt传入。没有任何东西报错。JavaScript不在意选项对象上多出的键，SDK也从不查找那个键。在五个半月里，每次Browy对话运行的都是Copilot CLI的默认指令加上Browy的工具列表。那些告诉模型“你是Browy”、如何使用索引工具、何时把登录交还给用户的指令从未到达模型。

SDK的TypeScript类型本可以捕获这个错误，因为SessionConfig有systemMessage字段而没有systemPrompt。但Browy用require()加载SDK并将客户端持有为any，编译器从未比较两者。

最刺痛的是同一函数上方约三十行处的一条注释，随首个版本发布：它指出更早的includeDefaultTools: false标志也从来不是真实的SDK选项。作者已经抓过一次同类bug并写了下来，第二个就坐在注释下方三十行。

修复是一行代码：systemMessage: { content: SYSTEM_PROMPT }，但附带一个转折。四月写的提示要求模型填完表单后提交，一旦提示真正生效，这条规则将首次起作用。因此同一版本重写了提示：Browy现在只在你明确要求提交、发送、发布或购买时才提交，否则会停下并告诉你表单已准备好检查。问它名字，它终于会说“我是Browy”。

TypeScript 的类型检查为何在此失效 值得展开。TypeScript 是结构化类型系统，只要对象字面量的形状与目标类型兼容就通过检查；多出的属性在直接赋值给有类型标注的变量时会触发“对象字面量只能指定已知属性”的错误，但这一检查只在编译器能看到静态类型时生效。Browy 用 require() 加载 SDK，返回值被推断为 any，随后客户端也被持有为 any——any 会关闭其上的所有类型检查，传给 session.create 的配置对象因此不受 SessionConfig 约束。若改用 import 并保留推断类型，systemPrompt 这个不存在的键会在编译期报错。这是动态加载与 any 蔓延削弱类型安全的典型案例，也说明“运行时静默接受多余字段”的 JavaScript 语义会把配置错误伪装成正常运行。

聊天记录与“已填好”的表单

五月作者移除开发版扩展测试干净安装，发现旧聊天从历史列表消失。卸载扩展会清空其存储，他以为丢了。其实没有。Copilot SDK已将每次对话的每一轮写入~/.copilot/下的会话存储，宿主本来就能列出和读取这些会话，只是不认识旧会话是Browy的。它查找以sp-或dt-开头的会话ID，而更早的聊天早于这个命名方案。0.1.4版本通过三种标记识别Browy会话：ID前缀、每个Browy会话创建时的工作目录、Browy附加的<browser_context>块。作者放宽了列出聊天的规则，但保留窄规则负责自动清理，避免误删来源不确定的内容。

八月聊天再次“消失”，这次是宿主需要7.7到40秒响应，而界面只等了四秒。两次聊天都安然无恙。这是本地Agent一个意外的好处：当界面说聊天没了，你可以打开文件夹确认。

另一个bug更微妙。每轮Browy在<recent_actions>块中向模型展示自己最近五次工具调用，包括参数、是否成功、耗时和结果开头，让模型判断上一次点击是否生效。这个列表存在宿主的Agent对象上，而一个Agent服务所有聊天。于是新聊天的第一条消息带着上一个聊天的最后五次调用。作者在十月十三日拍演示视频时发现了它：在新聊天中让Browy填刚在另一聊天填过的同一张表单，它回复表单已填好，却一次工具都没调用。模型不是在编造，它在阅读：上下文显示fill_form刚刚返回ok，它有充分理由认为那是自己的聊天。修复按聊天为列表建立键值，并新增测试确保新聊天不会以他人工具调用开场。

那次拍摄还产出了首页的65秒演示视频：一句话输入侧边栏，一个标签页开着论文，另一个标签页是26个字段的投稿表单，结束时所有字段填好，提交按钮仍在等待作者。

关键要点

• Browy通过chrome.debugger和原生消息在用户自己的浏览器中工作，保留登录状态，以本地Node宿主协调Copilot CLI完成模型调用。
• 用编号索引快照替代CSS选择器，结合点击前后状态对比，显著提升Agent操作网页的可靠性。
• 安全模型假设页面可能包含针对模型的恶意文本，敏感工具（如本机脚本执行）默认关闭。
• 开发中的真实教训：字段名错误的系统提示五个月未生效、跨聊天工具调用历史泄漏、会话识别规则过窄导致聊天“丢失”，均以简单修复和测试收尾。
• 架构取舍清晰：牺牲规模换取登录态与本地数据控制，仅支持Chromium，安装分两步且体积较大。