@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/component/list-types.cs

@@ -0,0 +1,90 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using System.Reflection;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// component.list-types — 枚举当前项目可用的 Component 类型,支持 keyword 过滤与分页。
+    /// </summary>
+    public class ComponentListTypesTool : IUnityCliTool<ComponentListTypesTool.Request, ComponentListTypesTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Keyword { get; set; }
+            public string Search { get; set; }
+            public int? PageSize { get; set; }
+            public int? Cursor { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long Count { get; set; }
+            public List<ComponentTypeInfo> Types { get; set; }
+            public GoPageInfo PageInfo { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "component.list-types",
+            Summary = "Enumerate Component types available in the current project across loaded assemblies.",
+            Description = "Enumerate Component types available in the current project across loaded assemblies. Use keyword plus pageSize/cursor to bound token usage before calling component.add/get/set/modify. Returns fullName/name/assembly/namespace and pageInfo.nextCursor.",
+            Group = "component",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List Rigidbody types", Input = new Request { Keyword = "Rigidbody", PageSize = 20 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var keyword = request.Keyword ?? request.Search;
+            var pageSize = Math.Max(1, Math.Min(request.PageSize ?? 100, 500));
+            var cursor = Math.Max(0, request.Cursor ?? 0);
+            var types = new List<Type>();
+            foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+            {
+                Type[] candidates;
+                try { candidates = assembly.GetTypes(); }
+                catch (ReflectionTypeLoadException e) { candidates = e.Types.Where(t => t != null).ToArray(); }
+                foreach (var t in candidates)
+                {
+                    if (t == null || !typeof(Component).IsAssignableFrom(t)) continue;
+                    if (t.IsAbstract) continue;
+                    if (!string.IsNullOrEmpty(keyword) && t.FullName.IndexOf(keyword, StringComparison.OrdinalIgnoreCase) < 0) continue;
+                    types.Add(t);
+                }
+            }
+            types.Sort((a, b) => string.Compare(a.FullName, b.FullName, StringComparison.Ordinal));
+            var total = types.Count;
+            var page = types.Skip(cursor).Take(pageSize).ToList();
+            long? nextCursor = cursor + page.Count < total ? (long?)(cursor + page.Count) : null;
+            var result = new Result
+            {
+                Count = total,
+                Types = page.ConvertAll(t => new ComponentTypeInfo { FullName = t.FullName, Name = t.Name, Assembly = t.Assembly.GetName().Name, Namespace = t.Namespace }),
+                PageInfo = new GoPageInfo { PageSize = pageSize, Cursor = cursor, NextCursor = nextCursor, Total = total }
+            };
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+    }
+
+    /// <summary>Component 类型信息摘要。</summary>
+    public sealed class ComponentTypeInfo
+    {
+        public string FullName { get; set; }
+        public string Name { get; set; }
+        public string Assembly { get; set; }
+        public string Namespace { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/component/modify.cs

@@ -0,0 +1,103 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// component.modify — 用可验证的 SerializedProperty pathPatches 修改单个 Component。支持 dryRun。
+    /// </summary>
+    public class ComponentModifyTool : IUnityCliTool<ComponentModifyTool.Request, ComponentModifyTool.Result>
+    {
+        public sealed class Request : IUnityCliObjectReferenceInput
+        {
+            public int? InstanceId { get; set; }
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public string Target { get; set; }
+            public string AssetPath { get; set; }
+            public string Guid { get; set; }
+            public int? ComponentInstanceId { get; set; }
+            public int? ComponentIndex { get; set; }
+            public string Component { get; set; }
+            public string ComponentType { get; set; }
+            public int? MaxDepth { get; set; }
+            [UnityCliAnyJson] public List<object> PathPatches { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool? DryRun { get; set; }
+            public string TypeName { get; set; }
+            public List<string> ChangedPaths { get; set; }
+            [UnityCliAnyJson] public object UpdatedData { get; set; }
+            public List<GameObjectPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "component.modify",
+            Summary = "Modify one Component with verified serialized pathPatches; use component.get/type.schema first.",
+            Description = "Apply direct replace pathPatches to verifiable SerializedProperties of one Component. Returns fresh updated data and changed paths. Use component.get first. In Play Mode, scene component changes affect only the current runtime session unless later persisted by Unity workflow; in Edit Mode they mark scene/component state dirty.",
+            Group = "component",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "component-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Patch localPosition", Input = new Request { Path = "Player", Component = "Transform", PathPatches = new List<object> { new Dictionary<string, object> { { "path", "m_LocalPosition.x" }, { "op", "replace" }, { "value", 1L } } } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("component.modify");
+            var component = UnityCliBridge.ObjectRefResolver.ResolveComponent(request);
+            if (request.PathPatches == null || request.PathPatches.Count == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_PATCH_REQUIRED", "component.modify requires non-empty pathPatches.", "Pass direct replace pathPatches for writable serialized properties.");
+            UnityCliBridge.ObjectPatch.ValidateOnly(component, request.PathPatches, null);
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    DryRun = true,
+                    TypeName = component.GetType().FullName,
+                    PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "component.modify", Target = component.gameObject.name } }
+                });
+            }
+            if (EditorApplication.isPlaying && EditorUtility.IsPersistent(component))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", "component.modify cannot modify persistent assets during Play Mode.", "Target a scene component or exit Play Mode before modifying an asset.");
+            }
+
+            // 所有请求形态、target 和 PlayMode 均已预检；紧邻首个 patch effect 提交屏障。
+            ctx.CommitEffect();
+            UnityCliBridge.ObjectPatch.PatchResult result = UnityCliBridge.ObjectPatch.ApplyVerifiedSerializedPatches(component, request.PathPatches);
+            UnityCliSceneMutation.MarkSceneObjectDirty(component);
+            UnityCliSceneMutation.MarkSceneDirty(component.gameObject.scene);
+            var componentId = component.GetInstanceID();
+            var observedComponent = EditorUtility.InstanceIDToObject(componentId) as Component;
+            if (observedComponent == null || observedComponent.GetInstanceID() != componentId)
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_MODIFY_STATE_MISMATCH", "Component target/type did not match after independent readback.", "Inspect the component and retry after the Editor is idle.");
+            var observedSerializedObject = new SerializedObject(observedComponent);
+            observedSerializedObject.Update();
+            UnityCliBridge.ObjectPatch.VerifyFreshSerializedProperties(observedComponent, request.PathPatches);
+            var maxDepth = request.MaxDepth ?? 2;
+            var updatedData = UnityCliBridge.ObjectSerializer.Serialize(observedComponent, new UnityCliBridge.ObjectSerializer.Options { MaxDepth = maxDepth, IncludeFields = true, IncludeProperties = true, DeepSerialization = false });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                TypeName = component.GetType().FullName,
+                ChangedPaths = new List<string>(result.ChangedPaths),
+                UpdatedData = updatedData
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/component/remove.cs

@@ -0,0 +1,147 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// component.remove — 从 GameObject 删除一个或多个非 Transform Component,支持 componentIndex 精确选择。
+    /// </summary>
+    public class ComponentRemoveTool : IUnityCliTool<ComponentRemoveTool.Request, ComponentRemoveTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Component { get; set; }
+            public List<string> Components { get; set; }
+            public int? ComponentIndex { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ComponentSummary Component { get; set; }
+            public List<ComponentSummary> Components { get; set; }
+            public long RemovedCount { get; set; }
+            public List<GameObjectPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "component.remove",
+            Summary = "Remove one or more non-Transform Components from a GameObject.",
+            Description = "Remove one or more non-Transform Components from a GameObject in the current scene/session. Use component for one type and componentIndex when multiple components of the same type exist; use components as a string array to remove multiple different component types in one call.",
+            Group = "component",
+            DestructiveHint = false,
+            SideEffects = new[] { "component-remove", "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Remove first BoxCollider", Input = new Request { Target = "Player", Component = "BoxCollider", ComponentIndex = 0 } },
+                new ToolExample { Description = "Remove multiple component types", Input = new Request { Target = "ComponentTarget", Components = new List<string> { "BoxCollider", "Rigidbody" } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("component.remove");
+            var gameObject = ComponentAddTool.ResolveTarget(request.Target, "Component remove requires a target.");
+
+            // components[] 批量删除模式
+            if (request.Components != null && request.Components.Count > 0)
+            {
+                var targets = new List<Component>();
+                foreach (var name in request.Components)
+                {
+                    var component = GameObjectToolSupport.ResolveComponent(gameObject, name, null);
+                    if (component == null)
+                    {
+                        throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_NOT_FOUND", "Component not found on target: " + name, "Run unitycli tools run component.get or tools run scene.gameobject.components to list components.");
+                    }
+                    EnsureNotTransform(component, name);
+                    targets.Add(component);
+                }
+                var targetIds = new HashSet<int>();
+                foreach (var component in targets)
+                    if (!targetIds.Add(component.GetInstanceID()))
+                        throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_REMOVE_DUPLICATE", "components resolves the same Component more than once.", "Pass each component type once.");
+                EnsureDependenciesRemain(gameObject, targets);
+                var removed = new List<ComponentSummary>();
+                ctx.CommitEffect();
+                foreach (var component in targets)
+                {
+                    removed.Add(GameObjectToolSupport.BuildComponentSummary(component));
+                    UnityCliSceneMutation.DestroyObject(component);
+                }
+                UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+                var observedTarget = EditorUtility.InstanceIDToObject(gameObject.GetInstanceID()) as GameObject;
+                if (observedTarget == null || targetIds.Any(id => EditorUtility.InstanceIDToObject(id) != null))
+                    throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_REMOVE_STATE_MISMATCH", "Removed component remained on the target after independent readback.", "Inspect the target GameObject and retry after the Editor is idle.");
+                var effects = new List<GameObjectPlannedEffect>();
+                foreach (var name in request.Components)
+                {
+                    effects.Add(new GameObjectPlannedEffect { Type = "component.remove", Target = GameObjectToolSupport.HierarchyPath(gameObject), Component = name });
+                }
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Components = removed, RemovedCount = removed.Count, PlannedEffects = effects });
+            }
+
+            // 单组件删除模式
+            var componentName = ComponentAddTool.RequireComponentName(request.Component);
+            var singleComponent = GameObjectToolSupport.ResolveComponent(gameObject, componentName, request.ComponentIndex);
+            if (singleComponent == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_NOT_FOUND", "Component not found on target: " + componentName, "Run unitycli tools run component.get or tools run scene.gameobject.components to list components.");
+            }
+            EnsureNotTransform(singleComponent, componentName);
+            EnsureDependenciesRemain(gameObject, new[] { singleComponent });
+            var singleRemoved = GameObjectToolSupport.BuildComponentSummary(singleComponent);
+            var removedId = singleComponent.GetInstanceID();
+            ctx.CommitEffect();
+            UnityCliSceneMutation.DestroyObject(singleComponent);
+            UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+            var observedSingleTarget = EditorUtility.InstanceIDToObject(gameObject.GetInstanceID()) as GameObject;
+            if (EditorUtility.InstanceIDToObject(removedId) != null || observedSingleTarget == null)
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_REMOVE_STATE_MISMATCH", "Removed component remained on the target after independent readback.", "Inspect the target GameObject and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Component = singleRemoved,
+                PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "component.remove", Target = GameObjectToolSupport.HierarchyPath(gameObject), Component = componentName } }
+            });
+        }
+
+        /// <summary>在 effect 前验证剩余组件仍满足 RequireComponent，避免 Unity 静默拒绝删除。</summary>
+        private static void EnsureDependenciesRemain(GameObject gameObject, IEnumerable<Component> removals)
+        {
+            var removedIds = new HashSet<int>(removals.Select(component => component.GetInstanceID()));
+            var remaining = gameObject.GetComponents<Component>().Where(component => component != null && !removedIds.Contains(component.GetInstanceID())).ToArray();
+            foreach (var owner in remaining)
+            {
+                foreach (RequireComponent requirement in owner.GetType().GetCustomAttributes(typeof(RequireComponent), true))
+                {
+                    foreach (var fieldName in new[] { "m_Type0", "m_Type1", "m_Type2" })
+                    {
+                        var field = typeof(RequireComponent).GetField(fieldName, System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.NonPublic);
+                        var requiredType = field == null ? null : field.GetValue(requirement) as System.Type;
+                        if (requiredType != null && !remaining.Any(component => requiredType.IsAssignableFrom(component.GetType())))
+                            throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_REMOVE_DEPENDENCY", owner.GetType().Name + " requires " + requiredType.Name + ", so the requested removal is invalid.", "Remove the dependent component in the same request, or keep its required component.");
+                    }
+                }
+            }
+        }
+
+        private static void EnsureNotTransform(Component component, string name)
+        {
+            if (component is Transform)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_REMOVE_UNSUPPORTED", "Transform cannot be removed from a GameObject.", "Remove a non-Transform component.");
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/component/set.cs

@@ -0,0 +1,93 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// component.set — 设置 Component 的一个或多个简单公开字段/属性。
+    /// </summary>
+    public class ComponentSetTool : IUnityCliTool<ComponentSetTool.Request, ComponentSetTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Component { get; set; }
+            public int? ComponentIndex { get; set; }
+            public string Property { get; set; }
+            [UnityCliAnyJson] public object Value { get; set; }
+            [UnityCliAnyJson] public Dictionary<string, object> Properties { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ComponentSummary Component { get; set; }
+            public List<ChangedProperty> ChangedProperties { get; set; }
+            public List<GameObjectPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "component.set",
+            Summary = "Set one simple public field/property, or multiple simple fields/properties via properties, on a Component attached to a GameObject.",
+            Description = "Set one simple public field/property, or multiple simple fields/properties via properties, on a Component attached to a GameObject. For nested values, object references, arrays, or SerializedObject-style patches, use component.modify after component.get/type.schema.",
+            Group = "component",
+            DestructiveHint = false,
+            SideEffects = new[] { "component-modify", "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set multiple Rigidbody values", Input = new Request { Target = "Player", Component = "Rigidbody", Properties = new Dictionary<string, object> { { "mass", 5L }, { "useGravity", false } } } },
+                new ToolExample { Description = "Set one boolean value", Input = new Request { Target = "Main Camera", Component = "Camera", Property = "enabled", Value = false } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("component.set");
+            var gameObject = ComponentAddTool.ResolveTarget(request.Target, "Component set requires a target.");
+            var componentName = ComponentAddTool.RequireComponentName(request.Component);
+            var component = GameObjectToolSupport.ResolveComponent(gameObject, componentName, request.ComponentIndex);
+            if (component == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_NOT_FOUND", "Component not found on target: " + componentName, "Run unitycli tools run component.get or tools run scene.gameobject.components to list components.");
+            }
+
+            if (string.IsNullOrEmpty(request.Property) && (request.Properties == null || request.Properties.Count == 0))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_PROPERTY_REQUIRED", "component.set requires property/value or a properties object.", "Pass --input '{\"target\":\"Player\",\"component\":\"Rigidbody\",\"properties\":{\"mass\":5}}'.");
+            }
+
+            var propertyChanges = new List<ComponentPropertyChange>();
+            if (!string.IsNullOrEmpty(request.Property))
+            {
+                if (request.Value == null)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_VALUE_REQUIRED", "component.set requires a value when property is provided.", "Pass value as --input JSON so booleans/numbers keep their type.");
+                }
+                propertyChanges.Add(GameObjectToolSupport.BuildComponentPropertyChange(component.GetType(), request.Property, request.Value));
+            }
+            propertyChanges.AddRange(GameObjectToolSupport.BuildComponentPropertyChanges(component.GetType(), request.Properties));
+
+            ctx.CommitEffect();
+            UnityCliSceneMutation.RecordObject(component, "component.set");
+            GameObjectToolSupport.ApplyComponentPropertyChanges(component, propertyChanges);
+            UnityCliSceneMutation.MarkSceneObjectDirty(component);
+            UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+            var observedComponent = ComponentAddTool.VerifyComponentReadback(gameObject.GetInstanceID(), component.GetInstanceID(), component.GetType(), propertyChanges);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Component = GameObjectToolSupport.BuildComponentSummary(observedComponent),
+                ChangedProperties = ComponentAddTool.BuildChangedProperties(propertyChanges),
+                PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "component.set", Target = GameObjectToolSupport.HierarchyPath(gameObject), Component = component.GetType().Name } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/console/clear.cs

@@ -0,0 +1,38 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using UnityEditor;
+using UnityEditor.Compilation;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>console.clear — 清空 Console。</summary>
+    public class ConsoleClearTool : IUnityCliTool<ConsoleClearTool.Request, ConsoleClearTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public bool DryRun { get; set; } public bool Cleared { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "console.clear", Summary = "Clear the Unity Console log.", Description = "Clear all Console entries via LogEntries.Clear(). dryRun=true previews without clearing.", Group = "console",DestructiveHint = false, SupportsDryRun = true, SideEffects = new[] { "editor-console-state" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Clear console", Input = new Request { } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "console.clear" } } });
+            var logEntriesType = GameObjectToolSupport.FindType("UnityEditor.LogEntries");
+            if (logEntriesType == null)
+                throw new UnityCliBridge.BridgeCommandException("E_CONSOLE_CLEAR_UNSUPPORTED", "UnityEditor.LogEntries is unavailable.", "Use a Unity Editor version that exposes Console log entries.");
+            var clearMethod = logEntriesType.GetMethod("Clear", BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            var getCountMethod = logEntriesType.GetMethod("GetCount", BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (clearMethod == null || getCountMethod == null)
+                throw new UnityCliBridge.BridgeCommandException("E_CONSOLE_CLEAR_UNSUPPORTED", "UnityEditor.LogEntries.Clear or GetCount is unavailable.", "Use a Unity Editor version that exposes Console log entry controls.");
+            ctx.CommitEffect();
+            clearMethod.Invoke(null, null);
+            var count = Convert.ToInt32(getCountMethod.Invoke(null, null));
+            if (count != 0)
+                throw new UnityCliBridge.BridgeCommandException("E_CONSOLE_CLEAR_STATE_MISMATCH", "Unity Console still contains " + count + " entries after clearing.", "Inspect the Unity Console and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, Cleared = true, PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "console.clear" } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/console/get.cs

@@ -0,0 +1,28 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using UnityEditor;
+using UnityEditor.Compilation;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>console.get — 读取 Console 日志(支持过滤和分页)。</summary>
+    public class ConsoleGetTool : IUnityCliTool<ConsoleGetTool.Request, ConsoleGetTool.Result>
+    {
+        public sealed class Request { public string Type { get; set; } public string Filter { get; set; } public int? Count { get; set; } public int? Cursor { get; set; } }
+        public sealed class Result { public List<ConsoleEntry> Items { get; set; } public PageInfo PageInfo { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "console.get", Summary = "Read Unity Console entries with type filter, text search, and cursor paging.", Description = "Read Console entries newest-first. type filters by error/warning/log. filter does case-insensitive text search. cursor for pagination.", Group = "console",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read errors", Input = new Request { Type = "error", Count = 10 } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var count = Math.Max(1, Math.Min(r.Count ?? 50, 500));
+            var cursor = Math.Max(0, r.Cursor ?? 0);
+            var items = EditorToolSupport.ReadConsoleEntries(r.Type, r.Filter, count + cursor);
+            var paged = items.Skip(cursor).Take(count).ToList();
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Items = paged, PageInfo = new PageInfo { PageSize = count, Cursor = cursor, Total = items.Count, NextCursor = cursor + paged.Count < items.Count ? (long?)(cursor + paged.Count) : null } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/controller/add-blend-tree-child.cs

@@ -0,0 +1,88 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.add-blend-tree-child — 向 BlendTree 添加子动画。</summary>
+    public class ControllerAddBlendTreeChildTool : IUnityCliTool<ControllerAddBlendTreeChildTool.Request, ControllerAddBlendTreeChildTool.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? Threshold { get; set; } public float? PositionX { get; set; } public float? PositionY { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string StateName { get; set; } public long ChildCount { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.add-blend-tree-child", Summary = "Add a child motion to an existing BlendTree state.", Description = "Add an AnimationClip as a child to a BlendTree state. threshold for 1D, positionX/positionY for 2D.", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add blend tree child", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", StateName = "Move", ClipPath = "Assets/Animations/Walk.anim", Threshold = 0.5f } } } };
+        /// <summary>按 BlendTree 类型添加 child，并以 GUID、数量增量和请求值证明持久终态。</summary>
+        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 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;
+            var state = AnimationToolSupport.FindStateInLayer(sm, r.StateName);
+            if (state == null) throw new UnityCliBridge.BridgeCommandException("E_STATE_NOT_FOUND", "State '" + r.StateName + "' not found in layer " + layerIndex + ".", "Run controller.get-info to inspect states.");
+            var blendTree = state.motion as BlendTree;
+            if (blendTree == null) throw new UnityCliBridge.BridgeCommandException("E_NOT_A_BLEND_TREE", "State '" + r.StateName + "' does not have a BlendTree motion.", "Use controller.create-blend-tree-1d or create-blend-tree-2d first.");
+            if (string.IsNullOrEmpty(r.ClipPath)) throw new UnityCliBridge.BridgeCommandException("E_CLIP_PATH_REQUIRED", "controller.add-blend-tree-child requires clipPath.", "Pass an Assets/*.anim AnimationClip path.");
+            var clipPath = SceneToolSupport.NormalizeAssetPath(r.ClipPath);
+            var clip = AssetDatabase.LoadAssetAtPath<AnimationClip>(clipPath);
+            if (clip == null) throw new UnityCliBridge.BridgeCommandException("E_CLIP_NOT_FOUND", "AnimationClip not found at: " + r.ClipPath, "Create the clip first.");
+            var controllerGuid = AssetDatabase.AssetPathToGUID(path);
+            var clipGuid = AssetDatabase.AssetPathToGUID(clipPath);
+            if (string.IsNullOrEmpty(controllerGuid) || string.IsNullOrEmpty(clipGuid))
+                throw new UnityCliBridge.BridgeCommandException("E_CONTROLLER_BLEND_TREE_CHILD_IDENTITY_MISSING", "Controller or clip has no stable asset GUID.", "Reimport the assets before retrying.");
+
+            var isOneDimensional = blendTree.blendType == BlendTreeType.Simple1D;
+            var isTwoDimensional = blendTree.blendType == BlendTreeType.SimpleDirectional2D
+                || blendTree.blendType == BlendTreeType.FreeformDirectional2D
+                || blendTree.blendType == BlendTreeType.FreeformCartesian2D;
+            if (!isOneDimensional && !isTwoDimensional)
+                throw new UnityCliBridge.BridgeCommandException("E_BLEND_TREE_TYPE_UNSUPPORTED", "controller.add-blend-tree-child supports 1D and 2D BlendTrees only.", "Use a 1D or 2D BlendTree state.");
+            if (isOneDimensional && (r.PositionX.HasValue || r.PositionY.HasValue))
+                throw new UnityCliBridge.BridgeCommandException("E_BLEND_TREE_CHILD_INPUT_CONFLICT", "positionX/positionY are only valid for 2D BlendTrees.", "Pass threshold for a 1D BlendTree.");
+            if (isTwoDimensional && r.Threshold.HasValue)
+                throw new UnityCliBridge.BridgeCommandException("E_BLEND_TREE_CHILD_INPUT_CONFLICT", "threshold is only valid for 1D BlendTrees.", "Pass positionX/positionY for a 2D BlendTree.");
+            var threshold = r.Threshold ?? 0f;
+            var position = new Vector2(r.PositionX ?? 0f, r.PositionY ?? 0f);
+            if (float.IsNaN(threshold) || float.IsInfinity(threshold) || float.IsNaN(position.x) || float.IsInfinity(position.x) || float.IsNaN(position.y) || float.IsInfinity(position.y))
+                throw new UnityCliBridge.BridgeCommandException("E_BLEND_TREE_CHILD_VALUE_INVALID", "BlendTree child threshold and position must be finite.", "Pass finite numeric values.");
+            var beforeChildren = blendTree.children ?? new ChildMotion[0];
+            var beforeMatches = beforeChildren.Count(child => MatchesRequestedChild(child, clip, isOneDimensional, threshold, position));
+
+            ctx.CommitEffect();
+            Undo.RecordObject(blendTree, "Add BlendTree Child");
+            if (isOneDimensional)
+            {
+                // 显式关闭自动 threshold，防止 Unity 重排后改写请求值。
+                blendTree.useAutomaticThresholds = false;
+                blendTree.AddChild(clip, threshold);
+            }
+            else blendTree.AddChild(clip, position);
+            EditorUtility.SetDirty(blendTree);
+            EditorUtility.SetDirty(controller);
+
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path, controllerGuid);
+            var observedClipPath = AssetDatabase.GUIDToAssetPath(clipGuid);
+            var observedClip = string.Equals(observedClipPath, clipPath, System.StringComparison.Ordinal) ? AssetDatabase.LoadAssetAtPath<AnimationClip>(observedClipPath) : null;
+            var observedState = observedController == null || layerIndex >= observedController.layers.Length ? null : AnimationToolSupport.FindStateInLayer(observedController.layers[layerIndex].stateMachine, r.StateName);
+            var observedTree = observedState == null ? null : observedState.motion as BlendTree;
+            var observedChildren = observedTree == null ? null : observedTree.children;
+            var observedMatches = observedChildren == null || observedClip == null ? 0 : observedChildren.Count(child => MatchesRequestedChild(child, observedClip, isOneDimensional, threshold, position));
+            if (observedChildren == null || observedChildren.Length != beforeChildren.Length + 1 || observedMatches != beforeMatches + 1 || (isOneDimensional && observedTree.useAutomaticThresholds))
+                throw AnimationToolSupport.StateMismatch("E_CONTROLLER_BLEND_TREE_CHILD_STATE_MISMATCH", "BlendTree child");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, StateName = observedState.name, ChildCount = observedChildren.Length, PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.add-blend-tree-child", Path = path, State = observedState.name } } });
+        }
+
+        private static bool MatchesRequestedChild(ChildMotion child, AnimationClip clip, bool oneDimensional, float threshold, Vector2 position)
+        {
+            return child.motion == clip && (oneDimensional
+                ? Mathf.Approximately(child.threshold, threshold)
+                : Mathf.Approximately(child.position.x, position.x) && Mathf.Approximately(child.position.y, position.y));
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,43 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.Animations;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>controller.add-layer — 添加层到 Controller。</summary>
+    public class ControllerAddLayerTool : IUnityCliTool<ControllerAddLayerTool.Request, ControllerAddLayerTool.Result>
+    {
+        public sealed class Request { public string ControllerPath { get; set; } public string LayerName { get; set; } public float? Weight { get; set; } public string BlendingMode { get; set; } }
+        public sealed class Result { public string Path { get; set; } public string LayerName { get; set; } public long LayerIndex { get; set; } public double Weight { get; set; } public string BlendingMode { get; set; } public List<AnimationPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "controller.add-layer", Summary = "Add a new layer to an AnimatorController.", Description = "Add a layer with a name, weight (default 1), and blending mode (override or additive).", Group = "controller",DestructiveHint = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add layer", Input = new Request { ControllerPath = "Assets/Animations/Player.controller", LayerName = "UpperBody" } } } };
+        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.LayerName)) throw new UnityCliBridge.BridgeCommandException("E_LAYER_NAME_REQUIRED", "controller.add-layer requires layerName.", "Pass a name for the new layer.");
+            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 blendingMode = (r.BlendingMode ?? "override").ToLowerInvariant() == "additive" ? AnimatorLayerBlendingMode.Additive : AnimatorLayerBlendingMode.Override;
+            ctx.CommitEffect();
+            Undo.RecordObject(controller, "Add Layer");
+            controller.AddLayer(r.LayerName);
+            var layers = controller.layers;
+            var newLayer = layers[layers.Length - 1];
+            newLayer.defaultWeight = weight; newLayer.blendingMode = blendingMode;
+            layers[layers.Length - 1] = newLayer; controller.layers = layers;
+            EditorUtility.SetDirty(controller);
+            var observedController = AnimationToolSupport.ReloadControllerAsset(path);
+            var observedLayers = observedController == null ? null : observedController.layers;
+            var observedIndex = observedLayers == null ? -1 : observedLayers.Length - 1;
+            if (observedIndex < 0 || observedLayers[observedIndex].name != r.LayerName || !Mathf.Approximately(observedLayers[observedIndex].defaultWeight, weight) || observedLayers[observedIndex].blendingMode != blendingMode)
+                throw AnimationToolSupport.StateMismatch("E_CONTROLLER_ADD_LAYER_STATE_MISMATCH", "AnimatorController layer");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Path = path, LayerName = observedLayers[observedIndex].name, LayerIndex = observedIndex, Weight = observedLayers[observedIndex].defaultWeight, BlendingMode = observedLayers[observedIndex].blendingMode.ToString(), PlannedEffects = new List<AnimationPlannedEffect> { new AnimationPlannedEffect { Type = "controller.add-layer", Path = path } } });
+        }
+    }
+}
+#endif