@alpsckr/unitycli 0.4.0

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

@@ -0,0 +1,40 @@
+#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.canvas.create — 创建 uGUI Canvas。</summary>
+    public class UiCanvasCreateTool : IUnityCliTool<UiCanvasCreateTool.Request, UiCanvasCreateTool.Result>
+    {
+        public sealed class Request { public string Name { get; set; } }
+        public sealed class Result { public UiElementRef Element { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.canvas.create", Summary = "Create a uGUI Canvas with CanvasScaler and GraphicRaycaster.", Description = "Create a ScreenSpaceOverlay Canvas with ScaleWithScreenSize mode (1920x1080 reference).", Group = "ui",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create Canvas", Input = new Request { Name = "MainCanvas" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var name = string.IsNullOrEmpty(r.Name) ? "Canvas" : r.Name;
+            ctx.CommitEffect();
+            var go = new GameObject(name, typeof(RectTransform), typeof(Canvas), typeof(UiCanvasScaler), typeof(UiGraphicRaycaster));
+            var canvas = go.GetComponent<Canvas>();
+            canvas.renderMode = RenderMode.ScreenSpaceOverlay;
+            var scaler = go.GetComponent<UiCanvasScaler>();
+            scaler.uiScaleMode = UiCanvasScaler.ScaleMode.ScaleWithScreenSize;
+            scaler.referenceResolution = new Vector2(1920, 1080);
+            var observedGo = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedCanvas = observedGo == null ? null : observedGo.GetComponent<Canvas>();
+            var observedScaler = observedGo == null ? null : observedGo.GetComponent<UiCanvasScaler>();
+            var observedRaycaster = observedGo == null ? null : observedGo.GetComponent<UiGraphicRaycaster>();
+            if (observedGo == null || observedGo.transform.parent != null || observedGo.GetComponent<RectTransform>() == null || observedCanvas == null || observedCanvas.renderMode != RenderMode.ScreenSpaceOverlay || observedScaler == null || observedScaler.uiScaleMode != UiCanvasScaler.ScaleMode.ScaleWithScreenSize || observedScaler.referenceResolution != new Vector2(1920, 1080) || observedRaycaster == null)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_CANVAS_READBACK_FAILED", "Created Canvas does not match required components and settings.", "Check Unity Console for scene mutation errors.");
+            Selection.activeGameObject = observedGo;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Element = UiToolSupport.BuildUiElementRef(go, "Canvas"), PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.canvas.create", Target = GameObjectToolSupport.HierarchyPath(go) } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/create-panel-settings.cs

@@ -0,0 +1,44 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.create-panel-settings — 创建 PanelSettings 资产。</summary>
+    public class UiCreatePanelSettingsTool : IUnityCliTool<UiCreatePanelSettingsTool.Request, UiCreatePanelSettingsTool.Result>
+    {
+        public sealed class Request { public string Path { get; set; } public string ScaleMode { get; set; } public int? ReferenceWidth { get; set; } public int? ReferenceHeight { get; set; } public int? SortingOrder { get; set; } }
+        public sealed class Result { public UiPanelSettingsInfo PanelSettings { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.create-panel-settings", Summary = "Create a PanelSettings asset for UI Toolkit.", Description = "Create a .asset PanelSettings with scale mode and reference resolution. dryRun=true previews.", Group = "ui",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create PanelSettings", Input = new Request { Path = "Assets/UI/Panel.asset" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            UiToolSupport.EnsureEditorNotBusy("ui.create-panel-settings");
+            var path = AssetToolSupport.RequireAssetPath(r.Path);
+            if (!path.EndsWith(".asset", System.StringComparison.OrdinalIgnoreCase)) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_PATH_REQUIRED", "Pass an Assets/*.asset path.", "Pass a canonical Assets/*.asset path.");
+            if (AssetToolSupport.AssetExists(path)) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_EXISTS", "PanelSettings asset already exists: " + path, "Choose a new path.");
+            if (!string.IsNullOrEmpty(r.ScaleMode) && !string.Equals(r.ScaleMode, "constantpixelsize", System.StringComparison.OrdinalIgnoreCase) && !string.Equals(r.ScaleMode, "scalewithscreensize", System.StringComparison.OrdinalIgnoreCase)) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_SCALE_MODE_INVALID", "ScaleMode must be ConstantPixelSize or ScaleWithScreenSize.", "Pass a documented PanelScaleMode value.");
+            if ((r.ReferenceWidth.HasValue && r.ReferenceWidth.Value <= 0) || (r.ReferenceHeight.HasValue && r.ReferenceHeight.Value <= 0)) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_RANGE_INVALID", "Reference dimensions must be positive.", "Pass positive reference dimensions.");
+            var scaleMode = string.Equals(r.ScaleMode, "constantpixelsize", System.StringComparison.OrdinalIgnoreCase) ? PanelScaleMode.ConstantPixelSize : PanelScaleMode.ScaleWithScreenSize;
+            var resolution = new Vector2Int(r.ReferenceWidth ?? 1920, r.ReferenceHeight ?? 1080);
+            var sortingOrder = r.SortingOrder ?? 0;
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.create-panel-settings", Path = path } } });
+            ctx.CommitEffect();
+            SceneToolSupport.CreateAssetDirectory(path);
+            var panel = ScriptableObject.CreateInstance<PanelSettings>();
+            panel.scaleMode = scaleMode;
+            panel.referenceResolution = resolution;
+            panel.sortingOrder = sortingOrder;
+            AssetDatabase.CreateAsset(panel, path);
+            AssetDatabase.SaveAssets();
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            var observed = AssetDatabase.LoadAssetAtPath<PanelSettings>(path);
+            if (observed == null || observed.scaleMode != scaleMode || observed.referenceResolution != resolution || observed.sortingOrder != sortingOrder) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_READBACK_FAILED", "Created PanelSettings could not be verified: " + path, "Check Unity Console for asset import errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { PanelSettings = new UiPanelSettingsInfo { Path = AssetDatabase.GetAssetPath(observed), ScaleMode = observed.scaleMode.ToString(), ReferenceWidth = observed.referenceResolution.x, ReferenceHeight = observed.referenceResolution.y, SortingOrder = observed.sortingOrder }, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.create-panel-settings", Path = path } } });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,41 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.detach-document — 从 GameObject 移除 UIDocument 组件。</summary>
+    public class UiDetachDocumentTool : IUnityCliTool<UiDetachDocumentTool.Request, UiDetachDocumentTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } }
+        public sealed class Result { public bool Attached { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.detach-document", Summary = "Remove a UIDocument component from a target GameObject.", Description = "Remove UIDocument component. Only affects current scene session. 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 = "Detach UIDocument", Input = new Request { Target = "Player" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            UiToolSupport.EnsureEditorNotBusy("ui.detach-document");
+            var go = UnityCliBridge.ObjectRefResolver.FindGameObjectByPath(r.Target);
+            if (go == null) throw new UnityCliBridge.BridgeCommandException("E_TARGET_NOT_FOUND", "ui.detach-document requires a target GameObject.", "Pass --target <path>.");
+            var doc = go.GetComponent<UIDocument>();
+            if (doc == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_NOT_FOUND", "No UIDocument on target: " + r.Target, "Pass a target with a UIDocument.");
+            var targetId = go.GetInstanceID();
+            var dryRun = ctx.DryRun;
+            if (!dryRun)
+            {
+                ctx.CommitEffect();
+                UnityCliSceneMutation.DestroyObject(doc);
+                UnityCliSceneMutation.MarkSceneDirty(go.scene);
+                var observedGo = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+                var observedDocument = observedGo == null || observedGo.GetInstanceID() != targetId ? null : observedGo.GetComponent<UIDocument>();
+                if (observedDocument != null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_READBACK_FAILED", "UIDocument is still attached after detach: " + r.Target, "Check Unity Console for scene mutation errors.");
+                go = observedGo;
+            }
+            if (go == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_READBACK_FAILED", "Target GameObject could not be re-resolved after detach: " + r.Target, "Check Unity Console for scene mutation errors.");
+            var observed = go.GetComponent<UIDocument>();
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Attached = observed != null, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.detach-document", Target = GameObjectToolSupport.HierarchyPath(go) } } });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,49 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.document.create — 创建 UXML/USS 资产和 UIDocument GameObject。</summary>
+    public class UiDocumentCreateTool : IUnityCliTool<UiDocumentCreateTool.Request, UiDocumentCreateTool.Result>
+    {
+        public sealed class Request { public string Name { get; set; } public string Uxml { get; set; } public string Uss { get; set; } public string PanelSettings { get; set; } public bool? Overwrite { get; set; } }
+        public sealed class Result { public UiDocumentLiveInfo Document { get; set; } public UiElementRef Target { get; set; } public bool Attached { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.document.create", Summary = "Create a UIDocument GameObject with UXML/USS assets and optional PanelSettings.", Description = "Create .uxml (and optional .uss) text assets, then a UIDocument GameObject linking them. overwrite=true to replace existing assets.", Group = "ui",DestructiveHint = true, SideEffects = new[] { "asset-write", "scene-modify" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create UIDocument", Input = new Request { Name = "UIDocument", Uxml = "Assets/UI/Main.uxml" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            UiToolSupport.EnsureEditorNotBusy("ui.document.create");
+            var name = string.IsNullOrEmpty(r.Name) ? "UIDocument" : r.Name;
+            var uxmlPath = UiToolSupport.RequireUxmlPath(r.Uxml);
+            var ussPath = string.IsNullOrEmpty(r.Uss) ? null : UiToolSupport.RequireUssPath(r.Uss);
+            var overwrite = r.Overwrite ?? false;
+            UiToolSupport.ValidateTextAssetCreation(uxmlPath, overwrite, "E_UI_UXML_EXISTS");
+            if (!string.IsNullOrEmpty(ussPath)) UiToolSupport.ValidateTextAssetCreation(ussPath, overwrite, "E_UI_USS_EXISTS");
+            PanelSettings panelSettings = null;
+            if (!string.IsNullOrEmpty(r.PanelSettings)) { var panelSettingsPath = AssetToolSupport.RequireExistingAssetPath(r.PanelSettings); panelSettings = AssetDatabase.LoadAssetAtPath<PanelSettings>(panelSettingsPath); if (panelSettings == null) throw new UnityCliBridge.BridgeCommandException("E_UI_PANEL_SETTINGS_NOT_FOUND", "PanelSettings asset not found: " + panelSettingsPath, "Create a PanelSettings asset or pass a valid path."); }
+            ctx.CommitEffect();
+            UiToolSupport.EnsureTextAsset(uxmlPath, UiToolSupport.DefaultUxml(ussPath));
+            if (!string.IsNullOrEmpty(ussPath)) UiToolSupport.EnsureTextAsset(ussPath, UiToolSupport.DefaultUss());
+            var go = new GameObject(name, typeof(UIDocument));
+            var documentObjectId = go.GetInstanceID();
+            var panelSettingsId = panelSettings == null ? 0 : panelSettings.GetInstanceID();
+            var doc = go.GetComponent<UIDocument>();
+            doc.visualTreeAsset = UiToolSupport.LoadVisualTreeAsset(uxmlPath);
+            if (panelSettings != null) doc.panelSettings = panelSettings;
+            Selection.activeGameObject = go;
+            EditorUtility.SetDirty(doc);
+            AssetDatabase.SaveAssets();
+            var observedUxml = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>(uxmlPath);
+            var observedUss = string.IsNullOrEmpty(ussPath) ? null : AssetDatabase.LoadAssetAtPath<StyleSheet>(ussPath);
+            var observedGo = EditorUtility.InstanceIDToObject(documentObjectId) as GameObject;
+            var observedPanelSettings = panelSettingsId == 0 ? null : EditorUtility.InstanceIDToObject(panelSettingsId) as PanelSettings;
+            var observedDocument = observedGo == null || observedGo.GetInstanceID() != documentObjectId ? null : observedGo.GetComponent<UIDocument>();
+            if (observedUxml == null || observedDocument == null || observedDocument.visualTreeAsset != observedUxml || (panelSettingsId != 0 && (observedPanelSettings == null || observedDocument.panelSettings != observedPanelSettings)) || (!string.IsNullOrEmpty(ussPath) && observedUss == null))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_READBACK_FAILED", "Created UIDocument could not be verified.", "Check Unity Console for asset import or scene serialization errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Document = new UiDocumentLiveInfo { VisualTreeAsset = observedDocument.visualTreeAsset == null ? null : AssetDatabase.GetAssetPath(observedDocument.visualTreeAsset), PanelSettings = observedDocument.panelSettings == null ? null : AssetDatabase.GetAssetPath(observedDocument.panelSettings), SortingOrder = observedDocument.sortingOrder }, Target = UiToolSupport.BuildUiElementRef(observedGo, "UIDocument"), Attached = true, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.document.create", Target = GameObjectToolSupport.HierarchyPath(observedGo), Uxml = uxmlPath, Uss = ussPath } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/document/delete.cs

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.document.delete — 删除 UXML/USS 资产。</summary>
+    public class UiDocumentDeleteTool : IUnityCliTool<UiDocumentDeleteTool.Request, UiDocumentDeleteTool.Result>
+    {
+        public sealed class Request { public string Uxml { get; set; } public string Path { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public UiDocumentAssetInfo Document { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.document.delete", Summary = "Delete a .uxml or .uss UI document asset.", Description = "Delete the asset via AssetDatabase.DeleteAsset. dryRun=true previews.", Group = "ui",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Delete UXML", Input = new Request { Uxml = "Assets/UI/Main.uxml" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = UiToolSupport.RequireUiDocumentAssetPath(r.Uxml ?? r.Path);
+            if (!AssetToolSupport.AssetExists(path))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_NOT_FOUND", "UI document asset not found: " + path, "Pass an existing Assets/*.uxml or Assets/*.uss path.");
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, Document = new UiDocumentAssetInfo { Path = path, Exists = AssetDatabase.LoadAssetAtPath<UnityEngine.Object>(path) != null }, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.document.delete", Path = path } } });
+            ctx.CommitEffect();
+            if (!AssetDatabase.DeleteAsset(path)) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_DELETE_FAILED", "Failed to delete UI document asset: " + path, "Check Unity Console and file permissions.");
+            AssetDatabase.Refresh();
+            var observedAsset = AssetDatabase.LoadAssetAtPath<UnityEngine.Object>(path);
+            var observedExists = observedAsset != null || File.Exists(SceneToolSupport.AssetFullPath(path));
+            if (observedExists) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_READBACK_FAILED", "Deleted UI document is still present: " + path, "Check Unity Console and file permissions.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, Document = new UiDocumentAssetInfo { Path = path, Exists = observedExists }, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.document.delete", Path = path } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/document/info.cs

@@ -0,0 +1,33 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.document.info — 读取 UIDocument 或 UXML 文件信息。</summary>
+    public class UiDocumentInfoTool : IUnityCliTool<UiDocumentInfoTool.Request, UiDocumentInfoTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string Path { get; set; } public string Uss { get; set; } }
+        public sealed class Result { public UiDocumentLiveInfo Document { get; set; } public UiDocumentAssetInfo Asset { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.document.info", Summary = "Inspect a UIDocument or UI document asset in the selected Editor.", Description = "Pass target for a live UIDocument inspection, or an Assets/*.uxml path for AssetDatabase metadata. Both modes execute through the selected open Editor. Use uss for an associated stylesheet asset.", Group = "ui",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read UIDocument", Input = new Request { Target = "UIDocument" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!string.IsNullOrEmpty(r.Target))
+            {
+                var go = UiToolSupport.ResolveGameObjectTarget(r.Target);
+                var doc = go.GetComponent<UIDocument>();
+                if (doc == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_NOT_FOUND", "UIDocument target not found: " + r.Target, "Pass a UIDocument GameObject or an Assets/*.uxml path.");
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Document = new UiDocumentLiveInfo { VisualTreeAsset = doc.visualTreeAsset?.name, PanelSettings = doc.panelSettings?.name, SortingOrder = doc.sortingOrder } });
+            }
+            var path = SceneToolSupport.NormalizeAssetPath(r.Path);
+            if (string.IsNullOrEmpty(path)) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_PATH_REQUIRED", "UIDocument info requires a target or Assets/*.uxml path.", "Pass a target or path.");
+            var vta = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>(path);
+            var ss = string.IsNullOrEmpty(r.Uss) ? null : AssetDatabase.LoadAssetAtPath<StyleSheet>(r.Uss);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Asset = new UiDocumentAssetInfo { Path = path, Name = Path.GetFileNameWithoutExtension(path), Exists = vta != null, VisualTreeName = vta?.name, StyleSheetName = ss?.name } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/document/update.cs

@@ -0,0 +1,36 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.document.update — 更新 UXML 文本内容。</summary>
+    public class UiDocumentUpdateTool : IUnityCliTool<UiDocumentUpdateTool.Request, UiDocumentUpdateTool.Result>
+    {
+        public sealed class Request { public string Uxml { get; set; } public string Path { get; set; } public string Content { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public UiDocumentAssetInfo Document { get; set; } public long SizeBytes { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.document.update", Summary = "Update the text content of an existing .uxml asset.", Description = "Write new content to an existing .uxml file and reimport. dryRun=true previews.", Group = "ui",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Update UXML", Input = new Request { Uxml = "Assets/UI/Main.uxml", Content = "<ui:UXML />" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var path = SceneToolSupport.NormalizeAssetPath(r.Uxml ?? r.Path);
+            if (string.IsNullOrEmpty(path) || !path.EndsWith(".uxml")) throw new UnityCliBridge.BridgeCommandException("E_UI_UXML_PATH_REQUIRED", "Pass an Assets/*.uxml path.", "");
+            if (r.Content == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_CONTENT_REQUIRED", "ui.document.update requires content.", "Pass --content or structured input content.");
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.document.update", Uxml = path } } });
+            var fullPath = SceneToolSupport.AssetFullPath(path);
+            if (!File.Exists(fullPath)) throw new UnityCliBridge.BridgeCommandException("E_UI_UXML_NOT_FOUND", "VisualTreeAsset not found: " + path, "Pass an existing Assets/*.uxml path.");
+            ctx.CommitEffect();
+            File.WriteAllText(fullPath, r.Content, System.Text.Encoding.UTF8);
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            AssetDatabase.SaveAssets();
+            var observedContent = File.ReadAllText(fullPath, System.Text.Encoding.UTF8);
+            var observedAsset = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>(path);
+            if (observedAsset == null || observedContent != r.Content) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_READBACK_FAILED", "Updated UXML could not be verified: " + path, "Check Unity Console for UXML import errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, Document = new UiDocumentAssetInfo { Path = AssetDatabase.GetAssetPath(observedAsset), Name = observedAsset.name, Exists = File.Exists(fullPath) }, SizeBytes = new FileInfo(fullPath).Length, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.document.update", Uxml = path } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/get-visual-tree.cs

@@ -0,0 +1,34 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.get-visual-tree — 读取 UIDocument 可视树结构。</summary>
+    public class UiGetVisualTreeTool : IUnityCliTool<UiGetVisualTreeTool.Request, UiGetVisualTreeTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string Parent { get; set; } public int? MaxDepth { get; set; } }
+        public sealed class Result { public List<UiHierarchyItem> Items { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.get-visual-tree", Summary = "Read the visual tree hierarchy of a live UIDocument.", Description = "Traverse the VisualElement hierarchy of a UIDocument's root. Returns element names and types.", Group = "ui",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Read visual tree", Input = new Request { Target = "UIDocument" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var go = UiToolSupport.ResolveGameObjectTarget(r.Target);
+            var doc = go.GetComponent<UIDocument>();
+            if (doc == null || doc.rootVisualElement == null) return new System.Threading.Tasks.ValueTask<Result>(new Result { Items = new List<UiHierarchyItem>() });
+            var items = new List<UiHierarchyItem>();
+            TraverseVisualElement(doc.rootVisualElement, "", 0, r.MaxDepth ?? 10, items);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Items = items });
+        }
+        private static void TraverseVisualElement(VisualElement ve, string parentPath, int depth, int maxDepth, List<UiHierarchyItem> items)
+        {
+            if (depth > maxDepth) return;
+            var path = string.IsNullOrEmpty(parentPath) ? ve.name : parentPath + "/" + ve.name;
+            items.Add(new UiHierarchyItem { Name = ve.name, Path = path, Type = ve.GetType().Name, ChildCount = ve.childCount });
+            foreach (var child in ve.Children()) TraverseVisualElement(child, path, depth + 1, maxDepth, items);
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,27 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.hierarchy — 列出 uGUI/UI Toolkit 层级。</summary>
+    public class UiHierarchyTool : IUnityCliTool<UiHierarchyTool.Request, UiHierarchyTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string Parent { get; set; } public int? PageSize { get; set; } }
+        public sealed class Result { public List<UiHierarchyItem> Items { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.hierarchy", Summary = "List uGUI and UI Toolkit elements in the scene hierarchy.", Description = "Find Canvas, UIDocument, and visual element GameObjects. Optionally filter by target/parent.", Group = "ui",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "List UI hierarchy", Input = new Request { } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var items = new List<UiHierarchyItem>();
+            var canvases = UnityEngine.Object.FindObjectsOfType<Canvas>();
+            foreach (var c in canvases) items.Add(new UiHierarchyItem { Name = c.gameObject.name, Path = GameObjectToolSupport.HierarchyPath(c.gameObject), Type = "Canvas", ChildCount = c.transform.childCount });
+            var docs = UnityEngine.Object.FindObjectsOfType<UIDocument>();
+            foreach (var d in docs) items.Add(new UiHierarchyItem { Name = d.gameObject.name, Path = GameObjectToolSupport.HierarchyPath(d.gameObject), Type = "UIDocument", ChildCount = d.transform.childCount });
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Items = items });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,47 @@
+#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.image.create — 创建 uGUI Image 元素。</summary>
+    public class UiImageCreateTool : IUnityCliTool<UiImageCreateTool.Request, UiImageCreateTool.Result>
+    {
+        public sealed class Request { public string Name { get; set; } public string Parent { get; set; } public string Sprite { 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.image.create", Summary = "Create a uGUI Image element with optional sprite.", Description = "Create an Image element. Pass --sprite for an Assets/* sprite path.", Group = "ui",DestructiveHint = false, SideEffects = new[] { "scene-modify" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Create Image", Input = new Request { Parent = "Canvas" } } } };
+        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) throw new UnityCliBridge.BridgeCommandException("E_UI_PARENT_NOT_FOUND", "UI parent Canvas or RectTransform not found: " + r.Parent, "Create a Canvas first.");
+            var name = string.IsNullOrEmpty(r.Name) ? "Image" : r.Name;
+            var requestedColor = string.IsNullOrEmpty(r.Color) ? Color.white : GraphicsToolSupport.ParseColor(r.Color);
+            var spritePath = SceneToolSupport.NormalizeAssetPath(r.Sprite);
+            var requestedSprite = string.IsNullOrEmpty(spritePath) ? null : AssetDatabase.LoadAssetAtPath<Sprite>(spritePath);
+            if (!string.IsNullOrEmpty(spritePath) && requestedSprite == null)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_SPRITE_NOT_FOUND", "Sprite asset not found: " + spritePath, "Pass an Assets/* sprite path or omit --sprite.");
+            UiToolSupport.ValidateUguiRequest(null, 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;
+            image.sprite = requestedSprite;
+            UiRectHelper.ApplyRect(go.GetComponent<RectTransform>(), r.Width, r.Height, r.X, r.Y);
+            var observedGo = EditorUtility.InstanceIDToObject(go.GetInstanceID()) as GameObject;
+            var observedImage = observedGo == null ? null : observedGo.GetComponent<UiImage>();
+            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)) || observedImage == null || observedImage.sprite != requestedSprite || observedImage.color != requestedColor)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_IMAGE_READBACK_FAILED", "Created Image does not match the requested sprite or color.", "Check Unity Console for scene mutation errors.");
+            Selection.activeGameObject = go;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Element = UiToolSupport.BuildUiElementRef(go, "Image"), PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.image.create", Target = GameObjectToolSupport.HierarchyPath(go) } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/link-stylesheet.cs

@@ -0,0 +1,54 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.link-stylesheet — 链接 USS 到 UXML。</summary>
+    public class UiLinkStylesheetTool : IUnityCliTool<UiLinkStylesheetTool.Request, UiLinkStylesheetTool.Result>
+    {
+        public sealed class Request { public string Path { get; set; } public string Uss { get; set; } public string StyleSheet { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.link-stylesheet", Summary = "Link a .uss stylesheet to a .uxml document by appending a Style element.", Description = "Append <Style src=\"...\" /> to the .uxml file. dryRun=true previews.", Group = "ui",DestructiveHint = true, SupportsDryRun = true, SideEffects = new[] { "asset-write" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Link stylesheet", Input = new Request { Path = "Assets/UI/Main.uxml", Uss = "Assets/UI/Main.uss" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var uxmlPath = SceneToolSupport.NormalizeAssetPath(r.Path);
+            var ussPath = SceneToolSupport.NormalizeAssetPath(r.Uss ?? r.StyleSheet);
+            if (string.IsNullOrEmpty(uxmlPath) || string.IsNullOrEmpty(ussPath)) throw new UnityCliBridge.BridgeCommandException("E_UI_PATH_REQUIRED", "ui.link-stylesheet requires --path (uxml) and --uss.", "Pass both uxml and uss paths.");
+            var dryRun = ctx.DryRun;
+            if (dryRun) return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = true, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.link-stylesheet", Path = uxmlPath, Uss = ussPath } } });
+            var uxmlFullPath = SceneToolSupport.AssetFullPath(uxmlPath);
+            var requestedStyleSheet = UiToolSupport.LoadStyleSheet(ussPath);
+            var content = File.ReadAllText(uxmlFullPath);
+            var styleLine = "  <Style src=\"" + Path.GetFileName(ussPath) + "\" />\n";
+            if (!content.Contains(styleLine.Trim()))
+            {
+                var insertIdx = content.LastIndexOf("</ui:UXML>");
+                if (insertIdx < 0) insertIdx = content.LastIndexOf("<");
+                if (insertIdx >= 0) content = content.Insert(insertIdx, styleLine);
+                else content += styleLine;
+            }
+            ctx.CommitEffect();
+            File.WriteAllText(uxmlFullPath, content, System.Text.Encoding.UTF8);
+            AssetDatabase.ImportAsset(uxmlPath, ImportAssetOptions.ForceUpdate);
+            AssetDatabase.SaveAssets();
+            var observedContent = File.ReadAllText(uxmlFullPath, System.Text.Encoding.UTF8);
+            var observedDocument = AssetDatabase.LoadAssetAtPath<VisualTreeAsset>(uxmlPath);
+            var observedStyleSheet = AssetDatabase.LoadAssetAtPath<StyleSheet>(ussPath);
+            var expectedSource = Path.GetFileName(AssetDatabase.GetAssetPath(requestedStyleSheet));
+            var parsed = System.Xml.Linq.XDocument.Parse(observedContent);
+            var linked = false;
+            foreach (var element in parsed.Descendants())
+            {
+                var source = element.Attribute("src");
+                if (element.Name.LocalName == "Style" && source != null && source.Value == expectedSource) { linked = true; break; }
+            }
+            if (observedDocument == null || observedStyleSheet == null || !linked) throw new UnityCliBridge.BridgeCommandException("E_UI_STYLESHEET_READBACK_FAILED", "Stylesheet link could not be verified: " + uxmlPath, "Check Unity Console for UXML import errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = false, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.link-stylesheet", Path = uxmlPath, Uss = ussPath } } });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/list-documents.cs

@@ -0,0 +1,34 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.list-documents — 列出 UI 文档资产。</summary>
+    public class UiListDocumentsTool : IUnityCliTool<UiListDocumentsTool.Request, UiListDocumentsTool.Result>
+    {
+        public sealed class Request { public string Kind { get; set; } public int? PageSize { get; set; } }
+        public sealed class Result { public List<UiDocumentAssetInfo> Items { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.list-documents", Summary = "List UXML and USS assets in the project.", Description = "Search AssetDatabase for .uxml and .uss assets. kind=uxml or uss to filter.", Group = "ui",DestructiveHint = false, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "List UXML assets", Input = new Request { Kind = "uxml" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var items = new List<UiDocumentAssetInfo>();
+            var kind = r.Kind ?? "all";
+            if (kind == "all" || kind == "uxml")
+            {
+                var guids = AssetDatabase.FindAssets("t:VisualTreeAsset");
+                foreach (var g in guids) { var p = AssetDatabase.GUIDToAssetPath(g); items.Add(new UiDocumentAssetInfo { Path = p, Name = Path.GetFileNameWithoutExtension(p), Exists = true }); }
+            }
+            if (kind == "all" || kind == "uss")
+            {
+                var guids = AssetDatabase.FindAssets("t:StyleSheet");
+                foreach (var g in guids) { var p = AssetDatabase.GUIDToAssetPath(g); items.Add(new UiDocumentAssetInfo { Path = p, Name = Path.GetFileNameWithoutExtension(p), Exists = true }); }
+            }
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Items = items });
+        }
+    }
+}
+#endif

package/unitypkg/Editor/Tools/ui/modify-visual-element.cs

@@ -0,0 +1,76 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+using UnityEngine;
+using UnityEngine.UIElements;
+
+namespace UnityCli
+{
+    /// <summary>ui.modify-visual-element — 修改 VisualElement 属性。</summary>
+    public class UiModifyVisualElementTool : IUnityCliTool<UiModifyVisualElementTool.Request, UiModifyVisualElementTool.Result>
+    {
+        public sealed class Request { public string Target { get; set; } public string ElementName { get; set; } public string Text { get; set; } public string Display { get; set; } public float? Width { get; set; } public float? Height { get; set; } public string AddClass { get; set; } public string RemoveClass { get; set; } }
+        public sealed class Result { public bool DryRun { get; set; } public UiVisualElementInfo Element { get; set; } public List<UiPlannedEffect> PlannedEffects { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "ui.modify-visual-element", Summary = "Modify a VisualElement in a live UIDocument by name.", Description = "Find a VisualElement by name in a UIDocument and modify text/display/size/classes. dryRun=true previews.", Group = "ui",DestructiveHint = false, SupportsDryRun = true, SideEffects = new[] { "ui-document-session-state" }, Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 600000, Examples = new[] { new ToolExample { Description = "Set text", Input = new Request { Target = "UIDocument", ElementName = "label", Text = "Updated" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request r, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var resolvedGo = UiToolSupport.ResolveGameObjectTarget(r.Target);
+            var targetId = resolvedGo.GetInstanceID();
+            var go = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+            var doc = go == null ? null : go.GetComponent<UIDocument>();
+            if (go == null || go.GetInstanceID() != targetId || doc == null || doc.rootVisualElement == null) throw new UnityCliBridge.BridgeCommandException("E_UI_DOCUMENT_NOT_FOUND", "No UIDocument with a visual tree on target.", "Pass a target with a UIDocument.");
+            var dryRun = ctx.DryRun;
+            var element = doc.rootVisualElement.Q(r.ElementName);
+            if (element == null) throw new UnityCliBridge.BridgeCommandException("E_UI_ELEMENT_NOT_FOUND", "VisualElement not found: " + r.ElementName, "Pass a valid element name.");
+            var textElement = element as TextElement;
+            if (r.Text != null && textElement == null)
+                throw new UnityCliBridge.BridgeCommandException("E_UI_ELEMENT_TEXT_UNSUPPORTED", "VisualElement does not support text: " + r.ElementName, "Target a Label/TextElement or omit the text field.");
+            DisplayStyle requestedDisplay = default;
+            if (!string.IsNullOrEmpty(r.Display) && !System.Enum.TryParse(r.Display, true, out requestedDisplay))
+                throw new UnityCliBridge.BridgeCommandException("E_UI_DISPLAY_INVALID", "Unsupported display value: " + r.Display, "Pass a valid DisplayStyle value.");
+            UiToolSupport.ValidateVisualElementSize(r.Width, r.Height);
+            var hasRequestedMutation = r.Text != null || !string.IsNullOrEmpty(r.Display) || r.Width.HasValue || r.Height.HasValue || !string.IsNullOrEmpty(r.AddClass) || !string.IsNullOrEmpty(r.RemoveClass);
+            if (!dryRun && hasRequestedMutation)
+            {
+                ctx.CommitEffect();
+                if (r.Text != null)
+                {
+                    textElement.text = r.Text;
+                }
+                if (!string.IsNullOrEmpty(r.Display)) element.style.display = requestedDisplay;
+                if (r.Width.HasValue) element.style.width = r.Width.Value;
+                if (r.Height.HasValue) element.style.height = r.Height.Value;
+                if (!string.IsNullOrEmpty(r.AddClass)) element.AddToClassList(r.AddClass);
+                if (!string.IsNullOrEmpty(r.RemoveClass)) element.RemoveFromClassList(r.RemoveClass);
+
+                // 写入后按实例 ID 重新解析场景对象和文档，确保读回来自当前对象。
+                var observedGo = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+                var observedDocument = observedGo == null || observedGo.GetInstanceID() != targetId ? null : observedGo.GetComponent<UIDocument>();
+                var observed = observedDocument == null || observedDocument.rootVisualElement == null ? null : observedDocument.rootVisualElement.Q(r.ElementName);
+                if (observed == null ||
+                    (r.Text != null && (!(observed is TextElement observedText) || observedText.text != r.Text)) ||
+                    (!string.IsNullOrEmpty(r.Display) && observed.style.display.value != requestedDisplay) ||
+                    (r.Width.HasValue && !Mathf.Approximately(observed.style.width.value.value, r.Width.Value)) ||
+                    (r.Height.HasValue && !Mathf.Approximately(observed.style.height.value.value, r.Height.Value)) ||
+                    (!string.IsNullOrEmpty(r.AddClass) && !observed.ClassListContains(r.AddClass)) ||
+                    (!string.IsNullOrEmpty(r.RemoveClass) && observed.ClassListContains(r.RemoveClass)))
+                    throw new UnityCliBridge.BridgeCommandException("E_UI_ELEMENT_READBACK_FAILED", "VisualElement does not match the requested changes: " + r.ElementName, "Check the UIDocument visual tree and retry.");
+                element = observed;
+            }
+            else if (!hasRequestedMutation)
+            {
+                // 空请求是只读操作；重新解析确保返回当前场景对象的状态而不提交 effect。
+                var observedGo = EditorUtility.InstanceIDToObject(targetId) as GameObject;
+                var observedDocument = observedGo == null || observedGo.GetInstanceID() != targetId ? null : observedGo.GetComponent<UIDocument>();
+                var observed = observedDocument == null || observedDocument.rootVisualElement == null ? null : observedDocument.rootVisualElement.Q(r.ElementName);
+                if (observed == null)
+                    throw new UnityCliBridge.BridgeCommandException("E_UI_ELEMENT_READBACK_FAILED", "VisualElement could not be re-resolved: " + r.ElementName, "Check the UIDocument visual tree and retry.");
+                element = observed;
+            }
+            var observedTextElement = element as TextElement;
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { DryRun = dryRun, Element = new UiVisualElementInfo { Name = element.name, Text = observedTextElement == null ? null : observedTextElement.text, Display = element.style.display.value.ToString(), Width = element.style.width.value.value, Height = element.style.height.value.value, Classes = new List<string>(element.GetClasses()).ToArray() }, PlannedEffects = new List<UiPlannedEffect> { new UiPlannedEffect { Type = "ui.modify-visual-element", Target = r.ElementName } } });
+        }
+    }
+}
+#endif