Update Match3D/image-generation docs & code

Adds/updates documentation, assets and implementation for Match3D and puzzle image generation workflows. Key changes: decision logs and pitfalls updated to prefer VectorEngine Gemini for Match3D material sheets and to require edits (multipart) for 1:1 container reference images; guidance added for when to use APIMart vs VectorEngine. .env.example clarified APIMart/Responses config. Many new public assets and PPT visuals added. Code changes across frontend and backend: updated shared contracts, server-rs match3d/puzzle/image-generation handlers, VectorEngine/OpenAI image generation clients, and multiple React components/tests to handle UI/background/container image signing, edits workflow, and puzzle UI background resolution. Added src/services/puzzle-runtime/puzzleUiBackgroundSource.ts and related test updates. Includes notes about multipart HTTP/1.1 requirement and test/verification commands in docs.

src/components/puzzle-agent/PuzzleAgentWorkspace.tsx

@@ -162,6 +162,7 @@ export function PuzzleAgentWorkspace({
   const [isHistoryPickerOpen, setIsHistoryPickerOpen] = useState(false);
   const [isRemoveImageConfirmOpen, setIsRemoveImageConfirmOpen] =
     useState(false);
+  const [isPointCostConfirmOpen, setIsPointCostConfirmOpen] = useState(false);
   const previousSessionIdRef = useRef<string | null>(
     session?.sessionId ?? null,
   );
@@ -192,6 +193,7 @@ export function PuzzleAgentWorkspace({
     setCropState(null);
     setIsHistoryPickerOpen(false);
     setIsRemoveImageConfirmOpen(false);
+    setIsPointCostConfirmOpen(false);
   }, [initialFormPayload, session]);
 
   const pictureDescription = formState.pictureDescription.trim();
@@ -359,6 +361,19 @@ export function PuzzleAgentWorkspace({
       return;
     }
 
+    if (formState.aiRedraw) {
+      setIsPointCostConfirmOpen(true);
+      return;
+    }
+
+    executeSubmitForm();
+  };
+
+  const executeSubmitForm = () => {
+    if (!canSubmit) {
+      return;
+    }
+
     const payloadPictureDescription = formState.aiRedraw
       ? pictureDescription
       : pictureDescription || formState.referenceImageLabel || '上传拼图图片';
@@ -371,10 +386,12 @@ export function PuzzleAgentWorkspace({
     };
 
     if (!session && onCreateFromForm) {
+      setIsPointCostConfirmOpen(false);
       onCreateFromForm(payload);
       return;
     }
 
+    setIsPointCostConfirmOpen(false);
     onExecuteAction({
       action: 'compile_puzzle_draft',
       promptText: payloadPictureDescription,
@@ -697,6 +714,43 @@ export function PuzzleAgentWorkspace({
           </div>
         </div>
       ) : null}
+      {isPointCostConfirmOpen ? (
+        <div className="platform-modal-backdrop fixed inset-0 z-[80] flex items-center justify-center px-4 py-6">
+          <div
+            role="dialog"
+            aria-modal="true"
+            aria-labelledby="puzzle-point-cost-confirm-title"
+            className="platform-modal-shell platform-remap-surface w-full max-w-xs rounded-[1.35rem] p-5 shadow-[0_24px_70px_rgba(15,23,42,0.22)]"
+          >
+            <div
+              id="puzzle-point-cost-confirm-title"
+              className="text-base font-black text-[var(--platform-text-strong)]"
+            >
+              确认消耗泥点
+            </div>
+            <div className="mt-2 text-sm font-semibold leading-6 text-[var(--platform-text-base)]">
+              消耗 2 泥点
+            </div>
+            <div className="mt-5 grid grid-cols-2 gap-3">
+              <button
+                type="button"
+                onClick={() => setIsPointCostConfirmOpen(false)}
+                className="platform-button platform-button--secondary justify-center"
+              >
+                取消
+              </button>
+              <button
+                type="button"
+                disabled={!canSubmit}
+                onClick={executeSubmitForm}
+                className={`platform-button platform-button--primary justify-center ${!canSubmit ? 'cursor-not-allowed opacity-55' : ''}`}
+              >
+                确定
+              </button>
+            </div>
+          </div>
+        </div>
+      ) : null}
     </div>
   );
 }