feat(cordis): 完成阶段5配置与调试工具

Assets/Modules/ShrinkContext.AppAdapter/Runtime/ShrinkAppCompositionProfile.cs

@@ -0,0 +1,282 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace ShrinkContext.AppAdapter
+{
+    [Serializable]
+    public sealed class ShrinkAppCompositionIsolate
+    {
+        public string key = string.Empty;
+        public string realm = string.Empty;
+
+        public ShrinkAppCompositionIsolate()
+        {
+        }
+
+        public ShrinkAppCompositionIsolate(string key, string realm)
+        {
+            this.key = key;
+            this.realm = realm;
+        }
+
+        internal ShrinkAppCompositionIsolate Clone() => new(key, realm);
+    }
+
+    [Serializable]
+    public sealed class ShrinkAppCompositionMetadata
+    {
+        public string name = string.Empty;
+        public string value = string.Empty;
+
+        public ShrinkAppCompositionMetadata()
+        {
+        }
+
+        public ShrinkAppCompositionMetadata(string name, string value)
+        {
+            this.name = name;
+            this.value = value;
+        }
+
+        internal ShrinkAppCompositionMetadata Clone() => new(name, value);
+    }
+
+    [Serializable]
+    public sealed class ShrinkAppCompositionIntercept
+    {
+        public string key = string.Empty;
+        public List<ShrinkAppCompositionMetadata> metadata = new();
+
+        public ShrinkAppCompositionIntercept()
+        {
+        }
+
+        public ShrinkAppCompositionIntercept(string key,
+            IEnumerable<ShrinkAppCompositionMetadata>? metadata = null)
+        {
+            this.key = key;
+            if (metadata != null)
+            {
+                foreach (var item in metadata)
+                    this.metadata.Add(item?.Clone() ?? throw new ArgumentException("Metadata must not contain null."));
+            }
+        }
+
+        internal ShrinkAppCompositionIntercept Clone() => new(key, metadata);
+    }
+
+    [Serializable]
+    public sealed class ShrinkAppCompositionEntry
+    {
+        public string id = string.Empty;
+        public bool enabled = true;
+        public List<ShrinkAppCompositionIsolate> isolate = new();
+        public List<ShrinkAppCompositionIntercept> intercept = new();
+
+        public ShrinkAppCompositionEntry()
+        {
+        }
+
+        public ShrinkAppCompositionEntry(string id, bool enabled = true,
+            IEnumerable<ShrinkAppCompositionIsolate>? isolate = null,
+            IEnumerable<ShrinkAppCompositionIntercept>? intercept = null)
+        {
+            this.id = id;
+            this.enabled = enabled;
+            if (isolate != null)
+            {
+                foreach (var item in isolate)
+                    this.isolate.Add(item?.Clone() ?? throw new ArgumentException("Isolate must not contain null."));
+            }
+
+            if (intercept != null)
+            {
+                foreach (var item in intercept)
+                    this.intercept.Add(item?.Clone() ?? throw new ArgumentException("Intercept must not contain null."));
+            }
+        }
+
+        internal string NormalizedId => id?.Trim() ?? string.Empty;
+
+        internal ShrinkAppCompositionEntry Clone() => new(id, enabled, isolate, intercept);
+
+        internal IReadOnlyDictionary<string, string>? BuildIsolate()
+        {
+            if (isolate == null || isolate.Count == 0)
+                return null;
+
+            var result = new Dictionary<string, string>(StringComparer.Ordinal);
+            foreach (var item in isolate)
+                result.Add(item.key.Trim(), item.realm.Trim());
+            return result;
+        }
+
+        internal IReadOnlyDictionary<string, IReadOnlyDictionary<string, object?>>? BuildIntercept()
+        {
+            if (intercept == null || intercept.Count == 0)
+                return null;
+
+            var result = new Dictionary<string, IReadOnlyDictionary<string, object?>>(StringComparer.Ordinal);
+            foreach (var item in intercept)
+            {
+                var values = new Dictionary<string, object?>(StringComparer.Ordinal);
+                foreach (var pair in item.metadata)
+                    values.Add(pair.name.Trim(), pair.value);
+                result.Add(item.key.Trim(), values);
+            }
+
+            return result;
+        }
+    }
+
+    /// <summary>
+    /// 可序列化的期望组合。组件工厂仍由代码目录注册；文档只控制条目选择、isolate 与 intercept。
+    /// intercept metadata 使用字符串值，领域策略负责解释其语义。
+    /// </summary>
+    [Serializable]
+    public sealed class ShrinkAppCompositionDocument
+    {
+        public bool includeUnlistedEntries = true;
+        public List<ShrinkAppCompositionEntry> entries = new();
+
+        public ShrinkAppCompositionDocument()
+        {
+        }
+
+        public ShrinkAppCompositionDocument(bool includeUnlistedEntries,
+            IEnumerable<ShrinkAppCompositionEntry>? entries = null)
+        {
+            this.includeUnlistedEntries = includeUnlistedEntries;
+            if (entries != null)
+            {
+                foreach (var entry in entries)
+                    this.entries.Add(entry?.Clone() ?? throw new ArgumentException("Entries must not contain null."));
+            }
+        }
+
+        public void Validate()
+        {
+            entries ??= new List<ShrinkAppCompositionEntry>();
+            var ids = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            foreach (var entry in entries)
+            {
+                if (entry == null)
+                    throw new ShrinkLoaderException("Composition entries must not contain null.");
+                if (string.IsNullOrWhiteSpace(entry.id))
+                    throw new ShrinkLoaderException("Composition entry id must not be empty.");
+                if (!ids.Add(entry.NormalizedId))
+                    throw new ShrinkLoaderException($"Duplicate composition entry id: '{entry.NormalizedId}'.");
+
+                ValidateIsolate(entry);
+                ValidateIntercept(entry);
+            }
+        }
+
+        public ShrinkAppCompositionDocument Clone()
+        {
+            Validate();
+            return new ShrinkAppCompositionDocument(includeUnlistedEntries, entries);
+        }
+
+        public string ToJson(bool prettyPrint = true)
+        {
+            Validate();
+            return JsonUtility.ToJson(this, prettyPrint);
+        }
+
+        public static ShrinkAppCompositionDocument FromJson(string json)
+        {
+            if (string.IsNullOrWhiteSpace(json))
+                throw new ArgumentException("Composition JSON must not be empty.", nameof(json));
+
+            var document = JsonUtility.FromJson<ShrinkAppCompositionDocument>(json);
+            if (document == null)
+                throw new ShrinkLoaderException("Composition JSON did not produce a document.");
+            document.entries ??= new List<ShrinkAppCompositionEntry>();
+            document.Validate();
+            return document;
+        }
+
+        private static void ValidateIsolate(ShrinkAppCompositionEntry entry)
+        {
+            entry.isolate ??= new List<ShrinkAppCompositionIsolate>();
+            var keys = new HashSet<string>(StringComparer.Ordinal);
+            foreach (var item in entry.isolate)
+            {
+                if (item == null || string.IsNullOrWhiteSpace(item.key) || string.IsNullOrWhiteSpace(item.realm))
+                    throw new ShrinkLoaderException(
+                        $"Composition entry '{entry.NormalizedId}' has an empty isolate key or realm.");
+                if (!keys.Add(item.key.Trim()))
+                    throw new ShrinkLoaderException(
+                        $"Composition entry '{entry.NormalizedId}' has duplicate isolate key '{item.key.Trim()}'.");
+            }
+        }
+
+        private static void ValidateIntercept(ShrinkAppCompositionEntry entry)
+        {
+            entry.intercept ??= new List<ShrinkAppCompositionIntercept>();
+            var keys = new HashSet<string>(StringComparer.Ordinal);
+            foreach (var item in entry.intercept)
+            {
+                if (item == null || string.IsNullOrWhiteSpace(item.key))
+                    throw new ShrinkLoaderException(
+                        $"Composition entry '{entry.NormalizedId}' has an empty intercept key.");
+                if (!keys.Add(item.key.Trim()))
+                    throw new ShrinkLoaderException(
+                        $"Composition entry '{entry.NormalizedId}' has duplicate intercept key '{item.key.Trim()}'.");
+
+                item.metadata ??= new List<ShrinkAppCompositionMetadata>();
+                var names = new HashSet<string>(StringComparer.Ordinal);
+                foreach (var pair in item.metadata)
+                {
+                    if (pair == null || string.IsNullOrWhiteSpace(pair.name))
+                        throw new ShrinkLoaderException(
+                            $"Composition entry '{entry.NormalizedId}' has empty intercept metadata.");
+                    if (!names.Add(pair.name.Trim()))
+                        throw new ShrinkLoaderException(
+                            $"Composition entry '{entry.NormalizedId}' has duplicate metadata '{pair.name.Trim()}'.");
+                }
+            }
+        }
+    }
+
+    [CreateAssetMenu(fileName = DefaultResourceName, menuName = "ShrinkSDK/Cordis/Composition Profile")]
+    public sealed class ShrinkAppCompositionProfile : ScriptableObject
+    {
+        public const string DefaultResourceName = "ShrinkAppComposition";
+
+        [SerializeField] private bool includeUnlistedEntries = true;
+        [SerializeField] private List<ShrinkAppCompositionEntry> entries = new();
+        [Tooltip("设置后以该 TextAsset 的 JSON 文档为准；留空则使用上面的序列化条目。")]
+        [SerializeField] private TextAsset? jsonOverride;
+
+        public bool IncludeUnlistedEntries => includeUnlistedEntries;
+        public IReadOnlyList<ShrinkAppCompositionEntry> Entries =>
+            entries ??= new List<ShrinkAppCompositionEntry>();
+        public TextAsset? JsonOverride => jsonOverride;
+
+        public ShrinkAppCompositionDocument ResolveDocument()
+        {
+            if (jsonOverride != null && !string.IsNullOrWhiteSpace(jsonOverride.text))
+                return ShrinkAppCompositionDocument.FromJson(jsonOverride.text);
+            return new ShrinkAppCompositionDocument(includeUnlistedEntries, entries);
+        }
+
+        public string ToJson(bool prettyPrint = true) => ResolveDocument().ToJson(prettyPrint);
+
+        public void SetDocument(ShrinkAppCompositionDocument document)
+        {
+            var copy = (document ?? throw new ArgumentNullException(nameof(document))).Clone();
+            includeUnlistedEntries = copy.includeUnlistedEntries;
+            entries = copy.entries;
+            jsonOverride = null;
+        }
+
+        public void SetJsonOverride(TextAsset? value) => jsonOverride = value;
+
+        public static ShrinkAppCompositionProfile? LoadDefault() =>
+            Resources.Load<ShrinkAppCompositionProfile>(DefaultResourceName);
+    }
+}

Assets/Modules/ShrinkContext.AppAdapter/Runtime/ShrinkAppCompositionProfile.cs.meta

@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 469746f53f0218442b72603e3c1f6955
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:

Assets/Modules/ShrinkContext.AppAdapter/Runtime/ShrinkAppLoaderBootstrapper.cs

@@ -47,6 +47,9 @@ 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 =>
             {

Assets/Modules/ShrinkContext.AppAdapter/Runtime/ShrinkAppLoaderHost.cs

@@ -27,9 +27,19 @@ namespace ShrinkContext.AppAdapter
             public string ModuleId = string.Empty;
         }
 
+        private sealed class CompositionOptions
+        {
+            public bool Enabled;
+            public IReadOnlyDictionary<string, string>? Isolate;
+            public IReadOnlyDictionary<string, IReadOnlyDictionary<string, object?>>? Intercept;
+        }
+
         private readonly Dictionary<string, ModuleRecord> _modules = new(StringComparer.OrdinalIgnoreCase);
         private readonly HashSet<string> _disabled = new(StringComparer.OrdinalIgnoreCase);
+        private readonly HashSet<string> _settingsDisabled = new(StringComparer.OrdinalIgnoreCase);
         private readonly ShrinkComponentCatalog _catalog;
+        private Dictionary<string, CompositionOptions>? _compositionOptions;
+        private bool _includeUnlistedEntries = true;
         private bool _started;
 
         public ShrinkAppLoaderHost(ShrinkAppSettings? settings = null,
@@ -60,7 +70,10 @@ namespace ShrinkContext.AppAdapter
             foreach (var rawId in Settings.disabledModuleIds ?? Array.Empty<string>())
             {
                 if (!string.IsNullOrWhiteSpace(rawId))
+                {
+                    _settingsDisabled.Add(rawId.Trim());
                     _disabled.Add(rawId.Trim());
+                }
             }
         }
 
@@ -69,6 +82,7 @@ namespace ShrinkContext.AppAdapter
         public ShrinkContextRuntime Context { get; }
         public ShrinkContextLoader Loader { get; }
         public bool IsRunning { get; private set; }
+        public ShrinkAppCompositionDocument? AppliedComposition { get; private set; }
 
         /// <summary>全部已注册模块 id（有序）。</summary>
         public IReadOnlyList<string> ModuleIds =>
@@ -88,7 +102,10 @@ namespace ShrinkContext.AppAdapter
             TryGetLoaderFiber(moduleId, out var fiber) && fiber.State == ShrinkFiberState.Inactive;
 
         public bool IsModuleDisabled(string moduleId) =>
-            !string.IsNullOrWhiteSpace(moduleId) && _disabled.Contains(moduleId.Trim());
+            !string.IsNullOrWhiteSpace(moduleId) &&
+            (_disabled.Contains(moduleId.Trim()) ||
+             (!_includeUnlistedEntries && _compositionOptions != null &&
+              !_compositionOptions.ContainsKey(moduleId.Trim())));
 
         /// <summary>查询模块当前纤程（被禁用模块返回 false）。</summary>
         public bool TryGetModuleFiber(string moduleId, out ShrinkFiber fiber) =>
@@ -142,6 +159,46 @@ namespace ShrinkContext.AppAdapter
             _catalog.Register(normalizedId, componentFactory);
         }
 
+        /// <summary>
+        /// 在启动前应用声明式条目策略。组件工厂必须已经由组合根注册；配置不能实例化任意类型。
+        /// ShrinkAppSettings.disabledModuleIds 仍作为额外禁用集合保留。
+        /// </summary>
+        public void ApplyComposition(ShrinkAppCompositionDocument document)
+        {
+            if (_started)
+                throw new InvalidOperationException("Composition can only be applied before StartAsync.");
+
+            var copy = (document ?? throw new ArgumentNullException(nameof(document))).Clone();
+            var options = new Dictionary<string, CompositionOptions>(StringComparer.OrdinalIgnoreCase);
+            foreach (var entry in copy.entries)
+            {
+                var id = entry.NormalizedId;
+                if (!_modules.ContainsKey(id))
+                    throw new ShrinkLoaderException(
+                        $"Composition entry '{id}' has no registered module/component factory.");
+
+                options.Add(id, new CompositionOptions
+                {
+                    Enabled = entry.enabled,
+                    Isolate = entry.BuildIsolate(),
+                    Intercept = entry.BuildIntercept()
+                });
+            }
+
+            _compositionOptions = options;
+            _includeUnlistedEntries = copy.includeUnlistedEntries;
+            AppliedComposition = copy;
+
+            _disabled.Clear();
+            foreach (var id in _settingsDisabled)
+                _disabled.Add(id);
+            foreach (var pair in options)
+            {
+                if (!pair.Value.Enabled)
+                    _disabled.Add(pair.Key);
+            }
+        }
+
         public async UniTask StartAsync()
         {
             if (_started)
@@ -172,10 +229,18 @@ namespace ShrinkContext.AppAdapter
             if (!TryGetRecord(moduleId, out _))
                 throw new InvalidOperationException($"Unknown module id: '{moduleId}'.");
 
+            var normalizedId = moduleId.Trim();
+            if (!disabled && !_includeUnlistedEntries && _compositionOptions != null &&
+                !_compositionOptions.ContainsKey(normalizedId))
+            {
+                throw new InvalidOperationException(
+                    $"Module '{normalizedId}' is excluded by the active composition profile.");
+            }
+
             if (disabled)
-                _disabled.Add(moduleId.Trim());
+                _disabled.Add(normalizedId);
             else
-                _disabled.Remove(moduleId.Trim());
+                _disabled.Remove(normalizedId);
 
             await Loader.ApplyAsync(BuildEntries());
         }
@@ -192,8 +257,15 @@ namespace ShrinkContext.AppAdapter
         {
             var entries = new List<ShrinkLoaderEntry>();
             foreach (var record in _modules.Values.OrderBy(m => m.ModuleId, StringComparer.OrdinalIgnoreCase))
+            {
+                CompositionOptions? options = null;
+                _compositionOptions?.TryGetValue(record.ModuleId, out options);
+                if (!_includeUnlistedEntries && _compositionOptions != null && options == null)
+                    continue;
+
                 entries.Add(new ShrinkLoaderEntry(record.ModuleId, record.ModuleId, Services,
-                    _disabled.Contains(record.ModuleId)));
+                    _disabled.Contains(record.ModuleId), options?.Isolate, options?.Intercept));
+            }
             return entries;
         }