@optima-chat/browser-cli 0.6.0 → 0.7.0

package/dist/index.js

@@ -98,6 +98,16 @@ var BrowserAPIError = class extends Error {
     this.name = "BrowserAPIError";
   }
 };
+function toAPIError(status, statusText, body) {
+  const detail = body.detail ?? body;
+  if (typeof detail === "string") {
+    return new BrowserAPIError(status, "http_error", `HTTP ${status}: ${detail}`);
+  }
+  if (detail?.message) {
+    return new BrowserAPIError(status, detail.error ?? "unknown", detail.message);
+  }
+  return new BrowserAPIError(status, "unknown", `HTTP ${status}: ${statusText}`);
+}
 async function request(path, options = {}) {
   const url = `${BROWSER_API_URL}${path}`;
   let response;
@@ -126,8 +136,7 @@ async function request(path, options = {}) {
         `HTTP ${response.status}: ${response.statusText}`
       );
     }
-    const detail = body.detail || body;
-    throw new BrowserAPIError(response.status, detail.error, detail.message);
+    throw toAPIError(response.status, response.statusText, body);
   }
   if (response.status === 204) {
     return void 0;
@@ -159,20 +168,20 @@ async function requestBinary(path) {
         `HTTP ${response.status}: ${response.statusText}`
       );
     }
-    const detail = body.detail || body;
-    throw new BrowserAPIError(response.status, detail.error, detail.message);
+    throw toAPIError(response.status, response.statusText, body);
   }
   const arrayBuffer = await response.arrayBuffer();
   return Buffer.from(arrayBuffer);
 }
 var BrowserAPI = class {
-  async createSession(url, profileId, force, connector, ziniaoProfileId) {
+  async createSession(url, profileId, force, connector, ziniaoProfileId, bitbrowserProfileId) {
     const body = {};
     if (url) body.url = url;
     if (profileId) body.profile_id = profileId;
     if (force) body.force = true;
     if (connector) body.connector = connector;
     if (ziniaoProfileId) body.ziniao_profile_id = ziniaoProfileId;
+    if (bitbrowserProfileId) body.bitbrowser_profile_id = bitbrowserProfileId;
     return request("/api/sessions", {
       method: "POST",
       body: JSON.stringify(body)
@@ -201,6 +210,9 @@ var BrowserAPI = class {
   async getZiNiaoProfiles() {
     return request("/api/user/ziniao-profiles");
   }
+  async getBitBrowserProfiles() {
+    return request("/api/user/bitbrowser-profiles");
+  }
   async closeSession(sessionId) {
     await request(`/api/sessions/${sessionId}`, { method: "DELETE" });
   }
@@ -246,6 +258,22 @@ var BrowserAPI = class {
   async getScreenshot(sessionId) {
     return requestBinary(`/api/sessions/${sessionId}/screenshot`);
   }
+  async runRecipeScript(name, params, pollMs = 2e3) {
+    const started = await request(`/api/scripts/${name}/run`, {
+      method: "POST",
+      body: JSON.stringify({ params })
+    });
+    for (; ; ) {
+      const task = await request(
+        `/api/script-tasks/${started.id}`
+      );
+      if (task.status === "completed") return task.output;
+      if (task.status === "failed" || task.status === "needs_fallback") {
+        throw new Error(task.error || `recipe ${task.status}`);
+      }
+      await new Promise((r) => setTimeout(r, pollMs));
+    }
+  }
   async search(sessionId, pattern) {
     return request(`/api/sessions/${sessionId}/search`, {
       method: "POST",
@@ -300,9 +328,11 @@ var BrowserAPI = class {
   async deleteScript(name) {
     await request(`/api/scripts/${encodeURIComponent(name)}`, { method: "DELETE" });
   }
-  async runScript(scriptName, params = {}, profileId) {
+  async runScript(scriptName, params = {}, profileId, connector, bitbrowserProfileId) {
     const payload = { params };
     if (profileId) payload.profile_id = profileId;
+    if (connector) payload.connector = connector;
+    if (bitbrowserProfileId) payload.bitbrowser_profile_id = bitbrowserProfileId;
     return request(`/api/scripts/${encodeURIComponent(scriptName)}/run`, {
       method: "POST",
       body: JSON.stringify(payload)
@@ -404,6 +434,9 @@ function formatFind(result) {
   }
   return lines.join("\n");
 }
+function formatDesktopNotConnected(result) {
+  return result.message ?? "\u684C\u9762\u5E94\u7528\u672A\u8FDE\u63A5\uFF0C\u8BF7\u5148\u5B89\u88C5\u5E76\u542F\u52A8\u684C\u9762\u5E94\u7528\u540E\u91CD\u8BD5\u3002";
+}
 function formatError(err) {
   if (err instanceof Error) {
     return `\u2717 Error: ${err.message}`;
@@ -430,9 +463,9 @@ function formatProfileDelete(profileId) {
 
 // src/commands/lifecycle.ts
 function registerLifecycleCommands(program2) {
-  program2.command("launch").description("Launch a browser session").option("--url <url>", "Navigate to URL after launch").option("--profile <id>", "Use a named browser profile").option("--force", "Close existing session before launching").option("--connector <type>", "Browser connector: chrome or ziniao").option("--ziniao-profile <id>", "ZiNiao browser profile ID").action(async (opts) => {
+  program2.command("launch").description("Launch a browser session").option("--url <url>", "Navigate to URL after launch").option("--profile <id>", "Use a named browser profile").option("--force", "Close existing session before launching").option("--connector <type>", "Browser connector: chrome, ziniao, or bitbrowser").option("--ziniao-profile <id>", "ZiNiao browser profile ID").option("--bitbrowser-profile <id>", "BitBrowser profile ID").action(async (opts) => {
     try {
-      const state = await api.createSession(opts.url, opts.profile, opts.force, opts.connector, opts.ziniaoProfile);
+      const state = await api.createSession(opts.url, opts.profile, opts.force, opts.connector, opts.ziniaoProfile, opts.bitbrowserProfile);
       saveSessionId(state.session_id);
       console.log(formatLaunch(state));
     } catch (err) {
@@ -748,7 +781,7 @@ function registerScriptCommands(program2) {
       process.exit(1);
     }
   });
-  program2.command("runscript").argument("<name>", "Script name").description("Run a script (polls until complete)").option("--param <params...>", "Parameters as key=value").option("--profile <id>", "Use a named browser profile").option("--no-poll", "Return immediately without polling").action(async (name, opts) => {
+  program2.command("runscript").argument("<name>", "Script name").description("Run a script (polls until complete)").option("--param <params...>", "Parameters as key=value").option("--profile <id>", "Use a named browser profile").option("--connector <type>", "Browser connector: chrome, ziniao, or bitbrowser").option("--bitbrowser-profile <id>", "BitBrowser profile ID (with --connector bitbrowser)").option("--no-poll", "Return immediately without polling").action(async (name, opts) => {
     try {
       const params = {};
       if (opts.param) {
@@ -758,7 +791,7 @@ function registerScriptCommands(program2) {
         }
       }
       clearSessionId();
-      const task = await api.runScript(name, params, opts.profile);
+      const task = await api.runScript(name, params, opts.profile, opts.connector, opts.bitbrowserProfile);
       console.log(`Script started (task: ${task.id})`);
       if (!opts.poll) {
         console.log(`Poll with: browser-cli script-task ${task.id}`);
@@ -820,6 +853,105 @@ function registerProfileCommands(program2) {
   });
 }
 
+// src/ziniao-doctor.ts
+var ZINIAO_WEBDRIVER_DOC_URL = "https://open.ziniao.com/docSupport?docId=99#%E7%AC%AC%E4%B8%80%E6%AD%A5%EF%BC%9A%E7%99%BB%E5%BD%95%E5%BC%80%E6%94%BE%E5%B9%B3%E5%8F%B0%E6%8E%A7%E5%88%B6%E5%8F%B00";
+var BOSS_GUIDANCE = [
+  "\u9700\u8981\u7D2B\u9E1F BOSS \u8D26\u53F7\u5B8C\u6210\u5F00\u901A\uFF08\u4E00\u6B21\u6027\u914D\u7F6E\uFF09\uFF1A",
+  "  1. \u767B\u5F55\u7D2B\u9E1F\u5F00\u653E\u5E73\u53F0\u63A7\u5236\u53F0\uFF0C\u5F00\u901A Webdriver \u6743\u9650\uFF1B",
+  "  2. \u521B\u5EFA\u4E13\u7528\u81EA\u52A8\u5316\u6210\u5458\u8D26\u53F7\uFF08robot\uFF09\uFF0C\u89D2\u8272\u9700\u542B\u300C\u67E5\u770B\u8D26\u53F7\u300D\u6743\u9650\uFF1B",
+  "  3. \u4E3A\u8BE5\u8D26\u53F7\u6388\u6743\u9700\u8981\u64CD\u4F5C\u7684\u5E97\u94FA\u3002",
+  `\u53C2\u8003\u6587\u6863: ${ZINIAO_WEBDRIVER_DOC_URL}`
+].join("\n");
+function ziniaoErrorHint(message) {
+  if (/webdriver|开通|权限|permission/i.test(message)) {
+    return `\u7591\u4F3C\u672A\u5F00\u901A Webdriver \u6743\u9650\u6216\u8D26\u53F7\u6743\u9650\u4E0D\u8DB3\u3002${BOSS_GUIDANCE}`;
+  }
+  if (/错误次数太多/.test(message)) {
+    return "\u7D2B\u9E1F\u98CE\u63A7\u5DF2\u4E34\u65F6\u9501\u5B9A\uFF0C\u8BF7\u7B49\u5F85\u7EA6 10 \u5206\u949F\u540E\u91CD\u8BD5\uFF08\u7EE7\u7EED\u5931\u8D25\u4F1A\u5EF6\u957F\u9501\u5B9A\uFF09\u3002";
+  }
+  if (/用户名或密码错误|密码错误/.test(message)) {
+    return "\u8BF7\u6838\u5BF9\u51ED\u636E\uFF08company=\u4F01\u4E1A\u540D\u79F0\uFF0Cusername/password=\u6210\u5458\u8D26\u53F7\uFF0C\u63A8\u8350 robot \u8D26\u53F7\uFF09\uFF0C\u7136\u540E\u7528 browser-cli ziniao set \u91CD\u65B0\u914D\u7F6E\u3002";
+  }
+  return null;
+}
+async function runZiNiaoDoctor(client) {
+  const checks = [];
+  const done = () => ({ checks, ok: checks.every((c) => c.ok === true) });
+  let cfg;
+  try {
+    cfg = await client.getZiNiaoConfig();
+  } catch (err) {
+    checks.push({
+      name: "\u540E\u7AEF\u8FDE\u63A5",
+      ok: false,
+      detail: err.message,
+      hint: "\u786E\u8BA4 browser-backend \u6B63\u5728\u8FD0\u884C\uFF0C\u4E14 BROWSER_API_URL \u6307\u5411\u6B63\u786E\u5730\u5740\u3002"
+    });
+    return done();
+  }
+  checks.push({ name: "\u540E\u7AEF\u8FDE\u63A5", ok: true });
+  if (!cfg.configured) {
+    checks.push({
+      name: "\u7D2B\u9E1F\u51ED\u636E",
+      ok: false,
+      hint: "browser-cli ziniao set --company <\u4F01\u4E1A\u540D\u79F0> --username <\u6210\u5458\u8D26\u53F7> --password <\u5BC6\u7801>\uFF08\u63A8\u8350\u4F7F\u7528\u4E13\u7528 robot \u6210\u5458\u8D26\u53F7\uFF09"
+    });
+    return done();
+  }
+  checks.push({ name: "\u7D2B\u9E1F\u51ED\u636E", ok: true, detail: `${cfg.company} / ${cfg.username}` });
+  try {
+    const r = await client.getZiNiaoProfiles();
+    if (!r.connected) {
+      checks.push({
+        name: "\u684C\u9762\u5E94\u7528",
+        ok: false,
+        detail: r.message,
+        hint: `\u8BF7\u542F\u52A8 Optima \u684C\u9762\u5E94\u7528\u5E76\u5B8C\u6210\u8FDE\u63A5\u3002${r.download_url ? `\u4E0B\u8F7D: ${r.download_url}` : ""}`.trim()
+      });
+      return done();
+    }
+    checks.push({ name: "\u684C\u9762\u5E94\u7528", ok: true });
+    if (!r.ziniao_available) {
+      checks.push({
+        name: "\u7D2B\u9E1F\u5BA2\u6237\u7AEF",
+        ok: false,
+        hint: "\u684C\u9762\u7AEF\u672A\u68C0\u6D4B\u5230\u53EF\u7528\u7684\u7D2B\u9E1F\uFF1A\u786E\u8BA4\u672C\u673A\u5DF2\u5B89\u88C5\u7D2B\u9E1F\u5BA2\u6237\u7AEF\uFF0C\u4E14\u51ED\u636E\u5DF2\u540C\u6B65\u5230\u684C\u9762\uFF08\u91CD\u542F\u684C\u9762\u5E94\u7528\u53EF\u89E6\u53D1\u540C\u6B65\uFF09\u3002"
+      });
+      return done();
+    }
+    checks.push({ name: "\u7D2B\u9E1F\u5BA2\u6237\u7AEF", ok: true });
+    if (r.profiles.length === 0) {
+      checks.push({
+        name: "\u5E97\u94FA\u5217\u8868",
+        ok: "warn",
+        detail: "\u767B\u5F55\u6210\u529F\uFF0C\u4F46\u5E97\u94FA\u5217\u8868\u4E3A\u7A7A",
+        hint: `robot \u8D26\u53F7\u7684\u89D2\u8272\u53EF\u80FD\u7F3A\u300C\u67E5\u770B\u8D26\u53F7\u300D\u6743\u9650\uFF0C\u6216\u5C1A\u672A\u6388\u6743\u4EFB\u4F55\u5E97\u94FA\u3002${BOSS_GUIDANCE}`
+      });
+      return done();
+    }
+    checks.push({ name: "\u5E97\u94FA\u5217\u8868", ok: true, detail: `${r.profiles.length} \u4E2A\u5E97\u94FA\u53EF\u7528` });
+  } catch (err) {
+    checks.push({
+      name: "\u7D2B\u9E1F Webdriver \u901A\u9053",
+      ok: false,
+      detail: err.message,
+      hint: ziniaoErrorHint(err.message ?? "") ?? void 0
+    });
+  }
+  return done();
+}
+function formatDoctorReport(checks) {
+  const lines = [];
+  for (const c of checks) {
+    const mark = c.ok === true ? "\u2713" : c.ok === "warn" ? "\u26A0" : "\u2717";
+    lines.push(`${mark} ${c.name}${c.detail ? `: ${c.detail}` : ""}`);
+    if (c.hint) {
+      lines.push(...c.hint.split("\n").map((l) => `    ${l}`));
+    }
+  }
+  return lines.join("\n");
+}
+
 // src/commands/ziniao.ts
 function registerZiNiaoCommands(program2) {
   const ziniao = program2.command("ziniao").description("Manage ZiNiao browser credentials");
@@ -851,15 +983,17 @@ function registerZiNiaoCommands(program2) {
     try {
       const result = await api.getZiNiaoProfiles();
       if (!result.connected) {
-        console.log("Desktop app not connected. Start Optima Browser Operator first.");
+        console.log(formatDesktopNotConnected(result));
         process.exit(1);
       }
       if (!result.ziniao_available) {
         console.log("ZiNiao not available on Desktop app. Start ZiNiao WebDriver mode first.");
+        console.log("Run: browser-cli ziniao doctor  \uFF08\u9010\u9879\u6392\u67E5\u7D2B\u9E1F\u901A\u9053\uFF09");
         process.exit(1);
       }
       if (result.profiles.length === 0) {
         console.log("No ZiNiao profiles found.");
+        console.log("Run: browser-cli ziniao doctor  \uFF08\u9010\u9879\u6392\u67E5\u7D2B\u9E1F\u901A\u9053\uFF0C\u5E38\u89C1\u539F\u56E0\uFF1Arobot \u8D26\u53F7\u7F3A\u300C\u67E5\u770B\u8D26\u53F7\u300D\u6743\u9650\u6216\u672A\u6388\u6743\u5E97\u94FA\uFF09");
         return;
       }
       console.log(`ZiNiao profiles (${result.profiles.length}):
@@ -870,9 +1004,16 @@ function registerZiNiaoCommands(program2) {
       console.log("\nUse: browser-cli launch --connector ziniao --ziniao-profile <id> --url <url>");
     } catch (err) {
       console.error(formatError(err));
+      const hint = ziniaoErrorHint(err?.message ?? "");
+      if (hint) console.error(hint);
       process.exit(1);
     }
   });
+  ziniao.command("doctor").description("Diagnose the ZiNiao Webdriver chain (credentials / desktop / permission / stores)").action(async () => {
+    const { checks, ok } = await runZiNiaoDoctor(api);
+    console.log(formatDoctorReport(checks));
+    if (!ok) process.exit(1);
+  });
   ziniao.command("clear").description("Remove ZiNiao credentials").action(async () => {
     try {
       await api.deleteZiNiaoConfig();
@@ -884,6 +1025,50 @@ function registerZiNiaoCommands(program2) {
   });
 }
 
+// src/commands/recipes.ts
+import { writeFileSync as writeFileSync3 } from "fs";
+function registerRecipeCommands(program2) {
+  program2.command("export-ad-report").description("Export TikTok Shop last-7-days video ad data into the session workspace").requiredOption("--ziniao-profile <id>", "ZiNiao browser profile ID").option("--out <path>", "Output CSV path", "./tt_video_ad_7d.csv").action(async (opts) => {
+    try {
+      const out = await api.runRecipeScript("tiktok_video_ad_export", {
+        ziniao_profile_id: opts.ziniaoProfile
+      });
+      writeFileSync3(opts.out, Buffer.from(out.content_b64, "base64"));
+      console.log(`Saved ${out.filename} -> ${opts.out} (${out.size} bytes)`);
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+}
+
+// src/commands/bitbrowser.ts
+function registerBitBrowserCommands(program2) {
+  const bitbrowser = program2.command("bitbrowser").description("Manage BitBrowser (\u6BD4\u7279\u6D4F\u89C8\u5668) anti-detect browser");
+  bitbrowser.command("profiles").description("List BitBrowser profiles (requires Desktop app online + BitBrowser running)").action(async () => {
+    try {
+      const result = await api.getBitBrowserProfiles();
+      if (!result.connected) {
+        console.log(formatDesktopNotConnected(result));
+        process.exit(1);
+      }
+      if (result.profiles.length === 0) {
+        console.log("No BitBrowser profiles found. Is BitBrowser running with its local API enabled?");
+        return;
+      }
+      console.log(`BitBrowser profiles (${result.profiles.length}):
+`);
+      for (const p of result.profiles) {
+        console.log(`  ${p.id}  ${p.name}`);
+      }
+      console.log("\nUse: browser-cli launch --connector bitbrowser --bitbrowser-profile <id> --url <url>");
+    } catch (err) {
+      console.error(formatError(err));
+      process.exit(1);
+    }
+  });
+}
+
 // src/index.ts
 var require2 = createRequire(import.meta.url);
 var { version } = require2("../package.json");
@@ -903,4 +1088,6 @@ registerTabCommands(program);
 registerScriptCommands(program);
 registerProfileCommands(program);
 registerZiNiaoCommands(program);
+registerRecipeCommands(program);
+registerBitBrowserCommands(program);
 program.parse();

package/package.json

@@ -1,14 +1,13 @@
 {
   "name": "@optima-chat/browser-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "bin": {
     "browser-cli": "./dist/index.js"
   },
   "files": [
-    "dist",
-    ".claude"
+    "dist"
   ],
   "scripts": {
     "build": "tsup",

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

@@ -1,242 +0,0 @@
----
-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 覆盖