@x1a0f3n9/dsh-web-search-deepseek 0.1.5-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/web/web-search-deepseek/README.md
+README.md: c060a5563015a899391010217f40489f817c9b7f
+README.zh.md: 4eac6adc3eda20475d1d99963cb8b9eb8772d571

package/README.md

@@ -0,0 +1,173 @@
+---
+description: "The DeepSeek-backed search provider for ctx.web: how deployments mount native DeepSeek web search through the Anthropic-compatible Messages API, with per-search credential resolution."
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-deepseek
+
+English | [中文](README.zh.md)
+
+## Summary
+
+With `dsh-web-search-deepseek`, the harness searches the web through DeepSeek's native search using an existing `DEEPSEEK_API_KEY`. Choose it when a deployment wants DeepSeek native search and accepts that one search costs a full model turn in latency and tokens, because DeepSeek exposes no dedicated search endpoint. Results come from the structured search blocks DeepSeek returns, never from scraping text out of a reply. A missing credential fails the call with a structured error; a response without a search-result block fails loudly rather than degrading. The model-facing `web_search` tool lives in `dsh-tool-web`.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Mount the provider in a composition that already loads the web service; it registers as the `deepseek-official` search provider, so `ctx.web.search()` resolves it automatically when it is the only usable search backend — or pin it with `searchProvider: deepseek-official`.
+
+### When to choose it
+
+Choose this backend when a deployment wants DeepSeek's native server-side web search and already holds a `DEEPSEEK_API_KEY` — the provider reuses that credential reference. One search is heavier than a dedicated retrieval endpoint: DeepSeek runs the search inside a full model turn, so expect one Messages call's latency and generated tokens per search, with up to `maxUses` server-side searches per request. Avoid it when per-search cost or latency dominates.
+
+### Minimal configuration
+
+Load the web service and the provider; the key resolves from `ctx.credentials` when that service is mounted, otherwise from the process environment. The search endpoint uses the Anthropic-compatible base (`https://api.deepseek.com/anthropic/v1`), distinct from the chat-completions base the LLM adapter uses — never reuse `$DEEPSEEK_BASE_URL`.
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    baseURL: https://gateway.internal/anthropic/v1
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `apiKey` | omitted | Literal DeepSeek API key; prefer `apiKeyEnv` so no secret enters configuration. A non-empty literal wins |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each search through `ctx.credentials`, or from the process environment when that service is absent. A missing value fails the call as `WEB_PROVIDER_CREDENTIAL_MISSING` |
+| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic-compatible endpoint base; `/messages` is appended. Falls back to `$DEEPSEEK_SEARCH_BASE_URL`; an unparseable value makes the provider unavailable |
+| `model` | `deepseek-v4-flash` | Anthropic-format model name |
+| `apiVersion` | `2023-06-01` | `anthropic-version` header value |
+| `maxTokens` | `4096` | Positive-integer upper bound on generated tokens for the Messages request |
+| `maxUses` | `5` | Positive-integer maximum `web_search` server-tool uses per request |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-deepseek) is the exhaustive source for every accepted field and its JSDoc. The entry above is the base layer of the provider's Settings section; a user layer over it reaches the next search, because the provider projects the section per call rather than capturing it at registration.
+
+### What a search returns
+
+`content` is always omitted: DeepSeek's provider prose is not trusted as an answer. `sources[]` comes from `web_search_result` items inside `web_search_tool_result` blocks — `url` and `title` directly, and `publishedAt` from `page_age` — with snippets joined from URL-keyed `cited_text` entries where an excerpt exists. Results are deduplicated by URL, and because DeepSeek exposes no result-count knob, the service enforces `maxResults` by truncating and flagging.
+
+### Request logging
+
+A search running under an initiating agent appends the log-only `web/deepseek-search-llm-request` session event immediately before dispatch. It carries the resolved endpoint, API version, and the exact secret-free JSON body sent to DeepSeek; headers and credentials are excluded. Credential failures and cancellations before dispatch create no event, while later HTTP or response failures leave the attempted request durable.
+
+### Failures and recovery
+
+Failures throw `WebError` with a machine-routable code: a missing credential is `WEB_PROVIDER_CREDENTIAL_MISSING`, caller cancellation is `WEB_ABORTED`, and provider or transport failures — including a response with no `web_search_tool_result` block — are `WEB_PROVIDER_ERROR`. HTTP redirects are rejected before the `Location` target is contacted. Every failure after dispatch names the resolved search endpoint and explains that search endpoint configuration is separate from chat. If the endpoint is unintended, the message tells the conversation model to guide the user to the Endpoint field under Settings > Plugins > Plugin configuration > Web search and save the change. When that page is unavailable, it names `DEEPSEEK_SEARCH_BASE_URL` and `web-search-deepseek.baseURL` as deployment configuration alternatives. The model must not choose or change the endpoint. The model-facing `web_search` tool surfaces this text under its own error wrapper.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the provider; the observable behavior is fully covered in [Use this package](#use-this-package).
+
+### Design philosophy
+
+The provider is built on two commitments:
+
+- **Structured blocks only.** DeepSeek runs the search server-side and returns structured `web_search_tool_result` blocks; the provider parses those blocks and never scrapes URLs out of model prose. In strict mode, a response with no such block throws `WEB_PROVIDER_ERROR` instead of degrading.
+- **One credential, resolved per search.** The provider reuses the `DEEPSEEK_API_KEY` reference (no new secret) but not `$DEEPSEEK_BASE_URL`, because search speaks the Anthropic-compatible Messages API. A mounted credentials service is authoritative; without one the provider falls back to the launching process environment. Resolving per call means a key stored or rotated in the Web Models page reaches the next search without a restart.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: config schema, Settings section installation, per-search option projection |
+| [`src/provider.ts`](src/provider.ts) | The `DeepSeekSearchProvider`: Messages request dispatch, block parsing, citation joining, credential resolution |
+| [`src/types.ts`](src/types.ts) | Anthropic wire types for the search response |
+| — | No runtime invariant companion is published; the package emits a pre-dispatch log event but owns no later authoritative dispatch event to relate it to. Exact envelope equality is pinned at the provider boundary instead. |
+
+### Request flow
+
+Each search projects the current Settings section into provider options — endpoint, model, key reference, limits — then resolves the credential reference through `ctx.credentials` (or the environment), appends the log-only session event, and dispatches the Messages request with the native `web_search` server tool. The response's `web_search_tool_result` blocks become `sources[]`; `cited_text` entries from text blocks are joined to their URLs as snippets; results are deduplicated by URL; and the service enforces the requested source bound on the way back.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough. They move from the shared vocabulary to the service, the model-facing tools, and the design rationale.
+
+- [Web subsystem](../../../docs/subsystems/web.md) — the exhaustive search request/result vocabulary and error codes.
+- [Web package map](../README.md) — the seven-package family and each role.
+- [dsh-web](../web/README.md) — the web service this provider registers into.
+- [dsh-tool-web](../tool-web/README.md) — the model-facing `web_search` tool that renders this provider's sources.
+- [Generated configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-web-search-deepseek) — every accepted config field and its source declaration.
+- [Web capability seam decision](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md) — why search and fetch share one provider-selection service.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Auxiliary DeepSeek search request
+
+#### What the model sees
+
+A separate DeepSeek model receives exactly `Perform a web search for the query: <query>` as its user text and one native `web_search` server-tool definition. This request is not part of the conversation model's context.
+
+#### Token effect
+
+Separate provider input and output tokens are incurred for each search; `maxTokens` caps generated output and `maxUses` caps native search uses.
+
+#### KV Cache effect
+
+Independent of the conversation request cache. The auxiliary instruction and native tool definition can form a stable prefix, but each changed query or model route prevents reuse from its first difference.
+
+### Conversation tool result, indirectly
+
+#### What the model sees
+
+Through `dsh-tool-web`, the conversation model sees deduplicated URLs, titles, dates, and citation snippets from structured search blocks; provider prose is not trusted as an answer. This provider's exact failures include the actionable missing-credential message, `DeepSeek search credential resolution failed: <error>`, and `DeepSeek search aborted`. Request, HTTP, native-search, and response-body failures append the resolved endpoint and the conditional configuration instruction described above. The consumer owns the error wrapper.
+
+#### Token effect
+
+Zero direct conversation tokens from registration. Result tokens scale with returned sources and snippets, then the service enforces the requested source bound.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the provider is expensive or incomplete. They are current package constraints.
+
+- **One search costs a full Messages model turn** — latency plus generated tokens, with up to `maxUses` server-side searches; DeepSeek exposes no dedicated retrieval endpoint.
+- **Dynamic credential availability resolves inside the operation** — the synchronous availability check can establish that a resolver exists but cannot query an asynchronous credential store, so a selected keyless provider fails the search with `WEB_PROVIDER_CREDENTIAL_MISSING`; the stable `web_search` schema stays registered.
+- **Over-returned sources still cost tokens** — with no result-count knob on the wire, `maxResults` is enforced only post-hoc by service truncation.
+- **Uncited results carry no `snippet`** — a source gains one only when a text-block citation (`cited_text`) matches its URL.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open questions and undecided directions. It is explicitly non-authoritative — shipped behavior, limits, and rationale live in the sections above and the linked Agent Notes.
+
+#### Future: dedicated retrieval endpoint
+
+A native DeepSeek search endpoint that avoids the full model turn would remove the dominant cost; until DeepSeek exposes one, this provider stays a Messages-call adapter.
+
+</details>

package/README.zh.md

@@ -0,0 +1,173 @@
+---
+description: "ctx.web 的 DeepSeek 搜索提供方：部署方如何通过 Anthropic 兼容 Messages API 挂载 DeepSeek 原生 web 搜索，并逐次解析凭据。"
+kind: "package-reference"
+---
+
+# @x1a0f3n9/dsh-web-search-deepseek
+
+[English](README.md) | 中文
+
+## 概述
+
+有了 `dsh-web-search-deepseek`，harness 可以通过 DeepSeek 原生搜索检索 web，使用部署已有的 `DEEPSEEK_API_KEY`。当部署希望使用 DeepSeek 原生搜索、并接受一次搜索在延迟与 token 上消耗一个完整模型轮次时选择它，因为 DeepSeek 不提供专用搜索端点。结果来自 DeepSeek 返回的结构化搜索块，绝不会从回复文本中抓取。凭据缺失时调用以结构化错误失败；响应缺少搜索结果块时会明确报错，而非降级。面向模型的 `web_search` 工具位于 `dsh-tool-web`。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+在已加载 web 服务的组合中挂载本提供方；它以 `deepseek-official` 搜索提供方身份注册，因此当它是唯一可用的搜索后端时，`ctx.web.search()` 会自动解析到它——也可以用 `searchProvider: deepseek-official` 固定。
+
+### 何时选择
+
+当部署希望使用 DeepSeek 原生服务端 web 搜索、且已持有 `DEEPSEEK_API_KEY` 时选择此后端——提供方复用该凭据引用。一次搜索比专用检索端点更重：DeepSeek 在完整模型轮次内执行搜索，因此每次搜索都要预期一次 Messages 调用的延迟与生成 token，每次请求最多 `maxUses` 次服务端搜索。当单次搜索的成本或延迟占主导时避免使用它。
+
+### 最小配置
+
+加载 web 服务与本提供方；密钥在已挂载 `ctx.credentials` 服务时从其解析，否则从进程环境解析。搜索端点使用 Anthropic 兼容基址（`https://api.deepseek.com/anthropic/v1`），不同于 LLM（大语言模型）适配器使用的 chat-completions 基址——绝不复用 `$DEEPSEEK_BASE_URL`。
+
+```yaml
+- name: '@x1a0f3n9/dsh-web'
+- name: '@x1a0f3n9/dsh-web-search-deepseek'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+    baseURL: https://gateway.internal/anthropic/v1
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `apiKey` | 未设置 | DeepSeek API 密钥字面值；优先使用 `apiKeyEnv`，避免密钥进入配置。非空字面值优先 |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | 每次搜索通过 `ctx.credentials` 解析的凭据引用；没有该服务时从进程环境解析。值缺失时调用以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败 |
+| `baseURL` | `https://api.deepseek.com/anthropic/v1` | Anthropic 兼容端点基址；追加 `/messages`。缺省时回退到 `$DEEPSEEK_SEARCH_BASE_URL`；无法解析时提供方不可用 |
+| `model` | `deepseek-v4-flash` | Anthropic 格式模型名称 |
+| `apiVersion` | `2023-06-01` | `anthropic-version` 标头值 |
+| `maxTokens` | `4096` | Messages 请求生成 token 的正整数上限 |
+| `maxUses` | `5` | 每次请求使用 `web_search` 服务器工具的正整数上限 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-deepseek)是每个受支持字段及其 JSDoc 的穷尽式真源。上面的条目是提供方 Settings 段的 base 层；叠加其上的用户层会作用于下一次搜索，因为提供方是按次投影该段，而不是在注册时固化它。
+
+### 搜索返回什么
+
+`content` 始终省略：DeepSeek 的提供方文本不作为答案受到信任。`sources[]` 来自 `web_search_tool_result` 块内的 `web_search_result` 条目——`url` 和 `title` 直接取自同名字段，`publishedAt` 取自 `page_age`——snippet 在存在摘录时按 URL 关联的 `cited_text` 条目拼接。结果按 URL 去重，且由于 DeepSeek 不公开结果数量旋钮，服务通过截断并标记来强制执行 `maxResults`。
+
+### 请求日志
+
+由发起 agent（智能体）运行的搜索会在发出请求前一刻，追加仅用于日志的 `web/deepseek-search-llm-request` 会话事件。其中包含已解析端点、API 版本，以及发送给 DeepSeek 且不含密钥的精确 JSON 请求体；不包含标头和凭据。发出请求前发生凭据失败或取消时不会创建事件，而发出请求后的 HTTP 或响应失败会保留本次请求尝试的持久记录。
+
+### 失败与恢复
+
+失败抛出携带可按机器路由 code 的 `WebError`：凭据缺失为 `WEB_PROVIDER_CREDENTIAL_MISSING`，调用方取消为 `WEB_ABORTED`，提供方或传输失败，包括响应中没有 `web_search_tool_result` 块，为 `WEB_PROVIDER_ERROR`。HTTP 重定向会在接触 `Location` 指向的目标之前被拒绝。请求发出后的每项失败都会指出已解析的搜索端点，并说明搜索端点配置独立于聊天端点。如果该端点不符合用户预期，错误消息会要求会话模型指导用户进入 Settings > Plugins > Plugin configuration > Web search，修改 Endpoint 字段并保存。该页面不可用时，消息会把 `DEEPSEEK_SEARCH_BASE_URL` 和 `web-search-deepseek.baseURL` 作为部署配置方式。模型不得替用户选择或修改端点。面向模型的 `web_search` 工具会在自己的错误包装层内呈现这段文本。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释提供方背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
+
+### 设计理念
+
+本提供方建立在两项承诺之上：
+
+- **只取结构化块。** DeepSeek 在服务端执行搜索并返回结构化的 `web_search_tool_result` 块；提供方解析这些块，绝不从模型文本中抓取 URL。严格模式下，没有此类块的响应会抛出 `WEB_PROVIDER_ERROR`，而非降级。
+- **一个凭据，逐次解析。** 提供方复用 `DEEPSEEK_API_KEY` 引用（不新增密钥），但不复用 `$DEEPSEEK_BASE_URL`，因为搜索使用 Anthropic 兼容 Messages API。已挂载的凭据服务具有权威性；没有该服务时回退到启动进程的环境。按次解析意味着在 Web 的 Models 页中存储或轮换的密钥无需重启，即可用于下一次搜索。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：配置 schema、Settings 段安装、逐次选项投影 |
+| [`src/provider.ts`](src/provider.ts) | `DeepSeekSearchProvider`：Messages 请求分发、块解析、引用拼接、凭据解析 |
+| [`src/types.ts`](src/types.ts) | 搜索响应的 Anthropic 协议类型 |
+| — | 不发布运行时不变量配套入口；本包会在分发前发出日志事件，但没有后续的权威分发事件可与之关联；精确的请求包络相等性改由提供方边界保障。 |
+
+### 请求流程
+
+每次搜索先把当前 Settings 段投影为提供方选项——端点、模型、密钥引用、上限——然后通过 `ctx.credentials`（或环境）解析凭据引用，追加仅用于日志的会话事件，并以原生 `web_search` 服务器工具分发 Messages 请求。响应中的 `web_search_tool_result` 块变为 `sources[]`；文本块中的 `cited_text` 条目按其 URL 拼接为 snippet；结果按 URL 去重；服务在返回路径上强制执行请求的来源上限。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。它们从共享词汇逐步进入服务、面向模型的工具与设计依据。
+
+- [web 子系统](../../../docs/subsystems/web.zh.md)——穷尽式的搜索请求／结果词汇与错误码。
+- [web 包映射](../README.zh.md)——七包家族与各角色。
+- [dsh-web](../web/README.zh.md)——本提供方注册进入的 web 服务。
+- [dsh-tool-web](../tool-web/README.zh.md)——渲染本提供方来源的面向模型 `web_search` 工具。
+- [生成配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-web-search-deepseek)——每个受支持配置字段及其源声明。
+- [web 能力 seam 决策](../../../.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md)——搜索与抓取为何共用一项提供方选择服务。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 辅助 DeepSeek 搜索请求
+
+#### 模型看到的内容
+
+独立的 DeepSeek 模型会原样接收 `Perform a web search for the query: <query>` 作为用户文本，并收到一个原生 `web_search` 服务器工具定义。该请求不属于会话模型上下文。
+
+#### Token 影响
+
+每次搜索都会产生独立的提供方输入与输出 token；`maxTokens` 限制生成输出，`maxUses` 限制原生搜索次数。
+
+#### KV Cache 影响
+
+与会话请求缓存相互独立。辅助指令与原生工具定义可以形成稳定前缀，但查询或模型路由的每次变化都会阻止从首个差异起的复用。
+
+### 间接的会话工具结果
+
+#### 模型看到的内容
+
+通过 `dsh-tool-web`，会话模型会看到结构化搜索块中去重后的 URL、标题、日期与引用 snippet；提供方文本不会作为答案受到信任。该提供方的具体失败消息包括带有处理指引的凭据缺失消息、`DeepSeek search credential resolution failed: <error>` 和 `DeepSeek search aborted`。请求、HTTP、原生搜索和响应正文失败会追加已解析端点及前述条件式配置指引。错误包装属于消费方。
+
+#### Token 影响
+
+注册不会直接产生会话 token。结果 token 随返回源与 snippet 增长，随后服务强制执行请求的来源上限。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV Cache 条目失效。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明提供方在哪些情况下昂贵或不完整。它们是当前包约束。
+
+- **一次搜索消耗一个完整的 Messages 模型轮次**——产生延迟与生成 token，最多执行 `maxUses` 次服务端搜索；DeepSeek 不公开专用检索端点。
+- **动态凭据的可用性在操作内部解析**——同步可用性检查可以确认解析器存在，但无法查询异步凭据存储，因此选中的无密钥提供方会使搜索以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；稳定的 `web_search` schema 仍保持注册。
+- **超量返回的来源仍消耗 token**——协议没有结果数量旋钮，`maxResults` 只能由服务在事后截断。
+- **未引用的结果没有 `snippet`**——只有当文本块引用（`cited_text`）匹配其 URL 时，来源才会获得 snippet。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放问题与尚未决定的探索方向。它明确不具权威性——已交付的行为、限制与既定理由以上文和相关 Agent Note 为准。
+
+#### 未来：专用检索端点
+
+能够避免完整模型轮次的 DeepSeek 原生搜索端点将消除主要成本；在 DeepSeek 公开此类端点之前，本提供方仍是 Messages 调用适配器。
+
+</details>

package/lib/index.js

@@ -0,0 +1,306 @@
+import z from "@deepseek-ai/schemastery";
+import { credentialRef } from "@x1a0f3n9/dsh-credentials";
+import { launchEnvironmentOf } from "@x1a0f3n9/dsh-launch-environment";
+import { WebError } from "@x1a0f3n9/dsh-web";
+//#region lib/types/provider.js
+/**
+* DeepSeek search through an Anthropic-compatible Messages model call with the native
+* `web_search_20250305` server tool. Each search costs a model turn, but returns structured
+* result blocks; absence of those blocks is an error rather than a prose-scraping fallback.
+* The wire format and native `fetch` client are provider-private and do not use `ctx.llm`.
+* @module @x1a0f3n9/dsh-web-search-deepseek/provider
+*/
+/** Stable id this provider registers under. */
+const DEEPSEEK_PROVIDER_ID = "deepseek-official";
+/**
+* Default endpoint: DeepSeek's Anthropic-compatible API, `/v1` included
+* (`/messages` is appended). This is NOT the chat-completions base
+* (`https://api.deepseek.com`) `@x1a0f3n9/dsh-llm-deepseek` uses, so this
+* provider does NOT reuse `$DEEPSEEK_BASE_URL` — only the API key is shared.
+*/
+const DEEPSEEK_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1";
+/** Default Anthropic-format model name (aligned with the repo's DeepSeek model vocabulary). */
+const DEEPSEEK_DEFAULT_MODEL = "deepseek-v4-flash";
+/** Default `anthropic-version` header value. */
+const DEEPSEEK_DEFAULT_API_VERSION = "2023-06-01";
+/** Default upper bound on generated tokens for the Messages request. */
+const DEEPSEEK_DEFAULT_MAX_TOKENS = 4096;
+/** Default maximum `web_search` server-tool uses per request. */
+const DEEPSEEK_DEFAULT_MAX_USES = 5;
+/** Attribution header sent on every request. Bump with the package version. */
+const USER_AGENT = "deepseek-harness/0.0.1";
+/**
+* Build a `url → cited_text` map from every `text` block's `citations[]`. This
+* is the snippet source: Anthropic `web_search_result` items carry
+* `url`/`title`/`page_age` but typically NO inline snippet — the excerpt lives
+* in a separate `text` block's citation, keyed by `url` (first occurrence wins).
+*
+* @param blocks - the response's content blocks; non-`text` blocks are skipped.
+* @returns the `url → cited_text` map (empty when no citations are present).
+*/
+function citationSnippets(blocks) {
+	const map = /* @__PURE__ */ new Map();
+	for (const block of blocks) {
+		if (block.type !== "text") continue;
+		for (const cite of block.citations ?? []) if (cite.url != null && cite.url.length > 0 && cite.cited_text != null && cite.cited_text.length > 0 && !map.has(cite.url)) map.set(cite.url, cite.cited_text);
+	}
+	return map;
+}
+/**
+* Map a DeepSeek Anthropic Messages response to a normalized search result. Walks
+* `web_search_tool_result` blocks for citeable `web_search_result` items, joins each to its
+* citation excerpt as `snippet`, and dedupes by `url` (a `max_uses > 1` request can surface
+* the same URL across searches). The web service owns the final `maxResults` truncation, so
+* `truncated` is always `false` here.
+*
+* @param response - the parsed Messages response body.
+* @returns the normalized result with deduped, snippet-joined sources.
+* @throws {@link WebError} when native search produced no result block.
+*/
+function mapAnthropicResponse(response) {
+	const blocks = response.content ?? [];
+	const resultBlocks = blocks.filter((block) => 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");
+	const snippets = citationSnippets(blocks);
+	const seen = /* @__PURE__ */ new Set();
+	const sources = [];
+	for (const block of resultBlocks) for (const item of block.content ?? []) {
+		if (item.type !== "web_search_result" || item.url.length === 0 || seen.has(item.url)) continue;
+		seen.add(item.url);
+		const snippet = snippets.get(item.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 } : {}
+		});
+	}
+	return {
+		sources,
+		truncated: false
+	};
+}
+/**
+* The DeepSeek-backed search provider. HTTP redirects fail as `WEB_PROVIDER_ERROR`;
+* failures after dispatch name the endpoint and tell the model how the user can configure it.
+*/
+var DeepSeekSearchProvider = class {
+	resolveOptions;
+	id = DEEPSEEK_PROVIDER_ID;
+	/**
+	* @param resolveOptions - the options for the NEXT operation, snapshotted
+	* once at each operation's entry so one search never mixes two sections. A
+	* thunk rather than a value because the plugin's settings section can change
+	* between searches, and re-registering the provider to carry a new endpoint
+	* would make the seam's selection observable to the user as a flicker.
+	*/
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	available() {
+		const options = this.resolveOptions();
+		return ((options.apiKey?.length ?? 0) > 0 || options.resolveApiKey !== void 0) && URL.canParse(options.baseURL) && isPositiveInteger(options.maxTokens) && isPositiveInteger(options.maxUses);
+	}
+	async search(request, signal) {
+		const options = this.resolveOptions();
+		const apiKey = await this.apiKey(options, signal);
+		throwIfSearchAborted(signal);
+		const endpoint = `${options.baseURL}/messages`;
+		const body = {
+			model: options.model,
+			max_tokens: options.maxTokens,
+			messages: [{
+				role: "user",
+				content: [{
+					type: "text",
+					text: `Perform a web search for the query: ${request.query}`
+				}]
+			}],
+			tools: [{
+				type: "web_search_20250305",
+				name: "web_search",
+				max_uses: options.maxUses
+			}]
+		};
+		options.recordRequest?.({
+			endpoint,
+			apiVersion: options.apiVersion,
+			body
+		});
+		throwIfSearchAborted(signal);
+		let response;
+		try {
+			response = await fetch(endpoint, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					"x-api-key": apiKey,
+					"authorization": `Bearer ${apiKey}`,
+					"anthropic-version": options.apiVersion,
+					"content-type": "application/json",
+					"accept": "application/json",
+					"user-agent": USER_AGENT
+				},
+				body: JSON.stringify(body),
+				...signal !== void 0 ? { signal } : {}
+			});
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw searchEndpointError(endpoint, `DeepSeek search request failed: ${String(error)}`, error);
+		}
+		if (!response.ok) {
+			let message = `DeepSeek API error (HTTP ${response.status})`;
+			try {
+				const parsed = await response.json();
+				const detail = typeof parsed.error === "string" ? parsed.error : parsed.error?.message ?? parsed.message;
+				if (detail !== void 0 && detail.length > 0) message += `: ${detail}`;
+			} catch (error) {
+				if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			}
+			throw searchEndpointError(endpoint, message);
+		}
+		try {
+			return mapAnthropicResponse(await response.json());
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw searchEndpointError(endpoint, error instanceof WebError ? error.message : `DeepSeek returned an unprocessable response body: ${String(error)}`, error);
+		}
+	}
+	/**
+	* Resolve one operation's credential without retaining it on the provider.
+	* @param options - the caller's snapshot, so the key and the endpoint it is sent to come from one section.
+	* @param signal - abort signal for the surrounding search.
+	* @returns the resolved key.
+	*/
+	async apiKey(options, signal) {
+		throwIfSearchAborted(signal);
+		if (options.apiKey !== void 0 && options.apiKey.length > 0) return options.apiKey;
+		let resolved;
+		try {
+			resolved = await abortable(options.resolveApiKey?.() ?? Promise.resolve(void 0), signal);
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+			throw new WebError(`DeepSeek search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (resolved !== void 0 && resolved.length > 0) return resolved;
+		throw new WebError(`DeepSeek search has no API key for "${options.apiKeyEnv ?? "DEEPSEEK_API_KEY"}"; store it through the credentials service (the web Models page writes it), export it in the launching environment, or set a literal "apiKey" in the web-search-deepseek config`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+	}
+};
+/** Add endpoint recovery instructions to failures that occur after request dispatch begins. */
+function searchEndpointError(endpoint, message, cause) {
+	return new WebError(`${message}\n\nThe web search request used endpoint ${JSON.stringify(endpoint)}. Search endpoint configuration is separate from chat. If that endpoint is not intended, guide the user to Settings > Plugins > Plugin configuration > Web search, where they can change and save Endpoint. If that settings page is unavailable, the user can set DEEPSEEK_SEARCH_BASE_URL or configure web-search-deepseek.baseURL to a trusted Anthropic-compatible Messages API base. Only the user should choose or change the endpoint.`, "WEB_PROVIDER_ERROR", cause === void 0 ? void 0 : { cause });
+}
+/**
+* Race a same-process asynchronous preflight against caller cancellation. The
+* attached settlement handlers keep observing an uncooperative operation after
+* abort so a later rejection cannot become unhandled.
+*/
+function abortable(operation, signal) {
+	if (signal === void 0) return operation;
+	if (signal.aborted) return Promise.reject(searchAborted(signal));
+	return new Promise((resolve, reject) => {
+		const onAbort = () => {
+			reject(searchAborted(signal));
+		};
+		signal.addEventListener("abort", onAbort, { once: true });
+		operation.then((value) => {
+			signal.removeEventListener("abort", onAbort);
+			resolve(value);
+		}, (error) => {
+			signal.removeEventListener("abort", onAbort);
+			reject(new Error(String(error).replace(/^Error: /u, ""), { cause: error }));
+		});
+	});
+}
+/** Throw the provider's stable cancellation error when the caller already aborted. */
+function throwIfSearchAborted(signal) {
+	if (signal?.aborted === true) throw searchAborted(signal);
+}
+/** Build the provider's stable cancellation error while retaining the caller's reason. */
+function searchAborted(signal, fallback) {
+	return new WebError("DeepSeek search aborted", "WEB_ABORTED", { cause: signal?.aborted === true ? signal.reason : fallback });
+}
+/** True for a fetch/`AbortSignal` abort, surfaced as `WEB_ABORTED`. */
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+/** True for DeepSeek request limits that can be sent to the Messages API. */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Register a DeepSeek-backed provider in `ctx.web`. It calls the Anthropic-compatible Messages API
+* with native `web_search_20250305`. The provider reuses `DEEPSEEK_API_KEY` but not
+* `DEEPSEEK_BASE_URL`, because search and chat-completions use different bases.
+* @module @x1a0f3n9/dsh-web-search-deepseek
+*/
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-search-deepseek";
+/** The web seam this provider registers into. */
+const inject = ["web"];
+const DEFAULT_API_KEY_ENV = "DEEPSEEK_API_KEY";
+const Config = z.object({
+	apiKey: z.string().role("secret"),
+	apiKeyEnv: z.string().role("credential-ref").default(DEFAULT_API_KEY_ENV),
+	baseURL: z.string(),
+	model: z.string().default(DEEPSEEK_DEFAULT_MODEL),
+	apiVersion: z.string().default(DEEPSEEK_DEFAULT_API_VERSION),
+	maxTokens: z.number().step(1).min(1).default(DEEPSEEK_DEFAULT_MAX_TOKENS),
+	maxUses: z.number().step(1).min(1).default(5)
+});
+/**
+* Environment variable naming this provider's endpoint. Deliberately distinct
+* from `$DEEPSEEK_BASE_URL`, which belongs to the chat-completions adapter:
+* search speaks the Anthropic-compatible Messages API, so one variable cannot
+* serve both.
+*/
+const SEARCH_BASE_URL_ENV = "DEEPSEEK_SEARCH_BASE_URL";
+/** Settings namespace carrying this provider's endpoint, model, and key reference. */
+const WEB_SEARCH_DEEPSEEK_SETTINGS_NAMESPACE = "web-search-deepseek";
+/**
+* Project one resolved section into the options the provider serves its next
+* search with. Environment fallbacks stay here rather than in the provider:
+* every value it reads is already fully defaulted.
+* @param ctx - plugin context supplying the credential and environment planes.
+* @param config - the currently authoritative section.
+* @returns options for one search.
+*/
+function resolveOptions(ctx, config) {
+	const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
+	const literalApiKey = config.apiKey !== void 0 && config.apiKey.length > 0 ? config.apiKey : void 0;
+	return {
+		...literalApiKey === void 0 ? {} : { apiKey: literalApiKey },
+		resolveApiKey: async () => {
+			const credentials = ctx.get("credentials");
+			if (credentials !== void 0) return (await credentials.resolve(apiKeyEnv))?.value;
+			const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
+			return ambient !== void 0 && ambient.value.length > 0 ? ambient.value : void 0;
+		},
+		apiKeyEnv,
+		baseURL: config.baseURL ?? launchEnvironmentOf(ctx).get(SEARCH_BASE_URL_ENV)?.value ?? "https://api.deepseek.com/anthropic/v1",
+		model: config.model ?? "deepseek-v4-flash",
+		apiVersion: config.apiVersion ?? "2023-06-01",
+		maxTokens: config.maxTokens ?? 4096,
+		maxUses: config.maxUses ?? 5,
+		recordRequest: (request) => {
+			ctx.get("agents")?.currentInitiator()?.session.append("web/deepseek-search-llm-request", request);
+		}
+	};
+}
+/** Register the DeepSeek search provider with `ctx.web`. */
+function apply(ctx, config) {
+	let current = () => config;
+	ctx.inject(["settings"], (settingsCtx) => {
+		settingsCtx.settings.installSection(ctx, WEB_SEARCH_DEEPSEEK_SETTINGS_NAMESPACE, Config, config, {
+			setSource: (source) => {
+				current = source;
+			},
+			onChange: () => {}
+		});
+	});
+	ctx.web.registerSearchProvider(new DeepSeekSearchProvider(() => resolveOptions(ctx, current())));
+}
+//#endregion
+export { Config, DEEPSEEK_DEFAULT_API_VERSION, DEEPSEEK_DEFAULT_BASE_URL, DEEPSEEK_DEFAULT_MAX_TOKENS, DEEPSEEK_DEFAULT_MAX_USES, DEEPSEEK_DEFAULT_MODEL, DEEPSEEK_PROVIDER_ID, DeepSeekSearchProvider, WEB_SEARCH_DEEPSEEK_SETTINGS_NAMESPACE, apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Register a DeepSeek-backed provider in `ctx.web`. It calls the Anthropic-compatible Messages API
+ * with native `web_search_20250305`. The provider reuses `DEEPSEEK_API_KEY` but not
+ * `DEEPSEEK_BASE_URL`, because search and chat-completions use different bases.
+ * @module @x1a0f3n9/dsh-web-search-deepseek
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export { DeepSeekSearchProvider, DEEPSEEK_DEFAULT_API_VERSION, DEEPSEEK_DEFAULT_BASE_URL, DEEPSEEK_DEFAULT_MAX_TOKENS, DEEPSEEK_DEFAULT_MAX_USES, DEEPSEEK_DEFAULT_MODEL, DEEPSEEK_PROVIDER_ID, } from './provider.ts';
+export type { DeepSeekSearchLlmRequest, DeepSeekSearchProviderOptions } from './provider.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-search-deepseek";
+/** The web seam this provider registers into. */
+export declare const inject: string[];
+/** Plugin config (all optional — `apply` fills env-var and constant defaults). */
+export interface Config {
+    /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+    apiKey?: string;
+    /** Credential reference resolved for each search; defaults to `DEEPSEEK_API_KEY`. */
+    apiKeyEnv?: string;
+    /** Anthropic-compatible endpoint base; `/messages` is appended. */
+    baseURL?: string;
+    /** Anthropic-format model name. Defaults to `deepseek-v4-flash`. */
+    model?: string;
+    /** `anthropic-version` header value. Defaults to `2023-06-01`. */
+    apiVersion?: string;
+    /** Upper bound on generated tokens for the Messages request. Defaults to 4096. */
+    maxTokens?: number;
+    /** Maximum `web_search` server-tool uses per request. Defaults to 5. */
+    maxUses?: number;
+}
+export declare const Config: z<Config>;
+/** Settings namespace carrying this provider's endpoint, model, and key reference. */
+export declare const WEB_SEARCH_DEEPSEEK_SETTINGS_NAMESPACE = "web-search-deepseek";
+/** Register the DeepSeek search provider with `ctx.web`. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/provider.d.ts

@@ -0,0 +1,138 @@
+/**
+ * DeepSeek search through an Anthropic-compatible Messages model call with the native
+ * `web_search_20250305` server tool. Each search costs a model turn, but returns structured
+ * result blocks; absence of those blocks is an error rather than a prose-scraping fallback.
+ * The wire format and native `fetch` client are provider-private and do not use `ctx.llm`.
+ * @module @x1a0f3n9/dsh-web-search-deepseek/provider
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@x1a0f3n9/dsh-web';
+import type { CredentialRef } from '@x1a0f3n9/dsh-credentials';
+import type { AnthropicResponse, ContentBlock } from './types.ts';
+/** Stable id this provider registers under. */
+export declare const DEEPSEEK_PROVIDER_ID = "deepseek-official";
+/**
+ * Default endpoint: DeepSeek's Anthropic-compatible API, `/v1` included
+ * (`/messages` is appended). This is NOT the chat-completions base
+ * (`https://api.deepseek.com`) `@x1a0f3n9/dsh-llm-deepseek` uses, so this
+ * provider does NOT reuse `$DEEPSEEK_BASE_URL` — only the API key is shared.
+ */
+export declare const DEEPSEEK_DEFAULT_BASE_URL = "https://api.deepseek.com/anthropic/v1";
+/** Default Anthropic-format model name (aligned with the repo's DeepSeek model vocabulary). */
+export declare const DEEPSEEK_DEFAULT_MODEL = "deepseek-v4-flash";
+/** Default `anthropic-version` header value. */
+export declare const DEEPSEEK_DEFAULT_API_VERSION = "2023-06-01";
+/** Default upper bound on generated tokens for the Messages request. */
+export declare const DEEPSEEK_DEFAULT_MAX_TOKENS = 4096;
+/** Default maximum `web_search` server-tool uses per request. */
+export declare const DEEPSEEK_DEFAULT_MAX_USES = 5;
+/**
+ * Exact secret-free DeepSeek Messages request recorded immediately before one
+ * auxiliary search dispatch.
+ */
+export interface DeepSeekSearchLlmRequest {
+    /** Fully resolved Messages endpoint. */
+    readonly endpoint: string;
+    /** `anthropic-version` header value. */
+    readonly apiVersion: string;
+    /** Exact JSON body sent to the provider. */
+    readonly body: {
+        readonly model: string;
+        readonly max_tokens: number;
+        readonly messages: readonly [
+            {
+                readonly role: 'user';
+                readonly content: readonly [
+                    {
+                        readonly type: 'text';
+                        readonly text: string;
+                    }
+                ];
+            }
+        ];
+        readonly tools: readonly [
+            {
+                readonly type: 'web_search_20250305';
+                readonly name: 'web_search';
+                readonly max_uses: number;
+            }
+        ];
+    };
+}
+declare module '@x1a0f3n9/dsh-session/types' {
+    interface SessionEventMap {
+        /** Secret-free auxiliary DeepSeek search request recorded before dispatch. */
+        'web/deepseek-search-llm-request': DeepSeekSearchLlmRequest;
+    }
+}
+/** Resolved provider options (the plugin's `apply` supplies credential and constant defaults). */
+export interface DeepSeekSearchProviderOptions {
+    /** Literal DeepSeek API key; when present it wins over {@link resolveApiKey}. */
+    apiKey?: string;
+    /** Resolve the current DeepSeek API key for one search operation. */
+    resolveApiKey?: () => Promise<string | undefined>;
+    /** Credential reference named by missing-credential diagnostics. */
+    apiKeyEnv?: CredentialRef;
+    /** Endpoint base; `/messages` is appended. */
+    baseURL: string;
+    /** Anthropic-format model name. */
+    model: string;
+    /** `anthropic-version` header value. */
+    apiVersion: string;
+    /** Upper bound on generated tokens for the Messages request. */
+    maxTokens: number;
+    /** Maximum `web_search` server-tool uses per request. */
+    maxUses: number;
+    /**
+     * Record the exact secret-free request immediately before dispatch. A throw
+     * prevents dispatch so model-visible auxiliary input cannot escape logging.
+     */
+    recordRequest?: (request: DeepSeekSearchLlmRequest) => void;
+}
+/**
+ * Build a `url → cited_text` map from every `text` block's `citations[]`. This
+ * is the snippet source: Anthropic `web_search_result` items carry
+ * `url`/`title`/`page_age` but typically NO inline snippet — the excerpt lives
+ * in a separate `text` block's citation, keyed by `url` (first occurrence wins).
+ *
+ * @param blocks - the response's content blocks; non-`text` blocks are skipped.
+ * @returns the `url → cited_text` map (empty when no citations are present).
+ */
+export declare function citationSnippets(blocks: readonly ContentBlock[]): Map<string, string>;
+/**
+ * Map a DeepSeek Anthropic Messages response to a normalized search result. Walks
+ * `web_search_tool_result` blocks for citeable `web_search_result` items, joins each to its
+ * citation excerpt as `snippet`, and dedupes by `url` (a `max_uses > 1` request can surface
+ * the same URL across searches). The web service owns the final `maxResults` truncation, so
+ * `truncated` is always `false` here.
+ *
+ * @param response - the parsed Messages response body.
+ * @returns the normalized result with deduped, snippet-joined sources.
+ * @throws {@link WebError} when native search produced no result block.
+ */
+export declare function mapAnthropicResponse(response: AnthropicResponse): WebSearchResult;
+/**
+ * The DeepSeek-backed search provider. HTTP redirects fail as `WEB_PROVIDER_ERROR`;
+ * failures after dispatch name the endpoint and tell the model how the user can configure it.
+ */
+export declare class DeepSeekSearchProvider implements WebSearchProvider {
+    private readonly resolveOptions;
+    readonly id = "deepseek-official";
+    /**
+     * @param resolveOptions - the options for the NEXT operation, snapshotted
+     * once at each operation's entry so one search never mixes two sections. A
+     * thunk rather than a value because the plugin's settings section can change
+     * between searches, and re-registering the provider to carry a new endpoint
+     * would make the seam's selection observable to the user as a flicker.
+     */
+    constructor(resolveOptions: () => DeepSeekSearchProviderOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+    /**
+     * Resolve one operation's credential without retaining it on the provider.
+     * @param options - the caller's snapshot, so the key and the endpoint it is sent to come from one section.
+     * @param signal - abort signal for the surrounding search.
+     * @returns the resolved key.
+     */
+    private apiKey;
+}
+//# sourceMappingURL=provider.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Provider-private wire types for DeepSeek's Anthropic-compatible Messages API. Citeable
+ * result items and citation excerpts arrive in separate blocks; the provider joins them by
+ * URL. These types do not create a dependency on `ctx.llm`.
+ * @module @x1a0f3n9/dsh-web-search-deepseek/types
+ */
+/** A `web_search_result` item inside a `web_search_tool_result` block. */
+export interface WebSearchResultItem {
+    type: string;
+    url: string;
+    title?: string | null;
+    /** Provider-supplied page age/recency string (mapped to `publishedAt`). */
+    page_age?: string | null;
+}
+/** A `web_search_tool_result` content block: the citeable result shape. */
+export interface WebSearchToolResultBlock {
+    type: 'web_search_tool_result';
+    content?: WebSearchResultItem[];
+}
+/** One citation location inside a `text` block (the snippet source). */
+export interface CitationLocation {
+    type?: string;
+    url?: string | null;
+    cited_text?: string | null;
+}
+/** A `text` content block: the model's prose plus per-URL citations. */
+export interface TextBlock {
+    type: 'text';
+    text?: string | null;
+    citations?: CitationLocation[];
+}
+/** Any content block; only `web_search_tool_result` and `text` are consumed. */
+export type ContentBlock = WebSearchToolResultBlock | TextBlock | {
+    type: string;
+};
+/** DeepSeek's Anthropic Messages response envelope. */
+export interface AnthropicResponse {
+    content?: ContentBlock[];
+}
+/** DeepSeek's error response envelope (best-effort; fields vary). */
+export interface AnthropicError {
+    error?: {
+        message?: string;
+    } | string;
+    message?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@x1a0f3n9/dsh-web-search-deepseek",
+  "description": "DeepSeek-backed search provider (native web_search via the Anthropic-compatible API) for the DeepSeek Harness web capability seam (ctx.web)",
+  "version": "0.1.5-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/web/web-search-deepseek"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@x1a0f3n9/dsh-credentials": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-settings": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.2"
+  },
+  "devDependencies": {
+    "@x1a0f3n9/dsh-agent": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-credentials": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-session": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-credentials-local": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-launch-environment": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-web": "^0.1.5-rc.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@x1a0f3n9/dsh-settings": "^0.1.5-rc.2",
+    "@x1a0f3n9/dsh-http-proxy": "^0.1.5-rc.2"
+  }
+}