Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

18.3 KB
Raw Blame
import {
  MODEL_ACCESS_MEDIA_CAPABILITIES,
  type MediaCapability,
  type ModelAccessParseResult,
} from '@cindy/model-providers';

export const MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION = 1 as const;
export const MODEL_ACCESS_INVOCATION_GUIDE_PATH = '/api/model-access/invocation-guide' as const;
export const MODEL_ACCESS_INVOCATION_GUIDES_PATH = '/api/model-access/invocation-guides' as const;

export type MediaResultKind = 'image' | 'video' | 'audio';
export type MediaRequestBodyEncoding = 'json' | 'multipart';

export interface MediaResultExtractor {
  path: string[];
  encoding: 'url' | 'base64';
  kind: MediaResultKind;
  mediaType?: string;
  allowedUrlHosts?: string[];
}

export interface MediaHttpRequestGuide {
  method: 'POST';
  path: string;
  headers?: Record<string, string>;
  /** Defaults to JSON for persisted/older schemaVersion 1 Guides. */
  bodyEncoding?: MediaRequestBodyEncoding;
  bodyModelPath: string[];
  multipartFiles?: MediaMultipartFileGuide[];
  timeoutMs: number;
  maxRequestBytes: number;
  maxResponseBytes: number;
}

export interface MediaMultipartFileGuide {
  bodyField: string;
  formField: string;
  kind: MediaResultKind;
  maxItems: number;
}

export interface MediaSyncResponseGuide {
  mode: 'sync';
  media: MediaResultExtractor[];
}

export interface MediaAsyncPollGuide {
  method: 'GET' | 'POST';
  path: string;
  headers?: Record<string, string>;
  bodyTaskIdPath?: string[];
  statusPath: string[];
  successValues: string[];
  failureValues: string[];
  recommendedIntervalMs: number;
  timeoutMs: number;
  maxResponseBytes: number;
  media: MediaResultExtractor[];
}

export interface MediaAsyncResponseGuide {
  mode: 'async';
  taskIdPath: string[];
  poll: MediaAsyncPollGuide;
}

export interface MediaInvocationOperationGuide {
  capability: MediaCapability;
  request: MediaHttpRequestGuide;
  response: MediaSyncResponseGuide | MediaAsyncResponseGuide;
  instructions: string;
  exampleBody: Record<string, unknown>;
  inputSchema: Record<string, unknown>;
  officialDocs: string;
}

export interface MediaInvocationGuide {
  schemaVersion: typeof MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION;
  guideId: string;
  revision: string;
  connection: { providerId: string };
  operations: MediaInvocationOperationGuide[];
}

export interface ResolvedMediaInvocationGuide {
  modelId: string;
  guide: MediaInvocationGuide;
}

/** Persisted snapshot after `prepare` selects one operation from the Server Guide. */
export type PreparedMediaInvocationGuide = Omit<MediaInvocationGuide, 'operations'> &
  Pick<ResolvedMediaInvocationGuide, 'modelId'> &
  MediaInvocationOperationGuide;

type PlainObject = Record<string, unknown>;

const FORBIDDEN_HEADERS = new Set([
  'authorization',
  'cookie',
  'host',
  'content-length',
  'content-type',
  'proxy-authorization',
  'proxy-authenticate',
  'transfer-encoding',
  'connection',
  'trailer',
  'upgrade',
  'te',
]);
const GUIDE_FIELDS = [
  'schemaVersion',
  'guideId',
  'revision',
  'connection',
  'operations',
] as const;
const RESOLVED_GUIDE_FIELDS = ['modelId', 'guide'] as const;
const OPERATION_FIELDS = [
  'capability',
  'request',
  'response',
  'instructions',
  'exampleBody',
  'inputSchema',
  'officialDocs',
] as const;
const PREPARED_GUIDE_FIELDS = [
  'schemaVersion',
  'guideId',
  'modelId',
  'revision',
  'connection',
  ...OPERATION_FIELDS,
] as const;

function ok<T>(value: T): ModelAccessParseResult<T> {
  return { ok: true, value };
}

function fail<T>(error: string): ModelAccessParseResult<T> {
  return { ok: false, error };
}

function isPlainObject(value: unknown): value is PlainObject {
  return typeof value === 'object' && value !== null && !Array.isArray(value);
}

function unknownField(value: PlainObject, allowed: readonly string[], path: string): string | null {
  const names = new Set(allowed);
  const field = Object.keys(value).find((candidate) => !names.has(candidate));
  return field ? `${path}.${field} is not allowed` : null;
}

function boundedString(value: unknown, max: number): value is string {
  return typeof value === 'string' && value.length > 0 && value.length <= max;
}

function objectPathError(value: unknown, path: string): string | null {
  if (
    !Array.isArray(value) ||
    value.length === 0 ||
    value.length > 24 ||
    value.some(
      (segment) =>
        !boundedString(segment, 128) ||
        ['__proto__', 'prototype', 'constructor'].includes(segment),
    )
  ) {
    return `${path} must be a non-empty bounded string path`;
  }
  return null;
}

function relativePathError(value: unknown, path: string, allowTaskId: boolean): string | null {
  const containsControlCharacter =
    typeof value === 'string' &&
    [...value].some((character) => {
      const code = character.charCodeAt(0);
      return code <= 0x1f || code === 0x7f;
    });
  if (
    !boundedString(value, 2_048) ||
    !value.startsWith('/') ||
    value.startsWith('//') ||
    value.includes('://') ||
    value.includes('\\') ||
    containsControlCharacter
  ) {
    return `${path} must be a relative HTTP path`;
  }
  if (!allowTaskId && value.includes('{taskId}')) return `${path} cannot contain {taskId}`;
  if (/\{(?!taskId\})/.test(value)) return `${path} contains an unsupported template`;
  return null;
}

function positiveIntegerError(
  value: unknown,
  path: string,
  min: number,
  max: number,
): string | null {
  return !Number.isInteger(value) || (value as number) < min || (value as number) > max
    ? `${path} must be an integer between ${min} and ${max}`
    : null;
}

function headersError(value: unknown, path: string): string | null {
  if (value === undefined) return null;
  if (!isPlainObject(value) || Object.keys(value).length > 16) {
    return `${path} must be an object with at most 16 fields`;
  }
  for (const [name, headerValue] of Object.entries(value)) {
    if (!/^[A-Za-z0-9-]{1,64}$/.test(name) || FORBIDDEN_HEADERS.has(name.toLowerCase())) {
      return `${path}.${name} is not an allowed fixed header`;
    }
    if (typeof headerValue !== 'string' || headerValue.length > 1_024 || /[\r\n]/.test(headerValue)) {
      return `${path}.${name} must be a bounded string`;
    }
  }
  return null;
}

function extractorError(value: unknown, path: string): string | null {
  if (!isPlainObject(value)) return `${path} must be an object`;
  let error = unknownField(
    value,
    ['path', 'encoding', 'kind', 'mediaType', 'allowedUrlHosts'],
    path,
  );
  if (error) return error;
  error = objectPathError(value.path, `${path}.path`);
  if (error) return error;
  if (value.encoding !== 'url' && value.encoding !== 'base64') {
    return `${path}.encoding must be url or base64`;
  }
  if (value.kind !== 'image' && value.kind !== 'video' && value.kind !== 'audio') {
    return `${path}.kind must be image, video or audio`;
  }
  if (value.mediaType !== undefined && !boundedString(value.mediaType, 128)) {
    return `${path}.mediaType must be a bounded string when present`;
  }
  if (value.encoding === 'url') {
    if (
      !Array.isArray(value.allowedUrlHosts) ||
      value.allowedUrlHosts.length === 0 ||
      value.allowedUrlHosts.length > 16 ||
      value.allowedUrlHosts.some(
        (host) =>
          typeof host !== 'string' ||
          !/^[a-z0-9.-]{1,253}$/i.test(host) ||
          !host.includes('.') ||
          /^\d+(?:\.\d+){3}$/.test(host) ||
          host.startsWith('.') ||
          host.endsWith('.') ||
          host.includes('..') ||
          host.toLowerCase().endsWith('.local'),
      )
    ) {
      return `${path}.allowedUrlHosts must contain trusted DNS suffixes`;
    }
  } else if (value.allowedUrlHosts !== undefined) {
    return `${path}.allowedUrlHosts is only valid for URL results`;
  }
  return null;
}

function mediaListError(value: unknown, path: string): string | null {
  if (!Array.isArray(value) || value.length === 0 || value.length > 16) {
    return `${path} must be a non-empty array with at most 16 entries`;
  }
  for (const [index, extractor] of value.entries()) {
    const error = extractorError(extractor, `${path}[${index}]`);
    if (error) return error;
  }
  return null;
}

function multipartFilesError(value: unknown, path: string): string | null {
  if (!Array.isArray(value) || value.length === 0 || value.length > 16) {
    return `${path} must be a non-empty array with at most 16 entries`;
  }
  const bodyFields = new Set<string>();
  for (const [index, file] of value.entries()) {
    const filePath = `${path}[${index}]`;
    if (!isPlainObject(file)) return `${filePath} must be an object`;
    let error = unknownField(file, ['bodyField', 'formField', 'kind', 'maxItems'], filePath);
    if (error) return error;
    if (!boundedString(file.bodyField, 128) || !/^[A-Za-z0-9_.-]+$/.test(file.bodyField)) {
      return `${filePath}.bodyField must be a safe bounded string`;
    }
    if (
      !boundedString(file.formField, 128) ||
      !/^[A-Za-z0-9_.-]+$/.test(file.formField.replaceAll('[', '').replaceAll(']', ''))
    ) {
      return `${filePath}.formField must be a bounded string`;
    }
    if (file.kind !== 'image' && file.kind !== 'video' && file.kind !== 'audio') {
      return `${filePath}.kind must be image, video or audio`;
    }
    error = positiveIntegerError(file.maxItems, `${filePath}.maxItems`, 1, 16);
    if (error) return error;
    if (bodyFields.has(file.bodyField)) return `${path} must not repeat bodyField`;
    bodyFields.add(file.bodyField);
  }
  return null;
}

function requestError(value: unknown, path: string): string | null {
  if (!isPlainObject(value)) return `${path} must be an object`;
  let error = unknownField(
    value,
    [
      'method',
      'path',
      'headers',
      'bodyEncoding',
      'bodyModelPath',
      'multipartFiles',
      'timeoutMs',
      'maxRequestBytes',
      'maxResponseBytes',
    ],
    path,
  );
  if (error) return error;
  if (value.method !== 'POST') return `${path}.method must be POST`;
  error = relativePathError(value.path, `${path}.path`, false);
  if (error) return error;
  error = headersError(value.headers, `${path}.headers`);
  if (error) return error;
  if (
    value.bodyEncoding !== undefined &&
    value.bodyEncoding !== 'json' &&
    value.bodyEncoding !== 'multipart'
  ) {
    return `${path}.bodyEncoding must be json or multipart`;
  }
  error = objectPathError(value.bodyModelPath, `${path}.bodyModelPath`);
  if (error) return error;
  if (value.bodyEncoding === 'multipart') {
    if ((value.bodyModelPath as string[]).length !== 1) {
      return `${path}.bodyModelPath must be top-level for multipart requests`;
    }
    error = multipartFilesError(value.multipartFiles, `${path}.multipartFiles`);
    if (error) return error;
  } else if (value.multipartFiles !== undefined) {
    return `${path}.multipartFiles is only valid for multipart requests`;
  }
  for (const [field, max] of [
    ['timeoutMs', 600_000],
    ['maxRequestBytes', 268_435_456],
    ['maxResponseBytes', 268_435_456],
  ] as const) {
    error = positiveIntegerError(value[field], `${path}.${field}`, 1, max);
    if (error) return error;
  }
  return null;
}

function stringSetError(value: unknown, path: string): string | null {
  if (
    !Array.isArray(value) ||
    value.length === 0 ||
    value.length > 32 ||
    value.some((item) => !boundedString(item, 128))
  ) {
    return `${path} must be a non-empty bounded string array`;
  }
  return new Set(value).size === value.length ? null : `${path} must not contain duplicates`;
}

function pollError(value: unknown, path: string): string | null {
  if (!isPlainObject(value)) return `${path} must be an object`;
  let error = unknownField(
    value,
    [
      'method',
      'path',
      'headers',
      'bodyTaskIdPath',
      'statusPath',
      'successValues',
      'failureValues',
      'recommendedIntervalMs',
      'timeoutMs',
      'maxResponseBytes',
      'media',
    ],
    path,
  );
  if (error) return error;
  if (value.method !== 'GET' && value.method !== 'POST')
    return `${path}.method must be GET or POST`;
  error = relativePathError(value.path, `${path}.path`, true);
  if (error) return error;
  error = headersError(value.headers, `${path}.headers`);
  if (error) return error;
  if (value.method === 'GET') {
    if (!(value.path as string).includes('{taskId}')) {
      return `${path} GET polling path must include {taskId}`;
    }
    if (value.bodyTaskIdPath !== undefined) {
      return `${path}.bodyTaskIdPath is only valid for POST polling`;
    }
  } else if (
    value.bodyTaskIdPath === undefined &&
    !(value.path as string).includes('{taskId}')
  ) {
    return `${path} POST polling must declare bodyTaskIdPath or {taskId}`;
  }
  if (value.bodyTaskIdPath !== undefined) {
    error = objectPathError(value.bodyTaskIdPath, `${path}.bodyTaskIdPath`);
    if (error) return error;
  }
  error = objectPathError(value.statusPath, `${path}.statusPath`);
  if (error) return error;
  error = stringSetError(value.successValues, `${path}.successValues`);
  if (error) return error;
  error = stringSetError(value.failureValues, `${path}.failureValues`);
  if (error) return error;
  for (const [field, max] of [
    ['recommendedIntervalMs', 300_000],
    ['timeoutMs', 600_000],
    ['maxResponseBytes', 268_435_456],
  ] as const) {
    error = positiveIntegerError(value[field], `${path}.${field}`, 1, max);
    if (error) return error;
  }
  return mediaListError(value.media, `${path}.media`);
}

function responseError(value: unknown, path: string): string | null {
  if (!isPlainObject(value)) return `${path} must be an object`;
  if (value.mode === 'sync') {
    const unknown = unknownField(value, ['mode', 'media'], path);
    return unknown ?? mediaListError(value.media, `${path}.media`);
  }
  if (value.mode === 'async') {
    let error = unknownField(value, ['mode', 'taskIdPath', 'poll'], path);
    if (error) return error;
    error = objectPathError(value.taskIdPath, `${path}.taskIdPath`);
    return error ?? pollError(value.poll, `${path}.poll`);
  }
  return `${path}.mode must be sync or async`;
}

function operationError(value: unknown, path: string, checkFields = true): string | null {
  if (!isPlainObject(value)) return `${path} must be an object`;
  let error = checkFields ? unknownField(value, OPERATION_FIELDS, path) : null;
  if (error) return error;
  if (
    typeof value.capability !== 'string' ||
    !MODEL_ACCESS_MEDIA_CAPABILITIES.includes(value.capability as MediaCapability)
  ) {
    return `${path}.capability must be supported`;
  }
  if (!boundedString(value.instructions, 20_000)) {
    return `${path}.instructions must be a bounded string`;
  }
  error = requestError(value.request, `${path}.request`);
  if (error) return error;
  error = responseError(value.response, `${path}.response`);
  if (error) return error;
  if (!isPlainObject(value.exampleBody)) return `${path}.exampleBody must be an object`;
  if (!isPlainObject(value.inputSchema)) return `${path}.inputSchema must be an object`;
  if (!boundedString(value.officialDocs, 2_048)) return `${path}.officialDocs must be a URL`;
  try {
    const docs = new URL(value.officialDocs);
    if (docs.protocol !== 'https:' || !docs.hostname || docs.username || docs.password) {
      return `${path}.officialDocs must be an HTTPS URL`;
    }
  } catch {
    return `${path}.officialDocs must be an HTTPS URL`;
  }
  return null;
}

function guideBaseError(value: PlainObject, fields: readonly string[]): string | null {
  let error = unknownField(value, fields, 'guide');
  if (error) return error;
  if (value.schemaVersion !== MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION) {
    return `guide.schemaVersion must be ${MODEL_ACCESS_INVOCATION_GUIDE_SCHEMA_VERSION}`;
  }
  if (!boundedString(value.guideId, 128) || !/^[a-zA-Z0-9._-]+$/.test(value.guideId)) {
    return 'guide.guideId must be a bounded identifier';
  }
  for (const [field, max] of [['revision', 128]] as const) {
    if (!boundedString(value[field], max)) return `guide.${field} must be a bounded string`;
  }
  if (!isPlainObject(value.connection)) return 'guide.connection must be an object';
  error = unknownField(value.connection, ['providerId'], 'guide.connection');
  if (error) return error;
  if (
    !boundedString(value.connection.providerId, 128) ||
    !/^[a-zA-Z0-9_-]+$/.test(value.connection.providerId)
  ) {
    return 'guide.connection.providerId must be a bounded string';
  }
  return null;
}

function resolvedBindingError(
  value: PlainObject,
  fields: readonly string[],
  path: string,
): string | null {
  const error = unknownField(value, fields, path);
  if (error) return error;
  if (!boundedString(value.modelId, 256)) return `${path}.modelId must be a bounded string`;
  return null;
}

export function parseMediaInvocationGuide(
  value: unknown,
): ModelAccessParseResult<MediaInvocationGuide> {
  if (!isPlainObject(value)) return fail('guide must be an object');
  let error = guideBaseError(value, GUIDE_FIELDS);
  if (error) return fail(error);
  if (!Array.isArray(value.operations) || value.operations.length === 0 || value.operations.length > 16) {
    return fail('guide.operations must be a non-empty array with at most 16 entries');
  }
  const capabilities = new Set<MediaCapability>();
  for (const [index, operation] of value.operations.entries()) {
    error = operationError(operation, `guide.operations[${index}]`);
    if (error) return fail(error);
    const capability = (operation as PlainObject).capability as MediaCapability;
    if (capabilities.has(capability)) {
      return fail('guide.operations must not contain duplicate capabilities');
    }
    capabilities.add(capability);
  }
  return ok(value as unknown as MediaInvocationGuide);
}

export function parseResolvedMediaInvocationGuide(
  value: unknown,
): ModelAccessParseResult<ResolvedMediaInvocationGuide> {
  if (!isPlainObject(value)) return fail('resolved guide must be an object');
  const error = resolvedBindingError(value, RESOLVED_GUIDE_FIELDS, 'resolvedGuide');
  if (error) return fail(error);
  const guide = parseMediaInvocationGuide(value.guide);
  if (!guide.ok) return fail(guide.error);
  return ok(value as unknown as ResolvedMediaInvocationGuide);
}

export function parsePreparedMediaInvocationGuide(
  value: unknown,
): ModelAccessParseResult<PreparedMediaInvocationGuide> {
  if (!isPlainObject(value)) return fail('guide must be an object');
  const error =
    guideBaseError(value, PREPARED_GUIDE_FIELDS) ??
    resolvedBindingError(value, PREPARED_GUIDE_FIELDS, 'guide') ??
    operationError(value, 'guide', false);
  return error ? fail(error) : ok(value as unknown as PreparedMediaInvocationGuide);
}