内容
# <img src="extension/icons/icon128.png" width="32" alt="" align="top"> 铬桥
[俄语版本](README.ru.md)
您基于Chromium的浏览器与Claude Code之间的桥梁。官方的“Chrome中的Claude”扩展程序在某些Chromium浏览器（Arc，Vivaldi等）中连接，但自动化功能却卡住了：其工具是基于标签组API构建的，而该API在这些浏览器中缺失或损坏。此桥梁仅使用普通的`chrome.tabs` / `chrome.scripting` / `chrome.debugger`，因此它可以在任何可以加载扩展程序的Chromium浏览器中运行。
## 演示
Claude通过桥梁驱动浏览器 - 打开维基百科，输入搜索并跳转到文章：
## 架构
```
Claude Code ⇄ (stdio MCP) ⇄ server/index.mjs ⇄ (WebSocket, 127.0.0.1:8929) ⇄ 浏览器中的扩展程序
⇅ (WebSocket /聊天)
聊天面板（扩展程序图标的弹出窗口）
```
- `extension/` - 一个MV3扩展程序：服务工作线程保持与本地服务器的WebSocket连接，并执行其命令（标签、导航、页面文本、截图、点击、表单填写）。点击图标会打开聊天面板（`chat.html`）- 一个锚定在扩展程序图标上的弹出窗口。
- `server/` - 一个MCP服务器（stdio），它向Claude Code公开`browser_*`工具，并将它们代理到扩展程序。它仅接受来自`chrome-extension://…`来源的WS连接 - 普通网页无法连接。它还提供`/chat`通道：面板消息通过Claude代理SDK（通过Claude Code登录进行身份验证）与相同的`browser_*`工具运行；内置工具（Bash，Read等）被禁用。
## 聊天面板
“Chrome中的Claude”侧面板的等效功能：一个弹出窗口，当您点击扩展程序图标时打开（无`chrome.sidePanel` - 它并非在所有地方都受支持）。聊天可以查看浏览器：列出标签、读取页面、截图和点击。
面板UI默认为英语，当浏览器UI语言为俄语时自动切换为俄语。底部栏中的语言选择器（自动/英语/俄语）覆盖自动检测；页面徽章遵循相同的选择。
- 弹出窗口在失去焦点时关闭（点击页面）- 这是浏览器行为。对话上下文不会丢失：面板记住`session_id`，服务器通过代理SDK的`resume`恢复对话。在弹出窗口关闭时正在进行的回合将被中断。
- 它仅在服务器运行时才有效（通常是带有`chromium-bridge` MCP的活动Claude Code会话）；否则，面板显示“服务器不可用”。
- 面板标题中的模型选择器：“默认”从`~/.claude/settings.json`获取模型（通过`/model`设置的任何内容；SDK会话本身不读取Claude Code设置，服务器明确传递模型），其他条目是硬覆盖。切换立即应用（`setModel`）并被记住。启动覆盖：服务器环境中的`CHROMIUM_BRIDGE_CHAT_MODEL=sonnet`。端口：`CHROMIUM_BRIDGE_PORT`（默认为8929）- 仅服务器端；扩展程序始终连接到8929，因此更改端口也意味着编辑`extension/sw.js`和`extension/chat.js`中的`WS_URL`。
- 聊天历史记录：标题中的 🕓 按钮列出过去的对话（存储在面板的localStorage中，最后30个）。
- 每次对话后，都会显示一行使用情况：对话令牌（↑输入包括缓存/↓输出）和累计会话成本（美元，在订阅上这是估计值，而不是单独的账单）。
- 代理在聊天过程中拍摄的截图直接在聊天馈送中显示（单击展开）。它们不会保存到历史记录中（localStorage是有限的）。
- 您可以从剪贴板粘贴图像（在输入框中按Cmd+V，最多每个消息5个）- 模型可以看到它们；历史记录中只留下一个标记。
- “在采取行动前询问”模式（输入框上方的复选框）：读取（标签、文本、截图、控制台、网络）无需询问即可进行，而修改操作 - 点击/输入/导航/JS/表单/关闭标签页/文件上传 - 等待允许/拒绝卡片。代理看到拒绝并继续对话。切换立即应用，无需重新创建会话（通过代理SDK的canUseTool）。
## 页面指示
当Claude对标签页执行操作时（从面板或Claude Code）：
- 橙色光环围绕页面边缘燃烧，并带有“✳ Claude正在工作…”的徽章，在最后一次操作后2.5秒后渐隐；
- 虚拟光标（橙色箭头）滑到操作点并点击时脉动一个环；它在3.5秒不活动后消失。
两者都在截图时隐藏，以免出现在帧中并混淆模型在处理坐标时。对于无法注入脚本的页面（`chrome://`等），指示静默跳过。
## 安装
1. **扩展程序**：克隆此仓库，打开`chrome://extensions`（在正确的空间/配置文件中！），启用“开发者模式”，点击“加载解包”，然后选择`extension/`文件夹。
2. **MCP服务器** - 任意方式：
- 通过npm：`claude mcp add -s user chromium-bridge -- npx chromium-bridge`
- 从克隆仓库：`cd server && npm install`，然后`claude mcp add -s user chromium-bridge -- node "$(pwd)/index.mjs"`。
它在会话启动时加载 - 在安装扩展程序后重启Claude Code会话。
对于其他MCP客户端，请在您的配置文件中添加以下内容：
```json
{
"mcpServers": {
"chromium-bridge": {
"command": "npx",
"args": ["chromium-bridge"]
}
}
}
```
3. 检查：`browser_status`工具应返回`{"connected": true}`。
## 工具（v0.5）
| 工具 | 功能 |
|---|---|
| `browser_status` | 检查与扩展程序的连接 |
| `browser_tabs_list` | 列出标签页（id，标题，URL） |
| `browser_tab_create` / `browser_tab_close` | 打开/关闭标签页 |
| `browser_navigate` | 导航到URL；`back`/`forward`用于历史记录 |
| `browser_page_text` | 页面标题，URL和可见文本 |
| `browser_computer` | 通过CDP的鼠标/键盘/截图：按坐标或引用，点击，拖动，悬停，输入，键组合，滚动，缩放区域截图，等待 |
| `browser_read_page` | 具有引用ID的可访问性树（过滤器=交互式） |
| `browser_find` | 按文本/角色查找元素，返回引用 |
| `browser_form_input` | 按选择器或引用设置输入/文本区域/选择/复选框/可编辑内容的值 |
| `browser_click` | 按CSS选择器进行DOM点击（普通的.click（）） |
| `browser_upload_file` | 将文件放入`<input type="file">` |
| `browser_javascript` | 在页面上运行JS（支持await） |
| `browser_console_messages` | 标签页控制台（带有正则表达式过滤器） |
| `browser_network_requests` | 标签页网络请求（带有正则表达式过滤器） |
| `browser_resize_window` | 窗口大小 |
| `browser_gif_start` / `browser_gif_stop` | 记录标签页的GIF → 文件；对于长时间录制，帧率会自动减半，以便整个场景都能适应 |
除基本标签页操作外，所有操作都通过`chrome.debugger`（CDP）工作：截图不需要激活标签页，点击是真正的鼠标事件，控制台/网络是从标签页的第一个CDP触摸开始收集的。
## 限制
- 扩展程序存在于一个浏览器配置文件中 - 请在您要自动化的配置文件中安装它。
- 在服务器运行时，其周期性ping保持扩展程序的服务工作线程唤醒。如果工作线程已经处于睡眠状态（例如，服务器刚刚启动），则keepalive闹钟会在〜30秒内唤醒它，服务器在错误之前最多等待12秒重新连接。
- 信任模型：WS服务器监听127.0.0.1并拒绝其来源不是`chrome-extension://…`的连接，这将网页排除在外。它不区分扩展程序，非浏览器本地进程可以伪造来源标头 - 任何以您的用户身份运行的程序都值得信赖，就像大多数本地开发工具一样。不要在共享机器上运行桥梁。
- 在第一个CDP操作中，浏览器会显示一条“Chromium Bridge启动了此浏览器的调试”栏 - 这是正常的，调试器是控制机制。关闭此栏会分离调试器（下一个操作会重新附加它）。
- 控制台/网络不会追溯记录 - 仅在标签页首次触摸后记录。
- 端口8929由一个会话拥有：第二个并行的Claude Code会话无法启动自己的WS服务器（扩展程序与第一个会话保持连接）。
## 许可证
[MIT](LICENSE)
