@forgeax-extension/character-3d 0.1.2

package/server/providers/visvise.ts

@@ -0,0 +1,329 @@
+// VISVISE via LiteLLM GatewayClient. Same 3D key as Meshy/Hunyuan.
+//
+// C1 2026-08-14 body clues (docs/evidence/gateway-rodin-visvise-probe-2026-08-14.json):
+//   visvise-3d / visvise-3d-low → require `algorithm_model` (no public enum; do not invent)
+//   visvise-3d-mid → `image_url` (image-only)
+//   pose/rig/skin/text-motion/video-motion → `input_model_url` must be a VISVISE COS URL
+//   no views model on catalog
+// C7: call visvise-rigging only; do not chain visvise-skinning unless live proves needed.
+
+import type { ProviderResult, ProviderResultFile } from '../../shared/catalog';
+import type { FileFormat, FileRole, GenerationMode } from '../../shared/manifest';
+import type { VisviseEnv } from '../env';
+import { audit } from '../audit';
+import { RateGuard } from '../rate-guard';
+import { extractGatewayUrls } from './gateway-data';
+import { GatewayClient, type FetchLike } from './gateway-client';
+import { defaultVisviseAlgorithmModel } from '../../shared/provider-params';
+import {
+  VISVISE_GATEWAY_MODELS,
+  visviseGenerateModel,
+  type VisviseQuality,
+} from './gateway-models';
+
+const GATEWAY_SUBMIT = '/v1/3d/generations';
+const GATEWAY_POLL = '/v1/3d/tasks';
+
+export type VisviseGenerateMode = 'text' | 'image';
+
+export interface VisviseGenerateInput {
+  mode: VisviseGenerateMode | 'views';
+  prompt?: string;
+  imageUrl?: string;
+  quality?: VisviseQuality;
+  /** Only send when the caller pasted a list_algorithm_model value. Do not invent. */
+  algorithmModel?: string;
+  enableAPose?: boolean;
+  faceType?: 1 | 2;
+  faceNum?: number;
+  enablePbr?: boolean;
+}
+
+export interface VisviseUrlInput {
+  inputModelUrl: string;
+  prompt?: string;
+  videoUrl?: string;
+}
+
+export type DownloadLike = (url: string) => Promise<Uint8Array>;
+
+/** Map LiteLLM/Weaver 400s we have live evidence for. Unknown strings stay raw. */
+export function explainVisviseGatewayError(message: string): string | null {
+  if (message.includes('模型url路径前缀错误')) {
+    return 'VISVISE 拒绝了这张图的地址：网关要求图片已经在该账号的 VISVISE COS（weaver/user-…）下。工作台上传的是 ForgeaX COS，过不了前缀校验。只改算法名解决不了。等网关适配器代传，或从官网贴已上传的 VISVISE COS 地址。';
+  }
+  if (message.includes('algorithm_model is required')) {
+    return '网关要求填写 algorithm_model（算法模型名）。';
+  }
+  if (message.includes('image-to-3d-mid requires')) {
+    return 'VISVISE 中档不是单图降质量：网关要正/背/左/右四张图，或先有 360 / 拆分资产。本轮工作台没有四视图入口。';
+  }
+  if (message.includes('输入视图不能为空')) {
+    return '网关没收到它能用的输入视图（官方 input_view 键会被适配器丢掉，只认 image_url）。';
+  }
+  return null;
+}
+
+function rewriteVisviseError(error: unknown): unknown {
+  if (!(error instanceof Error)) return error;
+  const explained = explainVisviseGatewayError(error.message);
+  if (!explained) return error;
+  const extra = error as Error & { code?: string; status?: number; httpStatus?: number; body?: string };
+  return Object.assign(new Error(explained), {
+    code: extra.code,
+    status: extra.status,
+    httpStatus: extra.httpStatus,
+    body: extra.body,
+    cause: error,
+  });
+}
+
+export interface VisviseProviderDeps {
+  env: VisviseEnv;
+  slug: string;
+  fetchImpl?: FetchLike;
+  downloadImpl?: DownloadLike;
+  rateGuard?: RateGuard;
+  sleep?: (ms: number) => Promise<void>;
+}
+
+const DATA_TYPE_TO_FILE: Record<string, { role: FileRole; format: FileFormat }> = {
+  glb: { role: 'source_mesh', format: 'glb' },
+  fbx: { role: 'source_mesh', format: 'fbx' },
+  obj: { role: 'source_mesh', format: 'obj' },
+};
+
+export function buildVisviseGeneratePayload(input: VisviseGenerateInput): Record<string, unknown> {
+  if (input.mode === 'views') {
+    throw Object.assign(new Error('VISVISE views is not on the LiteLLM catalog; use text or image'), {
+      code: 'views_not_supported',
+    });
+  }
+  const mode: VisviseGenerateMode = input.mode;
+  const model = visviseGenerateModel(mode, input.quality);
+  const payload: Record<string, unknown> = { model };
+  payload.algorithm_model = input.algorithmModel?.trim() || defaultVisviseAlgorithmModel(input.quality);
+  if (typeof input.enableAPose === 'boolean') payload.enable_a_pose = input.enableAPose;
+  if (input.faceType === 1 || input.faceType === 2) payload.face_type = input.faceType;
+  const highOnly = input.quality !== 'mid' && input.quality !== 'low';
+  if (highOnly && typeof input.faceNum === 'number' && input.faceNum > 0) payload.face_num = input.faceNum;
+  if (highOnly && typeof input.enablePbr === 'boolean') payload.enable_pbr = input.enablePbr;
+  if (mode === 'text') payload.prompt = input.prompt ?? '';
+  else payload.image_url = input.imageUrl ?? '';
+  return payload;
+}
+
+/** Map filtered providerParams onto a generate input. Unset keys stay omitted. */
+export function visviseInputFromFiltered(
+  base: Pick<VisviseGenerateInput, 'mode' | 'prompt' | 'imageUrl'>,
+  filtered: Record<string, string | number | boolean>,
+): VisviseGenerateInput {
+  const input: VisviseGenerateInput = { ...base };
+  const q = filtered.quality;
+  if (q === 'standard' || q === 'mid' || q === 'low') input.quality = q;
+  if (typeof filtered.algorithm_model === 'string' && filtered.algorithm_model.trim()) {
+    input.algorithmModel = filtered.algorithm_model.trim();
+  }
+  if (typeof filtered.enable_a_pose === 'boolean') input.enableAPose = filtered.enable_a_pose;
+  if (filtered.face_type === '1' || filtered.face_type === 1) input.faceType = 1;
+  if (filtered.face_type === '2' || filtered.face_type === 2) input.faceType = 2;
+  if (typeof filtered.face_num === 'number') input.faceNum = filtered.face_num;
+  if (typeof filtered.enable_pbr === 'boolean') input.enablePbr = filtered.enable_pbr;
+  return input;
+}
+
+export function buildVisviseUrlPayload(
+  model: string,
+  input: VisviseUrlInput,
+  extra?: Record<string, unknown>,
+): Record<string, unknown> {
+  return {
+    model,
+    input_model_url: input.inputModelUrl,
+    ...extra,
+  };
+}
+
+/** Prefer the VISVISE COS URL from generate/rig. Do not invent a ForgeaX COS stand-in. */
+export function visviseInputUrl(
+  refs: { meshUrl?: string | null; rigUrl?: string | null } | undefined,
+  stage: 'rig' | 'motion',
+): string | null {
+  const mesh = refs?.meshUrl?.trim() || null;
+  const rig = refs?.rigUrl?.trim() || null;
+  if (stage === 'motion') return rig ?? mesh;
+  return mesh;
+}
+
+export class VisviseProvider {
+  private readonly env: VisviseEnv;
+  private readonly slug: string;
+  private readonly fetchImpl: FetchLike;
+  private readonly downloadImpl: DownloadLike;
+  private readonly rateGuard: RateGuard;
+  private readonly sleep: (ms: number) => Promise<void>;
+
+  constructor(deps: VisviseProviderDeps) {
+    this.env = deps.env;
+    this.slug = deps.slug;
+    this.fetchImpl = deps.fetchImpl ?? ((url, init) => fetch(url, init));
+    this.downloadImpl =
+      deps.downloadImpl ??
+      (async (url) => this.gateway().download(url, { format: urlFormat(url), image: isImageUrl(url) }));
+    this.rateGuard = deps.rateGuard ?? new RateGuard(this.env.rateLimitPerMin);
+    this.sleep = deps.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  }
+
+  async generate(input: VisviseGenerateInput): Promise<ProviderResult> {
+    const payload = buildVisviseGeneratePayload(input);
+    const out = await this.submitDownload(payload, input.mode === 'views' ? 'image' : input.mode, 'generate');
+    if (!out.files.some((f) => f.role === 'source_mesh' && f.format === 'glb')) {
+      throw Object.assign(new Error('visvise generate succeeded without a GLB mesh'), {
+        code: 'provider_no_output',
+      });
+    }
+    return {
+      provider: 'visvise',
+      mode: input.mode as GenerationMode,
+      providerMode: 'real',
+      sourceJobId: out.sourceJobId,
+      prompt: input.prompt ?? null,
+      files: out.files,
+      visviseRefs: { meshUrl: out.remoteUrls.glb ?? null, rigUrl: null },
+    };
+  }
+
+  async pose(input: VisviseUrlInput): Promise<{ sourceJobId: string | null; imageData: Uint8Array; sourceUrl: string }> {
+    this.rateGuard.check();
+    const submitted = await this.gateway().post(
+      GATEWAY_SUBMIT,
+      buildVisviseUrlPayload(VISVISE_GATEWAY_MODELS.pose, input),
+    );
+    const resp = await this.resolve(submitted, 'pose');
+    const urls = extractGatewayUrls(resp);
+    const url = urls.__thumbnail ?? Object.values(urls).find((u) => /\.(png|jpe?g|webp)(?:\?|$)/i.test(u));
+    if (!url) {
+      throw Object.assign(new Error('visvise pose returned no image url'), { code: 'provider_no_output' });
+    }
+    return {
+      sourceJobId: typeof resp.id === 'string' ? resp.id : null,
+      imageData: await this.downloadImpl(url),
+      sourceUrl: url,
+    };
+  }
+
+  async autoRig(input: VisviseUrlInput): Promise<{
+    sourceJobId: string | null;
+    sourceUrl: string | null;
+    files: Array<{ format: 'glb' | 'fbx'; data: Uint8Array }>;
+  }> {
+    const out = await this.submitDownload(
+      buildVisviseUrlPayload(VISVISE_GATEWAY_MODELS.autoRig, input),
+      'image',
+      'auto-rig',
+    );
+    const files = out.files
+      .filter((f) => f.role === 'source_mesh' && (f.format === 'glb' || f.format === 'fbx'))
+      .map((f) => ({ format: f.format as 'glb' | 'fbx', data: f.data }));
+    if (!files.some((f) => f.format === 'glb')) {
+      throw Object.assign(new Error('visvise rigging returned no GLB'), { code: 'provider_no_output' });
+    }
+    return { sourceJobId: out.sourceJobId, sourceUrl: out.remoteUrls.glb ?? null, files };
+  }
+
+  async textMotion(input: VisviseUrlInput): Promise<{ sourceJobId: string | null; files: Array<{ format: 'glb' | 'fbx'; data: Uint8Array }> }> {
+    if (!input.prompt?.trim()) {
+      throw Object.assign(new Error('visvise text-motion requires prompt'), { code: 'invalid_motion_input' });
+    }
+    const out = await this.submitDownload(
+      buildVisviseUrlPayload(VISVISE_GATEWAY_MODELS.textMotion, input, { prompt: input.prompt.trim() }),
+      'image',
+      'text-motion',
+    );
+    return {
+      sourceJobId: out.sourceJobId,
+      files: out.files
+        .filter((f) => f.role === 'source_mesh' && (f.format === 'glb' || f.format === 'fbx'))
+        .map((f) => ({ format: f.format as 'glb' | 'fbx', data: f.data })),
+    };
+  }
+
+  async videoMotion(input: VisviseUrlInput): Promise<{ sourceJobId: string | null; files: Array<{ format: 'glb' | 'fbx'; data: Uint8Array }> }> {
+    if (!input.videoUrl?.trim()) {
+      throw Object.assign(new Error('visvise video-motion requires videoUrl'), { code: 'invalid_motion_input' });
+    }
+    const out = await this.submitDownload(
+      buildVisviseUrlPayload(VISVISE_GATEWAY_MODELS.videoMotion, input, { video_url: input.videoUrl.trim() }),
+      'image',
+      'video-motion',
+    );
+    return {
+      sourceJobId: out.sourceJobId,
+      files: out.files
+        .filter((f) => f.role === 'source_mesh' && (f.format === 'glb' || f.format === 'fbx'))
+        .map((f) => ({ format: f.format as 'glb' | 'fbx', data: f.data })),
+    };
+  }
+
+  private async submitDownload(
+    payload: Record<string, unknown>,
+    mode: GenerationMode,
+    label: string,
+  ): Promise<{ sourceJobId: string | null; files: ProviderResultFile[]; remoteUrls: Record<string, string> }> {
+    this.rateGuard.check();
+    let submitted: Record<string, unknown>;
+    try {
+      submitted = await this.gateway().post(GATEWAY_SUBMIT, payload);
+    } catch (error) {
+      throw rewriteVisviseError(error);
+    }
+    const resp = await this.resolve(submitted, label);
+    const sourceJobId = typeof resp.id === 'string' ? resp.id : typeof submitted.id === 'string' ? submitted.id : null;
+    await audit(this.slug, {
+      ts: new Date().toISOString(),
+      provider: 'visvise',
+      mode,
+      event: 'submit',
+      sourceJobId,
+      detail: label,
+    });
+    const urls = extractGatewayUrls(resp);
+    const files: ProviderResultFile[] = [];
+    for (const [key, mapping] of Object.entries(DATA_TYPE_TO_FILE)) {
+      const url = urls[key];
+      if (!url) continue;
+      files.push({ role: mapping.role, format: mapping.format, data: await this.downloadImpl(url) });
+    }
+    if (urls.__thumbnail) {
+      files.push({ role: 'preview_image', format: 'png', data: await this.downloadImpl(urls.__thumbnail) });
+    }
+    return { sourceJobId, files, remoteUrls: urls };
+  }
+
+  private async resolve(submitted: Record<string, unknown>, label: string): Promise<Record<string, unknown>> {
+    const status = String(submitted.status ?? '').toLowerCase();
+    if (status === 'succeeded' || extractGatewayUrls(submitted).glb) return submitted;
+    const taskId = typeof submitted.id === 'string' ? submitted.id : null;
+    if (!taskId) {
+      throw Object.assign(new Error(`visvise ${label} returned no task id`), { code: 'provider_no_task' });
+    }
+    return this.gateway().pollTask(`${GATEWAY_POLL}/${taskId}`, {
+      timeoutMs: this.env.pollTimeoutMs,
+      intervalMs: this.env.pollIntervalMs,
+      label: `visvise ${label}`,
+    });
+  }
+
+  private gateway(): GatewayClient {
+    return new GatewayClient({ env: this.env, fetchImpl: this.fetchImpl, sleep: this.sleep });
+  }
+}
+
+function urlFormat(url: string): string | undefined {
+  const path = url.split('?', 1)[0] ?? url;
+  return path.split('.').pop()?.toLowerCase();
+}
+
+function isImageUrl(url: string): boolean {
+  return /\.(png|jpe?g|webp|gif)(?:\?|$)/i.test(url);
+}

package/server/rate-guard.ts

@@ -0,0 +1,29 @@
+// RateGuard — client-side submit guard. Sliding 60s window; over-limit throws
+// QuotaProtectionError before any quotaed call is made. Mirrors the lab's
+// submit-only protection. In-process state; not a distributed limiter.
+
+export class QuotaProtectionError extends Error {
+  readonly code = 'quota_protection';
+  constructor(perMin: number) {
+    super(`rate limit: at most ${perMin} submits per minute`);
+    this.name = 'QuotaProtectionError';
+  }
+}
+
+export class RateGuard {
+  private readonly stamps: number[] = [];
+
+  constructor(private readonly perMin: number) {}
+
+  // Call immediately before a quotaed submit. Throws if the window is full.
+  check(now = Date.now()): void {
+    const windowStart = now - 60_000;
+    while (this.stamps.length && this.stamps[0] < windowStart) {
+      this.stamps.shift();
+    }
+    if (this.stamps.length >= this.perMin) {
+      throw new QuotaProtectionError(this.perMin);
+    }
+    this.stamps.push(now);
+  }
+}