FlowScope/docs/reviews/p2-phase2-package-preview-report.md

FlowScope P2 第二阶段 Package Preview 记录

日期：2026-06-04

本轮范围

本轮承接 P2 第一阶段后的 package 试迁移工作，重点不是改 Runtime API，而是把 FlowScope Git package 从“仓库内结构存在”推进到“真实消费方可用”的 preview 状态。

已完成事项

1. FlowScope package preview tag

   • tag：v0.2.0-preview.1
   • 提交：31641b2c35d1d6c4f056772f144562007f0d0782
   • 远端：ssh://git@git.zz.com:2222/Developer/FlowScope.git

2. 消费方 Git package 接入

   • 消费项目：C:\Users\13999\Documents\FishingFrenzy\FishingFrenzy
   • package URL：ssh://git@git.zz.com:2222/Developer/FlowScope.git?path=/Packages/com.flowscope.gamecore#v0.2.0-preview.1
   • R3 依赖：同时保留 com.cysharp.r3 与 org.nuget.r3。
   • Unity NuGet registry：https://unitynuget-registry.openupm.com，scope 为 org.nuget。

3. 最小消费方验证脚本

   • 文件：FishingFrenzy/Assets/Scripts/FlowScopePackageSmokeProbe.cs
   • 覆盖：编译期引用 FlowScope.Container.Container、FlowScope.Flow.GameFlow、FlowScope.Addressables.AddressablesResourceBackend 与 FlowScope.Resources.IResourceService。
   • 运行方式：挂到临时 GameObject 后，通过组件右键菜单 FlowScope/Validate Package References 手动执行。
   • 设计边界：不自动挂场景、不自动启动、不加载真实业务资源，只证明消费方工程能引用 package API。

4. 消费方验证结果

   • UnitySkills debug_check_compilation：isCompiling = false，isUpdating = false。
   • UnitySkills debug_get_errors：count = 0。
   • UnitySkills console_get_stats：errors = 0。
   • UnitySkills package_list：可见 com.flowscope.gamecore，版本为 0.2.0-preview.1。

5. 安装文档同步

   • Packages/com.flowscope.gamecore/README.md
   • Packages/com.flowscope.gamecore/Documentation~/installation.md
   • 已改为正式 SSH URL、preview tag、Unity NuGet registry 和 org.nuget.r3 说明。

本轮踩坑记录

1. FlowScope remote 曾残留旧仓库地址

   • 本地 origin 一度指向旧的 BombGameFramework 地址。
   • 已改为 ssh://git@git.zz.com:2222/Developer/FlowScope.git 后再推送 tag。

2. R3 Git package 不等于完整 R3 依赖

   • com.cysharp.r3 提供 Unity 适配层。
   • R3.dll 与 BCL DLL 需要由 org.nuget.r3 及其 NuGet 传递依赖提供。

3. Git package 必须保留 Unity .meta

   • preview tag 基于已补齐 package 顶层 .meta 的提交。
   • 缺少 .meta 时，消费方会出现 immutable package 相关导入错误。

剩余 P2 第二阶段事项

1. 当前 preview tag 已可被消费方解析，但 tag 内 package 文档仍是打 tag 当时的快照。后续如果要让 package 内文档也随 tag 发布，应在文档修正后创建下一个 preview tag。
2. 已在后续切片镜像 Samples~/MainMenuP0，但尚未在消费方导入 package sample 做人工验收。
3. 还没有迁移 package 内 Tests。
4. Addressables 测试资源已统一到主项目测试目录的 Resources/Fixtures/Addressables，后续迁移 Tests 前需要决定是否镜像到 package Tests~。
5. 仍需在一个真正空白 Unity 项目中重复 Git package 接入；FishingFrenzy 是真实消费方，但不是空白项目。