Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

src/components/custom-world-home/CustomWorldCreationHub.tsx

@@ -2,6 +2,7 @@ import { useEffect, useMemo, useState } from 'react';
 
 import type { BigFishWorkSummary } from '../../../packages/shared/src/contracts/bigFishWorkSummary';
 import type { CustomWorldWorkSummary } from '../../../packages/shared/src/contracts/customWorldAgent';
+import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
 import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type { CustomWorldLibraryEntry } from '../../../packages/shared/src/contracts/runtime';
 import type { CustomWorldProfile } from '../../types';
@@ -44,6 +45,9 @@ type CustomWorldCreationHubProps = {
   bigFishItems?: BigFishWorkSummary[];
   onOpenBigFishDetail?: (item: BigFishWorkSummary) => void;
   onDeleteBigFish?: ((item: BigFishWorkSummary) => void) | null;
+  match3dItems?: Match3DWorkSummary[];
+  onOpenMatch3DDetail?: (item: Match3DWorkSummary) => void;
+  onDeleteMatch3D?: ((item: Match3DWorkSummary) => void) | null;
   puzzleItems?: PuzzleWorkSummary[];
   onOpenPuzzleDetail?: (item: PuzzleWorkSummary) => void;
   onDeletePuzzle?: ((item: PuzzleWorkSummary) => void) | null;
@@ -130,6 +134,9 @@ export function CustomWorldCreationHub({
   bigFishItems = [],
   onOpenBigFishDetail,
   onDeleteBigFish = null,
+  match3dItems = [],
+  onOpenMatch3DDetail,
+  onDeleteMatch3D = null,
   puzzleItems = [],
   onOpenPuzzleDetail,
   onDeletePuzzle = null,
@@ -144,15 +151,19 @@ export function CustomWorldCreationHub({
         rpgItems: items,
         rpgLibraryEntries,
         bigFishItems,
+        match3dItems,
         puzzleItems,
         canDeleteRpg: Boolean(onDeletePublished),
         canDeleteBigFish: Boolean(onDeleteBigFish),
+        canDeleteMatch3D: Boolean(onDeleteMatch3D),
         canDeletePuzzle: Boolean(onDeletePuzzle),
       }),
     [
       bigFishItems,
       items,
+      match3dItems,
       onDeleteBigFish,
+      onDeleteMatch3D,
       onDeletePublished,
       onDeletePuzzle,
       puzzleItems,
@@ -187,6 +198,9 @@ export function CustomWorldCreationHub({
       case 'big-fish':
         onOpenBigFishDetail?.(item.source.item);
         return;
+      case 'match3d':
+        onOpenMatch3DDetail?.(item.source.item);
+        return;
       case 'rpg':
         if (item.status === 'draft') {
           onOpenDraft(item.source.item);
@@ -217,6 +231,12 @@ export function CustomWorldCreationHub({
           onDeleteBigFish?.(sourceItem);
         };
       }
+      case 'match3d': {
+        const sourceItem = item.source.item;
+        return () => {
+          onDeleteMatch3D?.(sourceItem);
+        };
+      }
       case 'rpg': {
         const sourceItem = item.source.item;
         return () => {

src/components/custom-world-home/creationWorkShelf.ts

@@ -1,15 +1,17 @@
 import type { BigFishWorkSummary } from '../../../packages/shared/src/contracts/bigFishWorkSummary';
 import type { CustomWorldWorkSummary } from '../../../packages/shared/src/contracts/customWorldAgent';
+import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
 import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type { CustomWorldLibraryEntry } from '../../../packages/shared/src/contracts/runtime';
 import { buildPublicWorkStagePath } from '../../routing/appPageRoutes';
 import {
   buildBigFishPublicWorkCode,
+  buildMatch3DPublicWorkCode,
   buildPuzzlePublicWorkCode,
 } from '../../services/publicWorkCode';
 import type { CustomWorldProfile } from '../../types';
 
-export type CreationWorkShelfKind = 'rpg' | 'big-fish' | 'puzzle';
+export type CreationWorkShelfKind = 'rpg' | 'big-fish' | 'match3d' | 'puzzle';
 export type CreationWorkShelfStatus = 'draft' | 'published';
 
 export type CreationWorkShelfBadgeTone = 'warm' | 'success' | 'neutral';
@@ -50,6 +52,10 @@ export type CreationWorkShelfSource =
       kind: 'big-fish';
       item: BigFishWorkSummary;
     }
+  | {
+      kind: 'match3d';
+      item: Match3DWorkSummary;
+    }
   | {
       kind: 'puzzle';
       item: PuzzleWorkSummary;
@@ -80,18 +86,22 @@ export function buildCreationWorkShelfItems(params: {
   rpgItems: CustomWorldWorkSummary[];
   rpgLibraryEntries?: CustomWorldLibraryEntry<CustomWorldProfile>[];
   bigFishItems: BigFishWorkSummary[];
+  match3dItems?: Match3DWorkSummary[];
   puzzleItems: PuzzleWorkSummary[];
   canDeleteRpg?: boolean;
   canDeleteBigFish?: boolean;
+  canDeleteMatch3D?: boolean;
   canDeletePuzzle?: boolean;
 }) {
   const {
     rpgItems,
     rpgLibraryEntries = [],
     bigFishItems,
+    match3dItems = [],
     puzzleItems,
     canDeleteRpg = false,
     canDeleteBigFish = false,
+    canDeleteMatch3D = false,
     canDeletePuzzle = false,
   } = params;
 
@@ -102,6 +112,9 @@ export function buildCreationWorkShelfItems(params: {
     ...bigFishItems.map((item) =>
       mapBigFishWorkToShelfItem(item, canDeleteBigFish),
     ),
+    ...match3dItems.map((item) =>
+      mapMatch3DWorkToShelfItem(item, canDeleteMatch3D),
+    ),
     ...puzzleItems.map((item) =>
       mapPuzzleWorkToShelfItem(item, canDeletePuzzle),
     ),
@@ -203,6 +216,48 @@ function mapBigFishWorkToShelfItem(
   };
 }
 
+function mapMatch3DWorkToShelfItem(
+  item: Match3DWorkSummary,
+  canDelete: boolean,
+): CreationWorkShelfItem {
+  const status = item.publicationStatus === 'published' ? 'published' : 'draft';
+  const publicWorkCode =
+    status === 'published' ? buildMatch3DPublicWorkCode(item.profileId) : null;
+
+  return {
+    id: item.workId,
+    kind: 'match3d',
+    status,
+    title: item.gameName,
+    summary: item.summary,
+    updatedAt: item.updatedAt,
+    coverImageSrc: item.coverImageSrc ?? null,
+    coverRenderMode: 'image',
+    coverCharacterImageSrcs: [],
+    publicWorkCode,
+    sharePath:
+      publicWorkCode && status === 'published'
+        ? buildPublicWorkStagePath('work-detail', publicWorkCode)
+        : null,
+    openActionLabel: status === 'published' ? '查看详情' : '继续创作',
+    canDelete,
+    canShare: status === 'published' && Boolean(publicWorkCode),
+    badges: [
+      buildStatusBadge(status),
+      { id: 'type', label: '抓鹅', tone: 'neutral' },
+    ],
+    metrics:
+      status === 'published'
+        ? buildPublishedMetrics({
+            playCount: item.playCount,
+            remixCount: 0,
+            likeCount: 0,
+          })
+        : [],
+    source: { kind: 'match3d', item },
+  };
+}
+
 function mapPuzzleWorkToShelfItem(
   item: PuzzleWorkSummary,
   canDelete: boolean,

src/components/match3d-result/Match3DResultView.test.tsx

@@ -0,0 +1,103 @@
+// @vitest-environment jsdom
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, test, vi } from 'vitest';
+
+import type { Match3DWorkProfile } from '../../../packages/shared/src/contracts/match3dWorks';
+import * as match3dWorksService from '../../services/match3d-works';
+import { Match3DResultView } from './Match3DResultView';
+
+vi.mock('../ResolvedAssetImage', () => ({
+  ResolvedAssetImage: ({
+    src,
+    alt,
+    className,
+  }: {
+    src?: string | null;
+    alt?: string;
+    className?: string;
+  }) => (src ? <img src={src} alt={alt} className={className} /> : null),
+}));
+
+vi.mock('../../services/match3d-works', () => ({
+  publishMatch3DWork: vi.fn(),
+  updateMatch3DWork: vi.fn(),
+}));
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+function createProfile(
+  overrides: Partial<Match3DWorkProfile> = {},
+): Match3DWorkProfile {
+  return {
+    workId: 'match3d-work-1',
+    profileId: 'match3d-profile-1',
+    ownerUserId: 'user-1',
+    sourceSessionId: 'match3d-session-1',
+    gameName: '水果抓大鹅',
+    themeText: '水果',
+    summary: '水果主题的经典消除玩法。',
+    tags: ['水果'],
+    coverImageSrc: null,
+    referenceImageSrc: null,
+    clearCount: 4,
+    difficulty: 3,
+    publicationStatus: 'draft',
+    playCount: 0,
+    updatedAt: '2026-05-01T00:00:00.000Z',
+    publishedAt: null,
+    publishReady: false,
+    ...overrides,
+  };
+}
+
+describe('Match3DResultView', () => {
+  test('试玩只要求基础配置可保存，不被发布封面门槛阻断', async () => {
+    const profile = createProfile();
+    const onStartTestRun = vi.fn();
+    vi.mocked(match3dWorksService.updateMatch3DWork).mockResolvedValue({
+      item: profile,
+    });
+
+    render(
+      <Match3DResultView
+        profile={profile}
+        onBack={() => {}}
+        onStartTestRun={onStartTestRun}
+      />,
+    );
+
+    fireEvent.click(screen.getByRole('button', { name: '试玩' }));
+
+    await waitFor(() => {
+      expect(match3dWorksService.updateMatch3DWork).toHaveBeenCalledWith(
+        'match3d-profile-1',
+        expect.objectContaining({
+          clearCount: 4,
+          difficulty: 3,
+          gameName: '水果抓大鹅',
+        }),
+      );
+    });
+    expect(onStartTestRun).toHaveBeenCalledWith(profile);
+    expect(match3dWorksService.publishMatch3DWork).not.toHaveBeenCalled();
+  });
+
+  test('发布仍要求封面和标签数量满足门槛', () => {
+    render(
+      <Match3DResultView
+        profile={createProfile()}
+        onBack={() => {}}
+        onStartTestRun={() => {}}
+      />,
+    );
+
+    const publishButton = screen.getByRole('button', { name: '发布' });
+    expect(publishButton).toHaveProperty('disabled', true);
+
+    fireEvent.click(publishButton);
+    expect(match3dWorksService.publishMatch3DWork).not.toHaveBeenCalled();
+  });
+});

src/components/match3d-result/index.ts

@@ -0,0 +1 @@
+export { Match3DResultView } from './Match3DResultView';

src/components/match3d-runtime/Match3DRuntimeShell.tsx

@@ -70,6 +70,22 @@ function buildClientEventId(itemInstanceId: string) {
   )}`;
 }
 
+function isRunState(
+  status: Match3DRunSnapshot['status'],
+  expected: 'running' | 'won' | 'failed' | 'stopped',
+) {
+  return String(status).toLowerCase() === expected;
+}
+
+function isItemState(
+  state: Match3DItemSnapshot['state'],
+  expected: 'in_board' | 'in_tray' | 'cleared' | 'flying',
+) {
+  return String(state)
+    .replace(/([a-z])([A-Z])/gu, '$1_$2')
+    .toLowerCase() === expected;
+}
+
 function isPointInsideCircle(
   pointX: number,
   pointY: number,
@@ -86,7 +102,7 @@ function findHitItem(
   return run.items
     .filter(
       (item) =>
-        item.state === 'InBoard' &&
+        isItemState(item.state, 'in_board') &&
         item.clickable &&
         isPointInsideCircle(pointX, pointY, item),
     )
@@ -137,13 +153,13 @@ function Match3DToken({
   const visualSeed = resolveVisualSeed(item.visualKey);
   const size = `${item.radius * 200}%`;
   const itemStateClass =
-    item.state === 'Flying'
+    isItemState(item.state, 'flying')
       ? 'scale-75 opacity-0'
       : item.clickable
         ? 'cursor-pointer opacity-100 hover:scale-105 active:scale-95'
         : 'opacity-48';
 
-  if (item.state !== 'InBoard' && item.state !== 'Flying') {
+  if (!isItemState(item.state, 'in_board') && !isItemState(item.state, 'flying')) {
     return null;
   }
 
@@ -160,7 +176,7 @@ function Match3DToken({
       }}
       aria-label={`${visualSeed.label} ${item.clickable ? '可点击' : '被遮挡'}`}
       data-testid={`match3d-item-${item.itemInstanceId}`}
-      disabled={disabled || !item.clickable || item.state !== 'InBoard'}
+      disabled={disabled || !item.clickable || !isItemState(item.state, 'in_board')}
       onClick={() => onClick(item)}
     >
       <span className="relative z-10">{visualSeed.label}</span>
@@ -193,11 +209,11 @@ function Match3DSettlement({
   onBack: () => void;
   onRestart: () => void;
 }) {
-  if (run.status === 'Running') {
+  if (isRunState(run.status, 'running')) {
     return null;
   }
-  const won = run.status === 'Won';
-  const stopped = run.status === 'Stopped';
+  const won = isRunState(run.status, 'won');
+  const stopped = isRunState(run.status, 'stopped');
   const title = won ? '通关完成' : stopped ? '已停止' : '本轮失败';
   const description = won
     ? `用时 ${formatElapsed(run.startedAtMs, run.remainingMs, run.durationLimitMs)}`
@@ -265,7 +281,7 @@ export function Match3DRuntimeShell({
   }, [run?.remainingMs, run?.snapshotVersion]);
 
   useEffect(() => {
-    if (!run || run.status !== 'Running') {
+    if (!run || !isRunState(run.status, 'running')) {
       return undefined;
     }
     const timer = window.setInterval(() => {
@@ -296,7 +312,7 @@ export function Match3DRuntimeShell({
   }, [run]);
 
   const handleItemClick = async (item: Match3DItemSnapshot) => {
-    if (!run || run.status !== 'Running' || pendingClick) {
+    if (!run || !isRunState(run.status, 'running') || pendingClick) {
       return;
     }
     const optimisticRun = buildOptimisticRun(run, item);
@@ -337,7 +353,7 @@ export function Match3DRuntimeShell({
   };
 
   const handleBoardPointerDown = (event: PointerEvent<HTMLDivElement>) => {
-    if (!run || run.status !== 'Running' || pendingClick) {
+    if (!run || !isRunState(run.status, 'running') || pendingClick) {
       return;
     }
     const rect = stageRef.current?.getBoundingClientRect();

src/components/platform-entry/PlatformWorkDetailView.tsx

@@ -53,6 +53,9 @@ function getSourceLabel(entry: PlatformPublicGalleryCard) {
   if ('sourceType' in entry && entry.sourceType === 'big-fish') {
     return '大鱼吃小鱼';
   }
+  if ('sourceType' in entry && entry.sourceType === 'match3d') {
+    return '抓大鹅';
+  }
   return 'RPG';
 }
 

src/components/platform-entry/platformEntryTypes.ts

@@ -24,6 +24,7 @@ export type SelectionStage =
   | 'big-fish-runtime'
   | 'match3d-agent-workspace'
   | 'match3d-result'
+  | 'match3d-runtime'
   | 'puzzle-agent-workspace'
   | 'puzzle-generating'
   | 'puzzle-result'

src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx

@@ -10,6 +10,8 @@ import type {
   CustomWorldAgentSessionSnapshot,
   CustomWorldWorkSummary,
 } from '../../../packages/shared/src/contracts/customWorldAgent';
+import type { Match3DRunSnapshot } from '../../../packages/shared/src/contracts/match3dRuntime';
+import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
 import type { PuzzleRunSnapshot } from '../../../packages/shared/src/contracts/puzzleRuntimeSession';
 import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type { RpgCreationResultView } from '../../../packages/shared/src/contracts/rpgCreationResultView';
@@ -30,6 +32,20 @@ import {
   startLocalBigFishRuntimeRun,
 } from '../../services/big-fish-runtime';
 import { listBigFishWorks } from '../../services/big-fish-works';
+import { match3dCreationClient } from '../../services/match3d-creation';
+import {
+  clickMatch3DItem,
+  finishMatch3DTimeUp,
+  restartMatch3DRun,
+  startMatch3DRun,
+  stopMatch3DRun,
+} from '../../services/match3d-runtime';
+import {
+  deleteMatch3DWork,
+  getMatch3DWorkDetail,
+  listMatch3DGallery,
+  listMatch3DWorks,
+} from '../../services/match3d-works';
 import {
   createPuzzleAgentSession,
   getPuzzleAgentSession,
@@ -242,10 +258,34 @@ vi.mock('../../services/big-fish-gallery', () => ({
 
 vi.mock('../../services/big-fish-runtime', () => ({
   advanceLocalBigFishRuntimeRun: vi.fn((run) => run),
-  recordBigFishPlay: vi.fn(),
+  recordBigFishPlay: vi.fn(() => Promise.resolve()),
   startLocalBigFishRuntimeRun: vi.fn(),
 }));
 
+vi.mock('../../services/match3d-creation', () => ({
+  match3dCreationClient: {
+    createSession: vi.fn(),
+    executeAction: vi.fn(),
+    getSession: vi.fn(),
+    streamMessage: vi.fn(),
+  },
+}));
+
+vi.mock('../../services/match3d-works', () => ({
+  deleteMatch3DWork: vi.fn(),
+  getMatch3DWorkDetail: vi.fn(),
+  listMatch3DGallery: vi.fn(),
+  listMatch3DWorks: vi.fn(),
+}));
+
+vi.mock('../../services/match3d-runtime', () => ({
+  clickMatch3DItem: vi.fn(),
+  finishMatch3DTimeUp: vi.fn(),
+  restartMatch3DRun: vi.fn(),
+  startMatch3DRun: vi.fn(),
+  stopMatch3DRun: vi.fn(),
+}));
+
 vi.mock('../../services/puzzle-runtime/puzzleLocalRuntime', async () => {
   const actual = await vi.importActual<
     typeof import('../../services/puzzle-runtime/puzzleLocalRuntime')
@@ -399,6 +439,23 @@ vi.mock('../big-fish-result/BigFishResultView', () => ({
   ),
 }));
 
+vi.mock('../match3d-runtime/Match3DRuntimeShell', () => ({
+  Match3DRuntimeShell: ({
+    run,
+    onBack,
+  }: {
+    run: Match3DRunSnapshot | null;
+    onBack: () => void;
+  }) => (
+    <div className="match3d-runtime-shell-mock">
+      <div>抓大鹅运行态：{run?.runId ?? 'missing-run'}</div>
+      <button type="button" onClick={onBack}>
+        返回
+      </button>
+    </div>
+  ),
+}));
+
 vi.mock('../custom-world-agent/CustomWorldAgentWorkspace', () => ({
   CustomWorldAgentWorkspace: ({
     session,
@@ -599,6 +656,26 @@ function buildClearedPuzzleRun(params: {
   };
 }
 
+function buildMockMatch3DRun(profileId: string): Match3DRunSnapshot {
+  return {
+    runId: `match3d-run-${profileId}`,
+    profileId,
+    ownerUserId: 'user-2',
+    status: 'running',
+    snapshotVersion: 1,
+    startedAtMs: 1_000,
+    durationLimitMs: 600_000,
+    serverNowMs: 1_000,
+    remainingMs: 600_000,
+    clearCount: 4,
+    totalItemCount: 12,
+    clearedItemCount: 0,
+    items: [],
+    traySlots: Array.from({ length: 7 }, (_, slotIndex) => ({ slotIndex })),
+    failureReason: null,
+  };
+}
+
 function buildMockRpgGalleryDetail(
   entry: CustomWorldGalleryCard,
 ): CustomWorldLibraryEntry<CustomWorldProfile> {
@@ -1056,6 +1133,7 @@ beforeEach(() => {
   vi.mocked(upsertProfileBrowseHistory).mockResolvedValue([]);
   vi.mocked(clearProfileBrowseHistory).mockResolvedValue([]);
   vi.mocked(deleteRpgEntryWorldProfile).mockResolvedValue([]);
+  vi.mocked(recordBigFishPlay).mockResolvedValue(undefined);
   vi.mocked(recordRpgEntryWorldGalleryPlay).mockImplementation(
     async (ownerUserId, profileId) => ({
       ownerUserId,
@@ -1500,8 +1578,43 @@ beforeEach(() => {
   vi.mocked(listBigFishGallery).mockResolvedValue({
     items: [],
   });
-  vi.mocked(recordBigFishPlay).mockResolvedValue({
-    session: {} as never,
+  vi.mocked(recordBigFishPlay).mockResolvedValue(undefined);
+  vi.mocked(match3dCreationClient.createSession).mockResolvedValue({
+    session: null,
+  });
+  vi.mocked(match3dCreationClient.getSession).mockResolvedValue({
+    session: null,
+  });
+  vi.mocked(match3dCreationClient.streamMessage).mockResolvedValue(null);
+  vi.mocked(match3dCreationClient.executeAction).mockResolvedValue({
+    session: null,
+  });
+  vi.mocked(listMatch3DWorks).mockResolvedValue({
+    items: [],
+  });
+  vi.mocked(listMatch3DGallery).mockResolvedValue({
+    items: [],
+  });
+  vi.mocked(getMatch3DWorkDetail).mockRejectedValue(
+    new Error('未找到抓大鹅作品'),
+  );
+  vi.mocked(deleteMatch3DWork).mockResolvedValue({
+    items: [],
+  });
+  vi.mocked(startMatch3DRun).mockRejectedValue(
+    new Error('未启动抓大鹅运行态'),
+  );
+  vi.mocked(clickMatch3DItem).mockRejectedValue(
+    new Error('未执行抓大鹅点击'),
+  );
+  vi.mocked(restartMatch3DRun).mockRejectedValue(
+    new Error('未重新开始抓大鹅运行态'),
+  );
+  vi.mocked(finishMatch3DTimeUp).mockResolvedValue({
+    run: buildMockMatch3DRun('match3d-profile-time-up'),
+  });
+  vi.mocked(stopMatch3DRun).mockResolvedValue({
+    run: buildMockMatch3DRun('match3d-profile-stopped'),
   });
   vi.mocked(startLocalBigFishRuntimeRun).mockReturnValue({
     runId: 'big-fish-run-1',
@@ -2057,7 +2170,7 @@ test('logged out public detail gates big fish start before local runtime', async
   );
 
   const searchInput = await screen.findByPlaceholderText(
-    '输入 SY / CW / BF / PZ 编号',
+    '输入 SY / CW / BF / M3 / PZ 编号',
   );
   await user.type(searchInput, 'BF-NPUBLIC1');
   await user.click(screen.getByRole('button', { name: '搜索' }));
@@ -2518,7 +2631,6 @@ test('puzzle creation timeout exits busy state and shows a readable error', asyn
 
   const button = screen.getByRole('button', { name: /拼图.*创意礼物/u });
   await user.click(button);
-  await user.click(await screen.findByRole('button', { name: '生成草稿' }));
 
   await waitFor(() => {
     expect(
@@ -2527,9 +2639,7 @@ test('puzzle creation timeout exits busy state and shows a readable error', asyn
       ).length,
     ).toBeGreaterThan(0);
   });
-  expect(
-    screen.getByRole('button', { name: '生成草稿' }) as HTMLButtonElement,
-  ).toHaveProperty('disabled', false);
+  expect(button as HTMLButtonElement).toHaveProperty('disabled', false);
   expect(screen.queryByText(/正在准备拼图共创工作区/u)).toBeNull();
 });
 
@@ -2734,7 +2844,7 @@ test('formal puzzle next level uses backend run and leaderboard keeps frontend l
   render(<TestWrapper withAuth />);
 
   const searchInput = await screen.findByPlaceholderText(
-    '输入 SY / CW / BF / PZ 编号',
+    '输入 SY / CW / BF / M3 / PZ 编号',
   );
   await user.type(searchInput, 'PZ-EPUBLIC1');
   await user.click(screen.getByRole('button', { name: '搜索' }));
@@ -2807,7 +2917,7 @@ test('public code search opens a published puzzle by PZ code', async () => {
   render(<TestWrapper withAuth />);
 
   const searchInput = await screen.findByPlaceholderText(
-    '输入 SY / CW / BF / PZ 编号',
+    '输入 SY / CW / BF / M3 / PZ 编号',
   );
   await user.type(searchInput, 'PZ-EPUBLIC1');
   await user.click(screen.getByRole('button', { name: '搜索' }));
@@ -2850,7 +2960,7 @@ test('public code search opens a published big fish work by BF code', async () =
   render(<TestWrapper withAuth />);
 
   const searchInput = await screen.findByPlaceholderText(
-    '输入 SY / CW / BF / PZ 编号',
+    '输入 SY / CW / BF / M3 / PZ 编号',
   );
   await user.type(searchInput, 'BF-NPUBLIC1');
   await user.click(screen.getByRole('button', { name: '搜索' }));
@@ -2872,6 +2982,56 @@ test('public code search opens a published big fish work by BF code', async () =
   expect(getRpgEntryWorldGalleryDetailByCode).not.toHaveBeenCalled();
 });
 
+test('public code search opens a published Match3D work by M3 code and starts runtime', async () => {
+  const user = userEvent.setup();
+  const match3dWork: Match3DWorkSummary = {
+    workId: 'match3d-work-public-1',
+    profileId: 'match3d-profile-public-1',
+    ownerUserId: 'user-2',
+    sourceSessionId: 'match3d-session-public-1',
+    gameName: '水果抓大鹅',
+    themeText: '水果消除',
+    summary: '把圆形空间里的水果全部消除。',
+    tags: ['水果', '消除'],
+    coverImageSrc: null,
+    referenceImageSrc: null,
+    clearCount: 4,
+    difficulty: 5,
+    publicationStatus: 'published',
+    playCount: 3,
+    updatedAt: '2026-04-25T10:30:00.000Z',
+    publishedAt: '2026-04-25T10:30:00.000Z',
+    publishReady: true,
+  };
+
+  vi.mocked(listMatch3DGallery).mockResolvedValue({
+    items: [match3dWork],
+  });
+  vi.mocked(startMatch3DRun).mockResolvedValue({
+    run: buildMockMatch3DRun(match3dWork.profileId),
+  });
+
+  render(<TestWrapper withAuth />);
+
+  const searchInput = await screen.findByPlaceholderText(
+    '输入 SY / CW / BF / M3 / PZ 编号',
+  );
+  await user.type(searchInput, 'M3-EPUBLIC1');
+  await user.click(screen.getByRole('button', { name: '搜索' }));
+
+  expect(await screen.findByText('详情')).toBeTruthy();
+  expect(screen.getByText('水果抓大鹅')).toBeTruthy();
+  await user.click(screen.getByRole('button', { name: '启动' }));
+
+  await waitFor(() => {
+    expect(startMatch3DRun).toHaveBeenCalledWith('match3d-profile-public-1');
+  });
+  expect(
+    await screen.findByText('抓大鹅运行态：match3d-run-match3d-profile-public-1'),
+  ).toBeTruthy();
+  expect(getRpgEntryWorldGalleryDetailByCode).not.toHaveBeenCalled();
+});
+
 test('starting draft generation leaves the agent workspace and shows the generation progress view', async () => {
   const user = userEvent.setup();
 

src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx

@@ -620,7 +620,7 @@ test('mobile home search submits public work code', async () => {
   );
 
   const searchInput = screen.getByPlaceholderText(
-    '输入 SY / CW / BF / PZ 编号',
+    '输入 SY / CW / BF / M3 / PZ 编号',
   );
   await user.type(searchInput, 'PZ-PROFILE1{enter}');
 

src/components/rpg-entry/RpgEntryHomeView.tsx

@@ -70,6 +70,7 @@ import {
   formatPlatformWorkDisplayTag,
   formatPlatformWorldTime,
   isBigFishGalleryEntry,
+  isMatch3DGalleryEntry,
   isPuzzleGalleryEntry,
   type PlatformPublicGalleryCard,
   type PlatformWorldCardLike,
@@ -303,7 +304,7 @@ function PublicCodeSearchBar({
             onSubmit();
           }
         }}
-        placeholder="输入 SY / CW / BF / PZ 编号"
+        placeholder="输入 SY / CW / BF / M3 / PZ 编号"
         className="w-full min-w-0 bg-transparent text-sm text-[var(--platform-text-strong)] outline-none placeholder:text-[var(--platform-text-soft)]"
       />
       <button
@@ -1020,7 +1021,9 @@ function buildPublicGalleryCardKey(entry: PlatformPublicGalleryCard) {
     ? 'big-fish'
     : isPuzzleGalleryEntry(entry)
       ? 'puzzle'
-      : 'rpg';
+      : isMatch3DGalleryEntry(entry)
+        ? 'match3d'
+        : 'rpg';
   return `${kind}:${entry.ownerUserId}:${entry.profileId}`;
 }
 
@@ -1029,7 +1032,9 @@ function describePublicGalleryCardKind(entry: PlatformPublicGalleryCard) {
     ? '大鱼'
     : isPuzzleGalleryEntry(entry)
       ? '拼图'
-      : describePlatformThemeLabel(entry.themeMode);
+      : isMatch3DGalleryEntry(entry)
+        ? '抓鹅'
+        : describePlatformThemeLabel(entry.themeMode);
   return formatPlatformWorkDisplayTag(kind);
 }
 

src/components/rpg-entry/rpgEntryWorldPresentation.ts

@@ -1,4 +1,5 @@
 import type { BigFishWorkSummary } from '../../../packages/shared/src/contracts/bigFishWorkSummary';
+import type { Match3DWorkSummary } from '../../../packages/shared/src/contracts/match3dWorks';
 import type { PuzzleDraftLevel } from '../../../packages/shared/src/contracts/puzzleAgentDraft';
 import type { PuzzleWorkSummary } from '../../../packages/shared/src/contracts/puzzleWorkSummary';
 import type {
@@ -9,6 +10,7 @@ import { buildCustomWorldPlayableCharacters } from '../../data/characterPresets'
 import { resolveCustomWorldCampSceneImage } from '../../data/customWorldVisuals';
 import {
   buildBigFishPublicWorkCode,
+  buildMatch3DPublicWorkCode,
   buildPuzzlePublicWorkCode,
 } from '../../services/publicWorkCode';
 import type { CustomWorldProfile } from '../../types';
@@ -20,6 +22,7 @@ export type PlatformWorldCardLike =
   | CustomWorldGalleryCard
   | CustomWorldLibraryEntry<CustomWorldProfile>
   | PlatformBigFishGalleryCard
+  | PlatformMatch3DGalleryCard
   | PlatformPuzzleGalleryCard;
 
 export type PlatformPuzzleGalleryCard = {
@@ -71,9 +74,31 @@ export type PlatformBigFishGalleryCard = {
   updatedAt: string;
 };
 
+export type PlatformMatch3DGalleryCard = {
+  sourceType: 'match3d';
+  workId: string;
+  profileId: string;
+  publicWorkCode: string;
+  ownerUserId: string;
+  authorDisplayName: string;
+  worldName: string;
+  subtitle: string;
+  summaryText: string;
+  coverImageSrc: string | null;
+  themeTags: string[];
+  playCount?: number;
+  remixCount?: number;
+  likeCount?: number;
+  recentPlayCount7d?: number;
+  visibility: 'published';
+  publishedAt: string | null;
+  updatedAt: string;
+};
+
 export type PlatformPublicGalleryCard =
   | CustomWorldGalleryCard
   | PlatformBigFishGalleryCard
+  | PlatformMatch3DGalleryCard
   | PlatformPuzzleGalleryCard;
 
 export function isLibraryWorldEntry(
@@ -94,6 +119,12 @@ export function isBigFishGalleryEntry(
   return 'sourceType' in entry && entry.sourceType === 'big-fish';
 }
 
+export function isMatch3DGalleryEntry(
+  entry: PlatformWorldCardLike,
+): entry is PlatformMatch3DGalleryCard {
+  return 'sourceType' in entry && entry.sourceType === 'match3d';
+}
+
 export function mapPuzzleWorkToPlatformGalleryCard(
   work: PuzzleWorkSummary,
 ): PlatformPuzzleGalleryCard {
@@ -120,6 +151,31 @@ export function mapPuzzleWorkToPlatformGalleryCard(
   };
 }
 
+export function mapMatch3DWorkToPlatformGalleryCard(
+  work: Match3DWorkSummary,
+): PlatformMatch3DGalleryCard {
+  return {
+    sourceType: 'match3d',
+    workId: work.workId,
+    profileId: work.profileId,
+    publicWorkCode: buildMatch3DPublicWorkCode(work.profileId),
+    ownerUserId: work.ownerUserId,
+    authorDisplayName: '玩家',
+    worldName: work.gameName,
+    subtitle: '经典消除玩法',
+    summaryText: work.summary,
+    coverImageSrc: work.coverImageSrc ?? null,
+    themeTags: work.tags.length > 0 ? work.tags : [work.themeText, '抓大鹅'],
+    playCount: work.playCount ?? 0,
+    remixCount: 0,
+    likeCount: 0,
+    recentPlayCount7d: 0,
+    visibility: 'published',
+    publishedAt: work.publishedAt ?? null,
+    updatedAt: work.updatedAt,
+  };
+}
+
 export function mapBigFishWorkToPlatformGalleryCard(
   work: BigFishWorkSummary,
 ): PlatformBigFishGalleryCard {
@@ -307,6 +363,10 @@ export function buildPlatformWorldTags(entry: PlatformWorldCardLike) {
     return entry.themeTags.length > 0 ? entry.themeTags.slice(0, 3) : ['拼图'];
   }
 
+  if (isMatch3DGalleryEntry(entry)) {
+    return entry.themeTags.length > 0 ? entry.themeTags.slice(0, 3) : ['抓大鹅'];
+  }
+
   if (!isLibraryWorldEntry(entry)) {
     return [
       describePlatformThemeLabel(entry.themeMode),
@@ -381,6 +441,10 @@ export function resolvePlatformPublicWorkCode(
     return entry.publicWorkCode;
   }
 
+  if (isMatch3DGalleryEntry(entry)) {
+    return entry.publicWorkCode;
+  }
+
   return entry.publicWorkCode;
 }