@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/scene/gameobject/component.cs

@@ -0,0 +1,63 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>scene.gameobject.component 只读 Tool：只读一个组件预览。</summary>
+        public sealed class SceneGameObjectComponentTool : IUnityCliTool<SceneGameObjectComponentTool.Request, SceneGameObjectComponentTool.Result>
+        {
+            public sealed class Request { public string Target { get; set; } public int Id { get; set; } public string Path { get; set; } public string Component { get; set; } }
+            public sealed class Result { public GameObjectRef GameObject { get; set; } public ComponentInfo Component { get; set; } }
+            public sealed class GameObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } }
+            public sealed class ComponentInfo
+            {
+                public string Type { get; set; } public string FullName { get; set; } public bool Enabled { get; set; }
+                [UnityCliAnyJson] public object Properties { get; set; }
+            }
+
+            // 返回只读 Tool 的发现元数据。
+            public ToolDescriptor Describe() => new()
+            {
+                Name = "scene.gameobject.component", Summary = "Read one component preview attached to a GameObject by component type name.",
+                Description = "Lightweight preview of one component attached to a GameObject. Use scene.gameobject.components first when unsure which component name exists. Does not replace deep reads; use component.get for complete fields/props.",
+                DestructiveHint = false,
+                Group = "scene", Target = "editor", PlayModeSupport = "supported",
+                Examples = new[] { new ToolExample { Description = "Read a Camera component preview", Input = new Request { Target = "Main Camera", Component = "Camera" } } }
+            };
+
+            /// <summary>供内部 completion observer 解析 GameObject/Component identity，缺失组件在 effect 前拒绝。</summary>
+            internal UnityCliProofResourceClaim ResolveProofResource(Request request)
+            {
+                request = request ?? new Request();
+                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path);
+                if (string.IsNullOrEmpty(request.Component))
+                    throw new BridgeCommandException("E_COMPONENT_TYPE_REQUIRED", "scene.gameobject.component requires component.", "Pass input component with a Unity component type name.");
+                var component = ResolveComponent(gameObject, request.Component);
+                if (component == null)
+                    throw new BridgeCommandException("E_COMPONENT_NOT_FOUND", "Component not found on target: " + request.Component, "Read scene.gameobject.components before constructing completionProbe.");
+                return SceneProofResource(gameObject, component);
+            }
+
+            /// <summary>读取指定组件及公开属性，不调用任何写入 API。</summary>
+            public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+            {
+                request = request ?? new Request();
+                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path);
+                if (string.IsNullOrEmpty(request.Component))
+                    throw new BridgeCommandException("E_COMPONENT_TYPE_REQUIRED", "scene.gameobject.component requires component.", "Pass input component with a Unity component type name.");
+                var component = ResolveComponent(gameObject, request.Component);
+                if (component == null)
+                    throw new BridgeCommandException("E_COMPONENT_NOT_FOUND", "Component not found on target: " + request.Component, "Run tools run scene.gameobject.components with the same target/path/id to list available component names.");
+                var result = new Result
+                {
+                    GameObject = new GameObjectRef { Id = gameObject.GetInstanceID(), Name = gameObject.name, Path = HierarchyPath(gameObject) },
+                    Component = new ComponentInfo { Type = component.GetType().Name, FullName = component.GetType().FullName, Enabled = ComponentEnabled(component), Properties = SceneContextComponentReadableProperties(component) }
+                };
+                return new System.Threading.Tasks.ValueTask<Result>(result);
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/gameobject/components.cs

@@ -0,0 +1,77 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>
+        /// scene.gameobject.components 只读 Tool：读取目标 GameObject 的组件列表。
+        /// </summary>
+        public sealed class SceneGameObjectComponentsTool : IUnityCliTool<SceneGameObjectComponentsTool.Request, SceneGameObjectComponentsTool.Result>
+        {
+            public sealed class Request
+            {
+                public string Target { get; set; }
+                public int Id { get; set; }
+                public string Path { get; set; }
+                public bool IncludeProperties { get; set; } = true;
+            }
+
+            public sealed class Result
+            {
+                public GameObjectRef GameObject { get; set; }
+                public List<ComponentInfo> Components { get; set; }
+                public long Count { get; set; }
+            }
+
+            public sealed class GameObjectRef
+            {
+                public long Id { get; set; }
+                public string Name { get; set; }
+                public string Path { get; set; }
+            }
+
+            public sealed class ComponentInfo
+            {
+                public string Type { get; set; }
+                public string FullName { get; set; }
+                public bool Enabled { get; set; }
+                [UnityCliAnyJson] public object Properties { get; set; }
+            }
+
+            public ToolDescriptor Describe() => new()
+            {
+                Name = "scene.gameobject.components",
+                Summary = "List components attached to one GameObject, optionally including readable property previews.",
+                Description = "Lightweight list of components attached to a GameObject: type names, enabled state, and optional readable property preview. Use this before component.get/component.modify to choose component name or index. Does not return every serialized field; use component.get for deep component data.",
+                DestructiveHint = false,
+                Group = "scene",
+                Target = "editor",
+                PlayModeSupport = "supported",
+                Examples = new[] { new ToolExample { Description = "List components on the main camera", Input = new Request { Target = "Main Camera", IncludeProperties = true } }, new ToolExample { Description = "List component names only", Input = new Request { Target = "Main Camera", IncludeProperties = false } } }
+            };
+
+            /// <summary>解析目标并直接构造组件列表 DTO，不经过 JSON 字符串。</summary>
+            public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+            {
+                var id = request.Id == 0 ? (int?)null : request.Id;
+                var gameObject = ResolveSceneContextGameObject(request.Target, id, request.Path);
+                var components = SceneContextComponentDetails(gameObject, request.IncludeProperties);
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    GameObject = new GameObjectRef
+                    {
+                        Id = gameObject.GetInstanceID(),
+                        Name = gameObject.name,
+                        Path = HierarchyPath(gameObject)
+                    },
+                    Components = components,
+                    Count = components.Count
+                });
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/gameobject-support.cs

@@ -0,0 +1,101 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        // 按 id、path、target 顺序解析场景对象；只读层级，不修改 Selection。
+        private static GameObject ResolveSceneContextGameObject(string target, int? id, string path)
+        {
+            GameObject gameObject = null;
+            if (id.HasValue) gameObject = EditorUtility.InstanceIDToObject(id.Value) as GameObject;
+            else if (!string.IsNullOrEmpty(path)) gameObject = GameObject.Find(path);
+            else if (!string.IsNullOrEmpty(target))
+            {
+                var resolution = ResolveGameObjectTarget(target);
+                if (resolution.Matches.Count == 1) gameObject = resolution.Target;
+                else if (resolution.Matches.Count > 1)
+                {
+                    throw new BridgeCommandException("E_TARGET_AMBIGUOUS", "Multiple GameObjects matched context target: " + target, "Pass a hierarchy path or instance id for disambiguation.");
+                }
+            }
+            if (gameObject == null)
+            {
+                throw new BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject context target not found.", "Pass input target, path, or id. Use a scene context such as scene.cameras to discover reusable scene object references.");
+            }
+            return gameObject;
+        }
+
+        /// <summary>构造同 session 内稳定的场景资源 claim；GlobalObjectId 不可用时绑定 scene handle 与 instance id。</summary>
+        private static UnityCliProofResourceClaim SceneProofResource(GameObject gameObject, Component component = null)
+        {
+            if (gameObject == null || !gameObject.scene.IsValid())
+                throw new BridgeCommandException("E_COMPLETION_PROBE_RESOURCE_INVALID", "completionProbe requires a live scene GameObject resource.", "Pass scene.gameobject read Tool input that resolves one scene object.");
+            var objectGlobalId = GlobalObjectId.GetGlobalObjectIdSlow(gameObject).ToString();
+            var objectIdentity = string.IsNullOrWhiteSpace(objectGlobalId)
+                ? "scene:" + gameObject.scene.handle.ToString(CultureInfo.InvariantCulture) + ":instance:" + gameObject.GetInstanceID().ToString(CultureInfo.InvariantCulture)
+                : objectGlobalId;
+            var observed = component == null ? (UnityEngine.Object)gameObject : component;
+            var observedGlobalId = GlobalObjectId.GetGlobalObjectIdSlow(observed).ToString();
+            var observedIdentity = string.IsNullOrWhiteSpace(observedGlobalId)
+                ? objectIdentity + ":instance:" + observed.GetInstanceID().ToString(CultureInfo.InvariantCulture)
+                : observedGlobalId;
+            return new UnityCliProofResourceClaim
+            {
+                ResourceKey = "scene-object:" + objectIdentity,
+                Identity = observedIdentity,
+                InstanceId = observed.GetInstanceID(),
+                SceneHandle = gameObject.scene.handle
+            };
+        }
+
+        // 读取单个组件的公开属性预览；getter 失败时跳过该属性。
+        private static Dictionary<string, object> SceneContextComponentReadableProperties(Component component)
+        {
+            var values = new Dictionary<string, object>();
+            foreach (var property in component.GetType().GetProperties(BindingFlags.Instance | BindingFlags.Public))
+            {
+                if (!property.CanRead || property.GetIndexParameters().Length > 0) continue;
+                try
+                {
+                    var value = property.GetValue(component, null);
+                    values[property.Name] = value == null ? null : Convert.ToString(value, CultureInfo.InvariantCulture);
+                }
+                catch
+                {
+                    // Unity getter 可能依赖不可用的内部状态，属性级失败不影响其余只读结果。
+                }
+            }
+            return values;
+        }
+
+        // 直接构造组件 DTO，避免读取路径出现序列化往返。
+        private static List<SceneGameObjectComponentsTool.ComponentInfo> SceneContextComponentDetails(GameObject gameObject, bool includeProperties)
+        {
+            var items = new List<SceneGameObjectComponentsTool.ComponentInfo>();
+            foreach (var component in gameObject.GetComponents<Component>())
+            {
+                if (component == null)
+                {
+                    items.Add(new SceneGameObjectComponentsTool.ComponentInfo { Type = "MissingScript", Enabled = false });
+                    continue;
+                }
+                items.Add(new SceneGameObjectComponentsTool.ComponentInfo
+                {
+                    Type = component.GetType().Name,
+                    FullName = component.GetType().FullName,
+                    Enabled = ComponentEnabled(component),
+                    Properties = includeProperties ? SceneContextComponentReadableProperties(component) : null
+                });
+            }
+            return items;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/gameobject.cs

@@ -0,0 +1,83 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public static partial class UnityCliBridge
+    {
+        /// <summary>scene.gameobject 只读 Tool：只读单个 GameObject 摘要。</summary>
+        public sealed class SceneGameObjectTool : IUnityCliTool<SceneGameObjectTool.Request, SceneGameObjectTool.Result>
+        {
+            public sealed class Request { public string Target { get; set; } public int Id { get; set; } public string Path { get; set; } public bool IncludeComponents { get; set; } = true; }
+            public sealed class Result { public GameObjectInfo GameObject { get; set; } }
+            public sealed class GameObjectInfo
+            {
+                public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } public bool Active { get; set; } public string Tag { get; set; } public long Layer { get; set; }
+                public TransformInfo Transform { get; set; } public List<ComponentInfo> Components { get; set; } public List<GameObjectRef> Children { get; set; }
+            }
+            public sealed class GameObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } }
+            public sealed class TransformInfo { public VectorInfo Position { get; set; } public VectorInfo Rotation { get; set; } public VectorInfo Scale { get; set; } }
+            public sealed class VectorInfo { public double X { get; set; } public double Y { get; set; } public double Z { get; set; } }
+            public sealed class ComponentInfo { public string Type { get; set; } public string FullName { get; set; } public bool Enabled { get; set; } }
+
+            // 返回只读 Tool 的发现元数据。
+            public ToolDescriptor Describe() => new()
+            {
+                Name = "scene.gameobject", Summary = "Read one GameObject summary by id, hierarchy path, or name without modifying the scene.",
+                Description = "Read one GameObject's lightweight scene summary by id, hierarchy path, or name. Use this before go.inspect, component.get, object.get-data, or mutation tools to confirm the stable path/id. Does not modify the scene; set includeComponents=false when only the reusable GameObject reference is needed.",
+                DestructiveHint = false,
+                Group = "scene", Target = "editor", PlayModeSupport = "supported",
+                Examples = new[] { new ToolExample { Description = "Read the main camera object", Input = new Request { Target = "Main Camera", IncludeComponents = true } }, new ToolExample { Description = "Read only the reusable object reference", Input = new Request { Target = "Main Camera", IncludeComponents = false } } }
+            };
+
+            /// <summary>供内部 completion observer 解析唯一场景对象 identity，不执行读取。</summary>
+            internal UnityCliProofResourceClaim ResolveProofResource(Request request)
+            {
+                request = request ?? new Request();
+                return SceneProofResource(ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path));
+            }
+
+            /// <summary>解析并读取场景对象；不修改场景或 Selection。</summary>
+            public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+            {
+                request = request ?? new Request();
+                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path);
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { GameObject = SceneGameObjectInfoFrom(gameObject, request.IncludeComponents) });
+            }
+        }
+
+        // 构造 GameObject DTO；includeComponents=false 时组件列表保持空集合。
+        private static SceneGameObjectTool.GameObjectInfo SceneGameObjectInfoFrom(GameObject gameObject, bool includeComponents)
+        {
+            var info = new SceneGameObjectTool.GameObjectInfo
+            {
+                Id = gameObject.GetInstanceID(), Name = gameObject.name, Path = HierarchyPath(gameObject), Active = gameObject.activeSelf, Tag = gameObject.tag, Layer = gameObject.layer,
+                Transform = new SceneGameObjectTool.TransformInfo
+                {
+                    Position = SceneVectorInfoFrom(gameObject.transform.position), Rotation = SceneVectorInfoFrom(gameObject.transform.eulerAngles), Scale = SceneVectorInfoFrom(gameObject.transform.localScale)
+                },
+                Components = new List<SceneGameObjectTool.ComponentInfo>(), Children = new List<SceneGameObjectTool.GameObjectRef>()
+            };
+            if (includeComponents)
+            {
+                foreach (var component in gameObject.GetComponents<Component>())
+                {
+                    info.Components.Add(new SceneGameObjectTool.ComponentInfo { Type = component == null ? "MissingScript" : component.GetType().Name, FullName = component == null ? null : component.GetType().FullName, Enabled = component != null && ComponentEnabled(component) });
+                }
+            }
+            foreach (Transform child in gameObject.transform)
+            {
+                info.Children.Add(new SceneGameObjectTool.GameObjectRef { Id = child.gameObject.GetInstanceID(), Name = child.gameObject.name, Path = HierarchyPath(child.gameObject) });
+            }
+            return info;
+        }
+
+        // 将 Vector3 转成场景对象协议 DTO。
+        private static SceneGameObjectTool.VectorInfo SceneVectorInfoFrom(Vector3 value)
+        {
+            return new SceneGameObjectTool.VectorInfo { X = value.x, Y = value.y, Z = value.z };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/hierarchy.cs

@@ -0,0 +1,250 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.hierarchy — 读取激活场景的轻量分页层级:parent/深度/名称过滤/组件预览。
+    /// </summary>
+    public class SceneHierarchyTool : IUnityCliTool<SceneHierarchyTool.Request, SceneHierarchyTool.Result>
+    {
+        public sealed class Request
+        {
+            public int? PageSize { get; set; }
+            public int? Cursor { get; set; }
+            public string Parent { get; set; }
+            public int? MaxDepth { get; set; }
+            public string Query { get; set; }
+            public string NameFilter { get; set; }
+            public string ComponentType { get; set; }
+            public bool IncludeComponents { get; set; }
+            public bool IncludeInactive { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SceneSummary Scene { get; set; }
+            public List<HierarchyItem> Items { get; set; }
+            public PageInfo PageInfo { get; set; }
+        }
+
+        public sealed class SceneSummary
+        {
+            public string Name { get; set; }
+            public string Path { get; set; }
+        }
+
+        public sealed class HierarchyItem
+        {
+            public long Id { get; set; }
+            public string Name { get; set; }
+            public string Path { get; set; }
+            public long Depth { get; set; }
+            public bool Active { get; set; }
+            public bool ActiveInHierarchy { get; set; }
+            public string Tag { get; set; }
+            public long Layer { get; set; }
+            public long ChildCount { get; set; }
+            public bool ChildrenTruncated { get; set; }
+            public long ComponentCount { get; set; }
+            public List<string> ComponentTypes { get; set; }
+            public List<string> Components { get; set; }
+        }
+
+        public sealed class PageInfo
+        {
+            public long Total { get; set; }
+            public long TotalCount { get; set; }
+            public long ReturnedCount { get; set; }
+            public long PageSize { get; set; }
+            public long Cursor { get; set; }
+            public long? NextCursor { get; set; }
+            public bool HasMore { get; set; }
+            public bool Truncated { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.hierarchy",
+            Summary = "Read a lightweight, paged hierarchy of active scene GameObjects.",
+            Description = "Read a lightweight, paged hierarchy of active scene GameObjects. Use parent to list a subtree, maxDepth to bound recursion, nameFilter/filter to narrow results, and includeComponents only when component previews are needed. For deep object or component fields, use go.inspect, object.get-data, or component.get after selecting a stable path/id.",
+            Group = "scene",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List a bounded hierarchy page", Input = new Request { PageSize = 25, MaxDepth = 1 } },
+                new ToolExample { Description = "Find camera nodes by component type", Input = new Request { ComponentType = "Camera", PageSize = 10 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var scene = SceneManager.GetActiveScene();
+            var parent = request.Parent;
+            var includeInactive = request.IncludeInactive;
+            var includeComponents = request.IncludeComponents;
+            var query = request.Query ?? request.NameFilter;
+            var componentType = request.ComponentType;
+            var maxDepth = Math.Max(0, Math.Min(request.MaxDepth ?? 1, 16));
+            var cursor = Math.Max(0, request.Cursor ?? 0);
+            var pageSize = Math.Max(1, Math.Min(request.PageSize ?? 50, 500));
+
+            var roots = new List<GameObject>();
+            if (!string.IsNullOrEmpty(parent))
+            {
+                var parentObject = SceneToolSupport.ResolveGameObjectByPath(parent);
+                if (parentObject == null)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_SCENE_HIERARCHY_PARENT_NOT_FOUND", "Parent GameObject not found: " + parent, "Run go.find or scene.hierarchy without parent, then pass a stable hierarchy path or instance id.");
+                }
+                for (var i = 0; i < parentObject.transform.childCount; i++)
+                {
+                    roots.Add(parentObject.transform.GetChild(i).gameObject);
+                }
+            }
+            else
+            {
+                roots.AddRange(scene.GetRootGameObjects());
+            }
+
+            var allItems = new List<HierarchyItem>();
+            foreach (var root in roots.OrderBy(g => HierarchyPath(g), StringComparer.Ordinal))
+            {
+                CollectHierarchy(root.transform, allItems, 0, maxDepth, query, includeInactive, includeComponents, componentType);
+            }
+
+            var total = allItems.Count;
+            var page = allItems.Skip(cursor).Take(pageSize).ToList();
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scene = new SceneSummary { Name = scene.name, Path = scene.path },
+                Items = page,
+                PageInfo = BuildPageInfo(pageSize, cursor, total, page.Count)
+            });
+        }
+
+        // 按深度/名称/inactive 策略收集层级项;分页在调用方统一处理。
+        private static void CollectHierarchy(Transform transform, List<HierarchyItem> items, int depth, int maxDepth, string query, bool includeInactive, bool includeComponents, string componentType)
+        {
+            var gameObject = transform.gameObject;
+            if (includeInactive || gameObject.activeInHierarchy)
+            {
+                if (TextMatches(query, gameObject.name, HierarchyPath(gameObject)) && ComponentMatches(gameObject, componentType))
+                {
+                    items.Add(BuildHierarchyItem(transform, depth, includeComponents));
+                }
+            }
+            if (depth >= maxDepth)
+            {
+                return;
+            }
+            foreach (Transform child in transform)
+            {
+                CollectHierarchy(child, items, depth + 1, maxDepth, query, includeInactive, includeComponents, componentType);
+            }
+        }
+
+        // 生成轻量 GameObject 层级项;componentTypes 始终返回,components 仅在 includeComponents 时返回。
+        private static HierarchyItem BuildHierarchyItem(Transform transform, int depth, bool includeComponents)
+        {
+            var componentNames = new List<string>();
+            foreach (var component in transform.GetComponents<Component>())
+            {
+                componentNames.Add(component != null ? component.GetType().Name : "MissingScript");
+            }
+            var gameObject = transform.gameObject;
+            var item = new HierarchyItem
+            {
+                Id = gameObject.GetInstanceID(),
+                Name = gameObject.name,
+                Path = HierarchyPath(gameObject),
+                Depth = depth,
+                Active = gameObject.activeSelf,
+                ActiveInHierarchy = gameObject.activeInHierarchy,
+                Tag = gameObject.tag,
+                Layer = gameObject.layer,
+                ChildCount = transform.childCount,
+                ChildrenTruncated = transform.childCount > 0,
+                ComponentCount = componentNames.Count,
+                ComponentTypes = componentNames
+            };
+            if (includeComponents)
+            {
+                item.Components = componentNames;
+            }
+            return item;
+        }
+
+        private static string HierarchyPath(GameObject gameObject)
+        {
+            var names = new Stack<string>();
+            var current = gameObject.transform;
+            while (current != null)
+            {
+                names.Push(current.name);
+                current = current.parent;
+            }
+            return string.Join("/", names.ToArray());
+        }
+
+        // 通用文本筛选;query 为空时视为匹配。
+        private static bool TextMatches(string query, params string[] values)
+        {
+            if (string.IsNullOrEmpty(query)) return true;
+            foreach (var value in values ?? new string[0])
+            {
+                if (!string.IsNullOrEmpty(value) && value.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0)
+                {
+                    return true;
+                }
+            }
+            return false;
+        }
+
+        // 判断 GameObject 是否拥有指定 Component 类型;空 componentType 表示不过滤(字符串匹配,不解析程序集)。
+        private static bool ComponentMatches(GameObject gameObject, string componentType)
+        {
+            if (gameObject == null || string.IsNullOrEmpty(componentType)) return true;
+            foreach (var component in gameObject.GetComponents<Component>())
+            {
+                if (ComponentTypeMatches(component, componentType)) return true;
+            }
+            return false;
+        }
+
+        private static bool ComponentTypeMatches(Component component, string componentType)
+        {
+            if (string.IsNullOrEmpty(componentType)) return true;
+            if (component == null) return string.Equals(componentType, "MissingScript", StringComparison.OrdinalIgnoreCase);
+            var type = component.GetType();
+            return string.Equals(type.Name, componentType, StringComparison.OrdinalIgnoreCase)
+                || string.Equals(type.FullName, componentType, StringComparison.OrdinalIgnoreCase)
+                || type.FullName.IndexOf(componentType, StringComparison.OrdinalIgnoreCase) >= 0;
+        }
+
+        private static PageInfo BuildPageInfo(int pageSize, int cursor, int totalCount, int returnedCount)
+        {
+            long? next = cursor + returnedCount < totalCount ? (long?)(cursor + returnedCount) : null;
+            return new PageInfo
+            {
+                Total = totalCount,
+                TotalCount = totalCount,
+                ReturnedCount = returnedCount,
+                PageSize = pageSize,
+                Cursor = cursor,
+                NextCursor = next,
+                HasMore = next != null,
+                Truncated = next != null
+            };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/list-opened.cs

@@ -0,0 +1,77 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.list-opened — 列出当前已加载(打开)场景:name/path/buildIndex/loaded/dirty/isActive。
+    /// </summary>
+    public class SceneListOpenedTool : IUnityCliTool<SceneListOpenedTool.Request, SceneListOpenedTool.Result>
+    {
+        public sealed class Request
+        {
+            // scene.list-opened 无入参
+        }
+
+        public sealed class Result
+        {
+            public List<OpenedScene> Scenes { get; set; }
+            public long Count { get; set; }
+            public string ActiveScene { get; set; }
+        }
+
+        public sealed class OpenedScene
+        {
+            public string Name { get; set; }
+            public string Path { get; set; }
+            public long BuildIndex { get; set; }
+            public bool IsLoaded { get; set; }
+            public bool IsDirty { get; set; }
+            public bool IsActive { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.list-opened",
+            Summary = "List currently loaded (opened) scenes with name, path, build index, loaded/dirty state and active flag.",
+            Description = "List currently loaded (opened) scenes with name, path, build index, loaded/dirty state and active flag. Read-only.",
+            Group = "scene",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List opened scenes", Input = new Request { } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var scenes = new List<OpenedScene>();
+            var active = SceneManager.GetActiveScene();
+            for (var i = 0; i < SceneManager.sceneCount; i++)
+            {
+                var scene = SceneManager.GetSceneAt(i);
+                scenes.Add(new OpenedScene
+                {
+                    Name = scene.name,
+                    Path = SceneToolSupport.NormalizeAssetPath(scene.path),
+                    BuildIndex = scene.buildIndex,
+                    IsLoaded = scene.isLoaded,
+                    IsDirty = scene.isDirty,
+                    IsActive = scene == active
+                });
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scenes = scenes,
+                Count = (long)SceneManager.sceneCount,
+                ActiveScene = active.name
+            });
+        }
+    }
+}
+#endif