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.interaction.test.tsx

@@ -150,6 +150,14 @@ function stubCanvas(dataUrl: string, drawImage = vi.fn()) {
   return drawImage;
 }
 
+function confirmPuzzlePointCost() {
+  const confirmDialog = screen.getByRole('dialog', {
+    name: '确认消耗泥点',
+  });
+  expect(within(confirmDialog).getByText('消耗 2 泥点')).toBeTruthy();
+  fireEvent.click(within(confirmDialog).getByRole('button', { name: '确定' }));
+}
+
 test('puzzle workspace submits the work form instead of agent chat', () => {
   const onCreateFromForm = vi.fn();
 
@@ -174,6 +182,9 @@ test('puzzle workspace submits the work form instead of agent chat', () => {
   });
   fireEvent.click(screen.getByRole('button', { name: /生成拼图游戏草稿/u }));
 
+  expect(onCreateFromForm).not.toHaveBeenCalled();
+  confirmPuzzlePointCost();
+
   expect(onCreateFromForm).toHaveBeenCalledWith({
     seedText: '一只猫在雨夜灯牌下回头。',
     pictureDescription: '一只猫在雨夜灯牌下回头。',
@@ -243,6 +254,7 @@ test('puzzle workspace keeps the reference image upload as a primary panel', ()
     target: { value: '一只猫在阳光窗台上看着毛线球。' },
   });
   fireEvent.click(screen.getByRole('button', { name: /生成拼图游戏草稿/u }));
+  confirmPuzzlePointCost();
   expect(onCreateFromForm).toHaveBeenCalledWith(
     expect.objectContaining({
       pictureDescription: '一只猫在阳光窗台上看着毛线球。',
@@ -303,6 +315,7 @@ test('puzzle workspace selects a history image from the upload card', async () =
     target: { value: '保留历史图里的主体，改成晴天花园。' },
   });
   fireEvent.click(screen.getByRole('button', { name: /生成拼图游戏草稿/u }));
+  confirmPuzzlePointCost();
 
   expect(onCreateFromForm).toHaveBeenCalledWith({
     seedText: '保留历史图里的主体，改成晴天花园。',
@@ -356,6 +369,7 @@ test('puzzle workspace falls back to compile action for restored sessions', () =
   );
 
   fireEvent.click(screen.getByRole('button', { name: /生成拼图游戏草稿/u }));
+  confirmPuzzlePointCost();
 
   expect(onCreateFromForm).not.toHaveBeenCalled();
   expect(onExecuteAction).toHaveBeenCalledWith({
@@ -389,6 +403,7 @@ test('puzzle workspace switches the image model from the description box', () =>
   expect(screen.queryByRole('menuitemradio', { name: '原模型' })).toBeNull();
   fireEvent.click(screen.getByRole('menuitemradio', { name: 'nanobanana2' }));
   fireEvent.click(screen.getByRole('button', { name: /生成拼图游戏草稿/u }));
+  confirmPuzzlePointCost();
 
   expect(onCreateFromForm).toHaveBeenCalledWith(
     expect.objectContaining({
@@ -538,6 +553,7 @@ test('puzzle workspace submits uploaded reference image when AI redraw is on', a
     target: { value: '保留上传画面的主体和构图，改成雨夜灯街。' },
   });
   fireEvent.click(screen.getByRole('button', { name: /生成拼图游戏草稿/u }));
+  confirmPuzzlePointCost();
 
   expect(onCreateFromForm).toHaveBeenCalledWith({
     seedText: '保留上传画面的主体和构图，改成雨夜灯街。',

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>
   );
 }