命令行与构建参考¶

最低构建环境¶

C++20 编译器；
CMake 3.25+；
Ninja；
Qt 6.8+ Base/Widgets/SVG；
Protobuf 29+。

默认构建只使用经许可策略允许的 Qt 模块。构建脚本不会安装 Engine。

macOS / Linux¶

# 完整 Debug 构建、测试、离线 smoke
./scripts/build.sh

# 只检查依赖
./scripts/build.sh --check-only

# 缺依赖就失败，不自动安装
./scripts/build.sh --no-install

# Release
./scripts/build.sh --preset release

# 跳过测试
./scripts/build.sh --skip-tests

# 指定并行数
./scripts/build.sh --jobs 4

可用环境变量：VMA_QT_ROOT、VMA_DEPS_ROOT、VCPKG_ROOT、CMAKE_PREFIX_PATH。

手工的最小开发验证：

cmake --preset dev
cmake --build --preset dev
ctest --preset dev
./build/dev/vm-accelerator-studio --smoke-exit

macOS 应用路径是：

build/dev/vm-accelerator-studio.app/Contents/MacOS/vm-accelerator-studio

Windows¶

# Debug 构建和测试
.\scripts\windows\build-and-test.ps1

# Release
.\scripts\windows\build-and-test.ps1 -Configuration Release

# 只检查
.\scripts\windows\build-and-test.ps1 -CheckOnly

# 不自动安装
.\scripts\windows\build-and-test.ps1 -NoInstall

默认可执行文件位于 build\windows-msvc-debug\vm-accelerator-studio.exe 或对应 release 目录。脚本可使用 WinGet、项目本地 Qt 和 vcpkg Protobuf。

Studio 命令行¶

vm-accelerator-studio [options] [project]

选项	用途
`--offline`	禁用启动恢复和自动远端对账
`--theme system\|light\|dark`	本次启动主题
`--language system\|en\|zh-CN`	本次启动语言
`--physics-inputs`	加载项目后打开 Physics Inputs
`--local-results`	打开并复验 Screening Results
`--screening-study`	打开 Screening Study
`--nonlinear-dynamics`	打开 Nonlinear Dynamics
`--nonlinear-view setup\|da\|fma\|losses\|convergence\|evidence`	选择非线性页签
`--orbit-correction`	打开 Errors & Orbit Correction
`--orbit-view setup\|horizontal\|vertical\|correctors\|response\|tolerance\|evidence`	选择轨道页签
`--historical-catalog <path>`	打开历史迁移目录
`--screenshot <path>`	渲染主窗口截图并退出
`--smoke-exit`	短暂打开外壳后成功退出
`--help` / `--version`	帮助/版本

例子：

./build/dev/vm-accelerator-studio \
  --offline --theme dark --language zh-CN \
  --nonlinear-dynamics --nonlinear-view fma \
  protocol/nonlinear_lattice_projection_v0_1/fixtures/portable-sextupole-ring.studio-project.json

./build/dev/vm-accelerator-studio \
  --offline --orbit-correction --orbit-view tolerance \
  protocol/orbit_error_model_v0_1/fixtures/portable-fodo-reference-ring.studio-project.json

--offline 下 v0.8/v0.9 不会自动协商 runtime，因此这些命令适合查看草稿或本地保留证据，不适合开始新的远程任务。

Xsuite importer 命令¶

必填参数为 --input、--output、--project-id、--display-name 和 --expected-sha256；--project-json、--evidence-json 为可选 sidecar。完整例子见导入与历史迁移。

GitBook 使用方式¶

本用户手册入口是：

docs/user-guide/README.md
docs/user-guide/SUMMARY.md

可把 docs/user-guide 作为 GitBook 内容根；所有链接均为相对路径，也可直接在 GitHub/Codex 中浏览。