获取指定平台(android/ios/windows)的 API 模块概览，包含模块名、描述、类和函数列表。

获取指定模块的完整 API 文档，支持模糊匹配。例如 'screen' 可匹配 'ascript.windows.screen'。返回函数签名、参数说明和文档。

按关键词搜索 API，覆盖函数名、类名和文档说明。当不确定功能在哪个模块时使用。

获取常见自动化任务的可运行代码示例。

获取指定平台的环境搭建和安装指南。

从当前 AScript 工程目录自动连接设备。 读取 .vscode/settings.json 中的 ascript.deviceId 和 ascript.platform，自动连接对应设备。 VSCode 插件创建工程时会保存这些信息，无需用户手动输入 IP。 传入当前工程的根目录路径即可。

扫描发现所有 AirScript 设备。 同时执行：1) 局域网扫描（WiFi 连接的 Android/iOS 设备）2) ADB 扫描（USB 连接的 Android 设备）。 返回所有发现的设备列表。

连接 Android/iOS 设备。连接后才能使用截图、控件树等设备工具。 局域网设备传 IP，ADB 设备传序列号并设 connection_mode='ADB'。

一次性获取设备当前状态：截图 + 控件树，比分开调用更快。 返回截图（PNG 图片）和控件树（Android JSON / iOS XML）。 【重要】拿到控件树后，编写代码必须优先使用控件选择器（通过 text/id/className 等属性定位并操作控件），只有控件树中确实找不到目标元素时才用坐标点击。

一步完成开发验证循环：上传代码 → 运行 → 收集日志 → 截图验证。 代码会上传为 init.py（入口文件），工程不存在时自动创建。 返回上传结果、运行结果、日志内容和运行后截图。

截取设备当前屏幕。返回 PNG 图片。用于查看设备当前界面状态。

获取设备当前界面的控件树（UI 层级结构）。返回所有控件的 id、text、desc、className、rect、clickable 等属性。

【Android】调用前必须先调 get_device_status 确认 run_mode，再选对应 mode，否则拿空树：

• run_mode.code=accessibility（无障碍模式）→ mode=0/1（简单/复杂），或 2/3（过滤系统层变种）

• run_mode.code=root（Root 或激活模式） → mode=9（root 控件）

• run_mode.code=hid（HID 控件 / 辅助控件模式）→ mode=6（辅助控件）

• run_mode.code=screen_only（图色模式） → 无控件树，跳过 dump，走 OCR/找图 ⚠ Android 命名陷阱：code="hid" 实际是 ASS 枚举（辅助控件，有控件树）；code="screen_only" 才是图色模式（无控件树）。 Selector 实例化要传相同的 mode：node.Selector(mode=<dump 的 mode>)。

【iOS】只有 WebDriverAgent 一套引擎，不接 mode 参数（传了被忽略），返回 WDA XML。iOS Selector() 也不接 engine mode；它的 MODE_EQUAL/CONTAINS/MATCHES 是给单个条件的匹配运算符（如 selector.text("x", mode=MODE_CONTAINS)），别和 Android 混。

【写 selector 必看】控件树里有 text/id/desc/className 等属性的元素，必须用 node.Selector() 通过属性定位操作，不要用坐标点击。坐标只用于控件树中确实没有任何可识别属性的元素。 Selector 实例化时也要传相同的 mode：node.Selector(mode=<dump 的同一个 mode>)。

在设备上实时测试 Selector 选择器，验证是否能精准匹配到目标控件。 传入过滤条件（text/id/type/desc/clickable），返回匹配到的控件及其完整属性。 用于编写代码前验证 node.Selector().text('xxx').find() 等语句是否能定位到正确控件。 条件可组合使用，如同时指定 text 和 clickable。

在设备屏幕上执行 OCR 文字识别。返回识别到的文字、位置坐标和置信度。

多点找色：在屏幕上查找符合颜色条件的坐标。 colors 格式：'x,y,#RRGGBB|x,y,#RRGGBB|...'，第一个点为锚点，后续为偏移点。 可选带偏差色：'x,y,#RRGGBB-#偏差|...'

多点比色：检查屏幕指定位置的颜色是否匹配。 返回布尔值。用于判断界面状态。

在设备上创建新工程。上传文件前需要先创建工程。

列出设备 AScript App 内已安装的 Python 第三方库（Android + iOS）。 AI 在写脚本（尤其是 eval_python 片段）前强烈建议先调用，确认要 import 的 lib 在该设备上可用。

Android: 走 /api/status 的 python.packages（importlib.metadata 实时查询）。 iOS: 借 eval_python 跑 importlib.metadata 实时列出。

常见自带库：opencv-python-headless / numpy / pillow / requests / pandas / openpyxl / pymysql / websockets / cryptography 等，具体清单随 App 版本和用户安装的插件而变化，以本工具实时返回为准。

获取设备完整运行状态（仅 Android）。一次性返回：

• device: 品牌/型号/ABI

• system: Android 版本/SDK/语言/时区

• screen: 分辨率/dpi/方向

• battery / network / storage / memory

• permissions: 全部权限授权状态

• run_mode: 当前运行模式（root / accessibility / screen_only / hid）— 决定可用的 API 集

• runtime: 是否正在跑脚本、当前工程名

• tools: 已安装工具配置

强烈建议生成脚本前先调用：根据 run_mode 选择 API（如 node.find 仅在 accessibility 模式可用），根据 permissions 决定是否需要先申请权限，根据 runtime.is_script_running 避免互踩。

列出设备上的所有工程。

在设备上运行指定工程。

停止设备上正在运行的工程。

在设备主进程的 Python 上下文中直接 exec 任意代码，立即返回结果（Android + iOS）。 几百毫秒一轮，不需要 upload_file/run_project，适合：

• 探索性调试：试 selector / 找图 / OCR / 找色 / 一次点击

• 复合决策：把'看屏幕→判断→点击'打包一段 Python 一次执行

• 自动裁模板、SoM 标注、智能 tap 路由

• 任意一次性同步 API 调用：action.click / slide / Selector(任何 mode) / Permission / KeyValue / Sms / Clipboard 等

Android 主进程 client 已本地 stub 化（App.java onCreate 时 bindClient），所有原本走 :py 进程 IPC 的 API 现在 eval 里也能直接调。

⛔ 红线：eval 代码无法外部中断！HTTP 60s 超时只断客户端连接，服务端 Python 仍在跑直到自然返回；卡住 = 整个 App UI 冻住。所有循环必须 range/deadline 限定， sleep ≤ 5s，try/except 整段。超过 30s 的逻辑改用 upload + run_project（可被 stop_project kill）。

⚠ 仍需谨慎的场景：

• 长循环 / 耗时 > 30s：用 upload+run_project

• 回调注册（event.on / sensor.on）：register 能调用，但 eval 返回时 _result 已定，回调触发的数据拿不回 — 持续监听必须用 upload+run_project

• 长 session（cloud_control 连云、ESP32 BLE HID 持久会话）：建议用工程模式

完整指南见 docs/AGENT_EVAL_GUIDE.md。

代码必须把结果赋给 _result 全局变量。返回值约定：

• 简单字符串：_result = 'ok'

• 结构化数据（推荐）：_result = json.dumps({'found': True, 'x': 320})

• 含截图返回：_result = json.dumps({'data': {...}, 'image_base64': '...'}) （MCP 自动识别 image_base64 字段并以图片形式返回给 AI 多模态查看）

image_path 非空时 App 会注入 _im_source 全局变量指向该图片路径； iOS 上若代码中引用 img 变量，会被预读为 cv2 ndarray。

跨平台：iOS 端会自动把 ascript.android. 替换为 ascript.ios.， 并预加载 cv2 / np / Image (PIL) 到执行环境，常用片段几乎无需修改。 完整 API 参见 search_api / get_module_apis（按 platform 选择）。

以调试模式启动 Android 工程，让脚本可被 VS Code / Cursor 通过 debugpy attach 调试。 前提：1) 平台为 Android（iOS 不支持）；2) 设备必须通过 ADB 连接（USB / adb tcpip）。 行为：自动 adb forward tcp:5678 → 设备 127.0.0.1:5678 + 调用设备 /api/model/run?debug=1，设备端 :py 进程进入 listen+wait_for_client 阻塞，等待 IDE attach。 返回：本地端口、可直接粘贴到 .vscode/launch.json 的 attach 配置片段、操作提示。 用户在 VS Code 按 F5 attach 后，业务从 main 开始运行，断点会被命中。 停止调试请调用 stop_project（同时停止业务和调试器）。

获取设备运行日志（实时收集指定秒数）。 用于查看脚本运行输出、错误信息和 print 内容。 建议在 run_project 后调用，查看脚本是否正常运行或有报错。

查询 AScript 在线插件库，返回所有可用插件列表。 插件提供额外能力：OCR（TomatoOcr）、YOLO 目标检测、HID 硬件控制、AI 大模型、蓝牙通信等。 按下载量排序，包含插件名、作者、描述。

获取指定插件的详细文档，包括 API 说明、参数、代码示例和版本历史。 需要先用 list_plugins 查到插件 id。

获取设备上指定工程的文件树结构。

上传文件到设备上的指定工程。content 为文件内容的 base64 编码。