架构：Browy Chromium 扩展（前端）

Browy 扩展是一个基于 Chromium 的 MV3 扩展，承载三个 UI 表面（侧边栏、 DevTools 面板、选项页），通过一个原生消息 port 和原生主机对话。

文件布局

extension/
├── manifest.json           ← MV3 清单：权限、后台 SW
├── background.js           ← service worker，port 的拥有者、CDP 桥
├── sidepanel.html / .js    ← 对话 UI（默认表面）
├── marked.min.js           ← 侧边栏的 Markdown 渲染器
├── devtools.html / .js     ← 注册 DevTools 面板
├── panel.html / .js / .css ← DevTools CLI 真正的表面
├── options.html / .js      ← 设置（模型、工具、安装帮助）
└── icons/                  ← 工具栏 + 商店素材

Port

一个 chrome.runtime.connectNative('com.browy.host') 的 port 跑在 service worker 上。这是连接主机的唯一通道。每个 UI 表面各自用 chrome.runtime.connect 向 service worker 开一个 port（sidepanel-<random>、devtools-panel-<random> 或 options）。service worker 把它们的消息转发给主机，再按 sessionId 把每条回复送回拥有这个会话的表面。不带 session id 的主机消息，比如 models.current 和 auth.status，会发给所有表面。

UI 表面

侧边栏：`sidepanel.html`

默认的对话 UI：带工具步骤的流式回复、从主机加载对话记录的历史对话浮层、Markdown 导出，以及一个打开选项页的设置按钮。大多数用户都待在这里。

DevTools 面板：`panel.html`

终端风格的 REPL。由 devtools.js 通过 chrome.devtools.panels.create('Browy', …) 注册。它和侧边栏共用同一个智能体后端，并且和被检查的目标绑定。参见 DevTools CLI 页面。

选项：`options.html`

模型选择器、工具开关、登录状态、当主机不可达时的安装帮助。通过 Chrome 标准的扩展选项入口或 Browy 工具栏菜单打开。

工具执行

工具在主机里运行。工具需要操作页面时，主机发一条 cdp.send 消息，SW 会：

选定标签页：如果主机在消息里固定了 tabId 就用它，否则用绑定到这个会话的标签页（DevTools 面板正在检查的那个），再否则用侧边栏所在窗口里的活动标签页（侧边栏在 session.start 里以 windowId 告知）；只有面板没有告知窗口时，才用最近聚焦窗口里的活动标签页。
如果还没附加，就调用 chrome.debugger.attach({tabId}, '1.3')。
用 chrome.debugger.sendCommand 执行命令（inspect_page 快照用的是 Runtime.evaluate，click_index 用的是 Input.dispatchMouseEvent，还有 Network.enable 等），把结果的整理交给主机。
通过 port 回发 {type: 'tool.result', sessionId, callId, ok, result}。

tab.new、tab.activate、tab.close、tab.list 和 tab.getActive 同样通过 chrome.tabs 处理；已附加标签页上的事件会以 cdp.event 的形式流回主机。

那个 Chrome 的*“Browy started debugging…”*黄色横幅，是 Chrome 对任何使用 DevTools Protocol 的扩展的强制披露。我们不去试图隐藏它。参见权限 → debugger。

存储

扩展自己的状态存在 chrome.storage.local：

当前对话：侧边栏是 browy.sessionId，每个被检查标签页的 DevTools 面板是 browy.dt.sessionId.<tabId>。这个 id 也是这段对话的 Copilot 会话 id。
对话显示缓存：browy.chat.<id>（渲染好的 HTML）、browy.chatMeta.<id> → {id, title, updated, preview} 和 browy.chatIndex（id 列表，最新的在前）
设置：settings.tools（按工具的开关）
界面标记：browy.firstSendDone（你发出第一条消息后隐藏入门提示）和 browy.hostUpdateSnoozeUntil（暂时隐藏后端更新提示条）

对话记录本身存在 Copilot CLI 的会话存储里（~/.copilot/ 下），你选的模型由主机保存在 ~/.browy/data/prefs.json。chrome.storage.local 存在当前这个浏览器配置里，扩展被移除时会一起清掉。

Content scripts

清单里没有声明任何 content script。需要在页面里运行的代码，比如 inspect_page 快照、evaluate_js 和 query_dom，都是主机通过 CDP 的 Runtime.evaluate 送到标签页里执行的。快照脚本会遍历开放的 shadow root 和同源 iframe，并给每个可交互元素打上 data-browy-id，让 *_index 工具之后还能找到它。

构建

扩展不需要打包步骤，原样发布。extension/ 就是一个普通的 Chromium 扩展目录。安装脚本把它复制到下载目录里的 Browy-Extension，方便你用 chrome://extensions → 加载已解压的扩展程序 侧载。npm run pack:extension 会把同一个目录打成 zip 交给 Chrome Web Store，商店里的这一个页面同时覆盖 Chrome、Edge 和 Brave。

另见

架构：原生主机（后端）主机进程、工具分发、SDK 循环。

架构：DevTools CLI DevTools 面板 REPL 的内部实现。

权限说明清单里的每一个权限为什么必要。