Files
deepseek-harness/packages/web/web-deepseek-api/README.zh.md
T
Yudong HanandLegGasai fda98dadd2 feat(web): add DeepSeek Search and Fetch APIs behind a settings switch (#6103)
* fix(web-search-deepseek): disable thinking for auxiliary search requests

The provider discards the generated text of the auxiliary Messages turn,
so reasoning tokens have no consumer. DeepSeek enables thinking by default,
which adds latency and output tokens to every search.

Fixes #6099.

* feat(web): add opt-in traditional Search and Fetch APIs

* test(web): verify API settings persistence and refresh Session evidence

* fix(web): require an explicit Search API base with its route prefix

* docs(web): document direct Search and Fetch API decisions

* fix(web): keep Messages search default behind the new Web Search API switch

- Rename useTraditionalApi/traditionalBaseURL to useSearchApi/searchApiBaseURL and
  label the switch "Use the new Web Search API"; Messages search stays the default.
- Default the Search / Fetch API base to https://api.deepseek.com/v1/tools.
- Authenticate the Search API with an API key only: DeepSeek Account tokens
  returned an empty HTTP 404 on /v1/tools/* when probed on 2026-10-16.
- Remove the count setting, which tool-web's maxResults always overrides, and
  the undocumented DeepSeek-API-Version header.
- Name the active API's base URL field and the current settings path in
  endpoint guidance; re-record the endpoint guidance Session.
- Keep WebFetchResult.statusCode required: DeepSeek Fetch reports HTTP 200 and
  drops the page title, so the fetch-metadata widening and its upgrade guide
  are removed.

* fix(web): accept account sign-in on the live Search API

The public Search and Fetch routes went live on 2026-10-16 and accept the
DeepSeek Account token, so account-route Sessions send it to the Search API
as they do for Messages search, and the settings copy no longer says account
sign-in does not apply.

Record the live behavior in the README and Agent Note: summaries of
1,000-2,300 characters, an HTTP 500 for an unresolvable Fetch target, and
migration notes for gateways without /v1/tools routes. Test doubles now use
the live response fields and RFC 3339 offsets.

* feat(web): configure Search API result count and send the triggering question

- Add web-search-deepseek.count (1-50, default 10, the service default) and
  show it as "Results per search" in Search API mode, where "Max searches per
  request" applies only to Messages; a smaller request maxResults still wins.
- Send the initiating Session's latest human prompt as ori_question, with
  whitespace collapsed and cut to the API's 128-character limit; blank or
  absent prompts omit it, and sendOriginalQuestion: false disables it. The
  settings hint states that the question is sent.
- Match the web search double on the request's query field, since
  ori_question now carries every query in the prompt.

* fix(client): unify web search endpoint override controls

* feat(web): configure registered search and fetch providers through shared settings

* feat(web): include Exa and Perplexity in provider settings

* test(web): cover provider settings branches and refresh plugin snapshots

* revert(web): drop the provider dropdown, schema-driven form, and Exa/Perplexity settings

Revert aed8c5cb609, d88c47dcd80, and 036a5a337d3. The Web search settings
page returns to the DeepSeek toggle; the DeepSeek Search and Fetch API split
is reintroduced as one plugin in the following commit.

* feat(web): move the DeepSeek Search and Fetch APIs into web-deepseek-api

The new web-deepseek-api plugin registers deepseek-search-api and
deepseek-fetch-api over one credential and API base, and exports the
authentication and redirect-rejecting transport that web-search-deepseek now
reuses for Messages search only. The web service reads searchProvider and
fetchProvider for each operation, so the Web search settings switch selects
both APIs together on save and restores Messages search with local HTTP fetch
when turned off. The switch hint links to the DeepSeek search and fetch guide.

* refactor(client): keep the web search endpoint fields on the shared override controls

Drop the always-visible reset and the inherited-address placeholder from the
Web search page, restoring ui-primitives to its base. Each endpoint field shows
the selected section's effective value and offers Reset to default only for an
override, like every other settings field.

* refactor(web): keep Messages search independent of web-deepseek-api

Restore dsh-web-search-deepseek to its own credential and transport code,
keeping only the disabled-thinking request and the current settings guidance,
so the Messages plugin no longer depends on the Search and Fetch API package.
dsh-web-deepseek-api keeps its transport internal; the regions that repeat the
Messages helpers carry jscpd:ignore markers, with the rationale recorded in the
Search and Fetch API Agent Note.

* refactor(web): keep the web-deepseek-api request type module-private

---------

Co-authored-by: LegGasai <[email protected]>
2026-10-17 15:08:08 +08:00

6.7 KiB
Raw Blame History

description, kind
description kind
DeepSeek Search 与 Fetch API 提供者、共享的鉴权与传输层、端点配置及标准化结果。 package-reference

@deepseek-ai/dsh-web-deepseek-api

English | 中文

概述

通过 DeepSeek Search 与 Fetch API 搜索和抓取网页:每次操作只发起一次直接请求,无需辅助模型请求。插件注册 deepseek-search-api 和 deepseek-fetch-api,两者共用一份凭据和一个 API 基础地址,并使用 API key(API 密钥)或已配置的账号集成鉴权。Search 返回标题、URL、可用的摘要和可用的发布时间;Fetch 返回页面 Markdown。Messages 搜索仍由 dsh-web-search-deepseek 提供;面向模型的工具由 dsh-tool-web 提供。

目录


使用此包

将插件与 dsh-web 一起挂载,并选择它的提供者。内置配置挂载此插件,同时选择 Messages 搜索和本地 HTTP 抓取。在插件 > 内置插件配置 > 网页搜索中开启启用新版 Web 搜索 API并保存,会同时选择此包的两个提供者;关闭后恢复内置选择。保存的选择从下一次操作开始生效。

- name: '@deepseek-ai/dsh-web'
  config:
    searchProvider: deepseek-search-api
    fetchProvider: deepseek-fetch-api
- name: '@deepseek-ai/dsh-web-deepseek-api'
  config:
    apiKeyEnv: DEEPSEEK_API_KEY
字段 默认值 含义
apiKey 省略 字面 API 密钥;建议使用凭据引用
apiKeyEnv DEEPSEEK_API_KEY 每次操作解析的凭据引用
baseURL https://api.deepseek.com/v1/tools 包含部署路径前缀的 Search 与 Fetch API 基础地址;追加 /search 或 /fetch
count 10 Search API 每次搜索的结果数,为 1 至 50 的整数;请求中更小的 maxResults 优先
sendOriginalQuestion true 将触发搜索的用户提示截取至 128 个字符,作为 Search API 的 ori_question 发送

baseURL 填写完整的 API 基础地址,包含路径前缀,但不包含操作名。默认值请求 https://api.deepseek.com/v1/tools/search 和 https://api.deepseek.com/v1/tools/fetch;使用其他前缀(例如 /api/v1/tools)的部署需要填写其完整基础地址。

真实 API 测试要求同时设置 DEEPSEEK_API_KEY 和 DEEPSEEK_SEARCH_API_TEST_BASE_URL,后者包含 API 路径前缀。

鉴权

使用 deepseek-account 路由的会话向账号服务请求已授权用于解析后端点的令牌,并通过 x-dsh-auth-token 发送;2026-10-16 公网 Search 与 Fetch 路由已接受该令牌。其他情况下,非空的字面 apiKey 优先于 apiKeyEnv;凭据引用通过 ctx.credentials 解析,该服务缺省时使用启动环境。API 密钥使用 Authorization: Bearer。凭据解析和端点选择使用同一份设置快照。

结果与失败

Search API 接收 query、count(配置的结果数,或请求中更小的 maxResults)、need_content: false,以及在 sendOriginalQuestion 未关闭时的 ori_question:发起会话中最近一条用户提示的文本,空白折叠后截取至 128 个字符。在会话之外或没有此类提示的搜索不发送该字段。提供者直接映射 results[].snippet,并将可为 null 的 date 映射为可选的 publishedAt。空结果数组表示成功。Fetch 发送 url,以文本正文返回原始 Markdown,并报告 HTTP 状态 200,因为目标没有可用内容时 API 会返回错误状态。返回 URL 为请求 URL:API 不报告重定向后的最终 URL。

baseURL 为空白或无法解析时,两个提供者都不可用;count 不在 1 至 50 之间时,Search 不可用。凭据缺失以 WEB_PROVIDER_CREDENTIAL_MISSING 失败;取消使用 WEB_ABORTED;传输、HTTP 和响应格式错误使用 WEB_PROVIDER_ERROR。重定向在联系目标前即被拒绝。Fetch API 的非成功状态表示抓取失败,不代表目标页面的状态。账号鉴权的 HTTP 401 响应提供重新登录指引;其他请求失败指出端点及 baseURL 设置字段。不会自动重试或回退至其他提供者。


理解实现

实现细节 — 点击展开

插件在每次操作时读取一次设置,并注册两个提供者。Search 提供者在返回服务结果前校验响应 JSON;Fetch 提供者校验 Markdown 正文。传输层负责凭据解析、取消、重定向拒绝和失败指引;记录钩子在发送前运行,抛出异常即阻止发送。Search 与 Fetch API 调用不产生辅助请求事件。工具调用和结果仍按常规记录到会话。

服务类型见 Web 子系统,受限的模型输出见 tool-web。


模型体验

会话工具结果

模型看到什么

web_search 和 web_fetch 工具在外部内容提示下呈现搜索来源或 Markdown。Fetch 结果包含请求 URL 和 HTTP 200。错误保留可操作的凭据或端点指引。Search 将查询连同触发问题直接发送给 Search API。

Token 影响

不消耗辅助模型 token。会话结果 token 随返回的摘要或 Markdown 增长,并受消费方限制。API 抓取计费独立于模型 token。

KV Cache 影响

工具结果追加在已有会话前缀之后。提供者注册不增加模型上下文。

已知限制与待办工作

  • 共享搜索请求不暴露 localization;提供者仅请求摘要,不消费 summary、site_name、site_icon 或搜索全文。2026-10-16 实测返回的 summary 长度为 1,000–2,300 个字符。
  • 2026-10-16 的探测中,不同的 ori_question 未改变结果顺序、评分或摘要;由于指南将其列为意图信号,提供者仍会发送。
  • 查询和 URL 约束由远端服务执行。2026-10-16 抓取无法解析的目标域名时返回 HTTP 500,而非文档所述的 404,其失败信息与端点失败附带相同的端点指引。Fetch 既不暴露目标状态,也不暴露最终重定向 URL,因此结果报告 HTTP 200 和请求 URL;提供者丢弃 API 返回的页面标题。
  • 可用性检查无法查询异步凭据存储。已配置的解析器在调用时仍可能因凭据缺失失败。

开发备注

无。