unity-yooasset

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

触发条件

• 构建或模拟 YooAsset 资源包
• 配置收集器
• 校验热更新资源
• 构建或模拟 YooAsset 资源包、配置 collector、校验热更资源

Unity YooAsset 技能

针对 YooAsset 热更新框架的编辑器端自动化——构建流水线编排、Collector 配置 CRUD、BuildReport 分析、PlayMode 运行时校验，以及配套的 YooAsset 工具。每项技能都会封装一个具体的 YooAsset Editor/runtime API 路径，并已依据 2.3.18 源码验证。如果缺少该包，除 yooasset_check_installed 外的所有技能都会返回 NoYooAsset() 错误，并附带安装说明。

要求：com.tuyoogame.yooasset ≥ 2.3.15，Unity 2022.3+（已依据 2.3.18 验证）。 强烈建议：在编写任何 YooAsset 运行时代码前，先加载 yooasset-design。PlayMode、参数类和句柄生命周期方面的陷阱都很严格，只有 advisory 模块会提示这些问题。

防护规则

运行模式（v1.9 三级）：

• Approval（默认）：查询／列出／读取类技能（yooasset_check_installed、yooasset_get_default_paths、yooasset_get_build_settings、yooasset_list_collector_packages、yooasset_list_collector_rules、yooasset_list_assetart_scanners、yooasset_runtime_get_validation_result、yooasset_load_build_report、yooasset_list_report_bundles、yooasset_get_bundle_detail、yooasset_list_report_assets、yooasset_get_asset_detail、yooasset_get_dependency_graph、yooasset_compare_build_reports、yooasset_list_independ_assets）可直接运行。构建器／Collector 修改操作／扫描器运行／打开窗口操作属于 FullAuto —— 遇到 MODE_RESTRICTED 时，运行授权流程。

• Auto / Bypass：SemiAuto 和 FullAuto 可直接运行。

• 本模块中禁止 Auto 模式执行的操作：

  • MayEnterPlayMode = true → yooasset_runtime_validate_package、yooasset_runtime_cleanup
  • SkillOperation.Delete → yooasset_remove_collector_package、yooasset_remove_collector_group、yooasset_remove_collector

  只有在 Bypass 模式下，或通过用户管理的 Allowlist 条目才能执行；授权流程会返回 MODE_FORBIDDEN。注意，yooasset_build_bundles 会执行大量磁盘 I/O，但没有 Reload/PlayMode 标记，因此仍可授权。

• 缺少 com.tuyoogame.yooasset 时，除 yooasset_check_installed 外，所有技能都会返回带有安装说明的 NoYooAsset() 错误。

请勿（常见幻觉）：

• yooasset_initialize / yooasset_load_asset / yooasset_create_downloader —— 这些并不存在，不能作为通用 REST 技能使用。运行时 API（YooAssets.Initialize、默认 package 的 YooAssets.LoadAssetAsync、ResourcePackage.LoadAssetAsync、RequestPackageVersionAsync、CreateResourceDownloader）属于游戏代码。编写运行时代码时，请使用 yooasset-design。
• yooasset_modify_group / yooasset_delete_collector / yooasset_open_scanner_window —— 名称有误。请使用下方的准确 schema 名称，或查询 GET /skills/schema?category=YooAsset。
• yooasset_install —— 不是技能。安装 Package 是 Package Manager 中由用户执行的操作。
• 请勿向 yooasset_build_bundles 传入 timeout —— YooAsset 2.3.16 中已移除此属性。运行时看门狗现在由 CacheFileSystemParameters.DOWNLOAD_WATCH_DOG_TIME 管理（属于运行时事项，而非构建参数）。
• 当 EditorUserBuildSettings.isBuildingPlayer == true 时，请勿调用 yooasset_build_bundles —— BuildParameters.CheckBuildParameters 会抛出异常。

路由：

• Collector 配置（packages、groups、collectors、rules）→ 本模块。
• 实际 bundle 构建 + 模拟 + 路径 → 本模块。
• 构建报告分析（bundle 大小、资源列表／详情、依赖关系图、报告比较、孤立资源）→ 本模块。
• 在 Editor PlayMode 中进行运行时验证 → 本模块中的 yooasset_runtime_validate_package + 轮询／清理技能。
• 运行时代码生成／设计（在游戏脚本中使用 Initialize / Load / Download / Scene）→ 使用 yooasset-design 自行编写。
• YooAsset 配套窗口及 AssetArtScanner 配置／运行 → 本模块。
• 版本策略决策（2.x 与 pre-2.3.15 manifest、IFilterRule 上的 FindAssetType）→ yooasset-design/PITFALLS.md。

技能

环境（1）

技能	用途	关键参数
yooasset_check_installed	反射探测 —— 即使缺少 Package 也可运行。报告运行时程序集、Package 版本、编辑器可用性，以及 4 条管线中已存在的管线。	（无）

构建流程（7）

技能	用途	关键参数
yooasset_build_bundles	通过 ScriptableBuildPipeline 或 RawFileBuildPipeline 构建资源包。输出到 <projectPath>/Bundles/<PackageName>/<Version>。	packageName、packageVersion="auto"、pipeline="ScriptableBuildPipeline"、buildTarget?、compression="LZ4"、fileNameStyle="HashName"、clearBuildCache=false、useAssetDependencyDB=true、verifyBuildingResult=true、replaceAssetPathWithAddress=false、stripUnityVersion=false、disableWriteTypeTree=false、trackSpriteAtlasDependencies=false、writeLinkXML=true、cacheServerHost=""、cacheServerPort=0、builtinShadersBundleName=""、monoScriptsBundleName=""、includePathInHash=false、buildinFileCopyOption="None"、buildinFileCopyParams=""、enableLog=true
yooasset_simulate_build	为 EditorSimulateMode 包运行 AssetBundleSimulateBuilder.SimulateBuild——仅生成虚拟资源包，不写入文件。	packageName
yooasset_get_default_paths	返回 YooAsset 使用的 BuildOutputRoot + StreamingAssetsRoot。	（无）
yooasset_get_build_settings	读取某个包／流水线已持久化的 YooAsset AssetBundle Builder EditorPrefs。	packageName、pipeline?
yooasset_set_build_settings	持久化 AssetBundle Builder EditorPrefs，以便在构建 UI 中使用可重复的默认设置。	packageName、pipeline?、compression?、fileNameStyle?、buildinFileCopyOption?、buildinFileCopyParams?、encryptionServicesClassName?、manifestProcessServicesClassName?、manifestRestoreServicesClassName?、clearBuildCache?、useAssetDependencyDB?
yooasset_open_builder_window	打开 YooAsset AssetBundle Builder 编辑器窗口。	（无）
yooasset_open_collector_window	打开 YooAsset AssetBundle Collector 编辑器窗口。	（无）

YooAsset 工具（8）

技能	用途	关键参数
yooasset_open_reporter_window	打开 YooAsset AssetBundle Reporter 窗口。	（无）
yooasset_open_debugger_window	打开 YooAsset AssetBundle Debugger 窗口。	（无）
yooasset_open_assetart_scanner_window	打开 YooAsset AssetArt Scanner 窗口。	（无）
yooasset_list_assetart_scanners	列出 AssetArtScanner 配置，可按关键词筛选。	keyword?
yooasset_run_assetart_scanner	运行一个扫描器，并可选择保存其报告文件。	scannerGUID、saveDirectory?
yooasset_run_all_assetart_scanners	运行所有扫描器，可按关键词筛选。	keyword?
yooasset_import_assetart_scanner_config	导入 AssetArtScanner JSON 配置。	configPath
yooasset_export_assetart_scanner_config	导出 AssetArtScanner JSON 配置。	configPath

运行时验证（3）

技能	用途	关键参数
yooasset_runtime_validate_package	启动异步 PlayMode 任务，初始化 EditorSimulateMode，设置默认包，可选择验证一次资源加载／释放和下载器状态，然后可选择清理并返回 Edit Mode。	packageName、assetLocation?、restoreEditMode=true、cleanup=true、checkDownloader=true、downloadingMaxNumber=4、failedTryAgain=1
yooasset_runtime_get_validation_result	轮询运行时验证任务的状态／结果。	jobId
yooasset_runtime_cleanup	移除已完成的验证任务，并可选择强制执行 YooAssets.Destroy()／退出 PlayMode。	jobId?、forceYooAssetsDestroy=false、exitPlayMode=false

收集器配置（13）

技能	用途	关键参数
yooasset_list_collector_packages	列出包 → 分组 → 收集器树。verbose=true 会返回完整层级。	verbose=false
yooasset_list_collector_rules	返回已注册的 Active / Address / Pack / Filter / Ignore 规则类。	ruleKind="all"（或 `activeRule
yooasset_create_collector_package	创建新的收集器包。除非 allowDuplicate=true，否则遇到重复项时会失败。	packageName、allowDuplicate=false
yooasset_create_collector_group	在现有包中创建分组。	packageName、groupName、groupDesc=""、activeRule="EnableGroup"、assetTags=""
yooasset_add_collector	向分组添加一个 AssetBundleCollector。通过 AssetDatabase 验证 collectPath，并通过已注册的类名验证每条规则。	packageName、groupName、collectPath、collectorType="MainAssetCollector"、addressRule="AddressByFileName"、packRule="PackDirectory"、filterRule="CollectAll"、assetTags=""、userData=""
yooasset_save_collector_config	持久化 AssetBundleCollectorSetting.asset。可选择运行 FixFile()，以修复悬空的规则引用。	fixErrors=true
yooasset_modify_collector_settings	修改全局收集器设置。	showPackageView=false、uniqueBundleName=false、save=true
yooasset_modify_collector_package	重命名/描述包并设置包级选项。	packageName、packageDesc?、newPackageName?、enableAddressable=false、supportExtensionless=true、locationToLower=false、includeAssetGUID=false、autoCollectShaders=true、ignoreRule="NormalIgnoreRule"、save=true
yooasset_remove_collector_package	按名称移除收集器包。	packageName、save=true
yooasset_modify_collector_group	重命名/描述分组并更新启用规则/标签。	packageName、groupName、newGroupName?、groupDesc?、activeRule="EnableGroup"、assetTags?、save=true
yooasset_remove_collector_group	从包中移除分组。	packageName、groupName、save=true
yooasset_modify_collector	修改通过 collectPath 匹配的现有收集器。	packageName、groupName、collectPath、newCollectPath?、collectorType="MainAssetCollector"、addressRule="AddressByFileName"、packRule="PackDirectory"、filterRule="CollectAll"、assetTags?、userData?、save=true
yooasset_remove_collector	移除通过 collectPath 匹配的收集器。	packageName、groupName、collectPath、save=true

构建报告分析（8）

工具	用途	关键参数
yooasset_load_build_report	反序列化 YooAsset 构建报告 .report 文件，并返回 ReportSummary 元数据及顶层汇总数据。	reportPath
yooasset_list_report_bundles	分页、筛选和排序列出报告中的 Bundle。	reportPath、filterEncrypted?、filterTag?、sortBy="size"（`size
yooasset_get_bundle_detail	获取单个 Bundle 的完整 ReportBundleInfo，包括 DependBundles、ReferenceBundles 和资源 BundleContents。	reportPath、bundleName
yooasset_list_report_assets	分页、筛选和排序列出报告中的资源。	reportPath、filterBundle?、filterTag?、search?、sortBy="path"（`path
yooasset_get_asset_detail	根据资源路径或地址获取完整的 ReportAssetInfo。	reportPath、assetPath?、address?
yooasset_get_dependency_graph	获取精简的 Bundle/资源依赖关系图，用于可视化或聚焦分析。	reportPath、rootBundle?、rootAssetPath?、maxNodes=200
yooasset_compare_build_reports	比较两个 .report 文件中的 Bundle/资源新增、移除和大小变化。	oldReportPath、newReportPath、limit=100
yooasset_list_independ_assets	列出未被任何主资源引用的资源，即待清理项。	reportPath、limit=100、offset=0

快速开始

import unity_skills as u

# 0. Probe installation (works even if package is missing)
u.call_skill("yooasset_check_installed")
# -> { installed, packageVersion, availablePipelines: [...], editorAvailable, ... }

# 1. Configure collectors (end-to-end)
u.call_skill("yooasset_list_collector_rules", ruleKind="all")  # discover available rule class names
u.call_skill("yooasset_create_collector_package", packageName="DefaultPackage")
u.call_skill("yooasset_create_collector_group",
    packageName="DefaultPackage", groupName="UI", activeRule="EnableGroup",
    assetTags="ui")
u.call_skill("yooasset_add_collector",
    packageName="DefaultPackage", groupName="UI",
    collectPath="Assets/GameRes/UI",
    collectorType="MainAssetCollector",
    addressRule="AddressByFileName",
    packRule="PackDirectory",
    filterRule="CollectAll")
u.call_skill("yooasset_modify_collector_package",
    packageName="DefaultPackage",
    enableAddressable=True,
    supportExtensionless=True,
    locationToLower=False)
u.call_skill("yooasset_save_collector_config", fixErrors=True)

# 2. Simulate build (EditorSimulateMode) — fast, no file I/O
u.call_skill("yooasset_simulate_build", packageName="DefaultPackage")
# -> { packageRootDirectory: ".../Bundles/DefaultPackage/Simulate" }

# 3. Real build
result = u.call_skill("yooasset_build_bundles",
    packageName="DefaultPackage",
    packageVersion="1.0.0",
    pipeline="ScriptableBuildPipeline",
    compression="LZ4",
    fileNameStyle="HashName",
    verifyBuildingResult=True)

# 4. Analyze the report
import os
report_path = os.path.join(
    result["outputDirectory"],
    f"{result['packageName']}_{result['packageVersion']}.report")
u.call_skill("yooasset_load_build_report", reportPath=report_path)
u.call_skill("yooasset_list_report_bundles", reportPath=report_path, sortBy="size", limit=20)
u.call_skill("yooasset_list_report_assets", reportPath=report_path, search="UI", limit=20)
u.call_skill("yooasset_get_dependency_graph", reportPath=report_path, maxNodes=100)
u.call_skill("yooasset_list_independ_assets", reportPath=report_path)

# 5. Optional PlayMode runtime validation
job = u.call_skill("yooasset_runtime_validate_package",
    packageName="DefaultPackage",
    assetLocation="ui/example",
    restoreEditMode=True,
    cleanup=True)
u.call_skill("yooasset_runtime_get_validation_result", jobId=job["jobId"])

关键规则（必须阅读）

1. yooasset_check_installed 是唯一无需 YOO_ASSET 编译定义即可运行的技能。 其他所有技能都会返回 NoYooAsset()——请先修正环境（安装或升级软件包，然后等待 Unity 重新编译），再重试。
2. Pipeline ↔ Parameters 配对关系会强制校验。 yooasset_build_bundles pipeline=ScriptableBuildPipeline 使用 ScriptableBuildParameters；pipeline=RawFileBuildPipeline 使用 RawFileBuildParameters。此处不接受 EditorSimulateBuildPipeline——请改用 yooasset_simulate_build。BuiltinBuildPipeline 已过时，且会被明确拒绝。
3. packageVersion="auto" 会填入 DateTime.UtcNow.ToString("yyyyMMddHHmm")。 如需确定性版本，请传入 semver 字符串。
4. yooasset_add_collector 会通过 AssetDatabase.LoadAssetAtPath 验证 collectPath。路径必须位于 Assets/... 下；绝对路径或带 ../ 的相对路径都会失败。
5. Create Skills 中的规则名称是 CLASS 类名，而非显示名称。 使用 yooasset_list_collector_rules 查找有效值（例如 EnableGroup、AddressByFileName、PackDirectory、CollectAll、NormalIgnoreRule）。
6. Collector 修改可以立即保存，也可以批量保存。 Create 技能会设置 IsDirty=true；modify/remove 技能提供 save=true。批量编辑时，传入 save=false，最后调用 yooasset_save_collector_config。
7. yooasset_build_bundles 不会跟踪撤销操作（它执行外部文件 I/O，而非场景／资源状态操作）。clearBuildCache=true 会重新运行整个流水线；默认设置会避免这种情况，以提升增量构建速度。
8. BuildReport 与 bundles 存放在一起，文件扩展名为 .report——YooAsset 2.3.18 会将其写入 <BuildOutputRoot>/<BuildTarget>/<PackageName>/<Version>/<PackageName>_<PackageVersion>.report。不要传入 BuildReport.json、<PackageName>_<PackageVersion>.json 或 buildlogtep.json：.json 文件是软件包清单，而 buildlogtep.json 是 Scriptable Build Pipeline 跟踪日志。yooasset_list_report_bundles 可直接读取 .report 文件，因此也可以指向归档副本。
9. 运行时验证可能会进入 PlayMode。 yooasset_runtime_validate_package 会有意采用异步方式；请轮询作业结果，如果编辑器处于不希望保留的状态，请使用 yooasset_runtime_cleanup。
10. yooasset_list_independ_assets 会列出未被任何主资源引用的资源——这些资源可能适合从 Collector 中移除。移除前请手动确认；之后创建的主资源仍可能需要它们。

版本范围

• 目标版本：YooAsset 2.3.18（发布于 2025-12-04）。源代码定位依据此版本。
• 最低版本：2.3.15（由 asmdef 中的 versionDefines 条目强制要求）。更早版本使用不兼容的清单格式和 FindAssetType 之前的 IFilterRule（无法通过此 Skill 模块的编译）。
• 2.3.17 修复了一个严重的 CRC 验证错误；使用 2.3.15/2.3.16 的用户应先升级，再依赖 verifyBuildingResult=true。
• 运行时规则（PlayMode 映射、handle 生命周期、更新流程、旧版 API 迁移）→ yooasset-design/SKILL.md。

精确签名

如需确认参数名称、默认值和返回字段，请查询 GET /skills/schema?category=YooAsset 或 unity_skills.get_skill_schema()。本文档是路由／最佳实践指南，并非签名信息来源。