@alpsckr/unitycli 0.4.0

package/extensions/probuilder/unitypkg/Editor/ProBuilder/flip-normals.cs

@@ -0,0 +1,102 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.flip-normals — 翻转 ProBuilder 网格选定面的法线。
+    /// </summary>
+    public class FlipNormalsTool : IUnityCliTool<FlipNormalsTool.Request, FlipNormalsTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public List<long> FaceIndices { get; set; }             // 可选,空则作用于全部面
+        }
+
+        public sealed class Result
+        {
+            public long FlippedCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.flip-normals",
+            Summary = "Flip normals of selected faces on a ProBuilder mesh.",
+            Description = "Flip the normals of selected faces on a ProBuilder mesh. When faceIndices is omitted, all faces are flipped. Complete terminal verification requires a Renderer with non-empty sharedMaterials, valid face submesh indices, and every material slot used by at least one face. UV0 must be complete for every raw vertex or absent for the whole mesh; partial UV0 profiles are rejected.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "翻转面 0 法线", Input = new Request { Target = "MyCube", 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);
+            if (mesh == null) throw ProBuilderErrors.OperationFailed("flip-normals", "No ProBuilderMesh on target.");
+            // The canonical snapshot freezes target/component identity before the effect.
+
+            var typedMesh = mesh as ProBuilderMesh;
+            var faceCount = typedMesh == null ? -1 : typedMesh.faces.Count;
+            if (faceCount < 1)
+                throw ProBuilderErrors.OperationFailed("flip-normals", "Target has no readable faces.");
+            int[] faceIndices = request.FaceIndices?.Select(i => ProBuilderOperationProof.CheckedInt(i, "faceIndices")).ToArray();
+            if (faceIndices == null || faceIndices.Length == 0)
+                faceIndices = Enumerable.Range(0, faceCount).ToArray();
+            // 同一 occurrence 仅消费一次，保留首次请求顺序。
+            faceIndices = faceIndices.Distinct().ToArray();
+            ProBuilderOperationProof.ValidateFaceIndices(mesh, faceIndices);
+            // effect 前按请求顺序冻结 exact occurrence；后续不得再按 index 解析选区。
+            var frozenFaces = faceIndices.Select(index => typedMesh.faces[index]).ToArray();
+            var plan = ProBuilderFlipCompletionProof.CaptureFlip(go, frozenFaces, faceIndices);
+            if (plan == null) throw ProBuilderErrors.OperationFailed("flip-normals", "Requested complete terminal state is not readable.");
+            ctx.CommitEffect();
+            try
+            {
+            Undo.RecordObject(go, "ProBuilder Flip Normals");
+            try { foreach (var face in plan.FrozenFaces) face.Reverse(); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch { throw ProBuilderErrors.OutcomeUnknown("flip-normals", "invoke", "Face.Reverse threw after the effect barrier."); }
+
+            if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(typedMesh))
+                throw ProBuilderErrors.OutcomeUnknown("flip-normals", "readback", "ProBuilder mesh payload-preserving refresh failed after the effect.");
+            EditorSceneManager.MarkSceneDirty(go.scene);
+            try
+            {
+                if (!ProBuilderFlipCompletionProof.FlipMatches(plan, target))
+                    throw ProBuilderErrors.OutcomeUnknown("flip-normals", "postcondition", "The complete Face.Reverse terminal state was not proven by fresh readback.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception)
+            {
+                throw ProBuilderErrors.OutcomeUnknown("flip-normals", "postcondition", "Flip terminal-state readback threw after the effect barrier.");
+            }
+
+            var flipped = plan.FrozenFaces.Length;
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { FlippedCount = flipped });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("flip-normals", "postcondition", exception.Message); }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/freeze-transform.cs

@@ -0,0 +1,45 @@
+#if UNITY_EDITOR
+using System;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+using UnityEngine.ProBuilder.MeshOperations;
+namespace UnityCli.ProBuilder
+{
+    /// <summary>probuilder.freeze-transform — 将变换烘焙到网格顶点并重置变换。</summary>
+    public class FreezeTransformTool : IUnityCliTool<FreezeTransformTool.Request, FreezeTransformTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } }
+        public sealed class Result { public long BakedVertexCount { get; set; } }
+        public ToolDescriptor Describe() => new() { Name = "probuilder.freeze-transform", Summary = "Bake a ProBuilder mesh scale into vertex positions and reset localScale.", Description = "Call ProBuilder 5.2.4 FreezeScaleTransform on a root object: bake localScale into every referenced raw vertex while preserving position and rotation, then set localScale to one.", 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("freeze-transform", "No ProBuilderMesh on target."); var count = mesh.vertexCount;
+            if (mesh.vertexCount < 1) throw ProBuilderErrors.OperationFailed("freeze-transform", "Mesh has no vertices.");
+            if (go.transform.localScale == Vector3.one) return new System.Threading.Tasks.ValueTask<Result>(new Result { BakedVertexCount = 0 });
+            var plan = ProBuilderAtomicReadback.CaptureScaleBake(go, mesh);
+            if (plan == null) throw ProBuilderErrors.OperationFailed("freeze-transform", "Scale bake inputs are unreadable or non-finite.");
+            var instanceId = go.GetInstanceID();
+            ctx.CommitEffect();
+            try
+            {
+                ProBuilderAtomicReadback.RegisterMeshUndo(go, mesh, "ProBuilder Freeze Transform", true);
+                mesh.FreezeScaleTransform();
+                mesh.ToMesh();
+                mesh.Refresh();
+                EditorSceneManager.MarkSceneDirty(go.scene);
+                var freshGo = EditorUtility.InstanceIDToObject(instanceId) as GameObject;
+                var fresh = ProBuilderReflection.GetProBuilderMesh(freshGo);
+                if (fresh == null) throw ProBuilderErrors.OutcomeUnknown("freeze-transform", "readback", "Fresh target mesh is unreadable.");
+                if (!ProBuilderAtomicReadback.ScaleWasBaked(freshGo, fresh, plan)) throw ProBuilderErrors.OutcomeUnknown("freeze-transform", "postcondition", "Scale was not baked into readable geometry.");
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { BakedVertexCount = count });
+            }
+            catch (Exception exception) when (!(exception is UnityCliBridge.BridgeCommandException))
+            {
+                throw ProBuilderErrors.OutcomeUnknown("freeze-transform", "invoke", exception.Message);
+            }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/insert-vertex.cs

@@ -0,0 +1,132 @@
+#if UNITY_EDITOR
+using System;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.insert-vertex — 在边或面上插入新顶点。
+    /// </summary>
+    public class InsertVertexTool : IUnityCliTool<InsertVertexTool.Request, InsertVertexTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            public EdgeRef Edge { get; set; }                       // 可选,边 {a,b}
+            public long? FaceIndex { get; set; }                    // 可选,面索引
+            public double X { get; set; }                           // 默认 0
+            public double Y { get; set; }                           // 默认 0
+            public double Z { get; set; }                           // 默认 0
+        }
+
+        public sealed class EdgeRef
+        {
+            public long A { get; set; }
+            public long B { get; set; }
+        }
+
+        public sealed class Result
+        {
+            public bool Inserted { get; set; }
+            public long VertexCountBefore { get; set; }
+            public long VertexCountAfter { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.insert-vertex",
+            Summary = "Insert a new vertex on an edge or face of a ProBuilder mesh.",
+            Description = "Insert a new vertex on an edge or face of a ProBuilder mesh. Provide exactly one of edge or faceIndex; the insertion point uses target-local X/Y/Z coordinates and must lie strictly inside the selected edge or face. Both modes require initialized sharedTextures and absent UV1 because ProBuilder 5.2.4 dereferences the texture lookup and ToMesh clears UV1. Face mode requires a manual-UV face with raw vertices used by no other face and an empty shared-texture partition. Edge mode requires every affected face to be one manual-UV triangle with raw vertices exclusively owned by that face and no shared-texture mapping because ProBuilder 5.2.4 deletes/reorders boundary vertices without preserving unrelated raw ownership or reordering sharedIndexesUV. Both modes freeze the exact new-point payload and preflight normal, tangent, and smoothing refresh arithmetic.",
+            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", Edge = new EdgeRef { A = 0, B = 1 }, X = 0.5, Y = 0, Z = 0 } }
+            }
+        };
+
+        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("insert-vertex", "No ProBuilderMesh on target.");
+            // Canonical insert proof owns the pre-effect identity claim.
+
+            var point = ProBuilderOperationProof.CheckedVector3(request.X, request.Y, request.Z, "point");
+            var target = request.Target;
+            var edge = request.Edge;
+            var faceIndex = request.FaceIndex;
+
+            if ((edge != null) == faceIndex.HasValue)
+                throw ProBuilderErrors.SchemaInvalid("Pass exactly one of edge or faceIndex for insert-vertex.");
+            var requestedFaces = faceIndex.HasValue ? new[] { ProBuilderOperationProof.CheckedInt(faceIndex.Value, "faceIndex") } : null;
+            var requestedEdges = edge == null ? null : ProBuilderOperationProof.ValidateEdges(mesh, null, new[] { new ProBuilderInput.EdgePair { a = ProBuilderOperationProof.CheckedInt(edge.A, "edge.a"), b = ProBuilderOperationProof.CheckedInt(edge.B, "edge.b") } });
+            if (requestedFaces != null)
+            {
+                ProBuilderOperationProof.ValidateFaceIndices(mesh, requestedFaces);
+                if (ProBuilderInsertCompletionProof.HasFaceInsertionSharedTextureConflict(go, requestedFaces[0]))
+                    throw ProBuilderErrors.SchemaInvalid("face insertion cannot preserve this mesh's shared texture groups with ProBuilder 5.2.4; use edge mode or remove the UV sharing partition explicitly first.");
+            }
+            var requestedEdge = edge == null ? null : new[] { ProBuilderOperationProof.CheckedInt(edge.A, "edge.a"), ProBuilderOperationProof.CheckedInt(edge.B, "edge.b") };
+            var before = ProBuilderInsertCompletionProof.Capture(go, requestedEdge, requestedFaces == null ? -1 : requestedFaces[0], out var captureFailure);
+            if (before == null) throw ProBuilderErrors.OperationFailed("insert-vertex", "Requested canonical insertion geometry is not readable: " + captureFailure + ".");
+            if (!ProBuilderInsertCompletionProof.PointIsStrictlyInterior(before, point))
+                throw ProBuilderErrors.SchemaInvalid("point must be strictly inside the requested edge or face and must not equal an existing point.");
+            if (!ProBuilderInsertCompletionProof.TerminalCanRefresh(before, point))
+                throw ProBuilderErrors.SchemaInvalid("the exact inserted topology must keep all 5.2.4 normal, tangent, and smoothing refresh arithmetic finite and bounded.");
+            var vertexCountBefore = ProBuilderReflection.GetVertexCount(mesh);
+            if (vertexCountBefore < 0)
+                throw ProBuilderErrors.OperationFailed("insert-vertex", "Pre-effect vertex count is not readable.");
+            ctx.CommitEffect();
+            try
+            {
+                Undo.RecordObject(go, "ProBuilder Insert Vertex");
+                var inserted = edge != null
+                    ? ProBuilderReflection.InsertVertexOnEdgeByPair(mesh, requestedEdge[0], requestedEdge[1], point)
+                    : ProBuilderReflection.InsertVertexInFace(mesh, requestedFaces[0], point);
+                if (!inserted)
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "invoke", "ProBuilder 5.2.4 AppendElements insertion failed.");
+                if (edge != null && !ProBuilderInsertCompletionProof.RestoreEdgeFaceAttributes(mesh, before))
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "invoke", "Affected edge faces could not restore their frozen attributes before refresh.");
+                if (!ProBuilderReflection.RefreshMesh(mesh))
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "invoke", "ProBuilder data changed but ToMesh/Refresh did not complete.");
+                var freshMesh = CanonicalMeshSnapshot.ResolveFreshMesh(target, before.Before.Identity);
+                if (freshMesh == null)
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "readback", "Fresh target topology could not be read.");
+                var vertexCountAfter = ProBuilderReflection.GetVertexCount(freshMesh);
+                if (vertexCountAfter < 0)
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "readback", "Fresh target topology could not be read.");
+                var after = CanonicalMeshSnapshot.Capture(freshMesh.gameObject, Array.Empty<int>());
+                if (after == null)
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "readback", "Fresh canonical topology or compiled Mesh could not be read.");
+                if (!ProBuilderInsertCompletionProof.Matches(before, after, point, out var proofFailure))
+                    throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "postcondition", "Requested point, edge replacement or face child union/winding/material/UV/smoothing were not proven by fresh readback: " + proofFailure + ".");
+                EditorSceneManager.MarkSceneDirty(go.scene);
+                return new System.Threading.Tasks.ValueTask<Result>(new Result
+                {
+                    Inserted = true,
+                    VertexCountBefore = vertexCountBefore,
+                    VertexCountAfter = vertexCountAfter
+                });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception)
+            {
+                throw ProBuilderErrors.OutcomeUnknown("insert-vertex", "postcondition", exception.Message);
+            }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/merge-faces.cs

@@ -0,0 +1,44 @@
+#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 MergeFacesTool : IUnityCliTool<MergeFacesTool.Request, MergeFacesTool.Result>
+    {
+        public sealed class Request { [UnityCliRequired] public string Target { get; set; } [UnityCliRequired] public List<long> FaceIndices { get; set; } }
+        public sealed class Result { public long BeforeFaceCount { get; set; } public long AfterFaceCount { get; set; } public long MergedSourceFaceCount { get; set; } }
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.merge-faces",
+            Summary = "Merge selected ProBuilder faces.",
+            Description = "Merge at least two unique valid faces into one ProBuilder face.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "合并 strict-domain 面 0 和 1", Input = new Request { FaceIndices = new List<long> { 0, 1 }, Target = "SharedEdgeTriangles" } }
+            }
+        };
+        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("merge-faces", "No ProBuilderMesh on target.");
+            var indices = request.FaceIndices?.Select(value => ProBuilderOperationProof.CheckedInt(value, "faceIndices")).ToArray(); var before = ProBuilderReflection.GetFaceCount(mesh); if (indices == null || indices.Length < 2 || indices.Distinct().Count() != indices.Length || before < 0 || ProBuilderReflection.GetFacesByIndices(mesh, indices) == null) throw ProBuilderErrors.SchemaInvalid("faceIndices must contain at least 2 unique valid faces."); var id = go.GetInstanceID(); ctx.CommitEffect();
+            try { ProBuilderAtomicReadback.RegisterMeshUndo(go, mesh, "ProBuilder Merge Faces"); var merged = MergeElements.Merge(mesh as ProBuilderMesh, ProBuilderReflection.GetFacesByIndices(mesh, indices).Cast<Face>()); if (merged == null) throw ProBuilderErrors.OutcomeUnknown("merge-faces", "invoke", "MergeElements.Merge failed."); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("merge-faces", "invoke", ex.Message); }
+            try { if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(mesh)) throw ProBuilderErrors.OutcomeUnknown("merge-faces", "readback", "ProBuilder refresh failed."); EditorSceneManager.MarkSceneDirty(go.scene); var fresh = ProBuilderReflection.GetProBuilderMesh(EditorUtility.InstanceIDToObject(id) as GameObject); var after = ProBuilderReflection.GetFaceCount(fresh); if (after < 0 || after != before - indices.Length + 1) throw ProBuilderErrors.OutcomeUnknown("merge-faces", "postcondition", "Fresh face count did not confirm merge."); return new System.Threading.Tasks.ValueTask<Result>(new Result { BeforeFaceCount = before, AfterFaceCount = after, MergedSourceFaceCount = indices.Length }); }
+            catch (UnityCliBridge.BridgeCommandException) { throw; } catch (Exception ex) { throw ProBuilderErrors.OutcomeUnknown("merge-faces", "readback", ex.Message); }
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/merge-objects.cs

@@ -0,0 +1,130 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.merge-objects — 将多个 GameObject 合并为单个 ProBuilder 对象。
+    /// </summary>
+    public class MergeObjectsTool : IUnityCliTool<MergeObjectsTool.Request, MergeObjectsTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public List<string> Targets { get; set; }
+            public string Name { get; set; }                         // 可选,默认 ProBuilder_Merged
+        }
+
+        public sealed class Result
+        {
+            public ObjectRef MergedObject { 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.merge-objects",
+            Summary = "Merge multiple GameObjects into a single ProBuilder mesh object.",
+            Description = "Merge at least two existing ProBuilderMesh objects into the first requested object with the ProBuilder 5.2.4 CombineMeshes API. Every source must already have ProBuilderMesh and no UV1; convert regular meshes with probuilder.convert-to-probuilder before calling this Tool. UV1 is rejected because ToMesh clears it. All target-local projections and the complete merged refresh arithmetic must be finite and bounded before mutation.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 15000,
+            MaxTimeoutMs = 60000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "合并两个对象", Input = new Request { Targets = new List<string> { "Cube1", "Cube2" }, Name = "Merged" } }
+            }
+        };
+
+        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);
+            if (request.Targets == null || targets == null || targets.Length != request.Targets.Count || targets.Length < 2)
+                throw ProBuilderErrors.SchemaInvalid("At least 2 unique, unambiguous targets required for merge-objects.");
+
+            var name = request.Name ?? "ProBuilder_Merged";
+            if (string.IsNullOrWhiteSpace(name)) throw ProBuilderErrors.SchemaInvalid("name must be non-empty.");
+            if (targets.Select(target => target.GetInstanceID()).Distinct().Count() != targets.Length)
+                throw ProBuilderErrors.SchemaInvalid("merge-objects does not accept duplicate source identities.");
+            if (targets.Any(left => targets.Any(right => left != right && (left.transform.IsChildOf(right.transform) || right.transform.IsChildOf(left.transform)))))
+                throw ProBuilderErrors.SchemaInvalid("merge-objects does not accept ancestor/descendant sources.");
+            if (targets.Any(target => ProBuilderReflection.GetProBuilderMesh(target) == null))
+                throw ProBuilderErrors.SchemaInvalid("merge-objects requires every target to already have a ProBuilderMesh component; call probuilder.convert-to-probuilder first for regular meshes.");
+            if (targets.Any(target => target.scene.handle != targets[0].scene.handle || !target.scene.isLoaded || target.transform.childCount != 0 && target != targets[0]))
+                throw ProBuilderErrors.SchemaInvalid("All sources must be in the same loaded scene and non-first sources must not have children.");
+            if (targets.Any(target => !FiniteInvertible(target.transform.localToWorldMatrix) || !FiniteInvertible(target.transform.worldToLocalMatrix)))
+                throw ProBuilderErrors.SchemaInvalid("Every source transform must be finite and invertible.");
+            var plan = ProBuilderVertexObjectCompletionProof.CaptureMergeObjects(targets, name);
+            if (plan == null)
+                throw ProBuilderErrors.SchemaInvalid("merge-objects requires strict canonical ProBuilder sources, complete sharedTextures, absent UV1, closed non-null material slots, deterministic contributor UVs, and fewer than 65535 raw vertices.");
+
+            var pbMeshes = targets.Select(ProBuilderReflection.GetProBuilderMesh).ToArray();
+            ctx.CommitEffect();
+            try
+            {
+                Undo.RecordObject(targets[0], "ProBuilder Merge Objects");
+                if (!ProBuilderReflection.CombineMeshesViaReflection(pbMeshes, pbMeshes[0])) throw ProBuilderErrors.OutcomeUnknown("merge-objects", "invoke", "ProBuilder 5.x CombineMeshes.Combine did not return exactly one mesh.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-objects", "invoke", exception.Message); }
+            GameObject freshGo;
+            object freshMesh;
+            try
+            {
+                if (!ProBuilderReflection.RefreshMesh(pbMeshes[0])) throw ProBuilderErrors.OutcomeUnknown("merge-objects", "readback", "ProBuilder mesh refresh failed after the effect.");
+                for (var index = 1; index < targets.Length; index++) Undo.DestroyObjectImmediate(targets[index]);
+                targets[0].name = name;
+                EditorSceneManager.MarkSceneDirty(targets[0].scene);
+                freshGo = EditorUtility.InstanceIDToObject(plan.Sources[0].Identity.GameObjectInstanceId) as GameObject;
+                freshMesh = ProBuilderReflection.GetProBuilderMesh(freshGo);
+                if (freshGo == null || freshMesh == null) throw ProBuilderErrors.OutcomeUnknown("merge-objects", "readback", "Result identity or mesh could not be resolved.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-objects", "readback", exception.Message); }
+            try
+            {
+                if (!ProBuilderVertexObjectCompletionProof.MergeObjectsMatches(plan, freshGo, freshMesh as UnityEngine.ProBuilder.ProBuilderMesh)) throw ProBuilderErrors.OutcomeUnknown("merge-objects", "postcondition", "The complete ProBuilder 5.2.4 combine terminal state was not proven by fresh readback.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-objects", "postcondition", exception.Message); }
+            try
+            {
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { MergedObject = new ObjectRef { Id = freshGo.GetInstanceID(), Name = freshGo.name, Path = HierarchyPath(freshGo) } });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-objects", "postcondition", exception.Message); }
+        }
+
+        /// <summary>矩阵必须有限且可逆，避免 contributor world 到 target local 变换不可复演。</summary>
+        private static bool FiniteInvertible(Matrix4x4 matrix)
+        {
+            if (Mathf.Abs(matrix.determinant) <= Mathf.Epsilon) return false;
+            for (var index = 0; index < 16; index++) if (float.IsNaN(matrix[index]) || float.IsInfinity(matrix[index])) return false;
+            return true;
+        }
+
+        private static string HierarchyPath(GameObject go)
+        {
+            var names = new Stack<string>();
+            var cur = go.transform;
+            while (cur != null) { names.Push(cur.name); cur = cur.parent; }
+            return string.Join("/", names.ToArray());
+        }
+    }
+}
+#endif

package/extensions/probuilder/unitypkg/Editor/ProBuilder/merge-vertices.cs

@@ -0,0 +1,109 @@
+#if UNITY_EDITOR
+using System.Collections.Generic;
+using System.Linq;
+using UnityEditor;
+using UnityEditor.SceneManagement;
+using UnityEngine;
+using UnityEngine.ProBuilder;
+
+namespace UnityCli.ProBuilder
+{
+    /// <summary>
+    /// probuilder.merge-vertices — 合并 ProBuilder 网格的选定顶点。
+    /// </summary>
+    public class MergeVerticesTool : IUnityCliTool<MergeVerticesTool.Request, MergeVerticesTool.Result>
+    {
+        public sealed class Request
+        {
+            [UnityCliRequired] public string Target { get; set; }
+            [UnityCliRequired] public List<long> VertexIndices { get; set; }
+            public bool CollapseToFirst { get; set; }               // 默认 false
+        }
+
+        public sealed class Result
+        {
+            public bool Changed { get; set; }
+            public string NoOpReason { get; set; }
+            public long MergedToIndex { get; set; }
+            public long SourceVertexCount { get; set; }
+        }
+
+        public ToolDescriptor Describe() => new()
+        {
+            Name = "probuilder.merge-vertices",
+            Summary = "Merge selected vertices of a ProBuilder mesh into a single vertex.",
+            Description = "Merge at least two selected vertices into one shared vertex. When collapseToFirst is true, the first selected vertex supplies the terminal position and payload; otherwise ProBuilder 5.2.4 averages the selected payload. An effectful merge must have initialized sharedTextures and no UV1 because MergeVertices dereferences the texture lookup and ToMesh clears UV1; an exact no-op returns before those APIs. The complete predicted raw, channel, world-position and triangle terminal must remain finite or the request is rejected before mutation.",
+            Group = "probuilder",
+            DestructiveHint = false,
+            SideEffects = new[] { "scene-modify", "undo-stack" },
+            Target = "editor",
+            PlayModeSupport = "editor-only",
+            DefaultTimeoutMs = 10000,
+            MaxTimeoutMs = 30000,
+            Examples = new[]
+            {
+                new ToolExample { Description = "合并顶点 0 和 1", Input = new Request { Target = "MyCube", VertexIndices = new List<long> { 0, 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("merge-vertices", "No ProBuilderMesh on target.");
+            var identity = ProBuilderOperationProof.CaptureIdentity(go);
+            if (identity == null) throw ProBuilderErrors.SchemaInvalid("Target must belong to a valid loaded scene.");
+
+            int[] vertexIndices = request.VertexIndices?.Select(i => ProBuilderOperationProof.CheckedInt(i, "vertexIndices")).ToArray();
+            var vertexCount = ProBuilderReflection.GetVertexCount(mesh);
+            if (vertexIndices == null || vertexIndices.Length < 2 || vertexIndices.Distinct().Count() != vertexIndices.Length)
+                throw ProBuilderErrors.SchemaInvalid("At least 2 unique vertexIndices are required for merge-vertices.");
+            if (vertexCount < 0 || vertexIndices.Any(index => index < 0 || index >= vertexCount))
+                throw ProBuilderErrors.SchemaInvalid("vertexIndices contains an invalid vertex index.");
+            var collapseToFirst = request.CollapseToFirst;
+            var before = ProBuilderVertexObjectCompletionProof.CaptureMergeVertices(mesh, vertexIndices, collapseToFirst);
+            if (before == null) throw ProBuilderErrors.OperationFailed("merge-vertices", "An effectful merge requires initialized sharedTextures, absent UV1, and a completely finite readable predicted terminal.");
+            if (before.IsNoOp)
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Changed = false, NoOpReason = "expected-terminal-equals-before", MergedToIndex = before.ExpectedReturnedIndex, SourceVertexCount = vertexIndices.Length });
+            ctx.CommitEffect();
+            try
+            {
+            int mergedToIndex;
+            try
+            {
+                Undo.RecordObject(go, "ProBuilder Merge Vertices");
+                if (!ProBuilderReflection.TryMergeVerticesWithCollapse(mesh, vertexIndices, collapseToFirst, out mergedToIndex))
+                    throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "invoke", "ProBuilder 5.x VertexEditing.MergeVertices could not be invoked.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "invoke", exception.Message); }
+            ProBuilderMesh freshMesh;
+            try
+            {
+                if (!ProBuilderReflection.RefreshMeshPreservingVertexPayload(mesh)) throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "readback", "ProBuilder mesh refresh failed after the effect.");
+                EditorSceneManager.MarkSceneDirty(go.scene);
+                freshMesh = ProBuilderOperationProof.ResolveFreshMesh(target, identity) as ProBuilderMesh;
+                if (freshMesh == null) throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "readback", "Fresh target identity could not be resolved.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "readback", exception.Message); }
+            try
+            {
+                if (!ProBuilderVertexObjectCompletionProof.MergeVerticesMatches(before, freshMesh, mergedToIndex)) throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "postcondition", "The complete ProBuilder 5.2.4 merge terminal state was not proven by fresh readback.");
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "postcondition", exception.Message); }
+                return new System.Threading.Tasks.ValueTask<Result>(new Result { Changed = true, MergedToIndex = mergedToIndex, SourceVertexCount = vertexIndices.Length });
+            }
+            catch (UnityCliBridge.BridgeCommandException) { throw; }
+            catch (System.Exception exception) { throw ProBuilderErrors.OutcomeUnknown("merge-vertices", "postcondition", exception.Message); }
+        }
+    }
+}
+#endif