xshat-lite 1.0.0

package/src/modules/browser.mjs

@@ -0,0 +1,1384 @@
+import { launchPersistentContext } from 'cloakbrowser';
+import { resolve } from 'node:path';
+import config from '../utils/config.mjs';
+
+function profileDirForChannel(userDataDir, channel) {
+  return resolve(userDataDir, channel);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function clipText(text, maxChars = 400) {
+  const normalized = String(text ?? '')
+    .replace(/\s+/g, ' ')
+    .trim();
+
+  if (normalized.length <= maxChars) {
+    return normalized;
+  }
+
+  return `${normalized.slice(0, Math.max(0, maxChars - 1))}…`;
+}
+
+function pushLimited(list, item, maxEntries = 30) {
+  list.push(item);
+  if (list.length > maxEntries) {
+    list.splice(0, list.length - maxEntries);
+  }
+}
+
+function createObservationStore(maxEntries = 30) {
+  return {
+    maxEntries,
+    updatedAt: null,
+    requests: [],
+    responses: [],
+    console: [],
+    pageErrors: [],
+    websockets: []
+  };
+}
+
+function pickHeader(headers = {}, name = '') {
+  const lowerName = String(name).toLowerCase();
+  for (const [key, value] of Object.entries(headers || {})) {
+    if (String(key).toLowerCase() === lowerName) {
+      return value;
+    }
+  }
+  return '';
+}
+
+function isTextLikeContentType(contentType = '') {
+  const value = String(contentType).toLowerCase();
+  return (
+    value.includes('json') ||
+    value.includes('text/') ||
+    value.includes('javascript') ||
+    value.includes('xml') ||
+    value.includes('html')
+  );
+}
+
+function localStorageEntriesFromState(state = {}) {
+  return (state.origins || [])
+    .filter((origin) => origin?.origin && Array.isArray(origin.localStorage))
+    .map((origin) => ({
+      origin: origin.origin,
+      localStorage: origin.localStorage
+    }));
+}
+
+function splitSelectorCandidates(selector) {
+  const source = String(selector ?? '').trim();
+  if (!source) {
+    return [];
+  }
+
+  const parts = [];
+  let current = '';
+  let quote = '';
+  let depth = 0;
+
+  for (let index = 0; index < source.length; index++) {
+    const char = source[index];
+    const prev = source[index - 1];
+
+    if (quote) {
+      current += char;
+      if (char === quote && prev !== '\\') {
+        quote = '';
+      }
+      continue;
+    }
+
+    if (char === '"' || char === '\'') {
+      quote = char;
+      current += char;
+      continue;
+    }
+
+    if (char === '(' || char === '[') {
+      depth++;
+      current += char;
+      continue;
+    }
+
+    if ((char === ')' || char === ']') && depth > 0) {
+      depth--;
+      current += char;
+      continue;
+    }
+
+    if (char === ',' && depth === 0) {
+      if (current.trim()) {
+        parts.push(current.trim());
+      }
+      current = '';
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (current.trim()) {
+    parts.push(current.trim());
+  }
+
+  return parts;
+}
+
+const genericEditableFallbacks = [
+  { selector: 'textarea:not([disabled]):not([readonly])', weight: 120 },
+  { selector: 'textarea[placeholder]', weight: 140 },
+  { selector: 'input[type="text"]:not([disabled]):not([readonly])', weight: 105 },
+  { selector: 'input[type="search"]:not([disabled]):not([readonly])', weight: 100 },
+  { selector: 'input:not([type]):not([disabled]):not([readonly])', weight: 95 },
+  { selector: '[contenteditable="true"]', weight: 135 },
+  { selector: '[contenteditable="plaintext-only"]', weight: 135 },
+  { selector: '[role="textbox"]', weight: 90 },
+  { selector: 'textarea', weight: 60 },
+  { selector: 'input', weight: 30 }
+];
+
+const chatLikeInputPattern = /message|prompt|chat|ask|question|input|search|write|tell|输入|消息|提问|发送|对话|问题|搜索|写点/i;
+
+function isRecoverableActionError(error) {
+  const message = String(error?.message || error || '').toLowerCase();
+  return [
+    'element is not visible',
+    'element is outside of the viewport',
+    'element is not attached to the dom',
+    'element is detached from document',
+    'another element',
+    'intercepts pointer events',
+    'not stable',
+    'timeout',
+    'strict mode violation'
+  ].some((pattern) => message.includes(pattern));
+}
+
+async function pickBestLocator(page, selector, {
+  requireEditable = false
+} = {}) {
+  const locator = page.locator(selector);
+  const count = await locator.count().catch(() => 0);
+
+  if (count <= 0) {
+    return null;
+  }
+
+  let fallback = null;
+
+  for (let index = 0; index < count; index++) {
+    const candidate = locator.nth(index);
+
+    if (!fallback) {
+      fallback = candidate;
+    }
+
+    try {
+      const visible = typeof candidate.isVisible === 'function'
+        ? await candidate.isVisible()
+        : true;
+
+      if (!visible) {
+        continue;
+      }
+
+      if (!requireEditable) {
+        return candidate;
+      }
+
+      const editable = await candidate.evaluate((node) => {
+        if (!(node instanceof HTMLElement)) {
+          return false;
+        }
+
+        if (node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement) {
+          return !node.disabled && !node.readOnly;
+        }
+
+        return node.isContentEditable;
+      }).catch(() => false);
+
+      if (editable) {
+        return candidate;
+      }
+    } catch {
+      // keep trying other matches
+    }
+  }
+
+  return fallback;
+}
+
+function scoreEditableCandidate(meta = {}, baseWeight = 0) {
+  let score = Number(baseWeight) || 0;
+  const tag = String(meta.tag || '').toLowerCase();
+  const type = String(meta.type || '').toLowerCase();
+  const combinedHint = [
+    meta.placeholder,
+    meta.ariaLabel,
+    meta.name,
+    meta.id,
+    ...(Array.isArray(meta.classes) ? meta.classes : [])
+  ].join(' ');
+
+  if (meta.visible) {
+    score += 220;
+  } else {
+    score -= 220;
+  }
+
+  if (meta.editable) {
+    score += 180;
+  } else {
+    score -= 280;
+  }
+
+  if (tag === 'textarea') {
+    score += 80;
+  }
+
+  if (tag === 'input') {
+    if (!type || ['text', 'search', 'email', 'url', 'tel'].includes(type)) {
+      score += 60;
+    } else {
+      score -= 120;
+    }
+  }
+
+  if (meta.contentEditable) {
+    score += 75;
+  }
+
+  if (meta.role === 'textbox') {
+    score += 40;
+  }
+
+  if (chatLikeInputPattern.test(combinedHint)) {
+    score += 110;
+  }
+
+  if ((meta.textLength || 0) > 0) {
+    score += Math.min(30, Math.floor((meta.textLength || 0) / 8));
+  }
+
+  const area = Number(meta.area) || 0;
+  if (area > 0) {
+    score += Math.min(45, Math.floor(area / 1200));
+  }
+
+  return score;
+}
+
+async function inspectEditableCandidate(locator) {
+  return locator.evaluate((node) => {
+    if (!(node instanceof HTMLElement)) {
+      return null;
+    }
+
+    const style = window.getComputedStyle(node);
+    const rect = node.getBoundingClientRect();
+    const tag = node.tagName.toLowerCase();
+    const input = node instanceof HTMLInputElement ? node : null;
+    const textarea = node instanceof HTMLTextAreaElement ? node : null;
+    const editable = Boolean(
+      (input && !input.disabled && !input.readOnly) ||
+      (textarea && !textarea.disabled && !textarea.readOnly) ||
+      node.isContentEditable
+    );
+
+    return {
+      tag,
+      type: input?.type || '',
+      role: node.getAttribute('role') || '',
+      placeholder: input?.placeholder || textarea?.placeholder || node.getAttribute('placeholder') || '',
+      ariaLabel: node.getAttribute('aria-label') || '',
+      name: node.getAttribute('name') || '',
+      id: node.id || '',
+      classes: typeof node.className === 'string'
+        ? node.className.split(/\s+/).filter(Boolean).slice(0, 8)
+        : [],
+      contentEditable: node.isContentEditable,
+      editable,
+      visible: (
+        rect.width > 0 &&
+        rect.height > 0 &&
+        style.visibility !== 'hidden' &&
+        style.display !== 'none'
+      ),
+      textLength: String(node.textContent || '').trim().length,
+      area: Math.round(rect.width * rect.height)
+    };
+  }).catch(() => null);
+}
+
+async function findEditableFallbackLocator(page) {
+  const best = {
+    locator: null,
+    score: Number.NEGATIVE_INFINITY
+  };
+
+  for (const entry of genericEditableFallbacks) {
+    const locator = page.locator(entry.selector);
+    const count = await locator.count().catch(() => 0);
+
+    for (let index = 0; index < count; index++) {
+      const candidate = locator.nth(index);
+      const meta = await inspectEditableCandidate(candidate);
+      if (!meta) {
+        continue;
+      }
+
+      const score = scoreEditableCandidate(meta, entry.weight);
+      if (score > best.score) {
+        best.locator = candidate;
+        best.score = score;
+      }
+    }
+  }
+
+  return best.locator;
+}
+
+export class BrowserManager {
+  constructor({
+    launcher = launchPersistentContext,
+    browserConfig = config.browser
+  } = {}) {
+    this.launcher = launcher;
+    this.browserConfig = { ...browserConfig };
+    this.channels = new Map();
+    this.chatManager = null;
+  }
+
+  setChatManager(chatManager = null) {
+    this.chatManager = chatManager || null;
+  }
+
+  getChatManager() {
+    return this.chatManager;
+  }
+
+  _getChannel(name) {
+    if (!this.channels.has(name)) {
+      this.channels.set(name, {
+        browser: null,
+        page: null,
+        config: { ...this.browserConfig },
+        pendingNavigation: null,
+        lastNavigationError: null,
+        observation: createObservationStore(
+          Number(this.browserConfig.observationLimit) || 30
+        )
+      });
+    }
+
+    return this.channels.get(name);
+  }
+
+  _markChannelClosed(name = 'chat') {
+    const channel = this._getChannel(name);
+    channel.browser = null;
+    channel.page = null;
+    channel.pendingNavigation = null;
+    channel.lastNavigationError = null;
+  }
+
+  _isClosedError(error) {
+    const message = String(error?.message || error || '').toLowerCase();
+    return (
+      message.includes('has been closed') ||
+      message.includes('target page, context or browser has been closed') ||
+      message.includes('browser has been closed') ||
+      message.includes('context has been closed') ||
+      message.includes('page has been closed')
+    );
+  }
+
+  async probeChannel(name = 'chat') {
+    const channel = this._getChannel(name);
+    if (!channel.browser || !channel.page) {
+      this._markChannelClosed(name);
+      return false;
+    }
+
+    try {
+      if (typeof channel.page.url === 'function') {
+        channel.page.url();
+      }
+
+      if (typeof channel.browser.pages === 'function') {
+        await channel.browser.pages();
+      }
+
+      return true;
+    } catch (error) {
+      if (this._isClosedError(error)) {
+        this._markChannelClosed(name);
+        return false;
+      }
+      throw error;
+    }
+  }
+
+  async launchChannel(name = 'chat', overrides = {}) {
+    const channel = this._getChannel(name);
+    const launchOptions = {
+      headless: overrides.headless ?? channel.config.headless,
+      humanize: overrides.humanize ?? channel.config.humanize,
+      userDataDir:
+        overrides.userDataDir ??
+        profileDirForChannel(channel.config.userDataDir, name)
+    };
+
+    channel.config = {
+      ...channel.config,
+      ...overrides,
+      ...launchOptions
+    };
+
+    channel.browser = await this.launcher({
+      headless: launchOptions.headless,
+      humanize: launchOptions.humanize,
+      userDataDir: launchOptions.userDataDir
+    });
+
+    channel.observation = createObservationStore(
+      Number(channel.config.observationLimit) ||
+      Number(this.browserConfig.observationLimit) ||
+      30
+    );
+    channel.page = await channel.browser.newPage();
+    this.annotatePage(channel.page, name);
+    this.attachChannelObservers(name);
+
+    if (this.browserConfig.shareAuthState && name !== 'chat' && this.isChannelReady('chat')) {
+      await this.syncStorageState('chat', name);
+    }
+
+    return channel.page;
+  }
+
+  async init(overrides = {}) {
+    return this.initChannel('chat', overrides);
+  }
+
+  async initChannel(name = 'chat', overrides = {}) {
+    const channel = this._getChannel(name);
+    if (await this.probeChannel(name)) {
+      return channel.page;
+    }
+
+    return this.launchChannel(name, overrides);
+  }
+
+  async goto(url) {
+    return this.gotoChannel('chat', url);
+  }
+
+  async gotoChannel(name = 'chat', url) {
+    return this.navigateChannel(name, url, { background: false });
+  }
+
+  async navigateChannel(name = 'chat', url, {
+    background = false,
+    waitUntil = 'domcontentloaded',
+    timeout
+  } = {}) {
+    const channel = this._getChannel(name);
+    if (!await this.probeChannel(name)) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    channel.lastNavigationError = null;
+    const navigation = channel.page.goto(url, {
+      waitUntil,
+      timeout: timeout ?? channel.config.gotoTimeout
+    });
+
+    if (!background) {
+      await navigation;
+      return channel.page;
+    }
+
+    channel.pendingNavigation = navigation
+      .catch((error) => {
+        channel.lastNavigationError = error;
+        return null;
+      })
+      .finally(() => {
+        channel.pendingNavigation = null;
+      });
+
+    return channel.page;
+  }
+
+  getCurrentUrl() {
+    return this.getCurrentUrlFor('chat');
+  }
+
+  getCurrentUrlFor(name = 'chat') {
+    const channel = this._getChannel(name);
+    return channel.page ? channel.page.url() : null;
+  }
+
+  async relaunch({ url, ...overrides } = {}) {
+    return this.relaunchChannel('chat', { url, ...overrides });
+  }
+
+  async relaunchChannel(name = 'chat', { url, ...overrides } = {}) {
+    const targetUrl = url ?? this.getCurrentUrlFor(name);
+    await this.closeChannel(name);
+    await this.launchChannel(name, overrides);
+
+    if (targetUrl) {
+      await this.gotoChannel(name, targetUrl);
+    }
+
+    const page = this.getPage(name);
+    if (typeof page?.bringToFront === 'function') {
+      await page.bringToFront();
+    }
+
+    return page;
+  }
+
+  annotatePage(page, name = 'chat') {
+    if (!page || typeof page !== 'object') {
+      return;
+    }
+
+    try {
+      page.__xshatChannelName = name;
+      page.__xshatBrowserManager = this;
+    } catch {
+      // ignore non-extensible page wrappers
+    }
+  }
+
+  attachChannelObservers(name = 'chat') {
+    const channel = this._getChannel(name);
+    const page = channel.page;
+    if (!page || typeof page.on !== 'function') {
+      return;
+    }
+
+    const observation = channel.observation;
+    const maxEntries = observation.maxEntries;
+    const markUpdated = () => {
+      observation.updatedAt = nowIso();
+    };
+
+    const pushEntry = (bucket, entry) => {
+      pushLimited(bucket, {
+        time: nowIso(),
+        ...entry
+      }, maxEntries);
+      markUpdated();
+    };
+
+    page.on('request', (request) => {
+      try {
+        pushEntry(observation.requests, {
+          method: request?.method?.() || 'GET',
+          url: request?.url?.() || '',
+          resourceType: request?.resourceType?.() || '',
+          navigation: Boolean(request?.isNavigationRequest?.())
+        });
+      } catch {
+        // ignore observer failures
+      }
+    });
+
+    page.on('requestfailed', (request) => {
+      try {
+        pushEntry(observation.requests, {
+          method: request?.method?.() || 'GET',
+          url: request?.url?.() || '',
+          resourceType: request?.resourceType?.() || '',
+          navigation: Boolean(request?.isNavigationRequest?.()),
+          failed: true,
+          failureText: request?.failure?.()?.errorText || 'request failed'
+        });
+      } catch {
+        // ignore observer failures
+      }
+    });
+
+    page.on('response', (response) => {
+      const entry = {
+        time: nowIso(),
+        url: response?.url?.() || '',
+        status: response?.status?.() || 0,
+        ok: Boolean(response?.ok?.()),
+        method: response?.request?.()?.method?.() || 'GET',
+        resourceType: response?.request?.()?.resourceType?.() || '',
+        contentType: '',
+        bodyPreview: '',
+        bodyCaptured: false
+      };
+      pushLimited(observation.responses, entry, maxEntries);
+      markUpdated();
+
+      Promise.resolve()
+        .then(async () => {
+          const headers = await response.headers();
+          entry.contentType = pickHeader(headers, 'content-type');
+
+          if (!isTextLikeContentType(entry.contentType)) {
+            return;
+          }
+
+          const bodyText = await response.text();
+          entry.bodyPreview = clipText(bodyText, 500);
+          entry.bodyCaptured = true;
+          markUpdated();
+        })
+        .catch(() => {});
+    });
+
+    page.on('console', async (message) => {
+      try {
+        const type = message?.type?.() || 'log';
+        const text = clipText(message?.text?.() || '', 300);
+        if (!text) {
+          return;
+        }
+
+        pushEntry(observation.console, {
+          type,
+          text
+        });
+      } catch {
+        // ignore observer failures
+      }
+    });
+
+    page.on('pageerror', (error) => {
+      try {
+        pushEntry(observation.pageErrors, {
+          message: clipText(error?.message || String(error), 400)
+        });
+      } catch {
+        // ignore observer failures
+      }
+    });
+
+    page.on('websocket', (socket) => {
+      try {
+        pushEntry(observation.websockets, {
+          url: socket?.url?.() || ''
+        });
+      } catch {
+        // ignore observer failures
+      }
+    });
+  }
+
+  async openAgentPage(url, overrides = {}) {
+    const agentWasReady = this.isChannelReady('agent');
+    const allowVisibleBrowser = this.browserConfig.allowVisibleBrowser !== false;
+
+    await this.initChannel('agent', {
+      headless: allowVisibleBrowser ? false : true,
+      ...overrides
+    });
+
+    if (
+      agentWasReady &&
+      this.browserConfig.shareAuthState &&
+      this.isChannelReady('chat')
+    ) {
+      await this.syncStorageState('chat', 'agent');
+    }
+
+    await this.navigateChannel('agent', url, {
+      background: true,
+      waitUntil: overrides.waitUntil || 'domcontentloaded',
+      timeout: overrides.timeout
+    });
+    const page = this.getPage('agent');
+    if (typeof page?.bringToFront === 'function') {
+      await page.bringToFront();
+    }
+    return page;
+  }
+
+  async exportStorageState(name = 'chat') {
+    const channel = this._getChannel(name);
+    if (!await this.probeChannel(name)) {
+      return null;
+    }
+
+    if (!channel.browser || typeof channel.browser.storageState !== 'function') {
+      return null;
+    }
+
+    return channel.browser.storageState();
+  }
+
+  async importStorageState(name = 'agent', state = null) {
+    const channel = this._getChannel(name);
+    if (!state) {
+      return false;
+    }
+
+    if (!await this.probeChannel(name)) {
+      return false;
+    }
+
+    if (!channel.browser) {
+      return false;
+    }
+
+    if (Array.isArray(state.cookies) && state.cookies.length > 0) {
+      if (typeof channel.browser.addCookies === 'function') {
+        try {
+          await channel.browser.addCookies(state.cookies);
+        } catch (error) {
+          if (this._isClosedError(error)) {
+            this._markChannelClosed(name);
+            return false;
+          }
+          throw error;
+        }
+      }
+    }
+
+    const originStates = localStorageEntriesFromState(state);
+    if (originStates.length === 0 || typeof channel.browser.newPage !== 'function') {
+      return true;
+    }
+
+    let tempPage;
+    try {
+      tempPage = await channel.browser.newPage();
+    } catch (error) {
+      if (this._isClosedError(error)) {
+        this._markChannelClosed(name);
+        return false;
+      }
+      throw error;
+    }
+    try {
+      for (const originState of originStates) {
+        if (!originState.localStorage.length) {
+          continue;
+        }
+
+        try {
+          await tempPage.goto(originState.origin, {
+            waitUntil: 'domcontentloaded',
+            timeout: channel.config.gotoTimeout
+          });
+          await tempPage.evaluate((entries) => {
+            for (const item of entries) {
+              if (!item?.name) {
+                continue;
+              }
+              localStorage.setItem(item.name, String(item.value ?? ''));
+            }
+          }, originState.localStorage);
+        } catch {
+          // 某些站点不允许直接访问 origin 根路径，这里静默跳过，cookies 仍会保留。
+        }
+      }
+    } finally {
+      if (typeof tempPage.close === 'function') {
+        await tempPage.close().catch(() => {});
+      }
+    }
+
+    return true;
+  }
+
+  async syncStorageState(from = 'chat', to = 'agent') {
+    if (from === to) {
+      return false;
+    }
+
+    const sourceReady = await this.probeChannel(from).catch(() => false);
+    const targetReady = await this.probeChannel(to).catch(() => false);
+    if (!sourceReady || !targetReady) {
+      return false;
+    }
+
+    const state = await this.exportStorageState(from);
+    if (!state) {
+      return false;
+    }
+
+    return this.importStorageState(to, state);
+  }
+
+  async waitForChannelNavigation(name = 'agent') {
+    const channel = this._getChannel(name);
+    if (channel.pendingNavigation) {
+      await channel.pendingNavigation;
+    }
+
+    return {
+      error: channel.lastNavigationError
+    };
+  }
+
+  getChannelObservation(name = 'chat', { limit = 5 } = {}) {
+    const channel = this._getChannel(name);
+    const observation = channel.observation || createObservationStore();
+    const slice = (items = []) => items.slice(-Math.max(1, limit));
+
+    return {
+      updatedAt: observation.updatedAt,
+      counts: {
+        requests: observation.requests.length,
+        responses: observation.responses.length,
+        console: observation.console.length,
+        pageErrors: observation.pageErrors.length,
+        websockets: observation.websockets.length
+      },
+      requests: slice(observation.requests),
+      responses: slice(observation.responses),
+      console: slice(observation.console),
+      pageErrors: slice(observation.pageErrors),
+      websockets: slice(observation.websockets)
+    };
+  }
+
+  async readChannelSnapshot(name = 'agent', {
+    maxChars = 4000,
+    includeHtml = false,
+    includeDomSummary = false,
+    includeObservation = true
+  } = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+
+    const title = typeof page.title === 'function' ? await page.title() : '';
+    const url = typeof page.url === 'function' ? page.url() : '';
+    const bodyText = await page.evaluate(() => document.body?.innerText || '');
+    const text = String(bodyText ?? '').replace(/\s+/g, ' ').trim().slice(0, maxChars);
+    const snapshot = {
+      title,
+      url,
+      text
+    };
+
+    if (includeObservation) {
+      snapshot.observation = this.getChannelObservation(name);
+    }
+
+    if (includeHtml && typeof page.content === 'function') {
+      try {
+        snapshot.html = clipText(await page.content(), maxChars);
+      } catch {
+        snapshot.html = '';
+      }
+    }
+
+    if (includeDomSummary) {
+      snapshot.dom = await this.inspectDom(name, {
+        selector: 'body',
+        maxNodes: 12,
+        textLimit: 80
+      });
+    }
+
+    return snapshot;
+  }
+
+  async clickSelector(name = 'agent', selector, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const selectors = splitSelectorCandidates(selector);
+    const timeout = options.timeout ?? 5000;
+    const maxAttempts = Math.max(
+      1,
+      Number(options.retryCount ?? this.browserConfig.actionRetryCount) || 1
+    );
+    const retryDelayMs =
+      Number(options.retryDelayMs ?? this.browserConfig.actionRetryDelayMs) || 350;
+    let lastError = null;
+
+    for (const candidate of selectors) {
+      for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        const locator = await pickBestLocator(page, candidate);
+
+        if (!locator) {
+          lastError = new Error(`未找到可点击元素: ${candidate}`);
+          break;
+        }
+
+        try {
+          await locator.waitFor({
+            state: options.state || 'attached',
+            timeout
+          });
+          await locator.scrollIntoViewIfNeeded().catch(() => {});
+          if (typeof page.waitForTimeout === 'function') {
+            await page.waitForTimeout(Math.min(250, retryDelayMs));
+          }
+          await locator.click({
+            timeout,
+            force: options.force ?? false
+          });
+          if (options.waitForNavigation || options.afterWaitForNavigation) {
+            await page.waitForLoadState(options.navigationState || 'domcontentloaded', {
+              timeout: options.navigationTimeout ?? timeout
+            }).catch(() => {});
+          } else if (typeof page.waitForTimeout === 'function') {
+            await page.waitForTimeout(Math.min(300, retryDelayMs));
+          }
+          return;
+        } catch (error) {
+          lastError = error;
+
+          if (!isRecoverableActionError(error) || attempt >= maxAttempts) {
+            break;
+          }
+
+          await locator.scrollIntoViewIfNeeded().catch(() => {});
+          await page.waitForTimeout(retryDelayMs);
+
+          try {
+            await locator.click({
+              timeout,
+              force: true
+            });
+            return;
+          } catch (forcedError) {
+            lastError = forcedError;
+
+            if (!isRecoverableActionError(forcedError) || attempt >= maxAttempts) {
+              break;
+            }
+
+            await page.waitForTimeout(retryDelayMs);
+          }
+        }
+      }
+    }
+
+    throw lastError || new Error(`点击失败: ${selector}`);
+  }
+
+  async typeSelector(name = 'agent', selector, text, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const selectors = splitSelectorCandidates(selector);
+    const timeout = options.timeout ?? 5000;
+    let locator = null;
+
+    for (const candidate of selectors) {
+      locator = await pickBestLocator(page, candidate, { requireEditable: true });
+      if (locator) {
+        break;
+      }
+    }
+
+    if (!locator) {
+      locator = await findEditableFallbackLocator(page);
+    }
+
+    if (!locator) {
+      throw new Error(`未找到可输入元素: ${selector}（已尝试通用输入框回退）`);
+    }
+
+    await locator.waitFor({
+      state: options.state || 'attached',
+      timeout
+    });
+    await locator.scrollIntoViewIfNeeded().catch(() => {});
+    await locator.click({
+      timeout,
+      force: options.force ?? true
+    });
+    if (typeof locator.focus === 'function') {
+      await locator.focus().catch(() => {});
+    }
+
+    if (options.clear !== false) {
+      const modifier = process.platform === 'darwin' ? 'Meta' : 'Control';
+      await page.keyboard.press(`${modifier}+A`).catch(() => {});
+      await page.keyboard.press('Backspace').catch(() => {});
+    }
+
+    const inputValue = String(text ?? '');
+
+    try {
+      if (typeof locator.fill === 'function') {
+        await locator.fill(inputValue);
+      } else if (page.keyboard?.insertText) {
+        await page.keyboard.insertText(inputValue);
+      } else if (page.keyboard?.type) {
+        await page.keyboard.type(inputValue);
+      }
+    } catch {
+      await locator.evaluate((node, value) => {
+        if (node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement) {
+          node.value = value;
+          node.dispatchEvent(new Event('input', { bubbles: true }));
+          node.dispatchEvent(new Event('change', { bubbles: true }));
+          return;
+        }
+
+        if (node instanceof HTMLElement) {
+          node.focus();
+          node.textContent = value;
+          node.dispatchEvent(new InputEvent('input', {
+            bubbles: true,
+            data: value,
+            inputType: 'insertText'
+          }));
+        }
+      }, inputValue);
+    }
+
+    if (options.pressEnter || options.submit) {
+      await page.keyboard.press(options.submitKey || 'Enter').catch(() => {});
+    }
+
+    if (typeof page.waitForTimeout === 'function') {
+      await page.waitForTimeout(150);
+    }
+  }
+
+  async waitForText(name = 'agent', text, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+
+    const timeout = options.timeout ?? 10000;
+    if (options.selector) {
+      await page.locator(options.selector).filter({ hasText: text }).first().waitFor({
+        timeout
+      });
+      return;
+    }
+
+    await page.waitForFunction(
+      (expected) => document.body?.innerText?.includes(expected),
+      text,
+      { timeout }
+    );
+  }
+
+  async waitForSelector(name = 'agent', selector, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const selectors = splitSelectorCandidates(selector);
+    let lastError = null;
+
+    for (const candidate of selectors) {
+      try {
+        await page.locator(candidate).first().waitFor({
+          state: options.state || 'visible',
+          timeout: options.timeout ?? 10000
+        });
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+
+    throw lastError || new Error(`未等到选择器出现: ${selector}`);
+  }
+
+  async waitForNavigation(name = 'agent', options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    await page.waitForLoadState(options.state || 'domcontentloaded', {
+      timeout: options.timeout ?? 10000
+    });
+  }
+
+  async pressKey(name = 'agent', key, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+
+    if (options.selector) {
+      const locator = page.locator(options.selector).first();
+      await locator.click({
+        timeout: options.timeout ?? 5000,
+        force: options.force ?? true
+      });
+      if (typeof locator.focus === 'function') {
+        await locator.focus();
+      }
+    }
+
+    const repeat = Math.max(1, Number(options.repeat) || 1);
+    for (let index = 0; index < repeat; index++) {
+      await page.keyboard.press(key);
+    }
+  }
+
+  async hoverSelector(name = 'agent', selector, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    await page.locator(selector).first().hover({
+      timeout: options.timeout ?? 5000,
+      force: options.force ?? true
+    });
+  }
+
+  async setCheckbox(name = 'agent', selector, checked = true, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const locator = page.locator(selector).first();
+    const method = checked ? 'check' : 'uncheck';
+    await locator[method]({
+      timeout: options.timeout ?? 5000,
+      force: options.force ?? true
+    });
+  }
+
+  async selectOption(name = 'agent', selector, value, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const locator = page.locator(selector).first();
+    const payload =
+      value && typeof value === 'object'
+        ? value
+        : { value: String(value ?? '') };
+
+    await locator.selectOption(payload, {
+      timeout: options.timeout ?? 5000
+    });
+  }
+
+  async scrollPage(name = 'agent', options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+
+    if (options.selector) {
+      await page.locator(options.selector).first().scrollIntoViewIfNeeded();
+      return;
+    }
+
+    const x = Number(options.x ?? options.left ?? 0);
+    const y = Number(options.y ?? options.top ?? 0);
+    const behavior = options.behavior === 'smooth' ? 'smooth' : 'auto';
+    const mode = options.mode === 'to' ? 'to' : 'by';
+
+    await page.evaluate(
+      ({ scrollX, scrollY, scrollBehavior, scrollMode }) => {
+        if (scrollMode === 'to') {
+          window.scrollTo({
+            left: scrollX,
+            top: scrollY,
+            behavior: scrollBehavior
+          });
+          return;
+        }
+
+        window.scrollBy({
+          left: scrollX,
+          top: scrollY,
+          behavior: scrollBehavior
+        });
+      },
+      {
+        scrollX: x,
+        scrollY: y,
+        scrollBehavior: behavior,
+        scrollMode: mode
+      }
+    );
+  }
+
+  async extractSelectorText(name = 'agent', selector, options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const selectors = splitSelectorCandidates(selector);
+    const texts = [];
+
+    for (const candidate of selectors) {
+      const locator = page.locator(candidate);
+      const count = await locator.count().catch(() => 0);
+      const limit = options.all ? count : Math.min(count, 1);
+
+      for (let index = 0; index < limit; index++) {
+        const text = await locator.nth(index).textContent().catch(() => '');
+        const normalized = String(text ?? '').trim();
+        if (normalized) {
+          texts.push(normalized);
+        }
+      }
+
+      if (texts.length > 0 && !options.all) {
+        break;
+      }
+    }
+
+    return options.all ? texts.filter(Boolean) : (texts[0] || '');
+  }
+
+  async screenshotChannel(name = 'agent', options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    await page.screenshot({
+      path: options.path,
+      fullPage: options.fullPage !== false
+    });
+  }
+
+  async inspectDom(name = 'agent', options = {}) {
+    const page = this.getPage(name);
+    if (!page) {
+      throw new Error(`浏览器页面未初始化: ${name}`);
+    }
+
+    await this.waitForChannelNavigation(name);
+    const selector = options.selector || 'body';
+    const maxNodes = Math.max(1, Number(options.maxNodes) || 20);
+    const textLimit = Math.max(20, Number(options.textLimit) || 120);
+
+    return page.evaluate(
+      ({ rootSelector, maxItems, maxTextLength }) => {
+        const root = document.querySelector(rootSelector);
+        if (!root) {
+          return [];
+        }
+
+        const nodes = [root, ...Array.from(root.querySelectorAll('*'))].slice(0, maxItems);
+        return nodes.map((node) => ({
+          tag: node.tagName.toLowerCase(),
+          id: node.id || '',
+          classes: node.className
+            ? String(node.className)
+              .split(/\s+/)
+              .filter(Boolean)
+            : [],
+          text: (node.innerText || node.textContent || '')
+            .replace(/\s+/g, ' ')
+            .trim()
+            .slice(0, maxTextLength),
+          name: node.getAttribute('name') || '',
+          role: node.getAttribute('role') || '',
+          href: node.getAttribute('href') || '',
+          type: node.getAttribute('type') || '',
+          placeholder: node.getAttribute('placeholder') || '',
+          ariaLabel: node.getAttribute('aria-label') || '',
+          title: node.getAttribute('title') || '',
+          value:
+            node instanceof HTMLInputElement ||
+            node instanceof HTMLTextAreaElement
+              ? (node.value || '').slice(0, maxTextLength)
+              : '',
+          contenteditable: node.getAttribute('contenteditable') || '',
+          visible: (() => {
+            const rect = node.getBoundingClientRect();
+            const style = window.getComputedStyle(node);
+            return (
+              rect.width > 0 &&
+              rect.height > 0 &&
+              style.visibility !== 'hidden' &&
+              style.display !== 'none'
+            );
+          })()
+        }));
+      },
+      {
+        rootSelector: selector,
+        maxItems: maxNodes,
+        maxTextLength: textLimit
+      }
+    );
+  }
+
+  getChannelState(name = 'agent') {
+    const channel = this._getChannel(name);
+    return {
+      ready: this.isChannelReady(name),
+      url: channel.page ? channel.page.url() : null,
+      hasPendingNavigation: Boolean(channel.pendingNavigation),
+      lastNavigationError: channel.lastNavigationError?.message || null,
+      observation: this.getChannelObservation(name, { limit: 3 })
+    };
+  }
+
+  async close() {
+    const names = [...this.channels.keys()];
+    await Promise.all(names.map((name) => this.closeChannel(name)));
+  }
+
+  async closeChannel(name = 'chat') {
+    const channel = this._getChannel(name);
+    if (channel.browser) {
+      await channel.browser.close().catch(() => {});
+      this._markChannelClosed(name);
+    }
+  }
+
+  getPage(name = 'chat') {
+    const channel = this._getChannel(name);
+    return channel.page;
+  }
+
+  isReady() {
+    return this.isChannelReady('chat');
+  }
+
+  isChannelReady(name = 'chat') {
+    const channel = this._getChannel(name);
+    return channel.browser !== null && channel.page !== null;
+  }
+}
+
+export default new BrowserManager();