---
name: opencli
description: 当用户想要与网站交互、浏览网页、提取数据、自动化网络任务或控制浏览器时使用。支持 79+ 平台，包括 Twitter、Amazon、YouTube、Spotify、Bilibili、小红书等。零视觉成本的结构化页面获取，完美适配 AI Agent。
metadata:
  lightclaw:
    emoji: "🌐"
    tags: ["web-automation", "browser-control", "data-extraction"]
---

# OpenCLI Web Automation 🌐

使用 OpenCLI 当：
- 用户想浏览或与网站交互
- 从网页提取数据
- 自动化网络任务（搜索、下载、填表）
- 控制 Electron 应用
- 需要登录后访问受保护资源

## 连接模式说明

OpenCLI 有两种连接 Chrome 的方式：

### 方式 1：CDP 直连（LightClaw 环境下的推荐方式）

LightClaw 通过 Playwright 管理 Chrome，并自动从 `~/.lightclaw/extensions/` 加载已安装的扩展。
OpenCLI 可以通过 `OPENCLI_CDP_ENDPOINT` 直接连接 LightClaw 的 Chrome（端口 18800）：

```bash
# Skill 脚本会自动检测并设置此变量
# 也可手动设置：
export OPENCLI_CDP_ENDPOINT=http://127.0.0.1:18800
opencli operate state
```

**注意**：需要 LightClaw 的浏览器工具先启动 Chrome（用户使用过浏览器功能后会自动启动）。

### 方式 2：浏览器扩展（独立环境）

仅在 LightClaw 之外独立使用 OpenCLI 时需要。

## 首次安装

```bash
python ~/.lightclaw/workspace/skills/opencli/scripts/setup_opencli.py
```

验证（需要 Chrome 已由 LightClaw 启动）：

```bash
OPENCLI_CDP_ENDPOINT=http://127.0.0.1:18800 opencli doctor
```

## 核心工作流

### 第一步：获取页面状态（零成本，无需视觉 Token）⚡

这是最关键的一步！每次都从这里开始。

```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_state.sh "https://example.com"
```

**返回值**：结构化 DOM，带有编号元素
- 立即显示所有可用的按钮、输入框、链接
- **零视觉 Token 成本** ← 关键优势
- 确定性输出（同一 URL 返回相同结构）
- 可本地验证，无需 API 调用

**示例输出**：
```json
{
  "url": "https://news.ycombinator.com",
  "title": "Hacker News",
  "state": {
    "buttons": [
      {"id": 0, "text": "new", "selector": "a.topsel"},
      {"id": 1, "text": "best", "selector": "a[href*=best]"},
      {"id": 2, "text": "best", "selector": "a[href*=newest]"}
    ],
    "inputs": [
      {"id": 10, "type": "text", "name": "search", "selector": "input[name=q]", "placeholder": "search"}
    ],
    "links": [
      {"id": 20, "text": "Guidelines", "href": "https://news.ycombinator.com/newsguidelines.html"},
      {"id": 21, "text": "FAQ", "href": "https://news.ycombinator.com/faq.html"}
    ]
  }
}
```

**关键点**：
- 每个交互元素都有 **id** 号
- 使用这些 id 来引用元素，而不是猜测 CSS 选择器
- 页面变化时需要重新获取状态

### 第二步：执行操作

根据获取的状态，执行具体操作。注意传递的是 id 号，不是选择器！

**点击按钮**：
```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation click \
  --element-id 0
```

**在输入框中输入文本**：
```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation type \
  --element-id 10 \
  --value "search query"
```

**选择下拉框选项**：
```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation select \
  --element-id 5 \
  --value "option_value"
```

**执行 JavaScript 提取数据**：
```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation eval \
  --script 'document.querySelectorAll(".item").map(el => ({
    title: el.querySelector(".title")?.textContent,
    link: el.querySelector("a")?.href,
    score: el.querySelector(".score")?.textContent
  }))'
```

**等待元素加载**：
```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation wait \
  --selector ".loading-complete"
```

**获取页面快照（仅在需要时）**：
```bash
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation screenshot
```

### 第三步：循环迭代

重复步骤 1-2：
1. 获取状态
2. 分析可用选项
3. 执行操作
4. 重复

## 支持的平台（79+）

### 中文平台 🇨🇳
- **短视频**：Bilibili, TikTok, 小红书, 抖音
- **社交**：知乎, 微博, 小红书
- **电商**：1688, 闲鱼, 小鹅通
- **内容**：百度贴吧, 虎扑, 知乎

### 国际平台 🌍
- **社交**：Twitter/X, Reddit, Facebook
- **视频**：YouTube, Netflix, Spotify
- **电商**：Amazon, eBay, Etsy
- **内容**：Medium, Hacker News, Pixiv

### AI 平台 🤖
- ChatGPT, Claude, Gemini, Kimi, 文心一言, 豆包

### 桌面应用 🖥️
- Cursor, VS Code, Discord, Obsidian, Notion

### 开发者工具 ⚙️
- GitHub, Docker, Vercel, Lark, 钉钉, 企业微信

完整列表可运行：
```bash
opencli list
```

## 认证与登录

对于受保护的网站（Gmail、Twitter、Bilibili 等）：

1. **首次登录**：
   - 获取状态，找到登录按钮/链接
   - 点击登录
   - 完成登录流程（可能需要验证码）
   - 之后的操作都将使用已登录会话

2. **会话复用**：
   - 登录后，会话会被持久化
   - 后续操作无需重新登录
   - 即使脚本重启，认证信息也保持有效

3. **处理验证码**：
   ```bash
   # 如果遇到 CAPTCHA，截图查看
   bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
     --operation screenshot
   
   # 可能需要人工干预，或使用 OCR 识别（如果可行）
   ```

## 数据提取模式

### 提取列表数据

```bash
# 获取所有文章的标题和链接
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation eval \
  --script 'Array.from(document.querySelectorAll("article")).map(article => ({
    title: article.querySelector("h2")?.textContent.trim(),
    link: article.querySelector("a")?.href,
    author: article.querySelector(".author")?.textContent.trim(),
    date: article.querySelector(".date")?.textContent.trim()
  }))'
```

### 提取表格数据

```bash
# 将 HTML 表格转换为 JSON
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation eval \
  --script 'const table = document.querySelector("table");
const headers = Array.from(table.querySelectorAll("th")).map(h => h.textContent.trim());
const rows = Array.from(table.querySelectorAll("tbody tr")).map(row =>
  Object.fromEntries(
    Array.from(row.querySelectorAll("td")).map((cell, i) => [headers[i], cell.textContent.trim()])
  )
);
rows'
```

### 提取属性值

```bash
# 获取所有图片的 src
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation eval \
  --script 'Array.from(document.querySelectorAll("img")).map(img => ({
    src: img.src,
    alt: img.alt,
    width: img.width,
    height: img.height
  }))'
```

## 常见场景

### 场景 1：搜索和抓取结果

```bash
# 1. 打开搜索引擎
opencli operate open "https://google.com"

# 2. 获取页面状态
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_state.sh

# 3. 点击搜索框（假设 id=2）和输入
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation type \
  --element-id 2 \
  --value "machine learning"

# 4. 点击搜索按钮（假设 id=5）
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation click \
  --element-id 5

# 5. 等待结果加载
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation wait \
  --selector ".g"

# 6. 获取结果页面状态
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_state.sh

# 7. 提取搜索结果
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation eval \
  --script 'Array.from(document.querySelectorAll(".g")).map(result => ({
    title: result.querySelector("h3")?.textContent,
    url: result.querySelector("a")?.href,
    snippet: result.querySelector(".VwiC3b")?.textContent
  }))'
```

### 场景 2：登录流程

```bash
# 1. 访问受保护网站
opencli operate open "https://bilibili.com"

# 2. 获取状态，找登录按钮
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_state.sh

# 3. 点击登录（假设 id=1）
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation click \
  --element-id 1

# 4. 等待登录表单加载
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation wait \
  --selector "input[name=username]"

# 5. 获取表单状态
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_state.sh

# 6. 填写用户名（假设 id=10）
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation type \
  --element-id 10 \
  --value "username"

# 7. 填写密码（假设 id=11）
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation type \
  --element-id 11 \
  --value "password"

# 8. 点击登录按钮（假设 id=12）
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation click \
  --element-id 12

# 9. 等待登录完成
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation wait \
  --selector ".user-profile"

# 10. 现在可以访问受保护的内容
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_state.sh
```

### 场景 3：下载内容

```bash
# Bilibili 视频下载示例
opencli operate open "https://www.bilibili.com/video/BV1xxx"

# 等待视频页面加载
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation wait \
  --selector ".bpx-player-container"

# 获取视频信息
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation eval \
  --script 'document.querySelector("h1")?.textContent.trim()'

# 点击下载按钮（如果存在）
bash ~/.lightclaw/workspace/skills/opencli/scripts/opencli_operate.sh \
  --operation click \
  --element-id 20
```

## 性能优化建议

✅ **总是从 state 开始** - 它是免费的、即时的，显示所有可用元素

✅ **批量操作** - 进行多个操作后再获取新的状态，避免频繁调用

✅ **使用 eval 提取数据** - 比截图便宜得多，更精确

✅ **仅在必要时截图** - 视觉 Token 很贵，优先用 eval 和 state

✅ **复用登录会话** - 无需每次重新登录

✅ **等待元素** - 使用 wait 确保页面加载完成，避免空指针错误

## 错误处理

如果操作失败：

1. **获取更新的状态** - 页面可能已变化
2. **检查错误信息** - 看是否有重定向、弹窗或错误提示
3. **截图查看** - 必要时获取页面快照
4. **重试操作** - 页面加载缓慢时，等待后重试
5. **检查网络** - 确保网络连接正常

常见问题：
- **元素 ID 已过期** → 获取新的状态
- **导航超时** → 使用 wait 在页面更新前等待
- **CAPTCHA 出现** → 截图手动处理，或寻找替代方法
- **需要身份验证** → 先完成登录流程
- **JavaScript 执行失败** → 检查语法，尝试更简单的选择器

## 故障排除

运行诊断来排查问题：

```bash
opencli doctor
```

这会检查：
- Node.js 版本
- OpenCLI CLI 安装
- Chrome 浏览器
- 浏览器扩展
- 网络连接
- 配置文件

如果有组件缺失或不兼容，诊断工具会提供修复建议。

## API 参考

详见 `references/` 目录下的参考文档：
- `opencli_commands.md` - 完整命令参考
- `advanced_patterns.md` - 高级用法和最佳实践
- `javascript_api.md` - JavaScript 执行和 DOM 操作
