FlowScope Package 目标结构

日期：2026-05-26

本文说明 FlowScope P2 阶段的目标 Unity Package 目录形态，以及第一阶段暂不搬迁 Assets/FlowScope 的边界。本文只描述目标结构与迁移约束，不代表当前仓库已经完成物理搬迁。

当前状态

当前 FlowScope 仍处于项目内开发模式：

My project/
  Assets/
    FlowScope/
      Runtime/
      Addressables/
      Samples/
      Tests/

当前尚未建立标准 Unity Package 根目录，未发现包级 package.json、Samples~、Tests~、Documentation~ 目录。MainMenuP0 示例仍位于 Assets/FlowScope/Samples/MainMenuP0。

目标包根目录

目标包建议使用独立目录承载，例如：

Packages/
  com.flowscope.gamecore/
    package.json
    Runtime/
    Addressables/
    Editor/
    Samples~/
    Tests/
    Documentation~/
    README.md
    CHANGELOG.md
    LICENSE.md

目录职责如下：

目录	职责
`package.json`	Unity Package Manager 元数据，声明包名、显示名、版本、Unity 版本与依赖。
`Runtime/`	FlowScope 核心运行时代码，包括 Container、Feature、GameFlow、Resource、Config、Save、Audio、UI 等能力。
`Addressables/`	Addressables 适配层，提供 `AddressablesResourceBackend` 与 `AddressablesResourceService`。
`Editor/`	只放编辑器诊断、检查、菜单入口等 Editor-only 内容，不承载运行时逻辑。
`Samples~/`	Package Manager 可导入示例，例如 `MainMenuP0`。示例可以依赖 Runtime 与所演示的适配包。
`Tests/`	包内测试，按 EditMode 与 PlayMode 分层保留测试 asmdef。
`Documentation~/`	Package Manager 文档入口，包含安装、接入、诊断与示例说明。

package.json 建议形态

目标包元数据建议保持最小可识别：

{
  "name": "com.flowscope.gamecore",
  "displayName": "FlowScope Game Core",
  "version": "0.2.0",
  "unity": "2022.3",
  "description": "A lightweight Unity game flow, resource, config, save, audio, and UI runtime foundation.",
  "dependencies": {
    "com.cysharp.r3": "https://github.com/Cysharp/R3.git?path=src/R3.Unity/Assets/R3.Unity#1.3.0",
    "com.unity.addressables": "1.21.21",
    "com.unity.ugui": "1.0.0"
  }
}

依赖说明：

com.cysharp.r3 是当前 FlowScope.Runtime.asmdef 直接引用 R3.Unity 的来源。
com.unity.addressables 只服务 FlowScope.Addressables，Runtime 不直接依赖 Addressables。
com.unity.ugui 服务当前 UI 与示例中的 Canvas、Button、Text 等 UGUI 类型。

如果后续发布渠道不接受 Git URL 形式依赖，应在发布前改为团队确认过的 OpenUPM、内网 registry 或嵌入式依赖策略。

asmdef 依赖方向

当前与目标结构都必须保持以下方向：

FlowScope.Runtime
  -> R3.Unity

FlowScope.Addressables
  -> FlowScope.Runtime
  -> Unity.Addressables
  -> Unity.ResourceManager

FlowScope.Editor
  -> FlowScope.Runtime
  -> 需要诊断的编辑器程序集

FlowScope.Samples.MainMenuP0
  -> FlowScope.Runtime
  -> R3.Unity

FlowScope.Tests.EditMode / FlowScope.Tests.PlayMode
  -> 被测程序集

禁止反向依赖：

FlowScope.Runtime 不依赖 FlowScope.Addressables。
FlowScope.Runtime 不依赖 FlowScope.Editor。
FlowScope.Runtime 不依赖 FlowScope.Samples.*。
FlowScope.Runtime 不依赖测试程序集。
Samples 不作为 Runtime 的依赖来源。

AddressablesResourceService 当前命名空间位于 FlowScope.Resources，但文件处于 Assets/FlowScope/Addressables 并编译进 FlowScope.Addressables 程序集；迁移时应保留程序集边界，不应因为命名空间相同而把 Addressables 适配代码并回 Runtime。

第一阶段暂不搬迁 Assets/FlowScope 的原因

P2 第一阶段只建立分发边界、安装接入文档、Addressables 验收与最小 Editor 诊断入口，不做物理搬迁，原因如下：

当前 Assets/FlowScope 已承载 P0/P1 Runtime、Addressables、Samples、Tests 的稳定验证路径。
MainMenuP0 示例、PlayMode 测试与 Unity 生成的 csproj 仍依赖当前 Asset 路径。
一次性移动 Runtime、Samples、Tests 会同时改变 asmdef 路径、资源路径、场景引用、prefab 引用与测试发现路径，容易把包结构问题和运行时回归混在一起。
第一阶段还有并行 worker 处理 Addressables 验收与 Editor 诊断；Package 文档 worker 不应覆盖或移动他们的文件。
先用文档锁定目标结构与依赖方向，可以让第二阶段本地 package 试迁移按批次验证，而不是一次性大搬迁。

建议迁移顺序

后续进入 P2 第二阶段时，建议按以下顺序迁移，每一步都保留独立验证记录：

创建 package 根目录与 package.json，先不移动 Runtime。
将 Runtime/ 移入包目录并验证 FlowScope.Runtime 编译边界。
将 Addressables/ 移入包目录并验证 FlowScope.Addressables 仍只依赖 Runtime 与 Unity Addressables。
将文档迁入 Documentation~/ 或同步保留到仓库 docs/。
将 MainMenuP0 作为包示例迁入 Samples~/MainMenuP0，验证场景、prefab、配置与测试路径。
将 EditMode / PlayMode 测试整理进包内 Tests/，验证 Unity Test Runner 发现与执行。

每一步完成前都应验证 generated csproj build、Unity Test Runner 和关键示例路径；如果某一步失败，应先回到该步骤修复，不继续叠加后续搬迁。

5.5 KiB Raw Blame History Unescape Escape