@qjp88995/provider-client 0.2.0 → 0.3.0

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

@@ -0,0 +1,184 @@
+import {
+  clip,
+  codeOf,
+  joinUrl,
+  parseErrorBody,
+  parseJson,
+  postJson,
+} from './http.js';
+import {
+  type WebPageOutcome,
+  type WebSearchAdapter,
+  type WebSearchConnection,
+  type WebSearchInput,
+  type WebSearchOutcome,
+  type WebSearchSettings,
+  type WebSearchTraits,
+  WebSearchUpstreamError,
+  type ZhipuSearchEngine,
+} 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: ZhipuSearchEngine = 'search_pro';
+
+/** reader 让智谱侧抓取页面的预算（秒）——上游参数，不是本地超时。 */
+const READER_FETCH_TIMEOUT_SECONDS = 20;
+
+interface ZhipuSearchBody {
+  search_result?: {
+    title?: string;
+    link?: string;
+    content?: string;
+    media?: string;
+    publish_date?: string;
+  }[];
+}
+
+interface ZhipuReaderBody {
+  reader_result?: {
+    content?: string;
+    title?: string;
+    description?: string;
+    url?: string;
+  };
+}
+
+type Settings = WebSearchSettings<'zhipu'>;
+
+/** 智谱「工具 API」：联网搜索（web_search）+ 网页阅读（reader）。 */
+export class ZhipuWebSearchAdapter implements WebSearchAdapter<'zhipu'> {
+  readonly kind = 'zhipu' as const;
+
+  traits(settings: Settings): WebSearchTraits {
+    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: WebSearchConnection,
+    settings: Settings,
+    input: WebSearchInput,
+    signal: AbortSignal
+  ): Promise<WebSearchOutcome> {
+    const engine = settings.searchEngine ?? DEFAULT_ENGINE;
+    const body: Record<string, unknown> = {
+      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: ZhipuSearchBody;
+    try {
+      data = await this.post<ZhipuSearchBody>('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: WebSearchConnection,
+    _settings: Settings,
+    input: { url: string },
+    signal: AbortSignal
+  ): Promise<WebPageOutcome> {
+    const data = await this.post<ZhipuReaderBody>(
+      '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,
+    };
+  }
+
+  private async post<T>(
+    path: 'web_search' | 'reader',
+    conn: WebSearchConnection,
+    body: Record<string, unknown>,
+    signal: AbortSignal
+  ): Promise<T> {
+    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<unknown>(label, res.text);
+    // 智谱部分接口会用 200 + error 体报业务错误，别把它当成功往下传。
+    const errBody = (json as { error?: { code?: unknown; message?: unknown } })
+      .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 as T;
+  }
+}