# SCREENSHOT **[提案]**

> [返回动作目录](README.md) · [统一选择器](../selector.md) · [基本运行约定](../security.md)

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

## 1. 任务结构

截取控件区域：

~~~json
{
  "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. 输出

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

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

## 4. 结果码

见[结果码总表](README.md#结果码总表)。SCREENSHOT 使用 `OK`、`UNSUPPORTED_ON_DEVICE`、`TARGET_NOT_FOUND`、`TARGET_AMBIGUOUS` 和 `ACTION_FAILED`（截图、裁剪、超限或保存失败）。

截图各阶段的失败是否需要拆成独立码，等实现时按排查需要决定。

## 5. 测试

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