@qjp88995/provider-client 0.2.0 → 0.4.0

package/src/provider-client.ts

@@ -1,5 +1,24 @@
-import { createCenterFetch } from './center-fetch.js';
+import { type CenterFetchOptions, createCenterFetch } from './center-fetch.js';
 import { errorFromResponse, ProviderClientError } from './errors.js';
+import {
+  createImageGenerator,
+  IMAGE_ADAPTERS,
+  type ImageGenerator,
+  isImageKind,
+} from './image/index.js';
+import {
+  createJustOne,
+  type JustOne,
+  type JustOneOptions,
+} from './justone/index.js';
+import {
+  createMedia,
+  isMediaKind,
+  MEDIA_ADAPTERS,
+  type MediaKind,
+  type MediaService,
+  type MediaSettings,
+} from './media/index.js';
 import {
   buildHandle,
   findModel,
@@ -10,6 +29,35 @@ import {
 } from './model-handle.js';
 import { type CatalogResponse, PC_HEADERS } from './types.js';
 import type { VendorFetch } from './vendors/index.js';
+import {
+  createWebSearch,
+  isWebSearchKind,
+  type WebSearch,
+  type WebSearchKind,
+  type WebSearchSettings,
+} from './web-search/index.js';
+
+/** `ProviderClient.webSearch` 的选项。 */
+export interface WebSearchOptions<
+  K extends WebSearchKind = WebSearchKind,
+> extends FetchForOptions {
+  /** 这家的设置（智谱档位、Kimi 基础 / 专业版）；不给用缺省。 */
+  settings?: WebSearchSettings<K>;
+}
+
+/** `ProviderClient.media` 的选项。 */
+export interface MediaOptions<
+  K extends MediaKind = MediaKind,
+> extends FetchForOptions {
+  /** 这家的设置（智谱的转写模型、解析档位与轮询预算）；不给用缺省。 */
+  settings?: MediaSettings<K>;
+  /** 下载非厂商地址（`kind: 'url'` 的输入、智谱的结果包）用的 fetch；默认全局 fetch。不经中心。 */
+  download?: VendorFetch;
+}
+
+/** `ProviderClient.justOne` 的选项。 */
+export interface JustOneClientOptions<C = unknown>
+  extends FetchForOptions, Pick<JustOneOptions<C>, 'onAttempt'> {}
 
 /** `ProviderClient.fetchFor` 的选项。 */
 export interface FetchForOptions {
@@ -21,6 +69,9 @@ export interface FetchForOptions {
   onCredential?: (ref: string) => void;
 }
 
+/** `ProviderClient.imageModel` 的选项。 */
+export type ImageModelOptions = FetchForOptions;
+
 export interface ProviderClientOptions {
   /** 中心的根地址，如 `https://provider.example.com`。 */
   centerUrl: string;
@@ -133,6 +184,234 @@ export class ProviderClient implements ModelResolver {
     });
   }
 
+  /**
+   * 某家厂商的联网搜索 / 读网页（适配器在本包，请求经中心透传、中心注入 key）。地址取自目录里这家的
+   * `web-search` 端点——它可以与对话端点不同域（MiniMax）。
+   * - 目录里没有这家 → `unknown_vendor`；这个版本的 client 没有这家的搜索适配器 → `unsupported_vendor_kind`；
+   *   这家没有启用的 `web-search` 端点 → `protocol_unavailable`。
+   * - 调用时中心自己报的错（没有可用 key、不许用这家……）是 `ProviderClientError`，厂商的失败是
+   *   `WebSearchUpstreamError`（带 `retryable`）。
+   * 目录只在创建时查一次。
+   */
+  async webSearch<K extends WebSearchKind>(
+    slug: string,
+    options: WebSearchOptions<K> = {}
+  ): Promise<WebSearch> {
+    const vendor = (await this.catalog()).vendors.find(v => v.slug === slug);
+    if (!vendor) {
+      throw new ProviderClientError(
+        'unknown_vendor',
+        `vendor "${slug}" is not in the catalog`,
+        null
+      );
+    }
+    if (!isWebSearchKind(vendor.kind)) {
+      throw new ProviderClientError(
+        'unsupported_vendor_kind',
+        `vendor kind "${vendor.kind}" has no web search adapter`,
+        null
+      );
+    }
+    const endpoint = vendor.endpoints.find(e => e.protocol === 'web-search');
+    if (!endpoint) {
+      throw new ProviderClientError(
+        'protocol_unavailable',
+        `vendor "${slug}" has no web-search endpoint`,
+        null
+      );
+    }
+    const fetch = createCenterFetch({
+      centerUrl: this.center,
+      apiKey: this.options.apiKey,
+      vendor: vendor.slug,
+      baseUrls: vendor.endpoints.map(e => e.baseUrl),
+      affinity: options.affinity,
+      pin: options.pin,
+      onCredential: options.onCredential,
+      fetch: this.send,
+    });
+    return createWebSearch({
+      kind: vendor.kind as K,
+      connection: { baseUrl: endpoint.baseUrl, fetch },
+      settings: options.settings,
+    });
+  }
+
+  /**
+   * 一个生图模型（适配器在本包，请求经中心透传、中心注入 key）。地址取自这家的对话端点（生图模型没有自己的协议，
+   * 用哪个端点由这家的生图适配器定）。**一次 `generate` 出一张**；要几张就并发几次。
+   * - 目录里没有这家 → `unknown_vendor`；这家没有这个生图模型（或停用了）→ `unknown_model`；
+   *   这个版本的 client 没有这家的生图适配器 → `unsupported_vendor_kind`；这家没有启用的对应端点 → `protocol_unavailable`。
+   * - 生成时中心自己报的错是 `ProviderClientError`，厂商的失败是 `ImageUpstreamError`（`retryable`、`contentFiltered`）。
+   * - 用量（张数、参考图数）在结果里，单价在目录里（`catalog()` 的 `imageModels[].pricing`），钱由 APP 自己算。
+   * 目录只在创建时查一次。
+   */
+  async imageModel(
+    ref: ModelRef,
+    options: ImageModelOptions = {}
+  ): Promise<ImageGenerator> {
+    const vendor = (await this.catalog()).vendors.find(
+      v => v.slug === ref.vendor
+    );
+    if (!vendor) {
+      throw new ProviderClientError(
+        'unknown_vendor',
+        `vendor "${ref.vendor}" is not in the catalog`,
+        null
+      );
+    }
+    const model = vendor.imageModels.find(m => m.modelId === ref.modelId);
+    if (!model) {
+      throw new ProviderClientError(
+        'unknown_model',
+        `image model "${ref.modelId}" is not in the catalog of vendor "${ref.vendor}"`,
+        null
+      );
+    }
+    if (!isImageKind(vendor.kind)) {
+      throw new ProviderClientError(
+        'unsupported_vendor_kind',
+        `vendor kind "${vendor.kind}" has no image generation adapter`,
+        null
+      );
+    }
+    const protocol = IMAGE_ADAPTERS[vendor.kind].endpointProtocol;
+    const endpoint = vendor.endpoints.find(e => e.protocol === protocol);
+    if (!endpoint) {
+      throw new ProviderClientError(
+        'protocol_unavailable',
+        `vendor "${ref.vendor}" has no ${protocol} endpoint (image generation uses its base URL)`,
+        null
+      );
+    }
+    const fetch = createCenterFetch({
+      centerUrl: this.center,
+      apiKey: this.options.apiKey,
+      vendor: vendor.slug,
+      baseUrls: vendor.endpoints.map(e => e.baseUrl),
+      affinity: options.affinity,
+      pin: options.pin,
+      onCredential: options.onCredential,
+      fetch: this.send,
+    });
+    return createImageGenerator({
+      kind: vendor.kind,
+      modelId: model.modelId,
+      referenceImages: model.capabilities.includes('reference-image'),
+      connection: { baseUrl: endpoint.baseUrl, fetch },
+    });
+  }
+
+  /**
+   * 某家厂商的媒体解析（适配器在本包，请求经中心透传、中心注入 key）：智谱的文件解析 / 语音转写（地址取自这家的
+   * `media` 端点）、BibiGPT 的视频链接解析（它唯一的 `http` 端点）。
+   * - 目录里没有这家 → `unknown_vendor`；这个版本的 client 没有这家的媒体适配器 → `unsupported_vendor_kind`；
+   *   这家没有启用的对应端点 → `protocol_unavailable`。
+   * - **每次调用是一个任务**：第一条请求带 `affinity`（给了的话）选 key，之后的轮询 / 取结果钉在那把 key 上
+   *   （`x-pc-pin`）——任务属于那个账号，换 key 就查不到；那把 key 中途不可用会报 `pinned_credential_unavailable`。
+   *   给了 `pin` 就从头钉住。
+   * - 中心自己报的错是 `ProviderClientError`，厂商的失败是 `MediaUpstreamError`。
+   * 目录只在创建时查一次。
+   */
+  async media<K extends MediaKind>(
+    slug: string,
+    options: MediaOptions<K> = {}
+  ): Promise<MediaService> {
+    const vendor = (await this.catalog()).vendors.find(v => v.slug === slug);
+    if (!vendor) {
+      throw new ProviderClientError(
+        'unknown_vendor',
+        `vendor "${slug}" is not in the catalog`,
+        null
+      );
+    }
+    if (!isMediaKind(vendor.kind)) {
+      throw new ProviderClientError(
+        'unsupported_vendor_kind',
+        `vendor kind "${vendor.kind}" has no media adapter`,
+        null
+      );
+    }
+    const protocol = MEDIA_ADAPTERS[vendor.kind].endpointProtocol;
+    const endpoint = vendor.endpoints.find(e => e.protocol === protocol);
+    if (!endpoint) {
+      throw new ProviderClientError(
+        'protocol_unavailable',
+        `vendor "${slug}" has no ${protocol} endpoint`,
+        null
+      );
+    }
+    const base: CenterFetchOptions = {
+      centerUrl: this.center,
+      apiKey: this.options.apiKey,
+      vendor: vendor.slug,
+      baseUrls: vendor.endpoints.map(e => e.baseUrl),
+      affinity: options.affinity,
+      fetch: this.send,
+    };
+    return createMedia({
+      kind: vendor.kind as K,
+      connection: {
+        baseUrl: endpoint.baseUrl,
+        openTask: () =>
+          createTaskFetch(base, options.pin, options.onCredential),
+        ...(options.download ? { download: options.download } : {}),
+      },
+      settings: options.settings,
+    });
+  }
+
+  /**
+   * JustOne 数据接口（客户端在本包，请求经中心透传；token 由中心注入 query 或表单字段，本进程不碰）。地址取自这家的
+   * `http` 端点。调用审计、花费由 APP 经 `onAttempt` 记。
+   * - 目录里没有这家 → `unknown_vendor`；这家不是 `justone` → `unsupported_vendor_kind`；没有启用的 `http` 端点 →
+   *   `protocol_unavailable`。
+   * - 调用时中心自己报的错是 `ProviderClientError`，JustOne 的失败是 `JustOneUpstreamError`，参数不对是 `JustOneParamsError`。
+   * 接口是无状态的，`affinity` / `pin` 只影响选哪把 key。目录只在创建时查一次。
+   */
+  async justOne<C = unknown>(
+    slug: string,
+    options: JustOneClientOptions<C> = {}
+  ): Promise<JustOne<C>> {
+    const vendor = (await this.catalog()).vendors.find(v => v.slug === slug);
+    if (!vendor) {
+      throw new ProviderClientError(
+        'unknown_vendor',
+        `vendor "${slug}" is not in the catalog`,
+        null
+      );
+    }
+    if (vendor.kind !== 'justone') {
+      throw new ProviderClientError(
+        'unsupported_vendor_kind',
+        `vendor kind "${vendor.kind}" is not justone`,
+        null
+      );
+    }
+    const endpoint = vendor.endpoints.find(e => e.protocol === 'http');
+    if (!endpoint) {
+      throw new ProviderClientError(
+        'protocol_unavailable',
+        `vendor "${slug}" has no http endpoint`,
+        null
+      );
+    }
+    const fetch = createCenterFetch({
+      centerUrl: this.center,
+      apiKey: this.options.apiKey,
+      vendor: vendor.slug,
+      baseUrls: vendor.endpoints.map(e => e.baseUrl),
+      affinity: options.affinity,
+      pin: options.pin,
+      onCredential: options.onCredential,
+      fetch: this.send,
+    });
+    return createJustOne<C>({
+      connection: { baseUrl: endpoint.baseUrl, fetch },
+      ...(options.onAttempt ? { onAttempt: options.onAttempt } : {}),
+    });
+  }
+
   async capabilitiesOf(ref: ModelRef) {
     const vendor = (await this.catalog()).vendors.find(
       v => v.slug === ref.vendor
@@ -166,6 +445,8 @@ export class ProviderClient implements ModelResolver {
     }
     if (!res.ok) throw await errorFromResponse(res);
     const body = (await res.json()) as CatalogResponse;
+    // 中心 2026-11 之前没有 `imageModels`：补成空数组，后面不用到处判空。
+    for (const v of body.vendors) v.imageModels ??= [];
     this.cached = {
       etag: res.headers.get('etag'),
       body,
@@ -174,3 +455,24 @@ export class ProviderClient implements ModelResolver {
     return body;
   }
 }
+
+/**
+ * 一个任务用的中心模式 fetch：还不知道落在哪把 key 时按粘性选（或按调用方给的 pin），第一次看到 `x-pc-credential`
+ * 之后的请求都钉在那把上。
+ */
+function createTaskFetch(
+  base: CenterFetchOptions,
+  pin: string | undefined,
+  onCredential: ((ref: string) => void) | undefined
+): VendorFetch {
+  let pinned = pin;
+  const report = (ref: string) => {
+    pinned ??= ref;
+    onCredential?.(ref);
+  };
+  return (input, init) =>
+    createCenterFetch({ ...base, pin: pinned, onCredential: report })(
+      input,
+      init
+    );
+}

package/src/types.ts

@@ -13,8 +13,16 @@ export const LLM_PROTOCOLS = [
 ] as const;
 export type LlmProtocol = (typeof LLM_PROTOCOLS)[number];
 
-/** 端点协议：LLM 线协议，加上非 LLM 厂商（媒体、数据接口）唯一的 `http`。模型只声明 LLM 协议。 */
-export const ENDPOINT_PROTOCOLS = [...LLM_PROTOCOLS, 'http'] as const;
+/**
+ * 端点协议：LLM 线协议；非 LLM 厂商（媒体、数据接口）唯一的 `http`；LLM 厂商的联网搜索 / 读网页 `web-search`
+ * （可以与对话端点不同域，如 MiniMax）；LLM 厂商借同一把 key 的媒体解析 `media`（智谱）。模型只声明 LLM 协议。
+ */
+export const ENDPOINT_PROTOCOLS = [
+  ...LLM_PROTOCOLS,
+  'http',
+  'web-search',
+  'media',
+] as const;
 export type EndpointProtocol = (typeof ENDPOINT_PROTOCOLS)[number];
 
 /** 厂商类别：只有 `llm` 有模型与适配器；其余的只经中心透传（适配器在各 APP）。 */
@@ -25,6 +33,10 @@ export type VendorCategory = (typeof VENDOR_CATEGORIES)[number];
 export const LLM_CAPABILITIES = ['vision', 'video', 'reasoning'] as const;
 export type LlmCapability = (typeof LLM_CAPABILITIES)[number];
 
+/** 生图模型的能力。`reference-image` = 能带参考图（图生图 / 改图）。 */
+export const IMAGE_CAPABILITIES = ['reference-image'] as const;
+export type ImageCapability = (typeof IMAGE_CAPABILITIES)[number];
+
 /** 厂商类型。`llm` 类别的每一种对应一个适配器（`VENDOR_ADAPTERS`）；bibigpt / justone 没有。 */
 export const VENDOR_KINDS = [
   'openai',
@@ -83,7 +95,10 @@ export interface CatalogVendor {
   /** 非 `llm` 的厂商没有模型，接入方只拿它的端点经中心透传。 */
   category: VendorCategory;
   endpoints: CatalogEndpoint[];
+  /** 对话模型。 */
   models: CatalogModel[];
+  /** 生图模型（中心 2026-11 起有；读目录时缺了按空数组补上）。 */
+  imageModels: CatalogImageModel[];
 }
 
 export interface CatalogEndpoint {
@@ -103,6 +118,20 @@ export interface CatalogModel {
   pricing: ModelPricing | null;
 }
 
+/** 生图的单价（每张，十进制字符串）。 */
+export interface ImagePricing {
+  currency: string;
+  perImage: string;
+}
+
+export interface CatalogImageModel {
+  /** 厂商侧的模型名（请求体里的 `model`）。 */
+  modelId: string;
+  displayName: string;
+  capabilities: ImageCapability[];
+  pricing: ImagePricing | null;
+}
+
 /** 中心的错误码（响应体 `{ code, message }`）。 */
 export const CENTER_ERROR_CODES = [
   'unauthorized',

package/src/web-search/deepseek.adapter.ts

@@ -0,0 +1,149 @@
+import { clip, joinUrl, parseErrorBody, parseJson, postJson } from './http.js';
+import {
+  recencySince,
+  type WebPageOutcome,
+  type WebSearchAdapter,
+  type WebSearchConnection,
+  type WebSearchInput,
+  type WebSearchOutcome,
+  type WebSearchSettings,
+  type WebSearchTraits,
+  WebSearchUpstreamError,
+} from './types.js';
+
+/**
+ * DeepSeek Search / Fetch API（2026-10-17 上线，<https://api-docs.deepseek.com/guides/search>）。
+ * 与对话 API 同一把 Bearer key；`web-search` 端点的根是 `https://api.deepseek.com/v1/tools`，下挂 `/search`、`/fetch`。
+ */
+const TRAITS: WebSearchTraits = {
+  readsPages: true,
+  maxResults: null,
+  filters: ['recency', 'domain'],
+  linksOftenMissing: false,
+  pageImagesArePlaceholders: false,
+};
+
+interface DeepseekSearchBody {
+  results?: {
+    title?: string;
+    url?: string;
+    snippet?: string;
+    summary?: string;
+    site_name?: string | null;
+    date?: string | null;
+  }[];
+}
+
+interface DeepseekFetchBody {
+  title?: string;
+  content?: string;
+}
+
+type Settings = WebSearchSettings<'deepseek'>;
+
+/**
+ * DeepSeek 没有单独的时间 / 域名过滤字段，靠查询里的操作符（`after:` / `site:`），
+ * 所以这两项拼进 `query`。查询上限 128 字符（含操作符），工具层的 70 字留足了余量。
+ */
+export class DeepseekWebSearchAdapter implements WebSearchAdapter<'deepseek'> {
+  readonly kind = 'deepseek' as const;
+
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  traits(): WebSearchTraits {
+    return TRAITS;
+  }
+
+  async search(
+    conn: WebSearchConnection,
+    _settings: Settings,
+    input: WebSearchInput,
+    signal: AbortSignal
+  ): Promise<WebSearchOutcome> {
+    const query = [
+      input.query,
+      input.domain ? `site:${input.domain}` : null,
+      input.recency ? `after:${recencySince(input.recency, this.now())}` : null,
+    ]
+      .filter(Boolean)
+      .join(' ');
+    const data = await this.post<DeepseekSearchBody>(
+      'search',
+      conn,
+      { query, ...(input.count !== undefined ? { count: input.count } : {}) },
+      signal
+    );
+    const items = (data.results ?? []).map(r => ({
+      title: r.title ?? '',
+      link: r.url ?? '',
+      // summary 是给模型看的长摘要（600–800 字），snippet 是给界面的短摘要。
+      content: r.summary || r.snippet || '',
+      media: r.site_name || null,
+      publishDate: r.date || null,
+    }));
+    return { engine: 'deepseek', items };
+  }
+
+  async readPage(
+    conn: WebSearchConnection,
+    _settings: Settings,
+    input: { url: string },
+    signal: AbortSignal
+  ): Promise<WebPageOutcome> {
+    const data = await this.post<DeepseekFetchBody>(
+      'fetch',
+      conn,
+      { url: input.url },
+      signal
+    );
+    if (typeof data.content !== 'string') {
+      throw new WebSearchUpstreamError('deepseek fetch 响应缺少 content');
+    }
+    return {
+      url: input.url,
+      title: data.title || null,
+      description: null,
+      content: data.content,
+    };
+  }
+
+  private async post<T>(
+    path: 'search' | 'fetch',
+    conn: WebSearchConnection,
+    body: Record<string, unknown>,
+    signal: AbortSignal
+  ): Promise<T> {
+    const label = `deepseek ${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);
+      const hint = STATUS_HINTS[res.status];
+      throw new WebSearchUpstreamError(
+        `${label} ${res.status}${hint ? `（${hint}）` : ''}${detail ? `: ${detail}` : ''}`,
+        {
+          code: parsed.code,
+          // 文档：408 / 429 / 5xx 等一等再试，其余 4xx 不改请求重试也没用。
+          retryable:
+            res.status >= 500 || res.status === 429 || res.status === 408,
+        }
+      );
+    }
+    return parseJson<T>(label, res.text);
+  }
+}
+
+/** 文档里有确定含义的状态码，带进错误文案让模型 / 运营不必去查。 */
+const STATUS_HINTS: Readonly<Record<number, string>> = {
+  401: 'API key 无效',
+  402: '账户余额不足，需要充值',
+  403: '网页被 DeepSeek 的安全策略拒绝',
+  404: '取不到这个网页的可用内容：链接失效、站点拦截或不是可提取的网页',
+  429: '超过 QPS 上限',
+};

package/src/web-search/http.ts

@@ -0,0 +1,108 @@
+import { parseCenterError, ProviderClientError } from '../errors.js';
+import { PC_HEADERS } from '../types.js';
+import { type WebSearchConnection, WebSearchUpstreamError } from './types.js';
+
+/**
+ * POST 一段 JSON，返回状态码与响应正文。只处理「请求没发出去」与「中心自己报的错」：
+ * - 中止原样抛（那是调用方超时或用户点了停止，不是上游故障，重试是错的）；网络错误转成可重试的上游错误。
+ * - 中心自己的错误体（`{ code, message }` 且没有 `x-pc-credential` 头，判据同 `toProviderClientError`）：
+ *   `upstream_error`（中心连不上厂商）当可重试的上游错误，其余（没有可用 key、不许用这家……）是配置问题，
+ *   抛 `ProviderClientError`。
+ * 厂商的状态码与响应体怎么解释是各适配器的事。
+ */
+export async function postJson(
+  label: string,
+  url: string,
+  { apiKey, fetch }: WebSearchConnection,
+  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 WebSearchUpstreamError(`${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 WebSearchUpstreamError(`${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;
+  }
+}
+
+/** 解析 JSON 响应体；不成形就是上游失败。 */
+export function parseJson<T>(label: string, text: string): T {
+  try {
+    return JSON.parse(text) as T;
+  } catch {
+    throw new WebSearchUpstreamError(`${label} 返回了无法解析的响应体`);
+  }
+}
+
+/** OpenAI 形状的错误体 `{error: {code, message}}`；其余形状当没有。 */
+export function parseErrorBody(text: string): {
+  code: string | undefined;
+  message: string | undefined;
+} {
+  try {
+    const body = JSON.parse(text) as {
+      error?: { code?: unknown; message?: unknown };
+    };
+    return {
+      code: codeOf(body.error?.code),
+      message:
+        typeof body.error?.message === 'string'
+          ? body.error.message
+          : undefined,
+    };
+  } catch {
+    return { code: undefined, message: undefined };
+  }
+}
+
+/** 错误码有时是字符串有时是数字，统一成字符串；其余形状当没有。 */
+export function codeOf(value: unknown): string | undefined {
+  return typeof value === 'string' || typeof value === 'number'
+    ? String(value)
+    : undefined;
+}
+
+/** 错误详情别整段回灌（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}`;
+}