跳到正文

文档 Hub

脚本

脚本是 VMPal 保存在 Hub 中的 shell 或 PowerShell 脚本。它可以在你的 Mac 上、虚拟机中或虚拟机的全新克隆中运行,就像干净的 CI 运行器,但用的是你自己的环境和数据。你可以在 Hub 中运行它,也可以让 AI 智能体或 vmpal 运行它。

交给 AI 智能体

编写和运行脚本最简单的方式,是交给你的编程智能体。它会编写脚本并保存到 VMPal 的 Hub 中,在你指定的位置运行它,并在运行失败时读取日志。为此,它会使用 VMPal 的 MCP 工具,或在它的终端中使用 vmpal script。

  1. 在 VMPal 中打开 设置 › AI智能体,然后打开 允许这台Mac上的编程智能体管理所有虚拟机。
  2. 点按 添加到Claude Code 或其他智能体的按钮(支持哪些智能体),然后重启智能体。
  3. 向它提出请求,例如:
    • “写一个 VMPal 脚本,在我的 Windows 虚拟机中构建这个应用,然后立即运行它。”
    • “运行我的测试脚本,告诉我它为什么失败。”
    • “让我的构建脚本在我的 Ubuntu 虚拟机的全新克隆中运行,30 分钟后停止。”

本页其余部分介绍脚本的工作原理,供你想深入了解时参考。

创建脚本

VMPal 把你的脚本保存在它的 Hub 中。

  1. 打开 Hub:点按 VMPal 窗口工具栏中的 Hub,或者选取 显示 › Hub(⌘2)。
  2. 点按 新建脚本。为它命名、选择语言、编写内容,然后点按 创建。新脚本的开头有一段注释,列出了它可以使用的变量。
  3. 选择它的运行位置:点按边栏中 运行位置 旁边的 选取…。也可以打开脚本的菜单(右键点按脚本,或点按 ⋯),然后选取 更改运行位置…。

在 Hub 的列表中,连按两下脚本或按下 Return 键可以编辑它,按下 Delete 键可以删除它,上下拖移可以调整列表顺序。在 VMPal 的虚拟机列表中,有脚本在其中运行的虚拟机会显示脚本标记。点按这个标记,即可在 Hub 中查看这些脚本。

运行位置

脚本可以在虚拟机的全新克隆中、虚拟机本身中或你的 Mac 上运行。如果选择了多个位置,它会在每个位置都运行。

在虚拟机中运行需要智能体控制,因此 VMPal 会在脚本运行的每台虚拟机中打开它。

虚拟机的全新克隆

这是在虚拟机中运行时的默认方式。克隆是虚拟机的一次性副本,就像全新的 CI 运行器。每次运行都会得到自己的克隆,运行结束后 VMPal 会删除它。

  • 很轻量。 VMPal 会立即创建克隆。轻量克隆需要 APFS。对于位于非 APFS 磁盘上的虚拟机,运行会改为使用虚拟机本身。
  • 虚拟机必须已关机。 请使用虚拟机的 关机。关闭它的窗口只会保存虚拟机,而不会将其关机。
  • 一次运行最多等待 30 分钟,等待虚拟机关机。超过这个时间,VMPal 会跳过这次运行。
  • 克隆得不到 Mac 上的任何东西。 它没有共享文件夹、转发端口或剪贴板。

虚拟机本身

要在虚拟机本身中运行,请在选择脚本运行位置时,取消勾选该虚拟机下方的 每次运行都克隆新的虚拟机。之后,边栏会在该虚拟机下方显示 在虚拟机本身中运行。

  • VMPal 会在后台启动虚拟机或让它继续运行,用 VMPal 保存的密码在登录界面登录,并在运行结束后让虚拟机继续开着。
  • 如果虚拟机已暂停,运行会一直等到它继续运行。
  • 运行会使用虚拟机自己的共享文件夹、剪贴板和网络,也就是你为它设置的那些。

这台 Mac

脚本会以你的身份在你的 Mac 上运行。这台 Mac 上的脚本决定 vmpal 和 AI 智能体能否让脚本在这里运行。

运行方式

每个脚本都由其运行位置的 shell 运行:

位置 语言 运行程序
Linux 虚拟机 Shell bash
macOS 虚拟机 Shell zsh
你的 Mac Shell zsh,或其 #! 行中指定的解释器
Windows 虚拟机 PowerShell Windows PowerShell
  • shell 脚本以登录 shell 的方式运行,从个人文件夹开始。
  • 运行使用用户的账户,而不是 root。 它们会读取登录 shell 的配置文件:Linux 中为 ~/.profile(不是 ~/.bashrc),macOS 中和你的 Mac 上为 ~/.zprofile(不是 ~/.zshrc)。因此,请为所有用户安装你的工具,或在这些文件中设置 PATH。
  • 由退出码决定运行是否成功。 退出状态为 0 表示成功,其他任何状态都表示失败。
  • PowerShell 在程序失败后会继续执行。 因此,请在每个程序之后检查 $LASTEXITCODE。
  • 除了脚本本身,VMPal 不会从你的 Mac 拷贝任何东西。 你的脚本需要自己获取代码,例如使用 git clone。

运行脚本

点按边栏或脚本菜单中的 立即运行。脚本会在你选择的每个位置运行。如果你还没有选择任何位置,VMPal 会询问你要在哪里运行。

要在其他位置运行,请在脚本菜单中按住 Option 键并选取 运行于…。VMPal 会先询问运行位置,然后在那里运行脚本,并且以后都在那里运行。

历史记录

边栏中的 历史记录 列出了每一次运行,显示运行的状态、耗时,以及失败或等待的原因。

  • 显示日志 会打开某次运行的输出。
  • 停止 会停止一次运行。脚本菜单中的 停止运行 会停止所有运行。
  • 连按两下某一项,即可查看它的全部内容,以及实时更新的各次运行日志。

日志

日志保存在你的 Mac 上的 ~/Library/Logs/VMPal/Hub 中。在 Hub 中,帮助 › 在访达中显示日志 会打开脚本的日志。

  • VMPal 会把每份日志控制在 16 MiB 以内。更长的日志会保留开头和结尾。
  • VMPal 会保留每个脚本最近 50 次已结束的运行及其日志。

退出 VMPal

如果你退出 VMPal 时有运行正在进行,它会先询问你,并提供 停止运行并退出。之后,它会停止这些运行并删除它们的克隆。VMPal 退出时仍在等待的运行永远不会开始。在有更新等待安装期间,也不会开始任何运行。

脚本的设置

要更改脚本的设置,请在它的菜单中选取 编辑脚本…,或点按边栏中脚本名称旁边的 编辑…。

设置 作用
语言 Shell,或用于 Windows 虚拟机的 PowerShell
超时 VMPal 会停止超过此时长的运行。可选择 5 分钟到 6 小时,默认为 1 小时。使用 vmpal 时,最长可设为 24 小时
颜色 为脚本在 Hub 中的行着色,并为它所运行的虚拟机的脚本标记着色。可以选择 Mac 的一种颜色,或者不选。脚本菜单中的 颜色,以及边栏中脚本名称旁边的颜色按钮,也可以更改颜色

在脚本的菜单中,复制 会在原脚本之后放一份它的副本。删除脚本… 会删除脚本及其运行记录和日志。

变量

每次运行都会得到以下环境变量:

变量 值
VMPAL_SCRIPT_NAME 脚本的名称
VMPAL_RUN_ID 本次运行的 ID
VMPAL_TARGET 运行位置:mac,或虚拟机的名称

在 PowerShell 中,它们分别是 $env:VMPAL_SCRIPT_NAME 等。

限制

  • 每个位置一次只运行一次。 脚本在它运行的每个位置一次只运行一次,另外最多有一次运行在等待。较新的运行会取代正在等待的运行。
  • 最多同时两个克隆。 最多同时进行两次在克隆中的运行。脚本对某台虚拟机的下一个克隆,要等 VMPal 删除上一个克隆后才会创建。
  • 最多同时两台 macOS 虚拟机。 macOS 最多允许同时运行两台 macOS 虚拟机,包括你自己运行的。已有两台在运行时,在 macOS 虚拟机中的运行会等待其中一台停止。
  • 虚拟机本身一次只接受一次运行,无论是哪个脚本。在虚拟机本身中运行的脚本最大为 32,000 字节(按 UTF-8 计算)。VMPal 会跳过更长的脚本的运行,因此请在克隆中运行这类脚本。
  • 30 分钟内必须开始。 如果一次运行等待了 30 分钟仍未开始(例如在等待虚拟机关机),VMPal 会跳过它。

这台 Mac 上的脚本

在你的 Mac 上运行的脚本会以你的身份执行代码。因此,当 vmpal 或 AI 智能体要让脚本在你的 Mac 上运行时,VMPal 会检查一项设置。具体是在它们要执行以下操作时:

  • 把你的 Mac 添加为脚本的运行位置
  • 立即在那里运行脚本
  • 更改在那里运行的脚本的内容

这项设置位于 设置 › AI智能体 › 这台Mac上的脚本:

选项 VMPal 的行为
允许(由智能体询问你) 默认选项。VMPal 会直接允许,不询问你。智能体被告知要先询问你,但 VMPal 无法核实这一点。因此,你 Mac 上的任何应用都可能通过这种方式以你的身份运行代码
在VMPal中询问 VMPal 会向你显示脚本的内容和运行位置,并询问你。对脚本的每个版本只询问一次
关闭 VMPal 会拒绝

这项设置不影响虚拟机中的脚本,也不影响你在 Hub 中的操作。

使用 vmpal

vmpal 是 VMPal 的命令行工具,用法类似 docker 或 gh。它的 vmpal script 命令可以完成 Hub 所做的事:

命令 作用
vmpal script create <name> --file <path> 保存脚本。用 --run-in <VM> 选择虚拟机的全新克隆,用 --run-in-place <VM> 选择虚拟机本身,用 --host 选择这台 Mac 作为运行位置
vmpal script run <script> --wait 立即运行脚本并等待各次运行结束。它的退出码会说明运行是否成功
vmpal script log <script> 显示最新一次运行的输出
vmpal script runs <script> 列出脚本的运行记录,以及它们的状态和失败原因
vmpal script edit <script> 更改脚本的内容、设置或运行位置
vmpal script create "Build" --file build.sh --timeout 30m --run-in "Ubuntu"
vmpal script run "Build" --wait
vmpal script log "Build"

命令列出了其余命令。AI 智能体可以用 VMPal 的 MCP 工具完成同样的操作,例如 vmpal_create_script、vmpal_run_script 和 vmpal_get_run_log。这需要打开 允许这台Mac上的编程智能体管理所有虚拟机。