fix(ci): ui-golden 需要机器级 SDL2 SDK——补 DTU_SDL2_DIR、配置期护栏与 build 缓存自愈

scripts/ci_runner_bootstrap.ps1

@@ -49,7 +49,7 @@
 
 .PARAMETER SetEnv
     Discover and write MACHINE-level DTU_PRECOMMIT_PYTHON / DTU_CPPCHECK /
-    DTU_MSVC_CL / DTU_MS_COVERAGE. Existing values are preserved unless
+        DTU_MSVC_CL / DTU_MS_COVERAGE / DTU_SDL2_DIR. Existing values are preserved unless
     -Force. MSVC discovery goes through vswhere (so VS on a non-default
     drive is found) and pins the toolset with -MsvcToolset, because the
     coverage baseline was recorded with one specific MSVC version -- see
@@ -245,6 +245,40 @@ function Find-MsvcCl {
     return $sorted[0].Cl
 }
 
+# ---------------------------------------------------------------------------
+# Locate an SDL2 SDK root usable by the UI simulator (ui-golden gate).
+# The SDK is DOWNLOADED, not tracked: .gitignore excludes simulator/SDL2/, so a
+# CI workspace never contains it. Measured 2026-10-27 run 45: ui-golden died with
+# C1083 "SDL2/SDL.h" on the runner while every local run was green -- a missing
+# third-party SDK, not a pixel regression. Discovery order:
+#   1) an already-valid DTU_SDL2_DIR (Machine, then Process)
+#   2) a machine-wide copy under -MachineSdkRoot (default D:\DTU_SDK)
+#   3) this repository checkout's simulator/SDL2/SDL2-* -- works for local runs,
+#      but a runner workspace will not contain it, so on the CI box prefer 1 or 2
+# Returns the root that contains include\SDL2\SDL.h, else $null.
+# ---------------------------------------------------------------------------
+function Find-Sdl2Sdk {
+    param([string]$MachineSdkRoot = 'D:\DTU_SDK')
+    $rel = 'include\SDL2\SDL.h'
+    $cand = [System.Collections.Generic.List[string]]::new()
+    foreach ($sc in @('Machine', 'User', 'Process')) {
+        $v = [Environment]::GetEnvironmentVariable('DTU_SDL2_DIR', $sc)
+        if ($v) { $cand.Add($v) }
+    }
+    if ($MachineSdkRoot -and (Test-Path -LiteralPath $MachineSdkRoot)) {
+        Get-ChildItem -LiteralPath $MachineSdkRoot -Directory -Filter 'SDL2-*' -ErrorAction SilentlyContinue |
+            Sort-Object Name -Descending | ForEach-Object { $cand.Add($_.FullName) }
+    }
+    $repoSdk = Join-Path (Split-Path -Parent $PSScriptRoot) 'simulator\SDL2'
+    if (Test-Path -LiteralPath $repoSdk) {
+        Get-ChildItem -LiteralPath $repoSdk -Directory -Filter 'SDL2-*' -ErrorAction SilentlyContinue |
+            Sort-Object Name -Descending | ForEach-Object { $cand.Add($_.FullName) }
+    }
+    foreach ($c in $cand) {
+        if ($c -and (Test-Path -LiteralPath (Join-Path $c $rel))) { return $c }
+    }
+    return $null
+}
 function Find-CoverageConsole {
     # Microsoft.CodeCoverage.Console.exe ships ONLY inside Visual Studio
     # (measured 2026-10-27: NuGet candidates contain no such .exe, or only the
@@ -380,10 +414,10 @@ if ($Status) {
     if (Test-Gitea $GiteaUrl) { Ok "Gitea reachable at $GiteaUrl" }
     else { Fail "Gitea NOT reachable at $GiteaUrl" }
 
-    foreach ($n in @('DTU_PRECOMMIT_PYTHON', 'DTU_CPPCHECK', 'DTU_MSVC_CL', 'DTU_MS_COVERAGE')) {
+    foreach ($n in @('DTU_PRECOMMIT_PYTHON', 'DTU_CPPCHECK', 'DTU_MSVC_CL', 'DTU_MS_COVERAGE', 'DTU_SDL2_DIR')) {
         $v = Get-MachineEnv $n
         if ($v) { Ok ("MACHINE {0} = {1}" -f $n, $v) }
-        else { Warn "MACHINE $n not set (CI auto-discovery still applies; see scripts/ci_find_python.ps1)" }
+        else { Warn "MACHINE $n not set (CI auto-discovery still applies; -SetEnv writes it, docs/CI/ guide sections 4.4 / 4.5 explain the pairing)" }
     }
     exit 0
 }
@@ -466,6 +500,22 @@ if ($SetEnv) {
     if ($cpp) { Set-MachineEnv 'DTU_CPPCHECK' $cpp 'DTU_CPPCHECK' }
     else { Warn 'cppcheck not found (install Cppcheck.Cppcheck, or set DTU_CPPCHECK manually)' }
 
+    # ui-golden needs the SDL2 SDK and a checked-out tree never has it (see
+    # Find-Sdl2Sdk). Pin it machine-wide so the runner resolves it under SYSTEM too.
+    $sdl = Find-Sdl2Sdk
+    if ($sdl) {
+        Set-MachineEnv 'DTU_SDL2_DIR' $sdl 'DTU_SDL2_DIR'
+        $repoRoot = (Split-Path -Parent $PSScriptRoot) + [IO.Path]::DirectorySeparatorChar
+        if ($sdl.StartsWith($repoRoot, [StringComparison]::OrdinalIgnoreCase)) {
+            Warn 'DTU_SDL2_DIR points INSIDE this repo checkout -- a runner workspace will not contain that path.'
+            Warn 'copy an SDK to D:\DTU_SDK (or point DTU_SDL2_DIR at a machine-wide path), then re-run -SetEnv'
+        }
+    }
+    else {
+        Warn 'no SDL2 SDK found: the ui-golden gate fails with C1083 SDL2/SDL.h (measured run 45).'
+        Warn 'download it per the simulator deployment guide (docs/CI/ guide, section 4.5) or copy one to D:\DTU_SDK, then re-run -SetEnv'
+    }
+
     $cl = Find-MsvcCl -ToolsetPrefix $MsvcToolset -Latest:$MsvcLatest
     if ($cl) {
         Set-MachineEnv 'DTU_MSVC_CL' $cl 'DTU_MSVC_CL'