@qjp88995/provider-client 0.1.1 → 0.3.0

package/dist/media/types.d.ts

@@ -0,0 +1,207 @@
+import type { VendorFetch } from '../vendors/index.js';
+/**
+ * 媒体解析的厂商适配（从 agent-base `media/adapters` 搬来）。适配器只管「这家的请求长什么样、响应怎么翻、
+ * 哪些失败值得重试」，外加只有它知道的两件事：哪些设置决定产出（缓存键）、这家单次收多大的文件。
+ * 物化图片到存储、解析缓存、审计与花费是 APP 的事。
+ */
+/** `audio` 语音转写；`file` 文件解析；`video-link` 按链接解析在线视频。 */
+export declare const MEDIA_CAPABILITIES: readonly ["audio", "file", "video-link"];
+export type MediaCapability = (typeof MEDIA_CAPABILITIES)[number];
+/** 要解析的东西：一个可直接下载的地址（不经中心、不带厂商鉴权），或现成的字节。 */
+export type MediaInput = {
+    kind: 'url';
+    url: string;
+} | {
+    kind: 'bytes';
+    bytes: Uint8Array;
+    mediaType: string;
+};
+export interface TokenUsage {
+    input?: number;
+    output?: number;
+    total?: number;
+}
+export interface AudioRequest {
+    input: MediaInput;
+    /** 语言提示；`auto` 或缺省 = 让厂商自己判断。 */
+    languageHint?: string;
+    durationHintMs?: number;
+    signal?: AbortSignal;
+}
+export interface AudioOutcome {
+    text: string;
+    rawResponse: unknown;
+    audioDurationMs?: number;
+    language?: string;
+    segments?: Array<{
+        start: number;
+        end: number;
+        text: string;
+    }>;
+    tokensUsed?: TokenUsage;
+    vendorExtra?: Record<string, unknown>;
+}
+export interface FileRequest {
+    input: MediaInput;
+    /** 异步任务的轮询预算（毫秒）；缺省用设置里的值。 */
+    maxWaitMs?: number;
+    signal?: AbortSignal;
+}
+/**
+ * 厂商交回来的**一张原始图片**：字节 + 它在 `markdown` 里被引用的写法。存进哪里、把 `ref` 换成什么地址是 APP 的事
+ * （厂商的链接会过期，进缓存之前必须先物化）。
+ */
+export interface ParsedImage {
+    /** markdown 里引用它的原始路径，逐字（智谱：`images/<md5>-image.png`）。 */
+    ref: string;
+    bytes: Uint8Array;
+    /** 完整子类型（`image/png`）。 */
+    mediaType: string;
+    /** 1 基页码；厂商没给就缺席。 */
+    page?: number;
+}
+export interface FileOutcome {
+    text: string;
+    markdown: string;
+    rawResponse: unknown;
+    pageCount?: number;
+    tokensUsed?: TokenUsage;
+    vendorExtra?: Record<string, unknown>;
+    /** 文档里的图片。缺席 = 这一档 / 这家不产出图片（智谱 lite），与「有图但一张没抠出来」（空数组）不同。 */
+    images?: ParsedImage[];
+    /**
+     * 非空 = **结果不完整**，一句给人看的原因：正文是好的，但本该有的图片没拿到（结果包下载失败、解不开……）。
+     * 调用方据此**别缓存**——缓存一份缺图的结果等于把一次瞬时故障固化成永久答案——并把这句话带给用户 / 模型。
+     */
+    degraded?: string;
+}
+export interface VideoLinkRequest {
+    /** 在线视频作品页的链接（已从分享文本里抽出来）。 */
+    url: string;
+    /** 取消信号：工具超时 / 用户停止时中断还在等的请求。 */
+    signal?: AbortSignal;
+}
+/** 一句字幕。时间单位是秒。 */
+export interface VideoLinkSubtitle {
+    start: number;
+    end: number;
+    text: string;
+    /** 厂商分出来的说话人编号；没分就缺席。 */
+    speaker?: number;
+}
+export interface VideoLinkChapter {
+    start: number;
+    end: number;
+    title: string;
+    summary: string;
+}
+/**
+ * 按链接解析一条在线视频的产出。除 `subtitles` 外的内容块都可能缺席——厂商某一步失败时写进 `missing`，
+ * 而不是让整次调用失败：字幕和元数据是主体，总结 / 原文细读是附加的。
+ */
+export interface VideoLinkOutcome {
+    title: string;
+    author?: string;
+    durationSec?: number;
+    /** ISO 时间；厂商没给就缺席。 */
+    publishedAt?: string;
+    /** 作品正文（小红书笔记正文、话题标签……），品牌名的准确写法常在这里。 */
+    description?: string;
+    subtitles: VideoLinkSubtitle[];
+    /** 全文总结（markdown，时间戳写成 `[mm:ss]`）。 */
+    summaryMarkdown?: string;
+    /** 章节总览（一段话）。 */
+    chapterOverview?: string;
+    chapters: VideoLinkChapter[];
+    /** 原文细读（按章节整理过的字幕，markdown）。 */
+    polishedMarkdown?: string;
+    /** 缺席内容块 → 一句给人看的原因。 */
+    missing: Partial<Record<'summary' | 'chapters' | 'polished', string>>;
+    /** 本次扣费与余额（秒）；厂商没给就缺席。 */
+    billing?: {
+        chargedSeconds?: number;
+        remainingSeconds?: number;
+    };
+    rawResponse: unknown;
+}
+/** 传给 `cacheKeyParts` 的调用参数——各能力参数的并集，适配器只挑自己关心的。 */
+export interface CacheKeyOpts {
+    languageHint?: string;
+    durationHintMs?: number;
+    maxWaitMs?: number;
+}
+/**
+ * 传给 `maxUploadBytes` 的提示：这次要送的是什么类型的文件。厂商的上限常按格式细分（智谱 prime 档 PDF 100MB、
+ * 表格只有 10MB）。`null` = 调用方也不知道类型，此时返回该能力的最小值。
+ */
+export interface UploadLimitHint {
+    mediaType: string | null;
+}
+/**
+ * 调一次上游要的东西。
+ * - `baseUrl`：这家媒体端点的根（智谱是 `media` 端点，BibiGPT 是它唯一的 `http` 端点）。
+ * - `openTask()`：**每次调用（一个任务）取一个新的** fetch，这次调用里建任务、轮询、取结果都用它。中心模式下它记住
+ *   第一条请求落在哪把 key 上，之后的请求钉在那把上（任务属于那个账号，换 key 就查不到）；直连模式就是同一个 fetch。
+ * - `download`：下载不属于厂商 API 的地址（`kind: 'url'` 的输入、智谱的结果包），不经中心、不带鉴权；缺省全局 fetch。
+ * - `apiKey`：只有直连模式给，适配器以 Bearer 发出；中心模式由中心注入。
+ */
+export interface MediaConnection {
+    baseUrl: string;
+    openTask(): VendorFetch;
+    download?: VendorFetch;
+    apiKey?: string;
+}
+/** 智谱文件解析档位：lite 只有正文；expert 只吃 PDF、带图片；prime 全格式、带图片。 */
+export declare const ZHIPU_FILE_TOOL_TYPES: readonly ["lite", "expert", "prime"];
+export type ZhipuFileToolType = (typeof ZHIPU_FILE_TOOL_TYPES)[number];
+/**
+ * 各家的设置（APP 存、调用时传；缺省值见各适配器）。**地址不是设置**：取自目录里这家的端点。
+ * 智谱的形状照 agent-base 的配置（去掉 `baseUrl`），存量配置可以原样传。
+ */
+export interface MediaSettingsByKind {
+    zhipu: {
+        audio?: {
+            model?: string;
+        };
+        file?: {
+            toolType?: ZhipuFileToolType;
+            defaultMaxWaitMs?: number;
+        };
+    };
+    bibigpt: Record<string, never>;
+}
+export type MediaKind = keyof MediaSettingsByKind;
+export declare const MEDIA_KINDS: readonly ["zhipu", "bibigpt"];
+export type MediaSettings<K extends MediaKind = MediaKind> = MediaSettingsByKind[K];
+/**
+ * 方法在不在 = 支不支持这项能力（`capabilities` 与之一致，spec 钉着）。
+ */
+export interface MediaAdapter<K extends MediaKind> {
+    readonly kind: K;
+    /** 这家的媒体请求走哪条端点：借 LLM key 的家是 `media`，自成一家的是 `http`。 */
+    readonly endpointProtocol: 'media' | 'http';
+    readonly capabilities: readonly MediaCapability[];
+    transcribeAudio?(conn: MediaConnection, settings: MediaSettings<K>, req: AudioRequest): Promise<AudioOutcome>;
+    parseFile?(conn: MediaConnection, settings: MediaSettings<K>, req: FileRequest): Promise<FileOutcome>;
+    fetchVideoLink?(conn: MediaConnection, settings: MediaSettings<K>, req: VideoLinkRequest): Promise<VideoLinkOutcome>;
+    /**
+     * 「这次调用的产出由哪些东西决定」，给调用方算解析缓存的键。`null` = **不可缓存**。只有适配器知道设置里哪些字段
+     * 换了会换来不同的产出（智谱的文件档位会，轮询预算不会）。
+     * - 绝不放密钥类字段（调用方可能明文落库供排查）。
+     * - 不认识的能力一律 null（fail-closed）；生成式产出（视频总结）不缓存。
+     */
+    cacheKeyParts(capability: MediaCapability, settings: MediaSettings<K>, opts: CacheKeyOpts): Record<string, unknown> | null;
+    /**
+     * 这家此能力单次最多收多大的文件（字节），按厂商文档抄数；`null` = 无声明，调用方只按自己的内存保护顶兜底。
+     * 文档只写「MB」没写清进制时按十进制取下界。
+     */
+    maxUploadBytes(capability: MediaCapability, settings: MediaSettings<K>, hint: UploadLimitHint): number | null;
+}
+/**
+ * 媒体厂商的上游失败（非 2xx、厂商说失败了、响应不成形、连不上……）。中心自己报的错（没有可用 key、
+ * 接入方不许用这家、钉住的 key 不可用……）不是这个，是 `ProviderClientError`。
+ */
+export declare class MediaUpstreamError extends Error {
+    readonly name: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/media/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"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"}

package/dist/media/types.js

@@ -0,0 +1,21 @@
+/**
+ * 媒体解析的厂商适配（从 agent-base `media/adapters` 搬来）。适配器只管「这家的请求长什么样、响应怎么翻、
+ * 哪些失败值得重试」，外加只有它知道的两件事：哪些设置决定产出（缓存键）、这家单次收多大的文件。
+ * 物化图片到存储、解析缓存、审计与花费是 APP 的事。
+ */
+/** `audio` 语音转写；`file` 文件解析；`video-link` 按链接解析在线视频。 */
+export const MEDIA_CAPABILITIES = ['audio', 'file', 'video-link'];
+/** 智谱文件解析档位：lite 只有正文；expert 只吃 PDF、带图片；prime 全格式、带图片。 */
+export const ZHIPU_FILE_TOOL_TYPES = ['lite', 'expert', 'prime'];
+export const MEDIA_KINDS = [
+    'zhipu',
+    'bibigpt',
+];
+/**
+ * 媒体厂商的上游失败（非 2xx、厂商说失败了、响应不成形、连不上……）。中心自己报的错（没有可用 key、
+ * 接入方不许用这家、钉住的 key 不可用……）不是这个，是 `ProviderClientError`。
+ */
+export class MediaUpstreamError extends Error {
+    name = 'MediaUpstreamError';
+}
+//# sourceMappingURL=types.js.map

package/dist/media/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/media/types.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AAEH,uDAAuD;AACvD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,CAAU,CAAC;AAqJ3E,0DAA0D;AAC1D,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC;AAe1E,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO;IACP,SAAS;CAC8B,CAAC;AAiD1C;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACzB,IAAI,GAAW,oBAAoB,CAAC;CACvD"}

package/dist/media/zhipu-parser-package.d.ts

@@ -0,0 +1,37 @@
+import type { ParsedImage } from './types.js';
+/**
+ * 智谱文件解析 `download_link` 结果包（zip）的读法。
+ *
+ * **文档只写了「图片 + Markdown + 版面 JSON」，目录结构与引图方式全部来自
+ * 2026-09-07 的探针**（三档各跑一遍真文件，判据记在 agent-base 的 providers.md）：
+ *
+ * - prime（异步）：`<hash>/<hash>_md_full.md` + `<hash>/<hash>_ocr_page<N>.json`
+ *   （每页一份，`PageNumber` **0 基**）+ `<hash>/images/<md5>-image.png`；
+ * - prime-sync：同上但**没有** `<hash>/` 这层目录；
+ * - expert：`result.md` + `images/<P>_<x>_<y>_<w>_<h>_0.jpg`，没有页 JSON，
+ *   页码只能从文件名前缀 `<P>` 取（0 基，与 prime 页 JSON 对过同一份 PDF）；
+ * - lite：只有 `result.md`，没有图片目录。
+ *
+ * 三档的 markdown 都用 `![](images/<name>)` 引图，路径**相对 md 所在目录**。
+ * 所以这里不按目录名硬编码：md 是包里唯一的 `.md` 条目，图片按 md 里的引用
+ * 去解析，页 JSON 按后缀认。布局变了，最先坏的是「找不到 md」这条响亮的错，
+ * 而不是静默少图。
+ */
+export interface ParsedPackage {
+    markdown: string;
+    images: ParsedImage[];
+    /** prime 有页 JSON 时给（= 页 JSON 份数）；其余档缺席。 */
+    pageCount?: number;
+    /** markdown 引用了、包里却没有的图片（排查用；正常为空）。 */
+    missingRefs: string[];
+}
+export declare function parseParserPackage(zip: Uint8Array): ParsedPackage;
+/**
+ * expert 档的图片名 `<P>_<x>_<y>_<w>_<h>_0.jpg`：`P` 是 0 基页码。**只在
+ * 五段数字都在时才信**——prime 的 `<md5>-image.png` 不会匹配，其它未知命名
+ * 也不会被误读成页码。
+ */
+export declare function pageFromExpertName(ref: string): number | undefined;
+/** markdown 里引用了哪些图片，按首次出现顺序去重。 */
+export declare function collectImageRefs(markdown: string): string[];
+//# sourceMappingURL=zhipu-parser-package.d.ts.map

package/dist/media/zhipu-parser-package.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zhipu-parser-package.d.ts","sourceRoot":"","sources":["../../src/media/zhipu-parser-package.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uCAAuC;IACvC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAeD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,aAAa,CA+DjE;AAgBD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAIlE;AAQD,mCAAmC;AACnC,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAO3D"}

package/dist/media/zhipu-parser-package.js

@@ -0,0 +1,108 @@
+import { unzipSync } from 'fflate';
+const UTF8 = new TextDecoder();
+const PAGE_JSON_RE = /_ocr_page(\d+)\.json$/;
+const MEDIA_TYPE_BY_EXT = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    bmp: 'image/bmp',
+};
+export function parseParserPackage(zip) {
+    const entries = unzipSync(zip);
+    const names = Object.keys(entries).filter(n => !n.endsWith('/'));
+    const mdNames = names.filter(n => /\.md$/i.test(n));
+    if (mdNames.length !== 1) {
+        throw new Error(`结果包里应有且只有一个 .md 文件，实际 ${mdNames.length} 个：` +
+            `${mdNames.join(', ') || '（无）'}；全部条目：${names.slice(0, 20).join(', ')}`);
+    }
+    const mdName = mdNames[0];
+    const mdDir = mdName.slice(0, mdName.lastIndexOf('/') + 1);
+    const markdown = UTF8.decode(entries[mdName]);
+    // 页码：prime 的页 JSON 里 `Elements[].ImagePath` 指向 `images/<name>`，
+    // `PageNumber` 0 基。递归走 `Elements`（表格里的图挂在 table 元素下）。
+    const pageByRef = new Map();
+    let pageJsonCount = 0;
+    for (const n of names) {
+        if (!PAGE_JSON_RE.test(n))
+            continue;
+        pageJsonCount += 1;
+        let page;
+        try {
+            page = JSON.parse(UTF8.decode(entries[n]));
+        }
+        catch {
+            continue; // 一页 JSON 坏了只是少了页码，不该让整包失败。
+        }
+        const pageNumber = page.PageNumber;
+        if (typeof pageNumber !== 'number')
+            continue;
+        walkElements(page.Elements, el => {
+            const ref = el.ImagePath;
+            if (typeof ref === 'string' && ref !== '' && !pageByRef.has(ref)) {
+                pageByRef.set(ref, pageNumber + 1);
+            }
+        });
+    }
+    const images = [];
+    const missingRefs = [];
+    for (const ref of collectImageRefs(markdown)) {
+        const entryName = mdDir + ref;
+        const bytes = entries[entryName];
+        if (!bytes) {
+            missingRefs.push(ref);
+            continue;
+        }
+        const ext = ref.slice(ref.lastIndexOf('.') + 1).toLowerCase();
+        const page = pageByRef.get(ref) ?? pageFromExpertName(ref);
+        images.push({
+            ref,
+            bytes,
+            mediaType: MEDIA_TYPE_BY_EXT[ext] ?? 'application/octet-stream',
+            ...(page !== undefined ? { page } : {}),
+        });
+    }
+    return {
+        markdown,
+        images,
+        ...(pageJsonCount > 0 ? { pageCount: pageJsonCount } : {}),
+        missingRefs,
+    };
+}
+function walkElements(els, visit) {
+    if (!Array.isArray(els))
+        return;
+    for (const el of els) {
+        if (!el || typeof el !== 'object')
+            continue;
+        visit(el);
+        walkElements(el.Elements, visit);
+    }
+}
+/**
+ * expert 档的图片名 `<P>_<x>_<y>_<w>_<h>_0.jpg`：`P` 是 0 基页码。**只在
+ * 五段数字都在时才信**——prime 的 `<md5>-image.png` 不会匹配，其它未知命名
+ * 也不会被误读成页码。
+ */
+export function pageFromExpertName(ref) {
+    const base = ref.slice(ref.lastIndexOf('/') + 1);
+    const m = /^(\d+)_\d+_\d+_\d+_\d+_\d+\./.exec(base);
+    return m ? Number(m[1]) + 1 : undefined;
+}
+/**
+ * markdown 图片语法 `![alt](url "title")` 的 URL 段。智谱三档产物都用它引图（探针 2026-09-07）。
+ * 与 agent-base `parsed-images.ts` 的同名正则一致（APP 改写引用时用它自己的那份）。
+ */
+const IMAGE_REF_RE = /(!\[[^\]]*\]\()([^)\s]+)((?:\s+"[^"]*")?\))/g;
+/** markdown 里引用了哪些图片，按首次出现顺序去重。 */
+export function collectImageRefs(markdown) {
+    const seen = new Set();
+    for (const m of markdown.matchAll(IMAGE_REF_RE)) {
+        const ref = m[2];
+        if (ref !== undefined && !seen.has(ref))
+            seen.add(ref);
+    }
+    return [...seen];
+}
+//# sourceMappingURL=zhipu-parser-package.js.map

package/dist/media/zhipu-parser-package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zhipu-parser-package.js","sourceRoot":"","sources":["../../src/media/zhipu-parser-package.ts"],"names":[],"mappings":"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"}

package/dist/media/zhipu.adapter.d.ts

@@ -0,0 +1,37 @@
+import { type AudioOutcome, type AudioRequest, type CacheKeyOpts, type FileOutcome, type FileRequest, type MediaAdapter, type MediaCapability, type MediaConnection, type MediaSettings, type UploadLimitHint } from './types.js';
+/**
+ * 智谱 BigModel 的文件解析与语音转写（agent-base 里叫 `bigmodel`），借智谱 LLM 的 key。根取自这家的 `media` 端点
+ * （`https://open.bigmodel.cn/api/paas/v4`），下挂 `/audio/transcriptions`、`/files/parser/…`。
+ */
+type Settings = MediaSettings<'zhipu'>;
+/**
+ * MIME → 上传时给厂商的文件扩展名。别处若另有一张「收得下哪些格式」的表，它必须是本表的子集——两张表漂了的表现是
+ * 「上游收得下的格式，适配器造不出正确的文件名」，是静默的错误。
+ */
+export declare const ZHIPU_MIME_TO_EXT: Readonly<Record<string, string>>;
+/**
+ * 各上限**逐字来自厂商文档**，改前先核对（数字过时的表现是静默的：要么白传被拒、要么把能解析的文件挡在门外）：
+ * - 文件解析 https://docs.bigmodel.cn/cn/guide/tools/file-parser.md ：Lite ≤50M；Expert ≤100M（仅 PDF）；
+ *   Prime 按格式——PDF/DOC/DOCX/PPT ≤100MB、XLS/XLSX/CSV ≤10MB、图片 ≤20MB（图片不该送到这里：看图归 LLM）。
+ *   txt/md 等 Prime 支持列表里有、尺寸表里没有的格式，取 Lite 同款 50MB 当下界。
+ * - 语音转写 https://docs.bigmodel.cn/api-reference/模型-api/语音转文本.md ：单文件 ≤25MB（还有 ≤30 秒时长限制，
+ *   字节层看不出时长，超时长交给厂商响亮报错）。
+ */
+export declare const ZHIPU_AUDIO_MAX_BYTES: number;
+export declare class ZhipuMediaAdapter implements MediaAdapter<'zhipu'> {
+    readonly kind: "zhipu";
+    readonly endpointProtocol: "media";
+    readonly capabilities: readonly ["audio", "file"];
+    /**
+     * - `audio`：转写是确定性的，产出由模型与语言提示决定。
+     * - `file`：版面解析同样确定，产出只由档位决定；轮询预算等多久都不改变内容，不进键。
+     *   `images: true` 是 agent-base 2026-09-07 加的**产出版本号**：expert/prime 从此带图片，与之前只取 `/text`
+     *   的缓存行不是同一种产出；lite 的产出没变，键也刻意不动。**照抄，别改**——改了 APP 里的存量缓存全部失效。
+     */
+    cacheKeyParts(capability: MediaCapability, settings: Settings, opts: CacheKeyOpts): Record<string, unknown> | null;
+    maxUploadBytes(capability: MediaCapability, settings: Settings, hint: UploadLimitHint): number | null;
+    transcribeAudio(conn: MediaConnection, settings: Settings, req: AudioRequest): Promise<AudioOutcome>;
+    parseFile(conn: MediaConnection, settings: Settings, req: FileRequest): Promise<FileOutcome>;
+}
+export {};
+//# sourceMappingURL=zhipu.adapter.d.ts.map

package/dist/media/zhipu.adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zhipu.adapter.d.ts","sourceRoot":"","sources":["../../src/media/zhipu.adapter.ts"],"names":[],"mappings":"AAOA,OAAO,EACL,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,YAAY,EACjB,KAAK,WAAW,EAChB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EACpB,KAAK,eAAe,EAEpB,KAAK,aAAa,EAElB,KAAK,eAAe,EAErB,MAAM,YAAY,CAAC;AAGpB;;;GAGG;AAEH,KAAK,QAAQ,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;AAcvC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAkB9D,CAAC;AAYF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,QAAU,CAAC;AAiD7C,qBAAa,iBAAkB,YAAW,YAAY,CAAC,OAAO,CAAC;IAC7D,QAAQ,CAAC,IAAI,EAAG,OAAO,CAAU;IACjC,QAAQ,CAAC,gBAAgB,EAAG,OAAO,CAAU;IAC7C,QAAQ,CAAC,YAAY,6BAA8B;IAEnD;;;;;OAKG;IACH,aAAa,CACX,UAAU,EAAE,eAAe,EAC3B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,YAAY,GACjB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;IAajC,cAAc,CACZ,UAAU,EAAE,eAAe,EAC3B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,eAAe,GACpB,MAAM,GAAG,IAAI;IAoBV,eAAe,CACnB,IAAI,EAAE,eAAe,EACrB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,YAAY,GAChB,OAAO,CAAC,YAAY,CAAC;IA+ClB,SAAS,CACb,IAAI,EAAE,eAAe,EACrB,QAAQ,EAAE,QAAQ,EAClB,GAAG,EAAE,WAAW,GACf,OAAO,CAAC,WAAW,CAAC;CAkHxB"}