联网搜索

SDK 自带的 WebSearch / WebFetch 是 Anthropic 第一方服务端工具， 一旦会话走第三方 OpenAI 兼容供应商就会被剥离。Spark Work 因此内置了独立的 spark_search MCP server：它在本地 Node 子进程里自己发 HTTP，与模型供应商完全解耦， 对普通会话与团队成员默认挂载，零配置即可用。

1. 工具与返回结构

命名空间是 mcp__spark_search__，只有两个工具（SDK 允许清单里的名字就是下面这两个）：

time_range 只对 keyed 后端（bocha / tavily / serper）精确生效；免密 HTML 引擎会忽略它。site 是拼进查询串的（site:example.com 之类写法同样可用）。

web_search 的返回对象：

{
  provider: "bocha" | "tavily" | "serper" | "bing" | "duckduckgo" | "baidu",
  query: "...",
  results: [{ title, url, snippet, source?, date?, score? }],
  warnings?: ["tavily: HTTP 429 ...", ...],   // 降级过程说明
  answer?: "..."                              // tavily / serper 的摘要（如果渠道给了）
}

fetch_url 的返回对象：

{
  url: "<跟随重定向后的最终地址>",
  title?: "<HTML 的 <title>，非 HTML 时没有>",
  contentType: "text/html; charset=utf-8",
  truncated: true | false,
  chars: 12000,
  text: "<正文；被截断时末尾会附加 [truncated, N chars total]>"
}

内容类型处理：JSON 原样返回；HTML/XML（或内容看起来像 HTML）会剥标签、解 HTML 实体、压缩空白后转成 文本；其它类型原样返回。正文超过 max_chars 会截断，参数被夹在 500~50000 之间。

2. 后端与降级链

免密默认链（零 key、零配置，顺序固定）：

1. bing → https://www.bing.com/search
2. duckduckgo → https://html.duckduckgo.com/html/
3. baidu → https://www.baidu.com/s（末级回退）

链式规则：某个引擎抛错或返回 0 条结果，就往下走，并把原因累积到 warnings 里返回。 三个都失败才抛错，错误信息形如 All keyless engines failed. bing: GET https://www.bing.com/search timed out [timeout] | ...。 请求会带桌面 Chrome 的 User-Agent 与 Accept-Language: zh-CN,zh;q=0.9,en;q=0.8。

keyed 后端（配了 key 自动优先，质量更高）：

免密引擎也可被单独指定：provider 填 bing / baidu / duckduckgo 时只用那一个，不再链式降级。

keyed 后端出错或 0 结果时不会直接失败，而是回落免密链，并在 warnings 里保留原因，所以「配置了 key 但结果看起来是白牌的」通常意味着 keyed 调用失败了。

3. 配置 keyed 后端

配置读的是 app_settings 表里分类为 webSearch 的三个键， 每次解析 MCP server 时实时读取：

当前版本没有对应的设置页面，最快的写法是让 Agent 调 mcp__spark_platform__settings_set：

settings_set({ category: "webSearch", key: "provider", value: "bocha" })
settings_set({ category: "webSearch", key: "apiKey", value: "<你的 key>" })
settings_set({ category: "webSearch", key: "baseUrl", value: "https://api.bochaai.com" })   # 可选

读取入口在子进程侧，对应这三个环境变量（key 只存在于该子进程内存）：

SPARK_SEARCH_PROVIDER        auto | bocha | tavily | serper | bing | baidu | duckduckgo
SPARK_SEARCH_API_KEY         keyed 后端的 key
SPARK_SEARCH_BASE_URL        keyed 后端 base url 覆盖
SPARK_SEARCH_TIMEOUT_MS      单次请求超时，默认 15000（1000~60000）
SPARK_SEARCH_TOTAL_TIMEOUT_MS  单次搜索总时限，默认 20000（1000~90000）
SPARK_SEARCH_MAX_RETRIES     可重试错误的最大重试次数，默认 1（0~3）
SPARK_SEARCH_RETRY_BACKOFF_MS  退避基数，默认 250（1~2000）
SPARK_SEARCH_FETCH_MAX_CHARS fetch_url 默认正文上限，默认 8000（500~50000）
SPARK_SEARCH_BING_URL / SPARK_SEARCH_BAIDU_URL / SPARK_SEARCH_DUCKDUCKGO_URL  覆盖免密引擎地址

其中前三个变量由应用按 webSearch 设置实时注入；其余是部署级逃生口，只有你自己 在启动环境里设置时才生效。

4. 超时、重试与限额

哪些错误算「可重试」：timeout、network、rate_limited（429）、server_error（5xx）。会读取响应里的 Retry-After（秒数或 HTTP 日期）， 但退避上限 2000 ms。4xx（除 429）与 invalid_response（返回体不是 JSON）不重试。

错误信息里带方括号分类标签，便于快速判断：

GET https://www.bing.com/search timed out [timeout]
GET https://api.tavily.com/search failed: fetch failed [network]
POST https://google.serper.dev/search returned HTTP 429 [rate_limited]
POST https://api.bochaai.com/v1/web-search returned HTTP 500 [server_error]
POST https://api.bochaai.com/v1/web-search returned HTTP 401 [http_4xx]
Non-JSON response from https://... [invalid_response]
GET https://... exceeded request budget [budget_exhausted]

5. 在会话里怎么用

不需要任何配置，直接派活：

帮我搜一下最近一周关于 React Server Components 的最佳实践，整理成 5 条要点并给出链接。

Agent 会先 web_search 拿候选，再对关键页面 fetch_url 读全文，最后给出带 出处的结论。注入的 system prompt（WEB_SEARCH_SYSTEM_PROMPT）明确要求：时效性问题要 主动核实而不是靠模型记忆、优先一手来源、结论附近给 URL、不要把「没搜到」当成「不存在」。

挂载范围：

• 宿主会话默认挂载，工具名会合并进 SDK 的允许清单。
• 团队成员默认也挂载，与 Host 走同一套解析。
• 例外：显式标记为只读的「原子」成员从空能力集开始，不会拿到 spark_search。
• 脚本文件缺失时（web-search-mcp-server.mjs 找不到或缺少依赖）会记 warn 并跳过， 此时工具列表里不会出现这两个工具。

配套技能是内置技能 builtin:multi-search-engine，它的 requiredTools 就是这两个工具，内容是多角度检索、交叉验证、给出处的操作规范。

6. 实现位置与排查

• MCP server：packages/agent-runtime/src/tools/web-search-mcp-server.mjs
• HTTP/重试/deadline 工具：packages/agent-runtime/src/tools/web-search-http.mjs
• 接线：SessionService.resolveWebSearchMcpServer()（读 webSearch 设置并注入 环境变量）+ 各轮次的 mcpServers.spark_search / allowedTools 合并
• 工具允许清单：SEARCH_TOOL_NAMES（session-mcp-tooling-helpers.ts）
• 提示词：WEB_SEARCH_SYSTEM_PROMPT（同文件）
• 伴随技能：apps/desktop/resources/skills/multi-search-engine/