@qjp88995/provider-client 0.2.0 → 0.3.0

package/src/media/types.ts

@@ -0,0 +1,233 @@
+import type { VendorFetch } from '../vendors/index.js';
+
+/**
+ * 媒体解析的厂商适配（从 agent-base `media/adapters` 搬来）。适配器只管「这家的请求长什么样、响应怎么翻、
+ * 哪些失败值得重试」，外加只有它知道的两件事：哪些设置决定产出（缓存键）、这家单次收多大的文件。
+ * 物化图片到存储、解析缓存、审计与花费是 APP 的事。
+ */
+
+/** `audio` 语音转写；`file` 文件解析；`video-link` 按链接解析在线视频。 */
+export const MEDIA_CAPABILITIES = ['audio', 'file', 'video-link'] as const;
+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 const ZHIPU_FILE_TOOL_TYPES = ['lite', 'expert', 'prime'] as const;
+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 const MEDIA_KINDS = [
+  'zhipu',
+  'bibigpt',
+] as const satisfies readonly MediaKind[];
+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 class MediaUpstreamError extends Error {
+  override readonly name: string = 'MediaUpstreamError';
+}

package/src/media/zhipu-parser-package.ts

@@ -0,0 +1,149 @@
+import { unzipSync } from 'fflate';
+
+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[];
+}
+
+const UTF8 = new TextDecoder();
+
+const PAGE_JSON_RE = /_ocr_page(\d+)\.json$/;
+
+const MEDIA_TYPE_BY_EXT: Record<string, string> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  bmp: 'image/bmp',
+};
+
+export function parseParserPackage(zip: Uint8Array): ParsedPackage {
+  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<string, number>();
+  let pageJsonCount = 0;
+  for (const n of names) {
+    if (!PAGE_JSON_RE.test(n)) continue;
+    pageJsonCount += 1;
+    let page: unknown;
+    try {
+      page = JSON.parse(UTF8.decode(entries[n]));
+    } catch {
+      continue; // 一页 JSON 坏了只是少了页码，不该让整包失败。
+    }
+    const pageNumber = (page as { PageNumber?: unknown }).PageNumber;
+    if (typeof pageNumber !== 'number') continue;
+    walkElements((page as { Elements?: unknown }).Elements, el => {
+      const ref = el.ImagePath;
+      if (typeof ref === 'string' && ref !== '' && !pageByRef.has(ref)) {
+        pageByRef.set(ref, pageNumber + 1);
+      }
+    });
+  }
+
+  const images: ParsedImage[] = [];
+  const missingRefs: string[] = [];
+  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,
+  };
+}
+
+interface PageElement {
+  ImagePath?: unknown;
+  Elements?: unknown;
+}
+
+function walkElements(els: unknown, visit: (el: PageElement) => void): void {
+  if (!Array.isArray(els)) return;
+  for (const el of els) {
+    if (!el || typeof el !== 'object') continue;
+    visit(el as PageElement);
+    walkElements((el as PageElement).Elements, visit);
+  }
+}
+
+/**
+ * expert 档的图片名 `<P>_<x>_<y>_<w>_<h>_0.jpg`：`P` 是 0 基页码。**只在
+ * 五段数字都在时才信**——prime 的 `<md5>-image.png` 不会匹配，其它未知命名
+ * 也不会被误读成页码。
+ */
+export function pageFromExpertName(ref: string): number | undefined {
+  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: string): string[] {
+  const seen = new Set<string>();
+  for (const m of markdown.matchAll(IMAGE_REF_RE)) {
+    const ref = m[2];
+    if (ref !== undefined && !seen.has(ref)) seen.add(ref);
+  }
+  return [...seen];
+}