agent_admin/docs/agent/actions/screenshot.md

SCREENSHOT [提案]

返回动作目录 · 统一选择器 · 基本运行约定

SCREENSHOT 用于诊断或人工复核。当前代码尚未实现。

1. 任务结构

截取控件区域：

{
  "id": "capture-result",
  "action": "SCREENSHOT",
  "packageName": "com.example.target",
  "scope": {
    "type": "ELEMENT",
    "selector": {
      "resourceId": "com.example.target:id/result"
    },
    "paddingDp": 8
  },
  "format": "PNG",
  "outputField": "resultImage",
  "maxBytes": 5242880,
  "timeoutMs": 5000
}

首批范围：

• SCREEN：当前显示屏。
• ELEMENT：唯一控件边界。
• REGION：显式屏幕比例区域。

首批格式支持 PNG；需要控制体积时再增加 JPEG 和质量参数。

2. 执行规则

1. 确认系统版本和无障碍服务具备截图能力。
2. 等待 packageName 和可选元素 selector。
3. 调用系统截图接口。
4. 在内存中按 scope 裁剪。
5. 编码并检查 maxBytes。
6. 保存到应用私有目录，返回生成的 artifactId。

任务不能提供任意文件系统路径。是否遮盖、上传或定期清理按实际部署需求增加，不作为首版动作的固定流程。

Android 无障碍截图从 API 30 开始可用；服务配置还需要声明对应能力。API 不支持时返回明确结果。

3. 输出

{
  "output": {
    "resultImage": {
      "artifactId": "generated-id",
      "format": "PNG",
      "width": 1080,
      "height": 720,
      "bytes": 245000
    }
  }
}

结果只返回产物标识和基本元数据，不把图片字节放入普通任务日志。

4. 结果码

• OK
• UNSUPPORTED_ON_DEVICE
• TARGET_NOT_FOUND
• TARGET_AMBIGUOUS
• CAPTURE_FAILED
• CROP_INVALID
• IMAGE_TOO_LARGE
• STORE_FAILED

5. 测试

单元测试覆盖 scope 校验、裁剪、大小限制和输出元数据。系统回调、不同 API、屏幕方向、FLAG_SECURE 和厂商差异需要真机验证。