OpenCode 在 11 月第一周放了一个叫 Browse 的东西,MIT 协议,一个 MCP server 加一个 Chromium 扩展。它的主张一句话能说完:不用无头浏览器,也不用云浏览器,用你正在登录的那一个。
我把仓库 clone 下来量了一遍,581 个文件、129,937 行。这次拆解里最值钱的东西不在代码里,在 changelog/ 那个目录里,而且最大的那份文件不是他们写的。
先给判断。Browse 真正解决的不是「让 agent 会点按钮」,无头 Playwright 早就会了。它解决的是会话归属:把「登录过」这件事当成一种资产复用,然后把不能自动化那几步明确地退还给人类。产品自己的版本史证明了这个取舍是试出来的,因为它试过反方向,八天就撤了。
它绕开的是哪两条路
浏览器 agent 这个位置上有两条成熟的走法。
一条是无头浏览器。Playwright 起一个干净实例,你给它脚本或者 cookie。麻烦在于会话不是你的,登录得自己想办法喂进去,cookie 抄来抄去还会过期。
另一条是云浏览器。会话跑在别人机器上,你远程看画面。它把「我的登录」变成了「某个托管环境里的登录」,隔离是干净的,代价是你得把账号交出去一遍。站内早前那篇《浏览器 Agent 三种形态对比》里已经把这三类的取舍摊开说过,这里不重讲形态,只拆 Browse 具体怎么实现的。
Browse 押的是第三条:扩展挂在你自己那个浏览器上,用你已经登录的会话干活。所以它的安装说明里有一句很直白的话,agent 用你已经登录的站点,不需要密钥,不需要配置。
这句话是卖点,也是它全部风险所在。你一旦承认 agent 可以用你的登录态,后面每个设计决定都要回答一个问题:它凭什么不能拿去干别的。
三段链路,和一次整体重写
先说它怎么连起来。这条链在官方文档和仓库里都能对出来:
agent 先起 browse mcp,这是一个 stdio 代理,按需拉起 relay,然后把每个调用转发给 relay 上的 127.0.0.1:19988。这个端口被别的程序占了就顺延到 19990 到 19997。扩展通过 WebSocket 连上 relay,再用 chrome.debugger 在你的浏览器里执行命令。
relay 是用 Rust 写的,在 rust/ 目录下,负责保存 agent 的标签页、交接状态、录屏和网络抓包,直接和每个标签页讲 Chrome DevTools Protocol,还会在一个内嵌的 QuickJS 引擎里跑 execute 脚本。没有东西用的时候它会自己退出。
这里有个我觉得挺少见的设计约束,写在仓库的 rust/PLAN.md 里,原话是重写必须讲扩展原有的协议,这样商店里的扩展不用换。也就是说他们把 CLI、relay、MCP server 三件东西合成一个几 MB 的原生二进制,但扩展那一侧的接口一个字都不能动。重写只换了后端,前端契约冻结。
六个 crate 的分工我按行数量了一下:
browse-relay9,528 行,relay 本体、配对、每个 tab 的 CDP 路由、交接、设置同步browse-page8,323 行,页面交互,隔离世界、快照、可交互性判断、拟人输入browse7,459 行,CLI 和安装器browse-capture6,214 行,截图、网络抓包、控制台、录屏browse-script1,933 行,QuickJS 里跑 executebrowse-core291 行,共享契约,PLAN.md 里专门写了「改动要小心,别的 crate 都依赖它」
12 天,14 个版本,先砍功能再重写
这个仓库的 changelog/ 目录是我这次拆解里最有收获的地方。十四个版本,从 11 月 3 日到 11 月 15 日,我把每个版本的一句话摘要连起来看了一遍:
- 0.0.4,11-03,扩展正式叫 Browse,安装收成一条命令
- 0.0.5,11-03,大页面快照变快,多 agent 并发时弹窗可靠
- 0.0.7,11-04,作为单一二进制安装;npm 包在 0.0.6 启动崩溃后恢复
- 0.0.8,11-04,引导页给安装选项
- 0.0.9,11-05,新的设置页和更清楚的 agent 选择器
- 0.0.10,11-05,扩展重连时机不对时不再丢 agent 会话
- 0.0.11,11-07,迁到标准 XDG 目录,给 agent 的工具集缩小
- 0.0.12,11-07,重跑安装可以给已装扩展但没配对的浏览器配对,含 SSH
- 0.0.13,11-07,agent 标签页默认进一个共享分组
- 0.0.14,11-07,改成从自建发布服务安装和更新
- 0.0.15,11-07,一批修复,Vivaldi、Dia、Windows 上更稳
- 0.0.16,11-08,自动更新能自己收尾,agent 不再互相抢标签页
- 0.0.17,11-14,browse 小了一大圈:secrets、飞行记录仪、幽灵光标、doctor 和 skill 全被删掉
- 0.1.0,11-15,重写成 Rust,一个二进制装 CLI、relay 和 MCP server
三处细节值得单独点出来。0.0.6 启动就崩,所以它没有 changelog 文件,只在 0.0.7 里被提了一句。11-08 之后有六天完全没有版本。然后是 11-14 的功能大砍,第二天紧接着整体重写。
十四个版本里我去掉两个没内容的日期,剩下十二天。一家公司用十二天把一个刚发布的产品砍掉五项功能再换掉实现语言,这件事本身就说明发布时的架构不是他们想要的终局。
0.1.0 那句摘要里还藏了一个我没预料到的改动:标签页成了句柄,会话没了。之前每个 agent 有自己的命名会话,现在 navigate 不带参数就开一个后台标签页并返回它的 id,之后每个调用都要指定这个 id。
安全模型,一条一条拆
这段是我花时间最多的地方,因为标题里那句「交回你手上」必须落到具体机制上才算数。
relay 的令牌。每个发给 relay 的请求都要带 ~/.local/share/browse/relay-token 里的令牌。我去读了生成它的源码,rust/crates/browse-relay/src/secrets.rs:令牌是 32 字节随机数的 base64url 编码,长度校验写死 43 个字符;文件用 0600 权限;创建走硬链接,两个进程同时创建时先到的那份赢。顺带一提,这个文件叫 secrets.rs 但它管的是 relay 令牌,不是站点密码,我一开始看名字也认错了。
配对。配对码只能用一次,十分钟内有效,连错五次会把所有待用的码一起作废。浏览器拿它换一把自己的随机密钥,用的是 ECDH 密钥协商,所以配对码和密钥都不经过连接本身。之后每次连接双方都要证明自己持有那把密钥。README 对这个设计的说明是一句很实在的话:先抢到端口的程序驱动不了你的浏览器。relay 只接受已发布的扩展 ID。
execute 的沙箱。这条是它自己把话说最明白的一处。脚本跑在 relay 内的 QuickJS 里,有 CPU、内存和时间上限,没有 Node,没有网络,文件访问限于白名单目录。README 的措辞是沙箱化但不是边界,紧接着一句是让 agent 跑的代码就等于你本人跑的代码。relay 启动时用的是白名单环境变量,所以你的 API key 不在里面。这三句话放在一起读,能看出他们不打算让你误以为 execute 是一道墙。
CDP 护栏。清 cookie、清缓存、清站点数据、关浏览器、改站点权限,这几类操作一律拒绝。关页面按关目标处理,意味着你借出去的那个标签页是被释放而不是被关掉。cookie 和 storage 的读写限于该标签页自己页面的 host。agent 开不了浏览器内部页面、别的扩展和本地文件,也不能把窗口弹到你正在看的上面。
站点白名单。开标签页时可以带 allowedOrigins,这个标签页就只能去这几个站点;带 readOnly 的标签页只能看不能动。两条都是可选的,默认不开。
机器人验证。遇到 Cloudflare、验证码墙、拒绝访问页面,Browse 会把这些如实报告给 agent,让它把需要真人交互的交给用户,原文写的是它自己从不尝试解决。这一条跟后面要说的隐身设计放在一起看会很有意思。
交接不可伪造。关闭交接状态只认两种输入:点击卡片,或者点工具栏按钮。README 特意补了一句,页面伪造不了。这是整套交接设计的承重点,如果页面能用脚本触发那句「继续」,交回你手上就成了摆设。
反检测是明写的设计目标
这一节我单独拎出来,因为它在同类产品里很少见:他们把「让 agent 不被站点发现」当成了要花工程量去做的事,而且写明了出处。
rust/PLAN.md 里给这条决策起的小标题就叫隐身,做法照抄 Patchright:默认不调用 Runtime.enable 和 Console.enable,browse 自己的代码跑在 Page.createIsolatedWorld 建出来的隔离世界里,页面里不留全局变量、绑定和 sourceURL 标记。README 那边补的是输入行为:鼠标走曲线路径,打字有节奏,滚动是滑行。文档也给了边界,说这能让 agent 难以被发现但不是不可能,调试器挂上时浏览器会显示那条正在调试的提示条。
仓库里最大的那个文件正好能印证这条路线。8,457 行的 rust/crates/browse-page/js/injected-script.js,文件头写明它是从 patchright-core 1.63.0 里取来的 Playwright InjectedScript,由脚本生成,标着不要手工编辑,署名是微软和 Patchright 的贡献者,Apache-2.0。也就是说这个仓库里最大的一份代码是借来的,借的对象是一个专门做反检测的 Playwright 分叉。
我不想在这上面下定论说这是好事还是坏事,因为它两边都成立:对合法的数据抓取和自动化,少留指纹是功能;对站点一侧的反爬,它是需要被识别的新变量。但有一点是确定的,这是设计目标,不是副作用,因为它有一个专门的决策条目和一份借来的实现。
上线八天就被删掉的那个功能
这是这次拆解里我认为最值得写的一条,也是网上能找到的中文资料基本都没提的。
0.0.17 的 changelog 原文第二行写着:移除了 secrets 功能,包括存储的站点密钥、secrets.type() 和 secrets_* 工具,更新时会删掉遗留的密钥文件。
仓库里还留着删它的代码,cli/src/setup/remove-stored-secrets.ts,注释说这些是被移除功能的凭据目录,要删干净免得有值留在磁盘上,删的是 site-secrets 和 secrets 两个目录,而且做成了幂等、永不抛错,理由是启动不能被一个删不掉的文件夹挡住。
那被删的功能原来长什么样,看旧版 README 能还原:有一条 browse secrets add <name> --origin https://example.com 命令,从标准输入或隐藏提示里读一个密码、密钥或者带 --totp 的 TOTP 种子,存到 ~/.local/share/browse/site-secrets/,权限 0700 和 0600。agent 用 secrets.type(locator, "<name>") 把它打进表单里,relay 在真正插值之前,拿浏览器帧树里那个字段的 frame URL 去比对密钥的 origin 和会话白名单,所以跨域 iframe 或者一次重定向什么也拿不到。
而旧版 README 自己在这段末尾留了一句警告,我原样引一下:存下来的 TOTP 种子会把双因素变成单因素,能自己交回 2FA 的时候还是自己交。
现在把这几件事连起来看。产品发布时给了一条把 2FA 自动化的路,代价是把 TOTP 种子落在磁盘上。八天后它们把这条路删了,理由写在 changelog 里,只用了「移除了 secrets 功能」这几个字,没有解释。留下的那条路就是交接,也就是你标题里写的那句。
我的读法是,这已经超出一次功能取舍,接近路线的自我否决。存种子能让流程完全无人化,交接做不到,但交接不需要你交出任何东西。产品选了后者,而且把删文件的清理代码也一起发布了。
顺带一个实用结论:网上流传的那些镜像 README 大多停留在 0.1.0 之前。你在搜索里能看到的 secrets_*、flight_recorder_*、session_* 这一整套工具表,现在已经不存在了,session 概念被标签页取代。照那份旧文档去配,第一步就会对不上。
上手:装、限、交回
装的部分官方给了三条等效路径,我按 README 抄下来。最简单的是先装 Chrome 扩展,它会带你走完剩下的步骤;不想用扩展引导的直接跑 curl -fsSL https://opencode.ai/browse/install | bash,或者 npx @opencode/browse install。安装脚本会从发布服务读频道的清单,下载对应二进制,装上之前校验大小和 SHA-256。npm 那条路会把版本对着 npm 公布的 SHA-512 完整性校验。
browse install 会做三件事:把 browse 放到位并把 ~/.local/bin 加进 PATH、给 agent 写 MCP 配置、把扩展连上。第二步会弹一个可选列表,这台机器上找到的 agent 默认勾上,上次的选择会被记住,编辑配置时会保留原来的注释和格式,JSON、TOML、YAML 都保留。
配好之后,推荐这样跑第一次:
browse navigate https://news.ycombinator.com
browse snapshot --tab <上面返回的 id>
navigate 不带 tab 会开一个后台标签页并把 id 打出来,之后所有命令都带这个 id。想先把范围收死,开标签页时带上 allowedOrigins,或者干脆开一个只读的。
遇到登录、2FA 或付款,页面上会出现一张小卡片,上面标着站点来源。你把人的那一步做完,然后点卡片上的继续,或者点工具栏按钮。工具栏图标会显示状态,agent 干活时是 RUN,等你的时候是 WAIT。
上手里最容易卡住的三处,都是我自己读文档和仓库时标出来的。装完 agent 说找不到 browse 的工具,要重启 agent 或者重新加载它的 MCP 服务,这是 MCP 配置只在新进程里生效。端口 19988 被别的程序占了,Browse 会顺延到 19990 到 19997,如果占端口的那个程序不响应 HTTP 就会卡住,这时候停掉那个程序或者用环境变量指定端口。relay 重启后扩展大约半分钟内会自己连回来,在这期间发出的调用会等它,所以看到短暂无响应先等一下再判断。
两类客户端拿到的东西不一样
这个设计我一开始没注意到,翻仓库的规划文档才看明白。OpenCode 用户拿到的是一组平铺的工具,navigate、snapshot、click、fill、screenshot、network、recording 这些都在里面,原因是 OpenCode 有代码模式,它能自己把工具编排成一段代码去跑。其他 MCP 客户端只拿到三个:execute、status 和 tabs,条件逻辑全塞在 execute 里跑 JavaScript,配一套 Playwright 风格的 page、snapshot() 和 handoff()。
relay 靠客户端名字来分,MCP 代理会把客户端名放在请求头里转发过去,也可以用环境变量强制统一。平铺那侧我数了有二十多个工具,execute 那侧只有三个,但后者的能力不比前者少。
这件事值得单独记一句,因为它说明工具数量不是成熟度的指标。同一个后端对不同宿主给出不同粒度,省的是 agent 的上下文和调用轮次。
怎么确认它真的按你说的在干活
交接设计最怕的是你不知道它此刻在干什么,所以诊断信号得先备好。
工具栏图标是第一个,ON 表示这个标签页交给了 agent,RUN 表示它正在干活,WAIT 表示它需要你。第二个是 browse status,它会把安装情况、配置写进了哪些 agent、更新状态、relay、扩展和 agent 标签页逐项列出来,扩展缺失、没配对、被关掉或者版本旧了,它会直接说你该做哪一步。第三个是 relay 日志,位置在 ~/.local/state/browse/logs/relay.log。
想事后回看有四条路。network 抓一个标签页的流量并做凭据脱敏,console 抓它的控制台消息和错误,recording 把一个标签页录成视频,screenshot_diff 能拿当前页面跟基线比。更省事的做法是在交接前后各跑一次 snapshot,对比两份大纲就能看出页面有没有被推进。
比上一个版本,你手上少了什么
0.0.17 一共删了五样,除了那套存密钥的功能,还有飞行记录仪、幽灵光标、doctor 和 skill。
飞行记录仪是常驻保存最近一分钟的录像、出事时再落盘的那种机制。幽灵光标是跟着操作走的指针提示和它的设置项。doctor 的检查项现在并进了 status。skill 变成 browse --help 里一段简短的 agent 指南。第二天 0.1.0 又把会话换掉,标签页成为唯一的句柄。
实际影响集中在多任务的组织方式上。以前你能给每个任务起一个命名会话,现在要改成按标签页和分组来管。好消息是标签页的选项(分组名、允许站点、只读、可见)会持久化,relay 重启之后还会回来。两次改动的方向是一致:把状态收敛到更少的地方,能删的都删掉。
它不适合谁
有三类场景我不建议用它。
要在构建流水线里跑无人的浏览器任务,这台机器上既没有你的登录态,也没有你坐在旁边点继续,交接这套机制等于空转,无头 Playwright 更合适。多人共用一台机器,或者要把浏览器借给不受信任的 agent,风险也大,因为它是绑在你的会话上的,权限边界就等于你的账号边界。再有就是站点明确禁止自动抓取的场景,隐身设计让它更难被发现,但难被发现是技术事实,该不该做是另一回事,这两件事别混在一起想。
局限,和它自己承认的部分
第一条是 execute 不是安全边界,这句话我直接引自 README。他们同时点明让 agent 跑的代码就等于你跑的代码。要真正隔离 agent 的执行,靠的不能是这一层。
第二条,远程模式不加密。agent 和浏览器在不同机器上时,Browse 自己不做传输加密,README 让你走 Tailscale 或 WireGuard 这类加密网络,并且明确说不要暴露在公网上。也就是说这个功能默认只在可信网络里成立。
第三条,隐身不等于不可见。调试器挂着的时候浏览器会显示提示条,这是站点一侧仍然可用的信号。
第四条,扩展声明了全站访问权限,还带 debugger、tabs、tabGroups、scripting、webNavigation、notifications 这一组。它同时提供了一组环境变量作为逃生通道,其中 OPENCODE_BROWSER_ALLOW_ALL_COOKIES=1 会让标签页读写整个 profile 的每一个 cookie,OPENCODE_BROWSER_ALLOW_ALL_STORAGE=1 会放开每个站点的存储。这些是给卡住的人准备的,代价是把前面那些护栏让掉。
第五条偏组织层面。README 里写着他们不收 pull request,只收 issue,然后由他们的 agent 来处理。MIT 协议允许你 fork,但主线的演进完全在一家公司手里,而且从版本史看,一次重写能在两天内落地。
判断
回到标题那句话。让 agent 用你真实浏览器里的登录态,这件事的价值和风险是同一件事:复用了会话,就等于复用了那个会话能做的所有事。站点白名单只能限制它去哪,限制不了它到了之后能干什么,这一点在官方文档里也留着。
所以「登录、2FA、付款交回你手上」不是这个产品的一个附加功能,它是让前面那句卖点能够成立的那一半。而八天前删掉 secrets 那个动作,等于他们自己把这个判断钉死了:能自动化的地方自动化,不能交出去的地方一步不让。
对同类产品来说,这条路线给了一个可抄的取舍模板,代价是抄不了那份捷径。你已经看到的、把 2FA 也自动化的那种做法,他们试过,撤了,还把清理代码留在了仓库里。
相关阅读
Browse 是 OpenCode 家族里独立的一个仓库,跟本体架构关系不大。想补本体的设计,看《OpenCode 架构拆解》;这个家族里已经写过安装、对比和排错三篇,那些讲的是方案与形态,本篇拆的是一个具体产品的源码、版本史和它对自身安全模型的措辞。
另一条让 agent 驱动真实应用的路是绕开浏览器直读无障碍树,不走截图也不走 CDP,可以对照《agent-desktop 拆解》看两种思路的分界。