开发文档

平台简介

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

快速开始

脚本 API

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

// @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("未找到目标")
}

插件开发

插件是给脚本引擎「补充自定义命令」的 JS 文件：导出一个 commands 命令集， 每个命令就是一个异步函数。脚本里不需要任何 import，直接 await 命令名(...) 调用， 第一个参数自动注入引擎对象 engine（拥有全部脚本 API）。

/**
 * 我的第一个插件 · 保存为 my-first.plugin.js
 * 放进爱玩工坊的 workspace/plugins 目录（或在工坊「插件」面板导入）
 */
export default {
  name: "我的第一个插件",
  version: "1.0.0",
  desc: "示例：连招、找图点击、带重试的等待",

  commands: {
    // 脚本里：await combo(100, 200)
    async combo(engine, x, y) {
      await engine.tap(x, y)
      await engine.sleep(120)
      await engine.tap(x + 50, y)
      await engine.sleep(120)
      await engine.swipe(x, y, x, y - 200, 300)
    },

    // 脚本里：await tapUntilGone("开始战斗", 10)
    async tapUntilGone(engine, text, maxTimes = 10) {
      for (let i = 0; i < maxTimes; i++) {
        const n = await engine.findByText(text)
        if (!n) return true          // 找不到了 = 已经消失
        await engine.tapText(text)
        await engine.sleep(1000)
      }
      return false
    }
  }
}

/* 安卓端：var __plugin 代替 export default，其余完全一致。
 * 手动安装时放进设备 filesDir/plugins；一般建议直接走云端安装（自动转换） */
var __plugin = {
  name: "我的第一个插件",
  version: "1.0.0",
  desc: "示例",
  commands: {
    async combo(engine, x, y) {
      await engine.tap(x, y)
      await engine.sleep(120)
    }
  }
}

engine 上挂载了全部脚本 API，插件里可直接调用。常用：

参数表单 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 接口

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

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"

角色与权限

常见问题