用途
unity-perception 用于只读的场景与项目分析。典型触发场景包括：编辑前收集上下文、理解不熟悉的场景或项目、在不改动的前提下审查结构。
主要能力
模块共 18 个 skill，其中 17 个标记为 SkillMode.SemiAuto，在 Approval / Auto / Bypass 三档模式下可直接执行、无需 grant。
16 个纯读 skill（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_analyze（场景 + 项目合并分析）、scene_health_check（只读健康报告）、scene_summarize（结构化场景摘要）、scene_component_stats（组件与设施统计）、scene_find_hotspots（深层级 / 大子级 / 空节点热点）、scene_tag_layer_stats（标签与图层使用）、scene_performance_hints（按优先级给出优化提示）。
- 场景快照与导出：scene_diff（捕获或比较轻量快照）、hierarchy_describe（返回文本层级树）、scene_context（导出层级、组件、引用）、scene_export_report（保存 markdown 场景报告）、scene_dependency_analyze（分析场景内影响 / 依赖图）。
- 项目与脚本分析：project_stack_detect（检测渲染管线、输入、UI、包、测试、目录）、script_analyze（按类名分析单个 MonoBehaviour / ScriptableObject / 用户类）、script_dependency_graph（按脚本类名做 N 跳依赖闭包）。
- 空间与材质查询：scene_spatial_query（查找某点或某对象附近的对象）、scene_materials（汇总场景材质与着色器）、scene_contract_validate（校验默认根节点、标签、图层、UI EventSystem 约定）。
使用方式
调用前应先通过 GET /skills/recommend?includeSchema=true 或 unity_skills.get_skill_schema() 获取参数定义；从 recommend/schema 拿到参数后可直接进入 dryRun。不要仅凭 skill 名称或描述猜测参数。
场景依赖分析与导出说明：
- scene_dependency_analyze 不是纯读，传入 savePath 会执行 Directory.CreateDirectory、File.WriteAllText、ImportAsset，落一个新工程资产，因此标记 MutatesAssets = true。仍无需 grant，但会进入 router 的 diff 捕获。
- 不传 savePath 时，该 skill 不写任何内容，仅在响应中返回 analysis 和 markdown，适合回答“谁依赖这个对象”的纯查询。只有用户确实需要文件时才传 savePath，响应中的 savedTo 会指出保存位置。
- scene_export_report 会把 markdown 文件写入磁盘（Operation = Analyze | Execute，MutatesAssets = true），因此不是 SemiAuto，而是走默认 SkillMode.FullAuto，在 Approval 模式下需要 grant 才能执行。
- 本模块不含 Delete / PlayMode / Reload / RiskLevel=high 类 skill，没有 IsForbiddenInSemi 拦截。
重要区分：
- scene_summarize vs scene_analyze vs scene_health_check：scene_summarize 适合快速概览（对象数量、层级深度、主要组件）；scene_analyze 适合广泛诊断（summary + findings + warnings + recommendations + next-skill 提示）；scene_health_check 关注卫生问题与红旗（缺失脚本、重名、深层级、空节点、热点类发现）。
- scene_context vs hierarchy_describe：hierarchy_describe 输出人类可读的文本树，较轻盈；scene_context 面向 AI 编码上下文，输出结构化层级 + 组件 + 引用 + 可选代码依赖。
- scene_dependency_analyze vs script_dependency_graph：前者针对场景对象引用，回答“删除或禁用该对象后谁依赖它”；后者针对脚本类依赖闭包，回答“改这个功能要动哪些脚本”。
- scene_context 不等于 editor_get_context：前者导出层级 / 组件 / 引用，后者关注当前编辑器状态。
关键返回结构：
- 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 的结构化导出。常用选项：rootPath 仅导出某个子树；includeValues=true 在关注序列化字段值时使用；includeCodeDeps=true 在需要大致场景到代码依赖图时使用。
- scene_export_report：写入 markdown 产物到磁盘，返回 savedTo、对象 / 脚本 / 引用计数与成功状态。默认 savePath = "Assets/Docs/SceneReport.md"，maxDepth = 10，maxObjects = 500。
路由提示：
- 当前选择 / 播放模式 / 编辑器状态 → editor_get_context。
- 按名称或路径搜索对象 → scene_find_objects 或 gameobject_find。
- 脚本依赖闭包 → script_dependency_graph。
选型建议：
- 快速场景概览 → 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")
限制与注意事项
- 常见误认：perception_analyze、perception_scan、perception_describe 并不存在。
- scene_context 不是 editor_get_context。
- 即使前缀像 scene_* 或 project_*，scene_analyze、scene_health_check、scene_contract_validate、scene_component_stats、scene_find_hotspots、project_stack_detect 均属于本模块。
- 确切的名称、参数、默认值与返回由 GET /skills/schema 或 unity_skills.get_skill_schema() 定义。