@alpsckr/unitycli 0.4.0

package/extensions/vfx-graph/unitypkg/Editor/Vfx/control-pause.cs

@@ -0,0 +1,37 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>切换目标 VisualEffect 的暂停状态。</summary>
+    public sealed class VfxControlPauseTool : IUnityCliTool<VfxControlPauseTool.Request, VfxControlActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.control.pause", Summary = "Toggle VisualEffect pause state.",
+            Description = "Toggle the public pause property on the existing VisualEffect component.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Toggle emitter pause", Input = new Request { Target = "Effects/Emitter" } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxControlActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.control.pause");
+            var paused = VfxActionToolSupport.ReadBool(effect, "pause");
+            if (!paused.HasValue) throw new UnityCliBridge.BridgeCommandException("E_VFX_PROPERTY_UNSUPPORTED", "VisualEffect pause state is unavailable.", "Check the installed Visual Effect Graph package version.");
+            var expected = !paused.Value;
+            var gameObjectId = effect.gameObject.GetInstanceID(); var effectType = effect.GetType();
+            VfxActionToolSupport.PrepareWritableBoolProperty(effectType, "pause");
+            ctx.CommitEffect();
+
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.pause");
+            VfxActionToolSupport.SetRequired(effect, "pause", expected);
+            await VfxActionToolSupport.RequirePauseState(effect, expected, "vfx.control.pause", ctx, ct);
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.pause");
+            return VfxActionToolSupport.BuildControlResult(effect, "vfx.control.pause", ctx.LogPath);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/control-play.cs

@@ -0,0 +1,40 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>启动目标 VisualEffect 的播放。</summary>
+    public sealed class VfxControlPlayTool : IUnityCliTool<VfxControlPlayTool.Request, VfxControlActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.control.play", Summary = "Play a VisualEffect component.",
+            Description = "Play the VisualEffect and prove a running transition through pause=false plus a changed positive aliveParticleCount. Fails closed when the graph exposes no observable particle transition.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Play the matrix emitter", Input = new Request { Target = "Effects/Emitter" } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxControlActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.control.play");
+            var beforeAlive = VfxActionToolSupport.ReadLong(effect, "aliveParticleCount");
+            if (!beforeAlive.HasValue)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_STATE_UNOBSERVABLE", "VisualEffect aliveParticleCount is unavailable for play proof.", "Use a Visual Effect Graph version exposing aliveParticleCount.");
+            var gameObjectId = effect.gameObject.GetInstanceID(); var effectType = effect.GetType();
+            VfxActionToolSupport.PrepareControlMethod(effectType, "Play");
+            VfxActionToolSupport.PrepareWritableBoolProperty(effectType, "pause");
+            ctx.CommitEffect();
+
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.play");
+            VfxActionToolSupport.InvokeRequired(effect, "Play");
+            VfxActionToolSupport.SetRequired(effect, "pause", false);
+            await VfxActionToolSupport.RequirePauseState(effect, false, "play", ctx, ct);
+            await VfxActionToolSupport.RequireAliveState(effect, count => count > 0 && count != beforeAlive.Value, "play", ctx, ct);
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.play");
+            return VfxActionToolSupport.BuildControlResult(effect, "vfx.control.play", ctx.LogPath);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/control-reinitialize.cs

@@ -0,0 +1,37 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>重新初始化目标 VisualEffect。</summary>
+    public sealed class VfxControlReinitializeTool : IUnityCliTool<VfxControlReinitializeTool.Request, VfxControlActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.control.reinitialize", Summary = "Reinitialize a VisualEffect component.",
+            Description = "Invoke Reinit and prove the reset by observing a transition from a positive aliveParticleCount to zero. Fails closed when no observable active particles exist before the call.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Reinitialize the matrix emitter", Input = new Request { Target = "Effects/Emitter" } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxControlActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.control.reinitialize");
+            var beforeAlive = VfxActionToolSupport.ReadLong(effect, "aliveParticleCount");
+            if (!beforeAlive.HasValue || beforeAlive.Value <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_STATE_UNOBSERVABLE", "VisualEffect has no live particles that can prove a reinitialize transition.", "Play an observable effect before calling vfx.control.reinitialize.");
+            var gameObjectId = effect.gameObject.GetInstanceID(); var effectType = effect.GetType();
+            VfxActionToolSupport.PrepareControlMethod(effectType, "Reinit");
+            ctx.CommitEffect();
+
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.reinitialize");
+            VfxActionToolSupport.InvokeRequired(effect, "Reinit");
+            await VfxActionToolSupport.RequireAliveState(effect, count => count == 0, "reinitialize", ctx, ct);
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.reinitialize");
+            return VfxActionToolSupport.BuildControlResult(effect, "vfx.control.reinitialize", ctx.LogPath);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/control-set-rate.cs

@@ -0,0 +1,36 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>设置目标 VisualEffect 的播放倍率。</summary>
+    public sealed class VfxControlSetRateTool : IUnityCliTool<VfxControlSetRateTool.Request, VfxControlActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } [UnityCliRequired] public double? Rate { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.control.set-rate", Summary = "Set VisualEffect playback rate.",
+            Description = "Set the public playRate property on the existing VisualEffect component and return its verified readback.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Set half-speed playback", Input = new Request { Target = "Effects/Emitter", Rate = 0.5 } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<VfxControlActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.RequireFinite(request.Rate, "rate", 0);
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.control.set-rate");
+            var property = effect.GetType().GetProperty("playRate", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.Public);
+            if (property == null || !property.CanRead || !property.CanWrite || property.PropertyType != typeof(float)) throw new UnityCliBridge.BridgeCommandException("E_VFX_PROPERTY_UNSUPPORTED", "VisualEffect playRate property is unavailable.", "Check the installed Visual Effect Graph package version.");
+            var gameObjectId = effect.gameObject.GetInstanceID(); var effectType = effect.GetType();
+            ctx.CommitEffect();
+            var observedObject = VfxToolSupport.FindGameObjectByTarget(gameObjectId.ToString(System.Globalization.CultureInfo.InvariantCulture));
+            effect = observedObject == null ? null : observedObject.GetComponent(effectType);
+            if (effect == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.control.set-rate target/component disappeared after commit.", "Retry after checking the target still exists.");
+            VfxActionToolSupport.SetAndReadRequired(effect, "playRate", (float)request.Rate.Value);
+            var result = VfxActionToolSupport.BuildControlResult(effect, "vfx.control.set-rate", ctx.LogPath);
+            return new System.Threading.Tasks.ValueTask<VfxControlActionResult>(result);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/control-set-seed.cs

@@ -0,0 +1,42 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>设置目标 VisualEffect 的随机种子。</summary>
+    public sealed class VfxControlSetSeedTool : IUnityCliTool<VfxControlSetSeedTool.Request, VfxControlActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } [UnityCliRequired] public int? Seed { get; set; } public bool? ResetSeedOnPlay { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.control.set-seed", Summary = "Set VisualEffect random seed.",
+            Description = "Set startSeed and optionally resetSeedOnPlay on the existing VisualEffect component, then return verified public-property readbacks.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set a deterministic seed", Input = new Request { Target = "Effects/Emitter", Seed = 42 } },
+                new ToolExample { Description = "Reset the seed on play", Input = new Request { Target = "Effects/Emitter", Seed = 7, ResetSeedOnPlay = true } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<VfxControlActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!request.Seed.HasValue || request.Seed.Value < 0) throw new UnityCliBridge.BridgeCommandException("E_VFX_SEED_INVALID", "VisualEffect seed must be non-negative.", "Pass seed as an integer greater than or equal to zero.");
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.control.set-seed");
+            var seedProperty = effect.GetType().GetProperty("startSeed", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.Public);
+            var resetProperty = effect.GetType().GetProperty("resetSeedOnPlay", System.Reflection.BindingFlags.Instance | System.Reflection.BindingFlags.Public);
+            if (seedProperty == null || !seedProperty.CanRead || !seedProperty.CanWrite || seedProperty.PropertyType != typeof(uint) || (request.ResetSeedOnPlay.HasValue && (resetProperty == null || !resetProperty.CanRead || !resetProperty.CanWrite || resetProperty.PropertyType != typeof(bool)))) throw new UnityCliBridge.BridgeCommandException("E_VFX_PROPERTY_UNSUPPORTED", "VisualEffect seed property is unavailable.", "Check the installed Visual Effect Graph package version.");
+            var gameObjectId = effect.gameObject.GetInstanceID(); var effectType = effect.GetType();
+            ctx.CommitEffect();
+            var observedObject = VfxToolSupport.FindGameObjectByTarget(gameObjectId.ToString(System.Globalization.CultureInfo.InvariantCulture));
+            effect = observedObject == null ? null : observedObject.GetComponent(effectType);
+            if (effect == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.control.set-seed target/component disappeared after commit.", "Retry after checking the target still exists.");
+            VfxActionToolSupport.SetAndReadRequired(effect, "startSeed", (uint)request.Seed.Value);
+            if (request.ResetSeedOnPlay.HasValue) VfxActionToolSupport.SetAndReadRequired(effect, "resetSeedOnPlay", request.ResetSeedOnPlay.Value);
+            var result = VfxActionToolSupport.BuildControlResult(effect, "vfx.control.set-seed", ctx.LogPath);
+            return new System.Threading.Tasks.ValueTask<VfxControlActionResult>(result);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/control-stop.cs

@@ -0,0 +1,37 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>停止目标 VisualEffect 的播放。</summary>
+    public sealed class VfxControlStopTool : IUnityCliTool<VfxControlStopTool.Request, VfxControlActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.control.stop", Summary = "Stop a VisualEffect component.",
+            Description = "Stop the VisualEffect and wait until a previously non-empty effect reports aliveParticleCount=0. Fails closed when no observable active particles exist before the call.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "component-state-edit" }, Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Stop the matrix emitter", Input = new Request { Target = "Effects/Emitter" } } }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxControlActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.control.stop");
+            var beforeAlive = VfxActionToolSupport.ReadLong(effect, "aliveParticleCount");
+            if (!beforeAlive.HasValue || beforeAlive.Value <= 0)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_STATE_UNOBSERVABLE", "VisualEffect has no live particles that can prove a stop transition.", "Play an observable effect before calling vfx.control.stop.");
+            var gameObjectId = effect.gameObject.GetInstanceID(); var effectType = effect.GetType();
+            VfxActionToolSupport.PrepareControlMethod(effectType, "Stop");
+            ctx.CommitEffect();
+
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.stop");
+            VfxActionToolSupport.InvokeRequired(effect, "Stop");
+            await VfxActionToolSupport.RequireAliveState(effect, count => count == 0, "stop", ctx, ct);
+            effect = VfxActionToolSupport.ResolveObservedEffect(gameObjectId, effectType, "vfx.control.stop");
+            return VfxActionToolSupport.BuildControlResult(effect, "vfx.control.stop", ctx.LogPath);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/effect-add.cs

@@ -0,0 +1,55 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>给目标 GameObject 添加 VisualEffect 组件。</summary>
+    public sealed class VfxEffectAddTool : IUnityCliTool<VfxEffectAddTool.Request, VfxEffectActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } public string Graph { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.effect.add", Summary = "Add a VisualEffect component.",
+            Description = "Ensure one VisualEffect component exists on the target and optionally assign an initial existing VFX Graph. Repeated calls are idempotent.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "scene-modify", "component-add", "component-reference-edit" },
+            Target = "editor", PlayModeSupport = "session-affecting", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Add VisualEffect to a new emitter", Input = new Request { Target = "Effects/NewEmitter" } },
+                new ToolExample { Description = "Add and bind a graph", Input = new Request { Target = "Effects/NewEmitter", Graph = "Assets/VFX/Explosion.vfx" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<VfxEffectActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.effect.add");
+            var effectType = VfxToolSupport.RequireVisualEffectType();
+            if (!string.IsNullOrWhiteSpace(request.Graph)) VfxActionToolSupport.PrepareGraphAssignment(effectType);
+            var gameObject = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "vfx.effect.add requires target.");
+            var effect = gameObject.GetComponent(effectType);
+            if (!string.IsNullOrWhiteSpace(request.Graph) && AssetDatabase.LoadAssetAtPath(VfxToolSupport.RequireVfxGraphPath(request.Graph), VfxToolSupport.RequireVfxAssetType()) == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_GRAPH_NOT_FOUND", "VFX Graph asset not found: " + request.Graph, "Pass an existing Assets/*.vfx path.");
+            var gameObjectId = gameObject.GetInstanceID();
+            ctx.CommitEffect();
+            var observedObject = VfxToolSupport.FindGameObjectByTarget(gameObjectId.ToString(System.Globalization.CultureInfo.InvariantCulture));
+            if (observedObject == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.effect.add target disappeared after commit.", "Retry after checking the target still exists.");
+            effect = observedObject.GetComponent(effectType);
+            var added = effect == null;
+            if (added) effect = observedObject.AddComponent(effectType);
+            if (!string.IsNullOrWhiteSpace(request.Graph)) { VfxActionToolSupport.AssignGraph(effect, request.Graph); VfxActionToolSupport.VerifyAssignedGraph(effect, request.Graph); }
+            effect = observedObject.GetComponent(effectType);
+            if (effect == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_STATE_UNOBSERVABLE", "VisualEffect component add could not be read back.", "Retry after checking the target.");
+            UnityCliSceneMutation.MarkSceneObjectDirty(effect);
+            VfxToolSupport.MarkSceneDirty(observedObject);
+            return new System.Threading.Tasks.ValueTask<VfxEffectActionResult>(new VfxEffectActionResult
+            {
+                Action = added ? "added" : "already-present",
+                Effect = VfxToolSupport.BuildEffectInfo(effect),
+                PlannedEffects = new List<VfxPlannedEffect> { new VfxPlannedEffect { Type = "vfx.effect.add", Target = GameObjectToolSupport.HierarchyPath(gameObject), Graph = request.Graph } }
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/effect-assign.cs

@@ -0,0 +1,44 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>给现有 VisualEffect 组件绑定图资产。</summary>
+    public sealed class VfxEffectAssignTool : IUnityCliTool<VfxEffectAssignTool.Request, VfxEffectActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } [UnityCliRequired] public string Graph { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.effect.assign", Summary = "Assign a VFX Graph to a VisualEffect.",
+            Description = "Bind one existing Assets/*.vfx graph to the existing VisualEffect component on the target.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new[] { "scene-modify", "component-reference-edit" }, Target = "editor", PlayModeSupport = "session-affecting",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Assign the matrix graph", Input = new Request { Target = "Effects/Emitter", Graph = "Assets/VFX/Explosion.vfx" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<VfxEffectActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.effect.assign");
+            VfxActionToolSupport.PrepareGraphAssignment(effect.GetType());
+            var graphPath = VfxToolSupport.RequireVfxGraphPath(request.Graph);
+            if (UnityEditor.AssetDatabase.LoadAssetAtPath(graphPath, VfxToolSupport.RequireVfxAssetType()) == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_GRAPH_NOT_FOUND", "VFX Graph asset not found: " + request.Graph, "Pass an existing Assets/*.vfx path.");
+            var gameObjectId = effect.gameObject.GetInstanceID();
+            var effectType = effect.GetType();
+            ctx.CommitEffect();
+            var observedObject = VfxToolSupport.FindGameObjectByTarget(gameObjectId.ToString(System.Globalization.CultureInfo.InvariantCulture));
+            effect = observedObject == null ? null : observedObject.GetComponent(effectType);
+            if (effect == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.effect.assign target/component disappeared after commit.", "Retry after checking the target still exists.");
+            VfxActionToolSupport.AssignGraph(effect, graphPath);
+            VfxActionToolSupport.VerifyAssignedGraph(effect, graphPath);
+            return new System.Threading.Tasks.ValueTask<VfxEffectActionResult>(new VfxEffectActionResult
+            {
+                Action = "assigned",
+                Effect = VfxToolSupport.BuildEffectInfo(effect),
+                PlannedEffects = new List<VfxPlannedEffect> { new VfxPlannedEffect { Type = "vfx.effect.assign", Target = request.Target, Graph = request.Graph } }
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/effect-info.cs

@@ -0,0 +1,30 @@
+#if UNITY_EDITOR
+namespace UnityCli
+{
+    /// <summary>读取目标 VisualEffect 组件及其图资产绑定。</summary>
+    public sealed class VfxEffectInfoTool : IUnityCliTool<VfxEffectInfoTool.Request, VfxEffectInfoTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+        public sealed class Result { public VfxEffectInfo Effect { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.effect.info", Summary = "Read VisualEffect component information.",
+            Description = "Report the existing VisualEffect component and assigned VFX Graph without modifying the scene.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new string[0], Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Inspect the matrix emitter", Input = new Request { Target = "Effects/Emitter" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext context, System.Threading.CancellationToken ct = default)
+        {
+            var effect = VfxActionToolSupport.RequireEffect(request.Target, "vfx.effect.info");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Effect = VfxToolSupport.BuildEffectInfo(effect)
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/graph-create.cs

@@ -0,0 +1,62 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.IO;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>创建独立 VFX Graph 资产。</summary>
+    public sealed class VfxGraphCreateTool : IUnityCliTool<VfxGraphCreateTool.Request, VfxGraphCreateTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Path { get; set; } public bool? Overwrite { get; set; } }
+        public sealed class Result { public VfxGraphInfo Graph { get; set; } public bool DryRun { get; set; } public List<VfxPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.graph.create", Summary = "Create a VFX Graph asset.",
+            Description = "Create one Assets/*.vfx Visual Effect Graph asset, optionally replacing an existing graph. Supports --dry-run without writing the asset.",
+            Group = "vfx",DestructiveHint = true, SupportsDryRun = true,
+            RequiresPackages = new[] { "com.unity.visualeffectgraph" }, SideEffects = new[] { "asset-write" },
+            Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Create a matrix graph", Input = new Request { Path = "Assets/VFX/UnityCliCreatedExplosion.vfx" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.graph.create");
+            var path = VfxToolSupport.RequireVfxGraphPath(request.Path);
+            var graphType = VfxToolSupport.RequireVfxAssetType();
+            VfxToolSupport.PrepareVfxGraphFactory();
+            var existing = AssetDatabase.LoadAssetAtPath(path, graphType);
+            if (existing != null && request.Overwrite != true)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_GRAPH_EXISTS", "VFX Graph already exists: " + path, "Pass overwrite=true or choose a different Assets/*.vfx path.");
+
+            var effects = new List<VfxPlannedEffect> { new VfxPlannedEffect { Type = "vfx.graph.create", Path = path } };
+            if (ctx.DryRun)
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Graph = new VfxGraphInfo { Path = path, Name = Path.GetFileNameWithoutExtension(path), Type = graphType.Name },
+                    DryRun = true,
+                    PlannedEffects = effects
+                });
+            }
+
+            ctx.CommitEffect();
+            AssetToolSupport.CreateAssetDirectory(path);
+            if (existing != null) AssetDatabase.DeleteAsset(path);
+            VfxToolSupport.CreateVfxGraphAsset(path, graphType);
+            AssetDatabase.SaveAssets();
+            AssetDatabase.ImportAsset(path, ImportAssetOptions.ForceUpdate);
+            var created = AssetDatabase.LoadAssetAtPath(path, graphType);
+            if (created == null || !graphType.IsInstanceOfType(created))
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_GRAPH_CREATE_FAILED", "VFX Graph asset creation did not produce a readable VisualEffectAsset: " + path, "Check Unity Console and UnityCliBridge.log for package authoring API errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Graph = VfxToolSupport.BuildGraphInfo(path, created),
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/graph-info.cs

@@ -0,0 +1,32 @@
+#if UNITY_EDITOR
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>读取 VFX Graph 资产元数据。</summary>
+    public sealed class VfxGraphInfoTool : IUnityCliTool<VfxGraphInfoTool.Request, VfxGraphInfoTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Path { get; set; } }
+        public sealed class Result { public VfxGraphInfo Graph { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.graph.info", Summary = "Read a VFX Graph asset.",
+            Description = "Read metadata for one existing Assets/*.vfx Visual Effect Graph asset without modifying it.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new string[0], Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Read the matrix graph", Input = new Request { Path = "Assets/VFX/Explosion.vfx" } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext context, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.graph.info");
+            var path = VfxToolSupport.RequireVfxGraphPath(request.Path);
+            var graph = AssetDatabase.LoadAssetAtPath(path, VfxToolSupport.RequireVfxAssetType());
+            if (graph == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_GRAPH_NOT_FOUND", "VFX Graph asset not found: " + path, "Create it with vfx.graph.create or pass an existing Assets/*.vfx path.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Graph = VfxToolSupport.BuildGraphInfo(path, graph) });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/line-create.cs

@@ -0,0 +1,75 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.line-create - 创建或初始化 LineRenderer。
+    /// </summary>
+    public class VfxLineCreateTool : IUnityCliTool<VfxLineCreateTool.Request, VfxLineCreateTool.Result>
+    {
+        public sealed class Request : LineRendererFields
+        {
+            public string Target { get; set; }
+            public string Name { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxLineRendererInfo Line { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.line-create",
+            Summary = "Create or initialize a LineRenderer and configure widths, colors, material, positions, and render settings.",
+            Description = "Create a new GameObject when target is omitted, ensure a LineRenderer exists, and configure widths, widthCurve, colors, colorGradient, material, positions, looping, world-space mode, alignment, texture mode, and corner/cap vertex counts.",
+            Group = "vfx",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-object-create", "component-add", "line-renderer-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Create a line with two points", Input = new Request { Name = "AimLine", Positions = new List<Vector3Input> { new Vector3Input { X = 0, Y = 0, Z = 0 }, new Vector3Input { X = 1, Y = 2, Z = 3 } } } },
+                new ToolExample { Description = "Configure widths and material", Input = new Request { Target = "AimLine", StartWidth = 0.2, EndWidth = 0.05, Material = "Assets/Materials/Line.mat" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.line-create");
+            VfxToolSupport.PrepareLineRendererFields(request);
+            var preparedTarget = string.IsNullOrWhiteSpace(request.Target) ? null : GameObjectToolSupport.ResolveUniqueTarget(request.Target, "vfx.line-create requires target.");
+            ctx.CommitEffect();
+            var gameObject = preparedTarget == null
+                ? VfxToolSupport.CreateSceneObject(string.IsNullOrWhiteSpace(request.Name) ? "Line" : request.Name)
+                : VfxToolSupport.FindGameObjectByTarget(preparedTarget.GetInstanceID().ToString(System.Globalization.CultureInfo.InvariantCulture));
+            if (gameObject == null) throw new UnityCliBridge.BridgeCommandException("E_VFX_OBSERVED_TARGET_MISSING", "vfx.line-create target disappeared after commit.", "Retry after checking the target still exists.");
+            var gameObjectId = gameObject.GetInstanceID();
+            var line = gameObject.GetComponent<LineRenderer>();
+            var effects = new List<VfxPlannedEffect>();
+            if (line == null)
+            {
+                line = gameObject.AddComponent<LineRenderer>();
+                effects.Add(new VfxPlannedEffect { Type = "vfx.line-create", Target = GameObjectToolSupport.HierarchyPath(gameObject), Property = "component", Value = "added" });
+            }
+            VfxToolSupport.ApplyLineRendererFields(line, request, "vfx.line-create", effects);
+            var observed = VfxToolSupport.ResolveObservedComponent<LineRenderer>(gameObjectId, "vfx.line-create");
+            VfxToolSupport.VerifyLineRendererFields(observed, request);
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Line = VfxToolSupport.BuildLineRendererInfo(observed),
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif