@optima-chat/optima-agent 0.9.7 → 0.9.8

package/.claude/skills/browser/SKILL.md

@@ -1,201 +1,201 @@
----
-name: browser
-description: "Browser automation for web interactions. Use when user needs to open/navigate to websites, login to platforms, fill forms, post content, test websites, or operate on third-party platforms without APIs. Uses 'browser-cli' commands. Do NOT use for simple web scraping (use WebFetch) or tasks that have dedicated skills (e.g. scout, tiktok, instagram, shein, etc.)."
----
-
-# 浏览器自动化 Skill
-
-## 使用场景
-
-- 用户要求打开网站或访问某个 URL（如"打开 github"、"open youtube"）
-- 用户要求登录平台、填写表单或发布内容
-- 用户需要测试网站功能
-- 用户需要操作没有 API 的第三方平台
-- 用户要求自动化浏览器交互
-
-**不适用场景：**
-- 简单网页抓取 → 使用 WebFetch
-- 已有专用 skill 的任务（如 scout、tiktok、instagram、shein 等）
-
-## 脚本优先原则
-
-每次执行浏览器任务前，**先检查是否有现成脚本**：
-
-1. `browser-cli scripts` — 查看已有脚本（显示名称、描述、步骤）
-2. 如果有匹配的脚本 → 直接用 `browser-cli runscript <name> --param ...`
-3. 如果没有 → 手动用 browser-cli 命令完成任务
-
-脚本执行零 token 消耗，比手动操作快 10 倍以上。
-
-## 命令
-
-### 会话管理
-
-```bash
-browser-cli launch [--url <url>] [--force]  # 启动浏览器（--force 先关闭已有会话）
-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/...    → 自动转换 ✓
-```
-
-## 需要用户登录态的任务
-
-当用户要求操作需要登录的平台（小红书、Instagram、微博、淘宝等社交/电商平台），在开始执行前先引导用户安装扩展：
-
-"这个任务需要用到你在 [平台名] 的登录态。请安装 Optima Browser Operator Chrome 扩展，这样我可以直接用你已登录的浏览器来操作，不需要你提供密码。"
-
-安装后用户回到聊天页面，扩展自动连接，直接执行任务。如果用户在该平台未登录，提示用户先在自己的 Chrome 里登录。
-
-## 注意事项
-
-- **脚本优先**：每次操作前先 `browser-cli scripts`，有脚本就用脚本
-- **DOM 自动返回**：每个操作会自动返回 DOM 状态 — 无需单独调用 `browser-cli dom`
-- **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
-- **5 分钟超时**：无操作 5 分钟后会话自动关闭
-- **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
-- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。如果用户已安装 Extension 且 Extension 已连接，用户的 Chrome 通常已经登录了——让用户在自己的 Chrome 里手动登录该平台，然后重新 `runscript`。如果没有 Extension（走 Chromium），用 `browser-cli launch --url <平台URL>` 引导用户登录
-- **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖
-- **Extension 模式**：标记了 `REQUIRES_USER_SESSION=True` 的脚本会自动使用用户的真实 Chrome（通过 Optima Browser Operator 扩展），未标记的脚本走 Chromium。这由后端自动判断，无需手动指定
+---
+name: browser
+description: "Browser automation for web interactions. Use when user needs to open/navigate to websites, login to platforms, fill forms, post content, test websites, or operate on third-party platforms without APIs. Uses 'browser-cli' commands. Do NOT use for simple web scraping (use WebFetch) or tasks that have dedicated skills (e.g. scout, tiktok, instagram, shein, etc.)."
+---
+
+# 浏览器自动化 Skill
+
+## 使用场景
+
+- 用户要求打开网站或访问某个 URL（如"打开 github"、"open youtube"）
+- 用户要求登录平台、填写表单或发布内容
+- 用户需要测试网站功能
+- 用户需要操作没有 API 的第三方平台
+- 用户要求自动化浏览器交互
+
+**不适用场景：**
+- 简单网页抓取 → 使用 WebFetch
+- 已有专用 skill 的任务（如 scout、tiktok、instagram、shein 等）
+
+## 脚本优先原则
+
+每次执行浏览器任务前，**先检查是否有现成脚本**：
+
+1. `browser-cli scripts` — 查看已有脚本（显示名称、描述、步骤）
+2. 如果有匹配的脚本 → 直接用 `browser-cli runscript <name> --param ...`
+3. 如果没有 → 手动用 browser-cli 命令完成任务
+
+脚本执行零 token 消耗，比手动操作快 10 倍以上。
+
+## 命令
+
+### 会话管理
+
+```bash
+browser-cli launch [--url <url>] [--force]  # 启动浏览器（--force 先关闭已有会话）
+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/...    → 自动转换 ✓
+```
+
+## 需要用户登录态的任务
+
+当用户要求操作需要登录的平台（小红书、Instagram、微博、淘宝等社交/电商平台），在开始执行前先引导用户安装扩展：
+
+"这个任务需要用到你在 [平台名] 的登录态。请安装 Optima Browser Operator Chrome 扩展，这样我可以直接用你已登录的浏览器来操作，不需要你提供密码。"
+
+安装后用户回到聊天页面，扩展自动连接，直接执行任务。如果用户在该平台未登录，提示用户先在自己的 Chrome 里登录。
+
+## 注意事项
+
+- **脚本优先**：每次操作前先 `browser-cli scripts`，有脚本就用脚本
+- **DOM 自动返回**：每个操作会自动返回 DOM 状态 — 无需单独调用 `browser-cli dom`
+- **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
+- **5 分钟超时**：无操作 5 分钟后会话自动关闭
+- **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
+- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。如果用户已安装 Extension 且 Extension 已连接，用户的 Chrome 通常已经登录了——让用户在自己的 Chrome 里手动登录该平台，然后重新 `runscript`。如果没有 Extension（走 Chromium），用 `browser-cli launch --url <平台URL>` 引导用户登录
+- **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖
+- **Extension 模式**：标记了 `REQUIRES_USER_SESSION=True` 的脚本会自动使用用户的真实 Chrome（通过 Optima Browser Operator 扩展），未标记的脚本走 Chromium。这由后端自动判断，无需手动指定