@alpsckr/unitycli 0.4.3 → 0.4.4

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

@@ -1,146 +1,148 @@
 #if UNITY_EDITOR
 using System;
 using System.Collections.Generic;
-using System.Globalization;
 using System.IO;
 using System.Reflection;
 using System.Threading;
 using System.Threading.Tasks;
-using UnityEditor;
-using UnityEngine;
 
 namespace UnityCli
 {
-    /// <summary>
-    /// profiler.memory-snapshot.take — 采集内存快照(.snap)。
-    /// MemoryProfiler.TakeSnapshot 的未来帧回调通过统一 wait scheduler 承接。
-    /// </summary>
+    /// <summary>profiler.memory-snapshot.take — governed pending publication 与唯一 callback terminal。</summary>
     public class ProfilerMemorySnapshotTakeTool : IUnityCliTool<ProfilerMemorySnapshotTakeTool.Request, ProfilerMemorySnapshotTakeTool.Result>
     {
         public sealed class Request
         {
             public string Path { get; set; }
+            [UnityCliRange(1048576L, ProfilerMemorySnapshotSupport.AbsoluteSnapshotBytes)] public long? MaxBytes { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
+            public string Path { get; set; }
             public long SizeBytes { get; set; }
-            public List<ProfilerPlannedEffect> PlannedEffects { get; set; }
+            public long RetainedCountLimit { get; set; }
+            public long RetainedBytesLimit { get; set; }
+            [UnityCliItemsRange(0, 1)] public List<ProfilerPlannedEffect> PlannedEffects { get; set; }
         }
 
         public ToolDescriptor Describe() => new()
         {
             Name = "profiler.memory-snapshot.take",
-            Summary = "Capture a memory snapshot (.snap) via MemoryProfiler using the unified callback wait path.",
-            Description = "Capture a memory snapshot (.snap) via MemoryProfiler. Requires package com.unity.memoryprofiler. The tool waits for TakeSnapshot's future-frame callback through the framework wait scheduler instead of a custom deferred interface.",
-            Group = "profiler",DestructiveHint = true, SideEffects = new[] { "memory-snapshot-write" }, Target = "editor", PlayModeSupport = "supported",
-            RequiresPackages = new[] { "com.unity.memoryprofiler" },
-            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
-            Examples = new[] { new ToolExample { Description = "Take a memory snapshot to a custom path", Input = new Request { Path = "Artifacts/snap1.snap" } } }
+            Summary = "Capture one governed Memory Profiler snapshot with bounded retention and one callback terminal.",
+            Description = "Capture a .snap artifact only under Library/UnityCli/memory-snapshots. path is a file name, not a directory. maxBytes defaults to and cannot exceed 4 GiB. Successful publication keeps the newest 100 snapshots while enforcing an 8 GiB directory ceiling. A pending same-root file is atomically moved only after a successful non-empty callback; timeout, cancellation, domain reload, late callback and write faults share one terminal and clean pending/orphan files. Requires com.unity.memoryprofiler. Available in Edit and Play Mode; it writes a project-local Library artifact but no Assets content.",
+            Group = "profiler", DestructiveHint = false, SideEffects = new[] { "memory-snapshot-write" }, Target = "editor", PlayModeSupport = "supported",
+            RequiresPackages = new[] { "com.unity.memoryprofiler" }, DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Take a governed snapshot", Input = new Request { Path = "capture.snap", MaxBytes = 1073741824L } } }
         };
 
         public async ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default)
         {
-            var profilerType = ProfilerToolSupport.MemoryProfilerType();
-            if (profilerType == null)
-            {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_PACKAGE_MISSING",
-                    "Package com.unity.memoryprofiler is required for memory snapshots.",
-                    "Install com.unity.memoryprofiler via the Package Manager.");
-            }
-
-            var outputPath = request.Path;
-            if (string.IsNullOrEmpty(outputPath))
-            {
-                var dir = Path.Combine(Application.temporaryCachePath, "MemoryCaptures");
-                Directory.CreateDirectory(dir);
-                outputPath = Path.Combine(dir, "snapshot_" + DateTime.Now.ToString("yyyyMMdd_HHmmss", CultureInfo.InvariantCulture) + ".snap");
-            }
-
-            var callbackType = typeof(Action<string, bool>);
-            var captureFlagsType = ProfilerToolSupport.FindType("Unity.Profiling.Memory.CaptureFlags")
-                ?? ProfilerToolSupport.FindType("UnityEngine.Profiling.Memory.Experimental.CaptureFlags");
-            MethodInfo takeMethod = null;
-            object[] invokeArgs = null;
-            if (captureFlagsType != null)
+            request = request ?? new Request();
+            var requestBudget = ctx.UseReadBudget(request.Budget);
+            requestBudget.CheckpointOrThrow();
+            var profilerType = ProfilerToolSupport.MemoryProfilerType(requestBudget);
+            if (profilerType == null) throw new UnityCliBridge.BridgeCommandException("E_PROFILER_PACKAGE_MISSING", "Package com.unity.memoryprofiler is required for memory snapshots.", "Install com.unity.memoryprofiler through Package Manager.");
+            var finalPath = ProfilerMemorySnapshotSupport.ResolveFinalPath(request.Path, ctx.RequestId);
+            if (File.Exists(finalPath)) throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Snapshot output already exists: " + finalPath, "Choose another .snap file name.");
+            var maxBytes = request.MaxBytes ?? ProfilerMemorySnapshotSupport.AbsoluteSnapshotBytes;
+            var pendingPath = ProfilerMemorySnapshotSupport.AcquirePendingPath(ctx.RequestId);
+            SnapshotBinding binding;
+            try
             {
-                takeMethod = profilerType.GetMethod("TakeSnapshot", new[] { typeof(string), callbackType, captureFlagsType });
+                binding = ResolveTakeSnapshot(profilerType, pendingPath, requestBudget);
+                ctx.CommitEffect();
             }
-            if (takeMethod != null)
+            catch
             {
-                invokeArgs = new object[] { outputPath, null, Enum.ToObject(captureFlagsType, 0) };
+                ProfilerMemorySnapshotSupport.ReleasePendingPath(pendingPath);
+                throw;
             }
-            else
+            try
             {
-                takeMethod = profilerType.GetMethod("TakeSnapshot", new[] { typeof(string), callbackType });
-            }
-            if (takeMethod == null)
-            {
-                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_API_UNSUPPORTED",
-                    "MemoryProfiler.TakeSnapshot API not found.",
-                    "The installed com.unity.memoryprofiler version may be incompatible.");
-            }
-
-            ctx.CommitEffect();
-            return await ctx.Wait.ForCallback<Result>((complete, fail) =>
-            {
-                var callback = new Action<string, bool>((capturedPath, captureResult) =>
+                var result = await ctx.Wait.ForCallback<Result>((complete, fail) =>
                 {
-                    try
+                    var callback = new Action<string, bool>((capturedPath, succeeded) =>
                     {
-                        if (!captureResult)
+                        try
                         {
-                            fail(new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_FAILED",
-                                "Snapshot capture reported failure for path: " + outputPath,
-                                "Check Unity Console for Memory Profiler errors."));
-                            return;
+                            var accepted = complete(() =>
+                            {
+                                requestBudget.ResumeAfterWait();
+                                requestBudget.CheckpointOrThrow();
+                                if (!succeeded) throw ProfilerMemorySnapshotSupport.Error("E_PROFILER_SNAPSHOT_FAILED", "MemoryProfiler reported snapshot failure.", "Inspect Unity Console before retrying.");
+                                var info = ProfilerMemorySnapshotSupport.Publish(capturedPath, pendingPath, finalPath, maxBytes, requestBudget);
+                                if (!requestBudget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(requestBudget.ExhaustedDimension);
+                                return new Result
+                                {
+                                    Path = finalPath,
+                                    SizeBytes = info.Length,
+                                    RetainedCountLimit = ProfilerMemorySnapshotSupport.RetainedSnapshotCount,
+                                    RetainedBytesLimit = ProfilerMemorySnapshotSupport.RetainedSnapshotBytes,
+                                    PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.memory-snapshot.take", Path = finalPath } }
+                                };
+                            });
+                            if (!accepted) ProfilerMemorySnapshotSupport.RequestPendingCleanup(pendingPath);
                         }
-
-                        var finalPath = capturedPath ?? outputPath;
-                        var info = new FileInfo(finalPath);
-                        if (!info.Exists || info.Length <= 0)
+                        finally
                         {
-                            fail(new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_ARTIFACT_MISSING",
-                                "MemoryProfiler reported success without a non-empty snapshot artifact: " + finalPath,
-                                "Check available disk space and the Unity Console, then retry the snapshot."));
-                            return;
+                            ProfilerMemorySnapshotSupport.ReleasePendingPath(pendingPath);
                         }
-                        complete(new Result
-                        {
-                            SizeBytes = info.Length,
-                            PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.memory-snapshot.take", Path = finalPath } }
-                        });
+                    });
+                    binding.SetCallback(callback);
+                    try { binding.Invoke(); }
+                    catch (TargetInvocationException exception)
+                    {
+                        fail(exception.InnerException ?? exception);
+                        ProfilerMemorySnapshotSupport.ReleasePendingPath(pendingPath);
                     }
                     catch (Exception exception)
                     {
-                        fail(exception);
+                        fail(ProfilerMemorySnapshotSupport.Error("E_PROFILER_SNAPSHOT_FAILED", "Snapshot capture failed: " + exception.Message, "Inspect Unity Console and the Memory Profiler package."));
+                        ProfilerMemorySnapshotSupport.ReleasePendingPath(pendingPath);
                     }
-                });
+                }, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct, () => ProfilerMemorySnapshotSupport.RequestPendingCleanup(pendingPath));
+                requestBudget.ResumeAfterWait();
+                return result;
+            }
+            catch
+            {
+                ProfilerMemorySnapshotSupport.RequestPendingCleanup(pendingPath);
+                throw;
+            }
+        }
 
-                if (invokeArgs != null)
-                {
-                    invokeArgs[1] = callback;
-                }
-                else
-                {
-                    invokeArgs = new object[] { outputPath, callback };
-                }
+        private static SnapshotBinding ResolveTakeSnapshot(Type profilerType, string pendingPath, UnityCliRequestBudget budget)
+        {
+            var callbackType = typeof(Action<string, bool>);
+            var captureFlagsType = ProfilerToolSupport.FindType("Unity.Profiling.Memory.CaptureFlags", budget)
+                ?? ProfilerToolSupport.FindType("UnityEngine.Profiling.Memory.Experimental.CaptureFlags", budget);
+            MethodInfo method = null;
+            object[] args = null;
+            if (captureFlagsType != null)
+            {
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                method = profilerType.GetMethod("TakeSnapshot", new[] { typeof(string), callbackType, captureFlagsType });
+            }
+            if (method != null) args = new object[] { pendingPath, null, Enum.ToObject(captureFlagsType, 0) };
+            else
+            {
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                method = profilerType.GetMethod("TakeSnapshot", new[] { typeof(string), callbackType });
+                if (method != null) args = new object[] { pendingPath, null };
+            }
+            if (method == null) throw new UnityCliBridge.BridgeCommandException("E_PROFILER_API_UNSUPPORTED", "MemoryProfiler.TakeSnapshot API is unavailable.", "Install a supported com.unity.memoryprofiler version.");
+            return new SnapshotBinding(method, args);
+        }
 
-                try
-                {
-                    takeMethod.Invoke(null, invokeArgs);
-                }
-                catch (TargetInvocationException exception)
-                {
-                    fail(exception.InnerException ?? exception);
-                }
-                catch (Exception exception)
-                {
-                    fail(new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_FAILED",
-                        "Snapshot capture failed: " + exception.Message,
-                        "Check Unity Console and the Memory Profiler package."));
-                }
-            }, TimeSpan.FromSeconds(30), ct);
+        private sealed class SnapshotBinding
+        {
+            private readonly MethodInfo method;
+            private readonly object[] args;
+            internal SnapshotBinding(MethodInfo method, object[] args) { this.method = method; this.args = args; }
+            internal void SetCallback(Action<string, bool> callback) { args[1] = callback; }
+            internal void Invoke() { method.Invoke(null, args); }
         }
     }
 }

package/unitypkg/Editor/Tools/project/info.cs

@@ -25,7 +25,7 @@ namespace UnityCli.Tools.Project
         {
             Name = "project.info", Summary = "Project metadata: name, path, Unity version, and overall project structure.",
             Description = "Project metadata: name, path, Unity version, and overall project structure.",
-            DestructiveHint = false,
+            DestructiveHint = false,
             Group = "project",
             Target = "editor",
             PlayModeSupport = "supported",

package/unitypkg/Editor/Tools/project/layers.cs

@@ -28,7 +28,7 @@ namespace UnityCli.Tools.Project
         {
             Name = "project.layers", Summary = "List all layers defined in the project's Tag Manager.",
             Description = "List all layers defined in the project's Tag Manager.",
-            DestructiveHint = false,
+            DestructiveHint = false,
             Group = "project",
             Target = "editor",
             PlayModeSupport = "supported",

package/unitypkg/Editor/Tools/project/tags.cs

@@ -21,7 +21,7 @@ namespace UnityCli.Tools.Project
         {
             Name = "project.tags", Summary = "List all tags defined in the project's Tag Manager.",
             Description = "List all tags defined in the project's Tag Manager.",
-            DestructiveHint = false,
+            DestructiveHint = false,
             Group = "project",
             Target = "editor",
             PlayModeSupport = "supported",

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

@@ -16,15 +16,16 @@ namespace UnityCli
             [UnityCliRequired]
             public string MethodName { get; set; }
             [UnityCliAnyJson] public object Args { get; set; }
-            public List<string> ParameterTypes { get; set; }
+            [UnityCliItemsRange(0, 256)] public List<string> ParameterTypes { get; set; }
             [UnityCliAnyJson] public Dictionary<string, object> InstanceRef { get; set; }
             [UnityCliRequired] public UnityCliCompletionProbe CompletionProbe { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
             [UnityCliAnyJson] public object Data { get; set; }
-            public List<PlannedEffect> PlannedEffects { get; set; }
+            [UnityCliItemsRange(0, 1)] public List<PlannedEffect> PlannedEffects { get; set; }
             public UnityCliCompletionProbeReadback Completion { get; set; }
         }
 
@@ -39,7 +40,7 @@ namespace UnityCli
         {
             Name = "reflection.method.call",
             Summary = "Call one synchronous C# method in the live Editor and prove declared state through a read Tool.",
-            Description = "Resolve the exact type, overload, arguments, and optional instance before invoking one synchronous method. completionProbe is mandatory and proves declared before/after state through an eligible read Tool in the same Editor turn. Task/ValueTask, iterator, yield, and AsyncOperation methods are rejected; a method return value is never accepted as completion proof.",
+            Description = "Resolve the exact type, overload, arguments, and optional instance under one request budget before invoking one synchronous method. completionProbe is mandatory and proves declared before/after state through an eligible read Tool in the same Editor turn. Candidate methods, parameters, signatures, reflection work, monotonic main-thread time, and output bytes are globally bounded in dry-run and execution. Task/ValueTask, iterator, yield, and AsyncOperation methods are rejected; a method return value is never accepted as completion proof.",
             Group = "reflection",
             DestructiveHint = true,
             SideEffects = new[] { "arbitrary-method-invocation" },
@@ -79,13 +80,14 @@ namespace UnityCli
                     "Run tools run reflection.method.find to discover methods, then retry with the required target fields.");
             }
 
+            var readBudget = ctx.UseReadBudget(request.Budget);
             var bindings = BindingFlags.Public | BindingFlags.NonPublic | BindingFlags.Instance | BindingFlags.Static;
-            // overload、参数与 instance 都是可预见校验，必须在 effect barrier 前完成。
+            // overload、参数与 instance 都是可预见校验，必须在 effect barrier 前完成并使用同一 budget。
             var prepared = UnityCliBridge.ReflectionInvoker.PrepareCall(
                 request.TypeName, request.MethodName,
-                request.Args, request.ParameterTypes, request.InstanceRef, bindings);
+                request.Args, request.ParameterTypes, request.InstanceRef, bindings, readBudget);
 
-            // dry-run 必须在任何反射调用前返回，任意方法即使看似只读也不能在预览阶段执行。
+            // dry-run 只完成有界 preparation，不执行目标方法。
             if (ctx.DryRun)
             {
                 return new System.Threading.Tasks.ValueTask<Result>(new Result
@@ -98,7 +100,7 @@ namespace UnityCli
             }
 
             Dictionary<string, object> data = null;
-            var completion = ctx.RunCompletionProbe(request.CompletionProbe, () => data = UnityCliBridge.ReflectionInvoker.InvokePrepared(prepared));
+            var completion = ctx.RunCompletionProbe(request.CompletionProbe, () => data = UnityCliBridge.ReflectionInvoker.InvokePrepared(prepared, readBudget));
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {
                 Data = data,

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

@@ -4,67 +4,57 @@ using System.Reflection;
 
 namespace UnityCli
 {
-    /// <summary>
-    /// reflection.method.find — 查找类型的公开/私有/静态/实例方法。只读。
-    /// </summary>
+    /// <summary>reflection.method.find — stable raw method ordinal pagination under one reflection budget。</summary>
     public class ReflectionMethodFindTool : IUnityCliTool<ReflectionMethodFindTool.Request, ReflectionMethodFindTool.Result>
     {
         public sealed class Request
         {
-            [UnityCliRequired]
-            public string TypeName { get; set; }
+            [UnityCliRequired] public string TypeName { get; set; }
             public string MethodName { get; set; }
             public bool IncludePrivate { get; set; }
             public bool IncludeStatic { get; set; } = true;
             public bool IncludeInstance { get; set; } = true;
+            [UnityCliRange(1L, 500L)] public int? PageSize { get; set; }
+            public string Cursor { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
-            public long Count { get; set; }
+            public long Total { get; set; }
+            public long ReturnedCount { get; set; }
             public List<UnityCliBridge.ReflectionMethodDescriptor> Methods { 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 = "reflection.method.find",
-            Summary = "Find C# methods on a type by name; does not limit public/private/static/instance scope.",
-            Description = "Find methods on a live C# type. Does not limit public/private/static/instance scope. Use the returned signatures to construct reflection.method.call calls. Read-only.",
-            Group = "reflection",
-            DestructiveHint = false,
-            Target = "editor",
-            PlayModeSupport = "supported",
-            DefaultTimeoutMs = 30000,
-            MaxTimeoutMs = 600000,
-            Examples = new[]
-            {
-                new ToolExample { Description = "Find Translate methods on Transform", Input = new Request { TypeName = "UnityEngine.Transform", MethodName = "Translate" } }
-            }
+            Summary = "Page live C# method signatures by exact type/name and visibility/static scope under one reflection budget.",
+            Description = "Find methods on one exact live type. includePrivate defaults false; includeStatic/includeInstance default true. pageSize is 1..500 (default 100). Filtering advances over raw MethodInfo ordinals, so sparse searches remain bounded and total is the raw method count rather than a fabricated filtered total. Each method and parameter descriptor consumes the shared scan/node/reflection/monotonic-time/UTF-8 budget; defaults are 10000/4096/4096/250 ms/1 MiB and maxima are 100000/20000/20000/2000 ms/8 MiB. A parameter-heavy method may return parametersTruncated with parameterCount. nextCursor binds type, flags, name filter and listener/assembly generation. Read-only in Edit and Play Mode.",
+            Group = "reflection", DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Find Translate overloads", Input = new Request { TypeName = "UnityEngine.Transform", MethodName = "Translate", PageSize = 100 } } }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            if (string.IsNullOrEmpty(request.TypeName))
-            {
-                throw new UnityCliBridge.BridgeCommandException("E_TYPE_NAME_REQUIRED",
-                    "reflection.method.find requires typeName.",
-                    "Pass --input '{\"typeName\":\"UnityEngine.Transform\",\"methodName\":\"Translate\"}'.");
-            }
-
-            // 构建 BindingFlags:默认包含公开/非公开,按 includeStatic/includeInstance 调整
-            var bindings = BindingFlags.Public | BindingFlags.NonPublic;
-            if (request.IncludeStatic) bindings |= BindingFlags.Static;
-            if (request.IncludeInstance) bindings |= BindingFlags.Instance;
-            if (!request.IncludePrivate)
-            {
-                bindings = BindingFlags.Public | (request.IncludeStatic ? BindingFlags.Static : BindingFlags.Default) | (request.IncludeInstance ? BindingFlags.Instance : BindingFlags.Default);
-            }
-
-            var methods = UnityCliBridge.ReflectionInvoker.FindMethods(request.TypeName, request.MethodName, bindings);
+            if (request == null || string.IsNullOrEmpty(request.TypeName))
+                throw new UnityCliBridge.BridgeCommandException("E_TYPE_NAME_REQUIRED", "reflection.method.find requires typeName.", "Pass a full live C# type name.");
+            var bindings = (request.IncludePrivate ? BindingFlags.Public | BindingFlags.NonPublic : BindingFlags.Public)
+                | (request.IncludeStatic ? BindingFlags.Static : BindingFlags.Default)
+                | (request.IncludeInstance ? BindingFlags.Instance : BindingFlags.Default);
+            if (!request.IncludeStatic && !request.IncludeInstance)
+                throw new UnityCliBridge.BridgeCommandException("E_REFLECTION_SCOPE_INVALID", "At least one of includeStatic/includeInstance must be true.", "Enable static methods, instance methods, or both.");
+            var budget = ctx.UseReadBudget(request.Budget);
+            var page = UnityCliBridge.ReflectionInvoker.FindMethods(request.TypeName, request.MethodName, bindings, request.PageSize ?? 100, request.Cursor, budget);
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {
-                Count = methods.Count,
-                Methods = methods
+                Total = page.Total, ReturnedCount = page.Methods.Count, Methods = page.Methods,
+                NextCursor = page.NextCursor, Truncated = page.Truncated, Generation = page.Generation, Budget = budget.Usage()
             });
         }
     }

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

@@ -1,54 +1,50 @@
 #if UNITY_EDITOR
-using System.Collections.Generic;
-
 namespace UnityCli
 {
-    /// <summary>
-    /// type.schema — 为 live C# / Unity 类型生成带 $defs 的 JSON Schema。只读。
-    /// </summary>
+    /// <summary>type.schema — live 类型 schema 的有界成员/definition 分页。</summary>
     public class TypeSchemaTool : IUnityCliTool<TypeSchemaTool.Request, TypeSchemaTool.Result>
     {
         public sealed class Request
         {
-            [UnityCliRequired]
-            public string TypeName { get; set; }
-            public int MaxDepth { get; set; } = 3;
+            [UnityCliRequired] public string TypeName { get; set; }
+            [UnityCliRange(0L, 16L)] public int? MaxDepth { get; set; }
+            [UnityCliRange(1L, 512L)] public int? MaxMembers { get; set; }
+            [UnityCliRange(1L, 256L)] public int? MaxDefinitions { get; set; }
+            [UnityCliRange(1L, 256L)] public int? PageSize { get; set; }
+            public string Cursor { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
         {
             [UnityCliAnyJson] public object Schema { get; set; }
+            public bool Truncated { get; set; }
+            public string NextCursor { get; set; }
+            public string Generation { get; set; }
+            public UnityCliRequestBudgetUsage Budget { get; set; }
         }
 
         public ToolDescriptor Describe() => new()
         {
             Name = "type.schema",
-            Summary = "Generate a JSON Schema for a live C# type with $defs.",
-            Description = "Generate a JSON Schema (with $defs) for a live C# or Unity type. Read-only. Use the schema to understand the structure of objects before calling object.get-data or object.modify.",
-            Group = "reflection",
-            DestructiveHint = false,
-            Target = "editor",
-            PlayModeSupport = "supported",
-            DefaultTimeoutMs = 30000,
-            MaxTimeoutMs = 600000,
-            Examples = new[]
-            {
-                new ToolExample { Description = "Get schema for Rigidbody", Input = new Request { TypeName = "UnityEngine.Rigidbody" } }
-            }
+            Summary = "Page a live C# type schema under global depth, member, definition, reflection and byte ceilings.",
+            Description = "Generate a JSON Schema page for one live C# type. maxDepth is 0..16 (default 3), maxMembers 1..512 (default 256), maxDefinitions 1..256 (default 128), and pageSize 1..256 (default 64). Primitive, enum, array, and dictionary roots use the same classification as recursive values and do not expose continuation; only object roots page bounded public member metadata by raw ordinal. nextCursor binds listener/assembly generation, the member fingerprint, and all structural limits. Recursive definitions, member candidates, interfaces, and friendly type names share the same scan/member/node/reflection/monotonic-time/UTF-8 budget (defaults 10000/4096/4096/250 ms/1 MiB; maxima 100000/20000/20000/2000 ms/8 MiB). Assembly reload or compilation invalidates the bounded type cache and old cursors. Read-only in Edit and Play Mode.",
+            Group = "reflection", DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read the first Rigidbody schema page", Input = new Request { TypeName = "UnityEngine.Rigidbody", PageSize = 64 } } }
         };
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
-            if (string.IsNullOrEmpty(request.TypeName))
-            {
-                throw new UnityCliBridge.BridgeCommandException("E_TYPE_NAME_REQUIRED",
-                    "type.schema requires typeName.",
-                    "Pass --input '{\"typeName\":\"UnityEngine.Rigidbody\"}'.");
-            }
-            var schema = UnityCliBridge.TypeSchemaGenerator.Generate(request.TypeName, request.MaxDepth);
+            if (request == null || string.IsNullOrEmpty(request.TypeName))
+                throw new UnityCliBridge.BridgeCommandException("E_TYPE_NAME_REQUIRED", "type.schema requires typeName.", "Pass a full live C# type name.");
+            var budget = ctx.UseReadBudget(request.Budget);
+            var page = UnityCliBridge.TypeSchemaGenerator.Generate(request.TypeName, request.MaxDepth ?? 3, request.MaxMembers ?? 256,
+                request.MaxDefinitions ?? 128, request.PageSize ?? 64, request.Cursor, budget);
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {
-                Schema = schema
+                Schema = page.Data, Truncated = page.Truncated, NextCursor = page.NextCursor,
+                Generation = page.Generation, Budget = budget.Usage()
             });
         }
     }

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

@@ -8,7 +8,7 @@ namespace UnityCli
         /// <summary>scene.gameobject.component 只读 Tool：只读一个组件预览。</summary>
         public sealed class SceneGameObjectComponentTool : IUnityCliTool<SceneGameObjectComponentTool.Request, SceneGameObjectComponentTool.Result>
         {
-            public sealed class Request { public string Target { get; set; } public int Id { get; set; } public string Path { get; set; } public string Component { get; set; } }
+            public sealed class Request { public string Target { get; set; } public int Id { get; set; } public string Path { get; set; } public string Component { get; set; } public UnityCliReadBudgetInput Budget { get; set; } }
             public sealed class Result { public GameObjectRef GameObject { get; set; } public ComponentInfo Component { get; set; } }
             public sealed class GameObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } }
             public sealed class ComponentInfo
@@ -44,16 +44,19 @@ namespace UnityCli
             public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
             {
                 request = request ?? new Request();
-                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path);
+                var budget = ctx.UseReadBudget(request.Budget);
+                var gameObject = ResolveSceneContextGameObject(request.Target, request.Id == 0 ? (int?)null : request.Id, request.Path, budget);
                 if (string.IsNullOrEmpty(request.Component))
                     throw new BridgeCommandException("E_COMPONENT_TYPE_REQUIRED", "scene.gameobject.component requires component.", "Pass input component with a Unity component type name.");
-                var component = ResolveComponent(gameObject, request.Component);
+                var component = ResolveSceneContextComponent(gameObject, request.Component, budget);
                 if (component == null)
                     throw new BridgeCommandException("E_COMPONENT_NOT_FOUND", "Component not found on target: " + request.Component, "Run tools run scene.gameobject.components with the same target/path/id to list available component names.");
+                if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var componentType = component.GetType();
                 var result = new Result
                 {
-                    GameObject = new GameObjectRef { Id = gameObject.GetInstanceID(), Name = gameObject.name, Path = HierarchyPath(gameObject) },
-                    Component = new ComponentInfo { Type = component.GetType().Name, FullName = component.GetType().FullName, Enabled = ComponentEnabled(component), Properties = SceneContextComponentReadableProperties(component) }
+                    GameObject = new GameObjectRef { Id = ConsumeSceneGetter(budget, gameObject.GetInstanceID), Name = ConsumeSceneGetter(budget, () => gameObject.name), Path = GameObjectToolSupport.HierarchyPath(gameObject, budget) },
+                    Component = new ComponentInfo { Type = componentType.Name, FullName = componentType.FullName, Enabled = GameObjectToolSupport.ComponentEnabled(component, budget), Properties = SceneContextComponentReadableProperties(component, budget) }
                 };
                 return new System.Threading.Tasks.ValueTask<Result>(result);
             }

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

@@ -17,12 +17,13 @@ namespace UnityCli
                 public int Id { get; set; }
                 public string Path { get; set; }
                 public bool IncludeProperties { get; set; } = true;
+                public UnityCliReadBudgetInput Budget { get; set; }
             }
 
             public sealed class Result
             {
                 public GameObjectRef GameObject { get; set; }
-                public List<ComponentInfo> Components { get; set; }
+                [UnityCliItemsRange(0, ObjectRefResolver.AbsoluteMaxBatchItems)] public List<ComponentInfo> Components { get; set; }
                 public long Count { get; set; }
             }
 
@@ -46,7 +47,7 @@ namespace UnityCli
                 Name = "scene.gameobject.components",
                 Summary = "List components attached to one GameObject, optionally including readable property previews.",
                 Description = "Lightweight list of components attached to a GameObject: type names, enabled state, and optional readable property preview. Use this before component.get/component.modify to choose component name or index. Does not return every serialized field; use component.get for deep component data.",
-                DestructiveHint = false,
+                DestructiveHint = false,
                 Group = "scene",
                 Target = "editor",
                 PlayModeSupport = "supported",
@@ -56,16 +57,18 @@ namespace UnityCli
             /// <summary>解析目标并直接构造组件列表 DTO，不经过 JSON 字符串。</summary>
             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);
                 var id = request.Id == 0 ? (int?)null : request.Id;
-                var gameObject = ResolveSceneContextGameObject(request.Target, id, request.Path);
-                var components = SceneContextComponentDetails(gameObject, request.IncludeProperties);
+                var gameObject = ResolveSceneContextGameObject(request.Target, id, request.Path, budget);
+                var components = SceneContextComponentDetails(gameObject, request.IncludeProperties, budget);
                 return new System.Threading.Tasks.ValueTask<Result>(new Result
                 {
                     GameObject = new GameObjectRef
                     {
-                        Id = gameObject.GetInstanceID(),
-                        Name = gameObject.name,
-                        Path = HierarchyPath(gameObject)
+                        Id = ConsumeSceneGetter(budget, gameObject.GetInstanceID),
+                        Name = ConsumeSceneGetter(budget, () => gameObject.name),
+                        Path = GameObjectToolSupport.HierarchyPath(gameObject, budget)
                     },
                     Components = components,
                     Count = components.Count