@alpsckr/unitycli 0.4.2 → 0.4.4

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

@@ -2,15 +2,13 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
-using System.Linq;
+using UnityEditor;
 using UnityEngine;
 using UnityEngine.SceneManagement;
 
 namespace UnityCli
 {
-    /// <summary>
-    /// go.find — 按名称/标签/层/组件/层级路径/实例ID 搜索 GameObject,可选优先 Prefab Stage。
-    /// </summary>
+    /// <summary>go.find — exact selector 直达，其他 selector 按 raw hierarchy position 有界续页。</summary>
     public class GameObjectFindTool : IUnityCliTool<GameObjectFindTool.Request, GameObjectFindTool.Result>
     {
         public sealed class Request
@@ -24,26 +22,52 @@ namespace UnityCli
             public string Component { get; set; }
             public string Path { get; set; }
             public string Id { get; set; }
+            [UnityCliStringEnum("by_name", "by_tag", "by_layer", "by_component", "by_path", "by_id")]
             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; }
+            [UnityCliRange(1L, 500L)] public int? PageSize { get; set; }
+            public string Cursor { get; set; }
+            public UnityCliReadBudgetInput Budget { 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 long ReturnedCount { get; set; }
+            [UnityCliItemsRange(0, 500)] public List<Item> Items { get; set; }
+            public PageInfo PageInfo { get; set; }
+            public UnityCliRequestBudgetUsage Budget { get; set; }
+        }
+
+        public sealed class Item
+        {
+            public long Id { get; set; }
+            public string Name { get; set; }
+            public string Path { 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 sealed class PageInfo
+        {
+            public long PageSize { get; set; }
+            public string Cursor { get; set; }
+            public string NextCursor { get; set; }
+            public bool Complete { get; set; }
+            public bool Truncated { get; set; }
+            public string Generation { 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.",
+            Summary = "Resolve exact GameObject ids/paths directly or page filtered hierarchy matches from stable raw positions.",
+            Description = "Search loaded GameObjects by exact name, tag, layer or component. by_id uses direct instance resolution and by_path walks only the exact case-sensitive path; neither materializes the scene tree. Other selectors stream Unity hierarchy order with pageSize 1..500 (default 50). All work shares budget defaults of 10000 scans, 4096 nodes, 2048 getters, 4096 reflection calls, 250 main-thread ms and 1 MiB UTF-8; maxima are 100000/20000/10000/20000/2000 ms/8 MiB. No filtered total is fabricated: pageInfo.complete/truncated and nextCursor identify the next raw object. preferPrefabStage scans the open Prefab Stage first. Read-only in Edit and Play Mode.",
             Group = "go",
             DestructiveHint = false,
             Target = "editor",
@@ -52,47 +76,116 @@ namespace UnityCli
             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 } }
+                new ToolExample { Description = "Find an exact object name", Input = new Request { SearchTerm = "Player", SearchMethod = "by_name", PageSize = 25 } },
+                new ToolExample { Description = "Resolve a full hierarchy path directly", Input = new Request { SearchTerm = "World/Player", SearchMethod = "by_path" } }
             }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
+            request = request ?? new Request();
             var searchTerm = request.SearchTerm ?? request.Query ?? request.Target ?? request.Name ?? request.Tag ?? request.Layer ?? request.Component ?? request.Path ?? request.Id;
-            if (string.IsNullOrEmpty(searchTerm))
+            if (string.IsNullOrEmpty(searchTerm)) throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject find requires a search term.", "Pass searchTerm and one documented searchMethod.");
+            var method = request.SearchMethod ?? InferSearchMethod(request);
+            var budget = ctx.UseReadBudget(request.Budget);
+            var pageSize = request.PageSize ?? 50;
+            if ((method == "by_id" || method == "by_path") && !string.IsNullOrEmpty(request.Cursor))
+                throw new UnityCliBridge.BridgeCommandException("E_CONTINUATION_INVALID", "Exact by_id/by_path resolution does not accept cursor.", "Remove cursor for exact resolution.");
+
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var prefabStage = UnityEditor.SceneManagement.PrefabStageUtility.GetCurrentPrefabStage();
+            GameObject prefabRoot = null;
+            var prefabStageIdentity = string.Empty;
+            if (request.PreferPrefabStage && prefabStage != null)
             {
-                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject find requires a search term.", "Pass --input '{\"searchTerm\":\"Player\",\"searchMethod\":\"by_name\"}'.");
+                if (!budget.TryConsumeGetters(3)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                prefabRoot = prefabStage.prefabContentsRoot;
+                if (prefabRoot != null)
+                    prefabStageIdentity = prefabStage.scene.handle.ToString(CultureInfo.InvariantCulture) + "\0" + prefabStage.assetPath;
+            }
+            var prefabOpen = prefabRoot != null;
+            var generation = UnityCliContinuationToken.Fingerprint(
+                UnityCliReadGeneration.Hierarchy(SceneManager.GetActiveScene()) + "\0" + method + "\0" + searchTerm + "\0" + request.IncludeInactive
+                + "\0" + prefabOpen + "\0" + prefabStageIdentity);
+            if (method == "by_id" || method == "by_path")
+            {
+                var exact = ResolveExact(method, searchTerm, budget);
+                var exactItems = new List<Item>();
+                if (exact != null)
+                {
+                    if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    if (request.IncludeInactive || exact.activeInHierarchy) exactItems.Add(BuildItem(exact, budget));
+                }
+                return new System.Threading.Tasks.ValueTask<Result>(ResultPage(exactItems, pageSize, request.Cursor, null, generation, prefabOpen, budget));
             }
-            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)
+            Type componentType = null;
+            int? layer = null;
+            if (method == "by_component") componentType = GameObjectToolSupport.ResolveComponentType(searchTerm, budget);
+            if (method == "by_layer") layer = GameObjectToolSupport.ParseLayer(searchTerm);
+            var prefabTraversal = prefabOpen ? new UnityCliHierarchyPager.Traversal(prefabStage.scene, prefabRoot, int.MaxValue, budget) : null;
+            var sceneTraversal = new UnityCliHierarchyPager.LoadedSceneTraversal(budget, prefabOpen ? prefabStage.scene.handle : 0);
+            GameObject current;
+            var phase = prefabOpen ? "prefab" : "scene";
+            if (string.IsNullOrEmpty(request.Cursor)) current = prefabOpen ? prefabRoot : sceneTraversal.First(budget);
+            else
+            {
+                current = UnityCliHierarchyPager.ResolveCursor(request.Cursor, "go.find", generation, budget, out phase);
+                if (phase != "scene" && phase != "prefab") throw UnityCliHierarchyPager.Stale();
+                if (phase == "prefab" && (!prefabOpen || !IsDescendantOrSelf(current.transform, prefabRoot.transform, budget))) throw UnityCliHierarchyPager.Stale();
+                if (phase == "scene" && prefabOpen && current.scene.handle == prefabStage.scene.handle) throw UnityCliHierarchyPager.Stale();
+            }
+
+            var items = new List<Item>();
+            while (current != null && items.Count < pageSize)
             {
-                foreach (var t in prefabStage.prefabContentsRoot.GetComponentsInChildren<Transform>(includeInactive))
+                var candidate = current;
+                if (!budget.TryConsumeScannedRecord()) break;
+                try
+                {
+                    var nextPhase = phase;
+                    var next = phase == "prefab" ? prefabTraversal.Next(candidate, budget) : sceneTraversal.Next(candidate, budget);
+                    if (phase == "prefab" && next == null) { nextPhase = "scene"; next = sceneTraversal.First(budget); }
+                    if (Matches(candidate, method, searchTerm, request.IncludeInactive, componentType, layer, budget))
+                        items.Add(BuildItem(candidate, budget));
+                    phase = nextPhase;
+                    current = next;
+                }
+                catch (UnityCliRequestBudgetExceededException)
                 {
-                    if (MatchesGameObject(t.gameObject, searchMethod, searchTerm)) prefabStageMatches.Add(t.gameObject);
+                    current = candidate;
+                    break;
                 }
             }
-            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
+
+            if (items.Count == 0 && current != null) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension ?? "scannedRecords");
+            var nextCursor = UnityCliHierarchyPager.Cursor("go.find", generation, phase, current, budget);
+            return new System.Threading.Tasks.ValueTask<Result>(ResultPage(items, pageSize, request.Cursor, nextCursor, generation, prefabOpen, budget));
+        }
+
+        private static Result ResultPage(List<Item> items, int pageSize, string cursor, string nextCursor, string generation, bool prefabOpen, UnityCliRequestBudget budget)
+        {
+            return new Result
             {
-                PrefabStageOpen = prefabStageOpen,
-                MatchCount = total,
-                Items = page.ConvertAll(BuildItem),
-                PageInfo = new GoPageInfo { PageSize = pageSize, Cursor = cursor, NextCursor = nextCursor, Total = total }
-            });
+                PrefabStageOpen = prefabOpen,
+                ReturnedCount = items.Count,
+                Items = items,
+                PageInfo = new PageInfo
+                {
+                    PageSize = pageSize, Cursor = cursor, NextCursor = nextCursor,
+                    Complete = nextCursor == null, Truncated = nextCursor != null, Generation = generation
+                },
+                Budget = budget.Usage()
+            };
+        }
+
+        private static GameObject ResolveExact(string method, string value, UnityCliRequestBudget budget)
+        {
+            if (method == "by_path") return UnityCliBridge.ObjectRefResolver.FindGameObjectByExactPath(value, budget);
+            int instanceId;
+            if (!int.TryParse(value, NumberStyles.Integer, CultureInfo.InvariantCulture, out instanceId)) return null;
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return EditorUtility.InstanceIDToObject(instanceId) as GameObject;
         }
 
         private static string InferSearchMethod(Request request)
@@ -105,47 +198,51 @@ namespace UnityCli
             return "by_name";
         }
 
-        private static List<GameObject> SearchGameObjects(string searchMethod, string searchTerm, bool includeInactive)
+        private static bool Matches(GameObject gameObject, string method, string value, bool includeInactive, Type componentType, int? layer, UnityCliRequestBudget budget)
         {
-            var allObjects = UnityEngine.Object.FindObjectsOfType<GameObject>(includeInactive)
-                .OrderBy(GameObjectToolSupport.HierarchyPath, StringComparer.Ordinal).ToList();
-            return allObjects.Where(go => MatchesGameObject(go, searchMethod, searchTerm)).ToList();
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            if (!includeInactive && !gameObject.activeInHierarchy) return false;
+            if (method == "by_component")
+            {
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                return gameObject.GetComponent(componentType) != null;
+            }
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            if (method == "by_tag") return string.Equals(gameObject.tag, value, StringComparison.Ordinal);
+            if (method == "by_layer") return gameObject.layer == layer;
+            if (method != "by_name") throw new UnityCliBridge.BridgeCommandException("E_SEARCH_METHOD_INVALID", "Unsupported GameObject searchMethod: " + method, "Use by_name, by_tag, by_layer, by_component, by_path, or by_id.");
+            return string.Equals(gameObject.name, value, StringComparison.Ordinal);
         }
 
-        private static bool MatchesGameObject(GameObject gameObject, string searchMethod, string searchTerm)
+        private static Item BuildItem(GameObject gameObject, UnityCliRequestBudget budget)
         {
-            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);
+            if (!budget.TryConsumeNode() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var path = UnityCliHierarchyPager.Path(gameObject, budget);
+            var name = gameObject.name;
+            if (!budget.TryConsumeGetter() || !budget.TryConsumeGetter() || !budget.TryConsumeGetter()
+                || !budget.TryConsumeGetter() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var tag = gameObject.tag;
+            var childCount = gameObject.transform.childCount;
+            if (!budget.TryReserveSerializedUtf8(name) || !budget.TryReserveSerializedUtf8(path) || !budget.TryReserveSerializedUtf8(tag))
+                throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return new Item
+            {
+                Id = gameObject.GetInstanceID(), Name = name, Path = path,
+                Active = gameObject.activeSelf, ActiveInHierarchy = gameObject.activeInHierarchy,
+                Tag = tag, Layer = gameObject.layer,
+                ChildCount = childCount, ChildrenTruncated = childCount > 0
+            };
         }
 
-        private static GoFindItem BuildItem(GameObject gameObject)
+        private static bool IsDescendantOrSelf(Transform value, Transform root, UnityCliRequestBudget budget)
         {
-            var componentNames = new List<string>();
-            foreach (var component in gameObject.GetComponents<Component>())
+            while (value != null)
             {
-                componentNames.Add(component != null ? component.GetType().Name : "MissingScript");
+                if (value == root) return true;
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                value = value.parent;
             }
-            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
-            };
+            return false;
         }
     }
 }

package/unitypkg/Editor/Tools/graphics/GraphicsToolSupport.cs

@@ -2,6 +2,7 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
+using System.Linq;
 using System.Reflection;
 using System.Security.Cryptography;
 using UnityEditor;
@@ -181,6 +182,23 @@ namespace UnityCli
             return null;
         }
 
+        /// <summary>构造探针所属 GameObject 的 fresh identity。</summary>
+        public static GraphicsProbeTarget BuildProbeTarget(GameObject gameObject)
+        {
+            return new GraphicsProbeTarget
+            {
+                Id = gameObject.GetInstanceID(),
+                Name = gameObject.name,
+                Path = GameObjectToolSupport.HierarchyPath(gameObject)
+            };
+        }
+
+        /// <summary>将探针位置投影为 typed DTO，避免返回请求字符串。</summary>
+        public static List<Vector3Data> BuildProbePositions(IEnumerable<Vector3> positions)
+        {
+            return (positions ?? Enumerable.Empty<Vector3>()).Select(position => new Vector3Data(position)).ToList();
+        }
+
         /// <summary>构造 ReflectionProbe 摘要 DTO。</summary>
         public static ReflectionProbeInfo BuildReflectionProbeInfo(ReflectionProbe probe)
         {
@@ -326,6 +344,13 @@ namespace UnityCli
         public long GiWorkflowMode { get; set; }
     }
 
+    public sealed class GraphicsProbeTarget
+    {
+        public long Id { get; set; }
+        public string Name { get; set; }
+        public string Path { get; set; }
+    }
+
     public sealed class ReflectionProbeInfo
     {
         public string Mode { get; set; }

package/unitypkg/Editor/Tools/graphics/light-probe-group.cs

@@ -11,8 +11,8 @@ namespace UnityCli
     public class GraphicsLightProbeGroupTool : IUnityCliTool<GraphicsLightProbeGroupTool.Request, GraphicsLightProbeGroupTool.Result>
     {
         public sealed class Request { public string Target { get; set; } public bool? Create { get; set; } public string Positions { get; set; } }
-        public sealed class Result { public long ProbeCount { get; set; } public List<GraphicsPlannedEffect> PlannedEffects { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "graphics.light-probe-group", Summary = "Add, configure, or read a LightProbeGroup component on a target.", Description = "Resolve a target GameObject, optionally create a LightProbeGroup, and set probe positions from a space-separated vector array.", Group = "graphics",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read light probe group", Input = new Request { Target = "LightProbes" } } } };
+        public sealed class Result { public GraphicsProbeTarget Target { get; set; } public long ProbeCount { get; set; } public List<Vector3Data> Positions { get; set; } public List<GraphicsPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "graphics.light-probe-group", Summary = "Read, create, or set one LightProbeGroup's probe positions.", Description = "Dedicated LightProbeGroup Tool for Edit and Play mode. Resolve one target, set create=true to add the object/component when missing, and pass positions as space-separated x,y,z vectors to replace the array. Success re-resolves the component and returns fresh target identity, probe count, and positions.", Group = "graphics",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read light probe positions", Input = new Request { Target = "LightProbes" } }, new ToolExample { Description = "Set two light probe positions", Input = new Request { Target = "LightProbes", Positions = "0,0,0 0,2,0" } } } };
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
             var createdObject = string.IsNullOrEmpty(r.Target);
@@ -43,7 +43,13 @@ namespace UnityCli
             var observedProbe = observedObject.GetComponent<LightProbeGroup>();
             var observedPositions = observedProbe == null ? null : observedProbe.probePositions;
             if (observedProbe == null || (positions != null && !SamePositions(observedPositions, positions))) throw new UnityCliBridge.BridgeCommandException("E_LIGHT_PROBE_GROUP_STATE_MISMATCH", "LightProbeGroup probe positions did not retain the request.", "Retry after the editor is idle.");
-            return new System.Threading.Tasks.ValueTask<Result>(new Result { ProbeCount = observedPositions == null ? 0 : observedPositions.Length, PlannedEffects = effects });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Target = GraphicsToolSupport.BuildProbeTarget(observedObject),
+                ProbeCount = observedPositions == null ? 0 : observedPositions.Length,
+                Positions = GraphicsToolSupport.BuildProbePositions(observedPositions),
+                PlannedEffects = effects
+            });
         }
         private static bool SamePositions(Vector3[] actual, Vector3[] expected)
         {

package/unitypkg/Editor/Tools/graphics/pipeline-info.cs

@@ -12,7 +12,7 @@ namespace UnityCli
     {
         public sealed class Request { }
         public sealed class Result { public GraphicsSummary Graphics { get; set; } public QualitySettingsInfo QualitySettings { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "graphics.pipeline-info", Summary = "Read the active render pipeline asset and quality settings.", Description = "Read-only: returns render pipeline summary and current QualitySettings.", Group = "graphics",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read pipeline info", Input = new Request { } } } };
+        public ToolDescriptor Describe() => new() { Name = "graphics.pipeline-info", Summary = "Read active/default render pipeline identity and current quality settings.", Description = "Read-only in Edit and Play mode. Returns the active/default render pipeline identity plus current QualitySettings; use graphics.pipeline-settings for default pipeline writes and graphics.quality for quality writes.", Group = "graphics",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read pipeline info", Input = new Request { } } } };
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result { Graphics = GraphicsToolSupport.BuildGraphicsSummary(), QualitySettings = GraphicsToolSupport.BuildQualitySettings() });
     }
 }

package/unitypkg/Editor/Tools/graphics/pipeline-settings.cs

@@ -13,7 +13,7 @@ namespace UnityCli
     {
         public sealed class Request { public string RenderPipeline { get; set; } }
         public sealed class Result { public GraphicsSummary Graphics { get; set; } public List<GraphicsPlannedEffect> PlannedEffects { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "graphics.pipeline-settings", Summary = "Set the default render pipeline asset for the project.", Description = "Set GraphicsSettings.defaultRenderPipeline. Pass 'built-in' or 'null' to reset to built-in.", Group = "graphics",DestructiveHint = true, SideEffects = new[] { "settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set URP pipeline", Input = new Request { RenderPipeline = "Assets/Settings/URP.asset" } } } };
+        public ToolDescriptor Describe() => new() { Name = "graphics.pipeline-settings", Summary = "Read or set the project's default render pipeline asset.", Description = "Dedicated GraphicsSettings.defaultRenderPipeline reader/writer for Edit and Play mode. Omit renderPipeline for a pure read; pass one imported Assets/*.asset RenderPipelineAsset, or built-in/null to reset. Success re-resolves the asset by path and GUID before returning the fresh pipeline summary; QualitySettings belong to graphics.quality.", Group = "graphics",DestructiveHint = true, SideEffects = new[] { "settings-write", "asset-import", "session-affecting" }, Target = "editor", PlayModeSupport = "session-affecting", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set URP pipeline", Input = new Request { RenderPipeline = "Assets/Settings/URP.asset" } } } };
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
             var effects = new List<GraphicsPlannedEffect>();

package/unitypkg/Editor/Tools/graphics/quality.cs

@@ -37,9 +37,9 @@ namespace UnityCli
         public ToolDescriptor Describe() => new()
         {
             Name = "graphics.quality", Summary = "Read and update Unity QualitySettings (quality level, vSync, anti-aliasing, shadows, LOD).",
-            Description = "Read or update QualitySettings. Pass qualityLevel (name or index) and individual settings to update; omit all to read current values.",
+            Description = "Dedicated QualitySettings reader/writer for Edit and Play mode. Pass qualityLevel (name or index) and individual quality fields to update; omit every field for a pure read. Success returns a fresh QualitySettings snapshot and the applied effects; render-pipeline assignment belongs to graphics.pipeline-settings.",
             Group = "graphics",DestructiveHint = true, SideEffects = new[] { "settings-write" },
-            Target = "editor", PlayModeSupport = "editor-only",
+            Target = "editor", PlayModeSupport = "session-affecting",
             DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
             Examples = new[] { new ToolExample { Description = "Read quality settings", Input = new Request { } } }
         };

package/unitypkg/Editor/Tools/graphics/reflection-probe.cs

@@ -12,8 +12,8 @@ namespace UnityCli
     public class GraphicsReflectionProbeTool : IUnityCliTool<GraphicsReflectionProbeTool.Request, GraphicsReflectionProbeTool.Result>
     {
         public sealed class Request { public string Target { get; set; } public bool? Create { get; set; } public string Mode { get; set; } public int? Resolution { get; set; } public int? Bounces { get; set; } public bool? Hdr { get; set; } public string BoxSize { get; set; } public string BoxOffset { get; set; } }
-        public sealed class Result { public ReflectionProbeInfo Probe { get; set; } public List<GraphicsPlannedEffect> PlannedEffects { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "graphics.reflection-probe", Summary = "Add, configure, or read a ReflectionProbe component on a target.", Description = "Resolve a target GameObject, optionally create a ReflectionProbe, and configure mode/resolution/bounces/hdr/boxSize/boxOffset.", Group = "graphics",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read reflection probe", Input = new Request { Target = "ReflectionProbe" } } } };
+        public sealed class Result { public GraphicsProbeTarget Target { get; set; } public ReflectionProbeInfo Probe { get; set; } public List<GraphicsPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "graphics.reflection-probe", Summary = "Read, create, or configure one ReflectionProbe component.", Description = "Dedicated ReflectionProbe Tool for Edit and Play mode. Resolve one target, set create=true to add the object/component when missing, and configure mode, resolution, bounces, hdr, boxSize, or boxOffset. Success re-resolves the component and returns fresh target identity and probe state.", Group = "graphics",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read reflection probe", Input = new Request { Target = "ReflectionProbe" } } } };
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
             var createdObject = string.IsNullOrEmpty(r.Target);
@@ -58,7 +58,7 @@ namespace UnityCli
             if (observedProbe == null) throw new UnityCliBridge.BridgeCommandException("E_REFLECTION_PROBE_STATE_MISMATCH", "ReflectionProbe could not be read after mutation.", "Retry after the editor is idle.");
             var observed = GraphicsToolSupport.BuildReflectionProbeInfo(observedProbe);
             if ((hasMode && observedProbe.mode != mode) || (r.Resolution.HasValue && observedProbe.resolution != r.Resolution.Value) || (r.Bounces.HasValue && observed.Bounces != r.Bounces.Value) || (r.Hdr.HasValue && observedProbe.hdr != r.Hdr.Value) || (boxSize.HasValue && observedProbe.size != boxSize.Value) || (boxOffset.HasValue && observedProbe.center != boxOffset.Value)) throw new UnityCliBridge.BridgeCommandException("E_REFLECTION_PROBE_STATE_MISMATCH", "ReflectionProbe readback did not match the request.", "Retry after the editor is idle.");
-            return new System.Threading.Tasks.ValueTask<Result>(new Result { Probe = observed, PlannedEffects = effects });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Target = GraphicsToolSupport.BuildProbeTarget(observedObject), Probe = observed, PlannedEffects = effects });
         }
         private static void SetBounces(ReflectionProbe p, int v)
         {

package/unitypkg/Editor/Tools/graphics/stats.cs

@@ -10,7 +10,7 @@ namespace UnityCli
     {
         public sealed class Request { }
         public sealed class Result { public RenderStatsInfo Stats { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "graphics.stats", Summary = "Read current render statistics (draw calls, batches, triangles, vertices, memory).", Description = "Read-only: returns a unified render stats snapshot from RenderStats (Unity 6) or UnityStats (2022.3).", Group = "graphics",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read render stats", Input = new Request { } } } };
+        public ToolDescriptor Describe() => new() { Name = "graphics.stats", Summary = "Read one unified render counter and memory snapshot.", Description = "Read-only in Edit and Play mode. Returns one bounded snapshot containing draw calls, batches, set-pass calls, triangles, vertices, screen resolution, texture/render-texture memory, and vertex-buffer memory from RenderStats (Unity 6) or UnityStats (2022.3).", Group = "graphics",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read render stats", Input = new Request { } } } };
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result { Stats = GraphicsToolSupport.BuildRenderStats() });
     }
 }

package/unitypkg/Editor/Tools/object/ObjectToolSupport.cs

@@ -49,8 +49,8 @@ namespace UnityCli
         {
             var options = new UnityCliBridge.ObjectSerializer.Options
             {
-                MaxDepth = request.MaxDepth ?? 4,
-                MaxArrayItems = System.Math.Max(0, System.Math.Min(request.MaxArrayItems ?? 50, 1000)),
+                MaxDepth = request.MaxDepth ?? UnityCliBridge.ObjectSerializer.DefaultMaxDepth,
+                MaxArrayItems = request.MaxArrayItems ?? UnityCliBridge.ObjectSerializer.DefaultMaxArrayItems,
                 IncludeFields = request.IncludeFields ?? true,
                 IncludeProperties = request.IncludeProperties ?? true,
                 DeepSerialization = request.DeepSerialization ?? true
@@ -61,7 +61,7 @@ namespace UnityCli
             }
             if (request.Paths != null)
             {
-                options.Paths = new HashSet<string>(request.Paths.Where(path => !string.IsNullOrWhiteSpace(path)).Select(path => path.Trim()));
+                options.Paths = request.Paths.Where(path => !string.IsNullOrWhiteSpace(path)).Select(path => path.Trim()).ToList();
             }
             var query = request.ViewQuery as Dictionary<string, object>;
             if (query != null)
@@ -72,7 +72,7 @@ namespace UnityCli
                 object maxDepth;
                 if (query.TryGetValue("maxDepth", out maxDepth) && maxDepth != null)
                 {
-                    options.MaxDepth = System.Math.Max(0, System.Convert.ToInt32(maxDepth, CultureInfo.InvariantCulture));
+                    options.MaxDepth = UnityCliBridge.ObjectSerializer.ParseMaxDepth(maxDepth);
                 }
             }
             if (!string.IsNullOrEmpty(request.NamePattern))

package/unitypkg/Editor/Tools/object/get-data.cs

@@ -17,17 +17,18 @@ namespace UnityCli
             public string Name { get; set; }
             public string Target { get; set; }
             public int? ComponentInstanceId { get; set; }
-            public int? ComponentIndex { get; set; }
+            [UnityCliRange(0L, int.MaxValue)] public int? ComponentIndex { get; set; }
             public string Component { get; set; }
             public string ComponentType { get; set; }
-            public int? MaxDepth { get; set; }
-            public int? MaxArrayItems { get; set; }
+            [UnityCliRange(0L, 16L)] public int? MaxDepth { get; set; }
+            [UnityCliRange(1L, 1000L)] public int? MaxArrayItems { get; set; }
             public bool? IncludeFields { get; set; }
             public bool? IncludeProperties { get; set; }
             public bool? DeepSerialization { get; set; }
-            public List<string> Paths { get; set; }
+            [UnityCliItemsRange(0, 128)] public List<string> Paths { get; set; }
             [UnityCliAnyJson] public object ViewQuery { get; set; }
             public string NamePattern { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -40,7 +41,7 @@ namespace UnityCli
         {
             Name = "object.get-data",
             Summary = "Read deep serialized data from any Unity Object by instanceId, assetPath, guid or path.",
-            Description = "Read deep serialized data from any UnityEngine.Object. Resolves the target by instanceId, assetPath/guid, or path/name. Supports maxDepth, maxArrayItems, includeFields, includeProperties, deepSerialization, paths (exact member reads) and viewQuery (filtered subtree). Read-only.",
+            Description = "Read deep serialized data from any UnityEngine.Object. maxDepth is 0..16 and maxArrayItems is 1..1000. paths accepts at most 128 ordered exact reads; all paths and recursive branches share one budget (10000 scans, 4096 nodes, 2048 getters, 4096 reflection calls, 250 main-thread ms, 1 MiB UTF-8 by default; public maxima are 100000/20000/10000/20000/2000 ms/8 MiB). Truncated nodes return nextPath. Read-only in Edit and Play Mode.",
             Group = "object",
             DestructiveHint = false,
             Target = "editor",
@@ -55,9 +56,10 @@ namespace UnityCli
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            var target = UnityCliBridge.ObjectRefResolver.ResolveObject(request);
+            var budget = ctx.UseReadBudget(request.Budget);
+            var target = UnityCliBridge.ObjectRefResolver.ResolveObject(request, budget);
             var options = ObjectToolSupport.BuildSerializerOptions(request);
-            var data = UnityCliBridge.ObjectSerializer.Serialize(target, options);
+            var data = UnityCliBridge.ObjectSerializer.Serialize(target, options, budget);
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {
                 TypeName = target.GetType().FullName,

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

@@ -23,14 +23,15 @@ namespace UnityCli
             public string Component { get; set; }
             public string ComponentType { get; set; }
             [UnityCliAnyJson] public List<object> PathPatches { get; set; }
-            public int? MaxDepth { get; set; }
-            public int? MaxArrayItems { get; set; }
+            [UnityCliRange(0L, 16L)] public int? MaxDepth { get; set; }
+            [UnityCliRange(1L, 1000L)] public int? MaxArrayItems { get; set; }
             public bool? IncludeFields { get; set; }
             public bool? IncludeProperties { get; set; }
             public bool? DeepSerialization { get; set; }
-            public List<string> Paths { get; set; }
+            [UnityCliItemsRange(0, 128)] public List<string> Paths { get; set; }
             [UnityCliAnyJson] public object ViewQuery { get; set; }
             public string NamePattern { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -71,7 +72,8 @@ namespace UnityCli
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
             ObjectToolSupport.EnsureEditorNotBusy("object.modify");
-            var target = UnityCliBridge.ObjectRefResolver.ResolveObject(request);
+            var readBudget = ctx.UseReadBudget(request.Budget);
+            var target = UnityCliBridge.ObjectRefResolver.ResolveObject(request, readBudget);
             if (EditorApplication.isPlaying && EditorUtility.IsPersistent(target))
             {
                 throw new UnityCliBridge.BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", "object.modify cannot modify persistent assets during Play Mode.", "Target a scene object or exit Play Mode before modifying an asset.");
@@ -112,7 +114,7 @@ namespace UnityCli
             if (observedTarget == null) throw new UnityCliBridge.BridgeCommandException("E_OBJECT_MODIFY_STATE_MISMATCH", "Target could not be fresh-resolved after patch.", "Retry after the Editor is idle.");
             UnityCliBridge.ObjectPatch.VerifyFreshSerializedProperties(observedTarget, request.PathPatches);
             var options = ObjectToolSupport.BuildSerializerOptions(request);
-            var updatedData = UnityCliBridge.ObjectSerializer.Serialize(observedTarget, options);
+            var updatedData = UnityCliBridge.ObjectSerializer.Serialize(observedTarget, options, readBudget);
 
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {