自定义脚本

内置脚本覆盖了常见流程。当你需要的功能它们没有提供时——换一个执行顺序、操作它们没触及的界面，或者自动化 TikTok / Instagram 以外的应用——你可以用任意语言自己写，由 TikMatrix 把手机交给你。

使用要求

授权要求

自定义脚本需要 Pro、Team 或 Business 套餐。 Starter 套餐不提供此功能。

套餐的设备数同时也是并发上限：Pro 套餐（20 台设备）最多同时驱动 20 台手机，无论走内置任务、自定义脚本，还是两者混用。

两种运行方式

独立运行

你自己运行程序，TikMatrix 只负责把设备借给你。

from tikmatrix import TikMatrix

client = TikMatrix()

for device in client.devices():
    if device["busy"]:
        continue
    with client.device(device["serial"], label="my crawler") as d:
        d.press("home")
        print(d.info())

适合一次性任务、数据采集，以及任何你想用自己的调度器来跑的场景。

托管运行

把程序注册到 TikMatrix，它就变成一个普通任务，可以使用任务队列、按套餐限制并发、自动重试、任务日志和定时计划模板。TikMatrix 会在启动你的程序之前先占用设备，并把租约 ID 通过环境变量传进去。

from tikmatrix import TikMatrix

with TikMatrix.from_env() as d:   # 设备已经占用好了
    d.click(text="Log in")
    print("done")                 # 这一行会出现在任务日志里

适合需要重复执行、定时执行或跨大量设备执行的场景。

快速开始

1. 安装客户端库

pip install requests

然后把 SDK 目录里的 tikmatrix.py 复制到你的脚本旁边。这个库只有单个文件，没有其它依赖。

你也可以不用它——接口就是普通的 JSON over HTTP，下面有原始接口清单。

2. 编写脚本

from tikmatrix import TikMatrix

client = TikMatrix()
with client.device("192.168.1.5:5555") as d:
    d.press("home")
    d.adb("shell", "am", "start", "-a", "android.settings.SETTINGS")
    d.wait_for(text="Settings", timeout=15)
    d.screenshot("settings.png")

3. 注册脚本（仅托管模式需要）

进入 设备 → 自定义脚本 → 添加脚本：

字段	含义
名称	显示在脚本列表和任务日志中
启动命令	要执行的程序命令行，例如 `python C:/scripts/my_flow.py`
工作目录	可选，程序的启动目录
平台	见下方平台模式
超时（秒）	超过后脚本被终止、任务标记为失败。默认 1800
额外环境变量	可选的 JSON 对象，会合并进程序的环境变量

之后点击脚本行上的 ▶ 按钮，像内置脚本一样选择设备即可。

设备租约

一台手机同一时间只能被一个东西驱动。占用（租约）会告诉 TikMatrix 这台设备正忙，于是：

任务队列不会再往同一块屏幕上派发任务；
你发出的 JSON-RPC 调用会像内置脚本一样上报 agent 健康状态，看门狗看到的是一个正忙的 agent，而不是一个失联的 agent。

租约同样会占用套餐中的一个设备名额。

租约会过期——默认 120 秒，最长 600 秒。Python 库会在后台线程自动续期，并在 with 代码块结束时释放，所以脚本崩溃后设备几秒内就会回到可用池，而不是一直被占到你重启软件为止。如果你直接调用接口，就需要自己发送心跳。

在 设置 → 开发者 API → 设备占用会话 中可以查看所有存活的租约，也可以手动释放。

平台模式

注册脚本时需要声明它面向的平台：

通用（generic） —— 设备原样交给你。不启动任何应用、不切换账号、不检查输入法，结束后也不关闭任何东西。用于自动化 TikTok / Instagram 以外的一切。

TikTok / Instagram —— 在你的程序启动前先打开应用并切换好账号，结束后关闭应用，行为与内置脚本完全一致。TIKMATRIX_PACKAGE 会告诉你解析出的包名。用于补充内置脚本没覆盖的步骤。

环境变量

托管脚本会收到：

变量	含义
`TIKMATRIX_API_BASE`	服务地址，例如 `http://127.0.0.1:50809`
`TIKMATRIX_SESSION_ID`	已经替你申请好的租约
`TIKMATRIX_SERIAL`	本次任务派发到的设备
`TIKMATRIX_PACKAGE`	解析出的应用包名
`TIKMATRIX_PLATFORM`	`tiktok`、`instagram` 或 `generic`

TikMatrix.from_env() 会自动读取以上全部变量。

独立运行的脚本拿不到这些变量——请自己显式申请设备租约。

常用操作

d.info()                                  # 设备信息
d.window_size()                           # (宽, 高)
d.screenshot("shot.png")                  # PNG 字节，可选保存到文件

d.find(text="Following")                  # 匹配到的节点，含 bounds 和 center
d.exists(resource_id="com.app:id/login")
d.wait_for(text="Home", timeout=15)       # 阻塞直到元素出现
d.click(text="Log in")                    # 等待出现后点击其中心

d.click_xy(540, 1200)
d.swipe(540, 1600, 540, 600)
d.press("back")                           # back / home / recent / enter
d.input_text("hello")                     # 通过内置输入法输入

d.jsonrpc("deviceInfo")                   # 任意 UIAutomator2 方法
d.adb("shell", "pm", "list", "packages")  # ADB，需在设置中启用

find 是在 dump 出来的 UI 树上匹配的，所以选择器没命中时，可以 print(d.hierarchy()) 看看它到底在什么内容里查找。设备界面里的元素检查器能可视化展示同一棵树，通常是找 resource-id 最快的方式。

HTTP 接口

设备类操作需要 x-session-id 请求头来指明一个存活的租约。没有 API 密钥：和本地 API 的其余部分一样，这些接口不做认证——能访问到这台机器的网络，就是访问控制本身。这些接口不返回任何 CORS 头，因此请用程序（curl、Python 等）调用，而不是在浏览器页面里调用。

方法	路径	用途
`GET`	`/api/v1/rpc/devices`	列出在线设备及其是否忙碌
`POST`	`/api/v1/rpc/session`	占用设备 → 返回 `session_id`
`POST`	`/api/v1/rpc/session/{id}/heartbeat`	续期租约
`DELETE`	`/api/v1/rpc/session/{id}`	释放租约
`GET`	`/api/v1/rpc/session`	列出存活的租约
`POST`	`/api/v1/rpc/jsonrpc`	调用 UIAutomator2 方法
`POST`	`/api/v1/rpc/adb`	执行 ADB 命令
`GET`	`/api/v1/rpc/hierarchy?serial=`	当前 UI 树（XML）
`GET`	`/api/v1/rpc/screenshot?serial=`	当前屏幕截图（PNG）

示例

# 占用设备
curl -X POST http://127.0.0.1:50809/api/v1/rpc/session \
  -H "Content-Type: application/json" \
  -d '{"serial":"192.168.1.5:5555","label":"curl test","ttl_secs":120}'

# {"code":0,"message":"success","data":{"session_id":"ff3ae079-...","serial":"192.168.1.5:5555", ...}}

# 驱动设备
curl -X POST http://127.0.0.1:50809/api/v1/rpc/jsonrpc \
  -H "x-session-id: ff3ae079-..." \
  -H "Content-Type: application/json" \
  -d '{"serial":"192.168.1.5:5555","method":"deviceInfo","params":[]}'

# 归还设备
curl -X DELETE http://127.0.0.1:50809/api/v1/rpc/session/ff3ae079-...

错误码

状态码	含义
403	套餐低于 Pro、未持有租约、租约已过期，或 ADB 访问被关闭
409	设备已被占用，或套餐并发名额已满

通过 API 触发自定义脚本

已注册的脚本也可以通过任务管理 API 启动，这样一个脚本就能给自己排后续的任务：

curl -X POST http://127.0.0.1:50809/api/v1/task \
  -H "Content-Type: application/json" \
  -d '{
    "serials": ["192.168.1.5:5555"],
    "script_name": "custom_script",
    "script_config": {
      "custom_script_id": 1,
      "custom_script_platform": "generic"
    }
  }'

custom_script_id 就是你注册的那个脚本的 id。

ADB 权限

/api/v1/rpc/adb 会给脚本一个设备 shell —— 推送素材、安装 APK、修改系统设置都需要它。正因为它等同于完整的 shell 权限，而这个接口本身没有 API key，所以默认是关闭的。当你确实有脚本需要它时，再到 设置 → 开发者 API → 允许执行 ADB 命令 中打开；只做界面自动化的脚本走 /rpc/jsonrpc 即可，无需开启。

关闭期间 /api/v1/rpc/adb 返回 403，其余接口照常工作。脚本执行过的每一条 ADB 命令都会写进你的日志文件。

注意事项与限制

命令是直接执行的，不经过 shell，所以 && 和 | 会被当作参数而不是操作符。需要 shell 行为请注册 cmd /c "..."（Windows）或 sh -c "..."（macOS）。
含空格的路径要加引号："C:/Program Files/Python/python.exe" my_script.py。
超时的脚本会被终止，任务标记为失败。
退出码非 0 即任务失败；脚本写入 stdout 和 stderr 的所有内容都会进入任务日志。
脚本以与 TikMatrix 相同的权限运行，请只注册你自己编写或信任的程序。

下一步

本地 API 概览 —— 响应格式与通用约定
任务管理 API —— 创建、查询、重试和停止任务
GitHub 上的 SDK 与示例

使用要求​

两种运行方式​

独立运行​

托管运行​

快速开始​

1. 安装客户端库​

2. 编写脚本​

3. 注册脚本（仅托管模式需要）​

设备租约​

平台模式​

环境变量​

常用操作​

HTTP 接口​

示例​

错误码​

通过 API 触发自定义脚本​

ADB 权限​

注意事项与限制​

下一步​