Merge remote-tracking branch 'origin/master'

# Conflicts: # docs/technical/README.md # server-rs/crates/spacetime-client/src/module_bindings/mod.rs
2026-05-01 01:14:04 +08:00
parent 29cf68a31a 38b5db553e
commit e18f09069c
601 changed files with 19836 additions and 4468 deletions
--- a/packages/shared/src/contracts/match3dAgent.ts
+++ b/packages/shared/src/contracts/match3dAgent.ts
@@ -0,0 +1,126 @@
+/**
+ * 抓大鹅 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 {
+  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;
+}