ai-browser-bridge

<p align="center"> <img src="assets/hero.png" alt="ai-browser-bridge — 在终端中通过 Chrome 驱动 ChatGPT、Gemini、Claude、DeepSeek、Grok、Perplexity 和 Flow" width="640" /> </p> # ai-browser-bridge > 在终端中驱动真正的 ChatGPT 或 Gemini 浏览器对话，并为 ChatGPT 提供一组狭窄、沙盒化的本地仓库工具，借助 MCP — 无需直接授予 shell 访问权限。 **English** · [עברית](README.he.md) · [Español](README.es.md) · [中文](README.zh.md)      --- ## 为什么存在 ChatGPT 在浏览器中表现最佳 — 真实的账户状态、模型选择、消息编辑、再生和对话历史都保持完整。编码在终端中最佳，文件、测试、差异和补丁直接检查和更改。 `ai-browser-bridge` 连接这两个界面。终端提示驱动现有的 ChatGPT 或 Gemini 浏览器会话，ChatGPT 可以通过一组 **经过验证的 MCP 工具** 访问当前仓库 — `grep`、`read`、`apply_patch`、`run_tests`、`git_diff` — 而不是原始 shell 访问。你保持在一个终端工作流中；提供者保留其真实的 UI。 ## 功能 - **终端驱动的 ChatGPT** — 发送提示并流式传输回复，无需离开 shell；真实的浏览器对话保持为真理源。 - **九个提供者，一个命令** — `chatgpt`、`gemini`、`claude`、`deepseek`、`grok`、`perplexity`、`duck`（[Duck.ai](https://duck.ai/chat)）、`arena`（[Arena](https://arena.ai/code/direct) — 直接/战斗/代理/并排 + 模型选择），以及 `flow`（Google 的 Veo 视频工作室 — 生成表面，而不是聊天）。使用 `--provider` 选择一个，或 **分发** 到多个（`--provider claude,deepseek,duck`）并在一次调用中获取每个提供者的回复，并按提供者键入。 - **为代理构建** — 稳定的非交互式 `bridge ask … --json` 合同（永远不会在管道中挂起）+ 外出 MCP `ask` 工具，以便任何代理都可以驱动网络聊天。 - **沙盒化的本地工具通过 MCP** — 每个文件操作都针对选定的仓库根目录进行验证；不允许任意 shell，仅允许列出的测试命令。 - **浏览器操作作为命令** — `/resume`、`/new`、`/model`、`/rewind`、`/stop`、`/context`、`/diff`、`/compact` 等。 - **仓库本地会话和记录（如果需要）** — TUI 和工具启用的运行在 `<repo>/.bridge/` 下持久存在；纯 `bridge ask` 保持无状态，仅重用共享的 Chrome 配置文件。 - **安全控制** — 权限模式（`read-only` / `ask` / `auto`）和每个补丁周围的自动文件检查点。 - **项目约定** — 自定义命令以及 `AGENTS.md` / `CLAUDE.md` 被馈送到 ChatGPT 以运行 `/task`。 - **真正的作曲家** — 提示历史、反向搜索、队列提示和 `@file` 提到自动完成。 ## 架构 ```text 终端（你） │ │ Ink / React CLI ▼ 编排器 ──────────────┬───────────────────────────────┐ │ 浏览器自动化 │ MCP 服务器 │ ▼ （Playwright + CDP）│ （MCP SDK） ▼ ChatGPT 浏览器 UI │ 本地仓库工具 ▲ │ （grep/read/patch/test/diff） │ ▼ │ └───── Cloudflare 隧道（cloudflared）◄────────────────┘ 公共 https://…trycloudflare.com/mcp ``` 四层，每层一个作业： | 层 | 技术 | 责任 | |-------|------|----------------| | **CLI** | Ink / React | 终端 UI：消息窗格、状态行、 `@file` 提及、 `/commands`。 | | **浏览器** | Playwright + Chrome DevTools 协议 | 附加到 Chrome 调试端口，重用一个共享的桥接 Chrome 配置文件。生命周期/状态/缓存代码位于 `src/features/browser/`；提供者选择器位于 `src/features/providers/<name>/` 下。 | | **MCP 服务器** | MCP SDK + 效果模式 | 将本地仓库工具作为经模式验证的沙盒化处理程序暴露给 ChatGPT、Claude 和 Grok。 | | **隧道** | Cloudflare 隧道（`cloudflared`） | 为本地 MCP 服务器提供一个临时的公共 HTTPS URL，供提供者连接器访问 — 无需部署。 | **为什么使用隧道？** 提供者 MCP 连接器通过 HTTPS 调用工具，但工具服务器在您的机器上运行。桥接器不是部署任何内容，而是启动一个临时的 Cloudflare 隧道（`*.trycloudflare.com`）在本地端口前面，并将该 Streamable HTTP `…/mcp` URL 同步到启动时的提供者应用程序中。（ngrok 可以解决相同的可达性问题；使用 Cloudflare 的 `cloudflared` 是因为其快速隧道不需要帐户或身份验证令牌。Grok 的 UI 可能会显示一个 `/sse` 示例 — 桥接器注册 `/mcp` 因为 cloudflared 快速隧道不支持 SSE。） ## 快速开始 **前提条件** - **macOS** — Chrome 使用 macOS `open` 命令启动，剪贴板/进程助手使用 `pbcopy`/`lsof`。 - **Node.js ≥ 20** 和 **pnpm** （仓库固定 `pnpm@10.14.0`）。 - **Google Chrome 或 Chrome for Testing** — 桥接器驱动一个共享的桥接器配置文件，通过调试端口。仅需在该桥接器启动的窗口中登录一次；每个仓库重用它。 - **`cloudflared`** （可选；ChatGPT、Claude、Grok）— 仅这些提供者需要它来调用本地 MCP 工具。无需它，TUI 仍然运行。使用 `brew install cloudflared` 安装。 **安装和构建** ```bash git clone https://github.com/YosefHayim/ai-browser-bridge.git cd ai-browser-bridge pnpm install pnpm build ``` **启动 Chrome，然后运行（ChatGPT — 默认）** ```bash node dist/bridge.js chrome start node dist/bridge.js --repo /path/to/your/project ``` **启动 Chrome，然后运行（Gemini 网页）** ```bash node dist/bridge.js chrome start --provider gemini node dist/bridge.js --provider gemini --repo /path/to/your/project ``` 更喜欢全局 `bridge` 命令？在构建后运行 `pnpm link --global`，然后使用 `bridge`、`bridge chrome start`、`bridge ask "…"` 等。 ### 浏览器配置文件策略 Chrome 136+ 不再接受针对真实默认 Chrome 数据目录的远程调试开关。因此，`ai-browser-bridge` **不** 驱动 `~/Library/Application Support/Google/Chrome`。它始终在调试端口启动浏览器，并使用一个全局桥接器配置文件： ```text ~/.ai-browser-bridge/chrome-profile ``` 该配置文件是桥接器的浏览器登录 SSO。对于桥接器启动的 Chrome 窗口，只需登录一次，然后 `bridge chrome start`、`bridge ask` 和 TUI 重用该登录凭证，而无需任何仓库或 shell 根目录。 对于发布和自动化工作，Chrome 团队建议使用 [Chrome for Testing](https://developer.chrome.com/blog/chrome-for-testing)。单独安装它，然后将桥接器指向该应用程序，同时保持相同的共享配置文件： ```bash AI_BROWSER_BRIDGE_CHROME_APP="Google Chrome for Testing" bridge chrome start ``` 应用程序覆盖仅更改启动的 Chrome 构建。配置文件保持 `~/.ai-browser-bridge/chrome-profile`；不要添加每个仓库的 Chrome 配置文件。参见 Chrome 的 [远程调试配置文件更改](https://developer.chrome.com/blog/remote-debugging-port)，了解上游原因。 **一次性，非交互式** ```bash node dist/bridge.js ask "summarize @src/core/engine.ts" --repo /path/to/project node dist/bridge.js ask "hello" --provider gemini --repo /path/to/project ``` ## 用法 ```text /help 列出命令 /sessions 列出本地会话 /resume <query> 通过编号/标题/ID恢复 /transcript 打印会话记录 /new 开始新的对话 /export 导出记录（md/json/jsonl) /model [name] 显示或切换模型 /permissions 显示或切换 MCP 权限模式 /rewind [text] 编辑上一个提示 + 再生 /checkpoints 列出文件检查点 /stop 停止活动响应 /restore <id> 从检查点恢复文件 /context 模型感知上下文估计 /status 仓库/模型/上下文/会话状态 /diff 询问 ChatGPT 读取差异 /mcp 连接器 + 暴露的工具 /task <request> 项目代理任务（MCP） /connector （重新）运行 MCP 连接器设置 /conversations 列出/搜索/打开浏览器对话 ``` **文件提及** — 在线引用仓库文件；它们在 ChatGPT 看到它们之前在仓库中解析并扩展： ```text refactor the CLI input flow in @src/features/terminal/tui/App.tsx compare @src/features/store/fileResolver.ts with @src/features/store/fileResolver.test.ts ``` 路径超出仓库根目录的文件将被跳过；超过 100 KB 的文件将被总结而不是内联。 **对话搜索** — `bridge chat search "query" --json` 通过共享的对话目录搜索 ChatGPT 历史记录。添加 `--open` 以导航浏览器到最佳匹配。 ## 代理和分发 `bridge ask` 是脚本和代理的稳定、非交互式接口 — 它打印到 stdout，从不提示管道，并且 `--json` 发出机器可读的有效载体。 ```bash # 一个提供者 bridge ask --provider claude --json "summarize the tradeoffs of optimistic locking" # 跨多个免费聊天分发；一次调用，回复按提供者键入 bridge ask --provider claude,deepseek,grok --json "same question, three models" # → { "claude": { "ok": true, "reply": "…", "elapsedMs": 8123 }, # "deepseek": { "ok": true, "reply": "…", "elapsedMs": 6210 }, # "grok": { "ok": false, "error": "…", "elapsedMs": 300000 } } ``` 分发是 **部分故障容忍** 的：仅当 *所有* 提供者失败时，或使用 `--strict` 时 *任何* 提供者失败时，运行退出。运行 `bridge chrome start --provider <name>` 并根据需要登录；桥接器在仓库之间重用共享的桥接器 Chrome 配置文件。 相同的分发核心通过输出的 MCP 工具公开 — 使用 `bridge serve` 启动一个_stdio MCP 服务器，任何 MCP 兼容的代理都可以调用 `ask({ prompt, providers })` 或 `search_conversations({ query, providers, limit })` 作为原生工具，而不是 shell 外壳。将它与 Claude Code 注册： ```bash claude mcp add ai-browser-bridge -- bridge serve ``` …或直接将它添加到任何 MCP 客户端配置中（标准的_stdio 服务器形状）： ```jsonc { "mcpServers": { "ai-browser-bridge": { "command": "bridge", "args": ["serve"] } } } ``` `ask` 工具接受 `{ prompt, providers?, timeoutSeconds? }` 并返回每个提供者的回复，按 ID 键入（与 `bridge ask` 相同的部分故障容忍分发）。`search_conversations` 工具接受 `{ query, providers?, limit? }` 并返回匹配的对话 URL，按提供者键入。在使用前运行 `bridge chrome start --provider <name>`，以便网关拥有一个已签名的 Chrome 会话来驱动。这是与传入的 MCP 服务器相反的方向，后者将您的仓库工具 *暴露给* 网络模型。 > 除 ChatGPT/Gemini 之外的提供者适配器附带标记为 `LIVE-VERIFY` 的最佳努力选择器 — 在依赖它们生产之前，请确认它们与实时登录的站点一致。 ## 状态存储位置 项目的持久桥接器状态写入 **该项目内部**，位于 `<repo>/.bridge/`： ```text <repo>/.bridge/ ├── .gitignore # 自动编写的单个 "*" — 参见下文 ├── config.json # 每个仓库的设置（包括 `provider`: chatgpt | gemini） ├── sessions/<id>/ # metadata.json + append-only events.jsonl 记录 ├── logs/<date>.jsonl # 提示、回复和 MCP 工具调用摘要 ├── checkpoints/ # 每个 apply_patch 之前/之后的快照 ├── exports/ /export 输出 ├── downloads/<conv>/ # 附件下载（默认情况下不给出 --out） └── screenshots/ /screenshot 和 /ui-qa 捕获 ``` 纯 `bridge ask` 和 `bridge chrome start` 不创建仓库本地状态；它们仅重用共享的 Chrome 配置文件。桥接器为持久的 TUI 会话、工具启用的询问 (`bridge ask --tools`)、检查点、导出、截图或默认附件下载创建 `<repo>/.bridge/`。 当需要仓库本地状态时，桥接器编写 `.bridge/.gitignore` 包含单个 `*`。这使得 git 忽略 **所有** 目录中的内容 — 会话记录、日志、下载、截图和检查点 — 因此其中任何内容都不能提交，即使它位于仓库内。Chrome 桥接器会话的 cookie 保留在共享的桥接器配置文件下 `~/.ai-browser-bridge/chrome-profile`，而不是 `.bridge/` 下。`git add -A` 和 `git add .bridge/` 都跳过桥接器状态；仅显式 `git add -f` 才能覆盖。文件在持久运行上重新断言，因此删除或篡改它会自动修复。 > 用户创作的配置适用于 **所有** 仓库，位于您的主目录：自定义命令位于 `~/.ai-browser-bridge/commands/*.md`，用户级钩子位于 `~/.ai-browser-bridge/hooks.json`。 ### 从 `chatgpt-local-bridge` 迁移 软件包更名为 **`ai-browser-bridge`**。全局用户配置从 `~/.chatgpt-local-bridge/` 移动到 `~/.ai-browser-bridge/` — 如果您有，请复制您的 `commands/` 文件夹和 `hooks.json`。持久的仓库本地状态保留在 `<repo>/.bridge/`（不变）。重新运行 `/connector` 或 `bridge ask --tools` 一次，以便 ChatGPT 拾取重命名的 MCP 连接器应用。 ## 权限和检查点 ```bash /permissions read-only # grep_code, read_file, git_diff /permissions auto # also the narrow write/test tools /permissions ask # blocks write/test/process tools (interactive confirm pending) ``` `apply_patch` 为每个 touched 路径生成快照，然后和之后恢复。 使用 `/checkpoints`、 `/restore <id>` 或 `/rewind --files <id>` 恢复。 ## 测试 ```bash pnpm test # vitest run pnpm typecheck # tsc --noEmit pnpm verify:push # biome ci + typecheck + test + build + check:class-api + check:tsdoc + check:boundaries ``` 覆盖率关注安全敏感路径 — 沙盒验证、仓库本地路径解析、`.bridge/` 自忽略保护、会话/检查点存储、权限和上下文计数。 ## Gemini 网页支持 桥接器可以使用与 ChatGPT 相同的 Playwright/CDP 模式驱动 **gemini.google.com**： ```bash bridge chrome start --provider gemini bridge --provider gemini --repo /path/to/project bridge ask "explain this repo" --provider gemini --repo /path/to/project ``` **Gemini 网页上有效的内容 - 终端驱动的提示和捕获的回复 - `@file` 提到扩展（仅仓库上下文内联到提示） - 模型检测/切换，当 Gemini UI 暴露选择器 - 重用相同的共享桥接器配置文件/调试端口模型与每个提供者 **Gemini 网页上无效的内容（今天） - **MCP 连接器** — gemini.google.com 没有像 ChatGPT、Claude 或 Grok 那样的自定义连接器 UI。桥接器跳过 MCP 服务器和 Cloudflare 隧道，当 `--provider gemini`。 - **`/task`, `/connector`, `/mcp`** — 这些需要实时 MCP 工具；使用 ChatGPT、Claude 或 Grok 进行这些工作流。 - **附件下载** - `bridge download` 仅限 ChatGPT 目前支持。 Gemini API 远程 MCP 使用官方 [Gemini API Remote MCP](https://ai.google.dev/gemini-api/docs/function-calling) 或 [Gemini CLI](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md) 代替浏览器 UI。 **选择器维护：** 当 Google 更改 Gemini 网页 UI 时，仅需在 [`src/features/providers/gemini/geminiPage.ts`](src/features/providers/gemini/geminiPage.ts) 中修复选择器。 ## Arena.ai 支持 桥接器使用专用的适配器驱动 **[Arena](https://arena.ai/code/direct)** | 模式 | `--model`令牌 | 网址 | |------|-----------------|-----| | **直接** (默认) | `direct` | `/code/direct` — 一个模型 | | **战斗模式** | `battle` | `/code` — 选项 A/B（当两个都完成时双重回复） | | **代理模式** | `agent` | `/agent` — 代理 shell（尽力而为） | | **并排** | `side` / `sbs` | `/text/side-by-side` — 选择两个模型 | ```bash bridge chrome start --provider arena bridge ask --provider arena "build a todo app" # Direct + Max bridge ask --provider arena --model glm-5.1 "reply with pong" # 选择一个模型 bridge ask --provider arena --model battle "compare two approaches" # 双重选项 A/B bridge ask --provider arena --model direct/gemini-3-flash "hello" # 模式 + 模型 ``` 模型搜索与 UI 选择器匹配（搜索模型 + 文本/代码/图像/搜索选项卡）。Battle 可能会在 Arena 上花费数分钟（完整的网站构建） — 如果需要，请提高 `--timeout`。Arena 上没有 MCP 连接器。 ## Google Flow 支持 桥接器还可以驱动 **[Google Labs Flow](https://labs.google/fx/tools/flow)** —— Google 的 Veo 驱动的 AI 视频工作室 —— 使用相同的 Playwright/CDP 模式。Flow 与聊天提供商不同：它是一个 **生成** 界面，因此“回复”是一个渲染的 **剪辑**，附件是 **素材**（参考图像）。 ```bash bridge chrome start --provider flow # 登录到 Google；账户需要 Flow 访问权限（AI Pro/Ultra） bridge ask --provider flow "一只猫在霓虹波浪上冲浪，电影般，8 秒" bridge ask --provider flow "相同的场景，黎明光线" --attach ref1.png ref2.png # 最多 3 个素材 ``` 除了生成外，桥接器通过 `bridge flow` 子命令驱动 Flow 的完整 **资产生命周期**（每个子命令都附加到当前 Flow 项目选项卡；添加 `--json` 以获取机器可读的输出）： ```bash bridge flow clips # 列出当前项目中的剪辑（ID + 可获取的 URL） bridge flow download # 下载每个剪辑的 mp4 到 ./downloads/flow（或 --id <clipId...>） bridge flow reuse --id <clipId> # 将剪辑添加回提示作为输入（“添加到提示”） bridge flow extend --id <clipId> # 将剪辑添加到场景（Flow 的“添加到场景”） bridge flow rename --id <clipId> --name "英雄镜头" bridge flow delete --id <clipId> --yes # 将剪辑移动到 Flow 垃圾箱（可恢复） bridge flow ingredients # 列出附加到提示的参考图像 bridge flow ingredient-remove --id <mediaId> # 取消附着一个素材 bridge flow ingredient-clear # 取消附着所有素材 bridge flow projects # 列出项目 bridge flow project-rename --name "启动预告片" bridge flow project-delete --yes # 永久删除当前项目 ``` 破坏性动词（`delete`、`project-delete`）需要 `--yes`；剪辑删除移动到 Flow 可恢复的垃圾箱。 没有 shell 访问权限的代理通过 `bridge serve` 获得与 **`flow_*` MCP 工具**相同的生命周期 —— `flow_list_clips`、`flow_download_clips`、`flow_reuse_clip`、`flow_extend_clip`、`flow_rename_clip`、`flow_delete_clip`、`flow_list_ingredients`、`flow_remove_ingredient`、`flow_clear_ingredients`、`flow_list_projects`、`flow_rename_project`、`flow_delete_project`。破坏性工具（`flow_delete_clip`、`flow_delete_project`）需要 `confirm: true`。 **Flow 支持的功能** - 终端驱动的镜头提示，触发 Veo 生成 - **素材** —— 附加最多三个参考图像到提示，并列出/删除/清除已附加的素材 - 返回一个捕获的 **剪辑引用**（视频 `src` / 下载 href）作为回复，以便代理获取结果指针 - **资产 CRUD** —— 列出/下载/重命名/删除剪辑，扩展或重用剪辑，管理提示素材，并列出/重命名/删除项目 —— 作为 `bridge flow …` CLI 命令 **和** `flow_*` MCP 工具通过 `bridge serve` - 重用与每个提供商相同的共享桥接配置文件/调试端口模型 **Flow 目前不支持的功能** - **MCP 连接器**、**`/task`**、**`/connector`**、**`/mcp`** —— Flow 没有连接器 UI，因此跳过 MCP 服务器和 Cloudflare 隧道（与 Gemini 相同） - **停止/渲染中控制** —— 取消正在进行的 Veo 渲染尚未连接。 Flow 需要 **Google AI Pro/Ultra** 计划。由于 Veo 渲染需要几分钟，因此 `--provider flow` 比聊天提供商等待响应时间更长。 **选择器维护：** Flow 的选择器已 **实时验证** 对话框登录项目编辑器。如果 Google 更改 UI，请使用 `node src/scripts/maintain/captureProviderSelectors.mjs` 重新捕获，然后更新 [`src/config/index.ts`](src/config/index.ts)；生成位于 [`src/features/providers/flow/flowPage.ts`](src/features/providers/flow/flowPage.ts)，资产 CRUD 位于 [`src/features/providers/flow/flowAssets.ts`](src/features/providers/flow/flowAssets.ts)。 ## 限制 - **仅限 macOS** （`open`、`pbcopy` 和 `lsof` 助手） - ChatGPT 和 Gemini 浏览器选择器可能会因 Web UI 更改而损坏；修复程序局限于浏览器层 - 上下文使用是一个 **估计值** —— 浏览器不暴露确切的服务器端令牌计数 - Cloudflare 隧道需要安装 `cloudflared` - 本地优先设计；不是托管的多用户服务 - 钩子命令执行被解析和报告，但尚未执行（允许列出的确认流程待处理） ## 许可证 [MIT](LICENSE) YosefHayim 版权所有