feat(cordis): 完成阶段5访问介导与诊断

2026-08-17 01:09:32 +08:00
parent de5ab449cd
commit 8738e633ee
35 changed files with 1540 additions and 50 deletions
@@ -0,0 +1,18 @@
+# Changelog
+
+本文件记录 `ShrinkDataSaver.Integration.App` 的包内变更。
+
+## [Unreleased]
+
+### Added
+
+- 拆分 `IShrinkDataSaverReader` / `IShrinkDataSaverWriter` 能力契约。
+- 支持通过 ShrinkContext intercept 向派生上下文提供只读 DataSaver 视图。
+
+## [0.1.0] - 2026-05-18
+
+### Added
+
+- 新增 `ShrinkDataSaver` 与 `ShrinkApp.Core` 的桥接包。
+- 新增 `ShrinkDataSaverAppInstaller`，把 DataSaver 纳入统一宿主启动链。
+- 新增 `ShrinkDataSaverService` 作为宿主服务门面。
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 3c6cf6fb5b92c5848b40e963a80a58c1
+TextScriptImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
@@ -0,0 +1,29 @@
+# ShrinkDataSaver.Integration.App
+
+`ShrinkDataSaver.Integration.App` 是 `ShrinkDataSaver` 与 `ShrinkApp.Core` 的桥接层。它的职责不是重新实现存档系统，而是把 `ShrinkDataSaver` 接到统一宿主链里，让项目在接入 `ShrinkApp` 时由宿主接管初始化顺序。
+
+## 当前能力
+
+- 提供原生 `ShrinkDataSaverAppComponent`，发布 `shrink.service.datasaver`
+- 在组件激活阶段调用 `ShrinkDataSaverRuntime.Initialize()`
+- ContextLoader 下向 `ShrinkApp.Services` 注册可逆的 `ShrinkDataSaverService` 门面
+- 区分 `IShrinkDataSaverReader` 与 `IShrinkDataSaverWriter`；默认上下文取得完整写能力
+- 支持以 `ShrinkDataSaverAccess.MetadataKey = ShrinkDataSaverAccess.ReadOnly` 的 intercept 向派生上下文只暴露读取能力，写接口和具体服务请求会被明确拒绝
+- `ShrinkDataSaverAppInstaller` 仅保留给 ClassicHost 兼容路径，已标记过时
+- 保留 `ShrinkDataSaverBootstrap` 的旧用法兼容；若宿主已接管，旧 bootstrap 会自动退出
+
+## 只读上下文
+
+```csharp
+var communityContext = ctx.Intercept(
+    ShrinkDataSaverAppComponent.ServiceKey,
+    new Dictionary<string, object?>
+    {
+        [ShrinkDataSaverAccess.MetadataKey] = ShrinkDataSaverAccess.ReadOnly
+    });
+
+var reader = communityContext.Get<IShrinkDataSaverReader>(
+    ShrinkDataSaverAppComponent.ServiceKey);
+```
+
+这是服务能力的最小化暴露：只约束通过 `ShrinkCtx.Get` 解析该键的调用方。它不会限制代码绕过上下文后直接访问静态 API，也不构成不可信模组沙箱。
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 85bcc5ac108273c41acdd89c5e2d0291
+TextScriptImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
@@ -0,0 +1,8 @@
+fileFormatVersion: 2
+guid: 79b02908f32342443bd1a986d535a7d2
+folderAsset: yes
+DefaultImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
@@ -0,0 +1,18 @@
+{
+  "name": "ShrinkDataSaver.Integration.App",
+  "rootNamespace": "ShrinkDataSaver.Integration.App",
+  "references": [
+    "ShrinkDataSaver.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: b6cfc65e2b6dc8942866f0f374874564
+AssemblyDefinitionImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
@@ -0,0 +1,65 @@
+#nullable enable
+using System;
+using System.Collections.Generic;
+using Cysharp.Threading.Tasks;
+using ShrinkApp;
+using ShrinkContext;
+using ShrinkDataSaver;
+
+namespace ShrinkDataSaver.Integration.App
+{
+    /// <summary>
+    /// ShrinkDataSaver 的原生 Cordis 组件（阶段 3）：
+    /// - 提供 <c>shrink.service.datasaver</c> 余效应键（门面服务）；
+    /// - 初始化为前向；停用时的终止动作为最终落盘设置（补偿式收尾：
+    ///   存档写入本身跨会话持久，不可严格求逆，以 flush 保证一致性，见论文 6.1 扣留与补偿）；
+    /// - 与经典 ShrinkDataSaverAppInstaller（ModuleId "shrink.datasaver"）二选一使用。
+    /// </summary>
+    public sealed class ShrinkDataSaverAppComponent : IShrinkComponent
+    {
+        public const string ServiceKey = "shrink.service.datasaver";
+        public const string ModuleKey = "app.module.shrink.datasaver";
+
+        private static readonly string[] ProvideKeys = { ModuleKey, ServiceKey };
+
+        public string Name => "shrink.datasaver";
+
+        public IReadOnlyList<string> Inject => Array.Empty<string>();
+
+        public IReadOnlyList<string> Provide => ProvideKeys;
+
+        public async UniTask ApplyAsync(ShrinkCtx ctx, object? config)
+        {
+            // 编辑器/EditMode 环境下 DontDestroyOnLoad 会抛异常，驱动只在播放模式常驻
+            ShrinkDataSaverRuntime.Initialize(new ShrinkDataSaverRuntimeConfig
+            {
+                DontDestroyOnLoadDriver = UnityEngine.Application.isPlaying
+            });
+            var facade = new ShrinkDataSaverService();
+            ctx.Set(ServiceKey, facade, new ShrinkDataSaverAccessPolicy(facade));
+            ctx.Set(ModuleKey, Name);
+
+            if (config is ShrinkAppServices appServices)
+            {
+                appServices.Register(facade);
+                ctx.EffectInverse(() =>
+                {
+                    appServices.TryUnregister(facade);
+                    return UniTask.CompletedTask;
+                });
+            }
+
+            await ctx.EffectAsync(async () =>
+            {
+                await UniTask.CompletedTask;
+                return () =>
+                {
+                    // 终止动作（触发式）：停用时把防抖中的设置写盘。
+                    // 磁盘 IO 在线程池完成，不阻塞停用链；未初始化环境安全跳过（SaveAsync 守卫）。
+                    ShrinkSettings.SaveAsync().Forget();
+                    return UniTask.CompletedTask;
+                };
+            });
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 0ce2260a6cfecb349abe6119fdf37c12
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
@@ -0,0 +1,108 @@
+#nullable enable
+
+using System;
+using Cysharp.Threading.Tasks;
+using ShrinkApp;
+using ShrinkContext;
+
+namespace ShrinkDataSaver.Integration.App
+{
+    [ShrinkAppModuleInstaller]
+    [Obsolete("ClassicHost compatibility only. ContextLoader projects should use ShrinkDataSaverAppComponent from a composition root.")]
+    public sealed class ShrinkDataSaverAppInstaller : IShrinkAppModuleInstaller
+    {
+        public string ModuleId => "shrink.datasaver";
+        public int Order => -2000;
+        public System.Collections.Generic.IReadOnlyList<string> DependsOn => Array.Empty<string>();
+
+        public void RegisterServices(ShrinkAppContext context)
+        {
+            context.Services.Register(new ShrinkDataSaverService());
+        }
+
+        public UniTask InitializeAsync(ShrinkAppContext context)
+        {
+            ShrinkDataSaverRuntime.Initialize();
+            return UniTask.CompletedTask;
+        }
+    }
+
+    /// <summary>不产生存档写入的读取能力。</summary>
+    public interface IShrinkDataSaverReader
+    {
+        int LoadedSlot { get; }
+        int GetRecentSlotIndex();
+        UniTask<int> GetRecommendedContinueSlotAsync();
+        UniTask<SaveMeta[]> GetAllMetaAsync();
+    }
+
+    /// <summary>完整存档能力；社区模组可通过 intercept 被降权为仅 <see cref="IShrinkDataSaverReader"/>。</summary>
+    public interface IShrinkDataSaverWriter : IShrinkDataSaverReader
+    {
+        UniTask SaveSlotAsync(int slotIndex, SaveOptions? options = null);
+        UniTask LoadSlotAsync(int slotIndex, string? decryptionKey = null);
+    }
+
+    public static class ShrinkDataSaverAccess
+    {
+        public const string MetadataKey = "access";
+        public const string ReadOnly = "read-only";
+    }
+
+    public sealed class ShrinkDataSaverService : IShrinkDataSaverWriter
+    {
+        public int LoadedSlot => ShrinkSave.LoadedSlot;
+        public int GetRecentSlotIndex() => ShrinkSave.GetRecentSlotIndex();
+        public UniTask<int> GetRecommendedContinueSlotAsync() => ShrinkSave.GetRecommendedContinueSlotAsync();
+        public UniTask<SaveMeta[]> GetAllMetaAsync() => ShrinkSave.GetAllMetaAsync();
+        public UniTask SaveSlotAsync(int slotIndex, SaveOptions? options = null) => ShrinkSave.SaveSlotAsync(slotIndex, options);
+        public UniTask LoadSlotAsync(int slotIndex, string? decryptionKey = null) => ShrinkSave.LoadSlotAsync(slotIndex, decryptionKey);
+    }
+
+    internal sealed class ShrinkDataSaverReadOnlyService : IShrinkDataSaverReader
+    {
+        private readonly IShrinkDataSaverReader _inner;
+
+        public ShrinkDataSaverReadOnlyService(IShrinkDataSaverReader inner)
+        {
+            _inner = inner ?? throw new ArgumentNullException(nameof(inner));
+        }
+
+        public int LoadedSlot => _inner.LoadedSlot;
+        public int GetRecentSlotIndex() => _inner.GetRecentSlotIndex();
+        public UniTask<int> GetRecommendedContinueSlotAsync() => _inner.GetRecommendedContinueSlotAsync();
+        public UniTask<SaveMeta[]> GetAllMetaAsync() => _inner.GetAllMetaAsync();
+    }
+
+    /// <summary>DataSaver provider 侧的访问介导；仅约束经 ShrinkCtx.Get 取得的能力。</summary>
+    internal sealed class ShrinkDataSaverAccessPolicy : IShrinkCoeffectAccessPolicy
+    {
+        private readonly ShrinkDataSaverReadOnlyService _readOnly;
+
+        public ShrinkDataSaverAccessPolicy(ShrinkDataSaverService full)
+        {
+            _readOnly = new ShrinkDataSaverReadOnlyService(
+                full ?? throw new ArgumentNullException(nameof(full)));
+        }
+
+        public object? Resolve(ShrinkCoeffectAccessContext context, object? value)
+        {
+            if (!context.TryGetMetadata<string>(ShrinkDataSaverAccess.MetadataKey, out var access) ||
+                !string.Equals(access, ShrinkDataSaverAccess.ReadOnly, StringComparison.Ordinal))
+                return value;
+
+            if (typeof(IShrinkDataSaverWriter).IsAssignableFrom(context.RequestedType) ||
+                context.RequestedType == typeof(ShrinkDataSaverService))
+            {
+                throw new ShrinkCoeffectAccessDeniedException(context.Key,
+                    "the current context grants read-only DataSaver access");
+            }
+
+            if (context.RequestedType == typeof(object) || context.RequestedType.IsInstanceOfType(_readOnly))
+                return _readOnly;
+
+            throw new ShrinkCoeffectAccessDeniedException(context.Key,
+                $"read-only DataSaver view cannot satisfy requested type '{context.RequestedType.FullName}'");
+        }
+    }
+}
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 9eea84dd572634c438c99aef69c51d9f
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData:
+  assetBundleName:
+  assetBundleVariant:
@@ -0,0 +1,23 @@
+{
+  "name": "com.cneicy.shrink-datasaver-integration-app",
+  "version": "0.1.0",
+  "displayName": "ShrinkDataSaver - App Integration",
+  "description": "ShrinkDataSaver 与 ShrinkApp 的桥接层，提供宿主接管初始化与服务注册。",
+  "unity": "2022.3",
+  "dependencies": {
+    "com.cneicy.shrink-datasaver": "2.2.0",
+    "com.cneicy.shrink-app-core": "0.1.0",
+    "com.cysharp.unitask": "2.5.10",
+    "com.cneicy.shrink-context-core": "0.1.0"
+  },
+  "keywords": [
+    "save",
+    "integration",
+    "app",
+    "bootstrap"
+  ],
+  "author": {
+    "name": "cneicy",
+    "url": "https://github.com/cneicy"
+  }
+}
@@ -0,0 +1,7 @@
+fileFormatVersion: 2
+guid: 8358963c0e3299e478b163272aa6b09b
+TextScriptImporter:
+  externalObjects: {}
+  userData:
+  assetBundleName:
+  assetBundleVariant: