---
name: browser
description: "Browser automation — controls real browsers (Chrome, ZiNiao/紫鸟) via browser-cli. MUST USE when user mentions: 紫鸟, ZiNiao, 反指纹浏览器, 店铺浏览器, TikTok Shop 后台操作, 多店铺管理, or needs to operate any logged-in platform. Also use for opening websites, filling forms, posting content, testing websites. Do NOT use for simple web scraping (use WebFetch)."
version: "1.1.0"
owner_repo: Optima-Chat/optima-browser-use
---

# 浏览器自动化 Skill

**重要：本 Skill 可以直接控制紫鸟浏览器和 Chrome。当用户提到紫鸟、店铺、TikTok Shop 后台时，按下方"紫鸟浏览器"章节操作。**

## 使用场景

- 用户提到紫鸟浏览器、ZiNiao、反指纹浏览器、多店铺管理
- 用户要求操作 TikTok Shop 卖家后台、领星 ERP 等需要登录态的平台
- 用户要求打开网站或访问某个 URL
- 用户要求登录平台、填写表单或发布内容
- 用户需要操作没有 API 的第三方平台

**不适用场景：**
- 简单网页抓取 → 使用 WebFetch

## 脚本优先原则

每次执行浏览器任务前，**先检查是否有现成脚本**：

1. `browser-cli scripts` — 查看已有脚本（显示名称、描述、步骤）
2. 如果有匹配的脚本 → 直接用 `browser-cli runscript <name> --param ...`
3. 如果没有 → 手动用 browser-cli 命令完成任务

脚本执行零 token 消耗，比手动操作快 10 倍以上。

## 前提条件：Desktop 桌面应用

**Browser Skill 需要用户安装 Optima Browser Operator 桌面应用。** 所有浏览器操作都通过 Desktop app 控制用户本地的 Chrome 或紫鸟浏览器。

如果 `browser-cli launch` 返回 `desktop_not_connected` 错误，提示用户：

> "需要安装 Optima Browser Operator 桌面应用才能使用浏览器功能。下载地址: https://github.com/Optima-Chat/optima-browser-use/releases"

### 紫鸟浏览器（跨境电商多店铺管理）

当用户提到紫鸟、多店铺、反指纹浏览器、TikTok Shop 店铺、或需要操作特定店铺时，按以下步骤操作：

```bash
# 1. 检查紫鸟凭证是否已配置
browser-cli ziniao show

# 2. 如果未配置，设置凭证（需要用户提供）
browser-cli ziniao set --company "公司名" --username "用户名" --password "密码"

# 3. 查看可用的紫鸟店铺列表（需要 Desktop app 在线）
browser-cli ziniao profiles
# 输出示例：
#   27774259938707  迪士尼授权林总店铺
#   27772540507986  Gigilli-US
#   27732948017158  马来本土店3SAVEZO

# 4. 用店铺 profile 启动浏览器（根据用户描述匹配店铺名）
browser-cli launch --connector ziniao --ziniao-profile 27774259938707 --url https://seller.tiktokshopglobalselling.com/homepage --force
```

**重要**：
- 用户说"迪士尼店铺"、"林总店铺"等 → 先 `ziniao profiles` 查列表，按名称模糊匹配找到 profile_id
- 用户说"打开紫鸟"但没指定店铺 → 先列出 profiles 让用户选
- 紫鸟需要 Desktop app 在线（紫鸟 WebDriver 会按需自动启动）

## 命令

### 会话管理

```bash
browser-cli launch [--url <url>] [--force]  # 启动浏览器（自动选择模式）
browser-cli launch --connector ziniao --ziniao-profile <id> [--url <url>]  # 指定紫鸟店铺
browser-cli launch --connector chrome [--url <url>]  # 指定 Chrome
browser-cli close                            # 关闭浏览器并释放资源
browser-cli status                           # 查看当前会话状态
```

### 导航

```bash
browser-cli navigate <url>            # 跳转到 URL
browser-cli back                      # 后退
browser-cli refresh                   # 刷新页面
```

### 交互

```bash
browser-cli click <index>             # 按索引点击元素
browser-cli input <index> <text> [--no-clear]  # 输入文本（--no-clear 追加而非替换）
browser-cli select <index> <option>   # 选择下拉选项
browser-cli scroll <up|down> [--pages <n>]     # 滚动页面（默认 1 页）
browser-cli keys <key>                # 键盘操作（Enter、Tab 等）
browser-cli upload <index> <file...>  # 上传文件到 file input（路径自动转换）
```

### 页面检查

```bash
browser-cli dom                       # 获取当前 DOM 状态
browser-cli screenshot [file]         # 截图（默认：/tmp/screenshot.png）
browser-cli search <pattern>          # 搜索页面文本
browser-cli find <css_selector>       # 通过 CSS 选择器查询
```

### 标签页管理

```bash
browser-cli tabs                      # 列出所有标签页
browser-cli switch <tab_id>           # 切换标签页
browser-cli close-tab <tab_id>        # 关闭标签页
```

### 脚本

```bash
browser-cli scripts                                        # 列出所有脚本（含描述和步骤）
browser-cli script-code <name>                             # 查看脚本源码
browser-cli runscript <name> --param key=value [...]       # 执行脚本（自动轮询到完成）
browser-cli runscript <name> --param key=value --no-poll   # 执行但不等待
browser-cli script-task <task-id>                          # 查询执行状态
browser-cli submit-script --name <name> --code-file <path> # 提交新脚本（新建或覆盖）
browser-cli delete-script <name>                           # 删除脚本
```

### Profile 管理

```bash
browser-cli profiles                   # 列出浏览器 profile
browser-cli delete-profile <id>        # 删除 profile
browser-cli launch --profile <id>      # 用指定 profile 启动
browser-cli runscript <name> --profile <id> --param ...  # 用指定 profile 执行脚本
```

## DOM 索引格式

每个操作都会返回当前 DOM 状态，格式如下：

```
[N]<tag attributes />
    content
```

- 索引号 (N) **不连续**（如 [7]、[20]、[30]）— 这是正常的
- 每次操作后索引会**重新分配** — 务必使用最新的索引
- 使用这些索引来执行 `click`、`input` 和 `select` 命令

## 操作流程

### 流程一：有脚本（常见）

```bash
# 1. 检查脚本
browser-cli scripts

# 2. 直接执行
browser-cli runscript xiaohongshu-image-note \
  --param title="今日分享" \
  --param body="内容..." \
  --param 'images=["~/images/photo1.jpg", "~/images/photo2.jpg"]'
# 输出: ✓ Script completed

# 小红书评论
browser-cli runscript xiaohongshu-comment \
  --param search_keyword="辞职做跨境电商" \
  --param comment="写得好！"

# 小红书数据采集
browser-cli runscript xiaohongshu-data-collect

# Instagram 发帖
browser-cli runscript instagram-image-post \
  --param 'images=["~/images/photo.jpg"]' \
  --param body="Morning vibes ☕"
```

### 流程二：无脚本（手动操作）

```bash
# 1. 启动浏览器
browser-cli launch --url https://example.com

# 2. 查看 DOM，找到要操作的元素
browser-cli dom

# 3. 操作元素（用 DOM 返回的索引）
browser-cli click 15
browser-cli input 22 "内容"
browser-cli keys Enter

# 4. 完成后关闭
browser-cli close
```

### 流程三：脚本失败（Fallback）

```bash
# 1. 执行脚本
browser-cli runscript xiaohongshu-image-note --param ...
# 输出: ⚠ Script needs fallback
# → 显示已完成和剩余步骤

# 2. Session 仍然打开 — 用手动命令继续完成剩余步骤
browser-cli dom
browser-cli click 15
browser-cli input 22 "内容"

# 3. 完成后关闭
browser-cli close
```

## 文件路径

浏览器后端可以直接读取用户工作空间的文件。传文件路径时直接使用你看到的路径即可，后端会自动转换：

```
~/images/photo.jpg              → 自动转换 ✓
/home/aiuser/images/photo.jpg   → 自动转换 ✓
/mnt/efs/{userId}/images/...    → 自动转换 ✓
```

## Desktop 桌面应用未连接时

如果 `browser-cli launch` 返回错误，提示用户安装 Desktop app：

1. 下载安装（Mac .dmg / Windows .exe）：https://github.com/Optima-Chat/optima-browser-use/releases
2. 首次启动自动打开浏览器登录授权
3. 授权后自动连接

**跨境电商用户（多店铺）**：推荐安装紫鸟浏览器 + Desktop app，可以按店铺 profile 分别操作，每个店铺独立登录态。

## 注意事项

- **脚本优先**：每次操作前先 `browser-cli scripts`，有脚本就用脚本
- **DOM 自动返回**：每个操作会自动返回 DOM 状态 — 无需单独调用 `browser-cli dom`
- **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
- **5 分钟超时**：无操作 5 分钟后会话自动关闭
- **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。让用户在自己的浏览器里手动登录该平台，然后重新 `runscript`
- **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖
