6.1 GUI 智能体与 Computer Use：视觉像素与 DOM 双模定位

// hybrid-gui-controller.ts
import { Page } from 'playwright';
 
export interface ClickTarget {
  selector?: string;      // DOM 路径优先
  textPattern?: string;   // 可视文本
  fallbackCoords?: { x: number; y: number }; // 视觉坐标保底
}
 
export class HybridBrowserController {
  constructor(private page: Page) {}
 
  /**
   * 双模稳健点击：DOM 尝试 -> 视觉坐标兜底
   */
  async robustClick(target: ClickTarget): Promise<string> {
    // 1. 尝试使用 DOM 路径精准命中
    if (target.selector) {
      try {
        const element = await this.page.waitForSelector(target.selector, { timeout: 3000 });
        if (element && (await element.isVisible())) {
          await element.click();
          return `【DOM 成功】：通过选择器 "${target.selector}" 完成高精度点击`;
        }
      } catch {
        console.warn(`[GUI Controller] DOM 选择器 ${target.selector} 超时或不可见，触发降级方案...`);
      }
    }
 
    // 2. 尝试使用可见文本定位
    if (target.textPattern) {
      try {
        const textBtn = this.page.getByText(target.textPattern).first();
        if (await textBtn.isVisible()) {
          await textBtn.click();
          return `【文本定位成功】：通过界面文本 "${target.textPattern}" 触发点击`;
        }
      } catch {
        console.warn(`[GUI Controller] 文本匹配失败，触发视觉像素绝对坐标点击...`);
      }
    }
 
    // 3. 终极兜底：基于像素坐标的模拟硬件物理点击
    if (target.fallbackCoords) {
      const { x, y } = target.fallbackCoords;
      await this.page.mouse.move(x, y);
      await this.page.mouse.down();
      await this.page.mouse.up();
      return `【视觉坐标兜底】：在像素坐标 [${x}, ${y}] 处完成硬件模拟物理点击`;
    }
 
    throw new Error('所有点击定位策略均宣告失败，请重新截屏评估界面状态！');
  }
}