AScript 插件使用说明（适用于 Cursor / VS Code）

AScript 插件让你在 Cursor / VS Code 里，像在 IDE 一样，创建 AScript 工程、连接设备、在本机或手机上运行脚本。

1. 安装插件

1. 打开 VS Code / Cursor 的扩展市场。
2. 搜索 “AScript (ascript)”。
3. 点击安装，安装完成后重启编辑器。

安装完不需要额外配置就可以新建工程；运行时建议先确认 Python 和设备配置。

2. 创建一个 AScript 工程

1. 在 VS Code / Cursor 中按下 Ctrl+Shift+P（macOS：Cmd+Shift+P）。
2. 搜索并执行命令 “AScript: 新建 AScript 工程”。
3. 选择一个空文件夹作为工程目录。
4. 插件会自动生成：
   • build.as
   • main.py
   • res/ 资源目录等基础结构。

建议：新建好工程后，选择“在新窗口中打开该工程”，后续所有操作都在这个工程窗口中完成。

3. 配置本地 Python（仅 Windows 本地运行需要）

如果你打算在 Windows 本机上直接运行 AScript 工程，需要先指定 Python 路径：

1. 打开设置（Ctrl+,），搜索 “AScript”。
2. 将 AScript › Python Path 设置为 Python 3.9–3.13 的可执行文件，例如：
   • D:\Python\3.11\python.exe
   • 或 C:\Users\你\AppData\Local\Programs\Python\Python311\python.exe 等。
3. 保存后即可在本机运行 AScript 工程。

提醒：AScript 当前只支持 Python 3.9–3.13，请避免使用 3.8 或 3.14。

4. 打开 AScript 面板

1. 在左侧活动栏点击 AScript 图标。
2. 可以看到几个主要区域：

• 网站
  • 官网：https://ascript.cn/
  • 开发者后台：https://as.airscript.cn/
  • 云控：http://control.ascript.cn:8088/
  • 云数据库：http://mysql.nspirit.cn/
• 设备管理 / 设备列表（移动端工程）
  • 添加 / 编辑 / 删除 Android / iOS 设备。
  • 一键扫描局域网和 ADB 设备。
  • 在设备下可以看到：
    • “运行 / 停止”按钮
    • 控件检索、图色助手
    • ADB 终端、投屏等工具。

即使是 Windows 工程，“网站”分组也会一直存在，方便快速打开常用网址。

5. 为移动端工程选择运行设备

当工程中存在 build.as 时，会被识别为移动端工程，可以在手机 / 平板上运行脚本。

方式一：在编辑器右上角选择设备（推荐）

1. 打开工程中的 main.py 或其他 Python 文件。
2. 在编辑器右上角点击 手机图标：AScript: 选择运行设备。
3. 在弹出的列表中选择一台设备：
   • 如果之前已经选择过，会自动高亮当前工程绑定的设备。
4. 选择后，插件会记住该工程对应的设备，保存在 .vscode/settings.json 里。

方式二：在 AScript 面板中直接点击设备“运行”

1. 打开 AScript 面板。
2. 在“设备列表”下找到目标设备。
3. 鼠标移到设备这一行，点击右侧的绿色运行按钮（▶）即可在该设备上运行当前工程。

6. 运行 AScript 工程

6.1 在 Windows 本地运行

适用于 Windows 类型的 AScript 工程（只在电脑本机执行脚本）：

1. 打开工程中的 main.py。
2. 使用任一方式运行：
   • 编辑器右上角点击 “AScript: 运行”。
   • 或按快捷键 Ctrl+Shift+R。
3. 运行日志会出现在 “输出 (Output)” 面板中的 “AScript” 通道里。
4. 想停止运行：
   • 点击右上角的 “AScript: 停止” 按钮，或
   • 使用文件资源管理器顶部的停止按钮。

6.2 在 Android / iOS 设备上运行

适用于含 build.as 的移动端工程：

1. 确认 AScript 面板中已经有至少一台设备在线。
2. 打开 main.py（或工程主脚本）。
3. 运行方式同上：
   • 点击编辑器右上角 “AScript: 运行”，
   • 或按 Ctrl+Shift+R。
4. 插件会自动执行以下步骤：
   • 对比本地与设备上的文件，仅同步新增 / 修改的文件；
   • 调用设备 API 启动脚本；
   • 通过 WebSocket 接收日志并显示在 Output → “AScript” 中。
5. 再次按 Ctrl+Shift+R 或点击运行时：
   • 插件会先自动停止当前运行；
   • 然后重新同步并重新启动，实现“一键重新运行”。

7. 常用命令与快捷键

命令（命令面板中搜索）

• AScript: 新建 AScript 工程
• AScript: 选择运行设备
• AScript: 运行
• AScript: 停止
• AScript: 管理设备列表
• AScript: 扫描设备

快捷键（默认）

• 运行当前工程：Ctrl+Shift+R
  • 当前文件需为 AScript 工程中的 Python 文件。

8. 常见问题

• 看不到运行按钮 / AScript 面板为空？
  • 确认已经“以文件夹形式”打开工程根目录。
  • 确认工程中是否有 build.as 或正确的 .vscode/settings.json。
• 设备列表为空或无法连接？
  • 检查手机上是否已启动 AScript 应用，并与电脑在同一局域网，或通过 USB + ADB 连接。
  • 如需投屏 / ADB 终端，确保本机已经安装并配置好 ADB。
• Python 运行异常？
  • 在终端中执行 python --version 检查版本。
  • 确认 ascript.pythonPath 配置与实际版本一致，并在 3.9–3.13 范围内。

如果你是新用户，只需记住三个步骤：安装插件 → 新建工程 → 按 Ctrl+Shift+R 运行，其余功能（设备管理、投屏、控件检索等）可以在 AScript 面板中慢慢探索。