@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,326 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader 域 IUnityCliTool 共享的基础设施 helper:Shader 路径校验、Shader 资产加载、
+    /// 诊断/属性/SubShader 反射读取、默认 Shader 内容生成。仅供 shader 域自包含工具复用;
+    /// 不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    public static class ShaderToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求,避免脏状态写入。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            SceneToolSupport.EnsureEditorNotBusy(command);
+        }
+
+        // 校验并返回 Assets/*.shader 或 *.shadergraph 路径;空或格式不符抛 BridgeCommandException。
+        public static string RequireShaderPath(string rawPath)
+        {
+            var path = AssetToolSupport.NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_PATH_REQUIRED", "Pass an Assets/*.shader or Assets/*.shadergraph path.", "Use tools run shader.list --input '{\"keyword\":\"<keyword>\"}' to discover the path, or pass an Assets/*.shader path.");
+            }
+            if (!path.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase)
+                || (!path.EndsWith(".shader", StringComparison.OrdinalIgnoreCase) && !path.EndsWith(".shadergraph", StringComparison.OrdinalIgnoreCase)))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_PATH_INVALID", "Shader path must be under Assets/ and end with .shader or .shadergraph: " + path, "Pass a Unity asset path such as Assets/Shaders/Example.shader.");
+            }
+            return path;
+        }
+
+        /// <summary>校验 Shader 路径并要求资产已存在。</summary>
+        public static string ResolveShaderPath(string rawPath)
+        {
+            var path = RequireShaderPath(rawPath);
+            if (!AssetToolSupport.AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_NOT_FOUND", "Shader asset not found: " + path, "Check the path or run tools run asset.search --input '{\"filter\":\"t:Shader\"}' to discover the path.");
+            }
+            return path;
+        }
+
+        /// <summary>加载 Shader 资产(任意类型);不存在抛 BridgeCommandException。</summary>
+        public static UnityEngine.Object LoadShaderLikeAsset(string path)
+        {
+            var asset = AssetDatabase.LoadAssetAtPath<UnityEngine.Object>(path);
+            if (asset == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_NOT_FOUND", "Shader asset not found: " + path, "Check the path or run tools run asset.search --input '{\"filter\":\"t:Shader\"}' to discover the path.");
+            }
+            return asset;
+        }
+
+        /// <summary>构造 Shader 资产摘要(含诊断)。</summary>
+        public static ShaderInfo BuildShaderInfo(string path, Shader shader, bool includeContentMetadata)
+        {
+            var fullPath = AssetToolSupport.AssetFullPath(path);
+            var fileInfo = new FileInfo(fullPath);
+            var asset = AssetDatabase.LoadAssetAtPath<UnityEngine.Object>(path);
+            return new ShaderInfo
+            {
+                Path = path,
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                Name = shader != null ? shader.name : (asset != null ? asset.name : Path.GetFileNameWithoutExtension(path)),
+                AssetType = asset == null ? null : asset.GetType().Name,
+                IsShaderGraph = path.EndsWith(".shadergraph", StringComparison.OrdinalIgnoreCase),
+                Exists = fileInfo.Exists,
+                SizeBytes = fileInfo.Exists ? fileInfo.Length : 0L,
+                Encoding = includeContentMetadata ? "utf-8" : null,
+                Diagnostics = BuildDiagnostics(shader)
+            };
+        }
+
+        /// <summary>构造 Shader 编译诊断(含消息明细)。</summary>
+        public static ShaderDiagnostics BuildDiagnostics(Shader shader)
+        {
+            if (shader == null)
+            {
+                return new ShaderDiagnostics { Supported = null, MessageCount = 0, Messages = new List<ShaderMessage>() };
+            }
+            var messages = ReadShaderMessages(shader);
+            return new ShaderDiagnostics
+            {
+                Supported = shader.isSupported,
+                MessageCount = messages.Count,
+                Messages = messages
+            };
+        }
+
+        /// <summary>构造诊断摘要(不含消息明细)。</summary>
+        public static ShaderDiagnostics BuildDiagnosticsSummary(Shader shader)
+        {
+            if (shader == null)
+            {
+                return new ShaderDiagnostics { Supported = null, MessageCount = 0, Messages = new List<ShaderMessage>() };
+            }
+            var count = ReadShaderMessages(shader).Count;
+            return new ShaderDiagnostics { Supported = shader.isSupported, MessageCount = count, Messages = new List<ShaderMessage>() };
+        }
+
+        // ─── Shader 反射读取(SubShader/Pass 结构;Unity 版本不支持时返回空) ──
+
+        /// <summary>读取 SubShader/Pass 结构 DTO 列表。</summary>
+        public static List<ShaderSubshader> BuildSubshaders(Shader shader, bool includeSourceCode, int maxSubshaders, int maxPasses)
+        {
+            var result = new List<ShaderSubshader>();
+            var shaderData = ShaderDataObject(shader);
+            if (shaderData == null) return result;
+            var subshaderCount = Math.Min(ReflectionInt(shaderData, "SubshaderCount"), maxSubshaders);
+            for (var s = 0; s < subshaderCount; s++)
+            {
+                var subshader = ReflectionInvoke(shaderData, "GetSubshader", s);
+                if (subshader == null) continue;
+                var passCountTotal = ReflectionInt(subshader, "PassCount");
+                var passCount = Math.Min(passCountTotal, maxPasses);
+                var passes = new List<ShaderPass>();
+                for (var p = 0; p < passCount; p++)
+                {
+                    var pass = ReflectionInvoke(subshader, "GetPass", p);
+                    var passInfo = new ShaderPass { Index = p };
+                    if (pass != null)
+                    {
+                        passInfo.Name = ReflectionValue(pass.GetType(), pass, "Name");
+                        if (includeSourceCode) passInfo.SourceCode = ReflectionValue(pass.GetType(), pass, "SourceCode");
+                    }
+                    passes.Add(passInfo);
+                }
+                result.Add(new ShaderSubshader { Index = s, PassCount = passCountTotal, Passes = passes });
+            }
+            return result;
+        }
+
+        /// <summary>判断 ShaderData 反射对象是否可用。</summary>
+        public static bool SubshaderDataAvailable(Shader shader)
+        {
+            return ShaderDataObject(shader) != null;
+        }
+
+        private static List<ShaderMessage> ReadShaderMessages(Shader shader)
+        {
+            var items = new List<ShaderMessage>();
+            var getMessages = ShaderMessagesMethod();
+            if (getMessages == null) return items;
+            var messages = getMessages.Invoke(null, new object[] { shader }) as Array;
+            if (messages == null) return items;
+            foreach (var message in messages)
+            {
+                var type = message.GetType();
+                items.Add(new ShaderMessage
+                {
+                    Severity = ReflectionValue(type, message, "severity"),
+                    Message = ReflectionValue(type, message, "message"),
+                    File = ReflectionValue(type, message, "file"),
+                    Line = ReflectionValue(type, message, "line"),
+                    Platform = ReflectionValue(type, message, "platform")
+                });
+            }
+            return items;
+        }
+
+        private static object ShaderDataObject(Shader shader)
+        {
+            var shaderUtil = Type.GetType("UnityEditor.ShaderUtil,UnityEditor");
+            if (shaderUtil == null) return null;
+            foreach (var method in shaderUtil.GetMethods(BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic))
+            {
+                if (method.Name != "GetShaderData") continue;
+                var parameters = method.GetParameters();
+                if (parameters.Length == 1 && parameters[0].ParameterType == typeof(Shader))
+                {
+                    return method.Invoke(null, new object[] { shader });
+                }
+            }
+            return null;
+        }
+
+        private static MethodInfo ShaderMessagesMethod()
+        {
+            var shaderUtil = Type.GetType("UnityEditor.ShaderUtil,UnityEditor");
+            if (shaderUtil == null) return null;
+            foreach (var method in shaderUtil.GetMethods(BindingFlags.Static | BindingFlags.Public | BindingFlags.NonPublic))
+            {
+                if (method.Name != "GetShaderMessages") continue;
+                var parameters = method.GetParameters();
+                if (parameters.Length == 1 && parameters[0].ParameterType == typeof(Shader)) return method;
+            }
+            return null;
+        }
+
+        private static object ReflectionInvoke(object target, string name, int index)
+        {
+            if (target == null) return null;
+            var method = target.GetType().GetMethod(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
+            return method == null ? null : method.Invoke(target, new object[] { index });
+        }
+
+        private static int ReflectionInt(object target, string name)
+        {
+            if (target == null) return 0;
+            var type = target.GetType();
+            var property = type.GetProperty(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
+            if (property != null)
+            {
+                var value = property.GetValue(target, null);
+                if (value is int) return (int)value;
+            }
+            var field = type.GetField(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
+            if (field != null)
+            {
+                var value = field.GetValue(target);
+                if (value is int) return (int)value;
+            }
+            return 0;
+        }
+
+        private static string ReflectionValue(Type type, object target, string name)
+        {
+            var field = type.GetField(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
+            if (field != null)
+            {
+                var value = field.GetValue(target);
+                return value == null ? null : value.ToString();
+            }
+            var property = type.GetProperty(name, BindingFlags.Instance | BindingFlags.Public | BindingFlags.NonPublic);
+            if (property != null)
+            {
+                var value = property.GetValue(target, null);
+                return value == null ? null : value.ToString();
+            }
+            return null;
+        }
+
+        /// <summary>生成默认的简单 unlit Shader 内容。</summary>
+        public static string DefaultShaderContent(string rawName, string path)
+        {
+            var name = string.IsNullOrEmpty(rawName) ? Path.GetFileNameWithoutExtension(path) : rawName;
+            return "Shader \"UnityCli/" + EscapeShaderName(name) + "\" {\n    Properties {\n        _Color (\"Color\", Color) = (1,1,1,1)\n    }\n    SubShader {\n        Tags { \"RenderType\"=\"Opaque\" }\n        Pass {\n            CGPROGRAM\n            #include \"UnityCG.cginc\"\n            #pragma vertex vert\n            #pragma fragment frag\n            struct appdata { float4 vertex : POSITION; };\n            struct v2f { float4 vertex : SV_POSITION; };\n            fixed4 _Color;\n            v2f vert (appdata v) { v2f o; o.vertex = UnityObjectToClipPos(v.vertex); return o; }\n            fixed4 frag (v2f i) : SV_Target { return _Color; }\n            ENDCG\n        }\n    }\n}\n";
+        }
+
+        private static string EscapeShaderName(string name)
+        {
+            return (name ?? "Shader").Replace("\\", "/").Replace("\"", "");
+        }
+    }
+
+    // ─── shader 域共享 DTO ────────────────────────────────────────────────
+
+    public sealed class ShaderInfo
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Name { get; set; }
+        public string AssetType { get; set; }
+        public bool IsShaderGraph { get; set; }
+        public bool Exists { get; set; }
+        public long SizeBytes { get; set; }
+        public string Encoding { get; set; }
+        public ShaderDiagnostics Diagnostics { get; set; }
+    }
+
+    public sealed class ShaderDiagnostics
+    {
+        public bool? Supported { get; set; }
+        public long MessageCount { get; set; }
+        public List<ShaderMessage> Messages { get; set; }
+    }
+
+    public sealed class ShaderMessage
+    {
+        public string Severity { get; set; }
+        public string Message { get; set; }
+        public string File { get; set; }
+        public string Line { get; set; }
+        public string Platform { get; set; }
+    }
+
+    public sealed class ShaderProperty
+    {
+        public string Name { get; set; }
+        public string Description { get; set; }
+        public string Type { get; set; }
+        public string Flags { get; set; }
+        public long NameId { get; set; }
+        public ShaderPropertyRange Range { get; set; }
+        public string DefaultTextureName { get; set; }
+        public List<string> Attributes { get; set; }
+    }
+
+    public sealed class ShaderPropertyRange
+    {
+        public double Min { get; set; }
+        public double Max { get; set; }
+    }
+
+    public sealed class ShaderSubshader
+    {
+        public long Index { get; set; }
+        public long PassCount { get; set; }
+        public List<ShaderPass> Passes { get; set; }
+    }
+
+    public sealed class ShaderPass
+    {
+        public long Index { get; set; }
+        public string Name { get; set; }
+        public string SourceCode { get; set; }
+    }
+
+    /// <summary>计划副作用项,shader 域 mutation 工具 Result 共享。</summary>
+    public sealed class ShaderPlannedEffect
+    {
+        public string Type { get; set; }
+        public string Path { get; set; }
+        public bool Refresh { get; set; }
+    }
+}
+#endif

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

@@ -0,0 +1,82 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.create — 创建 Shader 资产(.shader/.shadergraph)。拒绝覆盖(除非 overwrite)。
+    /// </summary>
+    public class ShaderCreateTool : IUnityCliTool<ShaderCreateTool.Request, ShaderCreateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Content { get; set; }
+            public string Name { get; set; }
+            public bool? Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ShaderInfo Shader { get; set; }
+            public List<ShaderPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.create",
+            Summary = "Create a new Assets/*.shader (or .shadergraph) asset from source content or a default unlit template.",
+            Description = "Create a new Shader asset at an Assets/*.shader path. With no content, a default unlit UnityCli/ shader is generated. For .shadergraph, content is required (pass a ShaderGraph JSON payload). Refuses to overwrite an existing shader unless overwrite=true. Creating a shader triggers recompilation.",
+            Group = "shader",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write", "shader-recompile" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a default shader", Input = new Request { Path = "Assets/Shaders/New.shader" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ShaderToolSupport.EnsureEditorNotBusy("shader.create");
+            var path = ShaderToolSupport.RequireShaderPath(request.Path);
+            var overwrite = request.Overwrite ?? false;
+            if (AssetToolSupport.AssetExists(path) && !overwrite)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_OUTPUT_EXISTS", "Shader output already exists: " + path, "Pass --overwrite or choose a different Assets/*.shader path.");
+            }
+
+            var content = request.Content;
+            if (string.IsNullOrEmpty(content))
+            {
+                if (path.EndsWith(".shadergraph", StringComparison.OrdinalIgnoreCase))
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_SHADER_CONTENT_REQUIRED", "ShaderGraph creation requires content or content-file.", "Pass a ShaderGraph JSON payload via --content-file.");
+                }
+                content = ShaderToolSupport.DefaultShaderContent(request.Name, path);
+            }
+
+            ctx.CommitEffect();
+            AssetToolSupport.WriteTextAsset(path, content, overwrite);
+            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_CREATE_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.create", Path = path, Refresh = true } }
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,90 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.delete — 删除 Shader 资产。destructive,支持 dryRun。
+    /// </summary>
+    public class ShaderDeleteTool : IUnityCliTool<ShaderDeleteTool.Request, ShaderDeleteTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool? DryRun { get; set; }
+            public ShaderInfo Shader { get; set; }
+            public List<ShaderPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.delete",
+            Summary = "Delete an Assets/*.shader or *.shadergraph asset; destructive, supports --dry-run preview.",
+            Description = "Delete an Assets/*.shader or *.shadergraph asset through AssetDatabase. Destructive: removes a persisted shader and may break materials referencing it. Supports --dry-run to preview the planned deletion without removing anything.",
+            Group = "shader",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-delete" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Preview deleting a shader", Input = new Request { Path = "Assets/Shaders/Old.shader" }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ShaderToolSupport.EnsureEditorNotBusy("shader.delete");
+            var path = ShaderToolSupport.ResolveShaderPath(request.Path ?? request.Target);
+            if (ctx.DryRun)
+            {
+                return new Result
+                {
+                    DryRun = true,
+                    Shader = ShaderToolSupport.BuildShaderInfo(path, AssetDatabase.LoadAssetAtPath<Shader>(path), false),
+                    PlannedEffects = new List<ShaderPlannedEffect> { new ShaderPlannedEffect { Type = "shader.delete", Path = path } }
+                };
+            }
+            ctx.CommitEffect();
+            if (!AssetDatabase.DeleteAsset(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_DELETE_FAILED", "Failed to delete shader asset: " + path, "Check Unity Console and file permissions.");
+            }
+            AssetDatabase.Refresh();
+            var fullPath = AssetToolSupport.AssetFullPath(path);
+            var deleted = await ctx.Wait.Until(
+                () => !File.Exists(fullPath)
+                    && !Directory.Exists(fullPath)
+                    && !AssetDatabase.IsValidFolder(path)
+                    && AssetDatabase.LoadMainAssetAtPath(path) == null,
+                TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)),
+                ct);
+            var observedExists = File.Exists(fullPath)
+                || Directory.Exists(fullPath)
+                || AssetDatabase.IsValidFolder(path)
+                || AssetDatabase.LoadMainAssetAtPath(path) != null;
+            if (!deleted || observedExists)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_DELETE_PROOF_MISSING", "Shader deletion was not observed in the file system and AssetDatabase: " + path, "Inspect Unity Console and file permissions before retrying.");
+            }
+            return new Result
+            {
+                Shader = new ShaderInfo { Path = path, Exists = observedExists },
+                PlannedEffects = new List<ShaderPlannedEffect> { new ShaderPlannedEffect { Type = "shader.delete", Path = path } }
+            };
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,125 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.Rendering;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.get-data — 读取 Shader 属性/subshaders/passes/编译消息。可按 path 或 name(Shader.Find)解析。
+    /// </summary>
+    public class ShaderGetDataTool : IUnityCliTool<ShaderGetDataTool.Request, ShaderGetDataTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string AssetPath { get; set; }
+            public string Name { get; set; }
+            public bool? IncludeMessages { get; set; }
+            public bool? IncludeProperties { get; set; }
+            public bool? IncludeSubshaders { get; set; }
+            public bool? IncludeSourceCode { get; set; }
+            public int? MaxSubshaders { get; set; }
+            public int? MaxPasses { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long RenderQueue { get; set; }
+            public bool IsSupported { get; set; }
+            public long PassCount { get; set; }
+            public long PropertyCount { get; set; }
+            public ShaderDiagnostics Diagnostics { get; set; }
+            public List<ShaderProperty> Properties { get; set; }
+            public bool SubshaderDataAvailable { get; set; }
+            public List<ShaderSubshader> Subshaders { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.get-data",
+            Summary = "Read shader properties, subshaders/passes and compile diagnostics; resolve by path or Shader.Find name.",
+            Description = "Read structured shader data: render queue, supported flag, pass count, properties (with type/flags/range/attributes), subshader/pass structure via ShaderUtil reflection, and compile diagnostics. Resolve by path/assetPath or by name (Shader.Find). includeSourceCode is opt-in (default false). Keep maxSubshaders/maxPasses bounded.",
+            Group = "shader",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read shader properties", Input = new Request { Path = "Assets/Shaders/Example.shader", IncludeProperties = true } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = request.Path ?? request.AssetPath;
+            Shader shader;
+            if (!string.IsNullOrEmpty(path))
+            {
+                shader = AssetDatabase.LoadMainAssetAtPath(path) as Shader;
+            }
+            else
+            {
+                shader = Shader.Find(request.Name);
+            }
+            if (shader == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SHADER_NOT_FOUND", "Shader not found.", "Run tools run shader.list --input '{\"keyword\":\"<keyword>\"}' to discover shader paths.");
+            }
+            var includeMessages = request.IncludeMessages ?? true;
+            var includeProperties = request.IncludeProperties ?? true;
+            var includeSubshaders = (request.IncludeSubshaders ?? true) || (request.IncludeSourceCode ?? false);
+            var includeSourceCode = request.IncludeSourceCode ?? false;
+            var maxSubshaders = Math.Max(0, Math.Min(request.MaxSubshaders ?? 8, 64));
+            var maxPasses = Math.Max(0, Math.Min(request.MaxPasses ?? 16, 128));
+
+            var properties = new List<ShaderProperty>();
+            if (includeProperties)
+            {
+                for (var i = 0; i < shader.GetPropertyCount(); i++)
+                {
+                    var propType = shader.GetPropertyType(i);
+                    var prop = new ShaderProperty
+                    {
+                        Name = shader.GetPropertyName(i),
+                        Description = shader.GetPropertyDescription(i),
+                        Type = propType.ToString(),
+                        Flags = shader.GetPropertyFlags(i).ToString(),
+                        NameId = shader.GetPropertyNameId(i),
+                        DefaultTextureName = propType == UnityEngine.Rendering.ShaderPropertyType.Texture ? shader.GetPropertyTextureDefaultName(i) : null,
+                        Attributes = new List<string>(shader.GetPropertyAttributes(i))
+                    };
+                    if (propType == UnityEngine.Rendering.ShaderPropertyType.Range)
+                    {
+                        var range = shader.GetPropertyRangeLimits(i);
+                        prop.Range = new ShaderPropertyRange { Min = range.x, Max = range.y };
+                    }
+                    properties.Add(prop);
+                }
+            }
+
+            var subshaders = includeSubshaders
+                ? ShaderToolSupport.BuildSubshaders(shader, includeSourceCode, maxSubshaders, maxPasses)
+                : new List<ShaderSubshader>();
+
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                RenderQueue = shader.renderQueue,
+                IsSupported = shader.isSupported,
+                PassCount = shader.passCount,
+                PropertyCount = shader.GetPropertyCount(),
+                Diagnostics = includeMessages
+                    ? ShaderToolSupport.BuildDiagnostics(shader)
+                    : ShaderToolSupport.BuildDiagnosticsSummary(shader),
+                Properties = properties,
+                SubshaderDataAvailable = ShaderToolSupport.SubshaderDataAvailable(shader),
+                Subshaders = subshaders
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,48 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// shader.info — 读取 Shader 资产摘要(含编译诊断)。
+    /// </summary>
+    public class ShaderInfoTool : IUnityCliTool<ShaderInfoTool.Request, ShaderInfoTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ShaderInfo Shader { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "shader.info",
+            Summary = "Return path, guid, name, asset type, size and compile diagnostics for an Assets/*.shader or *.shadergraph.",
+            Description = "Return path, guid, name, asset type, ShaderGraph flag, byte size and compile diagnostics for an Assets/*.shader or *.shadergraph. Read-only; use shader.read for source text and shader.get-data for properties/subshader structure.",
+            Group = "shader",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Inspect a shader", Input = new Request { Path = "Assets/Shaders/Example.shader" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = ShaderToolSupport.ResolveShaderPath(request.Path ?? request.Target);
+            var shader = ShaderToolSupport.LoadShaderLikeAsset(path) as Shader;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Shader = ShaderToolSupport.BuildShaderInfo(path, shader, false) });
+        }
+    }
+}
+#endif