@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/shader/list.cs

@@ -0,0 +1,82 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.list — 列出项目中所有 Shader 资产,可按 keyword 过滤。
+    /// </summary>
+    public class ShaderListTool : IUnityCliTool<ShaderListTool.Request, ShaderListTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Keyword { get; set; }
+            public string Search { get; set; }
+            public int? PageSize { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long Count { get; set; }
+            public List<ShaderListItem> Shaders { get; set; }
+        }
+
+        public sealed class ShaderListItem
+        {
+            public string Path { get; set; }
+            public string Guid { get; set; }
+            public string Name { get; set; }
+            public long PropertyCount { get; set; }
+            public long RenderQueue { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.list",
+            Summary = "List all Shader assets in the project, optionally filtered by keyword, paged.",
+            Description = "List all Shader assets in the project via AssetDatabase. Optional keyword filters by asset name/path. Results are paged via pageSize (default 100, max 500). Use shader.info or shader.get-data for details on a specific shader.",
+            Group = "shader",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List shaders matching a keyword", Input = new Request { Keyword = "Lit", PageSize = 25 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var keyword = request.Keyword ?? request.Search;
+            var guids = AssetDatabase.FindAssets("t:Shader " + (keyword ?? string.Empty));
+            var pageSize = Math.Max(1, Math.Min(request.PageSize ?? 100, 500));
+            var results = new List<ShaderListItem>();
+            foreach (var guid in guids)
+            {
+                if (results.Count >= pageSize) break;
+                var assetPath = AssetDatabase.GUIDToAssetPath(guid);
+                var shader = AssetDatabase.LoadMainAssetAtPath(assetPath) as Shader;
+                if (shader == null) continue;
+                results.Add(new ShaderListItem
+                {
+                    Path = AssetToolSupport.NormalizeAssetPath(assetPath),
+                    Guid = guid,
+                    Name = shader.name,
+                    PropertyCount = shader.GetPropertyCount(),
+                    RenderQueue = shader.renderQueue
+                });
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Count = results.Count,
+                Shaders = results
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/shader/read.cs

@@ -0,0 +1,84 @@
+#if UNITY_EDITOR
+using System;
+using System.Globalization;
+using System.IO;
+using System.Text;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.read — 分页读取 Shader 源码文本(offset/maxBytes/nextOffset)。
+    /// </summary>
+    public class ShaderReadTool : IUnityCliTool<ShaderReadTool.Request, ShaderReadTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Target { get; set; }
+            public int? Offset { get; set; }
+            public int? MaxBytes { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ShaderInfo Shader { get; set; }
+            public string Content { get; set; }
+            public string Encoding { get; set; }
+            public long SizeBytes { get; set; }
+            public long ReturnedBytes { get; set; }
+            public bool Truncated { get; set; }
+            public string NextOffset { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.read",
+            Summary = "Read shader source text in bounded pages with offset/maxBytes and nextOffset continuation.",
+            Description = "Read shader source text from an Assets/*.shader file in bounded pages. Use offset to continue from a previous nextOffset and maxBytes to cap the returned chunk. ShaderGraph (.shadergraph) assets are JSON, not HLSL source.",
+            Group = "shader",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read the first 64KB", Input = new Request { Path = "Assets/Shaders/Example.shader", MaxBytes = 65536 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = ShaderToolSupport.ResolveShaderPath(request.Path ?? request.Target);
+            ShaderToolSupport.LoadShaderLikeAsset(path);
+            byte[] bytes;
+            try
+            {
+                bytes = File.ReadAllBytes(AssetToolSupport.AssetFullPath(path));
+            }
+            catch (Exception exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to read Shader file: " + exception.Message, "Check file encoding and permissions: " + path);
+            }
+            var offset = Math.Max(0, request.Offset ?? 0);
+            var maxBytes = Math.Max(1, Math.Min(request.MaxBytes ?? 65536, 1024 * 1024));
+            if (offset > bytes.Length) offset = bytes.Length;
+            var returnedBytes = Math.Min(maxBytes, bytes.Length - offset);
+            var content = Encoding.UTF8.GetString(bytes, offset, returnedBytes);
+            var nextOffset = offset + returnedBytes < bytes.Length ? (offset + returnedBytes).ToString(CultureInfo.InvariantCulture) : null;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Shader = ShaderToolSupport.BuildShaderInfo(path, AssetDatabase.LoadAssetAtPath<Shader>(path), true),
+                Content = content,
+                Encoding = "utf-8",
+                SizeBytes = bytes.Length,
+                ReturnedBytes = returnedBytes,
+                Truncated = nextOffset != null,
+                NextOffset = nextOffset
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/shader/update.cs

@@ -0,0 +1,71 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.update — 用新 content 覆盖 Shader 源码并重新编译。
+    /// </summary>
+    public class ShaderUpdateTool : IUnityCliTool<ShaderUpdateTool.Request, ShaderUpdateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Target { get; set; }
+            public string Content { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ShaderInfo Shader { get; set; }
+            public List<ShaderPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.update",
+            Summary = "Overwrite an existing shader's source content and force-recompile it.",
+            Description = "Overwrite an existing Assets/*.shader (or .shadergraph) source with new content and force-reimport it. The shader must already exist. Updating triggers shader recompilation; check shader.get-data diagnostics afterward.",
+            Group = "shader",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write", "shader-recompile" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Update shader source", Input = new Request { Path = "Assets/Shaders/Example.shader", Content = "Shader \"UnityCli/Example\" { SubShader { Pass {} } }" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ShaderToolSupport.EnsureEditorNotBusy("shader.update");
+            var path = ShaderToolSupport.ResolveShaderPath(request.Path ?? request.Target);
+            ShaderToolSupport.LoadShaderLikeAsset(path);
+            var content = request.Content;
+            if (content == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_CONTENT_REQUIRED", "Shader update requires content or content-file.", "Pass replacement Shader content via --content-file.");
+            }
+
+            ctx.CommitEffect();
+            AssetToolSupport.WriteTextAsset(path, content, true);
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            AssetDatabase.SaveAssets();
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            if (!File.Exists(AssetToolSupport.AssetFullPath(path)) || File.ReadAllText(AssetToolSupport.AssetFullPath(path)) != content)
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_UPDATE_STATE_MISMATCH", "Fresh shader bytes did not match the requested content: " + path, "Check file permissions and retry.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Shader = ShaderToolSupport.BuildShaderInfo(path, AssetDatabase.LoadAssetAtPath<Shader>(path), false),
+                PlannedEffects = new List<ShaderPlannedEffect> { new ShaderPlannedEffect { Type = "shader.update", Path = path, Refresh = true } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/tests/list.cs

@@ -0,0 +1,98 @@
+#if UNITY_EDITOR
+using System;
+
+namespace UnityCli.Tools.Tests
+{
+    /// <summary>
+    /// tests.list 只读 Tool：读取 Unity Test Runner 可用性和测试发现诊断。
+    /// </summary>
+    public class TestsListTool : IUnityCliTool<TestsListTool.Request, TestsListTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Mode { get; set; }
+            public int PageSize { get; set; }
+            public string Cursor { get; set; }
+        }
+
+        public sealed class TestInfo { }
+
+        public sealed class Result
+        {
+            public bool Available { get; set; }
+            public TestInfo[] Tests { get; set; }
+            public int Count { get; set; }
+            public string Diagnostics { get; set; }
+            public string[] NextActions { get; set; }
+        }
+
+        // ── desc:只声明人工字段,source=built-in 表示进入只读 Tool 表 ──
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "tests.list",
+            Summary = "Report Unity Test Runner discovery availability and diagnostics.",
+            Description = "List all test fixtures and test methods in the project.",
+            DestructiveHint = false,
+            Group = "tests",
+            Target = "editor",
+            PlayModeSupport = "supported",
+            Examples = new[] { new ToolExample { Description = "List available EditMode tests", Input = new Request { Mode = "EditMode", PageSize = 50 } }, new ToolExample { Description = "List available PlayMode tests", Input = new Request { Mode = "PlayMode", PageSize = 50 } } }
+        };
+
+        /// <summary>
+        /// 检查 Unity Test Runner 相关类型是否可用；当前不做深度枚举，返回稳定诊断字段。
+    /// </summary>
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var testRunnerType = FindType("UnityEditor.TestTools.TestRunner.TestRunnerWindow")
+                ?? FindType("UnityEditor.TestRunner.TestRunnerWindow");
+            var editorTestType = FindType("NUnit.Framework.TestAttribute");
+
+            if (testRunnerType == null && editorTestType == null)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Available = false,
+                    Tests = new TestInfo[0],
+                    Count = 0,
+                    Diagnostics = "Unity Test Framework is not installed or not available. Test enumeration requires the Test Runner package.",
+                    NextActions = new[]
+                    {
+                        "Install the Unity Test Framework package via Package Manager.",
+                        "Enable the Test Runner window: Window > General > Test Runner."
+                    }
+                });
+            }
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Available = true,
+                Tests = new TestInfo[0],
+                Count = 0,
+                Diagnostics = "Test enumeration via reflection is not reliably available. Use the Unity Test Runner window for full test discovery, or run tests via the CLI test runner tool.",
+                NextActions = null
+            });
+        }
+
+        // 在当前 AppDomain 中查找 Unity/NUnit 类型；找不到时返回 null 并输出可恢复诊断。
+        private static Type FindType(string fullName)
+        {
+            var type = Type.GetType(fullName);
+            if (type != null) return type;
+            foreach (var assembly in AppDomain.CurrentDomain.GetAssemblies())
+            {
+                try
+                {
+                    type = assembly.GetType(fullName);
+                    if (type != null) return type;
+                }
+                catch
+                {
+                    // 忽略无法反射的编辑器程序集，继续查找其它程序集。
+                }
+            }
+            return null;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/texture/TextureToolSupport.cs

@@ -0,0 +1,327 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// texture 域 IUnityCliTool 共享的基础设施 helper:纹理路径校验、纹理资产/importer 加载、
+    /// 导入设置应用、颜色解析、sprite 切片构造。仅供 texture 域自包含工具复用;
+    /// 不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    public static class TextureToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求,避免脏状态写入。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            SceneToolSupport.EnsureEditorNotBusy(command);
+        }
+
+        // 校验并返回 Assets/ 纹理路径;空或扩展名不支持抛 BridgeCommandException。
+        public static string RequireTexturePath(string rawPath)
+        {
+            var path = AssetToolSupport.NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_PATH_REQUIRED", "Pass a texture path under Assets/.", "Use tools run asset.search --input '{\"filter\":\"t:Texture2D\"}' to discover the path, or pass an Assets/*.png path.");
+            }
+            if (!path.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase) || !IsTextureExtension(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_PATH_INVALID", "Texture path must be under Assets/ and use a supported texture extension: " + path, "Use .png, .jpg, .jpeg, .tga, .psd or .exr under Assets/.");
+            }
+            return path;
+        }
+
+        /// <summary>校验纹理路径并要求资产已存在。</summary>
+        public static string ResolveTexturePath(string rawPath)
+        {
+            var path = RequireTexturePath(rawPath);
+            if (!AssetToolSupport.AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_NOT_FOUND", "Texture asset not found: " + path, "Check the path or run tools run asset.search --input '{\"filter\":\"t:Texture2D\"}' to discover the path.");
+            }
+            return path;
+        }
+
+        /// <summary>加载 Texture2D 资产;不存在或导入失败抛 BridgeCommandException。</summary>
+        public static Texture2D LoadTextureAsset(string path)
+        {
+            var texture = AssetDatabase.LoadAssetAtPath<Texture2D>(path);
+            if (texture == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_NOT_FOUND", "Texture asset not found or failed to import: " + path, "Check importer diagnostics in Unity Console and UnityCliBridge.log.");
+            }
+            return texture;
+        }
+
+        /// <summary>获取 TextureImporter;不存在抛 BridgeCommandException。</summary>
+        public static TextureImporter RequireTextureImporter(string path)
+        {
+            var importer = AssetImporter.GetAtPath(path) as TextureImporter;
+            if (importer == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_IMPORTER_NOT_FOUND", "TextureImporter not found for: " + path, "Reimport the asset or verify it is a texture file.");
+            }
+            return importer;
+        }
+
+        /// <summary>判断路径是否为支持的纹理扩展名。</summary>
+        public static bool IsTextureExtension(string path)
+        {
+            var extension = Path.GetExtension(path).ToLowerInvariant();
+            return extension == ".png" || extension == ".jpg" || extension == ".jpeg" || extension == ".tga" || extension == ".psd" || extension == ".exr";
+        }
+
+        /// <summary>构造纹理资产摘要(path/guid/name/width/height/format/sizeBytes)。</summary>
+        public static TextureInfo BuildTextureInfo(string path, Texture2D texture)
+        {
+            var fileInfo = new FileInfo(AssetToolSupport.AssetFullPath(path));
+            return new TextureInfo
+            {
+                Path = path,
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                Name = texture == null ? Path.GetFileNameWithoutExtension(path) : texture.name,
+                Width = texture == null ? 0 : texture.width,
+                Height = texture == null ? 0 : texture.height,
+                Format = texture == null ? null : texture.format.ToString(),
+                SizeBytes = fileInfo.Exists ? fileInfo.Length : 0L
+            };
+        }
+
+        /// <summary>构造 TextureImporter 设置摘要。</summary>
+        public static TextureImportSettings BuildTextureImportSettings(TextureImporter importer)
+        {
+            return new TextureImportSettings
+            {
+                TextureType = importer.textureType.ToString(),
+                SpriteImportMode = importer.spriteImportMode.ToString(),
+                PixelsPerUnit = importer.spritePixelsPerUnit,
+                Pivot = new TexturePivot { X = importer.spritePivot.x, Y = importer.spritePivot.y },
+                Readable = importer.isReadable,
+                Mipmap = importer.mipmapEnabled,
+                SRGB = importer.sRGBTexture,
+                AlphaIsTransparency = importer.alphaIsTransparency,
+                WrapMode = importer.wrapMode.ToString(),
+                FilterMode = importer.filterMode.ToString(),
+                MaxTextureSize = importer.maxTextureSize,
+                Compression = importer.textureCompression.ToString()
+            };
+        }
+
+        /// <summary>应用纹理导入设置(可选字段为 null 时跳过);返回是否有变更。saveAndReimport=true 时保存并刷新。</summary>
+        public static bool ApplyTextureSettings(TextureImporter importer, TextureSettings f, bool saveAndReimport)
+        {
+            var changed = false;
+            if (!string.IsNullOrEmpty(f.TextureType))
+            {
+                var normalized = string.Equals(f.TextureType, "sprite", StringComparison.OrdinalIgnoreCase) ? "Sprite" : f.TextureType;
+                var next = (TextureImporterType)Enum.Parse(typeof(TextureImporterType), normalized, true);
+                if (importer.textureType != next)
+                {
+                    importer.textureType = next;
+                    changed = true;
+                }
+            }
+            changed = ApplyBool(f.Readable, importer.isReadable, v => importer.isReadable = v) || changed;
+            changed = ApplyBool(f.Mipmap, importer.mipmapEnabled, v => importer.mipmapEnabled = v) || changed;
+            changed = ApplyBool(f.SRGB, importer.sRGBTexture, v => importer.sRGBTexture = v) || changed;
+            changed = ApplyBool(f.AlphaIsTransparency, importer.alphaIsTransparency, v => importer.alphaIsTransparency = v) || changed;
+            changed = ApplyEnum(f.WrapMode, importer.wrapMode.ToString(), v => importer.wrapMode = (TextureWrapMode)Enum.Parse(typeof(TextureWrapMode), v, true)) || changed;
+            changed = ApplyEnum(f.FilterMode, importer.filterMode.ToString(), v => importer.filterMode = (FilterMode)Enum.Parse(typeof(FilterMode), v, true)) || changed;
+            changed = ApplyEnum(f.Compression, importer.textureCompression.ToString(), v => importer.textureCompression = (TextureImporterCompression)Enum.Parse(typeof(TextureImporterCompression), v, true)) || changed;
+            if (f.MaxTextureSize.HasValue && f.MaxTextureSize.Value > 0 && importer.maxTextureSize != f.MaxTextureSize.Value)
+            {
+                importer.maxTextureSize = f.MaxTextureSize.Value;
+                changed = true;
+            }
+            if (saveAndReimport && changed)
+            {
+                importer.SaveAndReimport();
+                AssetDatabase.Refresh();
+            }
+            return changed;
+        }
+
+        public static void ValidateTextureSettings(TextureSettings settings)
+        {
+            if (settings == null) return;
+            ValidateEnum<TextureImporterType>(settings.TextureType, "TextureType", "sprite", "Sprite");
+            ValidateEnum<TextureWrapMode>(settings.WrapMode, "WrapMode");
+            ValidateEnum<FilterMode>(settings.FilterMode, "FilterMode");
+            ValidateEnum<TextureImporterCompression>(settings.Compression, "Compression");
+            if (settings.MaxTextureSize.HasValue && settings.MaxTextureSize.Value <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_RANGE_INVALID", "MaxTextureSize must be positive.", "Pass a positive maxTextureSize.");
+        }
+
+        public static void ValidateSpriteRequest(string mode, int? pixelsPerUnit, double? pivotX, double? pivotY, List<TextureSliceInput> slices)
+        {
+            if (!string.IsNullOrEmpty(mode) && !string.Equals(mode, "single", StringComparison.OrdinalIgnoreCase) && !string.Equals(mode, "multiple", StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_SPRITE_MODE_INVALID", "SpriteMode must be single or multiple.", "Pass spriteMode=single or spriteMode=multiple.");
+            if (pixelsPerUnit.HasValue && pixelsPerUnit.Value <= 0) throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_RANGE_INVALID", "PixelsPerUnit must be positive.", "Pass a positive pixelsPerUnit.");
+            ValidateFiniteUnit(pivotX, "PivotX"); ValidateFiniteUnit(pivotY, "PivotY");
+            if (slices != null) foreach (var slice in slices)
+            {
+                if (slice == null || !IsFinite(slice.X) || !IsFinite(slice.Y) || !IsFinite(slice.Width) || !IsFinite(slice.Height) || slice.Width <= 0 || slice.Height <= 0)
+                    throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_SPRITE_SLICE_INVALID", "Sprite slice coordinates must be finite and width/height positive.", "Pass finite x/y/width/height values.");
+                ValidateFiniteUnit(slice.PivotX, "slice pivotX"); ValidateFiniteUnit(slice.PivotY, "slice pivotY");
+            }
+        }
+
+        private static void ValidateEnum<T>(string value, string field, params string[] aliases) where T : struct
+        {
+            if (string.IsNullOrEmpty(value)) return;
+            foreach (var alias in aliases) if (string.Equals(value, alias, StringComparison.OrdinalIgnoreCase)) return;
+            if (!Enum.GetNames(typeof(T)).Any(name => string.Equals(name, value, StringComparison.OrdinalIgnoreCase)))
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_ENUM_INVALID", field + " has an invalid enum value: " + value, "Pass a documented " + field + " value.");
+        }
+
+        private static bool IsFinite(float value) { return !float.IsNaN(value) && !float.IsInfinity(value); }
+        private static void ValidateFiniteUnit(double? value, string field)
+        {
+            if (!value.HasValue) return;
+            if (double.IsNaN(value.Value) || double.IsInfinity(value.Value) || value.Value < 0d || value.Value > 1d)
+                throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_RANGE_INVALID", field + " must be finite and in [0, 1].", "Pass a value from 0 through 1.");
+        }
+
+        private static bool ApplyBool(bool? next, bool current, Action<bool> setter)
+        {
+            if (!next.HasValue || current == next.Value) return false;
+            setter(next.Value);
+            return true;
+        }
+
+        private static bool ApplyEnum(string next, string current, Action<string> setter)
+        {
+            if (string.IsNullOrEmpty(next) || string.Equals(next, current, StringComparison.OrdinalIgnoreCase)) return false;
+            setter(next);
+            return true;
+        }
+
+        /// <summary>解析纹理颜色(十六进制 RGB/RGBA,可带 #);空返回白色。</summary>
+        public static Color ParseTextureColor(string rawColor)
+        {
+            if (string.IsNullOrEmpty(rawColor)) return Color.white;
+            Color color;
+            if (ColorUtility.TryParseHtmlString(rawColor.StartsWith("#", StringComparison.Ordinal) ? rawColor : "#" + rawColor, out color))
+            {
+                return color;
+            }
+            throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_COLOR_INVALID", "Texture color must be a hex RGB/RGBA value: " + rawColor, "Use values like --color ffffff or --color #ff00ffff.");
+        }
+
+        /// <summary>把结构化 sprite 切片输入转换为 SpriteMetaData 数组。</summary>
+        public static void ValidateSpriteSliceBounds(SpriteMetaData[] slices, int textureWidth, int textureHeight)
+        {
+            foreach (var slice in slices)
+                if (slice.rect.x < 0f || slice.rect.y < 0f || slice.rect.xMax > textureWidth || slice.rect.yMax > textureHeight)
+                    throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_SPRITE_SLICE_INVALID", "Sprite slice is outside texture bounds: " + slice.name, "Pass slice coordinates within the texture dimensions.");
+        }
+
+        public static SpriteMetaData[] BuildSpriteSlices(List<TextureSliceInput> slices)
+        {
+            if (slices == null || slices.Count == 0) return new SpriteMetaData[0];
+            var result = new List<SpriteMetaData>();
+            for (var i = 0; i < slices.Count; i++)
+            {
+                var item = slices[i];
+                if (item == null || item.Width <= 0 || item.Height <= 0)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_TEXTURE_SPRITE_SLICE_INVALID", "Sprite slice width and height must be positive.", "Pass slices with name,x,y,width,height and optional pivotX/pivotY.");
+                }
+                result.Add(new SpriteMetaData
+                {
+                    name = string.IsNullOrEmpty(item.Name) ? "slice_" + i.ToString(CultureInfo.InvariantCulture) : item.Name,
+                    rect = new Rect(item.X, item.Y, item.Width, item.Height),
+                    pivot = new Vector2(Mathf.Clamp01(item.PivotX), Mathf.Clamp01(item.PivotY)),
+                    alignment = (int)SpriteAlignment.Custom
+                });
+            }
+            return result.ToArray();
+        }
+    }
+
+    // ─── texture 域共享 DTO ───────────────────────────────────────────────
+
+    public sealed class TextureInfo
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Name { get; set; }
+        public long Width { get; set; }
+        public long Height { get; set; }
+        public string Format { get; set; }
+        public long SizeBytes { get; set; }
+    }
+
+    public sealed class TextureImportSettings
+    {
+        public string TextureType { get; set; }
+        public string SpriteImportMode { get; set; }
+        public double PixelsPerUnit { get; set; }
+        public TexturePivot Pivot { get; set; }
+        public bool Readable { get; set; }
+        public bool Mipmap { get; set; }
+        public bool SRGB { get; set; }
+        public bool AlphaIsTransparency { get; set; }
+        public string WrapMode { get; set; }
+        public string FilterMode { get; set; }
+        public long MaxTextureSize { get; set; }
+        public string Compression { get; set; }
+    }
+
+    public sealed class TexturePivot
+    {
+        public double X { get; set; }
+        public double Y { get; set; }
+    }
+
+    /// <summary>导入设置可选字段集合(均为 nullable,未提供则跳过)。</summary>
+    public sealed class TextureSettings
+    {
+        public string TextureType { get; set; }
+        public bool? Readable { get; set; }
+        public bool? Mipmap { get; set; }
+        public bool? SRGB { get; set; }
+        public bool? AlphaIsTransparency { get; set; }
+        public string WrapMode { get; set; }
+        public string FilterMode { get; set; }
+        public string Compression { get; set; }
+        public int? MaxTextureSize { get; set; }
+    }
+
+    /// <summary>sprite 切片输入(由 Request 反序列化)。</summary>
+    public sealed class TextureSliceInput
+    {
+        public string Name { get; set; }
+        public float X { get; set; }
+        public float Y { get; set; }
+        public float Width { get; set; }
+        public float Height { get; set; }
+        public float PivotX { get; set; } = 0.5f;
+        public float PivotY { get; set; } = 0.5f;
+    }
+
+    /// <summary>sprite 切片输出摘要。</summary>
+    public sealed class TextureSliceOutput
+    {
+        public string Name { get; set; }
+        public float X { get; set; }
+        public float Y { get; set; }
+        public float Width { get; set; }
+        public float Height { get; set; }
+    }
+
+    /// <summary>计划副作用项,texture 域 mutation 工具 Result 共享。</summary>
+    public sealed class TexturePlannedEffect
+    {
+        public string Type { get; set; }
+        public string Path { get; set; }
+        public bool Refresh { get; set; }
+    }
+}
+#endif