unity-perception

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

触发条件

• 编辑前收集上下文
• 理解陌生场景或项目
• 在不改动的前提下审查结构

Unity Perception 技能

使用此模块进行只读场景和项目分析。

运行模式

• Approval / Auto / Bypass：本模块 18 个 skill 里有 17 个标记为 Mode = SkillMode.SemiAuto，三档模式下直接执行无需 grant。其中 16 个是纯读（ReadOnly = true）：scene_analyze / scene_summarize / scene_health_check / scene_component_stats / scene_find_hotspots / scene_tag_layer_stats / scene_performance_hints / scene_diff / hierarchy_describe / scene_context / scene_spatial_query / scene_materials / scene_contract_validate / project_stack_detect / script_analyze / script_dependency_graph。
• scene_dependency_analyze 是第 17 个 SemiAuto，但它不是纯读：传入 savePath 会通过 Directory.CreateDirectory + File.WriteAllText + ImportAsset 写入一个新工程资产，因此它标记为 MutatesAssets = true，而不再标记为 ReadOnly。仍然无需 grant，但它会进入 router 的 diff 捕获，schema/flags 中也会带有 mutatesAssets —— 不传入 savePath 时才真的什么都不写。
• 特别说明：scene_export_report 会将 markdown 文件写入磁盘（Operation = Analyze | Execute，标记为 MutatesAssets = true），因此不是 SemiAuto——它采用默认的 SkillMode.FullAuto，在 Approval 模式下需要 grant 才能执行。
• 本模块不含 Delete / PlayMode / Reload / RiskLevel=high 类 skill —— 不会触发 IsForbiddenInSemi 拦截。

请勿（常见幻觉）：

• perception_analyze、perception_scan 和 perception_describe 均不存在
• scene_context 不等同于 editor_get_context：前者导出层级结构/组件/引用，而 editor context 侧重当前编辑器状态
• 即使前缀看起来像 scene_* 或 project_*，scene_analyze、scene_health_check、scene_contract_validate、scene_component_stats、scene_find_hotspots 和 project_stack_detect 也属于此模块

路由：

• 当前选中项/播放模式/编辑器状态 -> editor_get_context
• 按名称/路径搜索对象 -> scene_find_objects 或 gameobject_find
• 脚本依赖闭包 -> script_dependency_graph

技能

场景健康状况与摘要

技能	用途	关键参数
scene_analyze	综合场景 + 项目分析	topComponentsLimit?、issueLimit?、deepHierarchyThreshold?、largeChildCountThreshold?
scene_health_check	只读健康报告	issueLimit?、deepHierarchyThreshold?、largeChildCountThreshold?
scene_summarize	结构化场景摘要	includeComponentStats?、topComponentsLimit?
scene_component_stats	组件和设施统计	topComponentsLimit?
scene_find_hotspots	深层级/大型组/空节点热点	阈值 + maxResults?
scene_tag_layer_stats	标签/层使用情况	无
scene_performance_hints	优先级排序的优化提示	无

场景快照与导出

技能	用途	关键参数
scene_diff	捕获或比较轻量级快照	snapshotJson?
hierarchy_describe	返回文本层级树	maxDepth?、includeInactive?、maxItemsPerLevel?
scene_context	导出层级、组件和引用	maxDepth?、maxObjects?、rootPath?、includeValues?、includeReferences?、includeCodeDeps?
scene_export_report	保存 Markdown 场景报告	savePath?、maxDepth?、maxObjects?
scene_dependency_analyze	分析场景内的影响／依赖关系图	targetPath?、savePath? — 会写入

scene_dependency_analyze 中的 savePath 会执行写入，而非设置输出选项。 提供该参数会创建目录、写入 Markdown 报告，并将其作为项目资源导入，因此该技能被标记为 mutatesAssets，而非 ReadOnly。省略 savePath，即可在响应（analysis、markdown）中获得相同的分析结果，且不会改动磁盘上的任何内容——这是纯粹询问“哪些内容依赖于此”的用法。只有当用户确实要求生成文件时才传入 savePath，并预期响应中会包含指明文件位置的 savedTo。

项目与脚本分析

技能	用途	关键参数
project_stack_detect	检测管线、输入、UI、程序包、测试和文件夹	无
script_analyze	按类名分析一个 MonoBehaviour／ScriptableObject／用户类	scriptName、includePrivate?
script_dependency_graph	获取一个脚本类名的 N 跳依赖闭包	scriptName、maxHops?、includeDetails?

空间与材质查询

技能	用途	关键参数
scene_spatial_query	查找某个点或对象附近的对象	x/y/z?、radius?、nearObject?、componentFilter?、maxResults?
scene_materials	汇总场景材质和着色器	includeProperties?
scene_contract_validate	验证默认根节点／标签／层／UI EventSystem 约定	requiredRootsJson?、requiredTagsJson?、requiredLayersJson?、requireEventSystemForUi?

高频技能差异

scene_summarize 与 scene_analyze、scene_health_check 的区别

技能	最适合	典型输出重点
scene_summarize	快速概览	对象数量、层级深度、主要组件
scene_analyze	全面诊断	摘要 + 发现 + 警告 + 建议 + 后续技能提示
scene_health_check	卫生检查／风险提示	缺失脚本、重复名称、层级过深、空节点、热点类发现

scene_context 与 hierarchy_describe 的区别

技能	最适合	输出样式
hierarchy_describe	便于人类阅读的树	文本树，轻量
scene_context	AI 编码上下文	结构化层级 + 组件 + 引用 + 可选的代码依赖

scene_dependency_analyze 与 script_dependency_graph 的区别

技能	范围	适用情况
scene_dependency_analyze	场景对象引用	询问“如果删除或禁用此对象，哪些对象会依赖它？”
script_dependency_graph	脚本类依赖闭包	询问“要修改此功能，我需要改动哪些脚本？”

关键返回结构

scene_summarize

返回 sceneName、stats 和可选的 topComponents。

scene_analyze

返回 summary、stats、findings、warnings、recommendations 和 suggestedNextSkills。

scene_health_check

返回 summary、findings、hotspots 和 suggestedNextSkills。

scene_context

返回包含 objects、references 和可选 codeDependencies 的结构化导出。当另一个 AI 步骤需要完整的场景上下文，而不只是面向用户的摘要时，请使用此技能。

常用选项：

• 使用 rootPath 仅导出一个子树
• 当序列化字段值很重要时，设置 includeValues=true
• 当 AI 需要大致了解场景与代码之间的依赖关系时，设置 includeCodeDeps=true

scene_export_report

将 Markdown 文件写入磁盘，并返回 savedTo、对象／脚本／引用计数以及成功状态。当用户需要一份可长期保存的报告文件时，优先使用此技能。

默认值：

• savePath = "Assets/Docs/SceneReport.md"
• maxDepth = 10
• maxObjects = 500

何时使用哪种技能

需求	首选技能
快速查看场景概况	scene_summarize
全面诊断	scene_analyze
可疑的层级结构或杂乱场景	scene_find_hotspots
是否可安全删除／影响评估	scene_dependency_analyze
AI 编码上下文导出	scene_context
脚本阅读顺序	script_dependency_graph
渲染／输入／UI 栈检测	project_stack_detect

最简示例

import unity_skills

summary = unity_skills.call_skill("scene_summarize", includeComponentStats=True)
health = unity_skills.call_skill("scene_health_check", issueLimit=50)
context = unity_skills.call_skill("scene_context", maxDepth=6, maxObjects=120)
report = unity_skills.call_skill("scene_export_report", savePath="Assets/Docs/SceneReport.md")

精确签名

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