打包与发行布局

文档版本 v0.1.0-beta.3在 GitHub 上查看源文件

本页是 OmsiLaunch 0.1.0-beta3 英文原始页面 的译文。英文页面为规范文本：如有出入，以英文页面和代码为准。

本页说明 OmsiLaunch 0.1.0-beta3 发行包：tools\New-ReleasePackage.ps1 生成什么、release-manifest.json 的字段、控制器在运行时如何使用清单校验永久插件闭包、如何将包安装到 OMSI 安装根目录以及如何从中删除、使用后 .omsilaunch 目录包含哪些内容，以及验证脚本（tools\Test-ReleaseIdentity.ps1、tools\Test-ReleasePresentation.ps1、tools\Invoke-OfflineValidation.ps1）。产品标识来自 OmsiLaunch.Version.props。面向用户的安装步骤见安装；插件闭包在运行时的作用见永久插件。

产品标识（OmsiLaunch.Version.props）#

Directory.Build.props 将 InformationalVersion 设置为 OmsiLaunchProductVersion，不附带源代码修订号，因此 OmsiLaunch.exe /version 输出的正是 0.1.0-beta3。

构建（tools\New-ReleasePackage.ps1）#

New-ReleasePackage.ps1 [-Configuration Release|Debug] [-OutputDirectory <dir>] [-AllowOverwritePublished]（默认输出目录为 artifacts\release）从已构建的产物暂存一个包。当 OmsiLaunch-<product_version>.zip 已存在时，除非指定 -AllowOverwritePublished，否则拒绝写入 artifacts\release；候选包写入其他目录（离线验证使用 artifacts\candidate\post-round-a）。

暂存之前，会检查每个构建输出是否过期。

• OmsiLaunch.Native.x86.dll：按内容检查，而非按时间戳。 原生构建会写入 artifacts\x86\<cfg>\OmsiLaunch.Native.x86.build-receipt.txt（.vcxproj 中的目标 WriteOmsiLaunchNativeBuildReceipt）：其中记录所生成 DLL 的 SHA-256（output=）以及构建所用每个源文件的 SHA-256（source=<sha256>|<path>：.cpp、.rc、.vcxproj 和 OmsiLaunch.Version.props）。以下情况下打包会拒绝该 DLL：其哈希不是记录的输出（does not match its build receipt：过期或外来的副本，无论时间戳如何）、记录的源文件已更改（Native source changed after the recorded build）、有原生源文件未被回执覆盖，或回执缺失。
• Shim 和托管程序集：按时间戳检查。 每个产物都不得早于其所属项目的源文件（每个 shim 的 .cpp/.rc/.vcxproj；每个托管程序集自身的项目）。过期的输入会以 Stale build artifact 中止打包。

随后，包会在一个全新的、名称唯一的暂存目录（输出目录中的 .staging-<guid>）中组装，因此之前运行留下的任何文件都无法进入闭包。只有在下文所有检查都通过后，才会替换之前的 OmsiLaunch-current 文件夹和归档文件。

然后，脚本计算每个暂存文件的哈希，在包根目录以不带 BOM 的 UTF-8 写入 release-manifest.json（结果不再取决于 PowerShell 版本），在暂存区上运行 Test-ReleasePackageIntegrity.ps1，将每个暂存的插件文件和 OmsiLaunch.Native.x86.dll 与其构建输出重新比较，压缩暂存区，将归档解压到一个全新的临时目录，并根据同一清单校验解压出的闭包（归档中的清单必须与已校验的清单逐字节相同），然后将暂存区发布为 OmsiLaunch-current，将归档发布为 OmsiLaunch-current.zip，将其复制为 OmsiLaunch-<product_version>.zip（OmsiLaunch-0.1.0-beta3.zip），并写入内容为 <SHA-256> <file name> 的 OmsiLaunch-0.1.0-beta3.zip.sha256。任何产物缺失都会使脚本中止。该脚本不执行构建；请先运行 Invoke-OfflineValidation.ps1（或单独的 dotnet build / MSBuild 步骤）。

包布局#

OmsiLaunch.exe                       console shim (x64 native)
OmsiLaunchW.exe                      Windows-subsystem shim (x64 native)
nethost.dll                          .NET host locator used by both shims
OmsiLaunch.Controller.dll            managed controller (x64, net6.0-windows)
OmsiLaunch.Controller.deps.json
OmsiLaunch.Controller.runtimeconfig.json   requires Microsoft.NETCore.App 6.0 + Microsoft.WindowsDesktop.App 6.0
OmsiLaunch.Api.dll  OmsiLaunch.Core.dll  OmsiLaunch.Process.dll  OmsiLaunch.Configuration.dll
OmsiLaunch.Content.dll  OmsiLaunch.Builds.Omsi23004.dll  YamlDotNet.dll
LICENSE  THIRD-PARTY-NOTICES.md
release-manifest.json                package inventory and expected plugin hashes
plugins\                             the permanent plugin closure (9 files, all named OmsiLaunch.*)
  OmsiLaunch.Plugin.opl              OMSI plugin descriptor
  OmsiLaunch.PluginNE.dll            native export shim loaded by OMSI (x86)
  OmsiLaunch.Plugin.dll              managed plugin (x86, net6.0-windows)
  OmsiLaunch.Plugin.deps.json  OmsiLaunch.Plugin.runtimeconfig.json   requires Microsoft.NETCore.App 6.0 (x86)
  OmsiLaunch.Api.dll  OmsiLaunch.Builds.Omsi23004.dll  OmsiLaunch.Interop.dll   x86 copies
  OmsiLaunch.Native.x86.dll          native bridge (loaded from plugins\ only)
.omsilaunch\
  assets\splash\{PTB,ENG,DEU,FRA}.bmp   640x480 24-bit managed splash assets
  docs\                               English documentation (README.md, getting-started\, reference\, concepts\, status\, ...)
  docs\localized\<locale>\             translations of the 0.1.0-beta3 pages (not normative)
  examples\release-session.example.json
  examples\session-profiles\rmg-leste\profile.yaml

只有根目录下的产品文件、plugins\OmsiLaunch.* 和 .omsilaunch\ 归产品所有。plugins\ 下的第三方插件从不被 OmsiLaunch 枚举、复制、计算哈希、删除或还原。

release-manifest.json#

清单是数据，从不是可执行的策略：控制器只读取 plugins/ 条目。读取器接受带或不带 UTF-8 BOM 的文件（在此修正之前由 Windows PowerShell 5.1 写入的清单带有 BOM）。

清单的运行时用途（插件完整性）#

每次规划和启动之前，OmsiLaunchService.LoadArtifacts 都会构建预期的插件闭包（RuntimeArtifactSet.Load，src\OmsiLaunch.Process\RuntimeDeployment.cs）：

1. 控制器在 OmsiLaunch.exe 旁（AppContext.BaseDirectory）查找 release-manifest.json。存在时，ReleaseManifest.TryReadPluginHashes 提取 plugins/* 的哈希（无法作为清单读取该文件时为 OL_E_RELEASE_MANIFEST_INVALID）。
2. 计算每个已安装文件 <root>\plugins\OmsiLaunch.* 的哈希（SHA-256）并进行比较：
   • 有清单时：与清单中的哈希比较；记录计划诊断信息 plugin.integrity.reference = manifest。文件缺失 → OL_E_PERMANENT_PLUGIN_MISSING；文件存在但未列出 → OL_E_PERMANENT_PLUGIN_MANIFEST_INCOMPLETE；哈希不同 → OL_E_PERMANENT_PLUGIN_HASH_MISMATCH（reinstall the OmsiLaunch package so plugins\ and release-manifest.json agree）。
   • 无清单时（开发布局，或省略了清单的安装）：只能检查存在性以及与控制器旁打包副本的自一致性；plugin.integrity.reference = self。
3. 失败会将计划标记为不可运行（带详细信息的 OL_E_RUNTIME_ARTIFACT_MISSING）或拒绝启动（退出码 7）。

会话从不对插件文件进行暂存、快照、还原或删除；闭包是安装实例的永久组成部分。x86 的 OmsiLaunch.Native.x86.dll 只从 plugins\ 加载；托管程序集声明了 DefaultDllImportSearchPaths(AssemblyDirectory | System32)。

安装到 OMSI 根目录#

1. 校验归档：将 OmsiLaunch-0.1.0-beta3.zip 与 OmsiLaunch-0.1.0-beta3.zip.sha256 进行比对。
2. 将归档直接解压到 OMSI 安装根目录（包含 Omsi.exe 的目录）。这会放置根目录文件、plugins\OmsiLaunch.*（与任何第三方插件并列）以及 .omsilaunch\。
3. 将 release-manifest.json 保留在 OmsiLaunch.exe 旁：它用于启用基于清单的插件完整性校验。清单和二进制文件必须来自同一个包：在旧清单上覆盖新二进制文件（或反之）会导致每次启动都以 OL_E_PERMANENT_PLUGIN_HASH_MISMATCH 失败。Test-ReleasePresentation.ps1 -InstallPackage 现在会将清单与产品文件一起复制；它以前会跳过清单，导致较新的二进制文件旁留有旧清单（Round A RA-007）。
4. 使用 tools\Test-ReleasePackageIntegrity.ps1 -PackagePath <zip> -InstallationRoot <root> 以只读方式检查一致性：installation_comparison.coherent_with_package 必须为 true。
5. 不要将插件二进制文件移到 .omsilaunch\ 中，也不要重命名 plugins\OmsiLaunch.*。
6. 使用 OmsiLaunch.exe /version、OmsiLaunch.exe profiles 和一次 /plan 进行验证（参见第一个会话）。

会话从不覆盖已有的 .omsilaunch\assets\splash\*.bmp 文件（显式托管的资源集会保留）；通过解压新包来覆盖它们属于用户的有意操作。

使用后的 .omsilaunch 目录#

没有数据离开本机。参见事务与恢复。

卸载#

1. 确认没有正在运行的会话（OmsiLaunch.exe detect、OmsiLaunch.exe session status），且没有待处理的恢复（OmsiLaunch.exe /recovery-status；如果 pending 为 true，请运行 /recover），以确保 OMSI 文件已被还原。
2. 删除 plugins\OmsiLaunch.Plugin.opl、plugins\OmsiLaunch.PluginNE.dll、plugins\OmsiLaunch.Plugin.dll、plugins\OmsiLaunch.Plugin.deps.json、plugins\OmsiLaunch.Plugin.runtimeconfig.json、plugins\OmsiLaunch.Api.dll、plugins\OmsiLaunch.Builds.Omsi23004.dll、plugins\OmsiLaunch.Interop.dll、plugins\OmsiLaunch.Native.x86.dll。不要改动其他插件。
3. 删除上文布局中列出的根目录产品文件（OmsiLaunch.exe、OmsiLaunchW.exe、nethost.dll、OmsiLaunch.*.dll、OmsiLaunch.Controller.*.json、YamlDotNet.dll、release-manifest.json、LICENSE、THIRD-PARTY-NOTICES.md）。
4. 删除 .omsilaunch\（这会删除您的会话配置档和诊断信息）。存在 journal.json 时切勿删除该目录。

已完成的会话会还原其所有的每个文件，因此无需进一步清理。OMSI 自身在运行时写入的文件（例如 options.cfg 中的 [last_map]、缓存、laststn.osn、日志文件）属于 OMSI 的正常状态，不会被还原；参见事务与恢复。

验证脚本#

两个 Test-* 脚本都会读取 OmsiLaunch.Version.props 以获知预期版本。