browser-harness

来源：GitHub · ⭐ 2191 stars

项目简介

在当今人工智能浪潮中，大型语言模型（LLM）展现出了强大的理解和生成能力，但它们本质上是被“困在”文本世界里的。如何让LLM与现实世界的数字界面——尤其是网页浏览器——进行有效、可靠的交互，成为了一个关键挑战。传统方法如直接模拟点击或依赖固定的CSS选择器，极其脆弱，页面结构的微小变动就可能导致自动化流程崩溃。

browser-harness 项目应运而生，它旨在构建一个具有“自愈”能力的浏览器操作框架，专门为LLM设计。其核心价值在于，它将浏览器从被简单脚本操控的对象，升级为LLM可以理解、规划和执行复杂任务的智能体“身体”。通过将网页的视觉和语义信息（如按钮文本、图像描述）与DOM结构相结合，它允许LLM以更接近人类的方式（“点击那个写着‘登录’的蓝色按钮”）来指定操作，并由框架负责将其转化为可靠的动作执行，从而极大地提升了基于LLM的浏览器自动化的鲁棒性和泛化能力。

核心特性

  • 自愈能力与语义化操作：项目最大的亮点是“自愈”。它不依赖易变的CSS选择器路径，而是允许LLM通过元素的文本内容、角色、标签名等语义化属性来定位目标。当一次定位失败时，框架可以结合LLM的上下文理解，尝试其他策略或描述，自动“修复”交互流程。
  • 为LLM优化的观察与行动空间：框架将复杂的网页DOM树和视觉信息，提炼成对LLM更友好的结构化观察（Observation）。同时，它提供了一套精简、定义良好的行动（Action）集合（如click， type， scroll等），让LLM能够在一个受控且高效的空间内进行决策。
  • 无缝集成主流AI服务：原生支持与OpenAI、Anthropic Claude、Google Gemini等主流LLM API对接，开发者可以轻松地将强大的语言模型能力注入到浏览器自动化流程中。
  • 人类监督与接管：在关键步骤或LLM不确定时，可以暂停自动化流程，将控制权交还给人类操作员进行示范或确认，这些示范又能被记录和学习，形成良性循环。

技术实现

browser-harness 的技术栈清晰而高效。其底层基于 Playwright，这是一个现代、快速且可靠的浏览器自动化库，支持Chromium、Firefox和WebKit，提供了强大的页面操控和网络拦截能力。在此之上，项目构建了自己的抽象层。

其核心实现思路围绕着 “观察-思考-行动” 的智能体循环：

  1. 观察生成器：将Playwright获取的原始DOM进行加工，提取关键信息（如可交互元素的文本、位置、类型），并可能结合轻量级计算机视觉（或可访问性树）来补充纯DOM解析的不足（例如识别图标按钮），最终生成一份精简的、富含语义的“页面状态描述”供LLM消费。
  2. 行动翻译器：当LLM根据观察输出一个自然语言或结构化指令（如“在搜索框输入‘开源项目’”）后，行动翻译器负责将这个高级指令解析并映射到具体的、原子性的Playwright API调用上（如locator('input[placeholder*=\"搜索\"]').fill('开源项目')）。这里的“自愈”机制常常作用于这一层，当首次定位失败，翻译器会利用LLM提供的额外上下文或尝试备用策略重新定位。
  3. 循环控制器：管理整个交互流程，处理LLM的响应，执行行动，捕获结果和新的页面状态，并决定是继续自动化、请求人工帮助还是结束任务。这种架构将LLM的认知优势（理解、规划）与Playwright的精确执行能力完美结合，同时通过中间抽象层屏蔽了底层页面的不稳定性。

快速上手

以下是一个使用 browser-harness 配合 OpenAI GPT-4 完成百度搜索的简单示例。

首先，确保安装必要的库：

pip install browser-harness openai playwright
playwright install

接下来是核心代码：

import asyncio
from browser_harness import BrowserHarness
from browser_harness.agents import LMAgent
from browser_harness.models import OpenAIModel

async def main():
    # 1. 配置LLM（此处需要设置你的OPENAI_API_KEY环境变量）
    llm_model = OpenAIModel(model="gpt-4-turbo")

    # 2. 创建智能体，它将驱动整个决策过程
    agent = LMAgent(model=llm_model)

    # 3. 创建浏览器操作框架实例
    harness = BrowserHarness(agent=agent)

    # 4. 启动浏览器并导航到目标页面
    await harness.init()
    await harness.goto("https://www.baidu.com")

    # 5. 向智能体发出任务指令
    task_description = "在百度搜索框里输入‘browser-harness GitHub’，然后点击‘百度一下’按钮进行搜索。"
    
    # 智能体将自动执行：观察页面 -> 规划步骤 -> 执行操作
    result = await harness.run(task=task_description)

    # 6. 可以继续更多任务，例如点击第一个搜索结果
    # await harness.run(“点击第一个搜索结果链接”)
    
    # 等待一段时间查看结果，然后关闭
    await asyncio.sleep(3)
    await harness.close()

if __name__ == "__main__":
    asyncio.run(main())

在这个例子中，开发者只需告诉智能体“要做什么”，而“如何做”（定位搜索框、识别按钮）则由browser-harness框架和LLM协同完成，无需编写任何脆弱的选择器代码。

应用场景

  1. 复杂工作流自动化：自动化处理那些需要多步骤判断、表单填写和跳转的业务流程，例如跨多个内部系统的数据录入、定期从结构复杂的仪表盘抓取并汇总数据。即使页面布局更新，基于语义的自愈能力也能大幅降低维护成本。
  2. AI助手与Copilot：构建能够理解用户自然语言指令并操作网页的桌面助手。例如，用户说“帮我把上周的销售报告从CRM下载下来，用邮件发给我经理”，AI助手可以分解任务，登录系统，导航到报告页面，下载文件，然后打开邮箱客户端完成发送。
  3. 端到端测试与质量监控：用于生成和执行智能化的UI测试用例。测试人员可以用自然语言描述测试场景（“以错误密码登录，检查是否出现警告提示”），由LLM驱动完成测试，并能处理一些非预期的UI变化，使测试脚本更具弹性。

总结

browser-harness 是一个构思巧妙、解决实际痛点的开源项目。它精准地抓住了LLM与真实世界交互的关键瓶颈，通过构建一个语义化、可自愈的中间层，显著提升了智能体在动态Web环境中完成任务的可靠性和实用性。该项目非常适合那些正在探索AI智能体应用、需要构建复杂且健壮的网页自动化流程的开发者、测试工程师以及AI产品经理。虽然它仍处于发展阶段，但其设计理念已为下一代基于LLM的自动化工具指明了方向。