# 自主浏览器 · AI Browser Bridge

**默认用途：让已有 AI Agent 直接操作浏览器，无需配置模型。** 终端 Agent 可立即使用 [接入说明](AGENT-QUICKSTART.md) 和 agent.ps1；MCP 客户端使用本机生成的工具配置。插件内模型任务页只是可选功能。

一个可自行修改、运行的 Chrome Manifest V3 扩展，将网页提供给支持 MCP、HTTP 或命令行的 AI。扩展版本 **0.3.4 / 本地原型**，默认允许所有 HTTP / HTTPS 网站，也可切换为指定网站列表。

### 当前版本升级指南

0.3.4 新增可选 Chrome 内置 AI 状态检查与本地裁判 `browser_local_judge`；0.3.3 新增只读开发者诊断 `browser_debug`；0.3.2 修复自定义下拉已经展开时 `browser_choose` 反向关闭弹层的问题；0.3.1 新增精确选项工具，0.3.0 新增原生文件选择。请阅读 [0.3.0 使用与升级说明](docs/UPDATE-0.3.0.md)。

### 历史：从 0.1.0 更新到 0.1.1

如果加载的是本项目的 `extension` 文件夹，在 `chrome://extensions` 找到“自主浏览器”，点击重新加载，然后重新打开扩展面板。配对密钥和已保存的网站列表保留；未设置过 `allSites` 的旧配置默认启用所有网站。确认“允许所有网站（默认）”已勾选，点击“保存并连接”。如 Chrome 显示新增网站权限提示，按提示确认。若从其他目录解压安装，请用新扩展包更新那个目录后重新加载。

0.1.1 的连接状态和最近操作通过事件自动更新，无需持续点击刷新。原 0.1.0 桥接服务与新版扩展兼容，不必为了升级扩展断开正在使用的服务。

没有内置模型、开发者云端、遥测或 AutoGLM 依赖。浏览器控制在本机完成；接入的 AI 若运行在云端，返回给它的网页内容仍会进入该 AI 的服务。普通封闭聊天窗口不会因为安装扩展就自动获得工具能力。

## 已实现

- 网页可见正文提取、交互元素编号、点击、文本输入、主页面滚动。
- 在显式许可的本机目录内，按完整 SHA256 将文件绑定到最新 file-input ref；只选择文件，不自动点击提交。
- 标签页列举、新建、导航、关闭；通过临时 debugger 连接截图，完成后释放。
- Chrome 中文控制面板：配对、网站授权、连接状态、最近操作、暂停与重新连接。
- MCP stdio、带认证的本机 HTTP API、CLI 三种入口；不绑定模型厂商。
- 默认允许所有 HTTP / HTTPS 网站；关闭“允许所有网站”后按完整 origin 列表检查。拒绝 `file:`、`javascript:`、Chrome 内部页和带账户信息的 URL；浏览器保护的页面仍受 Chrome 限制。
- 命令全局顺序执行；失效元素引用与改变了标签/链接的元素会拒绝操作。
- 断线和超时不自动重放写入；排队命令失败返回。暂停不撤销已经执行的操作。
- 日志仅记录操作名称、标签页编号、时间和成功/失败，不记录输入内容、正文、截图或密钥。

## 本机启动与安装

要求：Node.js 22+、PowerShell 7、Chrome 120+。

本机已安装依赖；迁移到另一台电脑时先在项目目录运行 `npm ci`。

1. 在 PowerShell 7 中运行：

   ```powershell
   Set-Location 'K:\PythonProjects5\AI-Browser-Bridge'
   .\start.ps1
   ```

   服务只监听 `127.0.0.1:19387`，后台运行。再次启动会先检查已有服务，不会重复启动。

2. 在你希望使用的 Chrome 用户配置中打开 `chrome://extensions`，开启开发者模式，点击“加载已解压的扩展程序”，选择本项目的 **extension 文件夹**。
3. 运行 `.\pair.ps1`，密钥会复制到剪贴板，不会打印。打开“自主浏览器”的扩展选项，粘贴配对密钥。
4. 默认勾选“允许所有网站”，无需填写网站列表，点击“保存并连接”，状态会自动更新为“已连接”。若只想操作部分网站，取消勾选并逐行填写源地址，例如 `https://example.com`，再保存。路径不能填写；不同端口属于不同 origin。
5. 运行 `npm run status`。只有 `connected: true` 才表明当前 Chrome 扩展实际连接成功。

现有 AutoGLM 无需卸载。建议不要让两个自动化工具同时操作同一个标签页。第一版每个服务只连接一个 Chrome 用户配置，重复连接会被拒绝。

扩展更新后，在 Chrome 扩展页点“重新加载”，再打开扩展选项重新连接。断线时不会持续轮询重试；连接成功时每 20 秒发送一个纯本机保活消息，**不会调用模型或消耗模型 token**。

## 让其他 AI 接入

### MCP 客户端

`npm run setup` 会生成 `.local/mcp-config.json`，包含当前机器的 Node 可执行文件路径与 MCP 入口，不含密钥。将其中的服务器条目加入支持 stdio MCP 的客户端配置并重载连接。不同客户端的外围配置格式可能不同。

```json
{
  "mcpServers": {
    "ai-browser-bridge": {
      "command": "node",
      "args": ["K:/PythonProjects5/AI-Browser-Bridge/src/mcp.js"]
    }
  }
}
```

MCP 入口不会启动云模型。客户端自己决定下一步调用哪个工具。`tools/list` 暴露 20 个工具，`browser_screenshot` 返回 MCP 图片内容。

### CLI 客户端

```powershell
node src/cli.js tools
node src/cli.js call browser_tabs
'{"url":"https://example.com"}' | node src/cli.js call browser_open --stdin
'{"tabId":123}' | node src/cli.js call browser_read --stdin
```

必须使用实际返回的 tabId 和 ref，不能照抄示例中的 123。元素 ref 与最近一次快照绑定；导航或页面变化后重新读取。

### HTTP / 自己的 AI 程序

端点：`GET /status`、`GET /tools`、`POST /call`。请求头使用 `Authorization: Bearer <agentToken>`，令牌从本机 `.local/config.json` 读取。不要把配对密钥当成 agentToken，也不要把令牌贴到对话中。

```json
{"name":"browser_read","arguments":{"tabId":123,"maxChars":12000}}
```

服务拒绝网页 Origin 请求、错误 Host 和未认证请求，不提供浏览器可用的跨域开放接口。远程 AI 客户端需要本机适配器；本版本不提供公网网关。

## 验证与边界

```powershell
npm test
npm run test:e2e
```

自动测试使用独立临时 Chromium 配置和本地测试网页，不读取个人 Chrome 数据。端到端测试通过 MCP 完成打开、读取、填写、点击、截图、导航、暂停、恢复及关闭，并由独立 HTTP 客户端验证第二条接入路径。截图与报告在 `output/playwright/`。

本机测试脚本会优先使用已存在的 Playwright Chromium；其他机器可运行 `npx playwright install chromium`，或用 `AIB_TEST_CHROMIUM` 指向测试专用 Chromium。不要指向你的日常 Chrome 用户数据目录。

明确边界：

- 测试通过不等于已经装入你的日常 Chrome。实际连接以 `npm run status` 为准。
- 当前 DOM 操作限主框架和普通 DOM；尚未覆盖 iframe、Shadow DOM 的结构化定位、验证码和复杂富文本编辑器。文件上传支持主框架普通 DOM 的 file input；坐标操作可触达可见区域，但不提供 Canvas 结构化解析。
- 原有输入/点击使用 DOM 事件；新增键盘和坐标路径使用 CDP 可信事件。截图使用 debugger 权限，Chrome 可能显示调试提示；与其他调试器冲突时返回错误。
- 内置任务期间持有全局操作租约；外部客户端自行编排的多步工作流仍可能交错，需要自行协调。
- 指定网站模式约束工具的直接目标，**不是网络防火墙**。网页自身的脚本仍可能提交表单、发网络请求或跳转到其他网站；指定模式下未授权页不能继续读写，所有网站模式可继续操作其他 HTTP / HTTPS 页。截图包含页面中可见的嵌入内容。
- 文本提取不读取密码输入值，忽略隐藏文本与 `data-ai-private` 标记区域；截图没有自动脱敏。不能将其理解为完整敏感信息检测。
- 页面内容属于不可信数据，AI 客户端不得将网页中的指令当作用户授权。点击可能导致提交、发消息或购买，客户端必须遵守用户授权范围。
- `browser_local_judge` 只是可选的本地 Chrome 内置 AI 建议源。它不执行动作，也不替代用户授权；如果 Chrome 没有暴露 Built-in AI API、模型未下载或会话创建失败，会返回 `verdict: "unavailable"`，调用方必须按无裁判可用处理。
- 已有插件任务助手，模型在本机配置文件设置；尚无完整多轮聊天和模型管理界面。外部 AI 仍可独立调用工具。没有声称已全面超过 AutoGLM。

## 文件与运行状态

| 位置 | 用途 |
|---|---|
| `extension/` | 可直接加载的 Chrome 插件源码 |
| `src/server.js` | 本机 HTTP / WebSocket 桥接、排队、鉴权 |
| `src/mcp.js` | MCP stdio 适配 |
| `src/cli.js` | 命令行入口 |
| `.local/` | 本机密钥、日志、PID、接入配置，不进入分发包 |
| `test/` | 服务测试和真实扩展端到端测试 |
| `docs/HANDOFF.md` | 后续开发交接与已知限制 |

停止后台服务：`.\stop.ps1`。不设置开机自启、不修改现有 AI 客户端配置。若要完全停用，也可在 Chrome 中禁用扩展。

## 技术依据

- [Chrome WebSocket 与 service worker 生命周期](https://developer.chrome.com/docs/extensions/how-to/web-platform/websockets)
- [Chrome scripting API](https://developer.chrome.com/docs/extensions/reference/api/scripting)
- [Chrome debugger API](https://developer.chrome.com/docs/extensions/reference/api/debugger)
- [MCP stdio 传输规范](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports)
- [Playwright 扩展测试](https://playwright.dev/docs/chrome-extensions)