unity-skills

Unity Skills

文档仅提供英文版：无论用户使用哪种语言，都要按含义将请求匹配到相应模块，并始终使用用户的语言回复。

优先选择路径

• 自动执行 — 用户要求你执行操作，或任务需要遍历、搜索、批量处理、精确数字或处理大量对象：通过 REST 驱动 Editor。
• 指导 — 用户希望自己操作，或 surfaceProfile 为 guide：根据 SKILL_GUIDE.md 指出菜单和 Inspector 字段。
• 建议 — 不会改变任何内容的设计问题：根据匹配的建议文档作答（scriptdesign、architecture、patterns，均在模块索引中），不要调用 REST。

指定正确的 Editor

端口 8090–8100 按先到先得分配：每次写入都添加 ?expectProject=<project>（productName 或文件夹名称），或精确的 ?expectInstance=<instanceId>。其他 Editor 会返回 409 INSTANCE_MISMATCH，且不会执行任何操作。

GET /health（不受此检查限制）包含 currentMode、surfaceProfile、dryRunPolicy、instanceId：在与首次请求相同的 shell 命令中探测一次，不添加其他调用；之后仅在写入被拒绝、返回 409、503/连接被拒绝或模式异常时再探测。bypass 和 auto 会直接执行写入，但在 auto 模式下，需先征得用户同意再执行涉及 ≥5 个对象的批处理、应用 prefab、场景级操作、覆盖资产或不可逆更改（执行这些操作前单独探测）。approval 会通过一次性授权控制 FullAuto 写入（永久授权：用户的 Allowlist）。

在域重载期间，端口会返回 503 或在数秒内拒绝连接，此时 ~/.unity_skills/registry.json 中的条目会显示为 reloading：重试该端口，切勿切换到其他实例。

快速参考

每项技能均通过 POST /skill/<name> 传入 JSON 参数： curl -s "http://localhost:<port>/skill/gameobject_set_transform?expectProject=<project>" -d '{"name":"Crate","posX":4,"posY":1.5,"posZ":-2}'

通过 name 或精确的 path/instanceId 指定目标对象（parentPath、childPath 同理）；跳过查找调用——名称错误时，调用会失败并返回候选项。

调用
gameobject_create {name, primitiveType, parentName, x,y,z, rotX,rotY,rotZ, scaleX,scaleY,scaleZ, space} — x/y/z 和 rot 相对于父对象本地坐标，除非指定 space:"world"；scale 为本地坐标
gameobject_set_transform {name, posX,posY,posZ, rotX,rotY,rotZ, scaleX,scaleY,scaleZ, localPosX,localPosY,localPosZ} — pos、rot 为世界坐标；scale、localPos 为本地坐标；未指定的轴保持不变
gameobject_find {name, useRegex, component} · gameobject_get_info {name}
gameobject_rename {name, newName} · gameobject_duplicate {name}
gameobject_set_parent {childName, parentName} · gameobject_set_active {name, active}
gameobject_delete {name}（先执行 dryRun）
component_add {name, componentType}
component_set_property {name, componentType, propertyName, value} — 向量和颜色使用 "1,2,3"；引用使用 referenceName/referencePath/assetPath
component_get_properties {name, componentType}
material_assign {name, materialPath}
light_set_properties {name, r,g,b, intensity, range, spotAngle, shadows}
script_create {scriptName, folder, content} — 完整源代码；先执行 dryRun；等待时间见下文
scene_save {}（先执行 dryRun）

其他所有情况：调用一次发现接口

GET /skills/recommend?intent=<words>&includeSchema=true&topN=3&wire=v2 → 返回前 3 项技能及精确 schema（约 1–4 KB）；有多个需求时，每个需求再添加一个 &intent=<words>，仍使用同一次调用。已知名称 → GET /skills/schema?names=a,b&wire=v2。更多层级、v2 字段和常量 → 发现。

执行

多个步骤，一次调用：POST /skills/batch?expectProject=<project> {"steps":[{"skill":"gameobject_create","args":{"name":"Rig"}},{"skill":"gameobject_create","args":{"name":"Arm","parentName":"Rig"}}]} — 最多 50 个步骤；某个步骤可以引用更早步骤创建的对象，也可以使用 {"$ref":"$0.instanceId"}；第一个失败会跳过其余步骤，除非设置 continueOnError:true；?mode=transactional 表示全部成功或全部回滚 → batch。

dryRun。 如果本表、推荐内容或架构已在本次会话中提供了调用签名，请直接执行：验证失败时不会运行任何内容，并会返回 dryRun 报告（所有 validation 分类、参数列表）。对于删除操作、riskLevel 为 high、mayTriggerReload/mayEnterPlayMode、审批模式、非事务性多步骤批处理，或不确定时，先执行 dryRun（?mode=dryRun&wire=v2）；如果存在 dryRunPolicy，则使用返回的 ?dryRunToken= 执行。valid:true 表示没有验证错误（warnings 不会阻止执行；目标仍可能不存在）；authorization 会预览权限门槛。

切勿臆造技能或参数名称：使用本表、推荐内容或架构。失败时请读取 suggestedFixes；只有响应中指出某个模块文档时才打开它。

通过回读进行验证

成功写入后会返回从 Editor 回读的状态（例如 world position、valueSet）——这就是验证；resolutionNotes 会标记名称不完全匹配的情况。仅对异步结果或缺少字段的情况使用 *_get_info。脚本写入，以及你自行写入 .cs 文件后执行的 asset_refresh（compileTriggered:true），都会返回 waitUrl：一次 GET 即可等待编译和重新加载完成 → status:"completed"，或返回包含错误的 failed，错误位于 resultData.compilation。一条命令： u=http://localhost:<port>; c="$u/skill/script_create?expectProject=<project>"; b='{"scriptName":"Spin","content":"<source>"}'; s='{"steps":[{"skill":"component_add","args":{"name":"Crate","componentType":"Spin"}},{"skill":"component_set_property","args":{"name":"Crate","componentType":"Spin","propertyName":"speed","value":"9"}}]}'; curl -s "$c&mode=dryRun" -d "$b" | grep -q '"valid":true' && J=$(curl -s "$c" -d "$b" | tee /dev/stderr | grep -o '/jobs/[^"]*=90') && curl -s --retry 20 --retry-connrefused --retry-all-errors --retry-delay 2 "$u$J" && curl -s "$u/skills/batch?expectProject=<project>" -d "$s"

界面配置和错误

surfaceProfile 是用户选择的面板；guide 和 noSceneAuthoring 会隐藏某些写入操作，这些操作会返回 SURFACE_EXCLUDED，并指出要阅读的文档或要退出的配置。这是一条边界：继续完成任务的其余部分，绝不重试或绕过它（配置）。

代码	含义 → 操作
MISSING_PARAM / TARGET_NOT_FOUND	参数错误或无法解析 → 根据 details 修正参数 / 定位目标（gameobject_find）。
INSTANCE_MISMATCH (409)	根据 suggestedFixes 中的名称重新发送到对应端口。
MISSING_PACKAGE	告知用户（通过 dryRun 的 missingPackages；建议使用 unavailable，以便尽早显示）；是否安装由用户决定。
MODE_RESTRICTED / MODE_FORBIDDEN	授予权限 / 绕过限制或添加到 Allowlist → 运行模式。
其他	错误代码

编译状态、事件、分析 → 可观测性；已关闭的 Editor + 用户主动选择的 Unity CLI → unity-cli。

当前快照：839 个 REST 技能、56 个源文件、54 个类别、83 个模块文档目录（54 个 REST/模块文档 + 29 个建议文档），Unity 2022.3+，默认超时 15 minutes。

Python 辅助脚本：unity-skills/scripts/unity_skills.py