@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/navmesh/bake-clear.cs

@@ -0,0 +1,70 @@
+#if UNITY_EDITOR
+#pragma warning disable 0618
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+using UnityEditor.AI;
+
+namespace UnityCli
+{
+    /// <summary>清除当前 open scenes 的 legacy baked NavMesh，并证明 world topology 为空。</summary>
+    public sealed class NavMeshBakeClearTool : IUnityCliTool<NavMeshBakeClearTool.Request, NavMeshBakeClearTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result
+        {
+            public bool Cleared { get; set; }
+            public bool DryRun { get; set; }
+            public NavMeshTopologyData Before { get; set; }
+            public NavMeshTopologyData After { get; set; }
+            public List<NavMeshSceneFileData> Scenes { get; set; }
+            public List<NavMeshPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "navmesh.bake-clear",
+            Summary = "Clear the legacy baked NavMesh and prove the current NavMesh world is empty.",
+            Description = "Clears only Unity's legacy baked NavMesh for loaded saved scenes, then saves and hashes those exact scenes. Every target scene must be clean before the effect, so unrelated changes are never persisted. Active NavMeshSurface data is rejected because global triangulation cannot prove a legacy-only clear; surface assets are never deleted.",
+            Group = "navmesh",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "navmesh-clear", "scene-modify" },
+            Permissions = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Preview clearing the legacy NavMesh.", Input = new Request(), Execution = new ToolExampleExecution { DryRun = true } },
+                new ToolExample { Description = "Clear the legacy NavMesh.", Input = new Request() }
+            }
+        };
+
+        /// <summary>读取 before topology 后只跨一次 barrier；返回前重新计算 triangulation。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            NavMeshToolSupport.EnsureEditorReady("navmesh.bake-clear", true);
+            NavMeshToolSupport.EnsureNoActiveBake("navmesh.bake-clear");
+            if (UnityCliBridge.UnityCliNavMeshBakeCoordinator.HasActiveSurfaceData())
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SURFACE_DATA_ACTIVE", "navmesh.bake-clear cannot prove a legacy-only clear while active NavMeshSurface data is registered.", "Disable or clear NavMeshSurface data, then retry the legacy clear.");
+            ct.ThrowIfCancellationRequested();
+            var scenes = NavMeshToolSupport.PrepareLoadedSceneFiles("navmesh.bake-clear");
+            var before = NavMeshToolSupport.ReadTopology();
+            var effects = new List<NavMeshPlannedEffect> { new NavMeshPlannedEffect { Type = "navmesh.bake-clear", Target = "open-scenes" } };
+            if (ctx.DryRun || NavMeshToolSupport.TopologyEmpty(before))
+                return new ValueTask<Result>(new Result { Cleared = false, DryRun = ctx.DryRun, Before = before, After = before, Scenes = scenes, PlannedEffects = effects });
+
+            ctx.CommitEffect();
+            NavMeshBuilder.ClearAllNavMeshes();
+            var observedScenes = NavMeshToolSupport.SaveAndProveSceneFiles(scenes, true);
+            var after = NavMeshToolSupport.ReadTopology();
+            if (!NavMeshToolSupport.TopologyEmpty(after))
+                throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "Legacy NavMesh clear did not produce an empty terminal readback.", "Run navmesh.bake-status and inspect the open scenes before deciding whether to retry.");
+            return new ValueTask<Result>(new Result { Cleared = true, DryRun = false, Before = before, After = after, Scenes = observedScenes, PlannedEffects = effects });
+        }
+    }
+}
+#pragma warning restore 0618
+#endif

package/unitypkg/Editor/Tools/navmesh/settings/set.cs

@@ -0,0 +1,73 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>写入 default agent 的批准 NavMesh settings，并以 fresh SerializedObject/file hash 证明。</summary>
+    public sealed class NavMeshSettingsSetTool : IUnityCliTool<NavMeshSettingsSetTool.Request, NavMeshSettingsSetTool.Result>
+    {
+        public sealed class Request
+        {
+            public double? AgentRadius { get; set; }
+            public double? AgentHeight { get; set; }
+            public double? AgentSlope { get; set; }
+            public double? AgentClimb { get; set; }
+            public double? MinRegionArea { get; set; }
+            public double? VoxelSize { get; set; }
+            public bool? ManualVoxelSize { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Changed { get; set; }
+            public bool DryRun { get; set; }
+            public List<string> AppliedFields { get; set; }
+            public NavMeshSettingsData Before { get; set; }
+            public NavMeshSettingsData After { get; set; }
+            public List<NavMeshPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "navmesh.settings.set",
+            Summary = "Set declared default-agent NavMesh fields and prove exact ProjectSettings persistence.",
+            Description = "Accepts any non-empty subset of agentRadius, agentHeight, agentSlope, agentClimb, minRegionArea, voxelSize, and manualVoxelSize. Values are fully validated before one effect barrier; voxelSize enables manual mode. Dry-run and exact no-op requests do not write ProjectSettings/NavMeshAreas.asset.",
+            Group = "navmesh",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "project-settings-write" },
+            Permissions = new[] { "project-settings-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set agent radius and height.", Input = new Request { AgentRadius = 0.5d, AgentHeight = 2d } },
+                new ToolExample { Description = "Preview manual voxel size.", Input = new Request { VoxelSize = 0.1d }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>冻结字段、当前文件 hash 与目标值；no-op/dry-run 不跨 effect barrier。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            NavMeshToolSupport.EnsureEditorReady("navmesh.settings.set", true);
+            NavMeshToolSupport.EnsureNoActiveBake("navmesh.settings.set");
+            ct.ThrowIfCancellationRequested();
+            request = request ?? new Request();
+            var plan = NavMeshToolSupport.PrepareSettings(request.AgentRadius, request.AgentHeight, request.AgentSlope, request.AgentClimb, request.MinRegionArea, request.VoxelSize, request.ManualVoxelSize);
+            var effects = new List<NavMeshPlannedEffect> { new NavMeshPlannedEffect { Type = "navmesh.settings.set", Target = plan.Before.SettingsPath } };
+            if (ctx.DryRun || !plan.Changed)
+                return new ValueTask<Result>(new Result { Changed = false, DryRun = ctx.DryRun, AppliedFields = plan.Fields, Before = plan.Before, After = plan.Desired, PlannedEffects = effects });
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            NavMeshToolSupport.ApplySettings(plan);
+            var after = NavMeshToolSupport.ProveSettings(plan);
+            return new ValueTask<Result>(new Result { Changed = true, DryRun = false, AppliedFields = plan.Fields, Before = plan.Before, After = after, PlannedEffects = effects });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/navmesh/settings.cs

@@ -0,0 +1,37 @@
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>读取 default agent 的 legacy NavMesh bake settings 与持久化文件身份。</summary>
+    public sealed class NavMeshSettingsTool : IUnityCliTool<NavMeshSettingsTool.Request, NavMeshSettingsTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public NavMeshSettingsData Settings { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "navmesh.settings",
+            Summary = "Read the default agent's persisted NavMesh project settings.",
+            Description = "Read-only: returns default-agent radius, height, slope, climb, minimum region area, voxel size/manual mode, and SHA-256 of ProjectSettings/NavMeshAreas.asset. The centralized Unity NavMeshProjectSettings reflection boundary and every required serialized property fail closed.",
+            Group = "navmesh",
+            DestructiveHint = false,
+            SideEffects = System.Array.Empty<string>(),
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Read default NavMesh settings.", Input = new Request() } }
+        };
+
+        /// <summary>直接从 current SerializedObject 与文件读取，不触发 import、save 或其他副作用。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            ct.ThrowIfCancellationRequested();
+            NavMeshToolSupport.EnsureEditorReady("navmesh.settings", false);
+            return new ValueTask<Result>(new Result { Settings = NavMeshToolSupport.ReadSettings() });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/object/ObjectToolSupport.cs

@@ -0,0 +1,99 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// object 域 IUnityCliTool 共享的基础设施 helper:序列化选项构造、对象引用解析。
+    /// 仅供 object 域自包含工具复用;不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    internal static class ObjectToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求,避免脏状态写入。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            if (EditorApplication.isCompiling)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_COMPILING", "Unity Editor is compiling scripts.", "Wait for Unity to finish compiling and retry.", transient: true, retryAfterMs: 5000);
+            }
+            if (EditorApplication.isUpdating)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_IMPORTING", "Unity Editor is importing assets.", "Wait for Unity to finish importing and retry.", transient: true, retryAfterMs: 5000);
+            }
+            if (UnityCliBridge.IsPlayModeChanging())
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_PLAY_MODE", "Unity Editor is entering or exiting Play mode.", "Wait for Play mode transition to complete and retry.", transient: true, retryAfterMs: 3000);
+            }
+            if (BuildPipeline.isBuildingPlayer)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_BUSY", "Unity Editor is building the player.", "Wait for the build to complete and retry.", transient: true, retryAfterMs: 10000);
+            }
+        }
+
+        /// <summary>Unity 工程根目录(Assets 的父目录)。</summary>
+        public static string ProjectRoot()
+        {
+            return Directory.GetParent(Application.dataPath).FullName;
+        }
+
+        /// <summary>
+        /// 从 UnityCli.Protocol.BridgeRequest 构造 ObjectSerializer.Options,复刻旧 BuildSerializerOptions 逻辑。
+        /// 支持 paths/viewQuery 局部读取、namePattern 过滤。
+        /// </summary>
+        internal static UnityCliBridge.ObjectSerializer.Options BuildSerializerOptions(IUnityCliObjectSerializationInput request)
+        {
+            var options = new UnityCliBridge.ObjectSerializer.Options
+            {
+                MaxDepth = request.MaxDepth ?? 4,
+                MaxArrayItems = System.Math.Max(0, System.Math.Min(request.MaxArrayItems ?? 50, 1000)),
+                IncludeFields = request.IncludeFields ?? true,
+                IncludeProperties = request.IncludeProperties ?? true,
+                DeepSerialization = request.DeepSerialization ?? true
+            };
+            if (request.Paths != null && request.Paths.Count > 0 && request.ViewQuery != null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_OBJECT_READ_SCOPE_CONFLICT", "paths and viewQuery are mutually exclusive.", "Use paths for exact member reads, or viewQuery for one filtered subtree.");
+            }
+            if (request.Paths != null)
+            {
+                options.Paths = new HashSet<string>(request.Paths.Where(path => !string.IsNullOrWhiteSpace(path)).Select(path => path.Trim()));
+            }
+            var query = request.ViewQuery as Dictionary<string, object>;
+            if (query != null)
+            {
+                options.ViewPath = GetStringMember(query, "path");
+                options.NamePattern = GetStringMember(query, "namePattern");
+                options.TypeFilter = GetStringMember(query, "typeFilter");
+                object maxDepth;
+                if (query.TryGetValue("maxDepth", out maxDepth) && maxDepth != null)
+                {
+                    options.MaxDepth = System.Math.Max(0, System.Convert.ToInt32(maxDepth, CultureInfo.InvariantCulture));
+                }
+            }
+            if (!string.IsNullOrEmpty(request.NamePattern))
+            {
+                options.NameFilters = new HashSet<string>(request.NamePattern.Split(',').Select(value => value.Trim()));
+            }
+            return options;
+        }
+
+        private static string GetStringMember(Dictionary<string, object> obj, string key)
+        {
+            if (obj == null) return null;
+            return obj.TryGetValue(key, out var val) ? val as string : null;
+        }
+
+        private static string GetRawMember(Dictionary<string, object> obj, string key)
+        {
+            if (obj == null) return null;
+            if (!obj.TryGetValue(key, out var val) || val == null) return null;
+            return val.ToString();
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/object/get-data.cs

@@ -0,0 +1,69 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// object.get-data — 读取任意 UnityEngine.Object 的深序列化数据。只读。
+    /// </summary>
+    public class ObjectGetDataTool : IUnityCliTool<ObjectGetDataTool.Request, ObjectGetDataTool.Result>
+    {
+        public sealed class Request : IUnityCliObjectReferenceInput, IUnityCliObjectSerializationInput
+        {
+            public int? InstanceId { get; set; }
+            public string AssetPath { get; set; }
+            public string Guid { get; set; }
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public string Target { get; set; }
+            public int? ComponentInstanceId { get; set; }
+            public int? ComponentIndex { get; set; }
+            public string Component { get; set; }
+            public string ComponentType { get; set; }
+            public int? MaxDepth { get; set; }
+            public int? MaxArrayItems { get; set; }
+            public bool? IncludeFields { get; set; }
+            public bool? IncludeProperties { get; set; }
+            public bool? DeepSerialization { get; set; }
+            public List<string> Paths { get; set; }
+            [UnityCliAnyJson] public object ViewQuery { get; set; }
+            public string NamePattern { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string TypeName { get; set; }
+            [UnityCliAnyJson] public object Data { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "object.get-data",
+            Summary = "Read deep serialized data from any Unity Object by instanceId, assetPath, guid or path.",
+            Description = "Read deep serialized data from any UnityEngine.Object. Resolves the target by instanceId, assetPath/guid, or path/name. Supports maxDepth, maxArrayItems, includeFields, includeProperties, deepSerialization, paths (exact member reads) and viewQuery (filtered subtree). Read-only.",
+            Group = "object",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read object data by hierarchy path", Input = new Request { Path = "Player" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var target = UnityCliBridge.ObjectRefResolver.ResolveObject(request);
+            var options = ObjectToolSupport.BuildSerializerOptions(request);
+            var data = UnityCliBridge.ObjectSerializer.Serialize(target, options);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                TypeName = target.GetType().FullName,
+                Data = data
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,126 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// object.modify — 使用可验证的 SerializedProperty pathPatches 修改 Unity Object。
+    /// </summary>
+    public class ObjectModifyTool : IUnityCliTool<ObjectModifyTool.Request, ObjectModifyTool.Result>
+    {
+        public sealed class Request : IUnityCliObjectReferenceInput, IUnityCliObjectSerializationInput
+        {
+            public int? InstanceId { get; set; }
+            public string AssetPath { get; set; }
+            public string Guid { get; set; }
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public string Target { get; set; }
+            public int? ComponentInstanceId { get; set; }
+            public int? ComponentIndex { get; set; }
+            public string Component { get; set; }
+            public string ComponentType { get; set; }
+            [UnityCliAnyJson] public List<object> PathPatches { get; set; }
+            public int? MaxDepth { get; set; }
+            public int? MaxArrayItems { get; set; }
+            public bool? IncludeFields { get; set; }
+            public bool? IncludeProperties { get; set; }
+            public bool? DeepSerialization { get; set; }
+            public List<string> Paths { get; set; }
+            [UnityCliAnyJson] public object ViewQuery { get; set; }
+            public string NamePattern { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool DryRun { get; set; }
+            public string TypeName { get; set; }
+            public List<string> ChangedPaths { get; set; }
+            [UnityCliAnyJson] public object UpdatedData { get; set; }
+            public List<PlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public sealed class PlannedEffect
+        {
+            public string Type { get; set; }
+            public string Target { get; set; }
+            public bool HasPathPatches { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "object.modify",
+            Summary = "Modify any Unity Object via verified serialized pathPatches; supports dry-run.",
+            Description = "Modify an object using non-empty direct replace pathPatches on verifiable SerializedProperties. Resolves the target by instanceId, assetPath/guid, or path/name. Supports dry-run to preview without applying. Marks scene objects dirty.",
+            Group = "object",
+            DestructiveHint = true,
+            SideEffects = new[] { "object-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            SupportsDryRun = true,
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Modify by pathPatches", Input = new Request { Path = "Player", PathPatches = new List<object> { new Dictionary<string, object> { { "path", "m_Name" }, { "op", "replace" }, { "value", "PlayerModified" } } } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ObjectToolSupport.EnsureEditorNotBusy("object.modify");
+            var target = UnityCliBridge.ObjectRefResolver.ResolveObject(request);
+            if (EditorApplication.isPlaying && EditorUtility.IsPersistent(target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", "object.modify cannot modify persistent assets during Play Mode.", "Target a scene object or exit Play Mode before modifying an asset.");
+            }
+
+            if (request.PathPatches == null || request.PathPatches.Count == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_OBJECT_PATCH_REQUIRED", "object.modify requires non-empty pathPatches.", "Pass direct replace pathPatches for writable serialized properties.");
+
+            var hasPathPatches = true;
+            UnityCliBridge.ObjectPatch.ValidateOnly(target, request.PathPatches, null);
+
+            // dry-run 预览:不修改对象
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    DryRun = true,
+                    TypeName = target.GetType().FullName,
+                    PlannedEffects = new List<PlannedEffect>
+                    {
+                        new PlannedEffect { Type = "object.modify", Target = target.name, HasPathPatches = hasPathPatches }
+                    }
+                });
+            }
+
+            ctx.CommitEffect();
+            UnityCliBridge.ObjectPatch.PatchResult result = UnityCliBridge.ObjectPatch.ApplyVerifiedSerializedPatches(target, request.PathPatches);
+
+            // Edit Mode 中同时持久化 asset dirty；Play Mode helper 不写任何 Editor dirty 状态。
+            UnityCliSceneMutation.MarkSceneObjectDirty(target);
+            if (target is Component c && c.gameObject != null) UnityCliSceneMutation.MarkSceneDirty(c.gameObject.scene);
+            if (target is GameObject go) UnityCliSceneMutation.MarkSceneDirty(go.scene);
+
+            // 回读更新后数据；空 patch result 不能作为业务修改已完成的证明。
+            if (result == null || result.ChangedPaths == null || result.ChangedPaths.Count == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_OBJECT_MODIFY_STATE_MISMATCH", "Object patch produced no independently observed changed paths.", "Inspect the target and patch paths, then retry with valid writable properties.");
+            var observedTarget = EditorUtility.InstanceIDToObject(target.GetInstanceID());
+            if (observedTarget == null) throw new UnityCliBridge.BridgeCommandException("E_OBJECT_MODIFY_STATE_MISMATCH", "Target could not be fresh-resolved after patch.", "Retry after the Editor is idle.");
+            UnityCliBridge.ObjectPatch.VerifyFreshSerializedProperties(observedTarget, request.PathPatches);
+            var options = ObjectToolSupport.BuildSerializerOptions(request);
+            var updatedData = UnityCliBridge.ObjectSerializer.Serialize(observedTarget, options);
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                TypeName = target.GetType().FullName,
+                ChangedPaths = result.ChangedPaths,
+                UpdatedData = updatedData
+            });
+        }
+    }
+}
+#endif