建立3D生成目录化契约

新增 model3d common、text-to-model、image-to-model、multiview-to-model Rust contracts

通过 ts-rs 按目录生成 TypeScript bindings，移除依赖 barrel 的组织方式

增加 model3d contracts 定向生成脚本

package.json

@@ -41,6 +41,7 @@
     "admin-web:typecheck": "node scripts/admin-web-build.mjs typecheck",
     "admin-web:preview": "npm --prefix apps/admin-web run preview --",
     "spacetime:generate": "node scripts/generate-spacetime-bindings.mjs",
+    "contracts:model3d:generate": "cargo test --locked -p shared-contracts model3d --manifest-path server-rs/Cargo.toml",
     "spacetime:external-generation:maintain": "node scripts/spacetime-maintain-external-generation-jobs.mjs",
     "spacetime:editor-image-asset-kind:clean": "node scripts/spacetime-clean-editor-image-asset-kind.mjs",
     "spacetime:editor-canvas-layout:migrate": "node scripts/spacetime-migrate-editor-canvas-layout.mjs",

packages/shared/src/contracts/model3d/common/Model3dCompression.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dCompression = 'example';

packages/shared/src/contracts/model3d/common/Model3dExportOrientation.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dExportOrientation = '+x' | '-x' | '+y' | '-y';

packages/shared/src/contracts/model3d/common/Model3dGeometryQuality.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dGeometryQuality = 'standard' | 'detailed';

packages/shared/src/contracts/model3d/common/Model3dInputOrientation.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dInputOrientation = 'default' | 'align_image';

packages/shared/src/contracts/model3d/common/Model3dModelVersion.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dModelVersion =
+  | 'v3.1-20260211'
+  | 'v3.0-20250812'
+  | 'v2.5-20250123'
+  | 'P1-20260311'
+  | 'P2-20260801';

packages/shared/src/contracts/model3d/common/Model3dOutputFormat.ts

@@ -0,0 +1,10 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dOutputFormat =
+  | 'glb'
+  | 'gltf'
+  | 'fbx'
+  | 'obj'
+  | 'stl'
+  | 'usdz'
+  | '3mf';

packages/shared/src/contracts/model3d/common/Model3dStyle.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dStyle = 'example';

packages/shared/src/contracts/model3d/common/Model3dTaskStatus.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dTaskStatus =
+  | 'queued'
+  | 'running'
+  | 'completed'
+  | 'failed'
+  | 'cancelled'
+  | 'expired';

packages/shared/src/contracts/model3d/common/Model3dTextureAlignment.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dTextureAlignment = 'original_image' | 'geometry';

packages/shared/src/contracts/model3d/common/Model3dTextureQuality.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dTextureQuality = 'standard' | 'detailed' | 'extreme';

packages/shared/src/contracts/model3d/image-to-model/Model3dImageToModelRequest.ts

@@ -0,0 +1,32 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dCompression } from '../common/Model3dCompression';
+import type { Model3dExportOrientation } from '../common/Model3dExportOrientation';
+import type { Model3dGeometryQuality } from '../common/Model3dGeometryQuality';
+import type { Model3dInputOrientation } from '../common/Model3dInputOrientation';
+import type { Model3dModelVersion } from '../common/Model3dModelVersion';
+import type { Model3dStyle } from '../common/Model3dStyle';
+import type { Model3dTextureAlignment } from '../common/Model3dTextureAlignment';
+import type { Model3dTextureQuality } from '../common/Model3dTextureQuality';
+
+export type Model3dImageToModelRequest = {
+  input: string;
+  model: Model3dModelVersion | null;
+  enableImageAutofix: boolean | null;
+  modelSeed: number | null;
+  textureSeed: number | null;
+  texture: boolean | null;
+  pbr: boolean | null;
+  textureQuality: Model3dTextureQuality | null;
+  textureAlignment: Model3dTextureAlignment | null;
+  geometryQuality: Model3dGeometryQuality | null;
+  faceLimit: number | null;
+  autoSize: boolean | null;
+  orientation: Model3dInputOrientation | null;
+  quad: boolean | null;
+  smartLowPoly: boolean | null;
+  generateParts: boolean | null;
+  compress: Model3dCompression | null;
+  exportUv: boolean | null;
+  exportOrientation: Model3dExportOrientation | null;
+  style: Model3dStyle | null;
+};

packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewInputs.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Model3dMultiviewInputs =
+  | {
+      kind: 'views';
+      front: string;
+      left: string | null;
+      back: string | null;
+      right: string | null;
+    }
+  | { kind: 'taskId'; taskId: string };

packages/shared/src/contracts/model3d/multiview-to-model/Model3dMultiviewToModelRequest.ts

@@ -0,0 +1,30 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dCompression } from '../common/Model3dCompression';
+import type { Model3dExportOrientation } from '../common/Model3dExportOrientation';
+import type { Model3dGeometryQuality } from '../common/Model3dGeometryQuality';
+import type { Model3dInputOrientation } from '../common/Model3dInputOrientation';
+import type { Model3dModelVersion } from '../common/Model3dModelVersion';
+import type { Model3dTextureAlignment } from '../common/Model3dTextureAlignment';
+import type { Model3dTextureQuality } from '../common/Model3dTextureQuality';
+import type { Model3dMultiviewInputs } from './Model3dMultiviewInputs';
+
+export type Model3dMultiviewToModelRequest = {
+  inputs: Model3dMultiviewInputs;
+  model: Model3dModelVersion | null;
+  modelSeed: number | null;
+  textureSeed: number | null;
+  texture: boolean | null;
+  pbr: boolean | null;
+  textureQuality: Model3dTextureQuality | null;
+  geometryQuality: Model3dGeometryQuality | null;
+  textureAlignment: Model3dTextureAlignment | null;
+  faceLimit: number | null;
+  autoSize: boolean | null;
+  orientation: Model3dInputOrientation | null;
+  quad: boolean | null;
+  smartLowPoly: boolean | null;
+  generateParts: boolean | null;
+  compress: Model3dCompression | null;
+  exportUv: boolean | null;
+  exportOrientation: Model3dExportOrientation | null;
+};

packages/shared/src/contracts/model3d/text-to-model/Model3dArtifact.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dOutputFormat } from '../common/Model3dOutputFormat';
+
+export type Model3dArtifact = {
+  resourceId: string;
+  format: Model3dOutputFormat;
+  contentType: string;
+  sizeBytes: number;
+  sha256: string;
+  previewResourceId?: string | null;
+};

packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationJob.ts

@@ -0,0 +1,13 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dTaskStatus } from '../common/Model3dTaskStatus';
+import type { Model3dGenerationResult } from './Model3dGenerationResult';
+
+export type Model3dGenerationJob = {
+  operationId: string;
+  status: Model3dTaskStatus;
+  phase: string;
+  progress: number;
+  error?: string | null;
+  result?: Model3dGenerationResult | null;
+  updatedAtMicros: number;
+};

packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationResult.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dArtifact } from './Model3dArtifact';
+
+export type Model3dGenerationResult = {
+  resourceId: string;
+  assetId: string;
+  artifacts: Array<Model3dArtifact>;
+};

packages/shared/src/contracts/model3d/text-to-model/Model3dGenerationSubmission.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dTaskStatus } from '../common/Model3dTaskStatus';
+
+export type Model3dGenerationSubmission = {
+  operationId: string;
+  status: Model3dTaskStatus;
+  statusUrl: string;
+  pollAfterMs: number;
+};

packages/shared/src/contracts/model3d/text-to-model/Model3dTextToModelRequest.ts

@@ -0,0 +1,29 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Model3dCompression } from '../common/Model3dCompression';
+import type { Model3dExportOrientation } from '../common/Model3dExportOrientation';
+import type { Model3dGeometryQuality } from '../common/Model3dGeometryQuality';
+import type { Model3dModelVersion } from '../common/Model3dModelVersion';
+import type { Model3dStyle } from '../common/Model3dStyle';
+import type { Model3dTextureQuality } from '../common/Model3dTextureQuality';
+
+export type Model3dTextToModelRequest = {
+  prompt: string;
+  model: Model3dModelVersion | null;
+  negativePrompt: string | null;
+  imageSeed: number | null;
+  modelSeed: number | null;
+  textureSeed: number | null;
+  texture: boolean | null;
+  pbr: boolean | null;
+  textureQuality: Model3dTextureQuality | null;
+  geometryQuality: Model3dGeometryQuality | null;
+  faceLimit: number | null;
+  autoSize: boolean | null;
+  quad: boolean | null;
+  smartLowPoly: boolean | null;
+  generateParts: boolean | null;
+  compress: Model3dCompression | null;
+  exportUv: boolean | null;
+  exportOrientation: Model3dExportOrientation | null;
+  style: Model3dStyle | null;
+};

server-rs/crates/shared-contracts/Cargo.toml

@@ -13,3 +13,4 @@ oss-contracts = []
 serde = { workspace = true }
 serde_json = { workspace = true }
 sha2 = { workspace = true }
+ts-rs = { workspace = true }

server-rs/crates/shared-contracts/src/lib.rs

@@ -32,6 +32,7 @@ pub mod external_generation;
 pub mod game_creation_app;
 pub mod hyper3d;
 pub mod llm;
+pub mod model3d;
 #[cfg(any())]
 pub mod public_work;
 #[cfg(any())]

server-rs/crates/shared-contracts/src/model3d/common/compression.rs

@@ -0,0 +1,20 @@
+use serde::{Deserialize, Serialize};
+
+use super::MODEL3D_TS_EXPORT_DIR;
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize, ts_rs::TS)]
+#[ts(export, export_to = MODEL3D_TS_EXPORT_DIR)]
+pub enum Model3dCompression {
+    /// TODO(tripo-docs): replace this compile-time placeholder with the
+    /// official text-to-model compression enum values.
+    #[serde(rename = "example")]
+    Example,
+}
+
+impl Model3dCompression {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Example => "example",
+        }
+    }
+}

server-rs/crates/shared-contracts/src/model3d/common/export_orientation.rs

@@ -0,0 +1,27 @@
+use serde::{Deserialize, Serialize};
+
+use super::MODEL3D_TS_EXPORT_DIR;
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize, ts_rs::TS)]
+#[ts(export, export_to = MODEL3D_TS_EXPORT_DIR)]
+pub enum Model3dExportOrientation {
+    #[serde(rename = "+x")]
+    PlusX,
+    #[serde(rename = "-x")]
+    MinusX,
+    #[serde(rename = "+y")]
+    PlusY,
+    #[serde(rename = "-y")]
+    MinusY,
+}
+
+impl Model3dExportOrientation {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::PlusX => "+x",
+            Self::MinusX => "-x",
+            Self::PlusY => "+y",
+            Self::MinusY => "-y",
+        }
+    }
+}

server-rs/crates/shared-contracts/src/model3d/common/geometry_quality.rs

@@ -0,0 +1,21 @@
+use serde::{Deserialize, Serialize};
+
+use super::MODEL3D_TS_EXPORT_DIR;
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "lowercase")]
+#[derive(ts_rs::TS)]
+#[ts(export, export_to = MODEL3D_TS_EXPORT_DIR)]
+pub enum Model3dGeometryQuality {
+    Standard,
+    Detailed,
+}
+
+impl Model3dGeometryQuality {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Standard => "standard",
+            Self::Detailed => "detailed",
+        }
+    }
+}

server-rs/crates/shared-contracts/src/model3d/common/input_orientation.rs

@@ -0,0 +1,21 @@
+use serde::{Deserialize, Serialize};
+
+use super::MODEL3D_TS_EXPORT_DIR;
+
+#[derive(Clone, Copy, Debug, Deserialize, Eq, PartialEq, Serialize)]
+#[serde(rename_all = "snake_case")]
+#[derive(ts_rs::TS)]
+#[ts(export, export_to = MODEL3D_TS_EXPORT_DIR)]
+pub enum Model3dInputOrientation {
+    Default,
+    AlignImage,
+}
+
+impl Model3dInputOrientation {
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            Self::Default => "default",
+            Self::AlignImage => "align_image",
+        }
+    }
+}