v2.9.1 — 直接编辑预制体资产、运行时方法调用与场景验证、持续保存的 Console 日志

⭐ Highlights

• 不放进场景也能改预制体：29 个新技能直接查询和修改 .prefab 里的节点、组件、序列化属性与引用；同一资产上的多步修改要么全部生效、要么一个都不保存，可以撤销，变体和嵌套预制体的连接保持不变。
• 让 Agent 验证运行时行为：可以列出并调用组件或静态 C# 方法（支持重载、泛型、ref/out、Task 与协程），editor_run_scenario 把"调用 → 等待 → 断言"打包成一次验证；配套 Python 脚本能自动跑"编译 → 验证 → 修复"循环（最多 3 次）。
• Console 日志不再丢：日志持续保存并带时间，可以分页、按时间段查、合并重复项；Play 期间刷屏的错误也会被完整计数。
• 更稳：编译结果绑定到"这一次"编译；所有请求统一在主线程处理；Python 客户端等待任务时不会连到别的 Unity 实例，也不会重复执行结果不明的写操作。
• 感谢新赞助商 Mirasim：为即将发布的 v3.0 提供大量 API 额度支持。

Added

• 预制体资产编辑（29 个技能）：4 个只读查询；组件增删与启用、序列化属性与引用、节点创建 / 复制 / 删除 / 改名 / 换父节点、变换、激活状态、同级顺序共 12 组单项 + 批量技能；prefab_edit_batch 在单个资产上按序执行全有或全无的事务。参数与返回见 skills/prefab/ASSET_EDITING.md。
• 组件与静态方法的发现和调用（4 个技能）：component_get_methods(_batch)、component_invoke_method(_batch)，记录返回值、异常、执行帧与日志；默认要求 Play Mode，调用本身不会进入 Play Mode，不进入承诺回滚的事务批次。
• editor_run_scenario：调用、读取、等待与断言组合成一个异步验证作业，返回实际值与行为证据。
• scripts/runtime_verification.py：编译验证、场景执行与调用方提供的修复回调，默认最多修复 3 次、总计 30 分钟；插件与脚本本身不调用模型。
• Console 日志历史：持久化托管日志（UTC 时间），固定快照游标分页、类型 / 内容 / 时间窗口过滤、完整堆栈与覆盖缺口标记。
• skill-creator 指南：在自己的工程里编写 [UnitySkill] 自定义技能。
• 面板页脚 GitHub 按钮（三语 tooltip）。

Changed

• console_get_logs：默认合并完全相同的重复日志（collapse=true），新增游标、时间窗口与完整性字段；source 的取值改为 history / capture_session。原有 type / filter / limit 用法不变。
• console_export / console_get_stats：读取持久化历史，并报告有界保留是否截断（complete / dropped / truncated）。
• debug_force_recompile：返回可追踪的 jobId 与 waitUrl。
• 编译证据：脚本写入、asset_refresh 与强制重编译只采用自己触发的那一次编译结果；asset_refresh 的权限分类与 2.9.0 相同，Auto / Approval 模式下照常可用。
• HTTP 主线程调度：GET 请求也在主线程处理，/health 新增若干主线程诊断字段。
• Python 客户端：作业轮询固定原 Editor 身份；结果不明的写请求不自动重放。
• 技能重名告警与卸载保留用户自己添加的文件。

Fixed

• prefab_set_property：改由新的资产编辑引擎执行后，仍接受抽象基类作为组件类型、返回实际组件类型名，响应键与 2.9.0 相同。

Docs

• 技能与模块计数、NeverInSemi 清单同步到 839 个技能 / 83 个模块文档；6 个技能的返回形状按代码修正；skill-creator 示例改用实际存在的 SkillOperation.Query。

Compatibility

• Unity 2022.3+：CI 在 2022.3.62f1、6000.0.76f1、6000.2.11f1、6000.3.18f1、6000.4.12f1、6000.5.0f1 上 EditMode 全部通过，另在本机 2022.3.62f2 与 6000.3.9f1 完整回归。技能 805 → 839（+34），没有删除任何技能或参数。
• 行为变化仅限上方 Changed 中列出的 Console 相关输出（默认合并重复日志、source 取值）。
• Unity 6000.4+ 上旧的 instanceId 恒为 0：component_invoke_method 请用 entityId（或 path / name）定位对象；它返回的 Unity 对象同时带 entityId 与 instanceId。

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

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。

• 质量不降：设计问答以外的 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

v2.8.4 — 面板拖窗卡顿收敛 + 多实例连错防护 + AI 工具副本防降级

⭐ Highlights

• Windows 拖窗卡顿修复（#60）：技能列表改为定高 ListView 虚拟化，只渲染视口内的行；拖窗期间 Token 轨道临时降级为减列切片，并与 60 fps 动画彻底解耦，根治 Unity 6000.x 双源重绘导致的轨道撕裂。感谢 @Yuyuyuxmy 报告 issue #60 并贡献修复 PR #61！
• 多实例连错防护：多个 Unity 工程同开时，每个 HTTP 响应携带 X-Unity-Instance / X-Unity-Project 头，协议首次握手要求核对 projectName，裸 curl 连错编辑器也能立刻发现。
• AI 工具副本防降级：本机旧版本工程打开时，不再把另一工程已升级的全局 skill 副本（~/.claude/skills/unity-skills 等）覆盖回旧版本。
• 可选的 Agent 引导行：设置抽屉新增开关（默认关闭），开启后自动在各 AI 工具的根指令文件追加一行「use Unity Skills」引导，关闭即无痕移除。

Added

• 多实例身份标识：五条响应路径统一附加 X-Unity-Instance / X-Unity-Project 头（SkillsHttpServer），HTTP 线程零 Unity API。
• 多实例引导文档：根 SKILL.md 首次握手核对 projectName；协议文档新增 "Which Editor answered? (multi-instance)" 小节，写明自动发现顺序、--list-instances / --port 用法与静默回退条件。
• 可选的 Agent 指令文件引导行：设置抽屉开关（默认关闭）控制向 Claude Code 的 CLAUDE.md、Codex / Antigravity / Cursor / OpenCode / Kimi Code 共用的 AGENTS.md 等根指令文件追加 / 移除一行引导；按整句精确匹配、不留标记注释。

Fixed

• Token 等级「全量」档横向拖窗卡顿（#60，PR #61）：技能列表虚拟化 + 拖窗期间轨道降级切片；动画与拖窗解耦，6000.x 延迟网格管线的双源撕裂根治。报告人在 Windows 11 / 2022.3.62f3c1 确认改善。
• 设置抽屉两个开关滑块错位：换成标准 ui:Toggle，与其他设置项一致。
• AI 工具自动同步不再回写共享副本：安装时写入版本印记，逐目标比较后仅向更旧的副本刷新，副本更新则跳过并提示。

Changed

• Unity CLI 顾问文档对齐 1.0.0-beta.9：测试失败退出码拆分为 8（6 仅表示未得出结论）；冷启动新增 doctor --ci / projects verify 只读前置检查；补齐 test --retries / build --timeout 等新参数；DO NOT 清单扩充 close / vcs / plugin 等命令。
• agent.md 改名为 AGENTS.md：重写为面向 AI 的紧凑英文常驻上下文，根目录新增 CLAUDE.md 指向它。

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

v2.8.3 — Agent 身份可信归因 · 本地安装一键自更新 · 三语文案修复

⭐ Highlights

• AI Agent 真实身份归因：服务端不再依赖 AI 工具"自报身份"，改由 TCP 源端口反查客户端进程并沿父进程链归因——裸 curl 调用也能正确记为 ClaudeCode / Codex / Antigravity 等；审计日志与遥测首次带上 agent 字段，新工具无需改代码即可被识别。
• 本地安装一键自更新：ZIP 解压 / embedded 的 file: 引用此前只能手动更新，现在与 git 安装一样在编辑器内一键升级到最新版；下载带可取消进度条，更新后各 AI 工具的技能文件自动同步。
• 三语文案体验修复：更新页与多处面板切换语言后立即重新解析，不再停留在旧语言；字体图集补齐缺失汉字，并新增防误烤护栏。
• 启动日志精简：正常启动 / 域重载从 7 行降到 1 行。

Added

• AI Agent 进程链身份识别：排除表驱动（shell、终端宿主、curl/npm/git 等中间进程一律跳过），第一个未排除祖先即 Agent；解释器托管 CLI 解析命令行提取包名；端口→PID 在 accept 线程同步完成（实测 1–4ms）。三平台实现：macOS libproc/sysctl、Linux 纯 /proc、Windows GetExtendedTcpTable + Toolhelp32 + PEB；任一环节失败静默降级回 User-Agent。默认开启，可按工程关闭。
• 审计日志与遥测记录 agent 字段：审计窗口同步展示；历史记录不回填。
• 字体图集增量补字工具：原地追加字形不重建，Bake() 增加超集校验护栏。
• 本地安装（ZIP 解压 / embedded）一键自更新：从 GitHub 归档 zip 解出 SkillsForUnity 子树，校验后原子换目录并触发重编译；失败原因（网络 / 磁盘 / 校验 / 路径 / 取消）本地化展示。

Changed

• 遥测与审计改为落盘时绑定 agent：不再入队即定稿，杜绝 agent 字段被过早写死。
• 启动日志精简：只保留 REST Server started … · N skills · Instance 一行；首选端口被占自动回退时新增一条 Warning。

Fixed

• 更新页与多处面板切换语言后文案不刷新（含 beta 目标混排、横幅进度被覆盖、英文哨兵透传）。
• 字体图集缺失 3 个汉字（Unity 2022 静态图集下缺字）。
• 根 SKILL.md 字节预算测试在 Windows 检出下假红（#59）：改为 LF 归一化计量，新增 .gitattributes 锁定行尾。
• 进程链归因把解释器脚本当成 Agent 身份：内联代码（-c/-e）误判、带空格路径碎裂、脚本名截断走链三类错标全部修复；显式 X-Agent-Id 与进程链解析拼写统一。

Compatibility

• Unity 2022.3 LTS 与 Unity 6 均通过编译与 EditMode 测试矩阵。
• 已知限制：Windows 上陈旧 ppid 被复用存在概率性误归因（平台固有，概率极低）；本版之前的审计历史记录无 agent 字段。

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

v2.8.2 — 面板一键更新 + DontDestroyOnLoad 层级全链路可见

⭐ Highlights

• 面板内一键更新：设置抽屉新增"检查更新"按钮——点一次强制检查，发现新版本后按钮变成"更新到 vX.Y.Z"，再点一次直接在编辑器里完成更新并重编译生效，不用再打开 Package Manager 手动操作。更新目标跟随你的安装方式：稳定版安装更到最新稳定 Release，#beta 安装更到 beta 分支最新提交。顶部更新横幅也新增"直接更新"按钮，一键升级到横幅所示版本。
• DontDestroyOnLoad 对象终于可见：Play 模式下 Object.DontDestroyOnLoad 保留的对象此前对所有层级/查找技能隐身，现在层级树、文本树、场景上下文、组件列表与属性读写全链路覆盖，与正常场景对象能力一致。
• 开关样式修正：设置页蓝色开关的白色圆点垂直居中，不再偏下。

Added

• 设置页"检查更新"按钮（两步交互） — 强制检查跳过 24 小时缓存与"忽略此版本"标记；稳定版安装更新到最新稳定 tag，#beta 安装通过 commits/beta SHA 比对更新到 beta 最新；本地（file: / embedded）安装明确提示不支持自动更新。中/英/俄三语文案齐备。
• DontDestroyOnLoad 伪场景全链路可见（Play 模式） — 统一查找器接入伪场景根枚举，按 name/path/tag/component 查找与组件读写全部生效；scene_get_hierarchy 追加 DDOL 子树（节点新增 scene 归属字段）；scene_get_loaded 列出伪场景条目；hierarchy_describe 输出独立 DDOL 区段；scene_context / scene_export_report / scene_summarize 统计口径一致。

Changed

• 版本号更新 — SkillsLogger.Version / package.json / Python helper __version__ / agent.md 同步提升到 2.8.2。

Fixed

• 设置开关白色圆点垂直偏下 — 开关圆点改为 flex 居中，消除手工 margin 取整造成的视觉偏移。

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

v2.8.1 — 元数据真实性核对、Token Level 截断修正、客户端与面板小修

⭐ Highlights

• 技能元数据与实现一致：194 个会改场景或写资产的技能补齐了 MutatesScene / MutatesAssets 声明，?wire=v2 的 flags 不再漏报，noSceneAuthoring 档不再放过仍会改场景的技能；新增守卫测试防止再次漂移。
• 参数必填声明可信：98 个技能此前空 body 也能通过 dryRun，现在在执行前就返回 MISSING_PARAM / SEMANTIC_INVALID；32 个批量技能的必填令牌改为真实参数 items。
• Token Level 截断按档位生效：Minimal 档（页大小 5）下 6–10 项数组此前原样全返、Full 档（页大小 20）下 11–20 项被误包截断元数据，现阈值与页大小同源；/health 新增 summaryAutoTruncate / summaryPageSize / tokenLevel，调用方无需再事后反推。
• Python 客户端修三处并补封装：set_unity_version("6.2") 不再误匹配任意 6000.x 实例；get_job_logs 改走轻量 GET /jobs/{id}/logs；find_skills 新增 include_schema / wire；新增 get_meta()、execute_batch() 与 CLI --meta / --batch。
• 面板与 CI 细节：切换 Surface Profile 后已隐藏技能不再残留在详情栏；内联样式收敛为 USS class；删除 27 个无引用本地化键；check_locales.py 补上三元表达式与格式化重载的检测盲区。

Added

• /health 暴露 Token Level 设置 — 新增 summaryAutoTruncate、summaryPageSize、tokenLevel（minimal / standard / full / maximum / custom）三个字段；references/protocol-operating-mode.md 新增 Token Level 一节，给出四档预设与 (SurfaceProfile, SummaryAutoTruncate, SummaryPageSize) 的精确映射及分页方式。
• Python 客户端新封装 — get_meta(force_refresh=False)（GET /skills/meta，会话内缓存）与 execute_batch(steps, dry_run, continue_on_error, diff, mode)（POST /skills/batch，只发送服务端接受的键）；find_skills 新增 include_schema / wire；CLI 新增 --meta、--batch FILE、--batch-mode、--diff。
• 守卫测试 — SkillsRecordingUndoOrSnapshots_DeclareMutatesSceneOrAssets、RequiresInput_SingleTokensNameARealParameterOrGroupKey、截断阈值两条端到端用例；三个测试类补钉 Full 档，避免在 guide / noSceneAuthoring 档的机器上误红。

Changed

• 194 个技能补齐 MutatesScene / MutatesAssets（行为变更） — 场景对象操作（GameObject / Camera / Cinemachine / Component / Light / NavMesh / ProBuilder / Sample / Smart / UI / XR 等）标 MutatesScene；写 .asset / ProjectSettings 的操作（Terrain / Timeline / Animator / Audio / Physics / Prefab / ScriptableObject / Shader / Graphics / Project / Debug 等）标 MutatesAssets。noSceneAuthoring 档新增隐藏 validate_fix_missing_scripts；7 个只写 EditorPrefs 或只记录快照的技能有据豁免。URP 家族无 URP stub 的声明与真实现逐字对齐。
• 98 个技能改为前置拒绝空 body（行为变更） — 24 个 RequiresInput 语义定位令牌（vcam / terrain / director / animatorController / audioAsset 等）登记为组键或改为真实参数名；66 个技能补上缺失的 RequiresInput；selection / selectedGameObjects 改为专用语义检查。Timeline 文档 trackName / bindingObjectName 的 Required 列改为 Yes。
• 32 个批量技能的 RequiresInput 改为 items — schema required 与 dryRun 对齐，只传 items 的合法调用不受影响。
• 面板 — 切换 Surface Profile / Token Level 后清除失效选中；新增 .is-hidden 工具类与 UiVisibility.SetVisible，约 34 处内联 style.display / 固定布局常量改为 class；删除昨日 topbar 提交的死代码（ApplySettingsIcon、💡 剥离），窄屏权限徽章让位改为 USS 变量。
• 删除 27 个无引用本地化键（三语同步，1086 → 1059）。
• PlayCaptureService 参数校验先于编辑器忙检查。
• 版本号更新 — SkillsLogger.Version / package.json / Python helper __version__ / agent.md 同步提升到 2.8.1。

Fixed

• Token Level 自动截断阈值未随档位变化 — 触发条件硬编码"超过 10 项"，现与 SummaryPageSize 同源。
• Python _version_matches 丢弃 Unity 6 小版本 — 仅裸 "6" 通配，"6.N" 精确到 6000.N. 前缀。
• Python get_job_logs 走主线程重路径 — 改用服务端既有的轻量 GET /jobs/{id}/logs?limit=N；skills/batch/SKILL.md 补交叉引用。
• 7 个导入设置技能的 RequiresInput 幽灵令牌 — textureAsset / modelAsset / audioAsset 改为真实参数 assetPath。
• check_locales.py 假绿盲区 — 三元表达式、Get(key, args) 重载、TryGet / Has 此前全部漏检，现识别 352 处引用。
• Localization.cs 直调 Debug.LogError — 改走 SkillsLogger.LogError。
• docs/SETUP_GUIDE(_CN).md 过期 — 指定版本安装示例与模块计数（54 REST + 28 advisory = 82、805 技能）更新。

Compatibility

• 技能总数不变（805），端点集合不变；/health 仅新增字段，v1 已有字段逐字节不变。
• 行为变更集中在"此前错误放行"的路径：空 body 由 valid:true 改为前置拒绝、?wire=v2 的 flags 更真实、noSceneAuthoring 档多隐藏 1 个技能。合法调用不受影响。
• Unity 6000.3 与 2022.3 EditMode 全量回归均 0 失败。

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

v2.8.0 — JSON 多语言解耦架构、多 Tab 窗口与 Tab 可见性配置、Skills Token Level 过滤

⭐ Highlights

• 多语言体系解耦为独立 JSON 资源：将原 Localization.cs 中近 3,800 行的硬编码词典重构为独立的外部 JSON 文件（en.json、zh-CN.json、ru.json），1086 个词条 100% 严格对齐，大幅缩减代码体积与编辑器编译内存开销，并引入 CI 自动化多语言对齐检查工具与完整单元测试。
• UnitySkills 窗口多 Tab 架构升级：主窗口全面升级多 Tab 布局体系，新增 Tab 可见性持久化配置（TabVisibilitySettings），支持灵活自定义展示/隐藏各功能面板，并将 Unity CLI Tab 深度集成至主窗口。
• Skills Token Level 档位过滤：新增 Token 预算控制档位（Compact / Normal / Verbose）与可视化滑块控件，支持按预算动态调节技能元数据与 Schema 输出载荷，有效控制 AI 上下文 Token 消耗。
• UPM 测试程序集依赖修复：在 package.json 显式声明 com.unity.test-framework 依赖，彻底解决无头 CI 环境与独立 UPM 导入场景下的测试程序集编译问题。

Added

• JSON 多语言本地化体系与 CI 校验 — 新增 SkillsForUnity/Editor/Locales/ 目录（en.json、zh-CN.json、ru.json，各 1086 词条完整对齐），重构 Localization.cs 为轻量化 JSON 运行时加载器；新增 .github/scripts/check_locales.py CI 检查工具与 SkillsLocalizationTests 自动化测试。
• UnitySkills 窗口多 Tab 架构与 Tab 可见性设置 — 新增 TabVisibilitySettings 配置与持久化机制，支持自定义控制各功能 Tab（Unity CLI、Settings 等）的展示与隐藏；新增 UnityCliTabController 与 UnityCliTab.uxml 面板集成；新增 UnitySkillsWindowTabTests 单元测试。
• Skills Token Level 载荷过滤机制 — 新增 SkillsTokenLevel 枚举与 TokenLevelSliderWidget 滑块控件，支持按 Token 预算过滤技能元数据与 schema 输出；新增 SkillsTokenLevelTests 测试用例。

Changed

• Localization.cs 架构精简 — 移除近 3,800 行硬编码字典，改由 JSON 驱动，大幅降低编辑器内存占用与启动编译耗时。
• UI 控制器体验重构 — 优化 SettingsDrawerController、SkillsTabController、PendingApprovalBannerController、AIConfigTabController 与 UnityCliWindow 的交互与状态同步。
• 版本号更新 — SkillsLogger.Version / package.json / Python helper __version__ / agent.md 同步提升到 2.8.0。受支持版本表（.github/SECURITY.md）同步到 2.8.x。

Fixed

• 测试程序集依赖缺失 — 在 package.json 中补齐 "com.unity.test-framework": "1.1.33" 依赖，修复无头模式与纯 UPM 导入下的单元测试编译与运行问题。

Compatibility

• 完全向下兼容，既有 805 个 REST 技能与所有端点契约保持一致。
• 语言包文件位于 SkillsForUnity/Editor/Locales/，支持 Unity 2022.3+ 及 Unity 6000.x 全版本。

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

v2.7.1 — QFramework 双轨支持（20 个新技能 + 架构设计指导），源码注释全面英化

⭐ Highlights

• QFramework 支持落地：让 AI 直接在 Unity 里给 QFramework 项目生成架构层代码（Architecture / System / Model / Command / Utility / Query）、生成 ViewController 与 UIKit 面板绑定代码、管理 ResKit 的 AssetBundle 标记与构建，并能扫描项目里已有的架构实现类。技能总数 785 → 805。
• 未安装 QFramework 也完全无感：QFramework 没有 UPM 包（只能以 unitypackage 或单文件 QFramework.cs 装进 Assets/），因此本模块零编译期依赖、纯反射探测——没装时不激活、不报错、不影响编译，只有被调用的技能返回明确的 MISSING_PACKAGE 提示。
• 配套架构设计指导：新增 qframework-design advisory 模块（8 份中文文档），把四层分层红线、CQRS 用法、BindableProperty、各 Kit 的坑逐条锚定到 QFramework 源码或官方教程行号，供 AI 在写 QFramework 代码前加载，避免凭记忆产出过时 API。
• 英文注释基线：仓库源码注释统一为英文（144 个文件、约 5,420 行），便于国际协作与阅读。

Added

• qframework REST 模块（20 个技能） — 架构层代码生成（含 batch 变体，同名文件拒绝覆盖）、ViewController 绑定代码生成、UIKit 面板代码生成、UIKit 项目设置读写、ResKit AssetBundle 标记（幂等封装，含 batch）与标记列表、ResKit 构建选项（SimulationMode / append-hash / auto-generate-class）、AssetBundle 构建与清理、架构实现类扫描、QFramework 内置 API 文档特性查询、LocaleKit 语言配置。
• qframework-design advisory 模块（8 份文档） — 分层职责与通用规则、CQRS 与 BindableProperty、事件工具与两套 IOC 容器辨析、CodeGenKit + UIKit、ResKit、ActionKit + SingletonKit + AudioKit、数据结构类 Kit。明确标注了官方教程尚未同步的破坏性变更：RegisterSystem / RegisterModel / RegisterUtility 自 2026-08-12 起返回注册实例而非 void。
• SkillCategory.QFramework 与 60 条三语技能描述 — GET /skills/schema?category=QFramework 即刻可用。

Changed

• 源码注释统一为英文 — 144 个文件约 5,420 行，仅保留 7 行必要的中文引用（界面文案、上游第三方提示串、中文关键词映射表键名）。CONTRIBUTING.md 与 agent.md 已登记该规范。
• 13 处 API 响应文案改为英文 — 覆盖 Cinemachine 缺包与 Splines 版本提示、包安装/移除的瞬时不可用提示、Timeline 路径语义校验提示、测试脚本创建提示，与响应中既有的英文字段保持一致。多语言本地化文案不受影响。

Fixed

• MODE_RESTRICTED 授权提示中英混杂并泄露内部代号 — 发给调用方的 Dialog 通道提示已改写为纯英文，与 Panel 通道表述一致。
• 文档与代码的两处漂移 — CONTRIBUTING.md 的功能模块计数（55 → 54）、skills/cinemachine/SKILL.md 引用的缺包提示原文。

Compatibility

• 无破坏性变更，既有 805 个技能的调用契约不变；未安装 QFramework 的项目行为完全不受影响。
• QFramework 侧锚定 v1.0.257（2026-08 快照）。安装方式为官方 unitypackage 或单文件 QFramework.cs，没有 UPM 包；已装版本以编辑器内 PackageKit 面板为准（GitHub Release tag 滞后于作者实际迭代）。
• 验证：无头编译 0 error（41 条既有 warning 不变），EditMode 641 项测试 0 失败。

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

v2.7.0 — 治理面（Surface Profile）三档裁剪、wire v2 紧凑载荷、785 技能全量彻查修复、AI 工具安装自动同步

⭐ Highlights

• 接口载荷大幅瘦身（上下文安全保险）：裸 GET /skills 默认返回精简目录（678KB → 20.7KB，−97%），完整清单走 ?full=1；新增 ?wire=v2 紧凑载荷与一次性会话常量端点 /skills/meta。意义在于杜绝"一次误拉数百 KB 打爆上下文窗口"与长会话摊销——实测单任务对话 token 并不因此下降（真实前后数据见下方「对话 Token 实测」表）。
• Surface Profile 三档治理面：full / guide / noSceneAuthoring 按场景裁剪 AI 可见的技能面，并在执行期强制（batch/workflow 绕行入口同样被拦），不依赖 AI 自觉。
• 785 技能全量彻查：逐一真机实测后修复约 40 个"报成功但零效果"的静默 no-op 与一批误导性错误，49 处枚举参数从静默接受改为结构化拒绝（SEMANTIC_INVALID + validValues）。
• AI 工具安装自动同步：升级插件后，已安装的 AI 工具 SKILL.md 副本自动刷新到新版本，无需再回面板点安装；从不自动安装新目标，可在设置中关闭。

📊 前后对比

对话 Token 实测（真机 A/B：同任务、同模型、对照 subagent，token 从转录统计）

短任务：

长任务：

如实结论：单任务端到端 token 没有下降、普遍略升（+6~20%）——新版 agent 把省下的载荷预算花在了更多 dryRun 预演与交叉验证上（同类 recommend 调用的单位成本 −46%），两版全部任务 100% 成功、无一次因新协议打错调用。载荷层面仅作文字说明：裸 GET /skills 678KB→20.7KB（−97%，旧版一次误拉约 17 万 token 可直接打爆上下文、实测确有 agent 命中）、job_status 轮询 74KB→0.5KB、完整清单 ?wire=v2 −28%——这些换来的是上下文安全与长会话摊销 + 更高的验证质量，不是每个任务立省 token。

行为修复（假成功 → 真实结果）

Added

• Surface Profile 三档治理面（面板下拉切换，三语），执行期强制含 batch/workflow 入口
• ?wire=v2 紧凑清单、GET /skills/meta 会话常量、dryRun authorization 授权预览
• cinemachine_set_lens 支持 mode 投影覆盖（Orthographic / Perspective / Physical / None）
• AI 工具安装自动同步（SkillInstallSyncService，日志跟随面板语言 英/中/俄）
• light_get_properties 只读别名（技能总数 784 → 785）
• Addressables 模块文档补齐（8 技能，此前零文档）；模块文档 80 个（53 REST + 27 advisory）
• 新增约 300 条 EditMode 契约/治理/同步测试，双版本（2022.3 / 6000.3）全绿

Changed

• 裸 GET /skills 默认精简目录；/health 响应新增 surfaceProfile 等字段（移除 guideModeHint）
• job_status / job_wait 默认不携带明细（includeDetails=true 恢复）
• /skills/batch 未知键返回 400；约 121 个技能空请求体的错误码从 TARGET_NOT_FOUND 修正为 SEMANTIC_INVALID
• 两个 UI Toolkit .cs 生成器因声明 MayTriggerReload，在 Approval/Auto 下改为 MODE_FORBIDDEN（Bypass/Allowlist 可用）

Fixed

• 785 技能全量彻查修复约 40 项（静默 no-op / 误导错误 / Outputs 幽灵键 / RequiresInput 缺失）
• script_move 目录创建未注册、错误分类器可被调用方输入劫持、DOTween 索引错位与数值静默重置
• 高错误率技能全部复测 ≈0% 错误率

Docs

• 双语 README 瘦身，深度细节下沉新文档 docs/OPERATING_MODES(_CN).md
• CONTRIBUTING 重写（PR 以 beta 为 base、fork 自跑编译矩阵）；SECURITY 支持版本表更新至 2.7.x

Compatibility

• Unity 2022.3+ / Unity 6（6000.3）双版本编译与测试矩阵全绿
• 可选包（Cinemachine 2.6+/3.x、DOTween Pro、Addressables、YooAsset 等）均为反射/守卫实现，缺包优雅降级
• 升级零操作：老安装保持 Bypass 行为不变；已安装的 AI 工具副本将自动同步到 2.7.0

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

v2.6.2 — Kimi Code 内建支持：AI 配置面板第 6 个一键安装工具

⭐ Highlights

• Kimi Code 一键安装：在 Window > UnitySkills 的 AI Config 标签页里，Kimi Code 现在和 Claude Code / Codex / Antigravity / Cursor / OpenCode 一样是一张独立卡片，点一下即可把 unity-skills 技能装进项目级或用户级目录，无需手动拷贝任何文件。
• 支持 KIMI_CODE_HOME：如果你用该变量隔离了 Kimi 的数据根目录，用户级安装会自动跟着走；没设置时回落官方默认的 ~/.kimi-code。
• Kimi 流量不再显示为 Unknown：审计日志现在能正确把 Kimi Code 的请求识别为 KimiCode，与其余 5 个工具口径一致。

Added

• Kimi Code 内建支持（AI 配置面板第 6 个工具） — 支持项目级 .kimi-code/skills/unity-skills/ 与用户级 $KIMI_CODE_HOME/skills/unity-skills/（默认 ~/.kimi-code/skills/unity-skills/）两种安装位置，安装路径取自 Kimi Code CLI 官方 Skills 文档。Kimi Code 的 skill 发现是纯目录约定，无需在 config.toml 注册任何内容，因此安装/卸载全程不读写你的 Kimi 配置文件，冲突面仅限 unity-skills/ 这一个专属目录名。
• KIMI_CODE_HOME 环境变量支持 — 用户级安装根目录跟随该变量迁移；变量未设置或编辑器未继承到时回落 ~/.kimi-code。同时兼容被引号包裹而未被 shell 展开的前导 ~/ 写法。

Changed

• Kimi 流量的 agent 识别 — 审计日志新增 kimi → KimiCode 关键字映射。此前 Kimi Code 直接用内建 fetch 或 curl 打 REST 的流量（不经 Python helper 发 X-Agent-Id）会落到 Unknown(...)。一键安装写入的 agent_config.json 同样使用 KimiCode，两条识别路径口径统一。
• 安装位置选用 Kimi 专属目录而非共享 .agents/skills — Kimi Code CLI 也会扫描 Codex / Antigravity 共用的 .agents/skills。为使各工具的安装状态与卸载互不干扰，卡片只写 .kimi-code/；你已有的 Codex 全局安装（~/.agents/skills/）仍会被 Kimi Code 顺带发现，属额外收益而非冲突。
• 版本号更新 — SkillsLogger.Version / package.json / Python helper __version__ / agent.md / README 当前版本标记同步提升到 2.6.2。

Docs

• README / README_CN / SETUP_GUIDE 双语同步 — 原生支持的 IDE 数量由 5 提升到 6，工具支持表、一键安装步骤与手动安装路径表均补充 Kimi Code 条目（含 $KIMI_CODE_HOME 说明与 /skill:unity-skills 显式触发方式）。

Compatibility

• 无破坏性变化，无新增 skill，技能总数仍为 784。
• 未使用 Kimi Code 的用户升级后行为完全不变；已安装的其余 5 个工具不受影响，无需重新安装。

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