Merge remote-tracking branch 'origin/master' into codex/ddd

# Conflicts: # docs/technical/README.md # docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md # docs/technical/SPACETIMEDB_TABLE_CATALOG.md # scripts/generate-spacetime-bindings.mjs # server-rs/crates/api-server/src/app.rs # server-rs/crates/api-server/src/assets.rs # server-rs/crates/api-server/src/big_fish.rs # server-rs/crates/api-server/src/custom_world_ai.rs # server-rs/crates/api-server/src/llm.rs # server-rs/crates/api-server/src/main.rs # server-rs/crates/api-server/src/puzzle.rs # server-rs/crates/api-server/src/runtime_profile.rs # server-rs/crates/api-server/src/runtime_story/compat/ai.rs # server-rs/crates/api-server/src/runtime_story/compat/npc_actions.rs # server-rs/crates/api-server/src/runtime_story/compat/presentation.rs # server-rs/crates/api-server/src/runtime_story/compat/tests.rs # server-rs/crates/api-server/src/state.rs # server-rs/crates/module-auth/src/lib.rs # server-rs/crates/module-big-fish/src/lib.rs # server-rs/crates/module-custom-world/src/lib.rs # server-rs/crates/module-puzzle/src/lib.rs # server-rs/crates/module-runtime/src/lib.rs # server-rs/crates/spacetime-client/src/big_fish.rs # server-rs/crates/spacetime-client/src/lib.rs # server-rs/crates/spacetime-client/src/mapper.rs # server-rs/crates/spacetime-client/src/module_bindings/admin_disable_profile_redeem_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/admin_upsert_profile_redeem_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/advance_puzzle_next_level_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/append_ai_text_chunk_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/apply_chapter_progression_ledger_entry_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/attach_ai_result_reference_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/authorize_database_migration_operator_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/begin_story_session_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/big_fish_runtime_run_type.rs # server-rs/crates/spacetime-client/src/module_bindings/bind_asset_object_to_entity_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/cancel_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/clear_platform_browse_history_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/compile_big_fish_draft_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/compile_custom_world_published_profile_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/compile_puzzle_agent_draft_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/complete_ai_stage_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/complete_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/confirm_asset_object_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/consume_profile_wallet_points_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/continue_story_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_battle_state_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_big_fish_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_custom_world_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_profile_recharge_order_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/create_puzzle_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_big_fish_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_custom_world_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_puzzle_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/delete_runtime_snapshot_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/drag_puzzle_piece_or_group_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/execute_custom_world_agent_action_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/export_auth_store_snapshot_from_tables_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/export_database_migration_to_file_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/fail_ai_task_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/finalize_big_fish_agent_message_turn_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/finalize_custom_world_agent_message_turn_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/finalize_puzzle_agent_message_turn_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/generate_big_fish_asset_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_auth_store_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_battle_state_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_big_fish_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_chapter_progression_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_agent_card_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_agent_operation_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_gallery_detail_by_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_gallery_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_custom_world_library_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_player_progression_or_default_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_dashboard_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_play_stats_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_recharge_center_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_profile_referral_invite_center_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_agent_session_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_gallery_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_run_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_puzzle_work_detail_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_runtime_inventory_state_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_runtime_setting_or_default_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_runtime_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/get_story_session_state_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/grant_player_progression_experience_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/import_auth_store_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/import_database_migration_from_file_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/import_database_migration_incremental_from_file_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_asset_history_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_big_fish_works_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_custom_world_gallery_entries_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_custom_world_profiles_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_custom_world_works_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_platform_browse_history_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_profile_save_archives_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_profile_wallet_ledger_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_puzzle_gallery_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/list_puzzle_works_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/mod.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_big_fish_game_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_custom_world_world_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/publish_puzzle_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/record_big_fish_play_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/redeem_profile_referral_invite_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/redeem_profile_reward_code_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/refund_profile_wallet_points_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_combat_action_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_npc_battle_interaction_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_npc_interaction_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_npc_social_action_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resolve_treasure_interaction_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/resume_profile_save_archive_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/revoke_database_migration_operator_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/save_puzzle_generated_images_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/select_puzzle_cover_image_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/start_puzzle_run_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_big_fish_message_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_custom_world_agent_message_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_puzzle_agent_message_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/submit_puzzle_leaderboard_entry_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/swap_puzzle_pieces_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/unpublish_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/update_puzzle_work_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_auth_store_snapshot_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_chapter_progression_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_custom_world_agent_operation_progress_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_custom_world_profile_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_npc_state_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_platform_browse_history_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_runtime_setting_and_return_procedure.rs # server-rs/crates/spacetime-client/src/module_bindings/upsert_runtime_snapshot_and_return_procedure.rs # server-rs/crates/spacetime-module/src/auth/procedures.rs # server-rs/crates/spacetime-module/src/custom_world/mod.rs # server-rs/crates/spacetime-module/src/lib.rs # server-rs/crates/spacetime-module/src/migration.rs # server-rs/crates/spacetime-module/src/puzzle.rs # server-rs/crates/spacetime-module/src/runtime/profile.rs # src/components/platform-entry/PlatformEntryFlowShellImpl.tsx # src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx # src/services/aiService.ts # src/services/puzzle-runtime/puzzleRuntimeClient.ts
2026-05-02 03:35:59 +08:00
parent 9d9913095d fb6fb6e9f5
commit 8f4ca9abfa
513 changed files with 52813 additions and 6013 deletions
--- a/packages/shared/src/contracts/auth.ts
+++ b/packages/shared/src/contracts/auth.ts
@@ -6,16 +6,19 @@ export type AuthUser = {
  publicUserCode: string;
  username: string;
  displayName: string;
+  avatarUrl: string | null;
  phoneNumberMasked: string | null;
  loginMethod: AuthLoginMethod;
  bindingStatus: AuthBindingStatus;
  wechatBound: boolean;
+  createdAt: string;
 };

 export type PublicUserSummary = {
  id: string;
  publicUserCode: string;
  displayName: string;
+  avatarUrl: string | null;
 };

 export type PublicUserSearchResponse = {
@@ -41,6 +44,15 @@ export type AuthPasswordChangeResponse = {
  user: AuthUser;
 };

+export type AuthProfileUpdateRequest = {
+  displayName?: string;
+  avatarDataUrl?: string;
+};
+
+export type AuthProfileUpdateResponse = {
+  user: AuthUser;
+};
+
 export type AuthPasswordResetRequest = {
  phone: string;
  code: string;
@@ -54,7 +66,7 @@ export type AuthPasswordResetResponse = {

 export type AuthPhoneSendCodeRequest = {
  phone: string;
-  scene?: 'login' | 'bind_phone' | 'change_phone';
+  scene?: 'login' | 'bind_phone' | 'change_phone' | 'reset_password';
  captchaChallengeId?: string;
  captchaAnswer?: string;
 };
@@ -69,11 +81,23 @@ export type AuthPhoneSendCodeResponse = {
 export type AuthPhoneLoginRequest = {
  phone: string;
  code: string;
+  inviteCode?: string;
 };

 export type AuthPhoneLoginResponse = {
  token: string;
  user: AuthUser;
+  created: boolean;
+  referral: AuthPhoneLoginReferral | null;
+};
+
+export type AuthPhoneLoginReferral = {
+  ok: boolean;
+  message: string | null;
+  inviteeRewardGranted: boolean;
+  inviterRewardGranted: boolean;
+  inviteeBalanceAfter: number | null;
+  inviterBalanceAfter: number | null;
 };

 export type AuthMeResponse = {
--- a/packages/shared/src/contracts/bigFishWorkSummary.ts
+++ b/packages/shared/src/contracts/bigFishWorkSummary.ts
@@ -4,18 +4,23 @@ export interface BigFishWorkSummary {
  workId: string;
  sourceSessionId: string;
  ownerUserId: string;
+  authorDisplayName: string;
  title: string;
  subtitle: string;
  summary: string;
  coverImageSrc: string | null;
  status: BigFishWorkStatus;
  updatedAt: string;
+  publishedAt?: string | null;
  publishReady: boolean;
  levelCount: number;
  levelMainImageReadyCount: number;
  levelMotionReadyCount: number;
  backgroundReady: boolean;
  playCount?: number;
+  remixCount?: number;
+  likeCount?: number;
+  recentPlayCount7d?: number;
 }

 export interface BigFishWorksResponse {
--- a/packages/shared/src/contracts/match3dAgent.ts
+++ b/packages/shared/src/contracts/match3dAgent.ts
@@ -0,0 +1,127 @@
+/**
+ * 抓大鹅 Match3D 创作 Agent 共享契约。
+ * 字段按 HTTP facade 的 camelCase DTO 命名，后端领域层 snake_case 字段由 facade 映射。
+ */
+export type Match3DCreationStage =
+  | 'collecting'
+  | 'collecting_config'
+  | 'ready_to_compile'
+  | 'draft_ready'
+  | 'draft_compiled'
+  | 'ready_to_publish'
+  | 'published'
+  | string;
+
+export type Match3DAgentMessageRole = 'user' | 'assistant' | 'system' | string;
+
+export type Match3DAgentMessageKind =
+  | 'chat'
+  | 'summary'
+  | 'action_result'
+  | 'warning'
+  | string;
+
+export type Match3DAnchorStatus = 'confirmed' | 'missing' | 'inferred' | 'locked' | string;
+
+export interface CreateMatch3DAgentSessionRequest {
+  seedText?: string;
+  themeText?: string;
+  referenceImageSrc?: string | null;
+  clearCount?: number;
+  difficulty?: number;
+}
+
+export type CreateMatch3DSessionRequest = CreateMatch3DAgentSessionRequest;
+
+export interface SendMatch3DAgentMessageRequest {
+  clientMessageId: string;
+  text: string;
+  quickFillRequested?: boolean;
+  referenceImageSrc?: string | null;
+}
+
+export type SendMatch3DMessageRequest = SendMatch3DAgentMessageRequest;
+
+export interface ExecuteMatch3DAgentActionRequest {
+  action: string;
+  gameName?: string;
+  summary?: string;
+  tags?: string[];
+  coverImageSrc?: string | null;
+  clearCount?: number;
+  difficulty?: number;
+}
+
+export type ExecuteMatch3DActionRequest = ExecuteMatch3DAgentActionRequest;
+
+export interface Match3DAnchorItemResponse {
+  key: string;
+  label: string;
+  value: string;
+  status: Match3DAnchorStatus;
+}
+
+export interface Match3DAnchorPackResponse {
+  theme: Match3DAnchorItemResponse;
+  clearCount: Match3DAnchorItemResponse;
+  difficulty: Match3DAnchorItemResponse;
+}
+
+export interface Match3DCreatorConfig {
+  themeText: string;
+  referenceImageSrc?: string | null;
+  clearCount: number;
+  difficulty: number;
+}
+
+export interface Match3DResultDraft {
+  profileId: string;
+  gameName: string;
+  themeText: string;
+  summaryText?: string;
+  summary?: string;
+  tags: string[];
+  coverImageSrc?: string | null;
+  referenceImageSrc?: string | null;
+  clearCount: number;
+  difficulty: number;
+  totalItemCount?: number;
+  publishReady?: boolean;
+  blockers?: string[];
+}
+
+export interface Match3DAgentMessage {
+  id: string;
+  role: Match3DAgentMessageRole;
+  kind: Match3DAgentMessageKind;
+  text: string;
+  createdAt: string;
+}
+
+export type Match3DAgentMessageResponse = Match3DAgentMessage;
+
+export interface Match3DAgentSessionSnapshot {
+  sessionId: string;
+  currentTurn: number;
+  progressPercent: number;
+  stage: Match3DCreationStage;
+  anchorPack: Match3DAnchorPackResponse;
+  config?: Match3DCreatorConfig | null;
+  draft?: Match3DResultDraft | null;
+  messages: Match3DAgentMessage[];
+  lastAssistantReply?: string | null;
+  publishedProfileId?: string | null;
+  updatedAt: string;
+}
+
+export interface Match3DAgentSessionResponse {
+  session: Match3DAgentSessionSnapshot;
+}
+
+export type Match3DSessionResponse = Match3DAgentSessionResponse;
+
+export interface Match3DAgentActionResponse {
+  session: Match3DAgentSessionSnapshot;
+}
+
+export type Match3DActionResponse = Match3DAgentActionResponse;
--- a/packages/shared/src/contracts/match3dRuntime.ts
+++ b/packages/shared/src/contracts/match3dRuntime.ts
@@ -0,0 +1,129 @@
+/**
+ * 抓大鹅 Match3D 运行态共享契约。
+ * 前端可以使用 Flying 做即时表现；后端权威快照只应返回 InBoard、InTray、Cleared。
+ */
+export type Match3DRunStatus =
+  | 'running'
+  | 'won'
+  | 'failed'
+  | 'stopped'
+  | 'Running'
+  | 'Won'
+  | 'Failed'
+  | 'Stopped'
+  | string;
+export type Match3DItemState =
+  | 'in_board'
+  | 'in_tray'
+  | 'cleared'
+  | 'InBoard'
+  | 'Flying'
+  | 'InTray'
+  | 'Cleared'
+  | string;
+export type Match3DFailureReason =
+  | 'time_up'
+  | 'tray_full'
+  | 'TimeUp'
+  | 'TrayFull'
+  | string;
+export type Match3DClickRejectReason =
+  | 'run_not_active'
+  | 'snapshot_version_mismatch'
+  | 'item_not_found'
+  | 'item_not_in_board'
+  | 'item_not_clickable'
+  | 'tray_full'
+  | string;
+
+export type Match3DClickConfirmStatus =
+  | 'Accepted'
+  | 'RejectedNotClickable'
+  | 'RejectedAlreadyMoved'
+  | 'RejectedTrayFull'
+  | 'VersionConflict'
+  | 'RunFinished';
+
+export interface StartMatch3DRunRequest {
+  profileId: string;
+}
+
+export interface Match3DClickItemRequest {
+  runId?: string;
+  itemInstanceId: string;
+  clientActionId?: string;
+  snapshotVersion?: number;
+  clientSnapshotVersion: number;
+  clientEventId: string;
+  clickedAtMs: number;
+}
+
+export type ClickMatch3DItemRequest = Match3DClickItemRequest;
+
+export interface StopMatch3DRunRequest {
+  clientActionId: string;
+}
+
+export interface Match3DItemSnapshot {
+  itemInstanceId: string;
+  itemTypeId: string;
+  visualKey: string;
+  x: number;
+  y: number;
+  radius: number;
+  layer: number;
+  state: Match3DItemState;
+  clickable: boolean;
+  traySlotIndex?: number | null;
+}
+
+export interface Match3DTraySlot {
+  slotIndex: number;
+  itemInstanceId?: string | null;
+  itemTypeId?: string | null;
+  visualKey?: string | null;
+}
+
+export interface Match3DRunSnapshot {
+  runId: string;
+  profileId: string;
+  ownerUserId?: string;
+  status: Match3DRunStatus;
+  snapshotVersion: number;
+  startedAtMs: number;
+  durationLimitMs: number;
+  serverNowMs?: number;
+  remainingMs: number;
+  clearCount: number;
+  totalItemCount: number;
+  clearedItemCount: number;
+  boardVersion?: number;
+  items: Match3DItemSnapshot[];
+  traySlots: Match3DTraySlot[];
+  failureReason?: Match3DFailureReason | null;
+  lastConfirmedActionId?: string | null;
+}
+
+export interface Match3DClickConfirmation {
+  accepted: boolean;
+  rejectReason?: Match3DClickRejectReason | null;
+  enteredSlotIndex?: number | null;
+  clearedItemInstanceIds: string[];
+  run: Match3DRunSnapshot;
+}
+
+export interface Match3DClickItemResult {
+  status: Match3DClickConfirmStatus;
+  run: Match3DRunSnapshot;
+  acceptedItemInstanceId?: string;
+  clearedItemInstanceIds: string[];
+  failureReason?: Match3DFailureReason | null;
+}
+
+export interface Match3DRunResponse {
+  run: Match3DRunSnapshot;
+}
+
+export interface Match3DClickResponse {
+  confirmation: Match3DClickConfirmation;
+}
--- a/packages/shared/src/contracts/match3dWorks.ts
+++ b/packages/shared/src/contracts/match3dWorks.ts
@@ -0,0 +1,50 @@
+/**
+ * 抓大鹅 Match3D 作品读写共享契约。
+ * 首版作品发布必须补齐游戏名称、标签、封面、题材、消除次数和难度。
+ */
+export type Match3DWorkPublicationStatus = 'draft' | 'published' | string;
+
+export interface PutMatch3DWorkRequest {
+  gameName: string;
+  themeText?: string;
+  summary: string;
+  tags: string[];
+  coverImageSrc?: string | null;
+  referenceImageSrc?: string | null;
+  clearCount: number;
+  difficulty: number;
+}
+
+export interface Match3DWorkSummary {
+  workId: string;
+  profileId: string;
+  ownerUserId: string;
+  sourceSessionId?: string | null;
+  gameName: string;
+  themeText: string;
+  summary: string;
+  tags: string[];
+  coverImageSrc?: string | null;
+  referenceImageSrc?: string | null;
+  clearCount: number;
+  difficulty: number;
+  publicationStatus: Match3DWorkPublicationStatus;
+  playCount: number;
+  updatedAt: string;
+  publishedAt?: string | null;
+  publishReady: boolean;
+}
+
+export interface Match3DWorkProfile extends Match3DWorkSummary {}
+
+export interface Match3DWorksResponse {
+  items: Match3DWorkSummary[];
+}
+
+export interface Match3DWorkDetailResponse {
+  item: Match3DWorkProfile;
+}
+
+export interface Match3DWorkMutationResponse {
+  item: Match3DWorkProfile;
+}
--- a/packages/shared/src/contracts/puzzleAgentActions.ts
+++ b/packages/shared/src/contracts/puzzleAgentActions.ts
@@ -13,6 +13,7 @@ export interface PuzzleAgentSuggestedAction {
 }

 export type PuzzleAgentActionType =
+  | 'save_puzzle_form_draft'
  | 'compile_puzzle_draft'
  | 'generate_puzzle_images'
  | 'select_puzzle_image'
@@ -39,22 +40,43 @@ export interface PuzzleAgentOperationRecord {
 }

 export type PuzzleAgentActionRequest =
-  | { action: 'compile_puzzle_draft' }
  | {
-      action: 'generate_puzzle_images';
+      action: 'save_puzzle_form_draft';
      promptText?: string | null;
+      workTitle?: string;
+      workDescription?: string;
+      pictureDescription?: string;
+    }
+  | {
+      action: 'compile_puzzle_draft';
+      promptText?: string | null;
+      workTitle?: string;
+      workDescription?: string;
+      pictureDescription?: string;
      referenceImageSrc?: string | null;
      candidateCount?: number;
    }
+  | {
+      action: 'generate_puzzle_images';
+      levelId?: string | null;
+      promptText?: string | null;
+      referenceImageSrc?: string | null;
+      candidateCount?: number;
+      levelsJson?: string;
+    }
  | {
      action: 'select_puzzle_image';
+      levelId?: string | null;
      candidateId: string;
    }
  | {
      action: 'publish_puzzle_work';
+      workTitle?: string;
+      workDescription?: string;
      levelName?: string;
      summary?: string;
      themeTags?: string[];
+      levelsJson?: string;
    };

 /**
--- a/packages/shared/src/contracts/puzzleAgentDraft.ts
+++ b/packages/shared/src/contracts/puzzleAgentDraft.ts
@@ -22,7 +22,7 @@ export interface PuzzleAnchorPack {
 }

 export interface PuzzleCreatorIntent {
-  sourceMode: 'agent_chat';
+  sourceMode: 'agent_chat' | 'form';
  rawMessagesSummary: string;
  themePromise: string;
  visualSubject: string;
@@ -42,7 +42,20 @@ export interface PuzzleGeneratedImageCandidate {
  selected: boolean;
 }

+export interface PuzzleDraftLevel {
+  levelId: string;
+  levelName: string;
+  pictureDescription: string;
+  candidates: PuzzleGeneratedImageCandidate[];
+  selectedCandidateId: string | null;
+  coverImageSrc: string | null;
+  coverAssetId: string | null;
+  generationStatus: 'idle' | 'generating' | 'ready';
+}
+
 export interface PuzzleResultDraft {
+  workTitle?: string;
+  workDescription?: string;
  levelName: string;
  summary: string;
  themeTags: string[];
@@ -54,5 +67,11 @@ export interface PuzzleResultDraft {
  coverImageSrc: string | null;
  coverAssetId: string | null;
  generationStatus: 'idle' | 'generating' | 'ready';
+  levels?: PuzzleDraftLevel[];
+  formDraft?: {
+    workTitle?: string;
+    workDescription?: string;
+    pictureDescription?: string;
+  } | null;
  metadata?: JsonObject | null;
 }
--- a/packages/shared/src/contracts/puzzleAgentSession.ts
+++ b/packages/shared/src/contracts/puzzleAgentSession.ts
@@ -27,6 +27,7 @@ export interface PuzzleAgentMessage {

 export interface PuzzleAgentSessionSnapshot {
  sessionId: string;
+  seedText?: string;
  currentTurn: number;
  progressPercent: number;
  stage: PuzzleAgentStage;
@@ -42,6 +43,10 @@ export interface PuzzleAgentSessionSnapshot {

 export interface CreatePuzzleAgentSessionRequest {
  seedText?: string;
+  workTitle?: string;
+  workDescription?: string;
+  pictureDescription?: string;
+  referenceImageSrc?: string | null;
 }

 export interface CreatePuzzleAgentSessionResponse {
--- a/packages/shared/src/contracts/puzzleRuntimeSession.ts
+++ b/packages/shared/src/contracts/puzzleRuntimeSession.ts
@@ -1,4 +1,4 @@
-export type PuzzleGridSize = 3 | 4;
+export type PuzzleGridSize = 3 | 4 | 5 | 6 | 7;

 export interface PuzzleCellPosition {
  row: number;
@@ -27,6 +27,14 @@ export interface PuzzleLeaderboardEntry {
  isCurrentPlayer?: boolean;
 }

+export type PuzzleRuntimeLevelStatus = 'playing' | 'cleared' | 'failed';
+
+export type PuzzleRuntimePropKind =
+  | 'hint'
+  | 'reference'
+  | 'freezeTime'
+  | 'extendTime';
+
 export interface PuzzleBoardSnapshot {
  rows: number;
  cols: number;
@@ -39,6 +47,7 @@ export interface PuzzleBoardSnapshot {
 export interface PuzzleRuntimeLevelSnapshot {
  runId: string;
  levelIndex: number;
+  levelId: string | null;
  gridSize: PuzzleGridSize;
  profileId: string;
  levelName: string;
@@ -46,13 +55,31 @@ export interface PuzzleRuntimeLevelSnapshot {
  themeTags: string[];
  coverImageSrc: string | null;
  board: PuzzleBoardSnapshot;
-  status: 'playing' | 'cleared';
+  status: PuzzleRuntimeLevelStatus;
  startedAtMs: number;
  clearedAtMs: number | null;
  elapsedMs: number | null;
+  timeLimitMs: number;
+  remainingMs: number;
+  pausedAccumulatedMs: number;
+  pauseStartedAtMs: number | null;
+  freezeAccumulatedMs: number;
+  freezeStartedAtMs: number | null;
+  freezeUntilMs: number | null;
  leaderboardEntries: PuzzleLeaderboardEntry[];
 }

+export type PuzzleNextLevelMode = 'sameWork' | 'similarWorks' | 'none';
+
+export interface PuzzleRecommendedNextWork {
+  profileId: string;
+  levelName: string;
+  authorDisplayName: string;
+  themeTags: string[];
+  coverImageSrc: string | null;
+  similarityScore: number;
+}
+
 export interface PuzzleRunSnapshot {
  runId: string;
  entryProfileId: string;
@@ -63,11 +90,16 @@ export interface PuzzleRunSnapshot {
  previousLevelTags: string[];
  currentLevel: PuzzleRuntimeLevelSnapshot | null;
  recommendedNextProfileId: string | null;
+  nextLevelMode?: PuzzleNextLevelMode;
+  nextLevelProfileId?: string | null;
+  nextLevelId?: string | null;
+  recommendedNextWorks?: PuzzleRecommendedNextWork[];
  leaderboardEntries: PuzzleLeaderboardEntry[];
 }

 export interface StartPuzzleRunRequest {
  profileId: string;
+  levelId?: string | null;
 }

 export interface PuzzleRunResponse {
@@ -91,3 +123,11 @@ export interface DragPuzzlePieceRequest {
  targetRow: number;
  targetCol: number;
 }
+
+export interface UsePuzzleRuntimePropRequest {
+  propKind: PuzzleRuntimePropKind;
+}
+
+export interface UpdatePuzzleRuntimePauseRequest {
+  paused: boolean;
+}
--- a/packages/shared/src/contracts/puzzleWorkSummary.ts
+++ b/packages/shared/src/contracts/puzzleWorkSummary.ts
@@ -1,5 +1,5 @@
 import type { JsonObject } from './common';
-import type { PuzzleAnchorPack } from './puzzleAgentDraft';
+import type { PuzzleAnchorPack, PuzzleDraftLevel } from './puzzleAgentDraft';

 export type PuzzleWorkPublicationStatus = 'draft' | 'published';

@@ -9,6 +9,8 @@ export interface PuzzleWorkSummary {
  ownerUserId: string;
  sourceSessionId?: string | null;
  authorDisplayName: string;
+  workTitle?: string;
+  workDescription?: string;
  levelName: string;
  summary: string;
  themeTags: string[];
@@ -17,8 +19,16 @@ export interface PuzzleWorkSummary {
  publicationStatus: PuzzleWorkPublicationStatus;
  updatedAt: string;
  publishedAt: string | null;
-  playCount: number;
+  playCount?: number;
+  remixCount?: number;
+  likeCount?: number;
+  recentPlayCount7d?: number;
+  pointIncentiveTotalHalfPoints?: number;
+  pointIncentiveClaimedPoints?: number;
+  pointIncentiveTotalPoints?: number;
+  pointIncentiveClaimablePoints?: number;
  publishReady: boolean;
+  levels?: PuzzleDraftLevel[];
 }

 export interface PuzzleWorkProfile extends PuzzleWorkSummary {
--- a/packages/shared/src/contracts/rpgCreationFixtures.ts
+++ b/packages/shared/src/contracts/rpgCreationFixtures.ts
@@ -1,7 +1,3 @@
-import type {
-  CustomWorldLibraryEntry,
-  CustomWorldProfileRecord,
-} from './runtime';
 import type { RpgAgentSupportedAction } from './rpgAgentActions';
 import type { RpgCreationAnchorContent } from './rpgAgentAnchors';
 import type {
@@ -15,6 +11,10 @@ import type {
  ListRpgCreationWorksResponse,
  RpgCreationWorkSummary,
 } from './rpgCreationWorkSummary';
+import type {
+  CustomWorldLibraryEntry,
+  CustomWorldProfileRecord,
+} from './runtime';

 const RPG_CREATION_FIXTURE_SESSION_ID = 'rpg-session-fixture';
 const RPG_CREATION_FIXTURE_PROFILE_ID = 'rpg-profile-fixture';
@@ -661,6 +661,7 @@ export function createRpgWorldLibraryEntryFixture(): CustomWorldLibraryEntry<Cus
    landmarkCount: Array.isArray(profile.landmarks)
      ? profile.landmarks.length
      : 0,
+    likeCount: 0,
  } satisfies CustomWorldLibraryEntry<CustomWorldProfileRecord>);
 }

--- a/packages/shared/src/contracts/rpgRuntimeChat.ts
+++ b/packages/shared/src/contracts/rpgRuntimeChat.ts
@@ -3,6 +3,7 @@
 * 将角色聊天、NPC 对话与轻量 story 请求载荷从旧 story.ts 中独立出来。
 */
 import type { JsonObject } from './common';
+import type { SavedGameSnapshotInput } from './runtime';

 export type NpcChatTurnLimitReason = 'negative_affinity';

@@ -46,8 +47,15 @@ export type CharacterChatReplyRequest<
  TContext = unknown,
  TConversationTurn = unknown,
  TTargetStatus = unknown,
+  TSnapshotGameState = unknown,
+  TSnapshotCurrentStory = unknown,
 > = {
  sessionId?: string;
+  snapshot?: SavedGameSnapshotInput<
+    TSnapshotGameState,
+    string,
+    TSnapshotCurrentStory
+  >;
  worldType?: string;
  playerCharacter?: TCharacter;
  targetCharacter: TCharacter;
@@ -65,8 +73,15 @@ export type CharacterChatSuggestionsRequest<
  TContext = unknown,
  TConversationTurn = unknown,
  TTargetStatus = unknown,
+  TSnapshotGameState = unknown,
+  TSnapshotCurrentStory = unknown,
 > = {
  sessionId?: string;
+  snapshot?: SavedGameSnapshotInput<
+    TSnapshotGameState,
+    string,
+    TSnapshotCurrentStory
+  >;
  worldType?: string;
  playerCharacter?: TCharacter;
  targetCharacter: TCharacter;
@@ -83,8 +98,15 @@ export type CharacterChatSummaryRequest<
  TContext = unknown,
  TConversationTurn = unknown,
  TTargetStatus = unknown,
+  TSnapshotGameState = unknown,
+  TSnapshotCurrentStory = unknown,
 > = {
  sessionId?: string;
+  snapshot?: SavedGameSnapshotInput<
+    TSnapshotGameState,
+    string,
+    TSnapshotCurrentStory
+  >;
  worldType?: string;
  playerCharacter?: TCharacter;
  targetCharacter: TCharacter;
@@ -101,8 +123,15 @@ export type NpcChatDialogueRequest<
  TMonster = unknown,
  TStoryMoment = unknown,
  TContext = unknown,
+  TSnapshotGameState = unknown,
+  TSnapshotCurrentStory = unknown,
 > = {
  sessionId?: string;
+  snapshot?: SavedGameSnapshotInput<
+    TSnapshotGameState,
+    string,
+    TSnapshotCurrentStory
+  >;
  worldType?: string;
  character?: TCharacter;
  encounter: TEncounter;
@@ -126,8 +155,15 @@ export type NpcChatTurnRequest<
  TQuestOfferState = unknown,
  TQuestOfferEncounter = unknown,
  TChatDirective = NpcChatTurnDirective,
+  TSnapshotGameState = unknown,
+  TSnapshotCurrentStory = unknown,
 > = {
  sessionId?: string;
+  snapshot?: SavedGameSnapshotInput<
+    TSnapshotGameState,
+    string,
+    TSnapshotCurrentStory
+  >;
  worldType?: string;
  character?: TCharacter;
  player?: TCharacter;
@@ -175,8 +211,15 @@ export type NpcRecruitDialogueRequest<
  TMonster = unknown,
  TStoryMoment = unknown,
  TContext = unknown,
+  TSnapshotGameState = unknown,
+  TSnapshotCurrentStory = unknown,
 > = {
  sessionId?: string;
+  snapshot?: SavedGameSnapshotInput<
+    TSnapshotGameState,
+    string,
+    TSnapshotCurrentStory
+  >;
  worldType?: string;
  character?: TCharacter;
  encounter: TEncounter;
--- a/packages/shared/src/contracts/runtime.ts
+++ b/packages/shared/src/contracts/runtime.ts
@@ -59,12 +59,14 @@ export type ProfileWalletLedgerEntry = {
  balanceAfter: number;
  sourceType:
    | 'snapshot_sync'
+    | 'new_user_registration_reward'
    | 'invite_inviter_reward'
    | 'invite_invitee_reward'
    | 'points_recharge'
    | 'asset_operation_consume'
    | 'asset_operation_refund'
-    | 'redeem_code_reward';
+    | 'redeem_code_reward'
+    | 'puzzle_author_incentive_claim';
  createdAt: string;
 };

@@ -148,12 +150,20 @@ export type ProfileReferralInviteCenterResponse = {
  todayInviterRewardCount: number;
  todayInviterRewardRemaining: number;
  rewardPoints: number;
+  invitedUsers: ProfileReferralInvitedUser[];
  hasRedeemedCode: boolean;
  boundInviterUserId: string | null;
  boundAt: string | null;
  updatedAt: string;
 };

+export type ProfileReferralInvitedUser = {
+  userId: string;
+  displayName: string;
+  avatarUrl: string | null;
+  boundAt: string;
+};
+
 export type RedeemProfileReferralInviteCodeRequest = {
  inviteCode: string;
 };
@@ -176,6 +186,19 @@ export type RedeemProfileRewardCodeResponse = {
  ledgerEntry: ProfileWalletLedgerEntry;
 };

+export type AdminUpsertProfileInviteCodeRequest = {
+  inviteCode: string;
+  metadata?: Record<string, unknown> | null;
+};
+
+export type ProfileInviteCodeAdminResponse = {
+  userId: string;
+  inviteCode: string;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt: string;
+};
+
 export type ProfilePlayedWorkSummary = {
  worldKey: string;
  ownerUserId: string | null;
@@ -249,6 +272,10 @@ export type CustomWorldLibraryEntry<TProfile = CustomWorldProfileRecord> = {
  themeMode: CustomWorldThemeMode;
  playableNpcCount: number;
  landmarkCount: number;
+  playCount?: number;
+  remixCount?: number;
+  likeCount?: number;
+  recentPlayCount7d?: number;
 };

 export type CustomWorldGalleryCard = Omit<
--- a/packages/shared/src/index.ts
+++ b/packages/shared/src/index.ts
@@ -4,6 +4,15 @@ export type * from './contracts/bigFish';
 export * from './contracts/common';
 export type * from './contracts/creationAgentDocumentInput';
 export type * from './contracts/customWorldAgent';
+export * from './contracts/match3dAgent';
+export * from './contracts/match3dRuntime';
+export * from './contracts/match3dWorks';
+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/rpgAgentActions';
 export * from './contracts/rpgAgentAnchors';
 export * from './contracts/rpgAgentDraft';
@@ -12,12 +21,6 @@ export * from './contracts/rpgCreationFixtures';
 export * from './contracts/rpgCreationPreview';
 export * from './contracts/rpgCreationResultView';
 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';