@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,157 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// prefab.hierarchy — 读取 Prefab 子级/组件摘要,支持 parent/query/componentType 过滤与分页。
+    /// </summary>
+    public class PrefabHierarchyTool : IUnityCliTool<PrefabHierarchyTool.Request, PrefabHierarchyTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Parent { get; set; }
+            public string Query { get; set; }
+            public string NameFilter { get; set; }
+            public string Filter { get; set; }
+            public string ComponentType { get; set; }
+            public bool? IncludeSummaryDetails { get; set; }
+            public int? PageSize { get; set; }
+            public int? Cursor { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public PrefabInfo Prefab { get; set; }
+            public List<PrefabHierarchyItem> Items { get; set; }
+            public List<PrefabHierarchyItem> Children { get; set; }
+            public AssetPageInfo PageInfo { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.hierarchy",
+            Summary = "List prefab child/component summaries with parent, query and componentType filters, paged.",
+            Description = "List prefab child/component summaries. With no parent, returns the root; with parent, returns that parent's children. Filter by query/nameFilter on name or path, and componentType on a component type name. Results are paged via cursor/pageSize.",
+            Group = "prefab",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List root hierarchy", Input = new Request { Path = "Assets/Prefabs/Player.prefab", PageSize = 25 } },
+                new ToolExample { Description = "List children of a parent", Input = new Request { Path = "Assets/Prefabs/Player.prefab", Parent = "Rig", PageSize = 25 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = PrefabToolSupport.RequirePrefabPath(request.Path);
+            PrefabToolSupport.LoadPrefabAsset(path);
+            var pageSize = Math.Max(1, Math.Min(request.PageSize ?? 25, 500));
+            var cursor = Math.Max(0, request.Cursor ?? 0);
+            var parent = request.Parent;
+            var query = request.Query ?? request.NameFilter ?? request.Filter;
+            var componentType = request.ComponentType;
+            var includeSummaryDetails = request.IncludeSummaryDetails ?? false;
+            var root = PrefabUtility.LoadPrefabContents(path);
+            try
+            {
+                var parentTransform = ResolveParent(root.transform, parent);
+                var candidates = new List<GameObject>();
+                if (string.IsNullOrEmpty(parent))
+                {
+                    candidates.Add(root);
+                }
+                else
+                {
+                    foreach (Transform child in parentTransform)
+                    {
+                        candidates.Add(child.gameObject);
+                    }
+                }
+                var matches = new List<GameObject>();
+                foreach (var go in candidates)
+                {
+                    if (TextMatches(query, go.name, GameObjectToolSupport.HierarchyPath(go))
+                        && ComponentMatches(go, componentType))
+                    {
+                        matches.Add(go);
+                    }
+                }
+                matches.Sort((a, b) => StringComparer.Ordinal.Compare(GameObjectToolSupport.HierarchyPath(a), GameObjectToolSupport.HierarchyPath(b)));
+                var page = new List<PrefabHierarchyItem>();
+                for (var i = cursor; i < matches.Count && page.Count < pageSize; i++)
+                {
+                    page.Add(PrefabToolSupport.BuildHierarchyItem(matches[i]));
+                }
+                long? nextCursor = cursor + page.Count < matches.Count ? (long?)(cursor + page.Count) : null;
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Prefab = PrefabToolSupport.BuildPrefabInfo(path, root, root, includeSummaryDetails),
+                    Items = page,
+                    Children = page,
+                    PageInfo = new AssetPageInfo
+                    {
+                        PageSize = pageSize,
+                        Cursor = cursor,
+                        NextCursor = nextCursor,
+                        Total = matches.Count,
+                        Truncated = nextCursor != null
+                    }
+                });
+            }
+            finally
+            {
+                PrefabUtility.UnloadPrefabContents(root);
+            }
+        }
+
+        // 解析 parent:空返回 root;名称/路径匹配 root 或其子孙
+        private static Transform ResolveParent(Transform root, string parent)
+        {
+            if (string.IsNullOrEmpty(parent)) return root;
+            if (string.Equals(parent, root.name, StringComparison.Ordinal)
+                || string.Equals(parent, GameObjectToolSupport.HierarchyPath(root.gameObject), StringComparison.Ordinal))
+            {
+                return root;
+            }
+            foreach (var transform in root.GetComponentsInChildren<Transform>(true))
+            {
+                if (transform == null) continue;
+                if (string.Equals(transform.name, parent, StringComparison.Ordinal)
+                    || string.Equals(GameObjectToolSupport.HierarchyPath(transform.gameObject), parent, StringComparison.Ordinal))
+                {
+                    return transform;
+                }
+            }
+            throw new UnityCliBridge.BridgeCommandException("E_PREFAB_HIERARCHY_PARENT_NOT_FOUND", "Prefab hierarchy parent not found: " + parent, "Run prefab.hierarchy without parent, then pass a returned path as parent.");
+        }
+
+        private static bool TextMatches(string query, string name, string path)
+        {
+            if (string.IsNullOrEmpty(query)) return true;
+            return (name != null && name.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0)
+                || (path != null && path.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0);
+        }
+
+        private static bool ComponentMatches(GameObject go, string componentType)
+        {
+            if (string.IsNullOrEmpty(componentType)) return true;
+            foreach (var component in go.GetComponents<Component>())
+            {
+                var name = component == null ? "MissingScript" : component.GetType().Name;
+                if (string.Equals(name, componentType, StringComparison.OrdinalIgnoreCase)) return true;
+            }
+            return false;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/info.cs

@@ -0,0 +1,44 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>
+    /// prefab.info — 读取 Prefab 资产摘要(变体来源/依赖/嵌套 Prefab)。
+    /// </summary>
+    public class PrefabInfoTool : IUnityCliTool<PrefabInfoTool.Request, PrefabInfoTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public PrefabInfo Prefab { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.info",
+            Summary = "Return path, guid, root name, asset type, variant source, dependency and nested-prefab summary for an Assets/*.prefab.",
+            Description = "Return path, guid, root name, asset type, variant source, dependency and nested-prefab summary for an Assets/*.prefab. Read-only; use prefab.hierarchy for the child/component tree and prefab.modify to edit contents.",
+            Group = "prefab",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Inspect a prefab", Input = new Request { Path = "Assets/Prefabs/Player.prefab" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = PrefabToolSupport.RequirePrefabPath(request.Path);
+            var prefab = PrefabToolSupport.LoadPrefabAsset(path);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Prefab = PrefabToolSupport.BuildPrefabInfo(path, prefab, null, true) });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/instantiate.cs

@@ -0,0 +1,106 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// prefab.instantiate — 在场景中实例化 Prefab。支持 dryRun 预览。
+    /// </summary>
+    public class PrefabInstantiateTool : IUnityCliTool<PrefabInstantiateTool.Request, PrefabInstantiateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Parent { get; set; }
+            public string Name { get; set; }
+            public double? X { get; set; }
+            public double? Y { get; set; }
+            public double? Z { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool? DryRun { get; set; }
+            public GameObjectRef Instance { get; set; }
+            public string SourcePath { get; set; }
+            public List<PrefabPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.instantiate",
+            Summary = "Instantiate an Assets/*.prefab into the active scene with optional parent, position and name; supports --dry-run.",
+            Description = "Instantiate an Assets/*.prefab into the active scene. Optionally parent under a scene GameObject (name/path/instance id), set world position, and rename the instance. Supports --dry-run to preview the planned instantiation.",
+            Group = "prefab",
+            DestructiveHint = false,
+            SupportsDryRun = true,
+            SideEffects = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Instantiate a prefab", Input = new Request { Path = "Assets/Prefabs/Enemy.prefab", X = 0, Y = 0, Z = 0 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            PrefabToolSupport.EnsureEditorNotBusy("prefab.instantiate");
+            var path = PrefabToolSupport.RequirePrefabPath(request.Path);
+            GameObjectToolSupport.ValidateTransformMutationValues(request.X, request.Y, request.Z);
+            var sourceGuid = AssetDatabase.AssetPathToGUID(path);
+            var prefab = PrefabToolSupport.LoadPrefabAsset(path);
+            if (string.IsNullOrEmpty(sourceGuid) || AssetDatabase.GUIDToAssetPath(sourceGuid) != path)
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_NOT_FOUND", "Prefab source GUID could not be resolved: " + path, "Pass an existing canonical Assets/*.prefab path.");
+            var parentName = request.Parent;
+            Transform parent = null;
+            if (!string.IsNullOrEmpty(parentName))
+            {
+                var parentGo = GameObjectToolSupport.ResolveUniqueTarget(parentName, "Parent GameObject is required.");
+                parent = parentGo.transform;
+            }
+            var posX = (float)(request.X ?? 0f);
+            var posY = (float)(request.Y ?? 0f);
+            var posZ = (float)(request.Z ?? 0f);
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    DryRun = true,
+                    SourcePath = path,
+                    PlannedEffects = new List<PrefabPlannedEffect> { new PrefabPlannedEffect { Type = "prefab.instantiate", Path = path } }
+                });
+            }
+            ctx.CommitEffect();
+            // PlayMode 也必须经 PrefabUtility.InstantiatePrefab：Object.Instantiate 不建立 prefab 连接，
+            // 终态 readback 的 GetCorrespondingObjectFromSource 断言必然失败，把合法调用判成 outcome-unknown。
+            var instance = (GameObject)PrefabUtility.InstantiatePrefab(prefab, parent != null ? parent.gameObject.scene : SceneManager.GetActiveScene());
+            if (parent != null) instance.transform.SetParent(parent, false);
+            instance.transform.position = new Vector3(posX, posY, posZ);
+            if (!string.IsNullOrEmpty(request.Name)) instance.name = request.Name;
+            UnityCliSceneMutation.MarkSceneDirty(instance.scene);
+            var observedInstance = EditorUtility.InstanceIDToObject(instance.GetInstanceID()) as GameObject;
+            var observedSourcePath = AssetDatabase.GUIDToAssetPath(sourceGuid);
+            var observedPrefab = string.IsNullOrEmpty(observedSourcePath) ? null : PrefabToolSupport.LoadPrefabAsset(observedSourcePath);
+            if (observedInstance == null || observedSourcePath != path || observedPrefab != prefab || PrefabUtility.GetCorrespondingObjectFromSource(observedInstance) != observedPrefab ||
+                observedInstance.transform.position != new Vector3(posX, posY, posZ) ||
+                (parent != null && observedInstance.transform.parent != parent) ||
+                (!string.IsNullOrEmpty(request.Name) && observedInstance.name != request.Name))
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_INSTANTIATE_STATE_MISMATCH", "Prefab instance readback did not match the request.", "Inspect the active scene and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Instance = GameObjectToolSupport.BuildGameObjectRef(observedInstance),
+                SourcePath = path,
+                PlannedEffects = new List<PrefabPlannedEffect> { new PrefabPlannedEffect { Type = "prefab.instantiate", Path = path } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/modify.cs

@@ -0,0 +1,112 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// prefab.modify — 修改 Prefab 内容(name/addChild/removeChild),通过 LoadPrefabContents 编辑后保存。
+    /// </summary>
+    public class PrefabModifyTool : IUnityCliTool<PrefabModifyTool.Request, PrefabModifyTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public string AddChild { get; set; }
+            public string RemoveChild { get; set; }
+            public bool? Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public PrefabInfo Prefab { get; set; }
+            public List<PrefabPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.modify",
+            Summary = "Modify a prefab's root name or add/remove a child by editing prefab contents in-place.",
+            Description = "Modify a prefab's contents. Supports renaming the root, adding a child (overwrite=true to replace an existing child of the same name), and removing a child by name. At least one mutation is required. Changes are saved through PrefabUtility.SaveAsPrefabAsset.",
+            Group = "prefab",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Add a child to a prefab", Input = new Request { Path = "Assets/Prefabs/Player.prefab", AddChild = "HealthBar" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            PrefabToolSupport.EnsureEditorNotBusy("prefab.modify");
+            var path = PrefabToolSupport.RequirePrefabPath(request.Path);
+            PrefabToolSupport.LoadPrefabAsset(path);
+            var root = PrefabUtility.LoadPrefabContents(path);
+            var effects = new List<PrefabPlannedEffect>();
+            try
+            {
+                var name = request.Name;
+                var addChild = request.AddChild;
+                var removeChild = request.RemoveChild;
+                var existingAddChild = string.IsNullOrEmpty(addChild) ? null : root.transform.Find(addChild);
+                var existingRemoveChild = string.IsNullOrEmpty(removeChild) ? null : root.transform.Find(removeChild);
+                if (existingAddChild != null && !(request.Overwrite ?? false))
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_CHILD_EXISTS", "Prefab child already exists: " + addChild, "Pass --overwrite or choose another child name.");
+                if (!string.IsNullOrEmpty(addChild) && addChild == removeChild)
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_CHILD_CONFLICT", "addChild and removeChild cannot target the same child.", "Use separate prefab.modify requests for conflicting child operations.");
+                if (!string.IsNullOrEmpty(removeChild) && existingRemoveChild == null)
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_CHILD_NOT_FOUND", "Prefab child not found: " + removeChild, "Run tools run prefab.hierarchy --input '{\"path\":\"<path>\"}' to inspect child paths.");
+                var rename = !string.IsNullOrEmpty(name) && root.name != name;
+                if (!rename && string.IsNullOrEmpty(addChild) && string.IsNullOrEmpty(removeChild))
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_MODIFY_NOOP", "No Prefab modifications were requested.", "Pass name, addChild or removeChild.");
+
+                ctx.CommitEffect();
+                if (rename)
+                {
+                    root.name = name;
+                    effects.Add(new PrefabPlannedEffect { Type = "prefab.modify", Path = path, Property = "name" });
+                }
+                if (!string.IsNullOrEmpty(addChild))
+                {
+                    if (existingAddChild != null) Object.DestroyImmediate(existingAddChild.gameObject);
+                    var child = new GameObject(addChild);
+                    child.transform.SetParent(root.transform, false);
+                    effects.Add(new PrefabPlannedEffect { Type = "prefab.modify", Path = path, AddChild = addChild });
+                }
+                if (!string.IsNullOrEmpty(removeChild))
+                {
+                    Object.DestroyImmediate(existingRemoveChild.gameObject);
+                    effects.Add(new PrefabPlannedEffect { Type = "prefab.modify", Path = path, RemoveChild = removeChild });
+                }
+
+                PrefabUtility.SaveAsPrefabAsset(root, path);
+                AssetDatabase.SaveAssets();
+                AssetDatabase.Refresh();
+                var observed = PrefabToolSupport.LoadPrefabAsset(path);
+                if (rename && observed.name != name)
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_MODIFY_PROOF_MISSING", "Prefab root name was not persisted.", "Inspect the Prefab asset before submitting a new request.");
+                if (!string.IsNullOrEmpty(addChild) && observed.transform.Find(addChild) == null)
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_MODIFY_PROOF_MISSING", "Prefab child was not persisted: " + addChild, "Inspect the Prefab asset before submitting a new request.");
+                if (!string.IsNullOrEmpty(removeChild) && observed.transform.Find(removeChild) != null)
+                    throw new UnityCliBridge.BridgeCommandException("E_PREFAB_MODIFY_PROOF_MISSING", "Prefab child was not removed: " + removeChild, "Inspect the Prefab asset before submitting a new request.");
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Prefab = PrefabToolSupport.BuildPrefabInfo(path, observed, observed, true),
+                    PlannedEffects = effects
+                });
+            }
+            finally
+            {
+                PrefabUtility.UnloadPrefabContents(root);
+            }
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/overrides/apply.cs

@@ -0,0 +1,51 @@
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>将一个 scene prefab instance 的全部 non-default overrides 应用到 source asset。</summary>
+    public sealed class PrefabOverridesApplyTool : IUnityCliTool<PrefabOverridesApplyTool.Request, PrefabOverrideResult>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Instance { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.overrides.apply",
+            Summary = "Apply one scene prefab instance's non-default overrides to its source asset and prove both identities.",
+            Description = "Binds the outermost instance root, source path/GUID and serialized source hash before one effect barrier. Success requires a changed source hash, a connected clean instance, and the same source identity.",
+            Group = "prefab",
+            DestructiveHint = true,
+            SideEffects = new[] { "prefab-asset-write", "scene-modify", "undo" },
+            SupportsDryRun = true,
+            Permissions = new[] { "project-asset-write", "scene-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 60000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Apply overrides from one scene instance.", Input = new Request { Instance = "Environment/Crate" } },
+                new ToolExample { Description = "Preview whether one instance has overrides to apply.", Input = new Request { Instance = "Environment/Crate" }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        public ValueTask<PrefabOverrideResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            PrefabToolSupport.EnsureEditorNotBusy("prefab.overrides.apply");
+            ct.ThrowIfCancellationRequested();
+            var plan = PrefabOverrideToolSupport.PrepareOverride(request.Instance);
+            if (ctx.DryRun) return new ValueTask<PrefabOverrideResult>(PrefabOverrideToolSupport.DryRunOverride(plan, "apply"));
+            if (!plan.Before.HasOverrides) return new ValueTask<PrefabOverrideResult>(PrefabOverrideToolSupport.NoopOverride(plan, "apply"));
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            PrefabOverrideToolSupport.ApplyOverrides(plan);
+            return new ValueTask<PrefabOverrideResult>(PrefabOverrideToolSupport.ProveOverrides(plan, "apply"));
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/overrides/revert.cs

@@ -0,0 +1,51 @@
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>回退一个 scene prefab instance 的全部 non-default overrides，并保持 source asset 不变。</summary>
+    public sealed class PrefabOverridesRevertTool : IUnityCliTool<PrefabOverridesRevertTool.Request, PrefabOverrideResult>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Instance { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.overrides.revert",
+            Summary = "Revert one scene prefab instance's non-default overrides and prove a clean connected instance.",
+            Description = "Binds the outermost instance root and source identity before one effect barrier. Success requires the same source hash and GUID, a connected instance, no remaining non-default overrides, and a dirty scene readback.",
+            Group = "prefab",
+            DestructiveHint = true,
+            SideEffects = new[] { "scene-modify", "undo" },
+            SupportsDryRun = true,
+            Permissions = new[] { "scene-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 300000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Revert overrides on one scene instance.", Input = new Request { Instance = "Environment/Crate" } },
+                new ToolExample { Description = "Preview whether one instance has overrides to revert.", Input = new Request { Instance = "Environment/Crate" }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        public ValueTask<PrefabOverrideResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            PrefabToolSupport.EnsureEditorNotBusy("prefab.overrides.revert");
+            ct.ThrowIfCancellationRequested();
+            var plan = PrefabOverrideToolSupport.PrepareOverride(request.Instance);
+            if (ctx.DryRun) return new ValueTask<PrefabOverrideResult>(PrefabOverrideToolSupport.DryRunOverride(plan, "revert"));
+            if (!plan.Before.HasOverrides) return new ValueTask<PrefabOverrideResult>(PrefabOverrideToolSupport.NoopOverride(plan, "revert"));
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            PrefabOverrideToolSupport.RevertOverrides(plan);
+            return new ValueTask<PrefabOverrideResult>(PrefabOverrideToolSupport.ProveOverrides(plan, "revert"));
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/stage-close.cs

@@ -0,0 +1,67 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// prefab.stage-close - 关闭没有未保存修改的 Prefab Stage。
+    /// </summary>
+    public class PrefabStageCloseTool : IUnityCliTool<PrefabStageCloseTool.Request, PrefabStageCloseTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public PrefabStageInfo Stage { get; set; }
+            public List<PrefabPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.stage-close",
+            Summary = "Close the currently open Prefab Stage after verifying it has no unsaved changes.",
+            Description = "Close the currently open Prefab Stage without saving. If the stage has unsaved changes, the call fails with E_PREFAB_DIRTY_CONFLICT; run prefab.stage-save first, then call this tool again.",
+            Group = "prefab",
+            DestructiveHint = false,
+            SideEffects = new[] { "editor-session" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Close the open Prefab Stage", Input = new Request { } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            PrefabToolSupport.EnsureEditorNotBusy("prefab.stage-close");
+            var stage = PrefabToolSupport.RequireCurrentPrefabStage(request.Path);
+            var path = PrefabToolSupport.StageAssetPath(stage);
+            if (PrefabToolSupport.StageIsDirty(stage))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_DIRTY_CONFLICT", "Prefab Stage has unsaved changes: " + path, "Run tools run prefab.stage-save, then retry prefab.stage-close.");
+            }
+            ctx.CommitEffect();
+            if (!PrefabToolSupport.ClosePrefabStage())
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_STAGE_CLOSE_FAILED", "Failed to close Prefab Stage: " + path, "Close the Prefab Stage in Unity or check UnityCliBridge.log.");
+            }
+            var observedStage = PrefabToolSupport.CurrentPrefabStage();
+            if (observedStage != null)
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_STAGE_CLOSE_MISMATCH", "Prefab Stage remained open after close: " + PrefabToolSupport.StageAssetPath(observedStage), "Inspect the current Prefab Stage and retry.");
+            var observed = PrefabToolSupport.BuildClosedStageInfo(path);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Stage = observed,
+                PlannedEffects = new List<PrefabPlannedEffect> { new PrefabPlannedEffect { Type = "prefab.stage-close", Path = observed.Path } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/prefab/stage-open.cs

@@ -0,0 +1,69 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// prefab.stage-open — 在 Prefab Stage 中打开 Assets/*.prefab。editor-only。
+    /// </summary>
+    public class PrefabStageOpenTool : IUnityCliTool<PrefabStageOpenTool.Request, PrefabStageOpenTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public PrefabStageInfo Stage { get; set; }
+            public List<PrefabPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "prefab.stage-open",
+            Summary = "Open an Assets/*.prefab in the Unity Prefab Stage for isolated editing.",
+            Description = "Open an Assets/*.prefab in the Unity Prefab Stage. Editor-only: this drives the editor's Prefab Isolation UI. Refuses if another dirty Prefab Stage is open; run prefab.stage-save or prefab.stage-close first.",
+            Group = "prefab",
+            DestructiveHint = false,
+            SideEffects = new[] { "editor-session" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Open a prefab in Prefab Stage", Input = new Request { Path = "Assets/Prefabs/Player.prefab" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            PrefabToolSupport.EnsureEditorNotBusy("prefab.stage-open");
+            var path = PrefabToolSupport.RequirePrefabPath(request.Path);
+            PrefabToolSupport.LoadPrefabAsset(path);
+            var stage = PrefabToolSupport.CurrentPrefabStage();
+            if (stage != null && PrefabToolSupport.StageIsDirty(stage)
+                && !string.Equals(PrefabToolSupport.StageAssetPath(stage), path, System.StringComparison.OrdinalIgnoreCase))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_DIRTY_CONFLICT", "Current Prefab Stage has unsaved changes.", "Run tools run prefab.stage-save or close/save the current Prefab Stage in Unity before opening another Prefab.");
+            }
+            ctx.CommitEffect();
+            if (!PrefabToolSupport.OpenPrefabStage(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_STAGE_OPEN_FAILED", "Failed to open Prefab Stage: " + path, "Check Unity Console and UnityCliBridge.log.");
+            }
+            var observedStage = PrefabToolSupport.CurrentPrefabStage();
+            if (observedStage == null || !string.Equals(PrefabToolSupport.StageAssetPath(observedStage), path, System.StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_PREFAB_STAGE_OPEN_MISMATCH", "Prefab Stage did not open the requested asset: " + path, "Inspect the current Prefab Stage and retry.");
+            var observed = PrefabToolSupport.BuildStageInfo("open", observedStage);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Stage = observed,
+                PlannedEffects = new List<PrefabPlannedEffect> { new PrefabPlannedEffect { Type = "prefab.stage-open", Path = observed.Path } }
+            });
+        }
+    }
+}
+#endif