# 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~/EditMode` 第一刀 smoke 测试，但尚未迁移完整 Runtime/EditMode/PlayMode 测试。
4. Addressables 测试资源已统一到主项目测试目录的 `Resources/Fixtures/Addressables`，后续迁移 Tests 前需要决定是否镜像到 package `Tests~`。
5. 仍需在一个真正空白 Unity 项目中重复 Git package 接入；FishingFrenzy 是真实消费方，但不是空白项目。

## 2026-06-06 验证补充

本轮按 P2 收尾顺序补做以下检查：

1. Addressables 测试资源 entry
   - `Default Local Group.asset` 曾出现本地未提交改动，内容为清空 `FlowScope.Tests.Addressables.Text` 对应 entry。
   - 已确认该改动不是预期变更，并恢复到干净工作树；当前 `git status` 无该文件 diff。

2. 静态与生成 csproj 编译验证
   - `Packages/com.flowscope.gamecore/package.json` 可被 `ConvertFrom-Json` 解析。
   - `Packages/com.flowscope.gamecore/Tests~/EditMode/FlowScope.PackageTests.EditMode.asmdef` 可被 `ConvertFrom-Json` 解析。
   - `FlowScope.Runtime.csproj`、`FlowScope.Addressables.csproj`、`FlowScope.Tests.EditMode.csproj`、`FlowScope.Tests.PlayMode.csproj` 均可 `dotnet build --no-restore` 成功。
   - 编译仍有 Unity 生成 csproj 常见的 `MSB3277` 引用版本冲突 warning，但无错误。

3. Unity Test Runner
   - UnitySkills `http://127.0.0.1:8090/health` 当前不可连接。
   - 去掉 `-quit` 后重跑 Unity batchmode EditMode Test Runner，已生成 `C:\tmp\flowscope-p2-editmode-retry3-results.xml`。
   - 结果：`testcasecount=56`，`result=Passed`，`passed=56`，`failed=0`，`skipped=0`。
   - 注意：Unity 在保存结果后未自动退出，已手动停止残留 batchmode 进程；这不影响本次 XML 结果判定。

4. 空白 Unity 项目 Git URL 复验
   - 使用 `C:\tmp\flowscope-upm-probe-p2` 手工创建最小 probe 并写入 Git package manifest 后，Unity batchmode 能启动，但 UPM 在更新 manifest 时失败：`The "path" argument must be of type string. Received undefined`，未生成 `packages-lock.json`。
   - 该 probe 不是由 Unity Hub/template 正式创建的完整项目，因此本轮结果不能判定为 FlowScope package 安装失败，只能记录为“手工最小 probe 不足以完成空白项目 gate”。
   - 后续仍需使用一个真正由 Unity 创建的空白项目复验 Git URL 安装。

## 2026-06-06 空白项目复验补充

用户已在仓库内创建完整 Unity 空白项目 `TestFlowScopePackage`，本轮将该目录加入根 `.gitignore`，避免误提交验证工程。

验证步骤与结果：

1. 在 `TestFlowScopePackage/Packages/manifest.json` 写入 FlowScope Git package、R3 Git package、Unity NuGet scoped registry 和 `org.nuget.r3`。
2. Unity batchmode 打开项目时 UPM 失败：`The "path" argument must be of type string. Received undefined`，未生成可用的 FlowScope package lock。
3. 为定位原因，分别移除 FlowScope、R3 Git package、`org.nuget.r3`、scoped registry 做隔离验证。
4. 清理 `Library`、`Temp` 和 `Packages/packages-lock.json` 后，使用不含 FlowScope/R3/NuGet 的原始 manifest 重跑，仍出现同一个 UPM resolve 错误。

当前判断：该错误不是 FlowScope Git package 本身触发；`TestFlowScopePackage` 在原始 manifest 下也无法完成 UPM resolve。空白项目 gate 需要先在 Unity GUI 中确认该项目自身 Package Manager 可正常打开且不报错，再继续验证 FlowScope Git package。

## 2026-06-06 空白项目复验通过

用户使用 Unity GUI 打开并关闭 `TestFlowScopePackage` 后，项目自身 UPM 状态恢复正常；随后继续复验 FlowScope Git package。

验证结果：

1. `Packages/packages-lock.json` 已解析出：
   - `com.flowscope.gamecore`
     - source：`git`
     - version：`ssh://git@git.zz.com:2222/Developer/FlowScope.git?path=/Packages/com.flowscope.gamecore#v0.2.0-preview.1`
     - hash：`31641b2c35d1d6c4f056772f144562007f0d0782`
   - `com.cysharp.r3`
     - source：`git`
     - hash：`329ca7915713417f2e0837b0e0a80b4da074db4a`
   - `org.nuget.r3`
     - source：`registry`
     - version：`1.3.0`
2. Unity batchmode 导入验证通过：
   - log：`C:\tmp\flowscope-testpackage-import-aftergui.log`
   - exit code：`0`
   - 日志可见 `com.flowscope.gamecore@...#v0.2.0-preview.1` 被注册到 `Library/PackageCache/com.flowscope.gamecore@31641b2c35`
3. 空白消费方 smoke probe 编译验证通过：
   - 文件：`TestFlowScopePackage/Assets/FlowScopePackageSmokeProbe.cs`
   - log：`C:\tmp\flowscope-testpackage-smoke-compile2.log`
   - exit code：`0`
   - probe 覆盖 `FlowScope.Container.Container`、`FlowScope.Resources.ResourceService`、`FlowScope.Resources.IResourceService`、`FlowScope.Addressables.AddressablesResourceBackend`。

非阻塞注意事项：

- batchmode 日志提示 `Packages/com.flowscope.gamecore/Documentation~` 对应 `.meta` 存在但目录缺失，Unity 自动创建了该空目录。下一个 preview tag 前建议补齐 `Documentation~` 实际内容或移除空目录 `.meta`，避免消费方导入时出现该提示。

## 2026-06-06 当前提交导入与 sample 验收尝试

为验证下一个 preview tag 是否能消除 `Documentation~` 空目录提示，临时将忽略工程 `TestFlowScopePackage` 的 manifest 指向当前提交：

- `ssh://git@git.zz.com:2222/Developer/FlowScope.git?path=/Packages/com.flowscope.gamecore#e6d1f00e235a6d7cd81d84cbe9a1f8be2d27b89e`

验证观察：

1. Unity 默认 `Editor.log` 可见 `Packages/com.flowscope.gamecore/Documentation~` 被正常导入，未再出现 `Documentation~.meta` 存在但目录缺失的提示。
2. Unity 默认 `Editor.log` 可见 `Packages/com.flowscope.gamecore/Runtime`、`Addressables`、`Editor`、`README.md`、`CHANGELOG.md`、`package.json` 等内容被导入。
3. 未发现 `error CS`、`Compilation failed`、`Scripts have compiler errors` 等编译错误日志。

未完成项：

- 尝试通过 `FlowScopeSampleImportVerifier.ImportMainMenuP0` 自动导入 `Samples~/MainMenuP0`，但 `TestFlowScopePackage` 的 batchmode 没有稳定生成验证脚本对应的 Editor 程序集，也没有执行到 sample import 日志。
- 因此本轮只能确认“当前提交已补齐 `Documentation~` 导入内容”，不能宣称 `Samples~/MainMenuP0` 消费方导入验收通过。

后续处理：

1. 下一个 preview tag 可以覆盖 `Documentation~` 空目录 warning。
2. `Samples~/MainMenuP0` 仍需要在 Unity GUI 的 Package Manager 中人工导入，或在验证工程稳定生成 Editor 程序集后再跑自动导入脚本。

## 2026-06-08 MainMenuP0 手动导入与验证脚本修正

用户已在 `TestFlowScopePackage` 通过 Unity GUI 手动导入 `Samples~/MainMenuP0`，本地可见导入目录：

- `TestFlowScopePackage/Assets/Samples/FlowScope Game Core/0.2.0-preview.1/MainMenuP0`

导入后曾出现两个编译错误，来源均为忽略工程中的临时验证脚本 `Assets/Editor/FlowScopeSampleImportVerifier.cs`，不是 FlowScope package 本体：

1. `CS0104: 'PackageInfo' is an ambiguous reference between 'UnityEditor.PackageManager.PackageInfo' and 'UnityEditor.PackageInfo'`
   - 修正：使用完整类型名 `UnityEditor.PackageManager.PackageInfo.FindForAssetPath(...)`。
2. `CS0019: Operator '==' cannot be applied to operands of type 'Sample' and '<null>'`
   - 修正：`UnityEditor.PackageManager.UI.Sample` 不能按 `null` 判断；改用 `string.IsNullOrEmpty(sample.displayName)` 判断是否找到 sample。

当前状态：

- `MainMenuP0` sample 已完成手动导入。
- 临时验证脚本已在 `TestFlowScopePackage` 内修正。
- Unity batchmode 在当前机器状态下仍未稳定生成指定 log 并退出，因此还不能把自动 batchmode sample 验收记为通过。

## 2026-06-08 MainMenuP0 手动导入验收通过

用户重新打开 `TestFlowScopePackage` 后确认：

- Unity Console 已无 `FlowScopeSampleImportVerifier.cs` 的 `CS0104` / `CS0019` 编译错误。
- `Samples~/MainMenuP0` 已通过 Unity GUI 手动导入。

本轮判定：

- `Samples~/MainMenuP0` 消费方手动导入验收通过。
- 自动 batchmode sample import 仍不作为通过项记录，因为当前机器状态下 batchmode 未稳定生成指定 log 并退出。
- P2 package preview 可以进入 `0.2.0-preview.2` 版本收口；该版本覆盖空白项目 Git URL 安装、smoke probe 编译、`Documentation~` 内容补齐、`Tests~/EditMode` 第一刀和 `MainMenuP0` 手动导入验收。

## 2026-06-08 preview.2 消费方刷新确认

用户在 `TestFlowScopePackage` 中将 FlowScope package 刷新到 `v0.2.0-preview.2` 后确认：

- Package Manager 显示版本已从 `0.2.0-preview.1` 更新到 `0.2.0-preview.2`。
- 本轮刷新过程中未报告新的 Unity Console 编译错误。

问题原因记录：

- 之前未更新到 preview.2 的原因是 `TestFlowScopePackage/Packages/manifest.json` 仍指向临时验证提交 `e6d1f00e235a6d7cd81d84cbe9a1f8be2d27b89e`，该提交内 package 版本仍为 `0.2.0-preview.1`。
- 已将该忽略工程的 manifest 改为正式 tag：`ssh://git@git.zz.com:2222/Developer/FlowScope.git?path=/Packages/com.flowscope.gamecore#v0.2.0-preview.2`，并清理旧 `packages-lock.json` 与旧 `Library/PackageCache` 后完成刷新。

本轮判定：

- `v0.2.0-preview.2` 已完成空白消费方刷新确认。
- P2 package/editor 的 package preview 收口 gate 已满足；后续可以转回框架功能开发。