XScript

English | 简体中文

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

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

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

使用说明 · 可靠性、安全与性能 · 快速开始 · 脚本示例 · 开发与测试 · 文档 · 贡献

主要功能

• Android 自动化：无障碍与 Root 操作通道，支持点击、滑动、多点手势、按键、文字输入、控件选择器和 XPath 查询，以及 WebWindow 网页控件选择器（WebSelector）。
• 图像与视觉识别：截图、取色、找色（RGB / HSV / Lab 色彩空间、色块、主色）、模板匹配（含多尺度，以及 method="auto" / "feature" 的 ORB/SIFT 特征点找图，可找缩放、旋转后的目标）、OCR、图片字库与点阵字库（Ocr.matrix）、AI 识屏（screen.ai_find / ai_ask，接任意 OpenAI 兼容视觉模型）与 AI 智能体（agent.run("目标")，自动看屏幕操作直到完成）、OpenCV 图像处理、GP 图色流水线（含工程自带图色插件），以及基于 ONNX Runtime 的 YOLO 和 PaddleOCR 推理（PP-OCRv4 / v5 / v6，screen.ocr(engine="paddle_v6t") 或 "auto"）。
• 脚本开发与调试：浏览器多文件编辑、保存运行、日志、断点（桌面端支持条件断点、命中次数、日志点和监视表达式）、单步、调用栈和变量查看；提供 VS Code / Cursor 扩展、MCP 服务和 Python 类型存根。
• 设备服务：权限申请、短信只读查询、定位、传感器、事件监听、通知、剪贴板、KeyValue 存储和 HTML/悬浮界面。
• 工程与运行管理：工程导入导出、运行时安装 Python 依赖、开机运行、定时任务、异常重启控制，以及链接启动（xscript://，兼容 AScript 的 ascript://run?local=…）。
• 自托管管理后台：设备分组、批量任务、远程操作、屏幕墙、日志、告警、账号角色和操作审计；概览页有每日激活、在线设备、新设备和到期的趋势图；「AI 写脚本」在后台描述任务，用自己配置的 OpenAI 兼容模型生成小程序代码，保存为版本后下发到设备测试。数据默认存在 SQLite 文件里，设备多时可改用 PostgreSQL（可选）。
• 桌面端云控：桌面客户端的「云控」页用 API 令牌连接管理后台，批量运行、看实时画面和日志、编辑定时任务、把流程部署到分组并回滚，按后台角色灰显（说明）。
• 桌面端安装与更新：macOS dmg 和 Windows 安装包，设置里检查、下载并安装签名的新版本，导出脱敏的诊断包（说明）。
• 应用分发：脚本版本发布与回滚、独立 APK 打包（默认在后台本机打包，也可以交给单独的打包机，在后台添加和查看打包机状态）、签名更新和激活码授权管理。

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

可靠性、安全与性能

脚本运行更稳

• 模板匹配的 confidence 填 0 或负数不会再让脚本卡死，会自动限制在 0.01–1 之间。
• 等待类接口可以调整轮询间隔：screen.ocr_wait、Selector.find / find_all / exists / wait_gone 和 event.loop 都支持 interval=，默认值不变。最后一次等待会在到点前截短，不会超过 timeout；计时用单调时钟，系统改时间不影响等待。

密钥不外泄

• App 连接云控时把设备密钥放进 Authorization: Bearer 请求头，不再拼在地址里，所以服务端和反向代理的访问日志里看不到密钥。旧式 ?token= 仍然可用，日志里显示为 token=***。
• 设备上的云控状态、上报给服务端的设备信息和 GET /settings 里的云控地址，都把密钥显示为 token=***。
• 已登录的账号修改密码或开关两步验证时，错误次数同样受限：同一账号失败 5 次后锁定 5 分钟，换会话也一样。
• 公共接口的限流在并发请求下准确生效；伪造签名的授权令牌会按 IP 限流。

后台能撑更多设备

• 设备状态帧和 cloud.send() 数据不再逐条写库，而是每 15 秒合并写一次。控制台看到的在线状态和数据仍然是实时的。
• 概览页的统计更省：卡密用一次查询统计完，崩溃记录在数据库里筛选，页面每 15 秒刷新。分组列表只读需要的字段，运行日志按设备建了索引，导出运行日志改为流式输出，内存占用不随行数增长。
• 定时任务最多 4 个并发执行，慢任务不再拖住同一轮的其他任务。
• 登录校验和接口共用同一个数据库会话，系统设置缓存 5 秒。
• 在线设备超过 SQLite 的参数上限（3 万余台）时，按在线状态筛选和按分组下发仍然可用。
• 可选用 PostgreSQL 代替默认的 SQLite：设置 XSCRIPT_DATABASE_URL 即可，表结构自动创建和升级；已有的 SQLite 数据通过备份 / 恢复迁移过去。CI 在后端代码有改动时用 PostgreSQL 16 再跑一遍后端测试。

界面更省资源

• 网页控制台切到后台标签页后，屏幕墙、日志跟随和打包日志暂停轮询，切回来从断点继续。
• 桌面端屏幕墙等每台设备的上一张截图返回后才请求下一张，失败时退避，窗口隐藏时暂停。
• 桌面端窗口很窄时，局域网连接一行自动换行，不再出现横向滚动条。

开发与 CI

• Web 控制台有 vitest + Testing Library 单元测试，CI 和 scripts/verify.sh 都会运行；几个大页面拆分成独立组件。
• verify.sh 也会检查桌面端；桌面端排版测试使用固定的测试字体，结果不随机器上安装的字体变化。开发需要 Node 22+。
• CI 的运行时测试使用手机内置的库版本（numpy 1.23.3、Pillow 11.0.0 等；scripts/tests/test_phone_pins.py 防止和 APK 不一致），运行时和后台各有覆盖率下限（78% / 82%，分支覆盖）。后台 + MCP 和运行时两个任务也按改动的路径决定是否运行，只改文档或界面的 PR 不会跑它们。
• CI 缓存 npm / pip 依赖；Dependabot 每周提交 GitHub Actions、npm 和 pip 依赖的更新 PR。
• 修掉了三个偶发失败的测试，都找到了原因，不靠重跑：桌面端测试偶发段错误（QtWebEngine 的原生线程打日志时撞上 pytest-qt 正在替换的 Python 日志回调，现已关闭 pytest-qt 的 Qt 日志捕获）；投屏测试偶发除零（换帧时图片尺寸短暂为 0，测试改为一次读取已解码的帧）；Chrome 启动重试测试在机器繁忙时误报（改为在启动时计数）。

完整变化见更新记录。

使用说明

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

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

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

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

| 首页 | 小程序列表 | 小程序详情 | | :---: | :---: | :---: | | <img src="docs/images/phone-home.png" width="220" alt="首页：当前小程序、开发者地址、配对码、AI 编程和云控连接状态、各项权限"> | <img src="docs/images/phone-projects.png" width="220" alt="小程序列表：四个示例小程序，右上角新建、导入"> | <img src="docs/images/phone-project.png" width="220" alt="小程序详情：运行、日志、权限检查、开机自启、定时任务、文件"> | | 开发者地址、配对码、权限状态，一键运行上次的小程序 | 新建 / 导入，点进某个小程序 | 运行 / 日志、开机自启、停止后重新运行、定时任务 | | 查看代码 | 运行日志 | 定时任务 | | <img src="docs/images/phone-editor.png" width="220" alt="手机上查看和修改 __init__.py"> | <img src="docs/images/phone-run-log.png" width="220" alt="运行日志：print 输出实时显示，可停止、清空"> | <img src="docs/images/phone-schedule.png" width="220" alt="添加定时任务：每天定时、每隔 N 分钟、只运行一次"> | | 详情页点文件即可查看和简单修改 | print 输出实时显示，可 停止 / 清空 | 每天定时、每隔 N 分钟、只运行一次 | | 配对码 | 新建（模板） | | | <img src="docs/images/phone-pairing.png" width="220" alt="配对码弹窗：电脑首次连接时输入的配对码，可重新生成、复制或关闭"> | <img src="docs/images/phone-templates.png" width="220" alt="新建小程序：填名称并选择模板（空白、Hello、AScript 风格、每日签到、找图、OCR、悬浮窗界面）"> | | | 首页「配对码」：电脑端首次连接时输入，可重新生成；USB 连接的桌面客户端自动配对 | 七个模板，与网页 IDE、VS Code 插件的「新建工程」相同 | |

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

<img src="docs/images/phone-floating.png" width="240" alt="在别的 App 上方显示的悬浮窗：展开后有停止、日志、打开、隐藏四个按钮">

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

• 新建 工程时可选模板（空工程、Hello、AScript 兼容、签到、找图点击、OCR 读数、悬浮窗 UI，手机 App 的「新建」也一样）；新建文件 / 文件夹：文件路径如 utils/net.py，默认放在目录树选中的文件夹里；目录树用法同 VS Code。

• ⌘/Ctrl+S 保存，保存并运行（F6）在手机上运行，停止（Shift+F6）结束；保存并调试 支持断点、单步和变量查看。

• 删除文件：入口 __init__.py 不能删，文件夹要先清空。右上角可切换深色主题。

• 写代码时的帮助：API 补全（Ctrl+空格）、参数提示（Ctrl+Shift+空格）、悬停文档和推断类型；跳转到定义（F12 / Ctrl+点击）、查找引用（Shift+F12）、重命名符号（F2，跨文件）；本地语法检查，以及基本检查：未定义的名字和拼错的属性 / 关键字参数 / import（提示「是不是 …」）、调用参数不对、async / await 用错、重复定义，未使用的 import / 变量和执行不到的代码变淡。很多提示可以把光标放上去按 Ctrl+.（Mac 上 ⌘.）一键修复，可撤销。VS Code 扩展的「问题」面板显示同一套基本检查。详见使用手册。

  

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 官方扩展的逐项对照、没做的功能见插件说明。

PyCharm 插件

习惯 PyCharm 的话，用 ide/pycharm-plugin（PyCharm 2024.2+）：Tools → XScript 里上传运行（Ctrl+Alt+Shift+R）、停止、在设备上运行选中代码（Ctrl+Alt+Shift+E）、从设备拉取工程，底部 XScript 工具窗口看实时日志；新建工程模板和补全存根与 VS Code 插件相同。还没有断点调试。安装包从 CI 产物下载或自己构建，见插件说明。

更多说明（快捷键、错误提示、图色和标注工具、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/。初始化过程会提示创建管理员账号。容器部署、设备密钥、存储、备份和改用 PostgreSQL 见后台说明。

编辑器与 MCP

• IDE 工具说明：安装 VS Code / Cursor 扩展，上传工程并查看日志。
• Trae：Trae 直接安装同一个 vsix 扩展，并按相同 JSON 配置 MCP。
• MCP 服务说明：为支持 MCP 的客户端配置设备访问；get_coding_rules 提供 XScript 编码规则，get_module_apis / search_api 提供 API 目录，方便 AI 生成和检查符合规则的代码。
• 类型存根：配置 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
.ve