unity-validation

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

触发条件

• 检查断裂或缺失的引用
• 验证场景/项目完整性
• 构建前清理
• 检查断裂或丢失引用、校验场景/项目完整性、构建前清理

Unity 验证 Skills

维护项目健康状态——查找问题、清理并验证 Unity 项目。

运行模式

• Approval：只读分析 skill（validate_scene / validate_find_missing_scripts / validate_find_unused_assets / validate_texture_sizes / validate_project_structure / validate_missing_references / validate_mesh_collider_convex / validate_shader_errors，标记为 SkillMode.SemiAuto）直接执行；含 Delete 的 skill（validate_cleanup_empty_folders 标记为 Analyze | Delete、validate_fix_missing_scripts 标记为 Execute | Delete，默认 SkillMode.FullAuto）需要用户授权。
• Auto / Bypass：直接执行。
• 本模块包含 Delete 类高危 skill：validate_cleanup_empty_folders / validate_fix_missing_scripts 一旦 dryRun=false 就会真正删除；它们在 Approval / Auto 下会被 IsForbiddenInSemi 自动拦截，仅在 Bypass 或命中 Allowlist 时才能执行。强烈建议先使用 dryRun=true 预览。

不要（常见幻觉）：

• Validation skill 路由使用 validate_* 前缀，而不是 validation_*
• validation_run / validation_check 不存在 → 使用特定 skill，例如 validate_scene、validate_project_structure、validate_missing_references
• validation_fix 不存在 → 验证 skill 会报告问题；请使用其他模块修复
• validation_clean 不存在 → 使用 cleaner 模块执行清理操作

路由：

• 清理未使用/重复资源 → 使用 cleaner 模块
• 修复缺失脚本 → 使用 cleaner_fix_missing_scripts（cleaner 模块）
• 编译错误 → 使用 debug_check_compilation（debug 模块）

Skills 概览

Skill	描述
validate_scene	全面验证场景
validate_find_missing_scripts	查找缺少脚本的对象
validate_fix_missing_scripts	移除缺失的脚本组件
validate_cleanup_empty_folders	移除空文件夹
validate_find_unused_assets	查找可能未使用的资源
validate_texture_sizes	检查纹理尺寸
validate_project_structure	获取项目概览
validate_missing_references	查找组件上的空对象/缺失对象引用
validate_mesh_collider_convex	查找非凸 MeshCollider
validate_shader_errors	查找存在编译错误的着色器

另外还有六个 skill 具有 SkillCategory.Validation 类别，但其实现和文档位于 batch 模块中，因此 GET /skills/recommend?category=validation 会将它们与上述十个 skill 一并返回。它们的参数位于 ../batch/SKILL.md；除 batch_validate_scene_objects 是纯只读报告外，其余每个都是预览操作，需使用 batch_execute(confirmToken) 提交。

Skill	描述
batch_validate_scene_objects	分析场景对象，检查缺失脚本、缺失引用、重复名称和空对象
batch_fix_missing_scripts	预览批量移除缺失脚本
batch_cleanup_temp_objects	预览按常见临时名称模式删除临时辅助对象
batch_standardize_naming	预览通过去除空白和规范分隔符来统一名称
batch_set_render_layer	预览批量设置 GameObject 图层
batch_replace_material	预览批量替换材质

---

Skills

validate_scene

全面验证场景。

参数	类型	必填	默认值	描述
checkMissingScripts	bool	否	true	检查是否存在丢失的脚本
checkMissingPrefabs	bool	否	true	检查是否存在丢失的预制件
checkDuplicateNames	bool	否	true	检查重复名称
checkEmptyGameObjects	bool	否	false	检查空 GameObject（不含组件）

返回：{scene, totalIssues, summary: {errors, warnings, info}, issues: [{type, severity, gameObject, path, message, count}]}

validate_find_missing_scripts

查找存在丢失脚本引用的对象。

参数	类型	必填	默认值	描述
searchInPrefabs	bool	否	true	同时检查预制件资源

返回：{totalFound, objects: [{source, gameObject, path, missingCount, prefabPath?}]}（仅当 source="Prefab" 时才包含 prefabPath）

validate_fix_missing_scripts

移除丢失的脚本组件。

参数	类型	必填	默认值	描述
dryRun	bool	否	true	仅预览，不移除

返回：{success, dryRun, fixedCount, message, objects: [{gameObject, path, missingCount}]}

validate_cleanup_empty_folders

移除项目中的空文件夹。

参数	类型	必填	默认值	描述
rootPath	string	否	"Assets"	起始文件夹
dryRun	bool	否	true	仅预览，不删除

返回：{ success, dryRun, emptyFolderCount, folders, message }

validate_find_unused_assets

查找可能未使用的资源。

参数	类型	必填	默认值	描述
assetType	string	否	"Material"	筛选类型：Texture/Material/Prefab 等
limit	int	否	100	最大结果数

返回：{ success, assetType, potentiallyUnusedCount, assets }

validate_texture_sizes

检查尺寸过大的纹理。

参数	类型	必填	默认值	描述
maxRecommendedSize	int	否	2048	超过此尺寸时发出警告
limit	int	否	50	最大结果数

返回：{maxRecommendedSize, largeTextureCount, textures: [{path, name, width, height, maxTextureSize, format, recommendation}]}

validate_project_structure

获取项目文件夹结构概览。

参数	类型	必填	默认值	描述
rootPath	string	否	"Assets"	起始文件夹
maxDepth	int	否	2	最大文件夹深度

返回：{ success, rootPath, assetCounts, structure }

validate_missing_references

查找场景中组件上的空/丢失对象引用。

参数	类型	必填	默认值	描述
limit	int	否	50	最大结果数

返回：{ success, count, issues: [{ gameObject, path, component, property }] }

validate_mesh_collider_convex

查找非凸 MeshCollider（可能存在性能问题）。

参数	类型	必填	默认值	描述
limit	int	否	50	最大结果数

返回：{ success, count, nonConvexColliders: [{ gameObject, path, vertexCount }] }

validate_shader_errors

查找存在编译错误的着色器。

参数	类型	必填	默认值	描述
limit	int	否	50	最大结果数

返回：{ success, count, shaders: [{ name, path, errorCount }] }

---

常见工作流

构建前检查

import unity_skills

# Validate scene
scene_result = unity_skills.call_skill("validate_scene")
if scene_result['totalIssues'] > 0:
    print(f"Warning: {scene_result['totalIssues']} issues found")

# Check texture sizes
texture_result = unity_skills.call_skill("validate_texture_sizes", maxRecommendedSize=2048)
if texture_result['largeTextureCount'] > 0:
    print(f"Warning: {texture_result['largeTextureCount']} oversized textures")

项目清理

import unity_skills

# 1. Preview missing scripts fix
preview = unity_skills.call_skill("validate_fix_missing_scripts", dryRun=True)
print(f"Would fix {preview['fixedCount']} objects")

# 2. Actually fix (if preview looks good)
unity_skills.call_skill("validate_fix_missing_scripts", dryRun=False)

# 3. Preview empty folder cleanup
preview = unity_skills.call_skill("validate_cleanup_empty_folders", dryRun=True)
print(f"Would delete {len(preview['folders'])} folders")

# 4. Actually cleanup
unity_skills.call_skill("validate_cleanup_empty_folders", dryRun=False)

# 5. Review unused assets (manual review recommended)
unused = unity_skills.call_skill("validate_find_unused_assets")
for asset in unused['assets']:
    print(f"Potentially unused: {asset}")

最佳实践

1. 始终先使用 dryRun=True 预览更改
2. 在进行重大构建前运行验证
3. 删除前手动检查未使用的资源
4. 根据目标平台选择合适的纹理尺寸
5. 在缺失脚本导致运行时错误前修复它们
6. 定期清理可防止项目臃肿

---

精确签名

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