给 AI agent 一个真实浏览器，支持人工接管、认证复用与审计的安全浏览器控制面

方案简介

Auto Browser 是一个 MCP 原生的浏览器控制面，为授权工作流服务。它把一个真实的 Playwright 浏览器同时提供给 MCP 客户端、LLM agent 和运维人员，并在其上叠加人工接管（noVNC）、可复用认证档案、审批门、审计事件、PII 清洗、Witness 签名回执等安全机制，默认本地化部署（Docker Compose 或 Codespaces）。它解决的问题是：AI agent 操作真实网页时经常遇到脆弱站点、需要登录的流程或需要人类介入的环节，而普通 HTML 抓取无法胜任。适合内部后台工具运维、operator 协助的 QA 与浏览器调试、登录一次复用多次的账号工作流，以及需要真实浏览器而非仅 HTML 抓取的 MCP agent 工作流。明确不做 CAPTCHA 解决、未授权抓取或欺骗性身份工具。

亮点与能力

• MCP 原生：浏览器能力直接打包为 MCP server（支持 HTTP 与 stdio），兼容 Claude Desktop、Cursor 等 MCP 客户端，也可通过 REST API 用 curl 直接控制
• 人工接管：noVNC 让人可以在同一活跃会话中随时介入
• 认证复用：保存命名 auth profile，新会话打开即已登录
• 安全护栏：审批门、操作员身份头、PII 清洗、Witness 回执、保护档案
• 可验证证据：Witness 回执链用 Ed25519 签名，导出包可用独立脚本验证，接收方无需运行或信任本控制器
• text 观察预设：返回无障碍轮廓、提取文本与可交互元素，无截图无 OCR，最省成本的页面读取方式
• 任意 OpenAI 兼容模型驱动：通用适配器支持 openrouter、xai、deepseek、minimax 及自定义 base URL（自托管 Ollama/vLLM/LM Studio 等）
• Playwright 版本钉住一致性在 CI 强制执行，避免单侧升级导致 compose 崩溃循环

组成与分工

• MCP：对外暴露浏览器能力的协议层，HTTP 与 stdio 双通道，连接 Claude Desktop、Cursor 等 agent 客户端
• Playwright：底层真实浏览器自动化引擎，提供截图、DOM 摘要、OCR 摘录、标签控制、下载与网络检查
• noVNC：可视化人工接管入口，人在需要时介入同一活跃会话
• Docker Compose：本地一键启动全栈，端口默认绑定 127.0.0.1
• auto-browser-mcp / PyPI 包：pip install auto-browser-client SDK、pip install auto-browser-langchain LangChain/LangGraph/CrewAI 适配器、uvx auto-browser-mcp 零配置运行 stdio 桥
• Ed25519 Witness 回执：为审计证据链签名，导出包可独立验证

前置要求

• 本地 Docker（需有访问权限并可打开 localhost 套接字）
• Python 3.11 与 3.14 为 CI 测试矩阵版本
• 可选：Claude Desktop、Cursor 或任意支持 HTTP/stdio 的 MCP 客户端
• 可选：任意 OpenAI 兼容模型端点（OpenRouter、xAI、DeepSeek、MiniMax 或自托管 Ollama/vLLM/LM Studio）

实施步骤

1. 克隆并启动全栈

bash
git clone https://github.com/LvcidPsyche/auto-browser.git
cd auto-browser
docker compose up --build

默认设置即可完成本地开发。

2. 可选：环境配置与健康检查

bash
cp .env.example .env
make doctor

make doctor 需在普通终端运行，要求本地 Docker 访问权限及打开 localhost 套接字的权限。

3. 打开控制面

• API 文档：http://127.0.0.1:8000/docs
• 运维面板：http://127.0.0.1:8000/dashboard
• 可视化接管：http://127.0.0.1:6080/vnc.html?autoconnect=true&resize=scale

4. 跑通登录一次复用流程

1. 创建一个会话
2. 若站点需要人工登录，通过 noVNC 手动登录
3. 将会话保存为命名 auth profile
4. 从该 auth profile 打开新会话
5. 无需重新认证继续工作

使用与配置要点

• 让 agent 读页面：设置 PERCEPTION_PRESET_DEFAULT=text 作为部署级默认，使用 text 观察预设读取无障碍轮廓与文本，无截图无 OCR
• 单值查找：browser.find_elements 接受 query（纯文本或正则，大小写不敏感）返回每个匹配及上下文，无需完整 observe
• 审计查询：通过 browser://audit/events MCP 资源跨会话列出并读取近期审计事件
• 接入 agent 框架：pip install auto-browser-langchain 后在 LangChain/LangGraph/CrewAI 中使用；uvx auto-browser-mcp 零配置启动 stdio 桥
• 验证证据：导出的 Witness bundle 用 scripts/verify_witness_bundle.py 验证，该脚本不导入本项目的任何内容

注意事项与常见问题

• 明确不做：CAPTCHA 解决、未授权抓取或账号自动化、欺骗性身份塑造或绕过工具
• 所有发布端口默认绑定 127.0.0.1
• Playwright 版本在控制器（pip）与 browser-node（npm）两侧必须精确一致，单侧升级无法合并，否则 compose 部署会崩溃循环
• 对忽略 tool_choice 的端点提供了内容解析回退
• 仓库公开了对抗性审计文档 docs/audits/2026-08-execution-audit.md，记录了曾发现报告成功却实际未执行的安全控制及其修复
• 从 v1.3.0 起 fork 状态导出静态加密，shadow-browse 状态不落盘

优缺点

• ✓ 人类可在脆弱站点实时接管会话
• ✓ 登录一次保存为认证档案复用
• ✕ 不做 CAPTCHA 解决与未授权抓取
• ✕ 仅限授权工作流场景

出处

本方案挖掘自开源项目 LvcidPsyche/auto-browser，方案内容与实施命令均来自其 README 原文。