@alpsckr/unitycli 0.4.3 → 0.4.5

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

@@ -1,42 +1,39 @@
 #if UNITY_EDITOR
 using System;
 using System.Collections.Generic;
-using System.Linq;
+using System.Globalization;
+using UnityEditor;
 using UnityEngine;
 using UnityEngine.SceneManagement;
 
 namespace UnityCli
 {
-    /// <summary>
-    /// scene.hierarchy — 读取激活场景的轻量分页层级:parent/深度/名称过滤/组件预览。
-    /// </summary>
+    /// <summary>scene.hierarchy — 以 next raw GameObject 为游标的有界前序层级读取。</summary>
     public class SceneHierarchyTool : IUnityCliTool<SceneHierarchyTool.Request, SceneHierarchyTool.Result>
     {
         public sealed class Request
         {
-            public int? PageSize { get; set; }
-            public int? Cursor { get; set; }
+            [UnityCliRange(1L, 500L)] public int? PageSize { get; set; }
+            public string Cursor { get; set; }
             public string Parent { get; set; }
-            public int? MaxDepth { get; set; }
+            [UnityCliRange(0L, 16L)] 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 UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
             public SceneSummary Scene { get; set; }
-            public List<HierarchyItem> Items { get; set; }
+            [UnityCliItemsRange(0, 500)] public List<HierarchyItem> Items { get; set; }
             public PageInfo PageInfo { get; set; }
+            public UnityCliRequestBudgetUsage Budget { get; set; }
         }
 
-        public sealed class SceneSummary
-        {
-            public string Name { get; set; }
-            public string Path { get; set; }
-        }
+        public sealed class SceneSummary { public string Name { get; set; } public string Path { get; set; } }
 
         public sealed class HierarchyItem
         {
@@ -50,28 +47,28 @@ namespace UnityCli
             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 long? ComponentCount { get; set; }
+            [UnityCliItemsRange(0, UnityCliBridge.ObjectRefResolver.AbsoluteMaxBatchItems)] public List<string> ComponentTypes { get; set; }
+            [UnityCliItemsRange(0, UnityCliBridge.ObjectRefResolver.AbsoluteMaxBatchItems)] 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 string Cursor { get; set; }
+            public string NextCursor { get; set; }
             public bool HasMore { get; set; }
+            public bool Complete { get; set; }
             public bool Truncated { get; set; }
+            public string Generation { 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.",
+            Summary = "Read a lightweight, paged active scene hierarchy from stable raw GameObject positions.",
+            Description = "Read a lightweight active-scene hierarchy in Edit or Play mode. Use parent for one subtree, maxDepth to limit recursion, query/name/component filters to narrow results, and includeComponents only when component previews are needed. Read one selected object with scene.gameobject; use object.get-data or component.get for deep fields. pageSize is 1..500 (default 50), maxDepth is 0..16 (default 1), each page scans only forward from nextCursor, pageInfo never fabricates a filtered total, and old generations return E_CONTINUATION_STALE. All pages share scan/node/getter/reflection/time/UTF-8 budgets.",
             Group = "scene",
             DestructiveHint = false,
             Target = "editor",
@@ -80,169 +77,176 @@ namespace UnityCli
             MaxTimeoutMs = 600000,
             Examples = new[]
             {
-                new ToolExample { Description = "List a bounded hierarchy page", Input = new Request { PageSize = 25, MaxDepth = 1 } },
+                new ToolExample { Description = "List one 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)
         {
+            request = request ?? new Request();
+            var budget = ctx.UseReadBudget(request.Budget);
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             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))
+            if (!budget.TryConsumeGetter() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var sceneName = scene.name;
+            var scenePath = scene.path;
+            if (!budget.TryReserveSerializedUtf8(sceneName) || !budget.TryReserveSerializedUtf8(scenePath)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var parent = ResolveParent(request.Parent, budget);
+            if (parent != null)
             {
-                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);
-                }
+                if (!budget.TryConsumeGetters(2)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                if (parent.scene.handle != scene.handle)
+                    throw new UnityCliBridge.BridgeCommandException("E_SCENE_HIERARCHY_PARENT_NOT_FOUND", "Parent is not in the active scene: " + request.Parent, "Pass an exact active-scene hierarchy path or instance id.");
             }
+            var maxDepth = request.MaxDepth ?? 1;
+            var pageSize = request.PageSize ?? 50;
+            var query = request.Query ?? request.NameFilter;
+            if (parent != null && !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var selector = (parent == null ? "root" : parent.GetInstanceID().ToString(CultureInfo.InvariantCulture)) + "\0" + maxDepth.ToString(CultureInfo.InvariantCulture)
+                + "\0" + query + "\0" + request.ComponentType + "\0" + request.IncludeInactive + "\0" + request.IncludeComponents;
+            var generation = UnityCliContinuationToken.Fingerprint(UnityCliReadGeneration.Hierarchy(scene) + "\0" + selector);
+            var traversal = new UnityCliHierarchyPager.Traversal(scene, parent, maxDepth, budget);
+            GameObject current;
+            if (string.IsNullOrEmpty(request.Cursor)) current = traversal.First(budget);
             else
             {
-                roots.AddRange(scene.GetRootGameObjects());
+                current = UnityCliHierarchyPager.ResolveCursor(request.Cursor, "scene.hierarchy", generation, budget, out var phase);
+                if (!budget.TryConsumeGetters(parent == null ? 2 : 3)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                if (phase != "scene" || current.scene.handle != scene.handle || !WithinBoundary(current.transform, parent == null ? null : parent.transform, maxDepth, budget))
+                    throw UnityCliHierarchyPager.Stale();
             }
 
-            var allItems = new List<HierarchyItem>();
-            foreach (var root in roots.OrderBy(g => HierarchyPath(g), StringComparer.Ordinal))
+            var items = new List<HierarchyItem>();
+            while (current != null && items.Count < pageSize)
             {
-                CollectHierarchy(root.transform, allItems, 0, maxDepth, query, includeInactive, includeComponents, componentType);
+                var candidate = current;
+                if (!budget.TryConsumeScannedRecord()) break;
+                try
+                {
+                    var next = traversal.Next(candidate, budget);
+                    if (Matches(candidate, query, request.ComponentType, request.IncludeInactive, budget))
+                        items.Add(BuildItem(candidate.transform, parent, request.IncludeComponents, budget));
+                    current = next;
+                }
+                catch (UnityCliRequestBudgetExceededException)
+                {
+                    current = candidate;
+                    break;
+                }
             }
 
-            var total = allItems.Count;
-            var page = allItems.Skip(cursor).Take(pageSize).ToList();
+            if (items.Count == 0 && current != null) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension ?? "scannedRecords");
+            var nextCursor = UnityCliHierarchyPager.Cursor("scene.hierarchy", generation, "scene", current, budget);
             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)
+                Scene = new SceneSummary { Name = sceneName, Path = scenePath },
+                Items = items,
+                PageInfo = new PageInfo
+                {
+                    ReturnedCount = items.Count,
+                    PageSize = pageSize,
+                    Cursor = request.Cursor,
+                    NextCursor = nextCursor,
+                    HasMore = nextCursor != null,
+                    Complete = nextCursor == null,
+                    Truncated = nextCursor != null,
+                    Generation = generation
+                },
+                Budget = budget.Usage()
             });
         }
 
-        // 按深度/名称/inactive 策略收集层级项;分页在调用方统一处理。
-        private static void CollectHierarchy(Transform transform, List<HierarchyItem> items, int depth, int maxDepth, string query, bool includeInactive, bool includeComponents, string componentType)
+        private static GameObject ResolveParent(string parent, UnityCliRequestBudget budget)
         {
-            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)
+            if (string.IsNullOrEmpty(parent)) return null;
+            int instanceId;
+            GameObject value = null;
+            if (int.TryParse(parent, NumberStyles.Integer, CultureInfo.InvariantCulture, out instanceId))
             {
-                CollectHierarchy(child, items, depth + 1, maxDepth, query, includeInactive, includeComponents, componentType);
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                value = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
             }
+            else value = UnityCliBridge.ObjectRefResolver.FindGameObjectByExactPath(parent, budget);
+            if (value == null) throw new UnityCliBridge.BridgeCommandException("E_SCENE_HIERARCHY_PARENT_NOT_FOUND", "Parent GameObject not found: " + parent, "Pass an exact hierarchy path or instance id from a fresh scene.hierarchy page.");
+            return value;
         }
 
-        // 生成轻量 GameObject 层级项;componentTypes 始终返回,components 仅在 includeComponents 时返回。
-        private static HierarchyItem BuildHierarchyItem(Transform transform, int depth, bool includeComponents)
+        private static bool WithinBoundary(Transform value, Transform boundary, int maxDepth, UnityCliRequestBudget budget)
         {
-            var componentNames = new List<string>();
-            foreach (var component in transform.GetComponents<Component>())
+            if (value == null) return false;
+            var current = value;
+            var depth = 0;
+            while (current != null && current != boundary)
             {
-                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;
+                if (depth > maxDepth) return false;
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                current = current.parent;
+                depth++;
             }
-            return item;
+            return (boundary == null || current == boundary) && depth - 1 <= maxDepth;
         }
 
-        private static string HierarchyPath(GameObject gameObject)
+        private static bool Matches(GameObject gameObject, string query, string componentType, bool includeInactive, UnityCliRequestBudget budget)
         {
-            var names = new Stack<string>();
-            var current = gameObject.transform;
-            while (current != null)
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            if (!includeInactive && !gameObject.activeInHierarchy) return false;
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var name = gameObject.name;
+            if (!string.IsNullOrEmpty(query))
             {
-                names.Push(current.name);
-                current = current.parent;
+                var path = UnityCliHierarchyPager.Path(gameObject, budget);
+                if (name.IndexOf(query, StringComparison.OrdinalIgnoreCase) < 0 && path.IndexOf(query, StringComparison.OrdinalIgnoreCase) < 0) return false;
             }
-            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(componentType)) return true;
+            foreach (var component in UnityCliBridge.ObjectRefResolver.BoundedComponents(gameObject, budget))
             {
-                if (!string.IsNullOrEmpty(value) && value.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0)
-                {
-                    return true;
-                }
+                if (component == null && string.Equals(componentType, "MissingScript", StringComparison.OrdinalIgnoreCase)) return true;
+                if (component == null) continue;
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var type = component.GetType();
+                if (string.Equals(type.Name, componentType, StringComparison.OrdinalIgnoreCase)
+                    || string.Equals(type.FullName, componentType, StringComparison.OrdinalIgnoreCase)) return true;
             }
             return false;
         }
 
-        // 判断 GameObject 是否拥有指定 Component 类型;空 componentType 表示不过滤(字符串匹配,不解析程序集)。
-        private static bool ComponentMatches(GameObject gameObject, string componentType)
+        private static HierarchyItem BuildItem(Transform transform, GameObject parent, bool includeComponents, UnityCliRequestBudget budget)
         {
-            if (gameObject == null || string.IsNullOrEmpty(componentType)) return true;
-            foreach (var component in gameObject.GetComponents<Component>())
+            if (!budget.TryConsumeNode() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var gameObject = transform.gameObject;
+            var path = UnityCliHierarchyPager.Path(gameObject, budget);
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var name = gameObject.name;
+            if (!budget.TryReserveSerializedUtf8(name) || !budget.TryReserveSerializedUtf8(path)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            List<string> componentNames = null;
+            if (includeComponents)
             {
-                if (ComponentTypeMatches(component, componentType)) return true;
+                componentNames = new List<string>();
+                foreach (var component in UnityCliBridge.ObjectRefResolver.BoundedComponents(gameObject, budget))
+                {
+                    if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    var componentName = component == null ? "MissingScript" : component.GetType().FullName;
+                    if (!budget.TryReserveSerializedUtf8(componentName)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    componentNames.Add(componentName);
+                }
             }
-            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
+            if (!budget.TryConsumeGetter() || !budget.TryConsumeGetter() || !budget.TryConsumeGetter()
+                || !budget.TryConsumeGetter() || !budget.TryConsumeGetter() || !budget.TryConsumeGetter())
+                throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var childCount = transform.childCount;
+            var tag = gameObject.tag;
+            if (!budget.TryReserveSerializedUtf8(tag)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return new HierarchyItem
             {
-                Total = totalCount,
-                TotalCount = totalCount,
-                ReturnedCount = returnedCount,
-                PageSize = pageSize,
-                Cursor = cursor,
-                NextCursor = next,
-                HasMore = next != null,
-                Truncated = next != null
+                Id = gameObject.GetInstanceID(), Name = name, Path = path,
+                Depth = UnityCliHierarchyPager.Depth(transform, parent == null ? null : parent.transform, budget),
+                Active = gameObject.activeSelf, ActiveInHierarchy = gameObject.activeInHierarchy,
+                Tag = tag, Layer = gameObject.layer, ChildCount = childCount,
+                ChildrenTruncated = childCount > 0,
+                ComponentCount = componentNames == null ? (long?)null : componentNames.Count,
+                ComponentTypes = componentNames,
+                Components = componentNames
             };
         }
     }

package/unitypkg/Editor/Tools/screenshot/EditorElementCaptureToolSupport.cs

@@ -2,7 +2,6 @@
 using System;
 using System.Collections.Generic;
 using System.IO;
-using System.Linq;
 using UnityEditor;
 using UnityEngine;
 #if UNITY_6000_7_OR_NEWER
@@ -26,9 +25,10 @@ namespace UnityCli
             internal List<string> ElementClasses;
             internal long WindowInstanceId, MaxBytes;
             internal int Width, Height;
+            internal ScreenshotCaptureBudget CaptureBudget;
         }
 
-        internal static Plan Prepare(EditorElementCaptureRequest request)
+        internal static Plan Prepare(EditorElementCaptureRequest request, UnityCliRequestBudget requestBudget)
         {
 #if !UNITY_6000_7_OR_NEWER
             throw Unavailable();
@@ -41,20 +41,29 @@ namespace UnityCli
             var maxBytes = request.MaxBytes ?? (8L * 1024L * 1024L);
             if (maxWidth < 1 || maxWidth > MaxDimension || maxHeight < 1 || maxHeight > MaxDimension || maxBytes < 1024 || maxBytes > MaxArtifactBytes)
                 throw Error("E_EDITOR_ELEMENT_LIMIT_INVALID", "maxWidth/maxHeight must be 1..4096 and maxBytes must be 1024..33554432.");
-            var candidates = Resources.FindObjectsOfTypeAll<EditorWindow>()
-                .Where(value => value != null && value.rootVisualElement != null && value.rootVisualElement.panel != null)
-                .Where(value => string.Equals(value.GetType().Name, request.Window, StringComparison.Ordinal) || string.Equals(value.titleContent == null ? null : value.titleContent.text, request.Window, StringComparison.Ordinal))
-                .OrderBy(value => value.GetInstanceID()).Take(257).ToList();
+            var candidates = new List<EditorWindow>();
+            foreach (var value in Resources.FindObjectsOfTypeAll<EditorWindow>())
+            {
+                if (!requestBudget.TryConsumeScannedRecord()) throw new UnityCliRequestBudgetExceededException(requestBudget.ExhaustedDimension);
+                if (value == null || value.rootVisualElement == null || value.rootVisualElement.panel == null) continue;
+                if (!string.Equals(value.GetType().Name, request.Window, StringComparison.Ordinal)
+                    && !string.Equals(value.titleContent == null ? null : value.titleContent.text, request.Window, StringComparison.Ordinal)) continue;
+                candidates.Add(value);
+                if (candidates.Count > 256) break;
+            }
+            candidates.Sort((left, right) => left.GetInstanceID().CompareTo(right.GetInstanceID()));
             if (candidates.Count == 0) throw Error("E_EDITOR_ELEMENT_WINDOW_NOT_FOUND", "No attached EditorWindow exactly matches '" + request.Window + "'.");
             if (candidates.Count > 256) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "More than 256 EditorWindow candidates matched the bounded scan.");
             var window = candidates[0];
-            var element = Resolve(window.rootVisualElement, request.Selector);
+            var element = Resolve(window.rootVisualElement, request.Selector, requestBudget);
             if (element == null) throw Error("E_EDITOR_ELEMENT_NOT_FOUND", "No UI Toolkit element matched selector '" + request.Selector + "'.");
             var width = Mathf.CeilToInt(element.worldBound.width);
             var height = Mathf.CeilToInt(element.worldBound.height);
             if (width < 1 || height < 1 || width > maxWidth || height > maxHeight || (long)width * height > 16777216L)
                 throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "Resolved element dimensions " + width + "x" + height + " exceed the requested capture bounds.");
-            return new Plan { Element = element, WindowType = window.GetType().Name, WindowTitle = window.titleContent == null ? null : window.titleContent.text, WindowInstanceId = window.GetInstanceID(), Selector = request.Selector, ElementType = element.GetType().Name, ElementName = element.name, ElementClasses = element.GetClasses().Take(128).Select(Bound).ToList(), Width = width, Height = height, MaxBytes = maxBytes };
+            var limits = new ScreenshotBudgetInput { MaxArtifactBytes = maxBytes };
+            var captureBudget = ScreenshotToolSupport.PrepareCaptureBudget(width, height, 1, false, limits, requestBudget);
+            return new Plan { Element = element, WindowType = window.GetType().Name, WindowTitle = window.titleContent == null ? null : window.titleContent.text, WindowInstanceId = window.GetInstanceID(), Selector = request.Selector, ElementType = element.GetType().Name, ElementName = element.name, ElementClasses = BoundClasses(element, requestBudget), Width = width, Height = height, MaxBytes = maxBytes, CaptureBudget = captureBudget };
 #endif
         }
 
@@ -65,6 +74,7 @@ namespace UnityCli
             throw Unavailable();
 #else
             if (plan == null || plan.Element == null || plan.Element.panel == null) throw Error("E_EDITOR_ELEMENT_TARGET_CHANGED", "The frozen UI Toolkit element is no longer attached.");
+            plan.CaptureBudget.BeginCapture(plan.Width, plan.Height);
             RenderTexture texture = null;
             Texture2D readable = null;
             var previous = RenderTexture.active;
@@ -91,7 +101,7 @@ namespace UnityCli
             if (string.IsNullOrWhiteSpace(ctx.ArtifactDir)) throw Error("E_EDITOR_ELEMENT_ARTIFACT_UNAVAILABLE", "The request artifact directory is unavailable.");
             Directory.CreateDirectory(ctx.ArtifactDir);
             var output = Path.Combine(ctx.ArtifactDir, "editor-element.png");
-            var artifact = ScreenshotToolSupport.WriteScreenshotBytes(output, png);
+            var artifact = ScreenshotToolSupport.WriteScreenshotBytes(output, png, plan.CaptureBudget);
             if (artifact.SizeBytes > plan.MaxBytes || artifact.SizeBytes != png.LongLength)
             {
                 try { File.Delete(output); } catch { }
@@ -105,15 +115,16 @@ namespace UnityCli
 
         private static EditorElementCaptureResult Result(Plan plan, bool dryRun, ScreenshotArtifactProof artifact)
         {
-            return new EditorElementCaptureResult { Available = true, Element = new EditorElementIdentity { Selector = plan.Selector, Type = plan.ElementType, Name = plan.ElementName, Classes = plan.ElementClasses }, Width = plan.Width, Height = plan.Height, Artifact = artifact, DryRun = dryRun, PlannedEffects = new List<EditorElementCapturePlannedEffect> { new EditorElementCapturePlannedEffect { Type = "screenshot.editor-element", WindowInstanceId = plan.WindowInstanceId, Width = plan.Width, Height = plan.Height, MaxBytes = plan.MaxBytes } } };
+            return new EditorElementCaptureResult { Available = true, Element = new EditorElementIdentity { Selector = plan.Selector, Type = plan.ElementType, Name = plan.ElementName, Classes = plan.ElementClasses }, Width = plan.Width, Height = plan.Height, Artifact = artifact, DryRun = dryRun, PlannedEffects = new List<EditorElementCapturePlannedEffect> { new EditorElementCapturePlannedEffect { Type = "screenshot.editor-element", WindowInstanceId = plan.WindowInstanceId, Width = plan.Width, Height = plan.Height, MaxBytes = plan.MaxBytes, CapturePlan = plan.CaptureBudget.Plan } } };
         }
 
 #if UNITY_6000_7_OR_NEWER
         /// <summary>实现type/#id/.class与descendant/child链；全查询最多16段、10000候选。</summary>
-        private static VisualElement Resolve(VisualElement root, string selector)
+        private static VisualElement Resolve(VisualElement root, string selector, UnityCliRequestBudget budget)
         {
             var tokens = selector.Replace(">", " > ").Split(new[] { ' ' }, StringSplitOptions.RemoveEmptyEntries);
-            var segments = tokens.Count(token => token != ">");
+            var segments = 0;
+            foreach (var token in tokens) if (token != ">") segments++;
             if (segments < 1 || segments > 16) throw Error("E_EDITOR_ELEMENT_SELECTOR_INVALID", "selector must contain 1..16 simple segments.");
             var current = new List<VisualElement> { root };
             var direct = false;
@@ -124,11 +135,10 @@ namespace UnityCli
                 var next = new List<VisualElement>();
                 foreach (var parent in current)
                 {
-                    var values = direct ? parent.Children() : Descendants(parent, ref visited);
-                    foreach (var value in values)
+                    foreach (var value in TraverseChildren(parent, !direct, budget))
                     {
                         if (++visited > 10000) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "selector scan exceeded 10000 UI elements.");
-                        if (Matches(value, token)) next.Add(value);
+                        if (Matches(value, token, budget)) next.Add(value);
                         if (next.Count > 256) throw Error("E_EDITOR_ELEMENT_LIMIT_EXCEEDED", "selector produced more than 256 intermediate matches.");
                     }
                 }
@@ -136,27 +146,55 @@ namespace UnityCli
                 direct = false;
                 if (current.Count == 0) return null;
             }
-            return current.FirstOrDefault();
+            return current.Count == 0 ? null : current[0];
         }
 
-        private static IEnumerable<VisualElement> Descendants(VisualElement root, ref int visited)
+        private static List<string> BoundClasses(VisualElement element, UnityCliRequestBudget budget)
         {
-            var result = new List<VisualElement>();
-            var stack = new Stack<VisualElement>(root.Children().Reverse());
-            while (stack.Count > 0)
+            var result = new List<string>();
+            foreach (var value in element.GetClasses())
             {
-                var value = stack.Pop();
-                result.Add(value);
-                if (result.Count + visited > 10000) break;
-                foreach (var child in value.Children().Reverse()) stack.Push(child);
+                if (result.Count >= 128) break;
+                if (!budget.TryConsumeScannedRecord()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var bounded = Bound(value);
+                if (!budget.TryReserveSerializedUtf8(bounded)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                result.Add(bounded);
             }
             return result;
         }
 
-        private static bool Matches(VisualElement value, string simple)
+        /// <summary>用(parent,nextChildIndex)逐子节点DFS，任何childCount和索引读取前先消费同一请求预算。</summary>
+        private static IEnumerable<VisualElement> TraverseChildren(VisualElement root, bool recursive, UnityCliRequestBudget budget)
+        {
+            var stack = new Stack<VisualElementTraversalFrame>();
+            stack.Push(CreateTraversalFrame(root, budget));
+            while (stack.Count > 0)
+            {
+                var frame = stack.Peek();
+                if (frame.NextChildIndex >= frame.ChildCount)
+                {
+                    stack.Pop();
+                    continue;
+                }
+                if (!budget.TryCheckpoint() || !budget.TryConsumeScannedRecord() || !budget.TryConsumeNode() || !budget.TryConsumeGetter())
+                    throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var value = frame.Parent[frame.NextChildIndex++];
+                yield return value;
+                if (recursive) stack.Push(CreateTraversalFrame(value, budget));
+            }
+        }
+
+        private static VisualElementTraversalFrame CreateTraversalFrame(VisualElement parent, UnityCliRequestBudget budget)
+        {
+            if (!budget.TryCheckpoint() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            return new VisualElementTraversalFrame(parent, parent.childCount);
+        }
+
+        private static bool Matches(VisualElement value, string simple, UnityCliRequestBudget budget)
         {
             var typeEnd = simple.IndexOfAny(new[] { '#', '.' });
             var type = typeEnd < 0 ? simple : simple.Substring(0, typeEnd);
+            if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             if (!string.IsNullOrEmpty(type) && type != "*" && !string.Equals(value.GetType().Name, type, StringComparison.Ordinal)) return false;
             var position = Math.Max(0, typeEnd);
             while (position < simple.Length)
@@ -165,12 +203,26 @@ namespace UnityCli
                 var next = simple.IndexOfAny(new[] { '#', '.' }, position);
                 var name = simple.Substring(position, (next < 0 ? simple.Length : next) - position);
                 if (string.IsNullOrEmpty(name)) return false;
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
                 if (marker == '#' && !string.Equals(value.name, name, StringComparison.Ordinal)) return false;
                 if (marker == '.' && !value.ClassListContains(name)) return false;
                 position = next < 0 ? simple.Length : next;
             }
             return true;
         }
+
+        private sealed class VisualElementTraversalFrame
+        {
+            internal readonly VisualElement Parent;
+            internal readonly int ChildCount;
+            internal int NextChildIndex;
+
+            internal VisualElementTraversalFrame(VisualElement parent, int childCount)
+            {
+                Parent = parent;
+                ChildCount = childCount;
+            }
+        }
 #endif
 
         private static string Bound(string value) => value == null || value.Length <= 1024 ? value : value.Substring(0, 1024);