@deepseek-ai/dsh-web-deepseek-api 0.2.2-alpha.3 → 0.2.2-rc.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.i18n.yaml CHANGED
@@ -9,23 +9,23 @@
9
9
  en: a56113c9530cb046
10
10
  zh: bb07334e63fd9204
11
11
  /deepseek-ai-dsh-web-deepseek-api/summary:
12
- en: 0519addcba3db93f
13
- zh: 7c8bb421d7c89a1e
12
+ en: 68b1b7cc27238805
13
+ zh: b4b7cf49963f26a0
14
14
  /deepseek-ai-dsh-web-deepseek-api/table-of-contents:
15
15
  en: 76368b6b1da79c80
16
16
  zh: 1e8f931a56b7d34d
17
17
  /deepseek-ai-dsh-web-deepseek-api/use-this-package:
18
- en: 918391d0d2ef5e75
19
- zh: b9030f54ba1adfc5
18
+ en: 673ba23a4e608cf2
19
+ zh: 042afa607aaf4335
20
20
  /deepseek-ai-dsh-web-deepseek-api/use-this-package/authentication:
21
- en: 3037d291178a5b62
22
- zh: 27ed3abccd9d5cf3
21
+ en: b25cbe2a7894c03e
22
+ zh: db47f20dffe77a30
23
23
  /deepseek-ai-dsh-web-deepseek-api/use-this-package/results-and-failures:
24
- en: ed83053d3e5a7e57
25
- zh: 4c82d231fb6847d7
24
+ en: 7dbb34d960c1344c
25
+ zh: 51a1459415857ab5
26
26
  /deepseek-ai-dsh-web-deepseek-api/understand-the-implementation:
27
- en: 0372c46bac133870
28
- zh: 0c803f4fb04a7ee4
27
+ en: 71549e32f0a69c81
28
+ zh: 9cafbeb60bdf0114
29
29
  /deepseek-ai-dsh-web-deepseek-api/model-experience:
30
30
  en: 215e7ba838619b7b
31
31
  zh: a311da3843709f90
@@ -54,8 +54,8 @@
54
54
  en: 14f9af39f3be4fac
55
55
  zh: 3c7139fba0f17862
56
56
  /deepseek-ai-dsh-web-deepseek-api/known-limitations-and-deferred-work:
57
- en: 14dbc927803b012a
58
- zh: 09104e6062d80aa3
57
+ en: 689b26b5f3af8861
58
+ zh: 02cc62856a83cf48
59
59
  /deepseek-ai-dsh-web-deepseek-api/known-limitations-and-deferred-work/dev-note:
60
60
  en: 0a1253c6f7b5e8b9
61
61
  zh: 9f56528562c7c914
package/README.md CHANGED
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
9
9
 
10
10
  ## Summary
11
11
 
12
- Search and fetch the web through the DeepSeek Search and Fetch APIs: one direct request per operation, without an auxiliary model request. The plugin registers `deepseek-search-api` and `deepseek-fetch-api`, which share one credential and one API base, and authenticates with an API key or the configured account integration. Search returns titles, URLs, available snippets and summaries, and available publication dates; Fetch returns page Markdown. Messages search stays in [dsh-web-search-deepseek](../web-search-deepseek/README.md); the model-facing tools live in `dsh-tool-web`.
12
+ Search and fetch the web through the DeepSeek Search and Fetch APIs: one direct request per operation, without an auxiliary model request. The plugin registers `deepseek-search-api` and `deepseek-fetch-api`; each capability's billing chooses its DeepSeek credential: by default the conversation's account or API key on a DeepSeek model provider, otherwise the API key, then the signed-in account; it can also be fixed to either. YAML can give either capability its own base URL and key instead. Search returns titles, URLs, snippets, summaries, and dates; Fetch returns page Markdown. The model-facing tools live in `dsh-tool-web`; [legacy Messages search](../web-search-deepseek/README.md) remains a separate provider.
13
13
 
14
14
  ## Table of Contents
15
15
 
@@ -24,7 +24,7 @@ Search and fetch the web through the DeepSeek Search and Fetch APIs: one direct
24
24
  <a id="use-this-package"></a>
25
25
  ## Use this package
26
26
 
27
- Mount the plugin alongside `dsh-web` and select its providers. Shipped profiles mount it while selecting Messages search and local HTTP fetch. Turning on **Use the new Web Search API** in **Plugins > Built-in plugin settings > Web search** and saving selects both providers of this package; turning it off restores the shipped selection. A saved selection applies to the next operation.
27
+ Mount the plugin alongside `dsh-web` and select its providers. Shipped profiles mount it and select its Search API (`deepseek-search-api`) for search and local HTTP fetch for fetch. In **Plugins > Built-in plugin settings > Web search and fetch**, choosing **DeepSeek Search API** in the **Search** menu selects `deepseek-search-api` and choosing **DeepSeek Fetch API** in the **Fetch** menu selects `deepseek-fetch-api`; each menu is saved independently, and choosing another entry restores another provider. While a menu selects one of these providers, its **Billing** menu below writes `searchBilling` or `fetchBilling`: **Automatic**, **Signed-in DeepSeek account**, or **DeepSeek API key**. A saved selection applies to the next operation.
28
28
 
29
29
  ```yaml
30
30
  - name: '@deepseek-ai/dsh-web'
@@ -33,33 +33,48 @@ Mount the plugin alongside `dsh-web` and select its providers. Shipped profiles
33
33
  fetchProvider: deepseek-fetch-api
34
34
  - name: '@deepseek-ai/dsh-web-deepseek-api'
35
35
  config:
36
- apiKeyEnv: DEEPSEEK_API_KEY
36
+ searchBaseURL: https://search.example.test/api/v1/tools
37
+ searchApiKeyEnv: DEEPSEEK_SEARCH_API_KEY
37
38
  ```
38
39
 
39
40
  | Field | Default | Meaning |
40
41
  |---|---|---|
41
- | `apiKey` | omitted | Literal API key; prefer a credential reference |
42
- | `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each operation |
43
- | `baseURL` | `https://api.deepseek.com/v1/tools` | Search and Fetch API base including its deployment path prefix; append `/search` or `/fetch` |
44
42
  | `count` | `10` | Search API results per search, an integer from 1 to 50; a smaller `maxResults` on the request wins |
43
+ | `searchRequestsPerSecond` | `5` | Most Search requests this plugin instance sends in any one-second window, matching the service's account-wide 5 QPS limit; later searches wait, and the wait counts against the caller's timeout |
45
44
  | `sendOriginalQuestion` | `true` | Send the triggering human prompt, cut to 128 characters, as the Search API's `ori_question` |
45
+ | `searchBilling` | `auto` | Credential Search sends without own settings: `auto`, `account`, or `api-key` ([authentication](#authentication)) |
46
+ | `fetchBilling` | `auto` | Credential Fetch sends without own settings, with the same values |
47
+ | `searchBaseURL` | omitted | Search API base including its path prefix; `/search` is appended. Set alone, `searchApiKeyEnv` defaults to `DEEPSEEK_API_KEY` ([authentication](#authentication)) |
48
+ | `searchApiKeyEnv` | omitted | Search credential reference. Set alone, `searchBaseURL` defaults to `https://api.deepseek.com/v1/tools` |
49
+ | `fetchBaseURL` | omitted | Fetch API base including its path prefix; `/fetch` is appended, with the same defaults |
50
+ | `fetchApiKeyEnv` | omitted | Fetch credential reference, with the same defaults |
46
51
 
47
- Fill `baseURL` with the complete API base, including its path prefix and excluding the operation name. The default reaches `https://api.deepseek.com/v1/tools/search` and `https://api.deepseek.com/v1/tools/fetch`; a deployment with another prefix, such as `/api/v1/tools`, needs its complete base.
52
+ A capability with neither field follows its billing and reaches `/v1/tools/search` and `/v1/tools/fetch` under the origin of the selected DeepSeek model route's resolved Messages base URL, so the official `https://api.deepseek.com/anthropic`, or a `DEEPSEEK_BASE_URL` override, becomes `https://api.deepseek.com/v1/tools`, or the override's origin with `/v1/tools`. The `dsh` launcher accepts `DEEPSEEK_BASE_URL` from the launching environment or `$DSH_HOME/.env`, never from a project `.env` ([app-boot](../../boot/app-boot/README.md)). Fill an own base URL with the complete API base, including its path prefix and excluding the operation name; a deployment with another prefix, such as `/api/v1/tools`, needs its complete base. An empty field counts as unset. The own fields are YAML-only and take precedence over billing; the settings page shows only the billing menu for these providers. Stored `baseURL`, `apiKeyEnv`, and `apiKey` fields of earlier settings load without error and have no effect.
48
53
 
49
54
  Run the real API tests with `DEEPSEEK_API_KEY` and `DEEPSEEK_SEARCH_API_TEST_BASE_URL`; both are required, and the latter includes the API path prefix.
50
55
 
51
56
  <a id="authentication"></a>
52
57
  ### Authentication
53
58
 
54
- A Session using the `deepseek-account` route asks the account service for a token authorized for the resolved endpoint and sends it as `x-dsh-auth-token`; the public Search and Fetch routes accepted it on 2026-10-16. Otherwise a non-empty literal `apiKey` wins over `apiKeyEnv`; the reference resolves through `ctx.credentials`, or the launch environment when that service is absent. API keys use `Authorization: Bearer`. Credential resolution and endpoint selection share one settings snapshot.
59
+ Search and Fetch each resolve their endpoint and credential from one settings snapshot per operation, so a saved setting, a model-provider change, a sign-in, or a stored key applies to the next operation. The conversation's route is the `provider` of the initiating Session's latest request context; `ready()` uses the route of the model request being prepared.
55
60
 
56
- Each provider's `ready()` answers whether an operation for a model request has a credential, on any model route: the request's route is `deepseek-account` and `ctx.deepseekAccount` resolves a token for the API base, or a literal `apiKey` is set or `ctx.credentials.describe` reports the `apiKeyEnv` reference configured (without that service, the launch environment must carry it). A failed account-token or credential-store read answers false. While these providers are selected, [`dsh-tool-web`](../tool-web/README.md#search-readiness) withholds `web_search` and `web_fetch` with their prompt guidance from each request for which they answer false. Only presence is checked: a wrong key counts as ready and fails each call.
61
+ - **Own settings.** A capability with a non-empty `*BaseURL` or `*ApiKeyEnv` sends only the key under its `*ApiKeyEnv` (`DEEPSEEK_API_KEY` when unset) as `Authorization: Bearer` to its `*BaseURL` (`https://api.deepseek.com/v1/tools` when unset) on every route, and never the account token. Without the key, the operation fails with a diagnostic that names the reference and the `*ApiKeyEnv` field.
62
+ - **Account token.** The operation sends the token that `ctx.deepseekAccount` releases for the dispatch endpoint as `x-dsh-auth-token`; the public Search and Fetch routes accepted it on 2026-10-16. The endpoint is under the origin of the active Loader entry of `@deepseek-ai/dsh-llm-deepseek-account` at the entry root that the model provider directory lists for `deepseek-account`; without that entry, it is under the origin of that route's default base URL (`https://api.deepseek.com`, or the `DEEPSEEK_BASE_URL` origin). No sign-in, no account service, or an empty token means no token. A failed account-token read fails the operation without trying another credential. An active entry whose settings the route's own resolver rejects fails the operation before that account token is read when the operation reaches this source.
63
+ - **API key.** The operation sends the key under the `apiKeyEnv` of the active `@deepseek-ai/dsh-llm-deepseek-api-key` entry the directory lists for `deepseek-official` (`DEEPSEEK_API_KEY` by default) as `Authorization: Bearer` to that route's origin, resolving its options as the route does. Without that entry, or with an inactive one, it sends `DEEPSEEK_API_KEY` to `https://api.deepseek.com/v1/tools`. An active entry whose settings the route's own resolver rejects fails each operation that needs the key, before the key is read; the operation never substitutes the official endpoint or `DEEPSEEK_API_KEY`.
64
+ - **`auto` billing** follows the conversation. On the `deepseek-account` route it sends the account token, and without one the API key; without the account route entry, only the API key. On the `deepseek-official` route it sends only the API key. On any other route or outside a Session it sends the API key, and without a key the account token; without a key, a mounted account route entry whose settings do not resolve fails the operation.
65
+ - **`account` billing** sends only the account token on every route, and **`api-key` billing** only the API key; neither falls back to the other credential.
66
+
67
+ Without a credential, the operation fails with a diagnostic for its billing that names the missing sign-in or the Models page and the key reference, and the `*Billing` field on the Web search and fetch settings page.
68
+
69
+ References use the [shared DeepSeek credential helpers](../../llm/llm-deepseek/README.md#account-credentials): `ctx.credentials` is authoritative, with launch-environment lookup only when that service is absent. Route and own keys receive the same whitespace normalization and format validation as model requests; malformed keys fail before dispatch.
70
+
71
+ Each provider's `ready()` answers whether its next operation for that route has a credential, in the order its billing resolves them: a non-empty account token, or a key that `ctx.credentials.describe` reports configured (without that service, the launch environment must carry it). A failed account-token or credential-store read, or a needed route entry whose settings do not resolve, answers false. While these providers are selected, [`dsh-tool-web`](../tool-web/README.md#search-readiness) withholds `web_search` and `web_fetch` with their prompt guidance from each request for which they answer false. Only presence is checked: a wrong key counts as ready and fails each call.
57
72
 
58
73
  ### Results and failures
59
74
 
60
75
  The Search API receives `query`, `count` (the configured count, or the request's smaller `maxResults`), `need_content: false`, and, unless `sendOriginalQuestion` is off, `ori_question`: the text of the initiating Session's latest human prompt with whitespace collapsed and cut to 128 characters. A search outside a Session or without such a prompt omits it. The provider maps `results[].snippet` as the display excerpt and `results[].summary` as the model-facing excerpt, and maps nullable `date` to optional `publishedAt`; `dsh-tool-web` caps each summary. An empty results array is successful. Fetch sends `url` and returns the original Markdown as a text body with HTTP status 200, because the API answers with an error status when the target yields no usable content. Its URL is the requested URL: the API reports no final redirected URL.
61
76
 
62
- A blank or unparseable `baseURL` makes both providers unavailable, and a `count` outside 1 to 50 makes Search unavailable. Missing credentials fail with `WEB_PROVIDER_CREDENTIAL_MISSING`; cancellation uses `WEB_ABORTED`; transport, HTTP, and malformed response failures use `WEB_PROVIDER_ERROR`. Redirects are rejected before contacting their target. Non-success Fetch API statuses are retrieval failures, not target-page statuses. Account-authenticated HTTP 401 responses provide sign-in guidance; other dispatch failures identify the endpoint and the `baseURL` settings field. No automatic retry or provider fallback occurs.
77
+ An unparseable own base URL makes that capability's provider unavailable; and a `count` outside 1 to 50 makes Search unavailable. A missing credential fails with `WEB_PROVIDER_CREDENTIAL_MISSING`; a needed model route whose settings do not resolve fails with `WEB_PROVIDER_MISCONFIGURED`, naming the resolver failure, the Models page, and the capability's `*BaseURL` and `*ApiKeyEnv`; cancellation uses `WEB_ABORTED`; transport, HTTP, and malformed response failures use `WEB_PROVIDER_ERROR`. Redirects are rejected before contacting their target. Non-success Fetch API statuses are retrieval failures, not target-page statuses. Account-authenticated HTTP 401 responses invalidate only the token sent by that request and provide sign-in guidance; a newer sign-in is preserved, and credential-removal failure does not replace the HTTP error. API-key failures and HTTP 403 never invalidate an account token; other dispatch failures identify the endpoint and say where it came from: for a route endpoint they guide the user to that provider's base URL on the Models page or to the capability's `*BaseURL` and `*ApiKeyEnv`, and for own settings to correcting or removing those fields. No automatic retry or provider fallback occurs.
63
78
 
64
79
  -----
65
80
 
@@ -69,7 +84,7 @@ A blank or unparseable `baseURL` makes both providers unavailable, and a `count`
69
84
  <details>
70
85
  <summary>Implementation internals — click to expand</summary>
71
86
 
72
- The [plugin](src/index.ts) reads its settings once per operation and registers both providers. The [Search provider](src/search.ts) validates response JSON before returning service results; the [Fetch provider](src/fetch.ts) validates the Markdown body. The [transport](src/transport.ts) owns credential resolution, cancellation, redirect rejection, and failure guidance; a recording hook runs before dispatch and prevents it by throwing. Search and Fetch API calls emit no auxiliary request event. Tool calls and results retain their normal Session logging.
87
+ The [plugin](src/index.ts) reads its settings once per operation, registers both providers, and turns one capability's settings snapshot, the conversation's route, and the active model route entries into the operation's ordered credentials, each bound to the API base it is sent to. The [Search provider](src/search.ts) validates response JSON before returning service results; the [Fetch provider](src/fetch.ts) validates the Markdown body. The [transport](src/transport.ts) reads those credentials in order, sends one request with the first present one, and owns cancellation, redirect rejection, and failure guidance; a recording hook runs before dispatch and prevents it by throwing. Search and Fetch API calls emit no auxiliary request event. The [Messages search provider](../web-search-deepseek/README.md) owns its `web/deepseek-search-llm-request` Session event declaration and recording. Tool calls and results retain their normal Session logging.
73
88
 
74
89
  See the [web subsystem](../../../docs/subsystems/web.md) for service types and [tool-web](../tool-web/README.md) for bounded model output.
75
90
 
@@ -116,7 +131,8 @@ A returning or removed web tool changes the declared tools as [`dsh-tool-web`](.
116
131
  - In 2026-10-16 probes, different `ori_question` values left result order, scores, and summaries unchanged; the provider still sends it because the guide documents it as an intent signal.
117
132
  - API query and URL constraints are enforced by the remote service. An unresolvable Fetch target returned HTTP 500 rather than the documented 404 on 2026-10-16, and its failure carries the same endpoint guidance as an endpoint failure. Fetch exposes neither the target status nor the final redirect URL, so results report HTTP 200 and the requested URL; the provider discards the API's page title.
118
133
  - `available()` cannot query asynchronous credential stores; `ready()` does, so model steps withhold the tools when the store lacks the key. A direct `ctx.web.search()` or `ctx.web.fetch()` call can still fail with a missing-credential error.
119
- - When the official route chats through a gateway, operations still send the key to the configured API base and fail unless it accepts the key.
134
+ - Search pacing limits send times within one plugin instance. Other processes and clients on the same account share the account-wide 5 QPS limit without coordination, and network jitter can still bunch arrivals; an HTTP 429 fails that search, and `dsh-tool-web` then fails the whole multi-query call. Fetch is not paced, so parallel `web_fetch` calls can exceed the Fetch limit.
135
+ - Route endpoints and keys follow only the Loader entries of `@deepseek-ai/dsh-llm-deepseek-api-key` and `@deepseek-ai/dsh-llm-deepseek-account` at the entry root; another package registering the same provider id, such as a test replay adapter, counts as no route, so its conversations use `DEEPSEEK_API_KEY` and the official base.
120
136
 
121
137
  <a id="dev-note"></a>
122
138
  ### Dev Note
package/README.zh.md CHANGED
@@ -9,7 +9,7 @@ kind: "package-reference"
9
9
 
10
10
  ## 概述
11
11
 
12
- 通过 DeepSeek Search 与 Fetch API 搜索和抓取网页:每次操作只发起一次直接请求,无需辅助模型请求。插件注册 `deepseek-search-api` 和 `deepseek-fetch-api`,两者共用一份凭据和一个 API 基础地址,并使用 API key(API 密钥)或已配置的账号集成鉴权。Search 返回标题、URL、可用的 snippet 与 summary 以及可用的发布时间;Fetch 返回页面 Markdown。Messages 搜索仍由 [dsh-web-search-deepseek](../web-search-deepseek/README.zh.md) 提供;面向模型的工具由 `dsh-tool-web` 提供。
12
+ 通过 DeepSeek Search 与 Fetch API 搜索和抓取网页:每次操作只发起一次直接请求,无需辅助模型请求。插件注册 `deepseek-search-api` 和 `deepseek-fetch-api`;每个能力的计费方式决定它的 DeepSeek 凭据:默认在 DeepSeek 模型提供方上沿用会话的账号或 API 密钥,否则先用 API 密钥,再用已登录的账号;也可以固定为其中一种。也可以在 YAML 中为任一能力单独配置基础地址与密钥。Search 返回标题、URL、snippet、summary 与发布时间;Fetch 返回页面 Markdown。面向模型的工具由 `dsh-tool-web` 提供;[旧版 Messages 搜索](../web-search-deepseek/README.zh.md)仍是独立提供方。
13
13
 
14
14
  ## 目录
15
15
 
@@ -24,7 +24,7 @@ kind: "package-reference"
24
24
  <a id="use-this-package"></a>
25
25
  ## 使用此包
26
26
 
27
- 将插件与 `dsh-web` 一起挂载,并选择它的提供者。内置配置挂载此插件,同时选择 Messages 搜索和本地 HTTP 抓取。在**插件 > 内置插件配置 > 网页搜索**中开启**启用新版 Web 搜索 API**并保存,会同时选择此包的两个提供者;关闭后恢复内置选择。保存的选择从下一次操作开始生效。
27
+ 将插件与 `dsh-web` 一起挂载,并选择它的提供方。内置配置挂载此插件,为搜索选择它的 Search API(`deepseek-search-api`),为抓取选择本地 HTTP 抓取。在**插件 > 内置插件配置 > 网页搜索与获取**中,在**搜索**下拉框选择 **DeepSeek Search API** 会选中 `deepseek-search-api`,在**获取**下拉框选择 **DeepSeek Fetch API** 会选中 `deepseek-fetch-api`;两个下拉框分别保存,选择其他条目即改用其他提供方。下拉框选中这两个提供方之一时,其下方的**计费方式**下拉框写入 `searchBilling` 或 `fetchBilling`:**自动**、**已登录的 DeepSeek 账号**或 **DeepSeek API Key**。保存的选择从下一次操作开始生效。
28
28
 
29
29
  ```yaml
30
30
  - name: '@deepseek-ai/dsh-web'
@@ -33,33 +33,48 @@ kind: "package-reference"
33
33
  fetchProvider: deepseek-fetch-api
34
34
  - name: '@deepseek-ai/dsh-web-deepseek-api'
35
35
  config:
36
- apiKeyEnv: DEEPSEEK_API_KEY
36
+ searchBaseURL: https://search.example.test/api/v1/tools
37
+ searchApiKeyEnv: DEEPSEEK_SEARCH_API_KEY
37
38
  ```
38
39
 
39
40
  | 字段 | 默认值 | 含义 |
40
41
  |---|---|---|
41
- | `apiKey` | 省略 | 字面 API 密钥;建议使用凭据引用 |
42
- | `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次操作解析的凭据引用 |
43
- | `baseURL` | `https://api.deepseek.com/v1/tools` | 包含部署路径前缀的 Search 与 Fetch API 基础地址;追加 `/search` 或 `/fetch` |
44
42
  | `count` | `10` | Search API 每次搜索的结果数,为 1 至 50 的整数;请求中更小的 `maxResults` 优先 |
43
+ | `searchRequestsPerSecond` | `5` | 本插件实例在任意一秒窗口内最多发送的 Search 请求数,与服务的账号级 5 QPS 限制一致;后续搜索排队等待,等待时间计入调用方的超时 |
45
44
  | `sendOriginalQuestion` | `true` | 将触发搜索的用户提示截取至 128 个字符,作为 Search API 的 `ori_question` 发送 |
45
+ | `searchBilling` | `auto` | 没有单独配置时 Search 发送的凭据:`auto`、`account` 或 `api-key`([鉴权](#authentication)) |
46
+ | `fetchBilling` | `auto` | 没有单独配置时 Fetch 发送的凭据,取值相同 |
47
+ | `searchBaseURL` | 省略 | Search API 基础地址,包含路径前缀;追加 `/search`。只设置此项时,`searchApiKeyEnv` 默认为 `DEEPSEEK_API_KEY`([鉴权](#authentication)) |
48
+ | `searchApiKeyEnv` | 省略 | Search 凭据引用。只设置此项时,`searchBaseURL` 默认为 `https://api.deepseek.com/v1/tools` |
49
+ | `fetchBaseURL` | 省略 | Fetch API 基础地址,包含路径前缀;追加 `/fetch`,默认值规则相同 |
50
+ | `fetchApiKeyEnv` | 省略 | Fetch 凭据引用,默认值规则相同 |
46
51
 
47
- `baseURL` 填写完整的 API 基础地址,包含路径前缀,但不包含操作名。默认值请求 `https://api.deepseek.com/v1/tools/search` 和 `https://api.deepseek.com/v1/tools/fetch`;使用其他前缀(例如 `/api/v1/tools`)的部署需要填写其完整基础地址。
52
+ 两个字段都未设置的能力按其计费方式,请求所选 DeepSeek 模型路由解析后的 Messages 基础地址的 origin 下的 `/v1/tools/search` 与 `/v1/tools/fetch`,因此官方 `https://api.deepseek.com/anthropic` 或 `DEEPSEEK_BASE_URL` 覆盖值分别得到 `https://api.deepseek.com/v1/tools`,或覆盖值的 origin 加 `/v1/tools`。`dsh` 启动器从启动环境或 `$DSH_HOME/.env` 接受 `DEEPSEEK_BASE_URL`,绝不从项目 `.env` 接受([app-boot](../../boot/app-boot/README.zh.md))。单独配置的基础地址填写完整的 API 基础地址,包含路径前缀,但不包含操作名;使用其他前缀(例如 `/api/v1/tools`)的部署需要填写其完整基础地址。空字段视为未设置。这些单独配置的字段只能在 YAML 中设置,优先于计费方式;设置页只为这两个提供方显示计费方式下拉框。早期设置中保存的 `baseURL`、`apiKeyEnv` 与 `apiKey` 字段可以正常加载,但不再生效。
48
53
 
49
54
  真实 API 测试要求同时设置 `DEEPSEEK_API_KEY` 和 `DEEPSEEK_SEARCH_API_TEST_BASE_URL`,后者包含 API 路径前缀。
50
55
 
51
56
  <a id="authentication"></a>
52
57
  ### 鉴权
53
58
 
54
- 使用 `deepseek-account` 路由的会话向账号服务请求已授权用于解析后端点的令牌,并通过 `x-dsh-auth-token` 发送;2026-10-16 公网 Search 与 Fetch 路由已接受该令牌。其他情况下,非空的字面 `apiKey` 优先于 `apiKeyEnv`;凭据引用通过 `ctx.credentials` 解析,该服务缺省时使用启动环境。API 密钥使用 `Authorization: Bearer`。凭据解析和端点选择使用同一份设置快照。
59
+ Search 与 Fetch 每次操作各自从同一份设置快照解析端点和凭据,因此保存的设置、模型提供方变更、登录或存入的密钥从下一次操作开始生效。会话的路由是发起会话最近一次请求上下文的 `provider`;`ready()` 使用正在准备的模型请求的路由。
55
60
 
56
- 每个提供者的 `ready()` 回答模型请求将发起的操作是否有凭据,不论模型路由:该请求的路由是 `deepseek-account` 且 `ctx.deepseekAccount` 为 API 基础地址解析出令牌,或者设置了字面 `apiKey`,或 `ctx.credentials.describe` 报告 `apiKeyEnv` 引用已配置(没有该服务时,启动环境必须包含它)。账号令牌或凭据存储读取失败时回答 false。这两个提供者被选中时,[`dsh-tool-web`](../tool-web/README.zh.md#search-readiness) 会从它们回答 false 的每个请求中撤下 `web_search` 与 `web_fetch` 及其提示词指引。只检查是否存在:错误的密钥仍算就绪,并使每次调用失败。
61
+ - **单独配置。** 设置了非空 `*BaseURL` 或 `*ApiKeyEnv` 的能力在任何路由上都只以 `Authorization: Bearer` 把其 `*ApiKeyEnv`(未设置时为 `DEEPSEEK_API_KEY`)下的密钥发往其 `*BaseURL`(未设置时为 `https://api.deepseek.com/v1/tools`),从不发送账号令牌。没有该密钥时,操作失败,诊断信息点名该引用和 `*ApiKeyEnv` 字段。
62
+ - **账号令牌。** 操作通过 `x-dsh-auth-token` 发送 `ctx.deepseekAccount` 为请求端点给出的令牌;2026-10-16 公网 Search 与 Fetch 路由已接受该令牌。端点位于模型提供方目录为 `deepseek-account` 列出的、入口根部活动的 `@deepseek-ai/dsh-llm-deepseek-account` Loader 条目的 origin 下;没有该条目时,位于该路由默认基础地址的 origin(`https://api.deepseek.com`,或 `DEEPSEEK_BASE_URL` 的 origin)下。没有登录、没有账号服务或令牌为空都算没有令牌。账号令牌读取失败时操作失败,不再尝试其他凭据。条目活动但其设置被该路由自身的解析器拒绝时,操作在轮到该来源时失败,不读取该账号令牌。
63
+ - **API 密钥。** 操作以 `Authorization: Bearer` 把目录为 `deepseek-official` 列出的活动 `@deepseek-ai/dsh-llm-deepseek-api-key` 条目的 `apiKeyEnv`(默认 `DEEPSEEK_API_KEY`)下的密钥发往该路由的 origin,并按该路由的方式解析其选项。没有该条目或条目未激活时,把 `DEEPSEEK_API_KEY` 发往 `https://api.deepseek.com/v1/tools`。条目活动但其设置被该路由自身的解析器拒绝时,每个需要该密钥的操作都在读取密钥前失败,绝不改用官方端点或 `DEEPSEEK_API_KEY`。
64
+ - **`auto` 计费**跟随会话。在 `deepseek-account` 路由上先发送账号令牌,没有令牌时发送 API 密钥;没有账号路由条目时只发送 API 密钥。在 `deepseek-official` 路由上只发送 API 密钥。在其他路由上或会话之外先发送 API 密钥,没有密钥时发送账号令牌;没有密钥且已挂载的账号路由条目设置无法解析时,操作失败。
65
+ - **`account` 计费**在任何路由上只发送账号令牌,**`api-key` 计费**只发送 API 密钥;两者都不回退到另一种凭据。
66
+
67
+ 没有凭据时,操作失败,诊断信息按计费方式点名缺少的登录或模型页面与密钥引用,以及网页搜索与获取设置页上的 `*Billing` 字段。
68
+
69
+ 引用使用[共享 DeepSeek 凭据函数](../../llm/llm-deepseek/README.zh.md#account-credentials):`ctx.credentials` 具有权威性,仅在该服务缺席时读取启动环境。路由密钥与单独配置的密钥均接受与模型请求相同的首尾空白规范化和格式校验;格式错误在发送请求前失败。
70
+
71
+ 每个提供者的 `ready()` 按其计费方式的解析顺序回答其在该路由上的下一次操作是否有凭据:非空账号令牌,或 `ctx.credentials.describe` 报告已配置的密钥(没有该服务时,启动环境必须包含它)。账号令牌或凭据存储读取失败,或所需路由条目的设置无法解析时,回答 false。这两个提供者被选中时,[`dsh-tool-web`](../tool-web/README.zh.md#search-readiness) 会从它们回答 false 的每个请求中撤下 `web_search` 与 `web_fetch` 及其提示词指引。只检查是否存在:错误的密钥仍算就绪,并使每次调用失败。
57
72
 
58
73
  ### 结果与失败
59
74
 
60
75
  Search API 接收 `query`、`count`(配置的结果数,或请求中更小的 `maxResults`)、`need_content: false`,以及在 `sendOriginalQuestion` 未关闭时的 `ori_question`:发起会话中最近一条用户提示的文本,空白折叠后截取至 128 个字符。在会话之外或没有此类提示的搜索不发送该字段。提供者将 `results[].snippet` 映射为展示用摘录,将 `results[].summary` 映射为面向模型的摘录,并将可为 null 的 `date` 映射为可选的 `publishedAt`;`dsh-tool-web` 限制每条摘要的长度。空结果数组表示成功。Fetch 发送 `url`,以文本正文返回原始 Markdown,并报告 HTTP 状态 200,因为目标没有可用内容时 API 会返回错误状态。返回 URL 为请求 URL:API 不报告重定向后的最终 URL。
61
76
 
62
- `baseURL` 为空白或无法解析时,两个提供者都不可用;`count` 不在 1 至 50 之间时,Search 不可用。凭据缺失以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败;取消使用 `WEB_ABORTED`;传输、HTTP 和响应格式错误使用 `WEB_PROVIDER_ERROR`。重定向在联系目标前即被拒绝。Fetch API 的非成功状态表示抓取失败,不代表目标页面的状态。账号鉴权的 HTTP 401 响应提供重新登录指引;其他请求失败指出端点及 `baseURL` 设置字段。不会自动重试或回退至其他提供者。
77
+ 单独配置的基础地址无法解析时,该能力的提供者不可用;`count` 不在 1 至 50 之间时,Search 不可用。凭据缺失以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败;所需模型路由的设置无法解析时以 `WEB_PROVIDER_MISCONFIGURED` 失败,并点名解析器的失败原因、模型页面以及该能力的 `*BaseURL` 与 `*ApiKeyEnv`;取消使用 `WEB_ABORTED`;传输、HTTP 和响应格式错误使用 `WEB_PROVIDER_ERROR`。重定向在联系目标前即被拒绝。Fetch API 的非成功状态表示抓取失败,不代表目标页面的状态。账号鉴权的 HTTP 401 响应只作废该请求实际发送的 token,并提供重新登录指引;更新的登录不受影响,凭据删除失败不会替换原 HTTP 错误。API 密钥失败与 HTTP 403 从不作废账号 token;其他请求失败指出端点及其来源:路由端点指导用户在模型页面检查该提供方的基础地址,或设置该能力的 `*BaseURL` 与 `*ApiKeyEnv`;单独配置指导用户修改或删除这两个字段。不会自动重试或回退至其他提供者。
63
78
 
64
79
  -----
65
80
 
@@ -69,7 +84,7 @@ Search API 接收 `query`、`count`(配置的结果数,或请求中更小的
69
84
  <details>
70
85
  <summary>实现细节 — 点击展开</summary>
71
86
 
72
- [插件](src/index.ts)在每次操作时读取一次设置,并注册两个提供者。[Search 提供者](src/search.ts)在返回服务结果前校验响应 JSON;[Fetch 提供者](src/fetch.ts)校验 Markdown 正文。[传输层](src/transport.ts)负责凭据解析、取消、重定向拒绝和失败指引;记录钩子在发送前运行,抛出异常即阻止发送。Search 与 Fetch API 调用不产生辅助请求事件。工具调用和结果仍按常规记录到会话。
87
+ [插件](src/index.ts)在每次操作时读取一次设置,注册两个提供者,并把一个能力的设置快照、会话的路由和活动的模型路由条目转换为该操作的有序凭据,每个凭据都绑定其发往的 API 基础地址。[Search 提供者](src/search.ts)在返回服务结果前校验响应 JSON;[Fetch 提供者](src/fetch.ts)校验 Markdown 正文。[传输层](src/transport.ts)按顺序读取这些凭据,用第一个存在的凭据发送一次请求,并负责取消、重定向拒绝和失败指引;记录钩子在发送前运行,抛出异常即阻止发送。Search 与 Fetch API 调用不产生辅助请求事件。[Messages 搜索提供方](../web-search-deepseek/README.zh.md)负责声明和记录自身的 `web/deepseek-search-llm-request` 会话事件。工具调用和结果仍按常规记录到会话。
73
88
 
74
89
  服务类型见 [Web 子系统](../../../docs/subsystems/web.zh.md),受限的模型输出见 [tool-web](../tool-web/README.zh.md)。
75
90
 
@@ -116,7 +131,8 @@ Search API 接收 `query`、`count`(配置的结果数,或请求中更小的
116
131
  - 2026-10-16 的探测中,不同的 `ori_question` 未改变结果顺序、评分或摘要;由于指南将其列为意图信号,提供者仍会发送。
117
132
  - 查询和 URL 约束由远端服务执行。2026-10-16 抓取无法解析的目标域名时返回 HTTP 500,而非文档所述的 404,其失败信息与端点失败附带相同的端点指引。Fetch 既不暴露目标状态,也不暴露最终重定向 URL,因此结果报告 HTTP 200 和请求 URL;提供者丢弃 API 返回的页面标题。
118
133
  - `available()` 无法查询异步凭据存储;`ready()` 可以,因此凭据存储缺少密钥时,模型步骤会撤下这两个工具。直接调用 `ctx.web.search()` 或 `ctx.web.fetch()` 仍可能因凭据缺失失败。
119
- - 官方路由经网关对话时,操作仍把密钥发往配置的 API 基础地址,除非该地址接受这个密钥,否则调用失败。
134
+ - Search 限速只约束单个插件实例内的发送时间。同一账号下的其他进程和客户端共享账号级 5 QPS 限制,彼此不协调,网络抖动也可能使请求集中到达;HTTP 429 会使该次搜索失败,随后 `dsh-tool-web` 会使整个多查询调用失败。Fetch 不限速,因此并行的 `web_fetch` 调用可能超过 Fetch 限制。
135
+ - 路由端点与密钥只认入口根部的 `@deepseek-ai/dsh-llm-deepseek-api-key` 与 `@deepseek-ai/dsh-llm-deepseek-account` Loader 条目;以相同提供方 id 注册的其他包(例如测试回放适配器)视为没有路由,其会话使用 `DEEPSEEK_API_KEY` 与官方基础地址。
120
136
 
121
137
  <a id="dev-note"></a>
122
138
  ### 开发备注