@qjp88995/provider-client 0.2.0 → 0.4.0

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';

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

@@ -0,0 +1,148 @@
+import { clip, codeOf, joinUrl, parseJson, postJson } from './http.js';
+import {
+  type WebSearchAdapter,
+  type WebSearchConnection,
+  type WebSearchFilter,
+  type WebSearchInput,
+  type WebSearchOutcome,
+  type WebSearchSettings,
+  type WebSearchTraits,
+  WebSearchUpstreamError,
+} from './types.js';
+
+/**
+ * MiniMax 联网搜索（`/v1/coding_plan/search`）。**官方没有文档页**（2026-10-24 只找到
+ * OpenClaw / Hermes 的第三方集成文档，两家对参数名说法还不一），下面每一条都是真机探测
+ * 出来的：请求体键是 `q`（`query` 回 2013）；没有条数参数（`num` / `count` / `limit` 一律
+ * 回 10 条）；查询里的 `site:` 不生效、`after:` 只是影响排序（仍混进更早的结果）。
+ * 普通 key 有余额就认，不必是 Token Plan key。
+ *
+ * `web-search` 端点的根是 `https://api.minimaxi.com/v1/coding_plan`（国际站 `api.minimax.io`，两站 key 不通用，
+ * 在中心是两家厂商）——**与对话端点不同域**，这正是端点要按协议分开登记的原因。
+ *
+ * 没有读网页接口：不实现 `readPage`，`traits().readsPages` 为 false。
+ */
+
+/** 失败也常是 HTTP 200：判据是 `base_resp.status_code`，0 才算成功。 */
+interface MinimaxSearchBody {
+  base_resp?: { status_code?: number; status_msg?: string };
+  organic?: {
+    title?: string;
+    link?: string;
+    snippet?: string;
+    /** `2026/05/05 00:00:00` 或空串。 */
+    date?: string;
+  }[];
+}
+
+type Settings = WebSearchSettings<'minimax'>;
+
+/** 上游定死的条数（实测没有条数参数）。 */
+const UPSTREAM_COUNT = 10;
+
+/**
+ * 时间 / 域名过滤一律报回 `ignored`、不拼进查询：实测两种操作符都靠不住，拼进去只会
+ * 改变关键词本身。条数上游定死 10 条，`count` 在本地截。
+ */
+export class MinimaxWebSearchAdapter implements WebSearchAdapter<'minimax'> {
+  readonly kind = 'minimax' as const;
+
+  traits(): WebSearchTraits {
+    return {
+      readsPages: false,
+      maxResults: UPSTREAM_COUNT,
+      filters: [],
+      linksOftenMissing: false,
+      pageImagesArePlaceholders: false,
+    };
+  }
+
+  async search(
+    conn: WebSearchConnection,
+    _settings: Settings,
+    input: WebSearchInput,
+    signal: AbortSignal
+  ): Promise<WebSearchOutcome> {
+    const label = 'minimax search';
+    const res = await postJson(
+      label,
+      joinUrl(conn.baseUrl, 'search'),
+      conn,
+      { q: input.query },
+      signal
+    );
+    const data = parseBody(label, res.status, res.text);
+    const code = data.base_resp?.status_code;
+    if (!res.ok || code !== 0) {
+      throw upstreamError(label, res.status, code, data.base_resp?.status_msg);
+    }
+
+    const items = (data.organic ?? []).map(r => ({
+      title: r.title ?? '',
+      link: r.link ?? '',
+      content: r.snippet ?? '',
+      media: null,
+      publishDate: r.date || null,
+    }));
+    const ignored: WebSearchFilter[] = [
+      ...(input.recency ? (['recency'] as const) : []),
+      ...(input.domain ? (['domain'] as const) : []),
+    ];
+    return {
+      engine: 'minimax',
+      items: input.count !== undefined ? items.slice(0, input.count) : items,
+      ...(ignored.length ? { ignored } : {}),
+    };
+  }
+}
+
+/** 4xx / 5xx 也可能带 `base_resp`（参数错是 400 + 2013）；不成形的非 2xx 当没有错误体。 */
+function parseBody(
+  label: string,
+  status: number,
+  text: string
+): MinimaxSearchBody {
+  if (status >= 200 && status < 300) return parseJson(label, text);
+  try {
+    return JSON.parse(text) as MinimaxSearchBody;
+  } catch {
+    return { base_resp: { status_msg: clip(text) } };
+  }
+}
+
+function upstreamError(
+  label: string,
+  status: number,
+  code: number | undefined,
+  msg: string | undefined
+): WebSearchUpstreamError {
+  const hint = code !== undefined ? CODE_HINTS[code] : undefined;
+  const head = code !== undefined ? `${label} ${code}` : `${label} ${status}`;
+  return new WebSearchUpstreamError(
+    `${head}${hint ? `（${hint}）` : ''}${msg ? `: ${msg}` : ''}`,
+    {
+      code: codeOf(code),
+      retryable:
+        status >= 500 ||
+        status === 429 ||
+        (code !== undefined && RETRYABLE_CODES.has(code)),
+    }
+  );
+}
+
+/**
+ * MiniMax 通用错误码里表示「稍后再试有用」的：未知错误、超时、限流（RPM / TPM）、
+ * 服务内部错误。鉴权、余额、参数类改了请求或账户才有用。
+ */
+const RETRYABLE_CODES: ReadonlySet<number> = new Set([
+  1000, 1001, 1002, 1013, 1024, 1033, 1039,
+]);
+
+/** 实测见过、或 MiniMax 通用错误码里含义确定的，带进错误文案让模型 / 运营不必去查。 */
+const CODE_HINTS: Readonly<Record<number, string>> = {
+  1002: '超过频率上限',
+  1004: 'API key 无效或没带上',
+  1008: '账户余额不足，需要充值',
+  2013: '请求参数不合法',
+  2049: 'API key 无效，或与所选站点不匹配',
+};

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

@@ -0,0 +1,228 @@
+import { clip, codeOf, joinUrl, parseJson, postJson } from './http.js';
+import {
+  recencySince,
+  utcDate,
+  type WebPageOutcome,
+  type WebSearchAdapter,
+  type WebSearchConnection,
+  type WebSearchFilter,
+  type WebSearchInput,
+  type WebSearchOutcome,
+  type WebSearchSettings,
+  type WebSearchTraits,
+  WebSearchUpstreamError,
+} from './types.js';
+
+/**
+ * Kimi 工具网关（<https://platform.kimi.com/docs/api/tools-search>）：搜索基础版 `/search`、
+ * 专业版 `/search_pro`、网页抓取 `/fetch`。与对话 API 同一把 Bearer key；`web-search` 端点的根是
+ * `https://api.moonshot.cn/v1/tools`（国际站 `api.moonshot.ai`，两站账号与 key 不通用，在中心是两家厂商）。
+ * 专业版与抓取的文档只列了国内站，国际站沿用同一组路径。
+ *
+ * **不是 Formula 的 `moonshot/web-search`**：那个回 `encrypted_output`，只有 Kimi 模型读得了。
+ */
+/** 文档：两档的 `limit` 都是 1–20。工具层允许到 50，超出的压到上限而不是让上游 400。 */
+const MAX_LIMIT = 20;
+
+/** 文档：每个字段都是字符串，没有数据时是空串。 */
+interface KimiSearchBody {
+  search_results?: {
+    title?: string;
+    url?: string;
+    snippet?: string;
+    site_name?: string;
+    date?: string;
+    /** 只有专业版有：按相关性打分的正文片段，没正文时是空数组。 */
+    chunks?: { text?: string; score?: number }[];
+  }[];
+}
+
+interface KimiFetchBody {
+  url?: string;
+  title?: string;
+  /** 正文与图片按页面顺序拼接，图片是 `![imageN](url)` 占位。 */
+  markdown?: string;
+}
+
+type Settings = WebSearchSettings<'moonshotai'>;
+
+/**
+ * 基础版没有时间 / 域名过滤字段，给了就报回 `ignored`——文档没说认 `site:` 之类的操作符，
+ * 拼进查询是在猜。专业版有 `sites` 与 `time_window`，两项都施加。`include_content` 不开：
+ * 会把每条结果的全文塞回来，体量没有上限。
+ */
+export class MoonshotaiWebSearchAdapter implements WebSearchAdapter<'moonshotai'> {
+  readonly kind = 'moonshotai' as const;
+
+  constructor(private readonly now: () => Date = () => new Date()) {}
+
+  traits(settings: Settings): WebSearchTraits {
+    return {
+      readsPages: true,
+      maxResults: MAX_LIMIT,
+      filters: settings.searchTier === 'pro' ? ['recency', 'domain'] : [],
+      linksOftenMissing: false,
+      // 抓取的正文里图片是占位符（`![imageN](url)`），模型得知道那不是它能看的图。
+      pageImagesArePlaceholders: true,
+    };
+  }
+
+  async search(
+    conn: WebSearchConnection,
+    settings: Settings,
+    input: WebSearchInput,
+    signal: AbortSignal
+  ): Promise<WebSearchOutcome> {
+    const pro = settings.searchTier === 'pro';
+    const label = pro ? 'kimi search_pro' : 'kimi search';
+    const body: Record<string, unknown> = {
+      text_query: input.query,
+      ...(input.count !== undefined
+        ? { limit: Math.min(input.count, MAX_LIMIT) }
+        : {}),
+      ...(pro && input.domain ? { sites: [input.domain] } : {}),
+      ...(pro && input.recency
+        ? {
+            time_window: {
+              start: recencySince(input.recency, this.now()),
+              end: utcDate(this.now()),
+            },
+          }
+        : {}),
+    };
+    const res = await postJson(
+      label,
+      joinUrl(conn.baseUrl, pro ? 'search_pro' : 'search'),
+      conn,
+      body,
+      signal
+    );
+    if (!res.ok) throw upstreamError(label, res.status, res.text);
+
+    const data = parseJson<KimiSearchBody>(label, res.text);
+    const items = (data.search_results ?? []).map(r => ({
+      title: r.title ?? '',
+      link: r.url ?? '',
+      content: r.snippet || bestChunk(r.chunks) || '',
+      media: r.site_name || null,
+      publishDate: r.date || null,
+    }));
+    const ignored: WebSearchFilter[] = pro
+      ? []
+      : [
+          ...(input.recency ? (['recency'] as const) : []),
+          ...(input.domain ? (['domain'] as const) : []),
+        ];
+    return {
+      engine: pro ? 'kimi-pro' : 'kimi',
+      items,
+      ...(ignored.length ? { ignored } : {}),
+    };
+  }
+
+  async readPage(
+    conn: WebSearchConnection,
+    _settings: Settings,
+    input: { url: string },
+    signal: AbortSignal
+  ): Promise<WebPageOutcome> {
+    const label = 'kimi fetch';
+    const res = await postJson(
+      label,
+      joinUrl(conn.baseUrl, 'fetch'),
+      conn,
+      { url: input.url },
+      signal
+    );
+    if (!res.ok) {
+      const err = errorBodyOf(res.text);
+      // 「读到了但没有可提取的正文」不是故障（也不计费）：交给工具层说「正文为空」，
+      // 别让模型当成链接坏了去重试。
+      if (res.status === 404 && err.type === 'markdown_not_found') {
+        return { url: input.url, title: null, description: null, content: '' };
+      }
+      throw upstreamError(label, res.status, res.text);
+    }
+    const data = parseJson<KimiFetchBody>(label, res.text);
+    if (typeof data.markdown !== 'string') {
+      throw new WebSearchUpstreamError('kimi fetch 响应缺少 markdown');
+    }
+    return {
+      url: data.url || input.url,
+      title: data.title || null,
+      description: null,
+      content: data.markdown,
+    };
+  }
+}
+
+/** 专业版的摘要偶尔为空，退回得分最高的正文片段。 */
+function bestChunk(
+  chunks: { text?: string; score?: number }[] | undefined
+): string | undefined {
+  let best: { text?: string; score?: number } | undefined;
+  for (const c of chunks ?? []) {
+    if (!c.text) continue;
+    if (!best || (c.score ?? 0) > (best.score ?? 0)) best = c;
+  }
+  return best?.text;
+}
+
+/**
+ * 错误体是 `{error: {message, type, code?}}`，判别靠 `type`（`rate_limited` /
+ * `upstream_failed` …）；401 / 403 没有错误体（抓取的 403 `security_risk` 有）。
+ */
+function upstreamError(
+  label: string,
+  status: number,
+  text: string
+): WebSearchUpstreamError {
+  const err = errorBodyOf(text);
+  const detail = err.message ?? clip(text);
+  const hint =
+    (err.type ? TYPE_HINTS[err.type] : undefined) ?? STATUS_HINTS[status];
+  return new WebSearchUpstreamError(
+    `${label} ${status}${hint ? `（${hint}）` : ''}${detail ? `: ${detail}` : ''}`,
+    {
+      code: err.type ?? err.code,
+      // 文档：429（限流 / 限流服务不可用）、500、502、504 稍后重试；400 / 403 改请求才有用。
+      retryable: status >= 500 || status === 429,
+    }
+  );
+}
+
+function errorBodyOf(text: string): {
+  type: string | undefined;
+  code: string | undefined;
+  message: string | undefined;
+} {
+  try {
+    const body = JSON.parse(text) as {
+      error?: { type?: unknown; code?: unknown; message?: unknown };
+    };
+    return {
+      type: codeOf(body.error?.type),
+      code: codeOf(body.error?.code),
+      message:
+        typeof body.error?.message === 'string'
+          ? body.error.message
+          : undefined,
+    };
+  } catch {
+    return { type: undefined, code: undefined, message: undefined };
+  }
+}
+
+/** 文档里有确定含义的状态码，带进错误文案让模型 / 运营不必去查。 */
+const STATUS_HINTS: Readonly<Record<number, string>> = {
+  401: 'API key 无效，或与所选站点不匹配',
+  403: '账户未激活或已停用',
+  429: '超过频率或并发上限',
+  504: '超时，搜索就换个更短的关键词，读网页就稍后再试',
+};
+
+/** 同一个状态码含义不止一种时按 `type` 区分（抓取的 403 不是账户问题）。 */
+const TYPE_HINTS: Readonly<Record<string, string>> = {
+  security_risk: '这个网址被 Kimi 的安全策略拦下，换一个网址，重试没用',
+  invalid_url: '网址不合法，只支持 http / https',
+};

package/src/web-search/types.ts

@@ -0,0 +1,172 @@
+import type { VendorFetch } from '../vendors/index.js';
+
+/**
+ * 联网搜索 / 读网页的厂商适配（从 agent-base `web-search/adapters` 搬来）。适配器只管「这家的请求长什么样、
+ * 响应怎么翻、哪些失败值得重试」；给模型看的工具说明是 APP 的事，适配器只交出事实（`WebSearchTraits`）。
+ */
+
+/** 时效过滤取值（缺省 = 不限时间）。各适配器自己翻成上游的写法。 */
+export const WEB_SEARCH_RECENCIES = [
+  'oneDay',
+  'oneWeek',
+  'oneMonth',
+  'oneYear',
+] as const;
+export type WebSearchRecency = (typeof WEB_SEARCH_RECENCIES)[number];
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const RECENCY_DAYS: Readonly<Record<WebSearchRecency, number>> = {
+  oneDay: 1,
+  oneWeek: 7,
+  oneMonth: 30,
+  oneYear: 365,
+};
+
+/** 「最近一段时间」的起始日期（UTC，YYYY-MM-DD）——上游只收日期的家（DeepSeek、Kimi 专业版）共用。 */
+export function recencySince(recency: WebSearchRecency, now: Date): string {
+  return utcDate(new Date(now.getTime() - RECENCY_DAYS[recency] * DAY_MS));
+}
+
+/** UTC 日期 YYYY-MM-DD。 */
+export function utcDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+export interface WebSearchInput {
+  query: string;
+  count?: number;
+  recency?: WebSearchRecency;
+  domain?: string;
+}
+
+export interface WebSearchItem {
+  title: string;
+  link: string;
+  /** 搜索引擎给的摘要，不是网页全文。 */
+  content: string;
+  /** 来源站点 / 媒体名（常为空）。 */
+  media: string | null;
+  publishDate: string | null;
+}
+
+/** 搜索的两项过滤。不是每家都支持（Kimi 基础版、MiniMax 都没有），不支持的由适配器报回 `ignored`。 */
+export const WEB_SEARCH_FILTERS = ['recency', 'domain'] as const;
+export type WebSearchFilter = (typeof WEB_SEARCH_FILTERS)[number];
+
+export interface WebSearchOutcome {
+  /** 「用的是哪个引擎」（智谱是档位名，其余是服务名）。 */
+  engine: string;
+  items: WebSearchItem[];
+  /**
+   * 调用方给了、这家却没法施加的过滤（缺省 = 都施加了）。调用方据此说破，别让模型以为
+   * 结果已经按时间 / 域名筛过。
+   */
+  ignored?: readonly WebSearchFilter[];
+}
+
+export interface WebPageOutcome {
+  url: string;
+  title: string | null;
+  description: string | null;
+  /** markdown 正文。可能为空串（纯脚本渲染 / 反爬页面、Kimi 的「没有可提取的正文」），由调用方解释。 */
+  content: string;
+}
+
+/**
+ * 调一次上游要的东西：这家 `web-search` 端点的根地址与出站 fetch。中心模式下 fetch 是中心的透传 fetch、
+ * 不带 key（中心注入）；直连模式给 `apiKey`，适配器以 Bearer 发出。
+ */
+export interface WebSearchConnection {
+  baseUrl: string;
+  fetch: VendorFetch;
+  apiKey?: string;
+}
+
+/** 智谱的搜索档位（`search_engine`）。 */
+export const ZHIPU_SEARCH_ENGINES = [
+  'search_std',
+  'search_pro',
+  'search_pro_sogou',
+  'search_pro_quark',
+] as const;
+export type ZhipuSearchEngine = (typeof ZHIPU_SEARCH_ENGINES)[number];
+
+/** Kimi 搜索：基础版 `/search`、专业版 `/search_pro`。 */
+export const KIMI_SEARCH_TIERS = ['basic', 'pro'] as const;
+export type KimiSearchTier = (typeof KIMI_SEARCH_TIERS)[number];
+
+/**
+ * 各家的设置（APP 存、调用时传；缺省值见各适配器）。**站点（国内 / 海外）不是设置**：两站账号与 key 不通用，
+ * 在中心是两家厂商，地址取自各自的 `web-search` 端点。
+ */
+export interface WebSearchSettingsByKind {
+  deepseek: Record<string, never>;
+  moonshotai: { searchTier?: KimiSearchTier };
+  minimax: Record<string, never>;
+  zhipu: { searchEngine?: ZhipuSearchEngine };
+}
+export type WebSearchKind = keyof WebSearchSettingsByKind;
+export const WEB_SEARCH_KINDS = [
+  'deepseek',
+  'moonshotai',
+  'minimax',
+  'zhipu',
+] as const satisfies readonly WebSearchKind[];
+export type WebSearchSettings<K extends WebSearchKind = WebSearchKind> =
+  WebSearchSettingsByKind[K];
+
+/**
+ * 这家（在这组设置下）的能力事实，给调用方写工具说明用。只依赖设置，不依赖「现在」——写进工具表的东西
+ * 相邻两轮必须一样。
+ */
+export interface WebSearchTraits {
+  /** 有读网页接口（MiniMax 没有）。 */
+  readsPages: boolean;
+  /** 一次最多返回几条；null = 没有比调用方更紧的上限。 */
+  maxResults: number | null;
+  /** 真能施加的过滤；不在里面的给了也会报回 `ignored`。 */
+  filters: readonly WebSearchFilter[];
+  /** 结果常不带链接（智谱 search_std，真机探针 2026-08-31）：「把链接交给读网页」常走不通。 */
+  linksOftenMissing: boolean;
+  /** 读网页的正文里图片只以 `![imageN](url)` 占位（Kimi），看不到图片内容。 */
+  pageImagesArePlaceholders: boolean;
+}
+
+export interface WebSearchAdapter<K extends WebSearchKind> {
+  readonly kind: K;
+  traits(settings: WebSearchSettings<K>): WebSearchTraits;
+  search(
+    conn: WebSearchConnection,
+    settings: WebSearchSettings<K>,
+    input: WebSearchInput,
+    signal: AbortSignal
+  ): Promise<WebSearchOutcome>;
+  /** 没有读网页接口的家（MiniMax）不实现，`traits().readsPages` 同步写 false（spec 钉着）。 */
+  readPage?(
+    conn: WebSearchConnection,
+    settings: WebSearchSettings<K>,
+    input: { url: string },
+    signal: AbortSignal
+  ): Promise<WebPageOutcome>;
+}
+
+/**
+ * 联网服务的上游失败（非 2xx / 网络错误 / 响应体不成形 / 2xx 里的业务错误）。中心自己报的错（没有可用 key、
+ * 接入方不许用这家……）不是这个，是 `ProviderClientError`。
+ */
+export class WebSearchUpstreamError extends Error {
+  override readonly name = 'WebSearchUpstreamError';
+  /** 上游业务错误码（智谱的 '1701' 并发超限、DeepSeek 的 error.code、Kimi 的 error.type），没有就是 null。 */
+  readonly code: string | null;
+  /** 这次失败值不值得重试。判据收在各适配器的抛出处，调用方只读这个标志，不解析消息文本。 */
+  readonly retryable: boolean;
+
+  constructor(
+    reason: string,
+    opts: { code?: string; retryable?: boolean } = {}
+  ) {
+    super(reason);
+    this.code = opts.code ?? null;
+    this.retryable = opts.retryable ?? false;
+  }
+}