Hamibot

https://docs.hamibot.com
Admin
Hamibot is a powerful Android automation tool that allows users to control and automate any...
Tokens:90,638
Snippets:1,041
Trust Score:8.4
Update:2 months ago
Show doc for...
Tokens:
Raw
### pm install

Source: https://docs.hamibot.com/reference/shell

Installs an application package from a specified path.

```APIDOC
## pm install [options] [path]

### Description
Installs a package located at the specified path to the system.

### Parameters
#### Path Parameters
- **path** (string) - Required - The file system path to the APK.

#### Options
- **-r** (flag) - Optional - Reinstall existing app, keeping data.
- **-t** (flag) - Optional - Allow test APK installation.
- **-g** (flag) - Optional - Grant all permissions listed in the manifest.
```

--------------------------------

### Start a new thread

Source: https://docs.hamibot.com/reference/threads

Demonstrates starting a new thread using threads.start() to execute code concurrently.

```javascript
threads.start(function () {
  //在新线程执行的代码
  while (true) {
    log('子线程');
  }
});
while (true) {
  log('脚本主线程');
}
```

--------------------------------

### Get Installed Apps

Source: https://docs.hamibot.com/reference/app

Retrieves information for all installed applications.

```javascript
log(app.getInstalledApps());
hamibot.exit();
```

--------------------------------

### Get Installed Packages

Source: https://docs.hamibot.com/reference/app

Retrieves a list of information for all installed application packages.

```javascript
log(app.getInstalledPackages());
hamibot.exit();
```

--------------------------------

### app.startActivity(name)

Source: https://docs.hamibot.com/reference/app

Starts a specific Hamibot interface.

```APIDOC
## app.startActivity(name)

### Description
Launches a specific Hamibot interface.

### Parameters
- **name** (String) - Required - The name of the activity to start (e.g., 'console').

### Example
```javascript
app.startActivity('console');
```
```

--------------------------------

### app.startService(options)

Source: https://docs.hamibot.com/reference/app

Constructs an Intent based on the provided options and starts the service.

```APIDOC
## app.startService(options)

### Description
Constructs an Intent based on the provided options and starts the service.

### Parameters
- **options** (Object) - Required - Configuration object for the intent.
```

--------------------------------

### app.startActivity(options)

Source: https://docs.hamibot.com/reference/app

Constructs an Intent based on the provided options and starts the corresponding Activity.

```APIDOC
## app.startActivity(options)

### Description
Constructs an Intent based on the provided options and starts the corresponding Activity.

### Parameters
- **options** (Object) - Required - Configuration object for the intent.
```

--------------------------------

### get-install-location

Source: https://docs.hamibot.com/reference/shell

Returns the current default installation location.

```APIDOC
## get-install-location

### Description
Returns the current installation location (0: auto, 1: internal, 2: external).
```

--------------------------------

### app.getInstalledApps()

Source: https://docs.hamibot.com/reference/app

Retrieves information for all installed applications.

```APIDOC
## app.getInstalledApps()

### Description
Retrieves information about all installed applications.
```

--------------------------------

### Launch Application by Package Name

Source: https://docs.hamibot.com/reference/app

Starts an application using its package name. Returns false if the application is not found.

```javascript
// 启动 Hamibot
launch('com.hamibot.hamibot');
```

--------------------------------

### Launch Application by Name

Source: https://docs.hamibot.com/reference/app

Starts an application using its display name. Returns false if the application is not found.

```javascript
// 启动 Hamibot
launchApp('Hamibot');
```

--------------------------------

### threads.start(action)

Source: https://docs.hamibot.com/reference/threads

Starts a new thread and executes the provided action function.

```APIDOC
## threads.start(action)

### Description
Starts a new thread and executes the provided action function. Returns a Thread object.

### Parameters
- **action** (Function) - Required - The function to be executed in the new thread.
```

--------------------------------

### GET /v1/usage

Source: https://docs.hamibot.com/rest/usage

获取当前令牌的 API 配额使用情况。

```APIDOC
## GET /v1/usage

### Description
获取当前令牌的 API 配额使用情况，包括总配额、剩余次数、已用次数以及重置时间。

### Method
GET

### Endpoint
https://api.hamibot.com/v1/usage

### Parameters
#### Headers
- **Authorization** (string) - Required - 令牌（以 hmp 开头）

### Response
#### Success Response (200)
- **limit** (number) - 配额数量
- **remaining** (number) - 剩余次数
- **used** (number) - 已用次数
- **reset** (string) - 刷新时间（重置已用次数）

#### Response Example
{
  "limit": 800,
  "remaining": 748,
  "used": 52,
  "reset": "2022-01-01 00:00:00"
}
```

--------------------------------

### Set View Background

Source: https://docs.hamibot.com/reference/ui

Examples of setting the background using colors, local file paths, or system attributes.

```xml
bg="#00ff00"
```

```xml
bg="file:///storage/emulated/0/1.png"
```

```xml
bg="?attr/selectableItemBackground"
```

--------------------------------

### app.getInstalledPackages()

Source: https://docs.hamibot.com/reference/app

Retrieves information for all installed application packages.

```APIDOC
## app.getInstalledPackages()

### Description
Retrieves information about all installed application packages.
```

--------------------------------

### Perform a simple HTTP GET request

Source: https://docs.hamibot.com/reference/http

Executes a synchronous GET request to the specified URL and logs the status code and response body.

```javascript
var r = http.get('https://www.baidu.com');
log('code = ' + r.statusCode);
log('html = ' + r.body.string());
```

--------------------------------

### GET /v1/devscripts

Source: https://docs.hamibot.com/rest/devscripts

获取开发脚本列表，支持通过 name 参数进行过滤。

```APIDOC
## GET /v1/devscripts

### Description
获取开发脚本列表。

### Method
GET

### Endpoint
/v1/devscripts

### Parameters
#### Query Parameters
- **name** (string) - Optional - 脚本名称，用于过滤结果

### Response
#### Success Response (200)
- **count** (number) - 脚本总数
- **items** (array) - 脚本列表

#### Response Example
{
  "count": 1,
  "items": [
    {
      "_id": "bfe67d643ababe0ab6fda054",
      "name": "演示脚本"
    }
  ]
}
```

--------------------------------

### List Directory Contents

Source: https://docs.hamibot.com/reference/files

Examples of listing files in a directory, with and without a filter function.

```javascript
var arr = files.listDir('/storage/emulated/0/');
log(arr);
```

```javascript
var dir = '/storage/emulated/0/脚本/';
var jsFiles = files.listDir(dir, function (name) {
  return name.endsWith('.js') && files.isFile(files.join(dir, name));
});
log(jsFiles);
```

--------------------------------

### Wait for thread startup

Source: https://docs.hamibot.com/reference/threads

Ensures a thread has started executing before attempting to schedule tasks on it using waitFor.

```javascript
var thread = threads.start(function () {
  //do something
});
thread.waitFor();
thread.setTimeout(function () {
  //do something
}, 1000);
```

--------------------------------

### Start a Hamibot activity

Source: https://docs.hamibot.com/reference/app

Launches specific internal interfaces of the Hamibot application.

```javascript
app.startActivity('console');
```

--------------------------------

### 获取开发脚本列表

Source: https://docs.hamibot.com/rest/devscripts

通过 GET 请求获取所有开发脚本，支持使用 name 参数进行过滤。

```js
var res = http.request('https://api.hamibot.com/v1/devscripts', {
  method: 'GET',
  headers: {
    authorization: '你的令牌（hmp 开头）',
  },
});
log(res.body.json());
```

```shell
curl -H "Authorization: 你的令牌（hmp 开头）" \
    https://api.hamibot.com/v1/devscripts
```

--------------------------------

### 获取设备列表

Source: https://docs.hamibot.com/rest/robots

通过 GET 请求获取设备列表，支持通过 query 参数进行品牌、在线状态等过滤。

```javascript
var res = http.request('https://api.hamibot.com/v1/devices', {
  method: 'GET',
  headers: {
    authorization: '你的令牌（hmp 开头）',
  },
});
log(res.body.json());
```

```shell
curl -H "Authorization: 你的令牌（hmp 开头）" \
    https://api.hamibot.com/v1/devices
```

--------------------------------

### pm list packages

Source: https://docs.hamibot.com/reference/shell

Lists all installed packages on the device, with optional filtering and metadata display.

```APIDOC
## pm list packages [options] [filter]

### Description
Outputs all packages, or only those matching the provided filter.

### Parameters
#### Query Parameters
- **-f** (flag) - Optional - View associated files.
- **-d** (flag) - Optional - Filter to show only disabled packages.
- **-e** (flag) - Optional - Filter to show only enabled packages.
- **-s** (flag) - Optional - Filter to show only system packages.
- **-3** (flag) - Optional - Filter to show only third-party packages.
- **-i** (flag) - Optional - View installer for the package.
- **-u** (flag) - Optional - Include uninstalled packages.
- **--user** (integer) - Optional - The user space to query.
```

--------------------------------

### set-install-location location

Source: https://docs.hamibot.com/reference/shell

Changes the default installation location for applications.

```APIDOC
## set-install-location location

### Description
Changes the default installation location. Note: This command is for debugging purposes only and may cause unexpected behavior.

### Parameters
- **location** (integer) - Required - 0: Auto, 1: Internal, 2: External
```

--------------------------------

### Get Package Information

Source: https://docs.hamibot.com/reference/app

Retrieves detailed information for a specific application using its package name.

```javascript
log(app.getPackageInfo('com.hamibot.hamibot'));
hamibot.exit();
```

--------------------------------

### Applying margin to UI elements

Source: https://docs.hamibot.com/reference/ui

Provides an example of using the margin attribute to create spacing between UI components.

```javascript
'ui';
ui.layout(
  <horizontal>
    <button margin="30" text="距离四周30" />
    <button text="普通的按钮" />
  </horizontal>
);
```

--------------------------------

### Send an email via system app

Source: https://docs.hamibot.com/reference/app

Launches the default email application with pre-filled fields. Throws ActivityNotException if no email client is installed.

```javascript
// 发送邮件给 hamibot@example.com
app.sendEmail({
  email: ['hamibot@example.com'],
  subject: '这是一个邮件标题',
  text: '这是邮件正文',
});
```

--------------------------------

### Move and Manage Files and Directories

Source: https://docs.hamibot.com/reference/files

Demonstrates creating directories, writing to a file, and moving that file between directories.

```javascript
let dir1 = files.cwd() + '/dir1/';
let dir2 = files.cwd() + '/dir2/';
let file1 = dir1 + '1.txt';
let file2 = dir2 + '2.txt';
log('dir1 创建', files.ensureDir(dir1));
log('dir2 创建', files.ensureDir(dir2));
log('file1 创建', files.write(file1, 'hamibot11111'));
log('file1 移动', files.move(file1, file2));
log(
  '正常会看到 ' +
    files.cwd() +
    ' 下有 2 个文件夹 dir1 和 dir2，dir1 内无文件，dir2 有文件 2.txt'
);
```

--------------------------------

### Get Promotional Code List

Source: https://docs.hamibot.com/rest/devscripts

Retrieves a list of promotional codes associated with a specific script.

```javascript
var res = http.request(
  'https://api.hamibot.com/v1/devscripts/开发脚本_id/promocode',
  {
    method: 'GET',
    headers: {
      authorization: '你的令牌（hmp 开头）',
    },
  }
);
log(res.body.json());
```

```shell
curl -H "Authorization: 你的令牌（hmp 开头）" \
    https://api.hamibot.com/v1/devscripts/开发脚本_id/promocode
```

```json
{
  "count": 1,
  "items": [
    {
      "_id": "587b2858b712a80bc3f161a6", // 优惠码_id
      "code": "XXXXXXXX", // 优惠码
      "percentOff": 20, // 折扣
      "expiresAt": "2023-01-10 23:59:59", // 优惠码有效期
      "name": "脚本名称",
      "url": "https://hamibot.com/marketplace/xxx" // 脚本链接
    }
  ]
}
```

--------------------------------

### GET /v1/message/send

Source: https://docs.hamibot.com/rest/message

Sends a message to the user's Hamibot account. This endpoint supports both GET and POST requests and allows for Markdown-formatted content.

```APIDOC
## GET /v1/message/send

### Description
Sends a message to the user's Hamibot account. Messages support Markdown and are displayed in the console for easy review.

### Method
GET (also supports POST)

### Endpoint
https://api.hamibot.com/v1/message/send

### Parameters
#### Query Parameters
- **token** (string) - Required - The user's authentication token.
- **text** (string) - Required - The message content. Supports Markdown, maximum length 2000 characters.

### Request Example
https://api.hamibot.com/v1/message/send?token=hmp_...&text=Hello%20World

### Response
#### Success Response (204)
- No content returned on success.
```

--------------------------------

### Format strings with util.format

Source: https://docs.hamibot.com/reference/util

Demonstrates various string formatting scenarios using placeholders and argument handling.

```javascript
util.format('%s:%s', 'foo');
// Returns: 'foo:%s'
```

```javascript
util.format('%s:%s', 'foo', 'bar', 'baz'); // 'foo:bar baz'
```

```javascript
util.format(1, 2, 3); // '1 2 3'
```

```javascript
util.format('%% %s'); // '%% %s'
```

--------------------------------

### Perform an asynchronous HTTP GET request with a callback

Source: https://docs.hamibot.com/reference/http

Executes an asynchronous GET request using a callback function to handle the response or potential errors.

```javascript
http.get('https://www.baidu.com', {}, function (res, err) {
  if (err) {
    console.error(err);
    return;
  }
  log('code = ' + res.statusCode);
  log('html = ' + res.body.string());
});
```

--------------------------------

### http.get(url[, options, callback])

Source: https://docs.hamibot.com/reference/http

Performs an HTTP GET request to the specified URL. If no callback is provided, the request is executed synchronously.

```APIDOC
## http.get(url[, options, callback])

### Description
Performs an HTTP GET request to the specified URL. If a callback is provided, the request is asynchronous; otherwise, it blocks and executes synchronously.

### Parameters
- **url** (String) - Required - The URL to request, starting with 'http://' or 'https://'.
- **options** (Object) - Optional - Request configuration options.
- **callback** (Function) - Optional - A callback function receiving (res, err) arguments.
```

--------------------------------

### GET /v1/devscripts/:id

Source: https://docs.hamibot.com/rest/devscripts

获取指定开发脚本的详细信息。

```APIDOC
## GET /v1/devscripts/:id

### Description
获取指定开发脚本的详细信息。

### Method
GET

### Endpoint
/v1/devscripts/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - 开发脚本 ID

### Response
#### Success Response (200)
- **_id** (string) - 脚本 ID
- **name** (string) - 脚本名称

#### Response Example
{
  "_id": "bfe67d643ababe0ab6fda054",
  "name": "演示脚本"
}
```

--------------------------------

### GET /v1/orders/{order_id}

Source: https://docs.hamibot.com/rest/orders

根据交易编号获取订单详情。

```APIDOC
## GET /v1/orders/{order_id}

### Description
获取指定交易编号的订单详情。

### Method
GET

### Endpoint
https://api.hamibot.com/v1/orders/{order_id}

### Parameters
#### Path Parameters
- **order_id** (string) - Required - 交易编号

### Request Example
```javascript
var res = http.request('https://api.hamibot.com/v1/orders/交易编号', {
  method: 'GET',
  headers: {
    authorization: '你的令牌（hmp 开头）',
  },
});
log(res.body.json());
```

### Response
#### Success Response (200)
- 成功返回订单信息
```

--------------------------------

### Thread.waitFor()

Source: https://docs.hamibot.com/reference/threads

Waits for the thread to start execution.

```APIDOC
## Thread.waitFor()

### Description
Blocks until the thread has started execution. If the thread is already running, it returns immediately.
```

--------------------------------

### Create a file or directory

Source: https://docs.hamibot.com/reference/files

Creates a file or directory at the specified path. Returns false if the path already exists.

```javascript
files.create('/storage/emulated/0/新文件夹/');
```

--------------------------------

### 启动 Activity

Source: https://docs.hamibot.com/reference/app

使用 app.startActivity 直接构造并启动 Activity。

```javascript
app.startActivity({
  action: 'SEND',
  type: 'text/plain',
  data: 'file:///storage/emulated/0/1.txt',
});
```

--------------------------------

### open(path[, mode, encoding, bufferSize])

Source: https://docs.hamibot.com/reference/files

Opens a file and returns a file object.

```APIDOC
## open(path[, mode = "r", encoding = "utf-8", bufferSize = 8192])

### Description
Opens a file and returns a PReadableTextFile or PWritableTextFile object depending on the mode.

### Parameters
- **path** (String) - Required - The file path.
- **mode** (String) - Optional - "r" (read), "w" (write/overwrite), "a" (append), "rw" (read/write).
- **encoding** (String) - Optional - Character encoding.
- **bufferSize** (Number) - Optional - Buffer size for read/write operations.
```

--------------------------------

### POST /v1/scripts/{脚本_id}/run

Source: https://docs.hamibot.com/rest/scripts

Executes a specific script on the provided devices.

```APIDOC
## POST /v1/scripts/{脚本_id}/run

### Description
Executes a specific script on the provided devices.

### Method
POST

### Endpoint
/v1/scripts/{脚本_id}/run

### Parameters
#### Path Parameters
- **脚本_id** (string) - Required - The ID of the script

#### Request Body
- **devices** (array) - Required - List of devices to execute the script on
- **vars** (object) - Optional - Script configuration variables
```

--------------------------------

### hasher.listAlgorithms()

Source: https://docs.hamibot.com/reference/hasher

Returns a list of all supported hashing algorithms.

```APIDOC
## hasher.listAlgorithms()

### Description
Returns an array of strings representing all hashing algorithms supported by the system.
```

--------------------------------

### 获取单个开发脚本

Source: https://docs.hamibot.com/rest/devscripts

通过 GET 请求获取指定 ID 的开发脚本详情。

```js
var res = http.request('https://api.hamibot.com/v1/devscripts/开发脚本_id', {
  method: 'GET',
  headers: {
    authorization: '你的令牌（hmp 开头）',
  },
});
log(res.body.json());
```

```shell
curl -H "Authorization: 你的令牌（hmp 开头）" \
    https://api.hamibot.com/v1/devscripts/开发脚本_id
```

--------------------------------

### app.openAppSetting(packageName)

Source: https://docs.hamibot.com/reference/app

Opens the settings page for a specific application. Returns true if successful, false otherwise.

```APIDOC
## app.openAppSetting(packageName)

### Description
Opens the application details (settings) page. Returns false if the application cannot be found, otherwise returns true.

### Parameters
- **packageName** (string) - Required - The package name of the application.
```

--------------------------------

### Monitor and Log Sensor Data to CSV

Source: https://docs.hamibot.com/reference/sensors

Demonstrates listening to light and accelerometer sensors, updating variables, and periodically writing the data to a CSV file.

```javascript
//csv文件路径
cosnt csvPath = "/storage/emulated/0/sensors_data.csv";
//记录光线传感器的数据
var light = 0;
//记录加速度传感器的数据
var ax = 0;
var ay = 0;
var az = 0;
//监听光线传感器
sensors.register("light", sensors.delay.fastest)
	.on("change", l => {
		light = l;
	});
//监听加速度传感器
sensors.register("accelerometer", sensors.delay.fastest)
	.on("change", (ax0, ay0, az0) => {
		ax = ax0;
		ay = ay0;
		az = az0;
	});

var file = open(csvPath, "w");
//写csv表格头
file.writeline("light,ax,ay,az")
//每0.5秒获取一次数据并写入文件
setInterval(()=>{
	file.writeline(util.format("%d,%d,%d,%d", light, ax, ay, az));
}, 500);
//10秒后退出并打开文件
setTimeout(()=>{
	file.close();
	sensors.unregsiterAll();
	app.viewFile(csvPath);
}, 10 * 1000);
```

--------------------------------

### threads.shutDownAll()

Source: https://docs.hamibot.com/reference/threads

Stops all child threads started via threads.start().

```APIDOC
## threads.shutDownAll()

### Description
Stops all child threads that were started using the threads.start() method.
```

--------------------------------

### Execute am display-size Command

Source: https://docs.hamibot.com/reference/shell

Demonstrates how to use the shell function to change the display size of the device or emulator.

```javascript
shell('am display-size 1280x800', true);
```

--------------------------------

### files.createWithDirs(path)

Source: https://docs.hamibot.com/reference/files

Creates a file or directory, including any necessary parent directories.

```APIDOC
## files.createWithDirs(path)

### Description
Creates a file or directory at the specified path, creating any missing parent directories along the way. Returns true if successful, or false if the file already exists.

### Parameters
- **path** (String) - Required - The path to create.
```

--------------------------------

### GET /v1/devices/{device_id}

Source: https://docs.hamibot.com/rest/robots

Retrieves details for a specific device by its ID.

```APIDOC
## GET /v1/devices/{device_id}

### Description
Retrieves the details of a specific device using its unique identifier.

### Method
GET

### Endpoint
/v1/devices/{device_id}

### Parameters
#### Path Parameters
- **device_id** (string) - Required - The unique ID of the device

### Response
#### Success Response (200)
- **_id** (string) - Device ID
- **online** (boolean) - Online status
- **tags** (array) - Device tags
- **name** (string) - Device name
- **brand** (string) - Device brand
- **model** (string) - Device model
```

--------------------------------

### GET /v1/scripts/{脚本_id}

Source: https://docs.hamibot.com/rest/scripts

Retrieves details for a specific script by its ID.

```APIDOC
## GET /v1/scripts/{脚本_id}

### Description
Retrieves details for a specific script by its ID.

### Method
GET

### Endpoint
/v1/scripts/{脚本_id}

### Parameters
#### Path Parameters
- **脚本_id** (string) - Required - The ID of the script
```

--------------------------------

### Open and close a file

Source: https://docs.hamibot.com/reference/files

Demonstrates the basic lifecycle of opening a file for writing and ensuring it is closed to prevent data loss.

```javascript
let file = open(path, 'w');
file.close();
```

--------------------------------

### 获取脚本列表

Source: https://docs.hamibot.com/rest/scripts

通过 GET 请求获取脚本列表，支持通过 slug 或 name 进行过滤。

```javascript
var res = http.request('https://api.hamibot.com/v1/scripts', {
  method: 'GET',
  headers: {
    authorization: '你的令牌（hmp 开头）',
  },
});
log(res.body.json());
```

```shell
curl -H "Authorization: 你的令牌（hmp 开头）" \
    https://api.hamibot.com/v1/scripts
```

--------------------------------

### UiObject.setSelection(start, end)

Source: https://docs.hamibot.com/reference/widgetsBasedAutomation

Sets the selection range for text in an input field.

```APIDOC
## UiObject.setSelection(start, end)

### Description
Sets the selected text range in an input field. Can also be used to set the cursor position by setting start equal to end.

### Parameters
- **start** (Number) - The starting index of the selection.
- **end** (Number) - The ending index of the selection (exclusive).

### Returns
- **Boolean** - True if the operation was successful.
```

--------------------------------

### Apply Layout and Widget Attributes

Source: https://docs.hamibot.com/reference/ui

Demonstrates setting background color for a layout and text size for a button.

```javascript
'ui';
ui.layout(
  <vertical bg="#ff0000">
    <button text="第一个按钮" textSize="20sp" />
    <button text="第二个按钮" />
  </vertical>
);
```

--------------------------------

### dialogs.build(options)

Source: https://docs.hamibot.com/reference/dialogs

Constructs a new dialog instance based on the provided configuration options. Returns a Dialog object that can be configured with event listeners and displayed using the .show() method.

```APIDOC
## dialogs.build(options)

### Description
Creates a customizable dialog instance. The dialog can be configured with titles, content, buttons, input fields, progress bars, and selection lists.

### Parameters
- **options** (Object) - Required - Configuration object containing properties such as title, content, items, positive/negative/neutral button text, input settings, and progress bar configuration.

### Methods
- **.show()** - Displays the dialog.
- **.on(event, callback)** - Registers an event listener for user interactions (e.g., 'positive', 'negative', 'single_choice', 'input').
- **.dismiss()** - Closes the dialog programmatically.
```

--------------------------------

### app.launchApp(appName)

Source: https://docs.hamibot.com/reference/app

Launches an application by its name. Returns true if successful, false otherwise.

```APIDOC
## app.launchApp(appName)

### Description
Launches an application by its name. If multiple apps share the same name, one is selected.

### Parameters
- **appName** (String) - Required - The name of the application to launch.

### Returns
- **Boolean** - Returns true if the app exists and was launched, false otherwise.
```

--------------------------------

### engines.execAutoFile(path[, config])

Source: https://docs.hamibot.com/reference/engines

Executes a recorded auto file in a new environment.

```APIDOC
## engines.execAutoFile(path[, config])

### Description
Runs a recorded file (.auto) in a new environment. Returns a ScriptExecution object.

### Parameters
- **path** (String) - Required - The file path of the recorded file.
- **config** (Object) - Optional - Execution configuration.
```

--------------------------------

### GET /v1/devices

Source: https://docs.hamibot.com/rest/robots

Retrieves a list of devices associated with the account, with optional filtering.

```APIDOC
## GET /v1/devices

### Description
Retrieves a list of devices. Supports filtering by brand, model, online status, name, appVersion, and tag.

### Method
GET

### Endpoint
/v1/devices

### Parameters
#### Query Parameters
- **brand** (string) - Optional - Filter by device brand
- **model** (string) - Optional - Filter by device model
- **online** (boolean) - Optional - Filter by online status
- **name** (string) - Optional - Filter by device name
- **appVersion** (string) - Optional - Filter by app version
- **tag** (string) - Optional - Filter by device tag

### Response
#### Success Response (200)
- **count** (number) - Number of devices returned
- **items** (array) - List of device objects
```

--------------------------------

### app.launch(packageName)

Source: https://docs.hamibot.com/reference/app

Launches an application by its package name.

```APIDOC
## app.launch(packageName)

### Description
Launches an application by its package name.

### Parameters
- **packageName** (String) - Required - The package name of the application to launch.

### Returns
- **Boolean** - Returns true if the app exists and was launched, false otherwise.
```

--------------------------------

### List files with ls

Source: https://docs.hamibot.com/reference/shell

Lists files in the specified directory and logs the result.

```javascript
log(shell('ls /storage/emulated/0').result);
```

--------------------------------

### console.time(label) / console.timeEnd(label)

Source: https://docs.hamibot.com/reference/console.html

Starts and stops a timer to measure operation duration.

```APIDOC
## console.time([label])

### Description
Starts a timer identified by a unique label.

## console.timeEnd(label)

### Description
Stops the timer identified by the label and prints the elapsed time in milliseconds to the console.
```

--------------------------------

### ui.layoutFile(xmlFile)

Source: https://docs.hamibot.com/reference/ui

Renders a layout from an XML file path.

```APIDOC
## ui.layoutFile(xmlFile)

### Description
此函数和`ui.layout`相似，只不过允许传入一个 xml 文件路径来渲染布局。

### Parameters
- **xmlFile** (<String>) - Required - 布局 XML 文件的路径
```

--------------------------------

### Create and write to a storage

Source: https://docs.hamibot.com/reference/storages

Creates a storage instance with a specific name and saves a key-value pair.

```javascript
var storage = storages.create('ABC');
storage.put('a', 123);
```

--------------------------------

### Get APK Information

Source: https://docs.hamibot.com/reference/app

Retrieves detailed information from a specific APK file path.

```javascript
log(app.getApkInfo('/storage/emulated/0/com.hamibot.hamibot.apk'));
hamibot.exit();
```

--------------------------------

### Get Script Source

Source: https://docs.hamibot.com/reference/engines

Returns the source object of the script currently being executed by the engine.

```javascript
log(engines.myEngine().getSource());
```

--------------------------------

### Get Script Engine Working Directory

Source: https://docs.hamibot.com/reference/engines

Returns the directory path where the script is executing.

```javascript
log(engines.myEngine().cwd());
```

--------------------------------

### 构造并启动 Intent

Source: https://docs.hamibot.com/reference/app

使用 app.intent 构造意图对象，并通过 context.startActivity 启动。

```javascript
//打开应用来查看图片文件
var i = app.intent({
  action: 'VIEW',
  type: 'image/png',
  data: 'file:///storage/emulated/0/1.png',
});
context.startActivity(i);
```

--------------------------------

### Loop Music Playback

Source: https://docs.hamibot.com/reference/media

Demonstrates how to enable looping for music playback using the looping parameter.

```javascript
//传递第三个参数为 true 以循环播放音乐 media.playMusic("/storage/emulated/0/1.mp3", 1, true); //等待三次播放的时间 sleep(media.getMusicDuration() * 3);
```

--------------------------------

### Get Execution Arguments

Source: https://docs.hamibot.com/reference/engines

Retrieves the execution arguments, such as intent data, for the current engine.

```javascript
log(engines.myEngine().execArgv);
```

--------------------------------

### storages.create(name)

Source: https://docs.hamibot.com/reference/storages

Creates a local storage instance or retrieves an existing one by name.

```APIDOC
## storages.create(name)

### Description
Creates a local storage and returns a `Storage` object. Storages with the same name share data, while those with different names are isolated.

### Parameters
- **name** (String) - Required - The name of the local storage.
```

--------------------------------

### Get Current Script Directory

Source: https://docs.hamibot.com/reference/engines

Retrieves the working directory of the current script engine.

```javascript
toast(engines.myEngine().cwd());
```

--------------------------------

### console.show()

Source: https://docs.hamibot.com/reference/console.html

Displays the console floating window. Requires floating window permissions.

```APIDOC
## console.show()

### Description
Displays the console floating window. This requires the floating window permission to be granted.
```

--------------------------------

### UI Mode Dialog Handling

Source: https://docs.hamibot.com/reference/dialogs

Demonstrates how to handle dialogs in UI mode using either callbacks or Promises.

```javascript
'ui';
//回调形式
confirm('要清除所有缓存吗?', function (clear) {
  if (clear) {
    alert('清除成功!');
  }
});
//Promise形式
confirm('要清除所有缓存吗?').then((clear) => {
  if (clear) {
    alert('清除成功!');
  }
});
```

--------------------------------

### Measure execution time

Source: https://docs.hamibot.com/reference/console.html

Starts a timer with a label and prints the elapsed time in milliseconds when stopped.

```javascript
console.time('求和');
var sum = 0;
for (let i = 0; i < 100000; i++) {
  sum += i;
}
console.timeEnd('求和');
// 打印 求和: xxx ms
```

--------------------------------

### Execute Script File

Source: https://docs.hamibot.com/reference/engines

Runs a script file from the specified path in a new environment.

```javascript
engines.execScriptFile('/storage/emulated/0/1.js');
```

--------------------------------

### Retrieve component bounds

Source: https://docs.hamibot.com/reference/widgetsBasedAutomation

Gets the screen coordinates of a component and displays them via a toast message.

```javascript
var b = text('Hamibot').findOne().bounds();
toast('控件在屏幕上的范围为' + b);
```

--------------------------------

### files.create(path)

Source: https://docs.hamibot.com/reference/files

Creates a file or directory at the specified path.

```APIDOC
## files.create(path)

### Description
Creates a file or directory at the specified path. Returns true if successful, or false if the file already exists.

### Parameters
- **path** (String) - Required - The path to create.
```

--------------------------------

### GET /v1/devscripts/{开发脚本_id}/promocode

Source: https://docs.hamibot.com/rest/devscripts

Retrieves a list of promotional codes for a specific development script.

```APIDOC
## GET /v1/devscripts/{开发脚本_id}/promocode

### Description
Retrieves a list of promotional codes for a specific development script.

### Method
GET

### Endpoint
/v1/devscripts/{开发脚本_id}/promocode

### Parameters
#### Path Parameters
- **开发脚本_id** (string) - Required - The ID of the development script.

### Response
#### Success Response (200)
- **count** (integer) - Number of promotional codes
- **items** (array) - List of promotional code objects
```

--------------------------------

### new Shell(root)

Source: https://docs.hamibot.com/reference/shell

Creates a persistent shell session for executing multiple commands efficiently.

```APIDOC
## new Shell(root)

### Description
Constructor for a persistent Shell object. Using this is more efficient for multiple commands as it reuses the same shell process.

### Parameters
- **root** (Boolean) - Optional - Whether to run the shell process with root privileges (default: false).
```

--------------------------------

### Get device location

Source: https://docs.hamibot.com/reference/globals

Retrieves the device's longitude and latitude using the location service.

```javascript
const { ROBOT_ID } = hamibot.env; // https://docs.hamibot.com/reference/hamibot#env
log('当前设备: ' + hamibot.robotName);
log('设备 ID: ' + ROBOT_ID);
// 请求位置权限
runtime.requestPermissions(['access_fine_location']); // https://docs.hamibot.com/reference/globals#runtime-requestpermissions-permissions
let criteria = new android.location.Criteria();
criteria.setAccuracy(android.location.Criteria.ACCURACY_FINE);
let locationManager = context.getSystemService(
  android.content.Context.LOCATION_SERVICE
);
let provider = locationManager.getBestProvider(criteria, true);
if (provider) {
  let location = locationManager.getLastKnownLocation(provider);
  if (location) {
    log('经度：' + location.getLongitude());
    log('纬度：' + location.getLatitude());
  }
}
hamibot.exit();
```

--------------------------------

### Configure Shell Callback

Source: https://docs.hamibot.com/reference/shell

Sets up a callback to monitor shell output, specifically handling new lines as they are generated.

```javascript
var sh = new Shell();
sh.setCallback({
  onNewLine: function (line) {
    //有新的一行输出时打印到控制台
    log(line);
  },
});
while (true) {
  //循环输入命令
  var cmd = dialogs.rawInput('请输入要执行的命令，输入exit退出');
  if (cmd == 'exit') {
    break;
  }
  //执行命令
  sh.exec(cmd);
}
sh.exit();
```

--------------------------------

### Set Floating Window Size

Source: https://docs.hamibot.com/reference/floaty

Demonstrates setting a raw window to full screen using -1, -1 dimensions.

```javascript
var w = floaty.rawWindow(
  <frame gravity="center" bg="#77ff0000">
    <text id="text">悬浮文字</text>
  </frame>
);

w.setSize(-1, -1);

setTimeout(() => {
  w.close();
}, 5000);
```

--------------------------------

### Create file with parent directories

Source: https://docs.hamibot.com/reference/files

Creates a file or directory, including any missing parent directories in the path. Returns false if the file already exists.

```javascript
files.createWithDirs('/storage/emulated/0/新文件夹/新文件夹/新文件夹/1.txt');
```

--------------------------------

### GET /v1/scripts

Source: https://docs.hamibot.com/rest/scripts

Retrieves a list of scripts. Supports filtering by slug or name via query parameters.

```APIDOC
## GET /v1/scripts

### Description
Retrieves a list of scripts. Supports filtering by slug or name via query parameters.

### Method
GET

### Endpoint
/v1/scripts

### Parameters
#### Query Parameters
- **slug** (string) - Optional - Filter by script slug
- **name** (string) - Optional - Filter by script name

### Response
#### Success Response (200)
- **count** (number) - Total number of scripts
- **items** (array) - List of script objects
```

--------------------------------

### engines.execScriptFile(path[, config])

Source: https://docs.hamibot.com/reference/engines

Executes a script file from the specified path in a new environment.

```APIDOC
## engines.execScriptFile(path[, config])

### Description
Runs a script file located at the given path in a new environment. Returns a ScriptExecution object.

### Parameters
- **path** (String) - Required - The file path of the script.
- **config** (Object) - Optional - Execution configuration.
```

--------------------------------

### Get App Name from Package Name

Source: https://docs.hamibot.com/reference/app

Retrieves the application name associated with the provided package name.

```javascript
var name = getAppName('com.hamibot.hamibot'); // 返回 Hamibot
```

--------------------------------

### Get Package Name from App Name

Source: https://docs.hamibot.com/reference/app

Retrieves the package name associated with the provided application name.

```javascript
var name = getPackageName('Hamibot'); // 返回 com.hamibot.hamibot
```

--------------------------------

### app.sendEmail(options)

Source: https://docs.hamibot.com/reference/app

Launches the email application to send an email based on the provided options.

```APIDOC
## app.sendEmail(options)

### Description
Invokes the email application to send an email. All fields in the options object are optional. Throws ActivityNotException if no email application is installed.

### Parameters
- **options** (Object) - Required - Email configuration object.
  - **email** (String|Array) - Optional - Recipient email address(es).
  - **cc** (String|Array) - Optional - CC recipient email address(es).
  - **bcc** (String|Array) - Optional - BCC recipient email address(es).
  - **subject** (String) - Optional - Email subject.
  - **text** (String) - Optional - Email body content.
  - **attachment** (String) - Optional - Path to the attachment file.

### Example
```javascript
app.sendEmail({
  email: ['hamibot@example.com'],
  subject: '这是一个邮件标题',
  text: '这是邮件正文',
});
```
```

--------------------------------

### 以 Root 权限启动 Activity

Source: https://docs.hamibot.com/reference/app

在拥有 root 权限的情况下，通过设置 root: true 跳转到未暴露的 Activity。

```javascript
app.startActivity({
  packageName: 'com.hamibot.hamibot',
  className: 'com.hamibot.hamibot.ui.log.LogActivity_',
  root: true,
});
```

--------------------------------

### Get View attributes with attr()

Source: https://docs.hamibot.com/reference/ui

Retrieves the current value of a view attribute, shown here by incrementing a text-based counter.

```javascript
'ui';

ui.layout(
  <frame>
    <text id="example" text="1" />
  </frame>
);

plusOne();

function plusOne() {
  // 获取文本
  let text = ui.example.attr('text');
  // 解析为数字
  let num = parseInt(text);
  // 数字加1
  num++;
  // 设置文本
  ui.example.attr('text', String(num));
  // 1秒后继续
  ui.post(plusOne, 1000);
}
```

--------------------------------

### app.viewFile(path)

Source: https://docs.hamibot.com/reference/app

Opens a file using an external application.

```APIDOC
## app.viewFile(path)

### Description
Uses another application to view the specified file. Throws ActivityNotException if no suitable application is found.

### Parameters
- **path** (string) - Required - The file path.
```

--------------------------------

### Getting Device and Script Names

Source: https://docs.hamibot.com/reference/hamibot

Retrieves the current device name and script name for logging or identification purposes.

```javascript
log('当前设备:' + hamibot.robotName);
```

```javascript
log('当前脚本:' + hamibot.scriptName);
```

--------------------------------

### Get clipboard content

Source: https://docs.hamibot.com/reference/globals

Retrieves the current system clipboard text. On Android 10+, the app must be in the foreground.

```javascript
toast('剪贴板内容为:' + getClip());
```

--------------------------------

### dialogs.select(title, items, callback)

Source: https://docs.hamibot.com/reference/dialogs

Displays a list of options for the user to select from.

```APIDOC
## dialogs.select(title, items, callback)

### Description
Displays a list dialog. Returns the index of the selected item (0 to length-1), or -1 if cancelled.
```

--------------------------------

### Execute Script from String

Source: https://docs.hamibot.com/reference/engines

Runs a script provided as a string in a new environment. Use loop configuration for repeated execution.

```javascript
engines.execScript('hello world', "toast('hello world')");
```

```javascript
//每隔3秒运行一次脚本，循环10次
engines.execScript('hello world', "toast('hello world')", {
  loopTimes: 10,
  interval: 3000,
});
```

```javascript
function helloWorld() {
  //注意，这里的变量和脚本主体的变量并不共享
  toast('hello world');
}
engines.execScript('hello world', 'helloWorld();\n' + helloWorld.toString());
```

```javascript
function exec(action, args) {
  args = args || {};
  engines.execScript(
    action.name,
    action.name + '(' + JSON.stringify(args) + ');\n' + action.toString()
  );
}

//要执行的函数，是一个简单的加法
function add(args) {
  toast(args.a + args.b);
}

//在新的脚本环境中执行 1 + 2
exec(add, { a: 1, b: 2 });
```

--------------------------------

### View File

Source: https://docs.hamibot.com/reference/app

Opens a file using an external application. Throws an ActivityNotException if no suitable app is found.

```javascript
// 查看文本文件
app.viewFile('/storage/emulated/0/1.txt');
```

--------------------------------

### Demonstrate Thread-Unsafe Code

Source: https://docs.hamibot.com/reference/threads

An example of a race condition where multiple threads increment a shared variable without synchronization.

```javascript
var i = 0;
threads.start(function () {
  while (true) {
    log(i++);
  }
});
while (true) {
  log(i++);
}
```

--------------------------------

### dialogs.build(properties)

Source: https://docs.hamibot.com/reference/dialogs

Creates a highly customizable dialog instance.

```APIDOC
## dialogs.build(properties)

### Description
Creates a custom dialog based on the provided properties object. Returns a Dialog object that can be configured with event listeners (e.g., .on('positive', ...)) and displayed via .show().
```

--------------------------------

### Get device orientation and screen state

Source: https://docs.hamibot.com/reference/device

Retrieves the current screen orientation and checks if the device is in portrait or landscape mode.

```javascript
log('屏幕方向', device.getOrientation()); // 1 竖屏 2 横屏
log('竖屏', device.isPortrait());
log('横屏', device.isLandscape());
```

--------------------------------

### Display an input hint

Source: https://docs.hamibot.com/reference/ui

Sets a placeholder text that appears when the input field is empty.

```javascript
'ui';
ui.layout(
  <vertical>
    <input hint="请输入姓名" />
  </vertical>
);
```

--------------------------------

### Edit a file with an external application

Source: https://docs.hamibot.com/reference/app

Opens a file for editing using an installed application. Throws ActivityNotException if no suitable application is found.

```javascript
// 编辑文本文件
app.editFile("/storage/emulated/0/1.txt");
```

--------------------------------

### Capture Screen and Get Pixel Color

Source: https://docs.hamibot.com/reference/images.html

Requests landscape screen capture permissions and retrieves the color value at a specific coordinate.

```javascript
//请求横屏截图
if (!requestScreenCapture(true)) {
  toastLog('没有授予 Hamibot 屏幕截图权限');
  hamibot.exit();
}
sleep(1000);
//截图
var img = captureScreen();
//获取在点(100, 100)的颜色值
var color = images.pixel(img, 100, 100);
//显示该颜色值
toastLog(colors.toString(color));
hamibot.exit();
```

--------------------------------

### events.observeKey()

Source: https://docs.hamibot.com/reference/events

Enables key event monitoring (e.g., volume keys, Home key). This requires the accessibility service to be enabled.

```APIDOC
## events.observeKey()

### Description
Enables key event monitoring. This function must be called successfully before `onKeyDown` or `onKeyUp` listeners will function. Requires accessibility services.
```

--------------------------------

### POST /v1/devscripts/:id/run

Source: https://docs.hamibot.com/rest/devscripts

在指定设备上运行开发脚本。

```APIDOC
## POST /v1/devscripts/:id/run

### Description
在指定设备上运行开发脚本。

### Method
POST

### Endpoint
/v1/devscripts/:id/run

### Parameters
#### Path Parameters
- **id** (string) - Required - 开发脚本 ID

#### Request Body
- **devices** (array) - Required - 要执行脚本的设备列表
- **vars** (object) - Optional - 脚本配置，通过 hamibot.env 调用

### Response
#### Success Response (204)
- 成功执行

#### Error Response (422)
- 参数错误
```
Tokens:
Raw