@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/profiler/frame-debugger/events.cs

@@ -0,0 +1,140 @@
+#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 ProfilerFrameDebuggerEventsTool : IUnityCliTool<ProfilerFrameDebuggerEventsTool.Request, ProfilerFrameDebuggerEventsTool.Result>
+    {
+        public sealed class Request { public int? PageSize { get; set; } public int? Cursor { get; set; } }
+
+        public sealed class Result
+        {
+            public long TotalEvents { get; set; }
+            public List<FrameDebuggerEvent> Events { get; set; }
+            public string Note { get; set; }
+            public long? NextCursor { get; set; }
+        }
+
+        // 单个 draw call 事件:字段按 FrameDebuggerUtility 反射可用性填充(不可用字段省略)
+        public sealed class FrameDebuggerEvent
+        {
+            public long Index { get; set; }
+            public string Name { get; set; }
+            public string EventType { get; set; }
+            public string GameObjectInstanceID { get; set; }
+            public string ShaderName { get; set; }
+            public string PassName { get; set; }
+            public string VertexCount { get; set; }
+            public string IndexCount { get; set; }
+            public string InstanceCount { get; set; }
+            public string MeshName { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.frame-debugger.events",
+            Summary = "Read draw call events captured by the Frame Debugger, paginated.",
+            Description = "Read draw call events captured by the Frame Debugger, paginated. Returns shaderName, vertexCount, indexCount and similar fields per event when available.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read first page of events", Input = new Request { PageSize = 50, Cursor = 0 } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!FrameDebuggerReflection.Available)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_FRAME_DEBUGGER_UNAVAILABLE",
+                    "FrameDebuggerUtility not found via reflection.",
+                    "Run in a Unity Editor with Frame Debugger support.");
+            }
+            var pageSize = request.PageSize ?? 50;
+            var cursor = request.Cursor ?? 0;
+            var totalEvents = FrameDebuggerReflection.GetEventCount();
+
+            if (totalEvents == 0)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    TotalEvents = 0,
+                    Events = new List<FrameDebuggerEvent>(),
+                    Note = "Frame Debugger has no events. Is it enabled?"
+                });
+            }
+
+            // 反射读取事件描述数组(含 type/name 信息)
+            object[] frameEvents = null;
+            if (FrameDebuggerReflection.GetEventsMethod != null)
+            {
+                try
+                {
+                    var raw = FrameDebuggerReflection.GetEventsMethod.Invoke(null, null);
+                    if (raw is Array arr) { frameEvents = new object[arr.Length]; arr.CopyTo(frameEvents, 0); }
+                }
+                catch { /* 忽略,逐个读取 */ }
+            }
+
+            var end = Math.Min(cursor + pageSize, totalEvents);
+            var events = new List<FrameDebuggerEvent>();
+            for (int i = cursor; i < end; i++)
+            {
+                var entry = new FrameDebuggerEvent { Index = i };
+                if (FrameDebuggerReflection.EventNameMethod != null)
+                {
+                    try { entry.Name = (string)FrameDebuggerReflection.EventNameMethod.Invoke(null, new object[] { i }); }
+                    catch { /* 跳过 name */ }
+                }
+                if (frameEvents != null && i < frameEvents.Length)
+                {
+                    entry.EventType = FrameDebuggerReflection.ReadField(frameEvents[i], "type");
+                    entry.GameObjectInstanceID = FrameDebuggerReflection.ReadField(frameEvents[i], "gameObjectInstanceID");
+                }
+                if (FrameDebuggerReflection.GetEventDataMethod != null)
+                {
+                    try
+                    {
+                        var paramInfos = FrameDebuggerReflection.GetEventDataMethod.GetParameters();
+                        object eventData;
+                        if (paramInfos.Length == 2 && FrameDebuggerReflection.EventDataType != null)
+                        {
+                            eventData = Activator.CreateInstance(FrameDebuggerReflection.EventDataType);
+                            var args = new object[] { i, eventData };
+                            var ok = FrameDebuggerReflection.GetEventDataMethod.Invoke(null, args);
+                            eventData = (ok is true) ? args[1] : null;
+                        }
+                        else
+                        {
+                            eventData = FrameDebuggerReflection.GetEventDataMethod.Invoke(null, new object[] { i });
+                        }
+                        if (eventData != null)
+                        {
+                            entry.ShaderName = FrameDebuggerReflection.ReadField(eventData, "shaderName");
+                            entry.PassName = FrameDebuggerReflection.ReadField(eventData, "passName");
+                            entry.VertexCount = FrameDebuggerReflection.ReadField(eventData, "vertexCount");
+                            entry.IndexCount = FrameDebuggerReflection.ReadField(eventData, "indexCount");
+                            entry.InstanceCount = FrameDebuggerReflection.ReadField(eventData, "instanceCount");
+                            entry.MeshName = FrameDebuggerReflection.ReadField(eventData, "meshName");
+                        }
+                    }
+                    catch { /* 跳过该事件详细数据 */ }
+                }
+                events.Add(entry);
+            }
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                TotalEvents = totalEvents,
+                Events = events,
+                NextCursor = end < totalEvents ? (long?)end : null
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,38 @@
+#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 ProfilerFrameTool : IUnityCliTool<ProfilerFrameTool.Request, ProfilerFrameTool.Result>
+    {
+        public sealed class Request { public string Module { get; set; } = "CPU Usage"; }
+        public sealed class Result { public ProfilerState Profiler { get; set; } public ProfilerFrameInfo Frame { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.frame", Summary = "Read current frame count, timing, module diagnostics and FrameTimingManager CPU/GPU fields.",
+            Description = "Capture FrameTimingManager timing, then return current frame count, selected profiler module diagnostics, and CPU/GPU timing fields.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "frame-timing-capture" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read frame timing", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ctx.CommitEffect();
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+            Profiler = ProfilerToolSupport.BuildProfilerState(),
+            Frame = ProfilerToolSupport.BuildProfilerFrame(request.Module ?? "CPU Usage")
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,183 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Reflection;
+
+namespace UnityCli
+{
+    public class ProfilerHierarchyTool : IUnityCliTool<ProfilerHierarchyTool.Request, ProfilerHierarchyTool.Result>
+    {
+        public sealed class Request
+        {
+            public int? Frame { get; set; }
+            public int? Thread { get; set; }
+            public int? Top { get; set; }
+            public int? Depth { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public List<HierarchyItem> RootItems { get; set; }
+        }
+
+        public sealed class HierarchyItem
+        {
+            public long Id { get; set; }
+            public string Name { get; set; }
+            public long Depth { get; set; }
+            public double Ms { get; set; }
+            public long SiblingCount { get; set; }
+            public long ChildCount { get; set; }
+            public bool ChildrenTruncated { get; set; }
+            public List<HierarchyItem> Children { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.hierarchy",
+            Summary = "Read the per-function CPU call hierarchy (marker tree) for one profiler frame/thread.",
+            Description = "Read the CPU call hierarchy for a single profiler frame and thread via ProfilerDriver.GetHierarchyFrameDataView, recursing GetItemChildren to emit a structured marker tree. Defaults are bounded (top=20, depth=5); each node reports childCount and childrenTruncated so AI can see when detail was omitted.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Latest frame main-thread top markers", Input = new Request { Top = 20, Depth = 5 } },
+                new ToolExample { Description = "Latest frame on the main thread", Input = new Request { Frame = -1, Thread = 0 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var driverType = ProfilerToolSupport.FindType("UnityEditorInternal.ProfilerDriver");
+            if (driverType == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
+                    "UnityEditorInternal.ProfilerDriver is not available; hierarchy requires the Editor Profiler.",
+                    "Capture Profiler data in the selected Live Editor, then retry.");
+            }
+
+            // 省略 frame 时读取最新已采集帧
+            var frame = request.Frame ?? ProfilerToolSupport.ProfilerDriverIntProperty("lastFrameIndex", -1);
+            var threadIndex = request.Thread ?? 0;
+            var top = Math.Max(1, Math.Min(request.Top ?? 20, 5000));
+            var maxDepth = Math.Max(1, Math.Min(request.Depth ?? 5, 32));
+
+            var hierarchyViewType = ProfilerToolSupport.FindType("UnityEditor.Profiling.HierarchyFrameDataView")
+                ?? ProfilerToolSupport.FindType("UnityEditorInternal.HierarchyFrameDataView")
+                ?? ProfilerToolSupport.FindType("UnityEngine.Profiling.HierarchyFrameDataView");
+            if (hierarchyViewType == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
+                    "HierarchyFrameDataView type not available in this Unity version.",
+                    "Use an Editor version that exposes UnityEditor.Profiling.HierarchyFrameDataView, then record profiler frames before retrying.");
+            }
+
+            var viewModesType = hierarchyViewType.GetTypeInfo().GetDeclaredNestedType("ViewModes")?.AsType();
+            var getHierarchy = viewModesType == null
+                ? null
+                : driverType.GetMethod("GetHierarchyFrameDataView", new[] { typeof(int), typeof(int), viewModesType, typeof(int), typeof(bool) });
+            // 不同 Unity 版本签名不同;退回 (int,int) 最简重载
+            if (getHierarchy == null)
+            {
+                getHierarchy = driverType.GetMethod("GetHierarchyFrameDataView", new[] { typeof(int), typeof(int) });
+            }
+            if (getHierarchy == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
+                    "ProfilerDriver.GetHierarchyFrameDataView overload not found.",
+                    "Unity version may not expose this API via reflection.");
+            }
+
+            object view = null;
+            try
+            {
+                view = getHierarchy.GetParameters().Length == 2
+                    ? getHierarchy.Invoke(null, new object[] { frame, threadIndex })
+                    : getHierarchy.Invoke(null, new object[] { frame, threadIndex, 0, 0, false });
+            }
+            catch (Exception exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_UNAVAILABLE",
+                    "Failed to acquire hierarchy frame data: " + exception.Message,
+                    HierarchyDetails(frame, threadIndex),
+                    new[] { "Make sure the Profiler has recorded frames; pass profiler.start then profiler.stop, then query a recorded frame (or omit frame to use the latest)." });
+            }
+            if (view == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_NO_DATA",
+                    "No hierarchy data available for the requested frame/thread.",
+                    "Record profiler frames first (profiler.start → play → profiler.stop), then query a valid frame.");
+            }
+
+            var validProp = hierarchyViewType.GetProperty("valid");
+            if (validProp != null && !(bool)validProp.GetValue(view, null))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_HIERARCHY_NO_DATA",
+                    "HierarchyFrameDataView is invalid for the requested frame/thread.",
+                    "Record profiler frames first, then query a valid frame.");
+            }
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                RootItems = BuildHierarchyItems(view, hierarchyViewType, 0, top, maxDepth, 0)
+            });
+        }
+
+        // 递归构建调用树节点:按 top 限制每层子项数量、depth 限制最大深度,避免单帧树过大
+        private static List<HierarchyItem> BuildHierarchyItems(object view, Type viewType, int itemId, int top, int maxDepth, int depth)
+        {
+            var result = new List<HierarchyItem>();
+            if (depth > maxDepth) return result;
+
+            var childrenMethod = viewType.GetMethod("GetItemChildren", new[] { typeof(int), typeof(List<int>) });
+            var nameMethod = viewType.GetMethod("GetItemName", new[] { typeof(int) });
+            var msMethod = viewType.GetMethod("GetItemThreadMS", new[] { typeof(int) });
+
+            var childIds = new List<int>();
+            try { if (childrenMethod != null) childrenMethod.Invoke(view, new object[] { itemId, childIds }); }
+            catch { return result; }
+
+            var emitted = 0;
+            foreach (var childId in childIds)
+            {
+                if (emitted >= top) break;
+                string name = null;
+                double ms = 0;
+                try { if (nameMethod != null) name = nameMethod.Invoke(view, new object[] { childId }) as string; } catch { }
+                try { if (msMethod != null) { var v = msMethod.Invoke(view, new object[] { childId }); if (v is double d) ms = d; else if (v is float f) ms = f; } } catch { }
+
+                var grandChildren = new List<int>();
+                try { if (childrenMethod != null) childrenMethod.Invoke(view, new object[] { childId, grandChildren }); } catch { }
+
+                var item = new HierarchyItem
+                {
+                    Id = childId,
+                    Name = name ?? "(unknown)",
+                    Depth = depth,
+                    Ms = ms,
+                    SiblingCount = childIds.Count,
+                    ChildCount = grandChildren.Count,
+                    ChildrenTruncated = grandChildren.Count > top || (grandChildren.Count > 0 && depth + 1 > maxDepth)
+                };
+                if (grandChildren.Count > 0 && depth + 1 <= maxDepth)
+                {
+                    item.Children = BuildHierarchyItems(view, viewType, childId, top, maxDepth, depth + 1);
+                }
+                result.Add(item);
+                emitted++;
+            }
+            return result;
+        }
+
+        private static ProfilerHierarchyDetails HierarchyDetails(int frame, int threadIndex)
+        {
+            return new ProfilerHierarchyDetails
+            {
+                Frame = frame,
+                Thread = threadIndex,
+                ProfilerRecording = ProfilerToolSupport.GetProfilerSessionEnabled()
+            };
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,85 @@
+#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 ProfilerLoadTool : IUnityCliTool<ProfilerLoadTool.Request, ProfilerLoadTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Path { get; set; } }
+        public sealed class Result { public long InputSizeBytes { get; set; } public string InputSha256 { get; set; } public long FirstFrameIndex { get; set; } public long LastFrameIndex { get; set; } public bool Loaded { get; set; } public List<ProfilerPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.load", Summary = "Load a saved profiler data file (.raw/.data) into the Profiler window.",
+            Description = "Stop Profiler recording, clear the current frame buffer, then load one saved profiler data file. Success requires an attributable non-empty frame range after the empty-buffer barrier while the input size and SHA-256 remain unchanged.",
+            Group = "profiler",DestructiveHint = false, SideEffects = new[] { "profiler-loaded-data-session", "profiler-recording-stop" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Load profiler data", Input = new Request { Path = "Artifacts/profiler/baseline.raw" } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(request.Path))
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_PATH_REQUIRED", "profiler.load requires path.", "Pass a .raw or .data file path.");
+            var resolvedPath = System.IO.Path.GetFullPath(request.Path);
+            if (!File.Exists(resolvedPath))
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_CAPTURE_NOT_FOUND", "Profiler capture file not found: " + request.Path, "Use profiler.capture or profiler.export to create a capture file.");
+            var inputSizeBytes = new FileInfo(resolvedPath).Length;
+            if (inputSizeBytes <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_CAPTURE_EMPTY", "Profiler capture file is empty: " + resolvedPath, "Pass a non-empty capture produced by profiler.capture or profiler.export.");
+            var inputSha256 = ProfilerToolSupport.FileSha256(resolvedPath);
+            var driverType = ProfilerToolSupport.FindType("UnityEditorInternal.ProfilerDriver");
+            if (driverType == null)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_UNSUPPORTED", "UnityEditorInternal.ProfilerDriver is unavailable.", "Use a Unity Editor version that supports loading profiler captures.");
+            var loadMethod = driverType.GetMethod("LoadProfile", new Type[] { typeof(string), typeof(bool) });
+            var clearMethod = driverType.GetMethod("ClearAllFrames", BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic);
+            if (loadMethod == null || clearMethod == null)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_UNSUPPORTED", "ProfilerDriver.LoadProfile or ClearAllFrames is unavailable.", "Use a supported Unity Editor version that exposes isolated profiler capture loading.");
+
+            // 停止采集并建立空 frame buffer barrier，后续出现的 frame 只能归因于本次 LoadProfile。
+            ctx.CommitEffect();
+            ProfilerToolSupport.SetProfilerSessionEnabled(false);
+            ProfilerToolSupport.SetProfilerEditorRecording(false);
+            clearMethod.Invoke(null, null);
+            var cleared = await ctx.Wait.UntilStable(() =>
+                ProfilerToolSupport.ProfilerDriverIntProperty("firstFrameIndex", -1) < 0
+                && ProfilerToolSupport.ProfilerDriverIntProperty("lastFrameIndex", -1) < 0,
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            if (!cleared)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_PRECONDITION_FAILED", "Profiler frame buffer could not be cleared before loading the capture.", "Close active Profiler recording and retry.");
+            try { loadMethod.Invoke(null, new object[] { resolvedPath, false }); }
+            catch (TargetInvocationException exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_FAILED", "Profiler capture could not be loaded: " + (exception.InnerException ?? exception).Message, "Check that the capture file is valid and compatible with this Unity Editor version.");
+            }
+            catch (Exception exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_FAILED", "Profiler capture could not be loaded: " + exception.Message, "Check that the capture file is valid and compatible with this Unity Editor version.");
+            }
+            var loaded = await ctx.Wait.UntilStable(() =>
+            {
+                var first = ProfilerToolSupport.ProfilerDriverIntProperty("firstFrameIndex", -1);
+                var last = ProfilerToolSupport.ProfilerDriverIntProperty("lastFrameIndex", -1);
+                return !ProfilerToolSupport.GetProfilerSessionEnabled()
+                    && first >= 0 && last >= first
+                    && new FileInfo(resolvedPath).Length == inputSizeBytes
+                    && string.Equals(ProfilerToolSupport.FileSha256(resolvedPath), inputSha256, StringComparison.Ordinal);
+            }, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            var observedFirst = ProfilerToolSupport.ProfilerDriverIntProperty("firstFrameIndex", -1);
+            var observedLast = ProfilerToolSupport.ProfilerDriverIntProperty("lastFrameIndex", -1);
+            if (!loaded || ProfilerToolSupport.GetProfilerSessionEnabled() || observedFirst < 0 || observedLast < observedFirst)
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_PROOF_MISSING", "ProfilerDriver did not expose an attributable loaded frame range for " + resolvedPath + ".", "Verify that the capture contains readable frames and matches this Unity version.");
+            if (new FileInfo(resolvedPath).Length != inputSizeBytes || !string.Equals(ProfilerToolSupport.FileSha256(resolvedPath), inputSha256, StringComparison.Ordinal))
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_LOAD_PROOF_MISSING", "Profiler capture input changed while loading: " + resolvedPath, "Keep the capture file unchanged and retry.");
+            return new Result { InputSizeBytes = inputSizeBytes, InputSha256 = inputSha256, FirstFrameIndex = observedFirst, LastFrameIndex = observedLast, Loaded = true, PlannedEffects = new List<ProfilerPlannedEffect> { new ProfilerPlannedEffect { Type = "profiler.load", Path = resolvedPath, SideEffects = "sha256=" + inputSha256 } } };
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,78 @@
+#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 ProfilerMemorySnapshotCompareTool : IUnityCliTool<ProfilerMemorySnapshotCompareTool.Request, ProfilerMemorySnapshotCompareTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string SnapshotA { get; set; }
+            [UnityCliRequired] public string SnapshotB { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public MemorySnapshotEntry SnapshotA { get; set; }
+            public MemorySnapshotEntry SnapshotB { get; set; }
+            public SnapshotDelta Delta { get; set; }
+            public string Note { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.memory-snapshot.compare",
+            Summary = "Compare two .snap memory snapshots at file-level metadata (size delta, time delta).",
+            Description = "Compare two .snap memory snapshots at file-level metadata (size delta, time delta). For object-level diff, open both in the Memory Profiler window.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Compare two snapshots", Input = new Request { SnapshotA = "snap1.snap", SnapshotB = "snap2.snap" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var snapshotAPath = request.SnapshotA;
+            var snapshotBPath = request.SnapshotB;
+            if (string.IsNullOrEmpty(snapshotAPath) || string.IsNullOrEmpty(snapshotBPath))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_PATH_REQUIRED",
+                    "profiler.memory-snapshot.compare requires --snapshot-a and --snapshot-b.",
+                    "Pass two .snap file paths.");
+            }
+            if (!File.Exists(snapshotAPath))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_NOT_FOUND",
+                    "Snapshot file not found: " + snapshotAPath,
+                    "Check the path or run profiler.memory-snapshot.list.");
+            }
+            if (!File.Exists(snapshotBPath))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PROFILER_SNAPSHOT_NOT_FOUND",
+                    "Snapshot file not found: " + snapshotBPath,
+                    "Check the path or run profiler.memory-snapshot.list.");
+            }
+
+            var fiA = new FileInfo(snapshotAPath);
+            var fiB = new FileInfo(snapshotBPath);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                SnapshotA = MemorySnapshotEntry.FromFileInfo(fiA),
+                SnapshotB = MemorySnapshotEntry.FromFileInfo(fiB),
+                Delta = new SnapshotDelta
+                {
+                    SizeDeltaBytes = fiB.Length - fiA.Length,
+                    TimeDeltaSeconds = (fiB.CreationTimeUtc - fiA.CreationTimeUtc).TotalSeconds
+                },
+                Note = "File-level metadata comparison. For object-level diff, open both snapshots in the Memory Profiler window."
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,73 @@
+#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 ProfilerMemorySnapshotListTool : IUnityCliTool<ProfilerMemorySnapshotListTool.Request, ProfilerMemorySnapshotListTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public List<MemorySnapshotEntry> Snapshots { get; set; }
+            public List<string> SearchedDirs { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "profiler.memory-snapshot.list",
+            Summary = "List .snap memory snapshot files in the default capture directories or a custom path.",
+            Description = "List .snap memory snapshot files in the default capture directories or a custom path. This reads file metadata only and does not open or modify snapshots.",
+            Group = "profiler",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "List snapshots in default dirs", Input = new Request { } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var searchPath = request.Path;
+            var dirs = new List<string>();
+            if (!string.IsNullOrEmpty(searchPath))
+            {
+                dirs.Add(searchPath);
+            }
+            else
+            {
+                dirs.Add(Path.Combine(Application.temporaryCachePath, "MemoryCaptures"));
+                dirs.Add(Path.Combine(Application.dataPath, "..", "MemoryCaptures"));
+            }
+
+            var snapshots = new List<MemorySnapshotEntry>();
+            foreach (var dir in dirs)
+            {
+                if (!Directory.Exists(dir)) continue;
+                foreach (var file in Directory.GetFiles(dir, "*.snap"))
+                {
+                    var fi = new FileInfo(file);
+                    snapshots.Add(new MemorySnapshotEntry
+                    {
+                        Path = fi.FullName,
+                        SizeBytes = fi.Length,
+                        Created = fi.CreationTimeUtc.ToString("O", CultureInfo.InvariantCulture)
+                    });
+                }
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Snapshots = snapshots,
+                SearchedDirs = dirs
+            });
+        }
+    }
+}
+#endif