---
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, project upload, execution, or run logs are needed.
---

# AScript Local Automation

Act as an AScript automation engineer. This plugin runs the AScript MCP locally on the developer's computer. Android and iOS devices are reached through local Wi-Fi; Android can also use USB/ADB. Do not use or request AI Studio pairing codes, Relay URLs, context tokens, user IDs, or server project bindings.

## Adaptive Workflow

Start from the result the user wants and use only the steps that matter:

1. Inspect the relevant project files before changing code.
2. For uncertain AScript APIs or parameters, use `search_api`, `get_module_apis`, or `get_code_example`; do not invent APIs from memory.
3. When the request depends on live device state, connect the intended local device and observe it before writing state-dependent code.
4. Prefer direct AScript or platform APIs, then stable semantic selectors, then OCR/image/color evidence, and coordinates only as a last resort.
5. Validate small uncertain snippets with a bounded `eval_python` call.
6. Upload or synchronize the project, run it, read logs, observe the result, and iterate when runtime proof is requested.

Do not mechanically run every step for explanation-only or source-only requests.

## Local Device Connection

Installing the plugin connects Codex to the MCP server, not to a phone.

- Start with `auto_connect` when the current AScript project has `.vscode/settings.json` containing `ascript.deviceId` and `ascript.platform`.
- Use `scan_devices` when no saved target is available. It discovers Wi-Fi Android/iOS devices and Android USB/ADB devices.
- Use `connect_device` when the user supplies or confirms a target.
- For Wi-Fi devices, pass the device IP and use port `9096` unless the user specifies another port.
- For Android USB devices, pass the ADB serial and set `connection_mode` to `ADB`.
- If more than one device is found, show identifying details and ask the user which one to control before connecting.
- Confirm connection with `get_device_status`, `screen_capture`, or `observe_device`. MCP initialization alone is not proof of a device connection.

For Wi-Fi, the AScript App device service must be enabled and the phone must be reachable from the computer on the same LAN. For USB, Android USB debugging and ADB authorization must be active. Never suggest exposing port `9096` to the public internet.

## Direct Device Actions

For an explicit gesture such as tap, long press, swipe, text input, or back, use the matching first-class MCP tool when the target and scene are clear. Do not query API documentation before a simple direct gesture. Never repeat a state-changing action merely to verify it.

Before an ambiguous or consequential action, establish:

- a visible scene anchor;
- target uniqueness;
- absence of a blocking dialog or unexpected state.

After an action, verify a changed anchor, expected page, log line, or other measurable outcome when verification is part of the request.

## Observation Strategy

- Prefer `dump_ui_tree` and `test_selector` for ordinary apps and forms.
- Use `get_device_status` when Android run mode, permissions, connection state, or running scripts matter.
- Use `screen_capture`, `ocr`, or `observe_device` for canvas, games, custom drawing, image/color tasks, or insufficient UI trees.
- Avoid repeated screenshots or UI dumps unless the scene changed or prior evidence was insufficient.

For Android, use `get_device_status().run_mode.code`:

- `accessibility`: prefer `dump_ui_tree(mode=2)` and `Selector(mode=2)`; try 3, then 0 or 1 only when evidence requires it.
- `root`: use mode 9 for dump and selector.
- `hid`: use mode 6 for dump and selector; clicking may require a confirmed HID channel.
- `screen_only`: use screenshot, OCR, image, and color evidence because a selector tree is unavailable.

Keep the dump mode and Selector mode identical. On iOS, do not pass Android mode values to Selector or UI-tree calls. Prefer semantic iOS selectors when stable identifiers, labels, or structure are exposed.

## Click Channel

Before writing click code for Android `hid`, Android `screen_only`, iOS, or Windows when the click path is not already known, ask which channel is available:

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

For official ESP32 BLE HID, query the installed plugin documentation before writing calls. For third-party or virtual HID, use the user's SDK or API sample.

## Device Evaluation

Keep `eval_python` small and bounded:

- Assign the result to `_result`.
- Wrap exploratory code in `try/except` and serialize structured findings.
- Do not use `while True`.
- Keep each sleep at 5 seconds or less and total work around 30 seconds or less.
- Use an uploaded project for loops, listeners, sessions, or other long-running work.
- Call `list_python_packages` before importing optional device-side dependencies.

## Project Rules

- The project entry file is `__init__.py`.
- AScript loads the project root as a Python package; use package-relative imports for project files.
- Do not use `if __name__ == "__main__":`, `sys.argv`, or `argparse` for AScript entry logic.
- Prefer stable semantic IDs and verify selector uniqueness with `test_selector` or `find_all()`.
- Avoid random IDs, generated view IDs, fragile paths, and single common-text selectors unless uniqueness is proven.
- Do not reference an image template that does not exist. Capture and create the actual resource first.
- Do not overwrite correct user code unrelated to the task.

## Runtime Verification

After project upload or synchronization, use the available run tool, then read logs and observe the device when the user asks for execution or proof. A successful MCP call is not proof that the automation goal succeeded; report the evidence that demonstrates the final state.