Playwright AutoShot Easy 扣子IDE插件

📋 插件概述

面向「快速自动化」的易用插件：以最少输入执行常见浏览器动作（navigate / wait / click / fill / screenshot）。支持三种动作提供方式：
1）直接传 actions（数组）；2）多行 DSL 字符串；3）简化字段由插件自动生成。浏览器固定 chromium，支持移动端仿真（deviceName 或 viewport + isMobile）。

🎯 核心功能

动作执行 - POST /api/automation/execute
智能兼容 - 支持 actions 数组 / DSL 字符串 / 简化字段自动生成
稳健超时 - 60s 请求超时 + 429 指数退避重试

🔧 输入参数说明

必需参数

参数名	类型	说明	示例
`url`	string	目标页面 URL	`"https://example.com"`

可选基础参数

参数名	类型	默认值	说明
`base_url`	string	`http://106.55.254.115:4000`	Playwright API 服务地址（优先）
`ip`	string	`106.55.254.115`	与 `port`/`scheme` 组合出地址
`port`	string/integer	`4000`	服务端口
`scheme`	string	`http`	协议
`operation`	string	`execute`	支持：`health`/`docs`/`execute`

动作参数（必需其一）

actions（array 或 string）：
- 若为数组：例如 [{ "type":"wait","duration":500 }, ...]
- 若为字符串：多行 DSL（推荐由 playwright_steps_builder 生成）
DSL 语法：navigate <url>、wait <ms>、click <selector>、fill <selector>|<value>、screenshot、evaluate <js>（evaluate 顶层不要写 return，如需返回可用 (() => document.title)()）。

执行控制 & 移动端仿真

参数名	类型	默认值	说明
`waitFor`	integer	`8000`	服务端在动作之间的附加等待（毫秒）
`deviceName`	string	-	预设设备（如 `iPhone 12`、`Pixel 5`），自动带 UA/DPR/触摸/视口
`viewportWidth`	integer	-	自定义视口宽（与 `viewportHeight` 同用）
`viewportHeight`	integer	-	自定义视口高
`isMobile`	boolean	-	移动端布局（不等同于整页截图）

📤 输出结果

{
  "success": true,
  "message": "OK",
  "result_data": {
    "actionsCount": 3,
    "results": [
      { "type": "wait", "duration": 500 },
      { "type": "click", "selector": "text=More information", "success": true },
      { "type": "screenshot", "data": "iVBORw0K..." }
    ],
    "success": true,
    "timestamp": "2025-09-06T00:00:00.000Z",
    "url": "https://example.com"
  },
  "task_id": "",
  "metadata": { "endpoint": "/api/automation/execute" }
}

说明：results 按动作顺序返回；若包含 screenshot，data 常为 base64 图像（由服务端实现决定）。

示例1：与 Steps Builder 联动（DSL 字符串）

{
  "url": "https://example.com",
  "actions": "navigate https://example.com\nwait 500\nclick text=More information\nscreenshot"
}

示例2：直接传 DSL 字符串

{
  "url": "https://example.com",
  "actions": "navigate https://example.com\nwait 500\nclick text=More information\nscreenshot"
}

示例3：actions 数组

{
  "url": "https://example.com",
  "actions": [
    { "type": "wait", "duration": 500 },
    { "type": "evaluate", "script": "(() => document.title)()" },
    { "type": "screenshot" }
  ],
  "waitFor": 8000
}

示例4：移动端仿真（设备名）

{
  "url": "https://example.com",
  "actions": [ { "type": "screenshot" } ],
  "deviceName": "iPhone 12"
}

🔄 插件工作流程

A 读取连接与操作 → B 解析 actions（数组/DSL/简化字段） → C 组装执行 payload → D 调用 /api/automation/execute → E 透传结果

A：按 base_url > 环境变量 > ip/port/scheme > 默认，确定服务地址。
B：优先使用 actions；否则解析 DSL；再否则用简化字段生成（navigate→wait→click→fill→screenshot）。
C：合并 waitFor 与移动端仿真（deviceName 或 viewport+isMobile）。
D：提交至服务端，超时 60s；遇 429 进行指数退避重试（最多 3 次）。
E：原样返回服务端响应。

⚠️ 重要说明

仅 isMobile=true 不会自动整页；是否整页取决于步骤与截图策略（本插件不做整页拼接）。
DSL 的 evaluate 不要写顶层 return，建议 (() => document.title)() 或直接表达式。
至少需要一种动作来源（actions/DSL/简化字段），否则不会执行。

FAQ 常见问题

点击不生效？ 建议在打开页面后增加 500~1500ms 的 wait 再点击。
移动端效果不一致？ 优先使用 deviceName 获得更一致的 UA/DPR/触摸/视口。
需要更复杂的流程？ 可配合 playwright_steps_builder 生成更丰富的 DSL，或使用 Pro 版。

🔧 API 限制说明

请求超时：60s（插件内置）
429 频率限制：指数退避，最多 3 次
其余限制取决于 Playwright API Service 的部署与站点可达性

📞 技术支持

服务自检：/health
API 文档：/api-docs
静态访问域：https://playwright.caogiso.site