@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/reflection/method/find.cs

@@ -0,0 +1,72 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Reflection;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// reflection.method.find — 查找类型的公开/私有/静态/实例方法。只读。
+    /// </summary>
+    public class ReflectionMethodFindTool : IUnityCliTool<ReflectionMethodFindTool.Request, ReflectionMethodFindTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string TypeName { get; set; }
+            public string MethodName { get; set; }
+            public bool IncludePrivate { get; set; }
+            public bool IncludeStatic { get; set; } = true;
+            public bool IncludeInstance { get; set; } = true;
+        }
+
+        public sealed class Result
+        {
+            public long Count { get; set; }
+            public List<UnityCliBridge.ReflectionMethodDescriptor> Methods { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "reflection.method.find",
+            Summary = "Find C# methods on a type by name; does not limit public/private/static/instance scope.",
+            Description = "Find methods on a live C# type. Does not limit public/private/static/instance scope. Use the returned signatures to construct reflection.method.call calls. Read-only.",
+            Group = "reflection",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Find Translate methods on Transform", Input = new Request { TypeName = "UnityEngine.Transform", MethodName = "Translate" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(request.TypeName))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TYPE_NAME_REQUIRED",
+                    "reflection.method.find requires typeName.",
+                    "Pass --input '{\"typeName\":\"UnityEngine.Transform\",\"methodName\":\"Translate\"}'.");
+            }
+
+            // 构建 BindingFlags:默认包含公开/非公开,按 includeStatic/includeInstance 调整
+            var bindings = BindingFlags.Public | BindingFlags.NonPublic;
+            if (request.IncludeStatic) bindings |= BindingFlags.Static;
+            if (request.IncludeInstance) bindings |= BindingFlags.Instance;
+            if (!request.IncludePrivate)
+            {
+                bindings = BindingFlags.Public | (request.IncludeStatic ? BindingFlags.Static : BindingFlags.Default) | (request.IncludeInstance ? BindingFlags.Instance : BindingFlags.Default);
+            }
+
+            var methods = UnityCliBridge.ReflectionInvoker.FindMethods(request.TypeName, request.MethodName, bindings);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Count = methods.Count,
+                Methods = methods
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/reflection/type/schema.cs

@@ -0,0 +1,56 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// type.schema — 为 live C# / Unity 类型生成带 $defs 的 JSON Schema。只读。
+    /// </summary>
+    public class TypeSchemaTool : IUnityCliTool<TypeSchemaTool.Request, TypeSchemaTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string TypeName { get; set; }
+            public int MaxDepth { get; set; } = 3;
+        }
+
+        public sealed class Result
+        {
+            [UnityCliAnyJson] public object Schema { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "type.schema",
+            Summary = "Generate a JSON Schema for a live C# type with $defs.",
+            Description = "Generate a JSON Schema (with $defs) for a live C# or Unity type. Read-only. Use the schema to understand the structure of objects before calling object.get-data or object.modify.",
+            Group = "reflection",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Get schema for Rigidbody", Input = new Request { TypeName = "UnityEngine.Rigidbody" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(request.TypeName))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TYPE_NAME_REQUIRED",
+                    "type.schema requires typeName.",
+                    "Pass --input '{\"typeName\":\"UnityEngine.Rigidbody\"}'.");
+            }
+            var schema = UnityCliBridge.TypeSchemaGenerator.Generate(request.TypeName, request.MaxDepth);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Schema = schema
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,181 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene 域 IUnityCliTool 共享的基础设施 helper:路径规范化、场景信息构造、
+    /// 资产目录创建、忙状态拦截、场景路径解析。仅供 scene 域自包含工具复用;
+    /// 不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    public static class SceneToolSupport
+    {
+        /// <summary>Wrapper for ObjectRefResolver.FindGameObjectByPath,供 scene 工具使用(ObjectRefResolver 是 internal nested)。</summary>
+        public static GameObject ResolveGameObjectByPath(string path)
+        {
+            return UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(path);
+        }
+
+        // 场景资产路径规范化:反斜杠转正斜杠并去首尾空白;空返回 null。
+        internal static string NormalizeAssetPath(string rawPath)
+        {
+            if (string.IsNullOrWhiteSpace(rawPath)) return null;
+            var path = rawPath.Replace('\\', '/').Trim();
+            if (path.Split('/').Contains(".") || path.Split('/').Contains(".."))
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_PATH_INVALID", "Scene paths must not contain '.' or '..' segments: " + path, "Pass a canonical Assets/*.unity path.");
+            return path;
+        }
+
+        // Unity 工程根目录(Assets 的父目录)。
+        internal static string ProjectRoot()
+        {
+            return Directory.GetParent(UnityEngine.Application.dataPath).FullName;
+        }
+
+        // Assets/ 相对路径转工程内绝对路径。
+        internal static string AssetFullPath(string assetPath)
+        {
+            var fullPath = Path.GetFullPath(Path.Combine(ProjectRoot(), assetPath.Replace('/', Path.DirectorySeparatorChar)));
+            var dataPath = Path.GetFullPath(UnityEngine.Application.dataPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+            if (!string.Equals(fullPath, dataPath, StringComparison.OrdinalIgnoreCase) && !fullPath.StartsWith(dataPath + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_PATH_INVALID", "Scene path resolves outside Application.dataPath: " + assetPath, "Pass a canonical Assets/*.unity path.");
+            return fullPath;
+        }
+
+        // 判断 Assets/ 路径是否存在(文件或已导入资产)。
+        internal static bool AssetExists(string assetPath)
+        {
+            return File.Exists(AssetFullPath(assetPath)) || !string.IsNullOrEmpty(AssetDatabase.AssetPathToGUID(assetPath));
+        }
+
+        // 确保资产目录存在,缺失则创建并刷新 AssetDatabase。
+        internal static void CreateAssetDirectory(string assetPath)
+        {
+            var directory = Path.GetDirectoryName(assetPath);
+            if (string.IsNullOrEmpty(directory) || AssetDatabase.IsValidFolder(directory.Replace('\\', '/')))
+            {
+                return;
+            }
+            Directory.CreateDirectory(Path.Combine(ProjectRoot(), directory.Replace('/', Path.DirectorySeparatorChar)));
+            AssetDatabase.Refresh();
+        }
+
+        // 拦截编译/导入/构建/PlayMode 过渡期的写入请求,避免脏状态写入。
+        // 不含 domainReloading 字段检查(该字段为 UnityCliBridge 私有,自包含工具不可见);
+        // isCompiling/isUpdating 已覆盖绝大多数不可写窗口。
+        internal static void EnsureEditorNotBusy(string command)
+        {
+            if (EditorApplication.isCompiling)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_COMPILING", "Unity Editor is compiling scripts.", "Wait for Unity to finish compiling and retry.", transient: true, retryAfterMs: 5000);
+            }
+            if (EditorApplication.isUpdating)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_IMPORTING", "Unity Editor is importing assets.", "Wait for Unity to finish importing and retry.", transient: true, retryAfterMs: 5000);
+            }
+            if (UnityCliBridge.IsPlayModeChanging())
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_PLAY_MODE", "Unity Editor is entering or exiting Play mode.", "Wait for Play mode transition to complete and retry.", transient: true, retryAfterMs: 3000);
+            }
+            if (BuildPipeline.isBuildingPlayer)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_BUSY", "Unity Editor is building the player.", "Wait for the build to complete and retry.", transient: true, retryAfterMs: 10000);
+            }
+        }
+
+        /// <summary>优先校验显式 path；仅给出 name 时按场景资产文件名精确解析，拒绝 0 个或多个匹配。</summary>
+        internal static string ResolveExistingScenePath(string path, string name)
+        {
+            if (!string.IsNullOrWhiteSpace(path)) return ResolveScenePath(path, true);
+
+            var normalizedName = NormalizeAssetPath(name);
+            if (string.IsNullOrEmpty(normalizedName)) return ResolveScenePath(null, true);
+            if (normalizedName.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase)) return ResolveScenePath(normalizedName, true);
+
+            var sceneName = Path.GetFileNameWithoutExtension(normalizedName);
+            var matches = new List<string>();
+            foreach (var guid in AssetDatabase.FindAssets("t:Scene"))
+            {
+                var candidate = NormalizeAssetPath(AssetDatabase.GUIDToAssetPath(guid));
+                if (!string.IsNullOrEmpty(candidate)
+                    && candidate.EndsWith(".unity", StringComparison.OrdinalIgnoreCase)
+                    && string.Equals(Path.GetFileNameWithoutExtension(candidate), sceneName, StringComparison.OrdinalIgnoreCase))
+                {
+                    matches.Add(candidate);
+                }
+            }
+            matches.Sort(StringComparer.OrdinalIgnoreCase);
+            if (matches.Count == 0)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_NOT_FOUND", "Scene asset name not found: " + normalizedName, "Run tools run asset.search --input '{\"filter\":\"t:Scene\"}' or pass an existing Assets/*.unity path.");
+            }
+            if (matches.Count > 1)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_AMBIGUOUS", "Multiple scene assets matched name " + normalizedName + ": " + string.Join(", ", matches.ToArray()), "Pass the exact Assets/*.unity path.");
+            }
+            return matches[0];
+        }
+
+        // 解析并校验 Assets/*.unity 场景路径;requireExisting=true 时还要求资产已存在。
+        internal static string ResolveScenePath(string pathOrName, bool requireExisting)
+        {
+            var path = NormalizeAssetPath(pathOrName);
+            if (string.IsNullOrEmpty(path))
+            {
+                if (requireExisting)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_SCENE_PATH_REQUIRED", "Pass an Assets/*.unity scene path.", "Use tools run scene.load --input '{\"path\":\"Assets/Scenes/Main.unity\"}'.");
+                }
+                return null;
+            }
+            if (!path.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase) || !path.EndsWith(".unity", StringComparison.OrdinalIgnoreCase))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_PATH_INVALID", "Scene path must be under Assets/ and end with .unity: " + path, "Pass a Unity scene asset path such as Assets/Scenes/Main.unity.");
+            }
+            if (requireExisting && !AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_NOT_FOUND", "Scene asset not found: " + path, "Run tools run asset.search --input '{\"filter\":\"t:Scene\"}' or pass an existing Assets/*.unity path.");
+            }
+            return path;
+        }
+
+        // 构造轻量场景信息(name/path/buildIndex/isLoaded/isDirty)。
+        internal static SceneInfo BuildSceneInfo(Scene scene)
+        {
+            return new SceneInfo
+            {
+                Name = scene.name,
+                Path = NormalizeAssetPath(scene.path),
+                BuildIndex = scene.buildIndex,
+                IsLoaded = scene.isLoaded,
+                IsDirty = scene.isDirty
+            };
+        }
+    }
+
+    /// <summary>场景摘要信息,scene 域工具 Result 共享。</summary>
+    public sealed class SceneInfo
+    {
+        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; }
+    }
+
+    /// <summary>计划副作用项,scene 域 mutation 工具 dryRun/成功结果共享。</summary>
+    public sealed class ScenePlannedEffect
+    {
+        public string Type { get; set; }
+        public string Path { get; set; }
+        public string Target { get; set; }
+        public string SideEffects { get; set; }
+    }
+}
+#endif

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

@@ -0,0 +1,62 @@
+#if UNITY_EDITOR
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.active — 返回当前激活场景的 name/path/buildIndex/isLoaded/isDirty。
+    /// </summary>
+    public class SceneActiveTool : IUnityCliTool<SceneActiveTool.Request, SceneActiveTool.Result>
+    {
+        public sealed class Request
+        {
+            // scene.active 无入参
+        }
+
+        public sealed class Result
+        {
+            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 ToolDescriptor Describe() => new()
+        {
+            Name = "scene.active",
+            Summary = "Return name, path and build index of the currently active scene.",
+            Description = "Return name, path and build index of the currently active scene. Read-only; use scene.list-opened for all loaded scenes and scene.set-active to change the active scene.",
+            Group = "scene",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Get the active scene", Input = new Request { } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var scene = SceneManager.GetActiveScene();
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Name = scene.name,
+                Path = NormalizeAssetPath(scene.path),
+                BuildIndex = scene.buildIndex,
+                IsLoaded = scene.isLoaded,
+                IsDirty = scene.isDirty
+            });
+        }
+
+        private static string NormalizeAssetPath(string path)
+        {
+            if (string.IsNullOrEmpty(path)) return path;
+            return path.Replace("\\", "/");
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/build-settings.cs

@@ -0,0 +1,69 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.build-settings — 列出 Editor Build Settings 中注册的场景(enabled 与路径)。
+    /// </summary>
+    public class SceneBuildSettingsTool : IUnityCliTool<SceneBuildSettingsTool.Request, SceneBuildSettingsTool.Result>
+    {
+        public sealed class Request
+        {
+            // scene.build-settings 无入参
+        }
+
+        public sealed class Result
+        {
+            public System.Collections.Generic.List<BuildSceneEntry> Scenes { get; set; }
+            public long Count { get; set; }
+        }
+
+        public sealed class BuildSceneEntry
+        {
+            public string Path { get; set; }
+            public bool Enabled { get; set; }
+            public long BuildIndex { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.build-settings",
+            Summary = "List scenes registered in the Editor Build Settings (enabled scenes and their paths).",
+            Description = "List scenes registered in the Editor Build Settings (enabled scenes and their paths). Read-only; use build.scene.add or build.scene.remove to change the build list.",
+            Group = "scene",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List build settings scenes", Input = new Request { } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var scenes = EditorBuildSettings.scenes ?? new EditorBuildSettingsScene[0];
+            var entries = new System.Collections.Generic.List<BuildSceneEntry>();
+            for (var index = 0; index < scenes.Length; index++)
+            {
+                var scene = scenes[index];
+                entries.Add(new BuildSceneEntry
+                {
+                    Path = SceneToolSupport.NormalizeAssetPath(scene.path),
+                    Enabled = scene.enabled,
+                    BuildIndex = (long)index
+                });
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scenes = entries,
+                Count = (long)scenes.Length
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,78 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.create — 在 Assets/*.unity 路径创建新空场景并可加载。拒绝覆盖已存在场景资产。
+    /// </summary>
+    public class SceneCreateTool : IUnityCliTool<SceneCreateTool.Request, SceneCreateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Name { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SceneInfo Scene { get; set; }
+            public string RequestedPath { get; set; }
+            public List<ScenePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.create",
+            Summary = "Create a new empty scene at an Assets/*.unity path and optionally load it.",
+            Description = "Create a new empty scene at an Assets/*.unity path and optionally load it. Refuses to overwrite an existing scene asset.",
+            Group = "scene",
+            DestructiveHint = true,
+            SideEffects = new[] { "scene-modify", "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a new scene", Input = new Request { Path = "Assets/Scenes/Main.unity" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            SceneToolSupport.EnsureEditorNotBusy("scene.create");
+            var path = SceneToolSupport.ResolveScenePath(request.Path ?? request.Name, false);
+            if (!string.IsNullOrEmpty(path) && File.Exists(SceneToolSupport.AssetFullPath(path)))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_OUTPUT_EXISTS", "Scene already exists: " + path, "Choose a different Assets/*.unity path or run scene load/save.");
+            }
+            ctx.CommitEffect();
+            var scene = EditorSceneManager.NewScene(NewSceneSetup.EmptyScene, NewSceneMode.Single);
+            if (!string.IsNullOrEmpty(path))
+            {
+                SceneToolSupport.CreateAssetDirectory(path);
+                if (!EditorSceneManager.SaveScene(scene, path))
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_SCENE_SAVE_FAILED", "Failed to save new scene: " + path, "Check destination path and Unity Console diagnostics.");
+                }
+            }
+            var observedScene = SceneManager.GetActiveScene();
+            if (!observedScene.IsValid() || !observedScene.isLoaded || (!string.IsNullOrEmpty(path) && observedScene.path != path))
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_CREATE_STATE_MISMATCH", "Created scene readback did not match the requested path.", "Inspect the active scene and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scene = SceneToolSupport.BuildSceneInfo(observedScene),
+                RequestedPath = path,
+                PlannedEffects = new List<ScenePlannedEffect>
+                {
+                    new ScenePlannedEffect { Type = "scene.create", Path = path }
+                }
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,125 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.data — 参数化 Scene 深读:maxDepth/nameFilter/includeComponents/maxResults。
+    /// </summary>
+    public class SceneDataTool : IUnityCliTool<SceneDataTool.Request, SceneDataTool.Result>
+    {
+        public sealed class Request
+        {
+            public int? MaxDepth { get; set; }
+            public int? MaxResults { get; set; }
+            public string NameFilter { get; set; }
+            public bool IncludeComponents { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SceneInfo Scene { get; set; }
+            public long Count { get; set; }
+            public List<DataItem> Items { get; set; }
+        }
+
+        public sealed class DataItem
+        {
+            public string Name { get; set; }
+            public string Path { get; set; }
+            public long Depth { get; set; }
+            public long ChildCount { get; set; }
+            public List<string> Components { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.data",
+            Summary = "Deep-read active scene hierarchy with maxDepth/nameFilter; prefer scene.hierarchy for paged navigation.",
+            Description = "Parameterized deep read of the active scene hierarchy: maxDepth, nameFilter, includeComponents, maxResults. Read-only; for paged lightweight state use scene.hierarchy or tools run scene.hierarchy.",
+            Group = "scene",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read scene data with filter", Input = new Request { NameFilter = "Camera", MaxDepth = 2 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var maxDepth = Math.Max(1, Math.Min(request.MaxDepth ?? 2, 6));
+            var maxResults = Math.Max(1, Math.Min(request.MaxResults ?? 200, 2000));
+            var nameFilter = request.NameFilter;
+            var includeComponents = request.IncludeComponents;
+            var scene = SceneManager.GetActiveScene();
+            var roots = scene.GetRootGameObjects();
+            var items = new List<DataItem>();
+            var count = 0;
+            foreach (var root in roots)
+            {
+                if (count >= maxResults) break;
+                CollectSceneData(root.transform, 0, maxDepth, nameFilter, includeComponents, items, ref count, maxResults);
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scene = SceneToolSupport.BuildSceneInfo(scene),
+                Count = count,
+                Items = items
+            });
+        }
+
+        // 递归收集场景节点摘要,受 maxDepth/maxResults/nameFilter 约束。
+        private static void CollectSceneData(Transform t, int depth, int maxDepth, string nameFilter, bool includeComponents, List<DataItem> items, ref int count, int maxResults)
+        {
+            if (count >= maxResults) return;
+            if (string.IsNullOrEmpty(nameFilter) || t.name.IndexOf(nameFilter, StringComparison.OrdinalIgnoreCase) >= 0)
+            {
+                var item = new DataItem
+                {
+                    Name = t.name,
+                    Path = TransformPath(t),
+                    Depth = depth,
+                    ChildCount = t.childCount
+                };
+                if (includeComponents)
+                {
+                    var componentNames = new List<string>();
+                    foreach (var c in t.GetComponents<Component>())
+                    {
+                        if (c != null) componentNames.Add(c.GetType().Name);
+                    }
+                    item.Components = componentNames;
+                }
+                items.Add(item);
+                count++;
+            }
+            if (depth < maxDepth)
+            {
+                for (var i = 0; i < t.childCount; i++)
+                {
+                    CollectSceneData(t.GetChild(i), depth + 1, maxDepth, nameFilter, includeComponents, items, ref count, maxResults);
+                }
+            }
+        }
+
+        private static string TransformPath(Transform t)
+        {
+            var path = t.name;
+            var p = t.parent;
+            while (p != null)
+            {
+                path = p.name + "/" + path;
+                p = p.parent;
+            }
+            return path;
+        }
+    }
+}
+#endif