内容
语言: 简体中文
# Gemini 网页桥接
[](https://github.com/andrewLi1994/gemini-web-bridge/actions/workflows/ci.yml)
Gemini 网页桥接为您的 AI 客户端（例如 Codex、Cursor、Claude Desktop 或自定义脚本）提供了一个本地的、用户控制的通道，以便访问已登录的 Gemini 网页会话，而无需 Gemini API 密钥。桥接器负责可靠的浏览器自动化，并返回 Gemini 的完整原始答案。
典型用途包括理解一个或多个公共 YouTube 视频的音频和视觉内容，询问有关公共 URL 的限定问题，或获取独立的辅助分析。
## 运行模式
- **Codex 插件**：与 Codex 无缝集成。
- **标准 MCP 服务器**：与任何 MCP 兼容的客户端（例如 Cursor、Claude Desktop、Windsurf）一起使用。
- **独立 CLI**：可以直接从终端或 shell 脚本调用。
## 要求
- macOS
- 支持插件市场的 Codex
- Node.js 22 或更高版本
- Google Chrome、Microsoft Edge、Brave 或 Chromium
- 可以使用 Gemini 网页的 Google 帐户
## 安装或升级
```sh
codex plugin marketplace add andrewLi1994/gemini-web-bridge --ref main
codex plugin add gemini-web-bridge@gemini-web-bridge
```
对于现有安装：
```sh
codex plugin marketplace upgrade gemini-web-bridge
```
安装或升级后启动新的 Codex 线程。正常情况下，询问结果，例如：
```text
比较这两个公共 YouTube 视频中的声明，并检查其证据有何不同：<URL1> <URL2>
```
Codex 会决定是否使用一个 Gemini 会话、多个全新会话、后续提示或根本不调用 Gemini。在每次成功的全新调用后，将返回一个本地的随机会话句柄；视频和 Codex 线程不会自动选择或重用会话。
## MCP 客户端配置
由于 Gemini 网页桥接是一个标准的 MCP 服务器，因此可以在其他 MCP 兼容的客户端中配置它。
### Claude Desktop
将以下内容添加到您的配置文件中（位于 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
```json
{
"mcpServers": {
"gemini-web-bridge": {
"command": "node",
"args": [
"/absolute/path/to/gemini-web-bridge/plugins/gemini-web-bridge/dist/mcp-server.mjs"
]
}
}
}
```
*注意：请记得将 `/absolute/path/to` 替换为系统上该项目的实际路径。编辑完成后，请完全重启 Claude Desktop。*
### Cursor
您可以通过 Cursor 设置 UI 进行配置：
1. 打开 **Cursor 设置** > **MCP**。
2. 点击 **+ 添加新的 MCP 服务器**。
3. 将名称设置为 `gemini-web-bridge`，类型设置为 `stdio`。
4. 将命令设置为 `node "/absolute/path/to/gemini-web-bridge/plugins/gemini-web-bridge/dist/mcp-server.mjs"`。
## 首次使用
1. Codex 仅需一次权限即可发送最低必要的公共 URL、限定问题、语言和输出要求到 Gemini 网页。
2. 如果需要登录，插件会打开一个可见的 Chrome 窗口，带有专用的配置文件。
3. 手动登录并关闭整个专用 Chrome 窗口。插件验证登录后，Codex 会自动继续未完成的请求。
正常请求在无头后台浏览器中运行。任务页面和浏览器在成功、失败或取消后关闭。
## 隐私和安全
- 不得自动发送完整的 Codex 会话、本地文件、凭证、机密和私人数据。
- Google 登录 cookie 保留在专用的本地 Chrome 配置文件中。
- 本地状态仅存储同意、会话句柄、Gemini URL、线程标签和时间戳。不复制提示或答案。
- 运行时数据存储在 `~/Library/Application Support/Codex UI Extensions/Gemini Web Bridge/` 下，并从 Git 中排除。
- Chrome 调试使用绑定到 `127.0.0.1` 的随机端口。
- 浏览器和状态操作使用跨进程锁、限制权限、原子写入和过时锁定恢复。
- 插件不会填写 Google 登录表单、绕过 CAPTCHA 挑战或绕过帐户限制。
- Gemini 响应是未经信任的外部材料。Codex 而非自动化必须评估其质量和声明。
## 可靠性边界
桥接器报告机械状态，例如需要登录、CAPTCHA、速率限制、浏览器断开连接、不完整的生成、未知的提交结果或更改的页面结构。它从不确定 Gemini 答案在语义上是好还是坏。
仅已知在提交前发生的故障可以自动重试一次。在发送操作确认后，桥接器绝不会盲目地重新提交；Codex 决定是否跟进或创建新的会话。
Gemini 网页不是一个稳定的 API。页面重新设计可能会暂时破坏自动化，直到选择器更新，并且 Gemini 的可用功能可能会因帐户或请求而异。
## v0.2 兼容性
旧的 `analyze_youtube` MCP 工具仍然可用，但已弃用。现有的视频到会话的映射在旧的 `sessions.json` 保留为备份的情况下迁移到随机会话句柄。新工作使用 `gemini_web_ask`。已弃用的工具计划在 v0.3 中删除。
## 诊断 CLI
CLI 镜像 MCP 原语用于开发和恢复；它不是正常的用户界面。
```sh
node plugins/gemini-web-bridge/dist/gemini-web-cli.mjs status
node plugins/gemini-web-bridge/dist/gemini-web-cli.mjs authorize --confirmed
node plugins/gemini-web-bridge/dist/gemini-web-cli.mjs login --wait
printf '%s' '{"prompt":"Ask a minimal scoped question"}' | node plugins/gemini-web-bridge/dist/gemini-web-cli.mjs ask
node plugins/gemini-web-bridge/dist/gemini-web-cli.mjs conversations
```
CLI 结果是 stdout 上的 JSON；进度事件是 stderr 上的 JSON 行。退出代码 `2` 表示需要人类登录/验证，`3` 表示速率限制，`4` 表示自动化失败，`5` 表示输入无效或缺少会话。
## 卸载
```sh
codex plugin remove gemini-web-bridge@gemini-web-bridge
codex plugin marketplace remove gemini-web-bridge
```
卸载不会删除专用的 Chrome 配置文件。如需删除运行时目录，请手动删除以注销和删除本地会话元数据。
## 开发
```sh
npm ci --prefix plugins/gemini-web-bridge
npm run verify
```
MCP 服务器和诊断 CLI 作为生成的单文件包提交，因此市场用户无需安装 npm 依赖项。在源代码或依赖项更改后，运行 `npm run build` 并提交更新的 `dist/` 文件。
在 [MIT License](LICENSE) 下许可。 通过 [private vulnerability reporting](SECURITY.md) 报告安全问题。
