1. 项目概述当AI助手能“看见”你的屏幕最近在折腾AI应用开发的朋友可能都遇到过这样一个痛点我们想让大语言模型LLM去操作一个桌面软件、填写一个网页表单或者分析一张截图里的信息。传统的做法要么是写一大堆复杂的API调用脚本要么是手动截图、上传、再让AI分析流程割裂效率低下。有没有一种方式能让AI像真人一样“看见”屏幕上的内容理解界面元素并直接进行交互呢这就是browserbase/stagehand项目要解决的核心问题。它不是一个简单的浏览器自动化工具而是一个将计算机视觉CV与大语言模型LLM能力深度融合的AI智能体框架。简单来说它让AI拥有了“眼睛”和“手”——通过视觉模型实时“观察”屏幕状态通过语言模型“理解”任务意图并生成操作指令最终通过自动化工具“执行”这些操作。这个项目特别适合那些希望构建能够与任意图形用户界面GUI进行智能交互的自动化流程、RPA机器人流程自动化增强应用或是进行端到端UI测试的开发者。我花了几天时间深入研究了它的源码和设计并动手搭建了几个实验场景。我发现它的价值远不止于“自动化点击”其背后关于多模态AI智能体的设计思路、对真实世界交互不确定性的处理以及如何将视觉感知与逻辑决策无缝衔接才是真正值得深挖的干货。接下来我将从设计思路、核心架构、实操部署到避坑经验为你完整拆解这个颇具前瞻性的项目。2. 核心架构与设计哲学拆解Stagehand 的命名很有意思“Stagehand”在戏剧中是舞台工作人员负责根据剧情LLM的指令来操作舞台上的道具屏幕元素。这个名字精准地概括了它的角色一个听从AI导演指挥在数字舞台屏幕上执行动作的智能执行者。它的设计哲学可以概括为以视觉为统一感知层以自然语言为统一控制接口实现跨平台、跨应用的通用型AI交互。2.1 为什么是“视觉优先”而非“DOM优先”传统网页自动化如 Puppeteer、Playwright核心是操作DOM文档对象模型。它们需要开发者预先知道按钮的ID、CSS选择器写死的脚本无法应对UI的微小变化。而Stagehand选择了另一条路基于像素的视觉感知。核心考量通用性DOM只存在于浏览器中。但Stagehand的野心不限于浏览器还包括桌面应用如Photoshop、VS Code、移动端模拟器甚至远程桌面。只有屏幕截图像素阵列是所有这些场景的“最大公约数”。应对动态UI现代应用UI动态化程度高元素选择器可能随时变化。视觉方案不关心底层代码只关心屏幕上“看起来像按钮的那个区域”鲁棒性更强。赋能LLMLLM在多模态理解上进步神速如GPT-4V。直接给LLM一张截图和任务描述它就能指出需要操作的位置和方式这种交互更符合人类的直觉也降低了开发门槛。技术实现路径Stagehand 的流程是一个经典的“感知-决策-执行”循环感知Perception通过pyautogui、mss或其他截图库捕获当前屏幕或指定窗口的图像。决策Decision将截图和用户的任务描述如“点击登录按钮”一起发送给多模态LLM例如GPT-4V、Claude 3。LLM分析图像理解任务并输出一个结构化的动作指令例如{action: click, coordinates: [123, 456], description: Login button}。执行Execution框架解析动作指令调用对应的自动化库如pyautogui执行点击pynput模拟键盘输入来操作屏幕坐标[123, 456]。这个循环会持续进行直到任务完成或达到最大步数限制。2.2 核心组件深度解析Stagehand 的代码结构清晰地反映了上述哲学。我们来看几个关键模块vision_processor.py- 视觉处理引擎这是项目的“眼睛”。它不仅要截图还要负责图像的预处理以适配不同LLM的输入要求。截图策略支持全屏、活动窗口、指定区域等多种模式。对于浏览器场景它可能会与Playwright集成直接获取浏览器标签页的截图比全屏截图更精准、更快。图像预处理包括调整分辨率以控制API成本、格式转换JPEG/PNG、以及可选的OCR光学字符识别文字提取将图片中的文字作为附加上下文提供给LLM增强其理解能力。坐标系统一无论截图来源是哪里最终都需要将LLM返回的坐标通常是基于截图图像的相对坐标转换为当前屏幕的绝对坐标。这里涉及屏幕缩放比例DPI/缩放设置的校准是容易出错的细节点。llm_orchestrator.py- 智能决策中枢这是项目的“大脑”。它负责与多模态LLM API对话。提示词工程Prompt Engineering这是灵魂所在。Stagehand 提供给LLM的提示词Prompt绝非简单的“描述这张图”。它通常包含系统角色设定将LLM定义为一个专业的UI自动化助手。动作空间定义明确告诉LLM可以输出哪些动作click, type, scroll, wait, keypress等及其参数格式。历史上下文包含之前几步的截图和动作让LLM具备短期记忆理解任务进程。任务目标用户的原始指令。当前状态最新的屏幕截图。LLM适配层虽然OpenAI的GPT-4V是首选但框架设计上支持切换其他支持视觉的模型如Anthropic Claude 3、Google Gemini Pro Vision甚至本地部署的开源模型如LLaVA。适配层需要处理不同API的调用格式和响应解析。输出解析与验证LLM的回复是自由文本需要被稳健地解析成结构化的JSON指令。这里会用到Pydantic模型进行数据验证和类型转换确保执行环节收到的指令是合法、安全的。action_executor.py- 动作执行器这是项目的“手”。它接收结构化的动作指令并调用底层操作系统级的自动化工具来执行。动作映射将抽象的click、type映射到pyautogui.click(x, y)、pyautogui.write(text)。执行可靠性加入重试机制、异常处理。例如点击前等待目标区域稳定执行后等待一个合理的网络或UI响应时间通过sleep或更智能的等待条件。安全边界这是一个关键设计。框架应避免执行危险操作比如在系统关键区域任务栏、系统设置盲目点击或输入破坏性命令。好的实现会有坐标白名单或动作过滤器。task_planner.py(可选但常见) - 高层任务规划器对于复杂任务如“从Gmail收件箱中找到某封邮件并回复”单步的“感知-决策-执行”循环效率太低。高级架构中会引入一个“规划器”它先让LLM可以是纯文本的GPT-4将大任务分解成一系列子任务步骤再由上述循环逐个执行。这模仿了人类的先计划、再行动的逻辑。3. 从零开始搭建与核心配置实战理解了原理我们动手搭建一个属于自己的Stagehand智能体。这里我以在Windows系统上使用OpenAI GPT-4V模型自动化操作Chrome浏览器为例展示最核心的配置和代码。3.1 环境准备与依赖安装首先创建一个干净的Python虚拟环境强烈推荐避免包冲突。# 创建并激活虚拟环境 python -m venv stagehand_env stagehand_env\Scripts\activate # Windows # source stagehand_env/bin/activate # Linux/Mac # 安装核心依赖 pip install openai # LLM API客户端 pip install pillow # 图像处理 pip install pyautogui # 桌面自动化 pip install mss # 快速截图 pip install playwright # 浏览器控制如果需要 playwright install chromium # 安装浏览器驱动注意pyautogui在不同操作系统上可能有细微差异特别是在获取屏幕尺寸和处理多显示器时。在Mac上可能需要辅助功能权限在Linux上可能需要安装scrot或python3-tk。3.2 核心配置与初始化接下来我们编写一个简化的config.py和主程序入口。重点是配置好LLM和动作执行参数。# config.py import os from pydantic import BaseSettings class Settings(BaseSettings): # OpenAI API 配置 openai_api_key: str os.getenv(OPENAI_API_KEY) openai_model: str gpt-4-vision-preview # 指定视觉模型 openai_max_tokens: int 300 # 视觉捕捉配置 screen_capture_mode: str active_window # 可选full_screen, region capture_delay: float 0.5 # 每次动作后等待UI稳定的时间秒 # 动作执行配置 mouse_move_duration: float 0.2 # 鼠标移动动画时长模拟真人操作 default_typing_speed: float 0.05 # 每个字符的输入间隔秒 class Config: env_file .env settings Settings()在主程序中我们需要初始化几个核心管理器。# main.py import asyncio from openai import AsyncOpenAI from vision_processor import VisionProcessor from action_executor import ActionExecutor from llm_orchestrator import LLMOrchestrator import config class StagehandAgent: def __init__(self): self.vision VisionProcessor(config.settings.screen_capture_mode) self.executor ActionExecutor( move_durationconfig.settings.mouse_move_duration, typing_speedconfig.settings.default_typing_speed ) self.llm_client AsyncOpenAI(api_keyconfig.settings.openai_api_key) self.orchestrator LLMOrchestrator(self.llm_client, config.settings.openai_model) async def perform_task(self, task_description: str, max_steps: int 10): 执行一个高级任务 history [] for step in range(max_steps): print(fStep {step 1}: Capturing screen...) # 1. 感知截图 screenshot, screenshot_info self.vision.capture() # 2. 决策询问LLM下一步该做什么 llm_response await self.orchestrator.decide_next_action( tasktask_description, screenshotscreenshot, historyhistory[-3:] # 只传递最近几步历史控制上下文长度 ) print(fLLM Decision: {llm_response.action} at {llm_response.coordinates}) # 检查任务是否完成 if llm_response.action complete: print(Task completed by LLM.) break # 3. 执行执行动作 await self.executor.execute(llm_response) # 记录历史 history.append({ screenshot_info: screenshot_info, action: llm_response.dict() }) # 动作后延迟等待UI响应 await asyncio.sleep(config.settings.capture_delay) else: print(fReached max steps ({max_steps}) without completion.) async def main(): agent StagehandAgent() # 示例任务打开浏览器访问百度搜索“今日天气” task First, ensure the Chrome browser is in focus. Then, navigate to the address bar, type www.baidu.com and press Enter. After the page loads, find the search box, type todays weather Beijing and press Enter again. await agent.perform_task(task) if __name__ __main__: asyncio.run(main())3.3 核心模块实现详解上面代码中的三个核心模块需要具体实现。我们来看最关键的LLMOrchestrator.decide_next_action方法。# llm_orchestrator.py import base64 from typing import List, Optional from pydantic import BaseModel from openai import AsyncOpenAI class ActionResponse(BaseModel): 定义LLM应返回的动作结构 action: str # click, type, keypress, scroll, wait, complete coordinates: Optional[List[int]] None # [x, y] text: Optional[str] None # 用于type动作 key: Optional[str] None # 用于keypress如 “enter”, “tab” reasoning: str # LLM的思考过程用于调试 class LLMOrchestrator: def __init__(self, client: AsyncOpenAI, model: str): self.client client self.model model async def decide_next_action(self, task: str, screenshot, history) - ActionResponse: # 将PIL Image转换为base64用于API传输 buffered BytesIO() screenshot.save(buffered, formatPNG) img_base64 base64.b64encode(buffered.getvalue()).decode(utf-8) # 构建消息历史包含之前的截图和动作 messages self._build_message_history(task, history) # 添加当前步骤的指令和截图 messages.append({ role: user, content: [ {type: text, text: self._get_system_prompt()}, { type: image_url, image_url: { url: fdata:image/png;base64,{img_base64}, detail: high # 高细节有助于识别小元素 } }, {type: text, text: fCurrent overall task: {task}\nWhat is the single next action? Respond in the specified JSON format.} ] }) try: response await self.client.chat.completions.create( modelself.model, messagesmessages, max_tokens300, response_format{ type: json_object } # 强制返回JSON ) # 解析JSON响应 import json response_json json.loads(response.choices[0].message.content) return ActionResponse(**response_json) except Exception as e: print(fError calling LLM: {e}) # 降级策略返回一个等待动作避免崩溃 return ActionResponse(actionwait, reasoningfLLM error: {e}) def _get_system_prompt(self) - str: 核心定义LLM的行为和输出格式 return You are a precise UI automation assistant. Your job is to analyze the provided screenshot and determine the next single action to progress towards the given task. AVAILABLE ACTIONS (respond in JSON format): - click: Click at a specific coordinate. Requires coordinates: [x, y]. - type: Type a string of text. Requires text: string to type. Optionally, coordinates can be provided to click the field first. - keypress: Press a single key. Requires key: keyname (e.g., enter, tab, escape). - scroll: Scroll up or down. Requires text: up or text: down. - wait: Wait for a moment, no parameters needed. - complete: The task is finished. No further parameters. OUTPUT FORMAT (JSON): { action: action_name, coordinates: [x, y], // if applicable text: text_or_direction, // if applicable key: keyname, // if applicable reasoning: Brief explanation of why this action is chosen. } INSTRUCTIONS: 1. Focus on the MOST IMMEDIATE and SIMPLE next action. 2. Coordinates are relative to the top-left corner of the provided image. 3. If you need to interact with a specific UI element (button, input field), identify it visually and provide its approximate center coordinates. 4. Be cautious of menus, pop-ups, or loading states. 5. If the task seems already accomplished, respond with {action: complete, reasoning: ...}. 这个系统提示词是项目成败的关键。它必须清晰、无歧义地定义动作空间和输出格式并引导LLM进行逐步、稳健的决策。4. 高级技巧与性能优化实战基础功能跑通后你会发现直接使用成本高、速度慢且不稳定。下面分享几个我实战中总结的优化技巧。4.1 降低API成本与延迟的策略GPT-4V的API调用不便宜每次对话都上传高清大图成本很快会失控。策略一智能截图与区域聚焦不要总是截取全屏。在任务开始时让LLM识别出目标应用窗口的大致区域后续只截取该区域。或者在已知要操作某个输入框时只截取包含该输入框及其周围上下文的小区域。# 在VisionProcessor中增加区域截图方法 def capture_region(self, region: tuple): region: (left, top, width, height) with mss.mss() as sct: monitor {top: region[1], left: region[0], width: region[2], height: region[3]} sct_img sct.grab(monitor) return Image.frombytes(RGB, sct_img.size, sct_img.bgra, raw, BGRX)策略二图像压缩与降采样在保证LLM能识别关键UI元素的前提下大幅降低图像分辨率。将截图从4K缩放到1080p甚至720p能减少80%以上的token消耗。from PIL import Image def compress_screenshot(image: Image, max_width: int 1280): w, h image.size if w max_width: ratio max_width / w new_h int(h * ratio) image image.resize((max_width, new_h), Image.Resampling.LANCZOS) # 可选转换为JPEG并降低质量 buffered BytesIO() image.save(buffered, formatJPEG, quality85, optimizeTrue) buffered.seek(0) return Image.open(buffered) # 返回处理后的图像对象策略三缓存与历史摘要对于连续步骤屏幕大部分区域未变化。可以计算当前截图与上一帧的差异度如均方误差MSE如果差异很小则不上传新图而是告诉LLM“界面与上一步基本相同请基于此继续决策”。或者将多步历史摘要成文本描述而非传递所有图片。4.2 提升动作执行可靠性的关键视觉定位的坐标总有误差UI响应也有延迟。技巧一基于特征的模糊点击不要盲目点击LLM返回的精确坐标[x, y]。可以以该坐标为中心在一个小范围内例如20x20像素搜索具有“可点击”特征的像素如颜色对比明显的按钮边缘然后点击这个区域内的一个随机点模拟真人操作的不精确性。技巧二执行后验证执行一个动作后比如点击“提交”按钮不应该立即进入下一个“感知-决策”循环。应该等待一个预期的新UI状态出现。例如点击登录后可以等待屏幕特定位置出现“欢迎用户名”的文字通过OCR快速检测或者等待页面URL改变。这需要扩展ActionExecutor使其具备简单的验证能力。class ActionExecutor: async def execute_and_verify(self, action: ActionResponse, expected_change: str): await self.execute(action) # 等待并验证 for _ in range(10): # 最多重试10次每次0.5秒 await asyncio.sleep(0.5) screenshot self.vision.capture() # 简单的OCR或颜色检测判断expected_change是否出现 if self._check_condition(screenshot, expected_change): return True print(Verification failed after action.) return False技巧三引入错误恢复机制当LLM连续几步决策无效如点击坐标无效或任务无进展时应触发恢复流程。例如可以回退到上一步状态让LLM重新决策或者切换到更保守的“探索”模式比如先让鼠标在屏幕上移动一圈重新获取完整的屏幕上下文。4.3 集成Playwright进行精准浏览器控制对于纯浏览器场景pyautogui的屏幕坐标控制显得笨重且脆弱。更好的方式是让Stagehand驱动Playwright。这时VisionProcessor从截取屏幕改为截取Playwright页面ActionExecutor将LLM的坐标指令转换为对Playwright元素的操作。实现思路LLM返回的坐标是基于当前页面截图的。使用Playwright的page.evaluate方法将图像坐标通过JavaScript转换为DOM元素。这可以通过document.elementFromPoint(x, y)实现。然后对获取到的DOM元素执行click()、type()等操作。这种方式比基于屏幕坐标的点击精准得多且不受浏览器窗口位置、大小的影响。# 在ActionExecutor中增加Playwright模式 async def execute_on_browser(self, action: ActionResponse, page): if action.action click and action.coordinates: # 将图像坐标转换为视口坐标再尝试获取元素 element await page.evaluate(f([x, y]) {{ const el document.elementFromPoint(x, y); return el ? {{ tag: el.tagName, id: el.id, classes: el.className, rect: el.getBoundingClientRect() }} : null; }}, action.coordinates) if element: # 更精准使用Playwright的选择器点击而非坐标 selector self._build_selector(element) # 根据元素信息构建选择器 await page.click(selector) else: # 降级到坐标点击 await page.mouse.click(action.coordinates[0], action.coordinates[1]) # ... 处理其他动作5. 典型问题排查与实战心得在实际部署和测试中我遇到了不少坑这里总结一份速查表。问题现象可能原因排查步骤与解决方案LLM返回的坐标完全错误1. 坐标系统混淆屏幕坐标 vs 图像坐标。2. 截图尺寸或DPI缩放未处理。3. LLM误解了指令。1.验证坐标转换在截图上用红点标记LLM返回的坐标保存图片查看位置是否正确。2.校准DPI确保VisionProcessor正确获取了系统的缩放比例ctypes.windll.shcore.GetScaleFactorForMonitoron Windows。3.优化提示词在系统提示中更强调“坐标是相对于你看到的这张图片的左上角”。AI陷入循环或重复无效动作1. 任务描述模糊。2. LLM缺乏足够的上下文记忆。3. UI状态变化未被AI感知。1.细化任务将“登录网站”改为“首先在地址栏输入example.com并回车。然后在用户名框输入test...”。2.增加历史长度给LLM提供前2-3步的截图和动作作为上下文。3.引入超时与回退设定单任务最大步数达到后重置或提示人工干预。API调用成本过高1. 截图分辨率太高。2. 每一步都调用LLM即使界面未变。3. 使用了昂贵的模型。1.强制降分辨率如前所述将截图宽度限制在1024像素以下。2.实现状态缓存计算连续帧的差异无变化时不调用LLM。3.模型降级对于简单、重复的识别任务可以尝试使用本地轻量级CV模型如YOLO识别按钮或便宜的API如GPT-4o-mini。动作执行失败点击没反应1. 坐标偏移多显示器、任务栏。2. 目标应用未获得焦点。3. 执行速度太快UI未就绪。1.焦点管理在执行关键动作前先用pyautogui.click()点击一下目标窗口的标题栏确保其激活。2.增加延迟在click或type动作前后增加time.sleep(0.3)。3.使用更可靠的定位切换到基于Playwright的浏览器控制模式。处理弹窗或意外界面LLM未在训练数据中见过此类界面或提示词未涵盖。1.增强提示词鲁棒性在系统提示中加入“如果遇到不认识的弹窗或错误信息尝试点击关闭按钮(X)或‘取消’按钮然后继续原任务”。2.人工干预点设计一个“暂停并请求人工帮助”的动作当LLM置信度低时触发。我的几点核心心得提示词是命门Stagehand的性能90%取决于你写给LLM的“剧本”系统提示词。需要反复调试用具体的例子告诉LLM什么是好的决策。可以尝试Few-Shot Learning在提示词里提供几个[截图 正确动作]的示例对。混合策略才是未来纯视觉LLM路径成本高、延迟大。生产级应用应该是混合架构先用传统的计算机视觉方法模板匹配、OCR处理可预测的、结构化的UI部分对于复杂、动态或未知的界面再fallback到LLM。这能极大提升效率和可靠性。安全第一永远不要在生产环境让此类智能体拥有不受限制的系统权限。必须在沙箱或虚拟机中运行并严格限制其可操作的应用和区域例如通过一个允许列表。它更像“副驾驶”而非“自动驾驶”目前阶段Stagehand这类工具最适合的是半自动化场景即由人类下达高级指令并监督整个过程AI负责执行繁琐、重复的低级操作。完全自主的AI智能体距离稳定可靠的商业应用还有很长的路。这个项目为我们打开了一扇窗让我们看到了未来人机交互的一种可能形态用自然语言指挥软件完成复杂工作流。虽然目前它更像一个精巧的“玩具”或研究原型但其背后的思想——将视觉理解与逻辑决策循环结合——无疑是构建更通用AI智能体的关键拼图。如果你正在探索AI Agent、RPA 2.0或者下一代UI测试工具Stagehand的代码和设计思路绝对值得你花时间深入研究一番。