@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,68 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.load — 按 Assets/*.unity 路径或唯一场景资产名加载场景(OpenSceneMode.Single)。
+    /// </summary>
+    public class SceneLoadTool : IUnityCliTool<SceneLoadTool.Request, SceneLoadTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Name { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SceneInfo Scene { get; set; }
+            public string RequestedPath { get; set; }
+            public List<ScenePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.load",
+            Summary = "Load or reload one scene; EditMode reload discards unsaved in-memory scene state.",
+            Description = "Load a scene by exact Assets/*.unity path or unique scene asset filename. A name is matched case-insensitively without the .unity suffix and fails when missing or ambiguous. In EditMode this uses OpenSceneMode.Single, replacing the currently open scene state without saving scene assets. When a task started from a clean scene and must discard all temporary in-memory changes, call this Tool once with the exact active scene path after finishing verification and deleting temporary objects; this avoids traversing unrelated shared Undo history. Only call it when discarding every current unsaved scene change is intended. Use scene.list-opened to confirm loaded scenes.",
+            Group = "scene",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Load a scene by path", Input = new Request { Path = "Assets/Scenes/Main.unity" } },
+                new ToolExample { Description = "Load a uniquely named scene asset", Input = new Request { Name = "Main" } }
+            }
+        };
+
+        /// <summary>解析 path/name 后以 Single 模式打开；name 必须在项目中唯一。</summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            SceneToolSupport.EnsureEditorNotBusy("scene.load");
+            request = request ?? new Request();
+            var path = SceneToolSupport.ResolveExistingScenePath(request.Path, request.Name);
+            ctx.CommitEffect();
+            var scene = EditorSceneManager.OpenScene(path, OpenSceneMode.Single);
+            var observedScene = SceneManager.GetActiveScene();
+            if (!observedScene.isLoaded || observedScene.path != path || observedScene.handle != scene.handle)
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_LOAD_STATE_MISMATCH", "Active scene did not match the requested scene after load.", "Inspect open scenes and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Scene = SceneToolSupport.BuildSceneInfo(observedScene),
+                RequestedPath = path,
+                PlannedEffects = new List<ScenePlannedEffect>
+                {
+                    new ScenePlannedEffect { Type = "scene.load", Path = SceneToolSupport.NormalizeAssetPath(scene.path) ?? path }
+                }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/move-object.cs

@@ -0,0 +1,122 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.move-object — 将 GameObject 移动到另一个已加载场景。
+    /// </summary>
+    public class SceneMoveObjectTool : IUnityCliTool<SceneMoveObjectTool.Request, SceneMoveObjectTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Path { get; set; }
+            public int? InstanceId { get; set; }
+            [UnityCliRequired]
+            public string Scene { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string FromScene { get; set; }
+            public string ToScene { get; set; }
+            public bool? Moved { get; set; }
+            public string Reason { get; set; }
+            public bool? DryRun { get; set; }
+            public List<ScenePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.move-object",
+            Summary = "Move a GameObject from its current scene into another already-loaded scene.",
+            Description = "Move a GameObject (resolved by target path or instanceId) into another already-loaded destination scene (--scene path). Useful for multi-scene editing. Requires the destination scene to be loaded (scene.load); returns moved=false if the object is already in the destination.",
+            Group = "scene",
+            DestructiveHint = false,
+            SupportsDryRun = true,
+            SideEffects = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Move an object to another scene", Input = new Request { Target = "Player", Scene = "Assets/Scenes/Gameplay.unity" } }
+            }
+        };
+
+        // 移动对象后读取场景标识，确保返回的是已生效的场景归属。
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            SceneToolSupport.EnsureEditorNotBusy("scene.move-object");
+            var target = request.Target ?? request.Path;
+            var instanceId = request.InstanceId;
+            var destScenePath = request.Scene;
+            if (string.IsNullOrEmpty(destScenePath))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_DESTINATION_REQUIRED", "scene.move-object requires --scene (destination scene path).", "Run tools run scene.list-opened to list loaded scenes.");
+            }
+            GameObject go = null;
+            if (instanceId.HasValue && instanceId.Value != 0)
+            {
+                go = EditorUtility.InstanceIDToObject(instanceId.Value) as GameObject;
+            }
+            if (go == null && !string.IsNullOrEmpty(target))
+            {
+                go = SceneToolSupport.ResolveGameObjectByPath(target);
+            }
+            if (go == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "GameObject not found: " + (target ?? instanceId?.ToString()), "Pass a valid target path or instanceId.");
+            }
+            var destScene = SceneManager.GetSceneByPath(destScenePath);
+            if (!destScene.IsValid() || !destScene.isLoaded)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_NOT_OPEN", "Destination scene is not loaded: " + destScenePath, "Load the destination scene first via scene.load, or run tools run scene.list-opened.");
+            }
+            if (go.scene == destScene)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    ToScene = destScenePath,
+                    Moved = false,
+                    Reason = "already in destination scene"
+                });
+            }
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    FromScene = go.scene.path,
+                    ToScene = destScenePath,
+                    DryRun = true,
+                    PlannedEffects = new List<ScenePlannedEffect>
+                    {
+                        new ScenePlannedEffect { Type = "scene.move-object", Target = go.name }
+                    }
+                });
+            }
+            var fromScene = go.scene.path;
+            var gameObjectId = go.GetInstanceID();
+            ctx.CommitEffect();
+            SceneManager.MoveGameObjectToScene(go, destScene);
+            // Resolve the same object afresh; the call itself is not completion proof.
+            var observed = EditorUtility.InstanceIDToObject(gameObjectId) as GameObject;
+            var observedScenePath = observed == null ? null : observed.scene.path;
+            var observedSceneHandle = observed == null ? 0 : observed.scene.handle;
+            if (observedScenePath != destScene.path || observedSceneHandle != destScene.handle)
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_MOVE_STATE_MISMATCH", "GameObject did not move to the requested destination scene.", "Inspect the object scene and destination scene load state before retrying.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                FromScene = fromScene,
+                ToScene = observedScenePath,
+                Moved = true
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/save.cs

@@ -0,0 +1,231 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>保存 active scene，或显式保存全部 open dirty scenes 并逐项证明 clean terminal。</summary>
+    public class SceneSaveTool : IUnityCliTool<SceneSaveTool.Request, SceneSaveTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public bool All { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long SavedCount { get; set; }
+            public SceneInfo Scene { get; set; }
+            public List<SceneSaveReadback> Scenes { get; set; }
+            public string RequestedPath { get; set; }
+            public bool? DryRun { get; set; }
+            public List<ScenePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public sealed class SceneSaveReadback
+        {
+            public SceneInfo Scene { get; set; }
+            public string Guid { get; set; }
+            public bool WasDirty { get; set; }
+            public bool Saved { get; set; }
+        }
+
+        private sealed class SceneSavePlan
+        {
+            public int Handle;
+            public string Name;
+            public string Path;
+            public bool WasDirty;
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.save",
+            Summary = "Save the active scene, or explicitly save every open dirty scene with per-scene clean readback.",
+            Description = "Default mode saves the active scene and requires path for an untitled scene. all=true is mutually exclusive with path/name, saves only loaded dirty scenes, fails before any write if one is untitled, and returns the complete frozen dirty set after path/GUID/clean proof. Dry-run performs no scene or asset write.",
+            Group = "scene",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-write", "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Save the active scene.", Input = new Request() },
+                new ToolExample { Description = "Preview saving every open dirty scene.", Input = new Request { All = true }, Execution = new ToolExampleExecution { DryRun = true } },
+                new ToolExample { Description = "Preview saving an untitled active scene to a path.", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>按显式 mode 分派；all mode 在 effect 前冻结完整 dirty set，effect 后逐 handle fresh 证明。</summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default(System.Threading.CancellationToken))
+        {
+            SceneToolSupport.EnsureEditorNotBusy("scene.save");
+            request = request ?? new Request();
+            ct.ThrowIfCancellationRequested();
+            if (request.All)
+                return new System.Threading.Tasks.ValueTask<Result>(SaveAll(request, ctx, ct));
+            return new System.Threading.Tasks.ValueTask<Result>(SaveActive(request, ctx, ct));
+        }
+
+        /// <summary>保留 active scene 单场景契约，并补充统一 scenes collection 与 fresh GUID proof。</summary>
+        private static Result SaveActive(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct)
+        {
+            var scene = SceneManager.GetActiveScene();
+            if (!scene.IsValid() || !scene.isLoaded)
+                throw Error("E_SCENE_NOT_LOADED", "scene.save requires one valid loaded active scene.", null);
+            var path = SceneToolSupport.ResolveScenePath(request.Path ?? request.Name, false);
+            if (string.IsNullOrEmpty(path)) path = SceneToolSupport.NormalizeAssetPath(scene.path);
+            if (string.IsNullOrEmpty(path))
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_PATH_REQUIRED", "Scene save requires path when the active scene has not been saved yet.", "Pass tools run scene.save --input '{\"path\":\"Assets/Scenes/Main.unity\"}'.");
+            var plan = new SceneSavePlan { Handle = scene.handle, Name = scene.name, Path = path, WasDirty = scene.isDirty };
+            var effects = Effects(new List<SceneSavePlan> { plan }, ctx.DryRun);
+            if (ctx.DryRun)
+            {
+                var preview = Readback(scene, plan, false, false);
+                return new Result { SavedCount = 0, Scene = preview.Scene, Scenes = new List<SceneSaveReadback> { preview }, RequestedPath = path, DryRun = true, PlannedEffects = effects };
+            }
+
+            ct.ThrowIfCancellationRequested();
+            CommitEffect(ctx);
+            SceneToolSupport.CreateAssetDirectory(path);
+            if (!EditorSceneManager.SaveScene(scene, path))
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_SAVE_FAILED", "Unity did not save the active scene.", "Inspect the active scene and project write permissions before retrying.");
+            var observed = FindSceneByHandle(plan.Handle);
+            var readback = Prove(observed, plan);
+            return new Result
+            {
+                SavedCount = 1,
+                Scene = readback.Scene,
+                Scenes = new List<SceneSaveReadback> { readback },
+                RequestedPath = path,
+                DryRun = false,
+                PlannedEffects = effects
+            };
+        }
+
+        /// <summary>只冻结 loaded dirty scenes；untitled 或 mode 冲突在调用 SaveOpenScenes 前整体失败。</summary>
+        private static Result SaveAll(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct)
+        {
+            if (request.Path != null || request.Name != null)
+                throw Error("E_SCENE_SAVE_MODE_CONFLICT", "scene.save all=true cannot be combined with path or name.", null);
+            var plans = CaptureDirtyScenes();
+            var effects = Effects(plans, ctx.DryRun);
+            var preview = new List<SceneSaveReadback>(plans.Count);
+            foreach (var plan in plans)
+            {
+                var scene = FindSceneByHandle(plan.Handle);
+                preview.Add(Readback(scene, plan, false, false));
+            }
+            if (ctx.DryRun)
+                return new Result { SavedCount = 0, Scenes = preview, DryRun = true, PlannedEffects = effects };
+            if (plans.Count == 0)
+                return new Result { SavedCount = 0, Scenes = preview, DryRun = false, PlannedEffects = effects };
+
+            ct.ThrowIfCancellationRequested();
+            CommitEffect(ctx);
+            if (!EditorSceneManager.SaveOpenScenes())
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_SAVE_ALL_FAILED", "Unity did not save every frozen dirty scene.", "Inspect scene paths and project write permissions before deciding whether to retry.");
+
+            var observed = new List<SceneSaveReadback>(plans.Count);
+            foreach (var plan in plans)
+                observed.Add(Prove(FindSceneByHandle(plan.Handle), plan));
+            EnsureAllLoadedScenesClean();
+            return new Result { SavedCount = observed.Count, Scenes = observed, DryRun = false, PlannedEffects = effects };
+        }
+
+        private static List<SceneSavePlan> CaptureDirtyScenes()
+        {
+            var result = new List<SceneSavePlan>();
+            var paths = new HashSet<string>(StringComparer.Ordinal);
+            for (var index = 0; index < SceneManager.sceneCount; index++)
+            {
+                var scene = SceneManager.GetSceneAt(index);
+                if (!scene.IsValid() || !scene.isLoaded || !scene.isDirty) continue;
+                var path = SceneToolSupport.NormalizeAssetPath(scene.path);
+                if (string.IsNullOrEmpty(path))
+                    throw Error("E_SCENE_SAVE_ALL_UNTITLED", "Every dirty scene must have an asset path before scene.save all=true can run.", scene.name);
+                if (!paths.Add(path))
+                    throw Error("E_SCENE_SAVE_ALL_IDENTITY_CONFLICT", "Two dirty open scenes resolve to the same asset path.", path);
+                result.Add(new SceneSavePlan { Handle = scene.handle, Name = scene.name, Path = path, WasDirty = true });
+            }
+            return result;
+        }
+
+        /// <summary>fresh scene handle/path/dirty 与 AssetDatabase GUID round-trip 构成单场景 terminal proof。</summary>
+        private static SceneSaveReadback Prove(Scene scene, SceneSavePlan plan)
+        {
+            var path = scene.IsValid() ? SceneToolSupport.NormalizeAssetPath(scene.path) : null;
+            var guid = string.IsNullOrEmpty(path) ? null : AssetDatabase.AssetPathToGUID(path);
+            if (!scene.IsValid() || !scene.isLoaded || scene.handle != plan.Handle
+                || !string.Equals(path, plan.Path, StringComparison.Ordinal) || scene.isDirty
+                || string.IsNullOrEmpty(guid)
+                || !string.Equals(AssetDatabase.GUIDToAssetPath(guid), plan.Path, StringComparison.Ordinal))
+                throw Error("E_SCENE_SAVE_STATE_MISMATCH", "A saved scene did not retain its frozen identity or clean asset state.", plan.Path);
+            return Readback(scene, plan, true, true);
+        }
+
+        private static SceneSaveReadback Readback(Scene scene, SceneSavePlan plan, bool saved, bool includeGuid)
+        {
+            return new SceneSaveReadback
+            {
+                Scene = SceneToolSupport.BuildSceneInfo(scene),
+                Guid = includeGuid ? AssetDatabase.AssetPathToGUID(plan.Path) : null,
+                WasDirty = plan.WasDirty,
+                Saved = saved
+            };
+        }
+
+        // Unity 2022 没有公开 GetSceneByHandle；按当前 loaded scene inventory 查找冻结 handle。
+        private static Scene FindSceneByHandle(int handle)
+        {
+            for (var index = 0; index < SceneManager.sceneCount; index++)
+            {
+                var scene = SceneManager.GetSceneAt(index);
+                if (scene.IsValid() && scene.handle == handle) return scene;
+            }
+            return default(Scene);
+        }
+
+        private static void EnsureAllLoadedScenesClean()
+        {
+            for (var index = 0; index < SceneManager.sceneCount; index++)
+            {
+                var scene = SceneManager.GetSceneAt(index);
+                if (scene.IsValid() && scene.isLoaded && scene.isDirty)
+                    throw Error("E_SCENE_SAVE_STATE_MISMATCH", "A loaded scene became dirty before save-all terminal readback completed.", scene.name);
+            }
+        }
+
+        private static List<ScenePlannedEffect> Effects(List<SceneSavePlan> plans, bool dryRun)
+        {
+            var result = new List<ScenePlannedEffect>(plans.Count);
+            foreach (var plan in plans)
+                result.Add(new ScenePlannedEffect { Type = "scene.save", Path = plan.Path, SideEffects = dryRun ? "none" : null });
+            return result;
+        }
+
+        // 两个互斥保存 mode 复用同一 barrier owner；每次调用只会进入其中一个分支。
+        private static void CommitEffect(UnityCliProjectToolContext ctx)
+        {
+            ctx.CommitEffect();
+        }
+
+        private static UnityCliBridge.BridgeCommandException Error(string code, string message, string scene)
+        {
+            return new UnityCliBridge.BridgeCommandException(
+                code,
+                message,
+                new Dictionary<string, object> { { "scene", scene } },
+                new[] { "Run tools run scene.list-opened and save untitled scenes individually with scene.save path before retrying." });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/set-active.cs

@@ -0,0 +1,76 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.set-active — 在已加载场景中设置激活场景。目标场景必须已加载。
+    /// </summary>
+    public class SceneSetActiveTool : IUnityCliTool<SceneSetActiveTool.Request, SceneSetActiveTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Path { get; set; }
+            public string Name { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SceneInfo Scene { get; set; }
+            public string RequestedPath { get; set; }
+            public List<ScenePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.set-active",
+            Summary = "Set the active scene among currently loaded scenes.",
+            Description = "Set the active scene among currently loaded scenes. The target scene must already be loaded (use scene.load first). Affects which scene new GameObjects are created in.",
+            Group = "scene",
+            DestructiveHint = false,
+            SideEffects = new[] { "editor-session" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set the active scene", Input = new Request { Path = "Assets/Scenes/Main.unity" } }
+            }
+        };
+
+        // 切换后读取 Unity 当前活动场景，确认写入已生效。
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            SceneToolSupport.EnsureEditorNotBusy("scene.set-active");
+            var path = SceneToolSupport.ResolveScenePath(request.Path ?? request.Name, true);
+            for (var i = 0; i < SceneManager.sceneCount; i++)
+            {
+                var scene = SceneManager.GetSceneAt(i);
+                if (string.Equals(SceneToolSupport.NormalizeAssetPath(scene.path), path, System.StringComparison.OrdinalIgnoreCase))
+                {
+                    ctx.CommitEffect();
+                    EditorSceneManager.SetActiveScene(scene);
+                    // 写后读取激活场景，确认场景切换已由 Unity 接受。
+                    var observedScene = SceneManager.GetActiveScene();
+                    if (observedScene.path != scene.path || observedScene.handle != scene.handle)
+                        throw new UnityCliBridge.BridgeCommandException("E_SCENE_ACTIVE_STATE_MISMATCH", "Unity did not set the requested active scene.", "Inspect the active scene and retry.");
+                    return new System.Threading.Tasks.ValueTask<Result>(new Result
+                    {
+                        Scene = SceneToolSupport.BuildSceneInfo(observedScene),
+                        RequestedPath = path,
+                        PlannedEffects = new List<ScenePlannedEffect>
+                        {
+                            new ScenePlannedEffect { Type = "scene.set-active", Path = SceneToolSupport.NormalizeAssetPath(scene.path) ?? path }
+                        }
+                    });
+                }
+            }
+            throw new UnityCliBridge.BridgeCommandException("E_SCENE_NOT_OPEN", "Scene is not currently open: " + path, "Run tools run scene.list-opened, then scene.load if needed.");
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scene/unload.cs

@@ -0,0 +1,109 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor.SceneManagement;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scene.unload — 卸载一个 additive 加载场景。不能卸载唯一打开的场景。支持 dryRun。
+    /// </summary>
+    public class SceneUnloadTool : IUnityCliTool<SceneUnloadTool.Request, SceneUnloadTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public bool? RemoveAll { get; set; }
+            public bool? Save { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public SceneInfo Scene { get; set; }
+            public string RequestedPath { get; set; }
+            public bool? DryRun { get; set; }
+            public string SceneName { get; set; }
+            public bool? IsDirty { get; set; }
+            public bool? WillSave { get; set; }
+            public List<ScenePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scene.unload",
+            Summary = "Unload an additively-loaded scene from the Editor.",
+            Description = "Unload an additively-loaded scene from the Editor. Cannot unload the only open scene. Destructive: removes the scene from the Editor session. Supports --dry-run.",
+            Group = "scene",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "scene-modify", "asset-write-when-save-true" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Preview unloading a scene", Input = new Request { Path = "Assets/Scenes/Level2.unity" }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            SceneToolSupport.EnsureEditorNotBusy("scene.unload");
+            var path = SceneToolSupport.ResolveScenePath(request.Path ?? request.Name, true);
+            for (var i = 0; i < SceneManager.sceneCount; i++)
+            {
+                var scene = SceneManager.GetSceneAt(i);
+                if (string.Equals(SceneToolSupport.NormalizeAssetPath(scene.path), path, System.StringComparison.OrdinalIgnoreCase))
+                {
+                    if (scene == SceneManager.GetActiveScene() && SceneManager.sceneCount == 1)
+                    {
+                        throw new UnityCliBridge.BridgeCommandException("E_SCENE_UNLOAD_LAST", "Cannot unload the only open scene.", "Open another scene first.");
+                    }
+                    var removeAll = request.RemoveAll == true;
+                    var opts = removeAll ? UnloadSceneOptions.UnloadAllEmbeddedSceneObjects : UnloadSceneOptions.None;
+                    var saveDirty = request.Save == true;
+                    if (ctx.DryRun)
+                    {
+                        return new System.Threading.Tasks.ValueTask<Result>(new Result
+                        {
+                            Scene = SceneToolSupport.BuildSceneInfo(SceneManager.GetActiveScene()),
+                            RequestedPath = path,
+                            DryRun = true,
+                            SceneName = scene.name,
+                            IsDirty = scene.isDirty,
+                            WillSave = saveDirty && scene.isDirty,
+                            PlannedEffects = new List<ScenePlannedEffect>
+                            {
+                                new ScenePlannedEffect { Type = "scene.unload", Path = path }
+                            }
+                        });
+                    }
+                    // dirty 保存策略:save=true 且场景有未保存改动时先保存再卸载,避免丢失改动。
+                    ctx.CommitEffect();
+                    if (saveDirty && scene.isDirty && !string.IsNullOrEmpty(scene.path))
+                    {
+                        EditorSceneManager.SaveScene(scene);
+                    }
+                    EditorSceneManager.CloseScene(scene, opts == UnloadSceneOptions.UnloadAllEmbeddedSceneObjects);
+                    var observedScene = SceneManager.GetSceneByPath(path);
+                    if (observedScene.isLoaded)
+                        throw new UnityCliBridge.BridgeCommandException("E_SCENE_UNLOAD_STATE_MISMATCH", "Scene remained loaded after unload.", "Inspect open scenes and retry after the Editor is idle.");
+                    return new System.Threading.Tasks.ValueTask<Result>(new Result
+                    {
+                        Scene = SceneToolSupport.BuildSceneInfo(SceneManager.GetActiveScene()),
+                        RequestedPath = path,
+                        PlannedEffects = new List<ScenePlannedEffect>
+                        {
+                            new ScenePlannedEffect { Type = "scene.unload", Path = path }
+                        }
+                    });
+                }
+            }
+            throw new UnityCliBridge.BridgeCommandException("E_SCENE_NOT_OPEN", "Scene is not currently open: " + path, "Run tools run scene.list-opened to list open scenes.");
+        }
+    }
+}
+#endif