HYPHA / DOCS

简体中文

English

简体中文

English

@codesoul-co/hypha-tools / media ​

模块用法 ​

用于声明 Tool 的文本、图像、音频与二进制输入输出。Media 模块公开 4 常量、2 函数、10 接口、2 类型。

从包入口导入 ​

ts
import {
  genericOcrInputJsonSchema,
  genericVideoSourceInputJsonSchema,
  ocrRequestSchema,
  videoSourceRequestSchema,
  createOcrToolSpec,
  createVideoSourceToolSpec,
} from '@codesoul-co/hypha-tools';

import type {
  OcrBlock,
  OcrBoundingBox,
  OcrPage,
  OcrProvider,
  OcrRequest,
  OcrResult,
  VideoSourceEpisode,
  VideoSourcePreview,
} from '@codesoul-co/hypha-tools';

// 完整导出列表见下方。

使用要点 ​

  • 12 个类型/接口用于应用代码、Adapter 或测试中的静态契约；请使用 import type，运行时不应依赖它们。
  • 2 个函数是该模块的直接操作入口；每个 overload 的必需/可选参数与返回类型均在下方列出。
  • 4 个常量/枚举提供稳定值、Schema、Definition 或默认配置；应复用这些导出，避免在应用中复制内部值。

运行时校验示例 ​

ts
import { ocrRequestSchema } from '@codesoul-co/hypha-tools';

declare function loadExternalInput(): unknown;
const input: unknown = loadExternalInput();
const parsed = ocrRequestSchema.parse(input);

配置、网络请求或持久化数据等不可信输入应先通过 Runtime Schema，再传给只接受已校验契约的函数或类。

公共导出 ​

Symbol种类签名说明
genericOcrInputJsonSchema常量const genericOcrInputJsonSchema: JsonSchemaGeneric Ocr Input 的 JSON Schema。
genericVideoSourceInputJsonSchema常量const genericVideoSourceInputJsonSchema: JsonSchemaGeneric Video Source Input 的 JSON Schema。
ocrRequestSchema常量const ocrRequestSchema: z.ZodObject<{ source: z.ZodType<OcrInputSource, z.ZodTypeDef, OcrInputSource>; languages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; pageRange: z.ZodOptional<z.ZodObject<{ start: z.ZodOptional<z.ZodNumber>; end: z.ZodOptional<z.ZodNumber>; }, "strip", z.ZodTypeAny, { start?: number | undefined; end?: number | undefined; }, { start?: number | undefined; end?: number | undefined; }>>; fe...Ocr Request 的运行时 Schema。
videoSourceRequestSchema常量const videoSourceRequestSchema: z.ZodObject<{ url: z.ZodString; titleHint: z.ZodOptional<z.ZodString>; locale: z.ZodOptional<z.ZodString>; includeEpisodes: z.ZodOptional<z.ZodBoolean>; includeCaptions: z.ZodOptional<z.ZodBoolean>; providerHint: z.ZodOptional<z.ZodString>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strip", z.ZodTypeAny, { url: string; metadata?: Record<string, unknown> | u...Video Source Request 的运行时 Schema。
createOcrToolSpec函数createOcrToolSpec(overrides?: Partial<ToolSpec>): ToolSpecCreate Ocr Tool Spec 函数，提供 1 个公开调用签名；参数与返回类型见下表。
createVideoSourceToolSpec函数createVideoSourceToolSpec(overrides?: Partial<ToolSpec>): ToolSpecCreate Video Source Tool Spec 函数，提供 1 个公开调用签名；参数与返回类型见下表。
OcrBlock接口interface OcrBlockOcr Block 接口，共包含 6 个公开字段或方法。
OcrBoundingBox接口interface OcrBoundingBoxOcr Bounding Box 接口，共包含 5 个公开字段或方法。
OcrPage接口interface OcrPageOcr Page 接口，共包含 7 个公开字段或方法。
OcrProvider接口interface OcrProviderOcr Provider 接口，共包含 3 个公开字段或方法。
OcrRequest接口interface OcrRequestOcr Request 接口，共包含 7 个公开字段或方法。
OcrResult接口interface OcrResultOcr Result 接口，共包含 10 个公开字段或方法。
VideoSourceEpisode接口interface VideoSourceEpisodeVideo Source Episode 接口，共包含 8 个公开字段或方法。
VideoSourcePreview接口interface VideoSourcePreviewVideo Source Preview 接口，共包含 15 个公开字段或方法。
VideoSourceProvider接口interface VideoSourceProviderVideo Source Provider 接口，共包含 4 个公开字段或方法。
VideoSourceRequest接口interface VideoSourceRequestVideo Source Request 接口，共包含 7 个公开字段或方法。
OcrInputSource类型type OcrInputSource = { type: 'artifact'; artifactRef: string; mimeType?: string; fileName?: string; } | { type: 'url'; url: string; mimeType?: string; fileName?: string; } | { type: 'inline'; dataBase64: string; mimeType: string; fileName?: string; } | { type: 'text'; text: string; fileName?: string; }Ocr Input Source 公共类型别名；完整类型表达式见声明。
VideoSourceKind类型type VideoSourceKind = 'video' | 'playlist' | 'collection' | 'live' | 'unknown'Video Source Kind 公共类型别名；完整类型表达式见声明。

genericOcrInputJsonSchema ​

Generic Ocr Input 的 JSON Schema。

  • 种类: 常量
  • 导入: import { genericOcrInputJsonSchema } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export declare const genericOcrInputJsonSchema: JsonSchema;

genericVideoSourceInputJsonSchema ​

Generic Video Source Input 的 JSON Schema。

  • 种类: 常量
  • 导入: import { genericVideoSourceInputJsonSchema } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export declare const genericVideoSourceInputJsonSchema: JsonSchema;

ocrRequestSchema ​

Ocr Request 的运行时 Schema。

  • 种类: 常量
  • 导入: import { ocrRequestSchema } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export declare const ocrRequestSchema: z.ZodObject<{ source: z.ZodType<OcrInputSource, z.ZodTypeDef, OcrInputSource>; languages: z.ZodOptional<z.ZodArray<z.ZodString, "many">>; pageRange: z.ZodOptional<z.ZodObject<{ start: z.ZodOptional<z.ZodNumber>; end: z.ZodOptional<z.ZodNumber>; }, "strip", z.ZodTypeAny, { start?: number | undefined; end?: number | undefined; }, { start?: number | undefined; end?: number | undefined; }>>; features: z.ZodOptional<z.ZodArray<z.ZodEnum<["text", "layout", "tables", "formulas"]>, "many">>; output: z.ZodOptional<z.ZodObject<{ includeBlocks: z.ZodOptional<z.ZodBoolean>; includeConfidence: z.ZodOptional<z.ZodBoolean>; artifactize: z.ZodOptional<z.ZodBoolean>; }, "strip", z.ZodTypeAny, { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; }, { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; }>>; providerHint: z.ZodOptional<z.ZodString>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strip", z.ZodTypeAny, { source: OcrInputSource; metadata?: Record<string, unknown> | undefined; output?: { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; } | undefined; languages?: string[] | undefined; pageRange?: { start?: number | undefined; end?: number | undefined; } | undefined; features?: ("text" | "layout" | "tables" | "formulas")[] | undefined; providerHint?: string | undefined; }, { source: OcrInputSource; metadata?: Record<string, unknown> | undefined; output?: { includeBlocks?: boolean | undefined; includeConfidence?: boolean | undefined; artifactize?: boolean | undefined; } | undefined; languages?: string[] | undefined; pageRange?: { start?: number | undefined; end?: number | undefined; } | undefined; features?: ("text" | "layout" | "tables" | "formulas")[] | undefined; providerHint?: string | undefined; }>;

videoSourceRequestSchema ​

Video Source Request 的运行时 Schema。

  • 种类: 常量
  • 导入: import { videoSourceRequestSchema } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export declare const videoSourceRequestSchema: z.ZodObject<{ url: z.ZodString; titleHint: z.ZodOptional<z.ZodString>; locale: z.ZodOptional<z.ZodString>; includeEpisodes: z.ZodOptional<z.ZodBoolean>; includeCaptions: z.ZodOptional<z.ZodBoolean>; providerHint: z.ZodOptional<z.ZodString>; metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>; }, "strip", z.ZodTypeAny, { url: string; metadata?: Record<string, unknown> | undefined; providerHint?: string | undefined; titleHint?: string | undefined; locale?: string | undefined; includeEpisodes?: boolean | undefined; includeCaptions?: boolean | undefined; }, { url: string; metadata?: Record<string, unknown> | undefined; providerHint?: string | undefined; titleHint?: string | undefined; locale?: string | undefined; includeEpisodes?: boolean | undefined; includeCaptions?: boolean | undefined; }>;

createOcrToolSpec ​

Create Ocr Tool Spec 函数，提供 1 个公开调用签名；参数与返回类型见下表。

  • 种类: 函数
  • 导入: import { createOcrToolSpec } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export declare function createOcrToolSpec(overrides?: Partial<ToolSpec>): ToolSpec;

调用签名 ​

text
createOcrToolSpec(overrides?: Partial<ToolSpec>): ToolSpec

参数 ​

参数类型必需说明
overridesPartial<ToolSpec>否可选参数；接受的值由类型列定义。

返回值 ​

  • 类型: ToolSpec
  • 说明: 返回值契约由上述类型定义。

createVideoSourceToolSpec ​

Create Video Source Tool Spec 函数，提供 1 个公开调用签名；参数与返回类型见下表。

  • 种类: 函数
  • 导入: import { createVideoSourceToolSpec } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export declare function createVideoSourceToolSpec(overrides?: Partial<ToolSpec>): ToolSpec;

调用签名 ​

text
createVideoSourceToolSpec(overrides?: Partial<ToolSpec>): ToolSpec

参数 ​

参数类型必需说明
overridesPartial<ToolSpec>否可选参数；接受的值由类型列定义。

返回值 ​

  • 类型: ToolSpec
  • 说明: 返回值契约由上述类型定义。

OcrBlock ​

Ocr Block 接口，共包含 6 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { OcrBlock } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface OcrBlock {
    id?: string;
    type: 'text' | 'title' | 'list' | 'table' | 'formula' | 'image' | 'unknown';
    text?: string;
    confidence?: number;
    boundingBox?: OcrBoundingBox;
    metadata?: Record<string, unknown>;
}

契约成员 ​

成员种类签名说明
boundingBox属性boundingBox?: OcrBoundingBox公开属性；类型、只读和可选状态以签名列为准。
confidence属性confidence?: number公开属性；类型、只读和可选状态以签名列为准。
id属性id?: string公开属性；类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性；类型、只读和可选状态以签名列为准。
text属性text?: string公开属性；类型、只读和可选状态以签名列为准。
type属性type: "unknown" | "image" | "table" | "list" | "text" | "title" | "formula"公开属性；类型、只读和可选状态以签名列为准。

OcrBoundingBox ​

Ocr Bounding Box 接口，共包含 5 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { OcrBoundingBox } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface OcrBoundingBox {
    x: number;
    y: number;
    width: number;
    height: number;
    unit?: 'pixel' | 'normalized' | 'point';
}

契约成员 ​

成员种类签名说明
height属性height: number公开属性；类型、只读和可选状态以签名列为准。
unit属性unit?: "pixel" | "normalized" | "point"公开属性；类型、只读和可选状态以签名列为准。
width属性width: number公开属性；类型、只读和可选状态以签名列为准。
x属性x: number公开属性；类型、只读和可选状态以签名列为准。
y属性y: number公开属性；类型、只读和可选状态以签名列为准。

OcrPage ​

Ocr Page 接口，共包含 7 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { OcrPage } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface OcrPage {
    pageNumber: number;
    text: string;
    confidence?: number;
    width?: number;
    height?: number;
    blocks?: OcrBlock[];
    artifactRefs?: string[];
}

契约成员 ​

成员种类签名说明
artifactRefs属性artifactRefs?: string[]公开属性；类型、只读和可选状态以签名列为准。
blocks属性blocks?: OcrBlock[]公开属性；类型、只读和可选状态以签名列为准。
confidence属性confidence?: number公开属性；类型、只读和可选状态以签名列为准。
height属性height?: number公开属性；类型、只读和可选状态以签名列为准。
pageNumber属性pageNumber: number公开属性；类型、只读和可选状态以签名列为准。
text属性text: string公开属性；类型、只读和可选状态以签名列为准。
width属性width?: number公开属性；类型、只读和可选状态以签名列为准。

OcrProvider ​

Ocr Provider 接口，共包含 3 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { OcrProvider } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface OcrProvider {
    readonly id: string;
    recognize(request: OcrRequest, context?: ToolCallContext): Promise<OcrResult>;
    health?(): Promise<{
        status: 'healthy' | 'degraded' | 'unavailable';
        message?: string;
    }>;
}

契约成员 ​

成员种类签名说明
health方法health?(): Promise<{ status: "healthy" | "degraded" | "unavailable"; message?: string; }>公开方法；参数与返回类型以签名列为准。
id属性readonly id: string公开属性；类型、只读和可选状态以签名列为准。
recognize方法recognize(request: OcrRequest, context?: ToolCallContext): Promise<OcrResult>公开方法；参数与返回类型以签名列为准。

OcrRequest ​

Ocr Request 接口，共包含 7 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { OcrRequest } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface OcrRequest {
    source: OcrInputSource;
    languages?: string[];
    pageRange?: {
        start?: number;
        end?: number;
    };
    features?: Array<'text' | 'layout' | 'tables' | 'formulas'>;
    output?: {
        includeBlocks?: boolean;
        includeConfidence?: boolean;
        artifactize?: boolean;
    };
    providerHint?: string;
    metadata?: Record<string, unknown>;
}

契约成员 ​

成员种类签名说明
features属性features?: ("text" | "layout" | "tables" | "formulas")[]公开属性；类型、只读和可选状态以签名列为准。
languages属性languages?: string[]公开属性；类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性；类型、只读和可选状态以签名列为准。
output属性output?: { includeBlocks?: boolean; includeConfidence?: boolean; artifactize?: boolean; }公开属性；类型、只读和可选状态以签名列为准。
pageRange属性pageRange?: { start?: number; end?: number; }公开属性；类型、只读和可选状态以签名列为准。
providerHint属性providerHint?: string公开属性；类型、只读和可选状态以签名列为准。
source属性source: OcrInputSource公开属性；类型、只读和可选状态以签名列为准。

OcrResult ​

Ocr Result 接口，共包含 10 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { OcrResult } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface OcrResult {
    status: 'completed' | 'partial' | 'failed';
    provider: string;
    providerVersion?: string;
    text?: string;
    pages: OcrPage[];
    detectedLanguages?: string[];
    artifactRefs?: string[];
    warnings?: string[];
    error?: {
        code: string;
        message: string;
        retryable?: boolean;
    };
    metadata?: Record<string, unknown>;
}

契约成员 ​

成员种类签名说明
artifactRefs属性artifactRefs?: string[]公开属性；类型、只读和可选状态以签名列为准。
detectedLanguages属性detectedLanguages?: string[]公开属性；类型、只读和可选状态以签名列为准。
error属性error?: { code: string; message: string; retryable?: boolean; }公开属性；类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性；类型、只读和可选状态以签名列为准。
pages属性pages: OcrPage[]公开属性；类型、只读和可选状态以签名列为准。
provider属性provider: string公开属性；类型、只读和可选状态以签名列为准。
providerVersion属性providerVersion?: string公开属性；类型、只读和可选状态以签名列为准。
status属性status: "completed" | "failed" | "partial"公开属性；类型、只读和可选状态以签名列为准。
text属性text?: string公开属性；类型、只读和可选状态以签名列为准。
warnings属性warnings?: string[]公开属性；类型、只读和可选状态以签名列为准。

VideoSourceEpisode ​

Video Source Episode 接口，共包含 8 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { VideoSourceEpisode } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface VideoSourceEpisode {
    id?: string;
    title: string;
    order: number;
    durationSeconds?: number;
    url?: string;
    thumbnailUrl?: string;
    captionRefs?: string[];
    metadata?: Record<string, unknown>;
}

契约成员 ​

成员种类签名说明
captionRefs属性captionRefs?: string[]公开属性；类型、只读和可选状态以签名列为准。
durationSeconds属性durationSeconds?: number公开属性；类型、只读和可选状态以签名列为准。
id属性id?: string公开属性；类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性；类型、只读和可选状态以签名列为准。
order属性order: number公开属性；类型、只读和可选状态以签名列为准。
thumbnailUrl属性thumbnailUrl?: string公开属性；类型、只读和可选状态以签名列为准。
title属性title: string公开属性；类型、只读和可选状态以签名列为准。
url属性url?: string公开属性；类型、只读和可选状态以签名列为准。

VideoSourcePreview ​

Video Source Preview 接口，共包含 15 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { VideoSourcePreview } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface VideoSourcePreview {
    provider: string;
    sourceKind: VideoSourceKind;
    sourceId?: string;
    canonicalUrl: string;
    title: string;
    description?: string;
    author?: string;
    durationSeconds?: number;
    publishedAt?: string;
    thumbnailUrl?: string;
    episodes: VideoSourceEpisode[];
    parsedAt: string;
    warnings?: string[];
    manualEntryRequired?: boolean;
    metadata?: Record<string, unknown>;
}

契约成员 ​

成员种类签名说明
author属性author?: string公开属性；类型、只读和可选状态以签名列为准。
canonicalUrl属性canonicalUrl: string公开属性；类型、只读和可选状态以签名列为准。
description属性description?: string公开属性；类型、只读和可选状态以签名列为准。
durationSeconds属性durationSeconds?: number公开属性；类型、只读和可选状态以签名列为准。
episodes属性episodes: VideoSourceEpisode[]公开属性；类型、只读和可选状态以签名列为准。
manualEntryRequired属性manualEntryRequired?: boolean公开属性；类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性；类型、只读和可选状态以签名列为准。
parsedAt属性parsedAt: string公开属性；类型、只读和可选状态以签名列为准。
provider属性provider: string公开属性；类型、只读和可选状态以签名列为准。
publishedAt属性publishedAt?: string公开属性；类型、只读和可选状态以签名列为准。
sourceId属性sourceId?: string公开属性；类型、只读和可选状态以签名列为准。
sourceKind属性sourceKind: VideoSourceKind公开属性；类型、只读和可选状态以签名列为准。
thumbnailUrl属性thumbnailUrl?: string公开属性；类型、只读和可选状态以签名列为准。
title属性title: string公开属性；类型、只读和可选状态以签名列为准。
warnings属性warnings?: string[]公开属性；类型、只读和可选状态以签名列为准。

VideoSourceProvider ​

Video Source Provider 接口，共包含 4 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { VideoSourceProvider } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface VideoSourceProvider {
    readonly id: string;
    supports(url: string): boolean | Promise<boolean>;
    preview(request: VideoSourceRequest, context?: ToolCallContext): Promise<VideoSourcePreview>;
    health?(): Promise<{
        status: 'healthy' | 'degraded' | 'unavailable';
        message?: string;
    }>;
}

契约成员 ​

成员种类签名说明
health方法health?(): Promise<{ status: "healthy" | "degraded" | "unavailable"; message?: string; }>公开方法；参数与返回类型以签名列为准。
id属性readonly id: string公开属性；类型、只读和可选状态以签名列为准。
preview方法preview(request: VideoSourceRequest, context?: ToolCallContext): Promise<VideoSourcePreview>公开方法；参数与返回类型以签名列为准。
supports方法supports(url: string): boolean | Promise<boolean>公开方法；参数与返回类型以签名列为准。

VideoSourceRequest ​

Video Source Request 接口，共包含 7 个公开字段或方法。

  • 种类: 接口
  • 导入: import type { VideoSourceRequest } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export interface VideoSourceRequest {
    url: string;
    titleHint?: string;
    locale?: string;
    includeEpisodes?: boolean;
    includeCaptions?: boolean;
    providerHint?: string;
    metadata?: Record<string, unknown>;
}

契约成员 ​

成员种类签名说明
includeCaptions属性includeCaptions?: boolean公开属性；类型、只读和可选状态以签名列为准。
includeEpisodes属性includeEpisodes?: boolean公开属性；类型、只读和可选状态以签名列为准。
locale属性locale?: string公开属性；类型、只读和可选状态以签名列为准。
metadata属性metadata?: Record<string, unknown>公开属性；类型、只读和可选状态以签名列为准。
providerHint属性providerHint?: string公开属性；类型、只读和可选状态以签名列为准。
titleHint属性titleHint?: string公开属性；类型、只读和可选状态以签名列为准。
url属性url: string公开属性；类型、只读和可选状态以签名列为准。

OcrInputSource ​

Ocr Input Source 公共类型别名；完整类型表达式见声明。

  • 种类: 类型
  • 导入: import type { OcrInputSource } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export type OcrInputSource = {
    type: 'artifact';
    artifactRef: string;
    mimeType?: string;
    fileName?: string;
} | {
    type: 'url';
    url: string;
    mimeType?: string;
    fileName?: string;
} | {
    type: 'inline';
    dataBase64: string;
    mimeType: string;
    fileName?: string;
} | {
    type: 'text';
    text: string;
    fileName?: string;
};

VideoSourceKind ​

Video Source Kind 公共类型别名；完整类型表达式见声明。

  • 种类: 类型
  • 导入: import type { VideoSourceKind } from '@codesoul-co/hypha-tools';
  • 源码模块: media

声明 ​

text
export type VideoSourceKind = 'video' | 'playlist' | 'collection' | 'live' | 'unknown';