跳转到内容

$shellHttp - Shell HTTP 命令

更新: 2026/3/2 字数: 0 字 时长: 0 分钟

$shellHttp 模块通过 HTTP 服务提供系统级控制能力,支持 Shell命令执行、触控操作、按键模拟、屏幕截图、文本输入 等功能,具备 高权限、高稳定性和后台运行能力,支持 开机自启和后台自恢复,是 Bot.js Pro 实现高级自动化控制的核心模块之一。

核心优势

  1. 高权限:超越普通 ADB 和 Shizuku 的权限等级
  2. 稳定性:支持开机自启和后台自恢复
  3. 全面性:集成 Shell 命令、触控、截图等多种功能
  4. 跨设备:支持 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 通信通道,所有操作前必须先执行初始化

js
$shellHttp.init(); // 使用默认端口 9124
js
$shellHttp.init(9124); // 指定端口号

$shellHttp.version()

  • 返回 {number} 服务版本号,最新版为 1

获取 ShellHttp 服务版本号,用于兼容性检查。

js
var version = $shellHttp.version();
console.log("ShellHttp 版本号: ", version);

$shellHttp.state()

  • 返回 {boolean} 服务运行状态

检查 ShellHttp 服务是否正在运行,确保通信通道正常。

js
var isRunning = $shellHttp.state();
console.log("ShellHttp 服务状态: ", isRunning);

$shellHttp.restart()

  • 返回 {boolean}

通过 ShellHttp 服务重启自身,用于服务异常恢复。

js

var ok = $shellHttp.restart();
if (ok) {
    console.log("shellHttp 重启成功");
} else {
    console.error("shellHttp 重启失败");
}

$shellHttp.stopService()

  • 无返回值

停止 ShellHttp 服务。

$shellHttp.destroy()

  • 无返回值

销毁 ShellHttp 资源,脚本结束前建议执行。

js
$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 命令,支持单命令和分号分隔的多命令。

单命令执行

js
var result = $shellHttp.exec("echo 'Hello ShellHttp'");
console.log("命令执行结果: ", result);
js
// 截屏
var result = $shellHttp.exec("screencap -p /sdcard/screen.png");
console.log("命令执行结果: ", result);

多命令组合执行

js
// 截图后生成布局节点文件
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

js
var saveResult = $shellHttp.saveWindowXml();
console.log("XML布局保存结果: ", saveResult);

系统按键操作

$shellHttp.home()

  • 返回 {boolean}

模拟按下主页键,返回设备主屏幕。

js
var homeResult = $shellHttp.home();
console.log("按下主页键: ", homeResult);

$shellHttp.back()

  • 返回 {boolean}

模拟按下返回键,返回上一个页面。

js
var backResult = $shellHttp.back();
console.log("按下返回键: ", backResult);

$shellHttp.recents()

  • 返回 {boolean}

模拟按下最近任务键,打开后台任务列表。

js
var recentResult = $shellHttp.recents();
console.log("打开最近任务: ", recentResult);

$shellHttp.powerDialog()

  • 返回 {boolean}

长按电源键弹出电源菜单

js
var powerDialogResult = $shellHttp.powerDialog();
console.log("弹出电源菜单: ", powerDialogResult);

$shellHttp.power()

  • 返回 {boolean}

按下电源键,实现锁屏/亮屏切换。

js
var powerResult = $shellHttp.power();
console.log("按下电源键: ", powerResult);

$shellHttp.notifications()

  • 返回 {boolean}

下拉通知栏

js
var notificationsResult = $shellHttp.notifications();
console.log("下拉通知栏: ", notificationsResult);

$shellHttp.quickSettings()

  • 返回 {boolean}

打开快速设置面板。

js
var quickSettingsResult = $shellHttp.quickSettings();
console.log("打开快速设置: ", quickSettingsResult);

$shellHttp.volumeUp()

  • 返回 {boolean}

音量增加一级。

js
var volumeUpResult = $shellHttp.volumeUp();
console.log("音量增加: ", volumeUpResult);

$shellHttp.volumeDown()

  • 返回 {boolean}

音量减少一级。

js
var volumeDownResult = $shellHttp.volumeDown();
console.log("音量减少: ", volumeDownResult);

屏幕截图操作

$shellHttp.captureScreen()

通过 ShellHttp 服务截图并返回 Image 对象。

js
var img = $shellHttp.captureScreen();
console.log("截图对象: ", img);
img.saveTo("/sdcard/test.png");
img.recycle();

$shellHttp.captureScreen(path)

  • path {string} 截图保存路径
  • 返回 {boolean}

通过 ShellHttp 服务截图并保存到指定路径。

js
var saveResult = $shellHttp.captureScreen("/sdcard/screen_test.png");
console.log("截图保存结果: ", saveResult);

文本操作

$shellHttp.setSelection()

  • 返回 {boolean}

全选当前页面文本/内容。

js
var setSelectionResult = $shellHttp.setSelection();
console.log("全选内容: ", setSelectionResult);

$shellHttp.copy()

  • 返回 {boolean}

复制选中文本到剪贴板。

js
var copyResult = $shellHttp.copy();
console.log("复制内容: ", copyResult);

$shellHttp.paste()

  • 返回 {boolean}

粘贴剪贴板内容到当前焦点位置(支持中文)。

js
setClip("这是要粘贴的中文内容");
var pasteResult = $shellHttp.paste();
console.log("粘贴内容: ", pasteResult);

$shellHttp.cut()

  • 返回 {boolean}

剪切选中文本到剪贴板。

js
var cutResult = $shellHttp.cut();
console.log("剪切内容: ", cutResult);

$shellHttp.input(text)

  • text {string} 要输入的文本内容
  • 返回 {boolean}

模拟键盘输入文本。

js
var inputResult = $shellHttp.input("hello123");
console.log("输入文本: ", inputResult);

中文输入

  1. 剪贴板+粘贴方案(推荐):
js
setClip("你好世界");
sleep(500)
$shellHttp.paste();
  1. $input 输入法(复杂场景):
js
$input.setText("你好世界");

$shellHttp.enter()

  • 返回 {boolean}

模拟按下回车键,适用于搜索、确认、换行等场景。

js
var enterResult = $shellHttp.enter();
console.log("按下回车键: ", enterResult);

$shellHttp.delete([count])

  • count {number} 可选,删除的字符数,默认 1
  • 返回 {boolean}

模拟删除键,删除光标后方字符。

js
var deleteSingle = $shellHttp.delete();
console.log("删除1个字符: ", deleteSingle);

var deleteMultiple = $shellHttp.delete(3);
console.log("删除3个字符: ", deleteMultiple);

$shellHttp.backspace([count])

  • count {number} 可选,退格的字符数,默认 1
  • 返回 {boolean}

模拟退格键,删除光标前方字符。

js
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}

模拟按下并释放指定键码或组合键。

单键操作

js
var keyPressResult = $shellHttp.keyPress(187); // 任务键
console.log("按下任务键: ", keyPressResult);

组合键操作

js
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}

模拟长按指定键码。

js
var longPressResult = $shellHttp.keyLongPress(26); // 长按电源键
console.log("长按电源键: ", longPressResult);
js
var customLongPress = $shellHttp.keyLongPress(26, 2000); // 长按2秒
console.log("自定义时长长按: ", customLongPress);

键码查看

js
console.log(android.view.KeyEvent); // 查看所有键码常量

触控操作

$shellHttp.click(x, y)

  • x {number} 触控点横坐标
  • y {number} 触控点纵坐标
  • 返回 {boolean}

模拟单击操作,点击指定坐标位置。

js
var clickResult = $shellHttp.click(500, 1000);
console.log("点击坐标: ", clickResult);

$shellHttp.longClick(x, y)

  • x {number} 触控点横坐标
  • y {number} 触控点纵坐标
  • 返回 {boolean}

模拟长按操作,长按指定坐标位置。

js
var longClickResult = $shellHttp.longClick(500, 1000);
console.log("长按坐标: ", longClickResult);

$shellHttp.press(x, y, duration)

  • x {number} 触控点横坐标
  • y {number} 触控点纵坐标
  • duration {number} 按住时长(毫秒)
  • 返回 {boolean}

自定义按住操作,按住指定坐标并保持指定时长。

js
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}

模拟触控抬起,手指从按下状态抬起。

按下→抬起实现模拟点击示例

js
// 按下→休息200毫秒→抬起
$shellHttp.touchDown(200, 500);
sleep(200);
$shellHttp.touchUp()

按下→移动→抬起实现自定义轨迹的滑动示例

js
// 按下→移动→抬起
$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}

释放所有触控点,清空触控状态。

js
$shellHttp.releaseTouch();

多指触控示例

js
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}

基础自定义滑动,指定起点、终点和时长。

js
$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}

高级自定义滑动,精细控制滑动的平滑度和时间点。

js
$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}

曲线滑动,模拟真人滑动的非匀速效果。

js
$shellHttp.swipe(200, 500, 600, 500, 50, 200, 2000, 200, 2);

$shellHttp.swipeUp([width, height])

  • width {number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地 device.width
  • height {number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地 device.height
  • 返回 {boolean}

模拟向上滑动操作,起点位于屏幕底部,终点位于屏幕上方,自动适配指定或本地屏幕尺寸。

基础滑动(使用本地屏幕尺寸)

js
$shellHttp.swipeUp();

自定义屏幕尺寸滑动

js
$shellHttp.swipeUp(device.width, device.height);

$shellHttp.swipeDown([width, height])

  • width {number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地 device.width
  • height {number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地 device.height
  • 返回 {boolean}

模拟向下滑动操作,起点位于屏幕上方,终点位于屏幕底部,自动适配指定或本地屏幕尺寸。

$shellHttp.swipeLeft([width, height])

  • width {number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地 device.width
  • height {number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地 device.height
  • 返回 {boolean}

模拟向左滑动操作,起点位于屏幕右侧,终点位于屏幕左侧,自动适配指定或本地屏幕尺寸。

$shellHttp.swipeRight([width, height])

  • width {number} 可选,参考屏幕宽度,用于计算滑动起点和终点,默认取本地 device.width
  • height {number} 可选,参考屏幕高度,用于计算滑动起点和终点,默认取本地 device.height
  • 返回 {boolean}

模拟向右滑动操作,起点位于屏幕左侧,终点位于屏幕右侧,自动适配指定或本地屏幕尺寸。

$shellHttp.zoomIn(x, y, stride)

  • x {number} 缩放中心横坐标
  • y {number} 缩放中心纵坐标
  • stride {number} 缩放步长(步长越大,缩放幅度越大)
  • 返回 {boolean}

模拟双指放大操作,以指定坐标为中心放大屏幕内容。

js
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}

模拟双指缩小操作,以指定坐标为中心缩小屏幕内容。

js
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);

示例

全功能测试脚本

js
/**
 * 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();

高级组合操作

js
// 初始化
$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命令集成

js
$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");