内容
# 代理浏览器
### 网络，如 LLM 所见
**稳定引用 · 精简观察 · 结果验证 · 任意代理主机 MCP**
[](https://www.python.org/downloads/)
[](./CHANGELOG.md)
[](#开发)
[](./LICENSE)
[](./docs/mcp.md)
> 不仅仅是 HTML 解析器。一个由**语义工具**控制的**真正的 Chromium 浏览器**，让 Claude、Cursor、LangGraph 或您自己的代理可以**看到、点击、输入和验证**，而不会淹没在 10 万以上的标记中。
**仓库：** [github.com/applejuice093/Agentic-browser](https://github.com/applejuice093/Agentic-browser) · **分支：** `dev`
---
## 为什么存在
传统的堆栈将**原始 HTML** 或脆弱的 CSS 交给模型。代理需要：
1. **小型、结构化的观察** （角色、标签、引用）
2. **意味着成功的动作** （URL/DOM 结果，而不是“没有异常”）
3. **一种方式来插入任何主机** （MCP + OpenAI/Anthropic 工具模式）
代理浏览器是为此循环而构建的。
```text
导航 → 观察（~1–2k tokens）→ 点击文本 / 输入 → 结果验证？
↘ 如果页面门 = 挑战 → 停止（不要妄想）
```
---
## 亮点 - 测量的正面结果
来自公共网站的实时基准测试（大约 token ≈ 字符/4）。使用 `examples/` 下的脚本重现。
### 令牌效率（LLM 馈送）
| 场景 | 原始 HTML → 模型 | 我们精简的观察 / 结构化馈送 | **减少** |
|----------|-----------------:|------------------------------------------:|--------------:|
| 引用抓取（结构化答案） | ~2.8k–6.2k | ~0.45k–1.3k | **~78–84% 更少的令牌** |
| 洛克星 GTA VI 着陆页 | ~**225,000** | ~**1,300** | **~99.4% 更少的令牌** |
| GitHub `vercel/next.js` | ~**110,000** | ~**1,900** | **~98.3% 更少的令牌** |
**总结：** 将 HTML 转储到 LLM 中是错误的选择。**观察模式在重型现代页面上小 ~98–99%**
### 任务质量
| 指标 | 传统 HTTP + BS4 | 代理浏览器 | 备注 |
|--------|------------------------|-----------------|--------|
| 引用抓取字段完整性 | **100%** （使用站点 CSS） | **100%** | 友好站点上的同等性能 |
| 纯文本“LLM 抓取”完整性 | **0%** 标签丢失 | **100%** 通过工具 | 文本转储会丢失结构 |
| GitHub 仓库上的内容信号 | **~70%** | **~80%** | 在 JS + 观察后略有优势 |
| 可操作元素引用 | **0** | **20–90+** 每页 | 只有我们可以按引用点击 |
| GitHub“打开问题”（v0.3.2 后） | N/A | **验证** → URL `/issues` | 结果检查，而不是假阳性 |
| 网络 / XHR 可见性 | **0%** | 完整的请求日志 + GraphQL 标志 | 代理可以等待 API |
### 产品完整性
| 领域 | 覆盖率 |
|------|----------|
| 里程碑路线图 M1–M10 | **100%** 计划的里程碑交付（以及代理原生 v0.3–0.4） |
| `dev` 上的自动测试 | **118 通过** （完整套件） |
| 主机的 MCP 工具 | **10 个工具** （导航、观察、点击、输入、等待、查找、网络等） |
| 观察令牌预算（默认） | **~2,000** （可配置） |
### 优点一览
- **~98–99%** 与原始 HTML 相比，在复杂着陆页上减少令牌（洛克星，GitHub）
- **~78–84%** 与 HTML 相比，在结构化提取任务中减少令牌
- **100%** 与最佳情况下的 CSS 解析器在演示站点上具有结构化字段同等性能
- **结果验证** - 仅当后置条件成立时才为“确定”（例如 URL 中的 `/issues`）
- **范围接地** - 导航优先查找，以便 PR/提交文本不会窃取“Issues”
- **页面门** - 检测并报告 `js_challenge` / 验证码 / 登录墙
- **MCP 就绪** - Claude Desktop、Cursor、任何 MCP 主机
- **OpenAI + Anthropic 工具模式** - `tools_as_openai()` / `tools_as_anthropic()`
- Cookie/CMP 拒绝、SPA 结算预算、过期引用恢复、网络智能
- 隐私默认值：在网络日志中屏蔽 `Authorization` / cookie
---
## 瓶颈和缺点（不粉饰）
我们衡量这些，以便您不会盲目发货。
| 问题 | 现实 | 影响 |
|-------|---------|--------|
| **延迟** | 真实浏览器 **~6–16×** 慢于 `httpx` 在同一 URL | 对高 QPS 爬虫不利；对代理步骤来说不错 |
| **机器人墙** | Reddit 类 JS 挑战：**两者** HTTP 和浏览器获得 **~17%** 内容信号 | **不是绕过工具** - 我们显示 `page_gate` 并停止 |
| **SSR 仅读** | 在某些营销页面上，普通 HTTP 已经有副本 | 代理在**动作**上获胜，不总是纯读取速度 |
| **完整语义快照** | 如果您转储所有内容，可能会**大于** HTML | 始终使用 **`observe()`**，而不是完整树，为 LLMs |
| **速度与设计目标** | 亚 500 毫秒动作延迟在重型 SPA 上 **未** 实现 | 受页面加载 + 结算支配，而不是 Python |
| **历史错误成功** | v0.3.2 之前的 GitHub “问题”点击可能会在不导航的情况下报告成功 | **修复**，结果验证 + GitHub 技能 |
| **技能覆盖** | GitHub 标签技能是一流的；其他领域需要软件包 | 在 `agent/skills/` 下可扩展 |
| **视觉** | OCR 可选；不在默认观察循环中 | 画布繁重的 UI 仍然较弱 |
**诚实的产品线：**
作为 **LLM 动作 + 紧凑感知层** 最佳。
不是批量 HTTP 解析的替代品，也不是验证码解决器。
---
## 架构
```text
┌──────────────────────────────────────────────────────┐
│ Claude · Cursor · LangGraph · OpenAI 工具循环 │
└──────────────────────────┬───────────────────────────┘
│ MCP stdio 或 函数工具
▼
┌──────────────────────────────────────────────────────┐
│ 代理浏览器 MCP · tools_as_openai() │
│ AgentSession：观察 · 点击文本 · 等待 · 网络 │
└──────────────────────────┬───────────────────────────┘
▼
┌──────────────────────────────────────────────────────┐
│ 语义 DOM · 范围接地 · 结果 · 门 │
│ 网络监视器 · 内存 · 结算 · 叠加层拒绝 │
└──────────────────────────┬───────────────────────────┘
▼
Playwright · Chromium
```
---
## 安装
### 要求
- **Python 3.11+**
- Git
- ~Windows / macOS / Linux
### 从 PyPI（推荐）
PyPI 包名为 **`agentic-browser`** （导入和 CLI 保持 `agent_browser` / `agent-browser`）。
```bash
pip install agentic-browser
playwright install chromium
# 带有 MCP 额外功能的
pip install "agentic-browser[mcp]"
# 带有视觉/OCR 额外功能的
pip install "agentic-browser[vision]"
```
### 从源码（库 + 开发）
```bash
git clone https://github.com/applejuice093/Agentic-browser.git
cd Agentic-browser
git checkout main
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS / Linux
# source .venv/bin/activate
pip install -e ".[dev]"
playwright install chromium
pytest -q
```
### 使用源码从 MCP（Claude / Cursor）
```bash
pip install -e ".[mcp,dev]"
playwright install chromium
```
### 可选视觉从源码（本地 OCR）
```bash
pip install -e ".[vision]"
# 安装系统 Tesseract；设置 Windows 上的 TESSERACT_CMD
```
### 额外功能总结
| 额外功能 | 安装 | 提供 |
|-------|---------|----------|
| 默认 | `pip install agentic-browser` 或 `pip install -e .` | 核心浏览器 + 代理 API |
| `mcp` | `pip install "agentic-browser[mcp]"` | 主机的 MCP 服务器 |
| `dev` | `pip install -e ".[dev]"` | pytest, ruff, mypy |
| `vision` | `pip install "agentic-browser[vision]"` | Pillow + pytesseract |
| `all` | `pip install "agentic-browser[all]"` 或 `pip install -e ".[all]"` | 所有功能 |
---
## 添加到您的代理（3 种方式）
### A) MCP — Claude Desktop / Cursor（**推荐**）
```bash
python -m agent_browser.mcp
# 或
agent-browser-mcp
```
**Cursor** — `.cursor/mcp.json` （使用 **您的** 虚拟环境 Python 路径）：
```json
{
"mcpServers": {
"agent-browser": {
"command": "C:\\A\\PROJECT\\Agentic Browser\\.venv\\Scripts\\python.exe",
"args": ["-m", "agent_browser.mcp"],
"env": {
"AGENT_BROWSER_HEADLESS": "true",
"AGENT_BROWSER_MAX_TOKENS": "2000",
"AGENT_BROWSER_ALLOWED_HOSTS": "github.com,example.com,quotes.toscrape.com"
}
}
}
}
```
**Claude Desktop** — `claude_desktop_config.json`:
```json
{
"mcpServers": {
"agent-browser": {
"command": "C:\\A\\PROJECT\\Agentic Browser\\.venv\\Scripts\\python.exe",
"args": ["-m", "agent_browser.mcp"],
"env": { "AGENT_BROWSER_HEADLESS": "true" }
}
}
}
```
完整指南（环境变量、系统提示、故障排除）： **[`docs/mcp.md`](./docs/mcp.md)**
### B) Python 库
```python
import asyncio
from agent_browser import Browser, tools_as_openai
async def main():
async with Browser(headless=True) as browser:
agent = await browser.open_agent("https://github.com/vercel/next.js")
obs = await agent.observe(max_tokens=2000)
if obs.page_gate not in (None, "open", "cookie_wall", "unknown"):
print("Blocked:", obs.page_gate, obs.page_gate_hint)
return
result = await agent.click_text("Issues", scope="nav", intent="issues")
print(result.ok, result.url_after, result.outcome_verified)
asyncio.run(main())
```
OpenAI / Anthropic 工具模式:
```python
from agent_browser import tools_as_openai, tools_as_anthropic
tools = tools_as_openai() # 聊天完成
# tools = tools_as_anthropic() # 消息 API
```
### C) CLI
```bash
agent-browser version
agent-browser open https://example.com
agent-browser scrape https://example.com -o data/out.json
```
---
## 核心概念
| 概念 | 含义 |
|---------|---------|
| **引用** | 点击/输入的稳定整数 ID（来自 `observe`） |
| **观察** | 紧凑的 LLM 负载：交互引用、标题、摘要、门、网络提示 |
| **动作结果** | `ok`、`error_code`、`outcome_verified`、`url_after`、可选的新观察 |
| **页面门** | `open` \| `js_challenge` \| `captcha` \| `login_wall` \| … |
| **范围** | `nav` / `main` / `form` — 查找/点击的定位区域 |
### MCP / 工具表面
`browser_navigate` · `browser_observe` · `browser_click` · `browser_click_text` · `browser_type` · `browser_wait` · `browser_find` · `browser_network` · `browser_resync` · `browser_prepare`
---
## 环境变量
| 变量 | 默认值 | 目的 |
|----------|---------|---------|
| `AGENT_BROWSER_HEADLESS` | `true` | 无头 Chromium |
| `AGENT_BROWSER_MAX_TOKENS` | `2000` | 观察预算 |
| `AGENT_BROWSER_DETAIL` | `normal` | `sparse` \| `normal` \| `full` |
| `AGENT_BROWSER_SETTLE_MS` | `8000` | SPA 结算预算 |
| `AGENT_BROWSER_ALLOWED_HOSTS` | _(all)_ | 以逗号分隔的允许列表 |
| `AGENT_BROWSER_DEFAULT_TIMEOUT_MS` | `30000` | 动作超时 |
| `TESSERACT_CMD` | — | OCR 二进制路径（视觉额外） |
---
## 项目布局
```text
src/agent_browser/
browser.py / page.py / cli.py
agent/ # AgentSession, MCP 工具桥, 结算, 叠加层, 接地, 结果, 技能
mcp/ # FastMCP stdio 服务器
observation/ # 紧凑的观察构建器
semantic/ accessibility/ events/ network/ vision/ memory/ planning/
docs/
mcp.md # 添加到您的代理（MCP + 工具）
USER_GUIDE.md
agent-native-loop.md
security.md
examples/
agent_loop_demo.py
openai_tool_agent.py
mcp_config_cursor.json
benchmark_hard_site.py
compare_rockstar_vi.py
tests/ # 118+ 自动测试
```
---
## 开发
```bash
git checkout dev
pip install -e ".[dev,mcp]"
playwright install chromium
pytest -q
ruff check src tests
```
| 文档 | 主题 |
|-----|--------|
| [`docs/mcp.md`](./docs/mcp.md) | **安装到您的代理（MCP + 工具）** |
| [`docs/USER_GUIDE.md`](./docs/USER_GUIDE.md) | 完整产品指南 |
| [`docs/agent-native-loop.md`](./docs/agent-native-loop.md) | 观察 / 动作 / 门 / 技能 |
| [`docs/security.md`](./docs/security.md) | 安全说明 |
| [`CHANGELOG.md`](./CHANGELOG.md) | 版本历史 |
| [`deep-research-report.md`](./deep-research-report.md) | 原始设计研究 |
---
## 路线图状态
| 跟踪 | 状态 |
|-------|--------|
| M1–M10 基础 | **完成** |
| 代理原生循环（v0.3） | **完成** |
| 叠加层 / 结算 / 恢复（v0.3.1） | **完成** |
| 接地 + 结果 + GitHub 技能（v0.3.2） | **完成** |
| MCP 主机集成（v0.4.0） | **完成** |
| 更多领域技能、视觉循环、池/扩展 | 下一步 |
---
---
## 许可证
MIT — 见 [LICENSE](./LICENSE)。
<p align="center">
<b>小型观察。真正的点击。验证结果。</b><br/>
<sub>代理浏览器 · 为需要在网络上采取行动的 LLM 而构建</sub>
</p>
