web_search 支持自建 /search 上游:上游参数逐请求由 header 带入

与 image_task / asr 同构:容器不存密钥,配置只写在 config.yml 的 mcp_servers[].headers。

- 新增 X-Web-Search-Base-Url(拼 /search)与可选 Authorization(裸 key 自动补 Bearer);
  配了地址就以它为准,失败直接报错,不静默退回免费后端
- 没配地址时行为不变:Parallel 优先,失败自动退 Exa(降级从前端 provider 参数收回服务端)
- 工具 schema 去掉 provider 参数(模型不该决定走哪家上游),只留 query / numResults
- 响应统一归一化:丢弃无 url 条目,snippet 压平并截断 500 字,published_at 映射为 publishedAt
- server.js 把 req.headers 传进协议层;stdio 模式无 header,只能用免费后端
- 设置页预设补两条可选字段(settings.js 无需改动,纯数据驱动)
This commit is contained in:
2026-11-02 20:28:10 +08:00
parent 509d63a99b
commit 10877c9723
7 changed files with 221 additions and 33 deletions
+93 -5
View File
@@ -1,9 +1,13 @@
/**
* 零依赖搜索核心:Parallel(默认,匿名免 key)与 Exa(备用)两个免费后端的统一封装。
* 零依赖搜索核心:三路上游,统一归一化成 `{ url, title?, snippet?, publishedAt? }[]`。
*
* 只用 Node 内置 fetch,不依赖任何 npm 包。两个后端都是公开的免费 MCP 端点,
* 本模块以 JSON-RPC `tools/call` 的方式直接调用它们,并归一化成统一的结果结构:
* `{ url, title?, snippet?, publishedAt? }[]`。
* - 自定义上游(`X-Web-Search-Base-Url` + `Authorization`):任意 `POST {base}/search`,
* 请求体 `{ query, max_results }`、响应 `{ results: [{ title, url, snippet }] }`。
* - Parallel(免费匿名 MCP 端点,默认后端)。
* - Exa(免费 MCP 端点,Parallel 挂掉时的兜底)。
*
* 只用 Node 内置 fetch,不依赖任何 npm 包。免费侧两个后端都是公开的 MCP 端点,
* 本模块以 JSON-RPC `tools/call` 的方式直接调用它们。
*
* 上游实现参考:@sheep233_/dsh-web-search-free(github.com/sheep-programmer/dsh-web-search-free)。
*/
@@ -13,9 +17,20 @@ export const PARALLEL_MCP_URL = 'https://search.parallel.ai/mcp';
/** Exa 免费 MCP 端点(匿名可用;EXA_API_KEY 可提升限额)。 */
export const EXA_MCP_URL = 'https://mcp.exa.ai/mcp';
const USER_AGENT = 'web_search/1.0.0';
const USER_AGENT = 'web_search/1.1.0';
/** 单次上游搜索请求的超时,避免远端挂起拖死 MCP 请求。 */
const REQUEST_TIMEOUT_MS = Number(process.env.SEARCH_TIMEOUT_MS ?? 30_000);
/**
* snippet 一律截断:搜索结果会进历史,之后每一轮都可能被整条重放。
* 有些上游(如自建 v1/search)的 snippet 是整段正文,不截等于白烧 token。
*/
const SNIPPET_MAX_CHARS = 500;
/** 压平空白并截断;空串返回 ''(调用方据此决定要不要带这个字段)。 */
export function capSnippet(text) {
const s = String(text == null ? '' : text).replace(/\s+/g, ' ').trim();
return s.length > SNIPPET_MAX_CHARS ? s.slice(0, SNIPPET_MAX_CHARS) + '…' : s;
}
/**
* 向免费 MCP 端点发一次 `tools/call`,返回工具结果里的 text 载荷。
@@ -124,6 +139,61 @@ export function parseExaText(text) {
return sources;
}
/**
* 自定义上游:`POST {base}/search`,body `{ query, max_results }`。
* 配置了地址就以它为准——失败直接抛错,不静默退回免费后端(否则 key 过期/base 写错
* 只会表现为「结果质量突然变差」,永远没人发现)。
* @param {{ auth: string, base: string }} up 由 mcp.js 从请求 header 解析(容器不存密钥)
*/
export async function customSearch(query, maxResults, up) {
const url = up.base.replace(/\/+$/, '') + '/search';
const headers = {
'content-type': 'application/json',
'accept': 'application/json',
'user-agent': USER_AGENT,
};
// 免鉴权的自建服务可省;有值才带,避免给上游塞一个空 Authorization 反而被拒
if (up.auth) headers.authorization = up.auth;
let response;
try {
response = await fetch(url, {
method: 'POST',
// 不跟随跳转:Authorization 不能被顺手带到别的地址去
redirect: 'error',
headers,
body: JSON.stringify({ query, max_results: maxResults }),
signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
});
} catch (error) {
throw new Error(`搜索上游请求失败(${url}):${String(error && error.message || error)}`);
}
const raw = await response.text();
if (!response.ok) {
// 带上游响应片段:401 和 500 的处置完全不同,只说「请求失败」没法排查
const detail = capSnippet(raw).slice(0, 200);
throw new Error(`搜索上游 HTTP ${response.status}${detail ? ':' + detail : ''}`);
}
let payload;
try {
payload = JSON.parse(raw);
} catch (error) {
throw new Error(`搜索上游返回了无法解析的响应:${String(error)}`);
}
const sources = [];
for (const item of payload.results ?? []) {
if (!item || !item.url) continue;
const snippet = capSnippet(item.snippet);
const publishedAt = item.published_at ?? item.publishedAt ?? item.publish_date;
sources.push({
url: String(item.url),
...(item.title ? { title: String(item.title) } : {}),
...(snippet ? { snippet } : {}),
...(publishedAt ? { publishedAt: String(publishedAt) } : {}),
});
}
return maxResults !== undefined ? sources.slice(0, maxResults) : sources;
}
/** Parallel 搜索(默认免费后端)。 */
export async function parallelSearch(query, maxResults) {
const text = await callMcpTool(PARALLEL_MCP_URL, 'web_search', {
@@ -134,6 +204,24 @@ export async function parallelSearch(query, maxResults) {
return maxResults !== undefined ? sources.slice(0, maxResults) : sources;
}
/**
* 免费侧入口:Parallel 优先,失败自动退 Exa。
* 降级放在服务端(而不是让模型显式传 provider)——模型看不到后端,也就不会选错。
* @param {string} [exaApiKey] 可选,提升 Exa 匿名限额
*/
export async function freeSearch(query, maxResults, exaApiKey) {
try {
return await parallelSearch(query, maxResults);
} catch (first) {
try {
return await exaSearch(query, maxResults, exaApiKey);
} catch (second) {
throw new Error(`免费搜索后端均不可用(parallel: ${String(first && first.message || first)};` +
`exa: ${String(second && second.message || second)})`);
}
}
}
/** Exa 搜索(备用免费后端;apiKey 可选,用于提升匿名限额)。 */
export async function exaSearch(query, maxResults, apiKey) {
const endpoint = apiKey