perf(save): encode detached snapshots and expose phase timings

.gitea/workflows/publish-nuget.yml

@@ -0,0 +1,123 @@
+name: Publish NuGet packages
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    env:
+      NUGET_AUTH_TOKEN: ${{ secrets.SHRINKSDK_PACKAGE_TOKEN }}
+      DOTNET_SYSTEM_GLOBALIZATION_INVARIANT: '1'
+      DOTNET_CLI_TELEMETRY_OPTOUT: '1'
+      LD_LIBRARY_PATH: /opt/dotnet-libs/usr/lib/x86_64-linux-gnu
+      SSL_CERT_FILE: /opt/ca-certificates.crt
+    steps:
+      - name: Fetch exact tagged source
+        env:
+          GITEA_REF: ${{ gitea.ref }}
+          GITEA_REPOSITORY: ${{ gitea.repository }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          tag="${GITEA_REF#refs/tags/}"
+          case "$tag" in
+            v[0-9]*) ;;
+            *) echo "Expected a version tag ref, got: $GITEA_REF" >&2; exit 1 ;;
+          esac
+          export SHRINKSDK_ARCHIVE_URL="https://git.crash.work/${GITEA_REPOSITORY}/archive/${tag}.tar.gz"
+          node --input-type=module <<'NODE'
+          import { writeFile } from 'node:fs/promises';
+
+          const response = await fetch(process.env.SHRINKSDK_ARCHIVE_URL);
+          if (!response.ok) {
+            throw new Error(`Release archive download failed: ${response.status} ${response.statusText}`);
+          }
+          await writeFile('release.tar.gz', new Uint8Array(await response.arrayBuffer()));
+          NODE
+          mkdir release
+          tar -xzf release.tar.gz --strip-components=1 -C release
+          rm -f release.tar.gz
+          printf '%s' "$tag" > release/.shrink-sdk-release-tag
+
+      - name: Install .NET 8 SDK
+        shell: bash
+        run: |
+          set -euo pipefail
+          node --input-type=module <<'NODE'
+          import { writeFile } from 'node:fs/promises';
+          import { rootCertificates } from 'node:tls';
+
+          await writeFile('/opt/ca-certificates.crt', rootCertificates.join('\n'));
+
+          const metadataResponse = await fetch('https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/8.0/releases.json');
+          if (!metadataResponse.ok) throw new Error(`Release metadata download failed: ${metadataResponse.status}`);
+          const metadata = await metadataResponse.json();
+          const sdkVersion = metadata['latest-sdk'];
+          const release = metadata.releases.find(item => item.sdk?.version === sdkVersion);
+          const file = release?.sdk?.files?.find(item => item.rid === 'linux-x64' && item.name.endsWith('.tar.gz'));
+          if (!file) throw new Error(`Linux x64 SDK archive not found for ${sdkVersion}`);
+          const archiveResponse = await fetch(file.url);
+          if (!archiveResponse.ok) throw new Error(`SDK download failed: ${archiveResponse.status}`);
+          await writeFile('/tmp/dotnet-sdk.tar.gz', new Uint8Array(await archiveResponse.arrayBuffer()));
+
+          const poolUrl = 'https://deb.debian.org/debian-security/pool/updates/main/o/openssl/';
+          const poolResponse = await fetch(poolUrl);
+          if (!poolResponse.ok) throw new Error(`OpenSSL package index download failed: ${poolResponse.status}`);
+          const poolIndex = await poolResponse.text();
+          const packages = [...poolIndex.matchAll(/href="(libssl3_[^"]+_amd64\.deb)"/g)].map(match => match[1]).sort();
+          const packageName = packages.at(-1);
+          if (!packageName) throw new Error('Debian libssl3 package was not found');
+          const packageResponse = await fetch(poolUrl + packageName);
+          if (!packageResponse.ok) throw new Error(`OpenSSL package download failed: ${packageResponse.status}`);
+          await writeFile('/tmp/libssl3.deb', new Uint8Array(await packageResponse.arrayBuffer()));
+          NODE
+          mkdir -p /opt/dotnet
+          tar -xzf /tmp/dotnet-sdk.tar.gz -C /opt/dotnet
+          mkdir -p /opt/dotnet-libs
+          dpkg-deb -x /tmp/libssl3.deb /opt/dotnet-libs
+          rm -f /tmp/dotnet-sdk.tar.gz
+          rm -f /tmp/libssl3.deb
+          /opt/dotnet/dotnet --info
+
+      - name: Validate, pack and publish
+        shell: bash
+        run: |
+          set -euo pipefail
+          : "${NUGET_AUTH_TOKEN:?SHRINKSDK_PACKAGE_TOKEN is required}"
+          export PATH="/opt/dotnet:$PATH"
+          cd release
+          tag="$(cat .shrink-sdk-release-tag)"
+          projects=()
+          if [[ -d DotNet~ ]]; then
+            while IFS= read -r -d '' project; do projects+=("$project"); done < <(find DotNet~ -type f -name '*.csproj' -print0)
+          fi
+          if [[ -d Godot~ ]]; then
+            while IFS= read -r -d '' project; do projects+=("$project"); done < <(find Godot~ -type f -name '*.csproj' -print0)
+          fi
+          if [[ "${#projects[@]}" -eq 0 ]]; then
+            while IFS= read -r -d '' project; do projects+=("$project"); done < <(find . -maxdepth 1 -type f -name '*.csproj' -print0)
+          fi
+          test "${#projects[@]}" -gt 0
+          if [[ -f package.json ]]; then
+            version="$(node -p "require('./package.json').version")"
+          else
+            version="$(dotnet msbuild "${projects[0]}" -getProperty:Version -nologo)"
+          fi
+          test "$tag" = "v$version"
+          mkdir -p packages
+          for project in "${projects[@]}"; do
+            dotnet restore "$project" --configfile NuGet.Config
+            dotnet pack "$project" --configuration Release --no-restore --output "$PWD/packages" --include-symbols --include-source
+          done
+          find packages -maxdepth 1 -name '*.nupkg' -type f | grep -q .
+          dotnet nuget push 'packages/*.nupkg' --api-key "$NUGET_AUTH_TOKEN" --source https://git.crash.work/api/packages/ShrinkSDK/nuget/index.json --skip-duplicate
+          if compgen -G 'packages/*.snupkg' > /dev/null; then
+            dotnet nuget push 'packages/*.snupkg' --api-key "$NUGET_AUTH_TOKEN" --source https://git.crash.work/api/packages/ShrinkSDK/nuget/index.json --skip-duplicate
+          fi

.gitignore

@@ -8,3 +8,11 @@
 /Tools~/**/[Oo]bj/
 *.user
 *.DotSettings.user
+/DotNet~/**/[Bb]in/
+/DotNet~/**/[Oo]bj/
+/Godot~/**/[Bb]in/
+/Godot~/**/[Oo]bj/
+/artifacts/
+/packages/
+!DotNet~/**/*.csproj
+!Godot~/**/*.csproj

.npmignore

@@ -6,3 +6,9 @@ Tools~/
 *.sln
 *.user
 *.DotSettings.user
+DotNet~/
+Godot~/
+NuGet.Config
+Directory.Build.props
+NuGet.Config.meta
+Directory.Build.props.meta

Directory.Build.props

@@ -0,0 +1,13 @@
+<Project>
+  <PropertyGroup>
+    <LangVersion>latest</LangVersion>
+    <Nullable>enable</Nullable>
+    <Deterministic>true</Deterministic>
+    <ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
+    <Authors>ShrinkSDK</Authors>
+    <Company>ShrinkSDK</Company>
+    <RepositoryUrl>https://git.crash.work/ShrinkSDK</RepositoryUrl>
+    <IncludeSymbols>true</IncludeSymbols>
+    <SymbolPackageFormat>snupkg</SymbolPackageFormat>
+  </PropertyGroup>
+</Project>

Directory.Build.props.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 5e806df0724397542b78a8347188b8bd
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

DotNet~/Runtime/ShrinkDataSaverRuntime.cs

@@ -0,0 +1,43 @@
+#nullable enable
+
+using System.IO;
+using Cysharp.Threading.Tasks;
+using ShrinkSDK.Runtime;
+
+namespace ShrinkDataSaver;
+
+public sealed class ShrinkDataSaverRuntimeConfig
+{
+    public string? RootPath { get; set; }
+    public string SaveFileExtension { get; set; } = ".sav";
+    public string SettingsFileName { get; set; } = "settings.json";
+    public int CurrentSaveVersion { get; set; } = 1;
+    public int MaxSlots { get; set; } = 3;
+    public float SettingsWriteDebounceSeconds { get; set; } = 0.35f;
+    public bool DontDestroyOnLoadDriver { get; set; }
+}
+
+public static class ShrinkDataSaverRuntime
+{
+    public static bool IsInitialized { get; private set; }
+
+    public static void Initialize(ShrinkDataSaverRuntimeConfig? config = null)
+    {
+        if (IsInitialized) return;
+        config ??= new ShrinkDataSaverRuntimeConfig();
+        var root = string.IsNullOrWhiteSpace(config.RootPath)
+            ? ShrinkRuntimeServices.Paths.PersistentDataPath
+            : config.RootPath!;
+        Directory.CreateDirectory(root);
+        var storage = new LocalStorageProvider(root);
+        ShrinkDataSaverPlatform.SettingsWriteDebounceSeconds = config.SettingsWriteDebounceSeconds;
+        ShrinkDataSaverPlatform.MaxSlots = config.MaxSlots;
+        ShrinkSettings.Initialize(storage, Path.Combine(root, config.SettingsFileName));
+        ShrinkSave.Initialize(storage, Path.Combine(root, "saves"), config.SaveFileExtension,
+            config.CurrentSaveVersion);
+        ShrinkSettings.LoadAsync().Forget();
+        IsInitialized = true;
+        ShrinkRuntimeServices.Logger.Log(ShrinkLogLevel.Information,
+            $"[ShrinkDataSaver] Runtime initialized. Root: {root}");
+    }
+}

DotNet~/ShrinkSDK.DataSaver.csproj

@@ -0,0 +1,29 @@
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>netstandard2.1</TargetFramework>
+    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
+    <AssemblyName>ShrinkDataSaver.Runtime</AssemblyName>
+    <RootNamespace>ShrinkDataSaver</RootNamespace>
+    <PackageId>ShrinkSDK.DataSaver</PackageId>
+    <Version>2.4.0</Version>
+    <Description>ShrinkSDK engine-neutral versioned save and settings runtime.</Description>
+    <ShrinkCodeGenEnabled>false</ShrinkCodeGenEnabled>
+    <Nullable>disable</Nullable>
+  </PropertyGroup>
+  <ItemGroup>
+    <Compile Include="Runtime\ShrinkDataSaverRuntime.cs" />
+    <Compile Include="..\Runtime\AssemblyInfo.cs" />
+    <Compile Include="..\Runtime\DataSerializer.cs" />
+    <Compile Include="..\Runtime\IStorageProvider.cs" />
+    <Compile Include="..\Runtime\LocalStorageProvider.cs" />
+    <Compile Include="..\Runtime\MigrationChain.cs" />
+    <Compile Include="..\Runtime\SaveEncryptor.cs" />
+    <Compile Include="..\Runtime\SaveTypes.cs" />
+    <Compile Include="..\Runtime\ShrinkDataSaverPlatform.cs" />
+    <Compile Include="..\Runtime\ShrinkSave.cs" />
+    <Compile Include="..\Runtime\ShrinkSettings.cs" />
+    <PackageReference Include="Newtonsoft.Json" Version="13.0.3" />
+    <PackageReference Include="UniTask" Version="2.5.10" />
+    <PackageReference Include="ShrinkSDK.Runtime.Abstractions" Version="0.1.0" />
+  </ItemGroup>
+</Project>

NuGet.Config

@@ -0,0 +1,8 @@
+<?xml version="1.0" encoding="utf-8"?>
+<configuration>
+  <packageSources>
+    <clear />
+    <add key="ShrinkSDK" value="https://git.crash.work/api/packages/ShrinkSDK/nuget/index.json" />
+    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
+  </packageSources>
+</configuration>

NuGet.Config.meta

@@ -0,0 +1,32 @@
+fileFormatVersion: 2
+guid: 8d396317cc7d3294683c90786f2b3289
+PluginImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  iconMap: {}
+  executionOrder: {}
+  defineConstraints: []
+  isPreloaded: 0
+  isOverridable: 0
+  isExplicitlyReferenced: 0
+  validateReferences: 1
+  platformData:
+  - first:
+      Any: 
+    second:
+      enabled: 0
+      settings: {}
+  - first:
+      Editor: Editor
+    second:
+      enabled: 0
+      settings:
+        DefaultValueInitialized: true
+  - first:
+      Windows Store Apps: WindowsStoreApps
+    second:
+      enabled: 1
+      settings: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

README.md

@@ -1,6 +1,8 @@
 # ShrinkDataSaver
 
-一个为 Unity C# 项目设计的模块化存档与设置管理系统。支持多存档槽、链式版本迁移、可选 AES-256 加密、关键模块保护、跨模块只读查询，以及完整的事件驱动架构。
+一个可用于 Unity、Godot 和普通 .NET 宿主的模块化存档与设置管理系统。支持多存档槽、链式版本迁移、可选 AES-256 加密、关键模块保护、跨模块只读查询，以及完整的事件驱动架构。
+
+Godot 和普通 .NET 项目安装 `ShrinkSDK.DataSaver`；可打包源码位于 `DotNet~`，持久化路径与生命周期由宿主平台服务注入。
 
 ## ✨ 特性概览
 
@@ -540,3 +542,13 @@ await ShrinkSave.LoadSlotAsync(slotIndex, key);
 ## 📄 License
 
 [MIT](LICENSE)
+
+## 可复用能力
+
+<!-- shrink:capabilities -->
+Capability: 模块化存档、槽位、设置、迁移、加密和损坏备份恢复
+Aliases: 存储 存档 保存 读档 设置 持久化 save
+Limits: 模块负责采集一致状态；后台不得读取 Unity 对象；不会自动保存任意游戏字段
+Extension: 存档模块注册、序列化器、迁移链与平台路径服务
+Evidence: [ShrinkSave](Runtime/ShrinkSave.cs); [ShrinkDataSaverRuntime](DotNet~/Runtime/ShrinkDataSaverRuntime.cs)
+<!-- /shrink:capabilities -->

Runtime/LocalStorageProvider.cs

@@ -108,8 +108,8 @@ namespace ShrinkDataSaver
             }
         }
 
-        public UniTask<bool> ExistsAsync(string path, CancellationToken ct = default) =>
+        public async UniTask<bool> ExistsAsync(string path, CancellationToken ct = default) =>
-            Task.Run(() => File.Exists(Resolve(path)), ct).AsUniTask();
+            await Task.Run(() => File.Exists(Resolve(path)), ct);
 
         public async UniTask DeleteAsync(string path, CancellationToken ct = default)
         {

Runtime/SaveTypes.cs

@@ -59,8 +59,21 @@ namespace ShrinkDataSaver
     }
 
 
+    public sealed class SavePhaseTimings
+    {
+        public double CaptureMilliseconds { get; internal set; }
+        public double EncodeMilliseconds { get; internal set; }
+        public double EncryptMilliseconds { get; internal set; }
+        public double WriteMilliseconds { get; internal set; }
+        public long EncodedBytes { get; internal set; }
+    }
+
     public class SaveOptions
     {
+        /// <summary>Only the detached JToken snapshot is encoded off-thread; module capture stays on the caller thread.</summary>
+        public bool EncodeInBackground = false;
+        public bool CollectTimings = false;
+        public SavePhaseTimings LastTimings { get; internal set; }
         public string SlotName = "New Save";
         public bool CaptureScreenshot = false;
 #if UNITY_5_3_OR_NEWER

Runtime/ShrinkSave.cs

@@ -1,6 +1,8 @@
 using System;
 using System.Collections.Generic;
 using System.IO;
+using System.Diagnostics;
+using System.Threading.Tasks;
 using System.Threading;
 using Cysharp.Threading.Tasks;
 using Newtonsoft.Json.Linq;
@@ -183,6 +185,14 @@ namespace ShrinkDataSaver
         {
             options ??= new SaveOptions();
             ValidateSlotIndex(slotIndex);
+            ct.ThrowIfCancellationRequested();
+            var timings = options.CollectTimings ? new SavePhaseTimings() : null;
+            options.LastTimings = timings;
+            var captureStarted = Stopwatch.GetTimestamp();
+            var encrypt = options.Encrypt;
+            var encryptionKey = options.EncryptionKey;
+            var encodeInBackground = options.EncodeInBackground;
+            var storage = _storage;
 
             var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
             OnSaveStarted?.Invoke(new SaveStartedEventArgs { SlotIndex = slotIndex, Timestamp = timestamp });
@@ -198,7 +208,7 @@ namespace ShrinkDataSaver
                         SaveVersion = _currentSaveVersion,
                         LastModified = timestamp,
                         PlaytimeSeconds = GetCurrentPlaytime(),
-                        IsEncrypted = options.Encrypt
+                        IsEncrypted = encrypt
                     }
                 };
 
@@ -233,24 +243,35 @@ namespace ShrinkDataSaver
                     }
                 }
 
-                if (options.Encrypt)
+                if (timings != null) timings.CaptureMilliseconds = PhaseElapsed(captureStarted);
+                ct.ThrowIfCancellationRequested();
+                // Modules have been materialized as private JSON tokens; the worker never touches providers or engine objects.
+                byte[] Encode()
                 {
-                    if (string.IsNullOrEmpty(options.EncryptionKey))
+                    ct.ThrowIfCancellationRequested();
+                    var stage = Stopwatch.GetTimestamp();
+                    if (encrypt)
                     {
-                        throw new ArgumentException("EncryptionKey missing.");
+                        if (string.IsNullOrEmpty(encryptionKey)) throw new ArgumentException("EncryptionKey missing.");
+                        var modulesBytes = DataSerializer.Serialize(modulesDict);
+                        if (timings != null) timings.EncodeMilliseconds += PhaseElapsed(stage);
+                        stage = Stopwatch.GetTimestamp();
+                        var encryptedBytes = SaveEncryptor.Encrypt(modulesBytes, encryptionKey);
+                        if (timings != null) timings.EncryptMilliseconds = PhaseElapsed(stage);
+                        packet.EncryptedModules = Convert.ToBase64String(encryptedBytes);
                     }
-
+                    else packet.Modules = modulesDict;
-                    var modulesBytes = DataSerializer.Serialize(modulesDict);
+                    ct.ThrowIfCancellationRequested();
-                    var encryptedBytes = SaveEncryptor.Encrypt(modulesBytes, options.EncryptionKey);
+                    stage = Stopwatch.GetTimestamp();
-                    packet.EncryptedModules = Convert.ToBase64String(encryptedBytes);
+                    var bytes = DataSerializer.Serialize(packet);
+                    if (timings != null) { timings.EncodeMilliseconds += PhaseElapsed(stage); timings.EncodedBytes = bytes.Length; }
+                    return bytes;
                 }
-                else
+                var finalBytes = encodeInBackground ? await Task.Run(Encode, ct) : Encode();
-                {
+                ct.ThrowIfCancellationRequested();
-                    packet.Modules = modulesDict;
+                var writeStarted = Stopwatch.GetTimestamp();
-                }
+                await storage.WriteAsync(SlotPath(slotIndex), finalBytes, ct);
-
+                if (timings != null) timings.WriteMilliseconds = PhaseElapsed(writeStarted);
-                var finalBytes = DataSerializer.Serialize(packet);
-                await _storage.WriteAsync(SlotPath(slotIndex), finalBytes, ct);
 
                 OnSaveCompleted?.Invoke(new SaveCompletedEventArgs
                 {
@@ -271,6 +292,8 @@ namespace ShrinkDataSaver
             }
         }
 
+        private static double PhaseElapsed(long started) => (Stopwatch.GetTimestamp() - started) * 1000d / Stopwatch.Frequency;
+
         public static async UniTask LoadSlotAsync(int slotIndex, string decryptionKey = null, CancellationToken ct = default)
         {
             var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds();

package.json

@@ -1,6 +1,6 @@
 {
   "name": "com.cneicy.shrink-datasaver",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "displayName": "ShrinkDataSaver",
   "description": "模块化 Unity 存档与设置管理系统，支持多槽位、链式版本迁移、AES-256 加密、关键模块保护、跨模块查询与事件驱动架构。",
   "unity": "2022.3",