@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,73 @@
+#if UNITY_EDITOR
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.get-data — 资产深读:底层复用 ObjectSerializer,支持 paths/viewQuery 互斥的 token-safe 读取。
+    /// </summary>
+    public class AssetGetDataTool : IUnityCliTool<AssetGetDataTool.Request, AssetGetDataTool.Result>
+    {
+        public sealed class Request : IUnityCliObjectSerializationInput
+        {
+            public string AssetPath { get; set; }
+            public string Path { get; set; }
+            public int? MaxDepth { get; set; }
+            public int? MaxArrayItems { get; set; }
+            public bool? IncludeFields { get; set; }
+            public bool? IncludeProperties { get; set; }
+            public bool? DeepSerialization { get; set; }
+            public System.Collections.Generic.List<string> Paths { get; set; }
+            [UnityCliAnyJson] public object ViewQuery { get; set; }
+            public string NamePattern { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string Guid { get; set; }
+            public string TypeName { get; set; }
+            [UnityCliAnyJson] public object Data { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.get-data",
+            Summary = "Deep-read an Assets/* asset's members via ObjectSerializer; use paths or viewQuery for token-safe fields.",
+            Description = "Deep-read an Assets/* asset's members. For token safety, pass exact paths or one viewQuery; they are mutually exclusive and skip full fields/props expansion. Keep maxDepth low before expanding large assets. Arrays/lists/dicts are bounded by maxArrayItems.",
+            Group = "asset",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read exact fields only", Input = new Request { AssetPath = "Assets/Materials/Probe.mat", NamePattern = "name" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AssetToolSupport.RequireAssetPath(request.AssetPath ?? request.Path);
+            if (!AssetToolSupport.AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_NOT_FOUND", "Asset not found: " + path, "Run tools run asset.search --input '{\"query\":\"<keyword>\"}' to discover the path.");
+            }
+            var asset = AssetDatabase.LoadMainAssetAtPath(path);
+            if (asset == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_LOAD_FAILED", "Asset main object could not be loaded: " + path, "Run asset.info to confirm the asset type, or use a more specific tool for folders/importers.");
+            }
+            var options = GameObjectToolSupport.BuildSerializerOptions(request);
+            var data = UnityCliBridge.ObjectSerializer.Serialize(asset, options);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                TypeName = asset.GetType().FullName,
+                // ObjectSerializer 输出为动态 JSON 树);解析为嵌套结构供框架序列化(IDictionary 支持)
+                Data = data
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/asset/import-settings/set.cs

@@ -0,0 +1,127 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>预检并写入一个 asset importer，reimport 后以 fresh importer/GUID/member 值证明终态。</summary>
+    public sealed class AssetImportSettingsSetTool : IUnityCliTool<AssetImportSettingsSetTool.Request, AssetImportSettingsSetTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Path { get; set; }
+
+            [UnityCliRequired, UnityCliAnyJson]
+            public Dictionary<string, object> Settings { get; set; }
+
+            [UnityCliStringEnum("Default", "Standalone", "iOS", "Android", "WebGL", "tvOS")]
+            public string Platform { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public AssetImportSettingsSnapshot ImportSettings { get; set; }
+            public bool Changed { get; set; }
+            public bool DryRun { get; set; }
+            public List<AssetImportSettingChange> Changes { get; set; }
+            public List<AssetPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.import-settings.set",
+            Summary = "Set validated default or platform importer settings and prove them after synchronous reimport.",
+            Description = "Prevalidates every supplied setting before one effect barrier. Default targets public importer members and Audio sample settings; platform overrides support TextureImporter and AudioImporter. Unknown, conflicting, reload-risk, or unconvertible settings fail without partial writes.",
+            Group = "asset",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-meta-write", "asset-import" },
+            SupportsDryRun = true,
+            Permissions = new[] { "project-asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 60000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample
+                {
+                    Description = "Make one texture readable and enable mipmaps.",
+                    Input = new Request
+                    {
+                        Path = "Assets/Textures/Icon.png",
+                        Platform = "Default",
+                        Settings = new Dictionary<string, object> { { "isReadable", true }, { "mipmapEnabled", true } }
+                    }
+                },
+                new ToolExample
+                {
+                    Description = "Preview an Android texture override without writing importer state.",
+                    Input = new Request
+                    {
+                        Path = "Assets/Textures/Icon.png",
+                        Platform = "Android",
+                        Settings = new Dictionary<string, object> { { "maxTextureSize", 1024L }, { "overridden", true } }
+                    },
+                    Execution = new ToolExampleExecution { DryRun = true }
+                }
+            }
+        };
+
+        /// <summary>先冻结全部 member/value，再按 dry-run/no-op/effect 三条路径返回统一 typed result。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.import-settings.set");
+            ct.ThrowIfCancellationRequested();
+            var plan = AssetImportSettingsToolSupport.Prepare(request.Path, request.Platform, request.Settings);
+            var plannedEffects = plan.Changed
+                ? new List<AssetPlannedEffect>
+                {
+                    new AssetPlannedEffect
+                    {
+                        Type = "asset.import-settings.set",
+                        Path = plan.Path,
+                        SideEffects = "asset-meta-write,asset-import"
+                    }
+                }
+                : new List<AssetPlannedEffect>();
+            if (ctx.DryRun)
+            {
+                return new ValueTask<Result>(new Result
+                {
+                    ImportSettings = AssetImportSettingsToolSupport.Read(plan.Path, plan.Platform),
+                    Changed = plan.Changed,
+                    DryRun = true,
+                    Changes = plan.Changes,
+                    PlannedEffects = plannedEffects
+                });
+            }
+            if (!plan.Changed)
+            {
+                return new ValueTask<Result>(new Result
+                {
+                    ImportSettings = AssetImportSettingsToolSupport.Read(plan.Path, plan.Platform),
+                    Changed = false,
+                    DryRun = false,
+                    Changes = plan.Changes,
+                    PlannedEffects = plannedEffects
+                });
+            }
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            AssetImportSettingsToolSupport.Apply(plan);
+            var readback = AssetImportSettingsToolSupport.Prove(plan);
+            return new ValueTask<Result>(new Result
+            {
+                ImportSettings = readback,
+                Changed = true,
+                DryRun = false,
+                Changes = plan.Changes,
+                PlannedEffects = plannedEffects
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/asset/import-settings.cs

@@ -0,0 +1,54 @@
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>读取一个 asset importer 的默认设置和指定平台 override，不触发 import 或写入。</summary>
+    public sealed class AssetImportSettingsTool : IUnityCliTool<AssetImportSettingsTool.Request, AssetImportSettingsSnapshot>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Path { get; set; }
+
+            [UnityCliStringEnum("Default", "Standalone", "iOS", "Android", "WebGL", "tvOS")]
+            public string Platform { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.import-settings",
+            Summary = "Read importer type, Unity version, default settings, and one platform override for an Assets/ asset.",
+            Description = "Reads the current AssetImporter without refreshing or reimporting. Texture, model, and audio importers return typed setting sets; other importers return the stable generic bundle fields.",
+            Group = "asset",
+            DestructiveHint = false,
+            SideEffects = new string[0],
+            SupportsDryRun = false,
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 120000,
+            Examples = new[]
+            {
+                new ToolExample
+                {
+                    Description = "Read the default TextureImporter settings for one asset.",
+                    Input = new Request { Path = "Assets/Textures/Icon.png", Platform = "Default" }
+                },
+                new ToolExample
+                {
+                    Description = "Read the Android platform override for one texture or audio asset.",
+                    Input = new Request { Path = "Assets/Textures/Icon.png", Platform = "Android" }
+                }
+            }
+        };
+
+        public ValueTask<AssetImportSettingsSnapshot> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            ct.ThrowIfCancellationRequested();
+            return new ValueTask<AssetImportSettingsSnapshot>(AssetImportSettingsToolSupport.Read(request.Path, request.Platform));
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,132 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Security.Cryptography;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.import — 从源文件或内联 content 导入资产到 Assets/ 路径。
+    /// </summary>
+    public class AssetImportTool : IUnityCliTool<AssetImportTool.Request, AssetImportTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Destination { get; set; }
+            public string Source { get; set; }
+            public string Content { get; set; }
+            public bool? Overwrite { 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.import",
+            Summary = "Import a file into an Assets/ path from a source file or inline content, then force-import it.",
+            Description = "Import a file into an Assets/ path. When source is set, the source file (absolute or Assets/ path) is copied to the destination; otherwise inline content is written. The destination is force-imported, compile/import/reload is absorbed, and success proves the recovered AssetDatabase resolves the destination GUID. Refuses to overwrite unless overwrite=true.",
+            Group = "asset",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-write", "asset-import" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Import inline text", Input = new Request { Path = "Assets/Generated/imported.txt", Content = "matrix import", Overwrite = true } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.import");
+            var path = AssetToolSupport.RequireAssetPath(request.Path ?? request.Destination);
+            var source = request.Source;
+            var overwrite = request.Overwrite ?? false;
+            var effects = new List<AssetPlannedEffect> { new AssetPlannedEffect { Type = "asset.import", Path = path, Source = source } };
+            if (ctx.DryRun)
+            {
+                return new Result
+                {
+                    Asset = new AssetDetail { Path = path, Name = Path.GetFileNameWithoutExtension(path), Extension = Path.GetExtension(path), Exists = File.Exists(AssetToolSupport.AssetFullPath(path)) },
+                    DryRun = true,
+                    PlannedEffects = effects
+                };
+            }
+
+            if (!string.IsNullOrEmpty(source))
+            {
+                var normalizedSource = AssetToolSupport.NormalizeAssetPath(source);
+                var fullSource = normalizedSource.StartsWith("Assets/", StringComparison.OrdinalIgnoreCase)
+                    ? AssetToolSupport.AssetFullPath(normalizedSource)
+                    : Path.GetFullPath(source.Replace('\\', Path.DirectorySeparatorChar).Replace('/', Path.DirectorySeparatorChar));
+                if (!File.Exists(fullSource))
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_SOURCE_NOT_FOUND", "Source file not found: " + source, "Pass an existing file path or Assets/* source asset.");
+                }
+                var fullDestination = AssetToolSupport.AssetFullPath(path);
+                if (File.Exists(fullDestination) && !overwrite)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_OUTPUT_EXISTS", "Asset already exists: " + path, "Pass --overwrite or choose another destination.");
+                }
+                if (string.Equals(Path.GetFullPath(fullSource), Path.GetFullPath(fullDestination), StringComparison.OrdinalIgnoreCase))
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_SOURCE_EQUALS_DESTINATION", "Asset import source and destination resolve to the same file.", "Choose a different destination path.");
+                ctx.CommitEffect();
+                AssetToolSupport.CreateAssetDirectory(path);
+                File.Copy(fullSource, fullDestination, true);
+            }
+            else
+            {
+                if (request.Content == null)
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_IMPORT_INPUT_REQUIRED", "asset.import requires source or content.", "Pass a source file or inline content.");
+                var fullDestination = AssetToolSupport.AssetFullPath(path);
+                if (File.Exists(fullDestination) && !overwrite)
+                    throw new UnityCliBridge.BridgeCommandException("E_ASSET_OUTPUT_EXISTS", "Asset already exists: " + path, "Pass --overwrite or choose another destination.");
+                ctx.CommitEffect();
+                AssetToolSupport.WriteTextAsset(path, request.Content, overwrite);
+            }
+            // effect 落盘后、ImportAsset 前采集目标字节哈希，用于证明 import 过程未篡改内容。
+            var destFullPath = AssetToolSupport.AssetFullPath(path);
+            var expectedHash = File.Exists(destFullPath) ? FileSha256(destFullPath) : null;
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            var ready = await ctx.Wait.UntilEditorReady(TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct);
+            if (!ready)
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_IMPORT_TIMEOUT", "The Editor did not reach a stable ready state after importing " + path + ".", "Inspect editor.state and compile diagnostics before submitting a new request.");
+            var asset = AssetToolSupport.BuildAssetDetail(path);
+            VerifyContentProof(path, expectedHash);
+            if (!asset.Exists || string.IsNullOrEmpty(AssetDatabase.AssetPathToGUID(path)))
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_IMPORT_PROOF_MISSING", "The imported asset is not resolvable after import: " + path, "Inspect import/compile diagnostics before submitting a new request.");
+            return new Result { Asset = asset, PlannedEffects = effects };
+        }
+
+        /// <summary>校验 import 后目标文件字节仍与 effect 落盘时一致，避免把预存资产误当成本次 import proof。</summary>
+        private static void VerifyContentProof(string path, string expectedHash)
+        {
+            var fullPath = AssetToolSupport.AssetFullPath(path);
+            var actualHash = File.Exists(fullPath) ? FileSha256(fullPath) : null;
+            if (!string.Equals(actualHash, expectedHash, StringComparison.Ordinal))
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_IMPORT_PROOF_MISSING", "Imported destination bytes do not match the content digest captured before import.", "Inspect the source and destination files before submitting a new request.");
+        }
+
+        private static string FileSha256(string path)
+        {
+            using (var stream = File.OpenRead(path))
+            using (var sha = SHA256.Create())
+            {
+                var bytes = sha.ComputeHash(stream);
+                return string.Concat(Array.ConvertAll(bytes, value => value.ToString("x2")));
+            }
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,48 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.info — 读取资产主对象摘要(path/guid/name/type/extension/isFolder/exists/sizeBytes)。
+    /// </summary>
+    public class AssetInfoTool : IUnityCliTool<AssetInfoTool.Request, AssetInfoTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public AssetDetail Asset { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.info",
+            Summary = "Return path, guid, name, type, extension, folder flag, existence, and byte size for an Assets/* asset.",
+            Description = "Return path, guid, name, type, extension, folder flag, existence, and byte size for an Assets/* asset. Read-only; use asset.get-data for deep member reads and asset.get-components for Prefab/GameObject component summaries.",
+            Group = "asset",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Inspect an asset", Input = new Request { Path = "Assets/Textures/Icon.png" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AssetToolSupport.RequireAssetPath(request.Path ?? request.Target);
+            if (!AssetToolSupport.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 new System.Threading.Tasks.ValueTask<Result>(new Result { Asset = AssetToolSupport.BuildAssetDetail(path) });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,69 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.modify — 用新 content 覆盖文本类资产文件并重新导入。
+    /// </summary>
+    public class AssetModifyTool : IUnityCliTool<AssetModifyTool.Request, AssetModifyTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Path { get; set; }
+            public string Content { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public AssetDetail Asset { get; set; }
+            public List<AssetPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.modify",
+            Summary = "Overwrite a text-like asset file with new content and force-reimport it.",
+            Description = "Overwrite a text-like asset file with new content and force-reimport it. The asset must already exist. Use asset.create for new files and asset.import for binary source files.",
+            Group = "asset",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write", "asset-import" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Modify a text asset", Input = new Request { Path = "Assets/Generated/notes.txt", Content = "updated" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.modify");
+            var path = AssetToolSupport.RequireExistingAssetPath(request.Path);
+            var content = request.Content;
+            var extension = Path.GetExtension(path).ToLowerInvariant();
+            var textExtensions = new HashSet<string> { ".txt", ".json", ".xml", ".csv", ".md", ".yaml", ".yml", ".uss", ".uxml", ".shader", ".cginc", ".compute", ".asmdef", ".asmref" };
+            if (!textExtensions.Contains(extension) || Directory.Exists(AssetToolSupport.AssetFullPath(path)))
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_MODIFY_TYPE_UNSUPPORTED", "asset.modify only supports existing ordinary text files with a safe extension: " + path, "Use an approved text extension or the specialized asset tool.");
+            if (content == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_CONTENT_REQUIRED", "Asset modify requires content or content-file.", "Pass text content for a text-like asset file.");
+            }
+            ctx.CommitEffect();
+            AssetToolSupport.WriteTextAsset(path, content, true);
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            if (!File.Exists(AssetToolSupport.AssetFullPath(path)) || File.ReadAllText(AssetToolSupport.AssetFullPath(path)) != content)
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_MODIFY_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.modify", Path = path } }
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,70 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.move — 移动资产到新 Assets/ 路径。
+    /// </summary>
+    public class AssetMoveTool : IUnityCliTool<AssetMoveTool.Request, AssetMoveTool.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.move",
+            Summary = "Move an existing Assets/ asset to a new Assets/ path.",
+            Description = "Move an existing Assets/ asset to a new Assets/ path through AssetDatabase.MoveAsset. Use asset.rename to change only the filename within the same directory.",
+            Group = "asset",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Move an asset", Input = new Request { Source = "Assets/Old/Icon.png", Destination = "Assets/New/Icon.png" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            AssetToolSupport.EnsureEditorNotBusy("asset.move");
+            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.");
+            }
+            var sourceGuid = AssetDatabase.AssetPathToGUID(source);
+            ctx.CommitEffect();
+            AssetToolSupport.CreateAssetDirectory(destination);
+            AssetDatabase.MoveAsset(source, destination);
+            AssetDatabase.Refresh();
+            var observedPath = string.IsNullOrEmpty(sourceGuid) ? null : AssetDatabase.GUIDToAssetPath(sourceGuid);
+            if (observedPath != destination || AssetDatabase.LoadMainAssetAtPath(observedPath) == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_MOVE_STATE_MISMATCH", "Asset move did not produce the expected source and destination state.", "Check source, destination 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.move", Path = destination, Source = source } }
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,86 @@
+#if UNITY_EDITOR
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// asset.preview — 生成资产缩略图预览元数据(宽高/终态)。
+    /// </summary>
+    public class AssetPreviewTool : IUnityCliTool<AssetPreviewTool.Request, AssetPreviewTool.Result>
+    {
+        public sealed class Request
+        {
+            public string AssetPath { get; set; }
+            public string Path { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string Guid { get; set; }
+            public string TypeName { get; set; }
+            public bool HasPreview { get; set; }
+            public long? Width { get; set; }
+            public long? Height { get; set; }
+            public bool? IsTransient { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "asset.preview",
+            Summary = "Return AssetPreview thumbnail metadata (width/height/transient) for an Assets/* asset.",
+            Description = "Return terminal AssetPreview thumbnail metadata for an Assets/* asset. A cache miss waits for Editor preview generation; assets without a preview return hasPreview=false as a terminal result. Does not return image bytes; use camera.screenshot or screenshot.scene-view for rendered captures.",
+            Group = "asset",
+            DestructiveHint = false,
+            SideEffects = new[] { "asset-preview-generation", "editor-cache-write" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Preview an asset", Input = new Request { AssetPath = "Assets/Materials/Probe.mat" } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = AssetToolSupport.RequireAssetPath(request.AssetPath ?? request.Path);
+            if (!AssetToolSupport.AssetExists(path))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_NOT_FOUND", "Asset not found: " + path, "Run tools run asset.search --input '{\"query\":\"<keyword>\"}' to discover the path.");
+            }
+            var asset = AssetDatabase.LoadMainAssetAtPath(path);
+            if (asset == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_NOT_FOUND", "Asset not found: " + path, "Run tools run asset.search --input '{\"query\":\"<keyword>\"}' to discover the path.");
+            }
+            var instanceId = asset.GetInstanceID();
+            ctx.CommitEffect();
+            AssetPreview.GetAssetPreview(asset);
+            var completed = await ctx.Wait.Until(
+                () => !AssetPreview.IsLoadingAssetPreview(instanceId),
+                System.TimeSpan.FromMilliseconds(System.Math.Max(1, ctx.TimeoutMs)),
+                ct);
+            if (!completed)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_ASSET_PREVIEW_TIMEOUT", "Asset preview did not finish loading: " + path, "Wait for the Editor to finish generating previews, then retry.");
+            }
+            var preview = AssetPreview.GetAssetPreview(asset);
+            var hasPreview = preview != null;
+            var result = new Result
+            {
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                TypeName = asset.GetType().FullName,
+                HasPreview = hasPreview,
+                IsTransient = false
+            };
+            if (hasPreview)
+            {
+                result.Width = preview.width;
+                result.Height = preview.height;
+            }
+            return result;
+        }
+    }
+}
+#endif