plugins/browser/INSTALL.md

# 安装指南

本插件依赖 Lightpanda 浏览器二进制（`lightpanda mcp` stdio MCP server）。Lightpanda 是轻量无头浏览器，
无需 Chrome/Chromium，适合资源受限的云端服务器。

## 平台支持

| 平台 | 支持 | 说明 |
|---|---|---|
| Linux x86_64 | ✅ 原生 | 下载 nightly 二进制即可 |
| macOS (aarch64) | ✅ 原生 | 下载 nightly 二进制 |
| Windows | ⚠️ 需 WSL2 | Lightpanda 无 Windows 原生二进制 |
| Docker | ✅ | 任意平台经 Docker 运行 |

## Linux / macOS

```bash
# Linux x86_64
curl -L -o /usr/local/bin/lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux \
  && chmod +x /usr/local/bin/lightpanda

# macOS aarch64
curl -L -o /usr/local/bin/lightpanda \
  https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos \
  && chmod +x /usr/local/bin/lightpanda
```

验证：

```bash
lightpanda version
```

## Windows（WSL2）

Lightpanda 无 Windows 原生二进制，需经 WSL2 中转：

```powershell
wsl --install
wsl -e sh -c 'curl -L -o /usr/local/bin/lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && chmod +x /usr/local/bin/lightpanda'
```

注：WSL 路径下探测到的二进制会经 WSL interop 调用，性能略低于 Linux 原生。

## Docker

任意平台均可经 Docker 运行（但本插件目前走 stdio 模式，Docker 的 serve 模式未在 v3 启用）：

```bash
docker run -d -p 9222:9222 lightpanda/browser:nightly
```

## HuggingFace Spaces

Dockerfile 内置 nightly release 下载，无需手动安装。

## 自定义路径

若二进制不在 PATH 中，设置环境变量：

```bash
export LIGHTPANDA_BINARY=/path/to/lightpanda
```

## 故障排查

### 二进制未找到

插件 UI 顶部"Lightpanda 二进制"卡片会显示当前平台对应的安装命令。按提示安装后刷新。

### 二进制存在但不可执行

```bash
chmod +x /usr/local/bin/lightpanda
```

### 版本不兼容

本插件要求 Lightpanda ≥ 0.2.0（支持 `lightpanda mcp` stdio server）。旧版本无 mcp 子命令。

```bash
lightpanda version   # 确认版本
```

### 子进程启动失败

查看子进程 stderr 日志：

```bash
curl http://localhost:7860/plugins/browser/api/process/logs?tail=50
```

或直接读 `data/lightpanda/mcp.log`。常见原因：端口/资源问题、二进制损坏、版本不兼容。