Skip to content

v2.9.0

Choose a tag to compare

View all tags
@Besty0728 Besty0728 released this 03 Oct 17:26
· 13 commits to main since this release
v2.9.0
58d3339

v2.9.0 — Agent 调用 token 降至约三分之一 + 精度与正确性大修 + dryRun 策略开关 + 本地自更新双轨

⭐ Highlights

  • 同样的 Unity 任务，Agent 只花约三分之一的 token：根 SKILL.md 围绕"速查表 → 一次发现调用 → 直接执行 → 以写后读回为准"重写，配合 recommend 排序修复、多意图查询、写后读回与一条命令等完编译。在 Claude Code 无头模式（claude -p）下以 Sonnet 5 对 2.8.4 做配对实测，每次任务平均处理 token 从 274.5K 降到 72.4K，成本从 US$0.185 降到 US$0.071，API 调用中位从 10 次降到 4 次。明细见下表。
  • "什么都没做却报成功"的路径全部改为明确报错：round5 的 13 项加 round6 的 30 余项静默降级（材质属性名被静默替换、拼错的枚举被归到零值、找不到的目标被跳过、保存失败照报成功……）现在在第一次写入前返回结构化错误，附合法值或最接近的名称；写技能回带从 Editor 读回的实际状态，缺少可选包在校验阶段就报出。
  • dryRun 从文档建议变成服务端保证：新增按项目保存、默认关闭的 dryRun 策略开关（关闭 / 仅高风险 / 所有写入），打开后受门的写调用必须带同一请求体 dryRun 得到的一次性令牌才执行；令牌永远不能顶替 _confirm。
  • 自己写了 .cs 之后一条命令等完编译：asset_refresh 在触发脚本编译时返回可等待的编译作业；GET /jobs/{id}?wait= 长轮询被域重载打断时回可重试的 503，curl --retry 即可接上。
  • 本地开发安装的一键更新走 git 快进：file: / 嵌入安装在 UnitySkills 克隆上只做 --ff-only 同步官方同名分支，工作区有改动、分叉或不在 main / beta 时拒绝并说明原因；非 git 副本走可回滚的 ZIP 替换并保留上一版备份。
  • Windows 就绪：PowerShell 5.1 / 7 与 Git Bash 调用指南（references/windows.md）、带 BOM 的请求体与批量文件照常解析、CLI 新增 --params-file 绕开引号问题、405 响应给出可直接粘贴的 PowerShell 命令；Windows 2022.3 实机完整 EditMode 1602 项 0 失败。

📊 本版实测：2.8.4 → 2.9.0 真实任务消耗

被测 Agent 为 Claude Code 无头模式 claude -p，模型 Sonnet 5（claude-sonnet-5）；8 个 Unity 编辑器任务 × 冷 / 热会话，每单元 5 对配对运行，两版本在两台同配置 Unity 6000.3.9f1 上交叉执行，验收由脚本独立从 Editor 读回。token 为 Claude Code 报告的用量之和（输入 + 缓存读 + 缓存写 + 输出），成本为其报告的 total_cost_usd。

指标（设计问答以外的任务，每次任务平均） 2.8.4 2.9.0
处理的 token（processed tokens） 274.5K 72.4K（配对几何均值 0.32 倍，95% CI 0.29–0.36）
成本 US$0.185 US$0.071
API 调用次数（中位） 10 4
REST 调用次数（中位） 9 3.5
用于查找技能的 token 61.7K 2.5K
dryRun 次数 1.65 0.04
写后额外读回次数 0.94 0.21
任务（REST 调用中位） 2.8.4 2.9.0
建层级 11 2
批量改名并排列 9–11 1–2
组件赋值 15 5
挂脚本（写 .cs → 编译 → 挂载） 20 5
移动物体 6 2
  • 质量不降：设计问答以外的 80 对运行全部通过；设计类问答（热会话）通过率 3/10 → 10/10。round5 的精度修复对照 round4 候选再测 574 次：20 个任务单元通过数全部相同，token 持平（0.97 倍），脚本类任务再省约 10%–27%。
  • 注意：实际消耗随任务、模型、上下文与缓存状态变化，数字仅供参考；评测原始数据为本地记录，完整条件见 CHANGELOG"本版实测"与"评测与验证"。

Added

  • dryRun 策略开关（DryRunPolicyService）：按项目保存、三档；受门调用返回 DRYRUN_REQUIRED（HTTP 200，什么都没执行）并自带 v2 预览、新令牌与可直接重发的调用，所以一次允许的调用最多多一个往返。令牌一次性、300 秒有效，绑定技能名与规范化请求体哈希；/skills/batch 一批一个令牌。审计新增 dryrun_passed / dryrun_policy_changed；Python 客户端新增 dry_run_token= 与 CLI --dry-run-token。
  • asset_refresh 返回编译作业：触发脚本编译时响应带 compileTriggered:true、jobId、waitUrl（/jobs/<id>?wait=90）与 scriptChanges；作业落在刷新后第一次结束的编译上，有错误则 failed 并给出 resultData.compilation.errors。
  • 按实例预期执行：写请求可带 ?expectProject= / ?expectInstance=（或对应头），端口上答话的是另一个 Editor 时在入队之前返回 409 INSTANCE_MISMATCH，什么都不执行。
  • GET /jobs/{id}?wait=<秒> 长轮询（上限 120 秒），等待在主线程之外进行。
  • 发现与 schema 扩充：/skills 与 /skills/schema 的 names= 精确过滤；/skills/recommend 可重复 intent= 一次排序多个需求，并用 unavailable + missingPackages 标出缺包技能；wire=v2 精简输出；[SkillParam] 参数说明进入 schema（约 196 条）；42 个请求体必填参数在 schema 中如实标为 required。
  • 写后读回：gameobject_create、gameobject_set_transform、component_set_property、material_assign、灯光与 ProBuilder 等写技能返回从 Editor 读回的实际状态；gameobject_create 新增 rotX/Y/Z、scaleX/Y/Z 与 space。
  • script_create 的 content 参数：原样写入完整源码。
  • 本地自更新双轨（LocalGitSync / GitCliRunner）：见 Highlights；设置抽屉显示当前更新方式，三语新增 43 个本地化键。
  • Python CLI --params-file：从 UTF-8 JSON 文件（有无 BOM 都行）读取参数，命令行 key=value 覆盖同名键。
  • references/windows.md：PowerShell / Git Bash 调用写法与会静默出错的陷阱，事实均引用 Microsoft Learn。

Fixed

  • 13 项静默降级（round5）：material_set_color(_batch) 显式 propertyName 不再被换成默认色；material_create 的 savePath 归一化，Packages/<本地包> 不再写到 Assets/Packages/…；light_set_enabled_batch 省略 enabled 返回 MISSING_PARAM；gameobject_find 未知 layer / 组件与非法正则不再静默放宽；script_create 未知模板在建任何文件前拒绝；component_remove(_batch) 补上 RequireComponent 依赖检查；布尔与枚举严格词表；camera_set_transform / camera_look_at 的 instant 终于生效；batch_query_* 的 queryJson 全面校验。
  • 写后读回补齐（round5）：材质纹理 / 关键字 / 渲染队列、gameobject_set_parent(_batch)（嵌套 Prefab 成员在调用前识别并结构化报错）、gameobject_set_active、层 / tag 批量、camera_set_culling_mask、physics_set_material、ui_add_outline、prefab_set_property、prefab_instantiate_batch、component_copy、prefab_create(_variant) 等读回实际状态。
  • 工作流快照与撤销缺口：7 个 material_set_* 与 prefab_revert_overrides 补上 TracksWorkflow；component_copy 补 Undo、快照与 MutatesScene。
  • 长轮询被域重载打断时回空 200：改为可重试的 503 + Retry-After: 2。
  • recommend 排序与未知选择器键：离线金标 rank@3 由 73% 升到 89%；/skills 遇到形似选择器的未知键返回 400 UNKNOWN_PARAM，不再静默返回约 707 KB 的完整清单。
  • 执行、校验与批量可靠性：缺少可选包在 dryRun 阶段就报 MISSING_PACKAGE；执行失败返回与 dryRun 相同的完整报告；批量前向父引用；原子批量报告已回滚的项。
  • 元数据一致性：33 个 URP 家族存根补 RequiresPackages（没装 URP 时校验阶段终于报得出缺包）；文档参数表与代码的 26 处差异修正；按代码实际要求补齐 10 个技能的必填校验；3 处 Outputs 对齐。
  • 长尾模块的静默降级（round6）：terrain_paint_texture 负数 layerIndex、console_get_logs / debug_get_logs 未知 type、smart_scene_query 拼错的成员 / 运算符、uitk_create_from_template 未知模板、test_smoke_skills 未知分类、cleaner_find_duplicates 新增 skipped、debug_check_compilation 新增 lastCompilation、sprite_set_import_settings 的 pivot、XR 交互层掩码、YooAsset 报表过滤、QFramework 设置还原、图形设置剥离还原器。
  • 二次审计发现的静默降级（round6）：decal_set_properties 在 URP 14 上 renderingLayerMask 从未写入；Cinemachine 拼错的混合样式被静默改成 Cut、找不到的目标被跳过；scene_save / scene_unload / scene_set_active 丢弃返回值；scene_find_objects 未定义 tag 得到 count: 0；scriptableobject_set 只读属性；ui_create_image / ui_create_rawimage 解析不了的路径仍建出空组件；package_install_cinemachine 非法版本；HybridCLR 三个还原器吞掉失败；DOTween ease 按成员校验、写入失败撤回组件；Netcode networkTopology 先校验先快照；urp_set_asset_settings 缺字段整次不写。
  • 可选包实测发现的三处缺陷：xr_configure_interaction_layers 从未写进过掩码（op_Implicit 转换）；无 HybridCLR 设置文件的工程切换场景后 hybridclr_settings_set 以 INTERNAL 结束；Behavior 未安装时直接声明 MISSING_PACKAGE。
  • 装了 NGO 但关闭了内置 2D 物理 / 物理 / 动画模块的工程里整个包编译失败：UnitySkills.Editor.asmdef 镜像 NGO 的 COM_UNITY_MODULES_* 版本定义；缺模块时对应三个技能返回 MISSING_PACKAGE。
  • CI 在全部 6 个 Unity 版本上恢复绿色：测试夹具程序集不再依赖 Physics 模块；batchmode 下无法满足前置条件的测试改为 Assert.Ignore，退出码回到 0。
  • 跑测试会清空用户的 allowlist：新增 ModePreferenceSnapshot，五个偏好键全存全还原。
  • 2022 首次导入会改写 18 个手写 .meta：改为提交 Unity 自己写出的完整形式，git 克隆安装不再变脏。
  • Windows 回归：材质创建 / 复制在 Windows 上未创建父目录导致 CreateAsset 失败；本地 Git 自更新的克隆目录名按平台路径规则比较；Python CLI --batch 读不了带 BOM 的文件。

Changed

  • 根 SKILL.md 重写并定稿（8189 字节）：/health 改为会话开始时探测一次并与第一个请求写在同一条命令里；速查表写明按 name / path / instanceId 直接定位、不必先发查找调用；"dryRun 通过才建脚本 → 等编译 → 一个 batch 里挂组件并设值"写成一条 shell 命令。移出的内容进入 references/protocol-discovery.md。
  • 四个试点模块文档拆分：gameobject / component / batch / script 拆成入口 + 每个技能一个 reference/<skill>.md，入口字节预算写进测试；新增 DocExampleValidationTests 校验所有文档调用示例。
  • 对技能发 GET 返回 405：GET /skill/<name> 不再执行，details.curl / details.powershell 给出改写好的 POST。
  • Addressables 7 个技能声明 RequiresPackages = com.unity.addressables，与其他 UPM 检测模块一致；addressables_check_installed 仍是探针。
  • 三个核心类拆成分部类文件：SkillsHttpServer（14 个文件）、SkillRouter（11 个）、SkillPlanningService（12 个），最大文件从 5,938 行降到 1,081 行；响应逐字节不变。
  • git 自更新层只经 LocalSelfUpdateService 访问，由 SelfUpdateBoundaryTests 守卫。
  • 共用辅助函数抽取（SkillParamUtil.TryParseBoolText、SkillsCommon.ClosestMatch 等）。

验证

  • 新增 Tests/Editor/OptionalPackages/ 87 个可选包真实路径测试（URP / Decal / Volume / PostProcess / Cinemachine 2 & 3 / Timeline / Netcode / Addressables / HybridCLR / Behavior / DOTween Pro / PrimeTween / YooAsset / XRI 2 & 3 / ProBuilder 5 & 6 / QFramework），6000.3 装齐包 80 通过、2022.3 52 通过，均 0 失败。
  • 假绿防护：文档标题级别、必填参数扫描、Outputs 契约、meta / locale 覆盖度、技能总数核对各加守卫与反例夹具。
  • 实机回归：Windows 2022.3.48f1c1 EditMode 1602 项 1521 通过 0 失败；macOS 6000.3.9f1 1601 项 1516 通过 0 失败；macOS 2022.3.62f2 1602 项 1509 通过 0 失败。

Compatibility

  • Unity 2022.3+，在 6000.x 上验证；CI 矩阵 6 个版本全绿。
  • 805 个技能不增不减，没有删除任何参数。 纠正性变化：若干参数按代码实际要求改为必填（如 animator_add_state / animator_add_transition / material_create.name / smart_reference_bind.targetName，完整清单见 CHANGELOG"元数据一致性"），8 个技能补 tracksWorkflow，21 个技能 Outputs 只增。
  • 行为变化需留意：GET /skill/<name> 现在返回 405 而不执行；/skills 与 /skills/schema 对形似选择器的未知键返回 400；dryRun 策略开关默认关闭，关闭时响应与之前逐字节一致（只有 /health、/permission/status、unity_diagnose 多一个 dryRunPolicy 字段）。
  • 可选包：Addressables 技能现在声明依赖包；NGO 工程若关闭内置 2D 物理 / 物理 / 动画模块，对应三个 Netcode 技能返回 MISSING_PACKAGE 而不是整包编译失败。
  • 本地 file: / 嵌入安装的一键更新改为 git 快进；有 .git 却找不到可用 git 时拒绝更新，请先安装 git。

完整更改日志见 https://github.com/Besty0728/Unity-Skills/blob/main/CHANGELOG.md

Assets 2
Loading