@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/animation/AnimationToolSupport.cs

@@ -0,0 +1,335 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// animation 域 IUnityCliTool 共享 helper:AnimationClip 资产加载/设置、
+    /// Animator 信息构造、AnimatorController 资产操作。仅供 animation 域自包含工具复用。
+    /// </summary>
+    public static class AnimationToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            SceneToolSupport.EnsureEditorNotBusy(command);
+        }
+
+        /// <summary>规范化并校验 Assets/*.anim 路径。</summary>
+        public static string RequireAnimationClipPath(string rawPath)
+        {
+            var path = SceneToolSupport.NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_PATH_REQUIRED", "Pass an Assets/*.anim path.", "Use tools run animation.clip --input '{\"path\":\"Assets/Animations/Example.anim\"}'.");
+            if (!path.StartsWith("Assets/", System.StringComparison.OrdinalIgnoreCase) || !path.EndsWith(".anim", System.StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_PATH_INVALID", "AnimationClip path must be under Assets/ and end with .anim: " + path, "Pass a Unity asset path such as Assets/Animations/Player.anim.");
+            return path;
+        }
+
+        public static WrapMode ValidateClipSettings(float? frameRate, string wrapMode, float? startTime, float? stopTime, float? length)
+        {
+            if (frameRate.HasValue && (float.IsNaN(frameRate.Value) || float.IsInfinity(frameRate.Value) || frameRate.Value <= 0f))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_VALUE_INVALID", "frameRate must be finite and greater than zero.", "Pass a positive finite frameRate.");
+            if (startTime.HasValue && (float.IsNaN(startTime.Value) || float.IsInfinity(startTime.Value)) || stopTime.HasValue && (float.IsNaN(stopTime.Value) || float.IsInfinity(stopTime.Value)) || length.HasValue && (float.IsNaN(length.Value) || float.IsInfinity(length.Value) || length.Value <= 0f))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_VALUE_INVALID", "Clip time values must be finite and length must be greater than zero.", "Pass finite startTime/stopTime and a positive finite length.");
+            if (stopTime.HasValue && length.HasValue)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_TIME_CONFLICT", "stopTime and length are mutually exclusive.", "Pass either stopTime or length.");
+            if (startTime.HasValue && stopTime.HasValue && stopTime.Value <= startTime.Value)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_TIME_INVALID", "stopTime must be greater than startTime.", "Pass startTime < stopTime.");
+            if (startTime.HasValue && length.HasValue && float.IsInfinity(startTime.Value + length.Value))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_TIME_INVALID", "startTime plus length must be representable as a finite float.", "Use smaller finite time values.");
+            if (string.IsNullOrEmpty(wrapMode)) return default(WrapMode);
+            WrapMode parsed;
+            if (!System.Enum.TryParse<WrapMode>(wrapMode, true, out parsed) || !System.Enum.IsDefined(typeof(WrapMode), parsed))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_WRAP_MODE_INVALID", "Unsupported WrapMode: " + wrapMode, "Pass a defined Unity WrapMode value.");
+            return parsed;
+        }
+
+        /// <summary>加载 AnimationClip 资产;不存在抛异常。</summary>
+        public static AnimationClip LoadAnimationClipAsset(string path)
+        {
+            var clip = AssetDatabase.LoadAssetAtPath<AnimationClip>(path);
+            if (clip == null)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_CLIP_NOT_FOUND", "AnimationClip asset not found: " + path, "Check the path or create one with animation.clip.create.");
+            return clip;
+        }
+
+        /// <summary>规范化并校验 Assets/*.controller 路径。</summary>
+        public static string RequireControllerPath(string rawPath)
+        {
+            var path = SceneToolSupport.NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path))
+                throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_PATH_REQUIRED", "Pass --controller-path <Assets/...>.controller>.", "Use controller.create to create one first.");
+            if (!path.StartsWith("Assets/", System.StringComparison.Ordinal) || !path.EndsWith(".controller", System.StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_PATH_INVALID", "AnimatorController path must be a canonical Assets/*.controller path: " + path, "Pass a Unity asset path such as Assets/Animations/Player.controller.");
+            // 在任何 AssetDatabase 查找或创建目录前证明物理路径仍受 Assets/ 包含。
+            SceneToolSupport.AssetFullPath(path);
+            return path;
+        }
+
+        /// <summary>加载 AnimatorController 资产。</summary>
+        public static AnimatorController LoadControllerAsset(string controllerPath)
+        {
+            var path = SceneToolSupport.NormalizeAssetPath(controllerPath);
+            if (string.IsNullOrEmpty(path)) return null;
+            return AssetDatabase.LoadAssetAtPath<AnimatorController>(path);
+        }
+
+        /// <summary>强制从 AssetDatabase 重新加载控制器，避免用 effect 前的缓存对象作为完成证明。</summary>
+        public static AnimatorController ReloadControllerAsset(string path)
+        {
+            AssetDatabase.SaveAssets();
+            AssetDatabase.Refresh();
+            return AssetDatabase.LoadAssetAtPath<AnimatorController>(path);
+        }
+
+        /// <summary>按 effect 前 GUID 重新定位控制器，拒绝 path 重绑定后的缓存读回。</summary>
+        public static AnimatorController ReloadControllerAsset(string path, string expectedGuid)
+        {
+            AssetDatabase.SaveAssets();
+            AssetDatabase.Refresh();
+            var observedPath = string.IsNullOrEmpty(expectedGuid) ? null : AssetDatabase.GUIDToAssetPath(expectedGuid);
+            if (string.IsNullOrEmpty(observedPath) || !string.Equals(observedPath, path, System.StringComparison.Ordinal)) return null;
+            return AssetDatabase.LoadAssetAtPath<AnimatorController>(observedPath);
+        }
+
+        /// <summary>捕获层的可持久化完整身份，用于数组编辑后的顺序与删除证明。</summary>
+        public static ControllerLayerIdentity CaptureLayerIdentity(AnimatorControllerLayer layer)
+        {
+            return new ControllerLayerIdentity
+            {
+                Name = layer.name,
+                DefaultWeight = layer.defaultWeight,
+                BlendingMode = layer.blendingMode,
+                IKPass = layer.iKPass,
+                SyncedLayerIndex = layer.syncedLayerIndex,
+                SyncedLayerAffectsTiming = layer.syncedLayerAffectsTiming,
+                AvatarMaskIdentity = AssetObjectIdentity(layer.avatarMask),
+                StateMachineIdentity = AssetObjectIdentity(layer.stateMachine)
+            };
+        }
+
+        /// <summary>比较层全部可公开持久化字段及其子资产 identity，不能只依赖数组索引或数量。</summary>
+        public static bool SameLayerIdentity(ControllerLayerIdentity actual, ControllerLayerIdentity expected)
+        {
+            return actual != null && expected != null
+                && actual.Name == expected.Name
+                && Mathf.Approximately(actual.DefaultWeight, expected.DefaultWeight)
+                && actual.BlendingMode == expected.BlendingMode
+                && actual.IKPass == expected.IKPass
+                && actual.SyncedLayerIndex == expected.SyncedLayerIndex
+                && actual.SyncedLayerAffectsTiming == expected.SyncedLayerAffectsTiming
+                && actual.AvatarMaskIdentity == expected.AvatarMaskIdentity
+                && actual.StateMachineIdentity == expected.StateMachineIdentity;
+        }
+
+        private static string AssetObjectIdentity(Object value)
+        {
+            if (value == null) return string.Empty;
+            string guid;
+            long localId;
+            if (AssetDatabase.TryGetGUIDAndLocalFileIdentifier(value, out guid, out localId))
+                return guid + ":" + localId.ToString(System.Globalization.CultureInfo.InvariantCulture);
+            return AssetDatabase.GetAssetPath(value) + ":" + value.name;
+        }
+
+        /// <summary>强制重新加载动画片段，用于持久化写入后的独立 readback。</summary>
+        public static AnimationClip ReloadAnimationClipAsset(string path)
+        {
+            AssetDatabase.SaveAssets();
+            AssetDatabase.Refresh();
+            return AssetDatabase.LoadAssetAtPath<AnimationClip>(path);
+        }
+
+        /// <summary>构造稳定的业务 readback mismatch，供 Coordinator 将 effect 后失败归类为 unknown。</summary>
+        public static UnityCliBridge.BridgeCommandException StateMismatch(string code, string subject)
+        {
+            return new UnityCliBridge.BridgeCommandException(code, subject + " did not match the requested value after independent readback.", "Inspect the target state and retry after the Editor is idle.");
+        }
+
+        /// <summary>读取 Animator 可用层数量;运行态缓存未初始化时回退到 AnimatorController 资产层。</summary>
+        public static int EffectiveAnimatorLayerCount(Animator animator)
+        {
+            if (animator == null) return 0;
+            if (animator.layerCount > 0) return animator.layerCount;
+            var controller = animator.runtimeAnimatorController as AnimatorController;
+            return controller == null || controller.layers == null ? 0 : controller.layers.Length;
+        }
+
+        /// <summary>读取 Animator 参数定义;运行态缓存为空时回退到 AnimatorController 资产。</summary>
+        public static AnimatorControllerParameter[] AnimatorParameterDefinitions(Animator animator)
+        {
+            if (animator == null) return new AnimatorControllerParameter[0];
+            if (animator.parameterCount > 0)
+            {
+                var arr = new AnimatorControllerParameter[animator.parameterCount];
+                for (var i = 0; i < animator.parameterCount; i++) arr[i] = animator.GetParameter(i);
+                return arr;
+            }
+            var controller = animator.runtimeAnimatorController as AnimatorController;
+            return controller == null || controller.parameters == null ? new AnimatorControllerParameter[0] : controller.parameters;
+        }
+
+        /// <summary>按名称查找 Animator 参数定义。</summary>
+        public static AnimatorControllerParameter FindAnimatorParameter(Animator animator, string parameterName)
+        {
+            foreach (var p in AnimatorParameterDefinitions(animator))
+                if (p != null && p.name == parameterName) return p;
+            return null;
+        }
+
+        /// <summary>按短名或 Base.Layer.State 路径查找 Controller 状态。</summary>
+        public static AnimatorState FindStateInLayer(AnimatorStateMachine sm, string stateName)
+        {
+            if (sm == null || sm.states == null) return null;
+            foreach (var cs in sm.states)
+            {
+                if (cs.state == null) continue;
+                if (cs.state.name == stateName) return cs.state;
+                if (!string.IsNullOrEmpty(stateName) && stateName.EndsWith("." + cs.state.name, System.StringComparison.Ordinal)) return cs.state;
+            }
+            return null;
+        }
+
+        /// <summary>构造 AnimationClip 信息 DTO。</summary>
+        public static AnimationClipInfo BuildAnimationClipInfo(string path, AnimationClip clip, int maxCurveKeys)
+        {
+            var keyLimit = Mathf.Clamp(maxCurveKeys, 0, 100);
+            var bindings = AnimationUtility.GetCurveBindings(clip);
+            var events = AnimationUtility.GetAnimationEvents(clip);
+            var settings = AnimationUtility.GetAnimationClipSettings(clip);
+            var bindingList = new List<AnimationBindingInfo>();
+            foreach (var binding in bindings)
+            {
+                var curve = AnimationUtility.GetEditorCurve(clip, binding);
+                var keys = curve == null ? new Keyframe[0] : curve.keys;
+                var keyList = new List<AnimationKeyInfo>();
+                for (var i = 0; i < Mathf.Min(keys.Length, keyLimit); i++)
+                {
+                    keyList.Add(new AnimationKeyInfo { Time = keys[i].time, Value = keys[i].value, InTangent = keys[i].inTangent, OutTangent = keys[i].outTangent });
+                }
+                bindingList.Add(new AnimationBindingInfo { Path = binding.path, Property = binding.propertyName, Type = binding.type == null ? null : binding.type.FullName, KeyCount = keys.Length, KeysTruncated = keys.Length > keyLimit, Keys = keyList });
+            }
+            var eventList = new List<AnimationEventInfo>();
+            foreach (var evt in events)
+            {
+                eventList.Add(new AnimationEventInfo { Time = evt.time, FunctionName = evt.functionName, StringParameter = evt.stringParameter, FloatParameter = evt.floatParameter, IntParameter = evt.intParameter });
+            }
+            return new AnimationClipInfo
+            {
+                Path = path, Guid = AssetDatabase.AssetPathToGUID(path), Name = clip.name, Length = clip.length,
+                FrameRate = clip.frameRate, Legacy = clip.legacy, WrapMode = clip.wrapMode.ToString(),
+                Settings = new AnimationClipSettingsInfo { StartTime = settings.startTime, StopTime = settings.stopTime, LoopTime = settings.loopTime, LoopBlend = settings.loopBlend },
+                Bindings = new AnimationBindingList { Count = bindings.Length, MaxCurveKeys = keyLimit, Items = bindingList },
+                Events = new AnimationEventList { Count = events.Length, Items = eventList }
+            };
+        }
+
+        /// <summary>构造 Animator 信息 DTO。</summary>
+        public static AnimatorInfo BuildAnimatorInfo(Animator animator, int layer)
+        {
+            var controller = animator.runtimeAnimatorController as AnimatorController;
+            var controllerPath = animator.runtimeAnimatorController == null ? null : SceneToolSupport.NormalizeAssetPath(AssetDatabase.GetAssetPath(animator.runtimeAnimatorController));
+            var controllerLayers = controller == null || controller.layers == null ? new AnimatorControllerLayer[0] : controller.layers;
+            var parameterDefinitions = AnimatorParameterDefinitions(animator);
+            var runtimeLayerCount = animator.layerCount;
+            var layerCount = runtimeLayerCount > 0 ? runtimeLayerCount : controllerLayers.Length;
+            var safeLayer = layerCount <= 0 ? 0 : Mathf.Clamp(layer, 0, layerCount - 1);
+            var state = runtimeLayerCount > 0 && safeLayer < runtimeLayerCount ? animator.GetCurrentAnimatorStateInfo(safeLayer) : default(AnimatorStateInfo);
+            var parameters = new List<AnimatorParameterInfo>();
+            foreach (var p in parameterDefinitions)
+            {
+                if (p == null) continue;
+                parameters.Add(new AnimatorParameterInfo { Name = p.name, Type = p.type.ToString(), DefaultFloat = p.defaultFloat, DefaultInt = p.defaultInt, DefaultBool = p.defaultBool });
+            }
+            var layers = new List<AnimatorLayerInfo>();
+            for (var i = 0; i < layerCount; i++)
+            {
+                var hasRuntime = i < runtimeLayerCount;
+                var hasController = i < controllerLayers.Length;
+                var stateInfo = hasRuntime ? animator.GetCurrentAnimatorStateInfo(i) : default(AnimatorStateInfo);
+                layers.Add(new AnimatorLayerInfo { Index = i, Name = hasController ? controllerLayers[i].name : null, Weight = hasRuntime ? animator.GetLayerWeight(i) : hasController ? controllerLayers[i].defaultWeight : 0f, CurrentStateHash = stateInfo.fullPathHash, CurrentStateNormalizedTime = stateInfo.normalizedTime, CurrentStateLength = stateInfo.length, IsInTransition = hasRuntime && animator.IsInTransition(i) });
+            }
+            var clips = new List<AnimatorClipInfo>();
+            if (animator.runtimeAnimatorController != null)
+            {
+                var animationClips = animator.runtimeAnimatorController.animationClips;
+                if (animationClips != null)
+                    foreach (var clip in animationClips)
+                        if (clip != null)
+                            clips.Add(new AnimatorClipInfo { Name = clip.name, Length = clip.length, FrameRate = clip.frameRate, IsLooping = clip.isLooping });
+            }
+            return new AnimatorInfo
+            {
+                Enabled = animator.enabled, Speed = animator.speed, ApplyRootMotion = animator.applyRootMotion,
+                UpdateMode = animator.updateMode.ToString(), CullingMode = animator.cullingMode.ToString(),
+                LayerCount = layerCount, ParameterCount = parameterDefinitions.Length,
+                SelectedLayer = safeLayer,
+                RuntimeAnimatorController = new ControllerRef { Name = animator.runtimeAnimatorController == null ? null : animator.runtimeAnimatorController.name, Path = controllerPath, Guid = string.IsNullOrEmpty(controllerPath) ? null : AssetDatabase.AssetPathToGUID(controllerPath) },
+                CurrentState = new AnimatorStateRef { FullPathHash = state.fullPathHash, ShortNameHash = state.shortNameHash, NormalizedTime = state.normalizedTime, Length = state.length },
+                Parameters = parameters, Layers = layers, Clips = clips
+            };
+        }
+    }
+
+    // ── animation 域 DTO ──
+
+    public sealed class AnimationClipInfo
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Name { get; set; }
+        public double Length { get; set; }
+        public double FrameRate { get; set; }
+        public bool Legacy { get; set; }
+        public string WrapMode { get; set; }
+        public AnimationClipSettingsInfo Settings { get; set; }
+        public AnimationBindingList Bindings { get; set; }
+        public AnimationEventList Events { get; set; }
+    }
+
+    public sealed class AnimationClipSettingsInfo
+    {
+        public double StartTime { get; set; }
+        public double StopTime { get; set; }
+        public bool LoopTime { get; set; }
+        public bool LoopBlend { get; set; }
+    }
+
+    public sealed class AnimationBindingList { public long Count { get; set; } public long MaxCurveKeys { get; set; } public List<AnimationBindingInfo> Items { get; set; } }
+    public sealed class AnimationBindingInfo { public string Path { get; set; } public string Property { get; set; } public string Type { get; set; } public long KeyCount { get; set; } public bool KeysTruncated { get; set; } public List<AnimationKeyInfo> Keys { get; set; } }
+    public sealed class AnimationKeyInfo { public double Time { get; set; } public double Value { get; set; } public double InTangent { get; set; } public double OutTangent { get; set; } }
+    public sealed class AnimationEventList { public long Count { get; set; } public List<AnimationEventInfo> Items { get; set; } }
+    public sealed class AnimationEventInfo { public double Time { get; set; } public string FunctionName { get; set; } public string StringParameter { get; set; } public double FloatParameter { get; set; } public long IntParameter { get; set; } }
+
+    public sealed class AnimatorInfo
+    {
+        public bool Enabled { get; set; }
+        public double Speed { get; set; }
+        public bool ApplyRootMotion { get; set; }
+        public string UpdateMode { get; set; }
+        public string CullingMode { get; set; }
+        public long LayerCount { get; set; }
+        public long ParameterCount { get; set; }
+        public long SelectedLayer { get; set; }
+        public ControllerRef RuntimeAnimatorController { get; set; }
+        public AnimatorStateRef CurrentState { get; set; }
+        public List<AnimatorParameterInfo> Parameters { get; set; }
+        public List<AnimatorLayerInfo> Layers { get; set; }
+        public List<AnimatorClipInfo> Clips { get; set; }
+    }
+
+    public sealed class ControllerRef { public string Name { get; set; } public string Path { get; set; } public string Guid { get; set; } }
+    public sealed class ControllerLayerIdentity { public string Name { get; set; } public float DefaultWeight { get; set; } public AnimatorLayerBlendingMode BlendingMode { get; set; } public bool IKPass { get; set; } public int SyncedLayerIndex { get; set; } public bool SyncedLayerAffectsTiming { get; set; } public string AvatarMaskIdentity { get; set; } public string StateMachineIdentity { get; set; } }
+    public sealed class AnimatorStateRef { public long FullPathHash { get; set; } public long ShortNameHash { get; set; } public double NormalizedTime { get; set; } public double Length { get; set; } }
+    public sealed class AnimatorParameterInfo { public string Name { get; set; } public string Type { get; set; } public double DefaultFloat { get; set; } public long DefaultInt { get; set; } public bool DefaultBool { get; set; } }
+    public sealed class AnimatorLayerInfo { public long Index { get; set; } public string Name { get; set; } public double Weight { get; set; } public long CurrentStateHash { get; set; } public double CurrentStateNormalizedTime { get; set; } public double CurrentStateLength { get; set; } public bool IsInTransition { get; set; } }
+    public sealed class AnimatorClipInfo { public string Name { get; set; } public double Length { get; set; } public double FrameRate { get; set; } public bool IsLooping { get; set; } }
+
+    public sealed class AnimationPlannedEffect { public string Type { get; set; } public string Target { get; set; } public string State { get; set; } public string Path { get; set; } public string Parameter { get; set; } public string Property { get; set; } public string Value { get; set; } }
+    public sealed class ControllerInfo { public string Path { get; set; } public string Guid { get; set; } public string Name { get; set; } public long LayerCount { get; set; } public long ParameterCount { get; set; } }
+}
+#endif

package/unitypkg/Editor/Tools/animation/AnimatorRuntimeToolSupport.cs

@@ -0,0 +1,24 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    public sealed class AnimatorParameterWithValue
+    {
+        public string Name { get; set; }
+        public string Type { get; set; }
+        [UnityCliAnyJson] public object Value { get; set; }
+    }
+
+    public sealed class AnimatorParameterRef
+    {
+        public string Name { get; set; }
+        public string Type { get; set; }
+    }
+
+    public sealed class CrossfadeInfo
+    {
+        public string State { get; set; }
+        public double Duration { get; set; }
+        public long Layer { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/animator/crossfade.cs

@@ -0,0 +1,117 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>对 Animator 执行一次 cross-fade，并通过同层状态读回证明目标已进入过渡或当前状态。</summary>
+    public class AnimatorCrossfadeTool : IUnityCliTool<AnimatorCrossfadeTool.Request, AnimatorCrossfadeTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string State { get; set; } public float? Duration { get; set; } public int? Layer { get; set; } }
+        public sealed class Readback { public int CurrentStateHash { get; set; } public int NextStateHash { get; set; } public bool InTransition { get; set; } public float NormalizedTime { get; set; } }
+        public sealed class Result { public CrossfadeInfo Transition { get; set; } public bool Changed { get; set; } public string NoOpReason { get; set; } public Readback State { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "animator.crossfade",
+            Summary = "Cross-fade an Animator to a named state with fresh state readback.",
+            Description = "Cross-fade a resolved Animator to a named state. The tool validates the controller, layer and state before one effect, then reads current and next state from the same Animator layer before returning.",
+            Group = "animation",DestructiveHint = false,
+            SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Crossfade to Run", Input = new Request { Target = "Player", State = "Run", Duration = 0.3f } } }
+        };
+
+        /// <summary>解析真实 state hash 后执行一次 CrossFade，并跨帧证明同一 Animator 已进入目标 state。</summary>
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "Animator crossfade requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            var controller = animator.runtimeAnimatorController as AnimatorController;
+            var controllerLayers = controller == null || controller.layers == null ? new AnimatorControllerLayer[0] : controller.layers;
+            var effectiveLayerCount = animator.layerCount > 0 ? animator.layerCount : controllerLayers.Length;
+            if (controller == null || effectiveLayerCount <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_NO_CONTROLLER", "Animator has no observable AnimatorController: " + GameObjectToolSupport.HierarchyPath(go), "Assign an AnimatorController with at least one layer.");
+            if (string.IsNullOrEmpty(request.State))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_STATE_REQUIRED", "Animator crossfade requires --state <name>.", "Pass an Animator state name.");
+            var duration = request.Duration ?? 0.25f;
+            var targetLayer = request.Layer ?? 0;
+            if (duration < 0f || float.IsNaN(duration) || float.IsInfinity(duration))
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_DURATION_INVALID", "Crossfade duration must be a finite non-negative value.", "Pass duration >= 0.");
+            if (targetLayer < 0 || targetLayer >= effectiveLayerCount || targetLayer >= controllerLayers.Length)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_LAYER_INVALID", "Crossfade layer is outside the Animator layer range.", "Pass a valid zero-based layer index.");
+            var state = AnimationToolSupport.FindStateInLayer(controllerLayers[targetLayer].stateMachine, request.State);
+            if (state == null)
+                throw new UnityCliBridge.BridgeCommandException("E_ANIMATION_STATE_UNOBSERVABLE", "Animator state cannot be resolved in the requested layer: " + request.State, "Pass a state name from the selected AnimatorController layer.");
+
+            var expectedHash = Animator.StringToHash(controllerLayers[targetLayer].name + "." + state.name);
+            var instanceId = go.GetInstanceID();
+            var globalId = GlobalObjectId.GetGlobalObjectIdSlow(go).ToString();
+            var sceneHandle = go.scene.handle;
+            var before = Observe(animator, targetLayer, expectedHash);
+            if (before != null)
+                return BuildResult(go, request.State, duration, targetLayer, false, "target-state-already-current-or-next", before, null);
+
+            ctx.CommitEffect();
+            try
+            {
+                if (animator.layerCount <= targetLayer) { animator.Rebind(); animator.Update(0f); }
+                animator.CrossFade(request.State, duration, targetLayer);
+                animator.Update(0f);
+            }
+            catch (System.Exception exception)
+            {
+                throw Unknown("invoke", exception.Message);
+            }
+
+            var reached = await ctx.Wait.UntilStable(() => Observe(animator, targetLayer, expectedHash) != null,
+                System.TimeSpan.FromMilliseconds(ctx.TimeoutMs), minimumFrames: 2, ct: ct);
+            if (!reached) throw Unknown("postcondition", "Animator did not reach a stable target-state readback before the deadline.");
+
+            var freshGo = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+            if (freshGo == null || freshGo.scene.handle != sceneHandle
+                || !string.Equals(GlobalObjectId.GetGlobalObjectIdSlow(freshGo).ToString(), globalId, StringComparison.Ordinal))
+                throw Unknown("readback", "Animator target identity changed after CrossFade.");
+            var freshAnimator = freshGo.GetComponent<Animator>();
+            var readback = Observe(freshAnimator, targetLayer, expectedHash);
+            if (readback == null) throw Unknown("postcondition", "Fresh Animator state no longer satisfies the requested transition.");
+            return BuildResult(freshGo, request.State, duration, targetLayer, true, null, readback,
+                new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animator.crossfade", Target = GameObjectToolSupport.HierarchyPath(freshGo), State = request.State } });
+        }
+
+        /// <summary>目标可位于 current 或 transition next；normalized time 必须是 fresh 有限值。</summary>
+        private static Readback Observe(Animator animator, int layer, int expectedHash)
+        {
+            if (animator == null || layer < 0 || layer >= animator.layerCount) return null;
+            var current = animator.GetCurrentAnimatorStateInfo(layer);
+            var next = animator.GetNextAnimatorStateInfo(layer);
+            var inTransition = animator.IsInTransition(layer);
+            var currentMatches = current.fullPathHash == expectedHash;
+            var nextMatches = inTransition && next.fullPathHash == expectedHash;
+            if (!currentMatches && !nextMatches) return null;
+            var normalizedTime = nextMatches ? next.normalizedTime : current.normalizedTime;
+            if (float.IsNaN(normalizedTime) || float.IsInfinity(normalizedTime) || normalizedTime < 0f) return null;
+            return new Readback { CurrentStateHash = current.fullPathHash, NextStateHash = next.fullPathHash, InTransition = inTransition, NormalizedTime = normalizedTime };
+        }
+
+        private static Result BuildResult(GameObject go, string state, float duration, int layer, bool changed, string noOpReason, Readback readback, List<AnimationPlannedEffect> effects)
+        {
+            return new Result {
+                Transition = new CrossfadeInfo { State = state, Duration = duration, Layer = layer }, Changed = changed,
+                NoOpReason = noOpReason, State = readback, PlannedEffects = effects
+            };
+        }
+
+        private static UnityCliBridge.BridgeCommandException Unknown(string stage, string cause)
+        {
+            return new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "Animator.CrossFade result cannot be confirmed; inspect the business state before deciding whether to retry.",
+                new Dictionary<string, object> { { "stage", stage }, { "cause", cause } }, new[] { "Inspect the Animator state before submitting a new request." });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/animator/get-info.cs

@@ -0,0 +1,24 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animator.get-info — 读取 Animator 详细信息(层/参数/剪辑)。</summary>
+    public class AnimatorGetInfoTool : IUnityCliTool<AnimatorGetInfoTool.Request, AnimatorGetInfoTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } }
+        public sealed class Result { public AnimatorInfo Animator { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animator.get-info", Summary = "Read Animator details: layers, parameters, clips, and runtime controller.", Description = "Resolve a target with an Animator and return enabled, speed, layerCount, parameters, layers, and clips.", Group = "animation",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read animator info", Input = new Request { Target = "Player" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animator info requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Animator = AnimationToolSupport.BuildAnimatorInfo(animator, 0) });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/animator/get-parameter.cs

@@ -0,0 +1,36 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animator.get-parameter — 读取单个 Animator 参数的当前值。</summary>
+    public class AnimatorGetParameterTool : IUnityCliTool<AnimatorGetParameterTool.Request, AnimatorGetParameterTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string ParameterName { get; set; } }
+        public sealed class Result { public AnimatorParameterWithValue Parameter { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animator.get-parameter", Summary = "Read a single Animator parameter's current or default value.", Description = "Resolve a target with an Animator and read a named parameter. Returns runtime value if available, otherwise the controller default.", Group = "animation",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read Speed parameter", Input = new Request { Target = "Player", ParameterName = "Speed" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animator get-parameter requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            if (string.IsNullOrEmpty(r.ParameterName)) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_PARAMETER_NAME_REQUIRED", "Animator get-parameter requires --parameter-name <name>.", "Pass the name of an Animator parameter.");
+            var param = AnimationToolSupport.FindAnimatorParameter(animator, r.ParameterName);
+            if (param == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_PARAMETER_NOT_FOUND", "Parameter '" + r.ParameterName + "' not found on Animator: " + GameObjectToolSupport.HierarchyPath(go), "Run animator.get-info to list available parameters.");
+            object value = null;
+            var hasRuntime = animator.parameterCount > 0;
+            switch (param.type)
+            {
+                case AnimatorControllerParameterType.Float: value = hasRuntime ? animator.GetFloat(r.ParameterName) : (object)param.defaultFloat; break;
+                case AnimatorControllerParameterType.Int: value = hasRuntime ? (long)animator.GetInteger(r.ParameterName) : (long)param.defaultInt; break;
+                case AnimatorControllerParameterType.Bool:
+                case AnimatorControllerParameterType.Trigger: value = hasRuntime ? animator.GetBool(r.ParameterName) : param.defaultBool; break;
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Parameter = new AnimatorParameterWithValue { Name = param.name, Type = param.type.ToString(), Value = value } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/animation/animator/set-enabled.cs

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>animator.set-enabled — 启用/禁用 Animator 组件。</summary>
+    public class AnimatorSetEnabledTool : IUnityCliTool<AnimatorSetEnabledTool.Request, AnimatorSetEnabledTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public bool? Value { get; set; } }
+        public sealed class Result { public bool Enabled { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "animator.set-enabled", Summary = "Enable or disable an Animator component on a target GameObject.", Description = "Resolve a target with an Animator and set animator.enabled. Defaults to true.", Group = "animation",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Disable animator", Input = new Request { Target = "Player", Value = false } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "Animator set-enabled requires --target <go>.");
+            var animator = go.GetComponent<Animator>();
+            if (animator == null) throw new UnityCliBridge.BridgeCommandException("E_ANIMATOR_NOT_FOUND", "Animator component not found on target: " + GameObjectToolSupport.HierarchyPath(go), "Add an Animator component or choose another target.");
+            var enabled = r.Value ?? true;
+            ctx.CommitEffect();
+            UnityCliSceneMutation.RecordObject(animator, "Set Animator Enabled");
+            animator.enabled = enabled;
+            UnityCliSceneMutation.MarkSceneObjectDirty(animator);
+            var observedTarget = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedAnimator = observedTarget == null ? null : observedTarget.GetComponent<Animator>();
+            var observedEnabled = observedAnimator != null && observedAnimator.enabled;
+            if (observedAnimator == null || observedEnabled != enabled) throw AnimationToolSupport.StateMismatch("E_ANIMATOR_ENABLED_STATE_MISMATCH", "Animator enabled state");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Enabled = observedEnabled, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "animator.set-enabled", Target = GameObjectToolSupport.HierarchyPath(go), Value = observedEnabled.ToString().ToLowerInvariant() } } });
+        }
+    }
+}
+#endif