unity-sample

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

触发条件

• 测试 REST 服务可达性
• 冒烟测试连通性
• 试发第一个调用
• 测试 REST 服务可达性、冒烟测试连通性、试发第一个调用

示例技能

用于测试 API 的基本示例。

防护措施

运行模式（v1.9 三层模式）：

• Approval（默认）：查询技能（get_scene_info、find_objects_by_name）直接运行。创建/修改技能（create_cube、create_sphere、set_object_position、set_object_rotation、set_object_scale）为 FullAuto；遇到 MODE_RESTRICTED 时，运行授权流程。
• Auto / Bypass：SemiAuto 和 FullAuto 直接运行。
• 此模块中禁止 Auto 调用：delete_object（SkillOperation.Delete）。只能在 Bypass 模式下或通过用户管理的 Allowlist 条目调用；授权流程会返回 MODE_FORBIDDEN。

界面配置：此模块的写入技能本质上是换了名称的 GameObject 创作，因此 guide 和 noSceneAuthoring 配置都会隐藏这些技能，并返回 SURFACE_EXCLUDED——不能通过模式或 Allowlist 绕过此限制。在 guide 配置下，details.manualDoc 指向 manual-gameobject，其中介绍了如何手动执行这些相同的基本对象/变换步骤。查询技能在所有配置中均可用。

SURFACE_EXCLUDED 除了会因技能名称被隐藏而返回，还有另一种情况：可见的封装技能会重放负载——batch_execute / batch_retry_failed（batch 模块）以及工作流撤销/重做/还原技能（workflow 模块）——在执行时，如果它们即将应用的负载属于当前配置禁用的类别，也会返回相同代码，即使这些封装技能本身从未被隐藏。

不要（常见幻觉）：

• 示例技能是用于测试/演示的基本技能——不要用于生产工作
• sample_create 是 gameobject_create 的简化版——请优先使用完整的 gameobject 模块
• sample_hello / sample_ping 仅用于连通性测试

路由：

• 执行实际的 GameObject 操作 → 使用 gameobject 模块
• 检查服务健康状况 → 使用 Python helper 的 unity_skills.health()

技能

create_cube

创建一个立方体基本体。 参数： x、y、z、name

create_sphere

创建一个球体基本体。 参数： x、y、z、name

delete_object

按名称删除对象。 参数： objectName

find_objects_by_name

查找名称包含指定字符串的对象。 参数： nameContains（也接受 name 作为兼容别名）

set_object_position

设置对象位置。 参数： objectName、x、y、z

set_object_rotation

设置对象旋转。 参数： objectName、x、y、z

set_object_scale

设置对象缩放。 参数： objectName、x、y、z

get_scene_info

获取当前场景信息。 参数： 无。

---

精确签名

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