Playwright Screenshot 扣子IDE插件

📋 插件概述

基于自建 Playwright API Service 的截图类扣子 IDE 插件，提供页面截图（首屏/整页）、截图列表查询，以及基础健康检查与文档查看。浏览器固定为 chromium，支持可选的移动端仿真（设备预设或自定义视口）。

🎯 核心功能

健康检查 - GET /health
接口文档 - GET /api-docs
标准截图 - POST /api/screenshot/capture
整页截图 - POST /api/screenshot/fullpage
截图列表 - GET /api/screenshot/list

当未显式传入 operation 且提供了 url 时：fullPage=false 走标准截图；fullPage=true 走整页截图。

🔧 输入参数说明

必需参数（用于截图）

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

可选基础连接参数

参数名	类型	默认值	说明
`base_url`	string	`http://106.55.254.115:4000`	完整服务地址（优先级最高）
`ip`	string	`106.55.254.115`	服务 IP（与 `port`/`scheme` 组合使用）
`port`	string/integer	`4000`	服务端口
`scheme`	string	`http`	协议

截图参数

参数名	类型	默认值	说明
`type`	string	`png`	图片类型，支持 `png`/`jpeg`
`quality`	integer	-	图片质量（仅 `jpeg` 生效）
`fullPage`	boolean	`false`	是否整页；为 `true` 时将调用整页接口
`clip_x`	integer	-	裁剪区域 x
`clip_y`	integer	-	裁剪区域 y
`clip_width`	integer	-	裁剪区域 width
`clip_height`	integer	-	裁剪区域 height

移动端仿真（可选）

参数名	类型	说明
`deviceName`	string	预设设备名（如 `iPhone 12`、`Pixel 5`），会带上对应 UA/触摸/DPR/视口
`viewportWidth`	integer	自定义视口宽（与 `viewportHeight` 同用）
`viewportHeight`	integer	自定义视口高
`isMobile`	boolean	移动端布局渲染开关（不等同于整页）

仅设置 isMobile=true 并不会自动整页截图；如需整页请传 fullPage=true。

📤 输出结果

{
  "success": true,
  "message": "OK",
  "result_data": {
    "filename": "screenshot-1757147293000.png",
    "filepath": "/app/screenshots/screenshot-1757147293000.png",
    "success": true,
    "timestamp": "2025-09-04T06:43:45.092Z",
    "url": "https://example.com",
    "public_url": "https://playwright.caogiso.site/screenshots/screenshot-1757147293000.png"
  },
  "task_id": "",
  "metadata": { "endpoint": "/api/screenshot/capture" }
}

提示：public_url 由 PLAYWRIGHT_PUBLIC_BASE 与 filename 拼接，默认域名 https://playwright.caogiso.site。

示例1：基础首屏截图

{ "url": "https://example.com" }

示例2：整页截图

{ "url": "https://example.com", "fullPage": true }

示例3：手机机型 + 整页

{ "url": "https://example.com", "fullPage": true, "deviceName": "iPhone 12" }

示例4：自定义移动视口（仅首屏）

{
  "url": "https://example.com",
  "fullPage": false,
  "viewportWidth": 375,
  "viewportHeight": 812,
  "isMobile": true
}

示例5：裁剪区域

{
  "url": "https://example.com",
  "clip_x": 0,
  "clip_y": 0,
  "clip_width": 800,
  "clip_height": 600
}

🔄 插件工作流程

A 参数读取/校验 → B 解析连接配置 → C 组装请求参数 → D 调用 API → E 透传结果并拼接 public_url → F 返回标准化结构

A：校验必填 url（截图类操作）
B：按 base_url > 环境变量 > ip/port/scheme > 默认顺序确定服务地址
C：合并截图与移动端仿真参数
D：发送 HTTP 请求（超时 60s；429 指数退避最多 3 次）
E：若返回包含 filename，拼接 public_url
F：返回标准结构

⚠️ 重要说明

仅 isMobile=true 不会自动整页；如需整页请传 fullPage=true。
若需“首屏但更长”，请增大 viewportHeight。
推荐使用 deviceName 以获得 UA/触摸/DPR/视口等一致的移动端表现。
JPEG 质量通过 quality 控制；PNG 无此参数。

FAQ 常见问题

截图高度不全？ 默认首屏或未开启整页；使用 fullPage=true 或增大 viewportHeight。
移动端效果与浏览器设备仿真不一致？ 仅设置 isMobile 未指定具体 UA/DPR；优先传 deviceName。
公开链接无法访问？ 检查 Nginx/服务是否映射 /screenshots，并确认 PLAYWRIGHT_PUBLIC_BASE 配置。

🔧 API 限制说明

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

📞 技术支持

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