用途
chromium-bridge 是一个连接 Chromium 系浏览器与 Claude Code 的 MCP 桥接工具。官方“Claude in Chrome”扩展在部分 Chromium 浏览器（如 Arc、Vivaldi 等）中虽然能连接，但自动化会挂起：其工具基于 tab groups API，而该 API 在这些浏览器中缺失或损坏。本桥接仅使用普通的 chrome.tabs / chrome.scripting / chrome.debugger，因此可在任何能够加载扩展的 Chromium 浏览器中工作。
主要能力
- 浏览器自动化工具：导航、点击、读取页面文本、截图、填表、运行 JavaScript、管理标签页、读取控制台与网络信息、关闭标签页、上传文件等。
- 通过 MCP 向 Claude Code 暴露 browser_* 工具。
- 提供浏览器内聊天面板（相当于“Claude in Chrome”侧边栏的替代）：点击扩展图标打开，面板可查看标签页、读取页面、截图和点击。
- 面板支持模型选择（Default 从 ~/.claude/settings.json 读取，其他为硬覆盖，切换即时生效并记忆），也支持环境变量 CHROMIUM_BRIDGE_CHAT_MODEL 启动覆盖。
- 聊天历史：面板头部 🕓 按钮列出过去对话（存于面板 localStorage，最多 30 条）。
- 每轮后显示用量行：轮次 token（↑ 输入含缓存 / ↓ 输出）及累计会话费用（订阅模式下为估算值）。
- 截图在聊天流中显示（点击放大），不保存进历史。
- 支持从剪贴板粘贴图片（输入框 Cmd+V，每条最多 5 张），历史中仅保留标记。
- “Ask before acting”模式（输入框上方复选框）：读取操作（标签页、文本、截图、控制台、网络）无询问执行；变更类操作（点击/输入/导航/JS/表单/关闭标签页/文件上传）等待 Allow / Deny 确认卡片。代理看到拒绝后会继续对话。切换立即生效，无需重建会话。
- 页面指示：当 Claude 在标签页上操作时，页面边缘出现橙色光晕及“✳ Claude is working…”标记，最后一次操作 2.5 秒后淡出；虚拟光标（橙色箭头）滑向操作点，点击时脉冲圆环，静止 3.5 秒后消失。两者在截图中隐藏，避免干扰模型坐标判断；无法注入脚本的页面（如 chrome://）会静默跳过。
- 界面语言：面板默认英文，浏览器 UI 语言为俄语时自动切换为俄语；底部栏语言选择器（Auto / English / Русский）可覆盖自动检测，页面标记跟随同一选择。
使用方式
扩展安装：克隆仓库，打开 chrome://extensions（注意在正确的空间/配置文件），启用“开发者模式”，点击“加载已解压的扩展程序”，选择 extension/ 文件夹。
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 客户端可在配置中加入：
{ "mcpServers" : { "chromium-bridge" : { "command" : " npx " , "args" : [ " chromium-bridge " ] } } }
检查：browser_status 工具应返回 {"connected": true}。
端口：CHROMIUM_BRIDGE_PORT（默认 8929，仅服务器端）；扩展始终连接 8929，因此改端口还需修改 extension/sw.js 和 extension/chat.js 中的 WS_URL。
工作原理：除基本标签页操作外，全部通过 chrome.debugger（CDP）实现——截图无需激活标签页，点击为真实鼠标事件，控制台/网络从首次 CDP 接触该标签页后开始收集。
适用场景
在官方 Claude in Chrome 扩展无法正常自动化的 Chromium 浏览器（Arc、Vivaldi 等）中，用 Claude Code 或内置聊天面板驱动浏览器完成网页操作、信息读取与自动化任务。
限制
- 仅当服务器运行时可用（通常是一个带 chromium-bridge MCP 的活动 Claude Code 会话）；否则面板显示“Server unavailable”。
- 扩展只存在于一个浏览器配置文件中——需安装在想要自动化的那个配置文件里。
- 弹窗失焦（点击页面）会关闭，这是浏览器行为。会话上下文不丢失：面板记住 session_id，服务器通过 Agent SDK resume 恢复对话。弹窗关闭时正在进行的轮次会被中断。
- 服务器运行时定期 ping 保持扩展 service worker 唤醒；若 worker 仍休眠（如服务器刚启动），keepalive 闹钟会在约 30 秒内唤醒，服务器在报错前最多等待 12 秒重连。
- 信任模型：WS 服务器监听 127.0.0.1，拒绝 Origin 不是 chrome-extension:// 的连接，以屏蔽网页；但不区分不同扩展，非浏览器的本地进程可伪造 Origin 头——以你的用户身份运行的东西都被信任，与多数本地开发工具相同。不要在共享机器上运行该桥接。
- 首次 CDP 动作时浏览器会显示“Chromium Bridge started debugging this browser”栏，属正常现象；关闭该栏会断开调试器（下次操作会重新附加）。
- 控制台/网络不追溯记录——仅在首次接触标签页之后开始。
- 端口 8929 由一个会话独占：第二个并行的 Claude Code 会话无法启动自己的 WS 服务器（扩展保持与第一个连接）。
