gui-agent-vlm 0.1.0__tar.gz

gui_agent_vlm-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.env

gui_agent_vlm-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 守一
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gui_agent_vlm-0.1.0/PKG-INFO

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: gui-agent-vlm
+Version: 0.1.0
+Summary: GUI 自动化编排器 — 让 AI 通过纯视觉理解操作任何界面
+Project-URL: Homepage, https://github.com/xyshanren/browser-agent
+Project-URL: Source, https://github.com/xyshanren/browser-agent
+Project-URL: Documentation, https://github.com/xyshanren/browser-agent/blob/main/README.md
+Author-email: 守一 <lixy2017@aliyun.com>
+License: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: openai>=1.61.0
+Requires-Dist: pillow>=11.0.0
+Requires-Dist: playwright>=1.50.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: tenacity>=9.0.0
+Provides-Extra: all
+Requires-Dist: mcp>=1.0.0; extra == 'all'
+Requires-Dist: mss>=10.0.0; extra == 'all'
+Requires-Dist: ollama>=0.4.0; extra == 'all'
+Requires-Dist: playwright-stealth>=1.0.6; extra == 'all'
+Requires-Dist: pynput>=1.8.0; extra == 'all'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Provides-Extra: manop
+Requires-Dist: mss>=10.0.0; extra == 'manop'
+Requires-Dist: pynput>=1.8.0; extra == 'manop'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
+Provides-Extra: ollama
+Requires-Dist: ollama>=0.4.0; extra == 'ollama'
+Provides-Extra: stealth
+Requires-Dist: playwright-stealth>=1.0.6; extra == 'stealth'
+Description-Content-Type: text/markdown
+
+# Browser-Agent
+
+<div align="center">
+
+**GUI 自动化编排器 — 让 AI 通过纯视觉理解操作任何界面**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](pyproject.toml)
+[![Playwright](https://img.shields.io/badge/Playwright-1.50+-green.svg)](pyproject.toml)
+[![MCP](https://img.shields.io/badge/MCP-ready-purple.svg)](SKILL.md)
+
+</div>
+
+---
+
+## 快速开始
+
+```bash
+pip install browser-agent
+playwright install chromium
+```
+
+### 使用
+
+```python
+from browser_agent import BrowserAgent
+
+# 自动检测可用模型（Mano-P > Ollama > vLLM > LM Studio）
+agent = BrowserAgent()
+result = agent.run("搜索今天深圳的天气并告诉我结果")
+print(result.text)
+```
+
+或通过 CLI：
+```bash
+browser-agent "搜索今天深圳的天气"
+```
+
+### 指定模型
+
+```bash
+browser-agent --model-type ollama --model qwen3-vl:2b "搜索深圳天气"
+browser-agent --model-type openai --model gpt-4o --api-key sk-xxx "搜索深圳天气"
+browser-agent --model-type manop "搜索深圳天气"  # Mano-P 云端
+```
+
+## 架构
+
+```
+Agent (高层规划)
+  │  "帮我查天气、整理文件、发邮件"
+  ▼
+browser-agent (编排器 + ModelRouter 自动选模型)
+  │  Observe → Think → Act → Verify
+  │
+  ├── PlaywrightExecutor (浏览器)
+  │   └── 通过 VLM 截图理解 + 操作
+  │
+  └── ManoPExecutor (桌面 GUI)
+      └── 纯视觉定位（Mano-P 云端 API）
+```
+
+- **执行器可插拔** — Playwright（Web）/ Mano-P（桌面 GUI）
+- **模型自动检测** — Mano-P → Ollama → vLLM → LM Studio 自动回退
+- **三种调用方式** — CLI / Python API / MCP Server
+
+## 跨平台支持
+
+browser-agent 是纯 Python 项目，依赖全部跨平台，支持 **Linux、Windows、macOS**。
+
+### 平台兼容性矩阵
+
+| 场景 | Linux 原生 | WSL2 | Windows 原生 | macOS |
+|------|-----------|------|-------------|-------|
+| Playwright headless | ✅ | ✅ | ✅ | ✅ |
+| Playwright headed | ✅ Xvfb/X11 | ✅ WSLg(Win11)/Xvfb(Win10) | ✅ | ✅ |
+| Ollama 本地 VLM | ✅ | ✅ | ✅ | ✅ |
+| vLLM GPU | ✅ 最优 | ⚠️ GPU 穿透复杂 | ⚠️ CUDA | ⚠️ Metal |
+| LM Studio | ❌ | ❌ | ✅ | ✅ |
+| Mano-P 桌面 GUI | ❌ | ❌ | ❌ | ✅ MLX |
+
+### WSL2 中使用（Hermes Agent 典型场景）
+
+Hermes Agent 运行在 WSL2 中时，browser-agent 可直接装在 WSL2 内使用：
+
+```bash
+# WSL2 中安装
+pip install browser-agent playwright
+playwright install chromium
+playwright install-deps chromium   # 安装 Linux 系统依赖
+
+# 使用（headless 模式，无需显示环境）
+browser-agent "搜索今天深圳的天气"
+```
+
+**headless 模式完全不需要显示环境**，Playwright 在 WSL2 中运行无任何障碍。
+
+如需查看浏览器窗口（调试用）：
+- **Windows 11**: WSLg 自动支持，`--no-headless` 即可
+- **Windows 10**: 需安装 X 服务器（如 VcXsrv），设置 `DISPLAY=:0`
+
+### 跨平台调用（WSL2 Hermes → Windows browser-agent）
+
+如果需要在 WSL2 中调用 Windows 原生桌面上的浏览器或 Mano-P：
+
+```bash
+# 方案 1: 全部在 WSL2 内完成（推荐）
+# browser-agent 在 WSL2 中启动自己的 Chromium 进程，无需操作 Windows 浏览器
+browser-agent "搜索深圳天气"
+
+# 方案 2: 通过 MCP 桥接 Windows
+# Windows 上启动 MCP Server
+# PowerShell: browser-agent-mcp
+# WSL2 中的 Hermes 通过 host.docker.internal:PORT 连接
+```
+
+> **关键理解**: Playwright 启动的是自己管理的 Chromium 实例，不是操作"系统上已经打开的浏览器"。因此 WSL2 里的 browser-agent 无需与 Windows 端的浏览器交互——它自己在 WSL2 中启动 Chromium 即可。
+
+## 模型选择
+
+browser-agent 内置 ModelRouter，自动检测可用 VLM：
+
+| 优先级 | 模型源 | 如何启用 |
+|--------|--------|----------|
+| P0 | 用户显式指定 | `--model-type` / `--model` 参数 |
+| P1 | Ollama | 运行 `ollama serve` + 拉取 VLM 模型 |
+| P2 | vLLM | `vllm serve Qwen/Qwen2.5-VL-* --port 8000` |
+| P3 | LM Studio | 启动并加载 VLM 模型 |
+| P4 | Agent 注入 | 设置 `BROWSER_AGENT_FALLBACK_*` 环境变量 |
+
+Mano-P 云端 API 也已集成，代码就绪，但需要明略科技提供的 API key（`MANOP_API_KEY`），目前暂未开放注册。有 key 后可作为显式指定使用：`--model-type manop`。
+
+任何 AI Agent 可以通过环境变量将自己的模型注入 browser-agent：
+
+```bash
+export BROWSER_AGENT_FALLBACK_MODEL_TYPE=openai
+export BROWSER_AGENT_FALLBACK_MODEL=gpt-4o
+export BROWSER_AGENT_FALLBACK_API_KEY=sk-xxx
+```
+
+## MCP Server
+
+browser-agent 内置 MCP Server，可被任何 MCP 兼容客户端调用：
+
+```json
+{
+  "mcpServers": {
+    "browser-agent": {
+      "command": "python",
+      "args": ["-m", "browser_agent.mcp_server"]
+    }
+  }
+}
+```
+
+支持工具：`browser_navigate` / `browser_screenshot` / `browser_click` / `browser_type` / `browser_extract`
+
+## 作为 Agent Skill 使用
+
+参阅 [SKILL.md](SKILL.md) — 支持 CLI、Python API、MCP Server 三种集成方式。
+
+## Mano-P 集成
+
+Mano-P 是明略科技开源的 GUI-VLA 模型，代码已集成，但暂未默认启用。
+
+| 场景 | 方案 | 状态 |
+|:----|:------|:----:|
+| Web 浏览器 | PlaywrightExecutor + 本地 VLM | ✅ 生产可用 |
+| 桌面软件/3D/专业工具 | ManoPExecutor + Mano-P Cloud API | ⚠️ 代码就绪，需 `MANOP_API_KEY`（暂未开放注册） |
+| Mano-P 本地推理 | 直接在本地运行模型 | ⏳ 仅 macOS Apple Silicon，等待 NVIDIA CUDA 开源 |
+
+> 注意：Mano-P 不在自动检测队列中。持有了 `MANOP_API_KEY` 后通过 `--model-type manop` 显式指定即可使用。
+
+## 测试
+
+```bash
+pytest tests/ -v
+```
+
+## 许可证
+
+MIT

gui_agent_vlm-0.1.0/README.md

@@ -0,0 +1,182 @@
+# Browser-Agent
+
+<div align="center">
+
+**GUI 自动化编排器 — 让 AI 通过纯视觉理解操作任何界面**
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/Python-3.11+-blue.svg)](pyproject.toml)
+[![Playwright](https://img.shields.io/badge/Playwright-1.50+-green.svg)](pyproject.toml)
+[![MCP](https://img.shields.io/badge/MCP-ready-purple.svg)](SKILL.md)
+
+</div>
+
+---
+
+## 快速开始
+
+```bash
+pip install browser-agent
+playwright install chromium
+```
+
+### 使用
+
+```python
+from browser_agent import BrowserAgent
+
+# 自动检测可用模型（Mano-P > Ollama > vLLM > LM Studio）
+agent = BrowserAgent()
+result = agent.run("搜索今天深圳的天气并告诉我结果")
+print(result.text)
+```
+
+或通过 CLI：
+```bash
+browser-agent "搜索今天深圳的天气"
+```
+
+### 指定模型
+
+```bash
+browser-agent --model-type ollama --model qwen3-vl:2b "搜索深圳天气"
+browser-agent --model-type openai --model gpt-4o --api-key sk-xxx "搜索深圳天气"
+browser-agent --model-type manop "搜索深圳天气"  # Mano-P 云端
+```
+
+## 架构
+
+```
+Agent (高层规划)
+  │  "帮我查天气、整理文件、发邮件"
+  ▼
+browser-agent (编排器 + ModelRouter 自动选模型)
+  │  Observe → Think → Act → Verify
+  │
+  ├── PlaywrightExecutor (浏览器)
+  │   └── 通过 VLM 截图理解 + 操作
+  │
+  └── ManoPExecutor (桌面 GUI)
+      └── 纯视觉定位（Mano-P 云端 API）
+```
+
+- **执行器可插拔** — Playwright（Web）/ Mano-P（桌面 GUI）
+- **模型自动检测** — Mano-P → Ollama → vLLM → LM Studio 自动回退
+- **三种调用方式** — CLI / Python API / MCP Server
+
+## 跨平台支持
+
+browser-agent 是纯 Python 项目，依赖全部跨平台，支持 **Linux、Windows、macOS**。
+
+### 平台兼容性矩阵
+
+| 场景 | Linux 原生 | WSL2 | Windows 原生 | macOS |
+|------|-----------|------|-------------|-------|
+| Playwright headless | ✅ | ✅ | ✅ | ✅ |
+| Playwright headed | ✅ Xvfb/X11 | ✅ WSLg(Win11)/Xvfb(Win10) | ✅ | ✅ |
+| Ollama 本地 VLM | ✅ | ✅ | ✅ | ✅ |
+| vLLM GPU | ✅ 最优 | ⚠️ GPU 穿透复杂 | ⚠️ CUDA | ⚠️ Metal |
+| LM Studio | ❌ | ❌ | ✅ | ✅ |
+| Mano-P 桌面 GUI | ❌ | ❌ | ❌ | ✅ MLX |
+
+### WSL2 中使用（Hermes Agent 典型场景）
+
+Hermes Agent 运行在 WSL2 中时，browser-agent 可直接装在 WSL2 内使用：
+
+```bash
+# WSL2 中安装
+pip install browser-agent playwright
+playwright install chromium
+playwright install-deps chromium   # 安装 Linux 系统依赖
+
+# 使用（headless 模式，无需显示环境）
+browser-agent "搜索今天深圳的天气"
+```
+
+**headless 模式完全不需要显示环境**，Playwright 在 WSL2 中运行无任何障碍。
+
+如需查看浏览器窗口（调试用）：
+- **Windows 11**: WSLg 自动支持，`--no-headless` 即可
+- **Windows 10**: 需安装 X 服务器（如 VcXsrv），设置 `DISPLAY=:0`
+
+### 跨平台调用（WSL2 Hermes → Windows browser-agent）
+
+如果需要在 WSL2 中调用 Windows 原生桌面上的浏览器或 Mano-P：
+
+```bash
+# 方案 1: 全部在 WSL2 内完成（推荐）
+# browser-agent 在 WSL2 中启动自己的 Chromium 进程，无需操作 Windows 浏览器
+browser-agent "搜索深圳天气"
+
+# 方案 2: 通过 MCP 桥接 Windows
+# Windows 上启动 MCP Server
+# PowerShell: browser-agent-mcp
+# WSL2 中的 Hermes 通过 host.docker.internal:PORT 连接
+```
+
+> **关键理解**: Playwright 启动的是自己管理的 Chromium 实例，不是操作"系统上已经打开的浏览器"。因此 WSL2 里的 browser-agent 无需与 Windows 端的浏览器交互——它自己在 WSL2 中启动 Chromium 即可。
+
+## 模型选择
+
+browser-agent 内置 ModelRouter，自动检测可用 VLM：
+
+| 优先级 | 模型源 | 如何启用 |
+|--------|--------|----------|
+| P0 | 用户显式指定 | `--model-type` / `--model` 参数 |
+| P1 | Ollama | 运行 `ollama serve` + 拉取 VLM 模型 |
+| P2 | vLLM | `vllm serve Qwen/Qwen2.5-VL-* --port 8000` |
+| P3 | LM Studio | 启动并加载 VLM 模型 |
+| P4 | Agent 注入 | 设置 `BROWSER_AGENT_FALLBACK_*` 环境变量 |
+
+Mano-P 云端 API 也已集成，代码就绪，但需要明略科技提供的 API key（`MANOP_API_KEY`），目前暂未开放注册。有 key 后可作为显式指定使用：`--model-type manop`。
+
+任何 AI Agent 可以通过环境变量将自己的模型注入 browser-agent：
+
+```bash
+export BROWSER_AGENT_FALLBACK_MODEL_TYPE=openai
+export BROWSER_AGENT_FALLBACK_MODEL=gpt-4o
+export BROWSER_AGENT_FALLBACK_API_KEY=sk-xxx
+```
+
+## MCP Server
+
+browser-agent 内置 MCP Server，可被任何 MCP 兼容客户端调用：
+
+```json
+{
+  "mcpServers": {
+    "browser-agent": {
+      "command": "python",
+      "args": ["-m", "browser_agent.mcp_server"]
+    }
+  }
+}
+```
+
+支持工具：`browser_navigate` / `browser_screenshot` / `browser_click` / `browser_type` / `browser_extract`
+
+## 作为 Agent Skill 使用
+
+参阅 [SKILL.md](SKILL.md) — 支持 CLI、Python API、MCP Server 三种集成方式。
+
+## Mano-P 集成
+
+Mano-P 是明略科技开源的 GUI-VLA 模型，代码已集成，但暂未默认启用。
+
+| 场景 | 方案 | 状态 |
+|:----|:------|:----:|
+| Web 浏览器 | PlaywrightExecutor + 本地 VLM | ✅ 生产可用 |
+| 桌面软件/3D/专业工具 | ManoPExecutor + Mano-P Cloud API | ⚠️ 代码就绪，需 `MANOP_API_KEY`（暂未开放注册） |
+| Mano-P 本地推理 | 直接在本地运行模型 | ⏳ 仅 macOS Apple Silicon，等待 NVIDIA CUDA 开源 |
+
+> 注意：Mano-P 不在自动检测队列中。持有了 `MANOP_API_KEY` 后通过 `--model-type manop` 显式指定即可使用。
+
+## 测试
+
+```bash
+pytest tests/ -v
+```
+
+## 许可证
+
+MIT

gui_agent_vlm-0.1.0/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: browser-agent
+description: 浏览器/桌面 GUI 自动化工具。通过纯视觉理解操作界面，支持搜索、填表、数据抓取等任务。支持自动检测本地 VLM / Mano-P 云端 API / Agent 模型注入三种模型源。
+version: 1.2.0
+author: xyshanren
+license: MIT
+metadata:
+  hermes:
+    tags: [Browser-Automation, GUI-VLA, Web-Scraping, Vision-Language-Model, MCP]
+    related_skills: [cli, web-development]
+    homepage: https://github.com/xyshanren/browser-agent
+  mcp:
+    server_name: browser-agent
+    tools: [browser_navigate, browser_screenshot, browser_click, browser_type, browser_extract]
+prerequisites:
+  commands: [python3, pip3]
+  env_vars: []
+  run_once:
+    - command: pip3 install browser-agent playwright
+      description: 安装 browser-agent 及其依赖
+    - command: python3 -m playwright install chromium
+      description: 安装 Playwright 浏览器引擎
+    - command: pip3 install "browser-agent[mcp]"
+      description: 安装 MCP 支持（可选）
+required_environment_variables: []
+---
+
+# Browser-Agent: GUI 自动化工具
+
+通过 AI 视觉理解自动操作浏览器/桌面界面。支持：
+- 🌐 网页搜索、数据抓取、表单填写
+- 📊 提取结构化数据（表格、列表、价格）
+- 🔄 多步骤任务编排（先查天气、再搜索、最后汇总）
+- 🖥️ 浏览器操作（点击、输入、滚动、导航）
+
+## 工作原理
+
+```
+用户输入任务 → ModelRouter 自动选模型 → 截图观察页面 → VLM 理解内容 → 规划操作 → 执行操作 → 返回结果
+```
+
+模型选择（无需手动配置，自动检测）：
+
+| 优先级 | 模型源 | 检测方式 |
+|--------|--------|----------|
+| P0 | 显式指定 | `--model-type` / `--model` 参数 |
+| P1 | 本地 VLM (Ollama / vLLM / LM Studio) | 自动 ping localhost 端口 |
+| P2 | Agent 模型注入 | `BROWSER_AGENT_FALLBACK_*` 环境变量 |
+
+Mano-P 云端 API 也已集成（代码就绪，需 `MANOP_API_KEY`），有 key 后通过 `--model-type manop` 显式指定即可。
+
+## 使用方法
+
+### 基础任务
+
+```terminal
+browser-agent "搜索今天深圳的天气"
+```
+
+### 显示浏览器窗口（调试用）
+
+```terminal
+browser-agent --no-headless "帮我登录 GitHub 检查通知"
+```
+
+### 流式查看每一步
+
+```terminal
+browser-agent --stream "搜索 Python 3.13 新特性并总结"
+```
+
+### 使用不同模型
+
+不指定模型时，ModelRouter 自动检测可用模型：
+
+```terminal
+# 自动检测：Mano-P > Ollama > vLLM > LM Studio > Agent 注入
+browser-agent "搜索今天深圳的天气"
+```
+
+也支持手动指定：
+
+```terminal
+# 本地 vLLM
+browser-agent --model-type vllm --model "Qwen/Qwen2.5-VL-3B-Instruct" --api-base "http://localhost:8000/v1" "..."
+
+# OpenAI API
+browser-agent --model-type openai --model gpt-4o --api-key "sk-xxx" "..."
+
+# Mano-P 云端（GUI专用）
+browser-agent --model-type manop "..."
+```
+
+### Python 集成
+
+```python
+from browser_agent import BrowserAgent
+
+# 自动检测模型
+agent = BrowserAgent()
+result = agent.run("打开百度，搜索今天深圳的天气，告诉我温度和湿度")
+
+# 显式指定模型
+agent = BrowserAgent(model_type="ollama", model="qwen3-vl:2b")
+result = agent.run("搜索深圳天气")
+print(result.text)
+```
+
+## 多步骤编排
+
+对于复杂任务，Hermes Agent 可以分步调用 browser-agent：
+
+```terminal
+# 步骤 1: 收集信息
+browser-agent "打开百度，搜索深圳今天天气，提取温度和风力"
+
+# 步骤 2: 对比分析（基于步骤 1 的结果继续）
+browser-agent "打开百度，搜索广州今天天气，和深圳对比"
+
+# 或使用 Python 一次性编排
+python -c "
+from browser_agent import BrowserAgent
+a = BrowserAgent()
+r1 = a.run('搜索深圳天气')
+print('深圳:', r1.text)
+r2 = a.run('搜索广州天气')
+print('广州:', r2.text)
+print('综合:', r1.text, r2.text)
+"
+```
+
+## 注意事项
+
+1. **模型自动选择**: 不指定模型时，ModelRouter 按 P1→P2→P3 优先级自动检测。可用 `--model-type` 显式覆盖。
+2. **本地 VLM**: 如使用本地模型，需先安装并运行 Ollama / vLLM / LM Studio。Ollama: `ollama pull qwen3-vl:2b && ollama serve`
+3. **Mano-P 云端**: 设置 `MANOP_API_KEY` 环境变量即可启用，无需本地 GPU。
+4. **Agent 模型注入**: 调用方可设置 `BROWSER_AGENT_FALLBACK_*` 环境变量传递备选模型，仅 VLM 模型有效。
+5. **headless 模式（默认）**: 浏览器在后台运行，不显示窗口。
+6. **耗时任务**: 模型推理需要时间，每步约 5-15 秒。
+7. **反爬检测**: 部分网站可能拦截自动化操作，可尝试 `--no-headless` 降低被检测概率。
+
+### 跨平台说明
+
+browser-agent 是纯 Python 项目，**Android 和 iOS 除外**，主流平台均可运行：
+
+| 平台 | Playwright headless | Playwright headed | Ollama | 备注 |
+|------|-------------------|-------------------|--------|------|
+| Linux 原生 | ✅ | ✅ 需 Xvfb/X11 | ✅ | 服务器部署首选 |
+| WSL2 | ✅ | ✅ WSLg(Win11)/Xvfb(Win10) | ✅ | Hermes Agent 典型场景 |
+| Windows 原生 | ✅ | ✅ | ✅ | 桌面自动化首选 |
+| macOS | ✅ | ✅ | ✅ | 开发调试友好 |
+
+**WSL2 关键说明**：Playwright 在 WSL2 中 headless 模式运行无需任何额外配置。Hermes Agent 与 browser-agent 都装在 WSL2 内即可正常使用。Mano-P（桌面 GUI 自动化）目前仅支持 macOS Apple Silicon，Windows/Linux 暂不支持，等待其第三阶段开源。详见 [跨平台支持](README.md#跨平台支持)。
+
+---
+
+## MCP Server 模式
+
+browser-agent 内置 MCP Server，可以被**任何 MCP 兼容客户端**调用：
+
+### Claude Desktop 配置
+
+```json
+// Windows: %APPDATA%\Claude\claude_desktop_config.json
+// macOS: ~/.config/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "browser-agent": {
+      "command": "python",
+      "args": ["-m", "browser_agent.mcp_server"]
+    }
+  }
+}
+```
+
+### Cline / Cursor / Continue 配置
+
+在对应的 MCP settings 中添加：
+
+```json
+{
+  "mcpServers": {
+    "browser-agent": {
+      "command": "python",
+      "args": ["-m", "browser_agent.mcp_server"]
+    }
+  }
+}
+```
+
+### MCP 工具列表
+
+| 工具 | 说明 | 参数 |
+|------|------|------|
+| `browser_navigate` | 执行浏览器任务 | `task` (必填), `headless`, `max_steps` |
+| `browser_screenshot` | 截图当前页面 | `describe` (是否描述内容) |
+| `browser_click` | 点击元素 | `x`, `y` 或 `description` |
+| `browser_type` | 输入文本 | `text` (必填), `submit` |
+| `browser_extract` | 提取结构化数据 | `query` (必填), `format` |
+
+### 使用示例
+
+```
+用户: 帮我搜索一下 GitHub 上的热门 AI 项目
+     ↓ MCP 调用 browser_navigate
+     ↓ Agent 执行任务并返回结果
+```
+
+---
+
+## 多 Agent 共享
+
+browser-agent 作为独立 Python 包，支持被多个 Agent 框架共享：
+
+### 方式 A: pip 安装（推荐）
+
+```bash
+pip install browser-agent
+# 直接 import 使用
+```
+
+### 方式 B: MCP Server（跨框架通用）
+
+任何支持 MCP 的 Agent 框架都能通过 MCP Server 调用 browser-agent。
+
+### 方式 C: Agent 模型注入
+
+调用方可设置环境变量让 browser-agent 使用 Agent 自身的模型（需为 VLM）：
+
+```bash
+export BROWSER_AGENT_FALLBACK_MODEL_TYPE=openai
+export BROWSER_AGENT_FALLBACK_MODEL=gpt-4o
+export BROWSER_AGENT_FALLBACK_API_KEY=sk-xxx
+```