Back to Details

unity-perception

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
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.
**调用本模块中的任何技能之前：**如果您打算仅凭技能名称或描述猜测参数来调用技能，请停止——先阅读本文档（或通过
GET /skills/recommend?includeSchema=true
获取其 schema）。如果您已经从推荐/schema中获取了参数定义，可以直接执行dryRun。

Triggers

触发场景

  • Gathering context before editing
  • Understanding unfamiliar scene/project
  • Auditing structure without changes
  • 编辑前收集上下文、理解陌生场景或项目、在不改动的前提下审查结构
  • 编辑前收集上下文
  • 理解陌生场景/项目
  • 在不改动的前提下审查结构
  • 编辑前收集上下文、理解陌生场景或项目、在不改动的前提下审查结构

Unity Perception Skills

Unity Perception Skills

Use this module for read-only scene and project analysis.
使用本模块进行只读场景和项目分析。

Operating Mode

运行模式

  • 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
    拦截。
DO NOT (common hallucinations):
  • perception_analyze
    , 
    perception_scan
    , and 
    perception_describe
    do not exist
  • scene_context
    is not 
    editor_get_context
    : it exports hierarchy/components/references, while editor context focuses on current editor state
  • scene_analyze
    , 
    scene_health_check
    , 
    scene_contract_validate
    , 
    scene_component_stats
    , 
    scene_find_hotspots
    , and 
    project_stack_detect
    belong to this module even if the prefix looks like 
    scene_*
    or 
    project_*
Routing:
  • Current selection/play-mode/editor state -> 
    editor_get_context
  • Object search by name/path -> 
    scene_find_objects
    or 
    gameobject_find
  • Script dependency closure -> 
    script_dependency_graph
  • 审批/自动/绕过：本模块的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
    。仍然无需授权，但它会被路由的diff捕获，schema/flags中也会带有
    mutatesAssets
    ——只有不传
    savePath
    时才真正不会写入任何内容。
  • 特别说明：
    scene_export_report
    会将markdown文件写入磁盘（
    Operation = Analyze | Execute
    ，标记为
    MutatesAssets = true
    ），因此不属于SemiAuto——它使用默认的
    SkillMode.FullAuto
    ，在审批模式下需要授权（grant）才能执行。
  • 本模块不含Delete / PlayMode / Reload / RiskLevel=high类skill——没有
    IsForbiddenInSemi
    拦截。
请勿（常见幻觉）：
  • 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
    仍属于本模块
路由规则:
  • 当前选择/播放模式/编辑器状态 -> 
    editor_get_context
  • 按名称/路径搜索对象 -> 
    scene_find_objects
    或 
    gameobject_find
  • 脚本依赖闭包 -> 
    script_dependency_graph

Skills

技能列表

Scene Health and Summary

场景健康与概述

SkillUseKey parameters
scene_analyze
Combined scene + project analysis
topComponentsLimit?
, 
issueLimit?
, 
deepHierarchyThreshold?
, 
largeChildCountThreshold?
scene_health_check
Read-only health report
issueLimit?
, 
deepHierarchyThreshold?
, 
largeChildCountThreshold?
scene_summarize
Structured scene summary
includeComponentStats?
, 
topComponentsLimit?
scene_component_stats
Component and facility stats
topComponentsLimit?
scene_find_hotspots
Deep hierarchy / large group / empty node hotspotsthresholds + 
maxResults?
scene_tag_layer_stats
Tag/layer usagenone
scene_performance_hints
Prioritized optimization hintsnone
Skill用途关键参数
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 Snapshots and Exports

场景快照与导出

SkillUseKey parameters
scene_diff
Capture or compare lightweight snapshots
snapshotJson?
hierarchy_describe
Return text hierarchy tree
maxDepth?
, 
includeInactive?
, 
maxItemsPerLevel?
scene_context
Export hierarchy, components, references
maxDepth?
, 
maxObjects?
, 
rootPath?
, 
includeValues?
, 
includeReferences?
, 
includeCodeDeps?
scene_export_report
Save markdown scene report
savePath?
, 
maxDepth?
, 
maxObjects?
scene_dependency_analyze
Analyze impact / dependency graph in-scene
targetPath?
, 
savePath?
— writes
savePath
on 
scene_dependency_analyze
is a write, not an output option. Supplying it creates the directory, writes the markdown report and imports it as a project asset, which is why the skill is flagged 
mutatesAssets
rather than 
ReadOnly
. Omit 
savePath
and you get the same analysis in the response (
analysis
, 
markdown
) with nothing touched on disk — that is the form to use for a pure "what depends on this" question. Only pass 
savePath
when the user actually asked for a file, and expect 
savedTo
in the response naming it.
Skill用途关键参数
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 and Script Analysis

项目与脚本分析

SkillUseKey parameters
project_stack_detect
Detect pipeline, input, UI, packages, tests, foldersnone
script_analyze
Analyze one MonoBehaviour / ScriptableObject / user class by class name
scriptName
, 
includePrivate?
script_dependency_graph
N-hop dependency closure for one script class name
scriptName
, 
maxHops?
, 
includeDetails?
Skill用途关键参数
project_stack_detect
检测管线、输入、UI、包、测试、文件夹无
script_analyze
按类名分析单个MonoBehaviour / ScriptableObject / 用户类
scriptName
, 
includePrivate?
script_dependency_graph
单个脚本类的N跳依赖闭包
scriptName
, 
maxHops?
, 
includeDetails?

Spatial and Material Queries

空间与材质查询

SkillUseKey parameters
scene_spatial_query
Find objects near a point or object
x/y/z?
, 
radius?
, 
nearObject?
, 
componentFilter?
, 
maxResults?
scene_materials
Summarize scene materials and shaders
includeProperties?
scene_contract_validate
Validate default roots/tags/layers/UI EventSystem conventions
requiredRootsJson?
, 
requiredTagsJson?
, 
requiredLayersJson?
, 
requireEventSystemForUi?
Skill用途关键参数
scene_spatial_query
查找点或对象附近的对象
x/y/z?
, 
radius?
, 
nearObject?
, 
componentFilter?
, 
maxResults?
scene_materials
汇总场景材质与着色器
includeProperties?
scene_contract_validate
验证默认根节点/标签/层/UI EventSystem约定
requiredRootsJson?
, 
requiredTagsJson?
, 
requiredLayersJson?
, 
requireEventSystemForUi?

High-Frequency Skill Differences

高频技能差异

scene_summarize
vs 
scene_analyze
vs 
scene_health_check

scene_summarize
对比 
scene_analyze
对比 
scene_health_check

SkillBest forTypical output focus
scene_summarize
Fast overviewobject counts, hierarchy depth, top components
scene_analyze
Broad diagnosissummary + findings + warnings + recommendations + next-skill hints
scene_health_check
Hygiene / red flagsmissing scripts, duplicate names, deep hierarchy, empty nodes, hotspot-style findings
Skill适用场景典型输出重点
scene_summarize
快速概览对象数量、层级深度、主要组件
scene_analyze
全面诊断概述+发现+警告+建议+后续技能提示
scene_health_check
健康检查/风险标记缺失脚本、重复名称、深层层级、空节点、热点类发现

scene_context
vs 
hierarchy_describe

scene_context
对比 
hierarchy_describe

SkillBest forOutput style
hierarchy_describe
Human-readable treetext tree, lightweight
scene_context
AI coding contextstructured hierarchy + components + references + optional code dependencies
Skill适用场景输出风格
hierarchy_describe
人类可读的层级树文本树，轻量级
scene_context
AI编码上下文结构化层级+组件+引用+可选代码依赖

scene_dependency_analyze
vs 
script_dependency_graph

scene_dependency_analyze
对比 
script_dependency_graph

SkillScopeUse when
scene_dependency_analyze
Scene object referencesask "who depends on this object if I delete or disable it"
script_dependency_graph
Script class dependency closureask "which scripts do I have to touch to change this feature"
Skill范围适用场景
scene_dependency_analyze
场景对象引用询问“如果我删除或禁用此对象，哪些对象会受影响”
script_dependency_graph
脚本类依赖闭包询问“要更改此功能，我需要修改哪些脚本”

Key Return Shapes

关键返回结构

scene_summarize

scene_summarize

Returns 
sceneName
, 
stats
, and optional 
topComponents
.
返回
sceneName
, 
stats
, 和可选的
topComponents
。

scene_analyze

scene_analyze

Returns 
summary
, 
stats
, 
findings
, 
warnings
, 
recommendations
, and 
suggestedNextSkills
.
返回
summary
, 
stats
, 
findings
, 
warnings
, 
recommendations
, 和 
suggestedNextSkills
。

scene_health_check

scene_health_check

Returns 
summary
, 
findings
, 
hotspots
, and 
suggestedNextSkills
.
返回
summary
, 
findings
, 
hotspots
, 和 
suggestedNextSkills
。

scene_context

scene_context

Returns a structured export with 
objects
, 
references
, and optional 
codeDependencies
. Use it when another AI step needs full scene context, not just a human summary.
High-frequency options:
  • rootPath
    to export only one subtree
  • includeValues=true
    when serialized field values matter
  • includeCodeDeps=true
    when AI needs a rough scene-to-code dependency picture
返回包含
objects
, 
references
, 和可选
codeDependencies
的结构化导出。当其他AI步骤需要完整场景上下文而非仅人类可读的摘要时使用此技能。
高频选项:
  • rootPath
    ：仅导出单个子树
  • includeValues=true
    ：当序列化字段值很重要时使用
  • includeCodeDeps=true
    ：当AI需要了解场景到代码的大致依赖关系时使用

scene_export_report

scene_export_report

Writes a markdown artifact to disk and returns 
savedTo
, object/script/reference counts, and success state. Prefer this when the user wants a durable report file.
Defaults:
  • savePath = "Assets/Docs/SceneReport.md"
  • maxDepth = 10
  • maxObjects = 500
将markdown工件写入磁盘，并返回
savedTo
, 对象/脚本/引用数量以及成功状态。当用户需要持久化的报告文件时优先使用此技能。
默认值:
  • savePath = "Assets/Docs/SceneReport.md"
  • maxDepth = 10
  • maxObjects = 500

When to Use Which Skill

技能选择指南

NeedBest first skill
Quick scene overview
scene_summarize
Full diagnosis
scene_analyze
Suspicious hierarchy or clutter
scene_find_hotspots
Safe-to-delete / impact question
scene_dependency_analyze
AI coding context export
scene_context
Script reading order
script_dependency_graph
Render/input/UI stack detection
project_stack_detect
需求首选技能
快速场景概览
scene_summarize
全面诊断
scene_analyze
可疑层级或杂乱结构
scene_find_hotspots
安全删除/影响评估问题
scene_dependency_analyze
AI编码上下文导出
scene_context
脚本读取顺序
script_dependency_graph
渲染/输入/UI栈检测
project_stack_detect

Minimal Example

最简示例

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

Exact Signatures

精确签名

Exact names, parameters, defaults, and returns are defined by 
GET /skills/schema
or 
unity_skills.get_skill_schema()
, not by this file.
精确的名称、参数、默认值和返回结果由
GET /skills/schema
或
unity_skills.get_skill_schema()
定义，而非本文档。