developer-device-platform-device-run

开发者设备平台：Device Run

Device Run 会在远程 DDP 设备上执行作业，并将其工件（日志、拉取的文件）返回到 Cloud Storage 存储桶。一个会话会为每台请求的设备启动一个作业。

警告

开发者设备平台（DDP）目前处于预览阶段。 gcloud beta device-run 命令可能会随时更改，恕不另行通知。

何时使用此技能

用户想要……	使用
在远程设备上运行原生二进制文件或 shell 脚本	此技能（android-executable）
在远程设备上运行 Android instrumentation 测试 APK	此技能（instrumentation）
预留设备、通过 adb 连接、串流屏幕	developer-device-platform-basics
延长或取消交互式设备租约	developer-device-platform-basics
使用通过 USB 连接的设备	两者都不用（非 DDP）

以下设置已完成；此技能不依赖其他技能来进行身份验证、选择项目或启用 API。

此技能不处理的请求

对于交互式使用（预留设备、adb、屏幕串流、租约）：

• **如果已安装 developer-device-platform-basics：**不要提交 Device Run 会话；切换到 developer-device-platform-basics，并说明交互式预留也会计入当前有效项目的费用。
• **如果未安装 developer-device-platform-basics：**只用一条消息回复，不要调用任何工具（不运行命令、不搜索、不读取文件，也不进行计划安排），然后停止：
  1. 说明 Device Run 用于非交互式批处理作业，因此你不会提交 Device Run 会话。
  2. 引导用户使用 developer-device-platform-basics 技能进行交互式 Device Streaming 预留（或访问 https://docs.cloud.google.com/device-streaming/docs/overview.md.txt），并建议安装该技能。
  3. 提醒用户，交互式预留也会计入当前有效的 Google Cloud 项目的费用。

加快答复

查询 Device Run 语法时，优先使用此技能和 gcloud beta device-run ... --help，而不是广泛搜索网页。如果未安装 gcloud 或 beta 组件，请改用官方文档：https://docs.cloud.google.com/developer-device-platform/device-run.md.txt 和 https://docs.cloud.google.com/sdk/gcloud/reference/beta/device-run。对于试运行，请展示命令，而不要运行。

用量归属

**必须阅读：**在执行任何 gcloud、REST API 或 MCP 命令之前，必须阅读并遵循用量归属中的说明。

设置

每个环境只需运行一次这些检查。不要假定工具已安装，也不要未经用户批准就安装或更新软件。

1. gcloud CLI：检查是否已安装 gcloud，以及是否包含 Device Run 命令：

   gcloud --version
   gcloud beta device-run sessions submit android-executable --help >/dev/null
   

   如果缺少 gcloud，请告知用户访问 https://docs.cloud.google.com/sdk/docs/install-sdk.md.txt。如果缺少 beta 组件或 Device Run 命令，运行 gcloud components install beta 或 gcloud components update 前请先询问用户。

2. 身份验证：检查当前使用的账号。在 Compute Engine 或其他远程虚拟机上，当前账号可能是虚拟机的默认服务账号 ([email protected])，它通常缺少 Device Run 和账单调用所需的范围（No service account scopes specified）。如果没有当前账号，或者当前账号只有这类服务账号，请让用户登录。 --update-adc 也会在同一流程中更新应用默认凭据；在 SSH 或远程终端中添加 --no-launch-browser：

   gcloud auth list --filter=status:ACTIVE --format="value(account)"
   gcloud auth login --update-adc
   

3. 项目：使用用户当前的项目，或用户指定的项目。绝不要硬编码项目，也不要未经询问就更改当前项目。

   export PROJECT_ID=$(gcloud config get project)
   # 仅在用户要求切换时执行：
   gcloud config set project PROJECT_ID
   

4. 账单：Device Run 的费用计入项目。检查是否已启用账单；如果未启用，请停止并告知用户。

   gcloud billing projects describe "${PROJECT_ID}" \
     --format="value(billingEnabled)"
   

5. 启用 Device Run API（如果尚未启用，请先询问）：

   gcloud services enable devicerun.googleapis.com --project="${PROJECT_ID}"
   

6. IAM 角色：用户需要在项目中拥有 roles/devicerun.admin、 roles/serviceusage.serviceUsageConsumer 和 roles/viewer。若要从其他项目的存储桶读取输入，请向该存储桶授予 DDP 服务代理 roles/storage.objectViewer 角色（参见 https://docs.cloud.google.com/developer-device-platform/device-run/share-storage.md.txt）。

7. 存储桶：会话会在 Cloud Storage 中存储输入和输出。未指定 --bucket-name 时，gcloud 会使用或创建 gs://${PROJECT_ID}-devicerun。对于包含 :、. 或 google 的项目 ID，gcloud 会先将其替换为 -、- 和 elgoog，然后再添加 -devicerun；请从 submit 或 describe 打印的 Result files URI 中查看实际存储桶。使用 --bucket-name 显式指定的存储桶必须已存在。只传入存储桶名称（不带 gs://，也不带路径）。gs://<bucket>/automation/ 下的输入和输出会一直保留，直到你删除它们或 Cloud Storage 生命周期规则使其过期；期间会产生存储费用。

核心工作流

1. 选择设备。 用户通常会使用设备的商品名称（如“Pixel 10”“Galaxy S22”），而 --device 需要的是目录 ID，例如 frankel-36（代号 + Android API 级别）。请通过实时目录，将名称解析为 ID，参阅 device_selection.md；切勿凭记忆猜测 ID。如果某款设备提供多个 Android 版本，而用户没有指定版本，请列出这些版本、推荐一个，并让用户选择一个、多个（每个版本一个作业）或全部；切勿擅自选择。提交前，向用户展示解析后的 ID、设备名称和 Android 版本，并指出你替用户做出的任何其他选择（实体设备还是虚拟设备、变体）。

2. 准备输入。 --executable、--test、--target-app 和 --other-files-to-push 的源路径都支持 gs:// 路径或本地路径。本地文件会自动上传到新的 automation/inputs/<timestamp>/ 文件夹，因此对于每次运行都会变化的文件（脚本、刚构建的二进制文件），优先使用本地路径。对于较大的重复使用文件（模型、数据集），请将其上传到存储桶一次，然后通过 gs:// 路径引用。

3. 确认费用。 必须获得用户的明确确认。 Device Run 会话的费用计入当前 Google Cloud 项目。提交前，请告知用户项目（${PROJECT_ID}）、设备、作业数量和超时时间，提醒用户这会产生费用，然后暂停，直到用户批准。每次回答中只要展示了提交命令，就必须包含此费用警告，即使你只是在说明步骤，或用户会自行运行命令。

4. 提交。 选择提交类型：

   • 原生可执行文件或 shell 脚本：参阅 android_executable.md。
   • Instrumentation 测试 APK：参阅 instrumentation.md。
   • 每台设备使用同一二进制文件运行多种配置（不同标志、输入或环境变量）：参阅 multi_config_runs.md。

5. 等待。 对于运行时间超过几分钟的作业，使用 --async 提交，并遵循 session_lifecycle.md 中的说明。

6. 收集结果。 下载产物，并将其映射到对应设备，参阅 results.md。

7. 报告。 每台设备列出一行：设备 ID、作业文件夹（job-NNN）、结果、关键输出，以及会话文件夹的 gs:// 路径。明确指出失败、超时或已取消的作业，不要遗漏。

规则

• 始终设置超时时间。 --executable-timeout（或 --instrumentation-timeout）默认为 5m；有效范围为 1m 至 3h。估算运行时间并明确设置。
• 参数以逗号分隔。 --executable-args 中的每个元素都会成为一个参数。改写以空格分隔的命令行。如果某个值包含逗号，请使用 ^SEP^ 前缀（参见 android_executable.md）。
• 直接调用时不使用 shell。 将二进制文件作为 --executable 时不会调用 shell：请使用 --executable-env-vars 设置环境变量，而不是 export。
• 不要覆盖共享输入。 DDP 会在作业开始时获取输入。待处理会话正在使用某个 gs:// 脚本或二进制文件时，切勿覆盖它；请使用本地路径（会自动上传），或为每次运行使用唯一的 gs:// 路径。
• 为会话添加标签，使用 --labels（例如 purpose=smoke,build=1234），以便之后轻松查找。
• 礼貌轮询。 切勿密集轮询；每隔 30 到 60 秒轮询一次，并报告进度（参见 session_lifecycle.md）。
• 按要求取消。 如果用户想要停止，请取消会话（参见 session_lifecycle.md），并告知用户会话已取消。
• 不要使用 Device Streaming API（devicestreaming.googleapis.com、 deviceSessions）运行批处理作业；该 API 用于交互式租用。

参考索引

• device_selection.md：将“Pixel 10”等设备名称映射到目录 ID、OS 版本，以及实体设备或虚拟设备。
• android_executable.md：标志、直接调用、共享库、作为可执行文件的脚本。
• instrumentation.md：APK 测试、分片、测试目标。
• session_lifecycle.md：同步与异步、等待、描述、取消、状态和结果类型。
• results.md：存储桶布局、作业到设备的映射、日志。
• multi_config_runs.md：在每台设备上使用多种配置运行同一个二进制文件。
• troubleshooting.md：常见故障。