EricSun0218 · EricSun0218 · Aug 7, 2026 · Aug 7, 2026
@@ -1,4 +1,4 @@
-name: Build release artifacts
+name: Release
 
 on:
   workflow_dispatch:
@@ -7,6 +7,11 @@ on:
         description: Semantic version for the artifacts
         required: true
         default: 0.3.0-alpha.1
+      publish:
+        description: Publish NuGet packages and the GitHub pre-release
+        required: true
+        default: false
+        type: boolean
 
 permissions:
   contents: read
@@ -57,8 +62,134 @@ jobs:
       - name: Validate public tree
         shell: pwsh
         run: ./tools/Test-PublicTree.ps1
-      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+      - name: Build release bundle
+        shell: pwsh
+        run: ./tools/New-ReleaseBundle.ps1 -Version $env:RELEASE_VERSION
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
-          name: OpenGameAgent-${{ inputs.version }}
-          path: artifacts
+          name: OpenGameAgent-release-${{ inputs.version }}
+          path: artifacts/release
           if-no-files-found: error
+
+  stage-github-release:
+    if: ${{ inputs.publish }}
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_REPO: ${{ github.repository }}
+      RELEASE_VERSION: ${{ inputs.version }}
+      SOURCE_COMMIT: ${{ github.sha }}
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: OpenGameAgent-release-${{ inputs.version }}
+          path: release-assets
+      - name: Stage immutable GitHub pre-release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          tag="v${RELEASE_VERSION}"
+
+          existing_release="$(gh release view "${tag}" --json isDraft --jq .isDraft 2>/dev/null || true)"
+          if [[ "${existing_release}" == "false" ]]; then
+            echo "::error::Release ${tag} is already public and cannot be replaced."
+            exit 1
+          fi
+          if [[ "${existing_release}" == "true" ]]; then
+            gh release delete "${tag}" --yes
+          fi
+
+          tag_commit="$(gh api "repos/${GH_REPO}/commits/${tag}" --jq .sha 2>/dev/null || true)"
+          release_target=(--target "${SOURCE_COMMIT}")
+          if [[ -n "${tag_commit}" ]]; then
+            if [[ "${tag_commit}" != "${SOURCE_COMMIT}" ]]; then
+              echo "::error::Tag ${tag} points to ${tag_commit}, expected ${SOURCE_COMMIT}."
+              exit 1
+            fi
+            release_target=(--verify-tag)
+          fi
+
+          mapfile -t assets < <(
+            find release-assets -maxdepth 1 -type f ! -name RELEASE_NOTES.md -print |
+              sort
+          )
+          if [[ "${#assets[@]}" -ne 10 ]]; then
+            echo "::error::Expected 10 downloadable assets, found ${#assets[@]}."
+            printf '%s\n' "${assets[@]}"
+            exit 1
+          fi
+
+          gh release create "${tag}" +            "${release_target[@]}" +            --draft +            --prerelease +            --title "OpenGameAgent ${tag}" +            --notes-file release-assets/RELEASE_NOTES.md +            "${assets[@]}"
+
+          expected="$(printf '%s\n' "${assets[@]##*/}" | sort)"
+          actual="$(gh release view "${tag}" --json assets --jq '.assets[].name' | sort)"
+          if [[ "${actual}" != "${expected}" ]]; then
+            echo "::error::Draft release asset set is incomplete."
+            diff -u <(printf '%s\n' "${expected}") <(printf '%s\n' "${actual}") || true
+            exit 1
+          fi
+
+  publish-nuget:
+    if: ${{ inputs.publish }}
+    needs: stage-github-release
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      RELEASE_VERSION: ${{ inputs.version }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-dotnet@a98b56852c35b8e3190ac28c8c2271da59106c68 # v6
+        env:
+          DOTNET_INSTALL_DIR: ${{ runner.temp }}/.dotnet
+        with:
+          global-json-file: global.json
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: OpenGameAgent-release-${{ inputs.version }}
+          path: release-assets
+      - name: Exchange GitHub OIDC token for a temporary NuGet key
+        id: nuget-login
+        uses: NuGet/login@8d196754b4036150537f80ac539e15c2f1028841 # v1.2.0
+        with:
+          user: ${{ secrets.NUGET_USER }}
+      - name: Publish NuGet packages
+        shell: bash
+        env:
+          NUGET_API_KEY: ${{ steps.nuget-login.outputs.NUGET_API_KEY }}
+        run: |
+          set -euo pipefail
+          mapfile -t packages < <(find release-assets -maxdepth 1 -type f -name '*.nupkg' -print | sort)
+          if [[ "${#packages[@]}" -ne 6 ]]; then
+            echo "::error::Expected 6 NuGet packages, found ${#packages[@]}."
+            exit 1
+          fi
+          for package in "${packages[@]}"; do
+            dotnet nuget push "${package}" +              --api-key "${NUGET_API_KEY}" +              --source https://api.nuget.org/v3/index.json +              --skip-duplicate
+          done
+
+  publish-github-release:
+    if: ${{ inputs.publish }}
+    needs: publish-nuget
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    env:
+      GH_REPO: ${{ github.repository }}
+      RELEASE_VERSION: ${{ inputs.version }}
+    steps:
+      - name: Publish GitHub pre-release
+        shell: bash
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+          tag="v${RELEASE_VERSION}"
+          gh release edit "${tag}" --draft=false --prerelease
+          gh release view "${tag}" +            --json isDraft,isPrerelease +            --jq 'select(.isDraft == false and .isPrerelease == true)' >/dev/null
@@ -14,6 +14,16 @@ Inputs are bounded JSON. They may represent dialogue, combat observations, simul
 
 > Current version: `0.3.0-alpha.1`. Public APIs can change before `1.0`.
 
+## Install
+
+Install the complete game runtime from NuGet:
+
+```bash
+dotnet add package OpenGameAgent --version 0.3.0-alpha.1
+```
+
+The kernel, persistence, providers, and engine-compatible client are also published as separate `OpenGameAgent.*` packages. Godot, Unity, and portable server archives are available on the [Releases](https://github.com/EricSun0218/OpenGameAgent/releases) page. See [Getting started](docs/getting-started.md) and [Engine integration](docs/engine-integration.md) before connecting a game.
+
 ## Why game-specific?
 
 General agent loops commonly assume one user, wall-clock time, and a linear conversation. A game may have multiple timelines, save forks, thousands of actors, offline time jumps, engine main-thread constraints, and actions that must never be repeated after an uncertain failure.

@@ -14,6 +14,16 @@ OpenGameAgent 把小型、可组合的 Agent 内核带进游戏开发。它的
 
 > 当前版本：`0.3.0-alpha.1`。在 `1.0` 前公开 API 仍可能调整。
 
+## 安装
+
+从 NuGet 安装完整的游戏 Runtime：
+
+```bash
+dotnet add package OpenGameAgent --version 0.3.0-alpha.1
+```
+
+内核、持久化、模型提供方和引擎兼容客户端也分别提供 `OpenGameAgent.*` 包。Godot、Unity 与可移植服务端压缩包可以从 [Releases](https://github.com/EricSun0218/OpenGameAgent/releases) 页面下载。接入游戏前请阅读[快速开始](docs/getting-started.md)和[引擎接入](docs/engine-integration.md)。
+
 ## 为什么要做游戏专用层
 
 通用 Agent 往往默认单用户、现实时间和线性对话。游戏却可能拥有多条时间线、存档分支、成千上万个角色、离线时间跳跃、引擎主线程限制，以及不能在故障后盲目重试的状态变更。

@@ -42,6 +42,7 @@ if (Test-Path -LiteralPath $packageRoot) {
 }
 
 New-Item -ItemType Directory -Path (Join-Path $packagedAddon 'runtime'), (Join-Path $packagedAddon 'lib') -Force | Out-Null
+Copy-Item -LiteralPath (Join-Path $repositoryRoot 'LICENSE') -Destination (Join-Path $packageRoot 'LICENSE')
 Copy-Item -LiteralPath (Join-Path $addonRoot 'runtime\OpenGameAgentNode.cs') -Destination (Join-Path $packagedAddon 'runtime\OpenGameAgentNode.cs')
 Copy-Item -LiteralPath (Join-Path $addonRoot 'OpenGameAgent.Godot.props') -Destination (Join-Path $packagedAddon 'OpenGameAgent.Godot.props')
 Copy-Item -LiteralPath (Join-Path $addonRoot 'README.md') -Destination (Join-Path $packagedAddon 'README.md')

@@ -14,6 +14,7 @@ if ($LASTEXITCODE -ne 0) { throw 'Building the Godot package failed.' }
 $packageRoot = [string]$buildOutput[-1]
 
 $required = @(
+    'LICENSE',
     'addons\open_game_agent\plugin.cfg',
     'addons\open_game_agent\OpenGameAgent.Godot.props',
     'addons\open_game_agent\runtime\OpenGameAgentNode.cs',
@@ -27,4 +28,10 @@ foreach ($relative in $required) {
     }
 }
 
+$sourceLicenseHash = (Get-FileHash -LiteralPath (Join-Path $engineRoot 'LICENSE') -Algorithm SHA256).Hash
+$packagedLicenseHash = (Get-FileHash -LiteralPath (Join-Path $packageRoot 'LICENSE') -Algorithm SHA256).Hash
+if ($packagedLicenseHash -ne $sourceLicenseHash) {
+    throw 'Godot package must contain the complete repository license.'
+}
+
 $packageRoot
@@ -42,6 +42,7 @@ if (Test-Path -LiteralPath $packagePath) {
 
 New-Item -ItemType Directory -Path $outputRoot -Force | Out-Null
 Copy-Item -LiteralPath (Join-Path $engineRoot 'Packages\com.opengameagent.runtime') -Destination $packagePath -Recurse
+Copy-Item -LiteralPath (Join-Path $repositoryRoot 'LICENSE') -Destination (Join-Path $packagePath 'LICENSE.md') -Force
 $manifestPath = Join-Path $packagePath 'package.json'
 $manifest = Get-Content -LiteralPath $manifestPath -Raw | ConvertFrom-Json
 $manifest.version = $Version

@@ -13,6 +13,7 @@ if ($LASTEXITCODE -ne 0) { throw 'Building the Unity package failed.' }
 $packagePath = [string]$buildOutput[-1]
 
 $required = @(
+    'LICENSE.md',
     'package.json',
     'package.json.meta',
     'Runtime.meta',
@@ -35,6 +36,13 @@ foreach ($relative in $required) {
     }
 }
 
+$repositoryRoot = Split-Path -Parent (Split-Path -Parent $engineRoot)
+$sourceLicenseHash = (Get-FileHash -LiteralPath (Join-Path $repositoryRoot 'LICENSE') -Algorithm SHA256).Hash
+$packagedLicenseHash = (Get-FileHash -LiteralPath (Join-Path $packagePath 'LICENSE.md') -Algorithm SHA256).Hash
+if ($packagedLicenseHash -ne $sourceLicenseHash) {
+    throw 'Unity package must contain the complete repository license.'
+}
+
 $unexpected = Get-ChildItem -LiteralPath $packagePath -Recurse -File |
     Where-Object { $_.Name -match '^(GameAgent\.|OpenGameAgent\.Unity\.dll)' }
 if ($unexpected) {

@@ -0,0 +1,145 @@
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)]
+    [string] $Version,
+    [string] $ArtifactsDirectory,
+    [string] $OutputDirectory
+)
+
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+if ($Version -notmatch '^[0-9]+\.[0-9]+\.[0-9]+(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$') {
+    throw 'Version must be a semantic version.'
+}
+
+$repositoryRoot = Split-Path -Parent $PSScriptRoot
+if ([string]::IsNullOrWhiteSpace($ArtifactsDirectory)) {
+    $ArtifactsDirectory = Join-Path $repositoryRoot 'artifacts'
+}
+if ([string]::IsNullOrWhiteSpace($OutputDirectory)) {
+    $OutputDirectory = Join-Path $ArtifactsDirectory 'release'
+}
+
+$artifactsRoot = [IO.Path]::GetFullPath($ArtifactsDirectory)
+$outputRoot = [IO.Path]::GetFullPath($OutputDirectory)
+if (-not (Test-Path -LiteralPath $artifactsRoot -PathType Container)) {
+    throw "Artifacts directory '$artifactsRoot' does not exist."
+}
+if (-not $outputRoot.StartsWith($artifactsRoot + [IO.Path]::DirectorySeparatorChar, [StringComparison]::OrdinalIgnoreCase)) {
+    throw 'Release output must be a child of the artifacts directory.'
+}
+if (Test-Path -LiteralPath $outputRoot) {
+    throw "Release output '$outputRoot' already exists."
+}
+
+New-Item -ItemType Directory -Path $outputRoot | Out-Null
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+
+function New-DirectoryArchive {
+    param(
+        [Parameter(Mandatory = $true)]
+        [string] $Source,
+        [Parameter(Mandatory = $true)]
+        [string] $Destination
+    )
+
+    if (-not (Test-Path -LiteralPath $Source -PathType Container)) {
+        throw "Archive source '$Source' does not exist."
+    }
+    if (Test-Path -LiteralPath $Destination) {
+        throw "Archive destination '$Destination' already exists."
+    }
+
+    [IO.Compression.ZipFile]::CreateFromDirectory(
+        $Source,
+        $Destination,
+        [IO.Compression.CompressionLevel]::Optimal,
+        $true)
+}
+
+$expectedPackages = @(
+    'OpenGameAgent.Kernel',
+    'OpenGameAgent',
+    'OpenGameAgent.Persistence',
+    'OpenGameAgent.Providers.OpenAICompatible',
+    'OpenGameAgent.Providers.MediaHttp',
+    'OpenGameAgent.Client'
+)
+$nugetRoot = Join-Path $artifactsRoot 'nuget'
+foreach ($packageId in $expectedPackages) {
+    $name = "$packageId.$Version.nupkg"
+    $source = Join-Path $nugetRoot $name
+    if (-not (Test-Path -LiteralPath $source -PathType Leaf)) {
+        throw "Release package '$name' is missing."
+    }
+    Copy-Item -LiteralPath $source -Destination (Join-Path $outputRoot $name)
+}
+
+$godotSource = Join-Path $artifactsRoot 'godot\open-game-agent-godot'
+$unitySource = Join-Path $artifactsRoot 'unity\com.opengameagent.runtime'
+New-DirectoryArchive -Source $godotSource -Destination (Join-Path $outputRoot "OpenGameAgent.Godot-$Version.zip")
+New-DirectoryArchive -Source $unitySource -Destination (Join-Path $outputRoot "OpenGameAgent.Unity-$Version.zip")
+
+$serverSource = Join-Path $artifactsRoot 'server'
+$serverBundleName = "OpenGameAgent.Server-$Version-portable"
+$serverStage = Join-Path $outputRoot $serverBundleName
+if (-not $serverStage.StartsWith($outputRoot + [IO.Path]::DirectorySeparatorChar, [StringComparison]::OrdinalIgnoreCase)) {
+    throw 'Server staging path is unsafe.'
+}
+New-Item -ItemType Directory -Path $serverStage | Out-Null
+$serverFiles = @(
+    'appsettings.json',
+    'OpenGameAgent.Kernel.dll',
+    'OpenGameAgent.dll',
+    'OpenGameAgent.Persistence.dll',
+    'OpenGameAgent.Providers.OpenAICompatible.dll',
+    'OpenGameAgent.Server.deps.json',
+    'OpenGameAgent.Server.dll',
+    'OpenGameAgent.Server.runtimeconfig.json'
+)
+foreach ($relative in $serverFiles) {
+    $source = Join-Path $serverSource $relative
+    if (-not (Test-Path -LiteralPath $source -PathType Leaf)) {
+        throw "Portable server file '$relative' is missing."
+    }
+    Copy-Item -LiteralPath $source -Destination (Join-Path $serverStage $relative)
+}
+Copy-Item -LiteralPath (Join-Path $repositoryRoot 'LICENSE') -Destination (Join-Path $serverStage 'LICENSE')
+Copy-Item -LiteralPath (Join-Path $repositoryRoot 'docs\deployment-and-security.md') -Destination (Join-Path $serverStage 'README.md')
+New-DirectoryArchive -Source $serverStage -Destination (Join-Path $outputRoot "$serverBundleName.zip")
+Remove-Item -LiteralPath $serverStage -Recurse -Force
+
+$changelog = Get-Content -LiteralPath (Join-Path $repositoryRoot 'CHANGELOG.md') -Raw
+$escapedVersion = [regex]::Escape($Version)
+$match = [regex]::Match($changelog, "(?ms)^##\s+$escapedVersion\s*\r?\n(?<body>.*?)(?=^##\s+|\z)")
+if (-not $match.Success) {
+    throw "CHANGELOG.md does not contain version '$Version'."
+}
+$releaseNotes = @(
+    "# OpenGameAgent v$Version",
+    '',
+    $match.Groups['body'].Value.Trim(),
+    '',
+    '## Install',
+    '',
+    '```bash',
+    "dotnet add package OpenGameAgent --version $Version",
+    '```',
+    '',
+    'Use the versioned Godot or Unity archive below for engine integration. The portable server archive runs with `dotnet OpenGameAgent.Server.dll` on a .NET 8 host.',
+    '',
+    'This is an alpha release. Public APIs can change before 1.0.'
+) -join [Environment]::NewLine
+$releaseNotes | Set-Content -LiteralPath (Join-Path $outputRoot 'RELEASE_NOTES.md') -Encoding utf8NoBOM
+
+$downloadAssets = Get-ChildItem -LiteralPath $outputRoot -File |
+    Where-Object Name -ne 'RELEASE_NOTES.md' |
+    Sort-Object Name
+$checksumLines = foreach ($asset in $downloadAssets) {
+    $hash = (Get-FileHash -LiteralPath $asset.FullName -Algorithm SHA256).Hash.ToLowerInvariant()
+    "$hash  $($asset.Name)"
+}
+$checksumLines | Set-Content -LiteralPath (Join-Path $outputRoot 'SHA256SUMS.txt') -Encoding utf8NoBOM
+
+Write-Output $outputRoot