unity-asset

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

触发条件

• 整理项目资源
• 导入或移动文件
• 查询资源元数据
• 脚本化 AssetDatabase 操作
• 整理工程资源、导入或移动文件、查询资源元数据、脚本化 AssetDatabase 操作

Unity 资源技能

批处理优先：操作 2 个或更多资源时，使用 *_batch 技能。

操作模式

• Approval：本模块为 Mixed —— asset_find / asset_get_info / asset_get_labels 标记为 SkillMode.SemiAuto，可直接执行；写入类 skill（asset_move / asset_move_batch / asset_duplicate / asset_create_folder / asset_create_folder_batch / asset_refresh / asset_reimport* / asset_set_labels）采用默认的 SkillMode.FullAuto，需要 grant。
• Auto / Bypass：FullAuto 直接执行。
• 包含 NeverInSemi 高风险 skill：asset_import / asset_import_batch（标记 RiskLevel = "high" —— 写入项目）；asset_delete / asset_delete_batch（Operation.Delete）。这些技能在 Approval/Auto 模式下会返回 MODE_FORBIDDEN，只有 Bypass 或命中 Allowlist 时才可调用。

不要（常见臆测）：

• asset_create 不存在 → 文件夹使用 asset_create_folder，材质使用 material_create，脚本使用 script_create
• asset_rename 不存在 → 使用带新路径的 asset_move
• asset_search 不存在 → 使用带搜索筛选语法的 asset_find（例如 t:Texture2D player）
• asset_copy 不存在 → 使用 asset_duplicate

路由：

• 纹理/模型/音频导入设置 → 使用 importer 模块（SkillMode.FullAuto）
• 创建材质 → 使用 material 模块（SkillMode.FullAuto）
• 创建脚本 → 使用 script 模块

技能概览

单个对象	批处理版本	何时使用批处理
asset_import	asset_import_batch	导入 2 个或更多文件
asset_delete	asset_delete_batch	删除 2 个或更多资源
asset_move	asset_move_batch	移动 2 个或更多资源
asset_create_folder	asset_create_folder_batch	创建 2 个或更多文件夹

无需批处理：

• asset_duplicate - 复制单个资源
• asset_find - 搜索资源（返回列表）
• asset_refresh - 刷新 AssetDatabase
• asset_get_info - 获取资源信息
• asset_reimport - 强制重新导入资源
• asset_reimport_batch - 重新导入多个资源

---

技能

asset_import

将外部文件导入项目。

参数	类型	必填	描述
sourcePath	string	是	外部文件路径
destinationPath	string	是	项目目标路径

asset_import_batch

导入多个外部文件。

参数	类型	必填	默认值	描述
items	json string	是	-	每项对象组成的 JSON 数组（参见下方示例）

items 目前需要 JSON 字符串，而非原生数组。

返回值：{success, totalItems, successCount, failCount, results: [{target, success, serverAvailability?}]}：target 是该项的 destinationPath；仅当写入了脚本域资源或 Unity 正在编译时，才会出现 serverAvailability。

import json

unity_skills.call_skill("asset_import_batch", items=json.dumps([
    {"sourcePath": "C:/Downloads/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "C:/Downloads/tex2.png", "destinationPath": "Assets/Textures/tex2.png"}
]))

asset_delete

从项目中删除资源。

参数	类型	必填	描述
assetPath	string	是	要删除的资源路径

asset_delete_batch

删除多个资源。

参数	类型	必填	默认值	描述
items	json string	是	-	每项对象组成的 JSON 数组（见下方示例）

items 目前要求使用 JSON 字符串，而非原生数组。

返回值：{success, totalItems, successCount, failCount, results: [{target, success, serverAvailability?}]}：target 是已删除的 path；仅当删除了脚本域资源或 Unity 正在编译时，才会出现 serverAvailability。

import json

unity_skills.call_skill("asset_delete_batch", items=json.dumps([
    {"path": "Assets/Textures/old1.png"},
    {"path": "Assets/Textures/old2.png"}
]))

asset_move

移动或重命名资源。

参数	类型	必填	描述
sourcePath	string	是	当前资源路径
destinationPath	string	是	新路径/名称

asset_move_batch

移动多个资源。

参数	类型	必填	默认值	描述
items	json string	是	-	每项对象组成的 JSON 数组（见下方示例）

items 目前要求使用 JSON 字符串，而非原生数组。

返回值：{success, totalItems, successCount, failCount, results: [{target, success, from, to, serverAvailability?}]}：target 是该项的 sourcePath；仅当移动了脚本域资源或 Unity 正在编译时，才会出现 serverAvailability。

import json

unity_skills.call_skill("asset_move_batch", items=json.dumps([
    {"sourcePath": "Assets/Old/mat1.mat", "destinationPath": "Assets/New/mat1.mat"},
    {"sourcePath": "Assets/Old/mat2.mat", "destinationPath": "Assets/New/mat2.mat"}
]))

asset_duplicate

复制资源。

参数	类型	必填	描述
assetPath	string	是	要复制的资源

asset_find

根据搜索筛选条件查找资源。

参数	类型	必填	默认值	描述
searchFilter	string	是	-	搜索查询
limit	int	否	50	返回的最大结果数

搜索筛选语法：

筛选条件	示例	描述
t:Type	t:Texture2D	按类型筛选
l:Label	l:Architecture	按标签筛选
name	player	按名称筛选
组合	t:Material player	多个筛选条件

返回值：{count, totalFound, assets: [{path, name, type}]}

asset_create_folder

在项目中创建文件夹。

参数	类型	必填	描述
folderPath	string	是	完整文件夹路径

asset_create_folder_batch

创建多个文件夹。

参数	类型	必填	默认值	描述
items	json string	是	-	每项对象组成的 JSON 数组（见下方示例）

items 目前要求使用 JSON 字符串，而非原生数组。每个条目的父文件夹必须已存在，因此在一次调用中创建嵌套文件夹时，请按从最外层到最内层的顺序排列。

返回值：{success, totalItems, successCount, failCount, results: [{target, success, path, guid}]}

import json

unity_skills.call_skill("asset_create_folder_batch", items=json.dumps([
    {"folderPath": "Assets/Art"},
    {"folderPath": "Assets/Art/Textures"}
]))

asset_refresh

在外部更改后刷新 AssetDatabase，例如使用自己的文件工具写入或删除文件后。

无参数。

返回：{success, message, compileTriggered}。当刷新启动脚本编译（.cs、.asmdef、.asmref 或 .dll 发生更改）时，compileTriggered 为 true，结果还会包含 status:"accepted"、jobId、waitUrl（/jobs/<jobId>?wait=90）、serverAvailability，以及在 Unity 报告了文件时的 scriptChanges（最多 20 个路径；scriptChangesTruncated 统计其余路径）。compileTriggered:false 表示无需等待。

自己写入了 .cs 文件？调用 asset_refresh，然后 GET 其 waitUrl，并通过域重载重试相同 URL：curl -s --retry 20 --retry-connrefused --retry-all-errors --retry-delay 2 "http://localhost:<port>/jobs/<jobId>?wait=90"。status:"completed" 且 compilation.compiled:true、success:true 和 domainLoaded:true，即可证明新类型已可使用；"failed" 会在 resultData.compilation.errors 中列出编译错误。诊断信息针对整个项目（compilation.scope:"project"）；compilation.compiled:false 表示刷新后未进行编译。

asset_get_info

获取资源信息。

参数	类型	必填	描述
assetPath	string	是	资源路径

asset_reimport

强制重新导入资源。

参数	类型	必填	描述
assetPath	string	是	要重新导入的资源路径

asset_reimport_batch

重新导入匹配模式的多个资源。

参数	类型	必填	描述
searchFilter	string	否	AssetDatabase 搜索筛选条件（默认 *）
folder	string	否	要搜索的文件夹根目录（默认 Assets）
limit	int	否	要重新导入的资源数量上限（默认 100）

asset_set_labels

为资源设置标签（覆盖现有标签）。

参数	类型	必填	描述
assetPath	string	是	资源路径
labels	string	是	逗号分隔的标签（例如 "ui,icon,hud"）。空条目会被移除

返回：{success, assetPath, labels: [...]}

asset_get_labels

获取当前附加到资源的标签。

参数	类型	必填	描述
assetPath	string	是	资源路径

---

最简示例

import unity_skills

# GOOD: 1 API call instead of 4
unity_skills.call_skill("asset_move_batch", items=[
    {"sourcePath": "Assets/tex1.png", "destinationPath": "Assets/Textures/tex1.png"},
    {"sourcePath": "Assets/tex2.png", "destinationPath": "Assets/Textures/tex2.png"},
    {"sourcePath": "Assets/tex3.png", "destinationPath": "Assets/Textures/tex3.png"},
    {"sourcePath": "Assets/tex4.png", "destinationPath": "Assets/Textures/tex4.png"}
])

最佳实践

1. 将资源整理到逻辑清晰的文件夹中
2. 使用一致的命名约定
3. 外部文件更改后进行刷新
4. 使用搜索筛选条件提高效率
5. 批量删除前进行备份

---

精确签名

确切的名称、参数、默认值和返回值由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义，而非本文档。

常见错误

完整的传输层代码（COMPILING/RATE_LIMIT 等）→ ../../references/protocol-error-codes.md

错误	触发条件	修复方法
TARGET_NOT_FOUND	找不到源文件、资源路径或目标资源。	使用 asset_find / asset_get_info 验证路径，确保文件存在，然后使用准确的项目相对路径重试。
MISSING_PARAM	必需的路径参数为空或未提供（由路径验证捕获）。	提供必需的 assetPath、sourcePath、destinationPath 或 folderPath。
SEMANTIC_INVALID	路径无效（例如，包含 ..、不以 Assets//Packages/ 开头，或文件夹已存在）。	使用 Assets/ 或 Packages/ 下规范化的项目相对路径；如果文件夹已存在，请选择其他文件夹名称。
SKILL_ERROR	底层 AssetDatabase 或文件系统操作失败，例如 Failed to delete asset、AssetDatabase.MoveAsset 返回错误，或文件夹创建失败。	解决消息中描述的问题（例如，关闭被锁定的文件、修正父路径），然后重试。