@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/build/scene/add.cs

@@ -0,0 +1,45 @@
+#if UNITY_EDITOR
+using System.Linq;
+using UnityEditor;
+
+namespace UnityCli
+{
+    public class BuildSceneAddTool : IUnityCliTool<BuildSceneAddTool.Request, BuildSceneMutationResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Path { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "build.scene.add", Summary = "Add an enabled scene to persistent Unity Build Settings.", Description = "Adds path to EditorBuildSettings as an enabled scene when absent. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Add main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } };
+        public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = BuildToolSupport.NormalizeAssetPath(request.Path);
+            if (string.IsNullOrEmpty(path))
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_PATH_REQUIRED", "build.scene.add requires path.", "Pass a scene path such as Assets/Scenes/Main.unity.");
+            if (!path.StartsWith("Assets/", System.StringComparison.Ordinal) || !path.EndsWith(".unity", System.StringComparison.OrdinalIgnoreCase) || path.Contains(".."))
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_PATH_INVALID", "Build scene path must be a canonical Assets/*.unity path without traversal.", "Pass an existing path such as Assets/Scenes/Main.unity.");
+            if (AssetDatabase.LoadAssetAtPath<SceneAsset>(path) == null)
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_NOT_FOUND", "Scene asset not found: " + path, "Pass an existing Assets/*.unity scene asset.");
+            var scenes = BuildSceneStateTool.ReadScenes();
+            var existingIndex = System.Array.FindIndex(scenes, scene => scene.path == path);
+            var changed = existingIndex < 0 || !scenes[existingIndex].enabled;
+            if (!ctx.DryRun && changed)
+            {
+                ctx.CommitEffect();
+                if (existingIndex < 0)
+                    scenes = scenes.Concat(new[] { new EditorBuildSettingsScene(path, true) }).ToArray();
+                else
+                    scenes[existingIndex] = new EditorBuildSettingsScene(path, true);
+                EditorBuildSettings.scenes = scenes;
+                scenes = BuildSceneStateTool.ReadScenes();
+                if (!scenes.Any(scene => scene.path == path && scene.enabled))
+                    throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_ADD_MISMATCH", "Build Settings did not add enabled scene: " + path, "Inspect build.scene.list and retry.");
+            }
+            return new(new BuildSceneMutationResult
+            {
+                Count = scenes.LongLength,
+                Changed = !ctx.DryRun && changed,
+                NoOpReason = !ctx.DryRun && !changed ? "scene-already-enabled" : null,
+                DryRun = ctx.DryRun
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/build/scene/disable.cs

@@ -0,0 +1,3 @@
+#if UNITY_EDITOR
+namespace UnityCli { public class BuildSceneDisableTool : IUnityCliTool<BuildSceneDisableTool.Request, BuildSceneMutationResult> { public sealed class Request { [UnityCliRequired] public string Path { get; set; } } public ToolDescriptor Describe() => new() { Name = "build.scene.disable", Summary = "Disable a scene in persistent Unity Build Settings.", Description = "Marks an existing Build Settings scene as disabled. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Disable main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } }; public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { return BuildSceneStateTool.Execute(request.Path, false, "build.scene.disable", ctx); } } }
+#endif

package/unitypkg/Editor/Tools/build/scene/enable.cs

@@ -0,0 +1,4 @@
+#if UNITY_EDITOR
+using System.Linq; using UnityEditor;
+namespace UnityCli { public class BuildSceneEnableTool : IUnityCliTool<BuildSceneEnableTool.Request, BuildSceneMutationResult> { public sealed class Request { [UnityCliRequired] public string Path { get; set; } } public ToolDescriptor Describe() => new() { Name = "build.scene.enable", Summary = "Enable a scene in persistent Unity Build Settings.", Description = "Marks an existing Build Settings scene as enabled. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Enable main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } }; public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { return BuildSceneStateTool.Execute(request.Path, true, "build.scene.enable", ctx); } } }
+#endif

package/unitypkg/Editor/Tools/build/scene/list.cs

@@ -0,0 +1,4 @@
+#if UNITY_EDITOR
+using System.Collections.Generic; using UnityEditor;
+namespace UnityCli { public class BuildSceneListTool : IUnityCliTool<BuildSceneListTool.Request, BuildSceneListResult> { public sealed class Request { } public ToolDescriptor Describe() => new() { Name = "build.scene.list", Summary = "List scenes registered in Unity Build Settings.", Description = "Returns every Build Settings scene with path, enabled state, and build index. Read-only and available in Edit and Play mode.", Group = "build",Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "List build scenes", Input = new Request() } } }; public System.Threading.Tasks.ValueTask<BuildSceneListResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) { var scenes = EditorBuildSettings.scenes ?? new EditorBuildSettingsScene[0]; var entries = new List<BuildSceneEntry>(); for (var i = 0; i < scenes.Length; i++) entries.Add(new BuildSceneEntry { Path = BuildToolSupport.NormalizeAssetPath(scenes[i].path), Enabled = scenes[i].enabled, BuildIndex = i }); return new(new BuildSceneListResult { Count = scenes.Length, Scenes = entries }); } } }
+#endif

package/unitypkg/Editor/Tools/build/scene/remove.cs

@@ -0,0 +1,29 @@
+#if UNITY_EDITOR
+using System.Linq;
+using UnityEditor;
+
+namespace UnityCli
+{
+    public class BuildSceneRemoveTool : IUnityCliTool<BuildSceneRemoveTool.Request, BuildSceneMutationResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Path { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "build.scene.remove", Summary = "Remove a scene from persistent Unity Build Settings.", Description = "Removes path from EditorBuildSettings. dryRun=true previews without writing. Available in Edit and Play mode.", Group = "build",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "project-settings-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Remove main scene", Input = new Request { Path = "Assets/Scenes/Main.unity" }, Execution = new ToolExampleExecution { DryRun = true } } } };
+        public System.Threading.Tasks.ValueTask<BuildSceneMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = BuildToolSupport.NormalizeAssetPath(request.Path);
+            if (string.IsNullOrEmpty(path))
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_PATH_REQUIRED", "build.scene.remove requires path.", "Pass a scene path such as Assets/Scenes/Main.unity.");
+            var scenes = BuildSceneStateTool.ReadScenes();
+            if (!ctx.DryRun && scenes.Any(scene => scene.path == path))
+            {
+                ctx.CommitEffect();
+                EditorBuildSettings.scenes = scenes.Where(scene => scene.path != path).ToArray();
+                scenes = BuildSceneStateTool.ReadScenes();
+                if (scenes.Any(scene => scene.path == path))
+                    throw new UnityCliBridge.BridgeCommandException("E_BUILD_SCENE_REMOVE_MISMATCH", "Build Settings did not remove scene: " + path, "Inspect build.scene.list and retry.");
+            }
+            return new(new BuildSceneMutationResult { Count = scenes.LongLength, DryRun = ctx.DryRun });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/build/settings/get.cs

@@ -0,0 +1,3 @@
+#if UNITY_EDITOR
+namespace UnityCli { public class BuildSettingsGetTool : IUnityCliTool<BuildSettingsGetTool.Request, BuildSettingsResult> { public sealed class Request { } public ToolDescriptor Describe() => new() { Name = "build.settings.get", Summary = "Read persistent Unity PlayerSettings build configuration.", Description = "Returns product name, bundle version, company name, application identifier, scripting backend, and API compatibility level without writing settings. Available in Edit and Play mode.", Group = "build",Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read PlayerSettings", Input = new Request() } } }; public System.Threading.Tasks.ValueTask<BuildSettingsResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default) => new(BuildSettingsToolSupport.Read()); } }
+#endif

package/unitypkg/Editor/Tools/build/settings/set.cs

@@ -0,0 +1,74 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    public class BuildSettingsSetTool : IUnityCliTool<BuildSettingsSetTool.Request, BuildSettingsMutationResult>
+    {
+        public sealed class Request
+        {
+            public string ProductName { get; set; }
+            public string BundleVersion { get; set; }
+            public string CompanyId { get; set; }
+            public string ApplicationIdentifier { get; set; }
+            public string ScriptingBackend { get; set; }
+            public string ApiCompatibilityLevel { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "build.settings.set", Summary = "Update persistent Unity PlayerSettings build configuration, with dry-run support.",
+            Description = "Updates provided PlayerSettings fields: productName, bundleVersion, companyId, applicationIdentifier, scriptingBackend, and apiCompatibilityLevel. dryRun=true previews without writing. Available in Edit and Play mode.",
+            Group = "build",DestructiveHint = true, SupportsDryRun = true,
+            SideEffects = new[] { "player-settings-write" }, Target = "editor", PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000,
+            Examples = new[] { new ToolExample { Description = "Set product name", Input = new Request { ProductName = "My Game" }, Execution = new ToolExampleExecution { DryRun = true } } }
+        };
+
+        /// <summary>先解析全部枚举和空请求，再以单一 commit boundary 写入并读回 PlayerSettings。</summary>
+        public System.Threading.Tasks.ValueTask<BuildSettingsMutationResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var hasValue = !string.IsNullOrEmpty(request.ProductName)
+                || !string.IsNullOrEmpty(request.BundleVersion)
+                || !string.IsNullOrEmpty(request.CompanyId)
+                || !string.IsNullOrEmpty(request.ApplicationIdentifier)
+                || !string.IsNullOrEmpty(request.ScriptingBackend)
+                || !string.IsNullOrEmpty(request.ApiCompatibilityLevel);
+            if (!hasValue)
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SETTINGS_EMPTY", "build.settings.set requires at least one setting.", "Pass one or more documented PlayerSettings fields.");
+
+            ScriptingImplementation scriptingBackend = default;
+            if (!string.IsNullOrEmpty(request.ScriptingBackend) && !Enum.TryParse(request.ScriptingBackend, true, out scriptingBackend))
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SETTINGS_ENUM_INVALID", "Unknown scriptingBackend: " + request.ScriptingBackend, "Pass a Unity ScriptingImplementation enum name.");
+            ApiCompatibilityLevel compatibilityLevel = default;
+            if (!string.IsNullOrEmpty(request.ApiCompatibilityLevel) && !Enum.TryParse(request.ApiCompatibilityLevel, true, out compatibilityLevel))
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SETTINGS_ENUM_INVALID", "Unknown apiCompatibilityLevel: " + request.ApiCompatibilityLevel, "Pass a Unity ApiCompatibilityLevel enum name.");
+
+            if (ctx.DryRun)
+                return new(new BuildSettingsMutationResult { Changed = new List<string> { "productName", "bundleVersion", "companyId", "applicationIdentifier", "scriptingBackend", "apiCompatibilityLevel" }.FindAll(name => (name == "productName" && !string.IsNullOrEmpty(request.ProductName)) || (name == "bundleVersion" && !string.IsNullOrEmpty(request.BundleVersion)) || (name == "companyId" && !string.IsNullOrEmpty(request.CompanyId)) || (name == "applicationIdentifier" && !string.IsNullOrEmpty(request.ApplicationIdentifier)) || (name == "scriptingBackend" && !string.IsNullOrEmpty(request.ScriptingBackend)) || (name == "apiCompatibilityLevel" && !string.IsNullOrEmpty(request.ApiCompatibilityLevel))), DryRun = true });
+
+            ctx.CommitEffect();
+            var changed = new List<string>();
+            if (!string.IsNullOrEmpty(request.ProductName)) { PlayerSettings.productName = request.ProductName; changed.Add("productName"); }
+            if (!string.IsNullOrEmpty(request.BundleVersion)) { PlayerSettings.bundleVersion = request.BundleVersion; changed.Add("bundleVersion"); }
+            if (!string.IsNullOrEmpty(request.CompanyId)) { PlayerSettings.companyName = request.CompanyId; changed.Add("companyId"); }
+            if (!string.IsNullOrEmpty(request.ApplicationIdentifier)) { PlayerSettings.SetApplicationIdentifier(BuildTargetGroup.Unknown, request.ApplicationIdentifier); changed.Add("applicationIdentifier"); }
+            if (!string.IsNullOrEmpty(request.ScriptingBackend)) { PlayerSettings.SetScriptingBackend(BuildTargetGroup.Unknown, scriptingBackend); changed.Add("scriptingBackend"); }
+            if (!string.IsNullOrEmpty(request.ApiCompatibilityLevel)) { PlayerSettings.SetApiCompatibilityLevel(BuildTargetGroup.Unknown, compatibilityLevel); changed.Add("apiCompatibilityLevel"); }
+
+            var result = BuildSettingsToolSupport.Read();
+            var mismatch = (!string.IsNullOrEmpty(request.ProductName) && result.ProductName != request.ProductName)
+                || (!string.IsNullOrEmpty(request.BundleVersion) && result.BundleVersion != request.BundleVersion)
+                || (!string.IsNullOrEmpty(request.CompanyId) && result.CompanyId != request.CompanyId)
+                || (!string.IsNullOrEmpty(request.ApplicationIdentifier) && result.ApplicationIdentifier != request.ApplicationIdentifier)
+                || (!string.IsNullOrEmpty(request.ScriptingBackend) && !string.Equals(result.ScriptingBackend, scriptingBackend.ToString(), StringComparison.OrdinalIgnoreCase))
+                || (!string.IsNullOrEmpty(request.ApiCompatibilityLevel) && !string.Equals(result.ApiCompatibilityLevel, compatibilityLevel.ToString(), StringComparison.OrdinalIgnoreCase));
+            if (mismatch)
+                throw new UnityCliBridge.BridgeCommandException("E_BUILD_SETTINGS_STATE_MISMATCH", "PlayerSettings readback did not match every requested value.", "Inspect build.settings.get before retrying.");
+            return new(new BuildSettingsMutationResult { Changed = changed });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/camera/CameraToolSupport.cs

@@ -0,0 +1,292 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using System.Security.Cryptography;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera 域 IUnityCliTool 共享的基础设施 helper:相机解析、相机信息构造、
+    /// 截图捕获、清屏标志解析、忙状态拦截。仅供 camera 域自包含工具复用;
+    /// 不实现 IUnityCliTool,不参与工具发现。
+    /// </summary>
+    public static class CameraToolSupport
+    {
+        /// <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>解析 Camera:空 target 返回主相机或第一个相机;否则按名称/实例ID/层级路径匹配。</summary>
+        public static Camera ResolveCamera(string target)
+        {
+            var cameras = Camera.allCameras;
+            if (string.IsNullOrEmpty(target))
+            {
+                return Camera.main ?? (cameras.Length > 0 ? cameras[0] : null);
+            }
+            foreach (var camera in cameras)
+            {
+                if (camera.name == target
+                    || camera.GetInstanceID().ToString(CultureInfo.InvariantCulture) == target
+                    || HierarchyPath(camera.gameObject) == target)
+                {
+                    return camera;
+                }
+            }
+            return null;
+        }
+
+        /// <summary>构造 Camera 摘要信息 DTO。</summary>
+        public static CameraInfo BuildCameraInfo(Camera camera)
+        {
+            return new CameraInfo
+            {
+                Id = camera.GetInstanceID(),
+                Name = camera.name,
+                Path = HierarchyPath(camera.gameObject),
+                Tag = camera.tag,
+                Enabled = camera.enabled,
+                ClearFlags = camera.clearFlags.ToString(),
+                Projection = camera.orthographic ? "orthographic" : "perspective",
+                FieldOfView = camera.fieldOfView,
+                OrthographicSize = camera.orthographicSize,
+                Depth = camera.depth,
+                TargetTexture = camera.targetTexture != null ? camera.targetTexture.name : null,
+                PixelWidth = camera.pixelWidth,
+                PixelHeight = camera.pixelHeight
+            };
+        }
+
+        /// <summary>解析 CameraClearFlags 枚举值(大小写不敏感)。</summary>
+        public static CameraClearFlags ParseCameraClearFlags(string value)
+        {
+            CameraClearFlags parsed;
+            if (!Enum.TryParse<CameraClearFlags>(value, true, out parsed))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_CLEAR_FLAGS_INVALID", "Unsupported Camera clearFlags value: " + value, "Use Skybox, SolidColor, Depth, or Nothing.");
+            }
+            return parsed;
+        }
+
+        public static void ValidateFloatRange(double? value, string field, double min, double max)
+        {
+            if (!value.HasValue) return;
+            if (double.IsNaN(value.Value) || double.IsInfinity(value.Value) || value.Value < min || value.Value > max || value.Value < -float.MaxValue || value.Value > float.MaxValue)
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_VALUE_INVALID", field + " must be finite and representable as a Unity float.", "Pass a finite value in the documented range.");
+        }
+
+        /// <summary>截图尺寸必须在 1..8192 像素之间。</summary>
+        public static int ClampScreenshotDimension(int value, string name)
+        {
+            if (value < 1 || value > 8192)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_SIZE_INVALID", "Camera screenshot " + name + " must be between 1 and 8192 pixels: " + value.ToString(CultureInfo.InvariantCulture), "Use a smaller width/height before retrying.");
+            }
+            return value;
+        }
+
+        /// <summary>解析截图输出绝对路径;相对路径解析到 Unity 工程根目录下。</summary>
+        public static string ResolveScreenshotOutputPath(string rawPath)
+        {
+            if (string.IsNullOrEmpty(rawPath))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_PATH_REQUIRED", "Camera screenshot requires a path.", "Pass --output <path> or a positional screenshot path.");
+            }
+            var normalized = rawPath.Replace('\\', Path.DirectorySeparatorChar).Replace('/', Path.DirectorySeparatorChar);
+            return Path.GetFullPath(Path.IsPathRooted(normalized) ? normalized : Path.Combine(ProjectRoot(), normalized));
+        }
+
+        /// <summary>推断图片格式:显式 format > 路径扩展名 > png;仅接受 png/jpg。</summary>
+        public static string NormalizeFormat(string rawFormat, string outputPath)
+        {
+            var fmt = string.IsNullOrEmpty(rawFormat) ? Path.GetExtension(outputPath).TrimStart('.').ToLowerInvariant() : rawFormat.ToLowerInvariant();
+            if (string.IsNullOrEmpty(fmt)) fmt = "png";
+            if (fmt == "jpeg") fmt = "jpg";
+            if (fmt != "png" && fmt != "jpg")
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_FORMAT_UNSUPPORTED", "Screenshot format must be png or jpg.");
+            }
+            return fmt;
+        }
+
+        /// <summary>创建截图输出目录(缺失时)。</summary>
+        public static void CreateScreenshotDirectory(string outputPath)
+        {
+            try
+            {
+                Directory.CreateDirectory(Path.GetDirectoryName(outputPath));
+            }
+            catch (Exception exception)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to create screenshot output directory: " + exception.Message);
+            }
+        }
+
+        /// <summary>写入截图后重新读取字节、校验格式并返回稳定 artifact proof。</summary>
+        public static CameraArtifactProof WriteScreenshotBytes(string outputPath, byte[] bytes)
+        {
+            if (bytes == null || bytes.Length == 0)
+                throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_ENCODE_FAILED", "Screenshot encoder returned no bytes.", "Check the Camera render state and retry.");
+            try { File.WriteAllBytes(outputPath, bytes); }
+            catch (Exception exception) { throw new UnityCliBridge.BridgeCommandException("E_IO_ERROR", "Failed to write screenshot output: " + exception.Message); }
+            return VerifyScreenshotArtifact(outputPath, Path.GetExtension(outputPath).TrimStart('.'));
+        }
+
+        /// <summary>artifact proof 必须来自写后 fresh readback，不能只依赖 Exists 或原始编码 bytes。</summary>
+        public static CameraArtifactProof VerifyScreenshotArtifact(string outputPath, string format)
+        {
+            if (!File.Exists(outputPath)) throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_WRITE_PROOF_MISSING", "Screenshot output was not written: " + outputPath, "Check destination path and permissions, then retry.");
+            var bytes = File.ReadAllBytes(outputPath);
+            var normalized = NormalizeFormat(format, outputPath);
+            var valid = normalized == "png"
+                ? bytes.Length >= 8 && bytes[0] == 0x89 && bytes[1] == 0x50 && bytes[2] == 0x4e && bytes[3] == 0x47 && bytes[4] == 0x0d && bytes[5] == 0x0a && bytes[6] == 0x1a && bytes[7] == 0x0a
+                : bytes.Length >= 3 && bytes[0] == 0xff && bytes[1] == 0xd8 && bytes[2] == 0xff;
+            if (!valid) throw new UnityCliBridge.BridgeCommandException("E_SCREENSHOT_WRITE_PROOF_MISSING", "Screenshot output is empty or does not match its requested format: " + outputPath, "Use a .png or .jpg output path and retry.");
+            using (var sha = SHA256.Create()) return new CameraArtifactProof { SizeBytes = bytes.LongLength, Sha256 = string.Concat(Array.ConvertAll(sha.ComputeHash(bytes), value => value.ToString("x2"))) };
+        }
+
+        /// <summary>渲染指定 Camera 到 RenderTexture 并编码为图片字节,返回捕获结果。捕获后恢复相机状态。</summary>
+        public static CameraCapture CaptureCamera(Camera camera, int width, int height, bool transparent, int quality, string outputPath, string format, bool overwrite, bool inlineBase64)
+        {
+            if (File.Exists(outputPath) && !overwrite)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_OUTPUT_EXISTS", "Screenshot output already exists: " + outputPath, "Pass overwrite=true or choose a different output path.");
+            }
+            CreateScreenshotDirectory(outputPath);
+            var previousTarget = camera.targetTexture;
+            var previousActive = RenderTexture.active;
+            var previousClearFlags = camera.clearFlags;
+            var previousBackground = camera.backgroundColor;
+            var renderTexture = new RenderTexture(width, height, 24, RenderTextureFormat.ARGB32);
+            var texture = new Texture2D(width, height, transparent ? TextureFormat.ARGB32 : TextureFormat.RGB24, false);
+            try
+            {
+                camera.targetTexture = renderTexture;
+                if (transparent)
+                {
+                    camera.clearFlags = CameraClearFlags.SolidColor;
+                    camera.backgroundColor = new Color(0f, 0f, 0f, 0f);
+                }
+                camera.Render();
+                RenderTexture.active = renderTexture;
+                texture.ReadPixels(new Rect(0, 0, width, height), 0, 0);
+                texture.Apply();
+                var bytes = format == "jpg" ? texture.EncodeToJPG(quality) : texture.EncodeToPNG();
+                var artifact = WriteScreenshotBytes(outputPath, bytes);
+                var capture = new CameraCapture
+                {
+                    ScreenshotPath = outputPath,
+                    ArtifactPath = outputPath,
+                    Source = "camera",
+                    SizeBytes = artifact.SizeBytes,
+                    Sha256 = artifact.Sha256
+                };
+                // inlineBase64 仅在图片字节小于内联上限时附带,避免大 base64 撑爆 JSON 响应
+                const int InlineImageMaxBytes = 512 * 1024;
+                if (inlineBase64 && bytes != null && bytes.Length <= InlineImageMaxBytes)
+                {
+                    capture.ImageBase64 = Convert.ToBase64String(bytes);
+                    capture.ImageWidth = width;
+                    capture.ImageHeight = height;
+                    capture.ImageMimeType = format == "jpg" ? "image/jpeg" : "image/png";
+                }
+                return capture;
+            }
+            finally
+            {
+                RenderTexture.active = previousActive;
+                camera.targetTexture = previousTarget;
+                camera.clearFlags = previousClearFlags;
+                camera.backgroundColor = previousBackground;
+                UnityEngine.Object.DestroyImmediate(texture);
+                renderTexture.Release();
+                UnityEngine.Object.DestroyImmediate(renderTexture);
+            }
+        }
+
+        /// <summary>Unity 工程根目录(Assets 的父目录)。</summary>
+        public static string ProjectRoot()
+        {
+            return Directory.GetParent(UnityEngine.Application.dataPath).FullName;
+        }
+
+        /// <summary>构造 GameObject 层级路径(A/B/C)。</summary>
+        public static string HierarchyPath(GameObject gameObject)
+        {
+            var names = new Stack<string>();
+            var current = gameObject.transform;
+            while (current != null)
+            {
+                names.Push(current.name);
+                current = current.parent;
+            }
+            return string.Join("/", names.ToArray());
+        }
+    }
+
+    /// <summary>Camera 摘要信息,camera 域工具 Result 共享。</summary>
+    public sealed class CameraInfo
+    {
+        public long Id { get; set; }
+        public string Name { get; set; }
+        public string Path { get; set; }
+        public string Tag { get; set; }
+        public bool Enabled { get; set; }
+        public string ClearFlags { get; set; }
+        public string Projection { get; set; }
+        public double FieldOfView { get; set; }
+        public double OrthographicSize { get; set; }
+        public double Depth { get; set; }
+        public string TargetTexture { get; set; }
+        public long PixelWidth { get; set; }
+        public long PixelHeight { get; set; }
+    }
+
+    /// <summary>Camera 截图捕获结果,camera 域 screenshot/multiview 工具共享。</summary>
+    public sealed class CameraCapture
+    {
+        public string ScreenshotPath { get; set; }
+        public string ArtifactPath { get; set; }
+        public string Source { get; set; }
+        public string ImageBase64 { get; set; }
+        public long? ImageWidth { get; set; }
+        public long? ImageHeight { get; set; }
+        public string ImageMimeType { get; set; }
+        public long SizeBytes { get; set; }
+        public string Sha256 { get; set; }
+    }
+
+    public sealed class CameraArtifactProof { public long SizeBytes { get; set; } public string Sha256 { get; set; } }
+
+    /// <summary>计划副作用项,camera 域 mutation 工具 Result 共享。</summary>
+    public sealed class CameraPlannedEffect
+    {
+        public string Type { get; set; }
+        public string Target { get; set; }
+        public string Path { get; set; }
+        public string Property { get; set; }
+        public string Value { get; set; }
+    }
+}
+#endif

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

@@ -0,0 +1,114 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.create — 在激活场景创建 Camera GameObject,可设置父级/变换/投影/清屏/深度/MainCamera 标签。
+    /// </summary>
+    public class CameraCreateTool : IUnityCliTool<CameraCreateTool.Request, CameraCreateTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Name { get; set; }
+            public string Parent { get; set; }
+            public string Position { get; set; }
+            public string Rotation { get; set; }
+            public double? FieldOfView { get; set; }
+            public bool? Orthographic { get; set; }
+            public double? OrthographicSize { get; set; }
+            public string ClearFlags { get; set; }
+            public double? Depth { get; set; }
+            public string Tag { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public CameraInfo Camera { get; set; }
+            public List<CameraPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.create",
+            Summary = "Create a Unity Camera GameObject in the active scene with optional parent, transform, projection, clear flags, depth, and MainCamera tag.",
+            Description = "Create a Unity Camera GameObject in the active scene with optional parent, transform, projection, clear flags, depth, and MainCamera tag. Parent and enum inputs are validated before mutation to avoid partial objects.",
+            Group = "camera",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "component-add" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a perspective camera", Input = new Request { Name = "UnityCliAlignmentCamera", Position = "0,2,-6", Rotation = "15,0,0", FieldOfView = 60 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            CameraToolSupport.EnsureEditorNotBusy("camera.create");
+            var name = string.IsNullOrEmpty(request.Name) ? "Camera" : request.Name;
+            // 父级先解析,clearFlags 先校验,再创建 GameObject,避免半成品
+            var parentGo = string.IsNullOrEmpty(request.Parent) ? null : GameObjectToolSupport.ResolveUniqueTarget(request.Parent, "camera.create --parent <go> not found.");
+            var clearFlags = string.IsNullOrEmpty(request.ClearFlags) ? (CameraClearFlags?)null : CameraToolSupport.ParseCameraClearFlags(request.ClearFlags);
+            var position = string.IsNullOrEmpty(request.Position) ? (Vector3?)null : GameObjectToolSupport.ParseVector3(request.Position);
+            var rotation = string.IsNullOrEmpty(request.Rotation) ? (Vector3?)null : GameObjectToolSupport.ParseVector3(request.Rotation);
+            GameObjectToolSupport.ValidateMutationInputs(request.Tag, null);
+            CameraToolSupport.ValidateFloatRange(request.FieldOfView, "fieldOfView", 1d, 179d);
+            CameraToolSupport.ValidateFloatRange(request.OrthographicSize, "orthographicSize", double.Epsilon, float.MaxValue);
+            CameraToolSupport.ValidateFloatRange(request.Depth, "depth", -float.MaxValue, float.MaxValue);
+            var parentId = parentGo == null ? 0 : parentGo.GetInstanceID();
+
+            ctx.CommitEffect();
+            var gameObject = new GameObject(name);
+            if (parentGo != null)
+            {
+                gameObject.transform.SetParent(parentGo.transform, false);
+            }
+            var camera = gameObject.AddComponent<Camera>();
+            if (position.HasValue)
+            {
+                gameObject.transform.position = position.Value;
+            }
+            if (rotation.HasValue)
+            {
+                gameObject.transform.eulerAngles = rotation.Value;
+            }
+            if (request.FieldOfView.HasValue) camera.fieldOfView = (float)request.FieldOfView.Value;
+            if (request.Orthographic.HasValue) camera.orthographic = request.Orthographic.Value;
+            if (request.OrthographicSize.HasValue) camera.orthographicSize = (float)request.OrthographicSize.Value;
+            if (clearFlags.HasValue) camera.clearFlags = clearFlags.Value;
+            if (request.Depth.HasValue) camera.depth = (float)request.Depth.Value;
+            if (request.Tag == "MainCamera")
+            {
+                gameObject.tag = "MainCamera";
+            }
+            UnityCliSceneMutation.MarkSceneObjectDirty(gameObject);
+            UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+            var observed = EditorUtility.InstanceIDToObject(camera.GetInstanceID()) as Camera;
+            if (observed == null || observed.gameObject.name != name || (parentId == 0 && observed.transform.parent != null) || (parentId != 0 && (observed.transform.parent == null || observed.transform.parent.GetInstanceID() != parentId)) ||
+                (position.HasValue && observed.transform.position != position.Value) || (rotation.HasValue && observed.transform.eulerAngles != rotation.Value) ||
+                (request.FieldOfView.HasValue && !Mathf.Approximately(observed.fieldOfView, (float)request.FieldOfView.Value)) ||
+                (request.Orthographic.HasValue && observed.orthographic != request.Orthographic.Value) ||
+                (request.OrthographicSize.HasValue && !Mathf.Approximately(observed.orthographicSize, (float)request.OrthographicSize.Value)) ||
+                (clearFlags.HasValue && observed.clearFlags != clearFlags.Value) ||
+                (request.Depth.HasValue && !Mathf.Approximately(observed.depth, (float)request.Depth.Value)) ||
+                (request.Tag == "MainCamera" && observed.gameObject.tag != "MainCamera"))
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_CREATE_STATE_MISMATCH", "Created Camera did not satisfy the requested predicate.", "Inspect the Camera and retry after the Editor is idle.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Camera = CameraToolSupport.BuildCameraInfo(observed),
+                PlannedEffects = new List<CameraPlannedEffect>
+                {
+                    new CameraPlannedEffect { Type = "camera.create", Target = name }
+                }
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,49 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.info — 获取单个 Camera 的序列化设置。
+    /// </summary>
+    public class CameraInfoTool : IUnityCliTool<CameraInfoTool.Request, CameraInfoTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public CameraInfo Camera { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.info",
+            Summary = "Get one scene Camera's serializable settings by name, path, or instance id.",
+            Description = "Get one Camera's serializable settings. Resolves by Camera name, hierarchy path, or instance id; returns E_CAMERA_NOT_FOUND with recovery guidance when missing.",
+            Group = "camera",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Inspect Main Camera", Input = new Request { Target = "Main Camera" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var camera = CameraToolSupport.ResolveCamera(request.Target);
+            if (camera == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_NOT_FOUND", "Camera not found: " + request.Target, "Run tools run camera.list, then retry with a camera name, hierarchy path, or instance id from the result.");
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Camera = CameraToolSupport.BuildCameraInfo(camera) });
+        }
+    }
+}
+#endif