@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,119 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.lens — 更新 Camera 镜头/投影设置:FOV、正交模式/尺寸、近/远裁剪面、清屏标志、深度。
+    /// </summary>
+    public class CameraLensTool : IUnityCliTool<CameraLensTool.Request, CameraLensTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public double? FieldOfView { get; set; }
+            public bool? Orthographic { get; set; }
+            public double? OrthographicSize { get; set; }
+            public double? NearClipPlane { get; set; }
+            public double? FarClipPlane { get; set; }
+            public string ClearFlags { get; set; }
+            public double? Depth { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public CameraInfo Camera { get; set; }
+            public List<CameraPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.lens",
+            Summary = "Update Camera lens/projection settings: FOV, orthographic mode/size, near/far clip planes, clear flags, and depth.",
+            Description = "Update Camera lens/projection settings: FOV, orthographic mode/size, near/far clip planes, clear flags, and depth. Invalid clearFlags returns E_CAMERA_CLEAR_FLAGS_INVALID instead of silently doing nothing.",
+            Group = "camera",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set camera FOV", Input = new Request { Target = "UnityCliAlignmentCamera", FieldOfView = 45, NearClipPlane = 0.1, FarClipPlane = 1000 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(request.Target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "camera.lens requires target.", "Run tools run camera.list, then pass a camera name, hierarchy path, or instance id.");
+            }
+            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.");
+            }
+            if (!request.FieldOfView.HasValue && !request.Orthographic.HasValue && !request.OrthographicSize.HasValue && !request.NearClipPlane.HasValue && !request.FarClipPlane.HasValue && string.IsNullOrEmpty(request.ClearFlags) && !request.Depth.HasValue)
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_LENS_REQUEST_EMPTY", "camera.lens requires at least one lens setting.", "Pass a fieldOfView, projection, clipping, clearFlags, or depth value.");
+            CameraToolSupport.ValidateFloatRange(request.FieldOfView, "fieldOfView", 1d, 179d);
+            CameraToolSupport.ValidateFloatRange(request.OrthographicSize, "orthographicSize", double.Epsilon, float.MaxValue);
+            CameraToolSupport.ValidateFloatRange(request.NearClipPlane, "nearClipPlane", double.Epsilon, float.MaxValue);
+            CameraToolSupport.ValidateFloatRange(request.FarClipPlane, "farClipPlane", double.Epsilon, float.MaxValue);
+            CameraToolSupport.ValidateFloatRange(request.Depth, "depth", -float.MaxValue, float.MaxValue);
+            if (request.NearClipPlane.HasValue && request.FarClipPlane.HasValue && request.NearClipPlane.Value >= request.FarClipPlane.Value)
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_LENS_RANGE_INVALID", "nearClipPlane must be less than farClipPlane.", "Pass finite clipping planes with nearClipPlane < farClipPlane.");
+            // clearFlags 先校验再写入,避免部分应用
+            var clearFlags = string.IsNullOrEmpty(request.ClearFlags) ? (CameraClearFlags?)null : CameraToolSupport.ParseCameraClearFlags(request.ClearFlags);
+            var effects = new List<CameraPlannedEffect>();
+            var cameraId = camera.GetInstanceID();
+            ctx.CommitEffect();
+            if (request.FieldOfView.HasValue)
+            {
+                camera.fieldOfView = (float)request.FieldOfView.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "fieldOfView", Value = camera.fieldOfView.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+            if (request.Orthographic.HasValue)
+            {
+                camera.orthographic = request.Orthographic.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "orthographic", Value = camera.orthographic.ToString().ToLowerInvariant() });
+            }
+            if (request.OrthographicSize.HasValue)
+            {
+                camera.orthographicSize = (float)request.OrthographicSize.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "orthographicSize", Value = camera.orthographicSize.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+            if (request.NearClipPlane.HasValue)
+            {
+                camera.nearClipPlane = (float)request.NearClipPlane.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "nearClipPlane", Value = camera.nearClipPlane.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+            if (request.FarClipPlane.HasValue)
+            {
+                camera.farClipPlane = (float)request.FarClipPlane.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "farClipPlane", Value = camera.farClipPlane.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+            if (clearFlags.HasValue)
+            {
+                camera.clearFlags = clearFlags.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "clearFlags", Value = request.ClearFlags });
+            }
+            if (request.Depth.HasValue)
+            {
+                camera.depth = (float)request.Depth.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.lens", Property = "depth", Value = camera.depth.ToString(System.Globalization.CultureInfo.InvariantCulture) });
+            }
+            UnityCliSceneMutation.MarkSceneObjectDirty(camera);
+            var observed = EditorUtility.InstanceIDToObject(cameraId) as Camera;
+            if (observed == null || (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)) || (request.NearClipPlane.HasValue && !Mathf.Approximately(observed.nearClipPlane, (float)request.NearClipPlane.Value)) || (request.FarClipPlane.HasValue && !Mathf.Approximately(observed.farClipPlane, (float)request.FarClipPlane.Value)) || (clearFlags.HasValue && observed.clearFlags != clearFlags.Value) || (request.Depth.HasValue && !Mathf.Approximately(observed.depth, (float)request.Depth.Value)))
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_LENS_STATE_MISMATCH", "Camera lens 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 = effects });
+        }
+
+    }
+}
+#endif

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

@@ -0,0 +1,52 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.list — 列出场景中所有 Camera 组件的摘要信息。
+    /// </summary>
+    public class CameraListTool : IUnityCliTool<CameraListTool.Request, CameraListTool.Result>
+    {
+        public sealed class Request
+        {
+            // camera.list 无入参
+        }
+
+        public sealed class Result
+        {
+            public List<CameraInfo> Cameras { get; set; }
+            public long Count { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.list",
+            Summary = "List active scene Unity Camera components with name, hierarchy path, projection, FOV/ortho size, depth, targetTexture, and pixel size.",
+            Description = "List active scene Unity Camera components with name, hierarchy path, projection, FOV/ortho size, depth, targetTexture, and pixel size. Read-only; use paths or ids from this output for camera.info/screenshot/lens/target.",
+            Group = "camera",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "List scene cameras", Input = new Request { } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var cameras = Camera.allCameras;
+            var list = new List<CameraInfo>();
+            foreach (var camera in cameras)
+            {
+                list.Add(CameraToolSupport.BuildCameraInfo(camera));
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Cameras = list, Count = list.Count });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,96 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Globalization;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.multiview — 为每个命名 Camera 捕获一张 PNG/JPG 截图到输出目录,用于多视角审阅。
+    /// </summary>
+    public class CameraMultiviewTool : IUnityCliTool<CameraMultiviewTool.Request, CameraMultiviewTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Targets { get; set; }
+            public string Output { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public string Format { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public List<CameraCapture> Captures { get; set; }
+            public long Count { get; set; }
+            public List<CameraPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.multiview",
+            Summary = "Capture one PNG/JPG artifact per named Camera into an output directory for multiview review.",
+            Description = "Capture one PNG/JPG artifact per named Camera into an output directory for side-by-side scene review. Returns artifact paths instead of inline image bytes; keep target count and resolution small for token and disk efficiency.",
+            Group = "camera",
+            DestructiveHint = true,
+            SideEffects = new[] { "artifact-write", "render-texture" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Capture from two cameras", Input = new Request { Targets = "Main Camera,UnityCliAlignmentCamera", Output = "Artifacts/camera-multiview", Width = 320, Height = 180, Format = "png" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(request.Targets))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "camera.multiview requires targets.", "Run tools run camera.list, then pass comma-separated camera names, hierarchy paths, or instance ids.");
+            }
+            var names = request.Targets.Split(new[] { ',' }, System.StringSplitOptions.RemoveEmptyEntries);
+            var cameras = new List<Camera>();
+            foreach (var name in names)
+            {
+                var camera = CameraToolSupport.ResolveCamera(name.Trim());
+                if (camera == null)
+                {
+                    throw new UnityCliBridge.BridgeCommandException("E_CAMERA_NOT_FOUND", "Camera not found: " + name.Trim(), "Run tools run camera.list, then retry with camera names, hierarchy paths, or instance ids from the result.");
+                }
+                cameras.Add(camera);
+            }
+            var outputDir = string.IsNullOrEmpty(request.Output) ? "Screenshots" : request.Output;
+            var width = CameraToolSupport.ClampScreenshotDimension(request.Width ?? 1280, "width");
+            var height = CameraToolSupport.ClampScreenshotDimension(request.Height ?? 720, "height");
+            var format = CameraToolSupport.NormalizeFormat(request.Format, Path.Combine(outputDir, "capture.png"));
+            var captures = new List<CameraCapture>();
+            var effects = new List<CameraPlannedEffect>();
+            var plans = new List<KeyValuePair<int, string>>();
+            var outputPaths = new HashSet<string>(System.StringComparer.OrdinalIgnoreCase);
+            foreach (var camera in cameras)
+            {
+                var outputPath = CameraToolSupport.ResolveScreenshotOutputPath(Path.Combine(outputDir, camera.name + "." + format));
+                if (!outputPaths.Add(outputPath))
+                    throw new UnityCliBridge.BridgeCommandException("E_MULTIVIEW_OUTPUT_CONFLICT", "Each camera.multiview target must produce a distinct artifact path.", "Use uniquely named cameras or capture targets separately.");
+                plans.Add(new KeyValuePair<int, string>(camera.GetInstanceID(), outputPath));
+            }
+            ctx.CommitEffect();
+            foreach (var plan in plans)
+            {
+                var camera = EditorUtility.InstanceIDToObject(plan.Key) as Camera;
+                if (camera == null) throw new UnityCliBridge.BridgeCommandException("E_CAMERA_NOT_FOUND", "Camera disappeared before capture.", "Retry after the Editor is idle.");
+                var capture = CameraToolSupport.CaptureCamera(camera, width, height, false, 95, plan.Value, format, true, false);
+                if (!File.Exists(plan.Value) || new FileInfo(plan.Value).Length == 0)
+                    throw new UnityCliBridge.BridgeCommandException("E_MULTIVIEW_ARTIFACT_MISSING", "Camera capture artifact was not observed: " + plan.Value, "Check the output directory and retry.");
+                captures.Add(capture);
+                effects.Add(new CameraPlannedEffect { Type = "camera.multiview", Property = "capture", Path = plan.Value });
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Captures = captures, Count = captures.Count, PlannedEffects = effects });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,65 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.screenshot — 从指定 Camera 渲染 PNG/JPG 截图到文件。
+    /// </summary>
+    public class CameraScreenshotTool : IUnityCliTool<CameraScreenshotTool.Request, CameraCapture>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Path { get; set; }
+            public string Output { get; set; }
+            public int? Width { get; set; }
+            public int? Height { get; set; }
+            public string Format { get; set; }
+            public bool Transparent { get; set; }
+            public int? Quality { get; set; }
+            public bool Overwrite { get; set; }
+            public bool InlineBase64 { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.screenshot",
+            Summary = "Render a PNG/JPG artifact from one specific Camera; use screenshot.* for view-based captures.",
+            Description = "Render a screenshot from a specific Camera into a PNG/JPG artifact file. Defaults return artifact paths only; inlineBase64 must be explicit and is omitted when the image exceeds the bridge inline limit. Restores camera render state after capture.",
+            Group = "camera",
+            DestructiveHint = true,
+            SideEffects = new[] { "artifact-write", "render-texture" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Capture from Main Camera", Input = new Request { Target = "Main Camera", Path = "Artifacts/camera-main.png", Width = 640, Height = 360, Overwrite = true } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<CameraCapture> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var target = request.Target;
+            if (string.IsNullOrEmpty(target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "Camera screenshot requires a target Camera.", "Pass a Camera name, hierarchy path or instance id. Run tools run camera.list before retrying.");
+            }
+            var camera = CameraToolSupport.ResolveCamera(target);
+            if (camera == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "Camera not found: " + target, "Run tools run camera.list, then retry with a camera name, hierarchy path, or instance id from the result.");
+            }
+            var outputPath = CameraToolSupport.ResolveScreenshotOutputPath(request.Path ?? request.Output);
+            var format = CameraToolSupport.NormalizeFormat(request.Format, outputPath);
+            var width = CameraToolSupport.ClampScreenshotDimension(request.Width ?? (camera.pixelWidth > 0 ? camera.pixelWidth : 1280), "width");
+            var height = CameraToolSupport.ClampScreenshotDimension(request.Height ?? (camera.pixelHeight > 0 ? camera.pixelHeight : 720), "height");
+            var quality = Mathf.Clamp(request.Quality ?? 95, 1, 100);
+            ctx.CommitEffect();
+            return new System.Threading.Tasks.ValueTask<CameraCapture>(CameraToolSupport.CaptureCamera(camera, width, height, request.Transparent, quality, outputPath, format, request.Overwrite, request.InlineBase64));
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,94 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// camera.target — 通过 lookAt 和/或显式 position/rotation 调整 Camera 变换。
+    /// </summary>
+    public class CameraTargetTool : IUnityCliTool<CameraTargetTool.Request, CameraTargetTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string LookAt { get; set; }
+            public string Position { get; set; }
+            public string Rotation { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public CameraInfo Camera { get; set; }
+            public List<CameraPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "camera.target",
+            Summary = "Aim or move one Camera transform using lookAt and/or explicit position/rotation.",
+            Description = "Set a Camera transform by looking at a GameObject and/or assigning explicit position/rotation. Session-affecting: marks the Camera dirty and can affect the running Play Mode view without persisting runtime-only state.",
+            Group = "camera",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Point a camera at a target", Input = new Request { Target = "UnityCliAlignmentCamera", LookAt = "UnityCliAlignmentProbe" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (string.IsNullOrEmpty(request.Target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "camera.target requires target.", "Run tools run camera.list, then pass a camera name, hierarchy path, or instance id.");
+            }
+            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.");
+            }
+            if (string.IsNullOrEmpty(request.LookAt) && string.IsNullOrEmpty(request.Position) && string.IsNullOrEmpty(request.Rotation))
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_TARGET_REQUEST_EMPTY", "camera.target requires lookAt, position, or rotation.", "Pass at least one transform setting.");
+            if (!string.IsNullOrEmpty(request.LookAt) && !string.IsNullOrEmpty(request.Rotation))
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_TARGET_CONFLICT", "camera.target cannot combine lookAt with explicit rotation.", "Use lookAt or rotation, not both.");
+            var effects = new List<CameraPlannedEffect>();
+            var cameraId = camera.GetInstanceID();
+            var position = string.IsNullOrEmpty(request.Position) ? (Vector3?)null : GameObjectToolSupport.ParseVector3(request.Position);
+            var rotation = string.IsNullOrEmpty(request.Rotation) ? (Vector3?)null : GameObjectToolSupport.ParseVector3(request.Rotation);
+            var lookAtGo = string.IsNullOrEmpty(request.LookAt) ? null : GameObjectToolSupport.ResolveUniqueTarget(request.LookAt, "camera.target --look-at <go> not found.");
+            var plannedPosition = position ?? camera.transform.position;
+            var lookDirection = lookAtGo == null ? Vector3.zero : lookAtGo.transform.position - plannedPosition;
+            if (lookAtGo != null && lookDirection == Vector3.zero) throw new UnityCliBridge.BridgeCommandException("E_CAMERA_TARGET_INVALID", "camera.target lookAt must not be at the planned Camera position.", "Choose a target at a different position.");
+            var expectedLookRotation = lookAtGo == null ? Quaternion.identity : Quaternion.LookRotation(lookDirection);
+            ctx.CommitEffect();
+            if (position.HasValue)
+            {
+                camera.transform.position = position.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.target", Property = "position", Value = request.Position });
+            }
+            if (lookAtGo != null)
+            {
+                camera.transform.rotation = expectedLookRotation;
+                effects.Add(new CameraPlannedEffect { Type = "camera.target", Property = "lookAt", Target = CameraToolSupport.HierarchyPath(lookAtGo) });
+            }
+            if (rotation.HasValue)
+            {
+                camera.transform.eulerAngles = rotation.Value;
+                effects.Add(new CameraPlannedEffect { Type = "camera.target", Property = "rotation", Value = request.Rotation });
+            }
+            UnityCliSceneMutation.MarkSceneObjectDirty(camera);
+            var observed = EditorUtility.InstanceIDToObject(cameraId) as Camera;
+            if (observed == null || (lookAtGo != null && Quaternion.Angle(observed.transform.rotation, expectedLookRotation) > 0.01f) || (position.HasValue && observed.transform.position != position.Value) || (rotation.HasValue && observed.transform.eulerAngles != rotation.Value))
+                throw new UnityCliBridge.BridgeCommandException("E_CAMERA_TARGET_STATE_MISMATCH", "Camera transform did not satisfy the requested target 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 = effects });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/component/add.cs

@@ -0,0 +1,125 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// component.add — 向 GameObject 添加 Component,可在创建后一次性设置简单公开字段/属性。
+    /// </summary>
+    public class ComponentAddTool : IUnityCliTool<ComponentAddTool.Request, ComponentAddTool.Result>
+    {
+        public sealed class Request
+        {
+            public string Target { get; set; }
+            public string Component { get; set; }
+            [UnityCliAnyJson] public Dictionary<string, object> Properties { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public ComponentSummary Component { get; set; }
+            public List<ChangedProperty> ChangedProperties { get; set; }
+            public List<GameObjectPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "component.add",
+            Summary = "Add a Unity Component to a GameObject, optionally setting simple public fields/properties from a properties object after the component is created.",
+            Description = "Add a Unity Component to a GameObject, optionally setting simple public fields/properties from a properties object after the component is created. Use component.list-types first when the exact type name is unclear.",
+            Group = "component",
+            DestructiveHint = false,
+            SideEffects = new[] { "component-add", "scene-modify" },
+            Target = "editor",
+            PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Add AudioSource with initial properties", Input = new Request { Target = "ComponentTarget", Component = "AudioSource", Properties = new Dictionary<string, object> { { "volume", 0.5d }, { "playOnAwake", false } } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            GameObjectToolSupport.EnsureEditorNotBusy("component.add");
+            var gameObject = ResolveTarget(request.Target, "Component add requires a target.");
+            var componentName = RequireComponentName(request.Component);
+            var type = GameObjectToolSupport.ResolveComponentType(componentName);
+            if (!GameObjectToolSupport.AllowsMultipleComponents(type) && gameObject.GetComponent(type) != null)
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_EXISTS", "Component already exists on target: " + componentName, "Use component.set or component.modify to update existing component properties.");
+            }
+            var propertyChanges = GameObjectToolSupport.BuildComponentPropertyChanges(type, request.Properties);
+            ctx.CommitEffect();
+            var component = UnityCliSceneMutation.AddComponent(gameObject, type);
+            if (component == null || !type.IsInstanceOfType(component))
+            {
+                if (!object.ReferenceEquals(component, null)) UnityCliSceneMutation.DestroyObject(component);
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_ADD_FAILED", "Unity did not add component type: " + componentName, "The type may be restricted by Unity on this GameObject. Run component.get to inspect existing components, then choose a different component type or update the existing component.");
+            }
+            GameObjectToolSupport.ApplyComponentPropertyChanges(component, propertyChanges);
+            UnityCliSceneMutation.MarkSceneDirty(gameObject.scene);
+            var observedComponent = VerifyComponentReadback(gameObject.GetInstanceID(), component.GetInstanceID(), type, propertyChanges);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Component = GameObjectToolSupport.BuildComponentSummary(observedComponent),
+                ChangedProperties = BuildChangedProperties(propertyChanges),
+                PlannedEffects = new List<GameObjectPlannedEffect> { new GameObjectPlannedEffect { Type = "component.add", Target = GameObjectToolSupport.HierarchyPath(gameObject), Component = component.GetType().Name } }
+            });
+        }
+
+        internal static GameObject ResolveTarget(string target, string message)
+        {
+            if (string.IsNullOrEmpty(target))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", message, "Pass a GameObject name, hierarchy path or instance id.");
+            }
+            return GameObjectToolSupport.ResolveUniqueTarget(target, message);
+        }
+
+        internal static string RequireComponentName(string component)
+        {
+            if (string.IsNullOrEmpty(component))
+            {
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_TYPE_REQUIRED", "Component command requires --component <type>.", "Pass a Unity component type name, such as BoxCollider or UnityEngine.Rigidbody.");
+            }
+            return component;
+        }
+
+        internal static List<ChangedProperty> BuildChangedProperties(List<ComponentPropertyChange> changes)
+        {
+            var result = new List<ChangedProperty>();
+            foreach (var change in changes ?? new List<ComponentPropertyChange>())
+            {
+                result.Add(new ChangedProperty { Name = change.Name, Type = change.ValueType.Name, Value = change.InputValue });
+            }
+            return result;
+        }
+
+        /// <summary>effect 后重新解析目标与组件，并逐个比较已经转换的 typed value。</summary>
+        internal static Component VerifyComponentReadback(int targetId, int componentId, System.Type type, List<ComponentPropertyChange> changes)
+        {
+            var observedTarget = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            Component observedComponent = null;
+            if (observedTarget != null)
+                foreach (var candidate in observedTarget.GetComponents(type))
+                    if (candidate != null && candidate.GetInstanceID() == componentId) { observedComponent = candidate; break; }
+            if (observedComponent == null)
+                throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_STATE_MISMATCH", "Component target/type did not match after independent readback.", "Inspect the target GameObject and retry after the Editor is idle.");
+            var serialized = new SerializedObject(observedComponent);
+            serialized.Update();
+            foreach (var change in changes ?? new List<ComponentPropertyChange>())
+            {
+                var actual = change.Property != null ? change.Property.GetValue(observedComponent, null) : change.Field.GetValue(observedComponent);
+                if (!object.Equals(actual, change.Value))
+                    throw new UnityCliBridge.BridgeCommandException("E_COMPONENT_STATE_MISMATCH", "Component member '" + change.Name + "' did not match the requested converted value after readback.", "Inspect the component member and retry after the Editor is idle.");
+            }
+            return observedComponent;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/component/get.cs

@@ -0,0 +1,73 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// component.get — 深读单个 Component,支持 paths/viewQuery 互斥的 token-safe 读取。
+    /// </summary>
+    public class ComponentGetTool : IUnityCliTool<ComponentGetTool.Request, ComponentGetTool.Result>
+    {
+        public sealed class Request : IUnityCliObjectReferenceInput, IUnityCliObjectSerializationInput
+        {
+            public int? InstanceId { get; set; }
+            public string Path { get; set; }
+            public string Name { get; set; }
+            public string Target { get; set; }
+            public string AssetPath { get; set; }
+            public string Guid { get; set; }
+            public int? ComponentInstanceId { get; set; }
+            public int? ComponentIndex { get; set; }
+            public string Component { get; set; }
+            public string ComponentType { 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 List<string> Paths { get; set; }
+            [UnityCliAnyJson] public object ViewQuery { get; set; }
+            public string NamePattern { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public string TypeName { get; set; }
+            public GameObjectRef GameObject { get; set; }
+            [UnityCliAnyJson] public object Data { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "component.get",
+            Summary = "Deep-read one Component by GameObject and component selector; use paths/viewQuery for token-safe fields.",
+            Description = "Deep-read one Component after selecting a GameObject with go.find/go.inspect or tools run scene.gameobject.components. For token safety, pass exact paths or one viewQuery; they are mutually exclusive and skip full fields/props expansion. Use componentIndex/componentInstanceId when duplicate components exist. Keep maxDepth low before expanding MonoBehaviours.",
+            Group = "component",
+            DestructiveHint = false,
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read Transform position only", Input = new Request { Path = "Main Camera", Component = "Transform", MaxDepth = 2 } },
+                new ToolExample { Description = "Read one filtered subtree", Input = new Request { Path = "Main Camera", Component = "Transform", NamePattern = "position" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var component = UnityCliBridge.ObjectRefResolver.ResolveComponent(request);
+            var options = GameObjectToolSupport.BuildSerializerOptions(request);
+            var data = UnityCliBridge.ObjectSerializer.Serialize(component, options);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                TypeName = component.GetType().FullName,
+                GameObject = GameObjectToolSupport.BuildGameObjectRef(component.gameObject),
+                Data = data
+            });
+        }
+    }
+}
+#endif