DSH plugin 的 Web 访问契约:搜索与抓取两项操作到底怎么分工、错误怎么分才不踩坑
搜索和抓取共用一条 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 拥有的封闭可辨识联合,目前只有两种:
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 时,唯一可用才自动选,多个可用就明确报歧义。(来源)
选择规则在每次操作执行时解析,五种结果:
- 配置的 id 已注册且
available()— 用它; - 配置的 id 未注册 —
WEB_PROVIDER_CONFIGURED_MISSING; - 配置的 id 已注册但不可用 —
WEB_PROVIDER_CONFIGURED_UNAVAILABLE; - 未配 id,恰好一个已注册可用提供方 — 用它;
- 未配 id,多个可用 —
WEB_PROVIDER_AMBIGUOUS; - 未配 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 结果化与选择失败三条路径。(来源) 六步:
- 注册一个搜索提供方,让它在
maxResults为 2 时返回 5 条,断言sources只剩 2 条且truncated为真。 - 调
listProviders(),断言能看到该提供方;注销后再调,断言列表更新。 - 抓取一个返回 404 的 URL,断言不抛错、
statusCode为 404,且body有内容。 - 抓取一个返回 302 到同源新路径的 URL,断言
result.url是最终地址。 - 不配 id 且注册两个可用搜索提供方,断言报
WEB_PROVIDER_AMBIGUOUS。 - 配置一个未注册的 id,断言报
WEB_PROVIDER_CONFIGURED_MISSING。
如果第 3 步抛了 WebError,先确认是网络层真的失败了,还是提供方把非 2xx 当成了异常——后者违反 seam 语义。
搜索与抓取的报错排查,可以对照web_search 与 web_fetch 修复;自定义网关的接法见自定义 Web 网关。
一句话收束: 两项操作共享选择与错误、不共享 schema,搜索上限返回时强制,非 2xx 是结果不是异常,正文是封闭联合,没有 id 就报歧义。
常见问题
不会,DSH plugin 把 HTTP 状态码当成被抓资源状态的一部分。DSH plugin 对非 2xx 的成功网络抓取仍返回 WebFetchResult,带状态码与长度受限的解码正文。
由 DSH plugin 的 seam 在返回时强制。DSH plugin 的 maxResults 是消费方自有的上限,提供方返回超量时 seam 会截断 sources 并置 truncated。
不会,DSH plugin 规定它只是廉价本地检查。DSH plugin 用它判断凭证是否存在、配置是否可解析,禁止在可用性检查里发起网络调用。
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
来源
- DeepSeek Harness 官方参考 - Web 访问· deepseek-ai
- packages/web/web/src/types.ts· deepseek-ai