@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/controller/add-parameter.cs

@@ -0,0 +1,51 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.add-parameter — 添加参数到 Controller。</summary>
+    public class ControllerAddParameterTool : IUnityCliTool<ControllerAddParameterTool.Request, ControllerAddParameterTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string ParameterName { get; set; } public string ParameterType { get; set; } public string DefaultValue { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string ParameterName { get; set; } public string ParameterType { get; set; } public long TotalParameters { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.add-parameter", Summary = "Add a parameter to an AnimatorController asset.", Description = "Add a float/int/bool/trigger parameter. Optionally set a default value.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add MatrixSpeed parameter", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", ParameterName = "MatrixSpeed", ParameterType = "float" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            if (string.IsNullOrEmpty(r.ParameterName)) throw new UnityCliBridge.BridgeCommandException("E_PARAMETER_NAME_REQUIRED", "controller.add-parameter requires parameterName.", "Pass a name for the new parameter.");
+            foreach (var existing in controller.parameters) if (existing.name == r.ParameterName) throw new UnityCliBridge.BridgeCommandException("E_PARAMETER_EXISTS", "Parameter '" + r.ParameterName + "' already exists.", "Use animator.set-parameter to change its default value.");
+            var typeStr = (r.ParameterType ?? "float").ToLowerInvariant();
+            var paramType = typeStr == "int" || typeStr == "integer" ? AnimatorControllerParameterType.Int : typeStr == "bool" || typeStr == "boolean" ? AnimatorControllerParameterType.Bool : typeStr == "trigger" ? AnimatorControllerParameterType.Trigger : AnimatorControllerParameterType.Float;
+            var expectedFloat = 0f;
+            var expectedInt = 0;
+            var expectedBool = false;
+            if (r.DefaultValue != null && paramType == AnimatorControllerParameterType.Float)
+            {
+                if (!float.TryParse(r.DefaultValue, NumberStyles.Float, CultureInfo.InvariantCulture, out expectedFloat) || float.IsNaN(expectedFloat) || float.IsInfinity(expectedFloat))
+                    throw new UnityCliBridge.BridgeCommandException("E_PARAMETER_DEFAULT_INVALID", "Float parameter defaultValue must be finite.", "Pass a finite floating-point defaultValue.");
+            }
+            if (r.DefaultValue != null && paramType == AnimatorControllerParameterType.Int && !int.TryParse(r.DefaultValue, NumberStyles.Integer, CultureInfo.InvariantCulture, out expectedInt))
+                throw new UnityCliBridge.BridgeCommandException("E_PARAMETER_DEFAULT_INVALID", "Int parameter defaultValue must be an integer.", "Pass an integer defaultValue.");
+            if (r.DefaultValue != null && paramType == AnimatorControllerParameterType.Bool)
+                expectedBool = string.Equals(r.DefaultValue, "true", System.StringComparison.OrdinalIgnoreCase) || r.DefaultValue == "1";
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Add Animator Parameter");
+            controller.AddParameter(r.ParameterName, paramType);
+            if (r.DefaultValue != null) { var allParams = controller.parameters; var added = allParams[allParams.Length - 1]; if (paramType == AnimatorControllerParameterType.Float) added.defaultFloat = expectedFloat; else if (paramType == AnimatorControllerParameterType.Int) added.defaultInt = expectedInt; else if (paramType == AnimatorControllerParameterType.Bool) added.defaultBool = expectedBool; controller.parameters = allParams; }
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            AnimatorControllerParameter observedParameter = null;
+            if (observedController != null) foreach (var candidate in observedController.parameters) if (candidate.name == r.ParameterName) { observedParameter = candidate; break; }
+            if (observedParameter == null || observedParameter.type != paramType || (paramType == AnimatorControllerParameterType.Float && r.DefaultValue != null && !Mathf.Approximately(observedParameter.defaultFloat, expectedFloat)) || (paramType == AnimatorControllerParameterType.Int && r.DefaultValue != null && observedParameter.defaultInt != expectedInt) || (paramType == AnimatorControllerParameterType.Bool && r.DefaultValue != null && observedParameter.defaultBool != expectedBool))
+                throw AnimationToolSupport.StateMismatch("E_CONTROLLER_ADD_PARAMETER_STATE_MISMATCH", "AnimatorController parameter");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, ParameterName = observedParameter.name, ParameterType = observedParameter.type.ToString(), TotalParameters = observedController.parameters.Length, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.add-parameter", Path = path, Parameter = observedParameter.name } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/add-state.cs

@@ -0,0 +1,44 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.add-state — 在指定层添加状态。</summary>
+    public class ControllerAddStateTool : IUnityCliTool<ControllerAddStateTool.Request, ControllerAddStateTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string StateName { get; set; } public string ClipPath { get; set; } public int? LayerIndex { get; set; } public float? Speed { get; set; } public bool? IsDefault { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string StateName { get; set; } public bool HasMotion { get; set; } public string MotionName { get; set; } public double Speed { get; set; } public bool IsDefault { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.add-state", Summary = "Add a new state to an AnimatorController layer.", Description = "Add a state to the specified layer. Optionally assign a motion clip and set as default state.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add MatrixWalk state", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", StateName = "MatrixWalk" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            if (string.IsNullOrEmpty(r.StateName)) throw new UnityCliBridge.BridgeCommandException("E_STATE_NAME_REQUIRED", "controller.add-state requires stateName.", "Pass a name for the new state.");
+            var layerIndex = r.LayerIndex ?? 0;
+            if (layerIndex < 0 || layerIndex >= controller.layers.Length) throw new UnityCliBridge.BridgeCommandException("E_LAYER_INDEX_INVALID", "Layer index out of range.", "Run controller.get-info to inspect available layers.");
+            var sm = controller.layers[layerIndex].stateMachine;
+            if (AnimationToolSupport.FindStateInLayer(sm, r.StateName) != null) throw new UnityCliBridge.BridgeCommandException("E_STATE_EXISTS", "State '" + r.StateName + "' already exists in layer " + layerIndex + ".", "Choose a different state name.");
+            AnimationClip clip = null;
+            if (!string.IsNullOrEmpty(r.ClipPath)) { clip = AssetDatabase.LoadAssetAtPath<AnimationClip>(SceneToolSupport.NormalizeAssetPath(r.ClipPath)); if (clip == null) throw new UnityCliBridge.BridgeCommandException("E_CLIP_NOT_FOUND", "AnimationClip not found at: " + r.ClipPath, "Create the clip first or omit clipPath."); }
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Add Animator State");
+            var state = sm.AddState(r.StateName);
+            if (clip != null) state.motion = clip;
+            state.speed = r.Speed ?? 1f;
+            var isDefault = r.IsDefault ?? false;
+            if (isDefault) sm.defaultState = state;
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            var observedState = observedController == null || layerIndex >= observedController.layers.Length ? null : AnimationToolSupport.FindStateInLayer(observedController.layers[layerIndex].stateMachine, r.StateName);
+            if (observedState == null || !Mathf.Approximately(observedState.speed, r.Speed ?? 1f) || (clip != null && observedState.motion != clip) || (isDefault && observedController.layers[layerIndex].stateMachine.defaultState != observedState))
+                throw AnimationToolSupport.StateMismatch("E_CONTROLLER_ADD_STATE_STATE_MISMATCH", "AnimatorController state");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, StateName = observedState.name, HasMotion = observedState.motion != null, MotionName = observedState.motion?.name, Speed = observedState.speed, IsDefault = observedController.layers[layerIndex].stateMachine.defaultState == observedState, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.add-state", Path = path, State = observedState.name } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/add-transition.cs

@@ -0,0 +1,71 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.add-transition — 在状态间添加转换。</summary>
+    public class ControllerAddTransitionTool : IUnityCliTool<ControllerAddTransitionTool.Request, ControllerAddTransitionTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string FromState { get; set; } public string ToState { get; set; } public int? LayerIndex { get; set; } public bool? HasExitTime { get; set; } public float? Duration { get; set; } public float? ExitTime { get; set; } public string Conditions { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string ToState { get; set; } public bool HasExitTime { get; set; } public double Duration { get; set; } public long ConditionCount { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.add-transition", Summary = "Add a transition between two states in an AnimatorController layer.", Description = "Add a transition from fromState to toState. Supports AnyState as source. conditions is a JSON array of {parameter, mode, threshold}.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add transition", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", FromState = "Idle", ToState = "Walk" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            if (string.IsNullOrEmpty(r.FromState) || string.IsNullOrEmpty(r.ToState)) throw new UnityCliBridge.BridgeCommandException("E_STATE_NAME_REQUIRED", "controller.add-transition requires fromState and toState.", "Pass source and destination state names.");
+            var layerIndex = r.LayerIndex ?? 0;
+            if (layerIndex < 0 || layerIndex >= controller.layers.Length) throw new UnityCliBridge.BridgeCommandException("E_LAYER_INDEX_INVALID", "Layer index out of range.", "Run controller.get-info to inspect available layers.");
+            var sm = controller.layers[layerIndex].stateMachine;
+            var isAnyState = string.Equals(r.FromState, "AnyState", System.StringComparison.OrdinalIgnoreCase) || string.Equals(r.FromState, "Any", System.StringComparison.OrdinalIgnoreCase);
+            var toState = AnimationToolSupport.FindStateInLayer(sm, r.ToState);
+            if (toState == null) throw new UnityCliBridge.BridgeCommandException("E_STATE_NOT_FOUND", "Destination state '" + r.ToState + "' not found in layer " + layerIndex + ".", "Run controller.get-info to inspect available states.");
+            var fromState = isAnyState ? null : AnimationToolSupport.FindStateInLayer(sm, r.FromState);
+            if (!isAnyState && fromState == null) throw new UnityCliBridge.BridgeCommandException("E_STATE_NOT_FOUND", "Source state '" + r.FromState + "' not found in layer " + layerIndex + ".", "Run controller.get-info to inspect available states.");
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Add Animator Transition");
+            AnimatorStateTransition transition;
+            var fromStateName = r.FromState;
+            if (isAnyState) { transition = sm.AddAnyStateTransition(toState); fromStateName = "AnyState"; }
+            else transition = fromState.AddTransition(toState);
+            transition.hasExitTime = r.HasExitTime ?? true;
+            transition.duration = r.Duration ?? 0.25f;
+            transition.exitTime = r.ExitTime ?? 0.75f;
+            var conditionCount = 0;
+            if (!string.IsNullOrEmpty(r.Conditions))
+            {
+                foreach (var condStr in ExtractArrayItems(r.Conditions))
+                {
+                    var pName = ExtractJsonField(condStr, "parameter");
+                    var modeStr = ExtractJsonField(condStr, "mode") ?? "greater";
+                    var threshold = ExtractJsonFloat(condStr, "threshold", 0f);
+                    if (string.IsNullOrEmpty(pName)) continue;
+                    AnimatorConditionMode mode;
+                    switch (modeStr.ToLowerInvariant()) { case "less": mode = AnimatorConditionMode.Less; break; case "equals": mode = AnimatorConditionMode.Equals; break; case "notequal": case "not_equal": mode = AnimatorConditionMode.NotEqual; break; case "if": case "true": mode = AnimatorConditionMode.If; break; case "ifnot": case "if_not": case "false": mode = AnimatorConditionMode.IfNot; break; default: mode = AnimatorConditionMode.Greater; break; }
+                    transition.AddCondition(mode, threshold, pName); conditionCount++;
+                }
+            }
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            var observedMachine = observedController == null ? null : observedController.layers[layerIndex].stateMachine;
+            var observedDestination = observedMachine == null ? null : AnimationToolSupport.FindStateInLayer(observedMachine, r.ToState);
+            AnimatorStateTransition observedTransition = null;
+            if (observedMachine != null && observedDestination != null)
+            {
+                var transitions = isAnyState ? observedMachine.anyStateTransitions : AnimationToolSupport.FindStateInLayer(observedMachine, r.FromState).transitions;
+                foreach (var candidate in transitions) if (candidate.destinationState == observedDestination && candidate.hasExitTime == (r.HasExitTime ?? true) && Mathf.Approximately(candidate.duration, r.Duration ?? 0.25f) && candidate.conditions.Length == conditionCount) { observedTransition = candidate; break; }
+            }
+            if (observedTransition == null) throw AnimationToolSupport.StateMismatch("E_CONTROLLER_TRANSITION_STATE_MISMATCH", "AnimatorController transition");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, ToState = observedDestination.name, HasExitTime = observedTransition.hasExitTime, Duration = observedTransition.duration, ConditionCount = observedTransition.conditions.Length, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.add-transition", Path = path, State = fromStateName + "->" + observedDestination.name } } });
+        }
+        internal static string[] ExtractArrayItems(string json) { var items = new List<string>(); var depth = 0; var start = -1; for (var i = 0; i < json.Length; i++) { if (json[i] == '{') { if (depth == 0) start = i; depth++; } else if (json[i] == '}') { depth--; if (depth == 0 && start >= 0) { items.Add(json.Substring(start, i - start + 1)); start = -1; } } } return items.ToArray(); }
+        internal static string ExtractJsonField(string json, string field) { var key = "\"" + field + "\""; var idx = json.IndexOf(key, System.StringComparison.OrdinalIgnoreCase); if (idx < 0) return null; idx = json.IndexOf(':', idx + key.Length); if (idx < 0) return null; idx++; while (idx < json.Length && char.IsWhiteSpace(json[idx])) idx++; if (idx >= json.Length) return null; if (json[idx] == '"') { var end = json.IndexOf('"', idx + 1); return end > idx ? json.Substring(idx + 1, end - idx - 1) : null; } var endIdx = idx; while (endIdx < json.Length && json[endIdx] != ',' && json[endIdx] != '}' && !char.IsWhiteSpace(json[endIdx])) endIdx++; return json.Substring(idx, endIdx - idx); }
+        internal static float ExtractJsonFloat(string json, string field, float fallback) { var val = ExtractJsonField(json, field); float f; return float.TryParse(val, NumberStyles.Float, CultureInfo.InvariantCulture, out f) ? f : fallback; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/assign.cs

@@ -0,0 +1,38 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.assign — 将 Controller 分配到目标 Animator。</summary>
+    public class ControllerAssignTool : IUnityCliTool<ControllerAssignTool.Request, ControllerAssignTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string Target { get; set; } }
+        public sealed class Result { public string ControllerName { get; set; } public string ControllerPath { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.assign", Summary = "Assign an AnimatorController asset to a target GameObject's Animator.", Description = "Resolve a target GameObject, add an Animator if missing, and assign the controller asset.", Group = "controller",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Assign controller", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", Target = "Player" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            var go = GameObjectToolSupport.ResolveUniqueTarget(r.Target, "controller.assign requires target.");
+            var animator = go.GetComponent<Animator>();
+            ctx.CommitEffect();
+            if (animator == null) animator = UnityCliSceneMutation.AddComponent<Animator>(go);
+            UnityCliSceneMutation.RecordObject(animator, "Assign AnimatorController");
+            animator.runtimeAnimatorController = controller;
+            UnityCliSceneMutation.MarkSceneObjectDirty(animator);
+            UnityCliSceneMutation.MarkSceneDirty(go.scene);
+            var observedTarget = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedAnimator = observedTarget == null ? null : observedTarget.GetComponent<Animator>();
+            var observedController = observedAnimator == null ? null : observedAnimator.runtimeAnimatorController;
+            var observedPath = observedController == null ? null : AssetDatabase.GetAssetPath(observedController);
+            if (observedController != controller || observedPath != path) throw AnimationToolSupport.StateMismatch("E_CONTROLLER_ASSIGN_STATE_MISMATCH", "Animator controller assignment");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { ControllerName = observedController.name, ControllerPath = observedPath, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.assign", Path = observedPath, Target = GameObjectToolSupport.HierarchyPath(go) } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/create-blend-tree-1d.cs

@@ -0,0 +1,40 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.create-blend-tree-1d — 创建 1D BlendTree 状态。</summary>
+    public class ControllerCreateBlendTree1DTool : IUnityCliTool<ControllerCreateBlendTree1DTool.Request, ControllerCreateBlendTree1DTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string StateName { get; set; } public string BlendParameter { get; set; } public int? LayerIndex { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string StateName { get; set; } public string BlendParameter { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.create-blend-tree-1d", Summary = "Create a 1D BlendTree state in an AnimatorController layer.", Description = "Add a new state with a 1D BlendTree motion using the specified blend parameter.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create 1D blend tree", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", StateName = "MatrixMove", BlendParameter = "Speed" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            if (string.IsNullOrEmpty(r.StateName)) throw new UnityCliBridge.BridgeCommandException("E_STATE_NAME_REQUIRED", "controller.create-blend-tree-1d requires stateName.", "Pass a name for the blend tree state.");
+            var layerIndex = r.LayerIndex ?? 0;
+            if (layerIndex < 0 || layerIndex >= controller.layers.Length) throw new UnityCliBridge.BridgeCommandException("E_LAYER_INDEX_INVALID", "Layer index out of range.", "Run controller.get-info to inspect layers.");
+            var sm = controller.layers[layerIndex].stateMachine;
+            if (AnimationToolSupport.FindStateInLayer(sm, r.StateName) != null) throw new UnityCliBridge.BridgeCommandException("E_STATE_EXISTS", "State '" + r.StateName + "' already exists.", "Choose a different state name.");
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Create BlendTree 1D");
+            var blendTree = new BlendTree { name = r.StateName, blendType = BlendTreeType.Simple1D, blendParameter = r.BlendParameter ?? "" };
+            AssetDatabase.AddObjectToAsset(blendTree, controller);
+            var state = sm.AddState(r.StateName); state.motion = blendTree;
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            var observedState = observedController == null ? null : AnimationToolSupport.FindStateInLayer(observedController.layers[layerIndex].stateMachine, r.StateName);
+            var observedTree = observedState == null ? null : observedState.motion as BlendTree;
+            if (observedTree == null || observedTree.blendType != BlendTreeType.Simple1D || observedTree.blendParameter != (r.BlendParameter ?? "")) throw AnimationToolSupport.StateMismatch("E_CONTROLLER_BLEND_TREE_1D_STATE_MISMATCH", "1D BlendTree");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, StateName = observedState.name, BlendParameter = observedTree.blendParameter, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.create-blend-tree-1d", Path = path, State = observedState.name } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/create-blend-tree-2d.cs

@@ -0,0 +1,42 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.create-blend-tree-2d — 创建 2D BlendTree 状态。</summary>
+    public class ControllerCreateBlendTree2DTool : IUnityCliTool<ControllerCreateBlendTree2DTool.Request, ControllerCreateBlendTree2DTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string StateName { get; set; } public string BlendParameterX { get; set; } public string BlendParameterY { get; set; } public int? LayerIndex { get; set; } public string BlendType { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string StateName { get; set; } public string BlendType { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.create-blend-tree-2d", Summary = "Create a 2D BlendTree state in an AnimatorController layer.", Description = "Add a new state with a 2D BlendTree motion. blendType: simpledirectional2d, simpledirectional, freesystemlessdirectional.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create 2D blend tree", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", StateName = "Locomotion", BlendParameterX = "SpeedX", BlendParameterY = "SpeedY" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            if (string.IsNullOrEmpty(r.StateName)) throw new UnityCliBridge.BridgeCommandException("E_STATE_NAME_REQUIRED", "controller.create-blend-tree-2d requires stateName.", "Pass a name for the blend tree state.");
+            var layerIndex = r.LayerIndex ?? 0;
+            if (layerIndex < 0 || layerIndex >= controller.layers.Length) throw new UnityCliBridge.BridgeCommandException("E_LAYER_INDEX_INVALID", "Layer index out of range.", "Run controller.get-info to inspect layers.");
+            var sm = controller.layers[layerIndex].stateMachine;
+            if (AnimationToolSupport.FindStateInLayer(sm, r.StateName) != null) throw new UnityCliBridge.BridgeCommandException("E_STATE_EXISTS", "State '" + r.StateName + "' already exists.", "Choose a different state name.");
+            var bt = (r.BlendType ?? "simpledirectional2d").ToLowerInvariant();
+            var blendType = bt == "freedirectional" || bt == "freesystemlessdirectional" ? BlendTreeType.FreeformDirectional2D : bt == "freecartesian" || bt == "freesystemlesscartesian" ? BlendTreeType.FreeformCartesian2D : BlendTreeType.SimpleDirectional2D;
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Create BlendTree 2D");
+            var blendTree = new BlendTree { name = r.StateName, blendType = blendType, blendParameter = r.BlendParameterX ?? "", blendParameterY = r.BlendParameterY ?? "" };
+            AssetDatabase.AddObjectToAsset(blendTree, controller);
+            var state = sm.AddState(r.StateName); state.motion = blendTree;
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            var observedState = observedController == null ? null : AnimationToolSupport.FindStateInLayer(observedController.layers[layerIndex].stateMachine, r.StateName);
+            var observedTree = observedState == null ? null : observedState.motion as BlendTree;
+            if (observedTree == null || observedTree.blendType != blendType || observedTree.blendParameter != (r.BlendParameterX ?? "") || observedTree.blendParameterY != (r.BlendParameterY ?? "")) throw AnimationToolSupport.StateMismatch("E_CONTROLLER_BLEND_TREE_2D_STATE_MISMATCH", "2D BlendTree");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, StateName = observedState.name, BlendType = observedTree.blendType.ToString(), PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.create-blend-tree-2d", Path = path, State = observedState.name } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/create.cs

@@ -0,0 +1,31 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.create — 创建 AnimatorController 资产。</summary>
+    public class ControllerCreateTool : IUnityCliTool<ControllerCreateTool.Request, ControllerCreateTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } }
+        public sealed class Result { public ControllerInfo Controller { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.create", Summary = "Create a new AnimatorController asset at an Assets/*.controller path.", Description = "Create a new .controller asset with a default Base layer. Refuses to overwrite an existing controller.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create controller", Input = new Request { ControllerPath = "Assets/Animations/Created.controller" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            if (AssetDatabase.LoadAssetAtPath<AnimatorController>(path) != null)
+                throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_EXISTS", "AnimatorController already exists at: " + path, "Delete it first or use a different path.");
+            ctx.CommitEffect();
+            SceneToolSupport.CreateAssetDirectory(path);
+            var controller = AnimatorController.CreateAnimatorControllerAtPath(path);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            if (observedController == null || observedController.name != controller.name || observedController.layers == null || observedController.layers.Length != 1 || observedController.parameters == null || observedController.parameters.Length != 0)
+                throw AnimationToolSupport.StateMismatch("E_CONTROLLER_CREATE_STATE_MISMATCH", "AnimatorController creation");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Controller = new ControllerInfo { Path = path, Guid = AssetDatabase.AssetPathToGUID(path), Name = observedController.name, LayerCount = observedController.layers.Length, ParameterCount = observedController.parameters.Length }, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.create", Path = path } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/get-info.cs

@@ -0,0 +1,27 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.get-info — 读取 Controller 层/状态/参数信息。</summary>
+    public class ControllerGetInfoTool : IUnityCliTool<ControllerGetInfoTool.Request, ControllerGetInfoTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } }
+        public sealed class Result { public ControllerInfo Controller { get; set; } public List<AnimatorParameterInfo> Parameters { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.get-info", Summary = "Read AnimatorController layers, states, and parameters.", Description = "Read-only: returns controller path, guid, layer count, parameter count, and parameter definitions.", Group = "controller",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read controller info", Input = new Request { ControllerPath = "Assets/Animations/Player.controller" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            var parameters = new List<AnimatorParameterInfo>();
+            foreach (var p in controller.parameters) parameters.Add(new AnimatorParameterInfo { Name = p.name, Type = p.type.ToString(), DefaultFloat = p.defaultFloat, DefaultInt = p.defaultInt, DefaultBool = p.defaultBool });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Controller = new ControllerInfo { Path = path, Guid = AssetDatabase.AssetPathToGUID(path), Name = controller.name, LayerCount = controller.layers.Length, ParameterCount = controller.parameters.Length }, Parameters = parameters });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/remove-layer.cs

@@ -0,0 +1,57 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.remove-layer — 移除 Controller 层。</summary>
+    public class ControllerRemoveLayerTool : IUnityCliTool<ControllerRemoveLayerTool.Request, ControllerRemoveLayerTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public int? LayerIndex { get; set; } public string LayerName { get; set; } }
+        public sealed class Result { public string Path { get; set; } public long RemovedLayerIndex { get; set; } public string RemovedLayerName { get; set; } public long RemainingLayerCount { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.remove-layer", Summary = "Remove a layer from an AnimatorController by index or name.", Description = "Remove a layer. The base layer (index 0) cannot be removed. Pass layerIndex or layerName.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Remove layer", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", LayerIndex = 1 } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            if (!r.LayerIndex.HasValue && string.IsNullOrEmpty(r.LayerName)) throw new UnityCliBridge.BridgeCommandException("E_LAYER_IDENTIFIER_REQUIRED", "controller.remove-layer requires layerIndex or layerName.", "Pass either a layer index or a layer name.");
+            var removeIndex = -1; var removeName = "";
+            if (r.LayerIndex.HasValue) { removeIndex = r.LayerIndex.Value; if (removeIndex < 0 || removeIndex >= controller.layers.Length) throw new UnityCliBridge.BridgeCommandException("E_LAYER_NOT_FOUND", "Layer index out of range: " + removeIndex, "Run controller.get-info to inspect layers."); removeName = controller.layers[removeIndex].name; }
+            else { for (var i = 0; i < controller.layers.Length; i++) if (controller.layers[i].name == r.LayerName) { removeIndex = i; removeName = r.LayerName; break; } if (removeIndex < 0) throw new UnityCliBridge.BridgeCommandException("E_LAYER_NOT_FOUND", "Layer not found: " + r.LayerName, "Run controller.get-info to inspect layers."); }
+            if (removeIndex == 0) throw new UnityCliBridge.BridgeCommandException("E_LAYER_BASE_IMMUTABLE", "The base layer (index 0) cannot be removed.", "Remove a non-base layer instead.");
+            var controllerGuid = AssetDatabase.AssetPathToGUID(path);
+            if (string.IsNullOrEmpty(controllerGuid)) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController has no stable asset GUID: " + path, "Check the controller asset path and retry.");
+            var removedIdentity = AnimationToolSupport.CaptureLayerIdentity(controller.layers[removeIndex]);
+            var expectedRemaining = new List<ControllerLayerIdentity>();
+            for (var index = 0; index < controller.layers.Length; index++)
+                if (index != removeIndex) expectedRemaining.Add(AnimationToolSupport.CaptureLayerIdentity(controller.layers[index]));
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Remove Layer");
+            var layers = new List<AnimatorControllerLayer>(controller.layers); layers.RemoveAt(removeIndex); controller.layers = layers.ToArray();
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path, controllerGuid);
+            var observedLayers = observedController == null ? null : observedController.layers;
+            var removalProven = observedLayers != null && observedLayers.Length == expectedRemaining.Count;
+            if (removalProven)
+            {
+                for (var index = 0; index < observedLayers.Length; index++)
+                {
+                    var observedIdentity = AnimationToolSupport.CaptureLayerIdentity(observedLayers[index]);
+                    if (AnimationToolSupport.SameLayerIdentity(observedIdentity, removedIdentity)
+                        || !AnimationToolSupport.SameLayerIdentity(observedIdentity, expectedRemaining[index]))
+                    {
+                        removalProven = false;
+                        break;
+                    }
+                }
+            }
+            if (!removalProven) throw AnimationToolSupport.StateMismatch("E_CONTROLLER_REMOVE_LAYER_STATE_MISMATCH", "AnimatorController layer removal");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, RemovedLayerIndex = removeIndex, RemovedLayerName = removeName, RemainingLayerCount = observedController.layers.Length, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.remove-layer", Path = path } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/set-layer-weight.cs

@@ -0,0 +1,42 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.set-layer-weight — 设置层权重。</summary>
+    public class ControllerSetLayerWeightTool : IUnityCliTool<ControllerSetLayerWeightTool.Request, ControllerSetLayerWeightTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public int? LayerIndex { get; set; } public string LayerName { get; set; } public float? Weight { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string LayerName { get; set; } public double Weight { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.set-layer-weight", Summary = "Set the default weight of an AnimatorController layer.", Description = "Set the default weight of a layer by index or name. Weight 0 disables the layer.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set layer weight", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", LayerIndex = 1, Weight = 0.5f } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AnimationToolSupport.RequireControllerPath(r.ControllerPath);
+            var controller = AnimationToolSupport.LoadControllerAsset(path);
+            if (controller == null) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController not found at: " + path, "Check the path or create one with controller.create.");
+            var idx = -1;
+            if (r.LayerIndex.HasValue) idx = r.LayerIndex.Value;
+            else if (!string.IsNullOrEmpty(r.LayerName)) { for (var i = 0; i < controller.layers.Length; i++) if (controller.layers[i].name == r.LayerName) { idx = i; break; } }
+            if (idx < 0 || idx >= controller.layers.Length) throw new UnityCliBridge.BridgeCommandException("E_LAYER_NOT_FOUND", "Layer not found.", "Run controller.get-info to inspect layers.");
+            var weight = r.Weight ?? 1f;
+            if (float.IsNaN(weight) || float.IsInfinity(weight) || weight < 0f || weight > 1f)
+                throw new UnityCliBridge.BridgeCommandException("E_LAYER_WEIGHT_INVALID", "Layer weight must be finite and within Unity's 0 to 1 range.", "Pass a finite weight from 0 to 1.");
+            var controllerGuid = AssetDatabase.AssetPathToGUID(path);
+            if (string.IsNullOrEmpty(controllerGuid)) throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_NOT_FOUND", "AnimatorController has no stable asset GUID: " + path, "Check the controller asset path and retry.");
+            var expectedLayer = AnimationToolSupport.CaptureLayerIdentity(controller.layers[idx]);
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Set Layer Weight");
+            var layers = controller.layers; layers[idx].defaultWeight = weight; controller.layers = layers;
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path, controllerGuid);
+            var observedLayers = observedController == null ? null : observedController.layers;
+            if (observedLayers == null || idx >= observedLayers.Length || observedLayers[idx].name != expectedLayer.Name || !Mathf.Approximately(observedLayers[idx].defaultWeight, weight)) throw AnimationToolSupport.StateMismatch("E_CONTROLLER_LAYER_WEIGHT_STATE_MISMATCH", "AnimatorController layer weight");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, LayerName = observedLayers[idx].name, Weight = observedLayers[idx].defaultWeight, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.set-layer-weight", Path = path } } });
+        }
+    }
+}
+#endif