@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/asset/AssetToolSupport.cs

@@ -0,0 +1,253 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Text;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset 域 IUnityCliTool 共享的基础设施 helper:资产路径规范化、资产存在判断、
+    /// 资产目录创建、文本资产写入、资产信息构造、忙状态拦截。仅供 asset 域自包含工具复用;
+    /// 不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    public static class AssetToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求,避免脏状态写入。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            SceneToolSupport.EnsureEditorNotBusy(command);
+        }
+
+        // 资产路径规范化:反斜杠转正斜杠并去首尾空白;空返回 null。
+        public static string NormalizeAssetPath(string rawPath)
+        {
+            if (string.IsNullOrWhiteSpace(rawPath)) return null;
+            var path = rawPath.Replace('\\', '/').Trim();
+            if (path.Split('/').Any(segment => segment == "." || segment == ".."))
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_PATH_INVALID", "Asset paths must not contain '.' or '..' segments: " + path, "Pass a canonical Assets/* path without path traversal segments.");
+            return path;
+        }
+
+        /// <summary>Unity 工程根目录(Assets 的父目录)。</summary>
+        public static string ProjectRoot()
+        {
+            return Directory.GetParent(UnityEngine.Application.dataPath).FullName;
+        }
+
+        /// <summary>Assets/ 相对路径转工程内绝对路径。</summary>
+        public static string AssetFullPath(string assetPath)
+        {
+            var fullPath = Path.GetFullPath(Path.Combine(ProjectRoot(), assetPath.Replace('/', Path.DirectorySeparatorChar)));
+            var dataPath = Path.GetFullPath(UnityEngine.Application.dataPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+            if (!string.Equals(fullPath, dataPath, StringComparison.OrdinalIgnoreCase) && !fullPath.StartsWith(dataPath + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_PATH_INVALID", "Asset path resolves outside Application.dataPath: " + assetPath, "Pass a canonical path under Assets/.");
+            return fullPath;
+        }
+
+        /// <summary>判断 Assets/ 路径是否存在；历史 GUID 不能代表文件或已加载资产仍存在。</summary>
+        public static bool AssetExists(string assetPath)
+        {
+            var fullPath = AssetFullPath(assetPath);
+            return File.Exists(fullPath) || Directory.Exists(fullPath) || AssetDatabase.LoadMainAssetAtPath(assetPath) != null;
+        }
+
+        /// <summary>确保资产目录存在,缺失则创建并刷新 AssetDatabase。</summary>
+        public static void CreateAssetDirectory(string assetPath)
+        {
+            var path = RequireAssetPath(assetPath);
+            AssetFullPath(path); // 创建目录前确认路径仍位于 Assets/ 内。
+            var directory = Path.GetDirectoryName(path);
+            if (string.IsNullOrEmpty(directory) || AssetDatabase.IsValidFolder(directory.Replace('\\', '/')))
+            {
+                return;
+            }
+            Directory.CreateDirectory(Path.Combine(ProjectRoot(), directory.Replace('/', Path.DirectorySeparatorChar)));
+            AssetDatabase.Refresh();
+        }
+
+        // 校验并返回 Assets/ 资产路径;空或非 Assets/ 前缀抛 BridgeCommandException。
+        public static string RequireAssetPath(string rawPath)
+        {
+            var path = NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_PATH_REQUIRED", "Pass an Assets/* asset path.", "Use tools run asset.info --input '{\"path\":\"Assets/Example.asset\"}' or pass path in the tool input.");
+            }
+            if (!path.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase) && !string.Equals(path, "Assets", StringComparison.OrdinalIgnoreCase))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_PATH_INVALID", "Asset path must be under Assets/: " + path, "Pass a Unity project asset path such as Assets/Textures/Icon.png.");
+            }
+            return path;
+        }
+
+        // 校验 Assets/ 资产路径并要求资产已存在。
+        public static string RequireExistingAssetPath(string rawPath)
+        {
+            var path = RequireAssetPath(rawPath);
+            if (!AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_NOT_FOUND", "Asset not found: " + path, "Run tools run asset.search --input '{\"query\":\"<keyword>\"}' or pass an existing Assets/* path.");
+            }
+            return path;
+        }
+
+        /// <summary>创建 Assets/ 文件夹(逐级创建);已存在则跳过,冲突则报错。</summary>
+        public static void CreateAssetFolder(string path)
+        {
+            if (AssetDatabase.IsValidFolder(path))
+            {
+                return;
+            }
+            if (AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_OUTPUT_EXISTS", "Asset already exists and is not a folder: " + path, "Choose another Assets/* folder path.");
+            }
+            var segments = path.Split(new[] { '/' }, StringSplitOptions.RemoveEmptyEntries);
+            var current = segments.Length > 0 && string.Equals(segments[0], "Assets", StringComparison.OrdinalIgnoreCase) ? "Assets" : null;
+            if (current == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_PATH_INVALID", "Asset folder must be under Assets/: " + path, "Pass a path such as Assets/Generated.");
+            }
+            for (var index = 1; index < segments.Length; index++)
+            {
+                var next = current + "/" + segments[index];
+                if (!AssetDatabase.IsValidFolder(next))
+                {
+                    AssetDatabase.CreateFolder(current, segments[index]);
+                }
+                current = next;
+            }
+            AssetDatabase.Refresh();
+        }
+
+        /// <summary>写入文本资产文件;已存在且未授权覆盖则报错。写入后刷新 AssetDatabase。</summary>
+        public static void WriteTextAsset(string path, string content, bool overwrite)
+        {
+            path = RequireAssetPath(path);
+            var fullPath = AssetFullPath(path);
+            CreateAssetDirectory(path);
+            if (File.Exists(fullPath) && !overwrite)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Output already exists: " + path, "Pass --overwrite or choose a different asset path.");
+            }
+            try
+            {
+                File.WriteAllText(fullPath, content ?? string.Empty, new UTF8Encoding(false));
+                AssetDatabase.Refresh();
+            }
+            catch (Exception exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to write asset file: " + exception.Message, "Check destination path and permissions: " + path);
+            }
+        }
+
+        /// <summary>规范化搜索目录数组;仅允许 Assets/ 或 Packages/ 前缀。</summary>
+        public static string[] NormalizeAssetSearchFolders(string path, List<string> searchInFolders)
+        {
+            var folders = new List<string>();
+            if (searchInFolders != null)
+            {
+                foreach (var folder in searchInFolders)
+                {
+                    AddAssetSearchFolder(folders, folder);
+                }
+            }
+            if (!string.IsNullOrEmpty(path))
+            {
+                AddAssetSearchFolder(folders, path);
+            }
+            return folders.Distinct(StringComparer.OrdinalIgnoreCase).ToArray();
+        }
+
+        // 校验单个 AssetDatabase 搜索范围,仅允许 Assets/ 或 Packages/。
+        private static void AddAssetSearchFolder(List<string> folders, string rawPath)
+        {
+            if (string.IsNullOrEmpty(rawPath)) return;
+            var normalized = NormalizeAssetPath(rawPath);
+            if ((!normalized.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase) && !string.Equals(normalized, "Assets", StringComparison.OrdinalIgnoreCase)) && (!normalized.StartsWith("Packages/", StringComparison.OrdinalIgnoreCase) && !string.Equals(normalized, "Packages", StringComparison.OrdinalIgnoreCase)))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_SEARCH_SCOPE_INVALID", "Asset search scope must be under Assets/ or Packages/: " + rawPath, "Pass filter/query for search text, and use path/searchInFolders only for folder scopes.");
+            }
+            folders.Add(normalized);
+        }
+
+        /// <summary>构造资产详情 DTO(path/guid/name/type/extension/isFolder/exists/sizeBytes)。</summary>
+        public static AssetDetail BuildAssetDetail(string path)
+        {
+            var asset = AssetDatabase.LoadMainAssetAtPath(path);
+            var type = AssetDatabase.GetMainAssetTypeAtPath(path);
+            var fullPath = AssetFullPath(path);
+            var fileInfo = new FileInfo(fullPath);
+            var isFolder = AssetDatabase.IsValidFolder(path) || Directory.Exists(fullPath);
+            return new AssetDetail
+            {
+                Path = path,
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                Name = asset == null ? Path.GetFileNameWithoutExtension(path) : asset.name,
+                Type = type == null ? (isFolder ? "Folder" : null) : type.Name,
+                Extension = Path.GetExtension(path),
+                IsFolder = isFolder,
+                Exists = AssetExists(path),
+                SizeBytes = fileInfo.Exists ? (long)fileInfo.Length : 0L
+            };
+        }
+
+        /// <summary>构造资产摘要 DTO(path/guid/type/name)。</summary>
+        public static AssetSummary BuildAssetSummary(string path, Type assetType)
+        {
+            return new AssetSummary
+            {
+                Path = path,
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                Type = assetType == null ? null : assetType.Name,
+                Name = Path.GetFileNameWithoutExtension(path)
+            };
+        }
+    }
+
+    /// <summary>资产详情,asset 域工具 Result 共享。</summary>
+    public sealed class AssetDetail
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Name { get; set; }
+        public string Type { get; set; }
+        public string Extension { get; set; }
+        public bool IsFolder { get; set; }
+        public bool Exists { get; set; }
+        public long SizeBytes { get; set; }
+    }
+
+    /// <summary>资产搜索结果摘要项,asset.search 共享。</summary>
+    public sealed class AssetSummary
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Type { get; set; }
+        public string Name { get; set; }
+    }
+
+    /// <summary>分页信息,asset 域分页工具共享。</summary>
+    public sealed class AssetPageInfo
+    {
+        public long PageSize { get; set; }
+        public long Cursor { get; set; }
+        public long? NextCursor { get; set; }
+        public long Total { get; set; }
+        public bool Truncated { get; set; }
+    }
+
+    /// <summary>计划副作用项,asset 域 mutation 工具 Result 共享。</summary>
+    public sealed class AssetPlannedEffect
+    {
+        public string Type { get; set; }
+        public string Path { get; set; }
+        public string Source { get; set; }
+        public string SideEffects { get; set; }
+    }
+}
+#endif

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

@@ -0,0 +1,84 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.create — 创建文本资产或文件夹。拒绝覆盖已存在资产(除非 overwrite)。
+    /// </summary>
+    public class AssetCreateTool : IUnityCliTool<AssetCreateTool.Request, AssetCreateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Type { get; set; }
+            public string Content { get; set; }
+            public bool? Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public AssetDetail Asset { get; set; }
+            public List<AssetPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.create",
+            Summary = "Create a text asset file or folder under Assets/, refusing to overwrite unless overwrite=true.",
+            Description = "Create a text asset file or folder under Assets/. When type=folder (or the path has no extension) a folder is created; otherwise a text file is written and imported. Refuses to overwrite an existing asset unless overwrite=true.",
+            Group = "asset",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a text file", Input = new Request { Path = "Assets/Generated/created.txt", Content = "hello" } },
+                new ToolExample { Description = "Create a folder", Input = new Request { Path = "Assets/Generated/Sub", Type = "folder" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.create");
+            var path = AssetToolSupport.RequireAssetPath(request.Path);
+            var type = request.Type ?? "file";
+            var overwrite = request.Overwrite ?? false;
+            if (!string.Equals(type, "file", StringComparison.OrdinalIgnoreCase) && !string.Equals(type, "folder", StringComparison.OrdinalIgnoreCase) && !string.Equals(type, "directory", StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_TYPE_INVALID", "asset.create type must be file or folder.", "Pass type=file or type=folder.");
+            // 无扩展名或显式 folder 类型视为目录创建
+            if (string.Equals(type, "folder", StringComparison.OrdinalIgnoreCase)
+                || string.Equals(type, "directory", StringComparison.OrdinalIgnoreCase)
+                || string.IsNullOrEmpty(Path.GetExtension(path)))
+            {
+                if (AssetToolSupport.AssetExists(path))
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_OUTPUT_EXISTS", "Asset already exists: " + path, "Choose another Assets/* folder path.");
+                ctx.CommitEffect();
+                AssetToolSupport.CreateAssetFolder(path);
+                if (!AssetDatabase.IsValidFolder(path)) throw new UnityCliBridge.BridgeCommandException("E_ASSET_CREATE_STATE_MISMATCH", "Created folder could not be reloaded: " + path, "Inspect the AssetDatabase and retry.");
+            }
+            else
+            {
+                if (AssetToolSupport.AssetExists(path) && !overwrite)
+                    throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Output already exists: " + path, "Pass --overwrite or choose a different asset path.");
+                ctx.CommitEffect();
+                AssetToolSupport.WriteTextAsset(path, request.Content ?? string.Empty, overwrite);
+                AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+                if (!File.Exists(AssetToolSupport.AssetFullPath(path)) || File.ReadAllText(AssetToolSupport.AssetFullPath(path)) != (request.Content ?? string.Empty))
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_CREATE_STATE_MISMATCH", "Fresh asset bytes did not match the requested content: " + path, "Check file permissions and retry.");
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Asset = AssetToolSupport.BuildAssetDetail(path),
+                PlannedEffects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.create", Path = path } }
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,88 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.delete — 删除 Assets/ 资产(文件或文件夹)。destructive,支持 dryRun。
+    /// </summary>
+    public class AssetDeleteTool : IUnityCliTool<AssetDeleteTool.Request, AssetDeleteTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public AssetDetail Asset { get; set; }
+            public bool? DryRun { get; set; }
+            public List<AssetPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.delete",
+            Summary = "Delete an Assets/ asset file or folder; destructive, supports --dry-run preview.",
+            Description = "Delete an Assets/ asset file or folder through AssetDatabase. Destructive: removes a persisted asset. Supports --dry-run to preview the planned deletion without removing anything.",
+            Group = "asset",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-delete" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Preview a deletion", Input = new Request { Path = "Assets/Generated/old.txt" }, Execution = new ToolExampleExecution { DryRun = true } },
+                new ToolExample { Description = "Delete an asset", Input = new Request { Path = "Assets/Generated/old.txt" } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.delete");
+            var path = AssetToolSupport.RequireExistingAssetPath(request.Path);
+            if (ctx.DryRun)
+            {
+                return new Result
+                {
+                    Asset = AssetToolSupport.BuildAssetDetail(path),
+                    DryRun = true,
+                    PlannedEffects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.delete", Path = path, SideEffects = "none" } }
+                };
+            }
+            ctx.CommitEffect();
+            if (!AssetDatabase.DeleteAsset(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_DELETE_FAILED", "Failed to delete asset: " + path, "Check Unity Console and file permissions.");
+            }
+            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_ASSET_DELETE_PROOF_MISSING", "Asset deletion was not observed in the file system and AssetDatabase: " + path, "Inspect Unity Console and file permissions before retrying.");
+            }
+            return new Result
+            {
+                Asset = new AssetDetail { Path = path, Exists = observedExists },
+                PlannedEffects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.delete", Path = path } }
+            };
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/asset/duplicate.cs

@@ -0,0 +1,68 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.duplicate — 复制资产到新 Assets/ 路径。拒绝覆盖已存在目标。
+    /// </summary>
+    public class AssetDuplicateTool : IUnityCliTool<AssetDuplicateTool.Request, AssetDuplicateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Source { get; set; }
+            public string Path { get; set; }
+            public string Destination { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public AssetDetail Asset { get; set; }
+            public List<AssetPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.duplicate",
+            Summary = "Copy an existing Assets/ asset to a new Assets/ path, refusing to overwrite the destination.",
+            Description = "Copy an existing Assets/ asset to a new Assets/ path through AssetDatabase.CopyAsset. Refuses to overwrite an existing destination; choose a different path or delete it first.",
+            Group = "asset",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Duplicate an asset", Input = new Request { Source = "Assets/Materials/A.mat", Destination = "Assets/Materials/A_copy.mat" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.duplicate");
+            var source = AssetToolSupport.RequireExistingAssetPath(request.Source ?? request.Path);
+            var destination = AssetToolSupport.RequireAssetPath(request.Destination);
+            if (AssetToolSupport.AssetExists(destination))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_OUTPUT_EXISTS", "Destination asset already exists: " + destination, "Choose another destination path.");
+            }
+            ctx.CommitEffect();
+            AssetToolSupport.CreateAssetDirectory(destination);
+            AssetDatabase.CopyAsset(source, destination);
+            AssetDatabase.Refresh();
+            var destinationGuid = AssetDatabase.AssetPathToGUID(destination);
+            var observedPath = string.IsNullOrEmpty(destinationGuid) ? null : AssetDatabase.GUIDToAssetPath(destinationGuid);
+            if (string.IsNullOrEmpty(observedPath) || AssetDatabase.LoadMainAssetAtPath(observedPath) == null)
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_DUPLICATE_STATE_MISMATCH", "Duplicated asset was not available at the requested destination.", "Check destination path and Unity Console diagnostics.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Asset = AssetToolSupport.BuildAssetDetail(observedPath),
+                PlannedEffects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.duplicate", Path = destination, Source = source } }
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/asset/get-components.cs

@@ -0,0 +1,177 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.get-components — 读取 Prefab/GameObject 资产的组件摘要,避免深读整个对象图。分页+过滤。
+    /// </summary>
+    public class AssetGetComponentsTool : IUnityCliTool<AssetGetComponentsTool.Request, AssetGetComponentsTool.Result>
+    {
+        public sealed class Request
+        {
+            public string AssetPath { get; set; }
+            public string Path { get; set; }
+            public string Target { get; set; }
+            public bool? IncludeInactive { get; set; }
+            public string Query { get; set; }
+            public string NameFilter { get; set; }
+            public string PathFilter { get; set; }
+            public string ComponentType { get; set; }
+            public int? PageSize { get; set; }
+            public int? Cursor { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string Guid { get; set; }
+            public string MainObjectType { get; set; }
+            public AssetImporterInfo Importer { get; set; }
+            public bool IsGameObjectAsset { get; set; }
+            public long ComponentCount { get; set; }
+            public List<AssetComponentRow> Components { get; set; }
+            public AssetPageInfo PageInfo { get; set; }
+        }
+
+        public sealed class AssetImporterInfo
+        {
+            public string Type { get; set; }
+            public string AssetBundleName { get; set; }
+            public string UserData { get; set; }
+        }
+
+        public sealed class AssetComponentRow
+        {
+            public string GameObject { get; set; }
+            public string Path { get; set; }
+            public bool Active { get; set; }
+            public long ComponentIndex { get; set; }
+            public string Type { get; set; }
+            public string FullName { get; set; }
+            public bool Enabled { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.get-components",
+            Summary = "List Prefab/GameObject asset component summaries with paging and name/path/component-type filters.",
+            Description = "List component summaries for a Prefab/GameObject asset without deep-reading the whole object graph. Filters: query/nameFilter/pathFilter match GameObject name or relative path; componentType matches a component type name. Results are paged via cursor/pageSize.",
+            Group = "asset",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List components in a prefab", Input = new Request { AssetPath = "Assets/Prefabs/Player.prefab", PageSize = 50 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AssetToolSupport.RequireExistingAssetPath(request.AssetPath ?? request.Path ?? request.Target);
+            var includeInactive = request.IncludeInactive ?? true;
+            var pageSize = Math.Max(1, Math.Min(request.PageSize ?? 50, 500));
+            var cursor = Math.Max(0, request.Cursor ?? 0);
+            var query = request.Query ?? request.NameFilter ?? request.PathFilter;
+            var componentType = request.ComponentType;
+            var asset = AssetDatabase.LoadMainAssetAtPath(path);
+            var importer = AssetImporter.GetAtPath(path);
+            var root = AssetDatabase.LoadAssetAtPath<GameObject>(path);
+            var rows = new List<AssetComponentRow>();
+            if (root != null)
+            {
+                foreach (var transform in root.GetComponentsInChildren<Transform>(includeInactive))
+                {
+                    var gameObject = transform.gameObject;
+                    var relativePath = PrefabRelativePath(root.transform, transform);
+                    if (!TextMatches(query, gameObject.name, relativePath)) continue;
+                    var components = transform.GetComponents<Component>();
+                    for (var index = 0; index < components.Length; index++)
+                    {
+                        if (!ComponentTypeMatches(components[index], componentType)) continue;
+                        rows.Add(BuildRow(gameObject, components[index], index, relativePath));
+                    }
+                }
+            }
+            var page = new List<AssetComponentRow>();
+            for (var i = cursor; i < rows.Count && page.Count < pageSize; i++)
+            {
+                page.Add(rows[i]);
+            }
+            long? nextCursor = cursor + page.Count < rows.Count ? (long?)(cursor + page.Count) : null;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                MainObjectType = asset == null ? null : asset.GetType().FullName,
+                Importer = new AssetImporterInfo
+                {
+                    Type = importer == null ? null : importer.GetType().FullName,
+                    AssetBundleName = importer == null ? null : importer.assetBundleName,
+                    UserData = importer == null ? null : importer.userData
+                },
+                IsGameObjectAsset = root != null,
+                ComponentCount = rows.Count,
+                Components = page,
+                PageInfo = new AssetPageInfo
+                {
+                    PageSize = pageSize,
+                    Cursor = cursor,
+                    NextCursor = nextCursor,
+                    Total = rows.Count,
+                    Truncated = nextCursor != null
+                }
+            });
+        }
+
+        // 构造 GameObject 在 Prefab root 下的相对路径
+        private static string PrefabRelativePath(Transform root, Transform transform)
+        {
+            var stack = new Stack<string>();
+            var current = transform;
+            while (current != null)
+            {
+                stack.Push(current.name);
+                if (current == root) break;
+                current = current.parent;
+            }
+            return string.Join("/", stack.ToArray());
+        }
+
+        private static AssetComponentRow BuildRow(GameObject gameObject, Component component, int componentIndex, string relativePath)
+        {
+            return new AssetComponentRow
+            {
+                GameObject = gameObject.name,
+                Path = relativePath,
+                Active = gameObject.activeSelf,
+                ComponentIndex = componentIndex,
+                Type = component == null ? "MissingScript" : component.GetType().Name,
+                FullName = component == null ? null : component.GetType().FullName,
+                Enabled = component != null && GameObjectToolSupport.ComponentEnabled(component)
+            };
+        }
+
+        // query 为空时匹配全部;否则对 name 或 relativePath 做大小写不敏感包含匹配
+        private static bool TextMatches(string query, string name, string relativePath)
+        {
+            if (string.IsNullOrEmpty(query)) return true;
+            return (name != null && name.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0)
+                || (relativePath != null && relativePath.IndexOf(query, StringComparison.OrdinalIgnoreCase) >= 0);
+        }
+
+        // componentType 为空时匹配全部;否则按类型名大小写不敏感匹配(缺失脚本视作 MissingScript)
+        private static bool ComponentTypeMatches(Component component, string componentType)
+        {
+            if (string.IsNullOrEmpty(componentType)) return true;
+            var name = component == null ? "MissingScript" : component.GetType().Name;
+            return string.Equals(name, componentType, StringComparison.OrdinalIgnoreCase);
+        }
+    }
+}
+#endif