$shellHttp - Shell HTTP 命令
更新: 2026/3/2 字数: 0 字 时长: 0 分钟
$shellHttp 模块通过 HTTP 服务提供系统级控制能力,支持 Shell命令执行、触控操作、按键模拟、屏幕截图、文本输入 等功能,具备 高权限、高稳定性和后台运行能力,支持 开机自启和后台自恢复,是 Bot.js Pro 实现高级自动化控制的核心模块之一。
核心优势
- 高权限:超越普通 ADB 和 Shizuku 的权限等级
- 稳定性:支持开机自启和后台自恢复
- 全面性:集成 Shell 命令、触控、截图等多种功能
- 跨设备:支持 WiFi、USB 等多种连接方式
$shellHttp 适合需要高权限和稳定性的复杂自动化场景。
服务启动方式
在使用 $shellHttp 之前,必须先在 被控设备 启动服务。
目前支持以下四种启动方式:
WiFi 无线调试
推荐的服务启动方式,无需 USB 数据线,只需设备开启无线调试(5555端口),即可通过 WiFi 网络启动 $shellHttp 服务。
适用于:
- 模拟器
- 云手机
- 主板机
- Android 真机
- HarmonyOS 真机
支持情况说明
不同设备对无线调试端口(5555)的支持情况如下:
| 设备类型 | 说明 |
|---|---|
| 模拟器 | 通常默认开启无线调试(5555端口) |
| 云手机 | 大多数默认开启无线调试(5555端口),部分设备已 Root |
| 主板机 | 通常默认开启无线调试(5555端口) |
| Android 12+ 真机 | 可直接开启无线调试(5555端口),需通过配对码配对 |
| Android 11 及以下真机 | 需使用电脑开启无线调试(5555端口) |
| HarmonyOS 真机 | 需使用电脑开启无线调试(5555端口) |
| Root 真机 | 可通过 Root 权限直接开启无线调试(5555端口) |
视频教程待补充……
OTG-USB 调试
适用于:
- Android 真机
- HarmonyOS 真机
视频教程待补充……
Shizuku
设备安装并启动 Shizuku 后,授予 Bot.js Pro 应用 Shizuku 权限,即可通过 Shizuku 启动 $shellHttp 服务。
视频教程待补充……
Root
设备授予 Bot.js Pro 应用 Root 权限 后,即可直接启动 $shellHttp 服务。
视频教程待补充……
初始化与连接管理
$shellHttp.init([port])
port{number} 可选,服务端口号,默认9124- 无返回值
初始化 ShellHttp 服务连接,建立 HTTP 通信通道,所有操作前必须先执行初始化。
$shellHttp.init(); // 使用默认端口 9124$shellHttp.init(9124); // 指定端口号$shellHttp.version()
- 返回 {number} 服务版本号,最新版为
1
获取 ShellHttp 服务版本号,用于兼容性检查。
var version = $shellHttp.version();
console.log("ShellHttp 版本号: ", version);$shellHttp.state()
- 返回 {boolean} 服务运行状态
检查 ShellHttp 服务是否正在运行,确保通信通道正常。
var isRunning = $shellHttp.state();
console.log("ShellHttp 服务状态: ", isRunning);$shellHttp.restart()
- 返回 {boolean}
通过 ShellHttp 服务重启自身,用于服务异常恢复。
var ok = $shellHttp.restart();
if (ok) {
console.log("shellHttp 重启成功");
} else {
console.error("shellHttp 重启失败");
}$shellHttp.stopService()
- 无返回值
停止 ShellHttp 服务。
$shellHttp.destroy()
- 无返回值
销毁 ShellHttp 资源,脚本结束前建议执行。
$shellHttp.destroy();Shell 命令执行
$shellHttp.exec(command)
command{string} 要执行的 Shell 命令字符串返回 {object} 包含执行结果的 JSON 对象,其属性如下:
- code {number} 返回码。执行成功时为0,失败时为非0的数字。
- result {string} 运行结果(stdout输出结果)
- error {string} 运行的错误信息(stderr输出结果)。例如执行需要root权限的命令但没有授予root权限会返回错误信息"Permission denied"。
执行 Shell 命令,支持单命令和分号分隔的多命令。
单命令执行
var result = $shellHttp.exec("echo 'Hello ShellHttp'");
console.log("命令执行结果: ", result);// 截屏
var result = $shellHttp.exec("screencap -p /sdcard/screen.png");
console.log("命令执行结果: ", result);多命令组合执行
// 截图后生成布局节点文件
var result = $shellHttp.exec("screencap -p /sdcard/screenshot.png ; uiautomator dump /sdcard/window_dump.xml");
console.log("多命令执行结果: ", result);$shellHttp.saveWindowXml()
- 返回 {boolean} 保存成功返回
true,失败返回false
转储当前活动窗口 XML 布局信息到 /sdcard/window_dump.xml。
var saveResult = $shellHttp.saveWindowXml();
console.log("XML布局保存结果: ", saveResult);系统按键操作
$shellHttp.home()
- 返回 {boolean}
模拟按下主页键,返回设备主屏幕。
var homeResult = $shellHttp.home();
console.log("按下主页键: ", homeResult);$shellHttp.back()
- 返回 {boolean}
模拟按下返回键,返回上一个页面。
var backResult = $shellHttp.back();
console.log("按下返回键: ", backResult);$shellHttp.recents()
- 返回 {boolean}
模拟按下最近任务键,打开后台任务列表。
var recentResult = $shellHttp.recents();
console.log("打开最近任务: ", recentResult);$shellHttp.powerDialog()
- 返回 {boolean}
长按电源键弹出电源菜单。
var powerDialogResult = $shellHttp.powerDialog();
console.log("弹出电源菜单: ", powerDialogResult);$shellHttp.power()
- 返回 {boolean}
按下电源键,实现锁屏/亮屏切换。
var powerResult = $shellHttp.power();
console.log("按下电源键: ", powerResult);$shellHttp.notifications()
- 返回 {boolean}
下拉通知栏。
var notificationsResult = $shellHttp.notifications();
console.log("下拉通知栏: ", notificationsResult);$shellHttp.quickSettings()
- 返回 {boolean}
打开快速设置面板。
var quickSettingsResult = $shellHttp.quickSettings();
console.log("打开快速设置: ", quickSettingsResult);$shellHttp.volumeUp()
- 返回 {boolean}
音量增加一级。
var volumeUpResult = $shellHttp.volumeUp();
console.log("音量增加: ", volumeUpResult);$shellHttp.volumeDown()
- 返回 {boolean}
音量减少一级。
var volumeDownResult = $shellHttp.volumeDown();
console.log("音量减少: ", volumeDownResult);屏幕截图操作
$shellHttp.captureScreen()
- 返回 {Image}
通过 ShellHttp 服务截图并返回 Image 对象。
var img = $shellHttp.captureScreen();
console.log("截图对象: ", img);
img.saveTo("/sdcard/test.png");
img.recycle();$shellHttp.captureScreen(path)
path{string} 截图保存路径- 返回 {boolean}
通过 ShellHttp 服务截图并保存到指定路径。
var saveResult = $shellHttp.captureScreen("/sdcard/screen_test.png");
console.log("截图保存结果: ", saveResult);文本操作
$shellHttp.setSelection()
- 返回 {boolean}
全选当前页面文本/内容。
var setSelectionResult = $shellHttp.setSelection();
console.log("全选内容: ", setSelectionResult);$shellHttp.copy()
- 返回 {boolean}
复制选中文本到剪贴板。
var copyResult = $shellHttp.copy();
console.log("复制内容: ", copyResult);$shellHttp.paste()
- 返回 {boolean}
粘贴剪贴板内容到当前焦点位置(支持中文)。
setClip("这是要粘贴的中文内容");
var pasteResult = $shellHttp.paste();
console.log("粘贴内容: ", pasteResult);$shellHttp.cut()
- 返回 {boolean}
剪切选中文本到剪贴板。
var cutResult = $shellHttp.cut();
console.log("剪切内容: ", cutResult);$shellHttp.input(text)
text{string} 要输入的文本内容- 返回 {boolean}
模拟键盘输入文本。
var inputResult = $shellHttp.input("hello123");
console.log("输入文本: ", inputResult);中文输入
- 剪贴板+粘贴方案(推荐):
setClip("你好世界");
sleep(500)
$shellHttp.paste();$input输入法(复杂场景):
$input.setText("你好世界");$shellHttp.enter()
- 返回 {boolean}
模拟按下回车键,适用于搜索、确认、换行等场景。
var enterResult = $shellHttp.enter();
console.log("按下回车键: ", enterResult);$shellHttp.delete([count])
count{number} 可选,删除的字符数,默认1- 返回 {boolean}
模拟删除键,删除光标后方字符。
var deleteSingle = $shellHttp.delete();
console.log("删除1个字符: ", deleteSingle);
var deleteMultiple = $shellHttp.delete(3);
console.log("删除3个字符: ", deleteMultiple);$shellHttp.backspace([count])
count{number} 可选,退格的字符数,默认1- 返回 {boolean}
模拟退格键,删除光标前方字符。
var backspaceSingle = $shellHttp.backspace();
console.log("退格1个字符: ", backspaceSingle);
var backspaceMultiple = $shellHttp.backspace(5);
console.log("退格5个字符: ", backspaceMultiple);键盘按键操作
$shellHttp.keyPress(code[, modifier])
code{number} 按键对应的原生键码modifier{number} 可选,修饰键码,用于组合键- 返回 {boolean}
模拟按下并释放指定键码或组合键。
单键操作
var keyPressResult = $shellHttp.keyPress(187); // 任务键
console.log("按下任务键: ", keyPressResult);组合键操作
var comboResult = $shellHttp.keyPress(android.view.KeyEvent.KEYCODE_A, android.view.KeyEvent.KEYCODE_CTRL_LEFT);
console.log("Ctrl+A 全选: ", comboResult);$shellHttp.keyLongPress(code[, duration])
code{number} 按键对应的原生键码duration{number} 可选,长按时间(毫秒),默认1000- 返回 {boolean}
模拟长按指定键码。
var longPressResult = $shellHttp.keyLongPress(26); // 长按电源键
console.log("长按电源键: ", longPressResult);var customLongPress = $shellHttp.keyLongPress(26, 2000); // 长按2秒
console.log("自定义时长长按: ", customLongPress);键码查看
console.log(android.view.KeyEvent); // 查看所有键码常量触控操作
$shellHttp.click(x, y)
x{number} 触控点横坐标y{number} 触控点纵坐标- 返回 {boolean}
模拟单击操作,点击指定坐标位置。
var clickResult = $shellHttp.click(500, 1000);
console.log("点击坐标: ", clickResult);$shellHttp.longClick(x, y)
x{number} 触控点横坐标y{number} 触控点纵坐标- 返回 {boolean}
模拟长按操作,长按指定坐标位置。
var longClickResult = $shellHttp.longClick(500, 1000);
console.log("长按坐标: ", longClickResult);$shellHttp.press(x, y, duration)
x{number} 触控点横坐标y{number} 触控点纵坐标duration{number} 按住时长(毫秒)- 返回 {boolean}
自定义按住操作,按住指定坐标并保持指定时长。
var pressResult = $shellHttp.press(600, 900, 1000);
console.log("按住坐标: ", pressResult);$shellHttp.touchDown(x, y[, id])
x{number} 触控点横坐标y{number} 触控点纵坐标id{number} 可选,触控点ID(多触点时区分),默认0- 返回 {boolean}
模拟触控按下,手指按下指定坐标。
$shellHttp.touchMove(x, y[, id])
x{number} 移动后的横坐标y{number} 移动后的纵坐标id{number} 可选,触控点ID,默认0- 返回 {boolean}
模拟触控移动,手指在按下状态下移动到指定坐标。
$shellHttp.touchUp([id])
id{number} 可选,触控点ID,默认0- 返回 {boolean}
模拟触控抬起,手指从按下状态抬起。
按下→抬起实现模拟点击示例
// 按下→休息200毫秒→抬起
$shellHttp.touchDown(200, 500);
sleep(200);
$shellHttp.touchUp()按下→移动→抬起实现自定义轨迹的滑动示例
// 按下→移动→抬起
$shellHttp.touchDown(200, 500);
sleep(200);
$shellHttp.touchMove(250, 550);
sleep(200);
$shellHttp.touchMove(300, 550);
sleep(200);
$shellHttp.touchMove(350, 550);
sleep(200);
$shellHttp.touchMove(500, 550);
sleep(100);
$shellHttp.touchUp();$shellHttp.releaseTouch()
- 返回 {boolean}
释放所有触控点,清空触控状态。
$shellHttp.releaseTouch();多指触控示例
var width = device.width;
var height = device.height;
console.log("屏幕尺寸: ", width + "x" + height);
/* 带 ID 的多点触控 部分手机不兼容 */
/** 🖐️ 手指1(ID=1)从左侧中部向右滑动 */
console.log("手指1按下(ID=1):", $shellHttp.touchDown(width / 4, height / 2, 1));
sleep(200);
/** 🖐️ 手指2(ID=2)从右侧中部向左滑动 */
console.log("手指2按下(ID=2):", $shellHttp.touchDown(width * 3 / 4, height / 2, 2));
sleep(200);
/** 🖐️ 手指3(ID=3)从上方中间向下滑动 */
console.log("手指3按下(ID=3):", $shellHttp.touchDown(width / 2, height / 4, 3));
sleep(200);
/** 🖐️ 手指4(ID=4)从下方中间向上滑动 */
console.log("手指4按下(ID=4):", $shellHttp.touchDown(width / 2, height * 3 / 4, 4));
sleep(200);
/** 🖐️ 手指5(ID=5)左下角往右上 */
console.log("手指5按下(ID=5):", $shellHttp.touchDown(width / 4, height * 3 / 4, 5));
sleep(200);
/** 🖐️ 手指6(ID=6)右上角往左下 */
console.log("手指6按下(ID=6):", $shellHttp.touchDown(width * 3 / 4, height / 4, 6));
sleep(200);
/** 多指同时移动 */
for (var i = 0; i < 5; i++) {
var delta = i * 30; // 每步偏移量
console.log("手指1移动:", $shellHttp.touchMove(width / 4 + delta, height / 2, 1));
console.log("手指2移动:", $shellHttp.touchMove(width * 3 / 4 - delta, height / 2, 2));
console.log("手指3移动:", $shellHttp.touchMove(width / 2, height / 4 + delta, 3));
console.log("手指4移动:", $shellHttp.touchMove(width / 2, height * 3 / 4 - delta, 4));
console.log("手指5移动:", $shellHttp.touchMove(width / 4 + delta, height * 3 / 4 - delta, 5));
console.log("手指6移动:", $shellHttp.touchMove(width * 3 / 4 - delta, height / 4 + delta - 100, 6));
sleep(800);
}
/** 抬起所有手指 */
for (var id = 1; id <= 6; id++) {
console.log(`手指${id}抬起:`, $shellHttp.touchUp(id));
sleep(300);
}
console.log("✅ 六指触控测试完成");多指触控兼容性
- 部分设备或 ROM 不支持带 ID 的多点触控 API
- 建议先在目标设备上验证兼容性
- 若不支持可降级为两指/三指操作
$shellHttp.swipe(x1, y1, x2, y2, duration)
x1{number} 滑动起点横坐标y1{number} 滑动起点纵坐标x2{number} 滑动终点横坐标y2{number} 滑动终点纵坐标duration{number} 滑动总时长(毫秒)- 返回 {boolean}
基础自定义滑动,指定起点、终点和时长。
$shellHttp.swipe(100, 800, 900, 800, 500);$shellHttp.swipe(x1, y1, x2, y2, steps, downTime, duration, upTime)
x1/y1{number} 滑动起点坐标x2/y2{number} 滑动终点坐标steps{number} 滑动步数(步数越多越平滑)downTime{number} 按下后延时(毫秒)duration{number} 滑动核心时长(毫秒)upTime{number} 抬起前延时(毫秒)- 返回 {boolean}
高级自定义滑动,精细控制滑动的平滑度和时间点。
$shellHttp.swipe(200, 500, 600, 500, 50, 200, 2000, 200);$shellHttp.swipe(x1, y1, x2, y2, steps, downTime, duration, upTime, shape)
shape{number} 滑动曲线形状(0-6,不同数值对应不同速度曲线)- 其余参数同「高级自定义滑动」
- 返回 {boolean}
曲线滑动,模拟真人滑动的非匀速效果。
$shellHttp.swipe(200, 500, 600, 500, 50, 200, 2000, 200, 2);$shellHttp.swipeUp([width, height])
width{number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地device.widthheight{number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地device.height- 返回 {boolean}
模拟向上滑动操作,起点位于屏幕底部,终点位于屏幕上方,自动适配指定或本地屏幕尺寸。
基础滑动(使用本地屏幕尺寸)
$shellHttp.swipeUp();自定义屏幕尺寸滑动
$shellHttp.swipeUp(device.width, device.height);$shellHttp.swipeDown([width, height])
width{number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地device.widthheight{number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地device.height- 返回 {boolean}
模拟向下滑动操作,起点位于屏幕上方,终点位于屏幕底部,自动适配指定或本地屏幕尺寸。
$shellHttp.swipeLeft([width, height])
width{number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地device.widthheight{number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地device.height- 返回 {boolean}
模拟向左滑动操作,起点位于屏幕右侧,终点位于屏幕左侧,自动适配指定或本地屏幕尺寸。
$shellHttp.swipeRight([width, height])
width{number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地device.widthheight{number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地device.height- 返回 {boolean}
模拟向右滑动操作,起点位于屏幕左侧,终点位于屏幕右侧,自动适配指定或本地屏幕尺寸。
$shellHttp.zoomIn(x, y, stride)
x{number} 缩放中心横坐标y{number} 缩放中心纵坐标stride{number} 缩放步长(步长越大,缩放幅度越大)- 返回 {boolean}
模拟双指放大操作,以指定坐标为中心放大屏幕内容。
var x = device.width / 2;
var y = device.height / 2;
$shellHttp.zoomIn(x, y, 50);
sleep(200);
$shellHttp.zoomIn(x, y, 50);
sleep(200);
$shellHttp.zoomIn(x, y, 50);
sleep(200);
$shellHttp.zoomIn(x, y, 50);
sleep(200);
$shellHttp.zoomIn(x, y, 50);
sleep(200);
$shellHttp.zoomIn(x, y, 50);
sleep(200);$shellHttp.zoomOut(x, y, stride)
targetX/targetY{number} 缩放中心坐标stride{number} 缩放步长- 返回 {boolean}
模拟双指缩小操作,以指定坐标为中心缩小屏幕内容。
var x = device.width / 2;
var y = device.height / 2;
$shellHttp.zoomOut(x, y, 50);
sleep(200);
$shellHttp.zoomOut(x, y, 50);
sleep(200);
$shellHttp.zoomOut(x, y, 50);
sleep(200);
$shellHttp.zoomOut(x, y, 50);
sleep(200);
$shellHttp.zoomOut(x, y, 50);
sleep(200);
$shellHttp.zoomOut(x, y, 50);
sleep(200);示例
全功能测试脚本
/**
* ShellHttp 全功能演示
* 流程:初始化 → 状态检查 → 系统操作 → 触控演示 → 结束
*/
// ==================== 初始化 ====================
toastLog("正在初始化 ShellHttp 模块...");
$shellHttp.init();
// ==================== 状态检查 ====================
var isRunning = $shellHttp.state();
if (!isRunning) {
toastLog("ShellHttp 服务未运行");
console.error("服务状态异常");
exit();
}
var version = $shellHttp.version();
toastLog("ShellHttp 版本: " + version);
// ==================== 系统按键演示 ====================
toastLog("3秒后执行 返回键");
sleep(3000);
$shellHttp.back();
toastLog("3秒后执行 主页键");
sleep(3000);
$shellHttp.home();
// ==================== 截图演示 ====================
toastLog("3秒后截图并保存");
sleep(3000);
$shellHttp.captureScreen("/sdcard/shellhttp_demo.png");
// ==================== 触控演示 ====================
var x = device.width / 2;
var y = device.height / 2;
toastLog("3秒后点击屏幕中心点");
sleep(3000);
$shellHttp.click(x, y);
toastLog("3秒后向上滑动");
sleep(3000);
$shellHttp.swipeUp();
// ==================== 结束 ====================
toastLog("ShellHttp 测试完成!");
$shellHttp.release();高级组合操作
// 初始化
$shellHttp.init();
// 连续操作:截图 → 文本输入 → 搜索
$shellHttp.captureScreen("/sdcard/before_search.png");
$shellHttp.home();
sleep(1000);
$shellHttp.click(100, 100); // 点击搜索框
sleep(500);
setClip("自动化测试");
$shellHttp.paste();
sleep(500);
$shellHttp.enter();
// 保存操作后的截图
sleep(2000);
$shellHttp.captureScreen("/sdcard/after_search.png");Shell命令集成
$shellHttp.init();
// 获取系统信息
var sysInfo = $shellHttp.exec("getprop ro.build.version.sdk");
console.log("Android SDK版本: ", sysInfo.result);
// 批量文件操作
$shellHttp.exec("cd /sdcard && mkdir -p test_folder && touch test_folder/test.txt");
// 清理临时文件
$shellHttp.exec("rm -rf /sdcard/test_folder");