Browser-Harness：让 LLM 拥有自愈能力的浏览器自动化工具

Browser-Harness：让 LLM 拥有自愈能力的浏览器自动化工具

在 AI Agent 的实际应用中，浏览器自动化一直是一个重要但充满挑战的领域。传统的 Selenium、Puppeteer 等工具需要编写大量的定位器代码，一旦页面结构发生变化，整个自动化流程就会崩溃。

最近，GitHub 上出现了一个名为 browser-harness 的开源项目（3526+ ⭐），它通过"自愈"机制解决了这个问题，让 LLM 能够更可靠地完成浏览器任务。

什么是 Browser-Harness？

Browser-Harness 是一个自愈浏览器工具，专门为 LLM 设计。它的核心思想是：当页面元素定位失败时，不是立即报错，而是动态分析页面结构，找到替代方案继续执行。

核心特性

1. 智能元素定位：结合 DOM 结构、文本内容、语义信息多重匹配 2. 自动错误恢复：页面变化时自动调整定位策略 3. LLM 友好：提供清晰的接口让 LLM 理解和操作页面 4. 轻量级设计：基于 Playwright 构建，易于集成

传统方案的问题

让我们先看看传统浏览器自动化的痛点：

// ❌ 传统方案：脆弱的元素定位
const button = await page.locator('#submit-btn-12345');
await button.click();
// 一旦按钮 ID 变化，整个脚本就挂了

这种方案在以下场景中会失败：

• 动态生成的 ID（如 #btn-abc123）
• A/B 测试导致的页面变化
• SPA 应用的 DOM 结构重组
• 不同语言版本的页面

Browser-Harness 的解决方案

Browser-Harness 采用了更智能的定位策略：

// ✅ Browser-Harness：语义化定位
const harness = new BrowserHarness(page);
// 可以通过多种方式定位元素
await harness.click({
  text: '提交',  // 文本内容
  tag: 'button', // 标签类型
  nearest: { id: 'form-container' } // 附近的其他元素
});
// 即使元素属性变化，仍然可以找到目标

多重匹配策略

Browser-Harness 会按以下顺序尝试定位：

1. 精确匹配：使用最具体的定位器 2. 模糊匹配：基于文本相似度查找 3. 语义推断：根据周围元素结构推断目标 4. 上下文理解：利用 LLM 理解页面语义

实战示例：构建一个简单的订单查询 Agent

让我们用 Browser-Harness 构建一个能查询订单的 AI Agent：

1. 初始化

npm install browser-harness playwright

2. 核心代码

import { BrowserHarness } from 'browser-harness';
import { chromium } from 'playwright';
class OrderQueryAgent {
  constructor() {
    this.harness = null;
    this.page = null;
  }
  async init() {
    // 启动浏览器
    const browser = await chromium.launch({ headless: false });
    const context = await browser.newContext();
    this.page = await context.newPage();
    // 初始化 harness
    this.harness = new BrowserHarness(this.page);
  }
  async queryOrder(orderId) {
    try {
      // 导航到订单页面
      await this.page.goto('https://example.com/orders');
      // 查找搜索框（不依赖具体 ID）
      await this.harness.fill({
        placeholder: '订单号',
        value: orderId
      });
      // 点击搜索按钮
      await this.harness.click({
        text: '搜索',
        tag: 'button'
      });
      // 等待结果加载
      await this.page.waitForSelector('.order-status');
      // 提取订单状态
      const status = await this.harness.extract({
        selector: '.order-status',
        text: true
      });
      return {
        success: true,
        status: status
      };
    } catch (error) {
      // 自愈机制会尝试恢复
      console.error('查询失败，尝试恢复...', error.message);
      // 尝试刷新页面重试
      await this.page.reload();
      return this.queryOrder(orderId);
    }
  }
  async close() {
    await this.page.close();
  }
}
// 使用示例
(async () => {
  const agent = new OrderQueryAgent();
  await agent.init();
  const result = await agent.queryOrder('ORD-2024-0421');
  console.log('订单状态:', result.status);
  await agent.close();
})();

技术原理解析

1. 智能元素匹配

Browser-Harness 使用加权评分系统来选择最匹配的元素：

// 简化的评分算法示例
function scoreElement(element, criteria) {
  let score = 0;
  // 文本匹配（权重最高）
  if (element.textContent.includes(criteria.text)) {
    score += 100;
  }
  // 标签匹配
  if (element.tagName === criteria.tag) {
    score += 50;
  }
  // 上下文匹配
  if (isNear(element, criteria.nearest)) {
    score += 30;
  }
  // 可见性检查
  if (isVisible(element)) {
    score += 20;
  }
  return score;
}
// 选择得分最高的元素
const candidates = document.querySelectorAll('button');
const bestMatch = candidates
  .map(el => ({ element: el, score: scoreElement(el, criteria) }))
  .sort((a, b) => b.score - a.score)[0];

2. 错误恢复策略

当操作失败时，Browser-Harness 会：

async function resilientClick(harness, selector, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      // 尝试定位元素
      const element = await harness.locate(selector);
      if (element) {
        await element.click();
        return { success: true };
      }
      // 未找到，重新分析页面
      await harness.analyzePage();
    } catch (error) {
      // 记录失败，调整策略
      console.log(尝试 ${i + 1} 失败:, error.message);
      // 等待页面稳定后重试
      await harness.waitForStable(1000);
    }
  }
  return { success: false, error: '达到最大重试次数' };
}

与 LLM 的集成

Browser-Harness 的设计特别适合与 LLM 配合使用：

1. 结构化输出

// 为 LLM 提供清晰的页面信息
const pageInfo = await harness.getPageSummary();
/
返回：
{
  "title": "订单查询",
  "interactiveElements": [
    { "type": "input", "label": "订单号" },
    { "type": "button", "label": "搜索" }
  ],
  "possibleActions": [
    "输入订单号",
    "点击搜索按钮",
    "查看订单详情"
  ]
}
/

2. 自然语言映射

// 将 LLM 的指令转换为浏览器操作
async function executeInstruction(harness, instruction) {
  const action = parseInstruction(instruction);
  switch (action.type) {
    case 'click':
      return await harness.click({
        text: action.target,
        context: action.context
      });
    case 'input':
      return await harness.fill({
        placeholder: action.field,
        value: action.value
      });
    case 'extract':
      return await harness.extract({
        selector: action.target
      });
  }
}
// LLM 可以说："帮我点击那个搜索按钮"
// 而不需要知道具体的 CSS 选择器

实际应用场景

1. 自动化测试

// 更稳定的 E2E 测试
test('用户可以搜索商品', async () => {
  const harness = new BrowserHarness(page);
  await page.goto('/shop');
  // 不依赖特定 ID
  await harness.fill({ placeholder: '搜索商品', value: 'iPhone' });
  await harness.click({ text: '搜索', tag: 'button' });
  // 验证结果
  const results = await harness.extract({ selector: '.product-list' });
  expect(results).toContain('iPhone');
});

2. 数据采集

// 更智能的爬虫
async function scrapeProductPrices(url) {
  const harness = new BrowserHarness(page);
  await page.goto(url);
  // 自动找到价格元素
  const prices = await harness.extractAll({
    pattern: /\$\d+\.\d{2}/,
    context: 'product-card'
  });
  return prices;
}

3. RPA（机器人流程自动化）

// 财务自动对账
async function reconcileOrders() {
  const harness = new BrowserHarness(page);
  // 登录
  await harness.fill({ label: '用户名', value: 'admin' });
  await harness.fill({ label: '密码', value: '' });
  await harness.click({ text: '登录' });
  // 导出订单
  await harness.click({ text: '订单管理' });
  await harness.click({ text: '导出 CSV' });
  // 下载文件
  // ...
}

性能优化建议

1. 缓存元素定位结果

const cache = new Map();
async function smartLocate(harness, selector) {
  const cacheKey = JSON.stringify(selector);
  if (cache.has(cacheKey)) {
    const cached = cache.get(cacheKey);
    if (await cached.isVisible()) {
      return cached;
    }
  }
  const element = await harness.locate(selector);
  cache.set(cacheKey, element);
  return element;
}

2. 并行操作

// 同时获取多个信息
const [title, price, stock] = await Promise.all([
  harness.extract({ selector: 'h1' }),
  harness.extract({ selector: '.price' }),
  harness.extract({ selector: '.stock' })
]);

3. 选择性等待

// 只等待必要的元素
await harness.waitFor({
  selector: '.order-status',
  timeout: 5000
});

局限性

Browser-Harness 并非万能：

1. 复杂交互：拖拽、画布操作等仍需特殊处理 2. 性能开销：智能匹配比直接定位慢 3. 学习成本：需要理解其工作原理 4. iframe 限制：跨域 iframe 仍有限制

未来展望

Browser-Harness 代表了浏览器自动化的新方向：

• 更智能的 AI Agent：结合多模态 LLM 理解页面视觉
• 自学习机制：从失败中学习，改进定位策略
• 分布式执行：多个浏览器实例协同工作
• 低代码平台：让非开发者也能构建自动化流程

标签*：#AI #BrowserAutomation #LLM #WebDevelopment #JavaScript