plugins/browser/README.md

# browser

浏览器 MCP 插件（v3.0）：**纯 Lightpanda 单后端透传**，提供 28 个通用浏览器 MCP 工具，
为各环境 agent 暴露与 Lightpanda 上游一致的浏览器能力。

## 设计理念

Lightpanda 的 `lightpanda mcp` 子命令本身就是一个标准 stdio MCP server，自带 28 个工具（27 browser tool + save）
（含 JSON Schema 与标准化错误码）。本插件**不重新发明浏览器语义**，只做四件事：

1. **子进程生命周期**：单例长驻 `lightpanda mcp` 子进程，复用会话，支持链式操作
   （`goto` → `click` → `extract`）。
2. **JSON-RPC 透传**：行分隔协议，`initialize` 握手 + `tools/call` 透传。
3. **run_log 埋点**：每次调用创建 run，记录 init/call/complete/error 事件。
4. **错误码归一**：上游错误归一为 `BrowserError`，前端可据 code 给修复指引。

工具名、参数、返回结构、错误码全部由 Lightpanda 上游决定——平台层零手写 schema、零漂移。

## 为什么纯 Lightpanda

云端服务器资源不足以运行 Chrome。Lightpanda 是轻量无头浏览器，无需 Chrome/Chromium，
适合资源受限环境。Playwright 兜底依赖 Chrome，在本场景下失效，已移除。

## 28 个工具

| 类别 | 工具 |
|---|---|
| 导航 | `browser-goto` `browser-search` `browser-getUrl` |
| 读取 | `browser-markdown` `browser-html` `browser-links` `browser-evaluate` `browser-extract` `browser-tree` `browser-nodeDetails` `browser-interactiveElements` `browser-structuredData` `browser-detectForms` `browser-findElement` `browser-consoleLogs` `browser-getCookies` `browser-getEnv` |
| 交互 | `browser-click` `browser-fill` `browser-scroll` `browser-hover` `browser-press` `browser-selectOption` `browser-setChecked` |
| 等待 | `browser-waitForSelector` `browser-waitForScript` `browser-waitForState` |
| 录制 | `browser-save`（把会话存为可复用 agent 脚本，写磁盘） |

工具名格式为 `browser-{上游名}`（保留 camelCase）；入参统一 `params: dict` 透传给上游，校验由 Lightpanda 负责。
完整参数说明见 `/api/tools` 端点或各工具 description。

## 架构

```
agent ──FastMCP──▶ mcp.py（28 个 @mcp_tool 薄壳）
                       │
                       ▼
                 LightpandaClient（单例长驻）
                   ├─ initialize 握手（一次性）
                   ├─ tools/list 缓存（一次性，漂移校验）
                   └─ tools/call 透传（每次调用）
                       ▼
              ProcessSupervisor（stderr→日志文件）
                       ▼
            lightpanda mcp 子进程（stdio JSON-RPC）
```

```
plugins/browser/
├── plugin.json              元数据 + binary_dependencies
├── main.py                  Plugin 类（on_enable/on_disable/check_readiness/get_status）
├── api.py                   FastAPI 路由
├── mcp.py                   28 个 @mcp_tool（工厂从 tools_meta 生成）
├── frontend/index.html      静态 UI
└── browser/
    ├── binary_locator.py    探测 lightpanda 二进制（env/PATH/常见路径/WSL）
    ├── process_supervisor.py 子进程监管（stderr→文件）
    ├── mcp_client.py        行分隔 JSON-RPC 客户端
    ├── client.py            LightpandaClient 单例
    ├── tools_meta.py        28 工具元数据（27 browser tool + save）
    └── errors.py            BrowserError + 错误码（对齐上游）
```

## 配置

### 环境变量

| 变量 | 默认 | 说明 |
|---|---|---|
| `LIGHTPANDA_BINARY` | 自动探测 | Lightpanda 可执行文件绝对路径 |

### 子进程

- **懒启动**：插件 enable 时不预启动；首次工具调用时拉起子进程并握手。
- **长驻**：子进程持续运行，复用会话；`on_disable` 或 `/process/stop` 时关闭。
- **日志**：stderr 重定向到 `data/lightpanda/mcp.log`（stdio 协议强约束：stderr 不能走 PIPE）。

## 安装

详见 [INSTALL.md](./INSTALL.md)。快速概览：

- **Linux / macOS**：下载 nightly release 二进制
- **Windows**：Lightpanda 无原生二进制，需 WSL2 或 Docker
- **HuggingFace Spaces**：Dockerfile 内置 nightly release

## 使用

### 通过 MCP 客户端（Claude Desktop 等）

插件通过平台 FastMCP 暴露 28 个工具，agent 直接调用 `browser-goto` / `browser-markdown` 等。

### 通过平台 UI

1. 访问 `/tool/browser`
2. 顶部"Lightpanda 二进制"卡片显示状态；未找到时按 OS 显示安装命令
3. "工具调用"面板选工具 + 填参数，点"执行"
4. "运行日志"与"结果"区展示调用过程与返回
5. "健康检查"显示二进制/子进程/工具缓存状态及漂移校验

### 通过 HTTP API

```bash
# 探测二进制
curl http://localhost:7860/plugins/browser/api/binary-check

# 列出工具
curl http://localhost:7860/plugins/browser/api/tools

# 健康检查
curl http://localhost:7860/plugins/browser/api/health

# 调用 goto
curl -X POST http://localhost:7860/plugins/browser/api/mcp/browser-goto \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# 查看子进程日志
curl http://localhost:7860/plugins/browser/api/process/logs?tail=50
```

## 限制

- **Lightpanda 是 Beta**：参考 https://lightpanda.io/#status，部分网站可能不兼容
- **WSL2 局限**：Windows 上 WSL 与主进程通信经 stdin/stdout 转发，可能比 Linux 直接调用慢
- **工具集漂移**：`tools_meta.py` 是静态锚点；上游新增工具时需同步。`/health` 端点提供漂移校验预警

## 故障排查

| 现象 | 原因 | 解决 |
|---|---|---|
| `BINARY_NOT_FOUND` | PATH 中无 lightpanda | 按顶部卡片安装命令安装；或设 `LIGHTPANDA_BINARY` |
| `PROCESS_NOT_READY` | 子进程启动/握手失败 | 查看 `/process/logs`；可能二进制损坏或版本不兼容 |
| `PROTOCOL_TIMEOUT` | 子进程未及时响应 | 增大 timeout；查 `/process/logs` 找根因 |
| `NODE_NOT_FOUND` | selector 未命中元素 | 先用 `browser-tree`/`browser-findElement` 定位元素 |
| `FRAME_NOT_LOADED` | 未先 goto 导航 | 先调 `browser-goto` 加载页面 |

## 变更记录

见 [CHANGELOG](#v30)。v3.0 相对 v2.0：废弃多 driver 抽象与 Playwright/CDP，改为纯 Lightpanda 透传；
工具数 12 → 28（与上游对齐）；修复 v2 多个必现 bug。

### v3.0

- 纯 Lightpanda 单后端，删除 Playwright/CDP/lightpanda_driver/registry/driver 抽象
- 28 个工具从上游 `tools.zig` 静态提取，工厂生成，零手写 schema
- 单例长驻子进程，复用会话
- 修复 v2 的 `mcp_markdown` params.timeout 崩溃、`/binary-check` import 错、registry key 失效等