unity-smart

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

触发条件

• 按条件或邻近关系查询场景对象
• 自动排布对象
• 自动连线引用
• 按条件或邻近关系查询场景对象、自动排布对象、自动连线引用

Unity 智能技能

运行模式

• Approval：本模块为 Mixed —— 只读查询技能 smart_scene_query / smart_scene_query_spatial（标记为 ReadOnly = true, Mode = SkillMode.SemiAuto）可直接执行；其余布局/绑定/变换类技能 (smart_scene_layout / smart_reference_bind / smart_align_to_ground / smart_distribute / smart_snap_to_grid / smart_randomize_transform / smart_select_by_component) 为 SkillMode.FullAuto，需用户授权后执行一次并返回结果。
• Auto / Bypass：直接执行。
• 包含 NeverInSemi 高危技能：smart_replace_objects（Operation.Modify|Delete，会替换并删除原对象）。该技能在 Approval/Auto 下会返回 MODE_FORBIDDEN，仅在 Bypass 或命中 Allowlist 时可调用。

不要（常见幻觉）：

• smart_create / smart_build 不存在 → 智能技能是查询/布局工具，不用于创建对象
• smart_search / smart_query 不存在 → 使用 smart_scene_query（组件属性筛选）或 smart_scene_query_spatial（空间区域筛选）
• smart_move 不存在 → 使用 smart_snap_to_grid 或 smart_align_to_ground

路由：

• 创建对象 → 使用 gameobject 模块
• 简单对象搜索 → 使用 gameobject_find 或 scene_find_objects
• 复杂场景查询（类似 SQL）→ 使用 smart_scene_query（本模块）

技能

smart_scene_query

根据组件属性值查找对象（类似 SQL）。

参数	类型	必填	默认值	描述
componentName	string	是	-	组件类型（Light、Camera、MeshRenderer）
propertyName	string	是	-	要查询的属性（intensity、enabled 等）
op	string	否	"=="	==、!=、>、<、>=、<=、contains
value	string	否	null	比较值
limit	int	否	50	最大结果数
query	string	否	null	不支持的简写；若单独提供，将返回指导性错误

对于未知的 propertyName、列表之外的 op、对非数值成员使用 >/</>=/<= 或提供非数值 value，以及对布尔值使用除 ==/!= 之外的运算符，系统会返回 SEMANTIC_INVALID（若成员名称拼写错误，还会提供最接近的名称建议），而不会静默匹配空结果。

示例：

# Find all lights with intensity > 2
call_skill("smart_scene_query", componentName="Light", propertyName="intensity", op=">", value="2")

---

smart_scene_layout

将选中的对象排布成布局。

参数	类型	必填	默认值	描述
layoutType	string	否	"Linear"	Linear、Grid、Circle、Arc
axis	string	否	"X"	X、Y、Z、-X、-Y、-Z
spacing	float	否	2.0	项目之间的间距（或半径）
columns	int	否	3	用于 Grid 布局
arcAngle	float	否	180	用于 Arc 布局（角度）
lookAtCenter	bool	否	false	旋转以朝向中心

示例：

# Arrange selected objects in a circle
call_skill("smart_scene_layout", layoutType="Circle", spacing=5)

---

smart_reference_bind

自动将匹配的对象填入 List/Array 字段。

参数	类型	必填	默认值	描述
targetName	string	是	-	目标 GameObject
componentName	string	否	-	目标上的组件
fieldName	string	是	-	要填充的字段
sourceTag	string	否	null	按标签查找
sourceName	string	否	null	查找名称包含指定文本的对象
appendMode	bool	否	false	追加而非替换

示例：

# Fill GameManager.spawns with all SpawnPoint tagged objects
call_skill("smart_reference_bind", targetName="GameManager", componentName="GameController", fieldName="spawns", sourceTag="SpawnPoint")

---

smart_scene_query_spatial

查找球形／方形区域内的对象，可选择按组件筛选。

参数	类型	必填	默认值	描述
x	float	是	-	中心 X 坐标
y	float	是	-	中心 Y 坐标
z	float	是	-	中心 Z 坐标
radius	float	否	10	搜索球体半径
componentFilter	string	否	null	仅包含带有此组件的对象
limit	int	否	50	结果数量上限

返回： { success, count, center, radius, results }

---

smart_align_to_ground

向下对选中的对象进行射线检测，使其与地面对齐。需先在 Hierarchy 中选中对象。

参数	类型	必填	默认值	描述
maxDistance	float	否	100	射线检测的最大距离
alignRotation	bool	否	false	将旋转与表面法线对齐

返回： { success, aligned, total }

---

smart_distribute

在首个和最后一个位置之间均匀分布选中的对象。需先在 Hierarchy 中至少选中 3 个对象。

参数	类型	必填	默认值	描述
axis	string	否	"X"	X、Y、Z、-X、-Y、-Z

返回： { success, distributed, axis }

---

smart_snap_to_grid

将选中的对象吸附到网格。

参数	类型	必填	默认值	描述
gridSize	float	否	1	网格单元大小

返回： { success, snapped, gridSize }

---

smart_randomize_transform

在指定范围内随机调整选中对象的位置／旋转／缩放。

参数	类型	必填	默认值	描述
posRange	float	否	0	位置随机化范围
rotRange	float	否	0	旋转随机化范围（度）
scaleMin	float	否	1	最小统一缩放值
scaleMax	float	否	1	最大统一缩放值

返回： { success, randomized }

---

smart_replace_objects

将选中的对象替换为预制体（保留变换）。需先在 Hierarchy 中选中对象。

参数	类型	必填	默认值	描述
prefabPath	string	是	-	替换用预制体的资源路径

返回： { success, replaced, prefab }

---

smart_select_by_component

选择所有包含特定组件的对象。

参数	类型	必填	默认值	描述
componentName	string	否	-	要搜索的组件类型名称（省略 componentName 时，可使用别名 componentType）

返回： { success, selected, component }

---

精确签名

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