@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/screenshot/scene-view.cs

@@ -0,0 +1,99 @@
+#if UNITY_EDITOR
+using System;
+using System.IO;
+using UnityEngine;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot.scene-view — 捕获激活 SceneView 到文件。
+    /// </summary>
+    public class ScreenshotSceneViewTool : IUnityCliTool<ScreenshotSceneViewTool.Request, ScreenshotSceneViewTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Path { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public bool Transparent { get; set; }
+            public int? Quality { get; set; }
+            public bool Overwrite { get; set; }
+            public bool InlineBase64 { get; set; }
+        }
+
+        public sealed class Result : ScreenshotCaptureResult { }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.scene-view",
+            Summary = "Capture the active SceneView camera to a PNG/JPG file.",
+            Description = "Capture the active SceneView camera to a PNG/JPG file. Returns E_SCENE_VIEW_NOT_AVAILABLE when no SceneView is open.",
+            Group = "screenshot",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Capture scene view", Input = new Request { Path = "Assets/Shots/scene.png" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var sceneView = SceneView.lastActiveSceneView;
+            if (sceneView == null || sceneView.camera == null)
+                throw new UnityCliBridge.BridgeCommandException("E_SCENE_VIEW_NOT_AVAILABLE", "No active SceneView camera.", "Open a SceneView window.");
+            var camera = sceneView.camera;
+            var outputPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.Path);
+            var format = ScreenshotToolSupport.NormalizeFormat(null, outputPath);
+            var width = Math.Max(1, request.Width ?? (camera.pixelWidth > 0 ? camera.pixelWidth : 1280));
+            var height = Math.Max(1, request.Height ?? (camera.pixelHeight > 0 ? camera.pixelHeight : 720));
+            var quality = Mathf.Clamp(request.Quality ?? 95, 1, 100);
+
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            ctx.CommitEffect();
+            ScreenshotToolSupport.CreateScreenshotDirectory(outputPath);
+
+            var prevTarget = camera.targetTexture;
+            var prevActive = RenderTexture.active;
+            var prevClear = camera.clearFlags;
+            var prevBg = camera.backgroundColor;
+            var rt = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
+            var texture = new Texture2D(width, height, request.Transparent ? TextureFormat.ARGB32 : TextureFormat.RGB24, false);
+            byte[] bytes;
+            try
+            {
+                camera.targetTexture = rt;
+                if (request.Transparent) { camera.clearFlags = CameraClearFlags.SolidColor; camera.backgroundColor = new Color(0, 0, 0, 0); }
+                camera.Render();
+                RenderTexture.active = rt;
+                texture.ReadPixels(new Rect(0, 0, width, height), 0, 0);
+                texture.Apply();
+                bytes = format == "jpg" ? texture.EncodeToJPG(quality) : texture.EncodeToPNG();
+                ScreenshotToolSupport.WriteScreenshotBytes(outputPath, bytes);
+            }
+            finally
+            {
+                RenderTexture.active = prevActive;
+                camera.targetTexture = prevTarget;
+                camera.clearFlags = prevClear;
+                camera.backgroundColor = prevBg;
+                UnityEngine.Object.DestroyImmediate(texture);
+                rt.Release();
+                UnityEngine.Object.DestroyImmediate(rt);
+            }
+
+            var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, format);
+            var result = new Result
+            {
+                ScreenshotPath = outputPath, ArtifactPath = outputPath, Source = "scene-view",
+                SizeBytes = artifact.SizeBytes, Sha256 = artifact.Sha256
+            };
+            ScreenshotToolSupport.MaybeAppendInline(result, bytes, width, height, format == "jpg" ? "image/jpeg" : "image/png", request.InlineBase64);
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/screenshot/screen.cs

@@ -0,0 +1,89 @@
+#if UNITY_EDITOR
+using System;
+using System.IO;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot.screen — 用 ScreenCapture 抓最终合成画面（含屏幕空间 UI）到文件。
+    /// </summary>
+    public class ScreenshotScreenTool : IUnityCliTool<ScreenshotScreenTool.Request, ScreenshotScreenTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Path { get; set; }
+            public bool Overwrite { get; set; }
+            public bool InlineBase64 { get; set; }
+            public int? SuperSize { get; set; }
+        }
+
+        public sealed class Result : ScreenshotCaptureResult { }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.screen",
+            Summary = "Capture the final composited screen including screen-space UI to a PNG file.",
+            Description = "Capture the final composited frame (including Screen Space Overlay Canvas UI) via ScreenCapture. Resolution follows the Game View size and cannot be set arbitrarily; capture is most reliable in Play Mode and the file is written at the end of the frame.",
+            Group = "screenshot",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Capture the final screen with UI", Input = new Request { Path = "Assets/Shots/screen.png" } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var outputPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.Path);
+            if (!outputPath.EndsWith(".png", StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_FORMAT_UNSUPPORTED", "screenshot.screen only writes .png output.", "Pass a .png output path.");
+            if (File.Exists(outputPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            ctx.CommitEffect();
+            ScreenshotToolSupport.CreateScreenshotDirectory(outputPath);
+            var superSize = Math.Max(1, request.SuperSize ?? 1);
+
+            // ScreenCapture 抓最终合成画面（含屏幕空间 UI），在帧末异步落盘。
+            ScreenCapture.CaptureScreenshot(outputPath, superSize);
+
+            var written = await ctx.Wait.Until(() => File.Exists(outputPath) && new FileInfo(outputPath).Length > 0, TimeSpan.FromMilliseconds(Math.Max(1, ctx.TimeoutMs)), ct);
+            if (!written)
+                throw new UnityCliBridge.BridgeCommandException("E_EXECUTION_TIMEOUT", "ScreenCapture did not write the screenshot before the deadline.", "Retry with a larger timeout, or use screenshot.game-view for camera-only capture.");
+
+            var artifact = ScreenshotToolSupport.VerifyScreenshotArtifact(outputPath, "png");
+            var (width, height) = ReadPngDimensions(outputPath);
+            var result = new Result
+            {
+                ScreenshotPath = outputPath, ArtifactPath = outputPath, Source = "screen",
+                SizeBytes = artifact.SizeBytes, Sha256 = artifact.Sha256
+            };
+            if (request.InlineBase64)
+            {
+                var bytes = File.ReadAllBytes(outputPath);
+                ScreenshotToolSupport.MaybeAppendInline(result, bytes, (int)width, (int)height, "image/png", true);
+            }
+            return result;
+        }
+
+        // 从落盘 PNG 的 IHDR 读取实际宽高（大端），用于报告 Game View 实际分辨率。
+        private static (long width, long height) ReadPngDimensions(string path)
+        {
+            try
+            {
+                var bytes = File.ReadAllBytes(path);
+                if (bytes.Length >= 24 && bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4e && bytes[3] == 0x47)
+                {
+                    long width = ((long)bytes[16] << 24) | ((long)bytes[17] << 16) | ((long)bytes[18] << 8) | bytes[19];
+                    long height = ((long)bytes[20] << 24) | ((long)bytes[21] << 16) | ((long)bytes[22] << 8) | bytes[23];
+                    return (width, height);
+                }
+            }
+            catch { /* 尺寸读取失败返回 0，artifact proof 仍由 VerifyScreenshotArtifact 保证 */ }
+            return (0, 0);
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/screenshot/surround.cs

@@ -0,0 +1,181 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.IO;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// screenshot.surround — 6 角度环绕截图并生成 contact sheet。破坏性(asset-write)。
+    /// </summary>
+    public class ScreenshotSurroundTool : IUnityCliTool<ScreenshotSurroundTool.Request, ScreenshotSurroundTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public string OutputDir { get; set; } = "Assets/Screenshots/Surround";
+            public string ContactSheetPath { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public float? Radius { get; set; }
+            public float? Fov { get; set; }
+            public bool Overwrite { get; set; }
+            public bool InlineBase64 { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool DryRun { get; set; }
+            public double[] Center { get; set; }
+            public long Count { get; set; }
+            public ScreenshotArtifactEntry ContactSheet { get; set; }
+            public List<SurroundShot> Artifacts { get; set; }
+            public string ImageBase64 { get; set; }
+            public long? ImageWidth { get; set; }
+            public long? ImageHeight { get; set; }
+            public string ImageMimeType { get; set; }
+        }
+
+        public sealed class SurroundShot
+        {
+            public string Angle { get; set; }
+            public ScreenshotArtifactEntry Artifact { get; set; }
+            public double[] CameraPosition { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "screenshot.surround",
+            Summary = "Capture six fixed-angle screenshots and compose a 3x2 contact sheet; dry-run supported.",
+            Description = "Capture six fixed angles (front, back, left, right, top, bird_eye) around a GameObject and compose a 3x2 contact sheet PNG. Supports --dry-run to preview planned artifacts. Editor-only.",
+            Group = "screenshot",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            SupportsDryRun = true,
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Surround a target (dry-run)", Input = new Request { Target = "Player" }, Execution = new ToolExampleExecution { DryRun = true } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(request.Target);
+            if (go == null)
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "screenshot.surround requires a target GameObject.", "Pass --target <path>.");
+            var outputDir = request.OutputDir ?? "Assets/Screenshots/Surround";
+            var outputFullDir = ScreenshotToolSupport.AssetFullPath(outputDir);
+            var contactSheetPath = ScreenshotToolSupport.ResolveScreenshotOutputPath(request.ContactSheetPath ?? Path.Combine(outputDir, "surround_contact_sheet.png"));
+            var width = Math.Max(1, request.Width ?? 512);
+            var height = Math.Max(1, request.Height ?? 512);
+            var bounds = ScreenshotToolSupport.TargetRenderBounds(go);
+            var center = bounds.center;
+            var radius = request.Radius ?? Mathf.Max(bounds.extents.magnitude * 2.5f, 5f);
+
+            var labels = new[] { "front", "back", "left", "right", "top", "bird_eye" };
+            var positions = new[]
+            {
+                center + new Vector3(0, 0, -radius),
+                center + new Vector3(0, 0, radius),
+                center + new Vector3(-radius, 0, 0),
+                center + new Vector3(radius, 0, 0),
+                center + new Vector3(0, radius, 0),
+                center + new Vector3(radius * 0.7f, radius * 0.7f, -radius * 0.7f)
+            };
+            var shotPaths = new List<string>();
+            for (var i = 0; i < labels.Length; i++)
+            {
+                var path = Path.Combine(outputFullDir, "surround_" + labels[i] + ".png");
+                if (File.Exists(path) && !request.Overwrite)
+                    throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + path, "Pass overwrite=true or choose a different output-dir.");
+                shotPaths.Add(path);
+            }
+            if (File.Exists(contactSheetPath) && !request.Overwrite)
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Contact sheet output already exists: " + contactSheetPath, "Pass overwrite=true or choose a different contactSheetPath.");
+
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    DryRun = true,
+                    Center = new double[] { center.x, center.y, center.z },
+                    ContactSheet = new ScreenshotArtifactEntry { Source = "surround-contact-sheet", Path = contactSheetPath, Width = width * 3, Height = height * 2, Format = "png" },
+                    Artifacts = BuildPlannedShots(labels, shotPaths, width, height, positions)
+                });
+            }
+
+            ctx.CommitEffect();
+            Directory.CreateDirectory(outputFullDir);
+            ScreenshotToolSupport.CreateScreenshotDirectory(contactSheetPath);
+            var tempGo = new GameObject("__unitycli_surround_cam__");
+            var cam = tempGo.AddComponent<Camera>();
+            cam.fieldOfView = Mathf.Clamp(request.Fov ?? 60f, 10f, 120f);
+            cam.nearClipPlane = 0.1f;
+            cam.farClipPlane = Mathf.Max(radius * 6f, 100f);
+            cam.clearFlags = CameraClearFlags.SolidColor;
+            cam.backgroundColor = new Color(0.18f, 0.18f, 0.18f, 1f);
+            var tiles = new List<Texture2D>();
+            var artifacts = new List<SurroundShot>();
+            byte[] contactBytes = null;
+            try
+            {
+                for (var i = 0; i < labels.Length; i++)
+                {
+                    cam.transform.position = positions[i];
+                    cam.transform.LookAt(center);
+                    var tile = ScreenshotToolSupport.RenderScreenshotTexture(cam, width, height);
+                    tiles.Add(tile);
+                    var proof = ScreenshotToolSupport.WriteScreenshotBytes(shotPaths[i], tile.EncodeToPNG());
+                    artifacts.Add(new SurroundShot
+                    {
+                        Angle = labels[i],
+                        Artifact = new ScreenshotArtifactEntry { Source = "surround", Path = shotPaths[i], Camera = "surround:" + labels[i], Width = width, Height = height, Format = "png", SizeBytes = proof.SizeBytes, Sha256 = proof.Sha256 },
+                        CameraPosition = new double[] { positions[i].x, positions[i].y, positions[i].z }
+                    });
+                }
+                var contact = ScreenshotToolSupport.ComposeScreenshotContactSheet(tiles, width, height);
+                try { contactBytes = contact.EncodeToPNG(); ScreenshotToolSupport.WriteScreenshotBytes(contactSheetPath, contactBytes); }
+                finally { UnityEngine.Object.DestroyImmediate(contact); }
+            }
+            finally
+            {
+                foreach (var tile in tiles) UnityEngine.Object.DestroyImmediate(tile);
+                UnityEngine.Object.DestroyImmediate(tempGo);
+            }
+
+            var contactProof = ScreenshotToolSupport.VerifyScreenshotArtifact(contactSheetPath, "png");
+            var result = new Result
+            {
+                Center = new double[] { center.x, center.y, center.z }, Count = 6,
+                ContactSheet = new ScreenshotArtifactEntry { Source = "surround-contact-sheet", Path = contactSheetPath, Width = width * 3, Height = height * 2, Format = "png", SizeBytes = contactProof.SizeBytes, Sha256 = contactProof.Sha256 },
+                Artifacts = artifacts
+            };
+            if (request.InlineBase64 && contactBytes != null && contactBytes.Length <= 512 * 1024)
+            {
+                result.ImageBase64 = Convert.ToBase64String(contactBytes);
+                result.ImageWidth = width * 3;
+                result.ImageHeight = height * 2;
+                result.ImageMimeType = "image/png";
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(result);
+        }
+
+        private static List<SurroundShot> BuildPlannedShots(string[] labels, List<string> shotPaths, int width, int height, Vector3[] positions)
+        {
+            var shots = new List<SurroundShot>();
+            for (var i = 0; i < labels.Length; i++)
+            {
+                shots.Add(new SurroundShot
+                {
+                    Angle = labels[i],
+                    Artifact = new ScreenshotArtifactEntry { Source = "surround", Path = shotPaths[i], Camera = "surround:" + labels[i], Width = width, Height = height, Format = "png" },
+                    CameraPosition = new double[] { positions[i].x, positions[i].y, positions[i].z }
+                });
+            }
+            return shots;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scriptable-object/ScriptableObjectToolSupport.cs

@@ -0,0 +1,196 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scriptable-object 域 IUnityCliTool 共享的基础设施 helper:路径校验、类型解析、
+    /// 资产加载、属性序列化。仅供 scriptable-object 域自包含工具复用;
+    /// 不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    public static class ScriptableObjectToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求,避免脏状态写入。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            if (EditorApplication.isCompiling)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_COMPILING", "Unity Editor is compiling scripts.", "Wait for Unity to finish compiling and retry.", transient: true, retryAfterMs: 5000);
+            }
+            if (EditorApplication.isUpdating)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_IMPORTING", "Unity Editor is importing assets.", "Wait for Unity to finish importing and retry.", transient: true, retryAfterMs: 5000);
+            }
+            if (UnityCliBridge.IsPlayModeChanging())
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_PLAY_MODE", "Unity Editor is entering or exiting Play mode.", "Wait for Play mode transition to complete and retry.", transient: true, retryAfterMs: 3000);
+            }
+            if (BuildPipeline.isBuildingPlayer)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_UNITY_BUSY", "Unity Editor is building the player.", "Wait for the build to complete and retry.", transient: true, retryAfterMs: 10000);
+            }
+        }
+
+        /// <summary>Assets/ 路径规范化:反斜杠转正斜杠并去首尾空白。</summary>
+        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_SCRIPTABLE_OBJECT_PATH_INVALID", "ScriptableObject path must not contain '.' or '..' segments: " + path, "Pass a canonical Assets/*.asset path without path traversal segments.");
+            return path;
+        }
+
+        /// <summary>Unity 工程根目录(Assets 的父目录)。</summary>
+        public static string ProjectRoot()
+        {
+            return Directory.GetParent(Application.dataPath).FullName;
+        }
+
+        /// <summary>确保资产目录存在,缺失则创建并刷新 AssetDatabase。</summary>
+        public static void CreateAssetDirectory(string assetPath)
+        {
+            var path = RequireScriptableObjectPath(assetPath);
+            var fullPath = Path.GetFullPath(Path.Combine(ProjectRoot(), path.Replace('/', Path.DirectorySeparatorChar)));
+            var assetsPath = Path.GetFullPath(Application.dataPath).TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+            if (!fullPath.StartsWith(assetsPath + Path.DirectorySeparatorChar, StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_PATH_INVALID", "ScriptableObject path resolves outside Application.dataPath: " + path, "Pass a canonical Assets/*.asset path.");
+            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();
+        }
+
+        /// <summary>校验 Assets/*.asset 路径。</summary>
+        public static string RequireScriptableObjectPath(string rawPath)
+        {
+            var path = NormalizeAssetPath(rawPath);
+            if (string.IsNullOrEmpty(path) || !path.StartsWith("Assets/", System.StringComparison.OrdinalIgnoreCase) || !path.EndsWith(".asset", System.StringComparison.OrdinalIgnoreCase))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_PATH_INVALID", "ScriptableObject path must be under Assets/ and end with .asset: " + path, "Pass a Unity asset path such as Assets/Data/Config.asset.");
+            }
+            return path;
+        }
+
+        /// <summary>按全名或类名查找 ScriptableObject 类型。</summary>
+        public static System.Type ResolveScriptableObjectType(string typeName)
+        {
+            if (string.IsNullOrEmpty(typeName))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_TYPE_REQUIRED", "scriptable-object.create requires type <ScriptableObjectType>.", "Pass a full type name or a unique class name deriving from ScriptableObject.");
+            }
+            // 完整类型名优先。
+            System.Type type = null;
+            foreach (var assembly in System.AppDomain.CurrentDomain.GetAssemblies())
+            {
+                System.Type candidate;
+                try { candidate = assembly.GetType(typeName, false); } catch { continue; }
+                if (candidate != null) { type = candidate; break; }
+            }
+            // 未命中完整名称时要求类名唯一匹配。
+            if (type == null)
+            {
+                foreach (var assembly in System.AppDomain.CurrentDomain.GetAssemblies())
+                {
+                    System.Type[] types;
+                    try { types = assembly.GetTypes(); }
+                    catch (ReflectionTypeLoadException exception) { types = exception.Types; }
+                    catch { continue; }
+                    foreach (var candidate in types)
+                    {
+                        if (candidate != null && string.Equals(candidate.Name, typeName, System.StringComparison.Ordinal))
+                        {
+                            type = candidate;
+                            break;
+                        }
+                    }
+                    if (type != null) break;
+                }
+            }
+            if (type == null || !typeof(ScriptableObject).IsAssignableFrom(type) || type.IsAbstract || type.ContainsGenericParameters)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_TYPE_NOT_FOUND", "ScriptableObject type is not instantiable: " + typeName, "Use a concrete, non-generic type deriving from UnityEngine.ScriptableObject.");
+            }
+            return type;
+        }
+
+        /// <summary>加载 ScriptableObject 资产,不存在抛错。</summary>
+        public static ScriptableObject LoadScriptableObject(string path)
+        {
+            var asset = AssetDatabase.LoadAssetAtPath<ScriptableObject>(path);
+            if (asset == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_NOT_FOUND", "ScriptableObject asset not found: " + path, "Check the path or run tools run asset.search --input '{\"filter\":\"t:ScriptableObject\"}' to discover the path.");
+            }
+            return asset;
+        }
+
+        /// <summary>构造 ScriptableObject 摘要 DTO。</summary>
+        public static ScriptableObjectInfo BuildScriptableObjectInfo(string path, ScriptableObject asset)
+        {
+            var info = new ScriptableObjectInfo
+            {
+                Path = path,
+                Guid = AssetDatabase.AssetPathToGUID(path),
+                Name = asset.name,
+                Type = asset.GetType().FullName,
+                Properties = new Dictionary<string, string>()
+            };
+            foreach (var field in asset.GetType().GetFields(BindingFlags.Instance | BindingFlags.Public))
+            {
+                info.Properties[field.Name] = Convert.ToString(field.GetValue(asset), CultureInfo.InvariantCulture);
+            }
+            foreach (var property in asset.GetType().GetProperties(BindingFlags.Instance | BindingFlags.Public))
+            {
+                if (!property.CanRead || property.GetIndexParameters().Length > 0) continue;
+                try { info.Properties[property.Name] = Convert.ToString(property.GetValue(asset, null), CultureInfo.InvariantCulture); }
+                catch { }
+            }
+            return info;
+        }
+
+        /// <summary>输出 ScriptableObject 类型摘要 DTO。</summary>
+        public static ScriptableObjectTypeEntry BuildTypeEntry(System.Type type)
+        {
+            return new ScriptableObjectTypeEntry
+            {
+                Name = type.Name,
+                FullName = type.FullName,
+                Assembly = type.Assembly.GetName().Name,
+                Namespace = type.Namespace,
+                Abstract = type.IsAbstract
+            };
+        }
+    }
+
+    /// <summary>ScriptableObject 摘要信息,scriptable-object 域工具 Result 共享。</summary>
+    public sealed class ScriptableObjectInfo
+    {
+        public string Path { get; set; }
+        public string Guid { get; set; }
+        public string Name { get; set; }
+        public string Type { get; set; }
+        public Dictionary<string, string> Properties { get; set; }
+    }
+
+    /// <summary>ScriptableObject 类型摘要,scriptable-object.list-types 工具 Result 共享。</summary>
+    public sealed class ScriptableObjectTypeEntry
+    {
+        public string Name { get; set; }
+        public string FullName { get; set; }
+        public string Assembly { get; set; }
+        public string Namespace { get; set; }
+        public bool Abstract { get; set; }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/scriptable-object/create.cs

@@ -0,0 +1,79 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// scriptable-object.create — 在 Assets/*.asset 创建新 ScriptableObject 资产。
+    /// </summary>
+    public class ScriptableObjectCreateTool : IUnityCliTool<ScriptableObjectCreateTool.Request, ScriptableObjectCreateTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Path { get; set; }
+            [UnityCliRequired]
+            public string Type { get; set; }
+            public bool Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool DryRun { get; set; }
+            public ScriptableObjectInfo ScriptableObject { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "scriptable-object.create",
+            Summary = "Create a new ScriptableObject asset at an Assets/*.asset path.",
+            Description = "Create a new ScriptableObject asset at an Assets/*.asset path. Resolves the type by full name or class name. Refuses to overwrite an existing asset unless overwrite=true. Supports dry-run.",
+            Group = "scriptable-object",
+            DestructiveHint = true,
+            SideEffects = new[] { "asset-write" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            SupportsDryRun = true,
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a ScriptableObject", Input = new Request { Path = "Assets/Data/Config.asset", Type = "MyConfig" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            ScriptableObjectToolSupport.EnsureEditorNotBusy("scriptable-object.create");
+            var path = ScriptableObjectToolSupport.RequireScriptableObjectPath(request.Path);
+            var type = ScriptableObjectToolSupport.ResolveScriptableObjectType(request.Type);
+            if (AssetDatabase.LoadAssetAtPath<ScriptableObject>(path) != null && !request.Overwrite)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_EXISTS", "ScriptableObject asset already exists: " + path, "Pass overwrite=true or choose a different Assets/*.asset path.");
+            }
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true });
+            }
+            ctx.CommitEffect();
+            ScriptableObjectToolSupport.CreateAssetDirectory(path);
+            if (request.Overwrite && !string.IsNullOrEmpty(AssetDatabase.AssetPathToGUID(path)))
+            {
+                AssetDatabase.DeleteAsset(path);
+            }
+            var asset = ScriptableObject.CreateInstance(type);
+            AssetDatabase.CreateAsset(asset, path);
+            AssetDatabase.SaveAssets();
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            var observedAsset = AssetDatabase.LoadAssetAtPath<ScriptableObject>(path);
+            if (observedAsset == null || observedAsset.GetType() != type)
+                throw new UnityCliBridge.BridgeCommandException("E_SCRIPTABLE_OBJECT_CREATE_READBACK_FAILED", "Created ScriptableObject could not be reloaded with the requested type: " + path, "Check Unity Console for asset import errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ScriptableObject = ScriptableObjectToolSupport.BuildScriptableObjectInfo(path, observedAsset)
+            });
+        }
+    }
+}
+#endif