步骤 0 — 预检（务必首先运行）

在环境验证通过前，切勿编写自动化脚本。请运行：

python scripts/preflight.py browser     # 或：android | ios | desktop

该命令会校验 Python 版本、QIRA_API_KEY 环境变量、qirabot 模块是否可导入，以及目标平台特有组件（例如执行 adb devices）。若预检失败，请立即停止并修复其输出的错误项 —— 不要继续执行，否则将调试一个未完全配置成功的运行环境。

一个解释器，一个事实来源。 预检仅验证唯一一个 Python 解释器；成功后，会打印其绝对路径（格式为 interpreter: ... 并附带一条可直接运行的命令行）。请始终使用该精确路径来运行你的脚本，切勿仅用裸命令 python —— 否则实际运行可能落入与预检所验证环境不同的另一个 Python 环境中（这是最常见的“已就绪”误判陷阱）。任何已可用的环境均可（如已有 venv、用户全局 Python），关键在于复用已通过验证的那个环境，而非强制新建 venv。

仅当预检报告缺失依赖时才启动引导流程。优先选择隔离的 venv，而非用户全局 Python（并务必使用该 venv 中的 Python 再次运行 preflight，使其成为经验证的解释器）：

# browser / iOS / desktop 可共用同一个 venv：
python3 -m venv .qira-venv && source .qira-venv/bin/activate   # Windows：.qira-venv\Scripts\activate
pip install "qirabot[browser]"      # → 同时安装：playwright install chromium
#   或  qirabot[appium]  （iOS：需额外部署 Appium server 与 WebDriverAgent） /  qirabot[desktop]

# airtest 后端（Android、iOS 及窗口级 Windows 桌面）需在 Python 3.10–3.12 上使用
# 专属 venv —— 因 airtest 锁定 numpy<2，共享环境将引发冲突：
python3.12 -m venv .qira-venv-airtest && source .qira-venv-airtest/bin/activate
pip install "qirabot[airtest]"

export QIRA_API_KEY="qk_..."        # 来自 https://app.qirabot.com

步骤 1 — 选定目标并从模板起步

复制对应模板，填写其中的 TODO（起始 URL / 应用包名，及具体任务描述），然后使用预检输出的解释器绝对路径（而非裸命令 python）运行脚本。templates/bolt_on.py 展示了“绑定现有 driver”的模式，以 Selenium 为可运行示例，并在注释中提供了 Appium（iOS/Android）、pyautogui（全屏桌面，跨操作系统）和 Airtest（窗口级 Windows 桌面）等变体；完整平台动作矩阵与 bind() 细节详见 references/REFERENCE.md。

步骤 2 — 将任务交由 qirabot 处理（默认方式），仅在需要优化时降级至底层原语

默认方式：将整个任务交由 bot.ai 处理。

from qirabot import StepResult

def on_step(step: StepResult) -> None:   # 实时追踪 → 输出到 stdout（见下文）
    label = "done" if step.finished else step.action_type
    print(f"  step {step.step}: {label} {step.params} — {step.decision}")

result = bot.ai(target, "将最便宜的商品加入购物车并结算",
                max_steps=15, on_step=on_step)
print(result.success, result.output)

bot.ai 将“感知 → 决策 → 执行”循环卸载给 qirabot，后者自主维护步骤历史并在某一步骤执行失败时自动恢复。

任务字符串应为简洁的目标陈述，而非分步脚本。 bot.ai 足够智能，能自行规划点击路径；过度指定（如“点击搜索框，输入 X，点击第一条结果，然后……”）会与模型对抗、固化脆弱路径、并额外消耗步骤。应描述成功状态是什么样，而非如何达成。良好示例："将库存中最便宜的商品加入购物车并结算"；不良示例：6 步逐点点击配方。

此处示例显式传入了 target（bot.ai(target, ...)）。若你已先通过 bind() 绑定了稳定 target（如 android.py 和 bolt_on.py 模板所示），则可省略首参数：bot.ai("...")、bot.click("...")。（Playwright 场景请保留显式形式，以确保新标签页跳转行为可见——详见 references/REFERENCE.md。）

务必始终传入 on_step。 在其返回前，bot.ai 是一个黑盒——result 仅在最终返回。而 on_step 在每一步执行后触发，将模型当前的 decision 与动作实时打印至 stdout，这是你观察运行过程的唯一实时窗口：卡死、循环或失败的运行可直接通过控制台日志定位问题，无需打开 HTML 报告。（StepResult 还包含 .output 及 token/耗时统计——详见 references/REFERENCE.md。）

仅在明确需要优化时，才主动降级至单步原语 —— 例如你需要严格、可复现的确定性行为，或正在将稳定流程编码为可重复运行的脚本（如 CI 回归检查）。这些原语单次操作成本更低且可复现，但对 UI 变更极为脆弱：

bot.click(target, "Login button")
bot.type_text(target, "Email field", "a@b.com", press_enter=True)
bot.double_click(target, "the file name to rename")                # 双击
bot.long_press(target, "the message bubble", duration=2.5)         # 移动端：长按唤起上下文菜单
bot.key_down(target, "w"); bot.key_up(target, "w")                 # 桌面端：按键按下/释放（成对使用）
text = bot.extract(target, "the displayed account balance")        # 读取单一值
bot.wait_for(target, "the dashboard finished loading")             # 设定等待门限，超时抛出异常

extract() 用于从屏幕读取值；verify() 返回布尔值，供脚本分支判断。关于 bot.ai 后何时选用哪个方法，请参见步骤 3。

完整 API 文档（构造函数选项、bind()、导航/滚动/键盘操作、各平台动作矩阵及错误类型）详见 references/REFERENCE.md。

步骤 3 — 根据使用者身份检查结果

每次运行均生成一份自包含 HTML 报告，含各步骤截图，保存至 ./qira_runs///report.html（除非显式设置 report=False）。bot.ai 返回后留下三个信号——请根据后续处理主体选择使用方式：

• 由人工或代理阅读结果 → 打开报告，查看各步骤截图。请勿信任 result.success：该字段由刚执行动作的同一模型生成，属于自我报告，可能在点击错误按钮后仍宣称成功。
• 脚本需基于结果进行分支判断（CI 门禁、if logged_in skip login、条件流程）→ 使用 bot.verify(target, "...")。此为独立视觉调用，返回 bool，消耗一次 AI 调用。该布尔值必须驱动后续逻辑——否则即为一次付费却无实际用途的调用，而截图已免费向人工审核者传达了相同信息。
• 脚本需读取某个值（价格、用户名、状态）→ 使用 bot.extract(target, "...")。注意避免定位歧义：extract("the logged-in username") 可能误抓搜索框的轮播提示词——请精炼定位短语，并结合截图交叉验证。

当运行失败（result.success=False，或截图明显异常）时，stdout 中的 on_step 追踪日志是最快的问题入口 —— 定位模型开始循环或选择错误动作的步骤，再跳转至报告中该步骤对应的截图。

在报告中嵌入屏幕录像。 报告会自动识别 bot.report_dir 目录下名为 recording.mp4 的文件，并将其作为 标签嵌入报告顶部（与步骤截图并列）——只需在 bot.close() 前将录像文件置于该路径即可：

• 桌面端 / 浏览器 → 让 SDK 为你录制主机屏幕：Qirabot(record=True)（或设置环境变量 QIRA_RECORD=1）将自动调用 ffmpeg 生成 recording.mp4，无需额外代码。
• Android / iOS（或任意原生框架） → 主机录制无法捕获设备画面，因此需使用设备自身录制器录制设备屏幕，并将录像写入 bot.report_dir/recording.mp4。请在 bot.ai 之前启动，在 bot.close() 之前停止（close 操作会扫描该文件）：
  • Airtest（Android）：device().start_recording(output=os.path.join(bot.report_dir, "recording.mp4"), max_time=1800)，随后在 finally 块中调用 device().stop_recording(output=...)。
  • Appium（iOS/Android）：driver.start_recording_screen()，然后将 base64.b64decode(driver.stop_recording_screen()) 写入同一路径。

详细说明请参阅 references/REFERENCE.md（record 行）。

注意事项

• 一次脚本运行 = 一次 Qirabot 会话 = 一个任务。状态（当前页面/驱动实例）无法跨多次 python 调用持久化，因此请将整个任务封装于单个脚本中。若需在多次运行间复用登录态，请以持久化用户资料目录启动：bot.open(url, user_data_dir=os.path.expanduser("~/.qira-profiles/"))（首次登录后，后续运行将自动认证——详见 references/REFERENCE.md）。注意：请传入绝对路径 —— qirabot/Playwright 不解析 ~，因此字面量 "~/..." 将在当前工作目录下创建 ./~/ 子目录。请使用 os.path.expanduser。
• 对不可逆或面向外部的操作（如发布评论、下单购买、删除数据），在用户身份下执行前务必确认：先采集/读取信息，清晰汇报即将执行的操作，获得用户明确授权后再执行。请将读取步骤与执行步骤严格分离。
• 每次 AI 调用均消耗真实积分。留意 InsufficientBalanceError 异常。通过 Qirabot(model_alias=...) 选择成本最低且满足需求的模型 —— fast/balanced 适用于简单流程，仅在必要时升级（层级详见 REFERENCE）。长时间人工介入等待（如 QR/OTP）若采用轮询将产生计费 AI 调用 —— 请增大 wait_for 的 interval 参数，或改用直接轮询 live driver（详见 REFERENCE）。
• bot.close()（或 with 语句形式）用于终结任务并生成报告 —— 即使发生错误也务必调用。