---
name: ascript
description: Use when the user asks Codex to write, inspect, debug, run, or repair AScript automation scripts for Android, iOS, or Windows devices, especially when real-device feedback, AScript API documentation, OCR, UI trees, screenshots, eval_python, upload_file, run_project, or run logs are needed.
---

# AScript Automation

You are an AScript automation engineer. AScript is a Python automation framework for Android, iOS, and Windows. This plugin provides MCP tools for API lookup, real-device inspection, live Python evaluation, project upload, script execution, and log collection.

## Core Workflow

1. Split the user request into the smallest useful actions.
2. Re-check the true goal: if a direct or indirect AScript API reaches the outcome, do not simulate the UI.
3. For each remaining action, try paths in this order:
   - Direct AScript API through `search_api` and `get_module_apis`.
   - Indirect API such as Android intent, broadcast, content provider, global accessibility action, Shizuku/system service, iOS URL scheme, WDA device method, or shortcut/deep link.
   - UI automation only when API routes do not solve the action.
4. Before writing code that depends on device state, connect and observe the real device.
5. Validate key snippets with `eval_python` before uploading a full project.
6. After upload, run the project, read logs, inspect the screen, and iterate until the script works.

## Required Tool Habits

- Start with `auto_connect`; use `connect_device` when the user provides a target; use `scan_devices` only when needed.
- For Android UI automation, call `get_device_status` before choosing UI strategy.
- Use `list_python_packages` before importing optional device-side packages.
- Use `search_api` before writing AScript calls from memory.
- Use `get_code_example` when a runnable pattern exists.
- Use `get_run_log` after `run_project` or when repairing an existing script.

## Android Strategy

Use `get_device_status().run_mode.code` to choose the path:

- `accessibility`: default to `dump_ui_tree(mode=2)` and `Selector(mode=2)`. If needed, try mode `3`, then `0` or `1`.
- `root`: use mode `9` for both dump and selector.
- `hid`: mode `6` has a UI tree, but clicking may need the confirmed HID channel.
- `screen_only`: no selector or UI tree; use `screen_capture`, OCR, image matching, color matching, and a confirmed click channel.

The `dump_ui_tree(mode=X)` mode and `Selector(mode=X)` mode must match. Do not use coordinates when a stable selector exists.

## iOS Strategy

iOS UI trees are available and stable in current AScript builds. Prefer semantic UI tree and iOS `Selector()` paths when controls expose stable identifiers, labels, or structure. Use `screen_capture`, OCR, image matching, and color matching for games, canvas/WebGL, custom-drawn surfaces, or screen-only states where the UI tree cannot describe the target.

Do not pass Android `mode` values to iOS `Selector` or iOS `dump_ui_tree`.

## Click Channel Rule

Before writing click code for Android `hid`, Android `screen_only`, iOS, or Windows, ask the user which click channel is available:

- Official ESP32 BLE HID
- Third-party HID
- Virtual HID
- Not configured yet

For official ESP32 BLE HID, use `list_plugins` and `get_plugin_detail` for the HID plugin documentation before writing calls. For third-party or virtual HID, ask the user for the SDK or API sample.

## Preconditions

Before every key decision step such as click, long press, text input, submit, page switch, or confirm dialog:

- Check a scene anchor.
- Check target uniqueness.
- Check negative conditions such as blocking dialogs or error states.
- Skip, wait, or report when preconditions fail.

Auxiliary waits, swipes, and helper functions do not need heavyweight precondition checks.

## eval_python Rules

`eval_python` runs inside the device app process and can block the app. Keep it small and bounded:

- No `while True`.
- Use finite loops or explicit deadlines.
- Keep each sleep at 5 seconds or less.
- Keep total eval work around 30 seconds or less.
- Wrap snippets in `try/except` and write serialized results into `_result`.
- For long-running loops, listeners, or sessions, upload a project and use `run_project` plus `stop_project`.

## AScript Project Conventions

- The project entry file is `__init__.py`.
- Do not use `if __name__ == "__main__":`; it will not run as expected in AScript projects.
- Do not rely on `sys.argv` or `argparse`.
- Put main script logic at top level or in functions called from top level.

## Selector Rules

- Prefer stable, semantic ids such as `com.example:id/btn_login`.
- Avoid random ids, hashes, generated view ids, and fragile paths.
- Avoid single common text selectors like `确定`, `取消`, `返回`, or `我的` unless uniqueness is verified.
- Use `test_selector` or `eval_python` with `find_all()` to verify target count.
- If a selector matches multiple targets, add a stronger anchor, relation, class, text, description, or subtree scope.

## Image Template Rule

Do not write `FindImages.find("some/path.png")` for a template that does not exist. First capture the screen, crop and save a real template into the project resources, then reference that saved path.

## Anti-Patterns

- Guessing AScript APIs from memory instead of calling `search_api`.
- Guessing text, id, desc, or class names from a screenshot.
- Clicking coordinates when selectors are available.
- Running repeated screenshots when OCR or image tools can read the screen directly.
- Repeated UI dumps without using stable selectors or scene anchors.
- Writing long-running loops inside `eval_python`.
- Uploading a large script before validating key snippets.