@qjp88995/provider-client 0.1.1 → 0.3.0

package/src/provider-client.ts

@@ -1,5 +1,18 @@
-import { createCenterFetch } from './center-fetch.js';
+import { type CenterFetchOptions, createCenterFetch } from './center-fetch.js';
 import { errorFromResponse, ProviderClientError } from './errors.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 +23,46 @@ 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 {
+  /** 会话粘性键（`x-pc-affinity`）：建异步任务与轮询带同一个，就落在同一把 key 上（只要它还可用）。 */
+  affinity?: string;
+  /** 钉住某把 key（`x-pc-pin`）：那把不可用就直接报错，不换。 */
+  pin?: string;
+  /** 每次响应回来时告诉调用方实际用的是哪把 key（`x-pc-credential`）。 */
+  onCredential?: (ref: string) => void;
+}
 
 export interface ProviderClientOptions {
   /** 中心的根地址，如 `https://provider.example.com`。 */
@@ -93,6 +146,199 @@ export class ProviderClient implements ModelResolver {
     });
   }
 
+  /**
+   * 某家厂商的中心模式 fetch，交给 APP 自己的适配器（联网搜索、媒体解析、JustOne 这类不走模型句柄的调用）：
+   * 适配器照常用厂商的地址发请求，这个 fetch 把它改写到中心透传。可改写的 origin 取自目录里这家的端点，
+   * 非 LLM 厂商同样可用；适配器该用哪个 baseUrl 见 `catalog()` 里这家的 `endpoints`。
+   * 目录只在创建时查一次；目录里没有这家（或这个接入方看不到）时报 `unknown_vendor`。
+   */
+  async fetchFor(
+    slug: string,
+    options: FetchForOptions = {}
+  ): Promise<VendorFetch> {
+    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
+      );
+    }
+    return 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,
+    });
+  }
+
+  /**
+   * 某家厂商的联网搜索 / 读网页（适配器在本包，请求经中心透传、中心注入 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）：智谱的文件解析 / 语音转写（地址取自这家的
+   * `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
@@ -134,3 +380,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,11 +13,27 @@ export const LLM_PROTOCOLS = [
 ] as const;
 export type LlmProtocol = (typeof LLM_PROTOCOLS)[number];
 
+/**
+ * 端点协议：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）。 */
+export const VENDOR_CATEGORIES = ['llm', 'media', 'data'] as const;
+export type VendorCategory = (typeof VENDOR_CATEGORIES)[number];
+
 /** 模型能力（目录元数据：发不发图片 / 开不开推理由调用方据此决定）。 */
 export const LLM_CAPABILITIES = ['vision', 'video', 'reasoning'] as const;
 export type LlmCapability = (typeof LLM_CAPABILITIES)[number];
 
-/** 厂商类型。一种类型对应一个适配器（`VENDOR_ADAPTERS`）。 */
+/** 厂商类型。`llm` 类别的每一种对应一个适配器（`VENDOR_ADAPTERS`）；bibigpt / justone 没有。 */
 export const VENDOR_KINDS = [
   'openai',
   'generic',
@@ -29,6 +45,8 @@ export const VENDOR_KINDS = [
   'minimax',
   'dots',
   'google',
+  'bibigpt',
+  'justone',
 ] as const;
 export type VendorKind = (typeof VENDOR_KINDS)[number];
 
@@ -70,12 +88,14 @@ export interface CatalogVendor {
   slug: string;
   name: string;
   kind: VendorKind;
+  /** 非 `llm` 的厂商没有模型，接入方只拿它的端点经中心透传。 */
+  category: VendorCategory;
   endpoints: CatalogEndpoint[];
   models: CatalogModel[];
 }
 
 export interface CatalogEndpoint {
-  protocol: LlmProtocol;
+  protocol: EndpointProtocol;
   baseUrl: string;
 }
 
@@ -105,6 +125,7 @@ export const CENTER_ERROR_CODES = [
   'vendor_not_allowed',
   'no_credential',
   'pinned_credential_unavailable',
+  'payload_too_large',
 ] as const;
 export type CenterErrorCode = (typeof CENTER_ERROR_CODES)[number];
 

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}`;
+}

package/src/web-search/index.ts

@@ -0,0 +1,70 @@
+import { DeepseekWebSearchAdapter } from './deepseek.adapter.js';
+import { MinimaxWebSearchAdapter } from './minimax.adapter.js';
+import { MoonshotaiWebSearchAdapter } from './moonshotai.adapter.js';
+import type {
+  WebPageOutcome,
+  WebSearchAdapter,
+  WebSearchConnection,
+  WebSearchInput,
+  WebSearchKind,
+  WebSearchOutcome,
+  WebSearchSettings,
+  WebSearchTraits,
+} from './types.js';
+import { ZhipuWebSearchAdapter } from './zhipu.adapter.js';
+
+/** kind → 适配器。映射类型保证每个 kind 都有、且设置类型对得上；加一家漏了这里编译报错。 */
+export const WEB_SEARCH_ADAPTERS: {
+  readonly [K in WebSearchKind]: WebSearchAdapter<K>;
+} = {
+  deepseek: new DeepseekWebSearchAdapter(),
+  moonshotai: new MoonshotaiWebSearchAdapter(),
+  minimax: new MinimaxWebSearchAdapter(),
+  zhipu: new ZhipuWebSearchAdapter(),
+};
+
+export function isWebSearchKind(kind: string): kind is WebSearchKind {
+  return Object.hasOwn(WEB_SEARCH_ADAPTERS, kind);
+}
+
+/** 一家联网服务，连接与设置都已绑好。`readPage` 只在 `traits.readsPages` 时存在。 */
+export interface WebSearch {
+  readonly kind: WebSearchKind;
+  readonly traits: WebSearchTraits;
+  search(input: WebSearchInput, signal: AbortSignal): Promise<WebSearchOutcome>;
+  readPage?(
+    input: { url: string },
+    signal: AbortSignal
+  ): Promise<WebPageOutcome>;
+}
+
+export interface CreateWebSearchInput<K extends WebSearchKind> {
+  kind: K;
+  connection: WebSearchConnection;
+  settings?: WebSearchSettings<K>;
+}
+
+/**
+ * 绑好连接与设置的联网服务。中心模式用 `ProviderClient.webSearch`；这里是直连（本地开发、测试）与中心模式共用的底层：
+ * 直连时 `connection` 给厂商的 `web-search` 根地址 + `apiKey`。
+ */
+export function createWebSearch<K extends WebSearchKind>(
+  input: CreateWebSearchInput<K>
+): WebSearch {
+  // 映射类型按 K 取出来是联合，TS 收窄不了泛型索引；kind 与 settings 由签名绑在一起。
+  const adapter = WEB_SEARCH_ADAPTERS[input.kind] as WebSearchAdapter<K>;
+  const settings = (input.settings ?? {}) as WebSearchSettings<K>;
+  const conn = input.connection;
+  const traits = adapter.traits(settings);
+  const readPage = adapter.readPage?.bind(adapter);
+  return {
+    kind: input.kind,
+    traits,
+    search: (q, signal) => adapter.search(conn, settings, q, signal),
+    ...(readPage
+      ? { readPage: (q, signal) => readPage(conn, settings, q, signal) }
+      : {}),
+  };
+}
+
+export * from './types.js';