genymotion

Genymotion 统一技能

此技能是所有 Genymotion 虚拟设备管理任务的主要入口。 它同时支持 Genymotion SaaS（通过 gmsaas）和 Genymotion Desktop（通过 gmtool）。

---

步骤 1 — 确定目标平台

如果用户的请求未明确指定 Cloud 或 Local，请先询问：

AskUserQuestion:
  "Which platform do you want to use?"
  Options:
    - "Genymotion SaaS / Cloud (gmsaas) — remote device in the cloud"
    - "Genymotion Desktop / Local (gmtool) — local device on this machine"

表示 Cloud 的关键词：“cloud”、“SaaS”、“remote”、“gmsaas”、“Genymotion Cloud” 表示 Local 的关键词：“local”、“desktop”、“gmtool”、“on my machine”

---

步骤 2 — 检查先决条件

对于 Genymotion SaaS（gmsaas）

步骤 2a — 定位 gmsaas

先检测操作系统，然后检查 gmsaas 是否在 PATH 中：

• Linux / macOS：which gmsaas

• Windows（PowerShell）：where.exe gmsaas

• 如果在 PATH 中找到：后续命令均直接使用 gmsaas。

• 如果未在 PATH 中找到：不要自行搜索目录。请询问用户：

“未在 PATH 中找到 gmsaas。你是否有安装了 gmsaas 的 Python 虚拟环境？”

• 有 — 我会提供虚拟环境路径
• 没有 — 我需要安装 gmsaas

• 如果用户提供了虚拟环境路径，请使用相应的可执行文件：
  • Linux / macOS：<venv_path>/bin/gmsaas
  • Windows：<venv_path>\Scripts\gmsaas
• 如果未安装 gmsaas，请按照 references/setup-gmsaas.md 中的说明操作。

步骤 2b — 检查身份验证

定位到 gmsaas 后，运行 gmsaas doctor 以验证设置。

如果找到了 gmsaas，但尚未完成身份验证，请通过 gmsaas doctor 找出问题，并指导用户完成设置。

安全 — 切勿通过 Bash 工具运行 gmsaas auth token <token>。 令牌会暴露在 shell 历史记录中。请改为显示以下命令，让用户在自己的终端中运行：

# Linux / macOS:
export GENYMOTION_API_TOKEN="your_token"

# Windows (PowerShell):
$env:GENYMOTION_API_TOKEN = "your_token"

---

对于 Genymotion Desktop（gmtool）

运行：gmtool version

如果未找到 gmtool，请按照 references/setup-gmtool.md 中的说明操作。

如果找到了 gmtool，但许可证未激活（退出代码 9）：

gmtool license info                  # Check licence status
gmtool license register <key>        # Register a licence key

---

步骤 3 — 执行请求的操作

确认平台并满足先决条件后，请阅读相应的参考文件并遵循其中的说明：

• 对于 Genymotion SaaS（gmsaas） → 阅读 references/gmsaas-reference.md
• 对于 Genymotion Desktop（gmtool） → 阅读 references/gmtool-reference.md

参考文件位于 references/ 目录中：

• references/gmsaas-reference.md
• references/gmtool-reference.md

---

验证启动 / 停止操作

执行启动或停止命令后，务必验证实际状态。 不要仅凭命令的退出代码或未输出错误就假定操作成功。

Genymotion SaaS（gmsaas）

执行 gmsaas instances start 后：

使用以下策略轮询，直到状态为 ONLINE：

Repeat up to 10 times (max ~5 minutes):
  Run: gmsaas instances get <instance_uuid>
  If status = "ONLINE"  → proceed, inform the user the instance is ready
  If status = "BOOTING" → wait 30 seconds, then retry
  If status is anything else (ERROR, DELETING, unknown) → stop polling, inform the user and suggest checking https://cloud.geny.io/instances

If still not ONLINE after 10 attempts (~5 minutes):
  → Inform the user: "The instance is taking longer than expected to start.
     You can check its status at https://cloud.geny.io/instances or run:
     gmsaas instances get <instance_uuid>"
  → Do not proceed with ADB connect or further steps

每次轮询之间，都要告知用户你正在做什么：“实例正在 BOOTING — 30 秒后再次检查（第 N/10 次尝试）……”

执行 gmsaas instances adbconnect 后：

adb devices
# Expected: instance appears in the list (e.g. "localhost:5555  device")
# If list is empty despite successful adbconnect:
#   → The local ADB daemon may not be running. Start it:
gmsaas adb start
#   → Then retry: adb devices
# If still empty: run gmsaas doctor to check the Android SDK path configuration

执行 gmsaas instances stop 后：

gmsaas instances list
# Expected: instance no longer appears in the list
# Or: gmsaas instances get <instance_uuid> → status = "STOPPED" / "OFFLINE"
# If instance still appears as running: retry the stop command or ask the user to check the cloud dashboard

Genymotion Desktop（gmtool）

执行 gmtool admin start <device> 后：

gmtool admin list --running
# Expected: device appears in the list with State = On
# If not listed: check exit code, try gmtool admin details <device> for more info

执行 gmtool admin stop <device> 后：

gmtool admin list --off
# Expected: device appears with State = Off
# If still listed as running: retry stop or ask the user to close Genymotion Desktop

向用户报告已验证的状态。 不要说“设备已启动”，而要说“我已确认设备正在运行：gmtool admin list --running 显示其状态为 On。”

---

停止 SaaS 实例

触发此流程的关键词：“stop”、“arrêter”、“delete”、“supprimer”、“shut down”、“kill”，并同时包含“instance”、“cloud”或“gmsaas”。

SaaS 实例只要处于运行状态，就会持续产生费用。用户完成任务后，或询问如何避免费用时，务必主动提出停止实例。

停止单个实例

# List running instances to get the UUID
gmsaas instances list

# Stop the instance
gmsaas instances stop <instance_uuid>

停止所有正在运行的实例

如果用户想一次性停止所有实例：

# List all running instances and stop each one
gmsaas instances list
# Then for each instance UUID:
gmsaas instances stop <instance_uuid>

主动提示：在启动 SaaS 实例的任何工作流（安装 APK、测试、显示等）之后，提醒用户： "完成后别忘了停止实例，以免产生费用：gmsaas instances stop <instance_uuid>"

---

显示 SaaS 实例

触发此流程的关键词：与“云实例”“SaaS 实例”或“gmsaas 实例”搭配使用的“显示”“打开”“展示”“查看”

当用户想显示正在运行的 SaaS 实例时，提供以下选项：

AskUserQuestion:
  "How would you like to display your Genymotion SaaS instance?"
  Options:
    - "Open in the Genymotion Cloud web interface"
    - "Open via gmsaas instances display (opens and copies the link to clipboard)"
    - "Embed it in a custom web page (device-web-player SDK)"

前提条件

• 一个正在运行的 SaaS 实例（如果尚未启动，请先启动——参见步骤 2）
• 如果尚不清楚实例 UUID，请获取：gmsaas instances list

配方定义了虚拟设备配置（Android 版本 + 硬件配置）。 可以将其视为设备模板。启动实例之前，需要选择一个配方 UUID。 使用以下命令列出可用配方：gmsaas recipes list

选项 1 — 在 Genymotion Cloud 网页界面中打开

向用户提供可直接在浏览器中打开的 URL：

https://cloud.geny.io/instance/<instance_uuid>

用户必须事先登录 https://cloud.geny.io。如果这是用户首次访问，或者会话可能已过期，请提醒他们登录。

选项 2 — 通过 gmsaas instances display 打开

gmsaas instances display <instance_uuid>

注意：此命令会将实例显示链接复制到剪贴板，并可能在默认浏览器中自动打开。请告知用户链接已复制到剪贴板。

选项 3 — 嵌入自定义网页

→ 按照下文 在网页中显示 SaaS 实例（device-web-player） 部分操作。

---

在网页中显示 SaaS 实例（device-web-player）

触发此流程的关键词：与“云实例”或“SaaS”搭配使用的“网页”“嵌入”“浏览器”“device-web-player”“HTML 页面”“集成”“网页播放器”

阅读 references/device-web-player-reference.md，并按照 分步工作流 部分操作。

始终遵循以下关键要求：

• 绝不要通过 Bash 工具执行 curl 命令——这些命令会返回机密信息
• 绝不要要求用户将令牌粘贴到聊天中——应显示命令，让用户在自己的终端中运行
• 始终提供两个选项：默认模板（templates/device-web-player.html）或自定义设计
• 提醒用户通过 HTTP 提供页面（而不是 file://），以确保 WebRTC 正常工作

---

CI/CD 集成

触发此流程的关键词：与“Genymotion”或“SaaS”搭配使用的“CI/CD”“流水线”“GitHub Actions”“Jenkins”“Bitrise”“CircleCI”“持续集成”“自动化测试”“Detox”“Appium”

CI/CD 集成仅支持 Genymotion SaaS（gmsaas），不支持 Genymotion Desktop（gmtool）。 如果用户询问 Genymotion Desktop 的 CI/CD，请说明这一限制，并引导他们改用 SaaS。

阅读 references/cicd-reference.md，了解特定平台教程和通用集成模式。

---

通用工作流摘要

1. Identify the target platform (Cloud or Local) → ask if ambiguous
2. Check prerequisites (gmsaas or gmtool installed + authenticated/licensed)
   → If missing: guide the user through installation step by step
3. Read the corresponding reference file
4. Identify the requested action
5. Collect missing parameters (name, UUID, profile…) via list + AskUserQuestion
6. Execute the command via Bash
7. Verify the result with the appropriate check command (see "Verify Start / Stop Operations")
8. Report the verified state to the user — never assume success without checking
9. Handle errors (show the message + suggest a solution)
10. [SaaS only] Remind the user to stop the instance when done to avoid charges

---

示例

示例 1 — 启动云实例并安装 APK

用户说："在 Genymotion Cloud 上启动一台 Pixel 8 并安装我的 app.apk"

操作：

1. 检测平台 = Cloud → 检查 gmsaas
2. gmsaas recipes list → 请用户选择一个 Pixel 8 配方
3. gmsaas instances start <recipe_uuid> "pixel-8" --max-run-duration 3600
4. gmsaas instances get <instance_uuid> → 在继续操作前确认状态为 ONLINE
5. gmsaas instances adbconnect <instance_uuid>
6. adb install app.apk
7. 提醒用户完成后运行：gmsaas instances stop <instance_uuid>

结果：APK 已安装并在运行中的云实例上运行。ADB 连接前已确认实例状态。已提醒用户停止实例，以免产生费用。

---

示例 2 — 启动本地桌面设备并调试

用户说：“在本地启动一台 Android 13 设备，并向我展示日志”

操作：

1. 检测平台 = Local → 检查 gmtool
2. gmtool admin list → 找出一台 Android 13 设备
3. gmtool admin start "Pixel 7 API 33"
4. gmtool admin list --running → 验证设备显示为 State = On
5. gmtool device logcatdump -n "Pixel 7 API 33" ~/debug.log

结果：设备已启动，并在捕获日志前验证其正在运行。

---

示例 3 — 在网页中嵌入云实例

用户说：“我想在 HTML 页面中显示我的 Genymotion 实例”

操作：

1. 检测流程 = device-web-player
2. 检查实例是否正在运行 → gmsaas instances list
3. 询问用户：使用默认模板还是自定义设计？
4. 复制 templates/device-web-player.html（或生成自定义版本）
5. 显示 curl 命令，让用户在终端中运行（webrtc_url + access token）
6. 指示用户替换 REPLACE_WITH_WSS_ADDRESS 和 REPLACE_WITH_ACCESS_TOKEN
7. 提醒用户通过 HTTP 提供服务：python3 -m http.server 8080

结果：可直接使用的 HTML 页面，可通过 WebRTC 流式传输设备画面。

---

示例 4 — 在 GitHub Actions 流水线中设置 Genymotion

用户说：“如何在 GitHub Actions CI 中使用 Genymotion？”

操作：

1. 检测流程 = CI/CD → 阅读 references/cicd-reference.md
2. 说明：CI/CD 仅支持 Genymotion SaaS，不支持 Desktop
3. 提供 GitHub Actions 资源链接：https://github.com/marketplace/actions/genymotion-saas-action
4. 展示通用流程：身份验证 → 启动实例 → adbconnect → 运行测试 → 停止实例
5. 提醒用户将 GENYMOTION_API_TOKEN 保存为 CI 密钥

结果：用户获得了可用于 CI 流水线的有效起点。

---

故障排除

PATH 中找不到 gmsaas

原因：未安装 gmsaas，或 gmsaas 不在 PATH 中。 解决方案：运行 which gmsaas（Linux/macOS）或 where.exe gmsaas（Windows）。如果找不到，请参阅 references/setup-gmsaas.md。如果安装在虚拟环境中，请提供完整路径：<venv>/bin/gmsaas 或 <venv>\Scripts\gmsaas。

身份验证错误 — 401 / Unauthorized

原因：未设置 API 令牌、令牌已过期或已撤销。 解决方案：运行 gmsaas doctor 以确定问题。通过环境变量设置令牌（不要通过 Bash 工具运行）：

• Linux/macOS：export GENYMOTION_API_TOKEN="your_token"
• Windows：$env:GENYMOTION_API_TOKEN = "your_token"

实例卡在 BOOTING 状态

原因：云实例启动可能需要 1–3 分钟。极少数情况下，实例可能无法启动。 解决方案：每 30 秒轮询一次 gmsaas instances get <uuid>，最多尝试 10 次。如果 5 分钟后状态仍不是 ONLINE，请告知用户并提供链接：https://cloud.geny.io/instances。

adbconnect 后 adb devices 输出为空

原因：本地 ADB 守护进程未运行。 解决方案：运行 gmsaas adb start，然后重试 adb devices。如果仍为空，运行 gmsaas doctor 以验证 Android SDK 路径。

gmtool 许可证未激活（退出代码 9）

原因：尚未注册 Genymotion Desktop 许可证。 解决方案：运行 gmtool license info 检查状态，然后运行 gmtool license register <key> 激活许可证。

gmtool 找不到设备（退出代码 5）

原因：设备名称不正确，或尚未创建设备。 解决方案：运行 gmtool admin list 获取准确的设备名称。如果设备不存在，请先创建设备。

gmtool 虚拟化引擎无响应（退出代码 4）

原因：Genymotion Desktop 未运行，或虚拟机监控程序崩溃。 解决方案：打开 Genymotion Desktop 并等待其就绪，然后重试。

---

使用的工具

• Bash — 用于运行 gmsaas 和 gmtool
• AskUserQuestion — 用于确认平台并收集缺失参数
• Read — 用于读取参考文件 references/gmsaas-reference.md、references/gmtool-reference.md、references/device-web-player-reference.md
• Glob / Read — 用于查找本地 APK 文件或归档文件