@alpsckr/unitycli 0.4.3 → 0.4.5

package/unitypkg/Editor/ProjectTools/UnityCliSchemaDeriver.cs

@@ -38,7 +38,7 @@ namespace UnityCli
                     return new Dictionary<string, object> { { "type", "object" }, { "additionalProperties", AnyJsonSchema() } };
                 Type anyElement;
                 if (TryElementType(rawType, out anyElement))
-                    return new Dictionary<string, object> { { "type", "array" }, { "items", AnyJsonSchema() } };
+                    return ItemsRangeSchema(new Dictionary<string, object> { { "type", "array" }, { "items", AnyJsonSchema() } }, member, path);
                 return AnyJsonSchema();
             }
 
@@ -46,10 +46,10 @@ namespace UnityCli
             if (nullableType != null)
             {
                 if (member != null && member.IsDefined(typeof(UnityCliRequiredAttribute), true))
-                    return BuildSchema(nullableType, path, definitions, null, false);
+                    return BuildSchema(nullableType, path, definitions, member, false);
                 return new Dictionary<string, object>
                 {
-                    { "oneOf", new object[] { BuildSchema(nullableType, path, definitions, null, false), new Dictionary<string, object> { { "type", "null" } } } }
+                    { "oneOf", new object[] { BuildSchema(nullableType, path, definitions, member, false), new Dictionary<string, object> { { "type", "null" } } } }
                 };
             }
 
@@ -67,8 +67,8 @@ namespace UnityCli
             }
             if (rawType == typeof(char)) return TypeSchema("string");
             if (rawType == typeof(bool)) return TypeSchema("boolean");
-            if (IsInteger(rawType)) return IntegerSchema(rawType);
-            if (IsNumber(rawType)) return TypeSchema("number");
+            if (IsInteger(rawType)) return NumericRangeSchema(IntegerSchema(rawType), member, path);
+            if (IsNumber(rawType)) return NumericRangeSchema(TypeSchema("number"), member, path);
             if (rawType.IsEnum)
             {
                 return new Dictionary<string, object>
@@ -91,11 +91,11 @@ namespace UnityCli
             Type elementType;
             if (TryElementType(rawType, out elementType))
             {
-                return new Dictionary<string, object>
+                return ItemsRangeSchema(new Dictionary<string, object>
                 {
                     { "type", "array" },
                     { "items", BuildSchema(elementType, path + "[]", definitions, member, false) }
-                };
+                }, member, path);
             }
 
             if (rawType.IsPointer || rawType.IsByRef || rawType.IsGenericTypeDefinition || rawType.IsInterface || rawType.IsAbstract)
@@ -260,6 +260,35 @@ namespace UnityCli
             };
         }
 
+        /// <summary>将声明式集合范围投影为 JSON Schema；非法特性使 descriptor 派生失败。</summary>
+        private static Dictionary<string, object> ItemsRangeSchema(Dictionary<string, object> schema, MemberInfo member, string path)
+        {
+            var range = member == null ? null : member.GetCustomAttributes(typeof(UnityCliItemsRangeAttribute), true).Cast<UnityCliItemsRangeAttribute>().SingleOrDefault();
+            if (range == null) return schema;
+            if (range.Minimum < 0 || range.Minimum > range.Maximum) throw Unsupported(path, "items range is invalid");
+            schema["minItems"] = range.Minimum;
+            schema["maxItems"] = range.Maximum;
+            return schema;
+        }
+
+        /// <summary>将声明式业务范围收窄到 CLR 可表示范围；非法特性使 descriptor 派生失败。</summary>
+        private static Dictionary<string, object> NumericRangeSchema(Dictionary<string, object> schema, MemberInfo member, string path)
+        {
+            var range = member == null ? null : member.GetCustomAttributes(typeof(UnityCliRangeAttribute), true).Cast<UnityCliRangeAttribute>().SingleOrDefault();
+            if (range == null) return schema;
+            if (range.Minimum > range.Maximum) throw Unsupported(path, "numeric range minimum exceeds maximum");
+            decimal existingMinimum;
+            decimal existingMaximum;
+            var minimum = schema.TryGetValue("minimum", out var rawMinimum) ? Convert.ToDecimal(rawMinimum) : decimal.MinValue;
+            var maximum = schema.TryGetValue("maximum", out var rawMaximum) ? Convert.ToDecimal(rawMaximum) : decimal.MaxValue;
+            existingMinimum = Math.Max(minimum, range.Minimum);
+            existingMaximum = Math.Min(maximum, range.Maximum);
+            if (existingMinimum > existingMaximum) throw Unsupported(path, "numeric range is outside CLR range");
+            schema["minimum"] = existingMinimum;
+            schema["maximum"] = existingMaximum;
+            return schema;
+        }
+
         internal static void IntegerRange(Type type, out decimal minimum, out decimal maximum)
         {
             if (type == typeof(byte)) { minimum = byte.MinValue; maximum = byte.MaxValue; return; }

package/unitypkg/Editor/ProjectTools/UnityCliToolName.cs

@@ -0,0 +1,30 @@
+#if UNITY_EDITOR
+using System;
+using System.Text;
+using System.Text.RegularExpressions;
+
+namespace UnityCli
+{
+    /// <summary>按公开 contract profile 校验精确 Tool identity 与统一 UTF-8 byte 预算。</summary>
+    internal static class UnityCliToolName
+    {
+        internal const int MaxUtf8Bytes = 128;
+        private const string OfficialPrefix = "UnityPipeline_";
+        private static readonly Regex NativePattern = new Regex("^[a-z][a-z0-9-]*(?:\\.[a-z0-9][a-z0-9-]*)*\\z", RegexOptions.CultureInvariant);
+        private static readonly Regex OfficialSuffixPattern = new Regex("^[a-z][a-z0-9_-]*(?:\\.[a-z0-9][a-z0-9_-]*)*\\z", RegexOptions.CultureInvariant);
+
+        internal static void Validate(string name, string contractProfile)
+        {
+            var validProfile = string.Equals(contractProfile, "native", StringComparison.Ordinal)
+                || string.Equals(contractProfile, "official-attribute", StringComparison.Ordinal);
+            var validSyntax = string.Equals(contractProfile, "official-attribute", StringComparison.Ordinal)
+                ? name != null && name.StartsWith(OfficialPrefix, StringComparison.Ordinal)
+                    && OfficialSuffixPattern.IsMatch(name.Substring(OfficialPrefix.Length))
+                : string.Equals(contractProfile, "native", StringComparison.Ordinal)
+                    && name != null && NativePattern.IsMatch(name);
+            if (!validProfile || string.IsNullOrEmpty(name) || Encoding.UTF8.GetByteCount(name) > MaxUtf8Bytes || !validSyntax)
+                throw new InvalidOperationException("Tool name must use the registered Tool syntax and fit 128 UTF-8 bytes.");
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Properties/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly: InternalsVisibleTo("UnityCli.Editor.Tests")]

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

@@ -12,14 +12,15 @@ namespace UnityCli
         {
             public string AssetPath { get; set; }
             public string Path { get; set; }
-            public int? MaxDepth { get; set; }
-            public int? MaxArrayItems { get; set; }
+            [UnityCliRange(0L, 16L)] public int? MaxDepth { get; set; }
+            [UnityCliRange(1L, 1000L)] public int? MaxArrayItems { get; set; }
             public bool? IncludeFields { get; set; }
             public bool? IncludeProperties { get; set; }
             public bool? DeepSerialization { get; set; }
-            public System.Collections.Generic.List<string> Paths { get; set; }
+            [UnityCliItemsRange(0, 128)] public System.Collections.Generic.List<string> Paths { get; set; }
             [UnityCliAnyJson] public object ViewQuery { get; set; }
             public string NamePattern { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -33,7 +34,7 @@ namespace UnityCli
         {
             Name = "asset.get-data",
             Summary = "Deep-read an Assets/* asset's members via ObjectSerializer; use paths or viewQuery for token-safe fields.",
-            Description = "Deep-read an Assets/* asset's members. For token safety, pass exact paths or one viewQuery; they are mutually exclusive and skip full fields/props expansion. Keep maxDepth low before expanding large assets. Arrays/lists/dicts are bounded by maxArrayItems.",
+            Description = "Deep-read one loaded Assets/* object without importing. maxDepth is 0..16, maxArrayItems is 1..1000, and paths accepts at most 128 ordered exact reads. Every path and recursive branch shares the request scan/node/getter/reflection/monotonic-time/UTF-8 budget; defaults are 10000/4096/2048/4096/250 ms/1 MiB and maxima are 100000/20000/10000/20000/2000 ms/8 MiB. Truncated nodes return nextPath. Read-only in Edit and Play Mode.",
             Group = "asset",
             DestructiveHint = false,
             Target = "editor",
@@ -48,22 +49,30 @@ namespace UnityCli
 
         public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
+            var budget = ctx.UseReadBudget(request.Budget);
+            budget.CheckpointOrThrow();
             var path = AssetToolSupport.RequireAssetPath(request.AssetPath ?? request.Path);
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             if (!AssetToolSupport.AssetExists(path))
             {
                 throw new UnityCliBridge.BridgeCommandException("E_ASSET_NOT_FOUND", "Asset not found: " + path, "Run tools run asset.search --input '{\"query\":\"<keyword>\"}' to discover the path.");
             }
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
             var asset = AssetDatabase.LoadMainAssetAtPath(path);
             if (asset == null)
             {
                 throw new UnityCliBridge.BridgeCommandException("E_ASSET_LOAD_FAILED", "Asset main object could not be loaded: " + path, "Run asset.info to confirm the asset type, or use a more specific tool for folders/importers.");
             }
             var options = GameObjectToolSupport.BuildSerializerOptions(request);
-            var data = UnityCliBridge.ObjectSerializer.Serialize(asset, options);
+            var data = UnityCliBridge.ObjectSerializer.Serialize(asset, options, budget);
+            if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var guid = AssetDatabase.AssetPathToGUID(path);
+            if (!budget.TryConsumeReflectionCall()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+            var typeName = asset.GetType().FullName;
             return new System.Threading.Tasks.ValueTask<Result>(new Result
             {
-                Guid = AssetDatabase.AssetPathToGUID(path),
-                TypeName = asset.GetType().FullName,
+                Guid = guid,
+                TypeName = typeName,
                 // ObjectSerializer 输出为动态 JSON 树);解析为嵌套结构供框架序列化(IDictionary 支持)
                 Data = data
             });

package/unitypkg/Editor/Tools/build/BuildSceneStateTool.cs

@@ -1,4 +1,5 @@
 #if UNITY_EDITOR
+using System.Collections.Generic;
 using System.Linq;
 using UnityEditor;
 
@@ -16,22 +17,41 @@ namespace UnityCli
             var index = scenes.ToList().FindIndex(scene => scene.path == path);
             if (index < 0)
                 throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_NOT_FOUND", "Build Settings does not contain scene: " + path, "Run build.scene.list and pass a listed path.");
-            if (!ctx.DryRun)
+            var changed = scenes[index].enabled != enabled;
+            var plannedEffects = changed
+                ? new List<BuildScenePlannedEffect> { new BuildScenePlannedEffect { Type = toolName, Path = path, Enabled = enabled } }
+                : new List<BuildScenePlannedEffect>();
+            if (!ctx.DryRun && changed)
             {
                 ctx.CommitEffect();
                 scenes[index] = new EditorBuildSettingsScene(path, enabled);
                 EditorBuildSettings.scenes = scenes;
                 scenes = ReadScenes();
-                if (!scenes.Any(scene => scene.path == path && scene.enabled == enabled))
+                index = scenes.ToList().FindIndex(scene => scene.path == path);
+                if (index < 0 || scenes[index].enabled != enabled)
                     throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_STATE_MISMATCH", "Build Settings did not apply the requested enabled state for " + path + ".", "Inspect build.scene.list and retry.");
             }
-            return new(new BuildSceneMutationResult { Count = scenes.LongLength, DryRun = ctx.DryRun });
+            return new(new BuildSceneMutationResult
+            {
+                Count = scenes.LongLength,
+                Scene = BuildEntry(scenes[index], index),
+                Changed = !ctx.DryRun && changed,
+                NoOpReason = !changed ? "scene-already-" + (enabled ? "enabled" : "disabled") : null,
+                DryRun = ctx.DryRun,
+                PlannedEffects = plannedEffects
+            });
         }
 
         public static EditorBuildSettingsScene[] ReadScenes()
         {
             return EditorBuildSettings.scenes ?? new EditorBuildSettingsScene[0];
         }
+
+        // 将 fresh EditorBuildSettings 读回投影为公开条目。
+        public static BuildSceneEntry BuildEntry(EditorBuildSettingsScene scene, int index)
+        {
+            return new BuildSceneEntry { Path = BuildToolSupport.NormalizeAssetPath(scene.path), Enabled = scene.enabled, BuildIndex = index };
+        }
     }
 }
 #endif

package/unitypkg/Editor/Tools/build/BuildToolDtos.cs

@@ -8,7 +8,8 @@ namespace UnityCli
     public sealed class BuildProfileMutationResult { public bool Available { get; set; } public string Action { get; set; } public string ActivePath { get; set; } public bool DryRun { get; set; } }
     public sealed class BuildSceneEntry { public string Path { get; set; } public bool Enabled { get; set; } public long BuildIndex { get; set; } }
     public sealed class BuildSceneListResult { public long Count { get; set; } public List<BuildSceneEntry> Scenes { get; set; } }
-    public sealed class BuildSceneMutationResult { public long Count { get; set; } public bool Changed { get; set; } public string NoOpReason { get; set; } public bool DryRun { get; set; } }
+    public sealed class BuildScenePlannedEffect { public string Type { get; set; } public string Path { get; set; } public bool? Enabled { get; set; } }
+    public sealed class BuildSceneMutationResult { public long Count { get; set; } public BuildSceneEntry Scene { get; set; } public bool Changed { get; set; } public string NoOpReason { get; set; } public bool DryRun { get; set; } public List<BuildScenePlannedEffect> PlannedEffects { get; set; } }
     public sealed class BuildSettingsResult { public string ProductName { get; set; } public string BundleVersion { get; set; } public string CompanyId { get; set; } public string ApplicationIdentifier { get; set; } public string ScriptingBackend { get; set; } public string ApiCompatibilityLevel { get; set; } public List<string> Changed { get; set; } public bool DryRun { get; set; } }
     public sealed class BuildSettingsMutationResult { public List<string> Changed { get; set; } public bool DryRun { get; set; } }
 }

package/unitypkg/Editor/Tools/build/scene/add.cs

@@ -7,7 +7,7 @@ namespace UnityCli
     public class BuildSceneAddTool : IUnityCliTool<BuildSceneAddTool.Request, BuildSceneMutationResult>
     {
         public sealed class Request { [UnityCliRequired] public string Path { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "build.scene.add", Summary = "Add an enabled scene to persistent Unity Build Settings.", Description = "Adds path to EditorBuildSettings as an enabled scene when absent. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } };
+        public ToolDescriptor Describe() => new() { Name = "build.scene.add", Summary = "Add an enabled scene to persistent Unity Build Settings.", Description = "Adds one existing Assets/*.unity scene to EditorBuildSettings as enabled. Available in Edit and Play mode. dryRun previews the exact path; success returns the fresh scene entry, count, changed state, and no-op reason.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } };
         public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
             var path = BuildToolSupport.NormalizeAssetPath(request.Path);
@@ -32,12 +32,15 @@ namespace UnityCli
                 if (!scenes.Any(scene => scene.path == path && scene.enabled))
                     throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_ADD_MISMATCH", "Build Settings did not add enabled scene: " + path, "Inspect build.scene.list and retry.");
             }
+            var observedIndex = System.Array.FindIndex(scenes, scene => scene.path == path);
             return new(new BuildSceneMutationResult
             {
                 Count = scenes.LongLength,
+                Scene = observedIndex < 0 ? null : BuildSceneStateTool.BuildEntry(scenes[observedIndex], observedIndex),
                 Changed = !ctx.DryRun && changed,
-                NoOpReason = !ctx.DryRun && !changed ? "scene-already-enabled" : null,
-                DryRun = ctx.DryRun
+                NoOpReason = !changed ? "scene-already-enabled" : null,
+                DryRun = ctx.DryRun,
+                PlannedEffects = changed ? new System.Collections.Generic.List<BuildScenePlannedEffect> { new BuildScenePlannedEffect { Type = "build.scene.add", Path = path, Enabled = true } } : new System.Collections.Generic.List<BuildScenePlannedEffect>()
             });
         }
     }

package/unitypkg/Editor/Tools/build/scene/disable.cs

@@ -1,3 +1,3 @@
 #if UNITY_EDITOR
-namespace UnityCli { public class BuildSceneDisableTool : IUnityCliTool<BuildSceneDisableTool.Request, BuildSceneMutationResult> { public sealed class Request { [UnityCliRequired] public string Path { get; set; } } public ToolDescriptor Describe() => new() { Name = "build.scene.disable", Summary = "Disable a scene in persistent Unity Build Settings.", Description = "Marks an existing Build Settings scene as disabled. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Disable main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } }; public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { return BuildSceneStateTool.Execute(request.Path, false, "build.scene.disable", ctx); } } }
+namespace UnityCli { public class BuildSceneDisableTool : IUnityCliTool<BuildSceneDisableTool.Request, BuildSceneMutationResult> { public sealed class Request { [UnityCliRequired] public string Path { get; set; } } public ToolDescriptor Describe() => new() { Name = "build.scene.disable", Summary = "Disable a scene in persistent Unity Build Settings.", Description = "Marks one existing EditorBuildSettings scene as disabled. Available in Edit and Play mode. dryRun previews the exact path; success returns a fresh scene entry, changed state, and no-op reason.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Disable main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } }; public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { return BuildSceneStateTool.Execute(request.Path, false, "build.scene.disable", ctx); } } }
 #endif

package/unitypkg/Editor/Tools/build/scene/enable.cs

@@ -1,4 +1,4 @@
 #if UNITY_EDITOR
 using System.Linq; using UnityEditor;
-namespace UnityCli { public class BuildSceneEnableTool : IUnityCliTool<BuildSceneEnableTool.Request, BuildSceneMutationResult> { public sealed class Request { [UnityCliRequired] public string Path { get; set; } } public ToolDescriptor Describe() => new() { Name = "build.scene.enable", Summary = "Enable a scene in persistent Unity Build Settings.", Description = "Marks an existing Build Settings scene as enabled. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Enable main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } }; public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { return BuildSceneStateTool.Execute(request.Path, true, "build.scene.enable", ctx); } } }
+namespace UnityCli { public class BuildSceneEnableTool : IUnityCliTool<BuildSceneEnableTool.Request, BuildSceneMutationResult> { public sealed class Request { [UnityCliRequired] public string Path { get; set; } } public ToolDescriptor Describe() => new() { Name = "build.scene.enable", Summary = "Enable a scene in persistent Unity Build Settings.", Description = "Marks one existing EditorBuildSettings scene as enabled. Available in Edit and Play mode. dryRun previews the exact path; success returns a fresh scene entry, changed state, and no-op reason.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Enable main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } }; public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { return BuildSceneStateTool.Execute(request.Path, true, "build.scene.enable", ctx); } } }
 #endif

package/unitypkg/Editor/Tools/build/scene/list.cs

@@ -1,4 +1,4 @@
 #if UNITY_EDITOR
 using System.Collections.Generic; using UnityEditor;
-namespace UnityCli { public class BuildSceneListTool : IUnityCliTool<BuildSceneListTool.Request, BuildSceneListResult> { public sealed class Request { } public ToolDescriptor Describe() => new() { Name = "build.scene.list", Summary = "List scenes registered in Unity Build Settings.", Description = "Returns every Build Settings scene with path, enabled state, and build index. Read-only and available in Edit and Play mode.", Group = "build",Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "List build scenes", Input = new Request() } } }; public System.Threading.Tasks.ValueTask<BuildSceneListResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { var scenes = EditorBuildSettings.scenes ?? new EditorBuildSettingsScene[0]; var entries = new List<BuildSceneEntry>(); for (var i = 0; i < scenes.Length; i++) entries.Add(new BuildSceneEntry { Path = BuildToolSupport.NormalizeAssetPath(scenes[i].path), Enabled = scenes[i].enabled, BuildIndex = i }); return new(new BuildSceneListResult { Count = scenes.Length, Scenes = entries }); } } }
+namespace UnityCli { public class BuildSceneListTool : IUnityCliTool<BuildSceneListTool.Request, BuildSceneListResult> { public sealed class Request { } public ToolDescriptor Describe() => new() { Name = "build.scene.list", Summary = "List scenes registered in Unity Build Settings.", Description = "Returns every EditorBuildSettings scene with normalized path, enabled state, and build index. Read-only and available in Edit and Play mode; use the dedicated add/remove/enable/disable Tools for writes.", Group = "build",Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "List build scenes", Input = new Request() } } }; public System.Threading.Tasks.ValueTask<BuildSceneListResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { var scenes = EditorBuildSettings.scenes ?? new EditorBuildSettingsScene[0]; var entries = new List<BuildSceneEntry>(); for (var i = 0; i < scenes.Length; i++) entries.Add(new BuildSceneEntry { Path = BuildToolSupport.NormalizeAssetPath(scenes[i].path), Enabled = scenes[i].enabled, BuildIndex = i }); return new(new BuildSceneListResult { Count = scenes.Length, Scenes = entries }); } } }
 #endif

package/unitypkg/Editor/Tools/build/scene/remove.cs

@@ -7,14 +7,16 @@ namespace UnityCli
     public class BuildSceneRemoveTool : IUnityCliTool<BuildSceneRemoveTool.Request, BuildSceneMutationResult>
     {
         public sealed class Request { [UnityCliRequired] public string Path { get; set; } }
-        public ToolDescriptor Describe() => new() { Name = "build.scene.remove", Summary = "Remove a scene from persistent Unity Build Settings.", Description = "Removes path from EditorBuildSettings. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Remove main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } };
+        public ToolDescriptor Describe() => new() { Name = "build.scene.remove", Summary = "Remove a scene from persistent Unity Build Settings.", Description = "Removes one exact scene path from EditorBuildSettings. Available in Edit and Play mode. dryRun previews the path; success returns the fresh remaining count, changed state, and no-op reason.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Remove main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } };
         public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
         {
             var path = BuildToolSupport.NormalizeAssetPath(request.Path);
             if (string.IsNullOrEmpty(path))
                 throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_PATH_REQUIRED", "build.scene.remove requires path.", "Pass a scene path such as Assets/Scenes/Main.unity.");
             var scenes = BuildSceneStateTool.ReadScenes();
-            if (!ctx.DryRun && scenes.Any(scene => scene.path == path))
+            var existingIndex = System.Array.FindIndex(scenes, scene => scene.path == path);
+            var changed = existingIndex >= 0;
+            if (!ctx.DryRun && changed)
             {
                 ctx.CommitEffect();
                 EditorBuildSettings.scenes = scenes.Where(scene => scene.path != path).ToArray();
@@ -22,7 +24,15 @@ namespace UnityCli
                 if (scenes.Any(scene => scene.path == path))
                     throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_REMOVE_MISMATCH", "Build Settings did not remove scene: " + path, "Inspect build.scene.list and retry.");
             }
-            return new(new BuildSceneMutationResult { Count = scenes.LongLength, DryRun = ctx.DryRun });
+            return new(new BuildSceneMutationResult
+            {
+                Count = scenes.LongLength,
+                Scene = ctx.DryRun && changed ? BuildSceneStateTool.BuildEntry(scenes[existingIndex], existingIndex) : null,
+                Changed = !ctx.DryRun && changed,
+                NoOpReason = !changed ? "scene-not-registered" : null,
+                DryRun = ctx.DryRun,
+                PlannedEffects = changed ? new System.Collections.Generic.List<BuildScenePlannedEffect> { new BuildScenePlannedEffect { Type = "build.scene.remove", Path = path } } : new System.Collections.Generic.List<BuildScenePlannedEffect>()
+            });
         }
     }
 }

package/unitypkg/Editor/Tools/camera/CameraToolSupport.cs

@@ -3,7 +3,6 @@ using System;
 using System.Collections.Generic;
 using System.Globalization;
 using System.IO;
-using System.Security.Cryptography;
 using UnityEditor;
 using UnityEngine;
 
@@ -57,6 +56,27 @@ namespace UnityCli
             return null;
         }
 
+        /// <summary>读取型截图解析复用一次 Camera snapshot，并把每个候选计入请求 scan/getter 预算。</summary>
+        public static Camera ResolveCamera(string target, UnityCliRequestBudget budget)
+        {
+            if (budget == null) throw new ArgumentNullException("budget");
+            if (string.IsNullOrEmpty(target))
+            {
+                if (!budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                var main = Camera.main;
+                if (main != null) return main;
+            }
+            var cameras = Camera.allCameras;
+            foreach (var camera in cameras)
+            {
+                if (!budget.TryConsumeScannedRecord() || !budget.TryConsumeGetter()) throw new UnityCliRequestBudgetExceededException(budget.ExhaustedDimension);
+                if (string.IsNullOrEmpty(target) || camera.name == target || camera.GetInstanceID().ToString(CultureInfo.InvariantCulture) == target) return camera;
+                var path = UnityCliHierarchyPager.Path(camera.gameObject, budget);
+                if (path == target) return camera;
+            }
+            return null;
+        }
+
         /// <summary>构造 Camera 摘要信息 DTO。</summary>
         public static CameraInfo BuildCameraInfo(Camera camera)
         {
@@ -143,45 +163,25 @@ namespace UnityCli
             }
         }
 
-        /// <summary>写入截图后重新读取字节、校验格式并返回稳定 artifact proof。</summary>
-        public static CameraArtifactProof WriteScreenshotBytes(string outputPath, byte[] bytes)
-        {
-            if (bytes == null || bytes.Length == 0)
-                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_ENCODE_FAILED", "Screenshot encoder returned no bytes.", "Check the Camera render state and retry.");
-            try { File.WriteAllBytes(outputPath, bytes); }
-            catch (Exception exception) { throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to write screenshot output: " + exception.Message); }
-            return VerifyScreenshotArtifact(outputPath, Path.GetExtension(outputPath).TrimStart('.'));
-        }
-
-        /// <summary>artifact proof 必须来自写后 fresh readback，不能只依赖 Exists 或原始编码 bytes。</summary>
-        public static CameraArtifactProof VerifyScreenshotArtifact(string outputPath, string format)
-        {
-            if (!File.Exists(outputPath)) throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_WRITE_PROOF_MISSING", "Screenshot output was not written: " + outputPath, "Check destination path and permissions, then retry.");
-            var bytes = File.ReadAllBytes(outputPath);
-            var normalized = NormalizeFormat(format, outputPath);
-            var valid = normalized == "png"
-                ? bytes.Length >= 8 && bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4e && bytes[3] == 0x47 && bytes[4] == 0x0d && bytes[5] == 0x0a && bytes[6] == 0x1a && bytes[7] == 0x0a
-                : bytes.Length >= 3 && bytes[0] == 0xff && bytes[1] == 0xd8 && bytes[2] == 0xff;
-            if (!valid) throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_WRITE_PROOF_MISSING", "Screenshot output is empty or does not match its requested format: " + outputPath, "Use a .png or .jpg output path and retry.");
-            using (var sha = SHA256.Create()) return new CameraArtifactProof { SizeBytes = bytes.LongLength, Sha256 = string.Concat(Array.ConvertAll(sha.ComputeHash(bytes), value => value.ToString("x2"))) };
-        }
-
-        /// <summary>渲染指定 Camera 到 RenderTexture 并编码为图片字节,返回捕获结果。捕获后恢复相机状态。</summary>
-        public static CameraCapture CaptureCamera(Camera camera, int width, int height, bool transparent, int quality, string outputPath, string format, bool overwrite, bool inlineBase64)
+        /// <summary>按冻结 aggregate plan 渲染、编码与证明单张 Camera artifact，并在 finally 恢复纹理状态。</summary>
+        public static CameraCapture CaptureCamera(Camera camera, int width, int height, bool transparent, int quality, string outputPath, string format, bool overwrite, bool inlineBase64, ScreenshotCaptureBudget budget)
         {
             if (File.Exists(outputPath) && !overwrite)
             {
                 throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
             }
+            budget.BeginCapture(width, height);
             CreateScreenshotDirectory(outputPath);
             var previousTarget = camera.targetTexture;
             var previousActive = RenderTexture.active;
             var previousClearFlags = camera.clearFlags;
             var previousBackground = camera.backgroundColor;
-            var renderTexture = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
-            var texture = new Texture2D(width, height, transparent ? TextureFormat.ARGB32 : TextureFormat.RGB24, false);
+            RenderTexture renderTexture = null;
+            Texture2D texture = null;
             try
             {
+                renderTexture = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
+                texture = new Texture2D(width, height, transparent ? TextureFormat.ARGB32 : TextureFormat.RGB24, false);
                 camera.targetTexture = renderTexture;
                 if (transparent)
                 {
@@ -193,20 +193,22 @@ namespace UnityCli
                 texture.ReadPixels(new Rect(0, 0, width, height), 0, 0);
                 texture.Apply();
                 var bytes = format == "jpg" ? texture.EncodeToJPG(quality) : texture.EncodeToPNG();
-                var artifact = WriteScreenshotBytes(outputPath, bytes);
+                var artifact = ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes, budget);
                 var capture = new CameraCapture
                 {
                     ScreenshotPath = outputPath,
                     ArtifactPath = outputPath,
                     Source = "camera",
                     SizeBytes = artifact.SizeBytes,
-                    Sha256 = artifact.Sha256
+                    Sha256 = artifact.Sha256,
+                    CapturePlan = budget.Plan
                 };
-                // inlineBase64 仅在图片字节小于内联上限时附带,避免大 base64 撑爆 JSON 响应
+                // inlineBase64 同时受固定图片上限与请求级 UTF-8 预算约束。
                 const int InlineImageMaxBytes = 512 * 1024;
-                if (inlineBase64 && bytes != null && bytes.Length <= InlineImageMaxBytes)
+                string encoded;
+                if (inlineBase64 && bytes != null && bytes.Length <= InlineImageMaxBytes && budget.TryCreateInlineBase64(bytes, out encoded))
                 {
-                    capture.ImageBase64 = Convert.ToBase64String(bytes);
+                    capture.ImageBase64 = encoded;
                     capture.ImageWidth = width;
                     capture.ImageHeight = height;
                     capture.ImageMimeType = format == "jpg" ? "image/jpeg" : "image/png";
@@ -219,9 +221,8 @@ namespace UnityCli
                 camera.targetTexture = previousTarget;
                 camera.clearFlags = previousClearFlags;
                 camera.backgroundColor = previousBackground;
-                UnityEngine.Object.DestroyImmediate(texture);
-                renderTexture.Release();
-                UnityEngine.Object.DestroyImmediate(renderTexture);
+                if (texture != null) UnityEngine.Object.DestroyImmediate(texture);
+                if (renderTexture != null) { renderTexture.Release(); UnityEngine.Object.DestroyImmediate(renderTexture); }
             }
         }
 
@@ -275,10 +276,9 @@ namespace UnityCli
         public string ImageMimeType { get; set; }
         public long SizeBytes { get; set; }
         public string Sha256 { get; set; }
+        public ScreenshotCapturePlan CapturePlan { get; set; }
     }
 
-    public sealed class CameraArtifactProof { public long SizeBytes { get; set; } public string Sha256 { get; set; } }
-
     /// <summary>计划副作用项,camera 域 mutation 工具 Result 共享。</summary>
     public sealed class CameraPlannedEffect
     {

package/unitypkg/Editor/Tools/camera/multiview.cs

@@ -16,9 +16,11 @@ namespace UnityCli
         {
             public string Targets { get; set; }
             public string Output { get; set; }
-            public int? Width { get; set; }
-            public int? Height { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Width { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Height { get; set; }
             public string Format { get; set; }
+            public ScreenshotBudgetInput Limits { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public sealed class Result
@@ -26,13 +28,14 @@ namespace UnityCli
             public List<CameraCapture> Captures { get; set; }
             public long Count { get; set; }
             public List<CameraPlannedEffect> PlannedEffects { get; set; }
+            public ScreenshotCapturePlan CapturePlan { get; set; }
         }
 
         public ToolDescriptor Describe() => new()
         {
             Name = "camera.multiview",
             Summary = "Capture one PNG/JPG artifact per named Camera into an output directory for multiview review.",
-            Description = "Capture one PNG/JPG artifact per named Camera into an output directory for side-by-side scene review. Returns artifact paths instead of inline image bytes; keep target count and resolution small for token and disk efficiency.",
+            Description = "Capture 1..16 named Cameras to PNG/JPG artifacts. Each dimension is 1..8192 and each image is at most 16777216 pixels. Before the first effect, the aggregate plan must fit default ceilings of 33554432 total pixels, 128 MiB temporary memory and 64 MiB artifacts; public maxima are 67108864, 256 MiB and 256 MiB. All textures are released after each capture. Available in Edit and Play Mode with session render effects.",
             Group = "camera",
             DestructiveHint = true,
             SideEffects = new[] { "artifact-write", "render-texture" },
@@ -52,11 +55,14 @@ namespace UnityCli
             {
                 throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "camera.multiview requires targets.", "Run tools run camera.list, then pass comma-separated camera names, hierarchy paths, or instance ids.");
             }
+            var requestBudget = ctx.UseReadBudget(request.Budget);
             var names = request.Targets.Split(new[] { ',' }, System.StringSplitOptions.RemoveEmptyEntries);
+            if (names.Length < 1 || names.Length > 16)
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_LIMIT_INVALID", "camera.multiview targets must contain 1..16 cameras.", "Reduce the target list before retrying.");
             var cameras = new List<Camera>();
             foreach (var name in names)
             {
-                var camera = CameraToolSupport.ResolveCamera(name.Trim());
+                var camera = CameraToolSupport.ResolveCamera(name.Trim(), requestBudget);
                 if (camera == null)
                 {
                     throw new UnityCliBridge.BridgeCommandException("E_CAMERA_NOT_FOUND", "Camera not found: " + name.Trim(), "Run tools run camera.list, then retry with camera names, hierarchy paths, or instance ids from the result.");
@@ -67,6 +73,7 @@ namespace UnityCli
             var width = CameraToolSupport.ClampScreenshotDimension(request.Width ?? 1280, "width");
             var height = CameraToolSupport.ClampScreenshotDimension(request.Height ?? 720, "height");
             var format = CameraToolSupport.NormalizeFormat(request.Format, Path.Combine(outputDir, "capture.png"));
+            var captureBudget = ScreenshotToolSupport.PrepareCaptureBudget(width, height, cameras.Count, false, request.Limits, requestBudget);
             var captures = new List<CameraCapture>();
             var effects = new List<CameraPlannedEffect>();
             var plans = new List<KeyValuePair<int, string>>();
@@ -83,13 +90,13 @@ namespace UnityCli
             {
                 var camera = EditorUtility.InstanceIDToObject(plan.Key) as Camera;
                 if (camera == null) throw new UnityCliBridge.BridgeCommandException("E_CAMERA_NOT_FOUND", "Camera disappeared before capture.", "Retry after the Editor is idle.");
-                var capture = CameraToolSupport.CaptureCamera(camera, width, height, false, 95, plan.Value, format, true, false);
+                var capture = CameraToolSupport.CaptureCamera(camera, width, height, false, 95, plan.Value, format, true, false, captureBudget);
                 if (!File.Exists(plan.Value) || new FileInfo(plan.Value).Length == 0)
                     throw new UnityCliBridge.BridgeCommandException("E_MULTIVIEW_ARTIFACT_MISSING", "Camera capture artifact was not observed: " + plan.Value, "Check the output directory and retry.");
                 captures.Add(capture);
                 effects.Add(new CameraPlannedEffect { Type = "camera.multiview", Property = "capture", Path = plan.Value });
             }
-            return new System.Threading.Tasks.ValueTask<Result>(new Result { Captures = captures, Count = captures.Count, PlannedEffects = effects });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Captures = captures, Count = captures.Count, PlannedEffects = effects, CapturePlan = captureBudget.Plan });
         }
     }
 }

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

@@ -1,4 +1,5 @@
 #if UNITY_EDITOR
+using System.IO;
 using UnityEngine;
 
 namespace UnityCli
@@ -13,20 +14,22 @@ namespace UnityCli
             public string Target { get; set; }
             public string Path { get; set; }
             public string Output { get; set; }
-            public int? Width { get; set; }
-            public int? Height { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Width { get; set; }
+            [UnityCliRange(1L, 8192L)] public int? Height { get; set; }
             public string Format { get; set; }
             public bool Transparent { get; set; }
-            public int? Quality { get; set; }
+            [UnityCliRange(1L, 100L)] public int? Quality { get; set; }
             public bool Overwrite { get; set; }
             public bool InlineBase64 { get; set; }
+            public ScreenshotBudgetInput Limits { get; set; }
+            public UnityCliReadBudgetInput Budget { get; set; }
         }
 
         public ToolDescriptor Describe() => new()
         {
             Name = "camera.screenshot",
             Summary = "Render a PNG/JPG artifact from one specific Camera; use screenshot.* for view-based captures.",
-            Description = "Render a screenshot from a specific Camera into a PNG/JPG artifact file. Defaults return artifact paths only; inlineBase64 must be explicit and is omitted when the image exceeds the bridge inline limit. Restores camera render state after capture.",
+            Description = "Render one Camera to PNG/JPG. Before the first effect, dimensions must be 1..8192 with at most 16777216 pixels, and the aggregate plan must fit default ceilings of 33554432 total pixels, 128 MiB temporary memory and 64 MiB artifacts (public maxima 67108864, 256 MiB and 256 MiB). limits may only tighten or raise within those maxima; zero, negative and excessive values fail before capture. The texture and Camera state are released/restored in finally. Available in Edit and Play Mode with session render effects.",
             Group = "camera",
             DestructiveHint = true,
             SideEffects = new[] { "artifact-write", "render-texture" },
@@ -47,7 +50,8 @@ namespace UnityCli
             {
                 throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "Camera screenshot requires a target Camera.", "Pass a Camera name, hierarchy path or instance id. Run tools run camera.list before retrying.");
             }
-            var camera = CameraToolSupport.ResolveCamera(target);
+            var requestBudget = ctx.UseReadBudget(request.Budget);
+            var camera = CameraToolSupport.ResolveCamera(target, requestBudget);
             if (camera == null)
             {
                 throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "Camera not found: " + target, "Run tools run camera.list, then retry with a camera name, hierarchy path, or instance id from the result.");
@@ -56,9 +60,12 @@ namespace UnityCli
             var format = CameraToolSupport.NormalizeFormat(request.Format, outputPath);
             var width = CameraToolSupport.ClampScreenshotDimension(request.Width ?? (camera.pixelWidth > 0 ? camera.pixelWidth : 1280), "width");
             var height = CameraToolSupport.ClampScreenshotDimension(request.Height ?? (camera.pixelHeight > 0 ? camera.pixelHeight : 720), "height");
-            var quality = Mathf.Clamp(request.Quality ?? 95, 1, 100);
+            var quality = request.Quality ?? 95;
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            var captureBudget = ScreenshotToolSupport.PrepareCaptureBudget(width, height, 1, false, request.Limits, requestBudget);
             ctx.CommitEffect();
-            return new System.Threading.Tasks.ValueTask<CameraCapture>(CameraToolSupport.CaptureCamera(camera, width, height, request.Transparent, quality, outputPath, format, request.Overwrite, request.InlineBase64));
+            return new System.Threading.Tasks.ValueTask<CameraCapture>(CameraToolSupport.CaptureCamera(camera, width, height, request.Transparent, quality, outputPath, format, request.Overwrite, request.InlineBase64, captureBudget));
         }
     }
 }