@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/editor/EditorWindowFocusToolSupport.cs

@@ -0,0 +1,194 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Diagnostics;
+using System.Runtime.InteropServices;
+using System.Text;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>选定Editor process的native main-window冻结、focus effect和foreground proof owner。</summary>
+    internal static class EditorWindowFocusToolSupport
+    {
+        internal sealed class Plan
+        {
+            internal IntPtr Window;
+            internal int ProcessId;
+            internal string Title;
+            internal bool WasMinimized;
+            internal object HostView;
+            internal System.Reflection.MethodInfo HostFocus;
+        }
+
+        internal static Plan Prepare()
+        {
+#if !UNITY_EDITOR_WIN
+            throw new UnityCliBridge.BridgeCommandException("E_EDITOR_FOCUS_UNAVAILABLE", "editor.focus is available only on Windows.", "Run this Tool from a Windows Unity Editor instance.");
+#else
+            var processId = Process.GetCurrentProcess().Id;
+            var windows = TopLevelWindows(processId);
+            if (windows.Count == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_FOCUS_WINDOW_NOT_FOUND", "No visible top-level window belongs to the selected Unity Editor process.", "Open the selected Editor main window and retry.");
+            windows.Sort((left, right) => Score(right).CompareTo(Score(left)));
+            var target = windows[0];
+            object host;
+            System.Reflection.MethodInfo focus;
+            ResolveHostView(out host, out focus);
+            return new Plan { Window = target.Handle, ProcessId = processId, Title = target.Title, WasMinimized = IsIconic(target.Handle), HostView = host, HostFocus = focus };
+#endif
+        }
+
+        /// <summary>调用方必须先跨barrier；所有effect严格作用于冻结的current-process HWND。</summary>
+        internal static void Apply(Plan plan)
+        {
+#if !UNITY_EDITOR_WIN
+            throw new UnityCliBridge.BridgeCommandException("E_EDITOR_FOCUS_UNAVAILABLE", "editor.focus is available only on Windows.");
+#else
+            if (plan == null || plan.Window == IntPtr.Zero || !WindowBelongsToProcess(plan.Window, plan.ProcessId))
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_FOCUS_TARGET_CHANGED", "The frozen Unity Editor window no longer belongs to the selected process.", "Inspect editor.state and retry with the current instance.");
+            var foreground = GetForegroundWindow();
+            uint foregroundProcess;
+            var foregroundThread = foreground == IntPtr.Zero ? 0u : GetWindowThreadProcessId(foreground, out foregroundProcess);
+            var currentThread = GetCurrentThreadId();
+            var attached = foregroundThread != 0 && foregroundThread != currentThread && AttachThreadInput(currentThread, foregroundThread, true);
+            try
+            {
+                if (plan.WasMinimized) ShowWindowAsync(plan.Window, 9);
+                try { plan.HostFocus?.Invoke(plan.HostView, null); } catch { }
+                BringWindowToTop(plan.Window);
+                SetForegroundWindow(plan.Window);
+                SetFocus(plan.Window);
+            }
+            finally
+            {
+                if (attached) AttachThreadInput(currentThread, foregroundThread, false);
+            }
+#endif
+        }
+
+        internal static bool IsForeground(Plan plan)
+        {
+#if UNITY_EDITOR_WIN
+            return plan != null && plan.Window != IntPtr.Zero && GetForegroundWindow() == plan.Window && WindowBelongsToProcess(plan.Window, plan.ProcessId);
+#else
+            return false;
+#endif
+        }
+
+        internal static EditorFocusWindowState Snapshot(Plan plan)
+        {
+            return new EditorFocusWindowState
+            {
+                ProcessId = plan == null ? 0 : plan.ProcessId,
+                WindowHandle = plan == null ? null : "0x" + plan.Window.ToInt64().ToString("x"),
+                Title = plan == null ? null : plan.Title,
+                Foreground = IsForeground(plan),
+#if UNITY_EDITOR_WIN
+                Minimized = plan != null && plan.Window != IntPtr.Zero && IsIconic(plan.Window)
+#else
+                Minimized = false
+#endif
+            };
+        }
+
+#if UNITY_EDITOR_WIN
+        private sealed class WindowInfo { internal IntPtr Handle; internal string Title; }
+        private delegate bool EnumWindowsProc(IntPtr hwnd, IntPtr parameter);
+
+        private static List<WindowInfo> TopLevelWindows(int processId)
+        {
+            var result = new List<WindowInfo>();
+            EnumWindows((window, _) =>
+            {
+                uint ownerProcess;
+                GetWindowThreadProcessId(window, out ownerProcess);
+                if (ownerProcess != processId || !IsWindowVisible(window) || GetWindow(window, 4) != IntPtr.Zero) return true;
+                var length = Math.Min(4096, Math.Max(0, GetWindowTextLength(window)));
+                var title = new StringBuilder(length + 1);
+                GetWindowText(window, title, title.Capacity);
+                result.Add(new WindowInfo { Handle = window, Title = title.ToString() });
+                return true;
+            }, IntPtr.Zero);
+            return result;
+        }
+
+        private static int Score(WindowInfo value)
+        {
+            if (value == null) return int.MinValue;
+            var score = string.IsNullOrEmpty(value.Title) ? 0 : 10;
+            if (!string.IsNullOrEmpty(value.Title) && value.Title.IndexOf("Unity", StringComparison.OrdinalIgnoreCase) >= 0) score += 100;
+            if (!IsIconic(value.Handle)) score += 5;
+            return score;
+        }
+
+        private static bool WindowBelongsToProcess(IntPtr window, int processId)
+        {
+            uint actual;
+            GetWindowThreadProcessId(window, out actual);
+            return actual == processId && IsWindowVisible(window);
+        }
+
+        [DllImport("user32.dll")] private static extern bool EnumWindows(EnumWindowsProc callback, IntPtr parameter);
+        [DllImport("user32.dll")] private static extern uint GetWindowThreadProcessId(IntPtr window, out uint processId);
+        [DllImport("user32.dll")] private static extern bool IsWindowVisible(IntPtr window);
+        [DllImport("user32.dll")] private static extern bool IsIconic(IntPtr window);
+        [DllImport("user32.dll")] private static extern int GetWindowTextLength(IntPtr window);
+        [DllImport("user32.dll", CharSet = CharSet.Unicode)] private static extern int GetWindowText(IntPtr window, StringBuilder text, int capacity);
+        [DllImport("user32.dll")] private static extern IntPtr GetWindow(IntPtr window, uint command);
+        [DllImport("user32.dll")] private static extern bool ShowWindowAsync(IntPtr window, int command);
+        [DllImport("user32.dll")] private static extern bool BringWindowToTop(IntPtr window);
+        [DllImport("user32.dll")] private static extern bool SetForegroundWindow(IntPtr window);
+        [DllImport("user32.dll")] private static extern IntPtr SetFocus(IntPtr window);
+        [DllImport("user32.dll")] private static extern IntPtr GetForegroundWindow();
+        [DllImport("user32.dll")] private static extern bool AttachThreadInput(uint attach, uint attachTo, bool value);
+        [DllImport("kernel32.dll")] private static extern uint GetCurrentThreadId();
+#endif
+
+        /// <summary>HostView只作为激活辅助；terminal仍以Win32 exact HWND为准。</summary>
+        private static void ResolveHostView(out object host, out System.Reflection.MethodInfo focus)
+        {
+            host = null;
+            focus = null;
+            try
+            {
+                const System.Reflection.BindingFlags flags = System.Reflection.BindingFlags.Static | System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.NonPublic;
+                var assembly = typeof(EditorWindow).Assembly;
+                var containerType = assembly.GetType("UnityEditor.ContainerWindow");
+                var hostType = assembly.GetType("UnityEditor.HostView");
+                var guiType = assembly.GetType("UnityEditor.GUIView");
+                var isMain = containerType?.GetMethod("IsMainWindow", flags);
+                focus = guiType?.GetMethod("Focus", flags, null, Type.EmptyTypes, null);
+                if (containerType == null || hostType == null || isMain == null || focus == null) return;
+                object main = null;
+                foreach (var window in Resources.FindObjectsOfTypeAll(containerType))
+                    if ((bool)isMain.Invoke(window, null)) { main = window; break; }
+                var root = containerType.GetProperty("rootView", flags)?.GetValue(main, null) ?? containerType.GetField("m_RootView", flags)?.GetValue(main);
+                if (root == null) return;
+                if (hostType.IsInstanceOfType(root)) { host = root; return; }
+                var children = root.GetType().GetProperty("allChildren", flags)?.GetValue(root, null) as Array;
+                if (children == null) return;
+                foreach (var child in children)
+                    if (child != null && hostType.IsInstanceOfType(child) && child.GetType().Name == "DockArea") { host = child; return; }
+                foreach (var child in children)
+                    if (child != null && hostType.IsInstanceOfType(child)) { host = child; return; }
+            }
+            catch
+            {
+                host = null;
+                focus = null;
+            }
+        }
+    }
+
+    public sealed class EditorFocusWindowState
+    {
+        public long ProcessId { get; set; }
+        public string WindowHandle { get; set; }
+        public string Title { get; set; }
+        public bool Foreground { get; set; }
+        public bool Minimized { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/active-tool/set.cs

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using UnityEditor;
+using UnityEditor.Compilation;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>editor.active-tool.set — 设置 Editor 工具(Move/Rotate/Scale 等)。</summary>
+    public class EditorActiveToolSetTool : IUnityCliTool<EditorActiveToolSetTool.Request, EditorActiveToolSetTool.Result>
+    {
+        public sealed class Request { public string Tool { get; set; } }
+        public sealed class Result { public string EditorTool { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.active-tool.set", Summary = "Set the active Unity Editor tool (Move, Rotate, Scale, etc.).", Description = "Set the current Editor session tool through Tools.current. Accepts View, Move, Rotate, Scale, Rect, Transform.", Group = "editor",DestructiveHint = false, SideEffects = new[] { "editor-tool-state" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set Move tool", Input = new Request { Tool = "Move" } } } };
+        // 设置工具后从 Unity 读取当前工具，避免返回请求回显。
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(r.Tool)) throw new UnityCliBridge.BridgeCommandException("E_TOOL_REQUIRED", "editor.active-tool.set requires --tool.", "Pass View, Move, Rotate, Scale, Rect, Transform.");
+            Tool editorTool;
+            switch (r.Tool.ToLowerInvariant()) { case "view": case "pan": editorTool = Tool.View; break; case "move": case "translate": editorTool = Tool.Move; break; case "rotate": case "rotation": editorTool = Tool.Rotate; break; case "scale": editorTool = Tool.Scale; break; case "rect": editorTool = Tool.Rect; break; case "transform": editorTool = Tool.Transform; break; default: throw new UnityCliBridge.BridgeCommandException("E_TOOL_UNKNOWN", "Unknown editor tool: " + r.Tool, "Pass View, Move, Rotate, Scale, Rect, or Transform."); }
+            ctx.CommitEffect();
+            UnityEditor.Tools.current = editorTool;
+            var observedTool = UnityEditor.Tools.current;
+            if (observedTool != editorTool)
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_ACTIVE_TOOL_STATE_MISMATCH", "Unity did not apply the requested active Editor tool.", "Inspect the active Editor tool and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { EditorTool = observedTool.ToString() });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/active-tool.cs

@@ -0,0 +1,100 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli.Tools.Editor
+{
+    /// <summary>
+    /// editor.active-tool 只读 Tool：读取当前 Unity Editor 工具手柄状态。
+    /// </summary>
+    public class EditorActiveToolTool : IUnityCliTool<EditorActiveToolTool.Request, EditorActiveToolTool.Result>
+    {
+        public sealed class Request { }
+
+        public sealed class Vector3Info
+        {
+            public float X { get; set; }
+            public float Y { get; set; }
+            public float Z { get; set; }
+        }
+
+        public sealed class QuaternionInfo
+        {
+            public float X { get; set; }
+            public float Y { get; set; }
+            public float Z { get; set; }
+            public float W { get; set; }
+            public Vector3Info EulerAngles { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string ActiveTool { get; set; }
+            public bool IsCustom { get; set; }
+            public string PivotMode { get; set; }
+            public string PivotRotation { get; set; }
+            public bool HandleAvailable { get; set; }
+            public Vector3Info HandlePosition { get; set; }
+            public QuaternionInfo HandleRotation { get; set; }
+        }
+
+        // ── desc:只声明人工字段,source=built-in 表示进入只读 Tool 表 ──
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.active-tool", Summary = "Read the currently active Unity Editor transform/tool handle plus pivot mode, pivot rotation, handle position, and handle rotation.",
+            Description = "Read the currently active Unity Editor transform/tool handle plus pivot mode, pivot rotation, handle position, and handle rotation. Does not change the active tool.",
+            DestructiveHint = false,
+            Group = "editor",
+            Target = "editor",
+            PlayModeSupport = "supported",
+            Examples = new[] { new ToolExample { Description = "Read the active Editor tool", Input = new Request { } } }
+        };
+
+        /// <summary>
+        /// 读取当前 Editor 工具和手柄位置/旋转；只观察状态，不切换工具或修改 pivot 设置。
+    /// </summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var current = UnityEditor.Tools.current;
+            var handlePosition = UnityEditor.Tools.handlePosition;
+            var handleRotation = UnityEditor.Tools.handleRotation;
+            var handleAvailable = IsFinite(handlePosition) && IsFinite(handleRotation);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ActiveTool = current.ToString(),
+                IsCustom = current != Tool.Move && current != Tool.Rotate && current != Tool.Scale && current != Tool.Rect && current != Tool.None,
+                PivotMode = UnityEditor.Tools.pivotMode.ToString(),
+                PivotRotation = UnityEditor.Tools.pivotRotation.ToString(),
+                HandleAvailable = handleAvailable,
+                HandlePosition = ToVector3Info(handleAvailable ? handlePosition : Vector3.zero),
+                HandleRotation = ToQuaternionInfo(handleAvailable ? handleRotation : Quaternion.identity)
+            });
+        }
+
+        // Unity 在无有效 Scene handle 时可能返回 NaN/Infinity；协议边界只允许有限 JSON number。
+        private static bool IsFinite(Vector3 value) => IsFinite(value.x) && IsFinite(value.y) && IsFinite(value.z);
+
+        private static bool IsFinite(Quaternion value) => IsFinite(value.x) && IsFinite(value.y) && IsFinite(value.z) && IsFinite(value.w);
+
+        private static bool IsFinite(float value) => !float.IsNaN(value) && !float.IsInfinity(value);
+
+        // 将 Unity Vector3 转为稳定 JSON DTO。
+        private static Vector3Info ToVector3Info(Vector3 value) => new Vector3Info
+        {
+            X = value.x,
+            Y = value.y,
+            Z = value.z
+        };
+
+        // 将 Unity Quaternion 转为稳定 JSON DTO，并保留欧拉角便于 AI 直接读取。
+        private static QuaternionInfo ToQuaternionInfo(Quaternion value) => new QuaternionInfo
+        {
+            X = value.x,
+            Y = value.y,
+            Z = value.z,
+            W = value.w,
+            EulerAngles = ToVector3Info(value.eulerAngles)
+        };
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/autotick/set.cs

@@ -0,0 +1,102 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>配置当前Editor session的中央scheduler auto-tick状态。</summary>
+    public sealed class EditorAutoTickSetTool : IUnityCliTool<EditorAutoTickSetRequest, EditorAutoTickSetResult>
+    {
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.autotick.set",
+            Summary = "Configure session-only unfocused Editor ticking through the central scheduler.",
+            Description = "Enables or disables central-scheduler SignalTick pumping for only the current Editor process session. enable defaults to true and intervalMs defaults to 16; intervalMs accepts 0..60000, where 0 requests every scheduler update. State is not persisted and resets on domain reload or process restart. Framework dry-run reports the exact state transition without enabling ticks.",
+            Group = "editor",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "editor-tick-rate" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 120000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Enable approximately 60Hz unfocused ticking.", Input = new EditorAutoTickSetRequest { Enable = true, IntervalMs = 16 } },
+                new ToolExample { Description = "Preview disabling auto-tick.", Input = new EditorAutoTickSetRequest { Enable = false }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>所有参数与SignalTick availability在唯一barrier前冻结；scheduler是唯一状态owner。</summary>
+        public System.Threading.Tasks.ValueTask<EditorAutoTickSetResult> ExecuteAsync(EditorAutoTickSetRequest request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            EditorToolSupport.EnsureEditorNotBusy("editor.autotick.set");
+            ct.ThrowIfCancellationRequested();
+            request = request ?? new EditorAutoTickSetRequest();
+            var enable = request.Enable ?? true;
+            var interval = request.IntervalMs ?? 16L;
+            if (interval < 0 || interval > 60000)
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_AUTOTICK_INTERVAL_INVALID", "intervalMs must be between 0 and 60000.", "Pass a bounded non-negative intervalMs value.");
+
+            var before = UnityCliWaitScheduler.ReadAutoTickState();
+            UnityCliWaitScheduler.PrepareAutoTick(enable);
+            var changed = before.Enabled != enable || (enable && before.IntervalMs != interval);
+            var effects = changed
+                ? new List<EditorAutoTickPlannedEffect> { new EditorAutoTickPlannedEffect { Type = "editor.autotick.set", Enable = enable, IntervalMs = interval } }
+                : new List<EditorAutoTickPlannedEffect>();
+            if (ctx.DryRun || !changed)
+            {
+                var preview = new EditorAutoTickState
+                {
+                    EditorSessionId = before.EditorSessionId,
+                    Enabled = enable,
+                    IntervalMs = enable ? interval : before.IntervalMs,
+                    ForcedTickCount = before.ForcedTickCount,
+                    SignalTickAvailable = before.SignalTickAvailable,
+                    LastError = before.LastError
+                };
+                return new System.Threading.Tasks.ValueTask<EditorAutoTickSetResult>(new EditorAutoTickSetResult { Changed = false, WouldChange = changed, DryRun = ctx.DryRun, Before = before, After = preview, PlannedEffects = effects });
+            }
+
+            ctx.CommitEffect();
+            UnityCliWaitScheduler.ConfigureAutoTick(enable, interval);
+            var after = UnityCliWaitScheduler.ReadAutoTickState();
+            if (after.Enabled != enable || (enable && after.IntervalMs != interval) || !string.Equals(after.EditorSessionId, before.EditorSessionId, System.StringComparison.Ordinal))
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_AUTOTICK_VERIFY_FAILED", "The central scheduler did not retain the requested session auto-tick state.", "Inspect editor.state before deciding whether to retry.");
+            return new System.Threading.Tasks.ValueTask<EditorAutoTickSetResult>(new EditorAutoTickSetResult { Changed = true, WouldChange = true, DryRun = false, Before = before, After = after, PlannedEffects = effects });
+        }
+    }
+
+    public sealed class EditorAutoTickSetRequest
+    {
+        public bool? Enable { get; set; }
+        public long? IntervalMs { get; set; }
+    }
+
+    public sealed class EditorAutoTickState
+    {
+        public string EditorSessionId { get; set; }
+        public bool Enabled { get; set; }
+        public long IntervalMs { get; set; }
+        public long ForcedTickCount { get; set; }
+        public bool SignalTickAvailable { get; set; }
+        public string LastError { get; set; }
+    }
+
+    public sealed class EditorAutoTickPlannedEffect
+    {
+        public string Type { get; set; }
+        public bool Enable { get; set; }
+        public long IntervalMs { get; set; }
+    }
+
+    public sealed class EditorAutoTickSetResult
+    {
+        public bool Changed { get; set; }
+        public bool WouldChange { get; set; }
+        public bool DryRun { get; set; }
+        public EditorAutoTickState Before { get; set; }
+        public EditorAutoTickState After { get; set; }
+        public List<EditorAutoTickPlannedEffect> PlannedEffects { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/console.cs

@@ -0,0 +1,26 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reflection;
+using UnityEditor;
+using UnityEditor.Compilation;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>editor.console — 读取 Console 日志(只读)。</summary>
+    public class EditorConsoleTool : IUnityCliTool<EditorConsoleTool.Request, EditorConsoleTool.Result>
+    {
+        public sealed class Request { public string Type { get; set; } public int? Count { get; set; } }
+        public sealed class Result { public bool Cleared { get; set; } public List<ConsoleEntry> Items { get; set; } public PageInfo PageInfo { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "editor.console", Summary = "Read recent Unity Console log entries.", Description = "Read-only: returns recent Console entries filtered by type. Use console.clear to clear.", Group = "editor",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read console", Input = new Request { Count = 20 } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var count = Math.Max(1, Math.Min(r.Count ?? 50, 500));
+            var items = EditorToolSupport.ReadConsoleEntries(r.Type, null, count);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Cleared = false, Items = items, PageInfo = new PageInfo { PageSize = count, Cursor = 0, Total = items.Count } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/focus.cs

@@ -0,0 +1,80 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>聚焦选定Unity实例的native main window并证明exact foreground HWND。</summary>
+    public sealed class EditorFocusTool : IUnityCliTool<EditorFocusRequest, EditorFocusResult>
+    {
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.focus",
+            Summary = "Focus the selected Unity Editor main window and prove the exact native foreground target.",
+            Description = "Freezes one visible top-level HWND owned by the selected Unity Editor process, restores it when minimized, focuses it, and returns only after the exact HWND is the stable Win32 foreground window. Framework dry-run returns the frozen PID/HWND/title without changing desktop focus. Windows only.",
+            Group = "editor",
+            DestructiveHint = false,
+            SupportsDryRun = true,
+            SideEffects = new[] { "desktop-window-focus" },
+            Permissions = new[] { "desktop-window-control" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 120000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Focus the selected Unity Editor window.", Input = new EditorFocusRequest() },
+                new ToolExample { Description = "Preview the selected native window target.", Input = new EditorFocusRequest(), Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>effect后通过中央wait连续两帧验证frozen HWND，而非只相信SetForegroundWindow返回值。</summary>
+        public async System.Threading.Tasks.ValueTask<EditorFocusResult> ExecuteAsync(EditorFocusRequest request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            EditorToolSupport.EnsureEditorNotBusy("editor.focus");
+            ct.ThrowIfCancellationRequested();
+            var plan = EditorWindowFocusToolSupport.Prepare();
+            var before = EditorWindowFocusToolSupport.Snapshot(plan);
+            var effects = before.Foreground && !before.Minimized
+                ? new List<EditorFocusPlannedEffect>()
+                : new List<EditorFocusPlannedEffect> { new EditorFocusPlannedEffect { Type = "editor.focus", ProcessId = before.ProcessId, WindowHandle = before.WindowHandle } };
+            if (ctx.DryRun)
+                return new EditorFocusResult { Changed = false, WouldChange = effects.Count > 0, DryRun = true, Before = before, After = before, PlannedEffects = effects };
+            if (effects.Count == 0)
+                return new EditorFocusResult { Changed = false, WouldChange = false, DryRun = false, Before = before, After = before, PlannedEffects = effects };
+
+            ctx.CommitEffect();
+            EditorWindowFocusToolSupport.Apply(plan);
+            var proven = await ctx.Wait.UntilStable(
+                () => EditorWindowFocusToolSupport.IsForeground(plan),
+                TimeSpan.FromSeconds(3),
+                minimumFrames: 2,
+                minimumDuration: TimeSpan.FromMilliseconds(100),
+                ct: ct);
+            var after = EditorWindowFocusToolSupport.Snapshot(plan);
+            if (!proven || !after.Foreground || after.ProcessId != before.ProcessId || !string.Equals(after.WindowHandle, before.WindowHandle, StringComparison.Ordinal))
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_FOCUS_UNPROVEN", "The frozen Unity Editor HWND did not become the stable native foreground window.", "Inspect desktop focus restrictions and the selected editor.state before retrying.");
+            return new EditorFocusResult { Changed = true, WouldChange = true, DryRun = false, Before = before, After = after, PlannedEffects = effects };
+        }
+    }
+
+    public sealed class EditorFocusRequest { }
+
+    public sealed class EditorFocusPlannedEffect
+    {
+        public string Type { get; set; }
+        public long ProcessId { get; set; }
+        public string WindowHandle { get; set; }
+    }
+
+    public sealed class EditorFocusResult
+    {
+        public bool Changed { get; set; }
+        public bool WouldChange { get; set; }
+        public bool DryRun { get; set; }
+        public EditorFocusWindowState Before { get; set; }
+        public EditorFocusWindowState After { get; set; }
+        public List<EditorFocusPlannedEffect> PlannedEffects { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/menu-items.cs

@@ -0,0 +1,50 @@
+#if UNITY_EDITOR
+namespace UnityCli.Tools.Editor
+{
+    /// <summary>
+    /// editor.menu-items 只读 Tool：说明 Unity Editor menu item 枚举限制。
+    /// </summary>
+    public class EditorMenuItemsTool : IUnityCliTool<EditorMenuItemsTool.Request, EditorMenuItemsTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Search { get; set; }
+        }
+
+        public sealed class MenuItemInfo { }
+
+        public sealed class Result
+        {
+            public MenuItemInfo[] Items { get; set; }
+            public int Count { get; set; }
+            public string Diagnostics { get; set; }
+        }
+
+        // ── desc:只声明人工字段,source=built-in 表示进入只读 Tool 表 ──
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "editor.menu-items",
+            Summary = "Report Editor menu enumeration availability without executing menus.",
+            Description = "Attempt to enumerate Unity Editor menu items as read-only discovery. Unity has no stable public API for full menu enumeration, so this context may return an empty items array with diagnostics; executing a menu path remains the destructive Tool editor.menu.",
+            DestructiveHint = false,
+            Group = "editor",
+            Target = "editor",
+            PlayModeSupport = "supported",
+            Examples = new[] { new ToolExample { Description = "Search menu item metadata", Input = new Request { Search = "Save" } } }
+        };
+
+        /// <summary>
+        /// 返回菜单枚举限制诊断；只读，不执行任何 menu path。
+    /// </summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Items = new MenuItemInfo[0],
+                Count = 0,
+                Diagnostics = "Unity Editor menu items cannot be enumerated through a public API. Reflection on internal MenuItem cache is version-dependent and not guaranteed. This context returns an empty list); menu execution is a Tool (editor.menu), not a Context."
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/editor/menu.cs

@@ -0,0 +1,53 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>editor.menu — 执行具有确定 terminal predicate 的窄菜单项。</summary>
+    public class EditorMenuTool : IUnityCliTool<EditorMenuTool.Request, EditorMenuTool.Response>
+    {
+        public sealed class Request { public string Path { get; set; } }
+        public sealed class Response { public MenuResult Result { get; set; } public EditorStateInfo State { get; set; } public List<EditorPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new() { Name = "editor.menu", Summary = "Execute the terminally verifiable File/Save Unity Editor menu command.", Description = "Execute only File/Save, which succeeds after the active saved scene is no longer dirty. Assets/Refresh and other menu paths are rejected because they have no attributable business completion predicate.", Group = "editor",DestructiveHint = true, SideEffects = new[] { "scene-save" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Save the active scene", Input = new Request { Path = "File/Save" } } } };
+
+        /// <summary>首次调用执行 allowlisted menu；reload redelivery 只验证对应终态。</summary>
+        public async System.Threading.Tasks.ValueTask<Response> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrWhiteSpace(request.Path))
+                throw new UnityCliBridge.BridgeCommandException("E_SCHEMA_INVALID", "Editor menu path is required.", "Pass File/Save.");
+            var saveScene = string.Equals(request.Path, "File/Save", StringComparison.Ordinal);
+            if (!saveScene)
+                throw new UnityCliBridge.BridgeCommandException("E_MENU_COMPLETION_UNSUPPORTED", "The menu path has no registered terminal completion predicate: " + request.Path, "Use a dedicated Tool, or use File/Save.");
+
+            var scene = SceneManager.GetActiveScene();
+            if (saveScene && string.IsNullOrEmpty(scene.path))
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_PATH_REQUIRED", "File/Save cannot prove completion for an untitled scene.", "Use scene.save with an explicit Assets/*.unity path.");
+            var startedAt = DateTime.UtcNow;
+            EditorToolSupport.EnsureEditorNotBusy("editor.menu");
+            ctx.CommitEffect();
+            if (!EditorApplication.ExecuteMenuItem(request.Path))
+                throw new UnityCliBridge.BridgeCommandException("E_MENU_NOT_FOUND", "Unity menu item was not found or could not be executed.", "Use File/Save in a compatible Editor state.");
+            var stable = await ctx.Wait.UntilStable(
+                () =>
+                {
+                    var activeScene = SceneManager.GetActiveScene();
+                    return !string.IsNullOrEmpty(activeScene.path) && !activeScene.isDirty;
+                }, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct: ct);
+            scene = SceneManager.GetActiveScene();
+            if (!stable || string.IsNullOrEmpty(scene.path) || scene.isDirty)
+                throw new UnityCliBridge.BridgeCommandException("E_MENU_TERMINAL_NOT_OBSERVED", "The allowlisted menu command did not reach its terminal predicate.", "Inspect editor.state and scene state before submitting a new request.");
+            var elapsedMs = (long)Math.Round((DateTime.UtcNow - startedAt).TotalMilliseconds);
+            return new Response
+            {
+                Result = new MenuResult { Path = request.Path, Executed = true, ElapsedMs = elapsedMs },
+                State = EditorToolSupport.BuildEditorState(),
+                PlannedEffects = new List<EditorPlannedEffect> { new EditorPlannedEffect { Type = "editor.menu", Path = request.Path } }
+            };
+        }
+    }
+}
+#endif