Communitygithub.com

ASoudy/AGS

面向AI代理的浏览器自动化CLI工具,用于网页导航、表单填写、截图、数据提取等任务。

AGS 是什么?

该技能是一个基于CLI的浏览器自动化工具,专为AI代理设计,通过Chrome DevTools Protocol (CDP)直接控制Chrome/Chromium浏览器。它支持网页导航、元素交互(点击、填写、选择)、截图、PDF生成、网络请求拦截、设备模拟、剪贴板操作、对话框处理等全面功能。核心工作流程包括导航、快照获取元素引用(如@e1、@e2)、基于引用进行交互,以及重新快照。支持命令链式执行和批量执行,通过后台守护进程保持浏览器持久化,显著减少工具调用次数和令牌消耗。提供多种认证方案:导入用户浏览器状态、复用Chrome配置文件、持久化配置文件、会话名称自动保存/恢复、加密认证保管库以及手动状态文件管理。还支持WebSocket流式传输实时预览、AI自然语言控制(chat模式)、页面状态差异对比(diff)等功能。适用于需要程序化网页交互的任何场景,如表单自动化、数据抓取、Web应用测试和多步骤工作流。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/agent-browser

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

使用 agent-browser 进行浏览器自动化

该 CLI 通过 CDP 直接使用 Chrome/Chromium。通过 npm i -g agent-browser、brew install agent-browser 或 cargo install agent-browser 安装。运行 agent-browser install 下载 Chrome。系统上现有的 Chrome、Brave、Playwright 和 Puppeteer 安装会被自动检测。运行 agent-browser upgrade 更新至最新版本。

核心工作流

每个浏览器自动化任务都遵循以下模式:

  1. 导航:agent-browser open <url>
  2. 快照:agent-browser snapshot -i(获取元素引用,如 @e1、@e2)
  3. 交互:使用引用进行点击、填写、选择
  4. 重新快照:导航或 DOM 变化后,获取新的引用
agent-browser open https://example.com/form
agent-browser snapshot -i
# 输出:@e1 [input type="email"], @e2 [input type="password"], @e3 [button] "Submit"

agent-browser fill @e1 "[email protected]"
agent-browser fill @e2 "password123"
agent-browser click @e3
agent-browser wait 2000
agent-browser snapshot -i  # 检查结果

命令链式执行

命令可以通过 && 在单个 shell 调用中链式执行。浏览器通过后台守护进程在命令之间保持持久化,因此链式执行既安全又比单独调用更高效。

# 在单次调用中链式执行 open + snapshot(open 已等待页面加载完成)
agent-browser open https://example.com && agent-browser snapshot -i

# 链式执行多个交互
agent-browser fill @e1 "[email protected]" && agent-browser fill @e2 "password123" && agent-browser click @e3

# 导航并截图
agent-browser open https://example.com && agent-browser screenshot

何时链式执行: 当您无需在继续之前读取中间命令的输出时,使用 &&(例如,open + wait + screenshot)。当您需要先解析输出时,请单独运行命令(例如,快照以发现引用,然后使用这些引用进行交互)。

处理身份验证

当自动化需要登录的网站时,选择合适的方法:

选项 1:从用户浏览器导入身份验证(一次性任务最快)

# 连接到用户正在运行的 Chrome(他们已经登录)
agent-browser --auto-connect state save ./auth.json
# 使用该身份验证状态
agent-browser --state ./auth.json open https://app.example.com/dashboard

状态文件包含明文会话令牌——请添加到 .gitignore 并在不需要时删除。设置 AGENT_BROWSER_ENCRYPTION_KEY 以启用静态加密。

选项 2:Chrome 配置文件复用(零配置)

# 列出可用的 Chrome 配置文件
agent-browser profiles

# 复用用户现有的 Chrome 登录状态
agent-browser --profile Default open https://gmail.com

选项 3:持久化配置文件(用于重复任务)

# 首次运行:手动或通过自动化登录
agent-browser --profile ~/.myapp open https://app.example.com/login
# ... 填写凭据,提交 ...

# 所有后续运行:已验证
agent-browser --profile ~/.myapp open https://app.example.com/dashboard

选项 4:会话名称(自动保存/恢复 cookies + localStorage)

agent-browser --session-name myapp open https://app.example.com/login
# ... 登录流程 ...
agent-browser close  # 状态自动保存

# 下次:状态自动恢复
agent-browser --session-name myapp open https://app.example.com/dashboard

选项 5:身份验证保管库(凭据加密存储,按名称登录)

echo "$PASSWORD" | agent-browser auth save myapp --url https://app.example.com/login --username user --password-stdin
agent-browser auth login myapp

auth login 使用 load 导航,然后在填充/点击之前等待登录表单选择器出现,这在延迟的 SPA 登录屏幕上更可靠。

选项 6:状态文件(手动保存/加载)

# 登录后:
agent-browser state save ./auth.json
# 在未来会话中:
agent-browser state load ./auth.json
agent-browser open https://app.example.com/dashboard

请参阅 references/authentication.md 了解 OAuth、2FA、基于 cookie 的身份验证和令牌刷新模式。

基本命令

# 批量:对于 2 个或更多顺序命令,始终使用 batch。命令按顺序执行。
agent-browser batch "open https://example.com" "snapshot -i"
agent-browser batch "open https://example.com" "screenshot"
agent-browser batch "click @e1" "wait 1000" "screenshot"

# 导航
agent-browser open <url>              # 导航(别名:goto、navigate)
agent-browser close                   # 关闭浏览器
agent-browser close --all             # 关闭所有活动会话

# 快照
agent-browser snapshot -i             # 带有引用的交互元素(推荐)
agent-browser snapshot -i --urls      # 为链接包含 href URL
agent-browser snapshot -s "#selector" # 限定 CSS 选择器范围

# 交互(使用快照中的 @ref)
agent-browser click @e1               # 点击元素
agent-browser click @e1 --new-tab     # 点击并在新标签页中打开
agent-browser fill @e2 "text"         # 清除并输入文本
agent-browser type @e2 "text"         # 输入而不清除
agent-browser select @e1 "option"     # 选择下拉选项
agent-browser check @e1               # 勾选复选框
agent-browser press Enter             # 按下按键
agent-browser keyboard type "text"    # 在当前焦点处输入(无选择器)
agent-browser keyboard inserttext "text"  # 插入而不触发按键事件
agent-browser scroll down 500         # 滚动页面
agent-browser scroll down 500 --selector "div.content"  # 在特定容器内滚动

# 获取信息
agent-browser get text @e1            # 获取元素文本
agent-browser get url                 # 获取当前 URL
agent-browser get title               # 获取页面标题
agent-browser get cdp-url             # 获取 CDP WebSocket URL

# 等待
agent-browser wait @e1                # 等待元素出现
agent-browser wait 2000               # 等待毫秒数
agent-browser wait --url "**/page"    # 等待 URL 模式匹配
agent-browser wait --text "Welcome"   # 等待文本出现(子字符串匹配)
agent-browser wait --load networkidle # 等待网络空闲(注意:参见陷阱)
agent-browser wait --fn "!document.body.innerText.includes('Loading...')"  # 等待文本消失
agent-browser wait "#spinner" --state hidden  # 等待元素消失

# 下载
agent-browser download @e1 ./file.pdf          # 点击元素触发下载
agent-browser wait --download ./output.zip     # 等待任何下载完成
agent-browser --download-path ./downloads open <url>  # 设置默认下载目录

# 标签页管理
agent-browser tab list                         # 列出所有打开的标签页
agent-browser tab new                          # 打开一个空白新标签页
agent-browser tab new https://example.com      # 在新标签页中打开 URL
agent-browser tab 2                            # 按索引切换标签页(从0开始)
agent-browser tab close                        # 关闭当前标签页
agent-browser tab close 2                      # 按索引关闭标签页

# 网络
agent-browser network requests                 # 检查跟踪的请求
agent-browser network requests --type xhr,fetch  # 按资源类型过滤
agent-browser network requests --method POST   # 按 HTTP 方法过滤
agent-browser network requests --status 2xx    # 按状态码过滤(200、2xx、400-499)
agent-browser network request <requestId>      # 查看完整的请求/响应详情
agent-browser network route "**/api/*" --abort  # 阻止匹配的请求
agent-browser network har start                # 开始 HAR 录制
agent-browser network har stop ./capture.har   # 停止并保存 HAR 文件

# 视口和设备模拟
agent-browser set viewport 1920 1080          # 设置视口大小(默认:1280x720)
agent-browser set viewport 1920 1080 2        # 2x 视网膜(相同 CSS 大小,更高分辨率截图)
agent-browser set device "iPhone 14"          # 模拟设备(视口 + 用户代理)

# 捕获
agent-browser screenshot              # 截图到临时目录
agent-browser screenshot --full       # 全页面截图
agent-browser screenshot --annotate   # 带编号元素标签的注释截图
agent-browser screenshot --screenshot-dir ./shots  # 保存到自定义目录
agent-browser screenshot --screenshot-format jpeg --screenshot-quality 80
agent-browser pdf output.pdf          # 保存为 PDF

# 实时预览 / 流式传输
agent-browser stream enable           # 在自动选择的端口上启动运行时 WebSocket 流式传输
agent-browser stream enable --port 9223  # 绑定特定的 localhost 端口
agent-browser stream status           # 检查启用状态、端口、连接和屏幕投射
agent-browser stream disable          # 停止运行时流式传输并移除 .stream 元数据文件

# 剪贴板
agent-browser clipboard read                      # 从剪贴板读取文本
agent-browser clipboard write "Hello, World!"     # 向剪贴板写入文本
agent-browser clipboard copy                      # 复制当前选择
agent-browser clipboard paste                     # 从剪贴板粘贴

# 对话框(alert、confirm、prompt、beforeunload)
# 默认情况下,alert 和 beforeunload 对话框会自动接受,因此它们不会阻塞代理。
# confirm 和 prompt 对话框仍然需要显式处理。
# 使用 --no-auto-dialog(或 AGENT_BROWSER_NO_AUTO_DIALOG=1)禁用自动处理。
agent-browser dialog accept              # 接受对话框
agent-browser dialog accept "my input"   # 接受带文本的 prompt 对话框
agent-browser dialog dismiss             # 关闭/取消对话框
agent-browser dialog status              # 检查当前是否有打开的对话框

# 差异比较(比较页面状态)
agent-browser diff snapshot                          # 比较当前快照与上一次快照
agent-browser diff snapshot --baseline before.txt    # 比较当前快照与保存的文件
agent-browser diff screenshot --baseline before.png  # 视觉像素比较
agent-browser diff url <url1> <url2>                 # 比较两个页面
agent-browser diff url <url1> <url2> --wait-until networkidle  # 自定义等待策略
agent-browser diff url <url1> <url2> --selector "#main"  # 限定元素范围

# 聊天(AI 自然语言控制)
agent-browser chat "open google.com and search for cats"  # 单次指令
agent-browser chat                                        # 交互式 REPL 模式
agent-browser -q chat "summarize this page"               # 安静模式(仅文本,无工具调用)
agent-browser -v chat "fill in the login form"            # 详细模式(显示命令输出)
agent-browser --model openai/gpt-4o chat "take a screenshot"  # 覆盖模型

流式传输

每个会话自动在操作系统分配的端口上启动一个 WebSocket 流服务器。使用 agent-browser stream status 查看绑定的端口和连接状态。使用 stream disable 关闭它,使用 stream enable --port <port> 在特定端口上重新启用。

批量执行

运行 2 个或更多顺序命令时,始终使用 batch。Batch 按顺序执行命令,因此依赖命令(如导航然后截图)能够正确工作。每个引用的参数都是一个单独的命令。

# 导航并获取快照
agent-browser batch "open https://example.com" "snapshot -i"

# 在单次调用中导航、快照和截图
agent-browser batch "open https://example.com" "snapshot -i" "screenshot"

# 点击、等待、然后截图
agent-browser batch "click @e1" "wait 1000" "screenshot"

# 使用 --bail 在第一个错误时停止
agent-browser batch --bail "open https://example.com" "click @e1" "screenshot"

仅在需要读取输出以决定下一个命令时,才使用单个命令(而非 batch)。例如,当您需要读取引用以决定点击什么时,必须将 snapshot -i 作为单个命令运行。读取快照后,将剩余步骤批量执行。

还支持 stdin 模式用于程序化使用:

echo '[["open","https://example.com"],["screenshot"]]' | agent-browser batch --json
agent-browser batch --bail < commands.json

效率策略

这些模式最大限度地减少工具调用次数和令牌消耗。

使用 --urls 避免重新导航。 当需要访问页面中的链接时,使用 snapshot -i --urls 一次获取所有 href URL。然后直接 open 每个 URL,而不是点击引用并导航回退。

快照一次,多次操作。 永远不要对同一页面重新快照。从单个快照中提取所有需要的信息(引用、URL、文本),然后批量执行剩余操作。

多页面工作流(例如“访问 N 个站点并截取每个站点的截图”):

# 1. 在单次调用中获取所有 URL
agent-browser batch "open https://news.ycombinator.com" "snapshot -i --urls"
# 读取输出以提取 URL,然后直接访问每个 URL:
# 2. 每个目标站点一个 batch
agent-browser batch "open https://github.com/example/repo" "screenshot"
agent-browser batch "open https://example.com/article" "screenshot"
agent-browser batch "open https://other.com/page" "screenshot"

这种方法使用 4 次工具调用而不是 14 次以上。永远不要在访问之间返回列表页面。

常见模式

表单提交

# 导航并获取表单结构
agent-browser batch "open https://example.com/signup" "snapshot -i"
# 读取快照输出以识别表单引用,然后填写并提交
agent-browser batch "fill @e1 \"Jane Doe\"" "fill @e2 \"[email protected]\"" "select @e3 \"California\"" "check @e4" "click @e5" "wait 2000"

使用身份验证保管库进行身份验证(推荐)

# 保存凭据一次(使用 AGENT_BROWSER_ENCRYPTION_KEY 加密)
# 推荐:通过 stdin 管道密码以避免 shell 历史记录暴露
echo "pass" | agent-browser auth save github --url https://github.com/login --username user --password-stdin

# 使用保存的配置文件登录(LLM 从未看到密码)
agent-browser auth login github

# 列出/显示/删除配置文件
agent-browser auth list
agent-browser auth show github
agent-browser auth delete github

使用差异比较验证页面输出

# 导航到期望页面
agent-browser open https://example.com/settings
agent-browser snapshot -i
# 截取期望状态的截图
agent-browser screenshot --screenshot-dir ./baselines

# 稍后:比较当前页面状态与基线
agent-browser diff screenshot --baseline ./baselines/screenshot.png

完整文档请访问 agent-browser 文档

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

相关技能