企业官网建设流程全解析

Unity-Skills 是专为 Unity 设计的 AI 自动化 Skills 引擎，让 AI 通过 REST API 直接操控编辑器。它的批量操作（POST /skills/batch）是效率神器：一次 HTTP 请求、一条事务，就能按顺序执行最多 50 个技能步骤，并且支持用$ref跨步骤引用前面步骤的返回值，配合?mode=transactional事务模式实现失败自动回滚——全部成功才提交，任何一步失败则整体撤销，像数据库事务一样安全。

为什么批量操作是 Unity AI 自动化的必修课 🚀

让 AI 逐个调用技能接口，意味着 N 次 HTTP 往返、N 次唤醒 Unity 主线程，稍慢且容易中途断档。而POST /skills/batch端点把 N 个技能调用合并为一次往返、一次主线程唤醒：

• 每个步骤仍走完整的单技能流水线（参数校验、权限门、独立 Undo 组、审计日志），安全不打折
• 步骤数上限 50，超过会被400 SEMANTIC_INVALID拒绝，此时拆分调用即可
• 每个步骤都有独立的status（success / error / skipped），结果一目了然

批量技能文档入口：skills/batch/SKILL.md

$ref 跨步引用：让步骤之间"接力传值" 🔗

批量脚本中最常见的痛点：第二步要用到第一步创建的对象。以往只能靠对象名查找，而同名对象可能"撞车"。$ref的解法极其优雅——用 JSON 节点直接引用前面某个成功步骤的返回结果：

{ "steps": [ {"skill": "gameobject_create", "args": {"name": "Cube", "primitiveType": "Cube"}}, {"skill": "component_add", "args": {"instanceId": {"$ref": "$0.instanceId"}, "componentType": "Rigidbody"}} ] }

规则速览（详见 SkillsHttpServer.BatchRefs.cs 实现）：

官方建议：新建对象请通过$ref引用instanceId（Unity 6000.4+ 还有entityId），而不是靠名字查找——同名已有对象可能优先命中，这是批量脚本最常见的隐性 bug。

事务模式：失败自动回滚的"要么全做、要么全不做" 🛡️

普通模式下（continueOnError:false）遇到失败会停止后续步骤，已成功的步骤保留——这是"快速失败"。但当你希望整组操作要么完整生效、要么原样撤销时，加上?mode=transactional即可：

1. 全有或全无：任何一步失败，所有已执行步骤通过 Unity Undo 机制逐一回滚，响应返回status:"rolled_back"、rolledBack:true，每个已执行步骤被标记为rolled_back
2. 前置拦截：请求在真正执行之前就会做预检——continueOnError:true、未知技能、或可能触发域重载（Domain Reload）的步骤，直接400拒绝，绝不让事务"半成品"上路
3. 诚实提示边界：会写磁盘资产（Asset）的步骤会标记rollbackReliability:"partial"，因为 Undo 无法完全还原已落盘的资产写入——工具不会假装万无一失

⚠️ 注意：同一张图片在本文中已使用，此处请忽略重复占位——实际排版时建议在此处引用编辑器窗口截图。

先 dryRun 预演，再 diff=1 复查：批量操作的最快安全姿势 ✅

高手的三件套顺序，一条命令都不用改，只换 Query 参数：

• ?mode=dryRun：校验全部步骤但不执行、永不停车。允许某一步引用"稍后才创建"的对象（会附警告），$ref参数只做结构性检查并返回refsValidated
• ?mode=transactional：正式执行，失败整体回滚
• ?diff=1：追加净变更sceneDiff（changed / added / removed），回滚后同样能生成最终 diff，一眼看清"这 50 步到底改了什么"

完整协议细节见 references/SKILL_FULL.md 与 protocol-error-codes.md。

部分失败怎么办？只补发失败步骤 🔧

非事务模式下若出现status:"partial"，响应中的results数组会按index标明每一步的结局：

• success步骤的修改已生效，不要重发
• 失败步骤的 Undo 已记录变更会被自动撤销
• skipped步骤从未运行——把修好的失败步骤 + 所有 skipped 步骤重新提交即可

授权类响应（MODE_RESTRICTED/CONFIRMATION_REQUIRED）无论continueOnError如何设置都会中断整个批次并返回授权 token；完成授权后再提交剩余步骤。

另外，批量事务与"预览后提交"（batch_execute+confirmToken，见 batch_execute.md）是两套机制：前者组合 N 个不同技能、无需 token；后者提交一个已预览的批量操作、必须携带一次性 confirmToken。大任务返回jobId后用GET /jobs/{id}?wait=<秒>长等待即可。

动手前的资源清单 📚

一句话总结：$ref解决"步骤间传值"，transactional解决"失败怎么办"。掌握这两招，你的 Unity-Skills 批量脚本就能像数据库事务一样稳。