Browser automation for AI agents - AXTree scanning, stealth mode, plugin architecture
npm install @sdjz/pupbash
pup goto https://google.com
pup scan
pup click 3
pup type 2 "hello world" --enter
`
这是什么
LLM 看不到浏览器里的内容。pup 通过 DevTools Protocol 连接 Chrome,把页面元素扫描成结构化数据,让 Agent 能理解和操作页面。
- AXTree 扫描 - 通过无障碍树获取页面元素,语义化识别按钮/链接/输入框,无需 CSS 选择器
- Agent 优先 - 所有命令支持 JSON 输出,支持管道和 stdin
- 隐身模式 - 集成 puppeteer-extra-stealth,绕过大部分反爬检测
- DevTools 能力 - 完整 CDP 能力:网络抓包、脚本调试、Cookie/Storage 管理
- 性能分析 - Core Web Vitals、CPU 分析、内存分析、网络瀑布图
- 插件架构 - 模块化,按需加载
安装
`bash
npm install -g @sdjz/pup
`
快速开始
`bash
打开页面
pup goto https://example.com
扫描页面元素
pup scan --no-empty
通过元素 ID 交互
pup click 5
pup type 3 "search" --enter
JSON 输出
pup scan --json
`
命令
$3
`bash
goto # 打开 URL
back / forward # 历史导航
reload # 刷新页面
scroll # 滚动
wait # 等待毫秒
`
$3
`bash
scan # 扫描元素,获取 ID
scanall # 扫描整个页面(滚动)
find # 按文本查找元素
click # 点击元素
click --js # JS 点击(用于模态框)
type # 输入文本
type --enter --clear # 清空、输入、回车
hover # 鼠标悬停
select `
$3
`bash
tabs # 列出所有标签页
tab # 切换标签页
newtab [url] # 新建标签页
close # 关闭当前标签页
closetab # 关闭指定标签页
`
$3
`bash
network # 查看请求
network --capture # 启用 XHR 抓包
network --xhr # 查看抓到的 XHR
cookies # 查看 cookies
cookies --set name=val # 设置 cookie
storage # 查看 localStorage
storage --session # 查看 sessionStorage
scripts # 列出页面脚本
scripts --search # 搜索脚本内容
var # 读取全局变量
exec # 执行 JavaScript
hook # Hook 函数
cdp [params] # 原始 CDP 命令
dom # 查询 DOM
`
$3
`bash
perf # 快速概览(Web Vitals)
perf --reload # 刷新后测量
perf-load [url] # 完整页面加载分析
perf-js # JavaScript CPU 分析
perf-memory # 内存和 DOM 分析
perf-network # 网络瀑布图
perf-longtasks # 主线程阻塞
perf-trace # 完整时间线追踪
perf-analyze # AI 级详细分析
`
$3
`bash
upload # 上传文件
download # 下载文件
download links # 列出可下载链接
screenshot [file] # 截图
`
$3
`bash
emulate # iphone/ipad/android
emulate viewport 1920x1080
ipinfo # IP 和位置信息
status # 当前页面信息
ping # 连接测试
`
完整帮助: pup help
命令详情: pup help
Agent 集成
pup 输出专为 LLM 设计 - 结构化文本,易于阅读:
`bash
$ pup scan --no-empty --limit 5
[+] SCAN 150ms
title Google
url https://www.google.com/
◆ 5 elements in 874x560
[ 1] link "Gmail"
[ 2] combobox "Search"
[ 3] button "Google Search"
[ 4] button "I'm Feeling Lucky"
[ 5] link "About"
`
LLM 直接读取输出,理解页面,决定下一步操作。
$3
`
1. pup goto https://example.com # 打开页面
2. pup scan --no-empty # 扫描元素
3. LLM 决定: 点击元素 5
4. pup click 5 # 执行
5. pup scan --no-empty # 检查结果
6. ...循环
`
$3
`bash
pup batch "goto https://example.com ; scan --no-empty ; click 3"
`
$3
`bash
pup scan --json
{"ok":true,"cmd":"SCAN","elements":[...]}
`
$3
`bash
pup --json
{"cmd":"GOTO","url":"https://example.com"}
{"cmd":"SCAN"}
``