Lume 开发指南从工具链搭建到 macOS 离线无人值守安装的本地验证流程【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua本文基于 Lumecua monorepo 中基于 Apple Virtualization Framework 的 macOS/Linux 虚拟机 CLI 与框架见 libs/lume/README.md的开发文档完整覆盖工具链要求、VS Code monorepo 工作区配置、依赖解析与构建命令、lume create参数体系以及用本地 Apple restore 镜像IPSW端到端验证离线无人值守安装的完整流程。读完后你可以独立搭建 Lume 开发环境、编译运行与调试源码并复现“创建一台零 GUI 操作的纯净 macOS VM”这一核心场景。工具链要求与 Swift 包结构Development.md 给出的开发环境基线是Swift 6 或更高版本Xcode 15 或更高版本macOS Sequoia 15.2 或更高版本可选安装 Swift 扩展的 VS Code。这些要求与 Package.swift 的声明一致文件首行声明// swift-tools-version: 6.0即构建该包至少需要 Swift 6 工具链platforms指定.macOS(.v14)这是 SwiftPM 允许的最小部署目标而 Development 文档要求的 macOS 15.2 是“开发机”层面更高的实际门槛Apple Virtualization Framework 对宿主版本有要求。依赖方面lume可执行目标链接了 ArgumentParser命令行解析、YamsYAML 解析用于无人值守预设、swift-nio / NIOSSHSSH 客户端与健康检查、MCP swift-sdkMCP 服务端能力与 swift-atomics 等外部包测试目标lumeTests则额外依赖 swift-testing说明单测采用的是 Swift Testing 而非 XCTest 框架。理解包结构对定位源码很有帮助src目录按职责拆分为Commands/各子命令如Create.swift、Run.swift、SSH.swift、Unattended/离线安装编排、VM/虚拟机生命周期、SSH/、Server/HTTP 与 MCP 服务、Virtualization/Apple Virtualization Framework 封装等模块测试集中在tests/例如 UnattendedInstallerTests.swift 与 CreateCommandTests.swift。使用 monorepo 提供的 VS Code 工作区Lume 位于 cua monorepo 的libs/lume目录下。Development 文档建议在 monorepo 根目录使用专用工作区文件# Open VS Code workspace from the root of the monorepo code .vscode/lume.code-workspace.vscode/lume.code-workspace 的内容印证了文档中“预配置 Swift 语言支持、构建任务与调试配置”的说法其中值得关注的配置包括工作区只挂载../libs/lume一个文件夹显示名为lume避免 monorepo 其他语言项目干扰 Swift 索引settings中启用了swift.enableLanguageServer并显式将swift.path指向/Applications/Xcode.app/.../XcodeDefault.xctoolchain/usr/bin、DEVELOPER_DIR指向/Applications/Xcode.app即强制使用 Xcode 自带工具链以保证与 Apple 私有框架一致tasks中定义了build-debug默认构建任务执行 scripts/build/build-debug.sh同目录还有 build-release.sh 与 build-release-notarized.shlaunch中提供多个 LLDB 调试配置一个直接调试.build/debug/lume serve另一个模拟真实的lume create macos-vm --cpu 4 --memory 4GB --disk-size 40GB --ipsw /path/to/...ipsw命令行且都设置了preLaunchTask: build-debug即断点调试前自动先构建。本地初始化仓库Development 文档给出的初始化步骤为Fork 仓库后克隆、安装依赖、构建。核心命令是 SwiftPM 标准流程# 克隆后进入仓库 swift package resolve # 安装/锁定依赖 swift build # 构建项目swift package resolve会依据 Package.resolved 拉取并锁定上文提到的各依赖版本swift build产物落在.build/debug/lume工作区调试配置中的program路径即指向这里。若构建失败优先核对工具链是否满足“Swift 6 Xcode 15 macOS 15.2”基线这是该包能编译的前提。lume create参数解析无人值守安装的入口Development 文档“Testing Offline Unattended Setup”一节使用的三条命令是整个离线安装流程的入口lume create macos-tahoe --ipsw ~/Downloads/macos-tahoe.ipsw --unattended tahoe lume run macos-tahoe lume ssh macos-tahoe id -un第一条命令的参数语义可以从 Create.swift 中逐一确认参数说明默认值/约束来自源码name位置参数虚拟机名称必填--os操作系统macOS可选linux--cpuCPU 核数4--memory内存支持8/8GB/8192MB8GB--disk-size磁盘大小同上格式macOS 100GBLinux 50GB--display分辨率WIDTHxHEIGHT1024x768--ipswmacOS restore 镜像路径或latest下载最新支持版本macOS VM 必需--storage存储位置或 VM 存放目录默认位置--unattended离线无人值守预设名或自定义 YAML 路径内置预设sequoia、tahoe--vnc-port临时验证用 VNC 端口0自动分配--networknat/bridged/bridged:interfacenatCreate.swift中有两个与本文场景直接相关的行为值得注意--unattended仅支持 macOS--unattended is only supported for macOS VMs且磁盘下限校验为 macOS 30GB、Linux 10GB当指定了--unattended时noDisplay会被强制置为true“Default to no-display for unattended”即离线安装全程无头运行——这正是“无需 GUI 自动化”的实现前提。预设解析与内置 YAML 文件--unattended接受“预设名”或“YAML 文件路径”。UnattendedConfig.swift 中load(from:)先按预设名在 Bundle 资源unattended-presets目录查找*.yml找不到才按文件路径解析 YAML使用 Yams 库解码。当前内置的两个预设在 tahoe.yml 与 sequoia.yml 中二者内容完全一致# Offline macOS unattended setup preset. boot_wait: 0 boot_commands: [] health_check: type: ssh user: lume password: lume timeout: 5 retries: 60 retry_delay: 5配置结构对应UnattendedConfig结构体的四个字段boot_waitVM 启动后开始自动化前的等待秒数默认 60预设里为 0、boot_commands兼容字段离线安装会忽略、health_check成功后验证方式含type/user/password/timeout/retries/retry_delay、以及可选的post_ssh_commands健康检查通过后经 SSH 追加执行的命令文档注释说明其比经 VNC 在终端里敲命令更可靠。预设中的health_check含义是以lume/lume凭据 SSH 探测每次超时 5 秒最多重试 60 次、间隔 5 秒——即最长约 5 分钟的验证窗口。离线安装的三步编排安装的实际执行在 UnattendedInstaller.swiftinstall(vm:config:)编排为三个阶段首次启动“物化”状态materializeFirstBootState以displayMode: .none无头启动 VM等待 DHCP 租约解析出 VM IP通过 DHCPLeaseParser最长等 120 秒随后停止 VM。这一步让安装盘完成首次开机所需的文件系统初始化离线打补丁由MacOSOfflineSetupPatcherMacOSOfflineSetupPatcher.swift直接在关机状态下修改已安装的磁盘创建lume用户、开启 SSH 等全程不经过 Setup Assistant 的 GUI启动验证verifySetup再次无头启动 VM对 “auxiliary storage” 锁错误最多重试 3 次等 IP 后按health_check配置做 SSH 健康检查通过后再经 SSH 以 base64 编码的脚本执行“guest 最终化”guestFinalizationScript写入/var/db/.AppleSetupDone标记、com.apple.loginwindow自动登录lume用户、关闭 Guest 登录、标记 Setup Assistant 各步骤已完成、launchctl enable system/com.openssh.sshd启用 SSH、并用diskutil apfs updatePreboot将新建的管理员发布到 Recovery 环境最后校验标记文件属主必须是root:wheel输出含MARKER_OWNER0:0才算成功。若配置了post_ssh_commands则追加执行。验证完成后自动停止 VM。验证成功的判据就是 Development 文档给出的三条命令lume run启动后可用lume ssh macos-tahoe id -un登录guest 应报告用户名lume且使用默认密码lume可以 SSH 登录、开机过程不经过 Setup Assistant默认凭据lume/lume亦见 README.md 的说明。适用前提与已知限制Development 文档明确指出Tahoe 是“当前经过本地 IPSW 端到端验证”的预设Sequoia 预设首次带显示器启动时仍可能出现 Setup Assistant 的 Accessibility 步骤该问题以 issue #2155 跟踪。因此复现时优先使用 Tahoe 镜像换用 Sequoia 时把--unattended tahoe替换为--unattended sequoia并选择匹配的 VM 名称即可README 中有同样说明。开发工作流与测试Development 文档定义的日常流程是新建分支 → 修改代码 → 运行swift test→ 本地构建与测试 → 以清晰的 commit 信息提交。测试目标为 Package.swift 中声明的lumeTests路径tests/依赖 swift-testing 的Testing产品共约 30 个测试文件按模块组织无人值守安装UnattendedInstallerTests.swift、创建命令CreateCommandTests.swift、SSH 客户端SSHClientTests.swift、磁盘扩容 GPT 处理tests/DiskResize/以及带 Mock 的 VM/VNC 行为tests/Mocks/MockVM.swift。修改Unattended或Commands下的逻辑时对应测试是最直接的回归验证手段。提交 Pull Request 与问题反馈Development 文档对 PR 的要求是推送到自己的 Fork 后提交包含清晰标题与描述、关联 issue 引用、必要时的截图或日志的 PR并及时响应维护者反馈。补充说明工作区调试配置中已经内置了lume create --ipsw等典型命令的 LLDB 复现路径PR 中附上的日志可以直接来自.build/debug/lume的运行输出Bug 报告与功能建议的完整规范含需附带的 macOS 版本、lume 版本、复现步骤等要素见 CONTRIBUTING.md可选依赖方面仅lume sip命令依赖vncdotool经 VNC 控制 macOS Recovery其他开发场景无需安装。按以上流程即可在不离开本地 macOS 环境的前提下完成 Lume 的开发、构建、测试并用真实 restore 镜像端到端验证“离线无人值守安装 macOS VM”这一核心能力。【免费下载链接】cuaScale computer-use 2.0 with open-source drivers, cross-OS fleets, and benchmarks for training, evaluation, and data generation.项目地址: https://gitcode.com/GitHub_Trending/cua/cua创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考