主题
贝壳 · API 文档
贝壳通过本机 HTTP 指令调用，格式为 /cmd?fun=指令名&参数。
| 项目 | 值 |
|---|---|
| 手机脚本 | http://127.0.0.1:1688/cmd? |
| 电脑调用 | http://设备局域网IP:1688/cmd? |
| 请求方式 | GET |
| Bundle ID | cloud.hacker.shell |
| 结果文件 | /var/mobile/Media/Shell/tmp/iggresult.txt |
| 参数文件 | /var/mobile/Media/Shell/tmp/iggparams.txt |
| 导出目录 | /var/mobile/Media/Shell/exportdata/ |
| 导入目录 | /var/mobile/Media/Shell/importdata/ |
调用前准备
- HTTP 脚本默认开启，无法手动关闭，不需要额外设置。
- 每次调用任何指令前，都必须先把贝壳启动到前台：
lua
local shell = require("shell")
shell.runApp("cloud.hacker.shell")
shell.mSleep(3 * 1000) -- 第一次启动需要联网验证，建议等 3 秒返回值
指令调用后直接返回 JSON：
json
{"result": 1}同时写入结果文件 /var/mobile/Media/Shell/tmp/iggresult.txt。
| 值 | 含义 |
|---|---|
1 | 执行完成 |
2 | 正在执行，还未完成 |
3 | 一键新机成功，但 IP 地址重复（仅 newrecord） |
4 | 已到最后一条（仅 nextrecord）；haverecord 中表示记录不存在 |
0 | 执行出错 |
10 | 运行环境异常 |
100 | 产品未激活或已过期 |
接口一览
| 分类 | 功能 | 指令 |
|---|---|---|
| 屏幕 | 截屏 | /snapshot |
| 屏幕 | 点击屏幕 | /tap |
| 应用 | 选择应用 | select |
| 应用 | 取消选择应用 | unselect |
| 应用 | 清除所有选择 | unselectall |
| 应用 | 获取当前选择 | getcurrentselect |
| 应用 | 清理指定应用 | clean |
| 应用 | 删除应用的备份 | deletebackup |
| 应用 | 卸载选中的应用 | uninstallselectedapp |
| 应用 | 清理 AppStore | cleanappstore |
| 记录 | 一键新机 | newrecord |
| 记录 | 下一条记录 | nextrecord |
| 记录 | 判断记录是否存在 | haverecord |
| 记录 | 生效指定记录 | activerecord |
| 记录 | 生效第一条 / 最后一条 | activefirstrecord · activelastrecord |
| 记录 | 删除指定记录 | deleterecord |
| 记录 | 清除所有记录 | deleteallrecords |
| 记录 | 瘦身指定记录 | thinrecord |
| 记录 | 获取所有记录名 | getallrecordnames |
| 记录 | 按时间排序 | orderbytime · orderbytimedesc |
| 备注 | 设置 / 获取当前备注 | setcurrentremarks · getcurrentremarks |
| 定位 | 设置 / 清除当前坐标 | setcurrentrecordlocation · clearcurrentrecordlocation |
| 参数 | 获取 / 设置当前参数 | getcurrentrecordparam · setcurrentrecordparam |
| 导入导出 | 导出记录 | exportrecord · exportallrecords |
| 导入导出 | 导入记录 | importdirect · importcompatible |
接口详情
以下地址均以手机本机 127.0.0.1 为例。
截屏
GET http://127.0.0.1:1688/snapshot点击屏幕
GET http://127.0.0.1:1688/tap?x=0.5&y=0.5| 参数 | 必填 | 说明 |
|---|---|---|
x | 是 | 横向位置，取值 0 ~ 1（屏幕宽度的比例） |
y | 是 | 纵向位置，取值 0 ~ 1（屏幕高度的比例） |
选择 / 取消选择应用
GET http://127.0.0.1:1688/cmd?fun=select&app=应用BID&save=false
GET http://127.0.0.1:1688/cmd?fun=unselect&app=应用BID&save=false| 参数 | 必填 | 说明 |
|---|---|---|
app | 是 | 应用的 Bundle ID |
save | — | true 时会把选择结果保存到当前记录 |
清除所有选择
GET http://127.0.0.1:1688/cmd?fun=unselectall获取当前选择
GET http://127.0.0.1:1688/cmd?fun=getcurrentselect清理指定应用
GET http://127.0.0.1:1688/cmd?fun=clean&app=应用BID清理后数据永久丢失，请谨慎使用。
删除应用的备份
GET http://127.0.0.1:1688/cmd?fun=deletebackup&app=应用BID&record=记录ID| 参数 | 必填 | 说明 |
|---|---|---|
app | 是 | 应用的 Bundle ID |
record | 是 | 记录 ID |
请先用 unselect 取消选择该应用再调用，否则可能又被备份回来。删除后数据永久丢失。
卸载选中的应用
GET http://127.0.0.1:1688/cmd?fun=uninstallselectedapp如果已在 App 中打开「卸载应用」选项，一键新机后会自动执行，不需要再调用。
清理 AppStore
GET http://127.0.0.1:1688/cmd?fun=cleanappstore如果已在 App 中打开「清理 AppStore」选项，一键新机后会自动执行，不需要再调用。
一键新机
GET http://127.0.0.1:1688/cmd?fun=newrecord&machine=iPhone10,6&version=17D50&idfa=IDFA&checkip=true| 参数 | 必填 | 说明 |
|---|---|---|
machine | — | 机型标识，如 iPhone10,6 |
version | — | 系统内部版本号（Build），如 17D50 |
idfa | — | 指定 IDFA |
checkip | — | 是否检测 IP 重复 |
- 所有参数都可以不传，此时随机生成。
machine和version必须同时设置。- 传入
idfa时，请确保本机没有这个 IDFA 的记录，否则会出现意外错误。已有该记录时请用activerecord恢复。
下一条记录
GET http://127.0.0.1:1688/cmd?fun=nextrecord返回 4 表示已经是最后一条。
判断记录是否存在
GET http://127.0.0.1:1688/cmd?fun=haverecord&record=记录ID返回 1 表示存在，4 表示不存在。
生效指定记录
GET http://127.0.0.1:1688/cmd?fun=activerecord&record=记录ID生效第一条 / 最后一条
GET http://127.0.0.1:1688/cmd?fun=activefirstrecord
GET http://127.0.0.1:1688/cmd?fun=activelastrecord删除指定记录
GET http://127.0.0.1:1688/cmd?fun=deleterecord&record=记录ID清除所有记录
GET http://127.0.0.1:1688/cmd?fun=deleteallrecords瘦身指定记录
GET http://127.0.0.1:1688/cmd?fun=thinrecord&record=记录ID获取所有记录名
GET http://127.0.0.1:1688/cmd?fun=getallrecordnames记录名列表写入 /var/mobile/Media/Shell/tmp/iggrecords.txt。
按时间排序
GET http://127.0.0.1:1688/cmd?fun=orderbytime
GET http://127.0.0.1:1688/cmd?fun=orderbytimedescorderbytime 按时间正序，orderbytimedesc 按时间倒序。
设置 / 获取当前备注
GET http://127.0.0.1:1688/cmd?fun=setcurrentremarks&remarks=备注
GET http://127.0.0.1:1688/cmd?fun=getcurrentremarks| 参数 | 必填 | 说明 |
|---|---|---|
remarks | 是 | 备注内容，最长 20 个字符，中文需 URL 编码 |
设置 / 清除当前坐标
GET http://127.0.0.1:1688/cmd?fun=setcurrentrecordlocation&location=116.7361382365_39.8887921413_北京老胡同
GET http://127.0.0.1:1688/cmd?fun=clearcurrentrecordlocation| 参数 | 必填 | 说明 |
|---|---|---|
location | 是 | 格式 经度_纬度_地名，地名可省略 |
获取 / 设置当前参数
GET http://127.0.0.1:1688/cmd?fun=getcurrentrecordparam
GET http://127.0.0.1:1688/cmd?fun=setcurrentrecordparamgetcurrentrecordparam：把当前记录参数写入/var/mobile/Media/Shell/tmp/iggparams.txt。setcurrentrecordparam：读取该文件中的参数并应用到当前记录。建议不要修改 IDFA。
正确流程：先获取 → 修改文件中的字段 → 再设置。格式见 参数文件。
导出记录
GET http://127.0.0.1:1688/cmd?fun=exportrecord&record=记录ID
GET http://127.0.0.1:1688/cmd?fun=exportallrecords&zip=文件名导出到 /var/mobile/Media/Shell/exportdata/。
导入记录
GET http://127.0.0.1:1688/cmd?fun=importdirect
GET http://127.0.0.1:1688/cmd?fun=importcompatible把要导入的记录放在 /var/mobile/Media/Shell/importdata/，必须是导出的 zip 包。importdirect 为直接导入，importcompatible 为兼容性导入。
参数文件
路径：/var/mobile/Media/Shell/tmp/iggparams.txt
- 每行一个参数，换行符为
chr(10) - 参数名和参数值之间用冒号
:分隔 - 调用
getcurrentrecordparam后打开该文件即可看到实际格式
| 参数名 | 说明 |
|---|---|
DeviceName | 设备名称，如「xxxx iPhone」 |
SystemVersion | 系统版本号，如「10.3.1」 |
IDFA | IDFA |
IDFV | IDFV |
UDID | 设备 UDID |
IMEI | 设备 IMEI |
SerialNum | 设备序列号 |
MAC | MAC 地址 |
SSID | Wi-Fi 名称 |
BSSID | Wi-Fi BSSID |
OpenUDID | OpenUDID |
Lua 示例
lua
local json = require("cjson")
local http = require("socket.http")
local shell = require("shell")
local BASE = "http://127.0.0.1:1688/cmd?fun="
-- 统一调用，返回 result 数值
function Beike(query)
local res, code = http.request(BASE .. query)
if code == 200 then
return json.decode(res).result
end
end
-- 1. 启动贝壳（所有指令之前必须执行）
shell.runApp("cloud.hacker.shell")
shell.mSleep(3 * 1000)
-- 2. 一键新机
local r = Beike("newrecord")
if r == 3 then
-- IP 地址重复
elseif r == 100 then
-- 未激活或已过期
end
-- 3. 生效指定记录
Beike("activerecord&record=APP001")
-- 4. 设置当前记录坐标
Beike("setcurrentrecordlocation&location=116.7361382365_39.8887921413_北京老胡同")使用教程见 贝壳 · 使用教程。