feat(startup): 支持等待 ContextLoader 启动

.gitea/workflows/publish.yml

@@ -15,22 +15,39 @@ jobs:
     env:
       NODE_AUTH_TOKEN: ${{ secrets.SHRINKSDK_PACKAGE_TOKEN }}
     steps:
-      - name: Fetch tagged revision
+      - name: Fetch exact tagged release archive
+        env:
+          GITEA_REF: ${{ gitea.ref }}
         shell: bash
         run: |
           set -eu
-          ref="${{ gitea.sha }}"
-          test -n "$ref"
-          git init .
-          git remote add origin "https://git.crash.work/ShrinkSDK/ShrinkContext.AppAdapter.git"
-          git fetch --depth=1 origin "$ref"
-          git checkout --detach FETCH_HEAD
+          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/ShrinkSDK/ShrinkContext.AppAdapter/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: Validate immutable release version
         shell: bash
         run: |
           set -eu
-          tag="$(git describe --exact-match --tags HEAD)"
+          cd release
+          tag="$(cat .shrink-sdk-release-tag)"
           version="$(node -p "require('./package.json').version")"
           test "$tag" = "v$version"
           npm pack --dry-run
@@ -40,10 +57,11 @@ jobs:
         run: |
           set -eu
           : "${NODE_AUTH_TOKEN:?SHRINKSDK_PACKAGE_TOKEN is required}"
+          cd release
           npmrc="$HOME/.npmrc"
           cleanup() { rm -f "$npmrc"; }
           trap cleanup EXIT
           printf '%s\n' \
             'registry=https://git.crash.work/api/packages/ShrinkSDK/npm/' \
             '//git.crash.work/api/packages/ShrinkSDK/npm/:_authToken=${NODE_AUTH_TOKEN}' > "$npmrc"
-          npm publish --registry=https://git.crash.work/api/packages/ShrinkSDK/npm/
+          npm publish --registry=https://git.crash.work/api/packages/ShrinkSDK/npm/

.gitea/workflows/unity-verify.yml

@@ -26,12 +26,17 @@ jobs:
         shell: bash
         run: |
           set -eu
+          machine_id_file="/root/.local/share/unity3d/Unity/.machine-id"
+          if test -s "$machine_id_file"; then
+            cat "$machine_id_file" > /etc/machine-id
+            echo "Unity machine identity restored"
+          fi
+          git config --global url."https://ghfast.top/https://github.com/".insteadOf "https://github.com/"
           unity_bin="$(command -v unity-editor || command -v unity || command -v Unity || true)"
           test -n "$unity_bin"
           "$unity_bin" \
             -batchmode \
             -nographics \
-            -quit \
             -projectPath "$PWD/Development~/UnityProject" \
             -runTests \
             -testPlatform EditMode \

CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+本文件记录 `ShrinkContext.AppAdapter` 的包内变更。
+
+## [0.1.4] - 2026-08-28
+
+### Added
+
+- `ShrinkAppLoaderBootstrapper.WaitUntilStartedAsync(CancellationToken)` 支持多个调用方并发等待 ContextLoader 完成启动。
+- `ShrinkAppLoaderBootstrapper.StartError` 暴露启动失败异常。
+
+### Changed
+
+- ContextLoader 启动失败时发布 `ShrinkAppStartFailedEvent`，等待方收到原始异常，不再依赖轮询。
+- 精确依赖 `ShrinkApp.Core 0.1.3`。

CHANGELOG.md.meta

@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: b1937438081846a4ae5ca6f747953987
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 

Development~/UnityProject/Packages/manifest.json

@@ -10,6 +10,16 @@
   ],
   "dependencies": {
     "com.unity.test-framework": "1.1.33",
-    "com.cneicy.shrink-context-app-adapter": "file:../../.."
-  }
+    "com.cneicy.shrink-context-app-adapter": "file:../../..",
+    "com.cneicy.shrink-app-starter-basic": "0.2.1",
+    "com.cneicy.shrink-command": "0.2.0",
+    "com.cneicy.shrink-command-integration-app": "0.1.2",
+    "com.cneicy.shrink-datasaver-integration-app": "0.1.2",
+    "com.cneicy.shrink-network": "0.2.1",
+    "com.cneicy.shrink-network-integration-app": "0.1.2",
+    "com.cysharp.unitask": "https://github.com/Cysharp/UniTask.git?path=src/UniTask/Assets/Plugins/UniTask#7c0f199fe0d3fc528024488ccd671e6c7b27745b"
+  },
+  "testables": [
+    "com.cneicy.shrink-context-app-adapter"
+  ]
 }

Editor/ShrinkContextDiagnosticsWindow.cs

@@ -28,10 +28,10 @@ namespace ShrinkContext.AppAdapter.Editor
         private ShrinkContextBenchmarkReport? _benchmarkReport;
         private string? _benchmarkError;
 
-        [MenuItem("ShrinkSDK/Cordis/诊断与组合")]
+        [MenuItem("ShrinkSDK/上下文/诊断与组合")]
         public static void ShowWindow()
         {
-            var window = GetWindow<ShrinkContextDiagnosticsWindow>("Cordis Diagnostics");
+            var window = GetWindow<ShrinkContextDiagnosticsWindow>("Context 诊断与组合");
             window.minSize = new Vector2(720f, 520f);
         }
 
@@ -167,7 +167,7 @@ namespace ShrinkContext.AppAdapter.Editor
             if (_profile == null)
             {
                 EditorGUILayout.HelpBox(
-                    "未选择 Composition Profile。可通过 Assets/Create/ShrinkSDK/Cordis/Composition Profile 创建。",
+                    "未选择组合配置。可通过 Assets/Create/ShrinkSDK/上下文/组合配置创建。",
                     MessageType.Info);
                 return;
             }

README.md

@@ -10,18 +10,24 @@ ShrinkApp ↔ ShrinkContext 的桥接层：提供当前默认的 ContextLoader
 | `ShrinkAppLoaderHost` | 加载器驱动的 ShrinkApp 宿主：发现安装器（注入覆盖可测试）、应用声明式组合、经 `ShrinkContextLoader` 增量协调、运行中按模块开关 |
 | `ShrinkAppCompositionProfile` | ScriptableObject/JSON 组合文档：描述条目启用、显式排除、isolate 与 intercept；组件工厂仍由代码目录注册 |
 | `ShrinkAppLoaderBootstrapper` | `hostingMode == ContextLoader` 时自动创建常驻宿主，应用 `Resources/ShrinkAppComposition`，并把服务容器接回 `ShrinkApp.Services` |
-| `ShrinkContextDiagnosticsWindow` | `ShrinkSDK/Cordis/诊断与组合`：查看运行时 fiber/依赖/事务、编辑 Profile JSON、读取可选的 ModFramework 常驻统计并运行容量基准 |
+| `ShrinkContextDiagnosticsWindow` | `ShrinkSDK/上下文/诊断与组合`：查看运行时 fiber/依赖/事务、编辑 Profile JSON、读取可选的 ModFramework 常驻统计并运行容量基准 |
 
 ## 启用方式
 
 `ShrinkAppSettings.hostingMode` 设为 `ContextLoader`（Inspector 或资产字段）。经典项目默认 `ClassicHost`，行为零变化。
 
 ```csharp
+// 场景业务等待宿主完成；失败时直接收到启动异常。
+await ShrinkAppLoaderBootstrapper.WaitUntilStartedAsync(cancellationToken);
+
 // 运行中按模块开关（宿主与其余模块不重启）
 var host = ShrinkAppLoaderBootstrapper.Instance!.Host;
 await host.SetModuleDisabledAsync("shrink.network", true);
 ```
 
+`ShrinkAppLoaderBootstrapper.StartError` 保留最近一次启动异常；启动失败同时发布
+`ShrinkAppStartFailedEvent`。调用方不需要轮询 `Host.IsRunning`。
+
 ## 声明式组合
 
 默认资源名为 `Assets/Resources/ShrinkAppComposition.asset`。组合根先用代码注册安装器或原生组件工厂，Bootstrapper 再应用 Profile；配置文件不能通过类型名反射实例化任意组件。

Runtime/ShrinkAppCompositionProfile.cs

@@ -242,7 +242,7 @@ namespace ShrinkContext.AppAdapter
         }
     }
 
-    [CreateAssetMenu(fileName = DefaultResourceName, menuName = "ShrinkSDK/Cordis/Composition Profile")]
+    [CreateAssetMenu(fileName = DefaultResourceName, menuName = "ShrinkSDK/上下文/组合配置")]
     public sealed class ShrinkAppCompositionProfile : ScriptableObject
     {
         public const string DefaultResourceName = "ShrinkAppComposition";

Runtime/ShrinkAppLoaderBootstrapper.cs

@@ -1,6 +1,9 @@
 #nullable enable
+using System;
+using System.Threading;
 using Cysharp.Threading.Tasks;
 using ShrinkApp;
+using ShrinkEventBus;
 using UnityEngine;
 
 namespace ShrinkContext.AppAdapter
@@ -14,6 +17,7 @@ namespace ShrinkContext.AppAdapter
     public sealed class ShrinkAppLoaderBootstrapper : MonoBehaviour
     {
         private static ShrinkAppLoaderBootstrapper? _instance;
+        private static UniTaskCompletionSource _startupCompletion = new();
 
         /// <summary>
         /// Starter/组合包在 SubsystemRegistration 阶段设置的默认装配表。
@@ -22,9 +26,43 @@ namespace ShrinkContext.AppAdapter
         public static System.Action<ShrinkAppLoaderHost>? DefaultComposition { get; set; }
 
         public static ShrinkAppLoaderBootstrapper? Instance => _instance;
+        public static Exception? StartError { get; private set; }
 
         public ShrinkAppLoaderHost Host { get; private set; } = null!;
 
+        /// <summary>
+        /// 等待 ContextLoader 宿主完成启动。支持多个并发等待者；宿主失败时以原始异常结束。
+        /// </summary>
+        public static async UniTask WaitUntilStartedAsync(CancellationToken cancellationToken = default)
+        {
+            if (_instance?.Host?.IsRunning == true)
+                return;
+            if (StartError != null)
+                throw StartError;
+            if (ShrinkAppSettings.Instance.hostingMode != ShrinkAppHostingMode.ContextLoader)
+            {
+                throw new InvalidOperationException(
+                    "ShrinkAppLoaderBootstrapper requires ShrinkAppHostingMode.ContextLoader.");
+            }
+
+            var task = _startupCompletion.Task;
+            if (cancellationToken.CanBeCanceled)
+                await task.AttachExternalCancellation(cancellationToken);
+            else
+                await task;
+
+            if (StartError != null)
+                throw StartError;
+        }
+
+        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
+        private static void ResetStaticState()
+        {
+            _instance = null;
+            StartError = null;
+            _startupCompletion = new UniTaskCompletionSource();
+        }
+
         [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
         private static void AutoBootstrap()
         {
@@ -45,17 +83,39 @@ namespace ShrinkContext.AppAdapter
             }
 
             _instance = this;
-            Host = new ShrinkAppLoaderHost();
-            DefaultComposition?.Invoke(Host);
-            var profile = ShrinkAppCompositionProfile.LoadDefault();
-            if (profile != null)
-                Host.ApplyComposition(profile.ResolveDocument());
-            global::ShrinkApp.ShrinkApp.InitializeForExternalHost(Host.Services);
-            Host.StartAsync().Forget(ex =>
+            StartHostAsync().Forget();
+        }
+
+        private async UniTask StartHostAsync()
+        {
+            try
             {
+                Host = new ShrinkAppLoaderHost();
+                DefaultComposition?.Invoke(Host);
+                var profile = ShrinkAppCompositionProfile.LoadDefault();
+                if (profile != null)
+                    Host.ApplyComposition(profile.ResolveDocument());
+                global::ShrinkApp.ShrinkApp.InitializeForExternalHost(Host.Services);
+                await Host.StartAsync();
+                CompleteStartup(null);
+            }
+            catch (Exception ex)
+            {
+                CompleteStartup(ex);
+                EventBus.Post(new ShrinkAppStartFailedEvent
+                {
+                    ErrorMessage = ex.Message,
+                    FailedModuleId = string.Empty
+                });
                 Debug.LogException(ex);
                 Debug.LogError("[ShrinkApp.LoaderHost] 启动失败: " + ex.Message);
-            });
+            }
+        }
+
+        private static void CompleteStartup(Exception? error)
+        {
+            StartError = error;
+            _startupCompletion.TrySetResult();
         }
 
         private void OnDestroy()

Tests/ShrinkAppLoaderHostTests.cs

@@ -2,6 +2,7 @@
 using System;
 using System.Collections.Generic;
 using System.Linq;
+using System.Reflection;
 using Cysharp.Threading.Tasks;
 using NUnit.Framework;
 using ShrinkApp;
@@ -39,6 +40,8 @@ namespace ShrinkContext.AppAdapter.Tests
         [TearDown]
         public void TearDown()
         {
+            ResetBootstrapperState();
+            SetSharedSettings(null);
             if (_settings != null)
                 Object.DestroyImmediate(_settings);
         }
@@ -68,6 +71,33 @@ namespace ShrinkContext.AppAdapter.Tests
             CollectionAssert.AreEquivalent(new[] { "app.a", "app.b" }, probe.Value!.ModuleIds);
         }
 
+        [Test]
+        public void WaitUntilStartedAsync_AllConcurrentWaitersCompleteTogether()
+        {
+            PrepareBootstrapperWaitState();
+
+            var first = ShrinkAppLoaderBootstrapper.WaitUntilStartedAsync();
+            var second = ShrinkAppLoaderBootstrapper.WaitUntilStartedAsync();
+            CompleteBootstrapperStartup(null);
+
+            TestAwait.Run(UniTask.WhenAll(first, second));
+            Assert.IsNull(ShrinkAppLoaderBootstrapper.StartError);
+        }
+
+        [Test]
+        public void WaitUntilStartedAsync_PropagatesObservableStartupError()
+        {
+            PrepareBootstrapperWaitState();
+            var expected = new InvalidOperationException("test startup failure");
+            CompleteBootstrapperStartup(expected);
+
+            var actual = Assert.Throws<InvalidOperationException>(() =>
+                TestAwait.Run(ShrinkAppLoaderBootstrapper.WaitUntilStartedAsync()));
+
+            Assert.AreSame(expected, actual);
+            Assert.AreSame(expected, ShrinkAppLoaderBootstrapper.StartError);
+        }
+
         [Test]
         public void SetModuleDisabled_RetiresModuleAndDependents_EnableReloadsWithoutRestart()
         {
@@ -210,5 +240,36 @@ namespace ShrinkContext.AppAdapter.Tests
 
             public string Value { get; }
         }
+
+        private void PrepareBootstrapperWaitState()
+        {
+            ResetBootstrapperState();
+            _settings.hostingMode = ShrinkAppHostingMode.ContextLoader;
+            SetSharedSettings(_settings);
+        }
+
+        private static void CompleteBootstrapperStartup(Exception? error)
+        {
+            var method = typeof(ShrinkAppLoaderBootstrapper).GetMethod(
+                "CompleteStartup", BindingFlags.NonPublic | BindingFlags.Static);
+            Assert.IsNotNull(method);
+            method!.Invoke(null, new object?[] { error });
+        }
+
+        private static void ResetBootstrapperState()
+        {
+            var method = typeof(ShrinkAppLoaderBootstrapper).GetMethod(
+                "ResetStaticState", BindingFlags.NonPublic | BindingFlags.Static);
+            Assert.IsNotNull(method);
+            method!.Invoke(null, null);
+        }
+
+        private static void SetSharedSettings(ShrinkAppSettings? settings)
+        {
+            var property = typeof(ShrinkAppSettings).GetProperty(
+                nameof(ShrinkAppSettings.Instance), BindingFlags.Public | BindingFlags.Static);
+            Assert.IsNotNull(property);
+            property!.SetValue(null, settings);
+        }
     }
 }

package.json

@@ -1,13 +1,15 @@
 {
   "name": "com.cneicy.shrink-context-app-adapter",
-  "version": "0.1.0",
+  "version": "0.1.4",
   "displayName": "ShrinkContext - ShrinkApp Adapter",
   "description": "把现有 IShrinkAppModuleInstaller 包装为 ShrinkContext 组件：依赖缺失改为等待而非抛错，模块激活由响应式余效应驱动。",
   "unity": "2022.3",
   "dependencies": {
     "com.cneicy.shrink-context-core": "0.1.0",
-    "com.cneicy.shrink-app-core": "0.1.1",
-    "com.cysharp.unitask": "2.5.10"
+    "com.cneicy.shrink-app-core": "0.1.3",
+    "com.cneicy.shrink-eventbus": "2.0.0",
+    "com.cysharp.unitask": "2.5.10",
+    "com.unity.modules.jsonserialize": "1.0.0"
   },
   "keywords": [
     "context",
@@ -20,5 +22,6 @@
     "name": "cneicy",
     "url": "https://git.crash.work/ShrinkSDK"
   },
-  "documentationUrl": "https://git.crash.work/ShrinkSDK/ShrinkContext.AppAdapter"
+  "documentationUrl": "https://git.crash.work/ShrinkSDK/ShrinkContext.AppAdapter",
+  "changelogUrl": "https://git.crash.work/ShrinkSDK/ShrinkContext.AppAdapter/src/branch/main/CHANGELOG.md"
 }