@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,147 @@
+#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>
+    public class ProfilerMemorySnapshotTakeTool : IUnityCliTool<ProfilerMemorySnapshotTakeTool.Request, ProfilerMemorySnapshotTakeTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long SizeBytes { get; set; }
+            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" } } }
+        };
+
+        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)
+            {
+                takeMethod = profilerType.GetMethod("TakeSnapshot", new[] { typeof(string), callbackType, captureFlagsType });
+            }
+            if (takeMethod != null)
+            {
+                invokeArgs = new object[] { outputPath, null, Enum.ToObject(captureFlagsType, 0) };
+            }
+            else
+            {
+                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) =>
+                {
+                    try
+                    {
+                        if (!captureResult)
+                        {
+                            fail(new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_FAILED",
+                                "Snapshot capture reported failure for path: " + outputPath,
+                                "Check Unity Console for Memory Profiler errors."));
+                            return;
+                        }
+
+                        var finalPath = capturedPath ?? outputPath;
+                        var info = new FileInfo(finalPath);
+                        if (!info.Exists || info.Length <= 0)
+                        {
+                            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;
+                        }
+                        complete(new Result
+                        {
+                            SizeBytes = info.Length,
+                            PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.memory-snapshot.take", Path = finalPath } }
+                        });
+                    }
+                    catch (Exception exception)
+                    {
+                        fail(exception);
+                    }
+                });
+
+                if (invokeArgs != null)
+                {
+                    invokeArgs[1] = callback;
+                }
+                else
+                {
+                    invokeArgs = new object[] { outputPath, callback };
+                }
+
+                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);
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,34 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerMemoryTool : IUnityCliTool<ProfilerMemoryTool.Request, ProfilerMemoryTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public ProfilerState Profiler { get; set; } public ProfilerMemory Memory { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.memory", Summary = "Query Unity memory usage from the live Editor.",
+            Description = "Query Unity memory usage from the live Editor, including values exposed by UnityEngine.Profiling.Profiler.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Query memory", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result
+        {
+            Profiler = ProfilerToolSupport.BuildProfilerState(),
+            Memory = ProfilerToolSupport.BuildProfilerMemory()
+        });
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/module-enable.cs

@@ -0,0 +1,52 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerModuleEnableTool : IUnityCliTool<ProfilerModuleEnableTool.Request, ProfilerModuleEnableTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Module { get; set; } public bool Enabled { get; set; } = true; }
+        public sealed class Result { public bool WasEnabled { get; set; } public bool IsEnabled { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.module-enable", Summary = "Enable or disable a Profiler module (area) by name via Profiler.SetAreaEnabled.",
+            Description = "Enable or disable a Profiler module (area) by name via Profiler.SetAreaEnabled. Run profiler.areas to list valid area names.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "profiler-area-state" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Enable CPU area", Input = new Request { Module = "CPU", Enabled = true } } }
+        };
+
+        // 仅在 Profiler API 可读回并匹配请求时返回成功。
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var areaType = ProfilerToolSupport.FindProfilerAreaType();
+            if (areaType == null || !areaType.IsEnum)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_AREAS_UNAVAILABLE", "ProfilerArea enum not available in this Unity version.", "Run in a Unity Editor with profiling support.");
+            if (string.IsNullOrEmpty(request.Module))
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_MODULE_REQUIRED", "profiler.module-enable requires module.", "Pass a Profiler area name; run profiler.areas to list valid names.");
+            object areaValue;
+            try { areaValue = Enum.Parse(areaType, request.Module, true); }
+            catch { throw new UnityCliBridge.BridgeCommandException("E_PROFILER_MODULE_UNKNOWN", "Unknown Profiler area: " + request.Module, "Run profiler.areas to see valid area names."); }
+            var setAreaMethod = typeof(Profiler).GetMethod("SetAreaEnabled", BindingFlags.Static | BindingFlags.Public, null, new[] { areaType, typeof(bool) }, null);
+            var getAreaMethod = typeof(Profiler).GetMethod("GetAreaEnabled", BindingFlags.Static | BindingFlags.Public, null, new[] { areaType }, null);
+            if (setAreaMethod == null || getAreaMethod == null)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_MODULE_UNSUPPORTED", "Profiler.SetAreaEnabled or GetAreaEnabled is not available in this Unity version.", "Use a Unity Editor version that exposes Profiler.SetAreaEnabled(ProfilerArea,bool) and GetAreaEnabled(ProfilerArea).");
+            var wasEnabled = (bool)getAreaMethod.Invoke(null, new object[] { areaValue });
+            ctx.CommitEffect();
+            setAreaMethod.Invoke(null, new object[] { areaValue, request.Enabled });
+            var isEnabled = (bool)getAreaMethod.Invoke(null, new object[] { areaValue });
+            if (isEnabled != request.Enabled)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_MODULE_STATE_MISMATCH", "Profiler area did not reach the requested enabled state.", "Inspect the Profiler module state and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { WasEnabled = wasEnabled, IsEnabled = isEnabled });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerModulesTool : IUnityCliTool<ProfilerModulesTool.Request, ProfilerModulesTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public List<string> Modules { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.modules", Summary = "List available Profiler modules and their visibility state.",
+            Description = "List available Profiler modules. Use the returned module names with profiler.module-enable.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "List modules", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result
+        {
+            Modules = ProfilerToolSupport.BuildProfilerModules()
+        });
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/object-memory.cs

@@ -0,0 +1,49 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerObjectMemoryTool : IUnityCliTool<ProfilerObjectMemoryTool.Request, ProfilerObjectMemoryTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string Path { get; set; } }
+        public sealed class Result { public List<ObjectMemoryEntry> Objects { get; set; } public long TotalBytes { get; set; } }
+        public sealed class ObjectMemoryEntry { public string Name { get; set; } public long InstanceId { get; set; } public long SizeBytes { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.object-memory", Summary = "Query memory size of components on a GameObject via Profiler.GetRuntimeMemorySizeLong.",
+            Description = "Query runtime memory size of components on a GameObject via Profiler.GetRuntimeMemorySizeLong. target resolves by name/path/id.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Query object memory", Input = new Request { Target = "Player" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var target = request.Target ?? request.Path;
+            var go = string.IsNullOrEmpty(target) ? null : UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(target);
+            var result = new Result { Objects = new List<ObjectMemoryEntry>() };
+            if (go != null)
+            {
+                long total = 0;
+                foreach (var c in go.GetComponents<Component>())
+                {
+                    if (c == null) continue;
+                    var size = Profiler.GetRuntimeMemorySizeLong(c);
+                    total += size;
+                    result.Objects.Add(new ObjectMemoryEntry { Name = c.GetType().Name, InstanceId = c.GetInstanceID(), SizeBytes = size });
+                }
+                result.TotalBytes = total;
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,49 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerPauseTool : IUnityCliTool<ProfilerPauseTool.Request, ProfilerPauseTool.Result>
+    {
+        public sealed class Request { public bool? Paused { get; set; } }
+        public sealed class Result { public ProfilerState Profiler { get; set; } public bool Paused { get; set; } public List<ProfilerPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.pause", Summary = "Pause or resume Profiler data collection by toggling Unity Profiler.enabled.",
+            Description = "Pause or resume Profiler data collection. Pass paused=true to pause, false to resume; omit to toggle the current state.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "profiler-session-state" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Pause profiler", Input = new Request { Paused = true } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var wasEnabled = ProfilerToolSupport.GetProfilerSessionEnabled();
+            var paused = request.Paused ?? wasEnabled;
+            ctx.CommitEffect();
+            ProfilerToolSupport.SetProfilerSessionEnabled(!paused);
+            var stable = await ctx.Wait.UntilStable(
+                () => ProfilerToolSupport.GetProfilerSessionEnabled() == !paused,
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            var isEnabled = ProfilerToolSupport.GetProfilerSessionEnabled();
+            var observed = ProfilerToolSupport.BuildProfilerState();
+            if (!stable || isEnabled != !paused)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_STATE_MISMATCH", "Profiler pause write did not produce the requested stable readback.", "Inspect Profiler availability and Editor session state, then retry.");
+            return new Result
+            {
+                Profiler = observed,
+                Paused = !isEnabled,
+                PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.pause", SideEffects = "profilerEnabledFrom=" + wasEnabled + ",profilerEnabledTo=" + isEnabled } }
+            };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/rendering-stats.cs

@@ -0,0 +1,109 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// profiler.rendering-stats — 读取 UnityEditor.UnityStats 渲染采样统计。
+    /// UnityStats 字段只在 Game View 实际渲染帧被填充;非渲染帧返回 null,available=false 并给出 diagnostics。
+    /// </summary>
+    public class ProfilerRenderingStatsTool : IUnityCliTool<ProfilerRenderingStatsTool.Request, ProfilerRenderingStatsTool.Result>
+    {
+        public sealed class Request
+        {
+            // profiler.rendering-stats 无入参
+        }
+
+        public sealed class Result
+        {
+            public bool Available { get; set; }
+            public RenderingStats Stats { get; set; }
+            public string Diagnostics { get; set; }
+            public List<string> NextActions { get; set; }
+        }
+
+        // UnityStats 反射读取的渲染计数器(字段只在渲染帧被填充,非渲染帧为 null)
+        public sealed class RenderingStats
+        {
+            public string Batches { get; set; }
+            public string Triangles { get; set; }
+            public string Vertices { get; set; }
+            public string SetPassCalls { get; set; }
+            public string ScreenRes { get; set; }
+            public string UsedTextureMemory { get; set; }
+            public string RenderTextureCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.rendering-stats",
+            Summary = "Read UnityStats rendering counters (batches, triangles, vertices, setPassCalls) for the current frame, with an available flag when stats are null (non-rendering frame).",
+            Description = "Read rendering sample statistics from UnityEditor.UnityStats (batches, triangles, vertices, setPassCalls, screenRes, usedTextureMemory, renderTextureCount). These fields are only populated while the Game View is actively rendering; the response includes an `available` flag and diagnostics explaining when values are null, so callers do not mistake empty samples for data loss.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read rendering stats", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            // UnityStats 是 internal Editor 类型,不同 Unity 版本/反射策略下可能取不到
+            var statsType = ProfilerToolSupport.FindType("UnityEditor.UnityStats");
+            if (statsType == null)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Available = false,
+                    Diagnostics = "UnityStats type is not available in this Unity version.",
+                    NextActions = new List<string>
+                    {
+                        "Use a Unity 2022.x Editor where UnityEditor.UnityStats is reachable via reflection.",
+                        "For per-frame GPU/render counts prefer profiler.frame or profiler.hierarchy while the Profiler is recording."
+                    }
+                });
+            }
+
+            var stats = new RenderingStats();
+            var names = new[] { "batches", "triangles", "vertices", "setPassCalls", "screenRes", "usedTextureMemory", "renderTextureCount" };
+            var anyValue = false;
+            // 用反射名匹配属性(大小写敏感),按 UnityStats 实际成员名读取
+            foreach (var name in names)
+            {
+                var value = ProfilerToolSupport.StringMemberValue(statsType, null, name);
+                if (!string.IsNullOrEmpty(value)) anyValue = true;
+                AssignStat(stats, name, value);
+            }
+
+            var result = new Result
+            {
+                Available = anyValue,
+                Stats = stats
+            };
+            if (!anyValue)
+            {
+                result.Diagnostics = "UnityStats fields are null for the sampled frame. Rendering statistics are only populated while the Game View is actively rendering (enter Play Mode or focus the Game View and retry).";
+                result.NextActions = new List<string>
+                {
+                    "Enter Play Mode or make the Game View render at least one frame, then retry.",
+                    "For stable per-frame timings use profiler.frame (FrameTimingManager) or profiler.hierarchy."
+                };
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+
+        // 按 UnityStats 成员名把反射读到的 string 值赋给 DTO 对应字段
+        private static void AssignStat(RenderingStats stats, string name, string value)
+        {
+            switch (name)
+            {
+                case "batches": stats.Batches = value; break;
+                case "triangles": stats.Triangles = value; break;
+                case "vertices": stats.Vertices = value; break;
+                case "setPassCalls": stats.SetPassCalls = value; break;
+                case "screenRes": stats.ScreenRes = value; break;
+                case "usedTextureMemory": stats.UsedTextureMemory = value; break;
+                case "renderTextureCount": stats.RenderTextureCount = value; break;
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/profiler/script-stats.cs

@@ -0,0 +1,35 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerScriptStatsTool : IUnityCliTool<ProfilerScriptStatsTool.Request, ProfilerScriptStatsTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public long GcAllocs { get; set; } public long MonoHeapSize { get; set; } public long MonoUsedSize { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.script-stats", Summary = "Script/GC memory sample statistics (gcAllocs, monoHeap, monoUsed).",
+            Description = "Read Script/GC memory sample statistics from Unity Profiler counters. Read-only.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read script stats", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result
+        {
+            GcAllocs = (long)Profiler.GetTotalAllocatedMemoryLong(),
+            MonoHeapSize = (long)Profiler.GetMonoHeapSizeLong(),
+            MonoUsedSize = (long)Profiler.GetMonoUsedSizeLong()
+        });
+    }
+}
+#endif

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

@@ -0,0 +1,55 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerStartTool : IUnityCliTool<ProfilerStartTool.Request, ProfilerStartTool.Result>
+    {
+        public sealed class Request { public bool DeepProfiling { get; set; } public string LogFile { get; set; } public bool EnableCallstacks { get; set; } }
+        public sealed class Result { public ProfilerState Profiler { get; set; } public List<ProfilerPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.start", Summary = "Begin profiler data collection with optional deep profiling, binary log file and allocation callstacks.",
+            Description = "Begin Unity Profiler data collection in the Editor session. May enable deep profiling, binary logging or allocation callstacks.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "profiler-session-state" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Start profiler", Input = new Request { } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ctx.CommitEffect();
+            if (!ProfilerToolSupport.PreviousProfilerEditorRecording.HasValue)
+                ProfilerToolSupport.PreviousProfilerEditorRecording = ProfilerToolSupport.GetProfilerEditorRecording();
+            ProfilerToolSupport.SetProfilerEditorRecording(true);
+            ProfilerToolSupport.SetProfilerSessionEnabled(true);
+            ProfilerToolSupport.SetProfilerDeepProfiling(request.DeepProfiling);
+            if (!string.IsNullOrEmpty(request.LogFile)) { Profiler.logFile = request.LogFile; Profiler.enableBinaryLog = true; }
+            if (request.EnableCallstacks) Profiler.enableAllocationCallstacks = true;
+            var stable = await ctx.Wait.UntilStable(() =>
+            {
+                var state = ProfilerToolSupport.BuildProfilerState();
+                return state.Enabled && state.ProfileEditor && ProfilerToolSupport.GetProfilerDeepProfiling() == request.DeepProfiling
+                    && (string.IsNullOrEmpty(request.LogFile) || (state.EnableBinaryLog && string.Equals(state.LogFile, request.LogFile, StringComparison.Ordinal)))
+                    && (!request.EnableCallstacks || state.EnableAllocationCallstacks);
+            }, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            var observed = ProfilerToolSupport.BuildProfilerState();
+            if (!stable || !observed.Enabled || !observed.ProfileEditor || ProfilerToolSupport.GetProfilerDeepProfiling() != request.DeepProfiling || (!string.IsNullOrEmpty(request.LogFile) && (!observed.EnableBinaryLog || !string.Equals(observed.LogFile, request.LogFile, StringComparison.Ordinal))) || (request.EnableCallstacks && !observed.EnableAllocationCallstacks))
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_STATE_MISMATCH", "Profiler start write did not produce the requested stable readback.", "Inspect Profiler availability and Editor session state, then retry.");
+            return new Result
+            {
+                Profiler = observed,
+                PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.start" } }
+            };
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,36 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    public class ProfilerStatusTool : IUnityCliTool<ProfilerStatusTool.Request, ProfilerStatusTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result
+        {
+            public ProfilerState Profiler { get; set; }
+            public List<string> Modules { get; set; }
+            public string Platform { get; set; }
+            public bool FrameTimingAvailable { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.status", Summary = "Check whether the Unity profiler is currently active, with max-used memory and platform support.",
+            Description = "Read the current Unity Profiler state, available modules, max-used memory and platform support.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Check profiler status", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new System.Threading.Tasks.ValueTask<Result>(new Result
+        {
+            Profiler = ProfilerToolSupport.BuildProfilerState(),
+            Modules = ProfilerToolSupport.BuildProfilerModules(),
+            Platform = Application.platform.ToString(),
+            FrameTimingAvailable = ProfilerToolSupport.IsFrameTimingAvailable()
+        });
+    }
+}
+#endif

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

@@ -0,0 +1,53 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace UnityCli
+{
+    public class ProfilerStopTool : IUnityCliTool<ProfilerStopTool.Request, ProfilerStopTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public ProfilerState Profiler { get; set; } public List<ProfilerPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.stop", Summary = "Stop profiler data collection.",
+            Description = "Stop Unity Profiler data collection and restore the previous Editor profiling state.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "profiler-session-state" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Stop profiler", Input = new Request { } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ctx.CommitEffect();
+            ProfilerToolSupport.SetProfilerSessionEnabled(false);
+            if (ProfilerToolSupport.PreviousProfilerEditorRecording.HasValue)
+            {
+                ProfilerToolSupport.SetProfilerEditorRecording(ProfilerToolSupport.PreviousProfilerEditorRecording.Value);
+                ProfilerToolSupport.PreviousProfilerEditorRecording = null;
+            }
+            Profiler.enableBinaryLog = false;
+            var stable = await ctx.Wait.UntilStable(() =>
+            {
+                var state = ProfilerToolSupport.BuildProfilerState();
+                return !state.Enabled && !state.EnableBinaryLog;
+            }, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            var observed = ProfilerToolSupport.BuildProfilerState();
+            if (!stable || observed.Enabled || observed.EnableBinaryLog)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_STATE_MISMATCH", "Profiler stop write did not produce the requested stable readback.", "Inspect Profiler availability and Editor session state, then retry.");
+            return new Result
+            {
+                Profiler = observed,
+                PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.stop" } }
+            };
+        }
+    }
+}
+#endif