1

packages/shared/src/contracts/match3dAgent.ts

@@ -2,7 +2,10 @@
  * 抓大鹅 Match3D 创作 Agent 共享契约。
  * 字段按 HTTP facade 的 camelCase DTO 命名，后端领域层 snake_case 字段由 facade 映射。
  */
-import type { Match3DGeneratedItemAsset } from './match3dWorks';
+import type {
+  Match3DGeneratedBackgroundAsset,
+  Match3DGeneratedItemAsset,
+} from './match3dWorks';
 
 export type Match3DCreationStage =
   | 'collecting'
@@ -34,6 +37,7 @@ export interface CreateMatch3DAgentSessionRequest {
   assetStyleId?: string | null;
   assetStyleLabel?: string | null;
   assetStylePrompt?: string | null;
+  generateClickSound?: boolean;
 }
 
 export type CreateMatch3DSessionRequest = CreateMatch3DAgentSessionRequest;
@@ -55,6 +59,7 @@ export interface ExecuteMatch3DAgentActionRequest {
   coverImageSrc?: string | null;
   clearCount?: number;
   difficulty?: number;
+  generateClickSound?: boolean;
 }
 
 export type ExecuteMatch3DActionRequest = ExecuteMatch3DAgentActionRequest;
@@ -80,6 +85,7 @@ export interface Match3DCreatorConfig {
   assetStyleId?: string | null;
   assetStyleLabel?: string | null;
   assetStylePrompt?: string | null;
+  generateClickSound?: boolean;
 }
 
 export interface Match3DResultDraft {
@@ -96,6 +102,10 @@ export interface Match3DResultDraft {
   totalItemCount?: number;
   publishReady?: boolean;
   blockers?: string[];
+  backgroundPrompt?: string | null;
+  backgroundImageSrc?: string | null;
+  backgroundImageObjectKey?: string | null;
+  generatedBackgroundAsset?: Match3DGeneratedBackgroundAsset | null;
   generatedItemAssets?: Match3DGeneratedItemAsset[];
 }
 

packages/shared/src/contracts/match3dRuntime.ts

@@ -46,6 +46,7 @@ export type Match3DClickConfirmStatus =
 
 export interface StartMatch3DRunRequest {
   profileId: string;
+  itemTypeCountOverride?: number | null;
 }
 
 export interface Match3DClickItemRequest {

packages/shared/src/contracts/match3dWorks.ts

@@ -14,18 +14,39 @@ export type Match3DGeneratedItemAssetStatus =
   | 'failed'
   | string;
 
+export interface Match3DGeneratedBackgroundAsset {
+  prompt: string;
+  imageSrc?: string | null;
+  imageObjectKey?: string | null;
+  status: string;
+  error?: string | null;
+}
+
+export interface Match3DGeneratedItemImageView {
+  viewId: string;
+  viewIndex: number;
+  imageSrc?: string | null;
+  imageObjectKey?: string | null;
+}
+
 export interface Match3DGeneratedItemAsset {
   itemId: string;
   itemName: string;
   imageSrc?: string | null;
   imageObjectKey?: string | null;
+  imageViews?: Match3DGeneratedItemImageView[];
   modelSrc?: string | null;
   modelObjectKey?: string | null;
   modelFileName?: string | null;
   taskUuid?: string | null;
   subscriptionKey?: string | null;
+  soundPrompt?: string | null;
+  backgroundMusicTitle?: string | null;
+  backgroundMusicStyle?: string | null;
+  backgroundMusicPrompt?: string | null;
   backgroundMusic?: CreationAudioAsset | null;
   clickSound?: CreationAudioAsset | null;
+  backgroundAsset?: Match3DGeneratedBackgroundAsset | null;
   status: Match3DGeneratedItemAssetStatus;
   error?: string | null;
 }
@@ -34,6 +55,52 @@ export interface PutMatch3DAudioAssetsRequest {
   generatedItemAssets: Match3DGeneratedItemAsset[];
 }
 
+export interface PersistMatch3DGeneratedModelRequest {
+  itemId: string;
+  itemName: string;
+  sourceUrl: string;
+  fileName?: string | null;
+  taskUuid?: string | null;
+  subscriptionKey?: string | null;
+}
+
+export interface PersistMatch3DGeneratedModelResponse {
+  asset: Match3DGeneratedItemAsset;
+}
+
+export interface GenerateMatch3DCoverImageRequest {
+  prompt: string;
+  referenceImageSrc?: string | null;
+}
+
+export interface GenerateMatch3DCoverImageResponse {
+  item: Match3DWorkProfile;
+  coverImageSrc: string;
+  coverImageObjectKey: string;
+  prompt: string;
+}
+
+export interface GenerateMatch3DBackgroundImageRequest {
+  prompt: string;
+}
+
+export interface GenerateMatch3DBackgroundImageResponse {
+  item: Match3DWorkProfile;
+  backgroundImageSrc: string;
+  backgroundImageObjectKey: string;
+  generatedBackgroundAsset: Match3DGeneratedBackgroundAsset;
+  prompt: string;
+}
+
+export interface GenerateMatch3DItemAssetsRequest {
+  itemNames: string[];
+}
+
+export interface GenerateMatch3DItemAssetsResponse {
+  item: Match3DWorkProfile;
+  generatedItemAssets: Match3DGeneratedItemAsset[];
+}
+
 export interface PutMatch3DWorkRequest {
   gameName: string;
   themeText?: string;
@@ -72,6 +139,10 @@ export interface Match3DWorkSummary {
   updatedAt: string;
   publishedAt?: string | null;
   publishReady: boolean;
+  backgroundPrompt?: string | null;
+  backgroundImageSrc?: string | null;
+  backgroundImageObjectKey?: string | null;
+  generatedBackgroundAsset?: Match3DGeneratedBackgroundAsset | null;
   generatedItemAssets?: Match3DGeneratedItemAsset[];
 }
 

packages/shared/src/contracts/puzzleAgentActions.ts

@@ -4,6 +4,7 @@ export type PuzzleAgentSuggestedActionType =
   | 'request_summary'
   | 'compile_puzzle_draft'
   | 'generate_puzzle_images'
+  | 'generate_puzzle_ui_background'
   | 'generate_puzzle_tags'
   | 'publish_puzzle_work';
 
@@ -17,6 +18,7 @@ export type PuzzleAgentActionType =
   | 'save_puzzle_form_draft'
   | 'compile_puzzle_draft'
   | 'generate_puzzle_images'
+  | 'generate_puzzle_ui_background'
   | 'generate_puzzle_tags'
   | 'select_puzzle_image'
   | 'publish_puzzle_work';
@@ -77,6 +79,16 @@ export type PuzzleAgentActionRequest =
       themeTags?: string[];
       levelsJson?: string;
     }
+  | {
+      action: 'generate_puzzle_ui_background';
+      levelId?: string | null;
+      promptText: string;
+      workTitle?: string;
+      workDescription?: string;
+      summary?: string;
+      themeTags?: string[];
+      levelsJson?: string;
+    }
   | {
       action: 'generate_puzzle_tags';
       workTitle: string;

packages/shared/src/contracts/puzzleAgentDraft.ts

@@ -48,6 +48,9 @@ export interface PuzzleDraftLevel {
   levelName: string;
   pictureDescription: string;
   pictureReference?: string | null;
+  uiBackgroundPrompt?: string | null;
+  uiBackgroundImageSrc?: string | null;
+  uiBackgroundImageObjectKey?: string | null;
   backgroundMusic?: CreationAudioAsset | null;
   candidates: PuzzleGeneratedImageCandidate[];
   selectedCandidateId: string | null;

packages/shared/src/contracts/puzzleRuntimeSession.ts

@@ -1,3 +1,5 @@
+import type { CreationAudioAsset } from './creationAudio';
+
 export type PuzzleGridSize = 3 | 4 | 5 | 6 | 7;
 
 export interface PuzzleCellPosition {
@@ -55,6 +57,8 @@ export interface PuzzleRuntimeLevelSnapshot {
   authorDisplayName: string;
   themeTags: string[];
   coverImageSrc: string | null;
+  uiBackgroundImageSrc?: string | null;
+  backgroundMusic?: CreationAudioAsset | null;
   board: PuzzleBoardSnapshot;
   status: PuzzleRuntimeLevelStatus;
   startedAtMs: number;