mcpField
O
operate-vmos-edge-cli

operate-vmos-edge-cli

github.com/vmos-dev云与 DevOps344 次安装11 周前更新
代码仓库

关于 operate-vmos-edge-cli

operate-vmos-edge-cli 是用于通过命令行操作 VMOS Edge Desktop Electron 应用的技能，涵盖边缘主机上的 Android 虚拟设备管理、基于 CDP 的界面自动化和设备工作流编排。

主要功能

  1. 01管理边缘主机上的 Android 虚拟设备
  2. 02通过 CDP 自动化桌面界面
  3. 03运行 YAML 剧本和 JSON 批处理
  4. 04安装并验证 CLI
  5. 05排查 CLI 错误码

适用场景

  1. 01创建、启动、停止或删除虚拟设备
  2. 02自动操作 VMOS Edge Desktop
  3. 03构建可复用的设备工作流
  4. 04诊断 CLI 命令故障

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/vmos-dev/vmos-edge-skills --skill operate-vmos-edge-cli

安装后在 Claude Code 中输入/operate-vmos-edge-cli确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

agents/
openai.yaml
references/
command-patterns.md
error-recovery.md
invocation-preflight.md
page-map.md
ui-automation.md
scripts/
ensure-installed.mjs

详细介绍

操作 VMOS Edge CLI

概述

用于控制 VMOS Edge Desktop Electron 应用的 CLI 工具——管理边缘主机上的 Android 虚拟设备，通过 CDP 自动化桌面 UI，并编排设备工作流。

适用场景

  • 在边缘主机上创建、启动、停止或删除 Android 虚拟设备
  • 通过 CDP 自动化 VMOS Edge Desktop Electron UI
  • 为设备工作流编写 YAML playbook 或批量 JSON
  • 从 vmos-edge-cli 错误代码中恢复
  • 安装或验证 vmos-edge-cli 工具

不适用于： 原始 ADB 命令、Appium、Android Studio 模拟器或任何非 VMOS Android 工具。

预检

关卡——必须在执行任何其他命令前完成。请勿跳过。

# 1. Node.js 18+ required
node --version

# 2. Check CLI
vmos-edge-cli --version

# 3. If CLI missing → install
npm i -g @vmosedge/cli

# 4. Verify
vmos-edge-cli schema
检查失败操作
找不到 node停止。 告知用户安装 Node.js 18+。
找不到 npm停止。 告知用户安装 npm（随 Node.js 一同提供）。
找不到 vmos-edge-cli运行 npm i -g @vmosedge/cli，然后通过 schema 验证。
安装后 schema 失败报告错误并停止。请勿自行尝试其他方案。

请勿替换为 node dist/main.js、pnpm build 或 pnpm link。唯一受支持的安装方式是 npm i -g @vmosedge/cli。

上面的手动步骤与自动化脚本（scripts/ensure-installed.mjs）执行相同的流程——任选其一。平台路径和特殊情况请参阅 invocation-preflight.md。

关键规则

  1. 始终使用 ui state 检查，绝不使用 screenshot——state 免费且结构化。screenshot 会消耗视觉令牌。仅在用户要求保存图像时截图。
  2. 始终使用 ui click/type 交互，绝不通过 eval 点击或输入——eval 会绕过滚动和 CDP 回退机制，并且对屏幕外元素无效。
  3. 页面发生变化后始终运行 ui state——包括 click、goto、back 之后。切勿重复使用过期索引。
  4. 始终批量执行连续且安全的操作——如果每个步骤无论其他步骤的结果如何都是安全的，就应批量执行。切勿将它们拆成单独调用。
  5. 绝不在同一批次中混合会修改状态的命令——create、delete、start、stop、reset 均应作为单独的直接调用执行。检查结果后再发出下一条命令。单条命令可以针对多个项目（device start id1 id2、--count 5）——边界在命令之间，而不在目标之间。
  6. 编写批量操作/YAML 前始终运行 schema——切勿猜测参数名称。CLI 位置参数在批量操作/YAML 中的名称不同，无法靠猜测得出。运行 schema <domain> 以查明准确的名称和类型。
  7. 每条 device/image 命令都需要 --host <ip>——host 命令将 <ip> 作为位置参数。

核心工作流

应用会在命令之间持续运行——无需每次都运行 app start。

  1. 预检 → 请参阅上方的预检部分。必须通过后才能继续。
  2. 检查 → ui state、device list、host info 等。
  3. 执行 → 单条或会修改状态的操作使用直接调用；连续且安全的操作使用批量调用；可复用流程使用 run
  4. 解析 → 成功：读取 data。失败：根据 code 分支处理（参见 error-recovery.md）
  5. 验证 → 页面变化后运行 ui state，输入后运行 ui form-state，修改后运行 device info

快速参考

上下文格式示例
终端vmos-edge-cli <domain> <method>vmos-edge-cli ui eval "1+1"
YAML action:domain.methodaction: ui.eval
batch JSONdomain.method{"action":"ui.eval"}
YAML 变量${{ expr }}${{ devices[0].id }}
batch 变量$expr$devices[0].id

终端中使用空格。YAML 和 batch 中使用点号。变量语法不可互换。

参考索引

符合条件时，请使用 Read 工具读取这些文件——不要凭记忆操作。

常见陷阱

错误修正方法
使用 ui screenshot 检查页面使用 ui state——免费、结构化，且包含 [N] 索引
使用 ui eval "el.click()"使用 ui click <N>——可处理滚动并回退到 CDP
页面导航后复用索引再次运行 ui state 以获取新索引
分两次调用 host check 10.0.0.5，然后调用 host info 10.0.0.5将它们批量处理：一次调用即可，两项操作都可无条件安全运行
根据 CLI 语法猜测批量／YAML 参数名称位置参数的名称不同。先运行 schema <domain>
在一次批量调用中先运行 device create，再运行 device start绝不要这样做——不同的变更命令必须分开调用
未确认便向字段输入内容输入后运行 ui form-state 确认值
每条命令都运行 app start应用会持续运行——先检查 app status
复杂页面上的 ui state 输出过长使用 ui state --interactive-only，或在批量调用中设置 interactiveOnly: true
跳过预检，直接运行 CLI 命令CLI 可能尚未安装。务必先运行 Preflight gate

评论

支持 Markdown