1

packages/shared/src/contracts/bigFish.ts

@@ -0,0 +1,190 @@
+/**
+ * 大鱼吃小鱼玩法域前端共享契约。
+ * 字段与 server-rs/shared-contracts/src/big_fish.rs 保持 camelCase 对齐。
+ */
+export type CreateBigFishSessionRequest = {
+  seedText?: string;
+};
+
+export type SendBigFishMessageRequest = {
+  clientMessageId: string;
+  text: string;
+};
+
+export type BigFishActionId =
+  | 'big_fish_compile_draft'
+  | 'big_fish_generate_level_main_image'
+  | 'big_fish_generate_level_motion'
+  | 'big_fish_generate_stage_background'
+  | 'big_fish_publish_game';
+
+export type ExecuteBigFishActionRequest = {
+  action: BigFishActionId;
+  level?: number;
+  motionKey?: 'idle_float' | 'move_swim' | string;
+};
+
+export type SubmitBigFishInputRequest = {
+  x: number;
+  y: number;
+};
+
+export type BigFishAnchorStatus =
+  | 'confirmed'
+  | 'inferred'
+  | 'missing'
+  | 'locked'
+  | string;
+
+export type BigFishAnchorItemResponse = {
+  key: string;
+  label: string;
+  value: string;
+  status: BigFishAnchorStatus;
+};
+
+export type BigFishAnchorPackResponse = {
+  gameplayPromise: BigFishAnchorItemResponse;
+  ecologyVisualTheme: BigFishAnchorItemResponse;
+  growthLadder: BigFishAnchorItemResponse;
+  riskTempo: BigFishAnchorItemResponse;
+};
+
+export type BigFishLevelBlueprintResponse = {
+  level: number;
+  name: string;
+  oneLineFantasy: string;
+  silhouetteDirection: string;
+  sizeRatio: number;
+  visualPromptSeed: string;
+  motionPromptSeed: string;
+  mergeSourceLevel?: number | null;
+  preyWindow: number[];
+  threatWindow: number[];
+  isFinalLevel: boolean;
+};
+
+export type BigFishBackgroundBlueprintResponse = {
+  theme: string;
+  colorMood: string;
+  foregroundHints: string;
+  midgroundComposition: string;
+  backgroundDepth: string;
+  safePlayAreaHint: string;
+  spawnEdgeHint: string;
+  backgroundPromptSeed: string;
+};
+
+export type BigFishRuntimeParamsResponse = {
+  levelCount: number;
+  mergeCountPerUpgrade: number;
+  spawnTargetCount: number;
+  leaderMoveSpeed: number;
+  followerCatchUpSpeed: number;
+  offscreenCullSeconds: number;
+  preySpawnDeltaLevels: number[];
+  threatSpawnDeltaLevels: number[];
+  winLevel: number;
+};
+
+export type BigFishGameDraftResponse = {
+  title: string;
+  subtitle: string;
+  coreFun: string;
+  ecologyTheme: string;
+  levels: BigFishLevelBlueprintResponse[];
+  background: BigFishBackgroundBlueprintResponse;
+  runtimeParams: BigFishRuntimeParamsResponse;
+};
+
+export type BigFishAgentMessageResponse = {
+  id: string;
+  role: 'user' | 'assistant' | string;
+  kind: 'chat' | 'system' | 'warning' | string;
+  text: string;
+  createdAt: string;
+};
+
+export type BigFishAssetKind =
+  | 'level_main_image'
+  | 'level_motion'
+  | 'stage_background'
+  | string;
+
+export type BigFishAssetStatus = 'empty' | 'ready' | 'generating' | string;
+
+export type BigFishAssetSlotResponse = {
+  slotId: string;
+  assetKind: BigFishAssetKind;
+  level?: number | null;
+  motionKey?: string | null;
+  status: BigFishAssetStatus;
+  assetUrl?: string | null;
+  promptSnapshot: string;
+  updatedAt: string;
+};
+
+export type BigFishAssetCoverageResponse = {
+  levelMainImageReadyCount: number;
+  levelMotionReadyCount: number;
+  backgroundReady: boolean;
+  requiredLevelCount: number;
+  publishReady: boolean;
+  blockers: string[];
+};
+
+export type BigFishSessionSnapshotResponse = {
+  sessionId: string;
+  currentTurn: number;
+  progressPercent: number;
+  stage: string;
+  anchorPack: BigFishAnchorPackResponse;
+  draft?: BigFishGameDraftResponse | null;
+  assetSlots: BigFishAssetSlotResponse[];
+  assetCoverage: BigFishAssetCoverageResponse;
+  messages: BigFishAgentMessageResponse[];
+  lastAssistantReply?: string | null;
+  publishReady: boolean;
+  updatedAt: string;
+};
+
+export type BigFishSessionResponse = {
+  session: BigFishSessionSnapshotResponse;
+};
+
+export type BigFishActionResponse = {
+  session: BigFishSessionSnapshotResponse;
+};
+
+export type BigFishVector2Response = {
+  x: number;
+  y: number;
+};
+
+export type BigFishRuntimeEntityResponse = {
+  entityId: string;
+  level: number;
+  position: BigFishVector2Response;
+  radius: number;
+  offscreenSeconds: number;
+};
+
+export type BigFishRuntimeSnapshotResponse = {
+  runId: string;
+  sessionId: string;
+  status: 'running' | 'won' | 'failed' | string;
+  tick: number;
+  playerLevel: number;
+  winLevel: number;
+  leaderEntityId?: string | null;
+  ownedEntities: BigFishRuntimeEntityResponse[];
+  wildEntities: BigFishRuntimeEntityResponse[];
+  cameraCenter: BigFishVector2Response;
+  lastInput: BigFishVector2Response;
+  eventLog: string[];
+  updatedAt: string;
+};
+
+export type BigFishRunResponse = {
+  run: BigFishRuntimeSnapshotResponse;
+};

packages/shared/src/contracts/puzzleAgentActions.ts

@@ -0,0 +1,59 @@
+export type PuzzleAgentSuggestedActionType =
+  | 'request_summary'
+  | 'compile_puzzle_draft'
+  | 'generate_puzzle_images'
+  | 'publish_puzzle_work';
+
+export interface PuzzleAgentSuggestedAction {
+  id: string;
+  actionType: PuzzleAgentSuggestedActionType;
+  label: string;
+}
+
+export type PuzzleAgentActionType =
+  | 'compile_puzzle_draft'
+  | 'generate_puzzle_images'
+  | 'select_puzzle_image'
+  | 'publish_puzzle_work';
+
+export type PuzzleAgentOperationType =
+  | 'process_message'
+  | PuzzleAgentActionType;
+
+export type PuzzleAgentOperationStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed';
+
+export interface PuzzleAgentOperationRecord {
+  operationId: string;
+  type: PuzzleAgentOperationType;
+  status: PuzzleAgentOperationStatus;
+  phaseLabel: string;
+  phaseDetail: string;
+  progress: number;
+  error?: string | null;
+}
+
+export type PuzzleAgentActionRequest =
+  | { action: 'compile_puzzle_draft' }
+  | {
+      action: 'generate_puzzle_images';
+      promptText?: string | null;
+      candidateCount?: number;
+    }
+  | {
+      action: 'select_puzzle_image';
+      candidateId: string;
+    }
+  | {
+      action: 'publish_puzzle_work';
+      levelName?: string;
+      summary?: string;
+      themeTags?: string[];
+    };
+
+export interface PuzzleAgentActionResponse {
+  operation: PuzzleAgentOperationRecord;
+}

packages/shared/src/contracts/puzzleAgentDraft.ts

@@ -0,0 +1,58 @@
+import type { JsonObject } from './common';
+
+export type PuzzleAnchorStatus =
+  | 'missing'
+  | 'inferred'
+  | 'confirmed'
+  | 'locked';
+
+export interface PuzzleAnchorItem {
+  key: string;
+  label: string;
+  value: string;
+  status: PuzzleAnchorStatus;
+}
+
+export interface PuzzleAnchorPack {
+  themePromise: PuzzleAnchorItem;
+  visualSubject: PuzzleAnchorItem;
+  visualMood: PuzzleAnchorItem;
+  compositionHooks: PuzzleAnchorItem;
+  tagsAndForbidden: PuzzleAnchorItem;
+}
+
+export interface PuzzleCreatorIntent {
+  sourceMode: 'agent_chat';
+  rawMessagesSummary: string;
+  themePromise: string;
+  visualSubject: string;
+  visualMood: string[];
+  compositionHooks: string[];
+  themeTags: string[];
+  forbiddenDirectives: string[];
+}
+
+export interface PuzzleGeneratedImageCandidate {
+  candidateId: string;
+  imageSrc: string;
+  assetId: string;
+  prompt: string;
+  actualPrompt?: string | null;
+  sourceType: 'generated' | 'uploaded';
+  selected: boolean;
+}
+
+export interface PuzzleResultDraft {
+  levelName: string;
+  summary: string;
+  themeTags: string[];
+  forbiddenDirectives: string[];
+  creatorIntent: PuzzleCreatorIntent | null;
+  anchorPack: PuzzleAnchorPack;
+  candidates: PuzzleGeneratedImageCandidate[];
+  selectedCandidateId: string | null;
+  coverImageSrc: string | null;
+  coverAssetId: string | null;
+  generationStatus: 'idle' | 'generating' | 'ready';
+  metadata?: JsonObject | null;
+}

packages/shared/src/contracts/puzzleAgentSession.ts

@@ -0,0 +1,58 @@
+import type { PuzzleAgentActionResponse, PuzzleAgentSuggestedAction } from './puzzleAgentActions';
+import type { PuzzleAnchorPack, PuzzleResultDraft } from './puzzleAgentDraft';
+import type { PuzzleResultPreviewEnvelope } from './puzzleResultPreview';
+
+export type PuzzleAgentStage =
+  | 'collecting_anchors'
+  | 'draft_ready'
+  | 'image_refining'
+  | 'ready_to_publish'
+  | 'published';
+
+export type PuzzleAgentMessageRole = 'user' | 'assistant' | 'system';
+
+export type PuzzleAgentMessageKind =
+  | 'chat'
+  | 'summary'
+  | 'action_result'
+  | 'warning';
+
+export interface PuzzleAgentMessage {
+  id: string;
+  role: PuzzleAgentMessageRole;
+  kind: PuzzleAgentMessageKind;
+  text: string;
+  createdAt: string;
+}
+
+export interface PuzzleAgentSessionSnapshot {
+  sessionId: string;
+  currentTurn: number;
+  progressPercent: number;
+  stage: PuzzleAgentStage;
+  anchorPack: PuzzleAnchorPack;
+  draft: PuzzleResultDraft | null;
+  messages: PuzzleAgentMessage[];
+  lastAssistantReply: string | null;
+  publishedProfileId: string | null;
+  suggestedActions: PuzzleAgentSuggestedAction[];
+  resultPreview: PuzzleResultPreviewEnvelope | null;
+  updatedAt: string;
+}
+
+export interface CreatePuzzleAgentSessionRequest {
+  seedText?: string;
+}
+
+export interface CreatePuzzleAgentSessionResponse {
+  session: PuzzleAgentSessionSnapshot;
+}
+
+export interface SendPuzzleAgentMessageRequest {
+  clientMessageId: string;
+  text: string;
+}
+
+export interface SendPuzzleAgentMessageResponse extends PuzzleAgentActionResponse {
+  session: PuzzleAgentSessionSnapshot;
+}

packages/shared/src/contracts/puzzleResultPreview.ts

@@ -0,0 +1,21 @@
+import type { PuzzleResultDraft } from './puzzleAgentDraft';
+
+export interface PuzzleResultPreviewBlocker {
+  id: string;
+  code: string;
+  message: string;
+}
+
+export interface PuzzleResultPreviewFinding {
+  id: string;
+  severity: 'info' | 'warning' | 'blocker';
+  code: string;
+  message: string;
+}
+
+export interface PuzzleResultPreviewEnvelope {
+  draft: PuzzleResultDraft;
+  blockers: PuzzleResultPreviewBlocker[];
+  qualityFindings: PuzzleResultPreviewFinding[];
+  publishReady: boolean;
+}

packages/shared/src/contracts/puzzleRuntimeSession.ts

@@ -0,0 +1,74 @@
+export type PuzzleGridSize = 3 | 4;
+
+export interface PuzzleCellPosition {
+  row: number;
+  col: number;
+}
+
+export interface PuzzlePieceState {
+  pieceId: string;
+  correctRow: number;
+  correctCol: number;
+  currentRow: number;
+  currentCol: number;
+  mergedGroupId: string | null;
+}
+
+export interface PuzzleMergedGroupState {
+  groupId: string;
+  pieceIds: string[];
+  occupiedCells: PuzzleCellPosition[];
+}
+
+export interface PuzzleBoardSnapshot {
+  rows: number;
+  cols: number;
+  pieces: PuzzlePieceState[];
+  mergedGroups: PuzzleMergedGroupState[];
+  selectedPieceId: string | null;
+  allTilesResolved: boolean;
+}
+
+export interface PuzzleRuntimeLevelSnapshot {
+  runId: string;
+  levelIndex: number;
+  gridSize: PuzzleGridSize;
+  profileId: string;
+  levelName: string;
+  authorDisplayName: string;
+  themeTags: string[];
+  coverImageSrc: string | null;
+  board: PuzzleBoardSnapshot;
+  status: 'playing' | 'cleared';
+}
+
+export interface PuzzleRunSnapshot {
+  runId: string;
+  entryProfileId: string;
+  clearedLevelCount: number;
+  currentLevelIndex: number;
+  currentGridSize: PuzzleGridSize;
+  playedProfileIds: string[];
+  previousLevelTags: string[];
+  currentLevel: PuzzleRuntimeLevelSnapshot | null;
+  recommendedNextProfileId: string | null;
+}
+
+export interface StartPuzzleRunRequest {
+  profileId: string;
+}
+
+export interface PuzzleRunResponse {
+  run: PuzzleRunSnapshot;
+}
+
+export interface SwapPuzzlePiecesRequest {
+  firstPieceId: string;
+  secondPieceId: string;
+}
+
+export interface DragPuzzlePieceRequest {
+  pieceId: string;
+  targetRow: number;
+  targetCol: number;
+}

packages/shared/src/contracts/puzzleWorkSummary.ts

@@ -0,0 +1,39 @@
+import type { JsonObject } from './common';
+import type { PuzzleAnchorPack } from './puzzleAgentDraft';
+
+export type PuzzleWorkPublicationStatus = 'draft' | 'published';
+
+export interface PuzzleWorkSummary {
+  workId: string;
+  profileId: string;
+  ownerUserId: string;
+  sourceSessionId?: string | null;
+  authorDisplayName: string;
+  levelName: string;
+  summary: string;
+  themeTags: string[];
+  coverImageSrc: string | null;
+  coverAssetId?: string | null;
+  publicationStatus: PuzzleWorkPublicationStatus;
+  updatedAt: string;
+  publishedAt: string | null;
+  playCount: number;
+  publishReady: boolean;
+}
+
+export interface PuzzleWorkProfile extends PuzzleWorkSummary {
+  anchorPack: PuzzleAnchorPack;
+  metadata?: JsonObject | null;
+}
+
+export interface PuzzleWorksResponse {
+  items: PuzzleWorkSummary[];
+}
+
+export interface PuzzleWorkDetailResponse {
+  item: PuzzleWorkProfile;
+}
+
+export interface PuzzleWorkMutationResponse {
+  item: PuzzleWorkProfile;
+}

packages/shared/src/contracts/rpgCreationFixtures.ts

@@ -579,7 +579,7 @@ export function createRpgAgentSessionFixture(): RpgAgentSessionSnapshot {
     lockState: {
       lockedCardIds: ['world-foundation'],
     },
-    draftProfile,
+    draftProfile: draftProfile as unknown as Record<string, unknown>,
     messages: [
       {
         id: 'message-1',

packages/shared/src/index.ts

@@ -1,5 +1,6 @@
 export * from './assets/qwenSprite';
 export * from './contracts/auth';
+export type * from './contracts/bigFish';
 export * from './contracts/common';
 export type * from './contracts/customWorldAgent';
 export * from './contracts/rpgAgentActions';
@@ -9,6 +10,12 @@ export * from './contracts/rpgAgentSession';
 export * from './contracts/rpgCreationFixtures';
 export * from './contracts/rpgCreationPreview';
 export * from './contracts/rpgCreationWorkSummary';
+export * from './contracts/puzzleAgentActions';
+export * from './contracts/puzzleAgentDraft';
+export * from './contracts/puzzleAgentSession';
+export * from './contracts/puzzleResultPreview';
+export * from './contracts/puzzleRuntimeSession';
+export * from './contracts/puzzleWorkSummary';
 export * from './contracts/rpgRuntimeChat';
 export * from './contracts/rpgRuntimeQuestAssist';
 export * from './contracts/rpgRuntimeStoryAction';