@alpsckr/unitycli 0.4.3 → 0.4.4

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

@@ -1,182 +1,348 @@
 #if UNITY_EDITOR
 using System;
 using System.Collections.Generic;
+using System.Globalization;
 using System.Reflection;
 
 namespace UnityCli
 {
+    /// <summary>profiler.hierarchy — 使用 RawFrameDataView 扁平先序索引做全局节点续页。</summary>
     public class ProfilerHierarchyTool : IUnityCliTool<ProfilerHierarchyTool.Request, ProfilerHierarchyTool.Result>
     {
         public sealed class Request
         {
-            public int? Frame { get; set; }
-            public int? Thread { get; set; }
-            public int? Top { get; set; }
-            public int? Depth { get; set; }
+            [UnityCliRange(-1L, int.MaxValue)] public int? Frame { get; set; }
+            [UnityCliRange(0L, 1024L)] public int? Thread { get; set; }
+            [UnityCliRange(1L, 500L)] public int? PageSize { get; set; }
+            [UnityCliRange(0L, 32L)] public int? Depth { get; set; }
+            public string Cursor { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
-            public List<HierarchyItem> RootItems { get; set; }
+            public long Frame { get; set; }
+            public long Thread { get; set; }
+            [UnityCliItemsRange(0, 500)] public List<HierarchyItem> Items { get; set; }
+            public PageInfo PageInfo { get; set; }
+            public UnityCliRequestBudgetUsage Budget { get; set; }
         }
 
         public sealed class HierarchyItem
         {
             public long Id { get; set; }
+            public long ParentId { get; set; }
             public string Name { get; set; }
             public long Depth { get; set; }
             public double Ms { get; set; }
-            public long SiblingCount { get; set; }
             public long ChildCount { get; set; }
             public bool ChildrenTruncated { get; set; }
-            public List<HierarchyItem> Children { get; set; }
+        }
+
+        public sealed class PageInfo
+        {
+            public long PageSize { get; set; }
+            public long ReturnedCount { 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 = "profiler.hierarchy",
-            Summary = "Read the per-function CPU call hierarchy (marker tree) for one profiler frame/thread.",
-            Description = "Read the CPU call hierarchy for a single profiler frame and thread via ProfilerDriver.GetHierarchyFrameDataView, recursing GetItemChildren to emit a structured marker tree. Defaults are bounded (top=20, depth=5); each node reports childCount and childrenTruncated so AI can see when detail was omitted.",
-            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            Summary = "Page one profiler frame/thread call hierarchy with a global raw-node budget and stable continuation.",
+            Description = "Read a flat preorder page from Unity RawFrameDataView without copying the full hierarchy. frame defaults to the latest recorded frame, thread is 0..1024, pageSize is 1..500 (default 50), and depth is 0..32 (default 5). The DFS stack is carried by opaque nextCursor, so later pages resume in O(depth). All nodes share request scan/node/reflection/time/UTF-8 budgets; defaults are 10000/4096/4096/250 ms/1 MiB and public maxima are 100000/20000/20000/2000 ms/8 MiB. complete=false identifies truncation. Read-only in Edit and Play Mode.",
+            Group = "profiler", DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
             DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
-            Examples = new[]
-            {
-                new ToolExample { Description = "Latest frame main-thread top markers", Input = new Request { Top = 20, Depth = 5 } },
-                new ToolExample { Description = "Latest frame on the main thread", Input = new Request { Frame = -1, Thread = 0 } }
-            }
+            Examples = new[] { new ToolExample { Description = "Read latest-frame nodes", Input = new Request { PageSize = 50, Depth = 5 } } }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            var driverType = ProfilerToolSupport.FindType("UnityEditorInternal.ProfilerDriver");
-            if (driverType == null)
-            {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
-                    "UnityEditorInternal.ProfilerDriver is not available; hierarchy requires the Editor Profiler.",
-                    "Capture Profiler data in the selected Live Editor, then retry.");
-            }
-
-            // 省略 frame 时读取最新已采集帧
+            request = request ?? new Request();
+            var budget = ctx.UseReadBudget(request.Budget);
+            if (!request.Frame.HasValue && (!budget.TryConsumeReflectionCall() || !budget.TryConsumeGetter())) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             var frame = request.Frame ?? ProfilerToolSupport.ProfilerDriverIntProperty("lastFrameIndex", -1);
             var threadIndex = request.Thread ?? 0;
-            var top = Math.Max(1, Math.Min(request.Top ?? 20, 5000));
-            var maxDepth = Math.Max(1, Math.Min(request.Depth ?? 5, 32));
-
-            var hierarchyViewType = ProfilerToolSupport.FindType("UnityEditor.Profiling.HierarchyFrameDataView")
-                ?? ProfilerToolSupport.FindType("UnityEditorInternal.HierarchyFrameDataView")
-                ?? ProfilerToolSupport.FindType("UnityEngine.Profiling.HierarchyFrameDataView");
-            if (hierarchyViewType == null)
+            var pageSize = request.PageSize ?? 50;
+            var maxDepth = request.Depth ?? 5;
+            var accessor = RawHierarchyAccessor.Open(frame, threadIndex, budget);
+            try
             {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
-                    "HierarchyFrameDataView type not available in this Unity version.",
-                    "Use an Editor version that exposes UnityEditor.Profiling.HierarchyFrameDataView, then record profiler frames before retrying.");
+                var generation = UnityCliContinuationToken.Fingerprint(UnityCliReadGeneration.Session("profiler.hierarchy") + "\0" + accessor.CaptureIdentity);
+                var stack = string.IsNullOrEmpty(request.Cursor)
+                    ? new List<TraversalFrame> { new TraversalFrame { ParentId = 0, NextSample = 1, Depth = 0 } }
+                    : ParseCursor(request.Cursor, generation, accessor, maxDepth, budget);
+                var items = new List<HierarchyItem>();
+                while (stack.Count > 0 && items.Count < pageSize)
+                {
+                    var before = EncodeStack(stack);
+                    if (!TryNext(accessor, stack, maxDepth, budget, out var item))
+                    {
+                        if (budget.IsExhausted) stack = DecodeStack(before);
+                        break;
+                    }
+                    items.Add(item);
+                }
+                if (items.Count == 0 && stack.Count > 0) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension ?? "scannedRecords");
+                var nextCursor = stack.Count == 0 ? null : UnityCliContinuationToken.Create("profiler.hierarchy", generation, EncodeStack(stack));
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Frame = frame,
+                    Thread = threadIndex,
+                    Items = items,
+                    PageInfo = new PageInfo
+                    {
+                        PageSize = pageSize, ReturnedCount = items.Count, Cursor = request.Cursor, NextCursor = nextCursor,
+                        Complete = nextCursor == null, Truncated = nextCursor != null, Generation = generation
+                    },
+                    Budget = budget.Usage()
+                });
             }
+            finally { accessor.Dispose(); }
+        }
 
-            var viewModesType = hierarchyViewType.GetTypeInfo().GetDeclaredNestedType("ViewModes")?.AsType();
-            var getHierarchy = viewModesType == null
-                ? null
-                : driverType.GetMethod("GetHierarchyFrameDataView", new[] { typeof(int), typeof(int), viewModesType, typeof(int), typeof(bool) });
-            // 不同 Unity 版本签名不同;退回 (int,int) 最简重载
-            if (getHierarchy == null)
-            {
-                getHierarchy = driverType.GetMethod("GetHierarchyFrameDataView", new[] { typeof(int), typeof(int) });
-            }
-            if (getHierarchy == null)
+        /// <summary>扁平先序数组中，当前子树后的首个样本就是下一兄弟；栈只保留每层的下一个样本。</summary>
+        internal static bool TryNext(RawHierarchyAccessor accessor, List<TraversalFrame> stack, int maxDepth, UnityCliRequestBudget budget, out HierarchyItem item)
+        {
+            item = null;
+            while (stack.Count > 0)
             {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
-                    "ProfilerDriver.GetHierarchyFrameDataView overload not found.",
-                    "Unity version may not expose this API via reflection.");
+                var frame = stack[stack.Count - 1];
+                var parentEnd = accessor.SubtreeEndExclusive(frame.ParentId, budget);
+                if (budget.IsExhausted) return false;
+                if (frame.NextSample >= parentEnd) { stack.RemoveAt(stack.Count - 1); continue; }
+                if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeNode()) return false;
+                var child = frame.NextSample;
+                var childEnd = accessor.SubtreeEndExclusive(child, budget);
+                if (budget.IsExhausted) return false;
+                var grandChildren = accessor.ChildCount(child, budget);
+                if (budget.IsExhausted) return false;
+                if ((grandChildren > 0) != (childEnd > child + 1)) throw RawHierarchyAccessor.InvalidPreorder();
+                var name = accessor.Name(child, budget) ?? "(unknown)";
+                var milliseconds = accessor.Milliseconds(child, budget);
+                if (budget.IsExhausted || !budget.TryReserveSerializedUtf8(name)) return false;
+                frame.NextSample = childEnd;
+                item = new HierarchyItem
+                {
+                    Id = child, ParentId = frame.ParentId, Name = name, Depth = frame.Depth,
+                    Ms = milliseconds, ChildCount = grandChildren,
+                    ChildrenTruncated = grandChildren > 0 && frame.Depth >= maxDepth
+                };
+                if (grandChildren > 0 && frame.Depth < maxDepth)
+                    stack.Add(new TraversalFrame { ParentId = child, NextSample = child + 1, Depth = frame.Depth + 1 });
+                return true;
             }
+            return false;
+        }
 
-            object view = null;
+        private static List<TraversalFrame> ParseCursor(string cursor, string generation, RawHierarchyAccessor accessor, int maxDepth, UnityCliRequestBudget budget)
+        {
+            string position;
+            if (!UnityCliContinuationToken.TryParse(cursor, "profiler.hierarchy", generation, out position)) throw Stale();
             try
             {
-                view = getHierarchy.GetParameters().Length == 2
-                    ? getHierarchy.Invoke(null, new object[] { frame, threadIndex })
-                    : getHierarchy.Invoke(null, new object[] { frame, threadIndex, 0, 0, false });
+                var stack = DecodeStack(position);
+                if (stack.Count == 0 || stack.Count > maxDepth + 1) throw Stale();
+                for (var index = 0; index < stack.Count; index++)
+                {
+                    var frame = stack[index];
+                    if (frame.Depth != index || frame.ParentId < 0 || frame.ParentId >= accessor.SampleCount) throw Stale();
+                    var parentEnd = accessor.SubtreeEndExclusive(frame.ParentId, budget);
+                    if (budget.IsExhausted) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    if (frame.NextSample < frame.ParentId + 1 || frame.NextSample > parentEnd) throw Stale();
+                    if (index + 1 < stack.Count)
+                    {
+                        var activeChild = stack[index + 1].ParentId;
+                        if (activeChild <= frame.ParentId || activeChild >= parentEnd) throw Stale();
+                        var activeChildEnd = accessor.SubtreeEndExclusive(activeChild, budget);
+                        if (budget.IsExhausted) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                        if (activeChildEnd != frame.NextSample) throw Stale();
+                    }
+                }
+                return stack;
             }
-            catch (Exception exception)
+            catch (UnityCliRequestBudgetExceededException) { throw; }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw Stale(); }
+        }
+
+        private static string EncodeStack(List<TraversalFrame> stack)
+        {
+            var values = new List<string>();
+            foreach (var frame in stack) values.Add(frame.ParentId.ToString(CultureInfo.InvariantCulture) + "," + frame.NextSample.ToString(CultureInfo.InvariantCulture) + "," + frame.Depth.ToString(CultureInfo.InvariantCulture));
+            return string.Join(";", values.ToArray());
+        }
+
+        private static List<TraversalFrame> DecodeStack(string value)
+        {
+            var result = new List<TraversalFrame>();
+            if (string.IsNullOrEmpty(value)) return result;
+            foreach (var token in value.Split(';'))
             {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
-                    "Failed to acquire hierarchy frame data: " + exception.Message,
-                    HierarchyDetails(frame, threadIndex),
-                    new[] { "Make sure the Profiler has recorded frames; pass profiler.start then profiler.stop, then query a recorded frame (or omit frame to use the latest)." });
+                var parts = token.Split(',');
+                if (parts.Length != 3) throw new FormatException();
+                result.Add(new TraversalFrame
+                {
+                    ParentId = int.Parse(parts[0], CultureInfo.InvariantCulture),
+                    NextSample = int.Parse(parts[1], CultureInfo.InvariantCulture),
+                    Depth = int.Parse(parts[2], CultureInfo.InvariantCulture)
+                });
             }
-            if (view == null)
+            if (result.Count > 33) throw new FormatException();
+            return result;
+        }
+
+        private static UnityCliBridge.BridgeCommandException Stale()
+        {
+            return new UnityCliBridge.BridgeCommandException("E_CONTINUATION_STALE", "The profiler hierarchy continuation does not match the same frame/thread generation.", "Start a new profiler.hierarchy read without cursor.");
+        }
+
+        internal sealed class TraversalFrame { internal int ParentId; internal int NextSample; internal int Depth; }
+
+        internal sealed class RawHierarchyAccessor : IDisposable
+        {
+            private readonly object view;
+            private readonly PropertyInfo validProperty;
+            private readonly int sampleCount;
+            private readonly MethodInfo childCountMethod;
+            private readonly MethodInfo recursiveChildCountMethod;
+            private readonly MethodInfo nameMethod;
+            private readonly MethodInfo millisecondsMethod;
+            private readonly string captureIdentity;
+
+            private RawHierarchyAccessor(object view, Type type, UnityCliRequestBudget budget)
             {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_NO_DATA",
-                    "No hierarchy data available for the requested frame/thread.",
-                    "Record profiler frames first (profiler.start → play → profiler.stop), then query a valid frame.");
+                this.view = view;
+                validProperty = ReflectProperty(type, "valid", budget);
+                var sampleCountProperty = ReflectProperty(type, "sampleCount", budget);
+                var frameIndexProperty = ReflectProperty(type, "frameIndex", budget);
+                var threadIndexProperty = ReflectProperty(type, "threadIndex", budget);
+                var frameStartTimeProperty = ReflectProperty(type, "frameStartTimeMs", budget);
+                var frameTimeProperty = ReflectProperty(type, "frameTimeMs", budget);
+                childCountMethod = ReflectMethod(type, "GetSampleChildrenCount", new[] { typeof(int) }, budget);
+                recursiveChildCountMethod = ReflectMethod(type, "GetSampleChildrenCountRecursive", new[] { typeof(int) }, budget);
+                nameMethod = ReflectMethod(type, "GetSampleName", new[] { typeof(int) }, budget);
+                millisecondsMethod = ReflectMethod(type, "GetSampleTimeMs", new[] { typeof(int) }, budget);
+                if (sampleCountProperty == null || frameIndexProperty == null || threadIndexProperty == null || frameStartTimeProperty == null || frameTimeProperty == null
+                    || childCountMethod == null || recursiveChildCountMethod == null || nameMethod == null || millisecondsMethod == null)
+                    throw Unavailable("RawFrameDataView capture identity or preorder hierarchy members are unavailable.");
+                if (validProperty != null && !ReadBool(validProperty, view, budget)) throw NoData();
+                var identityValues = new object[5];
+                var identityProperties = new[] { frameIndexProperty, threadIndexProperty, frameStartTimeProperty, frameTimeProperty, sampleCountProperty };
+                for (var index = 0; index < identityProperties.Length; index++)
+                {
+                    if (!budget.TryConsumeGetter() || !budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                    identityValues[index] = identityProperties[index].GetValue(view, null);
+                }
+                sampleCount = Convert.ToInt32(identityValues[4], CultureInfo.InvariantCulture);
+                if (sampleCount <= 0) throw NoData();
+                captureIdentity = string.Join("\0", Array.ConvertAll(identityValues, value => Convert.ToString(value, CultureInfo.InvariantCulture)));
+                if (!budget.TryReserveSerializedUtf8(captureIdentity)) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             }
 
-            var validProp = hierarchyViewType.GetProperty("valid");
-            if (validProp != null && !(bool)validProp.GetValue(view, null))
+            internal int SampleCount { get { return sampleCount; } }
+            internal string CaptureIdentity { get { return captureIdentity; } }
+
+            internal static RawHierarchyAccessor Open(int frame, int thread, UnityCliRequestBudget budget)
             {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_NO_DATA",
-                    "HierarchyFrameDataView is invalid for the requested frame/thread.",
-                    "Record profiler frames first, then query a valid frame.");
+                var driver = UnityCliBridge.TypeSchemaGenerator.ResolveType("UnityEditorInternal.ProfilerDriver", budget);
+                if (driver == null) throw Unavailable("ProfilerDriver is unavailable.");
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var method = driver.GetMethod("GetRawFrameDataView", BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic, null, new[] { typeof(int), typeof(int) }, null);
+                if (method == null) throw Unavailable("ProfilerDriver.GetRawFrameDataView is unavailable.");
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                object view;
+                try { view = method.Invoke(null, new object[] { frame, thread }); }
+                catch (Exception exception) { throw Unavailable("Failed to open RawFrameDataView: " + exception.Message); }
+                return InitializeOwnedView(view, value => new RawHierarchyAccessor(value, value.GetType(), budget));
             }
 
-            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            /// <summary>raw view 初始化成功才转移 ownership；成员绑定失败必须立即释放原 view。</summary>
+            internal static T InitializeOwnedView<T>(object view, Func<object, T> initialize)
             {
-                RootItems = BuildHierarchyItems(view, hierarchyViewType, 0, top, maxDepth, 0)
-            });
-        }
-
-        // 递归构建调用树节点:按 top 限制每层子项数量、depth 限制最大深度,避免单帧树过大
-        private static List<HierarchyItem> BuildHierarchyItems(object view, Type viewType, int itemId, int top, int maxDepth, int depth)
-        {
-            var result = new List<HierarchyItem>();
-            if (depth > maxDepth) return result;
+                if (view == null) throw NoData();
+                if (initialize == null) throw new ArgumentNullException("initialize");
+                try { return initialize(view); }
+                catch
+                {
+                    (view as IDisposable)?.Dispose();
+                    throw;
+                }
+            }
 
-            var childrenMethod = viewType.GetMethod("GetItemChildren", new[] { typeof(int), typeof(List<int>) });
-            var nameMethod = viewType.GetMethod("GetItemName", new[] { typeof(int) });
-            var msMethod = viewType.GetMethod("GetItemThreadMS", new[] { typeof(int) });
+            internal static RawHierarchyAccessor InitializeForTests(object view, UnityCliRequestBudget budget)
+            {
+                return InitializeOwnedView(view, value => new RawHierarchyAccessor(value, value.GetType(), budget));
+            }
 
-            var childIds = new List<int>();
-            try { if (childrenMethod != null) childrenMethod.Invoke(view, new object[] { itemId, childIds }); }
-            catch { return result; }
+            internal int ChildCount(int sample, UnityCliRequestBudget budget) { return Convert.ToInt32(Invoke(childCountMethod, new object[] { sample }, budget), CultureInfo.InvariantCulture); }
 
-            var emitted = 0;
-            foreach (var childId in childIds)
+            /// <summary>Unity 的 raw samples 是先序扁平数组，递归后代数可直接确定子树右边界。</summary>
+            internal int SubtreeEndExclusive(int sample, UnityCliRequestBudget budget)
             {
-                if (emitted >= top) break;
-                string name = null;
-                double ms = 0;
-                try { if (nameMethod != null) name = nameMethod.Invoke(view, new object[] { childId }) as string; } catch { }
-                try { if (msMethod != null) { var v = msMethod.Invoke(view, new object[] { childId }); if (v is double d) ms = d; else if (v is float f) ms = f; } } catch { }
+                var recursiveChildren = Convert.ToInt32(Invoke(recursiveChildCountMethod, new object[] { sample }, budget), CultureInfo.InvariantCulture);
+                if (budget.IsExhausted) return sample + 1;
+                var end = (long)sample + recursiveChildren + 1L;
+                if (sample < 0 || sample >= sampleCount || recursiveChildren < 0 || end > sampleCount) throw InvalidPreorder();
+                return (int)end;
+            }
+
+            internal string Name(int sample, UnityCliRequestBudget budget) { return Invoke(nameMethod, new object[] { sample }, budget) as string; }
+            internal double Milliseconds(int sample, UnityCliRequestBudget budget) { return Convert.ToDouble(Invoke(millisecondsMethod, new object[] { sample }, budget), CultureInfo.InvariantCulture); }
 
-                var grandChildren = new List<int>();
-                try { if (childrenMethod != null) childrenMethod.Invoke(view, new object[] { childId, grandChildren }); } catch { }
+            public void Dispose() { (view as IDisposable)?.Dispose(); }
 
-                var item = new HierarchyItem
+            private object Invoke(MethodInfo method, object[] args, UnityCliRequestBudget budget)
+            {
+                if (!budget.TryConsumeReflectionCall()) return null;
+                try { return method.Invoke(view, args); }
+                catch (TargetInvocationException exception)
                 {
-                    Id = childId,
-                    Name = name ?? "(unknown)",
-                    Depth = depth,
-                    Ms = ms,
-                    SiblingCount = childIds.Count,
-                    ChildCount = grandChildren.Count,
-                    ChildrenTruncated = grandChildren.Count > top || (grandChildren.Count > 0 && depth + 1 > maxDepth)
-                };
-                if (grandChildren.Count > 0 && depth + 1 <= maxDepth)
+                    var inner = exception.InnerException ?? exception;
+                    throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_READ_FAILED", "Raw profiler hierarchy read failed: " + inner.GetType().Name + ".", "Record a fresh frame and restart pagination.");
+                }
+                catch (Exception exception)
                 {
-                    item.Children = BuildHierarchyItems(view, viewType, childId, top, maxDepth, depth + 1);
+                    throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_READ_FAILED", "Raw profiler hierarchy read failed: " + exception.GetType().Name + ".", "Record a fresh frame and restart pagination.");
                 }
-                result.Add(item);
-                emitted++;
             }
-            return result;
-        }
 
-        private static ProfilerHierarchyDetails HierarchyDetails(int frame, int threadIndex)
-        {
-            return new ProfilerHierarchyDetails
+            private static PropertyInfo ReflectProperty(Type type, string name, UnityCliRequestBudget budget)
+            {
+                if (!budget.TryConsumeReflectionCall()) return null;
+                return type.GetProperty(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
+            }
+
+            private static MethodInfo ReflectMethod(Type type, string name, Type[] parameters, UnityCliRequestBudget budget)
+            {
+                if (!budget.TryConsumeReflectionCall()) return null;
+                return type.GetMethod(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic, null, parameters, null);
+            }
+
+            private static bool ReadBool(PropertyInfo property, object target, UnityCliRequestBudget budget)
+            {
+                if (!budget.TryConsumeGetter() || !budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                return Convert.ToBoolean(property.GetValue(target, null), CultureInfo.InvariantCulture);
+            }
+
+            private static UnityCliBridge.BridgeCommandException Unavailable(string message)
+            {
+                return new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE", message, "Use an Editor exposing RawFrameDataView and record profiler frames before retrying.");
+            }
+
+            internal static UnityCliBridge.BridgeCommandException InvalidPreorder()
             {
-                Frame = frame,
-                Thread = threadIndex,
-                ProfilerRecording = ProfilerToolSupport.GetProfilerSessionEnabled()
-            };
+                return new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_READ_FAILED", "Raw profiler hierarchy preorder ranges are inconsistent.", "Record a fresh frame and restart pagination.");
+            }
+
+            private static UnityCliBridge.BridgeCommandException NoData()
+            {
+                return new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_NO_DATA", "No raw hierarchy data is available for the requested frame/thread.", "Record profiler frames, then query a valid frame and thread.");
+            }
         }
     }
 }

package/unitypkg/Editor/Tools/profiler/memory-snapshot/compare.cs

@@ -16,6 +16,7 @@ namespace UnityCli
         {
             [UnityCliRequired] public string SnapshotA { get; set; }
             [UnityCliRequired] public string SnapshotB { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -30,7 +31,7 @@ namespace UnityCli
         {
             Name = "profiler.memory-snapshot.compare",
             Summary = "Compare two .snap memory snapshots at file-level metadata (size delta, time delta).",
-            Description = "Compare two .snap memory snapshots at file-level metadata (size delta, time delta). For object-level diff, open both in the Memory Profiler window.",
+            Description = "Compare file metadata for two snapshot file names under Library/UnityCli/memory-snapshots. Arbitrary paths are rejected. Reads share the request node/getter/time/UTF-8 budget. For object-level diff, open both governed artifacts in the Memory Profiler window. Read-only in Edit and Play Mode.",
             Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
             DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
             Examples = new[] { new ToolExample { Description = "Compare two snapshots", Input = new Request { SnapshotA = "snap1.snap", SnapshotB = "snap2.snap" } } }
@@ -38,14 +39,14 @@ namespace UnityCli
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            var snapshotAPath = request.SnapshotA;
-            var snapshotBPath = request.SnapshotB;
-            if (string.IsNullOrEmpty(snapshotAPath) || string.IsNullOrEmpty(snapshotBPath))
+            if (string.IsNullOrEmpty(request.SnapshotA) || string.IsNullOrEmpty(request.SnapshotB))
             {
                 throw new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_PATH_REQUIRED",
                     "profiler.memory-snapshot.compare requires --snapshot-a and --snapshot-b.",
-                    "Pass two .snap file paths.");
+                    "Pass two .snap file names.");
             }
+            var snapshotAPath = ProfilerMemorySnapshotSupport.ResolveFinalPath(request.SnapshotA, ctx.RequestId);
+            var snapshotBPath = ProfilerMemorySnapshotSupport.ResolveFinalPath(request.SnapshotB, ctx.RequestId);
             if (!File.Exists(snapshotAPath))
             {
                 throw new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_NOT_FOUND",
@@ -59,6 +60,9 @@ namespace UnityCli
                     "Check the path or run profiler.memory-snapshot.list.");
             }
 
+            var budget = ctx.UseReadBudget(request.Budget);
+            if (!budget.TryConsumeNode() || !budget.TryConsumeNode() || !budget.TryConsumeGetter() || !budget.TryConsumeGetter())
+                throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             var fiA = new FileInfo(snapshotAPath);
             var fiB = new FileInfo(snapshotBPath);
             return new System.Threading.Tasks.ValueTask<Result>(new Result

package/unitypkg/Editor/Tools/profiler/memory-snapshot/list.cs

@@ -2,70 +2,72 @@
 using System;
 using System.Collections.Generic;
 using System.Globalization;
-using System.IO;
-using System.Reflection;
-using UnityEditor;
-using UnityEngine;
-using UnityEngine.Profiling;
 
 namespace UnityCli
 {
+    /// <summary>profiler.memory-snapshot.list — governed latest-100 catalog 的稳定续页。</summary>
     public class ProfilerMemorySnapshotListTool : IUnityCliTool<ProfilerMemorySnapshotListTool.Request, ProfilerMemorySnapshotListTool.Result>
     {
         public sealed class Request
         {
-            public string Path { get; set; }
+            [UnityCliRange(1L, 100L)] public int? PageSize { get; set; }
+            public string Cursor { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
             public List<MemorySnapshotEntry> Snapshots { get; set; }
-            public List<string> SearchedDirs { get; set; }
+            public string Root { get; set; }
+            public long Total { get; set; }
+            public string NextCursor { get; set; }
+            public bool Truncated { get; set; }
+            public string Generation { get; set; }
+            public UnityCliRequestBudgetUsage Budget { get; set; }
         }
 
         public ToolDescriptor Describe() => new()
         {
             Name = "profiler.memory-snapshot.list",
-            Summary = "List .snap memory snapshot files in the default capture directories or a custom path.",
-            Description = "List .snap memory snapshot files in the default capture directories or a custom path. This reads file metadata only and does not open or modify snapshots.",
-            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            Summary = "Page the governed latest-100 memory snapshot catalog with stable generation continuation.",
+            Description = "List only .snap artifacts under Library/UnityCli/memory-snapshots. pageSize is 1..100 (default 25); nextCursor binds the exact bounded catalog generation and stale cursors return E_CONTINUATION_STALE. total is exact because the product catalog is capped at 100 snapshots and 8 GiB. Metadata reads and UTF-8 output use the shared request budget. Read-only in Edit and Play Mode and never scans arbitrary directories.",
+            Group = "profiler", DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
             DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
-            Examples = new[] { new ToolExample { Description = "List snapshots in default dirs", Input = new Request { } } }
+            Examples = new[] { new ToolExample { Description = "List the first snapshot page", Input = new Request { PageSize = 25 } } }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            var searchPath = request.Path;
-            var dirs = new List<string>();
-            if (!string.IsNullOrEmpty(searchPath))
+            request = request ?? new Request();
+            var budget = ctx.UseReadBudget(request.Budget);
+            var files = ProfilerMemorySnapshotSupport.Catalog(budget);
+            var generation = ProfilerMemorySnapshotSupport.CatalogGeneration(files, budget);
+            var offset = 0;
+            if (!string.IsNullOrEmpty(request.Cursor))
             {
-                dirs.Add(searchPath);
+                string position;
+                if (!UnityCliContinuationToken.TryParse(request.Cursor, "profiler.memory-snapshot.list", generation, out position)
+                    || !int.TryParse(position, NumberStyles.Integer, CultureInfo.InvariantCulture, out offset) || offset < 0 || offset > files.Count)
+                    throw new UnityCliBridge.BridgeCommandException("E_CONTINUATION_STALE", "The memory snapshot continuation does not match the current catalog generation.", "Start a new snapshot list without cursor.");
             }
-            else
-            {
-                dirs.Add(Path.Combine(Application.temporaryCachePath, "MemoryCaptures"));
-                dirs.Add(Path.Combine(Application.dataPath, "..", "MemoryCaptures"));
-            }
-
+            var pageSize = request.PageSize ?? 25;
             var snapshots = new List<MemorySnapshotEntry>();
-            foreach (var dir in dirs)
+            var index = offset;
+            while (index < files.Count && snapshots.Count < pageSize)
             {
-                if (!Directory.Exists(dir)) continue;
-                foreach (var file in Directory.GetFiles(dir, "*.snap"))
-                {
-                    var fi = new FileInfo(file);
-                    snapshots.Add(new MemorySnapshotEntry
-                    {
-                        Path = fi.FullName,
-                        SizeBytes = fi.Length,
-                        Created = fi.CreationTimeUtc.ToString("O", CultureInfo.InvariantCulture)
-                    });
-                }
+                if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeNode() || !budget.TryConsumeGetter() || !budget.TryConsumeGetter()) break;
+                var item = MemorySnapshotEntry.FromFileInfo(files[index]);
+                if (!budget.TryReserveSerializedUtf8(item.Path) || !budget.TryReserveSerializedUtf8(item.Created)) break;
+                snapshots.Add(item);
+                index++;
             }
+            if (index == offset && index < files.Count)
+                throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension ?? "scannedRecords");
+            var next = index < files.Count ? UnityCliContinuationToken.Create("profiler.memory-snapshot.list", generation, index.ToString(CultureInfo.InvariantCulture)) : null;
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {
-                Snapshots = snapshots,
-                SearchedDirs = dirs
+                Snapshots = snapshots, Root = ProfilerMemorySnapshotSupport.Root, Total = files.Count,
+                NextCursor = next, Truncated = next != null, Generation = generation, Budget = budget.Usage()
             });
         }
     }