webcli — 无头浏览器命令行工具

您可通过 webcli 命令访问一个无头浏览器。使用它可导航网站、读取页面内容、与元素交互、截取屏幕截图，以及获取可访问性快照。

前提条件

npm install -g @erdinccurebal/webcli
npx playwright install chromium

项目主页：https://webcli.erdinc.curebal.dev/ 代码仓库：https://github.com/erdinccurebal/webcli

命令参考

导航

webcli go                     # 导航至指定 URL（自动启动守护进程）
webcli go  -w networkidle     # 等待网络请求完成
webcli go  -t mytab           # 在指定名称的标签页中打开
webcli back                        # 返回上一页
webcli forward                     # 前进到下一页
webcli reload                      # 重新加载当前页面

读取页面内容

webcli source                      # 获取页面全部可见文本
webcli links                       # 列出所有链接（文本 + href）
webcli forms                       # 列出所有表单及其输入字段
webcli html              # 获取指定元素的 innerHTML
webcli attr   # 获取指定元素的属性值
webcli eval ""                 # 执行 JavaScript 并返回结果
webcli title                       # 获取页面标题
webcli url                         # 获取当前 URL
webcli value             # 获取 input / textarea 的值
webcli count             # 统计匹配元素的数量
webcli box               # 获取元素边界框（x, y, w, h）
webcli styles  [props..] # 获取计算后的 CSS 样式
webcli visible           # 检查元素是否可见
webcli enabled           # 检查元素是否启用
webcli checked           # 检查复选框是否已勾选

可访问性快照（推荐 AI Agent 使用）

webcli snapshot                    # 获取含引用标识（@e1、@e2…）的可访问性树
webcli snapshot --all              # 包含非交互式元素
webcli snapshot --max-depth 5      # 限制树的最大深度

该快照为所有交互式元素分配确定性的引用标识。可在其他命令中使用这些引用：

webcli snapshot                    # 获取可访问性树：[button @e1] "Submit"，[textbox @e2] "Email"
webcli fill @e2 "user@example.com" # 使用引用填充
webcli click @e1                   # 使用引用点击

交互

webcli click "<可见文本>"         # 根据可见文本点击元素
webcli click @e1                   # 根据快照中的引用点击元素
webcli clicksel ""   # 根据 CSS 选择器点击元素
webcli dblclick "<文本>"           # 根据可见文本双击元素
webcli hover "<选择器>"          # 将鼠标悬停在元素上
webcli fill "<选择器>" "<值>"     # 填充输入字段（表单操作首选）
webcli type "<文本>"               # 键盘输入（仅对已聚焦元素有效）
webcli select "<选择器>" "<值>"   # 选择下拉菜单选项
webcli press Enter                 # 按下键盘按键（Enter、Tab、Escape 等）
webcli focus "<选择器>"          # 聚焦到指定元素
webcli check "<选择器>"         # 勾选复选框
webcli uncheck "<选择器>"       # 取消勾选复选框
webcli drag "<起始位置>" "<目标位置>" # 在两个选择器之间执行拖放操作
webcli upload "<选择器>" <文件路径>  # 向 input[type=file] 元素上传文件
webcli scroll down 500             # 页面滚动（up/down/left/right，单位：像素）

等待

webcli wait "<选择器>"           # 等待 CSS 选择器对应的元素变为可见
webcli waitfor "<文本>"            # 等待指定文本出现在页面上
webcli sleep 2000                  # 暂停 N 毫秒

截图与 PDF

webcli screenshot                  # 截取整页截图（返回保存路径）
webcli screenshot -o page.png      # 保存为指定文件名
webcli screenshot --no-full        # 仅截取视口区域（viewport-only）
webcli screenshot --annotate       # 截图并标注编号的交互式元素
webcli pdf                         # 将当前页面保存为 PDF
webcli pdf -o page.pdf             # 将 PDF 保存为指定文件名

控制台与错误

webcli console on                  # 开始捕获控制台日志
webcli console off                 # 停止捕获
webcli console                     # 显示已捕获的控制台消息
webcli errors                      # 显示页面错误

对话框处理

webcli dialog accept               # 接受 alert / confirm 对话框
webcli dialog accept "输入文本"    # 向 prompt 对话框输入文本并确认
webcli dialog dismiss              # 取消/关闭对话框

框架（iframe）切换

webcli frame "<选择器>"          # 切换至指定 iframe
webcli frame main                  # 切换回主框架（main frame）

存储（localStorage）

webcli storage get                 # 获取全部 localStorage 数据
webcli storage get mykey           # 获取指定键的值
webcli storage set mykey myvalue   # 设置指定键的值
webcli storage clear               # 清空全部 localStorage

状态管理

webcli state save session.json     # 保存 cookies + localStorage + sessionStorage
webcli state load session.json     # 恢复完整的浏览器状态

浏览器设置

webcli viewport 1920 1080          # 修改视口尺寸
webcli useragent "<字符串>"        # 修改 User-Agent 字符串
webcli device "iPhone 14"          # 模拟设备（同时修改视口和 UA）
webcli network on                  # 开始记录网络请求
webcli network off                 # 停止记录
webcli network                     # 显示网络请求日志

Cookie 管理

webcli cookie export               # 将 cookies 导出为 JSON 格式
webcli cookie import <文件路径>     # 从 JSON 文件导入 cookies

标签页与守护进程管理

webcli tabs                        # 列出当前所有打开的标签页
webcli quit                        # 关闭当前标签页
webcli quit -t mytab               # 关闭指定名称的标签页
webcli status                      # 显示守护进程信息（PID、运行时长、标签页列表）
webcli stop                        # 停止守护进程并关闭浏览器

全局选项

所有命令均支持以下选项：

• -t, --tab — 指定目标标签页（默认为 "default"）
• --json — 以结构化 JSON 格式输出结果
• --timeout — 设置命令超时时间（默认：30000 毫秒）

最佳实践

推荐的 AI Agent 工作流

1. webcli go — 导航至目标页面
2. webcli snapshot — 获取带引用标识的可访问性树
3. 使用引用标识进行交互：webcli click @e1、webcli fill @e2 "value"
4. 再次执行 webcli snapshot 查看更新后的页面状态
5. 如需视觉确认，执行 webcli screenshot

替代工作流（纯文本方式）

1. webcli go — 导航至目标页面
2. webcli source — 读取页面全文本内容
3. 使用 webcli click、webcli fill、webcli press 进行交互
4. 再次执行 webcli source 查看操作结果

表单填写

• 始终使用 webcli fill 填充输入字段——它能正确设置 React/Vue 中受控组件（controlled inputs）的值
• 按钮点击请使用 webcli click 或 webcli clicksel
• 提交表单建议使用 webcli press Enter
• 提交后，建议先执行 webcli sleep 1000，再执行 webcli source 验证结果

多标签页浏览

webcli go https://site-a.com -t research
webcli go https://site-b.com -t reference
webcli source -t research          # 读取指定标签页内容
webcli source -t reference

错误恢复

• 若命令超时，可尝试先执行 webcli sleep 2000，再重试
• 若找不到目标元素，可用 webcli source 检查当前页面实际内容
• 若守护进程疑似卡死，可执行 webcli stop 后重试命令
• 与动态加载的内容交互前，建议先使用 webcli wait ""

重要说明

• 在尝试任何交互操作前，请务必先用 webcli source 或 webcli snapshot 读取页面内容
• 为获得最可靠的元素定位能力，优先使用 webcli snapshot + 引用标识的方式
• 表单输入操作中，优先使用 webcli fill 而非 webcli type
• 在可行的前提下，优先使用 webcli click（按可见文本）而非 webcli clicksel（按 CSS 选择器）
• 高频交互之间建议插入 webcli sleep，确保页面有足够时间完成更新
• 守护进程在命令间持续运行——除非页面本身发生变化，否则无需重复导航