ChatGPTClaudeGrok / X / CursorGemini

DSH plugin 的 Web 访问契约:搜索与抓取两项操作到底怎么分工、错误怎么分才不踩坑

插件开发发布于 2026-11-12作者: DeepSeek Plugin 插件市场
DSH pluginDeepSeek HarnessWeb 访问WebFetchResult提供方选择
接入自定义搜索或抓取提供方时结果字段对不上,或抓取被拒却看不出原因。本文讲 ctx.web 为何一项能力两项操作、搜索上限如何强制、抓取为何只带 URL,以及可用性与选择规则。

搜索和抓取共用一条 seam,但字段、错误与降级方式完全不同。 DSH plugin 把两项操作放在同一个 ctx.web 上,是为了共享“选哪个提供方”和“怎么报错”这套规则,不是为了复用请求结构。按搜索的思路去读抓取结果,就会把 404 误判成失败。 DSH插件 接搜索或抓取提供方时,先把「非 2xx 是结果不是异常」记牢。

一项能力,两项操作

共享的是选择策略与错误词汇,不是 schema。(来源)

搜索与抓取既不共享请求 schema,也不共享业务逻辑,但它们被有意设计为同一个 ctx.web 中间层。收益有三项:一个提供方选择策略的所有者、一套中止与错误词汇、一个面向产品的“此 harness 如何访问 Web”配置界面。

代价是服务上并行的 searchX 与 fetchX 方法对。官方明确说这种并行是有意为之,而不是遗漏了可抽取的共性。所以不要试图在下游把两者抽象成一个通用“网络请求”。

提供方注册的是能力(WebSearchProvider 或 WebFetchProvider),不是工具。面向模型的名称、schema、提示词引导与展示全部集中在唯一消费方 dsh-tool-web 中。这也是为什么更换搜索提供方不会改变模型提交查询的方式,更换抓取提供方也不会改变模型请求 URL 的方式。

搜索:一个请求一个 query

上限由 seam 在返回时强制,提供方超量返回不会漏到模型侧。(来源)

每个 seam 请求只携带一个 query。消费方接受必填的 queries 数组,并把它扇出为多个独立 seam 请求;单元素数组执行一次搜索。

maxResults 是消费方自有的上限(dsh-tool-web 的 searchMaxResults,默认 10),通过 seam 传递并在返回时强制执行。如果提供方返回超量,seam 截断 sources[] 并设置 truncated。

WebSearchResult 三个字段:可选 content(提供方生成的答案文本或摘要)、sources[](可移植的引用形状)与 truncated。WebSearchSource 只有 url 必填,title、snippet、summary、publishedAt 都是可选——不是每个提供方都会返回它们,强迫适配器补造会让 seam 说谎。dsh-tool-web 展示时用 title ?? hostname(url)。

有一条建议值得采纳:如果提供方 API 支持结果数量控制(例如 DeepSeek Search API 的 count),应在请求层应用它作为成本与时延优化,但 seam 无论如何都会强制上限。

抓取:请求刻意只带 URL

抓取请求的“缺字段”是设计,不是遗漏。(来源)

WebFetchRequest 只有 url。它刻意省略 timeout、格式、prompt 与抽取控制:取消是直接执行参数,而展示与更高层的 LLM 关注点属于安全检索之外。

最重要的语义在这里:HTTP 状态码是被抓资源状态的一部分,不自动视为失败。即使一次成功的网络抓取收到 404 或 500,也仍会产出一个 WebFetchResult,其中包含状态码和长度受限的已解码正文。WebError 仅用于无法安全获取或表示资源的情况。

WebFetchResult 的 url 是经过允许的重定向后的最终 URL,不是请求 URL。statusCode 是响应状态,body 是按内容类型分类的解码正文,truncated 表示提供方是否截断。

所以判断“抓取失败”应当看两处:调用是否抛了 WebError,以及 statusCode 是否非 2xx。只看其中一处都会误判。

正文类型是封闭联合

新增一种 kind 是跨包协调变更,不是插件扩展点。(来源)

WebFetchBody 是 dsh-web 拥有的封闭可辨识联合,目前只有两种:

ts
type WebFetchBody =
  | { readonly kind: 'html'; readonly content: string }
  | { readonly kind: 'text'; readonly content: string }

提供方负责解码 kind,dsh-tool-web 负责渲染。消费方对 kind 做 switch 并以 default: assertNever(...) 收尾,因此新增一种正文会让每个消费方在编译期报错,直到被处理。

每个分支保持独立的对象字面量,即使字段目前相同——这样某个分支将来可以增加其他分支没有的字段。你在插件里给 WebFetchBody 加分支是不会生效的,这不是扩展点。

可用性与就绪判断不是一回事

available() 回答“能不能选”,ready() 回答“这条路由的请求有没有凭据”。(来源)

available() 是廉价本地检查(凭证是否存在、配置是否可解析),禁止发起网络调用。它是执行时选择提供方的输入,而不是健康检查系统:search() 与 fetch() 会读取它来选择可用提供方。

注册情况则不同,它在操作运行前即可观测:listProviders() 按 id、可选 title 与可选多语言 description 返回每个已注册的搜索与抓取提供方;每次注册或注销都会触发不带载荷的 web/providers-changed 事件。可用性仍只在操作运行时体现。

ready(llmProvider) 是可选实现,同样只检查配置、禁止网络调用:它回答为该对话路由上的模型请求发起的操作是否有可发送的凭据。searchReady() 与 fetchReady() 只询问 search() 或 fetch() 会选中的提供方,把没有 ready() 的提供方视为就绪,并在选择失败时回答 true——因为对应操作会把该失败报告为 WebError。

就绪判断不是选择输入。dsh-tool-web 把它作为 web_search 与 web_fetch 的激活条件,因此路由回答 false 的模型步骤既不声明也不派发该工具。

选择从不依赖注册顺序

没有显式 id 时,唯一可用才自动选,多个可用就明确报歧义。(来源)

选择规则在每次操作执行时解析,五种结果:

  1. 配置的 id 已注册且 available() — 用它;
  2. 配置的 id 未注册 — WEB_PROVIDER_CONFIGURED_MISSING;
  3. 配置的 id 已注册但不可用 — WEB_PROVIDER_CONFIGURED_UNAVAILABLE;
  4. 未配 id,恰好一个已注册可用提供方 — 用它;
  5. 未配 id,多个可用 — WEB_PROVIDER_AMBIGUOUS;
  6. 未配 id,没有可用 — WEB_PROVIDER_UNAVAILABLE。

第 5 条是关键:官方明确不会选用最先注册的提供方。每次操作在执行时读取配置的 id,因此保存的设置变更无需重新挂载 ctx.web 即对下一次搜索或抓取生效。

抓取网络策略与错误代码

文件沙箱不管 Web 访问,能不能出网是部署级问题。(来源)

已交付的 Cordis、Code 与 Standard preset 会在所有 sandbox 和审批模式下暴露 web_fetch,无需逐次确认。文件 sandbox preset 不管辖 Web 网络访问;需要确认步骤的部署必须添加 tools/pre-execute 策略或禁用抓取。

HTTP 提供方不限制目的地址:web_fetch 会像访问其他主机一样访问 loopback、内网与云元数据主机,模型也可以把数据发送到它能访问的任何 URL。跨源重定向需要新的工具调用。需要阻止私有目的地址的部署必须使用网络隔离、tools/pre-execute 策略,或不挂载抓取工具。

错误码按所有者划分。WebError 带开放 code 字符串(与 LlmError、SubagentError 一致),消费方必须容忍未知代码。共享运行时抛出的与 seam 无关的代码包括 WEB_PROVIDER_UNAVAILABLE、WEB_PROVIDER_CONFIGURED_MISSING、WEB_PROVIDER_CONFIGURED_UNAVAILABLE、WEB_PROVIDER_AMBIGUOUS、WEB_DUPLICATE_PROVIDER、WEB_ABORTED 与 WEB_PROVIDER_ERROR。

抓取传输层代码由 dsh-web-fetch-http 实现拥有:WEB_INVALID_URL、WEB_BLOCKED_URL、WEB_REDIRECT_BLOCKED、WEB_FETCH_TOO_LARGE、WEB_FETCH_TIMEOUT、WEB_UNSUPPORTED_CONTENT_TYPE。换一个抓取后端不需要抛这些代码,所以不要把它们的出现当成 seam 契约。

验证:搜索与抓取各跑一次

验证要覆盖强制截断、非 2xx 结果化与选择失败三条路径。(来源) 六步:

  1. 注册一个搜索提供方,让它在 maxResults 为 2 时返回 5 条,断言 sources 只剩 2 条且 truncated 为真。
  2. 调 listProviders(),断言能看到该提供方;注销后再调,断言列表更新。
  3. 抓取一个返回 404 的 URL,断言不抛错、statusCode 为 404,且 body 有内容。
  4. 抓取一个返回 302 到同源新路径的 URL,断言 result.url 是最终地址。
  5. 不配 id 且注册两个可用搜索提供方,断言报 WEB_PROVIDER_AMBIGUOUS。
  6. 配置一个未注册的 id,断言报 WEB_PROVIDER_CONFIGURED_MISSING。

如果第 3 步抛了 WebError,先确认是网络层真的失败了,还是提供方把非 2xx 当成了异常——后者违反 seam 语义。

搜索与抓取的报错排查,可以对照web_search 与 web_fetch 修复;自定义网关的接法见自定义 Web 网关。

一句话收束: 两项操作共享选择与错误、不共享 schema,搜索上限返回时强制,非 2xx 是结果不是异常,正文是封闭联合,没有 id 就报歧义。

ChatGPTClaudeGrok / X / CursorGemini

常见问题

DSH plugin 抓取遇到 404 响应时会抛错,还是照常返回结果?

不会,DSH plugin 把 HTTP 状态码当成被抓资源状态的一部分。DSH plugin 对非 2xx 的成功网络抓取仍返回 WebFetchResult,带状态码与长度受限的解码正文。

DSH plugin 的 maxResults 上限由谁强制,提供方还是 seam?

由 DSH plugin 的 seam 在返回时强制。DSH plugin 的 maxResults 是消费方自有的上限,提供方返回超量时 seam 会截断 sources 并置 truncated。

DSH plugin 的 available() 会发网络请求吗?

不会,DSH plugin 规定它只是廉价本地检查。DSH plugin 用它判断凭证是否存在、配置是否可解析,禁止在可用性检查里发起网络调用。

DSH plugin 有两个可用提供方但没配 id 会怎样?

DSH plugin 会报 WEB_PROVIDER_AMBIGUOUS,而不是选最先注册的。DSH plugin 的选择规则从不依赖注册、配置或热替换顺序。

相关术语

WebSearchResult
WebSearchResult 是归一化搜索结果,含可选提供方答案文本、已截断的引用来源列表与 truncated 标记。— packages/web/web/src/types.ts
WebFetchResult
WebFetchResult 是归一化抓取结果,含重定向后的最终 URL、HTTP 状态码、解码正文与截断标记。— packages/web/web/src/types.ts
WebFetchBody
WebFetchBody 是 dsh-web 拥有的封闭正文联合,目前只有 html 与 text 两种 kind。— packages/web/web/src/types.ts
WEB_PROVIDER_AMBIGUOUS
WEB_PROVIDER_AMBIGUOUS 是存在多个可用提供方却未配置 id 时抛出的结构化错误码。— packages/web/web/src/types.ts

来源