@alpsckr/unitycli 0.4.0

package/extensions/probuilder/unitypkg/Editor/ProBuilder/bevel-edges.cs

@@ -0,0 +1,119 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+using UnityEngine.ProBuilder.MeshOperations;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.bevel-edges — 对选定边进行倒角。
+    /// </summary>
+    public class BevelEdgesTool : IUnityCliTool<BevelEdgesTool.Request, BevelEdgesTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public double? Amount { get; set; }                     // 可选,默认 0.1
+            public List<long> EdgeIndices { get; set; }            // 可选
+            public List<EdgeRef> Edges { get; set; }               // 可选
+        }
+
+        public sealed class EdgeRef
+        {
+            public long A { get; set; }
+            public long B { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long ModifiedEdgeCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.bevel-edges",
+            Summary = "Bevel selected edges of a ProBuilder mesh by a given amount.",
+            Description = "Bevel one frozen typed edge of a ProBuilder mesh by a given amount. Specify the edge by edgeIndices (an index into the unique edge list) or by one vertex-pair edge [{a,b}]. The target must use the current ProBuilder 5.2.4 serialized mesh format with initialized sharedTextures and contain exactly two non-degenerate triangular face occurrences sharing that edge; each endpoint may occur only on those faces, with no additional raw, face, or position coincidence. Its Renderer must have nonempty sharedMaterials, every face submeshIndex must be in that range, and every material slot must be used so ToMesh cannot compact slots. The 5.2.4 amount clamp must be bit-exactly the request and at least 0.001; all other requests are rejected before scene mutation because their terminal topology cannot be uniquely proven.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "对两三角面共边倒角", Input = new Request { Target = "MyTwoTriangleWedge", Amount = 0.1, Edges = new List<EdgeRef> { new EdgeRef { A = 0, B = 1 } } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable)
+                throw ProBuilderErrors.PackageNotAvailable();
+
+            var target = request.Target;
+            var go = ProBuilderInput.ResolveTarget(target);
+            if (go == null) throw ProBuilderErrors.TargetNotFound(request.Target);
+
+            var mesh = ProBuilderReflection.GetProBuilderMesh(go);
+            if (mesh == null) throw ProBuilderErrors.OperationFailed("bevel-edges", "No ProBuilderMesh on target.");
+
+            var amount = ProBuilderOperationProof.CheckedFloat(request.Amount ?? 0.1, "amount");
+            if (amount <= 0)
+                throw ProBuilderErrors.SchemaInvalid("amount must be greater than 0 so bevel completion has observable topology.");
+            int[] edgeIndices = request.EdgeIndices?.Select(i => ProBuilderOperationProof.CheckedInt(i, "edgeIndices")).ToArray();
+            ProBuilderInput.EdgePair[] edgePairs = request.Edges?.Select(e => new ProBuilderInput.EdgePair { a = ProBuilderOperationProof.CheckedInt(e.A, "edges.a"), b = ProBuilderOperationProof.CheckedInt(e.B, "edges.b") }).ToArray();
+
+            if ((edgeIndices == null || edgeIndices.Length == 0) && (edgePairs == null || edgePairs.Length == 0))
+                throw ProBuilderErrors.SchemaInvalid("edgeIndices or edges parameter is required for bevel-edges.");
+
+            var edgeArray = ProBuilderOperationProof.ValidateEdges(mesh, edgeIndices, edgePairs);
+            var frozenEdges = edgeArray as Edge[];
+            var typedMesh = mesh as ProBuilderMesh;
+            if (frozenEdges == null || typedMesh == null || frozenEdges.Length != edgeArray.Length)
+                throw ProBuilderErrors.SchemaInvalid("bevel-edges requires a typed ProBuilder Edge[] selection.");
+            var plan = ProBuilderBevelCompletionProof.Capture(go, typedMesh, frozenEdges, amount);
+            if (plan == null)
+                throw ProBuilderErrors.SchemaInvalid("bevel-edges only accepts the deterministic 5.2.4 two-sided manifold domain; this request cannot be uniquely planned before mutation.");
+            ctx.CommitEffect();
+            try
+            {
+            Undo.RecordObject(go, "ProBuilder Bevel Edges");
+            try { Bevel.BevelEdges(typedMesh, plan.FrozenEdges, amount); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw ProBuilderErrors.OutcomeUnknown("bevel-edges", "invoke", "Bevel.BevelEdges threw after the effect barrier."); }
+
+            if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(typedMesh))
+                throw ProBuilderErrors.OutcomeUnknown("bevel-edges", "readback", "ProBuilder mesh payload-preserving refresh failed after effect.");
+            EditorSceneManager.MarkSceneDirty(go.scene);
+
+            try
+            {
+                // effect 前 identity fresh-resolve 后完整 capture；任何比较或 capture 异常都是未知终态。
+                var freshMesh = CanonicalMeshSnapshot.ResolveFreshMesh(target, plan.Before.Identity);
+                var after = freshMesh == null ? null : CanonicalMeshSnapshot.Capture(freshMesh.gameObject);
+                if (!ProBuilderBevelCompletionProof.Matches(plan, after))
+                {
+                    var mismatch = ProBuilderBevelCompletionProof.Mismatch(plan, after) ?? "unknown";
+                    throw ProBuilderErrors.OutcomeUnknown("bevel-edges", "postcondition", "Fresh mesh does not equal the frozen 5.2.4 bevel terminal plan at " + mismatch + ".");
+                }
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch
+            {
+                throw ProBuilderErrors.OutcomeUnknown("bevel-edges", "postcondition", "Bevel terminal-state readback threw after the effect barrier.");
+            }
+
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { ModifiedEdgeCount = plan.FrozenEdges.Length });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("bevel-edges", "postcondition", exception.Message); }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/bridge-edges.cs

@@ -0,0 +1,113 @@
+#if UNITY_EDITOR
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.bridge-edges — 在两条边之间创建桥接面。
+    /// </summary>
+    public class BridgeEdgesTool : IUnityCliTool<BridgeEdgesTool.Request, BridgeEdgesTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            [UnityCliRequired] public EdgeRef EdgeA { get; set; }
+            [UnityCliRequired] public EdgeRef EdgeB { get; set; }
+            public bool AllowNonManifold { get; set; }
+        }
+
+        public sealed class EdgeRef
+        {
+            public long A { get; set; }
+            public long B { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long NewFaceCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.bridge-edges",
+            Summary = "Bridge two edges on a ProBuilder mesh to create a connecting face.",
+            Description = "Create exactly one non-degenerate quad between two existing edges. The edges must resolve to four distinct shared endpoints, may not already bound the same face, and must not require the ProBuilder triangle-bridge branch. UV1 must be absent, and every existing triangle must have UV0 inputs whose full 5.2.4 tangent reciprocal, direction, and raw accumulation arithmetic stays finite. By default each edge must be a boundary edge; allowNonManifold permits one or both edges to have two readable incidences, but all other exact-plan restrictions still apply. The created quad receives a deterministic manual UV0 layout before tangent refresh.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "在闭合网格上桥接两条边", Input = new Request { Target = "MyCube", EdgeA = new EdgeRef { A = 0, B = 1 }, EdgeB = new EdgeRef { A = 5, B = 7 }, AllowNonManifold = true } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable)
+                throw ProBuilderErrors.PackageNotAvailable();
+
+            var target = request.Target;
+            var allowNonManifold = request.AllowNonManifold;
+            var go = ProBuilderInput.ResolveTarget(target);
+            if (go == null) throw ProBuilderErrors.TargetNotFound(request.Target);
+
+            var mesh = ProBuilderReflection.GetProBuilderMesh(go);
+            if (mesh == null) throw ProBuilderErrors.OperationFailed("bridge-edges", "No ProBuilderMesh on target.");
+
+            if (request.EdgeA == null || request.EdgeB == null)
+                throw ProBuilderErrors.SchemaInvalid("edgeA and edgeB parameters are required (as {a, b} vertex index pairs).");
+            var edgeA = new ProBuilderInput.EdgePair { a = ProBuilderOperationProof.CheckedInt(request.EdgeA.A, "edgeA.a"), b = ProBuilderOperationProof.CheckedInt(request.EdgeA.B, "edgeA.b") };
+            var edgeB = new ProBuilderInput.EdgePair { a = ProBuilderOperationProof.CheckedInt(request.EdgeB.A, "edgeB.a"), b = ProBuilderOperationProof.CheckedInt(request.EdgeB.B, "edgeB.b") };
+            var edgeArray = ProBuilderOperationProof.ValidateEdges(mesh, null, new[] { edgeA, edgeB });
+            var source = ProBuilderEdgeCompletionProof.Capture(go, mesh, edgeArray);
+            if (!ProBuilderEdgeCompletionProof.TryPlanBridge(source, allowNonManifold))
+                throw ProBuilderErrors.SchemaInvalid("bridge requires two distinct real edges with four shared endpoints and a complete provable quad plan.");
+            var frozenEdgeA = edgeArray.GetValue(0); var frozenEdgeB = edgeArray.GetValue(1);
+            ctx.CommitEffect();
+            try
+            {
+            bool invoked, bridged;
+            try
+            {
+                Undo.RecordObject(go, "ProBuilder Bridge Edges");
+                invoked = ProBuilderReflection.TryBridgeFrozenEdges(mesh, frozenEdgeA, frozenEdgeB, allowNonManifold, out bridged);
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "invoke", "AppendElements.Bridge threw after the effect barrier."); }
+            if (!invoked || !bridged)
+                throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "invoke", "AppendElements.Bridge did not create the planned face.");
+            if (!ProBuilderOperationProof.ApplyDeterministicQuadUvs(mesh, source[0].Before.Faces.Length, 1))
+                throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "invoke", "The created bridge quad could not receive its deterministic manual UV0 layout.");
+
+            try
+            {
+                if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(mesh)) throw new System.InvalidOperationException();
+                EditorSceneManager.MarkSceneDirty(go.scene);
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "readback", "ProBuilder mesh refresh failed after effect."); }
+            var freshMesh = ProBuilderEdgeCompletionProof.ResolveFresh(source[0], target);
+            if (freshMesh == null)
+                throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "readback", "Fresh target identity could not be resolved.");
+            try
+            {
+                if (!ProBuilderEdgeCompletionProof.BridgeMatches(source, go, freshMesh, allowNonManifold, out var mismatch))
+                    throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "postcondition", "Requested bridge face was not proven by fresh topology readback: " + mismatch + ".");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "postcondition", exception.Message); }
+
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { NewFaceCount = 1 });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("bridge-edges", "postcondition", exception.Message); }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/center-pivot.cs

@@ -0,0 +1,43 @@
+#if UNITY_EDITOR
+using System;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+using UnityEngine.ProBuilder.MeshOperations;
+namespace UnityCli.ProBuilder
+{
+    /// <summary>probuilder.center-pivot — 将轴心点居中到包围盒中心。</summary>
+    public class CenterPivotTool : IUnityCliTool<CenterPivotTool.Request, CenterPivotTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+        public sealed class Result { public Vec3 PivotOffset { get; set; } public Vec3 NewPosition { get; set; } }
+        public sealed class Vec3 { public double X { get; set; } public double Y { get; set; } public double Z { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "probuilder.center-pivot", Summary = "Center a ProBuilder mesh pivot to its renderer bounds center.", Description = "Center a mesh pivot to its renderer bounds center while preserving readable world geometry.", Group = "probuilder", DestructiveHint = false, SideEffects = new[] { "scene-modify", "undo-stack" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 10000, MaxTimeoutMs = 30000, Examples = new[] { new ToolExample { Description = "居中轴心", Input = new Request { Target = "MyCube" } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable) throw ProBuilderErrors.PackageNotAvailable(); var target = request.Target; var go = ProBuilderInput.ResolveTarget(target); if (go == null) throw ProBuilderErrors.TargetNotFound(target); var mesh = ProBuilderReflection.GetProBuilderMesh(go) as ProBuilderMesh; if (mesh == null) throw ProBuilderErrors.OperationFailed("center-pivot", "No ProBuilderMesh on target.");
+            var renderer = go.GetComponent<Renderer>(); if (renderer == null) throw ProBuilderErrors.OperationFailed("center-pivot", "Target has no Renderer to determine bounds center."); var pivot = renderer.bounds.center; if (float.IsNaN(pivot.x) || float.IsInfinity(pivot.x) || float.IsNaN(pivot.y) || float.IsInfinity(pivot.y) || float.IsNaN(pivot.z) || float.IsInfinity(pivot.z)) throw ProBuilderErrors.SchemaInvalid("Target bounds center must be finite."); var old = go.transform.position;
+            if (go.transform.position == pivot) return new System.Threading.Tasks.ValueTask<Result>(new Result { PivotOffset = new Vec3(), NewPosition = new Vec3 { X = pivot.x, Y = pivot.y, Z = pivot.z } }); var worldPositions = ProBuilderAtomicReadback.CaptureWorldPositions(go, mesh); if (worldPositions == null) throw ProBuilderErrors.OperationFailed("center-pivot", "Raw vertex positions are unreadable.");
+            var instanceId = go.GetInstanceID();
+            ctx.CommitEffect();
+            try
+            {
+                ProBuilderAtomicReadback.RegisterMeshUndo(go, mesh, "ProBuilder Center Pivot", true);
+                mesh.CenterPivot(null);
+                EditorSceneManager.MarkSceneDirty(go.scene);
+                var freshGo = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+                var fresh = ProBuilderReflection.GetProBuilderMesh(freshGo);
+                if (fresh == null) throw ProBuilderErrors.OutcomeUnknown("center-pivot", "readback", "Fresh target mesh is unreadable.");
+                if (!ProBuilderAtomicReadback.PivotPreservesWorldGeometry(freshGo, fresh, pivot, worldPositions, true)) throw ProBuilderErrors.OutcomeUnknown("center-pivot", "postcondition", "Center pivot or world geometry did not match the request.");
+                var offset = pivot - old;
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { PivotOffset = new Vec3 { X = offset.x, Y = offset.y, Z = offset.z }, NewPosition = new Vec3 { X = pivot.x, Y = pivot.y, Z = pivot.z } });
+            }
+            catch (Exception exception) when (!(exception is UnityCliBridge.BridgeCommandException))
+            {
+                throw ProBuilderErrors.OutcomeUnknown("center-pivot", "invoke", exception.Message);
+            }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/combine-meshes.cs

@@ -0,0 +1,58 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+namespace UnityCli.ProBuilder
+{
+    public class CombineMeshesTool : IUnityCliTool<CombineMeshesTool.Request, CombineMeshesTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public List<string> Targets { get; set; } public string Name { get; set; } }
+        public sealed class Result { public ObjectRef CombinedObject { get; set; } public long SourceCount { get; set; } }
+        public sealed class ObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } }
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.combine-meshes",
+            Summary = "Combine ProBuilder meshes into the first target.",
+            Description = "Combine at least two unique ProBuilder mesh targets into the first target.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 15000,
+            MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "合并两个 strict-domain 三角形", Input = new Request { Name = "CombinedTriangles", Targets = new List<string> { "TriangleA", "TriangleB" } } }
+            }
+        };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable) throw ProBuilderErrors.PackageNotAvailable(); var targets = ProBuilderInput.ResolveTargets(request.Targets); var name = request.Name ?? "ProBuilder_Combined";
+            if (targets == null || request.Targets == null || targets.Length != request.Targets.Count || targets.Length < 2 || string.IsNullOrWhiteSpace(name) || targets.Select(value => value.GetInstanceID()).Distinct().Count() != targets.Length) throw ProBuilderErrors.SchemaInvalid("combine-meshes requires at least 2 unique targets and a non-empty name.");
+            var meshes = targets.Select(ProBuilderReflection.GetProBuilderMesh).ToArray();
+            if (meshes.Any(value => value == null) || meshes.Any(value => ProBuilderReflection.GetFaceCount(value) < 1)) throw ProBuilderErrors.SchemaInvalid("Every target must have readable ProBuilder geometry.");
+            var totalVertices = meshes.Sum(ProBuilderReflection.GetVertexCount);
+            if (totalVertices < 1 || totalVertices >= ProBuilderMesh.maxVertexCount) throw ProBuilderErrors.SchemaInvalid("Combined raw vertex count must remain below ProBuilderMesh.maxVertexCount.");
+            var ids = targets.Select(value => value.GetInstanceID()).ToArray();
+            var minimumFaces = meshes.Sum(ProBuilderReflection.GetFaceCount);
+            ctx.CommitEffect();
+            try
+            {
+                foreach (var index in Enumerable.Range(0, targets.Length))
+                    ProBuilderAtomicReadback.RegisterMeshUndo(targets[index], meshes[index], "ProBuilder Combine Meshes", false, targets[index].GetComponent<Renderer>());
+                if (!ProBuilderReflection.CombineMeshesViaReflection(meshes, meshes[0])) throw ProBuilderErrors.OutcomeUnknown("combine-meshes", "invoke", "CombineMeshes.Combine failed.");
+                foreach (var source in targets.Skip(1)) Undo.DestroyObjectImmediate(source);
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("combine-meshes", "invoke", ex.Message); }
+            try { if (!ProBuilderReflection.RefreshMesh(meshes[0])) throw ProBuilderErrors.OutcomeUnknown("combine-meshes", "readback", "ProBuilder refresh failed."); var fresh = EditorUtility.InstanceIDToObject(ids[0]) as GameObject; if (fresh == null) throw ProBuilderErrors.OutcomeUnknown("combine-meshes", "readback", "Combined target identity could not be resolved."); fresh.name = name; EditorSceneManager.MarkSceneDirty(fresh.scene); var freshMesh = ProBuilderReflection.GetProBuilderMesh(fresh); if (fresh.name != name || !ProBuilderAtomicReadback.SourcesWereRemovedAndGeometryIncluded(fresh, freshMesh, ids, minimumFaces)) throw ProBuilderErrors.OutcomeUnknown("combine-meshes", "postcondition", "Combined geometry or source removal could not be confirmed."); return new System.Threading.Tasks.ValueTask<Result>(new Result { CombinedObject = new ObjectRef { Id = fresh.GetInstanceID(), Name = fresh.name, Path = HierarchyPath(fresh) }, SourceCount = targets.Length }); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("combine-meshes", "readback", ex.Message); }
+        }
+        private static string HierarchyPath(GameObject go) { var names = new Stack<string>(); for (var current = go.transform; current != null; current = current.parent) names.Push(current.name); return string.Join("/", names.ToArray()); }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/connect-elements.cs

@@ -0,0 +1,128 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.connect-elements — 在选定边或面之间插入连接边。
+    /// </summary>
+    public class ConnectElementsTool : IUnityCliTool<ConnectElementsTool.Request, ConnectElementsTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public List<long> EdgeIndices { get; set; }            // 可选
+            public List<EdgeRef> Edges { get; set; }               // 可选
+            public List<long> FaceIndices { get; set; }            // 可选
+        }
+
+        public sealed class EdgeRef
+        {
+            public long A { get; set; }
+            public long B { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public long ConnectedCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.connect-elements",
+            Summary = "Insert a connecting edge loop across selected edges or faces of a ProBuilder mesh.",
+            Description = "Connect the sole triangular face of a ProBuilder mesh, or exactly two distinct boundary edges of that face. The mesh must use serialized format 2, bind its serialized compiled Mesh to MeshFilter.sharedMesh, and have exactly three raw and shared vertices with unique positions, an empty shared-texture map, one non-null Renderer material on source submesh 0, and source Vertex channels whose 5.2.4 midpoint/centroid arithmetic stays finite. UV0 must be complete for all raw vertices or absent for the whole mesh; partial UV0 profiles are rejected. Other selections are rejected before the scene effect. Specify edgeIndices, vertex-pair edges [{a,b}], or one faceIndices value.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "连接唯一三角面", Input = new Request { Target = "MyTriangle", FaceIndices = new List<long> { 0 } } }
+            }
+        };
+
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable)
+                throw ProBuilderErrors.PackageNotAvailable();
+
+            var target = request.Target;
+            var go = ProBuilderInput.ResolveTarget(target);
+            if (go == null) throw ProBuilderErrors.TargetNotFound(request.Target);
+
+            var mesh = ProBuilderReflection.GetProBuilderMesh(go);
+            var typedMesh = mesh as UnityEngine.ProBuilder.ProBuilderMesh;
+            if (typedMesh == null) throw ProBuilderErrors.OperationFailed("connect-elements", "No ProBuilderMesh on target.");
+            // CanonicalMeshSnapshot 在 effect 前冻结 target 与 component identity。
+
+            int[] edgeIndices = request.EdgeIndices?.Select(i => ProBuilderOperationProof.CheckedInt(i, "edgeIndices")).ToArray();
+            ProBuilderInput.EdgePair[] edgePairs = request.Edges?.Select(e => new ProBuilderInput.EdgePair { a = ProBuilderOperationProof.CheckedInt(e.A, "edges.a"), b = ProBuilderOperationProof.CheckedInt(e.B, "edges.b") }).ToArray();
+            int[] faceIndices = request.FaceIndices?.Select(i => ProBuilderOperationProof.CheckedInt(i, "faceIndices")).ToArray();
+
+            if ((edgeIndices == null || edgeIndices.Length == 0) &&
+                (edgePairs == null || edgePairs.Length == 0) &&
+                (faceIndices == null || faceIndices.Length == 0))
+                throw ProBuilderErrors.SchemaInvalid("Either edgeIndices, edges, or faceIndices parameter is required for connect-elements.");
+
+            var faceMode = faceIndices != null && faceIndices.Length > 0;
+            if (faceMode && ((edgeIndices != null && edgeIndices.Length > 0) || (edgePairs != null && edgePairs.Length > 0)))
+                throw ProBuilderErrors.SchemaInvalid("Connect-elements accepts either edge selection or face selection, not both.");
+            if (faceMode) ProBuilderOperationProof.ValidateFaceIndices(typedMesh, faceIndices);
+            var resolved = faceMode ? null : ProBuilderOperationProof.ValidateEdges(typedMesh, edgeIndices, edgePairs);
+            var frozenEdges = resolved == null ? null : resolved.Cast<UnityEngine.ProBuilder.Edge>().ToArray();
+            var frozenFaces = faceMode ? faceIndices.Select(index => typedMesh.faces[index]).ToArray() : null;
+            var plan = ProBuilderConnectCompletionProof.Capture(go, faceMode, frozenEdges, frozenFaces);
+            if (plan == null)
+                throw ProBuilderErrors.OperationFailed("connect-elements", "Only a current-format sole triangular face with one bound compiled Mesh, three unique raw/shared vertices, one non-null source material, an empty shared-texture map, finite midpoint/centroid channel arithmetic, or exactly two of its boundary edges, has a unique ProBuilder 5.2.4 completion plan.");
+
+            ctx.CommitEffect();
+            try
+            {
+            Undo.RecordObject(go, "ProBuilder Connect Elements");
+            UnityEngine.ProBuilder.Face[] connectedFaces;
+            try
+            {
+                // effect API 只接收 effect 前冻结的 typed Edge[] 或 Face[]，并保留真实返回面用于业务结果和终态归因。
+                if (plan.FaceMode)
+                    connectedFaces = UnityEngine.ProBuilder.MeshOperations.ConnectElements.Connect(typedMesh, (UnityEngine.ProBuilder.Face[])plan.FrozenFaces);
+                else
+                    connectedFaces = UnityEngine.ProBuilder.MeshOperations.ConnectElements.Connect(typedMesh, (UnityEngine.ProBuilder.Edge[])plan.FrozenEdges).item1;
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw ProBuilderErrors.OutcomeUnknown("connect-elements", "invoke", "ConnectElements.Connect threw after the effect barrier."); }
+            if (connectedFaces == null || connectedFaces.Length != plan.ExpectedFaceCount)
+                throw ProBuilderErrors.OutcomeUnknown("connect-elements", "invoke", "ConnectElements.Connect did not return the complete frozen face set.");
+
+            if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(typedMesh))
+                throw ProBuilderErrors.OutcomeUnknown("connect-elements", "readback", "ProBuilder mesh refresh failed after effect.");
+            EditorSceneManager.MarkSceneDirty(go.scene);
+            try
+            {
+                var freshMesh = CanonicalMeshSnapshot.ResolveFreshMesh(target, plan.Before.Identity);
+                if (freshMesh == null)
+                    throw ProBuilderErrors.OutcomeUnknown("connect-elements", "readback", "Fresh target identity could not be resolved.");
+                var after = CanonicalMeshSnapshot.Capture(freshMesh.gameObject);
+                if (after == null)
+                    throw ProBuilderErrors.OutcomeUnknown("connect-elements", "readback", "Fresh canonical topology could not be read.");
+                if (!ProBuilderConnectCompletionProof.Matches(plan, after))
+                    throw ProBuilderErrors.OutcomeUnknown("connect-elements", "postcondition", "The complete frozen ConnectElements terminal plan was not proven by fresh readback.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw ProBuilderErrors.OutcomeUnknown("connect-elements", "postcondition", "Fresh terminal readback could not be proven."); }
+
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { ConnectedCount = connectedFaces.Length });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("connect-elements", "postcondition", exception.Message); }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/convert-to-probuilder.cs

@@ -0,0 +1,40 @@
+#if UNITY_EDITOR
+using System;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+namespace UnityCli.ProBuilder
+{
+    public class ConvertToProBuilderTool : IUnityCliTool<ConvertToProBuilderTool.Request, ConvertToProBuilderTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+        public sealed class Result { public bool Converted { get; set; } public long VertexCount { get; set; } public long FaceCount { get; set; } }
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.convert-to-probuilder",
+            Summary = "Convert a Unity mesh into a ProBuilder mesh.",
+            Description = "Convert a MeshFilter with readable vertices and triangle indices into a ProBuilder mesh.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "转换普通网格", Input = new Request { Target = "MyPrimitive" } }
+            }
+        };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable) throw ProBuilderErrors.PackageNotAvailable(); var go = ProBuilderInput.ResolveTarget(request.Target); if (go == null) throw ProBuilderErrors.TargetNotFound(request.Target); if (ProBuilderReflection.GetProBuilderMesh(go) != null) throw ProBuilderErrors.OperationFailed("convert-to-probuilder", "Target already has a ProBuilderMesh component.");
+            var source = ProBuilderAtomicReadback.CaptureSourceMeshGeometry(go.GetComponent<MeshFilter>()); if (source == null) throw ProBuilderErrors.SchemaInvalid("Target requires a MeshFilter with readable vertices and triangle indices."); var id = go.GetInstanceID(); ctx.CommitEffect(); object converted;
+            try { ProBuilderAtomicReadback.RegisterMeshUndo(go, null, "ProBuilder Convert to ProBuilder", false, go.GetComponent<MeshFilter>(), go.GetComponent<Renderer>()); converted = ProBuilderReflection.ConvertToProBuilderMesh(go); if (converted == null) throw ProBuilderErrors.OutcomeUnknown("convert-to-probuilder", "invoke", "MeshImporter failed."); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("convert-to-probuilder", "invoke", ex.Message); }
+            try { if (!ProBuilderReflection.RefreshMesh(converted)) throw ProBuilderErrors.OutcomeUnknown("convert-to-probuilder", "readback", "ProBuilder refresh failed."); EditorSceneManager.MarkSceneDirty(go.scene); var freshGo = EditorUtility.InstanceIDToObject(id) as GameObject; var fresh = ProBuilderReflection.GetProBuilderMesh(freshGo); var vertices = ProBuilderReflection.GetVertexCount(fresh); var faces = ProBuilderReflection.GetFaceCount(fresh); if (!ProBuilderAtomicReadback.ConvertedGeometryMatchesSource(fresh, source) || vertices < 1 || faces < 1) throw ProBuilderErrors.OutcomeUnknown("convert-to-probuilder", "postcondition", "Converted geometry could not be confirmed."); return new System.Threading.Tasks.ValueTask<Result>(new Result { Converted = true, VertexCount = vertices, FaceCount = faces }); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("convert-to-probuilder", "readback", ex.Message); }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/create-poly-shape.cs

@@ -0,0 +1,55 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+using UnityEngine.ProBuilder.MeshOperations;
+namespace UnityCli.ProBuilder
+{
+    public class CreatePolyShapeTool : IUnityCliTool<CreatePolyShapeTool.Request, CreatePolyShapeTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public List<Point3D> Points { get; set; } public double? ExtrudeHeight { get; set; } public bool FlipNormals { get; set; } public string Name { get; set; } }
+        public sealed class Point3D { public double X { get; set; } public double Y { get; set; } public double Z { get; set; } }
+        public sealed class Result { public ObjectRef Object { get; set; } }
+        public sealed class ObjectRef { public long Id { get; set; } public string Name { get; set; } public string Path { get; set; } public long FaceCount { get; set; } public long VertexCount { get; set; } }
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.create-poly-shape",
+            Summary = "Create a ProBuilder mesh from an extruded polygon.",
+            Description = "Create a ProBuilder mesh from at least three polygon points, with optional extrusion and normal direction.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 15000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "创建水平三角形", Input = new Request { FlipNormals = false, Name = "ProBuilder_Triangle", Points = new List<Point3D> { new Point3D { X = 0, Y = 0, Z = 0 }, new Point3D { X = 1, Y = 0, Z = 0 }, new Point3D { X = 0, Y = 0, Z = 1 } } } }
+            }
+        };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable) throw ProBuilderErrors.PackageNotAvailable();
+            var name = request.Name ?? "ProBuilder_PolyShape";
+            var height = ProBuilderOperationProof.CheckedFloat(request.ExtrudeHeight ?? 1d, "extrudeHeight");
+            var flipNormals = request.FlipNormals;
+            if (string.IsNullOrWhiteSpace(name) || request.Points == null || request.Points.Any(point => point == null)) throw ProBuilderErrors.SchemaInvalid("name must be non-empty and points must be objects.");
+            var points = request.Points.Select(point => ProBuilderOperationProof.CheckedVector3(point.X, point.Y, point.Z, "points")).ToList();
+            if (points.Count < 3) throw ProBuilderErrors.SchemaInvalid("At least 3 points are required for create-poly-shape.");
+            ctx.CommitEffect();
+            GameObject go = null;
+            var id = 0;
+            try { go = new GameObject(name); id = go.GetInstanceID(); Undo.RegisterCreatedObjectUndo(go, "ProBuilder Create Poly Shape"); var mesh = go.AddComponent<ProBuilderMesh>(); var action = AppendElements.CreateShapeFromPolygon(mesh, points, height, flipNormals); if (mesh == null || action == null || action.status != ActionResult.Status.Success) throw ProBuilderErrors.OutcomeUnknown("create-poly-shape", "invoke", "CreateShapeFromPolygon failed."); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("create-poly-shape", "invoke", ex.Message); }
+            try { var mesh = ProBuilderReflection.GetProBuilderMesh(go); if (!ProBuilderReflection.RefreshMesh(mesh)) throw ProBuilderErrors.OutcomeUnknown("create-poly-shape", "readback", "ProBuilder refresh failed."); EditorSceneManager.MarkSceneDirty(go.scene); var fresh = EditorUtility.InstanceIDToObject(id) as GameObject; var freshMesh = ProBuilderReflection.GetProBuilderMesh(fresh); if (fresh == null || fresh.name != name || !ProBuilderAtomicReadback.PolyShapeMatchesRequest(fresh, freshMesh, points, height, flipNormals)) throw ProBuilderErrors.OutcomeUnknown("create-poly-shape", "postcondition", "Created polygon could not be confirmed."); return new System.Threading.Tasks.ValueTask<Result>(new Result { Object = new ObjectRef { Id = fresh.GetInstanceID(), Name = fresh.name, Path = HierarchyPath(fresh), FaceCount = ProBuilderReflection.GetFaceCount(freshMesh), VertexCount = ProBuilderReflection.GetVertexCount(freshMesh) } }); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("create-poly-shape", "readback", ex.Message); }
+        }
+        private static string HierarchyPath(GameObject go) { var names = new Stack<string>(); for (var current = go.transform; current != null; current = current.parent) names.Push(current.name); return string.Join("/", names.ToArray()); }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/create-polygon.cs

@@ -0,0 +1,28 @@
+#if UNITY_EDITOR
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+namespace UnityCli.ProBuilder
+{
+    public class CreatePolygonTool : IUnityCliTool<CreatePolygonTool.Request, CreatePolygonTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } [UnityCliRequired] public List<long> VertexIndices { get; set; } public bool? Unordered { get; set; } }
+        public sealed class Result { public long NewFaceIndex { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "probuilder.create-polygon", Summary = "Create a polygon face from selected vertices.", Description = "Create a polygon from at least three valid vertex indices. unordered defaults to true.", Group = "probuilder", DestructiveHint = false, SideEffects = new[] { "scene-modify", "undo-stack" }, Target = "editor", PlayModeSupport = "editor-only", DefaultTimeoutMs = 10000, MaxTimeoutMs = 30000, Examples = new[] { new ToolExample { Description = "创建多边形", Input = new Request { Target = "MyCube", VertexIndices = new List<long> { 0, 1, 2 } } } } };
+        public System.Threading.Tasks.ValueTask<Result> ExecuteAsync(Request request, UnityCliProjectToolContext ctx, System.Threading.CancellationToken ct = default)
+        {
+            if (!ProBuilderReflection.IsAvailable) throw ProBuilderErrors.PackageNotAvailable(); var go = ProBuilderInput.ResolveTarget(request.Target); if (go == null) throw ProBuilderErrors.TargetNotFound(request.Target); var mesh = ProBuilderReflection.GetProBuilderMesh(go); if (mesh == null) throw ProBuilderErrors.OperationFailed("create-polygon", "No ProBuilderMesh on target.");
+            var indices = request.VertexIndices?.Select(value => ProBuilderOperationProof.CheckedInt(value, "vertexIndices")).ToArray(); var vertexCount = ProBuilderReflection.GetVertexCount(mesh); var beforeCount = ProBuilderReflection.GetFaceCount(mesh);
+            if (indices == null || indices.Length < 3 || indices.Distinct().Count() != indices.Length || vertexCount < 0 || beforeCount < 0 || indices.Any(value => value < 0 || value >= vertexCount)) throw ProBuilderErrors.SchemaInvalid("vertexIndices must contain at least 3 unique valid vertices.");
+            var unordered = request.Unordered ?? true; var id = go.GetInstanceID(); ctx.CommitEffect();
+            try { ProBuilderAtomicReadback.RegisterMeshUndo(go, mesh, "ProBuilder Create Polygon"); if (!ProBuilderReflection.CreatePolygon(mesh, indices, unordered)) throw ProBuilderErrors.OutcomeUnknown("create-polygon", "invoke", "AppendElements.CreatePolygon failed."); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("create-polygon", "invoke", ex.Message); }
+            try { if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(mesh)) throw ProBuilderErrors.OutcomeUnknown("create-polygon", "readback", "ProBuilder refresh failed."); EditorSceneManager.MarkSceneDirty(go.scene); var fresh = EditorUtility.InstanceIDToObject(id) as GameObject; var freshMesh = ProBuilderReflection.GetProBuilderMesh(fresh); if (!ProBuilderAtomicReadback.PolygonWasCreatedFromRequestedVertices(freshMesh, indices, beforeCount + 1)) throw ProBuilderErrors.OutcomeUnknown("create-polygon", "postcondition", "Created polygon could not be confirmed."); return new System.Threading.Tasks.ValueTask<Result>(new Result { NewFaceIndex = beforeCount }); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("create-polygon", "readback", ex.Message); }
+        }
+    }
+}
+#endif