@xbrowser/cli 1.25.2 → 1.27.0

package/dist/{chunk-DRKL2RFQ.js → chunk-IDXOIXQR.js}

@@ -9,7 +9,7 @@ import {
   resolveLaunchOpts,
   saveSessionDiskMeta,
   setActivePage
-} from "./chunk-NNI5RT4A.js";
+} from "./chunk-KECYFWJO.js";
 import {
   detectAntiBot,
   formatDetectionMessage
@@ -867,10 +867,14 @@ var clickCommand = registerCommand({
         targetIdsBefore = /* @__PURE__ */ new Set();
       }
       const pagePromise = new Promise((resolve3) => {
+        const waitMs = (() => {
+          const v = parseInt(process.env.XBROWSER_NEW_TAB_WAIT ?? "250", 10);
+          return Number.isFinite(v) && v > 0 ? v : 250;
+        })();
         const timer = setTimeout(() => {
           ctx.browserContext.off("page", handler);
           resolve3(void 0);
-        }, 3e3);
+        }, waitMs);
         const handler = (page2) => {
           if (targetIdsBefore.has(targetIdOf(page2))) return;
           try {
@@ -6053,26 +6057,193 @@ var waitForCommand = registerCommand({
   }
 });
 
-// src/commands/tab.ts
+// src/commands/task.ts
 import { z as z27 } from "zod";
-import { ok as ok26, fail as fail12 } from "@dyyz1993/xcli-core";
-var TabParams = z27.object({
-  subcommand: z27.enum(["list", "new", "close", "switch"]),
-  url: z27.string().optional(),
-  index: z27.number().int().min(0).optional()
+import { ok as ok26, fail as fail12, normalizeTips as normalizeTips5 } from "@dyyz1993/xcli-core";
+var DECISION_SYSTEM = `\u4F60\u662F\u6D4F\u89C8\u5668\u4EFB\u52A1\u51B3\u7B56\u5668\u3002\u6839\u636E\u76EE\u6807\u3001\u5F53\u524D\u9875\u9762\u5143\u7D20\u6E05\u5355\uFF08\u6BCF\u9879\u5E26 @eN \u7F16\u53F7\uFF09\u548C\u5DF2\u6267\u884C\u5386\u53F2\uFF0C\u8F93\u51FA\u4E0B\u4E00\u6B65\u52A8\u4F5C\u3002
+
+\u53EF\u7528\u52A8\u4F5C\uFF08\u53EA\u80FD\u8F93\u51FA\u4E00\u4E2A JSON \u5BF9\u8C61\uFF0C\u4E0D\u8981\u8F93\u51FA\u4EFB\u4F55\u5176\u4ED6\u6587\u5B57\uFF09\uFF1A
+{"action":"click","ref":"@eN","thought":"\u4E3A\u4EC0\u4E48"}
+{"action":"fill","ref":"@eN","value":"\u6587\u672C","thought":"\u4E3A\u4EC0\u4E48"}
+{"action":"select","ref":"@eN","value":"\u9009\u9879\u503C","thought":"\u4E3A\u4EC0\u4E48"}
+{"action":"press","value":"Enter","thought":"\u4E3A\u4EC0\u4E48"}
+{"action":"scroll","value":"down \u6216 up","thought":"\u4E3A\u4EC0\u4E48"}
+{"action":"done","value":"\u5B8C\u6210\u6458\u8981","thought":"\u4E3A\u4EC0\u4E48"}
+{"action":"blocked","value":"\u5361\u4F4F\u539F\u56E0","thought":"\u4E3A\u4EC0\u4E48"}
+
+\u89C4\u5219\uFF1A
+1. ref \u5FC5\u987B\u539F\u6837\u6765\u81EA\u672C\u6B21\u5143\u7D20\u6E05\u5355\uFF1B\u6E05\u5355\u91CC\u6CA1\u6709\u80FD\u63A8\u8FDB\u76EE\u6807\u7684\u5143\u7D20\u5C31\u8F93\u51FA blocked\u3002
+2. \u76EE\u6807\u5DF2\u5B8C\u6210\uFF08\u9875\u9762\u4E0A\u80FD\u786E\u8BA4\u7ED3\u679C\uFF09\u5C31\u8F93\u51FA done\uFF0Cvalue \u5199\u5B8C\u6210\u6458\u8981\u3002
+3. \u4E0D\u8981\u91CD\u590D\u521A\u5931\u8D25\u8FC7\u7684\u540C\u4E00\u52A8\u4F5C\uFF1B\u8FDE\u7EED\u5931\u8D25\u6362\u601D\u8DEF\u6216 blocked\u3002`;
+function extractDecision(raw) {
+  let s = raw.trim().replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/, "");
+  const start = s.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  for (let i = start; i < s.length; i++) {
+    if (s[i] === "{") depth++;
+    else if (s[i] === "}") {
+      depth--;
+      if (depth === 0) {
+        try {
+          return JSON.parse(s.slice(start, i + 1));
+        } catch {
+          return null;
+        }
+      }
+    }
+  }
+  return null;
+}
+var taskCommand = registerCommand({
+  name: "task",
+  description: "Autonomous goal loop: observe refs \u2192 LLM decides \u2192 act, until done/blocked (budget-capped)",
+  scope: "page",
+  parameters: z27.object({
+    goal: z27.string().describe("Natural-language goal"),
+    maxSteps: z27.number().int().positive().max(50).optional().default(15).describe("Hard action budget"),
+    timeout: z27.number().optional().default(18e4).describe("Wall clock budget in ms"),
+    limit: z27.number().int().positive().max(300).optional().default(80).describe("Max targets per observe")
+  }),
+  result: z27.object({
+    status: z27.enum(["done", "blocked", "max_steps", "error"]),
+    summary: z27.string().optional(),
+    steps: z27.array(z27.record(z27.unknown())),
+    finalUrl: z27.string().optional(),
+    usage: z27.object({ llmCalls: z27.number(), steps: z27.number() }).passthrough().optional()
+  }).passthrough(),
+  handler: async (p, ctx) => {
+    const creds = loadVLMCredentials2();
+    if (!creds) {
+      return fail12("task \u9700\u8981\u51B3\u7B56\u6A21\u578B\u51ED\u8BC1\uFF1A\u8BBE\u7F6E XBROWSER_VLM_CONFIG \u6216 ~/.zcode/v2/config.json");
+    }
+    const model = process.env.XBROWSER_TASK_MODEL || creds.model;
+    const started = Date.now();
+    const steps = [];
+    const history = [];
+    let llmCalls = 0;
+    let status = "max_steps";
+    let summary = "";
+    let lastError = "";
+    for (let step = 1; step <= p.maxSteps; step++) {
+      if (Date.now() - started > p.timeout) {
+        status = "blocked";
+        summary = `timeout after ${step - 1} steps`;
+        break;
+      }
+      const obs = await observePage(ctx.page, ctx.sessionId, { limit: p.limit, includeHidden: false });
+      const compact = obs.compact ?? obs.targets.map((t, i) => `@e${i + 1} [${t.tag ?? ""}] ${t.name ?? ""}`).join("\n");
+      const screenHash = obs.screenHash;
+      const userPayload = [
+        `\u76EE\u6807\uFF1A${p.goal}`,
+        `\u5F53\u524D\u9875\u9762\uFF08URL: ${obs.url ?? ""}\uFF09\uFF1A`,
+        compact,
+        history.length ? `
+\u5DF2\u6267\u884C\uFF08\u52FF\u91CD\u590D\u5931\u8D25\u52A8\u4F5C\uFF09\uFF1A
+${history.slice(-6).join("\n")}` : ""
+      ].filter(Boolean).join("\n");
+      let raw = "";
+      try {
+        raw = await vlmAsk({ ...creds, model }, [{ type: "text", text: `${DECISION_SYSTEM}
+
+---
+
+${userPayload}` }], 900);
+        llmCalls++;
+      } catch (e) {
+        lastError = e instanceof Error ? e.message : String(e);
+        status = "error";
+        summary = `LLM call failed: ${lastError}`;
+        break;
+      }
+      const decision = extractDecision(raw);
+      if (!decision || typeof decision.action !== "string") {
+        status = "blocked";
+        summary = `LLM returned unparsable decision: ${raw.slice(0, 120)}`;
+        break;
+      }
+      const action = decision.action;
+      const ref = typeof decision.ref === "string" ? decision.ref : void 0;
+      const value = typeof decision.value === "string" ? decision.value : void 0;
+      const thought = typeof decision.thought === "string" ? decision.thought : void 0;
+      if (action === "done") {
+        status = "done";
+        summary = value || thought || "task done";
+        steps.push({ step, thought, action: "done", ok: true, screenHash });
+        break;
+      }
+      if (action === "blocked") {
+        status = "blocked";
+        summary = value || thought || "LLM judged blocked";
+        steps.push({ step, thought, action: "blocked", ok: true, screenHash });
+        break;
+      }
+      const legalRefs = new Set(obs.targets.map((t, i) => t.ref ?? `e${i + 1}`));
+      const normalizedRef = ref ? legalRefs.has(ref.replace("@", "")) || legalRefs.has(ref) ? ref : void 0 : void 0;
+      if (ref && !normalizedRef && action !== "scroll" && action !== "press") {
+        history.push(`step${step}: ${action} ${ref} REJECTED (ref not in current list)`);
+        steps.push({ step, thought, action, ref, ok: false, error: "ref not in current list", screenHash });
+        continue;
+      }
+      const res = await actOnPage(ctx.page, ctx.sessionId, {
+        action,
+        ref: normalizedRef,
+        value,
+        selector: void 0,
+        force: false,
+        timeout: 1e4
+      });
+      const record = {
+        step,
+        thought,
+        action,
+        ref: normalizedRef,
+        value,
+        ok: res.success === true,
+        stale: res.stale,
+        error: res.success ? void 0 : res.message || res.reason,
+        screenHash
+      };
+      steps.push(record);
+      history.push(`step${step}: ${action} ${normalizedRef ?? ""} ${value ?? ""} -> ${res.success ? "ok" : `failed(${res.reason || res.message})`}`);
+      const sig = (s) => `${s.action}|${s.ref ?? ""}|${s.value ?? ""}`;
+      const last3 = steps.slice(-3);
+      if (last3.length === 3 && new Set(last3.map(sig)).size === 1) {
+        status = "blocked";
+        summary = "dead loop: identical action repeated 3 times";
+        break;
+      }
+    }
+    if (status === "max_steps") summary = summary || `hit maxSteps=${p.maxSteps}`;
+    const finalUrl = ctx.page ? ctx.page.url() : void 0;
+    const data = { status, summary, steps, finalUrl, usage: { llmCalls, steps: steps.length } };
+    if (status === "error") return fail12(summary || lastError, normalizeTips5([`completed steps: ${steps.length}`]));
+    return ok26(data, normalizeTips5([
+      status === "done" ? `\u2705 task done (${steps.length} steps, ${llmCalls} LLM calls)` : `\u26A0\uFE0F task ${status}: ${summary.slice(0, 80)}`
+    ]));
+  }
+});
+
+// src/commands/tab.ts
+import { z as z28 } from "zod";
+import { ok as ok27, fail as fail13 } from "@dyyz1993/xcli-core";
+var TabParams = z28.object({
+  subcommand: z28.enum(["list", "new", "close", "switch"]),
+  url: z28.string().optional(),
+  index: z28.number().int().min(0).optional()
 });
 var tabCommand = registerCommand({
   name: "tab",
   description: "Manage browser tabs: list, new, close, switch",
   scope: "page",
   parameters: TabParams,
-  result: z27.object({
-    success: z27.boolean(),
-    data: z27.unknown()
+  result: z28.object({
+    success: z28.boolean(),
+    data: z28.unknown()
   }),
   handler: async (p, ctx) => {
     if (!ctx.browserContext) {
-      return fail12("No browser context available. Use --cdp to connect to a browser first.");
+      return fail13("No browser context available. Use --cdp to connect to a browser first.");
     }
     const pages = ctx.browserContext.pages();
     switch (p.subcommand) {
@@ -6085,7 +6256,7 @@ var tabCommand = registerCommand({
       case "switch":
         return handleSwitch(p, pages, ctx);
       default:
-        return fail12(`Unknown subcommand: ${p.subcommand}`);
+        return fail13(`Unknown subcommand: ${p.subcommand}`);
     }
   }
 });
@@ -6100,7 +6271,7 @@ async function handleList(pages, ctx) {
     if (isActive) activeIndex = i;
     tabs.push({ index: i, url, title, active: isActive });
   }
-  return ok26({ tabs, total: tabs.length, activeIndex });
+  return ok27({ tabs, total: tabs.length, activeIndex });
 }
 async function handleNew(p, _pages, ctx) {
   const newPage = await ctx.browserContext.newPage();
@@ -6128,7 +6299,7 @@ async function handleNew(p, _pages, ctx) {
   const title = await newPage.title().catch(() => "");
   const allPages = ctx.browserContext.pages();
   const newIndex = allPages.indexOf(newPage);
-  return ok26({
+  return ok27({
     index: newIndex >= 0 ? newIndex : allPages.length - 1,
     url: newPage.url(),
     title,
@@ -6139,11 +6310,11 @@ async function handleNew(p, _pages, ctx) {
 async function handleClose(p, ctx) {
   const currentPages = ctx.browserContext.pages();
   if (currentPages.length <= 1) {
-    return fail12("Cannot close the last remaining tab");
+    return fail13("Cannot close the last remaining tab");
   }
   const closeIndex = p.index ?? currentPages.findIndex((pg) => pg === ctx.page);
   if (closeIndex < 0 || closeIndex >= currentPages.length) {
-    return fail12(`Invalid tab index: ${closeIndex}. Valid range: 0-${currentPages.length - 1}`);
+    return fail13(`Invalid tab index: ${closeIndex}. Valid range: 0-${currentPages.length - 1}`);
   }
   const pageToClose = currentPages[closeIndex];
   const isActivePage = pageToClose === ctx.page;
@@ -6158,7 +6329,7 @@ async function handleClose(p, ctx) {
     }
     ctx.page = newActivePage;
   }
-  return ok26({
+  return ok27({
     closedIndex: closeIndex,
     total: remainingPages.length,
     activeIndex: isActivePage ? closeIndex < remainingPages.length ? closeIndex : remainingPages.length - 1 : remainingPages.findIndex((pg) => pg === ctx.page)
@@ -6166,10 +6337,10 @@ async function handleClose(p, ctx) {
 }
 async function handleSwitch(p, pages, ctx) {
   if (p.index === void 0) {
-    return fail12("Parameter --index is required for switch subcommand");
+    return fail13("Parameter --index is required for switch subcommand");
   }
   if (p.index < 0 || p.index >= pages.length) {
-    return fail12(`Invalid tab index: ${p.index}. Valid range: 0-${pages.length - 1}`);
+    return fail13(`Invalid tab index: ${p.index}. Valid range: 0-${pages.length - 1}`);
   }
   const targetPage = pages[p.index];
   await targetPage.bringToFront().catch(() => {
@@ -6191,7 +6362,7 @@ async function handleSwitch(p, pages, ctx) {
   }
   ctx.page = targetPage;
   const title = await targetPage.title().catch(() => "");
-  return ok26({
+  return ok27({
     index: p.index,
     url: targetPage.url(),
     title,
@@ -6200,17 +6371,17 @@ async function handleSwitch(p, pages, ctx) {
 }
 
 // src/commands/addinitscript.ts
-import { z as z28 } from "zod";
-import { ok as ok27 } from "@dyyz1993/xcli-core";
+import { z as z29 } from "zod";
+import { ok as ok28 } from "@dyyz1993/xcli-core";
 import { readFileSync as readFileSync4 } from "fs";
-var InitScriptParams = z28.object({
-  script: z28.string().optional(),
-  file: z28.string().optional(),
-  stdin: z28.boolean().optional(),
-  name: z28.string().optional(),
-  list: z28.boolean().optional(),
-  remove: z28.union([z28.string(), z28.boolean()]).optional(),
-  base64: z28.string().optional()
+var InitScriptParams = z29.object({
+  script: z29.string().optional(),
+  file: z29.string().optional(),
+  stdin: z29.boolean().optional(),
+  name: z29.string().optional(),
+  list: z29.boolean().optional(),
+  remove: z29.union([z29.string(), z29.boolean()]).optional(),
+  base64: z29.string().optional()
 });
 var registeredScripts = /* @__PURE__ */ new Map();
 function resolveScriptContent(params) {
@@ -6244,14 +6415,14 @@ var addInitScriptCommand = registerCommand({
   description: "Add an initialization script that runs on every page load",
   scope: "page",
   parameters: InitScriptParams,
-  result: z28.object({
-    scripts: z28.array(z28.object({ name: z28.string(), size: z28.number(), preview: z28.string() })).optional(),
-    removed: z28.string().optional(),
-    existed: z28.boolean().optional(),
-    error: z28.string().optional(),
-    registered: z28.string().optional(),
-    hint: z28.string().optional(),
-    executedImmediately: z28.boolean().optional()
+  result: z29.object({
+    scripts: z29.array(z29.object({ name: z29.string(), size: z29.number(), preview: z29.string() })).optional(),
+    removed: z29.string().optional(),
+    existed: z29.boolean().optional(),
+    error: z29.string().optional(),
+    registered: z29.string().optional(),
+    hint: z29.string().optional(),
+    executedImmediately: z29.boolean().optional()
   }).passthrough(),
   handler: async (params, ctx) => {
     if (params.list) {
@@ -6260,20 +6431,20 @@ var addInitScriptCommand = registerCommand({
         size: content2.length,
         preview: content2.slice(0, 80)
       }));
-      return ok27({ scripts });
+      return ok28({ scripts });
     }
     if (params.remove && typeof params.remove === "string") {
       const existed = registeredScripts.delete(params.remove);
-      return ok27({ removed: params.remove, existed });
+      return ok28({ removed: params.remove, existed });
     }
     const removeTarget = (typeof params.remove === "string" ? params.remove : null) || (params.name && !resolveScriptContent(params) ? params.name : null);
     if (removeTarget && !resolveScriptContent(params)) {
       const existed = registeredScripts.delete(removeTarget);
-      return ok27({ removed: removeTarget, existed });
+      return ok28({ removed: removeTarget, existed });
     }
     let content = params.stdin ? await readStdin() : resolveScriptContent(params);
     if (!content) {
-      return ok27({ error: "No script content provided. Use --script, --file, --stdin, or --base64" });
+      return ok28({ error: "No script content provided. Use --script, --file, --stdin, or --base64" });
     }
     const scriptName = params.name ?? `script-${Date.now()}`;
     registeredScripts.set(scriptName, content);
@@ -6281,45 +6452,45 @@ var addInitScriptCommand = registerCommand({
     try {
       await ctx.page.evaluate(content);
     } catch {
-      return ok27({
+      return ok28({
         registered: scriptName,
         hint: "Script registered for future page loads; immediate execution skipped (page may not be ready)"
       });
     }
-    return ok27({ registered: scriptName, executedImmediately: true });
+    return ok28({ registered: scriptName, executedImmediately: true });
   }
 });
 registerCommandDefinition("addinitscript", ["script"]);
 
 // src/commands/find.ts
-import { z as z29 } from "zod";
-import { ok as ok28, fail as fail13, normalizeTips as normalizeTips5 } from "@dyyz1993/xcli-core";
-var actionSchema2 = z29.enum(["click", "fill", "type", "select", "hover", "check"]);
+import { z as z30 } from "zod";
+import { ok as ok29, fail as fail14, normalizeTips as normalizeTips6 } from "@dyyz1993/xcli-core";
+var actionSchema2 = z30.enum(["click", "fill", "type", "select", "hover", "check"]);
 var findCommand = registerCommand({
   name: "find",
   description: "Find elements by semantic strategy (text/role/label/placeholder/testid) and optionally perform an action",
   scope: "page",
-  parameters: z29.object({
-    strategy: z29.enum(["text", "role", "label", "placeholder", "testid", "alt", "title", "first", "last", "nth"]),
-    value: z29.string(),
-    name: z29.string().optional(),
-    exact: z29.boolean().optional().default(false),
-    operation: z29.string().optional().describe('Trailing operation syntax, e.g. click, fill "text", type "text"'),
+  parameters: z30.object({
+    strategy: z30.enum(["text", "role", "label", "placeholder", "testid", "alt", "title", "first", "last", "nth"]),
+    value: z30.string(),
+    name: z30.string().optional(),
+    exact: z30.boolean().optional().default(false),
+    operation: z30.string().optional().describe('Trailing operation syntax, e.g. click, fill "text", type "text"'),
     action: actionSchema2.optional().describe("Action to perform when not using trailing operation syntax"),
-    actionValue: z29.string().optional().describe("Value for fill/type/select when using action"),
-    index: z29.number().int().optional().describe("Index for nth strategy"),
-    click: z29.boolean().optional().default(false),
-    fill: z29.string().optional(),
-    type: z29.string().optional(),
-    select: z29.string().optional(),
-    hover: z29.boolean().optional().default(false),
-    check: z29.boolean().optional().default(false),
-    timeout: z29.number().optional().default(1e4)
+    actionValue: z30.string().optional().describe("Value for fill/type/select when using action"),
+    index: z30.number().int().optional().describe("Index for nth strategy"),
+    click: z30.boolean().optional().default(false),
+    fill: z30.string().optional(),
+    type: z30.string().optional(),
+    select: z30.string().optional(),
+    hover: z30.boolean().optional().default(false),
+    check: z30.boolean().optional().default(false),
+    timeout: z30.number().optional().default(1e4)
   }),
-  result: z29.object({
-    matched: z29.number(),
-    selector: z29.string(),
-    action: z29.string().optional()
+  result: z30.object({
+    matched: z30.number(),
+    selector: z30.string(),
+    action: z30.string().optional()
   }),
   handler: async (p, ctx) => {
     const page = ctx.page;
@@ -6334,7 +6505,7 @@ var findCommand = registerCommand({
     });
     const count = await locator.count();
     if (count === 0) {
-      return fail13(`No element found with ${p.strategy}="${p.value}"`);
+      return fail14(`No element found with ${p.strategy}="${p.value}"`);
     }
     const tips = [];
     const target = selectTarget(locator, p.strategy);
@@ -6346,15 +6517,15 @@ var findCommand = registerCommand({
       await target.click({ timeout: p.timeout, force: true });
       return okWithTips({ matched: count, selector, action: "click" }, tips);
     } else if (actionName === "fill") {
-      if (actionValue === void 0) return fail13("find fill requires a value");
+      if (actionValue === void 0) return fail14("find fill requires a value");
       await target.fill(actionValue, { timeout: p.timeout, force: true });
       return okWithTips({ matched: count, selector, action: `fill("${actionValue}")` }, tips);
     } else if (actionName === "type") {
-      if (actionValue === void 0) return fail13("find type requires a value");
+      if (actionValue === void 0) return fail14("find type requires a value");
       await target.type(actionValue, { delay: 10, timeout: p.timeout });
       return okWithTips({ matched: count, selector, action: `type("${actionValue}")` }, tips);
     } else if (actionName === "select") {
-      if (actionValue === void 0) return fail13("find select requires a value");
+      if (actionValue === void 0) return fail14("find select requires a value");
       await target.selectOption(actionValue);
       return okWithTips({ matched: count, selector, action: `select("${actionValue}")` }, tips);
     } else if (actionName === "hover") {
@@ -6368,8 +6539,8 @@ var findCommand = registerCommand({
   }
 });
 function okWithTips(data, tips) {
-  const result = ok28(data);
-  if (tips.length > 0) result.tips = normalizeTips5(tips);
+  const result = ok29(data);
+  if (tips.length > 0) result.tips = normalizeTips6(tips);
   return result;
 }
 function parseOperation(operation) {
@@ -6467,8 +6638,8 @@ function describeSelector(strategy, value, name) {
 }
 
 // src/commands/visual-tag.ts
-import { z as z30 } from "zod";
-import { ok as ok29, fail as fail14 } from "@dyyz1993/xcli-core";
+import { z as z31 } from "zod";
+import { ok as ok30, fail as fail15 } from "@dyyz1993/xcli-core";
 var SAFE_SET = "ahjkmnprtw3479".split("");
 var TAG_SCRIPT = `
 (function() {
@@ -6559,49 +6730,49 @@ var visualTagCommand = registerCommand({
   name: "visual-tag",
   description: "\u5728\u9875\u9762\u4E0A\u7ED9\u53EF\u4EA4\u4E92\u5143\u7D20\u53E0\u52A0\u9632\u6DF7\u6DC6\u77ED ID \u6807\u7B7E\uFF08\u89C6\u89C9\u5B9A\u4F4D\u7528\uFF09",
   scope: "page",
-  parameters: z30.object({
-    action: z30.enum(["tag", "lookup", "clear", "list"]),
-    id: z30.string().optional().describe("lookup \u65F6\u6307\u5B9A\u8981\u67E5\u7684 ID")
+  parameters: z31.object({
+    action: z31.enum(["tag", "lookup", "clear", "list"]),
+    id: z31.string().optional().describe("lookup \u65F6\u6307\u5B9A\u8981\u67E5\u7684 ID")
   }),
-  result: z30.object({
-    action: z30.string(),
-    tagged: z30.number().optional(),
-    id: z30.string().optional(),
-    element: z30.record(z30.unknown()).optional()
+  result: z31.object({
+    action: z31.string(),
+    tagged: z31.number().optional(),
+    id: z31.string().optional(),
+    element: z31.record(z31.unknown()).optional()
   }),
   handler: async (p, ctx) => {
     switch (p.action) {
       case "tag": {
         const result = await ctx.page.evaluate(TAG_SCRIPT);
         const parsed = JSON.parse(result);
-        return ok29({ action: "tag", tagged: parsed.tagged });
+        return ok30({ action: "tag", tagged: parsed.tagged });
       }
       case "lookup": {
-        if (!p.id) return fail14("lookup \u9700\u8981 --id \u53C2\u6570");
+        if (!p.id) return fail15("lookup \u9700\u8981 --id \u53C2\u6570");
         const result = await ctx.page.evaluate(
           `(function() { var m = window.__xbTagMap; if (!m) return JSON.stringify({err:'no-map'}); var e = m[${JSON.stringify(p.id)}]; return e ? JSON.stringify(e) : JSON.stringify({err:'not-found'}); })()`
         );
         const parsed = JSON.parse(result);
-        if (parsed.err) return fail14(`ID ${p.id}: ${parsed.err}`);
-        return ok29({ action: "lookup", id: p.id, element: parsed });
+        if (parsed.err) return fail15(`ID ${p.id}: ${parsed.err}`);
+        return ok30({ action: "lookup", id: p.id, element: parsed });
       }
       case "list": {
         const result = await ctx.page.evaluate(
           `(function() { var m = window.__xbTagMap; if (!m) return '{}'; var out = {}; for (var k in m) { out[k] = m[k].text || m[k].tagName; } return JSON.stringify(out); })()`
         );
-        return ok29({ action: "list", element: JSON.parse(result) });
+        return ok30({ action: "list", element: JSON.parse(result) });
       }
       case "clear": {
         await ctx.page.evaluate(`(function(){var o=document.getElementById('__xb-tag-overlay');if(o)o.remove();window.__xbTagMap=null;return 'cleared'})()`);
-        return ok29({ action: "clear" });
+        return ok30({ action: "clear" });
       }
     }
   }
 });
 
 // src/commands/visual-tag-v2.ts
-import { z as z31 } from "zod";
-import { ok as ok30, fail as fail15 } from "@dyyz1993/xcli-core";
+import { z as z32 } from "zod";
+import { ok as ok31, fail as fail16 } from "@dyyz1993/xcli-core";
 var SAFE_SET2 = "ahjkmnprtw3479".split("");
 var TAG_V2_SCRIPT = `
 (function() {
@@ -6948,45 +7119,45 @@ var visualTagV2Command = registerCommand({
   name: "visual-tag-v2",
   description: "\u5206\u8272\u6807\u6CE8\u9875\u9762\u5143\u7D20\uFF08\u7EA2=\u53EF\u70B9\u51FB \u84DD=\u8F93\u5165 \u7EFF=\u56FE\u7247 \u9EC4=\u5217\u8868 \u7D2B=\u6570\u5B57 \u6A59=\u6587\u672C\uFF09",
   scope: "page",
-  parameters: z31.object({
-    action: z31.enum(["tag", "lookup", "clear", "stats", "by-type", "find", "export", "interact"]),
-    id: z31.string().optional().describe("lookup \u65F6\u6307\u5B9A\u8981\u67E5\u7684 ID"),
-    query: z31.string().optional().describe('find \u65F6\u6307\u5B9A\u641C\u7D22\u8BCD\uFF08\u5982 "\u627E\u6709AI\u7F16\u7A0B\u6807\u7B7E\u7684\u5361\u7247"\uFF09'),
-    type: z31.string().optional().describe("by-type \u65F6\u8FC7\u6EE4\u7C7B\u578B\uFF1Aclick/input/img/list/count/text"),
-    "interact-action": z31.enum(["click", "fill", "read"]).optional().describe("interact \u52A8\u4F5C\u7C7B\u578B"),
-    value: z31.string().optional().describe("fill \u65F6\u7684\u586B\u5145\u503C")
+  parameters: z32.object({
+    action: z32.enum(["tag", "lookup", "clear", "stats", "by-type", "find", "export", "interact"]),
+    id: z32.string().optional().describe("lookup \u65F6\u6307\u5B9A\u8981\u67E5\u7684 ID"),
+    query: z32.string().optional().describe('find \u65F6\u6307\u5B9A\u641C\u7D22\u8BCD\uFF08\u5982 "\u627E\u6709AI\u7F16\u7A0B\u6807\u7B7E\u7684\u5361\u7247"\uFF09'),
+    type: z32.string().optional().describe("by-type \u65F6\u8FC7\u6EE4\u7C7B\u578B\uFF1Aclick/input/img/list/count/text"),
+    "interact-action": z32.enum(["click", "fill", "read"]).optional().describe("interact \u52A8\u4F5C\u7C7B\u578B"),
+    value: z32.string().optional().describe("fill \u65F6\u7684\u586B\u5145\u503C")
   }),
-  result: z31.object({
-    action: z31.string(),
-    total: z31.number().optional(),
-    byType: z31.record(z31.number()).optional(),
-    element: z31.record(z31.unknown()).optional()
+  result: z32.object({
+    action: z32.string(),
+    total: z32.number().optional(),
+    byType: z32.record(z32.number()).optional(),
+    element: z32.record(z32.unknown()).optional()
   }),
   handler: async (p, ctx) => {
     switch (p.action) {
       case "tag": {
         const result = await ctx.page.evaluate(TAG_V2_SCRIPT);
         const parsed = JSON.parse(result);
-        return ok30({ action: "tag", total: parsed.total, byType: parsed.byType });
+        return ok31({ action: "tag", total: parsed.total, byType: parsed.byType });
       }
       case "lookup": {
-        if (!p.id) return fail15("lookup \u9700\u8981 --id");
+        if (!p.id) return fail16("lookup \u9700\u8981 --id");
         const result = await ctx.page.evaluate(
           `(function(){var m=window.__xbTagMap;if(!m)return JSON.stringify({err:'no-map'});var e=m[${JSON.stringify(p.id)}];return e?JSON.stringify(e):JSON.stringify({err:'not-found'})})()`
         );
         const parsed = JSON.parse(result);
-        if (parsed.err) return fail15(`ID ${p.id}: ${parsed.err}`);
-        return ok30({ action: "lookup", id: p.id, element: parsed });
+        if (parsed.err) return fail16(`ID ${p.id}: ${parsed.err}`);
+        return ok31({ action: "lookup", id: p.id, element: parsed });
       }
       case "by-type": {
         const result = await ctx.page.evaluate(
           `(function(){var m=window.__xbTagMap;if(!m)return'{}';var out={};for(var k in m){if(!${JSON.stringify(p.type || "")}||m[k].type===${JSON.stringify(p.type || "")}){out[k]={type:m[k].type,text:m[k].text,num:m[k].num,label:m[k].formLabel}}}return JSON.stringify(out)})()`
         );
-        return ok30({ action: "by-type", element: JSON.parse(result) });
+        return ok31({ action: "by-type", element: JSON.parse(result) });
       }
       case "find": {
         const query = p.query;
-        if (!query) return fail15('find \u9700\u8981 --query \u53C2\u6570\uFF08\u5982 "\u627E\u6709AI\u7F16\u7A0B\u6807\u7B7E\u7684\u5361\u7247"\uFF09');
+        if (!query) return fail16('find \u9700\u8981 --query \u53C2\u6570\uFF08\u5982 "\u627E\u6709AI\u7F16\u7A0B\u6807\u7B7E\u7684\u5361\u7247"\uFF09');
         const result = await ctx.page.evaluate(
           `(function(){
             var map = window.__xbTagSerializable;
@@ -7028,21 +7199,21 @@ var visualTagV2Command = registerCommand({
             return JSON.stringify({total:results.length, results:results.slice(0,20)});
           })()`
         );
-        return ok30({ action: "find", query, element: JSON.parse(result) });
+        return ok31({ action: "find", query, element: JSON.parse(result) });
       }
       case "stats": {
         const result = await ctx.page.evaluate(
           `(function(){return JSON.stringify(window.__xbTagStats||{})})()`
         );
-        return ok30({ action: "stats", element: JSON.parse(result) });
+        return ok31({ action: "stats", element: JSON.parse(result) });
       }
       case "interact": {
         const query = p.query;
         const pAny = p;
         const action = pAny["interact-action"] || pAny.interactAction || pAny.interact_action;
         const value = pAny.value;
-        if (!query) return fail15("interact \u9700\u8981 --query \u53C2\u6570");
-        if (!action) return fail15("interact \u9700\u8981 --interact-action \u53C2\u6570\uFF08click/fill/read\uFF09");
+        if (!query) return fail16("interact \u9700\u8981 --query \u53C2\u6570");
+        if (!action) return fail16("interact \u9700\u8981 --interact-action \u53C2\u6570\uFF08click/fill/read\uFF09");
         const findResult = await ctx.page.evaluate(
           `(function(){
             var map = window.__xbTagSerializable;
@@ -7072,11 +7243,11 @@ var visualTagV2Command = registerCommand({
           })()`
         );
         const parsed = JSON.parse(findResult);
-        if (parsed.err) return fail15(parsed.err);
-        if (!parsed.total || !parsed.results?.length) return fail15(`\u672A\u627E\u5230\u5339\u914D "${query}" \u7684\u5143\u7D20`);
+        if (parsed.err) return fail16(parsed.err);
+        if (!parsed.total || !parsed.results?.length) return fail16(`\u672A\u627E\u5230\u5339\u914D "${query}" \u7684\u5143\u7D20`);
         const target = parsed.results[0];
         if (action === "read") {
-          return ok30({ action: "interact", query, target, result: { read: target.text || target.label } });
+          return ok31({ action: "interact", query, target, result: { read: target.text || target.label } });
         }
         if (action === "click") {
           const el = await ctx.page.evaluate(
@@ -7089,12 +7260,12 @@ var visualTagV2Command = registerCommand({
               return {x: Math.round(r.x + r.width/2), y: Math.round(r.y + r.height/2)};
             })()`
           );
-          if (!el) return fail15(`\u5143\u7D20 ${target.id} \u4E0D\u53EF\u4EA4\u4E92`);
+          if (!el) return fail16(`\u5143\u7D20 ${target.id} \u4E0D\u53EF\u4EA4\u4E92`);
           await ctx.page.mouse.click(el.x, el.y, { stealth: true });
-          return ok30({ action: "interact", query, target, result: { clicked: true, x: el.x, y: el.y } });
+          return ok31({ action: "interact", query, target, result: { clicked: true, x: el.x, y: el.y } });
         }
         if (action === "fill") {
-          if (!value) return fail15("fill \u9700\u8981 --value \u53C2\u6570");
+          if (!value) return fail16("fill \u9700\u8981 --value \u53C2\u6570");
           const el = await ctx.page.evaluate(
             `(function(){
               var map = window.__xbTagMap;
@@ -7105,12 +7276,12 @@ var visualTagV2Command = registerCommand({
               return {x: Math.round(r.x + r.width/2), y: Math.round(r.y + r.height/2)};
             })()`
           );
-          if (!el) return fail15(`\u5143\u7D20 ${target.id} \u4E0D\u53EF\u4EA4\u4E92`);
+          if (!el) return fail16(`\u5143\u7D20 ${target.id} \u4E0D\u53EF\u4EA4\u4E92`);
           await ctx.page.mouse.click(el.x, el.y, { stealth: true });
           await ctx.page.keyboard.type(value, { stealth: true });
-          return ok30({ action: "interact", query, target, result: { filled: true, value } });
+          return ok31({ action: "interact", query, target, result: { filled: true, value } });
         }
-        return fail15(`\u672A\u77E5 action: ${action}`);
+        return fail16(`\u672A\u77E5 action: ${action}`);
       }
       case "export": {
         const result = await ctx.page.evaluate(
@@ -7158,12 +7329,12 @@ var visualTagV2Command = registerCommand({
           })()`
         );
         const parsed = JSON.parse(result);
-        if (parsed.err) return fail15(String(parsed.err));
-        return ok30({ action: "export", element: parsed });
+        if (parsed.err) return fail16(String(parsed.err));
+        return ok31({ action: "export", element: parsed });
       }
       case "clear": {
         await ctx.page.evaluate(`(function(){var o=document.getElementById('__xb-tag-overlay');if(o)o.remove();window.__xbTagMap=null;window.__xbTagStats=null;return 'ok'})()`);
-        return ok30({ action: "clear" });
+        return ok31({ action: "clear" });
       }
     }
   }
@@ -7689,12 +7860,12 @@ function classifyFailure(message) {
 
 // src/executor.ts
 import {
-  ok as ok31,
-  fail as fail16,
+  ok as ok32,
+  fail as fail17,
   isCommandResult,
   CompositeStorage as CompositeStorage2,
   TipCollector as TipCollector2,
-  normalizeTips as normalizeTips6,
+  normalizeTips as normalizeTips7,
   configureArchiveStore,
   appendCommandToArchive,
   checkGuard,
@@ -8295,7 +8466,10 @@ function buildSnapshot(elements) {
 }
 
 // src/tips/index.ts
-var DEBOUNCE_MS = 500;
+function tipsDebounceMs() {
+  const v = parseInt(process.env.XBROWSER_TIPS_DEBOUNCE ?? "120", 10);
+  return Number.isFinite(v) && v > 0 ? v : 0;
+}
 var SKIP_DETECT_COMMANDS = /* @__PURE__ */ new Set([
   "goto",
   // 导航命令不需要检测
@@ -8387,7 +8561,9 @@ var TipsManager = class {
     }
   }
   debounce() {
-    return new Promise((resolve3) => setTimeout(resolve3, DEBOUNCE_MS));
+    const ms = tipsDebounceMs();
+    if (ms <= 0) return Promise.resolve();
+    return new Promise((resolve3) => setTimeout(resolve3, ms));
   }
   formatTips(tips) {
     return tips.map((tip) => {
@@ -8556,7 +8732,7 @@ async function guardCheck(commandName) {
   }
 }
 function errorResult(message) {
-  return { ...fail16(message), duration: 0 };
+  return { ...fail17(message), duration: 0 };
 }
 function tipsToMessages(tips) {
   if (!tips || tips.length === 0) return [];
@@ -8636,7 +8812,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
   }
   let targetPageOverride = null;
   if (_target && extraOpts?.cdpEndpoint) {
-    const { findTargetPage } = await import("./browser-L3TUDYY3.js");
+    const { findTargetPage } = await import("./browser-4IYIHZ6R.js");
     targetPageOverride = await findTargetPage(extraOpts.cdpEndpoint, _target);
     if (!targetPageOverride) {
       return errorResult(`Target "${_target}" not found. Use 'xbrowser targets --cdp ${extraOpts.cdpEndpoint}' to list available pages.`);
@@ -8748,7 +8924,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
     const cache = /* @__PURE__ */ new Map();
     const resolved = await resolveRefParams(session.page, params, command.selectorParams, cache, session.id);
     if (resolved.tips.length > 0) {
-      refTips = normalizeTips6(resolved.tips);
+      refTips = normalizeTips7(resolved.tips);
       params = resolved.params;
     }
   }
@@ -8816,8 +8992,8 @@ async function executeCommand(commandName, params, sessionName = "default", extr
       }
       const merged = [
         ...raw.tips || [],
-        ...normalizeTips6(smartTips),
-        ...snapshotHint ? normalizeTips6([snapshotHint]) : [],
+        ...normalizeTips7(smartTips),
+        ...snapshotHint ? normalizeTips7([snapshotHint]) : [],
         ...refTips
       ];
       const isSuccess = raw.success !== false;
@@ -8832,7 +9008,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
         timestamp: start
       });
       if (isSuccess) {
-        return { ...ok31(raw.data, merged.length > 0 ? merged : raw.tips), duration, ...hookOutputs ? { hookOutputs } : {} };
+        return { ...ok32(raw.data, merged.length > 0 ? merged : raw.tips), duration, ...hookOutputs ? { hookOutputs } : {} };
       }
       const fc = classifyFailure(raw.message);
       return {
@@ -8845,7 +9021,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
         ...hookOutputs ? { hookOutputs } : {}
       };
     }
-    const smartTipNormalized = normalizeTips6(smartTips);
+    const smartTipNormalized = normalizeTips7(smartTips);
     recordArchive(session?.id, sessionName, {
       step: 0,
       command: commandName,
@@ -8855,7 +9031,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
       duration,
       timestamp: start
     });
-    return { ...ok31(raw, smartTipNormalized), duration, ...hookOutputs ? { hookOutputs } : {} };
+    return { ...ok32(raw, smartTipNormalized), duration, ...hookOutputs ? { hookOutputs } : {} };
   } catch (err) {
     const end = Date.now();
     const duration = end - start;
@@ -8900,7 +9076,7 @@ async function executeCommand(commandName, params, sessionName = "default", extr
       duration,
       timestamp: start
     });
-    return { ...fail16(errorMessage), duration };
+    return { ...fail17(errorMessage), duration };
   } finally {
   }
 }
@@ -8945,7 +9121,7 @@ async function executeChain(input, options) {
             results.push({
               command: cmdName,
               raw: cmdStr,
-              ...fail16(`Plugin "${cmdName}" requires a sub-command`),
+              ...fail17(`Plugin "${cmdName}" requires a sub-command`),
               duration: 0
             });
             if (type === "and") {
@@ -8964,7 +9140,7 @@ async function executeChain(input, options) {
             results.push({
               command: cmdName,
               raw: cmdStr,
-              ...fail16(`Unknown command "${subCommand}" for plugin "${cmdName}"`),
+              ...fail17(`Unknown command "${subCommand}" for plugin "${cmdName}"`),
               duration: 0
             });
             if (type === "and") {
@@ -9034,7 +9210,7 @@ async function executeChain(input, options) {
                 success: false,
                 data: data2,
                 message: loginGuard.message,
-                tips: normalizeTips6(loginGuard.tips),
+                tips: normalizeTips7(loginGuard.tips),
                 duration: duration3
               });
               if (type === "and") {
@@ -9076,7 +9252,7 @@ async function executeChain(input, options) {
             results.push({
               command: `${cmdName} ${subCommand}`,
               raw: cmdStr,
-              ...ok31(data),
+              ...ok32(data),
               duration: duration2,
               ...hookOutputs ? { hookOutputs } : {}
             });
@@ -9104,7 +9280,7 @@ async function executeChain(input, options) {
             results.push({
               command: `${cmdName} ${subCommand}`,
               raw: cmdStr,
-              ...fail16(errorMessage),
+              ...fail17(errorMessage),
               duration: duration2
             });
             if (type === "and") {