export interface WebSearchProvider { // 搜索后端契约：id + 本地可用性检查 + 一次搜索  readonly id: string // 稳定标识，作注册表键；重复 id 在注册时就被拒绝（WEB_DUPLICATE_PROVIDER）  available(): boolean // 廉价的本地可用性检查（如"有没有 API key"），明确禁止发网络请求  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> // 执行一次搜索，signal 用于协作式取消export interface WebFetchProvider { // 抓取后端契约：与搜索同形，只是请求/结果类型不同  readonly id: string // 稳定标识；在 fetch 能力域内唯一  available(): boolean // 本地可用性检查；匿名公共抓取器恒返回 true（没有凭证可查）  fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult> // 取一个 URL，signal 用于协作式取消

function resolveProvider<P extends ResolvableProvider>(selection: Selection<P>): P { // 搜索/抓取共用的泛型选择器：返回选中的 provider，或抛出对应错误码  const { configuredId, providers } = selection // 解构两个输入：显式配置的 id（可无）+ 该能力域的注册表  if (configuredId !== undefined) { // 分支一：有显式配置——任何不匹配都 fail loud，绝不静默回退到自动选择    const provider = providers.get(configuredId) // 按名字查；undefined 即"没注册过"    if (!provider) throw new WebError(`configured web provider "${configuredId}" is not registered`, 'WEB_PROVIDER_CONFIGURED_MISSING') // 配了但缺失 → 专属错误码，让运维能直接定位配置问题    if (!provider.available()) throw new WebError(`configured web provider "${configuredId}" is registered but unavailable`, 'WEB_PROVIDER_CONFIGURED_UNAVAILABLE') // 注册了但不可用（如缺 key）→ 另一个专属错误码，和"没注册"区分开    return provider // 两项检查都过：就用配置指定的这个  const usable = [...providers.values()].filter(provider => provider.available()) // 分支二：无显式配置——先过滤出"可用"的候选（available() 是纯本地判断）  const [single] = usable // 取第一个元素；undefined 意味着一个可用的都没有  if (single === undefined) throw new WebError('no usable web provider is registered', 'WEB_PROVIDER_UNAVAILABLE') // 零可用 → 报错，不猜、不降级  if (usable.length > 1) { // 多个可用 → 歧义    const ids = usable.map(provider => provider.id).join(', ') // 把所有候选 id 拼进错误信息，告诉用户该配哪个    throw new WebError(`multiple usable web providers are registered (${ids}); configure one explicitly`, 'WEB_PROVIDER_AMBIGUOUS') // 强制显式配置——选择结果绝不依赖注册顺序  }  return single // 恰好一个可用 → 自动选中它（单 provider 部署的零配置体验）function capSources(result: WebSearchResult, maxResults: number | undefined): WebSearchResult { // 缝层对搜索结果数做最终执法：provider 可以超量返回，上限由缝保证  if (maxResults === undefined || result.sources.length <= maxResults) return result // 没设上限或本来就在限内 → 原样透传  return { ...result, sources: result.sources.slice(0, maxResults), truncated: true } // 截断到上限并置 truncated 标志，让模型知道"还有更多被丢掉了"

export function formatSearchOutput(result: WebSearchResult): string { // 把归一化搜索结果拼成一段模型可见的文本块  const parts: string[] = [] // 收集输出的各个部分，最后用空行连接  if (result.content !== undefined && result.content.length > 0) parts.push(result.content) // provider 生成的答案（Perplexity 有；Exa/DeepSeek 没有）放最前  if (result.sources.length > 0) { // 有来源 → 渲染成 markdown 列表    const lines = result.sources.map((source) => { // 每个 source 一行      const label = sourceLabel(source.url, source.title) // 显示名：优先 title，缺失时退回 hostname（再失败就用原始串）      const meta: string[] = [] // 收集可选元数据（摘要/日期），没有就不拼      if (source.snippet !== undefined && source.snippet.length > 0) meta.push(source.snippet) // 有 snippet 就带上      if (source.publishedAt !== undefined && source.publishedAt.length > 0) meta.push(`(${source.publishedAt})`) // 有日期就带括号附上      const suffix = meta.length > 0 ? ` — ${meta.join(' ')}` : '' // 元数据用破折号连接；全空则无后缀      return `- [${label}](${source.url})${suffix}` // 标准 markdown 链接 + 可选元数据——模型能直接引用    })    parts.push(`Sources:\n${lines.join('\n')}`) // 列表挂在 "Sources:" 标题下  } else if (result.content === undefined || result.content.length === 0) { // 既无来源也无答案 → 显式的空结果信号    parts.push('No results found.') // 明确告诉模型"没搜到"，引导它换查询词重试，而不是留白让它瞎猜  if (result.truncated) parts.push(`(Showing the first ${result.sources.length} sources. Refine the query for more.)`) // 截断提示：缝层砍过结果时，教模型收窄查询而不是以为这就是全部  parts.push('Cite the relevant URLs above as markdown links in your answer.') // 常驻指令：强制引用来源链接——搜索工具的价值一半在出处  return parts.join('\n\n') // 各部分之间空一行

const endpoint = `${options.baseURL}/messages` // Anthropic 兼容 Messages 端点（baseURL 默认已含 /anthropic/v1）const body: DeepSeekSearchLlmRequest['body'] = { // 发给 provider 的精确请求体——稍后会原样记入 session log  model: options.model, // 模型名，默认 deepseek-v4-flash  max_tokens: options.maxTokens, // 生成 token 上限，默认 4096  messages: [{ role: 'user', content: [{ type: 'text', text: `Perform a web search for the query: ${request.query}` }] }], // 唯一一条 user 消息：只说"搜这个查询"，不夹带任何上下文  tools: [{ type: 'web_search_20250305', name: 'web_search', max_uses: options.maxUses }], // 原生服务端 web_search 工具；默认单次请求最多用 5 次options.recordRequest?.({ endpoint, apiVersion: options.apiVersion, body }) // 派发前把无密钥的精确请求记入 session log——recordRequest 若抛错会阻止派发，模型可见输入逃不出日志throwIfSearchAborted(signal) // 发网络请求前再查一次取消：abort 之后绝不浪费一个模型回合let response: Response // 先声明响应变量，try 块内赋值——fetch 可能抛网络错误try { // fetch 会抛（网络/DNS/abort），统一在 catch 里分类  response = await fetch(endpoint, { // 真正发出 POST；endpoint 已含 /messages    method: 'POST', // 搜索是带 JSON body 的 POST（区别于抓页面的 GET）    redirect: 'error', // 携带凭证的请求拒绝任何重定向——API key 绝不会被自动转发到另一个源    headers: { // 请求头集合：双认证 + 版本 + 内容协商 + 署名      'x-api-key': apiKey, // 官方 DeepSeek 期望 x-api-key……      'authorization': `Bearer ${apiKey}`, // ……Anthropic 兼容代理可能只认 Authorization：两个都发，谁都能解析      'anthropic-version': options.apiVersion, // API 版本头（默认 2023-06-01）      'content-type': 'application/json', // JSON 请求体      'accept': 'application/json', // 期望 JSON 响应      'user-agent': USER_AGENT, // 署名 deepseek-harness/0.0.1，随包版本升级    },    body: JSON.stringify(body), // 序列化请求体    ...signal !== undefined ? { signal } : {}, // 把调用方取消信号透传给 fetch（没有就不传这个字段）  })} catch (error: unknown) {  if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error) // abort → 稳定的 WEB_ABORTED 错误码，而不是被当成网络故障  throw new WebError(`DeepSeek search request failed: ${String(error)}`, 'WEB_PROVIDER_ERROR', { cause: error }) // 其他失败 → provider 错误，cause 链上原始异常

export function mapAnthropicResponse(response: AnthropicResponse): WebSearchResult { // 把 DeepSeek Messages 响应映射成归一化搜索结果  const blocks = response.content ?? [] // content 块数组；缺失时按空处理  const resultBlocks = blocks.filter((block): block is WebSearchToolResultBlock => block.type === 'web_search_tool_result') // 挑出原生搜索结果的块（类型谓词收窄）  if (resultBlocks.length === 0) { // 一个搜索结果块都没有 → 这次请求根本没触发原生搜索    throw new WebError('DeepSeek returned no web_search_tool_result blocks; the request may not have triggered native web search', 'WEB_PROVIDER_ERROR') // fail loud：绝不退回"从散文里刮 URL"的降级路径——结构化结果缺失就是错误  const snippets = citationSnippets(blocks) // 从 text 块的 citations[] 建 url → cited_text 映射（这才是 snippet 的真实来源）  const seen = new Set<string>() // 去重集合：max_uses > 1 时同一条 URL 可能在多次搜索里重复出现  const sources: WebSearchSource[] = [] // 按结果顺序累积归一化 source  for (const block of resultBlocks) { // 遍历每个搜索结果块    for (const item of block.content ?? []) { // ……及其中的 web_search_result 条目      if (item.type !== 'web_search_result' || item.url.length === 0 || seen.has(item.url)) continue // 跳过非结果项、空 URL、以及已见过的重复 URL      seen.add(item.url) // 标记为已见      const snippet = snippets.get(item.url) // 查这条 URL 的引用摘录（可能没有）      sources.push({ url: item.url, ...item.title != null && item.title.length > 0 ? { title: item.title } : {}, ...snippet != null && snippet.length > 0 ? { snippet } : {}, ...item.page_age != null && item.page_age.length > 0 ? { publishedAt: item.page_age } : {} }) // url 必有；title/snippet/publishedAt 有则带上——绝不编造缺失字段  return { sources, truncated: false } // 最终 maxResults 截断归缝层管，所以 provider 永远报"未截断"

function renderBody(body: WebFetchBody, maxInputChars: number): RenderedBody { // 把解码后的 body 渲染成模型可见的 markdown 文本  const content = body.content.slice(0, maxInputChars) // 先把源文本切到预算内（默认 20 万字符），限制同步转换的工作量  const sourceTruncated = content.length !== body.content.length // 记录这次"转换前截断"是否真的丢了内容  switch (body.kind) { // WebFetchBody 是封闭联合类型——每个分支都必须处理，漏一个就编译失败    case 'html': // HTML：走 turndown 转 markdown，但有两道守卫      if (exceedsConversionDepth(content)) return { text: content, sourceTruncated } // 嵌套深度超过 512 → 跳过转换直接透传原文（防 DoS，见下方分析）      try {        return { text: turndown.turndown(content), sourceTruncated } // 正常路径：HTML → GFM markdown（含表格/删除线插件）      } catch { // turndown 的 DOM 遍历对畸形标记仍可能抛 RangeError——降级兜底        return { text: content, sourceTruncated } // 转换失败 → 原样返回 HTML，截断状态如实带上；"降级的页面"好过"报错的抓取"    case 'text': // 纯文本（json/xml/text/*）：原样透传      return { text: content, sourceTruncated } // 无需转换，直接返回；截断状态照带    default:      return assertNever(body, 'unhandled web fetch body kind') // 不可达分支：将来新增 body kind 时，这里会先编译报错逼你处理

function computeFetchOutput(result: WebFetchResult, maxOutputChars: number): RenderedFetch { // 组装完整的有界输出：header + body + 可选 footer  const header = `Fetched ${result.url} (HTTP ${result.statusCode})\n\n` // 状态行打头——非 2xx 也是"结果"不是错误，模型必须显式看到状态码  const rendered = renderBody(result.body, maxInputChars) // 转换/截断 body（见上方 renderBody）  const prefix = `${header}${rendered.text}` // header + body 拼起来  const truncated = result.truncated || rendered.sourceTruncated || prefix.length > maxOutputChars // "有效截断"= provider 砍过 OR 转换前切过 OR 整体超预算——三者任一即 true  const full = `${prefix}${truncated ? TRUNCATION_FOOTER : ''}` // 只有真被截断才追加"换个更具体的 URL 再抓"的提示  if (full.length <= maxOutputChars) return { text: full, truncated } // 整体不超预算 → 直接返回  if (maxOutputChars < TRUNCATION_FOOTER.length) return { text: full.slice(0, maxOutputChars), truncated } // 退化情形：预算比 footer 本身还小——硬切，footer 保不住就算了  return { text: `${prefix.slice(0, maxOutputChars - TRUNCATION_FOOTER.length)}${TRUNCATION_FOOTER}`, truncated } // 正常超预算：从 body 上砍，但给 footer 留位置——"截断提示"本身必须活下来

export function validateFetchUrl(input: string, maxUrlLength: number): URL { // 任何网络访问之前的传输卫生检查；违规抛 WebError  if (input.length > maxUrlLength) throw new WebError(`URL exceeds the maximum length of ${maxUrlLength}`, 'WEB_INVALID_URL') // 超长 URL 先拒（默认上限 2048）——不解析、不浪费  let url: URL // 声明解析结果，try 块内赋值  try { // new URL 可能抛（畸形输入）——下面 catch 统一包装    url = new URL(input) // 解析；畸形输入在这里抛  } catch (error: unknown) {    throw new WebError(`invalid URL: ${input}`, 'WEB_INVALID_URL', { cause: error }) // 包成类型化 WebError，cause 链上原始解析错误  if (url.protocol !== 'http:' && url.protocol !== 'https:') throw new WebError(`unsupported URL scheme "${url.protocol}" (only http and https are allowed)`, 'WEB_INVALID_URL') // 只允许 http(s)——file://、gopher:// 之类不在 web fetcher 的职责范围  if (url.username.length > 0 || url.password.length > 0) throw new WebError('credentials in URLs are not allowed', 'WEB_BLOCKED_URL') // user:pass@host 一律拒绝——不给"URL 里夹带凭证"留后门（注意错误码是 BLOCKED 不是 INVALID）  return url // 全部通过；返回解析后的 URL 供后续请求使用export function isSameOrigin(a: URL, b: URL): boolean { // 同源 = scheme + hostname + port 三者全等  return a.protocol === b.protocol && a.hostname === b.hostname && a.port === b.port // 一个表达式三个字段——专门用来给重定向跟随把关

private async followAndRead(initialUrl: string, signal: AbortSignal): Promise<WebFetchResult> { // 跟随同源重定向直到拿到非跳转响应（或抛错）  let currentUrl = validateFetchUrl(initialUrl, this.limits.maxUrlLength) // 初始 URL 先过传输卫生检查，再碰网络  let redirectsFollowed = 0 // 重定向跳数计数器，对应 maxRedirects 预算  for (;;) { // 循环直到出现非重定向响应（错误会直接抛出终止）    const response = await this.requestOnce(currentUrl, signal) // 一次 GET：redirect:'manual' + 共享 abort 信号 + 产品 User-Agent    if (isRedirectStatus(response.status)) { // 301/302/303/307/308 → 处理这一跳      if (redirectsFollowed >= this.limits.maxRedirects) { // 预算耗尽——在解析下一跳之前就拦下        await response.body?.cancel() // 取消（可能还在流的）body，防止 socket 泄漏        throw new WebError(`exceeded the maximum of ${this.limits.maxRedirects} redirects`, 'WEB_REDIRECT_BLOCKED') // 默认上限 5 跳      const location = response.headers.get('location') // 下一跳地址      if (location === null) { // 重定向状态码却没有 Location → 不是可用资源        await response.body?.cancel() // 同样的 socket 卫生        throw new WebError(`redirect response (HTTP ${response.status}) without a Location header`, 'WEB_PROVIDER_ERROR') // 重定向却没有目标地址 → 视为不可用资源，直接报错      const target = resolveRedirect(location, currentUrl) // 相对 Location 按当前 URL 解析成绝对地址      let validatedTarget: URL // 校验通过后的目标 URL，供下一跳使用      try { // 校验可能抛（含跨源拒绝）——catch 里先清理 body 再重抛        validatedTarget = validateFetchUrl(target.toString(), this.limits.maxUrlLength) // 目标重新过一遍完整卫生检查——重定向不能当"绕过凭证/非 http(s)/超长校验"的后门        if (!isSameOrigin(validatedTarget, currentUrl)) throw new WebError(`cross-origin redirect to ${validatedTarget.origin} is not followed automatically; retry against that URL directly`, 'WEB_REDIRECT_BLOCKED') // 跨源 → 拒绝：每个新 origin 都是一次新的工具调用，需要一次新的权限决策      } catch (error: unknown) {        await response.body?.cancel() // 任何校验失败都先清理 body 再抛出        throw error // 原样重抛（保留 WEB_REDIRECT_BLOCKED / WEB_INVALID_URL 等原始错误码）      await response.body?.cancel() // 丢弃这一跳的 body（重定向响应体没有内容价值）      currentUrl = validatedTarget // 前进到下一 URL      redirectsFollowed++ // 消耗一跳预算      continue // 回到循环顶部发下一个请求    return await this.readBody(response, currentUrl, signal) // 非重定向：分类 content-type → 解码 → 字节限额，返回最终结果

private async readCapped(response: Response, signal: AbortSignal): Promise<{ bytes: Uint8Array; truncatedByBytes: boolean }> { // 按 maxResponseBytes（默认 5MB）读取响应流  const declared = response.headers.get('content-length') // 服务端声明的大小（如果有）  if (declared !== null) { // 有 Content-Length → 先做"声明超限"快速拒绝；没有则直接进流式读取    const length = Number(declared) // 解析成数字    if (Number.isFinite(length) && length > this.limits.maxResponseBytes) { // 还没读一个字节就知道"比上限大"      await response.body?.cancel() // 立即取消——不下载注定要拒绝的东西      throw new WebError(`response exceeds the maximum of ${this.limits.maxResponseBytes} bytes`, 'WEB_FETCH_TOO_LARGE') // 声明超限 → 硬拒绝（错误码明确，模型知道是体积问题）  if (response.body === null) return { bytes: new Uint8Array(0), truncatedByBytes: false } // 防御：无 body 的响应 → 空结果、未截断  const chunks: Uint8Array[] = [] // 收集到的字节块  let total = 0 // 累计字节数  let truncatedByBytes = false // 只有"真的丢了字节"才置位  const reader = response.body.getReader() // body 流读取器  try {    for (;;) { // 读到 EOF 或预算耗尽      const { done, value } = await reader.read() // 读一块（或结束）      if (done) break // EOF → 完整读完      const remaining = this.limits.maxResponseBytes - total // 剩余字节预算      if (value.byteLength > remaining) { // 这一块超出预算        chunks.push(value.subarray(0, remaining)) // 只保留放得下的前缀        total += remaining // 预算恰好耗尽        truncatedByBytes = true // 只有被丢弃的字节才算截断——"恰好等于上限"的 body 不会被误标        break // 停止读取；剩余流在 finally 里放弃      chunks.push(value) // 整块放得下      total += value.byteLength // 记账  } catch (error: unknown) {    throw translateAbortOrNetwork(error, signal) // 读流中途故障 → 按 deadline 信号分类成超时/取消/网络错误（见下方分析）  } finally {    await reader.cancel().catch(() => {}) // 成功读完或超预算跳出后，best-effort 清理被放弃的流  const bytes = new Uint8Array(total) // 按精确总量分配最终缓冲  let offset = 0 // 写入游标  for (const chunk of chunks) { // 按顺序拷贝各块    bytes.set(chunk, offset) // 把这一块拷进最终缓冲的当前位置    offset += chunk.byteLength // 游标前移，指向下一块的写入点  }  return { bytes, truncatedByBytes } // 交回有界字节缓冲 + 是否丢过字节

web_search：一次模型回合的搜索

① 模型调用 web_search({query}) → tool-web 校验 query 非空（parseSearchArgs）

② ctx.web.search({query, maxResults:8}, signal) → resolveProvider 执行期选择（配置优先，否则唯一可用）

③ DeepSeekSearchProvider：快照 options → resolveApiKey（credentials seam / env）→ recordRequest 记入 session log

④ POST /anthropic/v1/messages：服务端 web_search 工具（max_uses≤5），redirect:'error'，双认证头

⑤ mapAnthropicResponse：web_search_tool_result 块 + citations 拼 snippet + url 去重；无结果块 → WEB_PROVIDER_ERROR

⑥ capSources 截断到 8 并置 truncated → formatSearchOutput：markdown 来源列表 + "引用 URL"指令

web_fetch：受控的匿名抓取

① 模型调用 web_fetch({url}) → tool-web 校验 url 非空；超时是部署策略（timeoutMs），不是模型参数

② ctx.web.fetch({url}, signal) → resolveProvider 执行期选择

③ HttpFetchProvider：validateFetchUrl（http(s)/无凭证/≤2048）+ deadline(30s) 统一管请求与读流

④ followAndRead：redirect:'manual'；仅同源跳 ≤5 次；跨源 → WEB_REDIRECT_BLOCKED（"retry against that URL directly"）

⑤ readBody：classifyContentType → decoderForCharset（未知 charset fail loud）→ readCapped 5MB 字节闸 → 解码后 10 万字符闸

⑥ tool-web renderBody：HTML→GFM（嵌套>512 透传原文）；computeFetchOutput 整体 ≤20 万字符，footer 必须存活

⑦ 模型收到 "Fetched <url> (HTTP <status>)" + body；非 2xx 是结果不是错误，状态码显式可见