@optima-chat/browser-cli 0.5.5 → 0.5.7

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

@@ -1,23 +1,24 @@
 ---
 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.)."
-version: "1.0.0"
+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 后台时，按下方"紫鸟浏览器"章节操作。**
+
 ## 使用场景
 
-- 用户要求打开网站或访问某个 URL（如"打开 github"、"open youtube"）
+- 用户提到紫鸟浏览器、ZiNiao、反指纹浏览器、多店铺管理
+- 用户要求操作 TikTok Shop 卖家后台、领星 ERP 等需要登录态的平台
+- 用户要求打开网站或访问某个 URL
 - 用户要求登录平台、填写表单或发布内容
-- 用户需要测试网站功能
 - 用户需要操作没有 API 的第三方平台
-- 用户要求自动化浏览器交互
 
 **不适用场景：**
 - 简单网页抓取 → 使用 WebFetch
-- 已有专用 skill 的任务（如 scout、tiktok、instagram、shein 等）
 
 ## 脚本优先原则
 
@@ -29,17 +30,13 @@ owner_repo: Optima-Chat/optima-browser-use
 
 脚本执行零 token 消耗，比手动操作快 10 倍以上。
 
-## 浏览器模式
+## 前提条件：Desktop 桌面应用
 
-系统支持三种浏览器模式，自动选择最优方案：
+**Browser Skill 需要用户安装 Optima Browser Operator 桌面应用。** 所有浏览器操作都通过 Desktop app 控制用户本地的 Chrome 或紫鸟浏览器。
 
-| 模式 | 触发条件 | 说明 |
-|------|----------|------|
-| **Desktop + 紫鸟** | 用户安装了 Desktop app 且配置了紫鸟 | 通过紫鸟反指纹浏览器操作，保留多店铺登录态 |
-| **Desktop + Chrome** | 用户安装了 Desktop app | 通过用户本地 Chrome 操作 |
-| **Cloud** | 无 Desktop app | 后端 headless Chromium，无登录态 |
+如果 `browser-cli launch` 返回 `desktop_not_connected` 错误，提示用户：
 
-**自动路由**：默认 `browser-cli launch` 会自动选择。如果用户安装了 Optima Browser Operator 桌面应用并在线，自动走 Desktop 模式。
+> "需要安装 Optima Browser Operator 桌面应用才能使用浏览器功能。下载地址: https://github.com/Optima-Chat/optima-browser-use/releases"
 
 ### 紫鸟浏览器（跨境电商多店铺管理）
 
@@ -66,7 +63,7 @@ browser-cli launch --connector ziniao --ziniao-profile 27774259938707 --url http
 **重要**：
 - 用户说"迪士尼店铺"、"林总店铺"等 → 先 `ziniao profiles` 查列表，按名称模糊匹配找到 profile_id
 - 用户说"打开紫鸟"但没指定店铺 → 先列出 profiles 让用户选
-- 紫鸟需要 Desktop app 在线 + 紫鸟 WebDriver 模式已启动
+- 紫鸟需要 Desktop app 在线（紫鸟 WebDriver 会按需自动启动）
 
 ## 命令
 
@@ -224,22 +221,16 @@ browser-cli close
 /mnt/efs/{userId}/images/...    → 自动转换 ✓
 ```
 
-## 需要用户登录态的任务
-
-当用户要求操作需要登录的平台（TikTok Shop、小红书、Instagram 等），需要用户的真实浏览器（有登录态）。
+## Desktop 桌面应用未连接时
 
-**推荐方案：Optima Browser Operator 桌面应用**
+如果 `browser-cli launch` 返回错误，提示用户安装 Desktop app：
 
-1. 用户下载安装桌面应用（Mac .dmg / Windows .exe）：https://github.com/Optima-Chat/optima-browser-use/releases
+1. 下载安装（Mac .dmg / Windows .exe）：https://github.com/Optima-Chat/optima-browser-use/releases
 2. 首次启动自动打开浏览器登录授权
-3. 授权后自动连接，后续 `browser-cli launch` 自动走 Desktop 模式
+3. 授权后自动连接
 
 **跨境电商用户（多店铺）**：推荐安装紫鸟浏览器 + Desktop app，可以按店铺 profile 分别操作，每个店铺独立登录态。
 
-**备选方案：Chrome 扩展**
-
-安装 Optima Browser Operator Chrome 扩展，直接用 Chrome 已登录的账号操作。
-
 ## 注意事项
 
 - **脚本优先**：每次操作前先 `browser-cli scripts`，有脚本就用脚本
@@ -247,6 +238,5 @@ browser-cli close
 - **避免不必要的截图**：截图消耗 token，日常导航用 DOM 输出即可
 - **5 分钟超时**：无操作 5 分钟后会话自动关闭
 - **务必关闭**：操作完成后运行 `browser-cli close` 释放资源
-- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。如果用户已安装 Extension 且 Extension 已连接，用户的 Chrome 通常已经登录了——让用户在自己的 Chrome 里手动登录该平台，然后重新 `runscript`。如果没有 Extension（走 Chromium），用 `browser-cli launch --url <平台URL>` 引导用户登录
+- **login_required 处理**：如果 runscript 返回 `login_required` 错误，说明该平台未登录。让用户在自己的浏览器里手动登录该平台，然后重新 `runscript`
 - **Fallback 后更新脚本**：如果脚本频繁失败，重新生成并 submit-script 覆盖
-- **Extension 模式**：标记了 `REQUIRES_USER_SESSION=True` 的脚本会自动使用用户的真实 Chrome（通过 Optima Browser Operator 扩展），未标记的脚本走 Chromium。这由后端自动判断，无需手动指定

package/dist/index.js

@@ -196,53 +196,38 @@ var BrowserAPI = class {
   async getStatus(sessionId) {
     return request(`/api/sessions/${sessionId}/status`);
   }
-  async navigate(sessionId, url) {
-    return request(`/api/sessions/${sessionId}/navigate`, {
+  /** Execute an action then fetch DOM state separately.
+   *  Decoupled to prevent EventBus overflow on remote CDP tunnels. */
+  async actThenState(sessionId, path, body, timeout) {
+    await request(`/api/sessions/${sessionId}/${path}`, {
       method: "POST",
-      body: JSON.stringify({ url })
+      body: JSON.stringify(body)
     });
+    return this.getState(sessionId);
+  }
+  async navigate(sessionId, url) {
+    return this.actThenState(sessionId, "navigate", { url });
   }
   async back(sessionId) {
-    return request(`/api/sessions/${sessionId}/back`, {
-      method: "POST",
-      body: JSON.stringify({})
-    });
+    return this.actThenState(sessionId, "back", {});
   }
   async refresh(sessionId) {
-    return request(`/api/sessions/${sessionId}/refresh`, {
-      method: "POST",
-      body: JSON.stringify({})
-    });
+    return this.actThenState(sessionId, "refresh", {});
   }
   async click(sessionId, index) {
-    return request(`/api/sessions/${sessionId}/click`, {
-      method: "POST",
-      body: JSON.stringify({ index })
-    });
+    return this.actThenState(sessionId, "click", { index });
   }
   async input(sessionId, index, text, clear = true) {
-    return request(`/api/sessions/${sessionId}/input`, {
-      method: "POST",
-      body: JSON.stringify({ index, text, clear })
-    });
+    return this.actThenState(sessionId, "input", { index, text, clear });
   }
   async scroll(sessionId, down, pages = 1) {
-    return request(`/api/sessions/${sessionId}/scroll`, {
-      method: "POST",
-      body: JSON.stringify({ down, pages })
-    });
+    return this.actThenState(sessionId, "scroll", { down, pages });
   }
   async keys(sessionId, keys) {
-    return request(`/api/sessions/${sessionId}/keys`, {
-      method: "POST",
-      body: JSON.stringify({ keys })
-    });
+    return this.actThenState(sessionId, "keys", { keys });
   }
   async select(sessionId, index, text) {
-    return request(`/api/sessions/${sessionId}/select`, {
-      method: "POST",
-      body: JSON.stringify({ index, text })
-    });
+    return this.actThenState(sessionId, "select", { index, text });
   }
   async getState(sessionId) {
     return request(`/api/sessions/${sessionId}/state`);
@@ -266,22 +251,21 @@ var BrowserAPI = class {
     return request(`/api/sessions/${sessionId}/tabs`);
   }
   async switchTab(sessionId, tabId) {
-    return request(`/api/sessions/${sessionId}/switch`, {
-      method: "POST",
-      body: JSON.stringify({ tab_id: tabId })
-    });
+    return this.actThenState(sessionId, "switch", { tab_id: tabId });
   }
   async closeTab(sessionId, tabId) {
-    return request(
+    await request(
       `/api/sessions/${sessionId}/tabs/${tabId}`,
       { method: "DELETE" }
     );
+    return this.getState(sessionId);
   }
   async uploadFiles(sessionId, index, filePaths) {
-    return request(`/api/sessions/${sessionId}/upload`, {
+    await request(`/api/sessions/${sessionId}/upload`, {
       method: "POST",
       body: JSON.stringify({ index, file_paths: filePaths })
     });
+    return this.getState(sessionId);
   }
   // Script methods
   async submitScript(name, code) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optima-chat/browser-cli",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {