@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,333 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>创建一个或一批 scene GameObject，并以完整 fresh object set 证明终态。</summary>
+    public class GameObjectCreateTool : IUnityCliTool<GameObjectCreateTool.Request, GameObjectCreateTool.Result>
+    {
+        private const int MaxBatchCount = 1000;
+
+        public sealed class Request
+        {
+            public string Name { get; set; }
+            public string Target { get; set; }
+            public string Parent { get; set; }
+            public string Primitive { get; set; }
+            public int? Count { get; set; }
+            public List<List<double>> Positions { get; set; }
+            public List<List<double>> Rotations { get; set; }
+            public List<List<double>> Scales { get; set; }
+            public bool? Active { get; set; }
+            public string TagValue { get; set; }
+            public string LayerValue { get; set; }
+            public double? X { get; set; }
+            public double? Y { get; set; }
+            public double? Z { get; set; }
+            public double? RotationX { get; set; }
+            public double? RotationY { get; set; }
+            public double? RotationZ { get; set; }
+            public double? ScaleX { get; set; }
+            public double? ScaleY { get; set; }
+            public double? ScaleZ { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long Count { get; set; }
+            public GameObjectDetail GameObject { get; set; }
+            public List<GameObjectDetail> GameObjects { get; set; }
+            public List<PlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public sealed class PlannedEffect
+        {
+            public string Type { get; set; }
+            public long Count { get; set; }
+            public string Parent { get; set; }
+            public string Target { get; set; }
+        }
+
+        private sealed class CreatePlan
+        {
+            public int Count;
+            public Transform Parent;
+            public PrimitiveType? Primitive;
+            public bool? Active;
+            public string TagValue;
+            public string LayerValue;
+            public List<CreateItemPlan> Items;
+        }
+
+        private sealed class CreateItemPlan
+        {
+            public string Name;
+            public double? X;
+            public double? Y;
+            public double? Z;
+            public double? RotationX;
+            public double? RotationY;
+            public double? RotationZ;
+            public double? ScaleX;
+            public double? ScaleY;
+            public double? ScaleZ;
+            public List<double> LocalPosition;
+            public List<double> LocalRotation;
+            public List<double> LocalScale;
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "go.create",
+            Summary = "Create one or up to 1000 scene GameObjects in one call, with optional primitive, parent, and per-object local transforms.",
+            Description = "count defaults to 1. For a batch, positions/rotations/scales are optional arrays of exactly count [x,y,z] vectors; scalar transform fields remain the single-object form. The parent and every input are resolved before one effect barrier. Success returns the complete ordered object set from fresh instance-id readback.",
+            Group = "go",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create one cube under the scene root.", Input = new Request { Name = "AlignmentCube", Primitive = "cube", X = 0, Y = 1, Z = 0 } },
+                new ToolExample
+                {
+                    Description = "Create three individually addressable spheres with local positions.",
+                    Input = new Request
+                    {
+                        Name = "Probe", Primitive = "sphere", Count = 3,
+                        Positions = new List<List<double>>
+                        {
+                            new List<double> { 0, 0, 0 }, new List<double> { 1, 0, 0 }, new List<double> { 2, 0, 0 }
+                        }
+                    }
+                }
+            }
+        };
+
+        /// <summary>整批预检后跨越唯一 effect barrier，在一个 Undo group 中创建并 fresh 证明完整集合。</summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default(System.Threading.CancellationToken))
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("go.create");
+            ct.ThrowIfCancellationRequested();
+            var plan = Prepare(request ?? new Request());
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            var instanceIds = new List<int>(plan.Count);
+            var undoGroup = UnityCliSceneMutation.BeginUndoGroup("go.create");
+            try
+            {
+                foreach (var item in plan.Items)
+                {
+                    var gameObject = plan.Primitive.HasValue
+                        ? GameObject.CreatePrimitive(plan.Primitive.Value)
+                        : new GameObject(item.Name);
+                    gameObject.name = item.Name;
+                    if (plan.Parent != null) gameObject.transform.SetParent(plan.Parent, false);
+                    GameObjectToolSupport.ApplyGameObjectMutations(gameObject, null, plan.Active, plan.TagValue, plan.LayerValue,
+                        item.X, item.Y, item.Z, item.RotationX, item.RotationY, item.RotationZ, item.ScaleX, item.ScaleY, item.ScaleZ);
+                    ApplyLocalTransforms(gameObject.transform, item);
+                    UnityCliSceneMutation.RegisterCreatedObject(gameObject, "go.create");
+                    UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+                    instanceIds.Add(gameObject.GetInstanceID());
+                }
+            }
+            finally
+            {
+                UnityCliSceneMutation.EndUndoGroup(undoGroup);
+            }
+
+            var observed = Prove(plan, instanceIds);
+            var parentPath = plan.Parent == null ? null : GameObjectToolSupport.HierarchyPath(plan.Parent.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Count = observed.Count,
+                GameObject = observed[0],
+                GameObjects = observed,
+                PlannedEffects = new List<PlannedEffect>
+                {
+                    new PlannedEffect { Type = "go.create", Count = observed.Count, Parent = parentPath, Target = parentPath ?? "<scene-root>" }
+                }
+            });
+        }
+
+        /// <summary>冻结 count、parent、primitive、每个名称与 transform；任一非法项都在 effect 前终止。</summary>
+        private static CreatePlan Prepare(Request request)
+        {
+            var count = request.Count ?? 1;
+            if (count < 1 || count > MaxBatchCount)
+                throw Error("E_GO_BATCH_COUNT_INVALID", "go.create count must be between 1 and " + MaxBatchCount + ".", "count", count);
+            ValidateVectorArray(request.Positions, count, "positions");
+            ValidateVectorArray(request.Rotations, count, "rotations");
+            ValidateVectorArray(request.Scales, count, "scales");
+            RejectTransformConflict(request.Positions, "positions", request.X, request.Y, request.Z);
+            RejectTransformConflict(request.Rotations, "rotations", request.RotationX, request.RotationY, request.RotationZ);
+            RejectTransformConflict(request.Scales, "scales", request.ScaleX, request.ScaleY, request.ScaleZ);
+            if (count > 1 && HasScalarTransform(request))
+                throw Error("E_GO_BATCH_TRANSFORM_CONFLICT", "Scalar transform fields are available only when count is 1; use positions, rotations, or scales for a batch.", "count", count);
+
+            GameObjectToolSupport.ValidateMutationInputs(request.TagValue, request.LayerValue);
+            var parent = string.IsNullOrEmpty(request.Parent)
+                ? null
+                : GameObjectToolSupport.ResolveUniqueTarget(request.Parent, "Parent GameObject is required.").transform;
+            var primitive = string.IsNullOrEmpty(request.Primitive)
+                ? (PrimitiveType?)null
+                : GameObjectToolSupport.ParsePrimitiveType(request.Primitive);
+            var baseName = request.Name ?? request.Target ?? "GameObject";
+            if (string.IsNullOrWhiteSpace(baseName))
+                throw Error("E_GO_CREATE_NAME_INVALID", "go.create name must not be empty or whitespace.", "name", null);
+
+            var items = new List<CreateItemPlan>(count);
+            for (var index = 0; index < count; index++)
+            {
+                var item = new CreateItemPlan
+                {
+                    Name = count > 1 ? baseName + (index + 1) : baseName,
+                    X = request.Positions == null ? request.X : null,
+                    Y = request.Positions == null ? request.Y : null,
+                    Z = request.Positions == null ? request.Z : null,
+                    RotationX = request.Rotations == null ? request.RotationX : null,
+                    RotationY = request.Rotations == null ? request.RotationY : null,
+                    RotationZ = request.Rotations == null ? request.RotationZ : null,
+                    ScaleX = request.Scales == null ? request.ScaleX : null,
+                    ScaleY = request.Scales == null ? request.ScaleY : null,
+                    ScaleZ = request.Scales == null ? request.ScaleZ : null,
+                    LocalPosition = request.Positions == null ? null : request.Positions[index],
+                    LocalRotation = request.Rotations == null ? null : request.Rotations[index],
+                    LocalScale = request.Scales == null ? null : request.Scales[index]
+                };
+                GameObjectToolSupport.ValidateTransformMutationValues(
+                    item.LocalPosition == null ? item.X : item.LocalPosition[0],
+                    item.LocalPosition == null ? item.Y : item.LocalPosition[1],
+                    item.LocalPosition == null ? item.Z : item.LocalPosition[2],
+                    item.LocalRotation == null ? item.RotationX : item.LocalRotation[0],
+                    item.LocalRotation == null ? item.RotationY : item.LocalRotation[1],
+                    item.LocalRotation == null ? item.RotationZ : item.LocalRotation[2],
+                    item.LocalScale == null ? item.ScaleX : item.LocalScale[0],
+                    item.LocalScale == null ? item.ScaleY : item.LocalScale[1],
+                    item.LocalScale == null ? item.ScaleZ : item.LocalScale[2]);
+                items.Add(item);
+            }
+            return new CreatePlan
+            {
+                Count = count,
+                Parent = parent,
+                Primitive = primitive,
+                Active = request.Active,
+                TagValue = request.TagValue,
+                LayerValue = request.LayerValue,
+                Items = items
+            };
+        }
+
+        private static void ValidateVectorArray(List<List<double>> values, int count, string field)
+        {
+            if (values == null) return;
+            if (values.Count != count)
+                throw Error("E_GO_BATCH_LENGTH_MISMATCH", field + " must contain exactly count vectors.", field, values.Count);
+            for (var index = 0; index < values.Count; index++)
+            {
+                if (values[index] == null || values[index].Count != 3)
+                    throw Error("E_GO_BATCH_VECTOR_INVALID", field + "[" + index + "] must be an [x,y,z] vector.", field + "[" + index + "]", values[index] == null ? null : (object)values[index].Count);
+            }
+        }
+
+        private static void RejectTransformConflict(List<List<double>> vectors, string field, double? x, double? y, double? z)
+        {
+            if (vectors != null && (x.HasValue || y.HasValue || z.HasValue))
+                throw Error("E_GO_BATCH_TRANSFORM_CONFLICT", field + " cannot be combined with its scalar transform fields.", field, null);
+        }
+
+        private static bool HasScalarTransform(Request request)
+        {
+            return request.X.HasValue || request.Y.HasValue || request.Z.HasValue
+                || request.RotationX.HasValue || request.RotationY.HasValue || request.RotationZ.HasValue
+                || request.ScaleX.HasValue || request.ScaleY.HasValue || request.ScaleZ.HasValue;
+        }
+
+        private static void ApplyLocalTransforms(Transform transform, CreateItemPlan item)
+        {
+            if (item.LocalPosition != null) transform.localPosition = Vector(item.LocalPosition);
+            if (item.LocalRotation != null) transform.localEulerAngles = Vector(item.LocalRotation);
+            if (item.LocalScale != null) transform.localScale = Vector(item.LocalScale);
+        }
+
+        /// <summary>effect 后只按冻结 instance id 顺序重取对象，并验证 identity、parent 与全部请求状态。</summary>
+        private static List<GameObjectDetail> Prove(CreatePlan plan, List<int> instanceIds)
+        {
+            if (instanceIds.Count != plan.Count)
+                throw Error("E_GO_CREATE_SET_MISMATCH", "go.create did not produce the requested object count.", "count", instanceIds.Count);
+            var uniqueIds = new HashSet<int>();
+            var result = new List<GameObjectDetail>(plan.Count);
+            for (var index = 0; index < instanceIds.Count; index++)
+            {
+                if (!uniqueIds.Add(instanceIds[index]))
+                    throw Error("E_GO_CREATE_SET_MISMATCH", "go.create returned a duplicate object identity.", "instanceId", instanceIds[index]);
+                var observed = EditorUtility.InstanceIDToObject(instanceIds[index]) as GameObject;
+                var expected = plan.Items[index];
+                if (observed == null || !observed.scene.IsValid() || !observed.scene.isLoaded
+                    || observed.name != expected.Name || observed.transform.parent != plan.Parent
+                    || (plan.Active.HasValue && observed.activeSelf != plan.Active.Value)
+                    || (!string.IsNullOrEmpty(plan.TagValue) && observed.tag != plan.TagValue)
+                    || (!string.IsNullOrEmpty(plan.LayerValue) && observed.layer != GameObjectToolSupport.ParseLayer(plan.LayerValue))
+                    || !TransformMatches(observed.transform, expected))
+                    throw Error("E_GO_CREATE_SET_MISMATCH", "A created GameObject did not match the frozen batch plan.", "index", index);
+                result.Add(GameObjectToolSupport.BuildGameObjectDetail(observed));
+            }
+            return result;
+        }
+
+        private static bool TransformMatches(Transform transform, CreateItemPlan item)
+        {
+            if (item.LocalPosition != null && !Approximately(transform.localPosition, item.LocalPosition, false)) return false;
+            if (item.LocalRotation != null && !Approximately(transform.localEulerAngles, item.LocalRotation, true)) return false;
+            if (item.LocalScale != null && !Approximately(transform.localScale, item.LocalScale, false)) return false;
+            if (item.X.HasValue && !Approximately(transform.position.x, item.X.Value)) return false;
+            if (item.Y.HasValue && !Approximately(transform.position.y, item.Y.Value)) return false;
+            if (item.Z.HasValue && !Approximately(transform.position.z, item.Z.Value)) return false;
+            if (item.RotationX.HasValue && !AngleApproximately(transform.eulerAngles.x, item.RotationX.Value)) return false;
+            if (item.RotationY.HasValue && !AngleApproximately(transform.eulerAngles.y, item.RotationY.Value)) return false;
+            if (item.RotationZ.HasValue && !AngleApproximately(transform.eulerAngles.z, item.RotationZ.Value)) return false;
+            if (item.ScaleX.HasValue && !Approximately(transform.localScale.x, item.ScaleX.Value)) return false;
+            if (item.ScaleY.HasValue && !Approximately(transform.localScale.y, item.ScaleY.Value)) return false;
+            return !item.ScaleZ.HasValue || Approximately(transform.localScale.z, item.ScaleZ.Value);
+        }
+
+        private static bool Approximately(Vector3 actual, List<double> expected, bool angle)
+        {
+            return angle
+                ? AngleApproximately(actual.x, expected[0]) && AngleApproximately(actual.y, expected[1]) && AngleApproximately(actual.z, expected[2])
+                : Approximately(actual.x, expected[0]) && Approximately(actual.y, expected[1]) && Approximately(actual.z, expected[2]);
+        }
+
+        private static bool Approximately(float actual, double expected)
+        {
+            return Mathf.Abs(actual - (float)expected) <= 0.0001f;
+        }
+
+        private static bool AngleApproximately(float actual, double expected)
+        {
+            return Mathf.Abs(Mathf.DeltaAngle(actual, (float)expected)) <= 0.0001f;
+        }
+
+        private static Vector3 Vector(List<double> values)
+        {
+            return new Vector3((float)values[0], (float)values[1], (float)values[2]);
+        }
+
+        private static UnityCliBridge.BridgeCommandException Error(string code, string message, string field, object actual)
+        {
+            return new UnityCliBridge.BridgeCommandException(
+                code,
+                message,
+                new Dictionary<string, object> { { "field", field }, { "actual", actual } },
+                new[] { "Inspect tools describe go.create and submit one valid single-object or batch request." });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/go/delete.cs

@@ -0,0 +1,87 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// go.delete — 从场景删除单个 GameObject(递归删除子级)。支持 dryRun 预览。
+    /// </summary>
+    public class GameObjectDeleteTool : IUnityCliTool<GameObjectDeleteTool.Request, GameObjectDeleteTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool? DryRun { get; set; }
+            public GameObjectRef Deleted { get; set; }
+            public bool Destroyed { get; set; }
+            public List<GameObjectPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "go.delete",
+            Summary = "Delete one scene GameObject; EditMode stays dirty, and final PlayMode proof requires reading editor.state.",
+            Description = "Delete one GameObject from the current scene/session and recursively remove its children. Dry-run returns target with destroyed=false. Live execution returns deleted with destroyed=true only after the target no longer exists; Play Mode scene instances are destroyed synchronously before the command returns. In EditMode, deletion adds shared Undo history and intentionally leaves the scene dirty. If a task started from a clean scene and must discard all temporary in-memory changes without saving, finish business verification, delete the temporary object, then call scene.load once with the exact active scene path; do not probe or repeat editor.undo when pre-existing Undo history is unknown. When final PlayMode is a task requirement, read the editor.state Context after cleanup. Prefer hierarchy paths or instance ids when plain names may be ambiguous.",
+            Group = "go",
+            DestructiveHint = false,
+            SupportsDryRun = true,
+            SideEffects = new[] { "scene-modify", "undo-stack", "recursive-delete" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Dry-run deletion by hierarchy path", Input = new Request { Target = "TempRoot/GeneratedChild" }, Execution = new ToolExampleExecution { DryRun = true } },
+                new ToolExample { Description = "Delete the generated child", Input = new Request { Target = "TempRoot/GeneratedChild" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("go.delete");
+            if (string.IsNullOrEmpty(request.Target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject delete requires a target.", "Pass a GameObject name, hierarchy path or instance id.");
+            }
+            var gameObject = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "GameObject delete requires a target.");
+            var targetRef = GameObjectToolSupport.BuildGameObjectRef(gameObject);
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    DryRun = true,
+                    Destroyed = false,
+                    PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "go.delete", Target = targetRef.Path, SideEffects = "none" } }
+                });
+            }
+            var scene = gameObject.scene;
+            ctx.CommitEffect();
+            UnityCliSceneMutation.DestroyObject(gameObject);
+            if (gameObject != null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_GAMEOBJECT_DELETE_FAILED",
+                    "GameObject remained alive after synchronous deletion: " + targetRef.Path,
+                    new Dictionary<string, object>
+                    {
+                        { "target", targetRef.Path },
+                        { "instanceId", targetRef.Id }
+                    },
+                    new[] { "Run tools run go.inspect for the target and inspect the Unity Console before retrying." });
+            }
+            UnityCliSceneMutation.MarkSceneDirty(scene);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Deleted = targetRef,
+                Destroyed = true,
+                PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "go.delete", Target = targetRef.Path } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/go/duplicate.cs

@@ -0,0 +1,76 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// go.duplicate — 复制场景中的 GameObject,可指定新名称或父级。
+    /// </summary>
+    public class GameObjectDuplicateTool : IUnityCliTool<GameObjectDuplicateTool.Request, GameObjectDuplicateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Name { get; set; }
+            public string NewName { get; set; }
+            public string Parent { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public GameObjectDetail GameObject { get; set; }
+            public List<GameObjectPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "go.duplicate",
+            Summary = "Duplicate a GameObject in the active scene, optionally assigning a new name or parent.",
+            Description = "Duplicate a GameObject in the active scene, optionally assigning a new name or parent. Prefer hierarchy paths or instance ids for target and parent; returns the duplicate path/id so follow-up calls can avoid ambiguous names.",
+            Group = "go",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Duplicate by hierarchy path", Input = new Request { Target = "Player/Avatar", NewName = "Player Copy" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("go.duplicate");
+            if (string.IsNullOrEmpty(request.Target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject duplicate requires a target.", "Pass a GameObject name, hierarchy path or instance id.");
+            }
+            var source = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "GameObject duplicate requires a target.");
+            var parentTransform = string.IsNullOrEmpty(request.Parent) ? source.transform.parent : GameObjectToolSupport.ResolveUniqueTarget(request.Parent, "Parent GameObject is required.").transform;
+            var parentId = parentTransform == null ? 0 : parentTransform.gameObject.GetInstanceID();
+            var duplicateName = request.NewName ?? request.Name ?? (source.name + " Copy");
+            ctx.CommitEffect();
+            var duplicate = UnityEngine.Object.Instantiate(source);
+            UnityCliSceneMutation.RegisterCreatedObject(duplicate, "go.duplicate");
+            var duplicateId = duplicate.GetInstanceID();
+            duplicate.name = duplicateName;
+            duplicate.transform.SetParent(parentTransform, true);
+            duplicate.transform.SetSiblingIndex(source.transform.GetSiblingIndex() + 1);
+            UnityCliSceneMutation.MarkSceneDirty(duplicate.scene);
+            var observed = EditorUtility.InstanceIDToObject(duplicateId) as GameObject;
+            if (observed == null || observed.name != duplicateName || (observed.transform.parent == null ? 0 : observed.transform.parent.gameObject.GetInstanceID()) != parentId)
+                throw new UnityCliBridge.BridgeCommandException("E_GO_DUPLICATE_STATE_MISMATCH", "Duplicate did not satisfy the requested name or parent after creation.", "Inspect the scene hierarchy and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                GameObject = GameObjectToolSupport.BuildGameObjectDetail(observed),
+                PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "go.duplicate", Target = GameObjectToolSupport.HierarchyPath(observed) } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/go/find.cs

@@ -0,0 +1,152 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Linq;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// go.find — 按名称/标签/层/组件/层级路径/实例ID 搜索 GameObject,可选优先 Prefab Stage。
+    /// </summary>
+    public class GameObjectFindTool : IUnityCliTool<GameObjectFindTool.Request, GameObjectFindTool.Result>
+    {
+        public sealed class Request
+        {
+            public string SearchTerm { get; set; }
+            public string Query { get; set; }
+            public string Target { get; set; }
+            public string Name { get; set; }
+            public string Tag { get; set; }
+            public string Layer { get; set; }
+            public string Component { get; set; }
+            public string Path { get; set; }
+            public string Id { get; set; }
+            public string SearchMethod { get; set; }
+            public bool IncludeInactive { get; set; }
+            public bool PreferPrefabStage { get; set; }
+            public int? PageSize { get; set; }
+            public int? Cursor { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool PrefabStageOpen { get; set; }
+            public long MatchCount { get; set; }
+            public List<GoFindItem> Items { get; set; }
+            public GoPageInfo PageInfo { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "go.find",
+            Summary = "Search GameObjects by name, tag, layer, component, hierarchy path, or instance id; optionally prefer an open Prefab Stage.",
+            Description = "Search GameObjects by name, tag, layer, component, hierarchy path, or instance id. Results are lightweight and paged. Pass preferPrefabStage=true to first match inside an open Prefab Stage (prefabContentsRoot), then merge scene matches.",
+            Group = "go",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Find by name", Input = new Request { SearchTerm = "Player", SearchMethod = "by_name", PageSize = 25 } },
+                new ToolExample { Description = "Find objects with Camera component", Input = new Request { SearchTerm = "Camera", SearchMethod = "by_component", PageSize = 10 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var searchTerm = request.SearchTerm ?? request.Query ?? request.Target ?? request.Name ?? request.Tag ?? request.Layer ?? request.Component ?? request.Path ?? request.Id;
+            if (string.IsNullOrEmpty(searchTerm))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject find requires a search term.", "Pass --input '{\"searchTerm\":\"Player\",\"searchMethod\":\"by_name\"}'.");
+            }
+            var searchMethod = request.SearchMethod ?? InferSearchMethod(request);
+            var includeInactive = request.IncludeInactive;
+            var preferPrefabStage = request.PreferPrefabStage;
+            var pageSize = Math.Max(1, Math.Min(request.PageSize ?? 50, 500));
+            var cursor = Math.Max(0, request.Cursor ?? 0);
+
+            // Prefab Stage 优先:preferPrefabStage=true 且有打开的 Prefab Stage 时,先在 prefab 内容里匹配,再合并场景匹配
+            var prefabStage = UnityEditor.SceneManagement.PrefabStageUtility.GetCurrentPrefabStage();
+            var prefabStageMatches = new List<GameObject>();
+            var prefabStageOpen = preferPrefabStage && prefabStage != null && prefabStage.prefabContentsRoot != null;
+            if (prefabStageOpen)
+            {
+                foreach (var t in prefabStage.prefabContentsRoot.GetComponentsInChildren<Transform>(includeInactive))
+                {
+                    if (MatchesGameObject(t.gameObject, searchMethod, searchTerm)) prefabStageMatches.Add(t.gameObject);
+                }
+            }
+            var sceneMatches = SearchGameObjects(searchMethod, searchTerm, includeInactive);
+            var matches = prefabStageOpen ? prefabStageMatches.Concat(sceneMatches).ToList() : sceneMatches;
+            var total = matches.Count;
+            var page = matches.Skip(cursor).Take(pageSize).ToList();
+            long? nextCursor = cursor + page.Count < total ? (long?)(cursor + page.Count) : null;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                PrefabStageOpen = prefabStageOpen,
+                MatchCount = total,
+                Items = page.ConvertAll(BuildItem),
+                PageInfo = new GoPageInfo { PageSize = pageSize, Cursor = cursor, NextCursor = nextCursor, Total = total }
+            });
+        }
+
+        private static string InferSearchMethod(Request request)
+        {
+            if (!string.IsNullOrEmpty(request.Tag)) return "by_tag";
+            if (!string.IsNullOrEmpty(request.Layer)) return "by_layer";
+            if (!string.IsNullOrEmpty(request.Component)) return "by_component";
+            if (!string.IsNullOrEmpty(request.Path)) return "by_path";
+            if (!string.IsNullOrEmpty(request.Id)) return "by_id";
+            return "by_name";
+        }
+
+        private static List<GameObject> SearchGameObjects(string searchMethod, string searchTerm, bool includeInactive)
+        {
+            var allObjects = UnityEngine.Object.FindObjectsOfType<GameObject>(includeInactive)
+                .OrderBy(GameObjectToolSupport.HierarchyPath, StringComparer.Ordinal).ToList();
+            return allObjects.Where(go => MatchesGameObject(go, searchMethod, searchTerm)).ToList();
+        }
+
+        private static bool MatchesGameObject(GameObject gameObject, string searchMethod, string searchTerm)
+        {
+            var normalized = (searchMethod ?? "by_name").Trim().ToLowerInvariant();
+            if (normalized == "by_id") return gameObject.GetInstanceID().ToString(CultureInfo.InvariantCulture) == searchTerm;
+            if (normalized == "by_path") return string.Equals(GameObjectToolSupport.HierarchyPath(gameObject), searchTerm, StringComparison.Ordinal);
+            if (normalized == "by_tag") return string.Equals(gameObject.tag, searchTerm, StringComparison.Ordinal);
+            if (normalized == "by_layer") return gameObject.layer == GameObjectToolSupport.ParseLayer(searchTerm);
+            if (normalized == "by_component") { var type = GameObjectToolSupport.ResolveComponentType(searchTerm); return type != null && gameObject.GetComponent(type) != null; }
+            if (normalized != "by_name") throw new UnityCliBridge.BridgeCommandException("E_SEARCH_METHOD_INVALID", "Unsupported GameObject searchMethod: " + searchMethod, "Use by_name, by_tag, by_layer, by_component, by_path, or by_id.");
+            return string.Equals(gameObject.name, searchTerm, StringComparison.Ordinal);
+        }
+
+        private static GoFindItem BuildItem(GameObject gameObject)
+        {
+            var componentNames = new List<string>();
+            foreach (var component in gameObject.GetComponents<Component>())
+            {
+                componentNames.Add(component != null ? component.GetType().Name : "MissingScript");
+            }
+            return new GoFindItem
+            {
+                Id = gameObject.GetInstanceID(),
+                Name = gameObject.name,
+                Path = GameObjectToolSupport.HierarchyPath(gameObject),
+                Active = gameObject.activeSelf,
+                ActiveInHierarchy = gameObject.activeInHierarchy,
+                Tag = gameObject.tag,
+                Layer = gameObject.layer,
+                ChildCount = gameObject.transform.childCount,
+                ChildrenTruncated = gameObject.transform.childCount > 0,
+                ComponentCount = componentNames.Count,
+                ComponentTypes = componentNames,
+                Components = componentNames
+            };
+        }
+    }
+}
+#endif