@alpsckr/unitycli 0.4.0

package/extensions/vfx-graph/unitypkg/Editor/Vfx/particle-main.cs

@@ -0,0 +1,75 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.particle-main - 修改 ParticleSystem 主模块。
+    /// </summary>
+    public class VfxParticleMainTool : IUnityCliTool<VfxParticleMainTool.Request, VfxParticleMainTool.Result>
+    {
+        public sealed class Request : ParticleMainFields
+        {
+            [UnityCliRequired]
+            public string Target { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxParticleSystemInfo ParticleSystem { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle-main",
+            Summary = "Update ParticleSystem main module fields such as lifetime, speed, size, looping, and simulation space.",
+            Description = "Update the main module of an existing ParticleSystem. Supports duration, start lifetime, start speed, start size, start color, rotation, gravity, maxParticles, loop, playOnAwake, simulationSpace, and scalingMode.",
+            Group = "vfx",
+            DestructiveHint = false,
+            SideEffects = new[] { "particle-main-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Set looping dust", Input = new Request { Target = "Effects/Dust", Loop = true, Duration = 3 } },
+                new ToolExample { Description = "Switch to world simulation", Input = new Request { Target = "Effects/Dust", SimulationSpace = "World" } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.particle-main");
+            var particleSystem = VfxToolSupport.ResolveParticleSystem(request.Target);
+            if (particleSystem == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_PARTICLE_SYSTEM_NOT_FOUND",
+                    "ParticleSystem not found: " + request.Target,
+                    "Pass a GameObject name / hierarchy path with a ParticleSystem component.");
+            }
+
+            VfxToolSupport.PrepareParticleMainFields(request);
+            VfxToolSupport.RequireMutation(request.Duration.HasValue || request.StartLifetime.HasValue || request.StartSpeed.HasValue || request.StartSize.HasValue || !string.IsNullOrWhiteSpace(request.StartColor) || request.StartRotation.HasValue || request.GravityModifier.HasValue || request.MaxParticles.HasValue || request.Loop.HasValue || request.PlayOnAwake.HasValue || !string.IsNullOrWhiteSpace(request.SimulationSpace) || !string.IsNullOrWhiteSpace(request.ScalingMode), "vfx.particle-main");
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            var effects = new List<VfxPlannedEffect>();
+            ctx.CommitEffect();
+            var writable = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-main");
+            VfxToolSupport.ApplyParticleMainFields(writable, request, "vfx.particle-main", effects);
+            var observed = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-main");
+            VfxToolSupport.VerifyParticleMainFields(observed, request);
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                ParticleSystem = VfxToolSupport.BuildParticleSystemInfo(observed),
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,38 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>暂停目标 ParticleSystem。</summary>
+    public sealed class VfxParticlePauseTool : IUnityCliTool<VfxParticlePauseTool.Request, VfxParticleActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } public bool? WithChildren { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle.pause", Summary = "Pause a ParticleSystem.",
+            Description = "Pause the existing ParticleSystem, optionally including child systems.",
+            Group = "vfx",SideEffects = new[] { "particle-playback-edit" },
+            Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Pause the dust system", Input = new Request { Target = "Effects/Dust" } },
+                new ToolExample { Description = "Pause child systems", Input = new Request { Target = "Effects/Dust", WithChildren = true } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxParticleActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var particleSystem = VfxActionToolSupport.RequireParticle(request.Target, "vfx.particle.pause");
+            var withChildren = request.WithChildren ?? true;
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            ctx.CommitEffect();
+
+            particleSystem = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.pause");
+            particleSystem.Pause(withChildren);
+            await VfxActionToolSupport.RequireParticleState(particleSystem, withChildren, system => system.isPaused, "vfx.particle.pause", ctx, ct);
+            return VfxActionToolSupport.BuildParticleResult(VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.pause"), "vfx.particle.pause", ctx.LogPath);
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,38 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>播放目标 ParticleSystem。</summary>
+    public sealed class VfxParticlePlayTool : IUnityCliTool<VfxParticlePlayTool.Request, VfxParticleActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } public bool? WithChildren { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle.play", Summary = "Play a ParticleSystem.",
+            Description = "Play the existing ParticleSystem, optionally including child systems.",
+            Group = "vfx",SideEffects = new[] { "particle-playback-edit" },
+            Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Play the dust system", Input = new Request { Target = "Effects/Dust" } },
+                new ToolExample { Description = "Play with child systems", Input = new Request { Target = "Effects/Dust", WithChildren = true } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxParticleActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var particleSystem = VfxActionToolSupport.RequireParticle(request.Target, "vfx.particle.play");
+            var withChildren = request.WithChildren ?? true;
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            ctx.CommitEffect();
+
+            particleSystem = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.play");
+            particleSystem.Play(withChildren);
+            await VfxActionToolSupport.RequireParticleState(particleSystem, withChildren, system => system.isPlaying && !system.isPaused, "vfx.particle.play", ctx, ct);
+            return VfxActionToolSupport.BuildParticleResult(VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.play"), "vfx.particle.play", ctx.LogPath);
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/particle-shape.cs

@@ -0,0 +1,148 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>
+    /// vfx.particle-shape - 修改 ParticleSystem 形状模块。
+    /// </summary>
+    public class VfxParticleShapeTool : IUnityCliTool<VfxParticleShapeTool.Request, VfxParticleShapeTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired]
+            public string Target { get; set; }
+            public bool? Enabled { get; set; }
+            public string ShapeType { get; set; }
+            public double? Radius { get; set; }
+            public double? Angle { get; set; }
+            public double? Arc { get; set; }
+            public double? Length { get; set; }
+            public double? BoxX { get; set; }
+            public double? BoxY { get; set; }
+            public double? BoxZ { get; set; }
+            public bool? RandomDirection { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public VfxParticleShapeInfo Shape { get; set; }
+            public List<VfxPlannedEffect> PlannedEffects { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle-shape",
+            Summary = "Update ParticleSystem shape type, dimensions, and random direction settings.",
+            Description = "Update the shape module of an existing ParticleSystem. Supports enabled, shapeType, radius, angle, arc, length, box axes, and randomDirection.",
+            Group = "vfx",
+            DestructiveHint = false,
+            SideEffects = new[] { "particle-shape-edit" },
+            Target = "editor",
+            PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000,
+            MaxTimeoutMs = 600000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Switch to cone", Input = new Request { Target = "Effects/Dust", ShapeType = "Cone", Radius = 0.5, Angle = 15 } },
+                new ToolExample { Description = "Edit box extents", Input = new Request { Target = "Effects/Dust", BoxX = 1, BoxY = 2, BoxZ = 3 } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.particle-shape");
+            var particleSystem = VfxToolSupport.ResolveParticleSystem(request.Target);
+            if (particleSystem == null)
+            {
+                throw new UnityCliBridge.BridgeCommandException(
+                    "E_PARTICLE_SYSTEM_NOT_FOUND",
+                    "ParticleSystem not found: " + request.Target,
+                    "Pass a GameObject name / hierarchy path with a ParticleSystem component.");
+            }
+
+            VfxToolSupport.RequireFinite(request.Radius, "radius", 0); VfxToolSupport.RequireFinite(request.Angle, "angle"); VfxToolSupport.RequireFinite(request.Arc, "arc", 0, 360); VfxToolSupport.RequireFinite(request.Length, "length", 0); VfxToolSupport.RequireFinite(request.BoxX, "boxX", 0); VfxToolSupport.RequireFinite(request.BoxY, "boxY", 0); VfxToolSupport.RequireFinite(request.BoxZ, "boxZ", 0);
+            if (!string.IsNullOrWhiteSpace(request.ShapeType)) VfxToolSupport.ParseEnum<ParticleSystemShapeType>(request.ShapeType, "E_PARTICLE_SHAPE_TYPE_INVALID", "Use a valid ParticleSystemShapeType value.");
+            VfxToolSupport.RequireMutation(request.Enabled.HasValue || !string.IsNullOrWhiteSpace(request.ShapeType) || request.Radius.HasValue || request.Angle.HasValue || request.Arc.HasValue || request.Length.HasValue || request.BoxX.HasValue || request.BoxY.HasValue || request.BoxZ.HasValue || request.RandomDirection.HasValue, "vfx.particle-shape");
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            var effects = new List<VfxPlannedEffect>();
+            ctx.CommitEffect();
+            particleSystem = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-shape");
+            var shape = particleSystem.shape;
+            if (request.Enabled.HasValue)
+            {
+                shape.enabled = request.Enabled.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "enabled", VfxToolSupport.Bool(shape.enabled)));
+            }
+            if (!string.IsNullOrWhiteSpace(request.ShapeType))
+            {
+                shape.shapeType = VfxToolSupport.ParseEnum<ParticleSystemShapeType>(request.ShapeType, "E_PARTICLE_SHAPE_TYPE_INVALID", "Use a valid ParticleSystemShapeType value.");
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "shapeType", shape.shapeType.ToString()));
+            }
+            if (request.Radius.HasValue)
+            {
+                shape.radius = (float)request.Radius.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "radius", VfxToolSupport.Number(shape.radius)));
+            }
+            if (request.Angle.HasValue)
+            {
+                shape.angle = (float)request.Angle.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "angle", VfxToolSupport.Number(shape.angle)));
+            }
+            if (request.Arc.HasValue)
+            {
+                shape.arc = (float)request.Arc.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "arc", VfxToolSupport.Number(shape.arc)));
+            }
+            if (request.Length.HasValue)
+            {
+                shape.length = (float)request.Length.Value;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "length", VfxToolSupport.Number(shape.length)));
+            }
+            if (request.BoxX.HasValue)
+            {
+                shape.scale = new Vector3((float)request.BoxX.Value, shape.scale.y, shape.scale.z);
+            }
+            if (request.BoxY.HasValue)
+            {
+                shape.scale = new Vector3(shape.scale.x, (float)request.BoxY.Value, shape.scale.z);
+            }
+            if (request.BoxZ.HasValue)
+            {
+                shape.scale = new Vector3(shape.scale.x, shape.scale.y, (float)request.BoxZ.Value);
+            }
+            if (request.BoxX.HasValue || request.BoxY.HasValue || request.BoxZ.HasValue)
+            {
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "box", VfxToolSupport.Number(shape.scale.x) + "," + VfxToolSupport.Number(shape.scale.y) + "," + VfxToolSupport.Number(shape.scale.z)));
+            }
+            if (request.RandomDirection.HasValue)
+            {
+                shape.randomDirectionAmount = request.RandomDirection.Value ? 1f : 0f;
+                effects.Add(VfxToolSupport.Effect("vfx.particle-shape", "randomDirection", VfxToolSupport.Bool(request.RandomDirection.Value)));
+            }
+
+            var observed = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle-shape");
+            VfxToolSupport.VerifyParticleShapeFields(observed, request.Enabled, request.ShapeType, request.Radius, request.Angle, request.Arc, request.Length, request.BoxX, request.BoxY, request.BoxZ, request.RandomDirection);
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Shape = new VfxParticleShapeInfo
+                {
+                    Enabled = observed.shape.enabled,
+                    ShapeType = observed.shape.shapeType.ToString(),
+                    Radius = observed.shape.radius,
+                    Angle = observed.shape.angle,
+                    Arc = observed.shape.arc,
+                    Length = observed.shape.length,
+                    Box = new Vector3Data(observed.shape.scale),
+                    RandomDirection = observed.shape.randomDirectionAmount > 0f
+                },
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,41 @@
+#if UNITY_EDITOR
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>停止目标 ParticleSystem。</summary>
+    public sealed class VfxParticleStopTool : IUnityCliTool<VfxParticleStopTool.Request, VfxParticleActionResult>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } public bool? WithChildren { get; set; } public string StopBehavior { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.particle.stop", Summary = "Stop a ParticleSystem.",
+            Description = "Stop the existing ParticleSystem with optional child propagation and stop behavior.",
+            Group = "vfx",SideEffects = new[] { "particle-playback-edit" },
+            Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "Stop the dust system", Input = new Request { Target = "Effects/Dust" } },
+                new ToolExample { Description = "Stop and clear particles", Input = new Request { Target = "Effects/Dust", WithChildren = true, StopBehavior = "StopEmittingAndClear" } }
+            }
+        };
+
+        public async System.Threading.Tasks.ValueTask<VfxParticleActionResult> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            var particleSystem = VfxActionToolSupport.RequireParticle(request.Target, "vfx.particle.stop");
+            var withChildren = request.WithChildren ?? true;
+            var behavior = string.IsNullOrEmpty(request.StopBehavior)
+                ? UnityEngine.ParticleSystemStopBehavior.StopEmitting
+                : VfxToolSupport.ParseEnum<UnityEngine.ParticleSystemStopBehavior>(request.StopBehavior, "E_PARTICLE_STOP_BEHAVIOR_INVALID", "Use StopEmitting or StopEmittingAndClear.");
+            var gameObjectId = particleSystem.gameObject.GetInstanceID();
+            ctx.CommitEffect();
+
+            particleSystem = VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.stop");
+            particleSystem.Stop(withChildren, behavior);
+            await VfxActionToolSupport.RequireParticleState(particleSystem, withChildren, system => !system.isPlaying && !system.isEmitting && !system.isPaused, "vfx.particle.stop", ctx, ct);
+            return VfxActionToolSupport.BuildParticleResult(VfxToolSupport.ResolveObservedComponent<ParticleSystem>(gameObjectId, "vfx.particle.stop"), "vfx.particle.stop", ctx.LogPath);
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,58 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+
+namespace UnityCli
+{
+    /// <summary>从 package 模板创建一个 VFX Graph 资产。</summary>
+    public sealed class VfxTemplateCreateTool : IUnityCliTool<VfxTemplateCreateTool.Request, VfxTemplateCreateTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Template { get; set; } [UnityCliRequired] public string Path { get; set; } public bool? Overwrite { get; set; } }
+        public sealed class Result { public VfxGraphInfo Graph { get; set; } public string TemplateName { get; set; } public bool DryRun { get; set; } public List<VfxPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.template.create", Summary = "Create a VFX Graph from a package template.",
+            Description = "Copy one installed VFX Graph template to an Assets/*.vfx destination. Supports --dry-run and explicit overwrite.",
+            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 simple particle graph", Input = new Request { Template = "SimpleParticleSystem", Path = "Assets/VFX/SimpleParticle.vfx", Overwrite = true } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.template.create");
+            VfxToolSupport.RequireVfxPackageInstalled();
+            var destinationPath = VfxToolSupport.RequireVfxGraphPath(request.Path);
+            var graphType = VfxToolSupport.RequireVfxAssetType();
+            var existing = AssetDatabase.LoadAssetAtPath(destinationPath, graphType);
+            if (existing != null && request.Overwrite != true)
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_GRAPH_EXISTS", "VFX Graph already exists: " + destinationPath, "Pass overwrite=true or choose a different Assets/*.vfx path.");
+            var templatePath = VfxToolSupport.ResolveVfxTemplatePath(request.Template);
+            if (string.IsNullOrEmpty(templatePath))
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_TEMPLATE_NOT_FOUND", "VFX Graph template not found: " + request.Template, "Run vfx.template.list to discover available templates.");
+
+            var effects = new List<VfxPlannedEffect> { new VfxPlannedEffect { Type = "vfx.template.create", Template = request.Template, Path = destinationPath } };
+            if (ctx.DryRun)
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { TemplateName = request.Template, DryRun = true, PlannedEffects = effects });
+
+            ctx.CommitEffect();
+            AssetToolSupport.CreateAssetDirectory(destinationPath);
+            if (existing != null) AssetDatabase.DeleteAsset(destinationPath);
+            if (!AssetDatabase.CopyAsset(templatePath, destinationPath))
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_TEMPLATE_COPY_FAILED", "Failed to copy template to: " + destinationPath, "Check the destination path and Unity Console errors.");
+            AssetDatabase.ImportAsset(destinationPath, ImportAssetOptions.ForceUpdate);
+            AssetDatabase.SaveAssets();
+            var created = AssetDatabase.LoadAssetAtPath(destinationPath, graphType);
+            if (created == null || !graphType.IsInstanceOfType(created))
+                throw new UnityCliBridge.BridgeCommandException("E_VFX_TEMPLATE_COPY_FAILED", "Copied template did not produce a readable VisualEffectAsset: " + destinationPath, "Check the template and Unity Console errors.");
+            return new System.Threading.Tasks.ValueTask<Result>(new Result
+            {
+                Graph = VfxToolSupport.BuildGraphInfo(destinationPath, created), TemplateName = request.Template,
+                PlannedEffects = effects
+            });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/Editor/Vfx/template-list.cs

@@ -0,0 +1,31 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+
+namespace UnityCli
+{
+    /// <summary>列出当前 VFX Graph package 提供的模板。</summary>
+    public sealed class VfxTemplateListTool : IUnityCliTool<VfxTemplateListTool.Request, VfxTemplateListTool.Result>
+    {
+        public sealed class Request { }
+        public sealed class Result { public List<string> Templates { get; set; } public long Count { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.template.list", Summary = "List available VFX Graph templates.",
+            Description = "List template names discovered in the installed Visual Effect Graph package without creating assets.",
+            Group = "vfx",RequiresPackages = new[] { "com.unity.visualeffectgraph" },
+            SideEffects = new string[0], Target = "editor", PlayModeSupport = "supported",
+            DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "List graph templates", Input = new Request() } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext context, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.template.list");
+            VfxToolSupport.RequireVfxPackageInstalled();
+            var templates = VfxToolSupport.DiscoverVfxTemplates();
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Templates = templates, Count = templates.Count });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,41 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>创建并配置一个 TrailRenderer。</summary>
+    public sealed class VfxTrailCreateTool : IUnityCliTool<VfxTrailCreateTool.Request, VfxTrailCreateTool.Result>
+    {
+        public sealed class Request : TrailRendererFields { public string Name { get; set; } }
+        public sealed class Result { public GameObjectRef Target { get; set; } public VfxTrailRendererInfo Trail { get; set; } public List<VfxPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.trail.create", Summary = "Create and configure a TrailRenderer.",
+            Description = "Create one scene GameObject with a TrailRenderer and apply width, gradient, material, lifetime, emission, alignment, texture, and vertex settings.",
+            Group = "vfx",SideEffects = new[] { "scene-object-create", "component-add", "trail-renderer-edit" },
+            Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Create a dash trail", Input = new Request { Name = "DashTrail", Time = 0.5, Emitting = true } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.trail.create");
+            VfxToolSupport.PrepareTrailRendererFields(request);
+            ctx.CommitEffect();
+            var gameObject = VfxToolSupport.CreateSceneObject(string.IsNullOrWhiteSpace(request.Name) ? "Trail" : request.Name);
+            var gameObjectId = gameObject.GetInstanceID();
+            var trail = gameObject.AddComponent<TrailRenderer>();
+            var effects = new List<VfxPlannedEffect> { new VfxPlannedEffect { Type = "vfx.trail.create", Target = GameObjectToolSupport.HierarchyPath(gameObject), Property = "component", Value = "added" } };
+            VfxToolSupport.ApplyTrailRendererFields(trail, request, effects, "vfx.trail.create");
+            var observed = VfxToolSupport.ResolveObservedComponent<TrailRenderer>(gameObjectId, "vfx.trail.create");
+            VfxToolSupport.VerifyTrailRendererFields(observed, request);
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Target = GameObjectToolSupport.BuildGameObjectRef(observed.gameObject), Trail = VfxToolSupport.BuildTrailRendererInfo(observed), PlannedEffects = effects });
+        }
+    }
+}
+#endif

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

@@ -0,0 +1,44 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using UnityEditor;
+using UnityEngine;
+
+namespace UnityCli
+{
+    /// <summary>配置现有 TrailRenderer。</summary>
+    public sealed class VfxTrailSetTool : IUnityCliTool<VfxTrailSetTool.Request, VfxTrailSetTool.Result>
+    {
+        public sealed class Request : TrailRendererFields { [UnityCliRequired] public string Target { get; set; } }
+        public sealed class Result { public VfxTrailRendererInfo Trail { get; set; } public List<VfxPlannedEffect> PlannedEffects { get; set; } }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "vfx.trail.set", Summary = "Configure an existing TrailRenderer.",
+            Description = "Apply width, gradient, material, lifetime, emission, alignment, texture, and vertex settings to one existing TrailRenderer.",
+            Group = "vfx",SideEffects = new[] { "trail-renderer-edit" },
+            Target = "editor", PlayModeSupport = "supported", DefaultTimeoutMs = 30000, MaxTimeoutMs = 60000,
+            Examples = new[] { new ToolExample { Description = "Update the matrix trail", Input = new Request { Target = "Trail", StartWidth = 0.2, EndWidth = 0 } } }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            VfxToolSupport.EnsureEditorReady("vfx.trail.set");
+            var gameObject = GameObjectToolSupport.ResolveUniqueTarget(request.Target, "vfx.trail.set requires target.");
+            var trail = gameObject.GetComponent<TrailRenderer>();
+            if (trail == null) throw new UnityCliBridge.BridgeCommandException("E_TRAIL_RENDERER_NOT_FOUND", "TrailRenderer not found on target: " + GameObjectToolSupport.HierarchyPath(gameObject), "Create one with vfx.trail.create or pass a target with TrailRenderer.");
+            VfxToolSupport.PrepareTrailRendererFields(request);
+            VfxToolSupport.RequireMutation(request.Time.HasValue || request.StartWidth.HasValue || request.EndWidth.HasValue || request.WidthMultiplier.HasValue || request.WidthCurve?.Count > 0 || !string.IsNullOrWhiteSpace(request.StartColor) || !string.IsNullOrWhiteSpace(request.EndColor) || request.ColorGradient?.Count > 0 || !string.IsNullOrWhiteSpace(request.Material) || request.MinVertexDistance.HasValue || request.Autodestruct.HasValue || request.Emitting.HasValue || !string.IsNullOrWhiteSpace(request.Alignment) || !string.IsNullOrWhiteSpace(request.TextureMode) || request.NumCornerVertices.HasValue || request.NumCapVertices.HasValue, "vfx.trail.set");
+            var gameObjectId = gameObject.GetInstanceID();
+            var effects = new List<VfxPlannedEffect>();
+            ctx.CommitEffect();
+            trail = VfxToolSupport.ResolveObservedComponent<TrailRenderer>(gameObjectId, "vfx.trail.set");
+            VfxToolSupport.ApplyTrailRendererFields(trail, request, effects, "vfx.trail.set");
+            var observed = VfxToolSupport.ResolveObservedComponent<TrailRenderer>(gameObjectId, "vfx.trail.set");
+            VfxToolSupport.VerifyTrailRendererFields(observed, request);
+            UnityCliSceneMutation.MarkSceneObjectDirty(observed);
+            VfxToolSupport.MarkSceneDirty(observed.gameObject);
+            return new System.Threading.Tasks.ValueTask<Result>(new Result { Trail = VfxToolSupport.BuildTrailRendererInfo(observed), PlannedEffects = effects });
+        }
+    }
+}
+#endif

package/extensions/vfx-graph/unitypkg/UnityCli.Extensions.VfxGraph.Editor.asmdef

@@ -0,0 +1,18 @@
+{
+  "name": "UnityCli.Extensions.VfxGraph.Editor",
+  "rootNamespace": "UnityCli.Vfx",
+  "references": [
+    "UnityCli.Editor"
+  ],
+  "includePlatforms": [
+    "Editor"
+  ],
+  "excludePlatforms": [],
+  "allowUnsafeCode": false,
+  "overrideReferences": false,
+  "precompiledReferences": [],
+  "autoReferenced": true,
+  "defineConstraints": [],
+  "versionDefines": [],
+  "noEngineReferences": false
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@alpsckr/unitycli",
+  "version": "0.4.0",
+  "description": "Windows-first CLI for UnityCLI automation.",
+  "type": "module",
+  "bin": {
+    "unitycli": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "unitypkg",
+    "extensions",
+    "contracts",
+    "schemas",
+    "skills",
+    "docs",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "generate:extensions": "node scripts/gen-extension-projections.mjs",
+    "generate:registries": "node scripts/gen-ts-registries.mjs && node scripts/gen-tool-completion-registry.mjs",
+    "build": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && tsc -p tsconfig.json",
+    "build:test": "npm run clean && npm run generate:extensions && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/gen-command-contract.mjs && node scripts/gen-protocol.mjs && node scripts/gen-tool-schemas.mjs && npm run generate:registries && tsc -p tsconfig.test.json && node scripts/copy-test-resources.cjs && tsc -p tsconfig.json",
+    "test": "node --test \"dist/tests/**/*.test.js\"",
+    "pretest": "npm run build:test",
+    "prepack": "npm run build",
+    "contracts:validate": "npm run build && node dist/contracts/validate-command-contract.js",
+    "architecture:audit": "node scripts/audit-final-architecture.mjs",
+    "static-catalog:audit": "node scripts/audit-static-capability-catalog.mjs",
+    "static-catalog:capture": "node scripts/capture-static-capability-catalog.mjs",
+    "architecture:validate": "node scripts/audit-final-architecture.mjs --strict && node scripts/audit-tool-completion-contract.mjs --strict && node scripts/audit-static-capability-catalog.mjs",
+    "completion:audit": "node scripts/audit-tool-completion-contract.mjs --strict",
+    "matrix:live": "node scripts/run-final-live-matrix.mjs",
+    "test:matrix-runner": "node --test scripts/run-final-live-matrix.test.mjs",
+    "matrix:live:dist": "node scripts/run-final-live-matrix.mjs --cli node --cli-arg dist/cli.js"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.10",
+    "typescript": "^5.9.3"
+  },
+  "license": "MIT"
+}