快速开始
两条路,本页都覆盖:CLI——用一条 shell 命令跑自然语言任务,零代码; 以及 Python SDK。即使你是冲着 SDK 来的,也建议先用 CLI 跑一条——一行 命令即可验证环境。(无需配置任何模型 API key——视觉模型托管在服务端。)
两条命令——先登录一次(自动打开浏览器完成授权;无头机器上用任意设备 打开打印出的链接即可),然后把任务交给 AI:
qirabot login # 浏览器授权;校验后保存,之后每次运行自动读取
qirabot browser "搜索 SpaceX 并提取词条的第一句话" --url wikipedia.org这就是一次完整运行:浏览器打开,AI 完成任务,结果(和一份 HTML 报告)输出 到终端。所有命令和选项见 CLI 参考。(想用环境变量? QIRA_API_KEY 和项目 .env 依然有效且优先级更高。)
browser 命令假定你走的是一行安装脚本或 pip install "qirabot[browser]" 路径——如果为设备后端只装了核心 qirabot,各 extra 见 安装。
用 Python 实现同一任务
bot.ai() 就是 CLI 命令底层的引擎:AI 看屏、决定下一步动作,循环执行直到 任务完成:
from qirabot import Qirabot
bot = Qirabot()
page = bot.open("https://www.wikipedia.org")
result = bot.ai(page, "搜索 SpaceX 并提取词条的第一句话")
print(f"Success: {result.success}")
print(f"Result: {result.output}")
bot.close()确定性步骤
想自己掌控每一步而不是把整个任务交给 AI 时,同样的自然语言定位能力也可以 按单步调用——更快、成本更低、控制流在你手里:
from qirabot import Qirabot
bot = Qirabot()
page = bot.open("https://www.saucedemo.com")
# 用自然语言描述元素(任何语言都行);AI 视觉定位,代码由你掌控:
bot.type_text(page, "用户名输入框", "standard_user")
bot.type_text(page, "密码输入框", "secret_sauce")
bot.click(page, "登录按钮")
# 基于视觉状态设卡点——wait_for 轮询直到成立,超时抛异常
bot.wait_for(page, "商品列表页已显示")
# 直接从屏幕提取结构化数据——不写爬取逻辑、不写选择器
count = bot.extract(page, "购物车角标上的数字,返回整数")
bot.close()核心调用:
| 调用 | 作用 |
|---|---|
bot.ai(target, task) | 自主多步任务——看屏、决策、执行、循环直到完成 |
bot.click(target, "描述") | AI 定位的点击(另有 double_click、type_text) |
bot.extract(target, "描述") | 从屏幕提取结构化数据 |
bot.verify(target, "断言") | 视觉断言——结果为 truthy/falsy,断言不成立不抛异常 |
bot.wait_for(target, "条件") | 轮询直到视觉条件成立,超时抛异常 |
target 就是你正在驱动的界面——bot.open() 返回的 page、你自己的 Playwright/Selenium/Appium 对象,或桌面场景下的 pyautogui 模块。完整 调用列表和各平台行为见 API 参考。
任务如何结束
result.success 是二值的通过/失败;result.status 说明原因: "completed"、"goal_failed"(登录墙、验证码)、"max_steps"(步数预算 截断——加大预算重试)、"error"。详情和异常体系见 错误处理。
result = bot.ai(page, "找到最便宜的航班并锁定")
if result.status == "max_steps":
# 不是真的失败——预算太小;加大步数重试
result = bot.ai(page, "找到最便宜的航班并锁定", max_steps=50)报告
每次运行都会在 ./qira_runs/<日期>/<时间-id>/ 写入一份自包含的 HTML 报告, 带逐步截图——出错或 Ctrl+C 也会生成,方便定位在哪一步停下。传 record=True(CLI 用 --record)还能录制整个运行过程的视频。
下一步
- 选择你的后端:浏览器 · Android · iOS · Windows 与游戏 · 桌面
- 要挂载到现有 Playwright / Selenium / Appium 套件?见 自定义 Adapter 与挂载
- CLI 参考