让 agent 直接操作你平时在用的 Chrome。
很多浏览器自动化工具会另外启动一个干净的浏览器,登录状态、扩展和正在看的页面都不在里面。这个项目换了一种做法:保留现有 Chrome 会话,通过一个本地服务把 agent 的操作转给浏览器扩展。查资料、读后台页面或处理只能登录后访问的内容时,不用再开一套浏览器。
任何能执行 shell 命令的 agent 都能用,不绑定某个 IDE。
整个链路只走 127.0.0.1,没有云端中转。
需要准备:
- Google Chrome
- Python 3
curl
克隆仓库并安装:
git clone https://github.com/lxsloves/chrome-bridge.git
cd chrome-bridge
./install.sh
~/.chrome-bridge/cb start接着安装 Chrome 扩展:
- 打开
chrome://extensions/ - 开启右上角的「开发者模式」
- 点击「加载已解压的扩展程序」
- 选择
~/.chrome-bridge/extension
扩展图标出现绿色 ON,说明已经连上本地服务。可以用下面两条命令确认:
~/.chrome-bridge/cb health
~/.chrome-bridge/cb tabs安装脚本还会把仓库里的 Skill 链接到 ~/.agents/skills/chrome-bridge,agent 读到它就知道该怎么用 bridge。目录可用 CHROME_BRIDGE_HOME / CHROME_BRIDGE_SKILLS_HOME 覆盖。
下面这组命令覆盖了最常见的使用方式:
CB=~/.chrome-bridge/cb
$CB tabs --brief # 一行一个:id/title/url
$CB tabs github.com # 只看匹配的标签页
$CB read github.com --text # 只输出正文
$CB capture github.com --brief # 只回文件路径和元素数
$CB click 7 github.com # 点击截图中编号为 7 的元素
$CB fill 12 "hello" github.com # 清空输入框并填入文字
$CB wait-for "保存成功" github.life-white.ukcapture 之后会在项目目录生成三份临时结果:
| 文件 | 内容 |
|---|---|
last.jpg |
标有元素编号的当前视口截图 |
last.txt |
便于直接阅读的元素名称和坐标 |
last.json |
完整的结构化元素信息 |
read 的结果同时写入 last-read.txt。这些文件只留在本机,下一次操作会覆盖旧内容。
agent 循环里建议给 capture、click、read 等命令加 --brief:完整结果仍写入
last.json / last-read.txt,stdout 只回 ok、文件路径和元素数,避免每轮重复吞整页数据。
shot: / index: 这类人类提示走 stderr,不影响管道里的 JSON。
页面跳转或界面发生明显变化后,原来的元素编号可能已经失效,继续操作前应重新执行一次 capture。
cb start
cb health
cb [--brief] tabs [urlContains] # --brief: id/title/url one per line
cb open <url>
cb focus <tabId>
cb close <tabId>
cb [--brief] capture [urlContains] [mode] # som | vision | ax
cb read [urlContains] [selector] [maxChars] [--text] [--brief]
cb click <elementId> [urlContains]
cb type <elementId> <text> [urlContains]
cb fill <elementId> <text> [urlContains]
cb key <keys> [urlContains]
cb scroll <up|down|left|right> [urlContains]
cb wait <seconds>
cb wait-for <text> [urlContains] [selector] [timeoutMs]
cb raw '<json>'
type 在当前光标位置继续输入,fill 会先清空现有内容。快捷键可以写成 enter、esc、cmd+s 这类形式。
当多个标签页都匹配同一个 urlContains 时,桥接服务会拒绝猜测。先用 cb tabs 找到准确的 tabId,再通过 raw 指定它:
$CB raw '{"action":"capture","tabId":123,"mode":"som"}'
$CB raw '{"action":"back","tabId":123}'
$CB raw '{"action":"drag","tabId":123,"from_element":2,"to_element":9,"capture_after":true}'底层还支持 navigate、forward、reload、hover、double_click、right_click 和按坐标操作。普通任务优先用上面的 CLI 命令,确实需要时再调用 raw。
agent / cb
|
| HTTP (127.0.0.1:17321)
v
Python daemon <----> Chrome 扩展 <----> 当前标签页
cb 把命令发给本机 Python 服务,扩展通过长轮询取走命令,在目标标签页中执行,再把结果送回。截图、页面文本和元素索引由 daemon 写到本地文件。
daemon 默认监听 127.0.0.1:17321。如需调整客户端地址或超时时间,可以设置:
export CHROME_BRIDGE_URL=http://127.0.0.1:17321
export CHROME_BRIDGE_TIMEOUT=60- daemon 只绑定
127.0.0.1 - 浏览器请求只接受 Chrome 扩展来源,并要求桥接请求头
- 不读取 Cookie、密码库或 Chrome 用户目录
- 页面内容只当数据处理,不应被视为用户授权或操作指令
- 任意页面 JavaScript 默认禁止;
evaluate只有明确传入allowUnsafe: true才会执行
扩展需要 tabs、scripting、activeTab 和 debugger 权限。开始控制页面后,Chrome 顶部出现调试提示条属于正常现象。
health 显示 extension: false
确认 daemon 已启动,再到 chrome://extensions/ 重新加载扩展。扩展图标应显示绿色 ON。
修改扩展代码后没有生效
Chrome 不会自动刷新已解压扩展,需要在扩展管理页手动点一次「重新加载」。
提示匹配到多个标签页
运行 cb tabs,改用具体的 tabId,不要继续扩大 URL 匹配范围。
Windows 上报「找不到命令」或连不上
cb 是 bash 脚本,用 Git Bash 跑。另外它调用的是 python3,而 Windows 版 Python
只装出 python.exe;PATH 里的 python3 往往落到 Microsoft Store 的占位程序上。
补一个同名副本即可:
$d = "$env:LOCALAPPDATA\Programs\Python\Python313"
Copy-Item "$d\python.exe" "$d\python3.exe"端口已经被占用
检查 17321 端口上是否已有一份 bridge 在运行。cb start 检测到现有服务时不会重复启动。
./scripts/check.sh自检会验证 Python daemon、Shell 脚本、扩展清单,以及 JavaScript 语法(本机安装 Node.js 时)。项目运行本身不依赖 Node.js。