@optima-chat/browser-cli 0.5.6 → 0.6.0

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

@@ -30,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"
 
 ### 紫鸟浏览器（跨境电商多店铺管理）
 
@@ -67,7 +63,7 @@ browser-cli launch --connector ziniao --ziniao-profile 27774259938707 --url http
 **重要**：
 - 用户说"迪士尼店铺"、"林总店铺"等 → 先 `ziniao profiles` 查列表，按名称模糊匹配找到 profile_id
 - 用户说"打开紫鸟"但没指定店铺 → 先列出 profiles 让用户选
-- 紫鸟需要 Desktop app 在线 + 紫鸟 WebDriver 模式已启动
+- 紫鸟需要 Desktop app 在线（紫鸟 WebDriver 会按需自动启动）
 
 ## 命令
 
@@ -225,22 +221,16 @@ browser-cli close
 /mnt/efs/{userId}/images/...    → 自动转换 ✓
 ```
 
-## 需要用户登录态的任务
+## Desktop 桌面应用未连接时
 
-当用户要求操作需要登录的平台（TikTok Shop、小红书、Instagram 等），需要用户的真实浏览器（有登录态）。
+如果 `browser-cli launch` 返回错误，提示用户安装 Desktop app：
 
-**推荐方案：Optima Browser Operator 桌面应用**
-
-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`，有脚本就用脚本
@@ -248,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

@@ -17,6 +17,11 @@ var ENV_CONFIG = {
   },
   development: {
     apiUrl: "http://127.0.0.1:7292"
+  },
+  // 阿里云 cn-prod（yzsgo 品牌域；权威映射见 optima-terraform
+  // alicloud/stacks/cn-prod-ingress-sae/main.tf 的 yzsgo_sub=browser-api）。
+  "cn-prod": {
+    apiUrl: "https://browser-api.yzsgo.com"
   }
 };
 var OPTIMA_TOKEN_FILE = join(homedir(), ".optima", "token.json");
@@ -30,6 +35,8 @@ function tokenEnvToBrowserEnv(tokenEnv) {
     case "ci":
     case "development":
       return "development";
+    case "cn-prod":
+      return "cn-prod";
     default:
       return null;
   }
@@ -44,23 +51,27 @@ function readOptimaToken() {
 }
 function getCurrentEnv() {
   const browserEnv = process.env.BROWSER_ENV;
-  if (browserEnv && ["production", "stage", "development"].includes(browserEnv)) {
+  if (browserEnv && ["production", "stage", "development", "cn-prod"].includes(browserEnv)) {
     return browserEnv;
   }
   const optimaEnv = process.env.OPTIMA_ENV;
-  if (optimaEnv && ["production", "stage", "development"].includes(optimaEnv)) {
+  if (optimaEnv && ["production", "stage", "development", "cn-prod"].includes(optimaEnv)) {
     return optimaEnv;
   }
   const optimaToken = readOptimaToken();
   if (optimaToken?.env) {
     const mapped = tokenEnvToBrowserEnv(optimaToken.env);
     if (mapped) return mapped;
+    throw new Error(
+      `Unknown environment "${optimaToken.env}" in ~/.optima/token.json. Known environments: prod, stage, ci, cn-prod. Upgrade browser-cli to a version that knows this environment, or set BROWSER_API_URL to override the endpoint explicitly.`
+    );
   }
   return "development";
 }
 function loadConfig() {
-  const env = getCurrentEnv();
-  const envConfig = ENV_CONFIG[env];
+  const apiUrlOverride = process.env.BROWSER_API_URL;
+  const env = apiUrlOverride ? void 0 : getCurrentEnv();
+  const apiUrl = apiUrlOverride ?? ENV_CONFIG[env].apiUrl;
   let token = process.env.BROWSER_TOKEN || null;
   if (!token) {
     const optimaToken = readOptimaToken();
@@ -69,7 +80,7 @@ function loadConfig() {
     }
   }
   return {
-    apiUrl: process.env.BROWSER_API_URL || envConfig.apiUrl,
+    apiUrl,
     token,
     env
   };
@@ -196,53 +207,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 +262,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.6",
+  "version": "0.6.0",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {