Developer/FlowScope
17
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b17b6237f3521922a9cf461b3872ad973a036dfc
FlowScope/docs/reviews/p2-phase2-package-preview-report.md
JSD\13999 b17b6237f3 关闭 P2 package editor 收尾
2026-06-08 17:05:05 +08:00

13 KiB
Raw Blame History

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 已满足；后续可以转回框架功能开发。

2026-06-08 P2 package/editor 正式收尾

外部审查结论：P2 package/editor 可以正式收尾。

收尾依据：

  • 当前分支工作树干净，package 版本为 0.2.0-preview.2。
  • v0.2.0-preview.2 tag 已发布，指向 b91fc54。
  • TestFlowScopePackage 已刷新到 v0.2.0-preview.2，且未报告新的 Unity Console 编译错误。
  • Samples~/MainMenuP0 已完成空白消费方手动导入验收。
  • 空白项目 Git URL 安装、最小 smoke probe 编译、Documentation~ 内容补齐、Tests~/EditMode 第一刀均已有记录。

不作为当前收尾阻塞：

  • package Tests~ 全量迁移策略和 PlayMode 测试迁移策略。
  • 是否将 package 作为源码主线。

下一步：关闭 P2 package/editor 工作面，转回 FlowScope 框架功能开发。

Reference in New Issue View Git Blame Copy Permalink