unity-yooasset-design

**调用此模块中的任何技能前：**如果你准备根据技能名称或描述猜测参数后调用技能，请停止——先阅读此文件（或通过 GET /skills/recommend?includeSchema=true 获取其架构）。如果你已经从 recommend/schema 获取了参数定义，则可以直接进行 dryRun。

触发条件

• 编写或审查 YooAsset 代码
• 初始化 package
• 通过句柄加载资源
• 配置热更/下载
• 选择运行模式
• 编写或审查 YooAsset 代码、初始化 package、用句柄加载资源、配置热更/下载、选择运行模式

YooAsset - 设计规则

参考模块。每条规则均提炼自 YooAsset v2.3.18（2025-12-04）在 Assets/YooAsset/ 中的源码。每条规则都引用了具体文件和行号，确保推理可审查，且 AI 不会依据过时记忆自行发挥。

模式：仅提供文档——没有需要限制的 REST 技能；在任何运行模式（Approval / Auto / Bypass）下均可自由加载。

何时加载此模块

在编写或审查以下任意内容前加载：

• YooAssets.Initialize() / CreatePackage() / Destroy() 引导代码
• 默认 package 快捷方式：YooAssets.SetDefaultPackage(...)、YooAssets.LoadAssetAsync(...)、YooAssets.CreateResourceDownloader(...)
• 使用 5 种 EPlayMode 变体中的任意一种调用 ResourcePackage.InitializeAsync(...)
• LoadAssetSync/Async、LoadSubAssetsAsync、LoadAllAssetsAsync、LoadRawFileAsync、LoadSceneAsync 及其对应的 Handle 用法 / 释放
• 补丁流程：RequestPackageVersionAsync → UpdatePackageManifestAsync → CreateResourceDownloader → BeginDownload
• FileSystemParameters 的构造（Buildin / Cache / Editor / WebServer / WebRemote / 自定义）
• IDecryptionServices / IRemoteServices / IWebDecryptionServices 的实现
• 编辑器侧的 AssetBundleBuilder.Run(...) 和 AssetBundleCollector 配置
• 任何基于 EOperationStatus / EFileClearMode / PackageDetails 进行分支处理的代码

关键规则摘要（即使跳过子文档也请牢记）

#	规则	源代码锚点
1	在任何 CreatePackage() 之前调用 YooAssets.Initialize()，并将其作为进程级单例。第二次调用只会记录警告并返回，但常规架构应通过 YooAssets.Initialized 进行检查。此调用会通过 DontDestroyOnLoad 创建一个 [{nameof(YooAssets)}] 驱动器 GameObject，用于驱动 OperationSystem.Update()。不要自行 Destroy 此驱动器。	Runtime/YooAssets.cs:38-64
2	ResourcePackage.InitializeAsync(...) 没有单独的 EPlayMode 参数：它会根据具体的 InitializeParameters 子类推断运行模式。五个内置子类与五种模式一一对应；未知子类会抛出 NotImplementedException，而已识别但语义不正确的子类会连接错误的文件系统拓扑，并在之后失败。	Runtime/ResourcePackage/ResourcePackage.cs:107-135, 170-181，Runtime/InitializeParameters.cs:8-110
3	EditorSimulateMode 仅在定义了 UNITY_EDITOR 时有效；WebPlayMode 仅在定义了 UNITY_WEBGL 时有效（WebGL 上会拒绝其他所有模式）。	Runtime/ResourcePackage/ResourcePackage.cs:160-197
4	每个 AssetHandle / SubAssetsHandle / AllAssetsHandle / RawFileHandle / SceneHandle 都必须通过 Release() 或 Dispose() 释放。若未释放，即使 AutoUnloadBundleWhenUnused = true，资源包也永远不会卸载。	Runtime/ResourceManager/Handle/HandleBase.cs:21-40，Runtime/InitializeParameters.cs:48-49
5	LoadAssetSync/Async 会执行仅限 DEBUG 的类型检查，拒绝任何派生自 UnityEngine.Behaviour 的 Type，以及任何未派生自 UnityEngine.Object 的类型。即使非 DEBUG 构建会移除此检查，也应将此限制视为架构约束。	Runtime/ResourcePackage/ResourcePackage.cs:1172-1187
6	YooAsset 2.3.18 在 YooAssets 上包含默认包的静态快捷方法（SetDefaultPackage、Load*、CreateResourceDownloader 等）。这些都是有效 API，但在多包或库代码中，架构上应优先使用显式的 ResourcePackage 引用。	Runtime/YooAssetsExtension.cs:16, 217-295, 479-506
7	RequestPackageVersionAsync() 返回 RequestPackageVersionOperation（提供 .PackageVersion）。2.3.18 中没有 UpdatePackageVersionOperation 类——如果你以为记得这个名称，那是把它和旧名称弄混了。	Runtime/ResourcePackage/ResourcePackage.cs:225-231
8	调用 UpdatePackageManifestAsync 之前，先调用 UnloadAllAssetsAsync()；如果加载器仍处于活动状态，YooAsset 会记录警告。	Runtime/ResourcePackage/ResourcePackage.cs:242-247
9	必须在 BeginDownload() 之前指定下载器回调（DownloadFinishCallback / DownloadUpdateCallback / DownloadErrorCallback / DownloadFileBeginCallback）。它们是委托字段，而非事件——每个槽位只能有一个订阅者。	Runtime/DownloadSystem + Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101, 330-336
10	必须先运行 ResourcePackage.DestroyAsync()，再调用 YooAssets.RemovePackage()。当 InitializeStatus != EOperationStatus.None 时，RemovePackage 会拒绝操作。	Runtime/YooAssets.cs:177-190，Runtime/ResourcePackage/ResourcePackage.cs:210-218
11	补丁流程必须严格按顺序执行：InitializeAsync → RequestPackageVersionAsync → UpdatePackageManifestAsync(version) → CreateResourceDownloader → BeginDownload。跳过步骤（例如，在获取版本和更新清单之间加载资源）不受支持。	Runtime/ResourcePackage/ResourcePackage.cs:225, 238, 972，Samples~/Space Shooter/.../PatchLogic/FsmNode/Fsm*.cs

子文档路由

子文档	阅读时机
INIT.md	Initialize / Destroy / CreatePackage / TryGetPackage / RemovePackage；单个驱动程序 GameObject；OperationSystem 循环
PLAYMODE.md	全部 5 种 EPlayMode 值、对应的 InitializeParameters 子类、平台 #if 守卫，以及运行时分发表
HANDLES.md	HandleBase API（Release / IsDone / Progress / Status / LastError / Completed / Task / IEnumerator）、AssetHandle.Instantiate*、引用计数、AutoUnloadBundleWhenUnused
LOADING.md	LoadAsset、LoadSubAssets、LoadAllAssets、LoadRawFile、LoadScene——所有重载 + Behaviour/Type 拒绝规则 + LoadSceneParameters
UPDATE.md	补丁流程、RequestPackageVersionOperation、UpdatePackageManifestOperation、PreDownloadContentOperation、ResourceDownloaderOperation（4 个回调、暂停/恢复/取消、Combine）
FILESYSTEM.md	FileSystemParameters + 24 个 FileSystemParametersDefine 常量 + 5 个工厂辅助方法 + IDecryptionServices / IRemoteServices / IWebDecryptionServices
BUILD.md	AssetBundleBuilder.Run(...)、BuildParameters（Scriptable / Raw / Simulate）、AssetBundleCollector、IFilterRule.FindAssetType、ScriptableBuildParameters.ReplaceAssetPathWithAddress
PITFALLS.md	30 个具体的幻觉陷阱 + 旧版 API 迁移部分

路由到其他模块

• YooAsset 使用者的 Asmdef 和程序集布局 → 加载 asmdef
• 多个 YooAsset 操作之间的异步编排 → 加载 async
• 架构层面的决策（Addressables 与 YooAsset、单包与多包）→ 加载 architecture
• 加载/释放热路径的性能审查 → 加载 performance

版本范围

本文档针对 YooAsset 2.3.18（2025-12-04）。近期重要历史：

• 2.3.18 — 新增 UNPACK_FILE_SYSTEM_ROOT 文件系统参数、EFileClearMode.ClearBundleFilesByLocations、RawFileBuildParameters.IncludePathInHash。
• 2.3.17 — [CRITICAL] 修复 CRC 验证错误，该错误会导致 2.3.15/2.3.16 上的损坏下载通过验证。还修复了销毁 Package 时的竞态问题：进行中的 AssetBundle 加载可能阻碍卸载。
• 2.3.16 — 移除下载器的 timeout 参数（请改用缓存文件系统上的 DOWNLOAD_WATCH_DOG_TIME）。IFilterRule 新增必需的 FindAssetType 属性。
• 2.3.15 — 升级清单二进制格式；使用 2.3.15+ 构建的安装程序无法被 2.3.14 或更早版本的客户端读取，反之亦然。新增 FILE_VERIFY_MAX_CONCURRENCY、StripUnityVersion、预览功能 UseWeakReferenceHandle（需启用 YOOASSET_EXPERIMENTAL）。

来源：Assets/YooAsset/CHANGELOG.md:5-275。

迁移说明（幻觉防护）

旧版 API（2.3.18 之前）	2.3.18 中的状态	替代方案	来源
CreateResourceDownloader(count, retry, timeout) 重载 / ResourceDownloaderOperation.timeout 属性	在 2.3.16 中已移除	在 CacheFileSystemParameters / BuildinFileSystemParameters 上设置 DOWNLOAD_WATCH_DOG_TIME	CHANGELOG.md:173-177，FileSystemParametersDefine.cs:18
没有 FindAssetType 属性的 IFilterRule	2.3.16 中的破坏性变更——编译会失败	实现 public string FindAssetType { get; }，返回 Unity 资源类型筛选字符串	CHANGELOG.md:179-192
旧版清单二进制文件（2.3.15 之前的客户端读取 2.3.15 或更高版本的清单，或反之）	线上协议不兼容	重新构建并重新发布安装包；不存在运行时桥接方案	CHANGELOG.md:196-198
YooAssets.LoadAsset(...)	不存在——方法名包括 LoadAssetSync / LoadAssetAsync，而不是单独的 LoadAsset	使用 package.LoadAssetAsync<T>(location)，或在调用 SetDefaultPackage 后使用 YooAssets.LoadAssetAsync<T>(location)	Runtime/YooAssetsExtension.cs:217-295，Runtime/ResourcePackage/ResourcePackage.cs:641-732
被标记为幻觉的 YooAssets.LoadAssetAsync(...)	规则已过时——2.3.18 提供了此默认包快捷方法	为明确所有权，优先使用 package.LoadAssetAsync<T>(location)；仅在调用 YooAssets.SetDefaultPackage(package) 后才可使用静态快捷方法	Runtime/YooAssetsExtension.cs:16, 260-295
package.UnloadUnusedAssets()（同步）	不存在	package.UnloadUnusedAssetsAsync(int loopCount = 10) 会返回一个 UnloadUnusedAssetsOperation	Runtime/ResourcePackage/ResourcePackage.cs:355-361
UpdatePackageVersionOperation 类（常与真实类型混淆）	不存在	RequestPackageVersionOperation，带有 .PackageVersion 字符串属性	Runtime/ResourcePackage/ResourcePackage.cs:225-231
用于资源同步的 NetworkVariable<T> / OnValueChanged 风格（从 Netcode 泄漏而来）	YooAsset 中不存在	订阅 AssetHandle.Completed 事件，或使用 await handle.Task / yield return handle	Runtime/ResourceManager/Handle/AssetHandle.cs:20-37，Runtime/ResourceManager/Handle/HandleBase.cs:152-173
ResourceDownloaderOperation.OnDownloadFinishCallback（事件风格）	该字段是普通委托，而非事件	赋值一次：downloader.DownloadFinishCallback = OnFinish;——不要使用 +=（这是单槽字段）	Runtime/ResourcePackage/Operation/DownloaderOperation.cs:86-101

如有疑问，请查阅引用的源代码，而不是依赖记忆。