oh-my-pi Browser Relay 实战让 omp 通过 Chrome 扩展驱动你现有的浏览器标签页【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本文聚焦 oh-my-piomp项目中的oh-my-pi/browser-relay组件讲解它如何通过一个 Chrome MV3 扩展与本地 CDP Relay 服务让 Eval 的browserAPI 直接驱动你现有的Chrome 标签页包括已登录会话而无需重启浏览器或手动暴露调试端口。读完本文你将掌握 browser relay 的架构原理、安装步骤、两种 opt-in 配置方式app.relay与browser.relay、omp browser-relay的常用参数以及它的安全边界与开发验证方法。为什么需要 Browser RelayChrome 136 之后的新约束传统上让自动化工具驱动 Chrome 的做法是携带--remote-debugging-port重启浏览器。但根据 browser-relay 包 README 的说明Chrome 136 会拒绝在默认 profile 上使用该启动参数这使得复用已登录、已配置好的日常浏览器这条路基本被堵死。oh-my-pi/browser-relay的解法是绕开启动参数改用 Chrome 官方支持的扩展机制浏览器侧一个Chrome MV3 扩展通过chrome.debuggerAPI 附加到标签页并收发 CDP 命令进程侧一个随 omp CLI 分发的relay 服务器omp browser-relay源码位于 packages/coding-agent/src/tools/browser/relay/对外伪装成 Chrome 的 CDP discovery endpoint供 omp 的 browser 工具基于 puppeteer以普通browserURL方式连接。这套组合的首次发布记录在 CHANGELOG.md 的17.2.52026-08-03条目中MV3 扩展使 omp browser tool 能够通过chrome.debugger附加并驱动现有浏览器标签页同时引入了自动、健壮的标签页管理能力——将 agent 正在驱动的标签页归入每个窗口专属的 omp 标签组并在断开连接时干净地解散该分组。整体架构扩展、中继服务与多路复用relay 架构由三个角色组成它们的分工在 server.ts 的模块注释中定义得非常清晰端点角色GET /json/version伪装 Chrome 的 CDP discovery 握手扩展连接完成后返回 200 及webSocketDebuggerUrl尚未连接时返回 503客户端如waitForCdp会持续轮询GET /json、GET /json/list可附加的页面目标列表调试辅助WS /cdp下游 CDP 客户端puppeteer接入点WS /extChrome 扩展接入点配置 token 时做门控关键难点在于Chrome 每个标签页只允许一个chrome.debugger附加而 omp 的 browser 工具会为每个被驱动的标签页建立两条 puppeteer 连接一条 supervisor、一条 tab worker。relay 的 bridge 在 bridge.ts 中解决了这一冲突它通过扩展在每个标签页上只维护一个chrome.debugger附加再用派发的会话 ID 把所有下游连接复用到这条通道上。同时chrome.debugger本身不暴露浏览器级 target 和Target.*层级bridge 负责合成这部分表面参考了 puppeteer-core 的cdp/ExtensionTransport.ts。从源码结构看扩展与 relay 之间的线协议定义在 protocol.ts扩展主动拨号到ws://127.0.0.1:port/ext交换 JSON 消息。relay 通过带编号的 RPC 驱动扩展扩展则把标签页生命周期事件与chrome.debugger事件实时推送回去。安装一条命令 开发者模式加载扩展的安装分两步均在 README.md 中有明确说明运行omp browser-relay install该命令会把打包好的扩展写入~/.omp/browser-relay/extension打开chrome://extensions开启Developer mode点击Load unpacked选择上述目录加载。也可以直接从发布资产中获取omp-browser-relay-extension.zip解压加载。扩展的清单文件位于 extension/manifest.json声明了debugger、tabs、tabGroups、storage、alarms五个权限并提供了独立设置页options.html点击工具栏图标即可打开设置。两种 Opt-in 方式单次调用与全局默认18.0.72026-08-26这一版的 CHANGELOG 专门澄清了两个 opt-in 路径的范围差异这是配置 relay 最容易混淆的地方方式一按调用启用per-call在 Eval 的browser.open(...)中传入app: { relay: true }。这种方式只对这一次调用生效不持久化任何状态其他调用和会话的默认行为保持不变。适合偶尔需要操作真实浏览器、不想改变全局行为的场景。方式二设为默认as the default运行omp config set browser.relay truerelay 会成为该 profile 下所有会话、所有项目的默认驱动方式。需要特别注意的是优先级关系项目级设置、环境变量PI_BROWSER_RELAY、以及显式的app选择方式一仍然优先于这个默认值。一旦启用任何会话里普通的browser.open(...)调用都会驱动你的真实浏览器——包括你没有正在观看的后台会话。这里有一个值得留意的副作用README 原话如果不带app.target这样的调用会采纳当前可见的标签页而如果调用携带了url它会把这个标签页导航离开你正在阅读的内容。因此在开启默认模式前请确认这对你的日常浏览体验是可接受的。目标选择与 omp 标签组选择哪个标签页通过app.target按 URL/title 的子串匹配来指定具体标签页不提供时omp 采纳当前可见的标签页且不抢焦点。对应到 relay 协议层扩展在 background.ts 中通过activateTabRPC 实现焦点与激活切换。标签页分组管理这正是 CHANGELOG 17.2.5 提到的自动、健壮的标签页管理。omp正在主动驱动的标签页会被收集进每个窗口的omp 标签组青色当 omp 释放该标签页时分组被解除断开连接时分组合部解散。其余标签页、固定标签页pinned、你自己创建的组、以及你手动拖出的标签页都不会被触碰。可以在omp browser-relay时加--no-group禁用该行为。分组逻辑的健壮性在源码里有充分体现扩展端把查询→分组→设标题这一非原子序列串行化enqueueGroupOp见 background.ts避免并发竞态产生重复的 omp 组并会愈合历史竞态留下的同标题重复组固定标签页永远不会被分组Chrome 分组会静默取消固定relay 端通过groupOptOut机制尊重用户意愿如果你手动把标签页拖出 omp 组relay不会再把它组回去也不会与用户对抗见 bridge.ts 的#onTabUpsert逻辑。自动启动全局 daemon broker 与租约机制你不需要手动运行 relay——当 Eval 的 browser API 第一次需要它时relay 会在 omp 的profile 无关的全局 daemon broker下自动启动。实现细节在 daemon.ts由于 MV3 扩展只能向外拨号service worker 无法监听 socket必须有一个原生进程持有 relay 端口这个进程就由 broker 拉起每个 relay consumer 都持有 broker 租约lease因此一个项目退出不会中断另一个项目只有当所有项目的最后一个 consumer 退出后服务才会停止如果某个 relay 已经手动占用了端口consumer 会采纳现成的服务而不会争夺绑定启动是幂等且可自愈的先探测http://cdpUrl/json/version若返回 503等待扩展或 2xx 即视为就绪发现记录在案但无响应的僵死 daemon 会替换重启跨进程启动竞争则通过最多 3 轮探测→描述→启动收敛。扩展连接后工具栏 badge 会显示on对应源码中 background.ts 的setBadge绿色 on / 灰色 off。omp browser-relay命令行参数该命令在 cli-reference.md 中登记为运行 Eval 的 browser API 用来驱动你自己的 Chrome 标签页的本地 CDP relay。日常使用中你通常不需要手动运行它只在以下三种情况才需要参数作用--token secret为/ext端点设置共享密钥扩展在设置页中填入相同 token 后以?token形式携带用于防止本机不可信进程驱动你的已登录浏览器--no-group禁用 omp 标签组分组行为--port port指定非默认端口扩展默认连接 9224见 background.tsrelay 服务器只绑定loopback127.0.0.1并在握手层做了两道防线见 server.ts/cdp拒绝带Origin头的升级请求防止网页驱动 relay/ext只接受chrome-extension://来源并校验 token。扩展内部实现一个哑管道式的 MV3 Service Worker扩展的设计哲学在 background.ts 的注释里写得很直白按设计保持哑管道dumb pipe所有 CDP 编排逻辑都放在 relay 服务器侧。service worker 只做三件事保持一条到 relay 的 WebSocket执行 relay 下发的 RPCattach、detach、send、createTab、removeTab、activateTab、group、ungroup对应 protocol.ts把chrome.debugger事件和标签页增删改事件流式推回。针对 MV3 service worker 的生命周期问题扩展做了三重保活与恢复设计连接期间打开状态的 WebSocket 本身 每 20 秒一次的pingChrome 116 支持断开被回收后chrome.alarms每 0.5 分钟触发一次connect()重新拨号background.ts重连采用指数退避1 秒起步、上限 10 秒并对 relay 主动发起的 detach 与用户取消如关闭调试 infobar做了区分避免把替换 socket 误判为用户操作分组标题写入chrome.storage.session即使 service worker 重启后仍能正确解散 omp 组监听chrome.storage.local变化设置页修改端口/token 后立即断开并用新参数重拨。每次连接时扩展通过hello消息上报浏览器版本、全量标签页快照和当前已附加的标签页 IDrelay 据此做状态对账并在 service worker 重启丢失附加后尽力恢复持有会话的标签页附加见 bridge.ts。协议与多路复用细节对下游 puppeteer 客户端而言bridge 模拟了这些行为详见 bridge.tsBrowser.getVersion、Target.getBrowserContexts等浏览器级命令由 bridge 直接应答Target.setDiscoverTargets/Target.setAutoAttach/Target.attachToTarget/Target.createTarget/Target.closeTarget/Target.activateTarget等被转译为对扩展的 RPCBrowser.close会被拒绝并忽略——relay 绝不关闭用户的真实浏览器会话 ID 有明确命名空间STtab.conn.n为 minted tab 伪会话仅用于满足 Target 层级、SPtab.conn.n为 minted page 伪会话转发到标签页根 debugger 会话、OOPIF/worker 等真实子会话则原样透传Runtime 域做了状态机管理default/enabled/disabled保证多个下游连接共享一个根Runtime.enable循环并对新启用者重放已存在的 execution context。限制与安全边界以下是官方 README 明确列出的限制使用前务必知晓chrome://、DevTools、Web Store 以及其他扩展页面不可附加对 agent 完全隐藏对应 bridge.ts 中的不合法 URL 正则只要有任何标签页被附加Chrome 就会显示 is debugging this browser 的提示条关闭该提示条会分离标签页直到该标签页再次导航才会恢复打开了 DevTools 的标签页无法附加每个标签页只允许一个 debugger这正是 relay 要为自身客户端做多路复用的原因安全上任何能访问 relay 端口的东西都能驱动你的已登录浏览器因此 relay 只绑定 loopback若本机存在不可信进程请务必使用--token。开发与验证构建与端到端冒烟对于想参与开发或自行验证的读者package.json 与 README 的 Development 一节给出了两条命令bun run build将扩展打包到dist/extension/压缩出用于发布的 zip并重新生成 omp CLI 内嵌的安装资产位于 packages/coding-agent/src/tools/browser/relay/extension-assets/这些资产需要提交bun scripts/smoke.ts [relay-url] [target-substring]端到端冒烟测试完整复刻 omp 的 supervisor tab worker 双连接模式先通过browserURL建立 supervisor 连接并发现目标再通过browserWSEndpoint建立 worker 连接按 ID 采纳目标随后依次执行evaluate、Page.getFrameTree额外 CDP 会话、goto导航、screenshot截图以及Target.createTarget/closeTarget新建与关闭标签页的路径最后断开两条连接并打印SMOKE OK。结合 CHANGELOG.md 的演进记录可以看到browser relay 从 17.2.5 的首版 MV3 扩展 omp 标签组管理到 18.0.7 的opt-in 路径范围澄清其核心价值始终稳定让 coding agent 安全、可配置地接管你日常使用的真实浏览器而不是在隔离环境里另起炉灶。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 oh-my-pi Browser Relay 实战：让 omp 通过 Chrome 扩展驱动你现有的浏览器标签页
oh-my-pi Browser Relay 实战让 omp 通过 Chrome 扩展驱动你现有的浏览器标签页【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi本文聚焦 oh-my-piomp项目中的oh-my-pi/browser-relay组件讲解它如何通过一个 Chrome MV3 扩展与本地 CDP Relay 服务让 Eval 的browserAPI 直接驱动你现有的Chrome 标签页包括已登录会话而无需重启浏览器或手动暴露调试端口。读完本文你将掌握 browser relay 的架构原理、安装步骤、两种 opt-in 配置方式app.relay与browser.relay、omp browser-relay的常用参数以及它的安全边界与开发验证方法。为什么需要 Browser RelayChrome 136 之后的新约束传统上让自动化工具驱动 Chrome 的做法是携带--remote-debugging-port重启浏览器。但根据 browser-relay 包 README 的说明Chrome 136 会拒绝在默认 profile 上使用该启动参数这使得复用已登录、已配置好的日常浏览器这条路基本被堵死。oh-my-pi/browser-relay的解法是绕开启动参数改用 Chrome 官方支持的扩展机制浏览器侧一个Chrome MV3 扩展通过chrome.debuggerAPI 附加到标签页并收发 CDP 命令进程侧一个随 omp CLI 分发的relay 服务器omp browser-relay源码位于 packages/coding-agent/src/tools/browser/relay/对外伪装成 Chrome 的 CDP discovery endpoint供 omp 的 browser 工具基于 puppeteer以普通browserURL方式连接。这套组合的首次发布记录在 CHANGELOG.md 的17.2.52026-08-03条目中MV3 扩展使 omp browser tool 能够通过chrome.debugger附加并驱动现有浏览器标签页同时引入了自动、健壮的标签页管理能力——将 agent 正在驱动的标签页归入每个窗口专属的 omp 标签组并在断开连接时干净地解散该分组。整体架构扩展、中继服务与多路复用relay 架构由三个角色组成它们的分工在 server.ts 的模块注释中定义得非常清晰端点角色GET /json/version伪装 Chrome 的 CDP discovery 握手扩展连接完成后返回 200 及webSocketDebuggerUrl尚未连接时返回 503客户端如waitForCdp会持续轮询GET /json、GET /json/list可附加的页面目标列表调试辅助WS /cdp下游 CDP 客户端puppeteer接入点WS /extChrome 扩展接入点配置 token 时做门控关键难点在于Chrome 每个标签页只允许一个chrome.debugger附加而 omp 的 browser 工具会为每个被驱动的标签页建立两条 puppeteer 连接一条 supervisor、一条 tab worker。relay 的 bridge 在 bridge.ts 中解决了这一冲突它通过扩展在每个标签页上只维护一个chrome.debugger附加再用派发的会话 ID 把所有下游连接复用到这条通道上。同时chrome.debugger本身不暴露浏览器级 target 和Target.*层级bridge 负责合成这部分表面参考了 puppeteer-core 的cdp/ExtensionTransport.ts。从源码结构看扩展与 relay 之间的线协议定义在 protocol.ts扩展主动拨号到ws://127.0.0.1:port/ext交换 JSON 消息。relay 通过带编号的 RPC 驱动扩展扩展则把标签页生命周期事件与chrome.debugger事件实时推送回去。安装一条命令 开发者模式加载扩展的安装分两步均在 README.md 中有明确说明运行omp browser-relay install该命令会把打包好的扩展写入~/.omp/browser-relay/extension打开chrome://extensions开启Developer mode点击Load unpacked选择上述目录加载。也可以直接从发布资产中获取omp-browser-relay-extension.zip解压加载。扩展的清单文件位于 extension/manifest.json声明了debugger、tabs、tabGroups、storage、alarms五个权限并提供了独立设置页options.html点击工具栏图标即可打开设置。两种 Opt-in 方式单次调用与全局默认18.0.72026-08-26这一版的 CHANGELOG 专门澄清了两个 opt-in 路径的范围差异这是配置 relay 最容易混淆的地方方式一按调用启用per-call在 Eval 的browser.open(...)中传入app: { relay: true }。这种方式只对这一次调用生效不持久化任何状态其他调用和会话的默认行为保持不变。适合偶尔需要操作真实浏览器、不想改变全局行为的场景。方式二设为默认as the default运行omp config set browser.relay truerelay 会成为该 profile 下所有会话、所有项目的默认驱动方式。需要特别注意的是优先级关系项目级设置、环境变量PI_BROWSER_RELAY、以及显式的app选择方式一仍然优先于这个默认值。一旦启用任何会话里普通的browser.open(...)调用都会驱动你的真实浏览器——包括你没有正在观看的后台会话。这里有一个值得留意的副作用README 原话如果不带app.target这样的调用会采纳当前可见的标签页而如果调用携带了url它会把这个标签页导航离开你正在阅读的内容。因此在开启默认模式前请确认这对你的日常浏览体验是可接受的。目标选择与 omp 标签组选择哪个标签页通过app.target按 URL/title 的子串匹配来指定具体标签页不提供时omp 采纳当前可见的标签页且不抢焦点。对应到 relay 协议层扩展在 background.ts 中通过activateTabRPC 实现焦点与激活切换。标签页分组管理这正是 CHANGELOG 17.2.5 提到的自动、健壮的标签页管理。omp正在主动驱动的标签页会被收集进每个窗口的omp 标签组青色当 omp 释放该标签页时分组被解除断开连接时分组合部解散。其余标签页、固定标签页pinned、你自己创建的组、以及你手动拖出的标签页都不会被触碰。可以在omp browser-relay时加--no-group禁用该行为。分组逻辑的健壮性在源码里有充分体现扩展端把查询→分组→设标题这一非原子序列串行化enqueueGroupOp见 background.ts避免并发竞态产生重复的 omp 组并会愈合历史竞态留下的同标题重复组固定标签页永远不会被分组Chrome 分组会静默取消固定relay 端通过groupOptOut机制尊重用户意愿如果你手动把标签页拖出 omp 组relay不会再把它组回去也不会与用户对抗见 bridge.ts 的#onTabUpsert逻辑。自动启动全局 daemon broker 与租约机制你不需要手动运行 relay——当 Eval 的 browser API 第一次需要它时relay 会在 omp 的profile 无关的全局 daemon broker下自动启动。实现细节在 daemon.ts由于 MV3 扩展只能向外拨号service worker 无法监听 socket必须有一个原生进程持有 relay 端口这个进程就由 broker 拉起每个 relay consumer 都持有 broker 租约lease因此一个项目退出不会中断另一个项目只有当所有项目的最后一个 consumer 退出后服务才会停止如果某个 relay 已经手动占用了端口consumer 会采纳现成的服务而不会争夺绑定启动是幂等且可自愈的先探测http://cdpUrl/json/version若返回 503等待扩展或 2xx 即视为就绪发现记录在案但无响应的僵死 daemon 会替换重启跨进程启动竞争则通过最多 3 轮探测→描述→启动收敛。扩展连接后工具栏 badge 会显示on对应源码中 background.ts 的setBadge绿色 on / 灰色 off。omp browser-relay命令行参数该命令在 cli-reference.md 中登记为运行 Eval 的 browser API 用来驱动你自己的 Chrome 标签页的本地 CDP relay。日常使用中你通常不需要手动运行它只在以下三种情况才需要参数作用--token secret为/ext端点设置共享密钥扩展在设置页中填入相同 token 后以?token形式携带用于防止本机不可信进程驱动你的已登录浏览器--no-group禁用 omp 标签组分组行为--port port指定非默认端口扩展默认连接 9224见 background.tsrelay 服务器只绑定loopback127.0.0.1并在握手层做了两道防线见 server.ts/cdp拒绝带Origin头的升级请求防止网页驱动 relay/ext只接受chrome-extension://来源并校验 token。扩展内部实现一个哑管道式的 MV3 Service Worker扩展的设计哲学在 background.ts 的注释里写得很直白按设计保持哑管道dumb pipe所有 CDP 编排逻辑都放在 relay 服务器侧。service worker 只做三件事保持一条到 relay 的 WebSocket执行 relay 下发的 RPCattach、detach、send、createTab、removeTab、activateTab、group、ungroup对应 protocol.ts把chrome.debugger事件和标签页增删改事件流式推回。针对 MV3 service worker 的生命周期问题扩展做了三重保活与恢复设计连接期间打开状态的 WebSocket 本身 每 20 秒一次的pingChrome 116 支持断开被回收后chrome.alarms每 0.5 分钟触发一次connect()重新拨号background.ts重连采用指数退避1 秒起步、上限 10 秒并对 relay 主动发起的 detach 与用户取消如关闭调试 infobar做了区分避免把替换 socket 误判为用户操作分组标题写入chrome.storage.session即使 service worker 重启后仍能正确解散 omp 组监听chrome.storage.local变化设置页修改端口/token 后立即断开并用新参数重拨。每次连接时扩展通过hello消息上报浏览器版本、全量标签页快照和当前已附加的标签页 IDrelay 据此做状态对账并在 service worker 重启丢失附加后尽力恢复持有会话的标签页附加见 bridge.ts。协议与多路复用细节对下游 puppeteer 客户端而言bridge 模拟了这些行为详见 bridge.tsBrowser.getVersion、Target.getBrowserContexts等浏览器级命令由 bridge 直接应答Target.setDiscoverTargets/Target.setAutoAttach/Target.attachToTarget/Target.createTarget/Target.closeTarget/Target.activateTarget等被转译为对扩展的 RPCBrowser.close会被拒绝并忽略——relay 绝不关闭用户的真实浏览器会话 ID 有明确命名空间STtab.conn.n为 minted tab 伪会话仅用于满足 Target 层级、SPtab.conn.n为 minted page 伪会话转发到标签页根 debugger 会话、OOPIF/worker 等真实子会话则原样透传Runtime 域做了状态机管理default/enabled/disabled保证多个下游连接共享一个根Runtime.enable循环并对新启用者重放已存在的 execution context。限制与安全边界以下是官方 README 明确列出的限制使用前务必知晓chrome://、DevTools、Web Store 以及其他扩展页面不可附加对 agent 完全隐藏对应 bridge.ts 中的不合法 URL 正则只要有任何标签页被附加Chrome 就会显示 is debugging this browser 的提示条关闭该提示条会分离标签页直到该标签页再次导航才会恢复打开了 DevTools 的标签页无法附加每个标签页只允许一个 debugger这正是 relay 要为自身客户端做多路复用的原因安全上任何能访问 relay 端口的东西都能驱动你的已登录浏览器因此 relay 只绑定 loopback若本机存在不可信进程请务必使用--token。开发与验证构建与端到端冒烟对于想参与开发或自行验证的读者package.json 与 README 的 Development 一节给出了两条命令bun run build将扩展打包到dist/extension/压缩出用于发布的 zip并重新生成 omp CLI 内嵌的安装资产位于 packages/coding-agent/src/tools/browser/relay/extension-assets/这些资产需要提交bun scripts/smoke.ts [relay-url] [target-substring]端到端冒烟测试完整复刻 omp 的 supervisor tab worker 双连接模式先通过browserURL建立 supervisor 连接并发现目标再通过browserWSEndpoint建立 worker 连接按 ID 采纳目标随后依次执行evaluate、Page.getFrameTree额外 CDP 会话、goto导航、screenshot截图以及Target.createTarget/closeTarget新建与关闭标签页的路径最后断开两条连接并打印SMOKE OK。结合 CHANGELOG.md 的演进记录可以看到browser relay 从 17.2.5 的首版 MV3 扩展 omp 标签组管理到 18.0.7 的opt-in 路径范围澄清其核心价值始终稳定让 coding agent 安全、可配置地接管你日常使用的真实浏览器而不是在隔离环境里另起炉灶。【免费下载链接】oh-my-pi⌥ Coding agent with the IDE wired in项目地址: https://gitcode.com/GitHub_Trending/oh/oh-my-pi创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考