WebStack-Screenshot 扣子IDE插件

插件概述

专为扣子IDE设计的网页截图工具，已完全集成price.caogiso.site统一API密钥管理系统。支持多种格式、灵活参数配置、自动保存与直接下载链接。

核心特性

JPEG/PNG/WebP 多格式
灵活参数 + 智能重试
自动保存 + 直链/预览/下载
异步查询任务进度
云端优化与稳定域名
API密钥认证与用量统计
统一用户管理与权限控制

服务地址

主域名：

http://screenshot.caogiso.site:xxxx

备用IP：

http://xxx.xx.xxx.xxx:6870

快速上手

推荐先用基础参数完成首次截图

基础参数（推荐）

参数名	类型	默认值	说明	注意事项
`url`	string	-	要截图的网页URL	必需参数
`type`	string	"jpeg"	图片格式	可选: jpeg, png, webp；quality 仅对 jpeg/webp 生效
`quality`	integer	80	图片质量(1-100)	仅当 type 为 jpeg/webp 生效
`viewport`	string	"1920x1080"	视口大小	格式: 宽x高
`full_page`	boolean	false	是否全页截图	为 true 时忽略 `viewport` 的高度
`is_mobile`	boolean	false	移动设备模式	影响 UA/布局，不改变像素密度
`clip`	string	-	裁剪区域	格式: x,y,width,height；x/y 可为 0；与 full_page 互斥

高级参数（可选）

参数名	类型	默认值	说明	注意事项
`encoding`	string	"binary"	返回编码格式	`base64` 时返回 data URI/JSON
`timeout`	integer	60	超时时间(秒)	1-300
`await_time`	integer	0	导航后额外等待(毫秒)	处理动态渲染/动画
`wait_until`	string	load	导航等待条件	可选: domcontentloaded/networkidle0；失败自动降级
`cache`	integer/boolean	86400	缓存时间(秒)	false=禁用缓存
`api_url`	string	-	服务地址	可用环境变量 `WEBSTACK_SCREENSHOT_API_URL` 指定
`api_key`	string	-	API密钥	必需参数，用于认证和用量统计

viewport 与 full_page、is_mobile 的关系

关系总览

full_page=false：输出范围由 viewport 决定（宽=视口宽，高=视口高）
full_page=true：仅使用 viewport 宽度，高度为页面滚动高度（含懒加载滚动）
is_mobile=true：改变 UA/设备指标，触发移动布局，不强制改动 viewport

常见问答

问：当 full_page=true 且 is_mobile=true 且 viewport="375x667" 时，是否只有 375 生效？

答：是。此时高度 667 被忽略，仅使用宽度 375。

基础使用示例（需要API密钥）

{
  "url": "https://www.baidu.com",
  "type": "jpeg",
  "quality": 80,
  "viewport": "1920x1080"
}

高级使用示例（移动全页）

{
  "url": "https://www.example.com",
  "type": "png",
  "viewport": "375x667",
  "is_mobile": true,
  "full_page": true,
  "await_time": 2000,
  "encoding": "binary"
}

裁剪示例（支持 x/y = 0）

{
  "url": "https://www.baidu.com",
  "type": "png",
  "viewport": "1920x1080",
  "full_page": false,
  "is_mobile": false,
  "clip": "0,0,800,600"
}

测试使用示例（多参数组合）

{
  "url": "https://www.github.com",
  "type": "webp",
  "quality": 90,
  "viewport": "1440x900",
  "full_page": false,
  "is_mobile": false,
  "cache": false,
  "timeout": 60
}

工作流程

A. 接收请求参数 → B. 验证参数格式 → C. 构建API请求 → D. 发送截图请求 → E. 处理响应结果 → F. 生成下载链接 → G. 返回结果数据

A. 接收请求参数

验证必需参数 url，设置默认值

B. 验证参数格式

检查参数类型，转换布尔值和数字

C. 构建API请求

构建符合 WebStack-Screenshot API 的请求参数

D. 发送截图请求

发送请求到截图服务，包含智能重试机制

E. 处理响应结果

解析响应，处理成功/失败情况

F. 生成下载链接

构建动态的直接访问 URL

G. 返回结果数据

返回包含下载链接与保存信息的完整结果

成功响应示例

{
  "success": true,
  "message": "截图生成成功并已保存",
  "task_id": "screenshot_1703123456",
  "result_data": [
    {
      "image_data": "binary_data_available",
      "encoding": "binary",
      "size_bytes": 64793,
      "content_type": "image/jpeg",
      "cache_control": "public, no-transform, s-maxage=86400, max-age=86400",
      "direct_url": "http://screenshot.caogiso.site:6870/screenshot?url=https://www.baidu.com&type=jpeg&quality=80&t=1703123456&viewport=1920x1080",
      "download_url": "http://screenshot.caogiso.site:6870/screenshot?url=https://www.baidu.com&type=jpeg&quality=80&t=1703123456&viewport=1920x1080",
      "preview_url": "http://screenshot.caogiso.site:6870/screenshot?url=https://www.baidu.com&type=jpeg&quality=80&t=1703123456&viewport=1920x1080",
      "download_filename": "screenshot_1703123456.jpg",
      "file_size_mb": 0.06,
      "status": "completed",
      "timestamp": 1703123456,
      "saved_file_path": "/tmp/screenshots/screenshot_www_baidu_com_1703123456.jpg",
      "saved_filename": "screenshot_www_baidu_com_1703123456.jpg",
      "saved_file_size": 64793,
      "saved_file_size_mb": 0.06,
      "saved_timestamp": 1703123456,
      "saved_directory": "/tmp/screenshots"
    }
  ],
  "metadata": {
    "url": "https://www.baidu.com",
    "type": "jpeg",
    "quality": 80,
    "viewport": "1920x1080",
    "full_page": false,
    "is_mobile": false,
    "encoding": "binary",
    "api_url": "http://screenshot.caogiso.site:6870"
  }
}

常见问题解决

现象：连接错误。解决：检查服务运行、验证 api_url、放行 6870 端口、尝试备用地址。

云端无法访问本地服务。使用服务器 IP 或域名：http://screenshot.caogiso.site:6870，插件会自动尝试多个地址。

增加 timeout（默认 60s），检查网络，减少 await_time，简化参数。

提高 quality，或改用 PNG；调整 viewport；适当增加 await_time。

API 限制与安全

频率/并发

最多 10 req/min
并发最多 5 个
自动排队与重试

数据大小

图片 ≤ 50MB
URL ≤ 2048 字符
超时 ≤ 300s

安全建议

敏感信息用环境变量
避免硬编码
推荐使用 HTTPS

性能建议

合理设置 timeout
使用 cache
避免不必要的全页截图

WebStack-Screenshot Coze IDE插件（已集成price.caogiso.site）

插件概述

核心特性

服务地址

快速上手

基础参数（推荐）

高级参数（可选）

viewport 与 full_page、is_mobile 的关系

关系总览

推荐组合

常见问答

基础使用示例（需要API密钥）

高级使用示例（移动全页）

裁剪示例（支持 x/y = 0）

测试使用示例（多参数组合）

工作流程

A. 接收请求参数

B. 验证参数格式

C. 构建API请求

D. 发送截图请求

E. 处理响应结果

F. 生成下载链接

G. 返回结果数据

成功响应示例

常见问题解决

API 限制与安全

插件概述

核心特性

服务地址

快速上手

基础参数（推荐）

高级参数（可选）

viewport 与 full_page、is_mobile 的关系

关系总览

推荐组合

常见问答

基础使用示例（需要API密钥）

高级使用示例（移动全页）

裁剪示例（支持 x/y = 0）

测试使用示例（多参数组合）

工作流程

A. 接收请求参数

B. 验证参数格式

C. 构建API请求

D. 发送截图请求

E. 处理响应结果

F. 生成下载链接

G. 返回结果数据

成功响应示例

常见问题解决

1. 连接错误

2. 云端环境连接问题

3. 请求超时

4. 图片质量问题

API 限制与安全