@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/material/set-renderer-color.cs

@@ -0,0 +1,108 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// material.set-renderer-color — 通过 MaterialPropertyBlock 设置 Renderer 实例颜色,不改共享 Material。
+    /// </summary>
+    public class MaterialSetRendererColorTool : IUnityCliTool<MaterialSetRendererColorTool.Request, MaterialSetRendererColorTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Name { get; set; }
+            public string Property { get; set; }
+            public string Color { get; set; }
+            public string Value { get; set; }
+            public int? Slot { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public MaterialColor Color { get; set; }
+            public bool? DryRun { get; set; }
+            public List<MaterialPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "material.set-renderer-color",
+            Summary = "Set a Renderer instance color via MaterialPropertyBlock without changing the shared material; supports --dry-run.",
+            Description = "Set a Renderer instance color through a MaterialPropertyBlock, leaving the shared Material asset untouched. Target must have a Renderer. property defaults to _Color; slot optionally targets a sub-material. Supports --dry-run to preview the planned color.",
+            Group = "material",
+            DestructiveHint = false,
+            SupportsDryRun = true,
+            SideEffects = new[] { "scene-modify", "renderer-property-block" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Tint a renderer red", Input = new Request { Target = "Player", Color = "#ff0000ff" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            MaterialToolSupport.EnsureEditorNotBusy("material.set-renderer-color");
+            var target = request.Target ?? request.Name;
+            var propertyName = request.Property ?? "_Color";
+            var colorValue = request.Color ?? request.Value;
+            var gameObject = GameObjectToolSupport.ResolveUniqueTarget(target, "Material renderer color requires a target GameObject.");
+            var renderer = gameObject.GetComponent<Renderer>();
+            if (renderer == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_RENDERER_NOT_FOUND", "Target has no Renderer component: " + target, "Choose a GameObject with a Renderer or use material.assign for UI Graphic materials.");
+            }
+            var color = MaterialToolSupport.ParseColor(colorValue);
+            var slot = request.Slot;
+            if (string.IsNullOrEmpty(propertyName) || float.IsNaN(color.r) || float.IsNaN(color.g) || float.IsNaN(color.b) || float.IsNaN(color.a) || float.IsInfinity(color.r) || float.IsInfinity(color.g) || float.IsInfinity(color.b) || float.IsInfinity(color.a))
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_COLOR_INVALID", "Property and color must be finite valid values.", "Pass a non-empty property and finite RGBA color.");
+            var materials = renderer.sharedMaterials;
+            if (slot.HasValue && (slot.Value < 0 || slot.Value >= materials.Length))
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_SLOT_INVALID", "Renderer material slot is out of range: " + slot.Value, "Pass a slot from 0 through " + (materials.Length - 1) + ".");
+            var materialIndex = slot ?? 0;
+            if (materials.Length == 0 || materials[materialIndex] == null || !materials[materialIndex].HasProperty(propertyName))
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_PROPERTY_NOT_FOUND", "Renderer material does not expose color property: " + propertyName, "Pass a color property supported by the selected material slot.");
+            var propertyId = Shader.PropertyToID(propertyName);
+            var rendererId = renderer.GetInstanceID();
+            var targetId = gameObject.GetInstanceID();
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Color = new MaterialColor { R = color.r, G = color.g, B = color.b, A = color.a },
+                    DryRun = true,
+                    PlannedEffects = new List<MaterialPlannedEffect> { new MaterialPlannedEffect { Type = "material.set-renderer-color", Target = GameObjectToolSupport.HierarchyPath(gameObject), Property = propertyName } }
+                });
+            }
+            var block = new MaterialPropertyBlock();
+            if (slot.HasValue) renderer.GetPropertyBlock(block, slot.Value); else renderer.GetPropertyBlock(block);
+            ctx.CommitEffect();
+            block.SetColor(propertyId, color);
+            if (slot.HasValue) renderer.SetPropertyBlock(block, slot.Value); else renderer.SetPropertyBlock(block);
+            UnityCliSceneMutation.MarkSceneObjectDirty(renderer);
+            UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+            var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            var observedRenderer = EditorUtility.InstanceIDToObject(rendererId) as Renderer;
+            var observedBlock = new MaterialPropertyBlock();
+            if (observedRenderer == null || observedTarget == null) throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_RENDERER_COLOR_STATE_MISMATCH", "Renderer disappeared before color readback.", "Retry after the Editor is idle.");
+            if (slot.HasValue) observedRenderer.GetPropertyBlock(observedBlock, slot.Value); else observedRenderer.GetPropertyBlock(observedBlock);
+            var observedColor = observedBlock.GetColor(propertyId);
+            if (!Mathf.Approximately(observedColor.r, color.r) || !Mathf.Approximately(observedColor.g, color.g) || !Mathf.Approximately(observedColor.b, color.b) || !Mathf.Approximately(observedColor.a, color.a))
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_RENDERER_COLOR_STATE_MISMATCH", "Renderer color did not match the requested property value.", "Inspect the Renderer property block and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Color = new MaterialColor { R = observedColor.r, G = observedColor.g, B = observedColor.b, A = observedColor.a },
+                PlannedEffects = new List<MaterialPlannedEffect> { new MaterialPlannedEffect { Type = "material.set-renderer-color", Target = GameObjectToolSupport.HierarchyPath(gameObject), Property = propertyName } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/material/set.cs

@@ -0,0 +1,114 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// material.set — 设置 Material 资产属性(color/float/vector/texture)。session-affecting(asset-write)。
+    /// </summary>
+    public class MaterialSetTool : IUnityCliTool<MaterialSetTool.Request, MaterialSetTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Path { get; set; }
+            [UnityCliRequired] public string Property { get; set; }
+            [UnityCliRequired] public string Value { get; set; }
+            public string Type { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public MaterialInfo Material { get; set; }
+            public string PropertyType { get; set; }
+            [UnityCliAnyJson] public object AppliedValue { get; set; }
+            public List<MaterialPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "material.set",
+            Summary = "Set a Material asset property (color, float, vector or texture) by shader property name.",
+            Description = "Set a Material asset property by shader property name. Pass the property value as value; the value type is inferred from the shader property when possible or overridden with type. Inspect properties with material.info first.",
+            Group = "material",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set the base color", Input = new Request { Path = "Assets/Materials/Probe.mat", Property = "_Color", Value = "#ff0000ff", Type = "color" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            MaterialToolSupport.EnsureEditorNotBusy("material.set");
+            var path = MaterialToolSupport.RequireMaterialPath(request.Path);
+            var propertyName = request.Property;
+            var value = request.Value;
+            var requestedType = request.Type;
+            var material = MaterialToolSupport.LoadMaterialAsset(path);
+            if (string.IsNullOrEmpty(propertyName))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_PROPERTY_REQUIRED", "Material set requires a property name.", "Inspect shader properties with tools run material.info --input '{\"path\":\"<path>\"}'.");
+            }
+            if (!material.HasProperty(propertyName))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_PROPERTY_NOT_FOUND", "Material property not found: " + propertyName, "Inspect shader properties with tools run material.info --input '{\"path\":\"<path>\"}'.");
+            }
+
+            var propertyType = MaterialToolSupport.MaterialPropertyType(material, propertyName);
+            var normalizedType = MaterialToolSupport.NormalizeMaterialValueType(string.IsNullOrEmpty(requestedType) ? propertyType : requestedType);
+            if (string.IsNullOrEmpty(normalizedType))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_PROPERTY_TYPE_UNSUPPORTED", "Unsupported Material property type for " + propertyName + ": " + propertyType, "Pass --type color|float|vector|texture when the shader property cannot be inferred.");
+            }
+            if (!MaterialToolSupport.TypesCompatible(propertyType, normalizedType))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_PROPERTY_TYPE_MISMATCH", "Material property " + propertyName + " is " + propertyType + ", not " + requestedType + ".", "Use the property type reported by tools run material.info --input '{\"path\":\"<path>\"}'.");
+            }
+
+            var plan = MaterialToolSupport.BuildMaterialValuePlan(normalizedType, value);
+            var appliedValue = PlannedValue(plan);
+            var materialGuid = AssetDatabase.AssetPathToGUID(path);
+            ctx.CommitEffect();
+            MaterialToolSupport.ApplyMaterialValue(material, propertyName, plan);
+            EditorUtility.SetDirty(material);
+            AssetDatabase.SaveAssets();
+            var observedPath = AssetDatabase.GUIDToAssetPath(materialGuid);
+            var observedMaterial = string.IsNullOrEmpty(observedPath) ? null : AssetDatabase.LoadAssetAtPath<Material>(observedPath);
+            if (observedMaterial == null || !ObservedValueMatches(observedMaterial, propertyName, normalizedType, appliedValue))
+                throw new UnityCliBridge.BridgeCommandException("E_MATERIAL_SET_STATE_MISMATCH", "Material property did not contain the requested value after save.", "Inspect the material property and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Material = MaterialToolSupport.BuildMaterialInfo(observedPath, observedMaterial, null),
+                PropertyType = propertyType,
+                AppliedValue = appliedValue,
+                PlannedEffects = new List<MaterialPlannedEffect> { new MaterialPlannedEffect { Type = "material.set", Path = path, Property = propertyName } }
+            });
+        }
+
+        private static object PlannedValue(MaterialValuePlan plan)
+        {
+            if (plan.Type == "color") return new MaterialColor { R = plan.Color.r, G = plan.Color.g, B = plan.Color.b, A = plan.Color.a };
+            if (plan.Type == "float") return plan.Float;
+            if (plan.Type == "vector") return new MaterialVector4 { X = plan.Vector.x, Y = plan.Vector.y, Z = plan.Vector.z, W = plan.Vector.w };
+            return new MaterialTextureValue { Path = plan.TexturePath, Guid = plan.Texture == null ? null : AssetDatabase.AssetPathToGUID(plan.TexturePath) };
+        }
+
+        private static bool ObservedValueMatches(Material material, string property, string type, object expected)
+        {
+            if (type == "float") return Mathf.Approximately(material.GetFloat(property), (float)expected);
+            if (type == "color") { var value = material.GetColor(property); var e = (MaterialColor)expected; return Mathf.Approximately(value.r, (float)e.R) && Mathf.Approximately(value.g, (float)e.G) && Mathf.Approximately(value.b, (float)e.B) && Mathf.Approximately(value.a, (float)e.A); }
+            if (type == "vector") { var value = material.GetVector(property); var e = (MaterialVector4)expected; return Mathf.Approximately(value.x, (float)e.X) && Mathf.Approximately(value.y, (float)e.Y) && Mathf.Approximately(value.z, (float)e.Z) && Mathf.Approximately(value.w, (float)e.W); }
+            var texture = material.GetTexture(property);
+            var eTexture = (MaterialTextureValue)expected;
+            return (texture == null ? null : AssetDatabase.AssetPathToGUID(AssetDatabase.GetAssetPath(texture))) == eTexture.Guid;
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,404 @@
+#if UNITY_EDITOR
+#pragma warning disable 0618
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Text;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.AI;
+using UnityEngine.SceneManagement;
+
+namespace UnityCli
+{
+    /// <summary>NavMesh settings 的公开 typed readback。</summary>
+    public sealed class NavMeshSettingsData
+    {
+        public bool Available { get; set; }
+        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 string SettingsPath { get; set; }
+        public string SettingsHash { get; set; }
+        public long SettingsSizeBytes { get; set; }
+    }
+
+    /// <summary>当前 NavMesh world triangulation 的有界摘要。</summary>
+    public sealed class NavMeshTopologyData
+    {
+        public long VertexCount { get; set; }
+        public long IndexCount { get; set; }
+        public string Sha256 { get; set; }
+    }
+
+    public sealed class NavMeshPlannedEffect
+    {
+        public string Type { get; set; }
+        public string Target { get; set; }
+    }
+
+    /// <summary>参与 legacy/surface 持久化 proof 的 scene 文件身份。</summary>
+    public sealed class NavMeshSceneFileData
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Sha256 { get; set; }
+        public long SizeBytes { get; set; }
+        public bool Dirty { get; set; }
+    }
+
+    /// <summary>legacy settings、topology 与 editor guard 的共享实现。</summary>
+    internal static class NavMeshToolSupport
+    {
+        internal const string NavigationPackageId = "com.unity.ai.navigation";
+        private const string SettingsRelativePath = "ProjectSettings/NavMeshAreas.asset";
+        private const string SettingsRootProperty = "m_Settings";
+        private const string PropAgentRadius = "agentRadius";
+        private const string PropAgentHeight = "agentHeight";
+        private const string PropAgentSlope = "agentSlope";
+        private const string PropAgentClimb = "agentClimb";
+        private const string PropMinRegionArea = "minRegionArea";
+        private const string PropManualCellSize = "manualCellSize";
+        private const string PropCellSize = "cellSize";
+
+        internal sealed class SettingsWritePlan
+        {
+            internal NavMeshSettingsData Before;
+            internal NavMeshSettingsData Desired;
+            internal UnityEngine.Object SettingsObject;
+            internal List<string> Fields;
+            internal bool Changed;
+        }
+
+        internal static void EnsureEditorReady(string tool, bool requireEditMode)
+        {
+            if (EditorApplication.isCompiling || EditorApplication.isUpdating)
+                throw new UnityCliBridge.BridgeCommandException("E_EDITOR_BUSY", tool + " requires an idle Unity Editor.", "Wait for compilation/import to finish, then retry.");
+            if (requireEditMode && (EditorApplication.isPlaying || EditorApplication.isPlayingOrWillChangePlaymode))
+                throw new UnityCliBridge.BridgeCommandException("E_TOOL_PLAYMODE_UNAVAILABLE", tool + " is available only in Edit Mode.", "Exit Play Mode, then retry.");
+        }
+
+        internal static void EnsureNoActiveBake(string tool)
+        {
+            var status = UnityCliBridge.UnityCliNavMeshBakeCoordinator.PublicStatus();
+            if (UnityCliBridge.UnityCliNavMeshBakeCoordinator.HasActiveNativeBake()
+                || string.Equals(Convert.ToString(status["state"], CultureInfo.InvariantCulture), "running", StringComparison.Ordinal))
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_BAKE_ACTIVE", tool + " cannot mutate NavMesh state while a tracked or untracked native bake is running.", "Use navmesh.bake-status and wait for all native NavMesh work to finish before retrying.");
+        }
+
+        /// <summary>必需 serialized property 缺失时 fail closed，不使用猜测默认值。</summary>
+        internal static NavMeshSettingsData ReadSettings()
+        {
+            var settingsObject = ProjectSettingsObject();
+            var serialized = new SerializedObject(settingsObject);
+            serialized.Update();
+            var prefix = DefaultAgentPrefix(serialized);
+            var data = new NavMeshSettingsData
+            {
+                Available = true,
+                AgentRadius = Float(serialized, prefix + "." + PropAgentRadius),
+                AgentHeight = Float(serialized, prefix + "." + PropAgentHeight),
+                AgentSlope = Float(serialized, prefix + "." + PropAgentSlope),
+                AgentClimb = Float(serialized, prefix + "." + PropAgentClimb),
+                MinRegionArea = Float(serialized, prefix + "." + PropMinRegionArea),
+                VoxelSize = Float(serialized, prefix + "." + PropCellSize),
+                ManualVoxelSize = Bool(serialized, prefix + "." + PropManualCellSize),
+                SettingsPath = SettingsRelativePath
+            };
+            PopulateSettingsFile(data);
+            return data;
+        }
+
+        /// <summary>effect 前冻结完整 requested settings 与当前 settings 文件身份。</summary>
+        internal static SettingsWritePlan PrepareSettings(
+            double? agentRadius,
+            double? agentHeight,
+            double? agentSlope,
+            double? agentClimb,
+            double? minRegionArea,
+            double? voxelSize,
+            bool? manualVoxelSize)
+        {
+            var fields = new List<string>();
+            var before = ReadSettings();
+            var desired = Copy(before);
+            ApplyRequested("agentRadius", agentRadius, 0.000001d, 1000d, fields, value => desired.AgentRadius = value);
+            ApplyRequested("agentHeight", agentHeight, 0.000001d, 1000d, fields, value => desired.AgentHeight = value);
+            ApplyRequested("agentSlope", agentSlope, 0d, 60d, fields, value => desired.AgentSlope = value);
+            ApplyRequested("agentClimb", agentClimb, 0d, 1000d, fields, value => desired.AgentClimb = value);
+            ApplyRequested("minRegionArea", minRegionArea, 0d, 1000000000d, fields, value => desired.MinRegionArea = value);
+            ApplyRequested("voxelSize", voxelSize, 0.000001d, 1000d, fields, value => { desired.VoxelSize = value; desired.ManualVoxelSize = true; });
+            if (manualVoxelSize.HasValue) { fields.Add("manualVoxelSize"); desired.ManualVoxelSize = manualVoxelSize.Value; }
+            if (fields.Count == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_SCHEMA_INVALID", "navmesh.settings.set requires at least one settings field.", "Pass one or more fields returned by navmesh.settings.");
+            var settingsObject = ProjectSettingsObject();
+            return new SettingsWritePlan
+            {
+                Before = before,
+                Desired = desired,
+                SettingsObject = settingsObject,
+                Fields = fields.Distinct(StringComparer.Ordinal).ToList(),
+                Changed = fields.Any(field => !FieldEquals(field, before, desired))
+            };
+        }
+
+        /// <summary>一次写入所有冻结字段并保存 ProjectSettings，调用方负责 effect barrier。</summary>
+        internal static void ApplySettings(SettingsWritePlan plan)
+        {
+            var serialized = new SerializedObject(plan.SettingsObject);
+            serialized.Update();
+            var prefix = DefaultAgentPrefix(serialized);
+            foreach (var field in plan.Fields)
+            {
+                switch (field)
+                {
+                    case "agentRadius": SetFloat(serialized, prefix + "." + PropAgentRadius, plan.Desired.AgentRadius); break;
+                    case "agentHeight": SetFloat(serialized, prefix + "." + PropAgentHeight, plan.Desired.AgentHeight); break;
+                    case "agentSlope": SetFloat(serialized, prefix + "." + PropAgentSlope, plan.Desired.AgentSlope); break;
+                    case "agentClimb": SetFloat(serialized, prefix + "." + PropAgentClimb, plan.Desired.AgentClimb); break;
+                    case "minRegionArea": SetFloat(serialized, prefix + "." + PropMinRegionArea, plan.Desired.MinRegionArea); break;
+                    case "voxelSize": SetFloat(serialized, prefix + "." + PropCellSize, plan.Desired.VoxelSize); SetBool(serialized, prefix + "." + PropManualCellSize, true); break;
+                    case "manualVoxelSize": SetBool(serialized, prefix + "." + PropManualCellSize, plan.Desired.ManualVoxelSize); break;
+                    default: throw new InvalidOperationException("Unexpected NavMesh settings field: " + field);
+                }
+            }
+            if (!serialized.ApplyModifiedPropertiesWithoutUndo())
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_WRITE_FAILED", "Unity did not apply the requested NavMesh settings.", "Inspect ProjectSettings/NavMeshAreas.asset and Unity Console before retrying.");
+            EditorUtility.SetDirty(plan.SettingsObject);
+            AssetDatabase.SaveAssets();
+        }
+
+        internal static NavMeshSettingsData ProveSettings(SettingsWritePlan plan)
+        {
+            var after = ReadSettings();
+            foreach (var field in plan.Fields)
+                if (!FieldEquals(field, after, plan.Desired))
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "NavMesh settings terminal readback does not match the requested values.", "Run navmesh.settings before deciding whether to retry.");
+            if (after.SettingsSizeBytes <= 0 || string.IsNullOrEmpty(after.SettingsHash) || !string.Equals(after.SettingsPath, plan.Before.SettingsPath, StringComparison.Ordinal)
+                || (plan.Changed && string.Equals(after.SettingsHash, plan.Before.SettingsHash, StringComparison.Ordinal)))
+                throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "NavMesh settings persistence could not be proven.", "Inspect ProjectSettings/NavMeshAreas.asset before deciding whether to retry.");
+            return after;
+        }
+
+        /// <summary>effect 前冻结全部 loaded saved scene；任何既存 dirty scene 都禁止被 bake/clear 顺带保存。</summary>
+        internal static List<NavMeshSceneFileData> PrepareLoadedSceneFiles(string tool)
+        {
+            var paths = new List<string>();
+            for (var index = 0; index < SceneManager.sceneCount; index++)
+            {
+                var scene = SceneManager.GetSceneAt(index);
+                if (!scene.IsValid() || !scene.isLoaded) continue;
+                if (string.IsNullOrEmpty(scene.path))
+                    throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SCENE_REQUIRED", tool + " requires every loaded target scene to be saved.", "Save or close untitled scenes, then retry.");
+                paths.Add(scene.path);
+            }
+            return PrepareSceneFiles(paths, tool);
+        }
+
+        internal static List<NavMeshSceneFileData> PrepareSceneFiles(IEnumerable<string> paths, string tool)
+        {
+            var result = new List<NavMeshSceneFileData>();
+            foreach (var path in (paths ?? Array.Empty<string>()).Where(value => !string.IsNullOrEmpty(value)).Distinct(StringComparer.Ordinal).OrderBy(value => value, StringComparer.Ordinal))
+            {
+                var scene = SceneManager.GetSceneByPath(path);
+                if (!scene.IsValid() || !scene.isLoaded)
+                    throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SCENE_REQUIRED", tool + " target scene is not loaded: " + path + ".");
+                if (scene.isDirty)
+                    throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SCENE_DIRTY", tool + " will not save a target scene that already has unrelated dirty changes: " + path + ".", "Save or discard that scene's changes, then retry.");
+                result.Add(ReadSceneFile(scene));
+            }
+            if (result.Count == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SCENE_REQUIRED", tool + " requires at least one loaded, saved scene.", "Save and load the target scene, then retry.");
+            return result;
+        }
+
+        /// <summary>effect前或terminal readback验证冻结scene identity与文件内容未被外部修改。</summary>
+        internal static void ValidateFrozenSceneFiles(IEnumerable<NavMeshSceneFileData> frozenScenes, string tool)
+        {
+            foreach (var frozen in frozenScenes ?? Array.Empty<NavMeshSceneFileData>())
+            {
+                var scene = SceneManager.GetSceneByPath(frozen.Path);
+                if (!scene.IsValid() || !scene.isLoaded || scene.isDirty
+                    || !string.Equals(AssetDatabase.AssetPathToGUID(frozen.Path), frozen.Guid, StringComparison.Ordinal))
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", tool + " target scene identity or dirty state changed.");
+                var observed = ReadSceneFile(scene);
+                if (observed.SizeBytes != frozen.SizeBytes || !string.Equals(observed.Sha256, frozen.Sha256, StringComparison.Ordinal))
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", tool + " target scene file changed outside the frozen request.");
+            }
+        }
+
+        /// <summary>effect 后只保存冻结 scene，并证明 GUID/path/clean/file artifact；不保存其他 loaded scene。</summary>
+        internal static List<NavMeshSceneFileData> SaveAndProveSceneFiles(IEnumerable<NavMeshSceneFileData> before, bool requireChangedHash)
+        {
+            var result = new List<NavMeshSceneFileData>();
+            foreach (var frozen in before ?? Array.Empty<NavMeshSceneFileData>())
+            {
+                var scene = SceneManager.GetSceneByPath(frozen.Path);
+                if (!scene.IsValid() || !scene.isLoaded || !string.Equals(AssetDatabase.AssetPathToGUID(frozen.Path), frozen.Guid, StringComparison.Ordinal))
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "NavMesh target scene identity changed before persistence proof.", "Inspect the target scenes before deciding whether to retry.");
+                EditorSceneManager.MarkSceneDirty(scene);
+                if (!EditorSceneManager.SaveScene(scene))
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "NavMesh target scene could not be saved after the effect.", "Inspect the target scene and Unity Console before deciding whether to retry.");
+                var observed = ReadSceneFile(scene);
+                if (observed.Dirty || (requireChangedHash && string.Equals(observed.Sha256, frozen.Sha256, StringComparison.Ordinal)))
+                    throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "NavMesh scene persistence proof did not change the serialized target.", "Inspect the target scene file before deciding whether to retry.");
+                result.Add(observed);
+            }
+            return result;
+        }
+
+        internal static Dictionary<string, object> SceneDictionary(NavMeshSceneFileData value)
+        {
+            return new Dictionary<string, object> { { "path", value.Path }, { "guid", value.Guid }, { "sha256", value.Sha256 }, { "sizeBytes", value.SizeBytes }, { "dirty", value.Dirty } };
+        }
+
+        private static NavMeshSceneFileData ReadSceneFile(Scene scene)
+        {
+            var root = Path.GetDirectoryName(Application.dataPath);
+            var fullPath = Path.Combine(root ?? string.Empty, scene.path.Replace('/', Path.DirectorySeparatorChar));
+            if (!File.Exists(fullPath)) throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SCENE_REQUIRED", "NavMesh target scene file is missing: " + scene.path + ".");
+            var guid = AssetDatabase.AssetPathToGUID(scene.path);
+            if (string.IsNullOrEmpty(guid)) throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SCENE_REQUIRED", "NavMesh target scene GUID is unavailable: " + scene.path + ".");
+            var bytes = File.ReadAllBytes(fullPath);
+            return new NavMeshSceneFileData { Path = scene.path, Guid = guid, Sha256 = Sha256(bytes), SizeBytes = bytes.LongLength, Dirty = scene.isDirty };
+        }
+
+        internal static NavMeshTopologyData ReadTopology()
+        {
+            var triangulation = NavMesh.CalculateTriangulation();
+            var vertices = triangulation.vertices ?? Array.Empty<Vector3>();
+            var indices = triangulation.indices ?? Array.Empty<int>();
+            var text = new StringBuilder();
+            for (var i = 0; i < vertices.Length; i++)
+                text.Append(vertices[i].x.ToString("R", CultureInfo.InvariantCulture)).Append(',')
+                    .Append(vertices[i].y.ToString("R", CultureInfo.InvariantCulture)).Append(',')
+                    .Append(vertices[i].z.ToString("R", CultureInfo.InvariantCulture)).Append(';');
+            text.Append('|');
+            for (var i = 0; i < indices.Length; i++) text.Append(indices[i].ToString(CultureInfo.InvariantCulture)).Append(',');
+            return new NavMeshTopologyData { VertexCount = vertices.LongLength, IndexCount = indices.LongLength, Sha256 = Sha256(Encoding.UTF8.GetBytes(text.ToString())) };
+        }
+
+        internal static Dictionary<string, object> TopologyDictionary()
+        {
+            var value = ReadTopology();
+            return new Dictionary<string, object> { { "vertexCount", value.VertexCount }, { "indexCount", value.IndexCount }, { "sha256", value.Sha256 } };
+        }
+
+        internal static bool TopologyEmpty(NavMeshTopologyData value)
+        {
+            return value != null && value.VertexCount == 0 && value.IndexCount == 0;
+        }
+
+        private static void PopulateSettingsFile(NavMeshSettingsData data)
+        {
+            var root = Path.GetDirectoryName(Application.dataPath);
+            var path = Path.Combine(root ?? string.Empty, SettingsRelativePath.Replace('/', Path.DirectorySeparatorChar));
+            if (!File.Exists(path))
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_UNAVAILABLE", "ProjectSettings/NavMeshAreas.asset is unavailable.", "Open the project in Unity and inspect Navigation settings.");
+            var bytes = File.ReadAllBytes(path);
+            data.SettingsHash = Sha256(bytes);
+            data.SettingsSizeBytes = bytes.LongLength;
+        }
+
+        /// <summary>集中绑定 Unity editor 的 NavMeshProjectSettings singleton；缺失 API 或 default agent 时 fail closed。</summary>
+        private static UnityEngine.Object ProjectSettingsObject()
+        {
+            var type = typeof(Editor).Assembly.GetType("UnityEditor.Unsupported", false);
+            var method = type == null ? null : type.GetMethod("GetSerializedAssetInterfaceSingleton", System.Reflection.BindingFlags.Static | System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.NonPublic, null, new[] { typeof(string) }, null);
+            var value = method == null ? null : method.Invoke(null, new object[] { "NavMeshProjectSettings" }) as UnityEngine.Object;
+            if (value == null)
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_SCHEMA_UNSUPPORTED", "Unity NavMeshProjectSettings singleton API is unavailable.", "Use a Unity version supported by this CLI build.");
+            return value;
+        }
+
+        private static string DefaultAgentPrefix(SerializedObject serialized)
+        {
+            var settings = serialized.FindProperty(SettingsRootProperty);
+            if (settings == null || !settings.isArray)
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_SCHEMA_UNSUPPORTED", "Unity NavMeshProjectSettings.m_Settings is unavailable.");
+            for (var index = 0; index < settings.arraySize; index++)
+            {
+                var element = settings.GetArrayElementAtIndex(index);
+                var id = element == null ? null : element.FindPropertyRelative("agentTypeID");
+                if (id != null && id.propertyType == SerializedPropertyType.Integer && id.intValue == 0) return element.propertyPath;
+            }
+            throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_SCHEMA_UNSUPPORTED", "Unity default NavMesh agent settings are unavailable.");
+        }
+
+        private static NavMeshSettingsData Copy(NavMeshSettingsData value)
+        {
+            return new NavMeshSettingsData
+            {
+                Available = value.Available,
+                AgentRadius = value.AgentRadius,
+                AgentHeight = value.AgentHeight,
+                AgentSlope = value.AgentSlope,
+                AgentClimb = value.AgentClimb,
+                MinRegionArea = value.MinRegionArea,
+                VoxelSize = value.VoxelSize,
+                ManualVoxelSize = value.ManualVoxelSize,
+                SettingsPath = value.SettingsPath,
+                SettingsHash = value.SettingsHash,
+                SettingsSizeBytes = value.SettingsSizeBytes
+            };
+        }
+
+        private static void ApplyRequested(string field, double? value, double minimum, double maximum, List<string> fields, Action<double> assign)
+        {
+            if (!value.HasValue) return;
+            if (double.IsNaN(value.Value) || double.IsInfinity(value.Value) || value.Value < minimum || value.Value > maximum)
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_VALUE_INVALID", field + " must be finite in [" + minimum.ToString("R", CultureInfo.InvariantCulture) + "," + maximum.ToString("R", CultureInfo.InvariantCulture) + "].", "Pass a value inside the documented range.");
+            fields.Add(field);
+            assign(value.Value);
+        }
+
+        private static bool FieldEquals(string field, NavMeshSettingsData left, NavMeshSettingsData right)
+        {
+            switch (field)
+            {
+                case "agentRadius": return Close(left.AgentRadius, right.AgentRadius);
+                case "agentHeight": return Close(left.AgentHeight, right.AgentHeight);
+                case "agentSlope": return Close(left.AgentSlope, right.AgentSlope);
+                case "agentClimb": return Close(left.AgentClimb, right.AgentClimb);
+                case "minRegionArea": return Close(left.MinRegionArea, right.MinRegionArea);
+                case "voxelSize": return Close(left.VoxelSize, right.VoxelSize) && left.ManualVoxelSize == right.ManualVoxelSize;
+                case "manualVoxelSize": return left.ManualVoxelSize == right.ManualVoxelSize;
+                default: return false;
+            }
+        }
+
+        private static bool Close(double left, double right) { return Math.Abs(left - right) <= 0.00001d; }
+        private static double Float(SerializedObject value, string path) { var property = Required(value, path, SerializedPropertyType.Float); return property.floatValue; }
+        private static bool Bool(SerializedObject value, string path)
+        {
+            var property = RequiredAny(value, path, SerializedPropertyType.Boolean, SerializedPropertyType.Integer);
+            return property.propertyType == SerializedPropertyType.Boolean ? property.boolValue : property.intValue != 0;
+        }
+        private static void SetFloat(SerializedObject value, string path, double number) { Required(value, path, SerializedPropertyType.Float).floatValue = checked((float)number); }
+        private static void SetBool(SerializedObject value, string path, bool flag)
+        {
+            var property = RequiredAny(value, path, SerializedPropertyType.Boolean, SerializedPropertyType.Integer);
+            if (property.propertyType == SerializedPropertyType.Boolean) property.boolValue = flag; else property.intValue = flag ? 1 : 0;
+        }
+        private static SerializedProperty Required(SerializedObject value, string path, SerializedPropertyType type) { return RequiredAny(value, path, type); }
+        /// <summary>Unity 2022/6000 对 serialized bool 的 type 投影不同，只接受已登记的两种明确形态。</summary>
+        private static SerializedProperty RequiredAny(SerializedObject value, string path, params SerializedPropertyType[] types)
+        {
+            var property = value.FindProperty(path);
+            if (property == null || !types.Contains(property.propertyType))
+                throw new UnityCliBridge.BridgeCommandException("E_NAVMESH_SETTINGS_SCHEMA_UNSUPPORTED", "Unity NavMesh settings property is unavailable or has an unsupported type: " + path + ".", "Use a Unity version supported by this CLI build.");
+            return property;
+        }
+        internal static string Sha256(byte[] value) { using (var hash = SHA256.Create()) return BitConverter.ToString(hash.ComputeHash(value ?? Array.Empty<byte>())).Replace("-", string.Empty).ToLowerInvariant(); }
+    }
+}
+#pragma warning restore 0618
+#endif