@alpsckr/unitycli 0.4.0

package/unitypkg/Editor/Tools/timeline/clip/add.cs

@@ -0,0 +1,93 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>向唯一 Timeline track 添加一个 clip，并以 fresh timing/playable/source binding 证明持久化结果。</summary>
+    public sealed class TimelineClipAddTool : IUnityCliTool<TimelineClipAddTool.Request, TimelineClipAddTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Timeline { get; set; }
+            public string Track { get; set; }
+            public string TrackLocalId { get; set; }
+            [UnityCliRequired]
+            public double Start { get; set; }
+            [UnityCliRequired]
+            public double Duration { get; set; }
+            public string Asset { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Added { get; set; }
+            public bool DryRun { get; set; }
+            public TimelineAssetInfo Timeline { get; set; }
+            public TimelineClipMutationInfo Clip { get; set; }
+            public List<TimelineMutationPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "timeline.clip.add",
+            Summary = "Add one Timeline clip and prove its track, timing, playable asset, source binding, and serialized artifact.",
+            Description = "Requires com.unity.timeline. timeline and asset accept an Assets path or GUID. Select exactly one target with track (unique exact name) or trackLocalId (stable decimal string from timeline.info). start must be finite and >= 0; duration must be finite and > 0 within the installed Timeline range. Animation tracks require an AnimationClip asset and Audio tracks require an AudioClip; other approved built-in tracks must expose CreateDefaultClip. The complete target/source/API/timing plan is validated before dry-run or one asset-write/import effect.",
+            Group = "timeline",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-write", "asset-import" },
+            Permissions = new[] { "project-asset-write" },
+            RequiresPackages = new[] { TimelineToolSupport.PackageId },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 60000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Add an Animation clip by stable track localId.", Input = new Request { Timeline = "Assets/Timelines/Intro.playable", TrackLocalId = "-1234567890123456789", Start = 0d, Duration = 2.5d, Asset = "Assets/Animations/Intro.anim" } },
+                new ToolExample { Description = "Preview a default Activation clip by unique track name.", Input = new Request { Timeline = "guid:0123456789abcdef0123456789abcdef", Track = "Activation", Start = 1d, Duration = 3d }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>effect 前冻结 target/source/overload/timing/clip count；actual 路径只跨一次 barrier。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            AssetToolSupport.EnsureEditorNotBusy("timeline.clip.add");
+            ct.ThrowIfCancellationRequested();
+            request = request ?? new Request();
+            var plan = TimelineMutationToolSupport.PrepareClipAdd(request.Timeline, request.Track, request.TrackLocalId,
+                request.Start, request.Duration, request.Asset);
+            var effects = new List<TimelineMutationPlannedEffect>
+            {
+                new TimelineMutationPlannedEffect { Type = "timeline.clip.add", Path = plan.Timeline.Path, Target = plan.Track.Identity.LocalId, SideEffects = "asset-write,asset-import" }
+            };
+            if (ctx.DryRun)
+            {
+                return new ValueTask<Result>(new Result
+                {
+                    Added = false,
+                    DryRun = true,
+                    Timeline = TimelineMutationToolSupport.BuildTimelineInfo(plan.Timeline),
+                    Clip = TimelineMutationToolSupport.PreviewClip(plan),
+                    PlannedEffects = effects
+                });
+            }
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            var clip = TimelineMutationToolSupport.AddClip(plan);
+            return new ValueTask<Result>(new Result
+            {
+                Added = true,
+                DryRun = false,
+                Timeline = TimelineMutationToolSupport.BuildTimelineInfo(plan.Timeline),
+                Clip = clip,
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,88 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>创建或显式替换一个 TimelineAsset，并证明 path、GUID、frame rate 与 file artifact。</summary>
+    public sealed class TimelineCreateTool : IUnityCliTool<TimelineCreateTool.Request, TimelineCreateTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Path { get; set; }
+            public double? FrameRate { get; set; }
+            public bool Overwrite { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Created { get; set; }
+            public bool Overwritten { get; set; }
+            public bool DryRun { get; set; }
+            public TimelineAssetInfo Timeline { get; set; }
+            public List<TimelinePlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "timeline.create",
+            Summary = "Create a TimelineAsset with a validated .playable path and frame rate, then prove its GUID and serialized artifact.",
+            Description = "Requires com.unity.timeline. frameRate defaults to 60 and must be finite in [0.000001,1000]. Existing Timeline assets require overwrite=true and retain their GUID; another asset type or orphan metadata at the path is always rejected. Dry-run validates the package API and complete create plan without writing assets.",
+            Group = "timeline",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-write", "asset-import" },
+            Permissions = new[] { "project-asset-write" },
+            RequiresPackages = new[] { TimelineToolSupport.PackageId },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 60000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a 30 fps Timeline asset.", Input = new Request { Path = "Assets/Timelines/Intro.playable", FrameRate = 30d } },
+                new ToolExample { Description = "Preview replacing an existing Timeline asset.", Input = new Request { Path = "Assets/Timelines/Intro.playable", FrameRate = 60d, Overwrite = true }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>先冻结反射 API/path/existing identity，再按 dry-run 或一次 effect barrier 创建并 fresh 证明。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            AssetToolSupport.EnsureEditorNotBusy("timeline.create");
+            ct.ThrowIfCancellationRequested();
+            request = request ?? new Request();
+            var plan = TimelineToolSupport.PrepareCreate(request.Path, request.FrameRate, request.Overwrite);
+            var effects = new List<TimelinePlannedEffect>
+            {
+                new TimelinePlannedEffect { Type = "timeline.create", Path = plan.Path, SideEffects = "asset-write,asset-import" }
+            };
+            if (ctx.DryRun)
+            {
+                return new ValueTask<Result>(new Result
+                {
+                    Created = false,
+                    Overwritten = plan.Existing,
+                    DryRun = true,
+                    Timeline = TimelineToolSupport.Preview(plan),
+                    PlannedEffects = effects
+                });
+            }
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            TimelineToolSupport.Create(plan);
+            var observed = TimelineToolSupport.ProveCreate(plan);
+            return new ValueTask<Result>(new Result
+            {
+                Created = true,
+                Overwritten = plan.Existing,
+                DryRun = false,
+                Timeline = observed,
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,54 @@
+#if UNITY_EDITOR
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>以 bounded fresh snapshot 读取 Timeline tracks、clips、timing 与 asset/output bindings。</summary>
+    public sealed class TimelineInfoTool : IUnityCliTool<TimelineInfoTool.Request, TimelineInfoResult>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Timeline { get; set; }
+            public int? Cursor { get; set; }
+            public int? PageSize { get; set; }
+            public int? MaxDepth { get; set; }
+            public int? MaxClipsPerTrack { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "timeline.info",
+            Summary = "Read a bounded TimelineAsset structure with stable track identities, clips, timing, and asset/output bindings.",
+            Description = "Requires com.unity.timeline. timeline accepts an Assets/*.playable path, a 32-character GUID, or guid:<GUID>. Tracks are flattened in root pre-order and paged by cursor/pageSize (default 0/50, max 200); maxDepth defaults to 8 (max 32), and maxClipsPerTrack defaults to 100 (max 500). timeline.trackCount and pageInfo.total count tracks within maxDepth; depthTruncated reports omitted descendants. Track parent identity and clip playable/source assets use stable GUID/localId string pairs. Output bindings describe Timeline track output types only; PlayableDirector scene-object bindings are outside a TimelineAsset and are not read.",
+            Group = "timeline",
+            DestructiveHint = false,
+            SupportsDryRun = false,
+            SideEffects = new string[0],
+            Permissions = new[] { "project-asset-read" },
+            RequiresPackages = new[] { TimelineToolSupport.PackageId },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 120000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Read the first Timeline structure page.", Input = new Request { Timeline = "Assets/Timelines/Intro.playable", PageSize = 50, MaxDepth = 8, MaxClipsPerTrack = 100 } },
+                new ToolExample { Description = "Read the next bounded page by GUID.", Input = new Request { Timeline = "guid:0123456789abcdef0123456789abcdef", Cursor = 50, PageSize = 50 } }
+            }
+        };
+
+        /// <summary>解析并 fresh 读取现有 asset；不调用 refresh/import/SaveAssets，也不跨 effect barrier。</summary>
+        public ValueTask<TimelineInfoResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            AssetToolSupport.EnsureEditorNotBusy("timeline.info");
+            ct.ThrowIfCancellationRequested();
+            request = request ?? new Request();
+            var plan = TimelineReadToolSupport.Prepare(request.Timeline, request.Cursor, request.PageSize, request.MaxDepth, request.MaxClipsPerTrack);
+            var result = TimelineReadToolSupport.Read(plan, ct);
+            return new ValueTask<TimelineInfoResult>(result);
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/timeline/track/add.cs

@@ -0,0 +1,91 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace UnityCli
+{
+    /// <summary>向 TimelineAsset 添加一个批准的 built-in track，并以 fresh localId/parent 结构证明持久化结果。</summary>
+    public sealed class TimelineTrackAddTool : IUnityCliTool<TimelineTrackAddTool.Request, TimelineTrackAddTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Timeline { get; set; }
+            [UnityCliRequired]
+            public string TrackType { get; set; }
+            public string Name { get; set; }
+            public string ParentTrack { get; set; }
+            public string ParentLocalId { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Added { get; set; }
+            public bool DryRun { get; set; }
+            public TimelineAssetInfo Timeline { get; set; }
+            public TimelineTrackMutationInfo Track { get; set; }
+            public List<TimelineMutationPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "timeline.track.add",
+            Summary = "Add one approved built-in Timeline track and prove its stable identity, exact type, name, and parent.",
+            Description = "Requires com.unity.timeline. timeline accepts an Assets/*.playable path or GUID. trackType is Animation, Audio, Activation, Control, Playable, Signal, or Marker. parentTrack selects one exact unique name; parentLocalId selects the stable decimal string returned by timeline.info, and the selectors are mutually exclusive. The complete type/parent/name plan is validated before dry-run or one asset-write/import effect.",
+            Group = "timeline",
+            DestructiveHint = true,
+            SupportsDryRun = true,
+            SideEffects = new[] { "asset-write", "asset-import" },
+            Permissions = new[] { "project-asset-write" },
+            RequiresPackages = new[] { TimelineToolSupport.PackageId },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 60000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Add a root Animation track.", Input = new Request { Timeline = "Assets/Timelines/Intro.playable", TrackType = "Animation", Name = "Character Animation" } },
+                new ToolExample { Description = "Preview an Audio track under a parent localId.", Input = new Request { Timeline = "guid:0123456789abcdef0123456789abcdef", TrackType = "Audio", Name = "Music", ParentLocalId = "-1234567890123456789" }, Execution = new ToolExampleExecution { DryRun = true } }
+            }
+        };
+
+        /// <summary>effect 前冻结全部 identity/API/parent/name 约束；actual 路径只跨一次 barrier。</summary>
+        public ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, CancellationToken ct = default(CancellationToken))
+        {
+            AssetToolSupport.EnsureEditorNotBusy("timeline.track.add");
+            ct.ThrowIfCancellationRequested();
+            request = request ?? new Request();
+            var plan = TimelineMutationToolSupport.PrepareTrackAdd(request.Timeline, request.TrackType, request.Name,
+                request.ParentTrack, request.ParentLocalId);
+            var effects = new List<TimelineMutationPlannedEffect>
+            {
+                new TimelineMutationPlannedEffect { Type = "timeline.track.add", Path = plan.Timeline.Path, Target = plan.Name, SideEffects = "asset-write,asset-import" }
+            };
+            if (ctx.DryRun)
+            {
+                return new ValueTask<Result>(new Result
+                {
+                    Added = false,
+                    DryRun = true,
+                    Timeline = TimelineMutationToolSupport.BuildTimelineInfo(plan.Timeline),
+                    Track = TimelineMutationToolSupport.PreviewTrack(plan),
+                    PlannedEffects = effects
+                });
+            }
+
+            ct.ThrowIfCancellationRequested();
+            ctx.CommitEffect();
+            var track = TimelineMutationToolSupport.AddTrack(plan);
+            return new ValueTask<Result>(new Result
+            {
+                Added = true,
+                DryRun = false,
+                Timeline = TimelineMutationToolSupport.BuildTimelineInfo(plan.Timeline),
+                Track = track,
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/UiToolSupport.cs

@@ -0,0 +1,162 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+using UiButton = UnityEngine.UI.Button;
+using UiCanvasScaler = UnityEngine.UI.CanvasScaler;
+using UiGraphicRaycaster = UnityEngine.UI.GraphicRaycaster;
+using UiImage = UnityEngine.UI.Image;
+using UiText = UnityEngine.UI.Text;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// ui 域 IUnityCliTool 共享 helper:uGUI 元素创建、UIDocument 管理、
+    /// VisualTreeAsset/StyleSheet 加载。仅供 ui 域自包含工具复用。
+    /// </summary>
+    public static class UiToolSupport
+    {
+        /// <summary>拦截编译/导入/构建/PlayMode 过渡期的写入请求。</summary>
+        public static void EnsureEditorNotBusy(string command)
+        {
+            SceneToolSupport.EnsureEditorNotBusy(command);
+        }
+
+        /// <summary>解析 UI 父节点(Canvas/RectTransform),空返回 null。</summary>
+        public static GameObject ResolveUiParent(string parent)
+        {
+            if (string.IsNullOrEmpty(parent)) return null;
+            try
+            {
+                var resolved = GameObjectToolSupport.ResolveUniqueTarget(parent, "UI parent not found.");
+                if (resolved == null || resolved.GetComponent<RectTransform>() == null) return null;
+                var instanceId = resolved.GetInstanceID();
+                var fresh = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+                return fresh != null && fresh.GetInstanceID() == instanceId && fresh.GetComponent<RectTransform>() != null ? fresh : null;
+            }
+            catch { return null; }
+        }
+
+        /// <summary>解析 GameObject 目标,支持名称/路径/实例ID。</summary>
+        public static GameObject ResolveGameObjectTarget(string target)
+        {
+            return GameObjectToolSupport.ResolveUniqueTarget(target, "Target not found: " + target);
+        }
+
+        /// <summary>加载 VisualTreeAsset;不存在抛异常。</summary>
+        public static VisualTreeAsset LoadVisualTreeAsset(string path)
+        {
+            var vta = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>(path);
+            if (vta == null) throw new UnityCliBridge.BridgeCommandException("E_UI_UXML_NOT_FOUND", "VisualTreeAsset not found: " + path, "Pass an existing Assets/*.uxml path.");
+            return vta;
+        }
+
+        /// <summary>加载 StyleSheet。</summary>
+        public static StyleSheet LoadStyleSheet(string path)
+        {
+            if (string.IsNullOrEmpty(path)) return null;
+            var ss = AssetDatabase.LoadAssetAtPath<StyleSheet>(path);
+            if (ss == null) throw new UnityCliBridge.BridgeCommandException("E_UI_USS_NOT_FOUND", "StyleSheet not found: " + path, "Pass an existing Assets/*.uss path.");
+            return ss;
+        }
+
+        /// <summary>校验 uxml 路径。</summary>
+        public static string RequireUxmlPath(string rawPath)
+        {
+            return RequireUiDocumentPath(rawPath, ".uxml", "E_UI_UXML_PATH_REQUIRED");
+        }
+
+        /// <summary>校验 USS 路径。</summary>
+        public static string RequireUssPath(string rawPath)
+        {
+            return RequireUiDocumentPath(rawPath, ".uss", "E_UI_USS_PATH_REQUIRED");
+        }
+
+        /// <summary>校验 UI 文档路径在 Assets/ 内且不含路径穿越段。</summary>
+        public static string RequireUiDocumentPath(string rawPath, string extension, string errorCode)
+        {
+            var path = AssetToolSupport.RequireAssetPath(rawPath);
+            if (!path.EndsWith(extension, System.StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException(errorCode, "Pass an Assets/*" + extension + " path.", "Use a canonical path under Assets/ without path traversal segments.");
+            AssetToolSupport.AssetFullPath(path);
+            return path;
+        }
+
+        /// <summary>校验 UXML 或 USS 文档路径。</summary>
+        public static string RequireUiDocumentAssetPath(string rawPath)
+        {
+            var path = AssetToolSupport.RequireAssetPath(rawPath);
+            if (!path.EndsWith(".uxml", System.StringComparison.OrdinalIgnoreCase) && !path.EndsWith(".uss", System.StringComparison.OrdinalIgnoreCase))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_PATH_INVALID", "UI document path must end with .uxml or .uss: " + path, "Pass a canonical Assets/*.uxml or Assets/*.uss path.");
+            AssetToolSupport.AssetFullPath(path);
+            return path;
+        }
+
+        public static void ValidateVisualElementSize(float? width, float? height)
+        {
+            ValidateFinite(width, "Width");
+            ValidateFinite(height, "Height");
+            if ((width.HasValue && width.Value < 0f) || (height.HasValue && height.Value < 0f))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_RANGE_INVALID", "Width and Height must be finite and non-negative.", "Pass finite dimensions greater than or equal to zero.");
+        }
+
+        /// <summary>在 effect 前验证文本资产路径与覆盖策略。</summary>
+        public static void ValidateTextAssetCreation(string path, bool overwrite, string existsErrorCode)
+        {
+            if (File.Exists(SceneToolSupport.AssetFullPath(path)) && !overwrite)
+                throw new UnityCliBridge.BridgeCommandException(existsErrorCode, "Asset already exists: " + path, "Pass overwrite=true or choose a different path.");
+        }
+
+        /// <summary>写入已验证的文本资产。</summary>
+        public static void EnsureTextAsset(string path, string defaultContent)
+        {
+            SceneToolSupport.CreateAssetDirectory(path);
+            File.WriteAllText(SceneToolSupport.AssetFullPath(path), defaultContent, System.Text.Encoding.UTF8);
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+        }
+
+        /// <summary>默认 UXML 模板。</summary>
+        public static string DefaultUxml(string ussPath)
+        {
+            var ussRef = string.IsNullOrEmpty(ussPath) ? "" : " <ui:UXML xmlns:ui=\"UnityEngine.UIElements\" xmlns:uie=\"UnityEditor.UIElements\">";
+            if (string.IsNullOrEmpty(ussRef))
+                return "<ui:UXML xmlns:ui=\"UnityEngine.UIElements\" xmlns:uie=\"UnityEditor.UIElements\">\n  <ui:Label text=\"Hello World\" />\n</ui:UXML>\n";
+            return "<ui:UXML xmlns:ui=\"UnityEngine.UIElements\" xmlns:uie=\"UnityEditor.UIElements\">\n  <Style src=\"" + Path.GetFileName(ussPath) + "\" />\n  <ui:Label text=\"Hello World\" />\n</ui:UXML>\n";
+        }
+
+        /// <summary>默认 USS 模板。</summary>
+        public static string DefaultUss() => ":root { font-size: 14px; }\n";
+
+        public static void ValidateUguiRequest(int? fontSize, float? width, float? height, float? x, float? y)
+        {
+            if (fontSize.HasValue && fontSize.Value <= 0) throw new UnityCliBridge.BridgeCommandException("E_UI_RANGE_INVALID", "FontSize must be positive.", "Pass a positive fontSize.");
+            ValidateFinite(width, "Width"); ValidateFinite(height, "Height"); ValidateFinite(x, "X"); ValidateFinite(y, "Y");
+            if (width.HasValue && width.Value < 0f || height.HasValue && height.Value < 0f)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_RANGE_INVALID", "Width and Height cannot be negative.", "Pass non-negative dimensions.");
+        }
+        private static void ValidateFinite(float? value, string field)
+        {
+            if (value.HasValue && (float.IsNaN(value.Value) || float.IsInfinity(value.Value)))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_VALUE_INVALID", field + " must be finite.", "Pass a finite numeric value.");
+        }
+
+        /// <summary>构造 UI 元素引用 DTO。</summary>
+        public static UiElementRef BuildUiElementRef(GameObject go, string kind)
+        {
+            return new UiElementRef { Id = go.GetInstanceID(), Name = go.name, Path = GameObjectToolSupport.HierarchyPath(go), Kind = kind };
+        }
+    }
+
+    // ── ui 域 DTO ──
+
+    public sealed class UiElementRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } public string Kind { get; set; } }
+    public sealed class UiDocumentAssetInfo { public string Path { get; set; } public string Name { get; set; } public bool Exists { get; set; } public string VisualTreeName { get; set; } public string StyleSheetName { get; set; } }
+    public sealed class UiDocumentLiveInfo { public string VisualTreeAsset { get; set; } public string PanelSettings { get; set; } public double SortingOrder { get; set; } }
+    public sealed class UiPanelSettingsInfo { public string Path { get; set; } public string ScaleMode { get; set; } public int ReferenceWidth { get; set; } public int ReferenceHeight { get; set; } public double SortingOrder { get; set; } }
+    public sealed class UiVisualElementInfo { public string Name { get; set; } public string Text { get; set; } public string Display { get; set; } public float? Width { get; set; } public float? Height { get; set; } public string[] Classes { get; set; } }
+    public sealed class UiPlannedEffect { public string Type { get; set; } public string Target { get; set; } public string Path { get; set; } public string Uxml { get; set; } public string Uss { get; set; } }
+    public sealed class UiHierarchyItem { public string Name { get; set; } public string Path { get; set; } public string Type { get; set; } public long ChildCount { get; set; } }
+}
+#endif

package/unitypkg/Editor/Tools/ui/UiUguiToolSupport.cs

@@ -0,0 +1,24 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    internal static class UiRectHelper
+    {
+        public static void ApplyRect(RectTransform rt, float? width, float? height, float? x, float? y)
+        {
+            if (width.HasValue) rt.sizeDelta = new Vector2(width.Value, rt.sizeDelta.y);
+            if (height.HasValue) rt.sizeDelta = new Vector2(rt.sizeDelta.x, height.Value);
+            if (x.HasValue || y.HasValue) rt.anchoredPosition = new Vector2(x ?? rt.anchoredPosition.x, y ?? rt.anchoredPosition.y);
+        }
+
+        public static void StretchRect(RectTransform rt)
+        {
+            rt.anchorMin = Vector2.zero;
+            rt.anchorMax = Vector2.one;
+            rt.offsetMin = Vector2.zero;
+            rt.offsetMax = Vector2.zero;
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/attach-document.cs

@@ -0,0 +1,46 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.attach-document — 将 UIDocument 挂载到 GameObject。</summary>
+    public class UiAttachDocumentTool : IUnityCliTool<UiAttachDocumentTool.Request, UiAttachDocumentTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string SourceAsset { get; set; } public string Uxml { get; set; } public string PanelSettings { get; set; } public int? SortOrder { get; set; } }
+        public sealed class Result { public bool Attached { get; set; } public bool HasPanelSettings { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.attach-document", Summary = "Attach a UIDocument component to a target GameObject.", Description = "Add or configure a UIDocument with optional visualTreeAsset and panelSettings. dryRun=true previews.", Group = "ui",DestructiveHint = false, SupportsDryRun = true, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Attach UIDocument", Input = new Request { Target = "Player", SourceAsset = "Assets/UI/Main.uxml" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            UiToolSupport.EnsureEditorNotBusy("ui.attach-document");
+            var go = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(r.Target);
+            if (go == null) throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "ui.attach-document requires a target GameObject.", "Pass --target <path>.");
+            var targetId = go.GetInstanceID();
+            var sourceAsset = r.SourceAsset ?? r.Uxml;
+            var sortOrder = r.SortOrder ?? 0;
+            var requestedUxml = string.IsNullOrEmpty(sourceAsset) ? null : UiToolSupport.LoadVisualTreeAsset(SceneToolSupport.NormalizeAssetPath(sourceAsset));
+            if (!string.IsNullOrEmpty(sourceAsset) && requestedUxml == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_SOURCE_NOT_FOUND", "VisualTreeAsset not found: " + sourceAsset, "Pass an existing .uxml asset.");
+            var requestedPanel = string.IsNullOrEmpty(r.PanelSettings) ? null : AssetDatabase.LoadAssetAtPath<PanelSettings>(SceneToolSupport.NormalizeAssetPath(r.PanelSettings));
+            if (!string.IsNullOrEmpty(r.PanelSettings) && requestedPanel == null) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_NOT_FOUND", "PanelSettings asset not found: " + r.PanelSettings, "Pass an existing PanelSettings asset.");
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { Attached = go.GetComponent<UIDocument>() != null, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.attach-document", Target = GameObjectToolSupport.HierarchyPath(go) } } });
+            ctx.CommitEffect();
+            var uiDoc = go.GetComponent<UIDocument>() ?? go.AddComponent<UIDocument>();
+            if (requestedUxml != null) uiDoc.visualTreeAsset = requestedUxml;
+            if (requestedPanel != null) uiDoc.panelSettings = requestedPanel;
+            else if (uiDoc.panelSettings == null) { var defaults = ScriptableObject.CreateInstance<PanelSettings>(); defaults.scaleMode = PanelScaleMode.ScaleWithScreenSize; defaults.referenceResolution = new Vector2Int(1920, 1080); uiDoc.panelSettings = defaults; }
+            uiDoc.sortingOrder = sortOrder;
+            UnityCliSceneMutation.MarkSceneObjectDirty(uiDoc);
+            UnityCliSceneMutation.MarkSceneDirty(go.scene);
+            var observedGo = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            var observed = observedGo == null || observedGo.GetInstanceID() != targetId ? null : observedGo.GetComponent<UIDocument>();
+            if (observed == null || (requestedUxml != null && observed.visualTreeAsset != requestedUxml) || (requestedPanel != null && observed.panelSettings != requestedPanel) || observed.sortingOrder != sortOrder)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_READBACK_FAILED", "Attached UIDocument does not match the requested configuration.", "Check Unity Console for scene serialization errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Attached = true, HasPanelSettings = observed.panelSettings != null, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.attach-document", Target = GameObjectToolSupport.HierarchyPath(observedGo) } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/button/create.cs

@@ -0,0 +1,58 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UiButton = UnityEngine.UI.Button;
+using UiCanvasScaler = UnityEngine.UI.CanvasScaler;
+using UiGraphicRaycaster = UnityEngine.UI.GraphicRaycaster;
+using UiImage = UnityEngine.UI.Image;
+using UiText = UnityEngine.UI.Text;
+
+namespace UnityCli
+{
+    /// <summary>ui.button.create — 创建 uGUI Button 元素。</summary>
+    public class UiButtonCreateTool : IUnityCliTool<UiButtonCreateTool.Request, UiButtonCreateTool.Result>
+    {
+        public sealed class Request { public string Name { get; set; } public string Parent { get; set; } public string Text { get; set; } public int? FontSize { get; set; } public string Color { get; set; } public float? Width { get; set; } public float? Height { get; set; } public float? X { get; set; } public float? Y { get; set; } }
+        public sealed class Result { public UiElementRef Element { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.button.create", Summary = "Create a uGUI Button with Image and Text label.", Description = "Create a Button element with Image background and a centered Text label child.", Group = "ui",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create Button", Input = new Request { Parent = "Canvas", Text = "Click Me" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var parent = UiToolSupport.ResolveUiParent(r.Parent);
+            if (parent == null || parent.GetComponent<RectTransform>() == null) throw new UnityCliBridge.BridgeCommandException("E_UI_PARENT_NOT_FOUND", "UI parent Canvas or RectTransform not found: " + r.Parent, "Create a Canvas first.");
+            var parentId = parent.GetInstanceID();
+            var freshParent = EditorUtility.InstanceIDToObject(parentId) as GameObject;
+            if (freshParent == null || freshParent.GetInstanceID() != parentId) throw new UnityCliBridge.BridgeCommandException("E_UI_PARENT_NOT_FOUND", "UI parent could not be fresh-resolved: " + r.Parent, "Retry after the Editor is idle.");
+            parent = freshParent;
+            var name = string.IsNullOrEmpty(r.Name) ? "Button" : r.Name;
+            var requestedColor = string.IsNullOrEmpty(r.Color) ? Color.white : GraphicsToolSupport.ParseColor(r.Color);
+            UiToolSupport.ValidateUguiRequest(r.FontSize, r.Width, r.Height, r.X, r.Y);
+            ctx.CommitEffect();
+            var go = new GameObject(name, typeof(RectTransform));
+            go.transform.SetParent(parent.transform, false);
+            var image = go.AddComponent<UiImage>();
+            image.color = requestedColor;
+            go.AddComponent<UiButton>();
+            var labelGo = new GameObject("Text", typeof(RectTransform));
+            labelGo.transform.SetParent(go.transform, false);
+            UiRectHelper.StretchRect(labelGo.GetComponent<RectTransform>());
+            var label = labelGo.AddComponent<UiText>();
+            label.text = string.IsNullOrEmpty(r.Text) ? name : r.Text;
+            label.font = Resources.GetBuiltinResource<Font>("LegacyRuntime.ttf");
+            label.fontSize = r.FontSize ?? 24;
+            label.alignment = TextAnchor.MiddleCenter;
+            label.color = Color.black;
+            UiRectHelper.ApplyRect(go.GetComponent<RectTransform>(), r.Width, r.Height, r.X, r.Y);
+            var observedGo = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedButton = observedGo == null ? null : observedGo.GetComponent<UiButton>();
+            var observedImage = observedGo == null ? null : observedGo.GetComponent<UiImage>();
+            var observedLabel = observedGo == null ? null : observedGo.GetComponentInChildren<UiText>();
+            var observedRect = observedGo == null ? null : observedGo.GetComponent<RectTransform>();
+            if (observedGo == null || observedGo.transform.parent != parent.transform || observedRect == null || (r.Width.HasValue && !Mathf.Approximately(observedRect.sizeDelta.x, r.Width.Value)) || (r.Height.HasValue && !Mathf.Approximately(observedRect.sizeDelta.y, r.Height.Value)) || (r.X.HasValue && !Mathf.Approximately(observedRect.anchoredPosition.x, r.X.Value)) || (r.Y.HasValue && !Mathf.Approximately(observedRect.anchoredPosition.y, r.Y.Value)) || observedButton == null || observedImage == null || observedImage.color != requestedColor || observedLabel == null || observedLabel.text != label.text || observedLabel.fontSize != label.fontSize)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_BUTTON_READBACK_FAILED", "Created Button does not match the requested values.", "Check Unity Console for scene mutation errors.");
+            Selection.activeGameObject = go;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Element = UiToolSupport.BuildUiElementRef(go, "Button"), PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.button.create", Target = GameObjectToolSupport.HierarchyPath(go) } } });
+        }
+    }
+}
+#endif