Yooasset

---
name: unity-yooasset
description: Automate YooAsset hot-update and asset bundles
---

> **Before calling any skill in this module:** if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via `GET /skills/recommend?includeSchema=true`) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.

## Triggers
- Building or simulating YooAsset bundles
- Configuring collectors
- Validating hot-update assets
- 构建或模拟 YooAsset 资源包、配置 collector、校验热更资源

# Unity YooAsset Skills

Editor-side automation for the YooAsset hot-update framework — build pipeline orchestration, Collector configuration CRUD, BuildReport analysis, PlayMode runtime validation, and companion YooAsset tools. Every skill wraps a concrete YooAsset Editor/runtime API path validated against 2.3.18 source. When the package is absent, every skill except `yooasset_check_installed` returns a `NoYooAsset()` error with install instructions.

> **Requires**: `com.tuyoogame.yooasset` **≥ 2.3.15**, Unity 2022.3+ (validated against 2.3.18).
> **Strongly recommended**: before writing ANY YooAsset runtime code, load [yooasset-design](../yooasset-design/SKILL.md). PlayMode / parameter-class / handle-lifecycle pitfalls are strict, and only the advisory module surfaces them.

## Guardrails

**Operating Mode** (v1.9 three-tier):
- **Approval** (default): query/list/read skills (`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`) run directly. Builders / Collector mutators / scanner runs / window-openers are FullAuto — on `MODE_RESTRICTED`, run the grant protocol.
- **Auto** / **Bypass**: SemiAuto and FullAuto run directly.
- Auto-forbidden in this module:
  - `MayEnterPlayMode = true` → `yooasset_runtime_validate_package`, `yooasset_runtime_cleanup`
  - `SkillOperation.Delete` → `yooasset_remove_collector_package`, `yooasset_remove_collector_group`, `yooasset_remove_collector`
  
  Reachable only under Bypass mode or via a user-managed Allowlist entry; the grant flow returns `MODE_FORBIDDEN`. Note `yooasset_build_bundles` runs heavy disk I/O but has no Reload/PlayMode flag, so it stays grantable.
- When `com.tuyoogame.yooasset` is missing, every skill except `yooasset_check_installed` returns a `NoYooAsset()` error with install instructions.

**DO NOT** (common hallucinations):
- `yooasset_initialize` / `yooasset_load_asset` / `yooasset_create_downloader` — do NOT exist as general-purpose REST skills. Runtime APIs (`YooAssets.Initialize`, default-package `YooAssets.LoadAssetAsync`, `ResourcePackage.LoadAssetAsync`, `RequestPackageVersionAsync`, `CreateResourceDownloader`) belong in game code. Use [yooasset-design](../yooasset-design/SKILL.md) when writing runtime code.
- `yooasset_modify_group` / `yooasset_delete_collector` / `yooasset_open_scanner_window` — wrong names. Use the exact schema names below or query `GET /skills/schema?category=YooAsset`.
- `yooasset_install` — NOT a skill. Package install is a Package Manager user action.
- Do NOT pass `timeout` to `yooasset_build_bundles` — the property was removed in YooAsset 2.3.16. Runtime watchdog now lives on `CacheFileSystemParameters.DOWNLOAD_WATCH_DOG_TIME` (runtime concern, not a build parameter).
- Do NOT call `yooasset_build_bundles` while `EditorUserBuildSettings.isBuildingPlayer == true` — `BuildParameters.CheckBuildParameters` throws.

**Routing**:
- Collector configuration (packages, groups, collectors, rules) → this module.
- Actual bundle build + simulate + paths → this module.
- Build report analysis (bundle size, asset list/detail, dependency graph, report compare, orphan) → this module.
- Runtime validation in Editor PlayMode → `yooasset_runtime_validate_package` + polling/cleanup skills in this module.
- Runtime code generation/design (Initialize / Load / Download / Scene in game scripts) → write it yourself using [yooasset-design](../yooasset-design/SKILL.md).
- YooAsset companion windows and AssetArtScanner config/runs → this module.
- Version-policy decisions (2.x vs pre-2.3.15 manifest, `FindAssetType` on `IFilterRule`) → [yooasset-design/PITFALLS.md](../yooasset-design/PITFALLS.md).

## Skills

### Environment (1)
| Skill | Purpose | Key Parameters |
|-------|---------|----------------|
| `yooasset_check_installed` | Reflection probe — works even when the package is missing. Reports runtime assembly, package version, editor availability, and which of the 4 pipelines are present. | (none) |

### Build pipeline (7)
| Skill | Purpose | Key Parameters |
|-------|---------|----------------|
| `yooasset_build_bundles` | Build bundles via `ScriptableBuildPipeline` or `RawFileBuildPipeline`. Writes to `<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` | Run `AssetBundleSimulateBuilder.SimulateBuild` for an `EditorSimulateMode` package — virtual bundles only, no files written. | `packageName` |
| `yooasset_get_default_paths` | Return `BuildOutputRoot` + `StreamingAssetsRoot` that YooAsset uses. | (none) |
| `yooasset_get_build_settings` | Read persisted YooAsset AssetBundle Builder EditorPrefs for a package/pipeline. | `packageName`, `pipeline?` |
| `yooasset_set_build_settings` | Persist AssetBundle Builder EditorPrefs for repeatable build UI defaults. | `packageName`, `pipeline?`, `compression?`, `fileNameStyle?`, `buildinFileCopyOption?`, `buildinFileCopyParams?`, `encryptionServicesClassName?`, `manifestProcessServicesClassName?`, `manifestRestoreServicesClassName?`, `clearBuildCache?`, `useAssetDependencyDB?` |
| `yooasset_open_builder_window` | Open the YooAsset `AssetBundle Builder` Editor window. | (none) |
| `yooasset_open_collector_window` | Open the YooAsset `AssetBundle Collector` Editor window. | (none) |

### YooAsset tools (8)
| Skill | Purpose | Key Parameters |
|-------|---------|----------------|
| `yooasset_open_reporter_window` | Open the YooAsset AssetBundle Reporter window. | (none) |
| `yooasset_open_debugger_window` | Open the YooAsset AssetBundle Debugger window. | (none) |
| `yooasset_open_assetart_scanner_window` | Open the YooAsset AssetArt Scanner window. | (none) |
| `yooasset_list_assetart_scanners` | List AssetArtScanner configurations, optionally filtered by keyword. | `keyword?` |
| `yooasset_run_assetart_scanner` | Run one scanner and optionally save its report file. | `scannerGUID`, `saveDirectory?` |
| `yooasset_run_all_assetart_scanners` | Run all scanners, optionally filtered by keyword. | `keyword?` |
| `yooasset_import_assetart_scanner_config` | Import AssetArtScanner JSON config. | `configPath` |
| `yooasset_export_assetart_scanner_config` | Export AssetArtScanner JSON config. | `configPath` |

### Runtime validation (3)
| Skill | Purpose | Key Parameters |
|-------|---------|----------------|
| `yooasset_runtime_validate_package` | Start an async PlayMode job that initializes `EditorSimulateMode`, sets default package, optionally validates one asset load/release and downloader status, then optionally cleans up and returns to Edit Mode. | `packageName`, `assetLocation?`, `restoreEditMode=true`, `cleanup=true`, `checkDownloader=true`, `downloadingMaxNumber=4`, `failedTryAgain=1` |
| `yooasset_runtime_get_validation_result` | Poll the runtime validation job status/result. | `jobId` |
| `yooasset_runtime_cleanup` | Remove completed validation jobs and optionally force `YooAssets.Destroy()` / exit PlayMode. | `jobId?`, `forceYooAssetsDestroy=false`, `exitPlayMode=false` |

### Collector configuration (13)
| Skill | Purpose | Key Parameters |
|-------|---------|----------------|
| `yooasset_list_collector_packages` | List Packages → Groups → Collectors tree. `verbose=true` returns the full descent. | `verbose=false` |
| `yooasset_list_collector_rules` | Return registered Active / Address / Pack / Filter / Ignore rule classes. | `ruleKind="all"` (or `activeRule|addressRule|packRule|filterRule|ignoreRule`) |
| `yooasset_create_collector_package` | Create a new Collector Package. Fails on duplicate unless `allowDuplicate=true`. | `packageName`, `allowDuplicate=false` |
| `yooasset_create_collector_group` | Create a Group inside an existing Package. | `packageName`, `groupName`, `groupDesc=""`, `activeRule="EnableGroup"`, `assetTags=""` |
| `yooasset_add_collector` | Add an `AssetBundleCollector` to a Group. Validates `collectPath` via AssetDatabase and each rule via its registered class name. | `packageName`, `groupName`, `collectPath`, `collectorType="MainAssetCollector"`, `addressRule="AddressByFileName"`, `packRule="PackDirectory"`, `filterRule="CollectAll"`, `assetTags=""`, `userData=""` |
| `yooasset_save_collector_config` | Persist the `AssetBundleCollectorSetting.asset`. Optionally run `FixFile()` to repair dangling rule references. | `fixErrors=true` |
| `yooasset_modify_collector_settings` | Modify global Collector settings. | `showPackageView=false`, `uniqueBundleName=false`, `save=true` |
| `yooasset_modify_collector_package` | Rename/describe a package and set package-level options. | `packageName`, `packageDesc?`, `newPackageName?`, `enableAddressable=false`, `supportExtensionless=true`, `locationToLower=false`, `includeAssetGUID=false`, `autoCollectShaders=true`, `ignoreRule="NormalIgnoreRule"`, `save=true` |
| `yooasset_remove_collector_package` | Remove a Collector package by name. | `packageName`, `save=true` |
| `yooasset_modify_collector_group` | Rename/describe a group and update active rule/tags. | `packageName`, `groupName`, `newGroupName?`, `groupDesc?`, `activeRule="EnableGroup"`, `assetTags?`, `save=true` |
| `yooasset_remove_collector_group` | Remove a group from a package. | `packageName`, `groupName`, `save=true` |
| `yooasset_modify_collector` | Modify an existing collector matched by `collectPath`. | `packageName`, `groupName`, `collectPath`, `newCollectPath?`, `collectorType="MainAssetCollector"`, `addressRule="AddressByFileName"`, `packRule="PackDirectory"`, `filterRule="CollectAll"`, `assetTags?`, `userData?`, `save=true` |
| `yooasset_remove_collector` | Remove a collector matched by `collectPath`. | `packageName`, `groupName`, `collectPath`, `save=true` |

### Build report analysis (8)
| Skill | Purpose | Key Parameters |
|-------|---------|----------------|
| `yooasset_load_build_report` | Deserialize a YooAsset BuildReport `.report` file and return `ReportSummary` metadata + top-level totals. | `reportPath` |
| `yooasset_list_report_bundles` | Paginated / filtered / sorted bundle listing from the report. | `reportPath`, `filterEncrypted?`, `filterTag?`, `sortBy="size"` (`size|name|refCount|dependCount`), `limit=100`, `offset=0` |
| `yooasset_get_bundle_detail` | Full `ReportBundleInfo` for a single bundle — `DependBundles`, `ReferenceBundles`, asset `BundleContents`. | `reportPath`, `bundleName` |
| `yooasset_list_report_assets` | Paginated / filtered / sorted asset listing from the report. | `reportPath`, `filterBundle?`, `filterTag?`, `search?`, `sortBy="path"` (`path|size|bundle|dependCount`), `limit=100`, `offset=0` |
| `yooasset_get_asset_detail` | Full `ReportAssetInfo` by asset path or address. | `reportPath`, `assetPath?`, `address?` |
| `yooasset_get_dependency_graph` | Compact bundle/asset dependency graph for visualization or focused analysis. | `reportPath`, `rootBundle?`, `rootAssetPath?`, `maxNodes=200` |
| `yooasset_compare_build_reports` | Compare two `.report` files for bundle/asset additions, removals, and size changes. | `oldReportPath`, `newReportPath`, `limit=100` |
| `yooasset_list_independ_assets` | Assets not referenced by any main asset — cleanup candidates. | `reportPath`, `limit=100`, `offset=0` |

## Quick Start

```python
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"])
```

## Critical Rules (must read)

1. **`yooasset_check_installed` is the ONLY skill that works without `YOO_ASSET` compile define.** Every other skill returns `NoYooAsset()` — correct the environment (install or upgrade the package, then let Unity recompile) before retrying.
2. **Pipeline ↔ Parameters pairing is enforced.** `yooasset_build_bundles pipeline=ScriptableBuildPipeline` uses `ScriptableBuildParameters`; `pipeline=RawFileBuildPipeline` uses `RawFileBuildParameters`. `EditorSimulateBuildPipeline` is rejected here — use `yooasset_simulate_build`. `BuiltinBuildPipeline` is legacy and explicitly rejected.
3. **`packageVersion="auto"` fills `DateTime.UtcNow.ToString("yyyyMMddHHmm")`.** Pass a semver string when you want deterministic versioning.
4. **`yooasset_add_collector` validates `collectPath`** via `AssetDatabase.LoadAssetAtPath`. Paths must be under `Assets/...`; absolute or relative `../` paths will fail.
5. **Rule names in Create Skills are CLASS names, not display names.** Use `yooasset_list_collector_rules` to discover valid values (e.g. `EnableGroup`, `AddressByFileName`, `PackDirectory`, `CollectAll`, `NormalIgnoreRule`).
6. **Collector mutations can save immediately or be batched.** Create skills mark `IsDirty=true`; modify/remove skills expose `save=true`. For bulk edits, pass `save=false` and finish with `yooasset_save_collector_config`.
7. **`yooasset_build_bundles` is NOT undo-tracked** (external file I/O, not scene/asset state). `clearBuildCache=true` re-runs the full pipeline; defaults avoid it for incremental speed.
8. **BuildReport lives next to bundles as a `.report` file** — YooAsset 2.3.18 writes it as `<BuildOutputRoot>/<BuildTarget>/<PackageName>/<Version>/<PackageName>_<PackageVersion>.report`. Do not pass `BuildReport.json`, `<PackageName>_<PackageVersion>.json`, or `buildlogtep.json`: the `.json` file is the package manifest and `buildlogtep.json` is the Scriptable Build Pipeline trace log. `yooasset_list_report_bundles` reads the `.report` file standalone, so you can also point it at an archived copy.
9. **Runtime validation may enter PlayMode.** `yooasset_runtime_validate_package` is intentionally async; poll the job result and use `yooasset_runtime_cleanup` if the editor is left in a state you do not want.
10. **`yooasset_list_independ_assets` identifies assets not referenced by any main asset** — candidates for the Collector to drop. Verify manually before removing; a main asset created later could still need them.

## Version Scope

- **Target**: YooAsset `2.3.18` (published 2025-12-04). Source anchors use this version.
- **Minimum**: `2.3.15` (enforced by the asmdef `versionDefines` entry). Earlier versions use an incompatible manifest format and pre-`FindAssetType` `IFilterRule` (would not compile against this Skill module).
- **2.3.17** fixed a critical CRC validation bug; users on 2.3.15/2.3.16 should upgrade before relying on `verifyBuildingResult=true`.
- Runtime-side rules (PlayMode mapping, handle lifecycle, update flow, legacy-API migration) → [yooasset-design/SKILL.md](../yooasset-design/SKILL.md).

## Exact Signatures

For authoritative parameter names, defaults, and return fields, query `GET /skills/schema?category=YooAsset` or `unity_skills.get_skill_schema()`. This document is a routing / best-practice guide, not the signature source.