feat(cordis): 接入上下文组合与模组事务热替换

2026-08-16 23:20:40 +08:00
commit ad256f109b
676 changed files with 52168 additions and 0 deletions
@@ -0,0 +1,62 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Cysharp.Threading.Tasks;
+using ShrinkApp;
+
+namespace ShrinkContext.AppAdapter
+{
+    /// <summary>
+    /// 把现有 <see cref="IShrinkAppModuleInstaller"/> 包装为 ShrinkContext 组件：
+    /// - inject 由 <c>DependsOn</c> 派生（模块依赖 → 模块键），依赖未就绪时安装器保持非活动等待，
+    ///   而不是像拓扑排序那样直接抛错；
+    /// - provide 发布模块键 <c>app.module.&lt;ModuleId&gt;</c>（安装器 Active 后对依赖者可见）；
+    /// - apply 依次执行 RegisterServices + InitializeAsync，config 必须传入 <see cref="ShrinkAppServices"/>。
+    ///
+    /// 已知边界（后续阶段补齐）：ShrinkAppServices 尚无注销能力，
+    /// 安装器卸载时不会移除已注册的服务；重新激活会重复执行 RegisterServices（同键覆盖）。
+    /// </summary>
+    public sealed class ShrinkAppInstallerComponent : IShrinkComponent
+    {
+        /// <summary>模块键前缀：依赖声明 <c>DependsOn = ["a"]</c> 映射为 <c>app.module.a</c>。</summary>
+        public const string ModuleKeyPrefix = "app.module.";
+
+        private readonly IShrinkAppModuleInstaller _installer;
+        private readonly ShrinkAppSettings? _settings;
+        private readonly string[] _inject;
+
+        public ShrinkAppInstallerComponent(IShrinkAppModuleInstaller installer, ShrinkAppSettings? settings = null)
+        {
+            _installer = installer ?? throw new ArgumentNullException(nameof(installer));
+            _settings = settings;
+            _inject = (installer.DependsOn ?? Array.Empty<string>())
+                .Where(id => !string.IsNullOrWhiteSpace(id))
+                .Select(id => ModuleKeyPrefix + id.Trim())
+                .ToArray();
+        }
+
+        public string Name => "app-installer:" + _installer.ModuleId;
+
+        public IReadOnlyList<string> Inject => _inject;
+
+        public IReadOnlyList<string> Provide => new[] { ModuleKeyPrefix + _installer.ModuleId };
+
+        public IShrinkAppModuleInstaller Installer => _installer;
+
+        public async UniTask ApplyAsync(ShrinkCtx ctx, object? config)
+        {
+            if (config is not ShrinkAppServices services)
+                throw new InvalidOperationException(
+                    $"ShrinkAppInstallerComponent '{_installer.ModuleId}' requires ShrinkAppServices as fiber config.");
+
+            // 先发布模块键再执行安装：装载期绑定对依赖者不可见（提供者须 Active），
+            // 供给冲突（重复 ModuleId）在安装器初始化之前即失败
+            ctx.Set(Provide[0], _installer.ModuleId);
+
+            var appContext = ShrinkAppContext.CreateStandalone(services, _settings);
+            _installer.RegisterServices(appContext);
+            await _installer.InitializeAsync(appContext);
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 9d8057e758d9edf46b18bd47145421c0
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,64 @@
+#nullable enable
+using Cysharp.Threading.Tasks;
+using ShrinkApp;
+using UnityEngine;
+
+namespace ShrinkContext.AppAdapter
+{
+    /// <summary>
+    /// ShrinkApp 加载器宿主的自动引导：
+    /// hostingMode == ContextLoader 时在 BeforeSceneLoad 创建常驻 GameObject 并启动 ShrinkAppLoaderHost，
+    /// 同时把服务容器接回 ShrinkApp 静态入口（InitializeForExternalHost），保证场景脚本照常访问 ShrinkApp.Services。
+    /// ClassicHost 模式下完全不动——经典路径零行为变化。
+    /// </summary>
+    public sealed class ShrinkAppLoaderBootstrapper : MonoBehaviour
+    {
+        private static ShrinkAppLoaderBootstrapper? _instance;
+
+        /// <summary>
+        /// Starter/组合包在 SubsystemRegistration 阶段设置的默认装配表。
+        /// AppAdapter 保持不依赖具体业务模块，组合根负责把原生组件挂到已发现的模块 id。
+        /// </summary>
+        public static System.Action<ShrinkAppLoaderHost>? DefaultComposition { get; set; }
+
+        public static ShrinkAppLoaderBootstrapper? Instance => _instance;
+
+        public ShrinkAppLoaderHost Host { get; private set; } = null!;
+
+        [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
+        private static void AutoBootstrap()
+        {
+            if (ShrinkAppSettings.Instance.hostingMode != ShrinkAppHostingMode.ContextLoader)
+                return;
+
+            var gameObject = new GameObject("ShrinkAppLoaderHost");
+            DontDestroyOnLoad(gameObject);
+            gameObject.AddComponent<ShrinkAppLoaderBootstrapper>();
+        }
+
+        private void Awake()
+        {
+            if (_instance != null && _instance != this)
+            {
+                Destroy(gameObject);
+                return;
+            }
+
+            _instance = this;
+            Host = new ShrinkAppLoaderHost();
+            DefaultComposition?.Invoke(Host);
+            global::ShrinkApp.ShrinkApp.InitializeForExternalHost(Host.Services);
+            Host.StartAsync().Forget(ex =>
+            {
+                Debug.LogException(ex);
+                Debug.LogError("[ShrinkApp.LoaderHost] 启动失败: " + ex.Message);
+            });
+        }
+
+        private void OnDestroy()
+        {
+            if (_instance == this)
+                _instance = null;
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: f4021699debf79945a4e30e8a43d3049
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,228 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using Cysharp.Threading.Tasks;
+using ShrinkApp;
+using ShrinkEventBus;
+using UnityEngine;
+
+namespace ShrinkContext.AppAdapter
+{
+    /// <summary>
+    /// 由 ShrinkContext 加载器驱动的 ShrinkApp 宿主（阶段 2 过渡路径，对应 ShrinkAppSettings.hostingMode = ContextLoader）。
+    ///
+    /// 与经典 ShrinkAppHost 的行为差异：
+    /// - 依赖缺失的安装器保持非活动等待（Waiting），而不是排序期抛错；
+    /// - 支持运行中 SetModuleDisabledAsync 按模块 disable/enable，无需重启宿主；
+    /// - 重复 ModuleId 在构造期抛错（与经典一致），依赖排序由响应式余效应结构性保证。
+    ///
+    /// 与 ShrinkAppHost 相同的语义：安装器单例实例、ModuleId 大小写不敏感、
+    /// disabledModuleIds 作为初始禁用集合、启动完成发布 ShrinkAppStartedEvent。
+    /// </summary>
+    public sealed class ShrinkAppLoaderHost
+    {
+        private sealed class ModuleRecord
+        {
+            public string ModuleId = string.Empty;
+        }
+
+        private readonly Dictionary<string, ModuleRecord> _modules = new(StringComparer.OrdinalIgnoreCase);
+        private readonly HashSet<string> _disabled = new(StringComparer.OrdinalIgnoreCase);
+        private readonly ShrinkComponentCatalog _catalog;
+        private bool _started;
+
+        public ShrinkAppLoaderHost(ShrinkAppSettings? settings = null,
+            IReadOnlyList<IShrinkAppModuleInstaller>? installers = null)
+        {
+            Settings = settings ?? ShrinkAppSettings.Instance;
+            Services = new ShrinkAppServices();
+            Context = new ShrinkContextRuntime();
+
+            var catalog = new ShrinkComponentCatalog();
+            foreach (var installer in installers ?? DiscoverDefaultInstallers())
+            {
+                if (installer == null || string.IsNullOrWhiteSpace(installer.ModuleId))
+                    throw new InvalidOperationException(
+                        $"Installer '{installer?.GetType().FullName ?? "<null>"}' has an empty ModuleId.");
+
+                var moduleId = installer.ModuleId.Trim();
+                if (!_modules.TryAdd(moduleId, new ModuleRecord { ModuleId = moduleId }))
+                    throw new InvalidOperationException($"Duplicate installer ModuleId: {moduleId}");
+
+                // 工厂每次重建条目时包装同一个安装器实例（与经典宿主的单例安装器语义一致）
+                catalog.Register(moduleId, () => new ShrinkAppInstallerComponent(installer, Settings));
+            }
+
+            Loader = new ShrinkContextLoader(Context, catalog);
+            _catalog = catalog;
+
+            foreach (var rawId in Settings.disabledModuleIds ?? Array.Empty<string>())
+            {
+                if (!string.IsNullOrWhiteSpace(rawId))
+                    _disabled.Add(rawId.Trim());
+            }
+        }
+
+        public ShrinkAppSettings Settings { get; }
+        public ShrinkAppServices Services { get; }
+        public ShrinkContextRuntime Context { get; }
+        public ShrinkContextLoader Loader { get; }
+        public bool IsRunning { get; private set; }
+
+        /// <summary>全部已注册模块 id（有序）。</summary>
+        public IReadOnlyList<string> ModuleIds =>
+            _modules.Values.Select(m => m.ModuleId).OrderBy(id => id, StringComparer.OrdinalIgnoreCase).ToArray();
+
+        public IReadOnlyList<string> ActiveModuleIds =>
+            ModuleIds.Where(IsModuleActive).ToArray();
+
+        /// <summary>已注册但当前非活动的模块（依赖缺失等待中；被禁用的模块不计入，见 IsModuleDisabled）。</summary>
+        public IReadOnlyList<string> WaitingModuleIds =>
+            ModuleIds.Where(IsModuleWaiting).ToArray();
+
+        public bool IsModuleActive(string moduleId) =>
+            TryGetLoaderFiber(moduleId, out var fiber) && fiber.State == ShrinkFiberState.Active;
+
+        public bool IsModuleWaiting(string moduleId) =>
+            TryGetLoaderFiber(moduleId, out var fiber) && fiber.State == ShrinkFiberState.Inactive;
+
+        public bool IsModuleDisabled(string moduleId) =>
+            !string.IsNullOrWhiteSpace(moduleId) && _disabled.Contains(moduleId.Trim());
+
+        /// <summary>查询模块当前纤程（被禁用模块返回 false）。</summary>
+        public bool TryGetModuleFiber(string moduleId, out ShrinkFiber fiber) =>
+            TryGetLoaderFiber(moduleId, out fiber!);
+
+        private bool TryGetLoaderFiber(string moduleId, out ShrinkFiber? fiber)
+        {
+            fiber = null;
+            if (string.IsNullOrWhiteSpace(moduleId))
+                return false;
+            if (!_modules.ContainsKey(moduleId.Trim()))
+                return false;
+            return Loader.TryGetFiber(moduleId.Trim(), out fiber!);
+        }
+
+        /// <summary>
+        /// 阶段 3：用原生 Cordis 组件替换指定模块的安装器包装（须在 StartAsync 之前调用）。
+        /// 目录同键覆盖——安装器不再被实例化包装，模块行为完全由原生组件定义。
+        /// </summary>
+        public void OverrideModuleComponent(string moduleId, Func<IShrinkComponent> componentFactory)
+        {
+            if (_started)
+                throw new InvalidOperationException("Module components can only be overridden before StartAsync.");
+            if (string.IsNullOrWhiteSpace(moduleId))
+                throw new ArgumentException("Module id must not be null or empty.", nameof(moduleId));
+            if (componentFactory == null)
+                throw new ArgumentNullException(nameof(componentFactory));
+            if (!_modules.ContainsKey(moduleId.Trim()))
+                throw new InvalidOperationException($"Unknown module id: '{moduleId}'.");
+
+            _catalog.Register(moduleId.Trim(), componentFactory);
+        }
+
+        /// <summary>
+        /// 向组合根加入没有旧安装器身份的原生组件（例如 Command-Network、EventBus 薄适配）。
+        /// 须在 StartAsync 前调用；模块 id 同时作为加载器条目 id 与组件目录键。
+        /// </summary>
+        public void AddModuleComponent(string moduleId, Func<IShrinkComponent> componentFactory)
+        {
+            if (_started)
+                throw new InvalidOperationException("Module components can only be added before StartAsync.");
+            if (string.IsNullOrWhiteSpace(moduleId))
+                throw new ArgumentException("Module id must not be null or empty.", nameof(moduleId));
+            if (componentFactory == null)
+                throw new ArgumentNullException(nameof(componentFactory));
+
+            var normalizedId = moduleId.Trim();
+            if (!_modules.TryAdd(normalizedId, new ModuleRecord { ModuleId = normalizedId }))
+                throw new InvalidOperationException($"Duplicate module id: '{normalizedId}'.");
+
+            _catalog.Register(normalizedId, componentFactory);
+        }
+
+        public async UniTask StartAsync()
+        {
+            if (_started)
+                return;
+            _started = true;
+
+            await Loader.ApplyAsync(BuildEntries());
+            IsRunning = true;
+            global::ShrinkApp.ShrinkApp.SetExternalHostRunning(true);
+
+            var active = ActiveModuleIds;
+            Debug.Log($"[ShrinkApp.LoaderHost] 启动完成：active={active.Count} " +
+                      $"waiting={WaitingModuleIds.Count} disabled={_disabled.Count} " +
+                      $"modules=[{string.Join(", ", active)}]");
+
+            EventBus.TriggerEvent(new ShrinkAppStartedEvent
+            {
+                ModuleIds = active.ToArray()
+            });
+        }
+
+        /// <summary>运行中按模块 disable/enable：增量协调，宿主与其余模块不重启。</summary>
+        public async UniTask SetModuleDisabledAsync(string moduleId, bool disabled)
+        {
+            EnsureStarted();
+            if (string.IsNullOrWhiteSpace(moduleId))
+                throw new ArgumentException("Module id must not be null or empty.", nameof(moduleId));
+            if (!TryGetRecord(moduleId, out _))
+                throw new InvalidOperationException($"Unknown module id: '{moduleId}'.");
+
+            if (disabled)
+                _disabled.Add(moduleId.Trim());
+            else
+                _disabled.Remove(moduleId.Trim());
+
+            await Loader.ApplyAsync(BuildEntries());
+        }
+
+        public async UniTask ShutdownAsync()
+        {
+            EnsureStarted();
+            await Context.ShutdownAsync();
+            IsRunning = false;
+            global::ShrinkApp.ShrinkApp.SetExternalHostRunning(false);
+        }
+
+        private List<ShrinkLoaderEntry> BuildEntries()
+        {
+            var entries = new List<ShrinkLoaderEntry>();
+            foreach (var record in _modules.Values.OrderBy(m => m.ModuleId, StringComparer.OrdinalIgnoreCase))
+                entries.Add(new ShrinkLoaderEntry(record.ModuleId, record.ModuleId, Services,
+                    _disabled.Contains(record.ModuleId)));
+            return entries;
+        }
+
+        private bool TryGetRecord(string moduleId, out ModuleRecord record)
+        {
+            if (!string.IsNullOrWhiteSpace(moduleId))
+                return _modules.TryGetValue(moduleId.Trim(), out record!);
+            record = null!;
+            return false;
+        }
+
+        private void EnsureStarted()
+        {
+            if (!_started)
+                throw new InvalidOperationException("ShrinkAppLoaderHost has not been started yet.");
+        }
+
+        private static IReadOnlyList<IShrinkAppModuleInstaller> DiscoverDefaultInstallers()
+        {
+            var installers = new List<IShrinkAppModuleInstaller>();
+            foreach (var type in ShrinkAppInstallers.GetDiscoveredInstallerTypes())
+            {
+                if (Activator.CreateInstance(type) is IShrinkAppModuleInstaller installer)
+                    installers.Add(installer);
+                else
+                    throw new InvalidOperationException($"Failed to create installer: {type.FullName}");
+            }
+
+            return installers;
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 4a5dccbb74da10d46837de4ba1240299
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,15 @@
+{
+    "name": "ShrinkContext.AppAdapter.Runtime",
+    "rootNamespace": "ShrinkContext.AppAdapter",
+    "references": [
+        "ShrinkContext.Core.Runtime",
+        "ShrinkApp.Core.Runtime",
+        "ShrinkEventBus.Runtime",
+        "UniTask"
+    ],
+    "includePlatforms": [],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "autoReferenced": false
+}
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 784bc035ead25ce438bcd7b9369a11c8
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: