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,101 @@
+# 架构
+
+## 架构概览
+
+- 这是一个以 Unity 包为边界的 SDK 单仓架构。
+- 主要由三个可分发模块组成：
+  - `ShrinkEventBus`
+  - `ShrinkDataSaver`
+  - `ShrinkDataSaver.Integration.EventBus`
+- 每个模块都按 `Runtime`、`Editor`、`Tests` 或 `CodeGen` 做职责分离。
+
+## 核心分层
+
+- 事件总线层
+  - 公开入口在 `Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`
+  - 负责注册、触发、注销、调试记录和实例注册状态
+- 事件元数据与执行层
+  - `Assets/Modules/ShrinkEventBus/Runtime/EventBase.cs`
+  - `Assets/Modules/ShrinkEventBus/Runtime/ListenerList.cs`
+  - `Assets/Modules/ShrinkEventBus/Runtime/EventHandlerInfo.cs`
+  - `Assets/Modules/ShrinkEventBus/Runtime/EventPool.cs`
+- 编译织入层
+  - `Assets/Modules/ShrinkEventBus/CodeGen/Editor/EventBusILPostProcessor.cs`
+  - 负责给订阅者自动注入 `AutoRegister` 与 `UnregisterInstance`
+- 存档核心层
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSettings.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/SaveTypes.cs`
+- 存储与安全层
+  - `Assets/Modules/ShrinkDataSaver/Runtime/IStorageProvider.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/LocalStorageProvider.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/SaveEncryptor.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/DataSerializer.cs`
+- 版本迁移层
+  - `Assets/Modules/ShrinkDataSaver/Runtime/MigrationChain.cs`
+- Unity 入口层
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaverBootstrap.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaverSettings.cs`
+- 集成桥接层
+  - `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEventBusBridge.cs`
+
+## 主要数据流
+
+## EventBus 数据流
+
+- 注册流：
+  - `[EventBusSubscriber]` + `[EventSubscribe]`
+  - `EventBusILPostProcessor` 在编译期织入
+  - 运行时通过 `EventBus.AutoRegister(this)` 完成注册
+- 触发流：
+  - `EventBus.TriggerEvent` 或 `EventBus.TriggerEventAsync`
+  - 从 `EventCache<TEvent>.List` 取监听列表
+  - `ListenerList` 返回已排序快照
+  - 依优先级逐个执行 handler
+
+## DataSaver 数据流
+
+- 保存流：
+  - `ShrinkSave.SaveSlotAsync`
+  - 序列化所有已注册模块
+  - 可选加密
+  - 经 `IStorageProvider.WriteAsync` 落盘
+  - 触发保存完成或失败事件
+- 加载流：
+  - `ShrinkSave.LoadSlotAsync`
+  - 从 `IStorageProvider.ReadAsync` 读取
+  - 可选解密
+  - 必要时执行 `MigrationChain.Apply`
+  - 分发给每个已注册模块反序列化
+  - 缓存 `_loadedModuleData` 供查询接口使用
+
+## 生命周期入口
+
+- `EventBus` 通过静态构造与运行时初始化参与系统启动。
+- `ShrinkDataSaverBootstrap` 是 `MonoBehaviour` 入口，负责：
+  - 初始化 `ShrinkSettings`
+  - 初始化 `ShrinkSave`
+  - 自动保存轮询
+  - 应用暂停与退出时落盘设置
+- `DataSaverEventBusBridge` 在 `AfterAssembliesLoaded` 订阅 DataSaver 原生事件。
+
+## 架构风格
+
+- 偏“静态门面 + 小型基础设施”的工具库风格。
+- 对业务方暴露的是简单静态 API，而不是依赖注入容器。
+- 内部通过接口和 asmdef 边界做最小抽象，典型例子是 `IStorageProvider`。
+- 编辑器功能与运行时彻底分离，避免运行时代码依赖 UnityEditor。
+
+## 入口判断
+
+- 真正的运行时入口不是某个 `Main.cs`，而是 Unity 生命周期钩子和静态类。
+- 如果要阅读项目行为，优先从以下文件开始：
+  - `Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaverBootstrap.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+  - `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEventBusBridge.cs`
+
+## 结论
+
+- 这套架构的重点是“低侵入接入 Unity 项目”，而不是重框架化。
+- 真正的设计价值在于 asmdef 分层、编译织入、静态门面和模块化存储抽象的组合。
@@ -0,0 +1,66 @@
+# 风险与关注点
+
+## 1. 中文编码已明显受损
+
+- 多个文件在 PowerShell 读取时出现明显乱码，不适合继续作为事实来源直接复用。
+- 典型位置：
+  - `Assets/Modules/ShrinkDataSaver/README.md`
+  - `Assets/Modules/ShrinkDataSaver.Integration.EventBus/README.md`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+  - `Assets/Modules/ShrinkDataSaver/Editor/ShrinkDataSaverEditorWindow.cs`
+- 这会影响对外文档、Unity Inspector 文本、日志可读性和包元数据质量。
+
+## 2. 仓库当前不在 Git 工作树内
+
+- 在 `D:\UnityBuilds\ShrinkSDK` 执行 `git status --short` 返回 “not a git repository”。
+- 这意味着当前无法依赖 Git 记录变更、提交地图文档或审查历史。
+- 如果这个目录只是导出副本，需要明确真实源码仓位置。
+
+## 3. EventBus 缺少自动化测试证据
+
+- 当前测试基本只覆盖 `Assets/Modules/ShrinkDataSaver/Tests`。
+- `ShrinkEventBus` 的以下关键能力没有看到测试文件：
+  - 优先级排序
+  - 取消事件传播
+  - 异步 handler 路径
+  - `EventPool<T>` 复用语义
+  - IL Post Processor 自动注册
+
+## 4. `ShrinkSettings.Unwatch` API 设计存在可用性问题
+
+- `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSettings.cs`
+- `Watch<T>` 内部把 `Action<T>` 包成新的 `Action<object>` 存入 `_watchers`。
+- `Unwatch` 却要求外部传 `Action<object>`，调用者几乎无法用原始 `Action<T>` 精确移除。
+- 这不是理论问题，而是实际 API 不对称。
+
+## 5. 截图路径可能留下纹理对象生命周期问题
+
+- `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+- `CaptureScreenshotAsync` 在截图和缩放时会创建 `Texture2D`，但没有看到显式销毁临时纹理。
+- 在频繁截图存档场景下，值得确认是否会累积内存压力。
+
+## 6. 集成桥接存在重复订阅风险窗口
+
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEventBusBridge.cs`
+- 该桥接在 `RuntimeInitializeOnLoadMethod` 里直接给静态事件追加订阅，没有看到“已初始化”防重复保护。
+- 如果遇到特定域重载配置或重复初始化路径，可能造成重复转发。
+- 这一点需要在真实 Unity 运行模式下验证，而不是仅凭源码静态阅读下结论。
+
+## 7. 集成层版本描述需要复核
+
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/package.json`
+- 该包依赖中声明 `com.cneicy.shrink-eventbus` 版本 `1.0.0`，但本仓库内 `ShrinkEventBus` 包版本是 `1.1.4`。
+- 这不一定是错误，但至少说明版本关系需要人工确认。
+
+## 8. 没有看到 CI 或发布流水线
+
+- 当前未发现 `.github/workflows`、GitLab CI 或 Azure Pipelines 配置。
+- 对一个要分发的 Unity SDK 来说，这意味着：
+  - 测试可能不自动跑
+  - 文档与包版本可能靠手工维护
+  - 编译织入问题更难被持续发现
+
+## 结论
+
+- 当前最现实的三个问题是：编码质量、EventBus 测试缺口、以及若干运行时边界没有自动化验证。
+- 如果后续要继续基于这个仓库规划工作，建议先确认真实源码仓与编码基线，再决定是否进入功能开发或补测试阶段。
@@ -0,0 +1,76 @@
+# 代码约定
+
+## 总体风格
+
+- 代码整体偏 Unity 常规 C# 风格，使用 PascalCase 命名类型与公开成员，私有字段使用前导下划线。
+- 重要入口类大量使用 `public static class`，例如：
+  - `Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSettings.cs`
+  - `Assets/Modules/ShrinkDataSaver/Runtime/MigrationChain.cs`
+- 面向使用者暴露简单 API，内部状态则保留在静态字段中。
+
+## 命名约定
+
+- 事件类统一以 `Event` 结尾，见 `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEvents.cs`。
+- 事件参数类统一以 `EventArgs` 结尾，见 `Assets/Modules/ShrinkDataSaver/Runtime/SaveTypes.cs`。
+- 配置类统一以 `Settings`、`Options`、`Config` 结尾。
+- 编辑器窗口统一以 `EditorWindow` 结尾，见：
+  - `Assets/Modules/ShrinkEventBus/Editor/EventBusViewerWindow.cs`
+  - `Assets/Modules/ShrinkDataSaver/Editor/ShrinkDataSaverEditorWindow.cs`
+
+## 模式约定
+
+- Unity 运行时与编辑器严格分目录、分 asmdef。
+- 用 Attribute 表达声明式能力：
+  - `[EventBusSubscriber]`
+  - `[EventSubscribe]`
+  - `[Cancelable]`
+  - `[HasResult]`
+- 用接口做最小抽象，而不是引入完整容器：
+  - `IStorageProvider`
+  - `ISaveModule`
+  - `ISaveModule<T>`
+
+## 空值与语法习惯
+
+- 仓库同时使用普通 C# 空值判断和 Unity 对象真值判断。
+- `ShrinkEventBus` 某些文件启用了 `#nullable enable`，例如：
+  - `Assets/Modules/ShrinkEventBus/Runtime/EventBase.cs`
+  - `Assets/Modules/ShrinkEventBus/Runtime/ListenerList.cs`
+- 但整个仓库并没有统一启用可空引用，说明这是局部使用而非全局规范。
+
+## 日志与注释
+
+- 日志前缀较统一，常见前缀有：
+  - `[EventBus]`
+  - `[ShrinkDataSaver]`
+  - `[ShrinkDataSaver.Integration]`
+- 源码注释和用户可见菜单文本原本倾向中文。
+- 但当前有多处中文字符串出现乱码，典型位置包括：
+  - `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+  - `Assets/Modules/ShrinkDataSaver/Editor/ShrinkDataSaverEditorWindow.cs`
+  - `Assets/Modules/ShrinkDataSaver/README.md`
+  - `Assets/Modules/ShrinkDataSaver.Integration.EventBus/README.md`
+
+## 错误处理
+
+- 运行时代码多采用“抛异常 + 触发失败事件 + Debug.Log”混合策略。
+- 对非关键模块失败通常记录日志后跳过，对关键模块失败则终止保存，见 `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`。
+- 异步 fire-and-forget 分支会用统一包装打印异常，见 `Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`。
+
+## 测试约定
+
+- 测试位于 `Assets/Modules/ShrinkDataSaver/Tests`。
+- 同时使用 `[Test]` 与 `[UnityTest]`。
+- 测试通过 `MockStorageProvider` 隔离文件系统，见 `Assets/Modules/ShrinkDataSaver/Tests/MockStorageProvider.cs`。
+
+## 可读性与组织
+
+- 单文件职责通常比较集中，尤其是 Runtime 层。
+- 但 `ShrinkSave.cs`、`ShrinkDataSaverEditorWindow.cs` 体量偏大，已经承担多个职责。
+
+## 结论
+
+- 当前代码约定的关键词是：静态门面、Attribute 驱动、asmdef 分层、中文日志、最小抽象。
+- 如果后续继续扩展，最需要先统一的是编码、可空规范和部分大文件拆分标准。
@@ -0,0 +1,75 @@
+# 外部集成
+
+## 总览
+
+- 这个仓库外部依赖不多，主要是 Unity 运行时、Unity 编译管线、文件系统和少量第三方包。
+- 没有发现数据库、网络 API、认证服务、WebHook、云函数等后端集成代码。
+
+## Unity 平台能力
+
+- `Assets/Modules/ShrinkEventBus/Runtime/EventAutoRegHelper.cs`
+  - 使用 `RuntimeInitializeOnLoadMethod` 参与运行时初始化。
+- `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaverBootstrap.cs`
+  - 依赖 `Application.persistentDataPath`
+  - 依赖 `DontDestroyOnLoad`
+  - 在 `OnApplicationQuit` 和 `OnApplicationPause` 里刷写设置
+- `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaverSettings.cs`
+  - 使用 `Resources.Load`
+  - 编辑器下回退到 `UnityEditor.AssetDatabase`
+
+## 第三方包
+
+- `com.cysharp.unitask`
+  - 用于异步事件处理与异步文件操作
+  - 关键落点：`Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`
+  - 关键落点：`Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+  - 关键落点：`Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSettings.cs`
+- `com.unity.nuget.newtonsoft-json`
+  - 用于 JSON 序列化、JObject 迁移链和弱类型数据缓存
+  - 关键落点：`Assets/Modules/ShrinkDataSaver/Runtime/DataSerializer.cs`
+  - 关键落点：`Assets/Modules/ShrinkDataSaver/Runtime/MigrationChain.cs`
+  - 关键落点：`Assets/Modules/ShrinkDataSaver/Runtime/SaveTypes.cs`
+
+## 编译管线集成
+
+- `Assets/Modules/ShrinkEventBus/CodeGen/Editor/EventBusILPostProcessor.cs`
+  - 接入 `Unity.CompilationPipeline.Common.ILPostProcessing`
+  - 使用 Mono.Cecil 改写带 `[EventBusSubscriber]` 的 `MonoBehaviour`
+- `Assets/Modules/ShrinkEventBus/CodeGen/Editor/PostProcessorAssemblyResolver.cs`
+- `Assets/Modules/ShrinkEventBus/CodeGen/Editor/PostProcessorReflectionImporter.cs`
+
+## 模块间集成
+
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEventBusBridge.cs`
+  - 将 `ShrinkDataSaver` 的原生事件桥接到 `ShrinkEventBus`
+  - 桥接方向是单向的：`ShrinkDataSaver -> ShrinkEventBus`
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEvents.cs`
+  - 定义桥接后的 9 个事件类型
+
+## 本地存储集成
+
+- `Assets/Modules/ShrinkDataSaver/Runtime/IStorageProvider.cs`
+  - 定义存储抽象
+- `Assets/Modules/ShrinkDataSaver/Runtime/LocalStorageProvider.cs`
+  - 当前唯一实现
+  - 使用本地文件系统读写、删除、列举文件
+  - 采用 `.tmp` 文件再替换的方式降低写坏文件的概率
+
+## 编辑器集成
+
+- `Assets/Modules/ShrinkEventBus/Editor/EventBusViewerWindow.cs`
+  - 通过 Unity 菜单打开事件查看器
+- `Assets/Modules/ShrinkDataSaver/Editor/ShrinkDataSaverEditorWindow.cs`
+  - 通过 Unity 菜单操作设置与存档
+
+## 未发现的外部依赖
+
+- 未发现 HTTP 客户端调用。
+- 未发现数据库连接代码。
+- 未发现 OAuth、Steamworks、Firebase、PlayFab、Addressables 等 SDK 实际接入代码。
+- README 中提到 Steam Cloud 场景，但当前仓库里没有直接调用 Steam API 的实现。
+
+## 结论
+
+- 该仓库的“集成”重点不是远程服务，而是 Unity 生命周期、编译后处理、文件系统和模块间桥接。
+- 如果后续要扩展云存档、远程同步或遥测，这里目前只有存储接口和事件桥接两个自然扩展点。
@@ -0,0 +1,5 @@
+# 2026-05-23 代码地图（已归档）
+
+此目录原位于 `.planning/codebase/`，现整体归档。它早于 ContextLoader、Cordis 阶段 0 至 5、当前包版本和根仓库 Git 修复，其中关于仓库不是 Git、测试规模、模块布局和风险状态的描述均不再可信。
+
+当前架构见仓库根 `DESIGN.md`。
@@ -0,0 +1,74 @@
+# 技术栈
+
+## 项目定位
+
+- 这是一个 Unity SDK 型仓库，不是完整游戏项目。
+- 当前 Unity 版本是 `2022.3.62f3`，见 `ProjectSettings/ProjectVersion.txt`。
+- 当前仅配置了一个示例场景 `Assets/Scenes/SampleScene.unity`，见 `ProjectSettings/EditorBuildSettings.asset`。
+
+## 运行时基础
+
+- 核心语言是 C#，通过 Unity asmdef 拆分模块。
+- 根解决方案是 `ShrinkSDK.sln`，包含 `ShrinkEventBus`、`ShrinkDataSaver`、集成层、编辑器扩展和测试项目。
+- 运行时代码主要在：
+  - `Assets/Modules/ShrinkEventBus/Runtime`
+  - `Assets/Modules/ShrinkDataSaver/Runtime`
+  - `Assets/Modules/ShrinkDataSaver.Integration.EventBus`
+
+## Unity 包依赖
+
+- `Packages/manifest.json` 中可确认以下关键依赖：
+  - `com.cysharp.unitask`
+  - `com.unity.nuget.newtonsoft-json`
+  - `com.unity.test-framework`
+  - `com.unity.ugui`
+  - `com.unity.textmeshpro`
+  - `com.unity.timeline`
+  - `com.unity.render-pipelines.universal`
+
+## 仓库内 SDK 包
+
+- `Assets/Modules/ShrinkEventBus/package.json`
+  - 包名 `com.cneicy.shrink-eventbus`
+  - 版本 `1.1.4`
+  - 依赖 `UniTask`
+- `Assets/Modules/ShrinkDataSaver/package.json`
+  - 包名 `com.cneicy.shrink-datasaver`
+  - 版本 `2.0.0`
+  - 依赖 `UniTask` 与 `Newtonsoft.Json`
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/package.json`
+  - 包名 `com.cneicy.shrink-datasaver-integration-eventbus`
+  - 版本 `2.0.0`
+  - 依赖 `ShrinkDataSaver` 与 `ShrinkEventBus`
+
+## 程序集拆分
+
+- `Assets/Modules/ShrinkEventBus/Runtime/ShrinkEventBus.Runtime.asmdef`
+- `Assets/Modules/ShrinkEventBus/Editor/ShrinkEventBus.Editor.asmdef`
+- `Assets/Modules/ShrinkEventBus/CodeGen/Editor/Unity.ShrinkEventBus.CodeGen.asmdef`
+- `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaver.Runtime.asmdef`
+- `Assets/Modules/ShrinkDataSaver/Editor/ShrinkDataSaver.Editor.asmdef`
+- `Assets/Modules/ShrinkDataSaver/Tests/ShrinkDataSaver.Tests.asmdef`
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/ShrinkDataSaver.Integration.EventBus.asmdef`
+
+## 关键技术点
+
+- 事件系统使用泛型静态缓存与对象池优化热路径，入口在 `Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`。
+- 自动注册依赖 Unity IL Post Processor 与 Mono.Cecil，入口在 `Assets/Modules/ShrinkEventBus/CodeGen/Editor/EventBusILPostProcessor.cs`。
+- 存档系统使用 `UniTask` 处理异步 IO，入口在 `Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`。
+- 序列化基于 `Newtonsoft.Json`，入口在 `Assets/Modules/ShrinkDataSaver/Runtime/DataSerializer.cs`。
+- 加密使用 AES-CBC + PBKDF2-SHA256，入口在 `Assets/Modules/ShrinkDataSaver/Runtime/SaveEncryptor.cs`。
+- 本地存储基于 `Application.persistentDataPath` 与文件系统，入口在 `Assets/Modules/ShrinkDataSaver/Runtime/LocalStorageProvider.cs`。
+
+## 编辑器与测试
+
+- 编辑器工具包括：
+  - `Assets/Modules/ShrinkEventBus/Editor/EventBusViewerWindow.cs`
+  - `Assets/Modules/ShrinkDataSaver/Editor/ShrinkDataSaverEditorWindow.cs`
+- 当前扫描到运行时相关文件约 `62` 个，编辑器相关文件约 `16` 个。
+- 测试主要集中在 `Assets/Modules/ShrinkDataSaver/Tests`，当前统计到 `[Test]`/`[UnityTest]` 标记共 `78` 个。
+
+## 结论
+
+- 这是一个围绕 Unity 包分发设计的多模块 SDK 仓库。
+- 技术选择偏向 Unity 原生能力 + `UniTask` + `Newtonsoft.Json`，没有引入重量级 DI、状态机或第三方测试平台。
@@ -0,0 +1,119 @@
+# 目录结构
+
+## 顶层结构
+
+- `Assets`
+  - 核心源码、编辑器扩展、测试、示例场景和包描述文件都在这里
+- `Packages`
+  - Unity 包清单与锁文件
+- `ProjectSettings`
+  - Unity 版本、渲染、输入、构建场景等项目配置
+- `Library`、`Temp`、`Logs`、`obj`
+  - Unity 生成目录，不属于源码地图重点
+
+## Assets 下的主要模块
+
+## `Assets/Modules/ShrinkEventBus`
+
+- `Runtime`
+  - 事件总线核心实现
+- `Editor`
+  - 事件查看器窗口
+- `CodeGen/Editor`
+  - IL Post Processor 与 Cecil 辅助类
+- `README.md`
+- `package.json`
+- `Benchmark.txt`
+
+## `Assets/Modules/ShrinkDataSaver`
+
+- `Runtime`
+  - 存档、设置、迁移、加密、存储抽象与配置
+- `Editor`
+  - 数据查看器窗口
+- `Tests`
+  - NUnit 与 Unity Test Runner 测试
+- `README.md`
+- `package.json`
+
+## `Assets/Modules/ShrinkDataSaver.Integration.EventBus`
+
+- `DataSaverEvents.cs`
+- `DataSaverEventBusBridge.cs`
+- `README.md`
+- `package.json`
+- `ShrinkDataSaver.Integration.EventBus.asmdef`
+
+## `Assets/Modules/ShrinkModFramework`
+
+- `Editor/Scaffolding`
+  - Mod SDK 导出器、外部 DLL 模组模板生成器、仓库内模组模板生成器与模板文件
+- `Runtime/Bootstrap`
+  - 自动启动、运行时驱动、设置资产与可选场景入口
+- `Runtime/Core`
+  - `IShrinkMod`、`ShrinkModBase`、`ShrinkModContext`、`ShrinkModHandle`
+- `Runtime/Metadata`
+  - 模组特性、依赖、状态、版本信息
+- `Runtime/Registry`
+  - 模组注册表与注册表管理器
+- `Runtime/Loading`
+  - 模组发现、依赖排序、外部 DLL 装载、Harmony 接入
+- `Runtime/Network`
+  - 模组网络抽象层
+- `Runtime/Integration`
+  - 对 `ShrinkEventBus`、`ShrinkCommand`、`ShrinkNetwork` 的可选自动接入胶水
+- `README.md`
+- `package.json`
+- `Runtime/ShrinkModFramework.Runtime.asmdef`
+
+## 其他目录
+
+- `Assets/Scenes/SampleScene.unity`
+  - 当前唯一启用的示例场景
+- `Assets/Settings`
+  - URP 资源和场景模板
+
+## 关键文件入口
+
+- 事件系统入口：`Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`
+- 事件订阅反射注册：`Assets/Modules/ShrinkEventBus/Runtime/EventBusRegHelper.cs`
+- 事件订阅编译织入：`Assets/Modules/ShrinkEventBus/CodeGen/Editor/EventBusILPostProcessor.cs`
+- 存档系统入口：`Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSave.cs`
+- 设置系统入口：`Assets/Modules/ShrinkDataSaver/Runtime/ShrinkSettings.cs`
+- Unity 启动器：`Assets/Modules/ShrinkDataSaver/Runtime/ShrinkDataSaverBootstrap.cs`
+- 模块桥接入口：`Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEventBusBridge.cs`
+- 模组框架启动入口：`Assets/Modules/ShrinkModFramework/Runtime/Bootstrap/ShrinkModRuntimeBootstrap.cs`
+- 模组装载入口：`Assets/Modules/ShrinkModFramework/Runtime/Loading/ShrinkModLoader.cs`
+- 模组模板生成入口：`Assets/Modules/ShrinkModFramework/Editor/Scaffolding/ShrinkExternalModTemplateGenerator.cs`
+- 仓库内模组模板生成入口：`Assets/Modules/ShrinkModFramework/Editor/Scaffolding/ShrinkInRepoModTemplateGenerator.cs`
+- Mod SDK 导出入口：`Assets/Modules/ShrinkModFramework/Editor/Scaffolding/ShrinkModSdkExporter.cs`
+
+## 命名组织规律
+
+- 包名与目录名基本一一对应：`ShrinkEventBus`、`ShrinkDataSaver`、`ShrinkDataSaver.Integration.EventBus`
+- `ShrinkModFramework` 继续遵循同样规则，并在 `Runtime` 下进一步按职责拆子目录
+- 命名空间与 asmdef 名称基本一致：
+  - `ShrinkEventBus`
+  - `ShrinkEventBus.Editor`
+  - `ShrinkEventBus.CodeGen`
+  - `ShrinkDataSaver`
+  - `ShrinkDataSaver.Editor`
+  - `ShrinkDataSaver.Integration`
+- 编辑器专属代码全部放在 `Editor` 目录下，符合 Unity 约定。
+
+## 解决方案结构
+
+- `ShrinkSDK.sln` 暴露了 8 个 C# 工程：
+  - `ShrinkEventBus.Runtime`
+  - `ShrinkEventBus.Editor`
+  - `Unity.ShrinkEventBus.CodeGen`
+  - `ShrinkDataSaver.Runtime`
+  - `ShrinkDataSaver.Editor`
+  - `ShrinkDataSaver.Tests`
+  - `ShrinkDataSaver.Integration.EventBus`
+  - `Assembly-CSharp`
+
+## 结论
+
+- 结构上最值得注意的是：这是按“可发布 Unity 包”来组织，而不是按单一游戏功能目录来组织。
+- 阅读顺序建议先从 `Runtime`，再到 `Editor`，最后看 `Tests` 与 `README.md`。
@@ -0,0 +1,65 @@
+# 测试情况
+
+## 当前测试布局
+
+- 测试集中在 `Assets/Modules/ShrinkDataSaver/Tests`。
+- 测试程序集定义见 `Assets/Modules/ShrinkDataSaver/Tests/ShrinkDataSaver.Tests.asmdef`。
+- 该 asmdef：
+  - 仅在 `Editor` 平台启用
+  - 依赖 `UnityEngine.TestRunner` 与 `UnityEditor.TestRunner`
+  - 通过 `UNITY_INCLUDE_TESTS` 控制
+  - 额外引用 `Newtonsoft.Json.dll`
+
+## 已覆盖模块
+
+- `Assets/Modules/ShrinkDataSaver/Tests/ShrinkSaveTests.cs`
+  - 模块注册
+  - 保存、加载、删除
+  - 事件触发
+  - 关键模块失败行为
+  - 版本迁移事件
+  - 查询接口
+  - 自动保存间隔
+  - 元数据读取
+  - `LoadedSlot` 状态
+  - 多模块往返
+- `Assets/Modules/ShrinkDataSaver/Tests/ShrinkSettingsTests.cs`
+  - 设置读写、监听、持久化与防抖行为
+- `Assets/Modules/ShrinkDataSaver/Tests/SaveEncryptorTests.cs`
+  - 加解密往返、错误密码、空输入等边界
+- `Assets/Modules/ShrinkDataSaver/Tests/MigrationChainTests.cs`
+  - 注册、链式迁移、缺步、回滚
+- `Assets/Modules/ShrinkDataSaver/Tests/DataSerializerTests.cs`
+  - JSON 序列化基础行为
+- `Assets/Modules/ShrinkDataSaver/Tests/SaveTypesTests.cs`
+  - 类型层面的默认值与结构行为
+
+## 测试风格
+
+- 同时使用同步 NUnit 测试和基于 `UniTask.ToCoroutine` 的 `UnityTest`。
+- 使用 `MockStorageProvider` 模拟存储后端，避免真实磁盘依赖。
+- 通过 `ResetForTesting()`、`MigrationChain.Clear()` 等内部重置方法控制静态状态污染。
+
+## 当前数量
+
+- 当前扫描到 `[Test]` 与 `[UnityTest]` 标记共 `78` 个。
+- 测试密度主要集中在 `ShrinkDataSaver`，并未均匀覆盖整个仓库。
+
+## 明显缺口
+
+- 没有看到 `ShrinkEventBus` 对应的测试目录。
+- `EventBus` 的优先级排序、取消传播、异步处理、自动注册织入结果，没有自动化测试证据。
+- 编辑器窗口也没有独立测试。
+- 没有发现 CI 配置文件，说明测试是否自动执行未知，当前更像本地手动运行模式。
+
+## 适合后续补强的位置
+
+- `Assets/Modules/ShrinkEventBus/Runtime/EventBus.cs`
+- `Assets/Modules/ShrinkEventBus/Runtime/ListenerList.cs`
+- `Assets/Modules/ShrinkEventBus/CodeGen/Editor/EventBusILPostProcessor.cs`
+- `Assets/Modules/ShrinkDataSaver.Integration.EventBus/DataSaverEventBusBridge.cs`
+
+## 结论
+
+- 这个仓库的测试现状可以概括为：`ShrinkDataSaver` 覆盖较扎实，`ShrinkEventBus` 和集成层明显偏弱。
+- 如果后续要发包或稳定演进，优先级最高的补测点是 EventBus 核心行为与编译织入结果。