Appearance
AI Agent
ai 是 Aimaxbot 注入到脚本运行环境中的全局对象，用于让 AI 根据自然语言目标操作手机。
脚本中直接使用全局
ai对象，无需 import。
Agent API
ai.agent(goal, maxSteps)
让 AI 根据当前屏幕状态循环观察、决策和执行，直到完成、失败、停止或达到最大步数。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
goal | string | - | 要完成的自然语言目标 |
maxSteps | number | 12 | 最大执行步数，范围 1 到 30 |
javascript
let result = ai.agent("打开设置并进入 Wi-Fi 页面", 8);
log(result);返回值是 JSON 字符串：
json
{
"status": "completed",
"result": "已进入 Wi-Fi 页面"
}状态值：
| 状态 | 说明 |
|---|---|
completed | 任务完成 |
stopped | 任务被停止 |
failed | 模型返回错误或执行失败 |
max_steps_reached | 达到最大步数仍未完成 |
别名：
javascript
ai.run(goal, maxSteps);
ai.task(goal, maxSteps);ai.do(instruction)
执行一个短指令，内部最多执行 1 步 Agent 动作，适合简单操作。
javascript
let result = ai.do("返回桌面");
log(result);ai.doAction(instruction) 是 ai.do(instruction) 的别名。
ai.stopAgent()
请求停止当前 Agent。
javascript
ai.stopAgent();Action 能力总览
开发者通常只需要调用 ai.agent() 或 ai.do()，不需要手写 action。下面的表用于了解 Agent 当前能调用哪些能力，以及这些能力依赖无障碍还是 HID。
| Action | 能力来源 | 说明 |
|---|---|---|
click / tap | 无障碍优先，HID 兜底 | 点击节点或坐标 |
long_press / long_click | 无障碍优先，HID 兜底 | 长按节点或坐标 |
swipe | 无障碍优先，HID 兜底 | 坐标滑动 |
scroll / scroll_up / scroll_down | 无障碍优先，HID 兜底 | 滚动页面或可滚动节点 |
text_input / set_text | 无障碍优先，HID 兜底 | 输入文本 |
global_action | 无障碍，部分 HID 兜底 | back / home / recents 可 HID 兜底；notifications / quick_settings 仅无障碍 |
hid | HID | 直接执行 HID 点击、滑动、输入、返回、Home、按键 |
intent | 系统能力 | 启动应用、Activity、网页或设置页 |
screenshot / screen_capture | 系统能力 | 截图保存 |
download | 系统能力 | 使用 DownloadManager 下载文件 |
http_request | 网络能力 | 发起 HTTP 请求 |
camera | 系统能力 | 打开系统相机拍照或录像 |
screen_record | 系统能力 | 录屏开始、停止、状态查询 |
audio_record | 系统能力 | 录音开始、停止、状态查询 |
volume | 系统能力 | 音量设置、增减、静音、查询 |
wake_screen | 系统能力 | 保持屏幕唤醒 |
clipboard | 系统能力 | 读写剪贴板 |
dpm | Device Policy Manager | 锁屏、设备管控、权限、限制等企业设备能力 |
wait | 通用 | 等待一段时间 |
finish | 通用 | 标记任务完成 |
error | 通用 | 标记任务无法继续 |
能力分类
无障碍支持
无障碍适合读取控件树、定位节点、点击控件、输入文本和执行系统全局动作。
| Action | 说明 |
|---|---|
click / tap | 优先点击 node_id 对应控件，失败后可按坐标点击 |
long_press / long_click | 优先长按控件，失败后可按坐标长按 |
swipe | 坐标滑动 |
scroll / scroll_up / scroll_down | 滚动指定节点或页面中的可滚动节点 |
text_input / set_text | 优先 SET_TEXT，失败后尝试粘贴 |
global_action | 支持 back、home、recents、notifications、quick_settings |
HID 支持
HID 适合在无障碍节点不可用、WebView/游戏/图片区域较多、或需要模拟更接近真实触控时使用。
| Action | 说明 |
|---|---|
click / tap | 无障碍失败后可用 HID 点击坐标 |
long_press / long_click | 无障碍失败后可用 HID 长按坐标 |
swipe | 无障碍失败后可用 HID 滑动 |
scroll / scroll_up / scroll_down | 无障碍失败后可用 HID 滑动模拟滚动 |
text_input / set_text | 无障碍输入失败后可用 HID 文本输入 |
global_action | 仅 back、home、recents 支持 HID 兜底 |
hid | 直接调用 HID 能力：点击、滑动、输入、返回、Home、常用按键 |
通用能力
这些能力不依赖无障碍或 HID，但可能需要系统权限、屏幕捕获授权、网络权限或 Device Owner。
| Action | 说明 |
|---|---|
intent | 打开应用、Activity、网页、设置页 |
screenshot / screen_capture | 截图 |
download | 下载文件 |
http_request | HTTP 请求 |
camera | 打开系统相机 |
screen_record | 录屏 |
audio_record | 录音 |
volume | 音量控制 |
wake_screen | 保持屏幕唤醒 |
clipboard | 剪贴板 |
dpm | 设备管理能力 |
wait | 等待 |
finish | 完成 |
error | 失败 |
示例
让 AI 完成一个页面操作
javascript
let result = ai.agent("打开浏览器，搜索 Aimaxbot 官网", 10);
log(result);与普通脚本混合使用
javascript
app.launchPackage("com.android.chrome");
sleep(2000);
let result = ai.agent("在当前页面搜索 Aimaxbot 官网", 8);
log(result);简单动作
javascript
ai.do("返回上一页");
ai.do("点击屏幕上的确认按钮");