developer-device-platform-basics

开发者设备平台

开发者设备平台（DDP）是 Google 完全托管的全球基础设施，提供对各种实体和虚拟设备的访问。

警告

开发者设备平台（DDP）目前处于预览阶段。

重要

对于所有 devicerun 和 devicestreaming API 操作（预留、 状态检查、停止／取消、更新或列出会话），始终核对并使用链接的 .md 参考文件中提供的确切说明和 curl 命令。

归属信息

必须阅读：在执行任何 gcloud、REST API 或 MCP 命令之前，你 必须阅读使用归属信息。对于直接在终端中执行的命令（绝不在生成的脚本、Terraform 或用户代码中）， 请在 gcloud 前添加 CLOUDSDK_METRICS_REQUEST_ATTRIBUTION="agent-skills/1.0 (skill:developer-device-platform-basics)" ，并在 User-Agent 标头中追加 agent-skills/1.0 (skill:developer-device-platform-basics)。

身份验证与设置

重要：在运行任何请求之前，必须按照以下步骤确保环境已正确初始化：

运行任何请求之前，请确认是否存在 gcloud 可执行文件。如果不存在，请参阅官方 Google Cloud CLI 安装指南， 在当前平台（Linux、macOS、Windows 等）上安装。

1. Google Cloud 身份验证：使用你的 Google Cloud 凭据进行身份验证，并为开发者设备平台配置有效的应用默认凭据（ADC）：

   gcloud auth login --no-browser
   gcloud auth application-default login --no-browser
   

2. 启用 API（如果尚未启用）：

   gcloud services enable devicerun.googleapis.com devicestreaming.googleapis.com testing.googleapis.com --quiet
   

说明

预览阶段的设备流式传输 API 需要 Cloud Testing API。

3. 启用 gcloud beta 组件：

   gcloud components install beta
   

4. 设置环境变量：设置所需的项目变量和 访问令牌：

   export PROJECT_ID=$(gcloud config get project)
   export ACCESS_TOKEN=$(gcloud auth application-default print-access-token 2>/dev/null)
   

5. Python 环境：有关设置 Python 虚拟 环境的说明，请参阅 start_adb_forwarder.md。

列出可用设备

要查找启动会话时要使用的正确 modelCode 和 osVersion， 可以列出可用设备：

1. 列出型号：运行以下命令，列出可用的 Android 设备 型号：

   gcloud beta device-run devices list
   

   使用 ID 列查找用于 CATALOG_ID 参数的值，以 描述特定设备（例如，shiba-36）。

2. 描述型号：运行 API 请求，获取特定型号的更多详细信息（例如，supportedProducts、分辨率）。始终以 describe_device.md 中提供的确切 curl 命令和说明为准。

启动设备会话

当用户要求预留或连接设备时：

1. 检查设备可用性：

   根据 Listing Available Devices 说明查找设备的 CATALOG_ID。按照 describe_device.md 中提供的确切 curl 命令和说明，检查 CATALOG_ID 的设备 可用性。设备的 supportedProducts 中必须包含 "deviceStreaming"，才能预留。

   如果未指定特定设备，则使用 CATALOG_ID=shiba-34（SDK 34 上的 Pixel 8）。

   如果用户未指定 OS_VERSION，请让用户从设备列表中选择一个版本（优先选择可用性最高的版本 {"available": "AVAILABILITY_HIGH" }）。

   如果 OS_VERSION 不支持 deviceStreaming，则不要预留设备。请提示用户选择其他 OS_VERSION。

2. 提取参数：

   • model_id：设备详情中的 modelCode。必填。
   • version_id：设备详情中的 osVersion。必填。

3. 预留设备：

   规则：必须获得用户明确确认。预留设备会产生费用并创建云资源。Agent 必须始终明确告知用户，费用将计入当前活跃的 Google Cloud 项目（例如 ${PROJECT_ID}）。在执行任何会话创建命令之前，必须停止并征求用户的明确批准。

   然后，使用 model_id 和 version_id 发起 API 请求以预留设备。始终遵循 reserve_device.md 中提供的确切 curl 命令和说明。

   解析响应以获取 session_name（会话名称，例如 projects/${PROJECT_ID}/deviceSessions/session-xxxxxx）。如果预留失败，请报告错误。

4. 等待会话变为活跃状态：

   等待设备会话完成配置期间，轮询会话状态，直到 "state" 为 "ACTIVE"。确切的 curl 命令请参阅 session_status.md。

   每隔 5 秒重复检查，以避免触发 API 速率限制。如果 2 分钟内（通常不到 1 分钟） 仍未变为活跃状态，请报告失败并取消会话。会话变为活跃状态后，从会话 JSON 响应中 提取 expireTime，并转换为用户当地时间，以便于阅读的格式显示（例如“2026 年 6 月 9 日下午 2:44 PDT”）。

5. 启动连接转发器：启动 ADB 转发器脚本，将连接转发到远程设备。始终遵循 start_adb_forwarder.md 中提供的确切命令和说明。确保记录 Command ID。

6. 等待上线并解析端口：等待转发器上线并提取监听端口。始终遵循 start_adb_forwarder.md 中提供的确切逻辑和说明。

7. 向用户提供说明：

   上线后，运行 adb -s localhost:{port} shell getprop ro.product.model 获取设备 型号名称。然后直接在聊天中向用户打印以下消息（不要创建任何制品文件），并附上 以下说明：

   设备已就绪！

   Device Model: {device_model}
   OS Version: {version_id}
   ADB Address: localhost:{port}
   Session Expiration: {expire_time_human_readable_local}
   

8. 保存会话状态：将 {session_name} 和 {command_id} 保存到对话记忆/上下文中， 以便之后进行清理。

查看已预留设备的屏幕

编码 Agent 可以直接使用 adb 与远程设备交互。用户可以使用实用工具显示屏幕，并在 DDP 中手动控制已预留的设备。实用工具示例请参阅 view_device.md。

停止设备会话

当用户要求停止、清理或释放设备时：

1. 识别会话：从上下文中获取活动的 {session_name} 和 {command_id}。如果没有这些信息，请先列出活动会话（参见下方的辅助命令）， 以查找会话名称。

2. 通过 API 取消会话：通过 API 取消会话。务必严格遵循 cancel_session.md 中提供的 curl 命令和说明。

3. 终止连接转发器：使用环境的进程管理功能，终止与 {command_id} 匹配的后台进程。

4. 确认：向用户确认会话已取消，资源已释放。

更改设备会话过期时间

当用户要求更改活动设备会话的过期时间时：

规则：必须获得用户明确确认。延长设备会话会产生额外的计费费用并创建云资源。Agent 必须始终明确告知用户，活动 Google Cloud 项目（例如 ${PROJECT_ID}）将产生额外费用。继续执行任何会话延长命令前，必须停止并征求用户的明确批准。

1. 提取参数：

   • session_name：活动会话名称。
   • ttl：新的剩余时长（例如 3600s）。如果以其他格式提供，请转换得出 ttl。

2. 通过 API 更改会话：使用 updateMask=ttl 通过 API 更改会话。务必严格遵循 update_session_expiration.md 中提供的 curl 命令和说明。

3. 重启连接转发器：

   • 运行 adb disconnect localhost:{port}，确保旧的转发器连接已关闭。
   • 停止与 {command_id} 对应的旧连接转发器。
   • 按照“启动设备会话”中的第 5 步启动新的连接转发器（计算新的 --ttl 时长，单位为秒，并保存新返回的 Command ID）。

4. 确认：向用户确认会话时长已更新，并且连接转发器已使用新的 TTL 重启。

辅助操作：列出活动会话

如果丢失上下文而需要查找活动会话，请始终严格遵循 list_sessions.md 中提供的 curl 命令和说明。

参考资料

• gcloud device-run CLI
• Device Streaming API
• describe_device.md
• reserve_device.md
• session_status.md
• start_adb_forwarder.md
• view_device.md
• cancel_session.md
• update_session_expiration.md
• list_sessions.md