Android Control API 接口文档

支持版本提示

Android Control API 需要特定的镜像版本支持，请确保您的云机镜像版本号不低于以下版本：

Android 10: vcloud_android10_edge_20260110 及以上
Android 13: vcloud_android13_edge_20260110 及以上
Android 15: vcloud_android15_edge_20260110 及以上
CBS: 1.1.1.10 及以上

简介

Android Control API 提供了 Android 系统的一系列操控与管理能力，涵盖了应用管理、输入控制、系统设置、文件操作等功能.

调用方式

1. 云机外 HTTP 调用

当您从宿主机或网络中的其他设备调用时，需要通过容器管理API进行转发：

URL 格式: http://{主机IP}:18182/android_api/v2/{云机ID}/{接口路径}

以「获取已安装应用列表」为例：

bash

curl http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list

javascript

const resp = await fetch(
  "http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list"
);
console.log(await resp.json());

python

import requests

resp = requests.get("http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list")
print(resp.json())

java

HttpURLConnection conn = (HttpURLConnection)
    new URL("http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list")
        .openConnection();
conn.setRequestMethod("GET");
String body = new String(conn.getInputStream().readAllBytes());
System.out.println(body);

resp, _ := http.Get("http://192.168.1.100:18182/android_api/v2/EDGE12345678/package/list")
defer resp.Body.Close()
body, _ := io.ReadAll(resp.Body)
fmt.Println(string(body))

2. 云机内 HTTP 调用

在安卓实例内部（如通过终端或内部脚本）直接调用：

URL 格式: http://127.0.0.1:18185/api/{接口路径}

以「获取已安装应用列表」为例：

bash

curl http://127.0.0.1:18185/api/package/list

javascript

const resp = await fetch("http://127.0.0.1:18185/api/package/list");
console.log(await resp.json());

python

import requests

resp = requests.get("http://127.0.0.1:18185/api/package/list")
print(resp.json())

kotlin

val url = URL("http://127.0.0.1:18185/api/package/list")
val conn = url.openConnection() as HttpURLConnection
val body = conn.inputStream.bufferedReader().readText()
println(body)

java

HttpURLConnection conn = (HttpURLConnection)
    new URL("http://127.0.0.1:18185/api/package/list").openConnection();
String body = new String(conn.getInputStream().readAllBytes());
System.out.println(body);

3. TCP 调用

在云机内或宿主机通过 TCP 进行低延迟调用：

地址: 127.0.0.1:18186
协议: 4字节大端长度头 + JSON Payload

请求 JSON 格式：{"path": "接口路径", "params": {参数}}

以「获取已安装应用列表」为例：

javascript

const net = require("net");

function tcpCall(path, params = {}, host = "127.0.0.1", port = 18186) {
  return new Promise((resolve, reject) => {
    const client = net.createConnection({ host, port }, () => {
      const payload = Buffer.from(JSON.stringify({ path, params }));
      const header = Buffer.alloc(4);
      header.writeUInt32BE(payload.length);
      client.write(Buffer.concat([header, payload]));
    });
    let buf = Buffer.alloc(0);
    client.on("data", (chunk) => {
      buf = Buffer.concat([buf, chunk]);
      if (buf.length >= 4) {
        const len = buf.readUInt32BE(0);
        if (buf.length >= 4 + len) {
          resolve(JSON.parse(buf.subarray(4, 4 + len).toString()));
          client.end();
        }
      }
    });
    client.on("error", reject);
  });
}

tcpCall("package/list").then(console.log);

python

import socket, struct, json

def tcp_call(path: str, params: dict = None,
             host="127.0.0.1", port=18186) -> dict:
    payload = json.dumps({"path": path, "params": params or {}}).encode()
    with socket.create_connection((host, port)) as sock:
        sock.sendall(struct.pack(">I", len(payload)) + payload)
        length = struct.unpack(">I", sock.recv(4))[0]
        data = b""
        while len(data) < length:
            data += sock.recv(length - len(data))
        return json.loads(data)

result = tcp_call("package/list")
print(result)

kotlin

import java.io.DataInputStream
import java.io.DataOutputStream
import java.net.Socket

fun tcpCall(path: String, params: String = "{}",
            host: String = "127.0.0.1", port: Int = 18186): String {
    Socket(host, port).use { socket ->
        val output = DataOutputStream(socket.getOutputStream())
        val input = DataInputStream(socket.getInputStream())
        val payload = """{"path":"$path","params":$params}""".toByteArray()
        output.writeInt(payload.size)
        output.write(payload)
        output.flush()
        val length = input.readInt()
        val response = ByteArray(length)
        input.readFully(response)
        return String(response)
    }
}

val result = tcpCall("package/list")
println(result)

java

import java.io.DataInputStream;
import java.io.DataOutputStream;
import java.net.Socket;

public static String tcpCall(String path) throws Exception {
    try (Socket socket = new Socket("127.0.0.1", 18186)) {
        DataOutputStream out = new DataOutputStream(socket.getOutputStream());
        DataInputStream in = new DataInputStream(socket.getInputStream());

        byte[] payload = ("{\"path\":\"" + path + "\",\"params\":{}}").getBytes();
        out.writeInt(payload.length);
        out.write(payload);
        out.flush();

        int length = in.readInt();
        byte[] response = new byte[length];
        in.readFully(response);
        return new String(response);
    }
}

// 调用
System.out.println(tcpCall("package/list"));

package main

import (
    "encoding/binary"
    "encoding/json"
    "fmt"
    "io"
    "net"
)

func tcpCall(path string, params map[string]any) (map[string]any, error) {
    conn, err := net.Dial("tcp", "127.0.0.1:18186")
    if err != nil {
        return nil, err
    }
    defer conn.Close()

    payload, _ := json.Marshal(map[string]any{"path": path, "params": params})
    header := make([]byte, 4)
    binary.BigEndian.PutUint32(header, uint32(len(payload)))
    conn.Write(header)
    conn.Write(payload)

    if _, err := io.ReadFull(conn, header); err != nil {
        return nil, err
    }
    buf := make([]byte, binary.BigEndian.Uint32(header))
    if _, err := io.ReadFull(conn, buf); err != nil {
        return nil, err
    }
    var result map[string]any
    json.Unmarshal(buf, &result)
    return result, nil
}

func main() {
    result, _ := tcpCall("package/list", nil)
    fmt.Println(result)
}

4. 命令行 (CLI) 调用

需要 API 版本 1.0.7 及以上

通过 ve 命令行工具调用设备 API，支持 Android / macOS / Windows / Linux 全平台。

安装

下载后直接使用，无需安装。

macOSLinuxWindowsAndroid

bash

# Apple Silicon (ARM64)
curl -fsSL -o ve https://help.vmosedge.com/cli/1.0.9/ve-darwin-arm64 && chmod +x ve && export PATH=$PWD:$PATH

# Intel (x64)
curl -fsSL -o ve https://help.vmosedge.com/cli/1.0.9/ve-darwin-x64 && chmod +x ve && export PATH=$PWD:$PATH

bash

# x64
curl -fsSL -o ve https://help.vmosedge.com/cli/1.0.9/ve-linux-x64 && chmod +x ve && export PATH=$PWD:$PATH

# ARM64
curl -fsSL -o ve https://help.vmosedge.com/cli/1.0.9/ve-linux-arm64 && chmod +x ve && export PATH=$PWD:$PATH

cmd

# x64
curl -o ve.exe https://help.vmosedge.com/cli/1.0.9/ve-windows-x64.exe && set PATH=%CD%;%PATH%

bash

curl -fsSL -o /data/local/tmp/ve https://help.vmosedge.com/cli/1.0.9/ve-android-arm64 && chmod +x /data/local/tmp/ve && export PATH=/data/local/tmp:$PATH

以上命令仅在当前终端会话生效。如需永久全局使用，可将 ve 所在目录加入系统环境变量。

云机内 API 版本 1.0.9 及以上镜像已自动安装，全局可用，无需手动操作。

使用方式

交互模式（推荐）：

bash

# 连接设备，进入交互模式
ve -s 192.168.1.100 shell
# 192.168.1.100 (v1.0.9)
# Tab 补全接口路径，输入 help 查看帮助，exit 退出
#
# ve@192.168.1.100 # list                          ← 列出接口
# ve@192.168.1.100 # input/click --x 100 --y 200   ← 执行点击
# ve@192.168.1.100 # accessibility/dump             ← 获取控件树
# ve@192.168.1.100 # info input/click               ← 查看接口文档
# ve@192.168.1.100 # exit                           ← 退出

交互模式支持 Tab 补全、上下键历史、行内提示等标准终端功能。

单条命令模式：

bash

ve -s 192.168.1.100 -l                               # 列出接口
ve -s 192.168.1.100 input/click --x 100 --y 200      # 执行命令
ve -s 192.168.1.100 info input/click                  # 查看接口文档

云机内调用：

bash

ve input/click --x 100 --y 200                        # 执行点击
ve shell                                              # 进入交互模式

参数说明

参数	说明
`-s, --server <addr>`	云机 IP（仅支持局域网模式）
`-l, --list`	列出所有可用接口
`-j, --json '{...}'`	直接传入 JSON body
`-f, --file <path>`	从文件读取 body（支持 JSON / YAML）
`-v, --version`	显示版本号
`-h, --help`	显示帮助信息

参数传递

bash

# --key value 形式（自动推断类型）
ve -s 192.168.1.100 input/click --x 100 --y 200

# 嵌套参数用点号分隔
ve -s 192.168.1.100 accessibility/node --selector.text "确定" --selector.class_name "Button"

# JSON body
ve -s 192.168.1.100 -j '{"x": 100, "y": 200}' input/click

# 从文件读取
ve -s 192.168.1.100 -f workflow.json workflow/run

5. WebSocket 调用

通过 WebSocket 进行实时双向通信，适用于需要持久连接、低延迟交互的场景。

端点: ws://{云机IP}:18185/ws
协议: JSON 文本帧

请求格式

json

{
  "path": "api/{接口路径}",
  "params": { ... },
  "request_id": "可选，自动生成"
}

响应格式

普通 JSON 响应（与 HTTP 一致）：

json

{
  "code": 200,
  "msg": "OK",
  "data": { ... },
  "request_id": "abc"
}

二进制数据响应（如截图）：

json

{
  "code": 200,
  "msg": "OK",
  "data": "base64编码字符串",
  "data_type": "base64",
  "data_size": 12345,
  "request_id": "abc"
}

示例

JavaScriptPythonKotlin

javascript

const ws = new WebSocket("ws://192.168.1.100:18185/ws");

ws.onopen = () => {
  // 获取已安装应用列表
  ws.send(JSON.stringify({
    path: "api/package/list"
  }));
};

ws.onmessage = (event) => {
  const response = JSON.parse(event.data);
  console.log(response);
};

// 发送带参数的请求
ws.send(JSON.stringify({
  path: "api/input/click",
  params: { x: 100, y: 200 }
}));

python

import asyncio, websockets, json

async def ws_call():
    async with websockets.connect("ws://192.168.1.100:18185/ws") as ws:
        # 获取已安装应用列表
        await ws.send(json.dumps({"path": "api/package/list"}))
        response = json.loads(await ws.recv())
        print(response)

        # 点击操作
        await ws.send(json.dumps({
            "path": "api/input/click",
            "params": {"x": 100, "y": 200}
        }))
        print(json.loads(await ws.recv()))

asyncio.run(ws_call())

kotlin

// 使用 OkHttp WebSocket
val client = OkHttpClient()
val request = Request.Builder()
    .url("ws://192.168.1.100:18185/ws")
    .build()

client.newWebSocket(request, object : WebSocketListener() {
    override fun onOpen(webSocket: WebSocket, response: Response) {
        webSocket.send("""{"path":"api/package/list"}""")
    }
    override fun onMessage(webSocket: WebSocket, text: String) {
        println(text)
    }
})

6. MCP 调用（AI Agent 集成）

需要 API 版本 1.0.7 及以上

通过 MCP（Model Context Protocol）将 Android 控制能力直接暴露给 AI Agent，支持 Claude Code、Cursor、Codex、Gemini、通义千问、Kimi 等任意兼容 MCP SSE 协议的客户端。

SSE 端点（二选一）：

模式	端点
局域网模式（勾选局域网IP）	`http://{云机IP}:18185/mcp/sse`
非局域网模式（未勾选局域网IP）	`http://{主机IP}:18182/android_api/v2/{云机ID}/mcp/sse`

以下配置以局域网模式为例，非局域网模式将 URL 替换为云机外 HTTP 调用地址即可。

bash

# 项目级（仅当前项目生效，默认）
claude mcp add --transport sse vmos-edge-control-api http://{云机IP}:18185/mcp/sse
# 全局（所有项目生效）
claude mcp add -s user --transport sse vmos-edge-control-api http://{云机IP}:18185/mcp/sse

# 移除
claude mcp remove vmos-edge-control-api
# 禁用（保留配置但不加载）
claude mcp disable vmos-edge-control-api
# 启用
claude mcp enable vmos-edge-control-api
# 查看列表
claude mcp list

yaml

# ~/.codex/config.yaml
mcp_servers:
  vmos-edge-control-api:
    type: sse
    url: "http://{云机IP}:18185/mcp/sse"

json

// ~/.gemini/settings.json
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "httpUrl": "http://{云机IP}:18185/mcp/sse"
    }
  }
}

json

// 项目根目录 .cursor/mcp.json 或 ~/.cursor/mcp.json
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "url": "http://{云机IP}:18185/mcp/sse"
    }
  }
}

json

// 在"MCP 服务"配置中添加
{
  "mcpServers": {
    "vmos-edge-control-api": {
      "type": "sse",
      "url": "http://{云机IP}:18185/mcp/sse"
    }
  }
}

连接成功后，AI 可直接调用截图、点击、输入文本、查看 UI 层次等工具，无需手动构造 HTTP 请求。

7. Skills 调用（AI Agent 集成）

推荐优先使用官方 skills 仓库 vmos-dev/vmos-edge-skills。

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-control-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-control-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-control-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-control-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-control-api

bash

npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill vmos-edge-control-api

参数格式支持

所有支持 POST 方法的接口，除了标准的 application/json 外，还支持 application/yaml 格式。

JSON 格式 (默认)

Content-Type: application/json

YAML 格式

Content-Type: application/yaml 或 text/yaml
示例:
yaml
```
package_name: com.android.settings
```

通用响应结构

所有接口均返回标准 JSON 格式，统一响应结构如下：

json

{
    "code": 200,            // 状态码，200 为成功
    "data": { ... },        // 具体的业务数据
    "msg": "OK",            // 状态描述
    "request_id": "..."     // 请求唯一标识
}

基础能力 (Base)

获取 API 版本

获取当前控制服务的版本信息以及所有支持的接口路径。需要镜像版本 20260113 及以上支持。

URL: /base/version_info
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "version_name": "1.0.0",
    "version_code": 100,
    "supported_list": [
      "base/sleep",
      "workflow",
      "base/version_info",
      "..."
    ]
  },
  "msg": "OK",
  "request_id": "si123456"
}

查询接口信息

查询支持的 API 接口信息。可指定接口路径获取详细文档，不传返回全部接口的简要信息。

URL: /base/list_action
方式: POST
参数:
参数名类型必选说明
paths array 否要查询的接口路径数组，不传返回全部
detail boolean 否是否返回详情（含 description、content 字段），默认 false

参数名	类型	必选	说明
paths	array	否	要查询的接口路径数组，不传返回全部
detail	boolean	否	是否返回详情（含 description、content 字段），默认 false

请求示例（查询指定接口）:

json

{
  "paths": ["input/click", "base/sleep"],
  "detail": true
}

返回示例:

json

{
  "code": 200,
  "data": {
    "input/click": {
      "title": "点击坐标",
      "description": "在屏幕上执行点击操作",
      "content": "- **URL**: `/input/click`\n..."
    },
    "base/sleep": {
      "title": "暂停响应",
      "description": "暂停接口响应一段时间"
    }
  },
  "msg": "OK",
  "request_id": "la123456"
}

暂停响应

暂停接口响应一段时间。常用于脚本执行中的等待。需要镜像版本 20260113 及以上支持。

URL: /base/sleep
方式: POST
参数:
参数名类型必选说明
duration long 是暂停时长 (ms)

参数名	类型	必选	说明
duration	long	是	暂停时长 (ms)

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sl123456"
}

应用运行管理 (Activity)

启动应用

URL: /activity/start
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

请求示例:

json

{
  "package_name": "com.android.settings"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.android.settings",
    "class_name": "com.android.settings.Settings"
  },
  "msg": "OK",
  "request_id": "8aca36b28c444ca09d07fb2690d03a3d"
}

启动指定 Activity

URL: /activity/start_activity
方式: POST

参数:

参数名	类型	必选	说明
package_name	string	否	应用包名 (指定了 action 时可选)
class_name	string	否	Activity 类名
action	string	否	Intent action
data	string	否	Intent data
extras	object	否	Intent extras (Key-Value 键值对)

请求示例:

json

{
  "package_name": "com.android.settings",
  "class_name": "com.android.settings.Settings",
  "extras": {
    "extra_key": "extra_value",
    "is_test": true
  }
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sa123456"
}

停止应用

URL: /activity/force_stop
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名
请求示例:
json
```
{
  "package_name": "com.example.app"
}
```

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "a1b2c3d4e5f6g7h8i9j0"
}

停止所有应用

停止所有运行中的应用（排除系统应用）。

URL: /activity/stop_all_apps
方式: POST
参数:
参数名类型必选说明
exclude_packages string[] 否额外排除不停止的包名列表
back_home boolean 否停止后是否回到桌面，默认 true

参数名	类型	必选	说明
exclude_packages	string[]	否	额外排除不停止的包名列表
back_home	boolean	否	停止后是否回到桌面，默认 `true`

请求示例:

json

{
  "exclude_packages": ["com.example.app1"]
}

返回示例:

json

{
  "code": 200,
  "data": ["com.example.app1", "com.example.app2"],
  "msg": "OK",
  "request_id": "b2c3d4e5f6g7h8i9j0a1"
}

获取正在运行的进程

URL: /activity/processes
方式: GET

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "process_name": "com.android.settings",
      "pid": 1234,
      "uid": 1000,
      "package_names": ["com.android.settings"],
      "importance": 100
    }
  ],
  "msg": "OK",
  "request_id": "c3d4e5f6g7h8i9j0a1b2"
}

获取最上层组件信息

URL: /activity/top_activity
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.android.settings",
    "class_name": "com.android.settings.Settings"
  },
  "msg": "OK",
  "request_id": "ta123456"
}

获取最近任务列表

URL: /activity/recent_tasks
方式: GET
参数:
参数名类型必选说明
max_num int 否最大数量，默认 20

参数名	类型	必选	说明
max_num	int	否	最大数量，默认 20

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "task_id": 123,
      "base_package_name": "com.android.settings",
      "base_class_name": "com.android.settings.Settings",
      "top_package_name": "com.android.settings",
      "top_class_name": "com.android.settings.Settings",
      "num_activities": 1,
      "last_active_time": 1736412345000
    }
  ],
  "msg": "OK",
  "request_id": "rt123456"
}

清空任务栈

移除所有最近任务（类似于清理后台最近应用卡片）。

URL: /activity/clear_tasks
方式: POST

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "task_id": 123,
      "base_package_name": "com.android.settings",
      "base_class_name": "com.android.settings.Settings",
      "top_package_name": "com.android.settings",
      "top_class_name": "com.android.settings.Settings"
    }
  ],
  "msg": "OK",
  "request_id": "ct123456"
}

切换任务到前台

URL: /activity/move_to_front
方式: POST
参数:
参数名类型必选说明
task_id int 是任务 ID
请求示例:
json
```
{
  "task_id": 123
}
```

参数名	类型	必选	说明
task_id	int	是	任务 ID

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "mtf123456"
}

应用管理 (Package)

安装应用

支持标准 APK 以及 APKS、APKM、XAPK、OBB 等分包格式。通过文件上传（multipart）方式安装。

URL: /package/install_sync
方式: POST
参数:
参数名类型必选说明
file file 是 APK/XAPK 文件（multipart/form-data）
installer_package_name string 否指定安装来源包名

参数名	类型	必选	说明
file	file	是	APK/XAPK 文件（multipart/form-data）
installer_package_name	string	否	指定安装来源包名

文件上传注意事项：使用 file（multipart）上传时，installer_package_name 等文本参数必须放在 file 字段之前，或通过 Query 参数传递（推荐）。示例：
POST /package/install_sync?installer_package_name=com.android.vending
Content-Type: multipart/form-data

file=@app.xapk

返回示例:

json

{
  "code": 200,
  "cost": 2723,
  "data": {
    "android.content.pm.extra.STATUS": 0,
    "android.content.pm.extra.PACKAGE_NAME": "com.apkmirror.helper.prod",
    "android.content.pm.extra.PRE_APPROVAL": false,
    "android.content.pm.extra.SESSION_ID": 1513445030,
    "android.content.pm.extra.LEGACY_STATUS": 1,
    "android.content.pm.extra.STATUS_MESSAGE": "INSTALL_SUCCEEDED: Session installed"
  },
  "msg": "OK",
  "request_id": "84d5716b8d374006b4cba9caaef794b6"
}

通过 URI 安装应用

需要 API 版本 1.0.7 及以上

仅支持 URI 方式安装，不支持文件上传。适用于已有 APK 下载链接或本地路径的场景。同步等待安装完成后返回结果。支持标准 APK 及 APKS、APKM、XAPK、OBB 等分包格式。

URL: /package/install_uri_sync
方式: POST
参数:
参数名类型必选说明
uri string 是 APK URI，支持 http://、https://（自动下载后安装）、file://、content:// 或本地路径
installer_package_name string 否指定安装来源包名

参数名	类型	必选	说明
uri	string	是	APK URI，支持 `http://`、`https://`（自动下载后安装）、`file://`、`content://` 或本地路径
installer_package_name	string	否	指定安装来源包名

请求示例:

json

{
  "uri": "https://example.com/app.apk"
}

返回示例:

json

{
  "code": 200,
  "cost": 2723,
  "data": {
    "android.content.pm.extra.STATUS": 0,
    "android.content.pm.extra.PACKAGE_NAME": "com.example.app",
    "android.content.pm.extra.PRE_APPROVAL": false,
    "android.content.pm.extra.SESSION_ID": 1513445030,
    "android.content.pm.extra.LEGACY_STATUS": 1,
    "android.content.pm.extra.STATUS_MESSAGE": "INSTALL_SUCCEEDED: Session installed"
  },
  "msg": "OK",
  "request_id": "84d5716b8d374006b4cba9caaef794b6"
}

卸载应用

URL: /package/uninstall
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "n4o5p6q7r8s9t0u1v2w3"
}

设置应用启用状态

URL: /package/enabled
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名
enabled boolean 是是否启用

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "se123456"
}

获取已安装应用列表

URL: /package/list
方式: GET
参数:
参数名类型必选说明
type string 否 all=全部, system=系统应用, user=用户应用 (默认 user)

参数名	类型	必选	说明
type	string	否	`all`=全部, `system`=系统应用, `user`=用户应用 (默认 `user`)

返回示例:

json

{
  "code": 200,
  "data": {
    "type": "user",
    "count": 1,
    "packages": [
      {
        "package_name": "com.example.app",
        "app_name": "示例应用",
        "version_name": "1.0.0",
        "version_code": 1,
        "is_system": false,
        "enabled": true,
        "uid": 10123,
        "source_dir": "/data/app/...",
        "data_dir": "/data/user/0/..."
      }
    ]
  },
  "msg": "OK",
  "request_id": "l2m3n4o5p6q7r8s9t0u1"
}

导出应用 APK

如果应用是单一 APK，将返回原始 APK 二进制流。如果应用是分包（Split APKs），将自动打包成 ZIP 格式并返回二进制流。

URL: /package/export
方式: GET
参数:
参数名类型必选说明
package_name string 是应用包名
返回: APK 或 ZIP 二进制流。

清除应用数据

URL: /package/clear_data
方式: POST
参数:
参数名类型必选说明
package_name string 是应用包名

请求示例:

json

{
  "package_name": "com.android.settings"
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "b2c3d4e5f6g7h8i9j0a1"
}

输入控制 (Input)

点击

URL: /input/click
方式: POST
参数:
参数名类型必选说明
x int 是 X 坐标
y int 是 Y 坐标
请求示例:
json
```
{
  "x": 100,
  "y": 200
}
```

参数名	类型	必选	说明
x	int	是	X 坐标
y	int	是	Y 坐标

返回示例:

json

{
  "code": 200,
  "data": {
    "x": 100,
    "y": 200
  },
  "msg": "OK",
  "request_id": "d4e5f6g7h8i9j0a1b2c3"
}

多击

URL: /input/multi_click
方式: POST
参数:
参数名类型必选说明
x int 是 X 坐标
y int 是 Y 坐标
times int 否点击次数，默认 2
interval long 否点击间隔 (ms)，默认 100

参数名	类型	必选	说明
x	int	是	X 坐标
y	int	是	Y 坐标
times	int	否	点击次数，默认 2
interval	long	否	点击间隔 (ms)，默认 100

请求示例:

json

{
  "x": 100,
  "y": 200,
  "times": 3,
  "interval": 200
}

返回示例:

json

{
  "code": 200,
  "data": {
    "x": 100,
    "y": 200,
    "times": 3,
    "interval": 200
  },
  "msg": "OK",
  "request_id": "mc12345678"
}

输入文本

URL: /input/text
方式: POST
参数:
参数名类型必选说明
text string 是要输入的文本内容
请求示例:
json
```
{
  "text": "Hello World"
}
```

参数名	类型	必选	说明
text	string	是	要输入的文本内容

返回示例:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "e5f6g7h8i9j0a1b2c3d4"
}

按键

URL: /input/keyevent
方式: POST
参数:
参数名类型必选说明
key_code int 否单个按键 KeyCode (如 4=返回, 3=Home)
key_codes array 否组合按键列表 (如 [113, 29] 为 CTRL + A)
请求示例 (单按键):
json
```
{
  "key_code": 4
}
```

参数名	类型	必选	说明
key_code	int	否	单个按键 KeyCode (如 4=返回, 3=Home)
key_codes	array	否	组合按键列表 (如 [113, 29] 为 CTRL + A)

返回示例:

json

{
  "code": 200,
  "data": [4],
  "msg": "OK",
  "request_id": "f6g7h8i9j0a1b2c3d4e5"
}

滑动

URL: /input/swipe
方式: POST

参数:

参数名	类型	必选	说明
start_x	int	是	起点 X
start_y	int	是	起点 Y
end_x	int	是	终点 X
end_y	int	是	终点 Y
duration	int	否	持续时间 (ms)，默认 300
up_delay	long	否	松手延迟 (ms)，null 为立即松手，-1 为不松手

请求示例:

json

{
  "start_x": 100,
  "start_y": 800,
  "end_x": 100,
  "end_y": 200,
  "duration": 500
}

返回示例:

json

{
  "code": 200,
  "data": {
    "start_x": 100,
    "start_y": 800,
    "end_x": 100,
    "end_y": 200,
    "duration": 500,
    "up_delay": null
  },
  "msg": "OK",
  "request_id": "g7h8i9j0a1b2c3d4e5f6"
}

曲线滑动

URL: /input/scroll_bezier
方式: POST

参数:

参数名	类型	必选	说明
start_x	int	是	起点 X
start_y	int	是	起点 Y
end_x	int	是	终点 X
end_y	int	是	终点 Y
duration	int	否	持续时间 (ms)，默认 500
up_delay	long	否	松手延迟 (ms)，null 为立即松手，-1 为不松手
clear_fling	string	否	惯性消除策略: "repeat_last"=重复最后一个点消除惯性

请求示例:

json

{
  "start_x": 200,
  "start_y": 1600,
  "end_x": 200,
  "end_y": 200,
  "duration": 500
}

返回示例:

json

{
  "code": 200,
  "data": {
    "start_x": 200,
    "start_y": 1600,
    "end_x": 200,
    "end_y": 200,
    "duration": 500
  },
  "msg": "OK",
  "request_id": "8aca36b28c444ca09d07fb2690d03a3d"
}

原始 MotionEvent

需要 API 版本 1.1.0 及以上

同 Android MotionEvent

URL: /input/motion_event
方式: POST
参数:
参数名类型必选说明
events array 是 MotionEvent 事件列表，详见下方说明

参数名	类型	必选	说明
events	array	是	MotionEvent 事件列表，详见下方说明

Event 对象（同 MotionEvent.obtain()）：

参数名	类型	必选	默认值	说明
delay	long	否	0	发送此事件前的延迟 (ms)

参数名	类型	必选	默认值	说明
action	int	是	-	同 `action`，动作类型，见下方常量表
x	float	条件	-	同 `x`，X 坐标（单指必填，有 `pointer_properties` 时忽略）
y	float	条件	-	同 `y`，Y 坐标（单指必填，有 `pointer_properties` 时忽略）
pointer_properties	array	条件	-	同 `pointerProperties`，指针属性列表，见下方 PointerProperties 对象
pointer_coords	array	条件	-	同 `pointerCoords`，指针坐标列表，见下方 PointerCoords 对象
pressure	float	否	1.0	同 `pressure`，压力值（单指模式有效）
size	float	否	1.0	同 `size`，触摸面积（单指模式有效）
button_state	int	否	0	同 `buttonState`，鼠标/手写笔按键状态
down_time	long	否	当前时间	同 `downTime`，按下时间戳 (ms, uptimeMillis)
event_time	long	否	当前时间	同 `eventTime`，事件时间戳 (ms, uptimeMillis)
meta_state	int	否	0	同 `metaState`，修饰键状态
x_precision	float	否	1.0	同 `xPrecision`，X 轴精度
y_precision	float	否	1.0	同 `yPrecision`，Y 轴精度
device_id	int	否	0	同 `deviceId`，输入设备 ID
edge_flags	int	否	0	同 `edgeFlags`，边缘标志
source	int	否	4098	同 `source`，输入源 (SOURCE_TOUCHSCREEN=4098)
flags	int	否	0	同 `flags`，事件标志

PointerProperties 对象（同 MotionEvent.PointerProperties）：
参数名类型必选默认值说明
id int 是 - 同 id，指针 ID（跨事件保持一致）
tool_type int 否 1 同 toolType，工具类型：TOOL_TYPE_FINGER=1, TOOL_TYPE_STYLUS=2

参数名	类型	必选	默认值	说明
id	int	是	-	同 `id`，指针 ID（跨事件保持一致）
tool_type	int	否	1	同 `toolType`，工具类型：TOOL_TYPE_FINGER=1, TOOL_TYPE_STYLUS=2

PointerCoords 对象（同 MotionEvent.PointerCoords）：

参数名	类型	必选	默认值	说明
x	float	是	-	同 `x`，X 坐标
y	float	是	-	同 `y`，Y 坐标
pressure	float	否	1.0	同 `pressure`，压力值
size	float	否	1.0	同 `size`，触摸面积
touch_major	float	否	0.0	同 `touchMajor`，触摸区域长轴
touch_minor	float	否	0.0	同 `touchMinor`，触摸区域短轴
tool_major	float	否	0.0	同 `toolMajor`，工具长轴
tool_minor	float	否	0.0	同 `toolMinor`，工具短轴
orientation	float	否	0.0	同 `orientation`，方向角 (弧度)

Action 常量:

常量名	值	说明
ACTION_DOWN	0	按下
ACTION_UP	1	抬起
ACTION_MOVE	2	移动
ACTION_CANCEL	3	取消
ACTION_OUTSIDE	4	区域外点击
ACTION_POINTER_DOWN	5	多指按下
ACTION_POINTER_UP	6	多指抬起
ACTION_HOVER_MOVE	7	悬停移动
ACTION_SCROLL	8	滚动
ACTION_HOVER_ENTER	9	悬停进入
ACTION_HOVER_EXIT	10	悬停离开

请求示例:

json

{
  "events": [
    { "action": 0, "x": 100, "y": 200, "delay": 0 },
    { "action": 2, "x": 150, "y": 250, "delay": 50 },
    { "action": 1, "x": 200, "y": 300, "delay": 50 }
  ]
}

多指示例（双指放大）:

json

{
  "events": [
    { "action": 0, "pointer_properties": [{ "id": 0 }], "pointer_coords": [{ "x": 450, "y": 600 }] },
    { "action": 261, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 450, "y": 600 }, { "x": 550, "y": 700 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 425, "y": 575 }, { "x": 575, "y": 725 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 400, "y": 550 }, { "x": 600, "y": 750 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 375, "y": 525 }, { "x": 625, "y": 775 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 350, "y": 500 }, { "x": 650, "y": 800 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 325, "y": 475 }, { "x": 675, "y": 825 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 300, "y": 450 }, { "x": 700, "y": 850 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 275, "y": 425 }, { "x": 725, "y": 875 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 250, "y": 400 }, { "x": 750, "y": 900 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 225, "y": 375 }, { "x": 775, "y": 925 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 200, "y": 350 }, { "x": 800, "y": 950 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 175, "y": 325 }, { "x": 825, "y": 975 }] },
    { "action": 2, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 150, "y": 300 }, { "x": 850, "y": 1000 }] },
    { "action": 262, "pointer_properties": [{ "id": 0 }, { "id": 1 }], "pointer_coords": [{ "x": 150, "y": 300 }, { "x": 850, "y": 1000 }] },
    { "action": 1, "pointer_properties": [{ "id": 0 }], "pointer_coords": [{ "x": 150, "y": 300 }] }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": {
    "sent_count": 3
  },
  "msg": "OK",
  "request_id": "mot1234567890"
}

权限管理 (Permission)

获取应用权限

URL: /permission/get
方式: GET
参数:
参数名类型必选说明
package_name string 是应用包名

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "count": 2,
    "permissions": [
      { "permission": "android.permission.CAMERA", "granted": true },
      { "permission": "android.permission.RECORD_AUDIO", "granted": false }
    ]
  },
  "msg": "OK",
  "request_id": "per1234567890"
}

设置应用权限

URL: /permission/set
方式: POST

参数:

参数名	类型	必选	说明
package_name	string	是	应用包名
grant	boolean	是	true=授予, false=撤销
permissions	array	否	权限列表 (如 ["android.permission.CAMERA"])
grant_all	boolean	否	是否授予所有请求的权限
special_permission	boolean	否	是否授予特殊系统权限（包含悬浮窗、文件管理、录屏等）

特殊权限说明: 当 special_permission 为 true 时，将自动授予应用以下特殊权限：
- 悬浮窗: 允许应用在其他应用上层显示。
- 文件管理: 允许应用访问所有外部存储文件（Android 11+）。
- 录屏: 自动允许录屏请求，跳过系统安全确认。

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "grant": true,
    "success_count": 1
  },
  "msg": "OK",
  "request_id": "per0987654321"
}

文件管理 (File)

导入文件

URL: /file/import
方式: POST
Content-Type: multipart/form-data
参数:
参数名类型必选说明
dir_path string 是目标目录 (如 /sdcard/Download/)
file file 是文件字段，支持多个文件
scan boolean 否是否扫描媒体库，默认 true，只扫描多媒体文件

参数名	类型	必选	说明
dir_path	string	是	目标目录 (如 `/sdcard/Download/`)
file	file	是	文件字段，支持多个文件
scan	boolean	否	是否扫描媒体库，默认 `true`，只扫描多媒体文件

返回示例:

json

{
  "code": 200,
  "data": {
    "files": [
      {
        "file_path": "/sdcard/Download/image.jpg",
        "file_size": 123456,
        "scanned": true,
        "mime_type": "image/jpeg"
      }
    ]
  },
  "msg": "OK",
  "request_id": "t0u1v2w3x4y5z6a7b8c9"
}

导出文件

URL: /file/export
方式: GET
参数:
参数名类型必选说明
path string 是文件路径
返回: 文件二进制流。

参数名	类型	必选	说明
path	string	是	文件路径

导出文件（URL）

将设备上的文件导出为可下载的 URL，适用于批量导出场景。

URL: /file/export_url
方式: POST
Content-Type: application/json
参数:
参数名类型必选说明
paths string[] 是文件路径列表

参数名	类型	必选	说明
paths	string[]	是	文件路径列表

请求示例:

json

{
  "paths": ["/sdcard/test.txt", "/sdcard/photo.png"]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {"url": "/assets/sdcard/test.txt", "name": "test.txt", "size": 1024},
    {"url": "/assets/sdcard/photo.png", "name": "photo.png", "size": 204800}
  ],
  "msg": "OK",
  "request_id": "abc123"
}

说明:
- 返回的 url 为相对路径，需拼接设备地址访问（如 http://<设备IP>:18185/api/assets/sdcard/test.txt）
- 每个文件包含 url（下载地址）、name（文件名）、size（文件大小，字节）

扫描媒体文件

扫描指定的媒体文件到系统媒体库。只扫描图片、视频和音频文件。需要 API 版本 1.0.4 及以上支持。

URL: /file/media_scan
方式: POST
Content-Type: application/json
参数:
参数名类型必选说明
paths array 是文件路径列表
mime_types array 是 MIME 类型列表，与 paths 一一对应

参数名	类型	必选	说明
paths	array	是	文件路径列表
mime_types	array	是	MIME 类型列表，与 paths 一一对应

请求示例:

json

{
  "paths": [
    "/sdcard/Download/image.jpg",
    "/sdcard/Download/video.mp4"
  ],
  "mime_types": [
    "image/jpeg",
    "video/mp4"
  ]
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sm123456"
}

说明:
- paths 和 mime_types 必须一一对应，数量必须相同
- 只扫描多媒体文件（图片、视频、音频），其他文件类型会被自动过滤
- 如果路径对应的文件不存在或不是文件，会被跳过
- 返回 true 表示成功，false 表示失败

HTTP下载文件

需要 API 版本 1.0.7 及以上

URL: /file/download
方式: POST
参数:
参数名类型必选说明
url string 是下载地址（支持 http/https）
path string 是保存路径（如 /sdcard/Download/file.zip）
overwrite boolean 否是否覆盖已存在文件，默认 true

参数名	类型	必选	说明
url	string	是	下载地址（支持 http/https）
path	string	是	保存路径（如 `/sdcard/Download/file.zip`）
overwrite	boolean	否	是否覆盖已存在文件，默认 `true`

返回示例:

json

{
  "code": 200,
  "data": {
    "path": "/sdcard/Download/file.zip",
    "size": 1048576
  },
  "msg": "OK",
  "request_id": "a1b2c3d4e5f6g7h8i9j0"
}

列出目录内容

URL: /file/list
方式: GET
参数:
参数名类型必选说明
path string 是目录路径
show_hidden boolean 否是否显示隐藏文件 (默认 false)
请求示例:
json
```
{
  "path": "/sdcard"
}
```

参数名	类型	必选	说明
path	string	是	目录路径
show_hidden	boolean	否	是否显示隐藏文件 (默认 false)

返回示例:

json

{
  "code": 200,
  "data": {
    "path": "/sdcard",
    "count": 2,
    "files": [
      {
        "name": "Download",
        "absolute_path": "/sdcard/Download",
        "is_directory": true,
        "is_file": false,
        "size": 4096,
        "last_modified": 1736412345000,
        "can_read": true,
        "can_write": true,
        "can_execute": true
      }
    ]
  },
  "msg": "OK",
  "request_id": "u1v2w3x4y5z6a7b8c9d0"
}

系统设置 (System)

执行 Shell 命令

URL: /system/shell
方式: POST
参数:
参数名类型必选说明
command string 是要执行的 Shell 命令
is_root boolean 否是否以 root 用户执行 (默认 true)

参数名	类型	必选	说明
command	string	是	要执行的 Shell 命令
is_root	boolean	否	是否以 root 用户执行 (默认 true)

请求示例:

json

{
  "command": "ls -l /sdcard",
  "is_root": true
}

返回示例:

json

{
  "code": 200,
  "data": {
    "command": "ls -l /sdcard",
    "is_root": true,
    "exit_code": 0,
    "output": "total 0\ndrwxrwx--- 2 root ...",
    "error": ""
  },
  "msg": "OK",
  "request_id": "q7r8s9t0u1v2w3x4y5z6"
}

设置壁纸

URL: /system/wallpaper
方式: POST
参数:
参数名类型必选说明
path string 是图片路径 (实例内路径或 Assets 路径)
type string 否 file (默认) 或 asset

参数名	类型	必选	说明
path	string	是	图片路径 (实例内路径或 Assets 路径)
type	string	否	`file` (默认) 或 `asset`

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "wal1234567890"
}

更新系统设置

更新系统时区、语言和地区。需要镜像版本 20260113 及以上支持。

URL: /system/update_settings
方式: POST
参数:
参数名类型必选说明
timezone string 否时区 ID (如 Asia/Shanghai)
language string 否语言代码 (如 zh)
region string 否国家/地区代码 (如 CN)

参数名	类型	必选	说明
timezone	string	否	时区 ID (如 `Asia/Shanghai`)
language	string	否	语言代码 (如 `zh`)
region	string	否	国家/地区代码 (如 `CN`)

请求示例:

json

{
  "timezone": "Asia/Shanghai",
  "language": "zh",
  "region": "CN"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "timezone": "Asia/Shanghai",
    "language": "zh",
    "region": "CN"
  },
  "msg": "OK",
  "request_id": "us123456"
}

设置系统属性

设置 Android 系统属性 (System Properties)。需要镜像版本 20260113 及以上支持。

URL: /system/set_prop
方式: POST
参数:
参数名类型必选说明
properties object 否属性键值对 (Key-Value)，直接使用指定的 key
persist_properties object 否属性键值对 (Key-Value)，key 会自动加上系统前缀

参数名	类型	必选	说明
properties	object	否	属性键值对 (Key-Value)，直接使用指定的 key
persist_properties	object	否	属性键值对 (Key-Value)，key 会自动加上系统前缀

请求示例:

json

{
  "properties": {
    "persist.sys.test": "value1",
    "debug.test": "value2"
  },
  "persist_properties": {
    "test": "value1",
    "key2": "value2"
  }
}

说明:
- properties 中的 key 会直接使用，如 persist.sys.test 会设置为 persist.sys.test
- persist_properties 中的 key 会自动加上系统前缀
- 至少需要提供 properties 或 persist_properties 其中一个参数

返回示例:

json

{
  "code": 200,
  "data": {
    "persist.sys.test": true,
    "debug.test": true,
    "test": true,
    "key2": true
  },
  "msg": "OK",
  "request_id": "sp123456"
}

修改系统设置项

需要 API 版本 1.0.7 及以上

URL: /system/settings_put
方式: POST
说明: 等同于 settings put <namespace> <key> <value>，支持 secure / global / system 三个命名空间
参数:
参数名类型必选说明
namespace string 是命名空间，可选值：secure、global、system
key string 是设置项 key，如 default_input_method
value string 是要设置的值

参数名	类型	必选	说明
namespace	string	是	命名空间，可选值：`secure`、`global`、`system`
key	string	是	设置项 key，如 `default_input_method`
value	string	是	要设置的值

请求示例:

json

{
  "namespace": "secure",
  "key": "default_input_method",
  "value": "com.example.ime/.InputMethodService"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "namespace": "secure",
    "key": "default_input_method",
    "value": "com.example.ime/.InputMethodService"
  },
  "msg": "OK",
  "request_id": "sp123456"
}

查询系统设置项

需要 API 版本 1.0.7 及以上

URL: /system/settings_get
方式: POST
说明: 等同于 settings get <namespace> <key>，支持 secure / global / system 三个命名空间
参数:
参数名类型必选说明
namespace string 是命名空间，可选值：secure、global、system
key string 是设置项 key，如 default_input_method

参数名	类型	必选	说明
namespace	string	是	命名空间，可选值：`secure`、`global`、`system`
key	string	是	设置项 key，如 `default_input_method`

请求示例:

json

{
  "namespace": "secure",
  "key": "default_input_method"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "namespace": "secure",
    "key": "default_input_method",
    "value": "com.example.ime/.InputMethodService"
  },
  "msg": "OK",
  "request_id": "sg123456"
}

电源管理 (Power)

点亮 / 熄灭屏幕

URL: /power/set_screen
方式: POST
参数:
参数名类型必选说明
on boolean 是 true 为点亮屏幕, false 为熄灭屏幕
请求示例:
json
```
{
  "on": true
}
```

参数名	类型	必选	说明
on	boolean	是	`true` 为点亮屏幕, `false` 为熄灭屏幕

返回示例:

json

{
  "code": 200,
  "data": {
    "on": true
  },
  "msg": "OK",
  "request_id": "ps123456"
}

锁定 / 解锁屏幕

URL: /power/locked
方式: POST
参数:
参数名类型必选说明
locked boolean 是 true 为锁定屏幕, false 为解锁屏幕
请求示例:
json
```
{
  "locked": true
}
```

参数名	类型	必选	说明
locked	boolean	是	`true` 为锁定屏幕, `false` 为解锁屏幕

返回示例:

json

{
  "code": 200,
  "data": {
    "locked": true
  },
  "msg": "OK",
  "request_id": "pl123456"
}

获取屏幕与锁屏状态

URL: /power/status
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "is_screen_on": true,
    "is_locked": false
  },
  "msg": "OK",
  "request_id": "pst123456"
}

电池管理 (Battery)

获取电池信息

获取当前设备的电池状态信息。返回的数据为 Android BatteryManager Intent 的原始 extras 数据。

URL: /battery/get
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "technology": "Li-ion",
    "icon-small": 17303583,
    "max_charging_voltage": 4400000,
    "health": 2,
    "max_charging_current": 3250000,
    "status": 3,
    "plugged": 0,
    "present": true,
    "seq": 1941,
    "charge_counter": 5000,
    "level": 47,
    "scale": 100,
    "temperature": 338,
    "voltage": 3036,
    "invalid_charger": 0,
    "battery_low": false
  },
  "msg": "OK",
  "request_id": "bg123456"
}

返回字段说明:

字段名	类型	说明
level	int	当前电量值 (0-scale)，-1 表示未知
scale	int	最大电量值，通常为 100
status	int	电池状态，见下表
plugged	int	充电器连接类型，见下表
health	int	电池健康状态，见下表
voltage	int	电池电压 (mV)，-1 表示未知
temperature	int	电池温度 (0.1°C，需除以10得到摄氏度)，-1 表示未知
technology	string	电池技术类型 (如 `Li-ion`)，可能为 null
present	boolean	是否存在电池
icon-small	int	电池图标资源 ID
max_charging_voltage	int	最大充电电压 (微伏，需除以1000000得到伏特)
max_charging_current	int	最大充电电流 (微安，需除以1000000得到安培)
seq	int	电池状态序列号
charge_counter	int	电池充电计数器
invalid_charger	int	无效充电器标识：`0`=有效、`1`=无效
battery_low	boolean	是否低电量

status 电池状态:
值常量名说明
1 BATTERY_STATUS_UNKNOWN 未知
2 BATTERY_STATUS_CHARGING 充电中
3 BATTERY_STATUS_DISCHARGING 放电中
4 BATTERY_STATUS_NOT_CHARGING 未充电
5 BATTERY_STATUS_FULL 已充满

值	常量名	说明
1	BATTERY_STATUS_UNKNOWN	未知
2	BATTERY_STATUS_CHARGING	充电中
3	BATTERY_STATUS_DISCHARGING	放电中
4	BATTERY_STATUS_NOT_CHARGING	未充电
5	BATTERY_STATUS_FULL	已充满

health 电池健康:

值	常量名	说明
1	BATTERY_HEALTH_UNKNOWN	未知
2	BATTERY_HEALTH_GOOD	良好
3	BATTERY_HEALTH_OVERHEAT	过热
4	BATTERY_HEALTH_DEAD	损坏
5	BATTERY_HEALTH_OVER_VOLTAGE	过压
6	BATTERY_HEALTH_UNSPECIFIED_FAILURE	未知故障
7	BATTERY_HEALTH_COLD	过冷

plugged 充电方式:
值常量名说明
0 - 未连接
1 BATTERY_PLUGGED_AC AC充电
2 BATTERY_PLUGGED_USB USB充电
4 BATTERY_PLUGGED_WIRELESS 无线充电

值	常量名	说明
0	-	未连接
1	BATTERY_PLUGGED_AC	AC充电
2	BATTERY_PLUGGED_USB	USB充电
4	BATTERY_PLUGGED_WIRELESS	无线充电

设置电池信息

设置设备的电池信息，支持设置电量、状态、健康状态、温度、电压等参数。需要 API 版本 1.0.4 及以上支持。

URL: /battery/set
方式: POST

参数:

参数名	类型	必选	说明
level	int	否	电池电量 (0-100)
status	int	否	电池状态，见 `/battery/get` 接口说明
health	int	否	电池健康，见 `/battery/get` 接口说明
plugged	int	否	充电方式，见 `/battery/get` 接口说明

请求示例:

json

{
  "level": 85,
  "status": 2,
  "health": 2,
  "plugged": 2
}

返回示例:

json

{
  "code": 200,
  "data": {
    "technology": "Li-ion",
    "icon-small": 17303583,
    "max_charging_voltage": 4400000,
    "health": 2,
    "max_charging_current": 3250000,
    "status": 2,
    "plugged": 2,
    "present": true,
    "seq": 1941,
    "charge_counter": 5000,
    "level": 85,
    "scale": 100,
    "temperature": 300,
    "voltage": 4200,
    "invalid_charger": 0,
    "battery_low": false
  },
  "msg": "OK",
  "request_id": "bs123456"
}

说明:
- 返回数据为设置后的最新电池信息，格式与 /battery/get 接口相同
- 至少需要提供一个参数，否则会返回错误
- level 参数会被自动限制在 0-100 范围内
- status 和 health 参数必须为有效的枚举值，否则设置会被忽略
- 返回字段说明请参考 /battery/get 接口

本地化 (Locale)

获取本地化信息

获取系统支持的所有语言、国家/地区以及时区列表。

URL: /locale/list
方式: GET
参数:
参数名类型必选说明
display_languages array 否指定显示名称的语言代码列表，默认 ["zh", "en"]

返回示例:

json

{
  "code": 200,
  "data": {
    "languages": [
      { 
        "code": "zh", 
        "names": { "zh": "中文", "en": "Chinese" } 
      },
      { 
        "code": "en", 
        "names": { "zh": "英语", "en": "English" } 
      }
    ],
    "regions": [
      { 
        "code": "CN", 
        "names": { "zh": "中国", "en": "China" } 
      },
      { 
        "code": "US", 
        "names": { "zh": "美国", "en": "United States" } 
      }
    ],
    "time_zones": [
      {
        "id": "Asia/Shanghai",
        "names": { "zh": "中国标准时间 (上海)", "en": "China Standard Time (Shanghai)" },
        "offset": 28800000,
        "raw_offset": 28800000
      }
    ]
  },
  "msg": "OK",
  "request_id": "li123456"
}

剪贴板 (Clipboard)

设置剪贴板

URL: /clipboard/set
方式: POST
参数:
参数名类型必选说明
text string 是文本内容
请求示例:
json
```
{
  "text": "Hello World"
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "h8i9j0a1b2c3d4e5f6g7"
}

获取当前剪贴板

URL: /clipboard/get
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "text": "Hello World",
    "length": 11
  },
  "msg": "OK",
  "request_id": "i9j0a1b2c3d4e5f6g7h8"
}

获取剪贴板历史列表

URL: /clipboard/list
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 2,
    "mime_type": "text/plain",
    "items": ["Hello", "World"]
  },
  "msg": "OK",
  "request_id": "j0a1b2c3d4e5f6g7h8i9"
}

清空剪贴板

URL: /clipboard/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "k1l2m3n4o5p6q7r8s9t0"
}

屏幕与显示 (Display)

获取屏幕信息

URL: /display/info
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "width": 1080,
    "height": 1920,
    "rotation": 0,
    "orientation": 1
  },
  "msg": "OK",
  "request_id": "o5p6q7r8s9t0u1v2w3x4"
}

屏幕旋转

URL: /display/rotate
方式: POST
参数:
参数名类型必选说明
rotation int 是旋转角度：0=0°, 1=90°, 2=180°, 3=270°
请求示例:
json
```
{
  "rotation": 1
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "width": 1920,
    "height": 1080,
    "rotation": 1,
    "orientation": 0
  },
  "msg": "OK",
  "request_id": "p6q7r8s9t0u1v2w3x4y5"
}

屏幕截图（压缩）

URL: /screenshot/format
方式: GET
参数:
参数名类型必选说明
format string 否 webp, png, jpeg (默认 jpg)
quality int 否质量 (1-100)，默认 100
返回: 原始图片二进制流 (Content-Type: image/jpeg 等)。

获取截图

URL: /screenshot/raw
方式: GET
返回: 原始 RGBA 像素数据流 (ARGB_8888)。每个像素占 4 字节。

通话记录 (CallLog)

添加通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/add
方式: POST
参数:
参数名类型必选说明
number string 是电话号码
type int 否类型：1=来电, 2=去电, 3=未接 (默认 1)
date long 否时间戳，默认当前时间
duration long 否通话时长 (秒)，默认 0

请求示例:

json

{
  "number": "13800001234",
  "type": 1,
  "duration": 60
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "number": "13800001234",
      "type": 1,
      "type_name": "INCOMING_TYPE",
      "date": 1678888888000,
      "duration": 60,
      "new": 0,
      "cached_name": null,
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    }
  ],
  "msg": "OK",
  "request_id": "cla123456"
}

批量添加通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/add_list
方式: POST
参数:
参数名类型必选说明
calllog_list array 是通话记录列表，每项包含 number, type, date, duration

请求示例:

json

{
  "list": [
    { "number": "13800001234", "type": 1, "duration": 60 },
    { "number": "13900005678", "type": 2, "duration": 120 }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "number": "13800001234",
      "type": 1,
      "type_name": "INCOMING_TYPE",
      "date": 1678888888000,
      "duration": 60,
      "new": 0,
      "cached_name": null,
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    },
    {
      "_id": 2,
      "number": "13900005678",
      "type": 2,
      "type_name": "OUTGOING_TYPE",
      "date": 1678888889000,
      "duration": 120,
      "new": 0,
      "cached_name": null
    }
  ],
  "msg": "OK",
  "request_id": "clal123456"
}

删除通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/delete
方式: POST
参数:
参数名类型必选说明
id long 是通话记录 ID

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "cld123456"
}

批量删除通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/delete_list
方式: POST
参数:
参数名类型必选说明
ids array 是通话记录 ID 数组
请求示例:
json
```
{
  "ids": [1, 2, 3]
}
```

返回示例:

json

{
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "cldl123456"
}

说明: 返回数据为成功删除的记录条数。

清空通话记录

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": 15,
  "msg": "OK",
  "request_id": "clc123456"
}

说明: 返回数据为删除的记录条数。

获取通话记录列表

需要 API 版本 1.0.4 及以上支持。

URL: /calllog/list
方式: GET
参数:
参数名类型必选说明
limit int 否限制数量，默认 100
offset int 否偏移量，默认 0

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "number": "13800001234",
        "type": 1,
        "type_name": "INCOMING_TYPE",
        "date": 1678888888000,
        "duration": 60,
        "new": 0,
        "cached_name": "张三",
        "contact": {
          "_id": 3,
          "display_name": "张三"
        }
      }
    ]
  },
  "msg": "OK",
  "request_id": "cll123456"
}

返回字段说明:

字段名	类型	说明
_id	long	通话记录唯一 ID
number	string	电话号码
type	int	通话类型：1=来电, 2=去电, 3=未接, 4=语音信箱, 5=拒接, 6=拦截
type_name	string	通话类型常量名 (如 `INCOMING_TYPE`)
date	long	通话时间戳 (ms)
duration	long	通话时长 (秒)
new	int	是否为新记录：1=是, 0=否
cached_name	string	联系人姓名缓存 (可能为 null)
contact	object	联系人信息 (号码匹配时返回，包含 `_id` 和 `display_name`)

联系人管理 (Contact)

添加联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/add
方式: POST
参数:
参数名类型必选说明
name string 是姓名
phone string 是电话号码
email string 否邮箱
organization string 否公司/组织
title string 否职位
note string 否备注

请求示例:

json

{
  "name": "张三",
  "phone": "13800138000"
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "display_name": "张三",
      "has_phone_number": 1,
      "phones": ["13800138000"]
    }
  ],
  "msg": "OK",
  "request_id": "con1234567890"
}

批量添加联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/add_list
方式: POST
参数:
参数名类型必选说明
contact_list array 是联系人列表，每项包含 name, phone, email, organization, title, note

请求示例:

json

{
  "contact_list": [
    { "name": "张三", "phone": "13800138000" },
    { "name": "李四", "phone": "13900139000", "email": "lisi@example.com" }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "display_name": "张三",
      "has_phone_number": 1,
      "phones": ["13800138000"]
    },
    {
      "_id": 2,
      "display_name": "李四",
      "has_phone_number": 1,
      "phones": ["13900139000"]
    }
  ],
  "msg": "OK",
  "request_id": "cal123456"
}

删除联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/delete
方式: POST
参数:
参数名类型必选说明
id long 是联系人 ID
请求示例:
json
```
{
  "id": 1
}
```

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "cd123456"
}

批量删除联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/delete_list
方式: POST
参数:
参数名类型必选说明
ids array 是联系人 ID 数组
请求示例:
json
```
{
  "ids": [1, 2, 3]
}
```

返回示例:

json

{
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "cdl123456"
}

说明: 返回数据为成功删除的记录条数。

获取联系人列表

URL: /contact/list
方式: GET
参数:
参数名类型必选说明
offset int 否偏移量，默认 0
limit int 否限制数量，默认 100

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "display_name": "张三",
        "has_phone_number": 1,
        "phones": ["13800138000"]
      }
    ]
  },
  "msg": "OK",
  "request_id": "cl123456"
}

返回字段说明:
字段名类型说明
_id long 联系人唯一 ID
display_name string 联系人显示名称
has_phone_number int 是否有电话号码：1=有, 0=无
phones array 电话号码列表

条件查询联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/query
方式: POST
参数:
参数名类型必选说明
id long 否联系人 ID
name string 否联系人姓名（模糊匹配）
phone string 否电话号码
offset int 否偏移量，默认 0
limit int 否限制数量，默认 100
请求示例:
json
```
{
  "name": "张"
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "display_name": "张三",
        "has_phone_number": 1,
        "phones": ["13800001234"]
      }
    ]
  },
  "msg": "OK",
  "request_id": "cq123456"
}

说明: 支持按 ID、姓名（模糊匹配）、电话号码查询联系人。参数可组合使用，不传参数则返回所有联系人。

清空联系人

需要 API 版本 1.0.4 及以上支持。

URL: /contact/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": 5,
  "msg": "OK",
  "request_id": "cc123456"
}

说明: 返回数据为删除的记录条数。

短信管理 (SMS)

获取短信列表

URL: /sms/list
方式: GET

参数:

参数名	类型	必选	说明
type	int	否	短信类型 (0: 所有, 1: 收件箱, 2: 已发送, 3: 草稿, 4: 待发送, 5: 失败, 6: 队列)，默认 0
offset	int	否	偏移量，默认 0
limit	int	否	限制数量，默认 100

返回示例:

json

{
  "code": 200,
  "data": {
    "type": 0,
    "offset": 0,
    "limit": 100,
    "count": 1,
    "list": [
      {
        "_id": 1,
        "address": "13800001234",
        "body": "这是一条测试短信",
        "date": 1736412345000,
        "type": 1,
        "type_name": "MESSAGE_TYPE_INBOX",
        "read": 1,
        "seen": 1,
        "creator": "com.android.messaging",
        "contact": {
          "_id": 3,
          "display_name": "张三"
        }
      }
    ]
  },
  "msg": "OK",
  "request_id": "sl123456"
}

返回字段说明:

字段名	类型	说明
_id	long	短信唯一 ID
address	string	对方号码
body	string	短信内容
date	long	时间戳 (ms)
type	int	短信类型：1=收件箱, 2=已发送, 3=草稿, 4=待发送, 5=失败, 6=队列
type_name	string	短信类型常量名 (如 `MESSAGE_TYPE_INBOX`)
read	int	是否已读：1=是, 0=否
seen	int	是否已展示：1=是, 0=否
creator	string	创建者包名
contact	object	联系人信息 (号码匹配时返回，包含 `_id` 和 `display_name`)

添加短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/add
方式: POST

参数:

参数名	类型	必选	说明
address	string	是	对方号码
body	string	是	短信内容
type	int	否	短信类型 (1: 收件箱, 2: 已发送, 3: 草稿, 4: 待发送, 5: 失败, 6: 队列)，默认 1
date	long	否	时间戳，默认当前时间
read	boolean	否	是否已读，默认 `true`
seen	boolean	否	是否已展示，默认 `true`

请求示例:

json

{
  "address": "13800001234",
  "body": "这是一条测试短信。",
  "type": 1,
  "read": true,
  "seen": true
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "address": "13800001234",
      "body": "这是一条测试短信。",
      "date": 1736412345000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging",
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    }
  ],
  "msg": "OK",
  "request_id": "sa123456"
}

批量添加短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/add_list
方式: POST
参数:
参数名类型必选说明
sms_list array 是短信列表，每项包含 address, body, type, date, read, seen

请求示例:

json

{
  "list": [
    { "address": "13800001234", "body": "测试短信1", "type": 1 },
    { "address": "13900005678", "body": "测试短信2", "type": 1 }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "_id": 1,
      "address": "13800001234",
      "body": "测试短信1",
      "date": 1736412345000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging",
      "contact": {
        "_id": 3,
        "display_name": "张三"
      }
    },
    {
      "_id": 2,
      "address": "13900005678",
      "body": "测试短信2",
      "date": 1736412346000,
      "type": 1,
      "type_name": "MESSAGE_TYPE_INBOX",
      "read": 1,
      "seen": 1,
      "creator": "com.android.messaging"
    }
  ],
  "msg": "OK",
  "request_id": "sal123456"
}

接收短信（模拟发送短信）

模拟接收短信，会触发系统短信接收流程。需要 API 版本 1.0.4 及以上支持，当前支持 Android 13 / 14。

URL: /sms/receive
方式: POST
参数:
参数名类型必选说明
sender string 是发送者号码
body string 是短信内容

请求示例:

json

{
  "sender": "13800001234",
  "body": "您的验证码是 123456。"
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sr123456"
}

说明: 与 /sms/add 的区别是，此接口会触发完整的短信接收流程，包括系统通知、广播等，而 /sms/add 只是向数据库中添加记录。

删除短信

URL: /sms/delete
方式: POST
参数:
参数名类型必选说明
id long 是短信 ID

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "sd123456"
}

批量删除短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/delete_list
方式: POST
参数:
参数名类型必选说明
ids array 是短信 ID 数组
请求示例:
json
```
{
  "ids": [1, 2, 3]
}
```

返回示例:

json

{
  "code": 200,
  "data": 3,
  "msg": "OK",
  "request_id": "sdl123456"
}

说明: 返回数据为成功删除的记录条数。

清空短信

需要 API 版本 1.0.4 及以上支持。

URL: /sms/clear
方式: POST

返回示例:

json

{
  "code": 200,
  "data": 20,
  "msg": "OK",
  "request_id": "sc123456"
}

说明: 返回数据为删除的记录条数。

位置管理 (Location)

获取位置信息

获取当前设备的 GPS 位置信息。需要 API 版本 1.0.4 及以上支持。

URL: /location/get_data
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "latitude": 39.9042,
    "longitude": 116.4074,
    "altitude": 0.0,
    "speed": 0.0,
    "bearing": 0.0,
    "accuracy": 50.0,
    "vertical_accuracy_meters": 50.0,
    "speed_accuracy_meters_per_second": 1.0,
    "bearing_accuracy_degrees": 30.0,
    "enabled": true,
    "time": 1673641234567,
    "provider": "gps"
  },
  "msg": "OK",
  "request_id": "lg123456"
}

返回字段说明:

字段名	类型	说明
latitude	double	纬度
longitude	double	经度
altitude	double	海拔 (米)
speed	double	速度 (米/秒)
bearing	double	方向 (角度)
accuracy	float	水平精度 (米)
vertical_accuracy_meters	float	垂直精度 (米)
speed_accuracy_meters_per_second	float	速度精度 (米/秒)
bearing_accuracy_degrees	float	方向精度 (角度)
enabled	boolean	模拟定位是否已开启
time	long	位置获取的时间戳 (ms)
provider	string	位置提供者 (如 `gps`, `network`, `properties`)

设置位置信息

模拟设备的 GPS 位置信息。需要 API 版本 1.0.4 及以上支持。

URL: /location/set_data
方式: POST

参数:

参数名	类型	必选	说明
enabled	boolean	否	是否开启模拟定位
persist	boolean	否	是否持久化（重启后是否生效），默认 `false`
latitude	double	否	纬度
longitude	double	否	经度
altitude	double	否	海拔 (米)，默认 `0.0`
speed	double	否	速度 (米/秒)，默认 `0.0`
bearing	double	否	方向 (角度)，默认 `0.0`
accuracy	double	否	水平精度 (米)，默认 `50.0`
vertical_accuracy_meters	double	否	垂直精度 (米)，默认 `50.0`
speed_accuracy_meters_per_second	double	否	速度精度 (米/秒)，默认 `1.0`
bearing_accuracy_degrees	double	否	方向精度 (角度)，默认 `30.0`

请求示例:

json

{
  "latitude": 39.9042,
  "longitude": 116.4074,
  "vertical_accuracy_meters": 50.0,
  "enabled": true,
  "persist": true
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "ls123456"
}

传感器管理 (Sensor)

获取传感器列表

获取系统支持的所有传感器信息。需要 API 版本 1.0.4 及以上支持。

URL: /sensor/list
方式: GET
参数:
参数名类型必选说明
type int 否传感器类型 ID，不传则返回所有

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "name": "Goldfish 3-axis Accelerometer",
      "type": 1,
      "type_name": "TYPE_ACCELEROMETER",
      "vendor": "The Android Open Source Project",
      "version": 1,
      "resolution": 0.0,
      "power": 0.0,
      "min_delay": 0,
      "string_type": "android.sensor.accelerometer"
    }
  ],
  "msg": "OK",
  "request_id": "sl123456"
}

返回字段说明:

字段名	类型	说明
name	string	传感器名称
type	int	传感器类型 ID
type_name	string	传感器类型常量名
vendor	string	传感器厂商
version	int	传感器版本
resolution	float	传感器分辨率
power	float	功耗 (mA)
min_delay	int	最小采样间隔 (微秒)
string_type	string	传感器类型字符串

获取传感器数据

获取当前传感器的实时数据。需要 API 版本 1.0.4 及以上支持。

URL: /sensor/get_data
方式: GET
参数:
参数名类型必选说明
type int 否传感器类型 ID (如 1=加速度)，不传则返回所有传感器数据
timeout long 否获取数据的超时时间 (ms)，默认 500

返回示例 (单个传感器):

json

{
  "code": 200,
  "data": {
    "type": 1,
    "type_name": "TYPE_ACCELEROMETER",
    "name": "Goldfish 3-axis Accelerometer",
    "values": [0.0, 9.8, 0.0],
    "timestamp": 1673641234567
  },
  "msg": "OK",
  "request_id": "sg123456"
}

返回示例 (所有传感器):

json

{
  "code": 200,
  "data": {
    "sensors": [
      {
        "type": 1,
        "type_name": "TYPE_ACCELEROMETER",
        "name": "Goldfish 3-axis Accelerometer",
        "values": [0.0, 9.8, 0.0]
      }
    ],
    "timestamp": 1673641234567
  },
  "msg": "OK",
  "request_id": "sg123456"
}

设置传感器数据

设置虚拟传感器的模拟数据。需要 API 版本 1.0.4 及以上支持。

URL: /sensor/set_data
方式: POST
参数:
参数名类型必选说明
sensors array 是传感器数据列表

Sensor 对象说明:

参数名	类型	必选	说明
type	int	是	传感器类型，见下表
value	double	否	单值传感器的值 (如光线、压力、距离、湿度、温度、步数等)
x	double	否	三轴传感器的 X 轴值 (如加速度、磁场、陀螺仪等)
y	double	否	三轴传感器的 Y 轴值
z	double	否	三轴传感器的 Z 轴值

传感器类型:

type	常量名	说明
1	TYPE_ACCELEROMETER	加速度传感器
2	TYPE_MAGNETIC_FIELD	磁场传感器
3	TYPE_ORIENTATION	方向传感器
4	TYPE_GYROSCOPE	陀螺仪传感器
5	TYPE_LIGHT	光线传感器
6	TYPE_PRESSURE	压力传感器
8	TYPE_PROXIMITY	距离传感器
9	TYPE_GRAVITY	重力传感器
10	TYPE_LINEAR_ACCELERATION	线性加速度传感器
11	TYPE_ROTATION_VECTOR	旋转向量传感器
12	TYPE_RELATIVE_HUMIDITY	湿度传感器
13	TYPE_AMBIENT_TEMPERATURE	温度传感器
14	TYPE_MAGNETIC_FIELD_UNCALIBRATED	未校准磁场传感器
15	TYPE_GAME_ROTATION_VECTOR	游戏旋转向量传感器
16	TYPE_GYROSCOPE_UNCALIBRATED	未校准陀螺仪传感器
17	TYPE_SIGNIFICANT_MOTION	显著运动传感器
18	TYPE_STEP_DETECTOR	步数检测传感器
19	TYPE_STEP_COUNTER	步数计数传感器
20	TYPE_GEOMAGNETIC_ROTATION_VECTOR	地磁旋转向量传感器
21	TYPE_HEART_RATE	心率传感器
22	TYPE_TILT_DETECTOR	倾斜检测传感器
25	TYPE_PICK_UP_GESTURE	拿起手势传感器
26	TYPE_WRIST_TILT_GESTURE	手腕倾斜传感器
27	TYPE_DEVICE_ORIENTATION	设备方向传感器
30	TYPE_MOTION_DETECT	运动检测传感器
35	TYPE_ACCELEROMETER_UNCALIBRATED	未校准加速度传感器
36	TYPE_HINGE_ANGLE	铰链角度传感器

请求示例:

json

{
  "sensors": [
    {
      "type": 5,
      "value": 100.0
    },
    {
      "type": 2,
      "x": 1.0,
      "y": 2.0,
      "z": 3.0
    }
  ]
}

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "ss123456"
}

账号管理 (Account)

添加账号

URL: /account/add
方式: POST
参数:
参数名类型必选说明
name string 是账号名 (如 example@gmail.com)
type string 是账号类型 (如 com.google)
password string 否密码
user_data object 否用户自定义数据 (Key-Value)

请求示例:

json

{
  "name": "test_user",
  "type": "com.example.account",
  "password": "password123",
  "user_data": {
    "key1": "value1"
  }
}

返回示例:

json

{
  "code": 200,
  "data": {
    "name": "test_user",
    "type": "com.example.account"
  },
  "msg": "OK",
  "request_id": "aa123456"
}

获取账号列表

URL: /account/list
方式: GET
参数:
参数名类型必选说明
type string 否过滤账号类型

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "accounts": [
      { "name": "test_user", "type": "com.example.account" }
    ]
  },
  "msg": "OK",
  "request_id": "al123456"
}

删除账号

URL: /account/delete
方式: POST
参数:
参数名类型必选说明
name string 是账号名
type string 是账号类型

返回示例:

json

{
  "code": 200,
  "data": {
    "name": "test_user",
    "type": "com.example.account"
  },
  "msg": "OK",
  "request_id": "ad123456"
}

多媒体与音频 (Media)

设置音量

URL: /media/set_volume
方式: POST

参数:

参数名	类型	必选	说明
stream_type	string	是	音量类型：`music`=媒体, `voice_call`=通话, `ring`=铃声, `alarm`=闹钟, `notification`=通知
volume	int	是	音量值 (0 到最大值)
show_ui	boolean	否	是否显示系统音量 UI (默认 `true`)

请求示例:

json

{
  "stream_type": "music",
  "volume": 8
}

返回示例:

json

{
  "code": 200,
  "data": {
    "stream_type": "music",
    "volume": 8
  },
  "msg": "OK",
  "request_id": "sv123456"
}

静音 / 取消静音

URL: /media/mute
方式: POST
参数:
参数名类型必选说明
mute boolean 是 true 为静音，false 为取消静音

返回示例:

json

{
  "code": 200,
  "data": {
    "mute": true
  },
  "msg": "OK",
  "request_id": "mu123456"
}

获取音量信息

URL: /media/get_volume
方式: GET

返回示例:

json

{
  "code": 200,
  "data": {
    "music": { "current": 8, "max": 15 },
    "voice_call": { "current": 5, "max": 10 },
    "ring": { "current": 10, "max": 15 },
    "is_mute": false
  },
  "msg": "OK",
  "request_id": "vi123456"
}

无障碍 (Accessibility)

导出 UI 层次结构

URL: /accessibility/dump
方式: GET

返回示例:

json

{
  "code": 200,
  "data": "<?xml version='1.0' encoding='UTF-8' standalone='yes' ?><hierarchy ...",
  "msg": "OK",
  "request_id": "r8s9t0u1v2w3x4y5z6a7"
}

UI 节点操作

统一的节点查找与操作接口，支持查找、等待、执行动作。需要镜像版本 20260201 及以上支持。

URL: /accessibility/node
方式: POST

参数:

参数名	类型	必选	说明
selector	object	是	节点选择器，包含查找条件
wait_timeout	long	否	等待超时时间 (ms)，默认 0 表示不等待
wait_interval	long	否	等待间隔 (ms)，默认 500
action	string	否	要执行的动作名称 (如 `click`, `set_text`)
action_params	object	否	动作参数 (如 `text`)
action_index	int	否	对第几个匹配的节点执行动作，默认 0

Selector 选择器参数:

参数名	类型	必选	说明
xpath	string	否	XPath 表达式，优先级最高
text	string	否	节点文本。支持正则表达式匹配（如 `.设置.`）
content_desc	string	否	节点内容描述。支持正则表达式
name	string	否	节点文本或内容描述。支持正则表达式
class	string	否	节点类名 (class)
resource_id	string	否	节点资源 ID (resource-id)
package	string	否	应用包名
index	int	否	节点在其父节点中的索引
clickable	boolean	否	是否可点击
enabled	boolean	否	是否启用
scrollable	boolean	否	是否可滚动
focusable	boolean	否	是否可聚焦
focused	boolean	否	是否已聚焦
selected	boolean	否	是否已选中
checkable	boolean	否	是否可勾选
checked	boolean	否	是否已勾选
center_x	int	否	节点中心 X 坐标
center_y	int	否	节点中心 Y 坐标

支持的 Action 动作:
- click: 点击
- long_click: 长按
- set_text: 设置文本 (需参数 text)
- clear_text: 清除文本
- scroll_forward / scroll_backward: 向前/向后滚动
- scroll_up / scroll_down / scroll_left / scroll_right: 方向滚动
- focus / clear_focus: 获取/清除焦点
- select / clear_selection: 选中/取消选中
- copy / paste / cut: 剪贴板操作
- expand / collapse: 展开/折叠
- ime_enter: 输入法确定

请求示例 (文本精准匹配):

json

{
  "selector": {
    "text": "设置"
  },
  "action": "click"
}

请求示例 (XPath 匹配):

json

{
  "selector": {
    "xpath": "//node[@text='设置' and @clickable='true']"
  },
  "action": "click"
}

请求示例 (等待并设置文本):

json

{
  "selector": {
    "resource_id": "com.example:id/input"
  },
  "wait_timeout": 5000,
  "action": "set_text",
  "action_params": {
    "text": "Hello"
  }
}

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "nodes": [ ... ],
    "action": "click",
    "action_index": 0,
    "action_node": { ... }
  },
  "msg": "OK",
  "request_id": "an123456"
}

设置无障碍服务隐藏状态

设置指定应用是否在无障碍服务列表中隐藏。需要镜像版本 20260113 及以上支持。

URL: /accessibility/set_hidden
方式: POST
参数:
参数名类型必选说明
package_names array 是无障碍服务包名数组
hidden boolean 否是否隐藏，默认 true

返回示例:

json

{
  "code": 200,
  "data": ["com.example.service1", "com.example.service2"],
  "msg": "OK",
  "request_id": "sh123456"
}

获取无障碍服务隐藏状态

获取当前处于隐藏状态的无障碍服务包名列表。需要镜像版本 20260113 及以上支持。

URL: /accessibility/get_hidden
方式: GET

返回示例:

json

{
  "code": 200,
  "data": ["com.example.service1", "com.example.service2"],
  "msg": "OK",
  "request_id": "gh123456"
}

通知管理 (Notification)

获取活跃通知列表

URL: /notification/list
方式: GET
参数:
参数名类型必选说明
package_name string 否过滤指定应用的通知

返回示例:

json

{
  "code": 200,
  "data": {
    "count": 1,
    "notifications": [
      {
        "package_name": "com.android.settings",
        "id": 1,
        "key": "0|com.android.settings|1|null|1000",
        "title": "通知标题",
        "text": "通知内容",
        "post_time": 1736412345000,
        "is_ongoing": false,
        "is_clearable": true,
        "priority": 0
      }
    ]
  },
  "msg": "OK",
  "request_id": "v2w3x4y5z6a7b8c9d0e1"
}

获取应用通知渠道列表

URL: /notification/channels
方式: GET
参数:
参数名类型必选说明
package_name string 是应用包名

返回示例:

json

{
  "code": 200,
  "data": {
    "package_name": "com.example.app",
    "count": 1,
    "channels": [
      {
        "id": "channel_id",
        "name": "渠道名称",
        "importance": 3,
        "description": "渠道描述"
      }
    ]
  },
  "msg": "OK",
  "request_id": "nc123456"
}

设备信息 (Device)

随机机型信息

随机生成并设置云机的机型信息。注意：该接口仅支持虚拟机类型云机。

URL: /device/random_model
方式: POST
参数:
参数名类型必选说明
is_china boolean 否是否仅随机中国机型，默认 false

返回示例:

json

{
  "code": 200,
  "data": {
    "manufacturer": "Xiaomi",
    "model": "MI 11",
    "brand": "Xiaomi",
    "device": "cetus",
    "product": "cetus",
    "hardware": "qcom"
  },
  "msg": "OK",
  "request_id": "s9t0u1v2w3x4y5z6a7b8"
}

Google 服务 (Google)

启用/禁用谷歌套件

启用或禁用完整的谷歌服务套件（包含 GMS 核心、Play 商店、服务框架等）。

URL: /google/set_enabled
方式: POST
参数:
参数名类型必选说明
enabled boolean 是 true 为启用, false 为禁用

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "gs123456"
}

重置 GAID

重置 Google 广告 ID (GAID)。

URL: /google/reset_gaid
方式: POST
参数:
参数名类型必选说明
gaid string 否指定 GAID，不传则随机生成

返回示例:

json

{
  "code": 200,
  "data": "550e8400-e29b-41d4-a716-446655440000",
  "msg": "OK",
  "request_id": "gr123456"
}

获取谷歌套件启用状态

获取当前谷歌服务套件的启用状态。只有套件内所有组件均处于启用状态，返回 true。

URL: /google/get_enabled
方式: GET

返回示例:

json

{
  "code": 200,
  "data": true,
  "msg": "OK",
  "request_id": "gst123456"
}

工作流 (Workflow)

提交工作流

提交工作流脚本异步执行。单例模式，同一时间只能执行一个工作流。

URL: /workflow/execute
方式: POST

参数:

参数名	类型	必选	说明
id	string	是	工作流 ID
name	string	是	工作流名称
description	string	否	工作流描述
version	string	否	版本号，默认 `"1.0.0"`
content	object	是	脚本内容，结构见下方

content 对象结构:

参数名	类型	必选	说明
steps	object	是	步骤定义（key 为步骤 ID，value 为 WorkflowStep）
flow	array	是	执行顺序（步骤 ID 列表）
exception_handlers	array	否	异常处理器列表，元素结构见下方
timeout	integer	否	超时时间（毫秒）

WorkflowStep 结构（参见执行工作流步骤）

exception_handlers 元素结构:

参数名	类型	必选	说明
selector	object	是	节点选择器
action	string	否	处理动作，默认 `"click"`
name	string	否	处理器名称
action_params	object	否	动作参数
max_trigger_count	integer	否	最大触发次数，默认 `3`

请求示例:

json

{
  "id": "demo_workflow",
  "name": "打开设置并点击",
  "content": {
    "steps": {
      "open_settings": {
        "description": "打开系统设置",
        "actions": [
          {
            "path": "activity/start",
            "params": { "package_name": "com.android.settings" }
          }
        ]
      },
      "wait_and_click": {
        "description": "等待并点击目标",
        "actions": [
          {
            "path": "accessibility/find_and_click",
            "params": { "text": "显示" },
            "throw_if_empty": ["clicked"]
          }
        ],
        "completed": "success",
        "loop": { "max_count": 5, "interval": 1000 }
      }
    },
    "flow": ["open_settings", "wait_and_click"],
    "exception_handlers": [
      {
        "name": "关闭弹窗",
        "selector": { "text": "关闭" },
        "action": "click",
        "max_trigger_count": 3
      }
    ]
  }
}

返回示例:

json

{
  "code": 200,
  "data": {
    "execution_id": "a1b2c3d4e5f6",
    "workflow_id": "demo_workflow",
    "workflow_name": "打开设置并点击",
    "status": "PENDING",
    "start_time": null,
    "end_time": null,
    "variables": null,
    "error": null,
    "records": []
  },
  "msg": "OK",
  "request_id": "xxx"
}

查询当前执行

查询当前正在运行的工作流执行信息。

URL: /workflow/current_execution
方式: GET

返回示例（有运行中的工作流）:

json

{
  "code": 200,
  "data": {
    "execution_id": "a1b2c3d4e5f6",
    "workflow_id": "demo_workflow",
    "workflow_name": "打开设置并点击",
    "status": "RUNNING",
    "start_time": 1709000000000,
    "end_time": null,
    "variables": null,
    "error": null,
    "records": [
      {
        "step_id": "open_settings",
        "succeed": true,
        "error": null,
        "start_time": 1709000000000,
        "end_time": 1709000001000,
        "duration": 1000,
        "action_results": [{"package_name": "com.android.settings"}]
      }
    ]
  },
  "msg": "OK",
  "request_id": "xxx"
}

返回示例（无运行中的工作流）:

json

{
  "code": 200,
  "data": { "running": false },
  "msg": "OK",
  "request_id": "xxx"
}

查询执行详情

根据 execution_id 查询工作流执行信息（优先查当前执行，再查历史）。

URL: /workflow/execution_get
方式: POST
参数:
参数名类型必选说明
execution_id string 是工作流执行 ID
请求示例:
json
```
{
  "execution_id": "a1b2c3d4e5f6"
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "execution_id": "a1b2c3d4e5f6",
    "workflow_id": "demo_workflow",
    "workflow_name": "打开设置并点击",
    "status": "COMPLETED",
    "start_time": 1709000000000,
    "end_time": 1709000010000,
    "variables": null,
    "error": null,
    "records": [
      {
        "step_id": "open_settings",
        "succeed": true,
        "error": null,
        "start_time": 1709000000000,
        "end_time": 1709000001000,
        "duration": 1000,
        "action_results": [{"package_name": "com.android.settings"}]
      },
      {
        "step_id": "wait_and_click",
        "succeed": true,
        "error": null,
        "start_time": 1709000001000,
        "end_time": 1709000005000,
        "duration": 4000,
        "action_results": [{"clicked": true}]
      }
    ]
  },
  "msg": "OK",
  "request_id": "xxx"
}

查询执行历史

查询工作流执行历史记录。

URL: /workflow/execution_history
方式: POST
参数:
参数名类型必选说明
workflow_id string 否按工作流 ID 过滤
limit integer 否返回条数，默认 50

请求示例:

json

{
  "workflow_id": "demo_workflow",
  "limit": 10
}

返回示例:

json

{
  "code": 200,
  "data": [
    {
      "execution_id": "a1b2c3d4e5f6",
      "workflow_id": "demo_workflow",
      "workflow_name": "打开设置并点击",
      "status": "COMPLETED",
      "start_time": 1709000000000,
      "end_time": 1709000010000,
      "variables": null,
      "error": null,
      "records": [
        {
          "step_id": "open_settings",
          "succeed": true,
          "error": null,
          "start_time": 1709000000000,
          "end_time": 1709000001000,
          "duration": 1000,
          "action_results": [{"package_name": "com.android.settings"}]
        }
      ]
    }
  ],
  "msg": "OK",
  "request_id": "xxx"
}

取消执行

取消当前正在执行的工作流。

URL: /workflow/cancel
方式: POST

返回示例:

json

{
  "code": 200,
  "data": { "success": true, "message": "Workflow cancelled" },
  "msg": "OK",
  "request_id": "xxx"
}

执行工作流步骤

同步执行一个工作流步骤（一组 action 的组合）。与「提交工作流」不同，此接口为同步调用，会等待所有 action 执行完毕后返回结果。适用于不需要完整工作流编排、只想快速执行一组操作的场景。

支持两种循环模式：

固定次数循环（count）：执行指定次数后结束，不检查 completed 条件
条件循环（max_count + completed）：最多执行指定次数，每次执行后检查 completed 条件，满足则提前退出
URL: /workflow/run_step
方式: POST

参数:

参数名	类型	必选	说明
actions	array	是	动作列表，结构见下方
description	string	否	步骤描述，用于日志和返回结果中的 `step_name`
completed	string	否	完成条件。目前支持 `"success"`：所有 action 执行成功即视为完成
loop	object	否	循环配置，不传则只执行一次

actions 元素结构:

参数名	类型	必选	说明
path	string	是	接口路径（如 `"screenshot"`、`"activity/start"`）
params	object	否	接口参数
throw_if_empty	array	否	结果校验：指定的 key 在返回结果中为 null 或空时抛出异常。例如 `["nodes"]` 表示返回结果中 `nodes` 字段不能为空

loop 循环配置:

参数名	类型	必选	说明
count	integer	否	固定循环次数。设为 `-1` 表示无限循环（需外部取消）
max_count	integer	否	最大循环次数，配合 `completed` 使用，满足条件则提前退出。设为 `-1` 表示无限循环直到成功
interval	integer	否	每次循环前的等待间隔（毫秒），默认 `0`

count 和 max_count 二选一。count 用于"执行 N 次不管结果"的场景；max_count 用于"重试直到成功"的场景。

请求示例（简单执行）:

json

{
  "description": "截屏并获取已安装应用",
  "actions": [
    { "path": "screenshot", "params": {} },
    { "path": "package/list", "params": {} }
  ]
}

请求示例（固定循环 3 次）:

json

{
  "description": "向下滑动 3 次",
  "actions": [
    {
      "path": "input/scroll_bezier",
      "params": { "start_x": 540, "start_y": 1200, "end_x": 540, "end_y": 400, "duration": 500 }
    },
    { "path": "base/sleep", "params": { "duration": 800 } }
  ],
  "loop": { "count": 3 }
}

请求示例（重试直到成功，最多 10 次）:

json

{
  "description": "等待登录按钮出现",
  "actions": [
    {
      "path": "accessibility/find_nodes",
      "params": { "text": "登录" },
      "throw_if_empty": ["nodes"]
    }
  ],
  "completed": "success",
  "loop": {
    "max_count": 10,
    "interval": 1000
  }
}

返回示例（成功）:

json

{
  "code": 200,
  "data": {
    "step_id": "a1b2c3d4",
    "succeed": true,
    "error": null,
    "start_time": 1709000000000,
    "end_time": 1709000005000,
    "duration": 5000,
    "action_results": [{ "nodes": [{"text": "登录", "bounds": "..."}] }]
  },
  "msg": "OK",
  "request_id": "rs123456"
}

返回示例（循环执行）:

json

{
  "code": 200,
  "data": {
    "step_id": "b2c3d4e5",
    "succeed": true,
    "error": null,
    "start_time": 1709000000000,
    "end_time": 1709000006000,
    "duration": 6000,
    "action_results": [null, null]
  },
  "msg": "OK",
  "request_id": "rs789012"
}

AI Agent

AI Agent 是一个基于大语言模型（LLM）的智能任务执行引擎，能够自主理解用户意图并通过工具调用完成复杂的 Android 设备操作任务。

设置 API 配置

URL: /ai_agent/config_set
方式: POST
说明: 设置 AI Agent 的 LLM API 配置。至少需要提供一个配置参数，仅更新传入的字段，未传入的字段保持不变。

参数:

参数名	类型	必选	说明
provider	string	否	LLM 提供商（如 `dashscope`、`openai`、`anthropic`）
model	string	否	模型名称（如 `qwen-flash`、`gpt-4o`）
base_url	string	否	API 基础 URL
api_key	string	否	API Key
max_turns	integer	否	最大工具调用轮次（默认 50）
system_prompt	string	否	系统提示词
api_type	string	否	API 类型：`chat_completions`（默认）或 `responses`

请求示例:

json

{
  "provider": "openai",
  "model": "gpt-4o",
  "base_url": "https://api.openai.com/v1",
  "api_key": "sk-xxxxx"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "saved": true
  },
  "msg": "OK",
  "request_id": "ag123456"
}

获取 API 配置

URL: /ai_agent/config_get
方式: POST
参数: 无

返回示例:

json

{
  "code": 200,
  "data": {
    "provider": "openai",
    "model": "gpt-4o",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-xxxxx",
    "max_turns": 50,
    "api_type": "chat_completions"
  },
  "msg": "OK",
  "request_id": "ag234567"
}

启动任务

URL: /ai_agent/task_run
方式: POST
说明: 异步启动一个 AI Agent 任务，立即返回 task_id。可通过 SSE 端点 /api/ai_agent/task_stream?task_id=xxx 获取实时执行进度。使用前需先通过 config_set 设置 API 配置。

参数:

参数名	类型	必选	说明
task	string	是	任务描述（自然语言）
model	string	否	覆盖配置中的模型名称
max_turns	integer	否	覆盖配置中的最大轮次
system_prompt	string	否	覆盖配置中的系统提示词
api_type	string	否	覆盖配置中的 API 类型

请求示例:

json

{
  "task": "打开设置，查看当前 WiFi 名称"
}

返回示例:

json

{
  "code": 200,
  "data": {
    "task_id": "r_abc123",
    "status": "running"
  },
  "msg": "OK",
  "request_id": "ag345678"
}

查询任务状态

URL: /ai_agent/task_status
方式: POST
说明: 获取当前运行中任务的状态和已累积的事件列表，适用于客户端断线重连场景。
参数: 无

返回示例（有运行中的任务）:

json

{
  "code": 200,
  "data": {
    "task_id": "r_abc123",
    "status": "running",
    "task": "打开设置，查看当前 WiFi 名称",
    "created_at": 1709000000000,
    "finished_at": 0,
    "events": [
      {
        "taskId": "r_abc123",
        "type": "RUN_STARTED",
        "timestamp": 1709000000100
      },
      {
        "taskId": "r_abc123",
        "type": "LLM_RESPONSE",
        "turn": 1,
        "content": "我需要先打开设置应用",
        "toolCalls": [
          {
            "id": "call_001",
            "name": "activity_start",
            "arguments": "{\"package_name\":\"com.android.settings\"}"
          }
        ],
        "timestamp": 1709000002000
      }
    ]
  },
  "msg": "OK",
  "request_id": "ag456789"
}

返回示例（无运行中的任务）:

json

{
  "code": 200,
  "data": {
    "status": "idle",
    "message": "当前没有运行中的任务"
  },
  "msg": "OK",
  "request_id": "ag567890"
}

停止任务

URL: /ai_agent/task_stop
方式: POST
说明: 通过 task_id 停止指定的正在执行的任务。
参数:
参数名类型必选说明
task_id string 是任务 ID
请求示例:
json
```
{
  "task_id": "r_abc123"
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "stopped": true,
    "task_id": "r_abc123"
  },
  "msg": "OK",
  "request_id": "ag678901"
}

查询任务列表

URL: /ai_agent/task_list
方式: POST
说明: 查询 AI Agent 的任务列表。
参数:
参数名类型必选说明
limit integer 否返回记录数量上限（默认 20）
请求示例:
json
```
{
  "limit": 10
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "tasks": [
      {
        "task_id": "r_abc123",
        "task": "打开设置，查看当前 WiFi 名称",
        "status": "completed",
        "created_at": 1709000000000,
        "finished_at": 1709000015000
      }
    ]
  },
  "msg": "OK",
  "request_id": "ag890123"
}

技能管理 (Skill)

AI Agent 支持通过技能（Skill）扩展能力。技能是一段 Markdown 格式的指令文本，用于指导 AI Agent 完成特定类型的任务。技能分为两种来源：

内置技能（builtin）：随系统预装，不可卸载
外部技能（external）：用户自行安装，存储在设备上

获取技能列表

URL: /ai/skill_list
方式: GET
参数: 无

返回示例:

json

{
  "code": 200,
  "data": {
    "skills": [
      {
        "name": "open_app",
        "display_name": "打开应用",
        "description": "打开指定应用",
        "scenarios": "当用户要求打开某个应用时使用",
        "source": "builtin"
      },
      {
        "name": "my_custom_skill",
        "display_name": "自定义技能",
        "description": "自定义技能",
        "scenarios": "自定义场景",
        "source": "external"
      }
    ],
    "count": 2
  },
  "msg": "OK",
  "request_id": "sk123456"
}

获取技能详情

URL: /ai/skill_get
方式: GET
参数:
参数名类型必选说明
name string 是技能名称
请求示例:
json
```
{
  "name": "open_app"
}
```

返回示例:

json

{
  "code": 200,
  "data": {
    "name": "open_app",
    "display_name": "打开应用",
    "description": "打开指定应用",
    "scenarios": "当用户要求打开某个应用时使用",
    "source": "builtin",
    "observe_mode": "screenshot",
    "content": "# 打开应用\n\n## 步骤\n1. 获取应用列表\n2. 启动目标应用..."
  },
  "msg": "OK",
  "request_id": "sk234567"
}

错误返回: 技能不存在时返回 HTTP 400

安装技能

URL: /ai/skill_install
方式: POST
说明: 安装或更新一个外部技能。技能内容以 Markdown 格式存储到设备上。如果同名技能已存在，将覆盖更新。
参数:
参数名类型必选说明
name string 是技能名称，只允许字母、数字、下划线和短横线
content string 是技能内容（Markdown 格式）

请求示例:

json

{
  "name": "my_custom_skill",
  "content": "# 自定义技能\n\n## 描述\n这是一个自定义技能\n\n## 步骤\n1. 执行操作 A\n2. 执行操作 B"
}

返回示例（成功）:

json

{
  "code": 200,
  "data": {
    "name": "my_custom_skill"
  },
  "msg": "OK",
  "request_id": "sk456789"
}

错误返回: 参数缺失或名称格式不合法时返回 HTTP 400，操作失败时返回 HTTP 500

卸载技能

URL: /ai/skill_uninstall
方式: POST
说明: 卸载一个外部技能。内置技能不可卸载。
参数:
参数名类型必选说明
name string 是技能名称
请求示例:
json
```
{
  "name": "my_custom_skill"
}
```

返回示例（成功）:

json

{
  "code": 200,
  "data": {
    "name": "my_custom_skill"
  },
  "msg": "OK",
  "request_id": "sk678901"
}

错误返回:
- 参数缺失或技能不存在时返回 HTTP 400
- 内置技能不可卸载时返回 HTTP 501
- 操作失败时返回 HTTP 500

Android Control API 接口文档 ​

简介 ​

调用方式 ​

1. 云机外 HTTP 调用 ​

2. 云机内 HTTP 调用 ​

3. TCP 调用 ​

4. 命令行 (CLI) 调用 ​

安装 ​

使用方式 ​

参数说明 ​

参数传递 ​

5. WebSocket 调用 ​

请求格式 ​

响应格式 ​

示例 ​

6. MCP 调用（AI Agent 集成） ​

7. Skills 调用（AI Agent 集成） ​

参数格式支持 ​

JSON 格式 (默认) ​

YAML 格式 ​

通用响应结构 ​

基础能力 (Base) ​

获取 API 版本 ​

查询接口信息 ​

暂停响应 ​

应用运行管理 (Activity) ​

启动应用 ​

启动指定 Activity ​

停止应用 ​

停止所有应用 ​

获取正在运行的进程 ​

获取最上层组件信息 ​

获取最近任务列表 ​

清空任务栈 ​

切换任务到前台 ​

应用管理 (Package) ​

安装应用 ​

通过 URI 安装应用 ​

卸载应用 ​

设置应用启用状态 ​

获取已安装应用列表 ​

导出应用 APK ​

清除应用数据 ​

输入控制 (Input) ​

点击 ​

多击 ​

输入文本 ​

按键 ​

滑动 ​

曲线滑动 ​

原始 MotionEvent ​

权限管理 (Permission) ​

获取应用权限 ​

设置应用权限 ​

文件管理 (File) ​

导入文件 ​

导出文件 ​

导出文件（URL） ​

扫描媒体文件 ​

HTTP下载文件 ​

列出目录内容 ​

系统设置 (System) ​

执行 Shell 命令 ​

设置壁纸 ​

更新系统设置 ​

设置系统属性 ​

修改系统设置项 ​

查询系统设置项 ​

电源管理 (Power) ​

点亮 / 熄灭屏幕 ​

锁定 / 解锁屏幕 ​

获取屏幕与锁屏状态 ​

电池管理 (Battery) ​

获取电池信息 ​

设置电池信息 ​

本地化 (Locale) ​

获取本地化信息 ​

剪贴板 (Clipboard) ​

设置剪贴板 ​

获取当前剪贴板 ​

Android Control API 接口文档

简介

调用方式

1. 云机外 HTTP 调用

2. 云机内 HTTP 调用

3. TCP 调用

4. 命令行 (CLI) 调用

安装

使用方式

参数说明

参数传递

5. WebSocket 调用

请求格式

响应格式

示例

6. MCP 调用（AI Agent 集成）

7. Skills 调用（AI Agent 集成）

参数格式支持

JSON 格式 (默认)

YAML 格式

通用响应结构

基础能力 (Base)

获取 API 版本

查询接口信息

暂停响应

应用运行管理 (Activity)

启动应用

启动指定 Activity

停止应用

停止所有应用

获取正在运行的进程

获取最上层组件信息

获取最近任务列表

清空任务栈

切换任务到前台

应用管理 (Package)

安装应用

通过 URI 安装应用

卸载应用

设置应用启用状态

获取已安装应用列表

导出应用 APK

清除应用数据

输入控制 (Input)

点击

多击

输入文本

按键

滑动

曲线滑动

原始 MotionEvent

权限管理 (Permission)

获取应用权限

设置应用权限

文件管理 (File)

导入文件

导出文件

导出文件（URL）

扫描媒体文件

HTTP下载文件

列出目录内容

系统设置 (System)

执行 Shell 命令

设置壁纸

更新系统设置

设置系统属性

修改系统设置项

查询系统设置项

电源管理 (Power)

点亮 / 熄灭屏幕

锁定 / 解锁屏幕

获取屏幕与锁屏状态

电池管理 (Battery)

获取电池信息

设置电池信息

本地化 (Locale)

获取本地化信息

剪贴板 (Clipboard)

设置剪贴板

获取当前剪贴板