feat(packages): 内置 SDK 包并完善 ContextLoader 集成

- 将 ShrinkEventBus、ShrinkDataSaver 及其 EventBus 集成从 gitlink 转为仓库直接维护的完整 UPM 包，补齐运行时、编辑器工具、测试与文档 - 新增 Command 和 Network 的 App 集成组件，支持 ContextLoader 服务发布、可逆注销及 Network Loopback 生命周期管理 - 更新 Starter 与演示组合逻辑，缺失模块时可注册、已有兼容安装器时可覆盖，并补充宿主启动断言 - 升级内部包依赖与 Shared CodeGen 包定义，放宽 Integration.App 包的 Git 忽略规则 - 将独立服务器生成器改为基于已编译程序集的语义扫描，支持 partial、复杂泛型、命名冲突检测及模板 SHA-256 覆写保护 - 新增 Network 语义扫描、模板保护和 App 组件生命周期测试 - 新增真实 UPM 消费工程验证脚本，校验内部版本一致性、程序集加载及 EditMode 测试 - 重构当前架构文档并归档已完成的 Cordis 迁移与旧代码地图
2026-08-18 18:06:34 +08:00
parent 517c4cf46e
commit d74c2f08ca
240 changed files with 13647 additions and 545 deletions
@@ -0,0 +1,11 @@
+# Changelog
+
+本文件记录 `ShrinkNetwork.Integration.App` 的包内变更。
+
+## [0.1.0] - 2026-05-18
+
+### Added
+
+- 新增 `ShrinkNetwork` 与 `ShrinkApp.Core` 的桥接包。
+- 新增 `ShrinkNetworkAppInstaller`，把默认网络服务挂入宿主服务容器。
+- 新增 `ShrinkNetworkAppService` 作为宿主侧网络门面。
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 12ec7a42482c6dc4b969870ad23daffc
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,23 @@
+# ShrinkNetwork.Integration.App
+
+`ShrinkNetwork.Integration.App` 是 `ShrinkNetwork` 与 `ShrinkApp.Core` 的桥接层。它负责把默认网络服务挂进宿主服务容器，让项目在进入统一宿主模式后，能明确地从 `ShrinkApp` 取得网络服务，而不是在各处直接耦合 `ShrinkNetworkRuntime.Default`。
+
+## 当前能力
+
+- 提供原生 `ShrinkNetworkAppComponent`，发布 `shrink.service.network`
+- 把 `ShrinkNetworkRuntime.Default` 包装为 `ShrinkNetworkAppService`
+- ContextLoader 下由 Starter 组合根装配，服务门面随组件停用可逆注销
+- `ShrinkNetworkAppInstaller` 仅保留给 ClassicHost 兼容路径，已标记过时
+
+## 使用示例
+
+```csharp
+var network = ShrinkApp.ShrinkApp.Services.GetRequired<ShrinkNetwork.Integration.App.ShrinkNetworkAppService>();
+var service = network.Service;
+```
+
+## 说明
+
+- 本包当前不主动绑定传输层，也不替业务决定 TCP / KCP / Loopback。
+- 静态消息合同与静态 handler 的默认注册仍由 `ShrinkNetworkRuntime.Default` 完成。
+- 运行时实例 handler 仍然走 `RegisterHandlers(object target)`。
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 00f656bae7782f54fa051900ddc0575c
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 13a446f2618993d4f84f800c349a6306
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,18 @@
+{
+  "name": "ShrinkNetwork.Integration.App",
+  "rootNamespace": "ShrinkNetwork.Integration.App",
+  "references": [
+    "ShrinkNetwork.Runtime",
+    "ShrinkApp.Core.Runtime",
+        "ShrinkContext.Core.Runtime",
+    "UniTask"
+  ],
+  "includePlatforms": [],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": false,
+  "autoReferenced": true,
+  "defineConstraints": [],
+  "versionDefines": [],
+  "noEngineReferences": false
+}
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 6396a2709306e6245892177071b1c3f2
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,89 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using Cysharp.Threading.Tasks;
+using ShrinkContext;
+using ShrinkNetwork;
+using UnityEngine;
+
+namespace ShrinkNetwork.Integration.App
+{
+    /// <summary>ShrinkNetwork 组件的配置。</summary>
+    public sealed class ShrinkNetworkAppModuleConfig
+    {
+        /// <summary>是否在激活时自动绑定 loopback 传输并打开默认会话（演示/调试台用）。</summary>
+        public bool BindLoopbackTransport;
+
+        public int LoopbackSessionId = 1;
+
+        /// <summary>可选：把网络服务同时注册进 ShrinkApp 服务容器（兼容旧调试台读取路径）。</summary>
+        public ShrinkApp.ShrinkAppServices? Services;
+    }
+
+    /// <summary>
+    /// ShrinkNetwork 的原生 Cordis 组件（阶段 3）：
+    /// - 提供 <c>shrink.service.network</c> 余效应键（服务实例），依赖者按键注入；
+    /// - 可选的 loopback 传输绑定是**可逆效应**：停用时解绑传输、清理会话并使挂起 RPC 失败——
+    ///   全部由效应回滚完成，而非手写卸载路径；
+    /// - 与经典 ShrinkNetworkAppInstaller（ModuleId "shrink.network"）二选一使用：
+    ///   两者都发布 "app.module.shrink.network"，同时激活会触发供给冲突。
+    /// </summary>
+    public sealed class ShrinkNetworkAppComponent : IShrinkComponent
+    {
+        public const string ServiceKey = "shrink.service.network";
+        public const string ModuleKey = "app.module.shrink.network";
+
+        private static readonly string[] ProvideKeys = { ModuleKey, ServiceKey };
+
+        public string Name => "shrink.network";
+
+        public IReadOnlyList<string> Inject => Array.Empty<string>();
+
+        public IReadOnlyList<string> Provide => ProvideKeys;
+
+        public async UniTask ApplyAsync(ShrinkCtx ctx, object? config)
+        {
+            var moduleConfig = config as ShrinkNetworkAppModuleConfig ?? new ShrinkNetworkAppModuleConfig();
+            var service = ShrinkNetworkRuntime.Default;
+
+            // set 是可逆效应：停用自动撤回服务键，依赖者随之停用
+            ctx.Set(ServiceKey, service);
+            var facade = new ShrinkNetworkAppService(service);
+            moduleConfig.Services?.Register(facade);
+            if (config is ShrinkApp.ShrinkAppServices appServices)
+            {
+                appServices.Register(facade);
+                ctx.EffectInverse(() =>
+                {
+                    appServices.TryUnregister(facade);
+                    return UniTask.CompletedTask;
+                });
+            }
+            ctx.Set(ModuleKey, Name);
+
+            if (moduleConfig.BindLoopbackTransport)
+            {
+                await ctx.EffectAsync(() => BindLoopbackAsync(service, moduleConfig.LoopbackSessionId));
+            }
+        }
+
+        private static async UniTask<Func<UniTask>> BindLoopbackAsync(ShrinkNetworkService service, int sessionId)
+        {
+            var client = new ShrinkLoopbackTransport();
+            var server = new ShrinkLoopbackTransport();
+            client.LinkPeer(server);
+
+            service.BindTransport(client);
+            client.OpenSession(sessionId);
+            await UniTask.CompletedTask;
+
+            return () =>
+            {
+                // 逆操作：关闭会话并解绑传输；BindTransport(null) 触发会话清理与挂起 RPC 失败
+                client.CloseSession(sessionId);
+                service.BindTransport(null);
+                return UniTask.CompletedTask;
+            };
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: f956f1f1465b7c749844f59dfd12412a
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,49 @@
+#nullable enable
+
+using System;
+using System.Linq;
+using Cysharp.Threading.Tasks;
+using ShrinkApp;
+
+namespace ShrinkNetwork.Integration.App
+{
+    [ShrinkAppModuleInstaller]
+    [Obsolete("ClassicHost compatibility only. ContextLoader projects should use ShrinkNetworkAppComponent from a composition root.")]
+    public sealed class ShrinkNetworkAppInstaller : IShrinkAppModuleInstaller
+    {
+        public string ModuleId => "shrink.network";
+        public int Order => -1400;
+        public System.Collections.Generic.IReadOnlyList<string> DependsOn => Array.Empty<string>();
+
+        public void RegisterServices(ShrinkAppContext context)
+        {
+            context.Services.Register(new ShrinkNetworkAppService(ShrinkNetworkRuntime.Default));
+        }
+
+        public UniTask InitializeAsync(ShrinkAppContext context)
+        {
+            return UniTask.CompletedTask;
+        }
+    }
+
+    public sealed class ShrinkNetworkAppService
+    {
+        public ShrinkNetworkAppService(ShrinkNetworkService service)
+        {
+            Service = service ?? throw new ArgumentNullException(nameof(service));
+        }
+
+        public ShrinkNetworkService Service { get; }
+
+        public ShrinkNetworkServiceDiagnosticsSnapshot GetDiagnosticsSnapshot()
+            => Service.GetDiagnosticsSnapshot();
+
+        public System.Collections.Generic.IReadOnlyList<string> GetSessionSummaries()
+        {
+            return Service.Sessions.Values
+                .OrderBy(session => session.SessionId)
+                .Select(session => $"session={session.SessionId}, remote={session.RemoteAddress}, peer={session.PeerKind}")
+                .ToArray();
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: ff40e733ef9026441b4698e55e421922
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 200fb1bcdd99fe34cb64508bd1e24c66
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,25 @@
+{
+    "name": "ShrinkNetwork.Integration.App.Tests",
+    "rootNamespace": "ShrinkNetwork.Integration.App.Tests",
+    "references": [
+        "ShrinkNetwork.Integration.App",
+        "ShrinkNetwork.Runtime",
+        "ShrinkContext.Core.Runtime",
+        "ShrinkApp.Core.Runtime",
+        "UniTask",
+        "UnityEngine.TestRunner",
+        "UnityEditor.TestRunner"
+    ],
+    "includePlatforms": [
+        "Editor"
+    ],
+    "excludePlatforms": [],
+    "allowUnsafeCode": false,
+    "overrideReferences": false,
+    "autoReferenced": false,
+    "defineConstraints": [
+        "UNITY_INCLUDE_TESTS"
+    ],
+    "versionDefines": [],
+    "noEngineReferences": false
+}
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: d64f2336fac149741b1d481059053715
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,98 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using Cysharp.Threading.Tasks;
+using NUnit.Framework;
+using ShrinkContext;
+using ShrinkNetwork;
+
+namespace ShrinkNetwork.Integration.App.Tests
+{
+    /// <summary>
+    /// 阶段 3 验收（EditMode 部分）：Network 组件热插拔——
+    /// 停用时传输解绑、会话清理、服务键撤回、依赖者停用，全部为效应回滚结果。
+    /// </summary>
+    public class ShrinkNetworkAppComponentTests
+    {
+        private ShrinkContextRuntime _runtime = null!;
+
+        [SetUp]
+        public void SetUp()
+        {
+            _runtime = new ShrinkContextRuntime();
+        }
+
+        [TearDown]
+        public void TearDown()
+        {
+            _runtime.ShutdownAsync().GetAwaiter().GetResult();
+        }
+
+        private static void Run(UniTask task) => task.GetAwaiter().GetResult();
+
+        [Test]
+        public void Apply_ProvidesServiceKey_AndBindsLoopbackWithSession()
+        {
+            var sessionsBefore = ShrinkNetworkRuntime.Default.Sessions.Count;
+            var fiber = _runtime.Use(new ShrinkNetworkAppComponent(),
+                new ShrinkNetworkAppModuleConfig { BindLoopbackTransport = true, LoopbackSessionId = 7 });
+
+            Assert.AreEqual(ShrinkFiberState.Active, fiber.State);
+            Assert.IsTrue(_runtime.TryGetRaw<ShrinkNetworkService>(_runtime.RootContext,
+                ShrinkNetworkAppComponent.ServiceKey, out var service));
+            Assert.AreSame(ShrinkNetworkRuntime.Default, service);
+            Assert.AreEqual(sessionsBefore + 1, service.Sessions.Count, "loopback 绑定应新建一个会话");
+        }
+
+        [Test]
+        public void Retire_UnbindsTransport_ClearsSessions_AndStopsDependents()
+        {
+            var sessionsBefore = ShrinkNetworkRuntime.Default.Sessions.Count;
+            var consumerFiber = _runtime.Use(new ServiceConsumerComponent());
+            Assert.AreEqual(ShrinkFiberState.Inactive, consumerFiber.State, "网络服务未提供前依赖者等待");
+
+            var networkFiber = _runtime.Use(new ShrinkNetworkAppComponent(),
+                new ShrinkNetworkAppModuleConfig { BindLoopbackTransport = true });
+            Assert.AreEqual(ShrinkFiberState.Active, networkFiber.State);
+            Assert.AreEqual(ShrinkFiberState.Active, consumerFiber.State, "服务键发布后依赖者激活");
+
+            Run(_runtime.RetireAsync(networkFiber));
+
+            Assert.AreEqual(sessionsBefore, ShrinkNetworkRuntime.Default.Sessions.Count,
+                "停用必须解绑传输并清理自己的会话（效应回滚，非手写卸载；不影响他人遗留会话）");
+            Assert.IsFalse(_runtime.TryGetRaw<ShrinkNetworkService>(_runtime.RootContext,
+                ShrinkNetworkAppComponent.ServiceKey, out _), "服务键随 set 的逆操作撤回");
+            Assert.AreEqual(ShrinkFiberState.Inactive, consumerFiber.State, "依赖者随提供者停用");
+        }
+
+        [Test]
+        public void Reactivate_RebindsLoopback()
+        {
+            var sessionsBefore = ShrinkNetworkRuntime.Default.Sessions.Count;
+            var first = _runtime.Use(new ShrinkNetworkAppComponent(),
+                new ShrinkNetworkAppModuleConfig { BindLoopbackTransport = true });
+            Run(_runtime.RetireAsync(first));
+            Assert.AreEqual(sessionsBefore, ShrinkNetworkRuntime.Default.Sessions.Count);
+
+            var second = _runtime.Use(new ShrinkNetworkAppComponent(),
+                new ShrinkNetworkAppModuleConfig { BindLoopbackTransport = true });
+            Assert.AreEqual(ShrinkFiberState.Active, second.State);
+            Assert.AreEqual(sessionsBefore + 1, ShrinkNetworkRuntime.Default.Sessions.Count, "重新激活重新绑定传输");
+        }
+
+        /// <summary>注入网络服务键的消费者组件。</summary>
+        private sealed class ServiceConsumerComponent : IShrinkComponent
+        {
+            public string Name => "network-consumer";
+            public IReadOnlyList<string> Inject { get; } = new[] { ShrinkNetworkAppComponent.ServiceKey };
+            public IReadOnlyList<string> Provide => Array.Empty<string>();
+            public ShrinkNetworkService? Seen { get; private set; }
+
+            public UniTask ApplyAsync(ShrinkCtx ctx, object? config)
+            {
+                Seen = ctx.Get<ShrinkNetworkService>(ShrinkNetworkAppComponent.ServiceKey);
+                return UniTask.CompletedTask;
+            }
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 490be582f048d0d4ea468903e7326aac
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
@@ -0,0 +1,23 @@
+{
+  "name": "com.cneicy.shrink-network-integration-app",
+  "version": "0.1.0",
+  "displayName": "ShrinkNetwork - App Integration",
+  "description": "ShrinkNetwork 与 ShrinkApp 的桥接层，把默认网络服务纳入统一宿主服务容器。",
+  "unity": "2022.3",
+  "dependencies": {
+    "com.cneicy.shrink-network": "0.2.0",
+    "com.cneicy.shrink-app-core": "0.1.1",
+    "com.cysharp.unitask": "2.5.10",
+    "com.cneicy.shrink-context-core": "0.1.0"
+  },
+  "keywords": [
+    "network",
+    "integration",
+    "app",
+    "rpc"
+  ],
+  "author": {
+    "name": "cneicy",
+    "url": "https://github.com/cneicy"
+  }
+}
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: b37c0ec21665ffb4abd20c33356ec649
+TextScriptImporter:
+  externalObjects: {}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: