开发文档

从写第一个脚本到批量云控，这里有你需要的全部接口说明。

平台简介

爱玩脚本工作室是一套安卓自动化脚本的「开发 + 分发 + 调度」平台，由四个子系统组成：

官网

产品介绍、下载中心、脚本市场、公告

开发者后台

应用管理、上传发布、收益结算、提现、API 密钥

网站后台

用户、应用审核、卡密、订单、结算系数、站点设置

云控后台

设备纳管、分组、批量下发、实时日志、数据大屏

能力边界

平台只做「模拟人手操作」：点击、滑动、输入、读屏、找图、找色、识别文字，全部基于 Android 无障碍服务与截屏，免 Root、不注入。不提供内存读写、进程注入、加速、协议重放等越过用户界面层的能力。

快速开始

① 下载并安装开发工具

安卓端 APK 装在模拟器 / 云手机 / 真机；PC 端 exe 装在电脑（通过 ADB 连设备）。见下载中心。

② 开启无障碍权限

首次启动按引导开启，这是点击、滑动、读屏的基础能力。

③ 在 AI 面板描述需求

例如「打开游戏后自动完成签到、领邮件、日常任务，循环 3 次，遇到弹窗自动关闭」。

④ 运行、调试、发布

点运行看效果；用抓抓 / 控件树 / 录制器微调；满意后发布成独立 APK 或上架市场。

脚本 API

脚本语言是 JavaScript，运行在沙箱中，无需 import。脚本头部用 // @design 1080x1920 声明设计分辨率，引擎会自动换算到目标设备。

分类	API	说明
基础操作	tap(x, y)	点击坐标
	swipe(x1,y1,x2,y2,dur)	滑动
	input(text)	输入文本
	back() / home()	返回 / 回桌面
	sleep(ms)	等待
	toast(msg) / log(...)	提示与日志
图像识别	find(img, opt)	模板匹配找图，返回坐标
	findColor(hex, opt)	找色
	findMultiColor(first, pts, opt)	多点找色（偏移组）
	findMultiColorAll / findColorAll	找全部匹配
	countColor(hex, opt)	统计颜色数量（血条 / 进度条）
	cmpColor(first, pts, opt)	多点比对（判断是否在某界面）
文本与控件	nodes(limit)	读取控件树
	findByText(t)	按文本找控件
	tapText(t)	点击指定文本控件
	text(t)	获取控件文本
流程控制	waitFor(fn, timeout)	等待条件成立
	retry(fn, n)	失败重试
	stop(msg) / chooseFeature(...)	停止 / 功能选择入口

多点找色示例

// @design 1080x1920
// 第一个点作为锚点，后续点用 "#颜色-偏色" 描述相对偏移
const pt = findMultiColor(
  "5AC8FA-101010",                 // 锚点颜色（含偏色容差）
  [
    "12,0,FFFFFF-101010",          // 相对锚点偏移 (+12, 0) 应是白色
    "0,14,FF3B30-101010",          // 相对锚点偏移 (0, +14) 应是红色
    "24,24,34C759-101010"
  ],
  { region: [0, 0, 1080, 1920], threshold: 0.9 }
)
if (pt) {
  toast("找到目标: " + pt.x + "," + pt.y)
  tap(pt.x, pt.y)
} else {
  toast("未找到目标")
}

参数表单 showForm

把参数从代码里挪到界面上。运行前弹出配置界面，改参数不用碰代码。

const cfg = await showForm([
  { type: "radio",    id: "mode",  label: "运行模式", options: ["快速", "完整"], default: "快速" },
  { type: "checkbox", id: "tasks", label: "要做的事情", options: ["主线", "日常", "刷野"], default: ["主线"] },
  { type: "select",   id: "server", label: "目标区服", options: ["一区", "二区", "三区"] },
  { type: "number",   id: "times", label: "循环次数", default: 3 },
  { type: "switch",   id: "autoFix", label: "异常自动重试", default: true },
  { type: "slider",   id: "delay", label: "操作间隔(ms)", min: 200, max: 3000, default: 800 },
  { type: "text",     id: "account", label: "账号" }
])
if (!cfg) return stop("用户取消")

if (cfg.tasks.includes("主线")) { /* ... */ }

云控接入

云控后台支持把云手机、模拟器、真机统一纳管，按分组批量下发任务，执行日志实时回传。

① 添加设备

云控后台 → 设备管理 → 添加设备，填名称与分组。

② 获取 Agent Key

点设备卡片上的「接入」，复制 Agent Key 或下载专属接入脚本。

③ 让设备上线

在能访问 adb 的电脑执行接入脚本，或把心跳逻辑内置到设备的开机自启中。

④ 批量下发

设备显示在线后，在「批量任务」或「脚本下发」中选择目标范围，一键下发。

设备 Agent 接口

所有请求需带请求头 X-Agent-Key: <设备 Agent Key>。

方法	路径	说明
POST	/api/agent/register	上线注册，上报型号 / 系统 / 分辨率
POST	/api/agent/heartbeat	心跳，建议 3-10 秒一次，返回是否有待执行任务
GET	/api/agent/poll	拉取待执行任务
POST	/api/agent/report	上报任务结果与日志
POST	/api/agent/log	执行过程中上报实时日志

curl -X POST http://www.awzs.top/api/agent/register \
  -H "Content-Type: application/json" \
  -d '{"agent_key":"DK-XXXX","model":"Pixel 6","android_ver":"13"}'

curl "http://www.awzs.top/api/agent/poll?agent_key=DK-XXXX"

角色与权限

角色	入口	权限
普通用户	/cloud.html	浏览市场、激活卡密、管理自己的云控设备
开发者	/dev.html	上架应用、收益分账、提现、API 密钥、云端脚本库
管理员	/admin.html	全部权限，含用户、审核、卡密、结算、站点设置

演示账号

管理员 admin / admin123
开发者 developer / dev123456
普通用户 user1 / 123456

常见问题

需要 Root 吗？

不需要。全部基于无障碍服务与截屏实现。

脚本能加密吗？

平台支持把脚本打包成独立 APK 分发；服务端存储的脚本仅授权账号可读取。

收益怎么算？

按频道系数 × 当日 DAU：免费 0.05、平台 VIP 0.4、单脚本付费 50% 分成。系数可在网站后台实时调整并对历史未结算数据重算。

云控支持多少设备？

采用心跳 + 拉取模式，设备只出网入网、不要求固定 IP，可水平扩展到数百台。

AI 生成需要自己的密钥吗？

平台可在网站后台统一配置 OpenAI 兼容接口；未配置时返回可用示例骨架，方便先跑通流程。