# lzh-browser-bridge **Repository Path**: Reusify/lzh-browser-bridge ## Basic Information - **Project Name**: lzh-browser-bridge - **Description**: Extension-held CDP bridge: an MV3 extension attaches chrome.debugger so agents never hit Chrome's allow-debugging prompt. MCP stdio server included. - **Primary Language**: Unknown - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-09-17 - **Last Updated**: 2026-10-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # lzh-browser-bridge 给 agent 用的浏览器控制桥。**扩展自己持有 `chrome.debugger`**,所以 agent 操作浏览器时**永不触发 Chrome 的「允许调试」弹窗**——这不是绕过,是架构层把机制本体消除了。 - 公开仓库(Gitee `Reusify/lzh-browser-bridge`),npm 包同名发布 - 能力层,**不含智能层**(不内置 LLM / Planner) - 纯 TypeScript;对外分发走 `dist/` 构建产物(安装期零构建) - 契约单一真源 `contracts/tools.json` → 编译 MCP / JSON-RPC / OpenAPI / CLI 四出口 + Agent 能力清单(全部落盘 `generated/`) ## 安装(三步) > 需要 Node ≥ 22.6。 ```bash # 1. 全局安装 npm i -g lzh-browser-bridge # 2. 装扩展:chrome://extensions/ → 开发者模式 → 加载已解压的扩展程序 # 选全局包内的 extension/ 目录(/lzh-browser-bridge/extension) # 3. 配 MCP(npx 直写,免绝对路径) { "lzh-browser-bridge": { "command": "npx", "args": ["-y", "lzh-browser-bridge"] } } ``` > 少数不解析 `.cmd` shim 的客户端(裸 spawn 无 shell)npx 会失败,改用 node 形态: > `{ "command": "node", "args": ["/lzh-browser-bridge/dist/mcp_stdio.js"] }` > > 端口默认 8765;可在 args 追加 `"--port", "8791"`(或 `env.BRIDGE_PORT`)改端口,配 `BRIDGE_HOME` 隔离测试实例。 > 更新包后 Chrome 内存里可能还是旧扩展代码:到 `chrome://extensions/` 点该扩展的刷新按钮重载即可。 ## 进程模型 ``` MCP 客户端 ──stdio──> stdio stub ──ws://127.0.0.1:8765──> daemon(单例) ──> 扩展 ──chrome.debugger(CDP)──> 浏览器 ``` - **daemon 单例**:靠绑定端口(默认 8765);空闲 10 分钟默认 `exit`(有扩展连着则不自退),下次调用自动拉起;也可用 `daemon_exit` 主动退出。 - **扩展主动拨号**连 daemon,CDP 由扩展自己持有。 - `browser_list` / `browser_select` / `daemon_exit` 由 **daemon 自身**实现,不下发扩展。 ## 能力清单 **Agent 请先读这里**:完整能力清单(工具名 / 标题 / 风险 / 驱动 / 必填参数 / 浏览器支持)是 [`generated/agent-capability-manifest.json`](generated/agent-capability-manifest.json), 由 `contracts/tools.json` 经 `npm run gen:contracts` 自动生成,**勿手改**(`npm run check:contracts` 卡漂移)。 命令行也能直接取(开发仓库用 `dist/cli.js`,全局安装用 `/lzh-browser-bridge/dist/cli.js`): ```bash node dist/cli.js tools --format manifest ``` > ⚠️ `page_eval` 是 **critical 风险**能力:**默认可用**(设计场景是驱动你自己已登录的本机浏览器)。如需关闭,在 daemon 进程环境设 `BRIDGE_DISABLE_EVAL=1` 并重启 daemon;关闭时返回 `EVAL_DISABLED` 且不执行任何代码。 完整参数、示例与返回形状 → [`contracts/tools.json`](contracts/tools.json)(单一真源);其余编译产物见 [`generated/`](generated/)(MCP / JSON-RPC / OpenAPI / CLI 四出口 + 上述能力清单)。 > 工具数量与分类**不在本文档写死**(一写死就会随版本漂移);机器可读的准确清单以 `generated/agent-capability-manifest.json` 与 [`generated/contract-report.md`](generated/contract-report.md) 为准。 ## 安全边界 - daemon 只绑 `127.0.0.1`;`BRIDGE_TOKEN` 非空时启用握手校验 - 遥测默认关闭、完全离线;storage 写 / 网络 mock 等其余 critical 能力暂未开放 - 不绕过验证码 / 风控,需要人工介入时走 HITL - `extension.pem` / `extension.crx`(签名私钥与打包产物)不入库、不进 npm 包 ## 开发 ```bash npm run build # tsc → dist/(改 daemon/ 源码后必须跑,且 dist/ 要一起提交) npm run check # tsc --noEmit npm run check:contracts # 契约卡口(generated/ 与真源是否漂移) npm run gen:contracts # 改了 contracts/tools.json 后重新落盘 ``` 三条改代码的铁律: 1. 改了 `daemon/` 源码必须 `npm run build` 并提交 `dist/` —— 安装包跑的是 `dist/`。 2. 改了 `extension/` 必须重建并重载扩展副本 —— 改源 ≠ 改被测副本。 3. 关浏览器只按 PID 关。严禁 `taskkill /f /im chrome.exe` 之类按名批量杀。 ## License [MIT](LICENSE)