XScript

面向 Android 的 Python 自动化开发平台。

XScript 将设备端 Python 运行时、自动化 API、浏览器开发工具和可自托管的管理后台组合在一起。你可以在电脑上编写脚本，将工程上传到手机或模拟器，执行控件操作、图像识别和设备任务，并通过日志与断点调试定位问题。

项目提供原生 xscript.android.* API，以及覆盖部分 AScript 公共接口的 ascript.android.* 兼容层。XScript 是独立项目，与 AScript 无隶属关系。

使用说明 · 快速开始 · 脚本示例 · 开发与测试 · 文档 · 贡献

主要功能

• Android 自动化：无障碍与 Root 操作通道，支持点击、滑动、多点手势、按键、文字输入、控件选择器和 XPath 查询。
• 图像与视觉识别：截图、取色、找色、模板匹配、OCR、OpenCV 图像处理、GP 图色流水线，以及基于 ONNX Runtime 的 YOLO 和 PaddleOCR 推理。
• 脚本开发与调试：浏览器多文件编辑、保存运行、日志、断点、单步、调用栈和变量查看；提供 VS Code / Cursor 扩展、MCP 服务和 Python 类型存根。
• 设备服务：权限申请、短信只读查询、定位、传感器、事件监听、通知、剪贴板、KeyValue 存储和 HTML/悬浮界面。
• 工程与运行管理：工程导入导出、运行时安装 Python 依赖、开机运行、定时任务和异常重启控制。
• 自托管管理后台：设备分组、批量任务、远程操作、屏幕墙、日志、告警、账号角色和操作审计。
• 应用分发：脚本版本发布与回滚、独立 APK 打包、签名更新和激活码授权管理。

视觉 AI 客户端支持显式配置自有推理服务；项目不包含视觉大模型服务。YOLO 模型由使用者提供，具体模型与第三方依赖的授权见第三方声明。

使用说明

不想自己构建时，直接用发布好的安装包，只需要一台 Android 8.0+ 手机或模拟器和一台电脑。

1. 安装 App：从 GitHub Release v0.2.6 下载 xscript-v0.2.6-release.apk，adb install 或拷到手机上点开安装。v0.2.1–v0.2.3 正式版可直接覆盖升级；装过 Debug 版的设备要先卸载（会清除应用数据）。

2. 授权：首次打开先允许 通知（否则开发服务不会启动），再按需开启 辅助权限管理（无障碍，点击和控件操作要用）、悬浮窗权限、图色权限（截图）。

3. 在手机上管理和运行小程序：

首页	小程序列表	小程序详情
开发者地址、权限状态，一键运行上次的小程序	新建 / 导入，点进某个小程序	运行 / 日志、开机自启、停止后重新运行、定时任务
查看代码	运行日志	定时任务
详情页点文件即可查看和简单修改	print 输出实时显示，可 停止 / 清空	每天定时、每隔 N 分钟、只运行一次

4. 后台悬浮窗：脚本运行时把 XScript 切到后台，屏幕边上会出现一个悬浮窗（绿点 + 工程名 + 已运行时间），几秒不碰就缩成半透明小球；拖动会带缓动吸附到左右边（避开状态栏和导航条）并记住位置，横竖屏各一份；点一下展开 停止 / 日志 / 打开 / 隐藏（图标在上、小字在下，随深浅色换配色）和脚本用 FloatWindow.add_menu 加的按钮，不用回到 App 就能停脚本；脚本出错结束时会标红保留几秒。首页 悬浮窗显示 可选 运行时显示（默认）/ 后台一直显示 / 已关闭，需要 悬浮窗权限，没授权时不显示也不影响运行。回到 App 或脚本结束就收起。

5. 在电脑上写脚本：首页 开发者地址 就是电脑要访问的地址。同一局域网直接打开 http://<开发者地址>/tools/；USB 或模拟器先 adb forward tcp:19860 tcp:9860，再打开 http://127.0.0.1:19860/tools/，进入 脚本 IDE。

• 新建 工程 / 文件 / 文件夹：文件路径如 utils/net.py，默认放在目录树选中的文件夹里；目录树用法同 VS Code。
• ⌘/Ctrl+S 保存，保存并运行（F6）在手机上运行，停止（Shift+F6）结束；保存并调试 支持断点、单步和变量查看。
• 删除文件：入口 __init__.py 不能删，文件夹要先清空。右上角可切换深色主题。

VS Code 插件

不想用网页 IDE 时，可以在 VS Code（或 Cursor）里写脚本：从 GitHub Release 下载 xscript-vscode-<版本>.vsix（版本号和 App 相同，校验值在 SHA256SUMS），然后 code --install-extension xscript-vscode-<版本>.vsix（v0.2.4 及更早的 Release 没有 vsix，可以先按插件说明自己打包）。装好后左侧活动栏出现 XScript 图标：

• 设备：扫描设备（ADB 和局域网）或 添加设备 填 App 里的开发者地址；点设备即设为当前设备。
• 运行：打开 __init__.py，按 Ctrl+Shift+R（或编辑器右上角 ▶）：只把改动的文件同步到手机并运行，日志实时输出；再按一次先停止再重新运行，Shift+F6 停止。.vscode/.syncignore 控制哪些文件不上传。
• 新建工程、从手机 拉取工程、截图、ADB 终端、投屏也在这个视图里。

和 AScript 官方扩展的逐项对照、没做的功能见插件说明。

更多说明（快捷键、错误提示、图色和标注工具、VS Code 插件、管理后台）见使用手册。

项目结构

xscript/
├── android/       Android 应用、设备端 Python 运行时与测试
├── backend/       FastAPI 管理服务、React 控制台与 APK 打包工具
├── ide/           VS Code / Cursor 扩展、MCP 服务与类型存根
├── protocol/      设备 HTTP API 的 OpenAPI 契约
├── examples/      自动化、设备服务、图色与调试示例
├── scripts/       验证、存根生成与设备测试脚本
├── deploy/        容器部署配置
└── docs/          使用、接口、架构与部署文档

设备端可以独立使用，管理后台按需部署。电脑端工具通过设备 HTTP API 连接应用；云控采用设备主动建立的 WebSocket 连接。

环境要求

• 运行设备：Android 8.0 / API 26 或更高版本的手机或模拟器；4KB 和 16KB 内存页面的设备都支持（16KB 页面设备靠清单里的 pageSizeCompat 兼容模式，已在 Android 17 模拟器验证，详见 功能对照）。
• Android 构建：JDK 17+、Android SDK Platform 37 与相应 Build Tools、Python 3.10，以及 Bash 环境。Gradle 通过仓库自带 wrapper 执行。
• 可选管理后台：Python 3.10+；构建 Web 控制台需要 Node.js 与 npm。
• Python 版本：管理后台、MCP 服务和构建机统一要求 Python 3.10+，设备上内置的是 Python 3.10（Chaquopy），ide/python-stubs 类型存根 3.8 起即可使用。
• 可选 IDE 工具：MCP 服务需要 Python 3.10+；编辑器扩展需要 VS Code 1.90+ 或兼容的 Cursor。

构建脚本默认尝试使用 Android Studio 自带 JBR，并查找 Python 3.10。可以通过 JAVA_HOME、ANDROID_HOME 和 XSCRIPT_BUILD_PYTHON 指定本机安装路径。其他构建细节见 Android 开发说明。

快速开始

1. 获取源码并构建

git clone https://github.com/JackLuguibin/xscript.git
cd xscript
./android/build.sh

调试 APK 输出到：

android/app/build/outputs/apk/debug/app-debug.apk

2. 安装并启动

确认设备已连接 ADB，然后安装：

adb devices
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

如果设备上装过用其他签名打包的 XScript（例如正式版，或别的电脑打的 Debug 包），adb install -r 会报 INSTALL_FAILED_UPDATE_INCOMPATIBLE。只能先 adb uninstall com.xscript.app 再安装，卸载会清除应用数据（工程、设置、授权），请先导出需要的工程。

在设备上打开 XScript，首次安装后先授予通知权限，否则 HTTP 服务不会启动；再根据使用的功能开启无障碍、悬浮窗或截图权限。Root 为可选通道，不是所有功能的前提。短信、定位和通知等功能需要各自的系统授权。

3. 连接开发工具

应用首页显示开发者地址。默认端口为 9860，被占用时依次尝试至 9869，请以设备实际显示为准。

通过 USB 或 Android Studio 模拟器连接时，可以转发端口：

adb forward tcp:19860 tcp:9860
curl http://127.0.0.1:19860/status

如果连接了多个设备，为 ADB 命令增加 -s <设备序列号>；如果设备端端口不是 9860，相应调整转发目标。

在浏览器打开 http://127.0.0.1:19860/tools/，进入脚本 IDE，新建工程，编辑 __init__.py，保存并运行。脚本 IDE 的目录树、文件管理和快捷键见使用手册。

4. 运行与调试示例

• 基础自动化：通过控件查找完成操作。
• 断点调试：设置行断点，观察变量并单步执行。
• 设备服务：短信权限、定位与传感器示例。
• GP 流水线：本地图像处理任务编排。
• 自有视觉服务：配置 VLM 客户端。

详细连接排查见入门指南，断点与调试生命周期见调试说明。

脚本示例

每个工程是一个 Python 包，入口为 __init__.py。运行时的工作目录为工程目录。

from xscript.android import node

button = node.Selector().text("搜索").find(timeout=5)
if button:
    button.click()
else:
    print("当前界面未找到搜索控件")

工程可以包含 Python 子模块、资源文件和 requirements.txt。第三方依赖是否可用取决于其 Python 版本与 Android 平台支持，并非所有桌面 Python 包都能在设备端安装。

迁移 AScript 工程时，可以使用 ascript.android.* 兼容入口；部分接口仍存在行为差异或尚未实现，请先阅读功能对照和兼容实现说明。

可选组件

管理后台

在独立 Python 3.10+ 环境中安装并初始化：

python3.10 -m venv .venv
.venv/bin/python -m pip install -e ./backend
(cd backend/web && npm ci && npm run build)
.venv/bin/python -m xscript_server init --data xscript-data
.venv/bin/python -m xscript_server serve --data xscript-data --port 8765

访问 http://127.0.0.1:8765/。初始化过程会提示创建管理员账号。容器部署、设备密钥、存储和备份见后台说明。

编辑器与 MCP

• IDE 工具说明：安装 VS Code / Cursor 扩展，上传工程并查看日志。
• MCP 服务说明：为支持 MCP 的客户端配置设备访问。
• 类型存根：配置 xscript.* 与 ascript.* 自动补全。

开发与测试

Python 后台/MCP 测试和设备端运行时测试使用独立环境：

# 后台与 MCP
python3.10 -m venv .venv
.venv/bin/python -m pip install -e './backend[test]' -e ./ide/mcp-server

# 设备端 API 的本机测试
python3.10 -m venv .venv-rt
.venv-rt/bin/python -m pip install numpy==1.26.4 opencv-python-headless==4.10.0.84 pillow==10.4.0

# Web 控制台与编辑器扩展
(cd backend/web && npm ci)
(cd ide/vscode-extension && npm ci)

# 仓库检查与 Android JVM 测试
./scripts/verify.sh
./android/build.sh :app:testDebugUnitTest

verify.sh 覆盖 Python 运行时、后台、MCP、类型存根、网页 IDE、编辑器扩展及 mock 集成流程。完整设备行为需要另外连接手机或模拟器验证。

修改公共 Python API 后重新生成类型存根：

python3 scripts/gen_stubs.py
python3 scripts/gen_completions.py   # 网页 IDE 的补全索引

设备调试回归测试会创建并清理自己的临时工程，执行前应确保没有其他脚本正在运行：

python3 scripts/device_debug_smoke.py --base http://127.0.0.1:19860
# 截图权限（模拟器上自动点系统授权对话框）和 /screen 缩放检查
scripts/emulator_grant_capture.sh emulator-5554
python3 scripts/device_screen_smoke.py http://127.0.0.1:19860

当前状态与限制

项目持续开发中。基本 DAP 调试、短信查询和加速度传感器回调已在 ARM64 Android 17 / API 37 模拟器上验证；不同设备、ROM 和权限策略仍可能影响实际行为。

以下能力尚未完整实现：APK 强制更新在 App 内下载后交给系统安装程序，需要用户允许「安装未知应用」，没有静默安装；更新前打的旧包没有服务器地址，需要重新打包一次才会读公告；登录 IP 白名单在反向代理后面需要 --behind-proxy；独立输入法、外部 Java 插件加载、原始 HID 硬件通道、通用 BLE，以及完整 V4 加密脚本运行。网页 IDE 的工程内搜索只做文本匹配（没有替换预览；撤销替换只保留最近一次、一步），截图面板只截取静态一帧；补全和语法检查都是轻量的本地实现：补全覆盖 xscript.* / ascript.* 和文件内的名字，不做类型推断；语法检查只抓常见的括号、引号、冒号和缩进错误，不能替代运行；没有悬停提示、跳转定义、重构和完整 IDE 的全部调试功能。管理后台的卡密已支持续期叠加、体验卡、多设备卡、滥用告警（统计窗口写入数据库，重启不丢）、App 内续期和按设备黑名单，但没有按次卡。VS Code / Cursor 扩展已打成 vsix，并在 Cursor 里加载验证（激活、11 条命令、调试类型、快捷键），一键调试以及条件 / 命中次数断点、日志点、修改变量用适配器脚本在两台模拟器上实测通过；但没有用鼠标在编辑器调试界面里点完整一轮（Cursor 无头宿主里不能驱动调试 UI）。具体范围见功能对照。

文档

• 使用手册：各组件的使用入口。
• 入门指南：构建、连接设备和常见问题。
• 脚本 API：设备端接口。
• 断点调试：网页调试与 DAP API。
• 云控协议：设备连接与指令转发。
• 打包与授权：独立 APK、更新与激活码。
• 发布流程：推 tag 由 GitHub Actions 构建签名 APK 和 VS Code 插件并发布 Release；CI 覆盖范围。
• 技术架构：模块与运行流程。
• 设备 HTTP 契约：客户端和设备共用的 API 定义。
• 路线图：后续规划。
• 更新记录：各版本面向用户的变化。

贡献

欢迎通过 Issues 报告问题、提出建议，或提交 Pull Request。

报告问题时请提供 Android 版本、设备/模拟器型号、复现步骤和相关日志；提交代码时请保持改动范围清晰，补充必要的测试与文档，并通过对应检查。

提交信息采用 Conventional Commits，例如：

feat(vision): add a new image-processing operation
fix(android): handle service disconnection
docs: improve setup instructions

安全说明

设备开发 HTTP 服务没有鉴权，能够访问端口的客户端可以上传和执行代码。请使用可信网络或 USB/ADB 转发，避免将开发端口直接暴露到公网。打包应用默认关闭开发服务。

自托管后台的公网部署应配置 HTTPS/WSS，并保护设备密钥、管理员凭据和签名私钥。部署与备份要求见后台说明。报告问题时不要附带这些凭据或个人设备数据。

许可证与第三方组件

XScript 以 MIT 许可证 开源，Copyright (c) 2026 Jack Lu (JackLuguibin)。第三方组件的许可证和条款分别适用。

依赖信息见 THIRD_PARTY_NOTICES.md；随包提供的 debugpy wheel 来源与许可证见 android/wheels/README.md。