XScript MCP server
Commit Nov 15, 2026Enables AI clients to perform Android automation, image recognition, and device control using Python scripts and MCP-enabled API discovery.
Also known as JackLuguibin/xscript
- Stars
- 12
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 15, 2026
- License
- MIT
What is XScript MCP?
XScript enables AI clients to perform Android automation, image recognition, and device control using Python scripts and MCP-enabled API discovery.
Summary generated from the project's README
About XScript MCP server
Automating Android devices through Python scripting is what xscript enables for developers and testers. By connecting an AI client to an Android phone or emulator, users can execute complex tasks involving UI interaction, image recognition, and device control. The system uses a local Python runtime on the device and communicates with desktop tools via a developer address and pairing code.
Users can manage automation through a web-based IDE or specialized extensions for VS Code and Cursor. The server provides specific tools for visual intelligence, such as template matching, OCR, and integration with OpenAI-compatible vision models for screen analysis. It also supports advanced debugging features like breakpoints, variable inspection, and call stacks. For large-scale operations, a self-hosted management backend allows for device grouping, batch tasks, and remote screen monitoring using a PostgreSQL or SQLite database.
What you can do with it
- 1Automated UI InteractionAn AI client can perform clicks, swipes, and text input by querying Android UI elements.
- 2Visual Recognition TasksDevelopers can use template matching or OCR to identify specific images or text on the screen.
- 3Large-Scale Device ManagementTeams can manage multiple devices simultaneously through a centralized dashboard with remote control capabilities.
Written from the project's README. Every use case is checked against a quote from it.
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablejackluguibin/xscript is public and reachablegithub.com/jackluguibin/xscript ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/jackluguibin/xscript ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubXScript
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.6.0 下载 xscript-v0.6.0-release.apk,adb install 或拷到手机上点开安装。v0.2.1–v0.2.3 正式版可直接覆盖升级;装过 Debug 版的设备要先卸载(会清除应用数据)。
2. 授权:首次打开先允许 通知(否则开发服务不会启动),再按需开启 辅助权限管理(无障碍,点击和控件操作要用)、悬浮窗权限、图色权限(截图)。
3. 在手机上管理和运行小程序:
| 首页 | 小程序列表 | 小程序详情 |
|---|---|---|
| 开发者地址、配对码、权限状态,一键运行上次的小程序 | 新建 / 导入,点进某个小程序 | 运行 / 日志、开机自启、停止后重新运行、定时任务 |
| 查看代码 | 运行日志 | 定时任务 |
| 详情页点文件即可查看和简单修改 | print 输出实时显示,可 停止 / 清空 |
每天定时、每隔 N 分钟、只运行一次 |
| 配对码 | 新建(模板) | |
| 首页「配对码」:电脑端首次连接时输入,可重新生成;USB 连接的桌面客户端自动配对 | 七个模板,与网页 IDE、VS Code 插件的「新建工程」相同 |
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。第一次打开会要求输入手机首页的 配对码。

-
新建 工程时可选模板(空工程、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. 运行与调试示例
连不上手机时按连不上手机怎么办逐项检查,更多连接说明见入门指南,断点与调试生命周期见调试说明。
脚本示例
每个工程是一个 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
.venv-rt/bin/python -m pip install numpy==1.23.3 opencv-python-headless==4.5.4.60 pillow==11.0.0 pyyaml==6.0.3 requests==2.33.1 packaging==24.2 # 与手机上内置的版本一致(opencv 4.5.1.48 没有 3.10 的 wheel,用 4.5.4.60)
# Web 控制台与编辑器扩展(Node 22+,见 .nvmrc)
(cd backend/web && npm ci)
(cd ide/vscode-extension && npm ci)
# 桌面端(可选;没有时 verify.sh 跳过这一步)
python3.10 -m venv .venv-desktop
.venv-desktop/bin/python -m pip install -e './desktop/app[test]'
(cd desktop/frontend && npm ci)
# 仓库检查与 Android JVM 测试
./scripts/verify.sh
./android/build.sh :app:testDebugUnitTest
verify.sh 覆盖 Python 运行时、后台、MCP、类型存根、网页 IDE、编辑器扩展、桌面端(装了 .venv-desktop 时)及 mock 集成流程。完整设备行为需要另外连接手机或模拟器验证。
修改公共 Python API 后重新生成类型存根:
python3 scripts/gen_stubs.py
python3 scripts/gen_completions.py # 网页 IDE 的补全索引
python3 scripts/gen_editor_docs.py # 网页 IDE 的悬停文档和参数提示(来自 ide/python-stubs,先跑 gen_stubs)
设备调试回归测试会创建并清理自己的临时工程,执行前应确保没有其他脚本正在运行:
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;原始 HID 硬件通道和完整 V4 加密脚本运行(自带输入法、外部 APK/JAR 插件加载、BLE 和按次卡已经实现,见功能对照)。网页 IDE 的工程内搜索只做文本匹配(没有替换预览;撤销替换只保留最近一次、一步),截图面板只截取静态一帧;补全和语法检查都是轻量的本地实现:补全覆盖 xscript.* / ascript.* 和文件内的名字,不做类型推断;语法检查按 Python 3.10 语法只报第一个错误,基本检查只报能确定的问题,没有完整的类型检查,不能替代运行;调试功能不如完整 IDE 齐全。管理后台的卡密已支持续期叠加、体验卡、多设备卡、滥用告警(统计窗口写入数据库,重启不丢)、App 内续期、按设备黑名单、按次卡(每次启动脚本扣一次)和代理账号(额度内只管理自己生成的卡,见后端说明)。VS Code / Cursor 扩展已打成 vsix,并装进真实 VS Code(隔离配置)在扩展宿主里验证(激活、全部命令、活动栏视图、调试类型、快捷键、运行 / 停止 / 拉取 / 截图),一键调试以及条件 / 命中次数断点、日志点、修改变量用适配器脚本在两台模拟器上实测通过;但没有用鼠标在编辑器调试界面里点完整一轮(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 服务默认需要配对码(App 首页「开发与连接 → 配对码」):桌面端、VS Code 扩展、MCP 和浏览器开发工具首次连接时输入一次,USB 连接的桌面端自动配对。设备还会拒绝跨站请求和非 IP 的 Host(防 DNS 重绑定)。配对码走明文 HTTP,请使用可信网络或 USB/ADB 转发,不要把开发端口暴露到公网。可以在 App 里关闭配对(与 AScript 一样开放),此时任何能访问端口的客户端都能上传和执行代码。打包应用默认关闭开发服务。仓库里 scripts/device_*.py 这类设备脚本先读 XSCRIPT_TOKEN,没有就通过 adb 自动取配对码。
APK 内置的 Pillow 为 11.0.0、requests 为 2.33.1(旧版 Pillow 9.2.0 / requests 2.32.3 有已公开的安全问题,例如 Pillow 的 ImageMath.eval 任意代码执行 CVE-2023-50447、requests 的 .netrc 凭据泄露 CVE-2024-47081)。Pillow 10 删掉的旧写法(Image.ANTIALIAS、textsize、getsize)由运行时补回,AScript 时代的脚本不用改。
自托管后台的公网部署应配置 HTTPS/WSS,并保护设备密钥、管理员凭据和签名私钥。App 通过 Authorization 请求头发送设备密钥,状态和设置接口里只显示 token=***;自写客户端也请用请求头,不要把密钥放进 URL(见云控协议)。部署与备份要求见后台说明。报告问题时不要附带这些凭据或个人设备数据。
许可证与第三方组件
XScript 以 MIT 许可证 开源,Copyright (c) 2026 Jack Lu (JackLuguibin)。第三方组件的许可证和条款分别适用。
依赖信息见 THIRD_PARTY_NOTICES.md;随包提供的 debugpy wheel 来源与许可证见 android/wheels/README.md。