ruflo 浏览器自动化技能指南基于 agent-browser 的 AI 优化快照与 Claude-Flow 集成实战【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo浏览器自动化是 AI Agent 落地真实业务的关键能力而传统 DOM/CSS 选择器方案对 LLM 极其不友好——超长页面会把上下文撑爆。本文以 ruflo 仓库中v3/claude-flow/browser模块的浏览器技能文档为主体系统讲解基于 agent-browser CLI 的自动化工作流如何用元素引用Element Refs将上下文消耗降低 93%如何通过snapshot -i获取仅含可交互元素的无障碍树以及如何与 Claude-Flow 的记忆、Hooks 与 MCP 工具体系深度集成。读完本文你将掌握一套可复制、可运行的浏览器自动化技能并理解其背后的源码级原理。一、技能概览为 Agent 优化的浏览器自动化浏览器技能Browser Automation Skill位于 v3/claude-flow/browser/skills/browser/SKILL.md其技能元数据定义如下name: browser description: Web browser automation with AI-optimized snapshots for claude-flow agents version: 1.0.0 triggers: - /browser - browse - web automation - scrape - navigate - screenshot tools: - browser/open - browser/snapshot - browser/click - browser/fill - browser/screenshot - browser/close核心设计理念只有一句话用元素引用e1、e2代替完整 DOM 来压缩上下文。该技能声称可将上下文消耗降低 93%——其依据在 v3/claude-flow/browser/README.md 中有明确示例传统写法body div.container form#login button[typesubmit].btn.btn-primary对应的元素引用仅为e3。元素引用来源于无障碍树快照指向页面上的可交互元素。从源码结构看该模块采用分层架构src/index.ts 及各子目录领域层src/domain定义ActionResult、Snapshot、OpenInput、ClickInput等类型与浏览器适配接口应用层src/applicationBrowserService聚合业务逻辑、action-router负责动作分发基础设施层src/infrastructureAgentBrowserAdapter封装 agent-browser CLI 调用memory-integration、hooks-integration、security-integration完成生态对接MCP 工具层src/mcp-tools/browser-tools.ts将全部操作注册为browser/前缀的 MCP 工具。二、环境准备与核心工作流2.1 安装依赖技能依赖 agent-browser CLI 与 Claude-Flow 运行时# agent-browser CLI全局安装必需 npm install -g agent-browser # Claude-Flow CLI对等依赖 npm install claude-flow/cli^3.0.0-alpha # Playwright 浏览器agent-browser 通常会自动安装缺失时手动补装 npx playwright install2.2 四步核心工作流任何自动化任务都遵循打开 → 快照 → 交互 → 重新快照的循环# 1. 导航到页面 agent-browser open url # 2. 获取含元素引用的无障碍树-i 仅可交互元素 agent-browser snapshot -i # 3. 使用快照返回的引用进行交互 agent-browser click e2 agent-browser fill e3 text # 4. 页面状态变化后重新快照 agent-browser snapshot -i第 4 步至关重要页面跳转、弹窗、异步渲染都会让旧引用失效每次导航后都必须重新快照。这也是 SKILL.md Tips 中第 4 条Re-snapshot after navigation的由来。三、命令速查手册3.1 导航Navigation命令说明open url导航到 URLback后退forward前进reload刷新页面close关闭浏览器在 MCP 工具层这些对应 browser-tools.ts 中的browser/open、browser/back、browser/forward、browser/reload、browser/close。其中browser/open支持三个可选参数waitUntil可选load、domcontentloaded、networkidle、headers设置限定于 URL 来源域的 HTTP 头、session隔离会话。底层实现见 agent-browser-adapter.ts它通过execFileSync拼装open url [--wait state] [--headers json]调用 agent-browser。3.2 快照与截图AI 优化命令说明snapshot完整无障碍树snapshot -i仅可交互元素按钮、链接、输入框snapshot -c紧凑模式移除空元素snapshot -d 3限制树深度为 3 层screenshot [path]截图不传路径时返回 base64快照是技能的灵魂。在 MCP 工具browser/snapshot的定义中browser-tools.tsinteractive与compact默认均为true即只显示可交互元素 移除空结构元素正是为了把 LLM 收到的 DOM 压缩到最小。快照还支持selector参数可将快照范围限定在某个 CSS 选择器内。适配层实现agent-browser-adapter.ts会将这些选项映射为-i、-c、-d、-s命令行参数。3.3 交互Interaction命令说明click sel点击元素fill sel text清空并填充输入框type sel text以键盘事件方式输入press key按键Enter、Tab 等hover sel悬停select sel val选择下拉选项check/uncheck sel勾选/取消勾选复选框scroll dir [px]滚动页面适配层为这些命令提供了更细的参数agent-browser-adapter.tsclick支持--buttonleft/right/middle、--click-count2 表示双击、--force元素不可见时强制点击type支持--delay模拟真实输入节奏scroll支持 up/down/left/right 方向与像素值。此外还有快照引用之外的补充操作dblclick、focus、scrollintoview、drag、upload可用于文件上传等复杂场景。3.4 信息获取Get Info命令说明get text sel获取文本内容get html sel获取 innerHTMLget value sel获取输入框值get attr sel attr获取属性get title获取页面标题get url获取当前 URL适配层还扩展了get count统计元素数量与get box获取元素坐标尺寸以及is visible/enabled/checked状态断言agent-browser-adapter.ts这些对测试类 Agent 非常实用。3.5 等待Wait命令说明wait selector等待元素出现wait ms等待指定毫秒数wait --text text等待文本出现wait --url pattern等待 URL 匹配模式wait --load networkidle等待加载状态等待是避免竞态条件的关键。适配层实现agent-browser-adapter.ts还支持--fn传入自定义等待函数四类条件selector / text / url / load任选其一即可。3.6 会话Sessions命令说明--session name使用隔离会话session list列出活动会话会话是并行与隔离的基础。MCP 工具层通过内存中的sessions注册表Mapstring, AgentBrowserAdapter见 browser-tools.ts按 session ID 复用适配器实例多个 Agent 可共享浏览器进程但互不干扰browser/close关闭会话后会自动从注册表中移除。四、选择器体系三种定位方式4.1 元素引用推荐# 从快照获取引用 agent-browser snapshot -i # Output: button Submit [refe2] # 使用引用交互 agent-browser click e2元素引用直接来自无障碍树确定性强、输出紧凑是技能文档明确推荐的首选方式。4.2 CSS 选择器agent-browser click #submit agent-browser fill .email-input testtest.comCSS 选择器适合快照之外的兜底定位但表达冗长会显著增加上下文开销。4.3 语义定位器Semantic Locatorsagent-browser find role button click --name Submit agent-browser find label Email fill testtest.com agent-browser find testid login-btn click语义定位器按 role、label、testid 等语义属性定位接近自然语言表达比 CSS 更稳定适合页面结构频繁变化的场景。五、实战示例5.1 登录流程agent-browser open https://example.com/login agent-browser snapshot -i agent-browser fill e2 userexample.com agent-browser fill e3 password123 agent-browser click e4 agent-browser wait --url **/dashboard5.2 表单提交agent-browser open https://example.com/contact agent-browser snapshot -i agent-browser fill e1 John Doe agent-browser fill e2 johnexample.com agent-browser fill e3 Hello, this is my message agent-browser click e4 agent-browser wait --text Thank you5.3 数据提取agent-browser open https://example.com/products agent-browser snapshot -i # 遍历产品元素引用 agent-browser get text e1 # 产品名 agent-browser get text e2 # 价格 agent-browser get attr e3 href # 链接在编程式场景中README.md 展示了等价的 TypeScript 写法browser.extractData([e1, e2, e3])可批量提取多个引用的文本返回Recordstring, string。5.4 多会话协作Swarm# 会话 1导航者Navigator登录并保存状态 agent-browser --session nav open https://example.com agent-browser --session nav state save auth.json # 会话 2爬取者Scraper复用同一登录态 agent-browser --session scrape state load auth.json agent-browser --session scrape open https://example.com/data agent-browser --session scrape snapshot -i这种导航者登录、多个爬取者共享认证态的模式是 Swarm 并行爬取的标准做法只做一次认证所有工作会话复用既高效又避免触发风控。模块提供了createBrowserSwarm见 README.md用于程序化编排支持hierarchical拓扑与navigator/scraper/validator/tester/monitor五种预置角色。六、与 Claude-Flow 的深度集成6.1 MCP 工具集成所有浏览器操作均以browser/前缀注册为 MCP 工具browser-tools.ts技能元数据声明了核心六个browser/open、browser/snapshot、browser/click、browser/fill、browser/screenshot、browser/close。注册方式import { browserTools } from claude-flow/browser; mcpServer.registerTools(browserTools);每个工具都带 JSON Schema 输入校验例如browser/click的button字段枚举left|right|middle且默认left、force可强制点击不可见元素browser-tools.ts。技能的导出入口在 src/skill/index.ts它将 MCP 工具、BrowserService与 Hooks 一并对外暴露。6.2 记忆集成Memory Integration成功的行为模式可以沉淀为可复用的模式记忆下次遇到相似任务时直接检索# 存储成功模式 npx claude-flow/cli memory store --namespace browser-patterns --key login-flow --value snapshot-fill-click-wait # 相似任务前检索 npx claude-flow/cli memory search --query login automation程序化层面BrowserMemoryManager见 README.md提供storeTrajectory、storePattern、storeSnapshot、storeError以及语义检索findSimilarTrajectories与getSessionStats。轨迹Trajectory在browser.startTrajectory(goal)时开始记录、endTrajectory(success, verdict)时落库其中包含目标、逐步动作、每步快照与成败判定——这些数据会交给 ReasoningBank 进行模式学习。6.3 Hooks 集成# 浏览前 Hook获取上下文建议 npx claude-flow/cli hooks pre-edit --file browser-task.ts # 浏览后 Hook记录执行结果 npx claude-flow/cli hooks post-task --task-id browse-1 --success truepreBrowseHook会根据目标推荐步骤、检索相似模式并给出模型建议与安全警告postBrowseHook记录轨迹结果若成功则沉淀为模式供下次复用README.md 的 Hooks Integration 章节。6.4 安全集成README 明确该模块是安全优先设计createBrowserService({ enableSecurity: true })默认开启 URL 校验与 PII 检测。scanUrl会识别钓鱼仿冒域名如paypa1-secure.xyz、非法 TLDscanForPII能识别身份证、信用卡等敏感信息并打码如***-**-6789validateInput可拦截 XSS 与 SQL 注入载荷。安全扫描器支持requireHttps、blockedDomains、allowedDomains、maxRedirects等配置见 README.md 的 Security Scanner API。七、使用建议与注意事项始终使用快照——快照针对 AI 优化过自带元素引用优先-i标志——只取可交互元素输出更小、信噪比更高用引用而非选择器——更可靠、更确定导航后重新快照——页面状态会变旧引用会失效并行任务用会话隔离——每个会话相互独立避免共享状态冲突。八、相关资源技能定义v3/claude-flow/browser/skills/browser/SKILL.md模块说明与 APIv3/claude-flow/browser/README.mdMCP 工具实现v3/claude-flow/browser/src/mcp-tools/browser-tools.tsCLI 适配层v3/claude-flow/browser/src/infrastructure/agent-browser-adapter.ts技能导出v3/claude-flow/browser/src/skill/index.ts测试用例v3/claude-flow/browser/tests覆盖适配器、安全、记忆、轨迹等 128 项测试【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ruflo 浏览器自动化技能指南：基于 agent-browser 的 AI 优化快照与 Claude-Flow 集成实战
ruflo 浏览器自动化技能指南基于 agent-browser 的 AI 优化快照与 Claude-Flow 集成实战【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo浏览器自动化是 AI Agent 落地真实业务的关键能力而传统 DOM/CSS 选择器方案对 LLM 极其不友好——超长页面会把上下文撑爆。本文以 ruflo 仓库中v3/claude-flow/browser模块的浏览器技能文档为主体系统讲解基于 agent-browser CLI 的自动化工作流如何用元素引用Element Refs将上下文消耗降低 93%如何通过snapshot -i获取仅含可交互元素的无障碍树以及如何与 Claude-Flow 的记忆、Hooks 与 MCP 工具体系深度集成。读完本文你将掌握一套可复制、可运行的浏览器自动化技能并理解其背后的源码级原理。一、技能概览为 Agent 优化的浏览器自动化浏览器技能Browser Automation Skill位于 v3/claude-flow/browser/skills/browser/SKILL.md其技能元数据定义如下name: browser description: Web browser automation with AI-optimized snapshots for claude-flow agents version: 1.0.0 triggers: - /browser - browse - web automation - scrape - navigate - screenshot tools: - browser/open - browser/snapshot - browser/click - browser/fill - browser/screenshot - browser/close核心设计理念只有一句话用元素引用e1、e2代替完整 DOM 来压缩上下文。该技能声称可将上下文消耗降低 93%——其依据在 v3/claude-flow/browser/README.md 中有明确示例传统写法body div.container form#login button[typesubmit].btn.btn-primary对应的元素引用仅为e3。元素引用来源于无障碍树快照指向页面上的可交互元素。从源码结构看该模块采用分层架构src/index.ts 及各子目录领域层src/domain定义ActionResult、Snapshot、OpenInput、ClickInput等类型与浏览器适配接口应用层src/applicationBrowserService聚合业务逻辑、action-router负责动作分发基础设施层src/infrastructureAgentBrowserAdapter封装 agent-browser CLI 调用memory-integration、hooks-integration、security-integration完成生态对接MCP 工具层src/mcp-tools/browser-tools.ts将全部操作注册为browser/前缀的 MCP 工具。二、环境准备与核心工作流2.1 安装依赖技能依赖 agent-browser CLI 与 Claude-Flow 运行时# agent-browser CLI全局安装必需 npm install -g agent-browser # Claude-Flow CLI对等依赖 npm install claude-flow/cli^3.0.0-alpha # Playwright 浏览器agent-browser 通常会自动安装缺失时手动补装 npx playwright install2.2 四步核心工作流任何自动化任务都遵循打开 → 快照 → 交互 → 重新快照的循环# 1. 导航到页面 agent-browser open url # 2. 获取含元素引用的无障碍树-i 仅可交互元素 agent-browser snapshot -i # 3. 使用快照返回的引用进行交互 agent-browser click e2 agent-browser fill e3 text # 4. 页面状态变化后重新快照 agent-browser snapshot -i第 4 步至关重要页面跳转、弹窗、异步渲染都会让旧引用失效每次导航后都必须重新快照。这也是 SKILL.md Tips 中第 4 条Re-snapshot after navigation的由来。三、命令速查手册3.1 导航Navigation命令说明open url导航到 URLback后退forward前进reload刷新页面close关闭浏览器在 MCP 工具层这些对应 browser-tools.ts 中的browser/open、browser/back、browser/forward、browser/reload、browser/close。其中browser/open支持三个可选参数waitUntil可选load、domcontentloaded、networkidle、headers设置限定于 URL 来源域的 HTTP 头、session隔离会话。底层实现见 agent-browser-adapter.ts它通过execFileSync拼装open url [--wait state] [--headers json]调用 agent-browser。3.2 快照与截图AI 优化命令说明snapshot完整无障碍树snapshot -i仅可交互元素按钮、链接、输入框snapshot -c紧凑模式移除空元素snapshot -d 3限制树深度为 3 层screenshot [path]截图不传路径时返回 base64快照是技能的灵魂。在 MCP 工具browser/snapshot的定义中browser-tools.tsinteractive与compact默认均为true即只显示可交互元素 移除空结构元素正是为了把 LLM 收到的 DOM 压缩到最小。快照还支持selector参数可将快照范围限定在某个 CSS 选择器内。适配层实现agent-browser-adapter.ts会将这些选项映射为-i、-c、-d、-s命令行参数。3.3 交互Interaction命令说明click sel点击元素fill sel text清空并填充输入框type sel text以键盘事件方式输入press key按键Enter、Tab 等hover sel悬停select sel val选择下拉选项check/uncheck sel勾选/取消勾选复选框scroll dir [px]滚动页面适配层为这些命令提供了更细的参数agent-browser-adapter.tsclick支持--buttonleft/right/middle、--click-count2 表示双击、--force元素不可见时强制点击type支持--delay模拟真实输入节奏scroll支持 up/down/left/right 方向与像素值。此外还有快照引用之外的补充操作dblclick、focus、scrollintoview、drag、upload可用于文件上传等复杂场景。3.4 信息获取Get Info命令说明get text sel获取文本内容get html sel获取 innerHTMLget value sel获取输入框值get attr sel attr获取属性get title获取页面标题get url获取当前 URL适配层还扩展了get count统计元素数量与get box获取元素坐标尺寸以及is visible/enabled/checked状态断言agent-browser-adapter.ts这些对测试类 Agent 非常实用。3.5 等待Wait命令说明wait selector等待元素出现wait ms等待指定毫秒数wait --text text等待文本出现wait --url pattern等待 URL 匹配模式wait --load networkidle等待加载状态等待是避免竞态条件的关键。适配层实现agent-browser-adapter.ts还支持--fn传入自定义等待函数四类条件selector / text / url / load任选其一即可。3.6 会话Sessions命令说明--session name使用隔离会话session list列出活动会话会话是并行与隔离的基础。MCP 工具层通过内存中的sessions注册表Mapstring, AgentBrowserAdapter见 browser-tools.ts按 session ID 复用适配器实例多个 Agent 可共享浏览器进程但互不干扰browser/close关闭会话后会自动从注册表中移除。四、选择器体系三种定位方式4.1 元素引用推荐# 从快照获取引用 agent-browser snapshot -i # Output: button Submit [refe2] # 使用引用交互 agent-browser click e2元素引用直接来自无障碍树确定性强、输出紧凑是技能文档明确推荐的首选方式。4.2 CSS 选择器agent-browser click #submit agent-browser fill .email-input testtest.comCSS 选择器适合快照之外的兜底定位但表达冗长会显著增加上下文开销。4.3 语义定位器Semantic Locatorsagent-browser find role button click --name Submit agent-browser find label Email fill testtest.com agent-browser find testid login-btn click语义定位器按 role、label、testid 等语义属性定位接近自然语言表达比 CSS 更稳定适合页面结构频繁变化的场景。五、实战示例5.1 登录流程agent-browser open https://example.com/login agent-browser snapshot -i agent-browser fill e2 userexample.com agent-browser fill e3 password123 agent-browser click e4 agent-browser wait --url **/dashboard5.2 表单提交agent-browser open https://example.com/contact agent-browser snapshot -i agent-browser fill e1 John Doe agent-browser fill e2 johnexample.com agent-browser fill e3 Hello, this is my message agent-browser click e4 agent-browser wait --text Thank you5.3 数据提取agent-browser open https://example.com/products agent-browser snapshot -i # 遍历产品元素引用 agent-browser get text e1 # 产品名 agent-browser get text e2 # 价格 agent-browser get attr e3 href # 链接在编程式场景中README.md 展示了等价的 TypeScript 写法browser.extractData([e1, e2, e3])可批量提取多个引用的文本返回Recordstring, string。5.4 多会话协作Swarm# 会话 1导航者Navigator登录并保存状态 agent-browser --session nav open https://example.com agent-browser --session nav state save auth.json # 会话 2爬取者Scraper复用同一登录态 agent-browser --session scrape state load auth.json agent-browser --session scrape open https://example.com/data agent-browser --session scrape snapshot -i这种导航者登录、多个爬取者共享认证态的模式是 Swarm 并行爬取的标准做法只做一次认证所有工作会话复用既高效又避免触发风控。模块提供了createBrowserSwarm见 README.md用于程序化编排支持hierarchical拓扑与navigator/scraper/validator/tester/monitor五种预置角色。六、与 Claude-Flow 的深度集成6.1 MCP 工具集成所有浏览器操作均以browser/前缀注册为 MCP 工具browser-tools.ts技能元数据声明了核心六个browser/open、browser/snapshot、browser/click、browser/fill、browser/screenshot、browser/close。注册方式import { browserTools } from claude-flow/browser; mcpServer.registerTools(browserTools);每个工具都带 JSON Schema 输入校验例如browser/click的button字段枚举left|right|middle且默认left、force可强制点击不可见元素browser-tools.ts。技能的导出入口在 src/skill/index.ts它将 MCP 工具、BrowserService与 Hooks 一并对外暴露。6.2 记忆集成Memory Integration成功的行为模式可以沉淀为可复用的模式记忆下次遇到相似任务时直接检索# 存储成功模式 npx claude-flow/cli memory store --namespace browser-patterns --key login-flow --value snapshot-fill-click-wait # 相似任务前检索 npx claude-flow/cli memory search --query login automation程序化层面BrowserMemoryManager见 README.md提供storeTrajectory、storePattern、storeSnapshot、storeError以及语义检索findSimilarTrajectories与getSessionStats。轨迹Trajectory在browser.startTrajectory(goal)时开始记录、endTrajectory(success, verdict)时落库其中包含目标、逐步动作、每步快照与成败判定——这些数据会交给 ReasoningBank 进行模式学习。6.3 Hooks 集成# 浏览前 Hook获取上下文建议 npx claude-flow/cli hooks pre-edit --file browser-task.ts # 浏览后 Hook记录执行结果 npx claude-flow/cli hooks post-task --task-id browse-1 --success truepreBrowseHook会根据目标推荐步骤、检索相似模式并给出模型建议与安全警告postBrowseHook记录轨迹结果若成功则沉淀为模式供下次复用README.md 的 Hooks Integration 章节。6.4 安全集成README 明确该模块是安全优先设计createBrowserService({ enableSecurity: true })默认开启 URL 校验与 PII 检测。scanUrl会识别钓鱼仿冒域名如paypa1-secure.xyz、非法 TLDscanForPII能识别身份证、信用卡等敏感信息并打码如***-**-6789validateInput可拦截 XSS 与 SQL 注入载荷。安全扫描器支持requireHttps、blockedDomains、allowedDomains、maxRedirects等配置见 README.md 的 Security Scanner API。七、使用建议与注意事项始终使用快照——快照针对 AI 优化过自带元素引用优先-i标志——只取可交互元素输出更小、信噪比更高用引用而非选择器——更可靠、更确定导航后重新快照——页面状态会变旧引用会失效并行任务用会话隔离——每个会话相互独立避免共享状态冲突。八、相关资源技能定义v3/claude-flow/browser/skills/browser/SKILL.md模块说明与 APIv3/claude-flow/browser/README.mdMCP 工具实现v3/claude-flow/browser/src/mcp-tools/browser-tools.tsCLI 适配层v3/claude-flow/browser/src/infrastructure/agent-browser-adapter.ts技能导出v3/claude-flow/browser/src/skill/index.ts测试用例v3/claude-flow/browser/tests覆盖适配器、安全、记忆、轨迹等 128 项测试【免费下载链接】ruflo The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, RAG integration, and native Claude Code / Codex / Hermes and many more Integrated项目地址: https://gitcode.com/GitHub_Trending/cl/ruflo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考