ci: core regression gates

- Add GitHub Actions core regression (MSVC/Ninja, Ubuntu/Ninja, MinGW)
- Add optional short soak workflow_dispatch job + artifacts
- Add ctest runtime-cli script replay gate (WorldDb cycle)
- Add schema version constants + runtime-cli/GUI checks
- Add doc/version contract tests + PR template

Author: 129s

.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## 变更说明
+- 
+
+## 回归与门禁（必选）
+- [ ] `ctest --test-dir build_core --output-on-failure` 通过（含 `RuntimeCli.RunWorldCycleScript`）
+- [ ] 如修改 `TickTelemetry` / `WorldAtlas` / Runtime API：已更新 `docs/architecture/foundation/telemetry-schema.md` / `docs/architecture/foundation/runtime-api.md`
+- [ ] 如新增/变更脚本/命令：已更新 `docs/handbook/CORE_REGRESSION.md` 或 `docs/guides/headless_runtime_cli.md`
+
+## 风险与回滚
+- 风险点：
+- 回滚方式：
+

.github/workflows/core-regression.yml

@@ -0,0 +1,170 @@
+name: core-regression
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+    inputs:
+      run_soak:
+        description: "Run short soak (uploads artifacts)"
+        type: boolean
+        default: false
+
+concurrency:
+  group: core-regression-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  windows-core:
+    name: Windows (Core)
+    runs-on: windows-latest
+    env:
+      CPM_SOURCE_CACHE: ${{ github.workspace }}\.cpmcache
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ilammy/msvc-dev-cmd@v1
+
+      - uses: seanmiddleditch/gha-setup-ninja@v5
+
+      - name: Cache CPM
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.CPM_SOURCE_CACHE }}
+          key: ${{ runner.os }}-cpm-${{ hashFiles('**/CMakeLists.txt', 'cmake/**') }}
+          restore-keys: |
+            ${{ runner.os }}-cpm-
+
+      - name: Configure (Core)
+        shell: pwsh
+        run: >
+          cmake -S . -B build_core -G Ninja
+          -DGENESISENGINE_ENABLE_TESTS=ON
+          -DGENESIS_BUILD_GUI=OFF
+          -DGENESIS_WITH_STYLE=OFF
+          -DCMAKE_BUILD_TYPE=Debug
+
+      - name: Build (Core)
+        shell: pwsh
+        run: cmake --build build_core --parallel
+
+      - name: Test (ctest)
+        shell: pwsh
+        run: ctest --test-dir build_core --output-on-failure
+
+  ubuntu-soak:
+    name: Ubuntu (Short Soak, optional)
+    if: ${{ github.event_name == 'workflow_dispatch' && inputs.run_soak }}
+    runs-on: ubuntu-latest
+    env:
+      CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpmcache
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Ninja
+        run: sudo apt-get update && sudo apt-get install -y ninja-build
+
+      - name: Cache CPM
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.CPM_SOURCE_CACHE }}
+          key: ${{ runner.os }}-cpm-${{ hashFiles('**/CMakeLists.txt', 'cmake/**') }}
+          restore-keys: |
+            ${{ runner.os }}-cpm-
+
+      - name: Configure (Core)
+        run: >
+          cmake -S . -B build_soak -G Ninja
+          -DGENESISENGINE_ENABLE_TESTS=OFF
+          -DGENESIS_BUILD_GUI=OFF
+          -DGENESIS_WITH_STYLE=OFF
+          -DCMAKE_BUILD_TYPE=RelWithDebInfo
+
+      - name: Build (runtime-cli)
+        run: cmake --build build_soak --parallel --target genesis_runtime_cli
+
+      - name: Run soak
+        run: |
+          mkdir -p out/ci
+          ./build_soak/src/genesis-runtime-cli soak data/world_multiagent --root . --steps 800 --agents 12 --out out/ci/soak_metrics.json --summary-out out/ci/soak_summary.md --quiet
+
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: soak-ci
+          path: out/ci
+
+  ubuntu-core:
+    name: Ubuntu (Core)
+    runs-on: ubuntu-latest
+    env:
+      CPM_SOURCE_CACHE: ${{ github.workspace }}/.cpmcache
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Ninja
+        run: sudo apt-get update && sudo apt-get install -y ninja-build
+
+      - name: Cache CPM
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.CPM_SOURCE_CACHE }}
+          key: ${{ runner.os }}-cpm-${{ hashFiles('**/CMakeLists.txt', 'cmake/**') }}
+          restore-keys: |
+            ${{ runner.os }}-cpm-
+
+      - name: Configure (Core)
+        run: >
+          cmake -S . -B build_core -G Ninja
+          -DGENESISENGINE_ENABLE_TESTS=ON
+          -DGENESIS_BUILD_GUI=OFF
+          -DGENESIS_WITH_STYLE=OFF
+          -DCMAKE_BUILD_TYPE=Debug
+
+      - name: Build (Core)
+        run: cmake --build build_core --parallel
+
+      - name: Test (ctest)
+        run: ctest --test-dir build_core --output-on-failure
+
+  windows-mingw-core:
+    name: Windows (Core, MinGW)
+    runs-on: windows-latest
+    env:
+      CPM_SOURCE_CACHE: ${{ github.workspace }}\.cpmcache
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: msys2/setup-msys2@v2
+        with:
+          msystem: MINGW64
+          update: true
+          install: >-
+            mingw-w64-x86_64-gcc
+            mingw-w64-x86_64-cmake
+            mingw-w64-x86_64-ninja
+
+      - name: Cache CPM
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.CPM_SOURCE_CACHE }}
+          key: ${{ runner.os }}-mingw-cpm-${{ hashFiles('**/CMakeLists.txt', 'cmake/**') }}
+          restore-keys: |
+            ${{ runner.os }}-mingw-cpm-
+
+      - name: Configure (Core, MinGW)
+        shell: msys2 {0}
+        run: >
+          cmake -S . -B build_core_mingw -G Ninja
+          -DGENESISENGINE_ENABLE_TESTS=ON
+          -DGENESIS_BUILD_GUI=OFF
+          -DGENESIS_WITH_STYLE=OFF
+          -DCMAKE_BUILD_TYPE=Debug
+
+      - name: Build (Core, MinGW)
+        shell: msys2 {0}
+        run: cmake --build build_core_mingw --parallel
+
+      - name: Test (ctest, MinGW)
+        shell: msys2 {0}
+        run: ctest --test-dir build_core_mingw --output-on-failure

docs/guides/build_pipeline.md

@@ -59,6 +59,7 @@ ctest --test-dir build --output-on-failure
 ```
 
 `ctest` 将自动运行已注册的 gtest 二进制及若干 CTest 条目（以 `tests/CMakeLists.txt` 为准）。
+其中包含一条 Runtime CLI 回放用例（`RuntimeCli.RunWorldCycleScript`），用于覆盖 “脚本→命令队列→执行→世界保存” 的最小闭环。
 
 ## 5. 世界生成（Worldgen）
 - Worldgen 可独立运行（通过 Runtime 命令 `world.db.generate` 或 headless 脚本），不再依赖旧的 `LocationGraph`。
@@ -77,5 +78,7 @@ ctest --test-dir build --output-on-failure
 4. （可选）通过沙盒 GUI 的 World Generation 面板或运行时命令脚本验证世界生成流程
 5. 在 `build/src/genesis-sandbox-gui` 目录下启动 GUI 进行回归验证
 
+Windows 一键回归（Core only）：`powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_regression_core.ps1 -Config Debug -BuildDir build_core`
+
 若引入新依赖或修改工具链，请记得更新本文件并在 PR 描述中说明。
 

docs/guides/headless_runtime_cli.md

@@ -25,6 +25,7 @@ cmake --build build_headless --target genesis_runtime_cli
 - `--world <folder>`：启动时先加载一次世界（可选；脚本也可自行 `world.db.load`）
 - `--events-out <file>`：把执行过的 `RuntimeEventReport` 列表写到 JSON 文件
 - `--after-steps <n>`：脚本执行完后额外推进 n 步（用于观察非事件驱动的演化）
+- `--no-schema-check`：禁用 `schema_version` 校验（不推荐；仅用于排障/临时兼容）
 
 ## 短 Soak 指标报告（软指标，不做硬门禁）
 

docs/handbook/CORE_REGRESSION.md

@@ -19,6 +19,9 @@ cmake --build build_core --parallel
 ctest --test-dir build_core --output-on-failure
 ```
 
+提示：
+- 当前 `ctest` 已包含一条 Runtime CLI 端到端回放用例（`RuntimeCli.RunWorldCycleScript`），用于覆盖 JSON 脚本→命令队列→执行→世界保存的最小闭环。
+
 关注的回归信号（示例）：
 - `genesis_runtime_tests`：事件队列、JSON 命令、快照 diff、涌现 smoke、多人回归
 - `RuntimeShortSoak.*`：短时稳定性与可观测性基线（默认纳入 `genesis_runtime_tests`）
@@ -40,8 +43,18 @@ cmake --build build_core --target genesis_runtime_cli
 .\build_core\src\genesis-runtime-cli.exe run-script data\scripts\world_cycle.json --root . --max-steps 256 --after-steps 32
 ```
 
+注意：`genesis-runtime-cli` 默认会校验 `TickTelemetry.schema_version` 与 `WorldAtlas.schema_version`（避免误用旧 DLL 导致“静默错读”）；如需临时绕过可追加 `--no-schema-check`（不推荐）。
+
 更多说明见：`docs/guides/headless_runtime_cli.md` 与 `docs/architecture/foundation/runtime-api.md`。
 
+## 3.0 一键回归（推荐）
+
+在 Windows PowerShell 下可直接使用脚本完成：配置→编译→ctest→CLI 回放：
+
+```powershell
+powershell -NoProfile -ExecutionPolicy Bypass -File scripts\run_regression_core.ps1 -Config Debug -BuildDir build_core
+```
+
 ## 3.1 短 Soak：软指标报告（多样性 / 资源经济）
 
 说明：Soak 报告用于版本间对比与调参，不作为 CI 硬门禁；CI 侧仍以单元/集成测试的“硬契约”与短 soak 的不变量断言为主。

include/genesis/runtime/SchemaVersions.hpp

@@ -0,0 +1,10 @@
+#pragma once
+
+#include <cstdint>
+
+namespace Genesis::Runtime {
+
+inline constexpr std::uint32_t kWorldAtlasSchemaVersion = 2;
+
+} // namespace Genesis::Runtime
+

include/genesis/runtime/WorldAtlas.hpp

@@ -4,12 +4,13 @@
 #include <optional>
 #include <vector>
 
+#include "genesis/runtime/SchemaVersions.hpp"
 #include "genesis/world/WorldDatabase.hpp"
 
 namespace Genesis::Runtime {
 
 struct WorldAtlas {
-    std::uint32_t schema_version{2};
+    std::uint32_t schema_version{kWorldAtlasSchemaVersion};
     std::uint32_t world_version{0};
 
     struct PerMap {
@@ -26,4 +27,3 @@ struct WorldAtlas {
 };
 
 } // namespace Genesis::Runtime
-

include/genesis/telemetry/SchemaVersions.hpp

@@ -0,0 +1,10 @@
+#pragma once
+
+#include <cstdint>
+
+namespace genesis::telemetry {
+
+inline constexpr std::uint32_t kTickTelemetrySchemaVersion = 5;
+
+} // namespace genesis::telemetry
+

include/genesis/telemetry/TelemetryBuffer.hpp

@@ -5,6 +5,7 @@
 #include <string>
 #include <vector>
 
+#include "genesis/telemetry/SchemaVersions.hpp"
 #include "genesis/world/WorldTypes.hpp"
 #include "genesis/world/WorldDatabase.hpp"
 
@@ -93,7 +94,7 @@ struct MovementSnapshot {
 };
 
 struct TickTelemetry {
-    std::uint32_t schema_version{5};
+    std::uint32_t schema_version{kTickTelemetrySchemaVersion};
     std::uint64_t step{0};
     float stepSeconds{0.0f};
     std::vector<ResourceSnapshot> resources;

scripts/run_regression_core.ps1

@@ -1,19 +1,67 @@
 param(
   [string]$Generator = "Ninja",
   [string]$Config = "Release",
-  [string]$BuildDir = "build_regression_core"
+  [string]$BuildDir = "build_regression_core",
+  [switch]$SkipRuntimeCliScript,
+  [string]$RuntimeCliScript = "data/scripts/world_cycle.json",
+  [UInt64]$RuntimeCliMaxSteps = 256,
+  [UInt64]$RuntimeCliAfterSteps = 32
 )
 
 $ErrorActionPreference = "Stop"
 
 $repoRoot = Resolve-Path (Join-Path $PSScriptRoot "..")
+$buildPath = Join-Path $repoRoot $BuildDir
 
-$args = @("-S", $repoRoot, "-B", (Join-Path $repoRoot $BuildDir), "-G", $Generator)
+function Ensure-Dir([string]$Path) {
+  New-Item -ItemType Directory -Force -Path $Path | Out-Null
+}
+
+$args = @("-S", $repoRoot, "-B", $buildPath, "-G", $Generator)
 $args += "-DGENESISENGINE_ENABLE_TESTS=ON"
 $args += "-DGENESIS_BUILD_GUI=OFF"
 $args += "-DGENESIS_WITH_STYLE=OFF"
 
 & cmake @args | Write-Host
-& cmake --build (Join-Path $repoRoot $BuildDir) --parallel --config $Config | Write-Host
-& ctest --test-dir (Join-Path $repoRoot $BuildDir) --output-on-failure -C $Config | Write-Host
+& cmake --build $buildPath --parallel --config $Config | Write-Host
+& ctest --test-dir $buildPath --output-on-failure -C $Config | Write-Host
+
+if (-not $SkipRuntimeCliScript) {
+  & cmake --build $buildPath --parallel --config $Config --target genesis_runtime_cli | Write-Host
+
+  $exe = Join-Path $buildPath "src\\genesis-runtime-cli.exe"
+  if (!(Test-Path $exe)) {
+    throw "Missing executable: $exe"
+  }
+
+  Ensure-Dir (Join-Path $repoRoot "out")
+  Ensure-Dir (Join-Path $repoRoot "out\\regression")
+  Ensure-Dir (Join-Path $repoRoot "out\\regression\\scripts")
+
+  $timestamp = Get-Date -Format "yyyyMMdd_HHmmss"
+  $backupFolder = Join-Path $repoRoot ("out\\regression\\world_new_backup_{0}" -f $timestamp)
+
+  $scriptPath = Resolve-Path (Join-Path $repoRoot $RuntimeCliScript)
+  if (!(Test-Path $scriptPath)) {
+    throw "Missing runtime-cli script: $scriptPath"
+  }
+
+  $scriptJson = Get-Content -Raw $scriptPath | ConvertFrom-Json
+  if ($null -eq $scriptJson.commands) {
+    throw "Invalid runtime-cli script (expected object with 'commands'): $scriptPath"
+  }
+
+  foreach ($cmd in $scriptJson.commands) {
+    if ($cmd.action -eq "world.db.save") {
+      $cmd.folder = $backupFolder
+    }
+  }
+
+  $patchedScriptPath = Join-Path $repoRoot ("out\\regression\\scripts\\world_cycle_{0}.json" -f $timestamp)
+  ($scriptJson | ConvertTo-Json -Depth 16) | Out-File -FilePath $patchedScriptPath -Encoding utf8
 
+  & $exe run-script $patchedScriptPath --root $repoRoot --max-steps $RuntimeCliMaxSteps --after-steps $RuntimeCliAfterSteps | Write-Host
+  if ($LASTEXITCODE -ne 0) {
+    throw ("runtime-cli run-script failed (exit={0})" -f $LASTEXITCODE)
+  }
+}