@qjp88995/provider-client 0.2.0 → 0.4.0

package/dist/web-search/zhipu.adapter.js

@@ -0,0 +1,98 @@
+import { clip, codeOf, joinUrl, parseErrorBody, parseJson, postJson, } from './http.js';
+import { WebSearchUpstreamError, } from './types.js';
+/**
+ * 智谱工具 API 的根取自这家的 `web-search` 端点（`https://open.bigmodel.cn/api/paas/v4`），下挂 `/web_search`、`/reader`。
+ * 不从对话端点推：chat 根是 `/api/paas/v4`、responses 根是 `/api/v1`，从哪条推都是猜。
+ */
+/** 不设档位时用高阶版（agent-base 的缺省）。 */
+const DEFAULT_ENGINE = 'search_pro';
+/** reader 让智谱侧抓取页面的预算（秒）——上游参数，不是本地超时。 */
+const READER_FETCH_TIMEOUT_SECONDS = 20;
+/** 智谱「工具 API」：联网搜索（web_search）+ 网页阅读（reader）。 */
+export class ZhipuWebSearchAdapter {
+    kind = 'zhipu';
+    traits(settings) {
+        return {
+            readsPages: true,
+            maxResults: null,
+            filters: ['recency', 'domain'],
+            // 真机探针（2026-08-31）：search_std 常返回空 link，「把链接交给读网页」就走不通。
+            linksOftenMissing: (settings.searchEngine ?? DEFAULT_ENGINE) === 'search_std',
+            pageImagesArePlaceholders: false,
+        };
+    }
+    async search(conn, settings, input, signal) {
+        const engine = settings.searchEngine ?? DEFAULT_ENGINE;
+        const body = {
+            search_query: input.query,
+            search_engine: engine,
+            // 意图识别用不上：调用方（模型）自己就是意图层，开了只多花一份钱。
+            search_intent: false,
+            ...(input.count !== undefined ? { count: input.count } : {}),
+            ...(input.recency ? { search_recency_filter: input.recency } : {}),
+            ...(input.domain ? { search_domain_filter: input.domain } : {}),
+        };
+        let data;
+        try {
+            data = await this.post('web_search', conn, body, signal);
+        }
+        catch (err) {
+            // 1703 = 搜索引擎没返回有效数据。这是「零结果」不是「上游坏了」——报成
+            // 错误会让模型把一次正常的空搜索当成故障去重试，而它该做的是换关键词。
+            if (err instanceof WebSearchUpstreamError && err.code === '1703') {
+                return { engine, items: [] };
+            }
+            throw err;
+        }
+        const items = (data.search_result ?? []).map(r => ({
+            title: r.title ?? '',
+            link: r.link ?? '',
+            content: r.content ?? '',
+            media: r.media || null,
+            publishDate: r.publish_date || null,
+        }));
+        return { engine, items };
+    }
+    async readPage(conn, _settings, input, signal) {
+        const data = await this.post('reader', conn, {
+            url: input.url,
+            return_format: 'markdown',
+            // 剥掉图片：远程图片链接模型看不了（ViewImage 只读工作空间），留着
+            // 只是往上下文里灌一堆没用的长 URL。
+            retain_images: false,
+            timeout: READER_FETCH_TIMEOUT_SECONDS,
+        }, signal);
+        const r = data.reader_result;
+        if (!r || typeof r.content !== 'string') {
+            throw new WebSearchUpstreamError('zhipu reader 响应缺少 reader_result.content');
+        }
+        return {
+            url: r.url || input.url,
+            title: r.title || null,
+            description: r.description || null,
+            content: r.content,
+        };
+    }
+    async post(path, conn, body, signal) {
+        const label = `zhipu ${path}`;
+        const res = await postJson(label, joinUrl(conn.baseUrl, path), conn, body, signal);
+        if (!res.ok) {
+            const parsed = parseErrorBody(res.text);
+            const detail = parsed.message ?? clip(res.text);
+            throw new WebSearchUpstreamError(`${label} ${res.status}${detail ? `: ${detail}` : ''}`, {
+                code: parsed.code,
+                retryable: res.status >= 500 || res.status === 429 || parsed.code === '1701',
+            });
+        }
+        const json = parseJson(label, res.text);
+        // 智谱部分接口会用 200 + error 体报业务错误，别把它当成功往下传。
+        const errBody = json
+            .error;
+        if (errBody) {
+            const code = codeOf(errBody.code);
+            throw new WebSearchUpstreamError(`${label} 业务错误${code ? ` ${code}` : ''}：${typeof errBody.message === 'string' ? errBody.message : clip(res.text)}`, { code, retryable: code === '1701' });
+        }
+        return json;
+    }
+}
+//# sourceMappingURL=zhipu.adapter.js.map

package/dist/web-search/zhipu.adapter.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qjp88995/provider-client",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Client for the provider center: vendor adapters for the AI SDK, model resolution through the center's catalog and passthrough proxy, and a direct mode for local development.",
   "license": "UNLICENSED",
   "type": "module",
@@ -33,7 +33,9 @@
     "@ai-sdk/google": "^4.0.104",
     "@ai-sdk/moonshotai": "^3.0.76",
     "@ai-sdk/openai": "^4.0.101",
-    "@ai-sdk/openai-compatible": "^3.0.77"
+    "@ai-sdk/openai-compatible": "^3.0.77",
+    "fflate": "^0.8.3",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "ai": "^7.0.150"
@@ -43,7 +45,6 @@
     "ai": "^7.0.150",
     "typescript": "^5.9.3",
     "vitest": "^4.1.10",
-    "zod": "^4.4.3",
     "@pc/shared": "0.1.0"
   },
   "scripts": {

package/src/direct-resolver.ts

@@ -61,6 +61,8 @@ export class DirectModelResolver implements ModelResolver {
         pricing: null,
         ...m,
       })),
+      // 直连不做生图（生图只走中心）。
+      imageModels: [],
     }));
   }
 

package/src/image/http.ts

@@ -0,0 +1,68 @@
+import { parseCenterError, ProviderClientError } from '../errors.js';
+import { PC_HEADERS } from '../types.js';
+import { type ImageConnection, ImageUpstreamError } from './types.js';
+
+/**
+ * POST 一段 JSON，返回状态码与响应正文（同 web-search 的 `postJson`）。只处理「请求没发出去」与「中心自己报的错」：
+ * 中止原样抛；网络错误、中心的 `upstream_error` 是可重试的上游错误；中心别的错（没有可用 key、不许用这家……）是配置问题，
+ * 抛 `ProviderClientError`。厂商的状态码与响应体怎么解释是适配器的事。
+ */
+export async function postJson(
+  label: string,
+  url: string,
+  { apiKey, fetch }: ImageConnection,
+  body: Record<string, unknown>,
+  signal: AbortSignal
+): Promise<{ status: number; ok: boolean; text: string }> {
+  let res: Response;
+  try {
+    res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(body),
+      signal,
+    });
+  } catch (err) {
+    if (signal.aborted) throw err;
+    const reason = err instanceof Error ? err.message : String(err);
+    throw new ImageUpstreamError(`${label} 请求失败：${reason}`, {
+      retryable: true,
+    });
+  }
+  const text = await res.text();
+  if (!res.ok && !res.headers.has(PC_HEADERS.credential)) {
+    const center = centerErrorOf(text);
+    if (center?.code === 'upstream_error') {
+      throw new ImageUpstreamError(`${label} 请求失败：${center.message}`, {
+        code: center.code,
+        retryable: true,
+      });
+    }
+    if (center) {
+      throw new ProviderClientError(center.code, center.message, res.status);
+    }
+  }
+  return { status: res.status, ok: res.ok, text };
+}
+
+function centerErrorOf(text: string) {
+  try {
+    return parseCenterError(JSON.parse(text));
+  } catch {
+    return null;
+  }
+}
+
+/** 错误详情别整段回灌（HTML 错误页可能几十 KB）。 */
+export function clip(text: string): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > 300 ? `${flat.slice(0, 300)}…` : flat;
+}
+
+/** 端点根 + 子路径（根上多余的 `/` 去掉）。 */
+export function joinUrl(baseUrl: string, path: string): string {
+  return `${baseUrl.replace(/\/+$/, '')}/${path}`;
+}

package/src/image/index.ts

@@ -0,0 +1,87 @@
+import {
+  fitImageSize,
+  type GenerateImageInput,
+  type GenerateImageOutcome,
+  type ImageAdapter,
+  type ImageConnection,
+  type ImageTraits,
+} from './types.js';
+import { VolcengineImageAdapter } from './volcengine.adapter.js';
+
+/** kind → 生图适配器。中心哪几家能录生图模型（`VendorKindInfo.imageGeneration`）与这里一一对应（契约测试钉着）。 */
+export const IMAGE_ADAPTERS = {
+  volcengine: new VolcengineImageAdapter(),
+} as const satisfies Record<string, ImageAdapter>;
+
+export type ImageKind = keyof typeof IMAGE_ADAPTERS;
+export const IMAGE_KINDS = Object.keys(IMAGE_ADAPTERS) as ImageKind[];
+
+export function isImageKind(kind: string): kind is ImageKind {
+  return Object.hasOwn(IMAGE_ADAPTERS, kind);
+}
+
+/** 一个生图模型，连接已绑好。 */
+export interface ImageGenerator {
+  readonly kind: ImageKind;
+  readonly modelId: string;
+  readonly traits: ImageTraits;
+  /** 能不能带参考图（目录里的 `reference-image` 能力）。 */
+  readonly referenceImages: boolean;
+  generate(
+    input: GenerateImageInput,
+    signal: AbortSignal
+  ): Promise<GenerateImageOutcome>;
+}
+
+export interface CreateImageGeneratorInput {
+  kind: ImageKind;
+  modelId: string;
+  /** 目录里这个模型有 `reference-image` 能力。 */
+  referenceImages: boolean;
+  connection: ImageConnection;
+}
+
+/**
+ * 绑好连接的生图模型。中心模式用 `ProviderClient.imageModel`；这里是直连（测试）与中心模式共用的底层。
+ * 生成前先校验（空提示词、参考图不支持 / 超张数）并把尺寸放进这家的限制（`fitImageSize`）。
+ */
+export function createImageGenerator(
+  input: CreateImageGeneratorInput
+): ImageGenerator {
+  const adapter: ImageAdapter = IMAGE_ADAPTERS[input.kind];
+  const traits = adapter.traits(input.modelId);
+  return {
+    kind: input.kind,
+    modelId: input.modelId,
+    traits,
+    referenceImages: input.referenceImages,
+    generate: (req, signal) => {
+      if (!req.prompt.trim()) {
+        return Promise.reject(new RangeError('prompt must not be empty'));
+      }
+      const refs = req.referenceImages ?? [];
+      if (refs.length > 0 && !input.referenceImages) {
+        return Promise.reject(
+          new RangeError(
+            `model "${input.modelId}" does not take reference images`
+          )
+        );
+      }
+      if (refs.length > traits.maxReferenceImages) {
+        return Promise.reject(
+          new RangeError(
+            `at most ${traits.maxReferenceImages} reference images, got ${refs.length}`
+          )
+        );
+      }
+      return adapter.generate(
+        input.connection,
+        input.modelId,
+        { ...req, size: fitImageSize(req.size, traits) },
+        signal
+      );
+    },
+  };
+}
+
+export * from './types.js';

package/src/image/types.ts

@@ -0,0 +1,134 @@
+import type { VendorFetch } from '../vendors/index.js';
+
+/**
+ * 生图的厂商适配。适配器只管「这家的请求长什么样、响应怎么翻、哪些失败值得重试」与这家的尺寸限制；
+ * 什么时候生、生几张、提示词怎么写是 APP 的事。**一次调用出一张图**（火山 5.5 不支持一次多张）：要几张就并发几次。
+ */
+
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/** 参考图（图生图 / 改图）。字节随请求发出（data URI），不依赖公网地址。 */
+export interface ReferenceImage {
+  data: Uint8Array;
+  /** `image/jpeg`、`image/png`、`image/webp` …… */
+  mimeType: string;
+}
+
+export const IMAGE_FORMATS = ['jpeg', 'png'] as const;
+export type ImageFormat = (typeof IMAGE_FORMATS)[number];
+
+export interface GenerateImageInput {
+  prompt: string;
+  /**
+   * 想要的像素尺寸。这家的面积上下限之外会**等比**缩放进去（比例不变），实际尺寸看结果；
+   * 想先知道就用 `fitImageSize(size, traits)`。
+   */
+  size: ImageSize;
+  /** 参考图；模型没有 `reference-image` 能力或超过 `traits.maxReferenceImages` 张就报错，不悄悄丢。 */
+  referenceImages?: readonly ReferenceImage[];
+  /** 缺省 `jpeg`（幻灯片配图用 jpeg 小一个量级）。 */
+  format?: ImageFormat;
+}
+
+export interface GeneratedImage {
+  data: Uint8Array;
+  mimeType: string;
+  width: number;
+  height: number;
+}
+
+export interface ImageUsage {
+  generatedImages: number;
+  inputImages: number;
+  /** 厂商报的 token 数（火山按面积折算）；不报为 null。计价按张，这个只做记录。 */
+  tokens: number | null;
+}
+
+export interface GenerateImageOutcome {
+  image: GeneratedImage;
+  usage: ImageUsage;
+}
+
+/** 这家（这个模型）生图的限制，给调用方定尺寸、写工具说明用。 */
+export interface ImageTraits {
+  /** 面积下限（像素）。 */
+  minPixels: number;
+  /** 面积上限（像素）。 */
+  maxPixels: number;
+  /** 宽高比（长边 / 短边）上限。 */
+  maxAspectRatio: number;
+  /** 一次最多带几张参考图。 */
+  maxReferenceImages: number;
+}
+
+/**
+ * 调一次上游要的东西：这家生图所用端点的根地址与出站 fetch。中心模式下 fetch 是中心的透传 fetch、不带 key；
+ * 直连模式给 `apiKey`。
+ */
+export interface ImageConnection {
+  baseUrl: string;
+  fetch: VendorFetch;
+  apiKey?: string;
+}
+
+export interface ImageAdapter<K extends string = string> {
+  readonly kind: K;
+  /** 生图请求发往这家哪个端点（取它的根地址）。 */
+  readonly endpointProtocol: 'openai-chat-completions';
+  traits(modelId: string): ImageTraits;
+  generate(
+    conn: ImageConnection,
+    modelId: string,
+    input: GenerateImageInput,
+    signal: AbortSignal
+  ): Promise<GenerateImageOutcome>;
+}
+
+/**
+ * 厂商的失败（HTTP 错误、拒绝生成、响应不成形、没拿到响应）。中心自己报的错是 `ProviderClientError`。
+ * 调用方只读 `retryable` 决定要不要再试，不解析消息文本。
+ */
+export class ImageUpstreamError extends Error {
+  override readonly name = 'ImageUpstreamError';
+  /** 上游错误码（火山的 `InvalidParameter`、`OutputImageSensitiveContentDetected` ……），没有就是 null。 */
+  readonly code: string | null;
+  readonly retryable: boolean;
+  /** 被内容审核拦下（换提示词再试；原样重试没用）。 */
+  readonly contentFiltered: boolean;
+
+  constructor(
+    reason: string,
+    opts: { code?: string; retryable?: boolean; contentFiltered?: boolean } = {}
+  ) {
+    super(reason);
+    this.code = opts.code ?? null;
+    this.retryable = opts.retryable ?? false;
+    this.contentFiltered = opts.contentFiltered ?? false;
+  }
+}
+
+/**
+ * 把想要的尺寸放进这家的限制：宽高比超了先按上限收窄短边；面积超了等比缩小、不够等比放大。取整后面积仍要在界内。
+ */
+export function fitImageSize(size: ImageSize, traits: ImageTraits): ImageSize {
+  let { width: w, height: h } = size;
+  if (!(w > 0 && h > 0)) throw new RangeError('image size must be positive');
+  const ratio = Math.max(w, h) / Math.min(w, h);
+  if (ratio > traits.maxAspectRatio) {
+    if (w > h) h = w / traits.maxAspectRatio;
+    else w = h / traits.maxAspectRatio;
+  }
+  const area = w * h;
+  const scale =
+    area > traits.maxPixels
+      ? Math.sqrt(traits.maxPixels / area)
+      : area < traits.minPixels
+        ? Math.sqrt(traits.minPixels / area)
+        : 1;
+  // 缩小向下取整、放大向上取整，取整后面积不越界。
+  const round = scale < 1 ? Math.floor : scale > 1 ? Math.ceil : Math.round;
+  return { width: round(w * scale), height: round(h * scale) };
+}

package/src/image/volcengine.adapter.ts

@@ -0,0 +1,133 @@
+import { clip, joinUrl, postJson } from './http.js';
+import {
+  type GenerateImageInput,
+  type GenerateImageOutcome,
+  type ImageAdapter,
+  type ImageConnection,
+  type ImageTraits,
+  ImageUpstreamError,
+} from './types.js';
+
+/**
+ * 火山方舟（Seedream）生图：`POST {对话端点根}/images/generations`（`https://ark.cn-beijing.volces.com/api/v3`），
+ * OpenAI 形状。2026-11-13 经中心透传实测（Seedream 5.5 / 5.0 flash）：
+ * - `size` 收 `WxH`，面积 921600～4624220 像素，比例宽松（16:1 也行），像素不用对齐；
+ * - 一次一张（`n` 被忽略，组图 5.5 不支持）；参考图 `image` 收 data URI，最多 10 张；
+ * - 返回链接 24 小时失效 → 要 `b64_json`；`watermark: false` 去掉右下角「AI 生成」；
+ * - 失败是 `{ error: { code, message } }`（`InvalidParameter` / `MissingParameter` …）。
+ */
+const TRAITS: ImageTraits = {
+  minPixels: 921_600,
+  maxPixels: 4_624_220,
+  maxAspectRatio: 16,
+  maxReferenceImages: 10,
+};
+
+interface ArkImagesBody {
+  data?: {
+    b64_json?: string;
+    size?: string;
+    output_format?: string;
+    error?: { code?: string; message?: string };
+  }[];
+  usage?: {
+    generated_images?: number;
+    input_images?: number;
+    total_tokens?: number;
+  };
+  error?: { code?: string; message?: string };
+}
+
+const LABEL = '火山方舟生图';
+
+export class VolcengineImageAdapter implements ImageAdapter<'volcengine'> {
+  readonly kind = 'volcengine' as const;
+  readonly endpointProtocol = 'openai-chat-completions' as const;
+
+  traits(): ImageTraits {
+    return TRAITS;
+  }
+
+  async generate(
+    conn: ImageConnection,
+    modelId: string,
+    input: GenerateImageInput,
+    signal: AbortSignal
+  ): Promise<GenerateImageOutcome> {
+    const format = input.format ?? 'jpeg';
+    const refs = input.referenceImages ?? [];
+    const body: Record<string, unknown> = {
+      model: modelId,
+      prompt: input.prompt,
+      size: `${input.size.width}x${input.size.height}`,
+      response_format: 'b64_json',
+      output_format: format,
+      watermark: false,
+    };
+    if (refs.length > 0) {
+      const uris = refs.map(
+        r =>
+          `data:${r.mimeType};base64,${Buffer.from(r.data).toString('base64')}`
+      );
+      body.image = uris.length === 1 ? uris[0] : uris;
+    }
+    const res = await postJson(
+      LABEL,
+      joinUrl(conn.baseUrl, 'images/generations'),
+      conn,
+      body,
+      signal
+    );
+    let parsed: ArkImagesBody;
+    try {
+      parsed = JSON.parse(res.text) as ArkImagesBody;
+    } catch {
+      throw new ImageUpstreamError(
+        `${LABEL}失败（HTTP ${res.status}）：${clip(res.text)}`,
+        { retryable: res.status === 429 || res.status >= 500 }
+      );
+    }
+    if (!res.ok || parsed.error) {
+      throw upstreamError(res.status, parsed.error);
+    }
+    const item = parsed.data?.[0];
+    if (item?.error) throw upstreamError(res.status, item.error);
+    if (!item?.b64_json) {
+      throw new ImageUpstreamError(`${LABEL}没有返回图片：${clip(res.text)}`, {
+        retryable: true,
+      });
+    }
+    const [w, h] = (item.size ?? '').split('x').map(Number);
+    const outFormat = item.output_format === 'png' ? 'png' : format;
+    return {
+      image: {
+        data: new Uint8Array(Buffer.from(item.b64_json, 'base64')),
+        mimeType: outFormat === 'png' ? 'image/png' : 'image/jpeg',
+        width: w && Number.isFinite(w) ? w : input.size.width,
+        height: h && Number.isFinite(h) ? h : input.size.height,
+      },
+      usage: {
+        generatedImages: parsed.usage?.generated_images ?? 1,
+        inputImages: parsed.usage?.input_images ?? refs.length,
+        tokens: parsed.usage?.total_tokens ?? null,
+      },
+    };
+  }
+}
+
+function upstreamError(
+  status: number,
+  error: { code?: string; message?: string } | undefined
+): ImageUpstreamError {
+  const code = error?.code;
+  const message = error?.message ?? '未知错误';
+  return new ImageUpstreamError(
+    `${LABEL}失败（HTTP ${status}${code ? `，${code}` : ''}）：${clip(message)}`,
+    {
+      ...(code ? { code } : {}),
+      // 限流、服务端故障可重试；参数错、审核拦下重试没用。
+      retryable: status === 429 || status >= 500,
+      contentFiltered: !!code && /Sensitive|Moderation|RiskControl/i.test(code),
+    }
+  );
+}