@qilin-agent/web-deepseek-api 0.0.0-stage → 3.1.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+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,49 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/web/web-deepseek-api/README.md
+/:
+  en: eb52169ad8cf3b38
+  zh: 4b91a4dc90777892
+/qilin-agent-web-deepseek-api:
+  en: 573be37817f28e89
+  zh: db508a438c0956c2
+/qilin-agent-web-deepseek-api/summary:
+  en: 4b7dde72d306e8fb
+  zh: b87b4113682a0f09
+/qilin-agent-web-deepseek-api/table-of-contents:
+  en: 76368b6b1da79c80
+  zh: 23ef7314e660bd7d
+/qilin-agent-web-deepseek-api/use-this-package:
+  en: 1b958fb5099eeb23
+  zh: e3533327f06598f6
+/qilin-agent-web-deepseek-api/use-this-package/authentication:
+  en: 57e660a47bc199e6
+  zh: 29f2cad58f71eef2
+/qilin-agent-web-deepseek-api/use-this-package/results-and-failures:
+  en: c9c724975ab64fe9
+  zh: 13a82ad855885f44
+/qilin-agent-web-deepseek-api/understand-the-implementation:
+  en: 61b1cc1b860121a1
+  zh: 5cf63ec1998d0234
+/qilin-agent-web-deepseek-api/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-web-deepseek-api/model-experience/conversation-tool-results:
+  en: dfd3b61aff4a8aa8
+  zh: 06e2b6cc71f461e2
+/qilin-agent-web-deepseek-api/model-experience/conversation-tool-results/what-the-model-sees:
+  en: a9fbb78ffe886f0b
+  zh: cb6840241bed1b40
+/qilin-agent-web-deepseek-api/model-experience/conversation-tool-results/token-effect:
+  en: d82cd03f38fb4b38
+  zh: 8348604fae11cd82
+/qilin-agent-web-deepseek-api/model-experience/conversation-tool-results/kv-cache-effect:
+  en: 54ed534b58469807
+  zh: fe809bb4f17e0e8e
+/qilin-agent-web-deepseek-api/known-limitations-and-deferred-work:
+  en: 8aeb97e282d1dcab
+  zh: 900004bd43bae32d
+/qilin-agent-web-deepseek-api/known-limitations-and-deferred-work/dev-note:
+  en: 0a1253c6f7b5e8b9
+  zh: 9f56528562c7c914

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+---
+description: "DeepSeek Search and Fetch API providers, their shared authentication and transport, endpoint configuration, and normalized results."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/web-deepseek-api
+
+English | [中文](README.zh.md)
+
+## Summary
+
+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 resolved per operation. Search returns titles, URLs, available snippets, and available publication dates; Fetch returns page Markdown. Messages search stays in [qilin-web-search-deepseek](../web-search-deepseek/README.md); the model-facing tools live in [qilin-tool-web](../tool-web/README.md).
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [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 plugin alongside `qilin-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.
+
+```yaml
+- name: '@qilin-agent/web'
+  config:
+    searchProvider: deepseek-search-api
+    fetchProvider: deepseek-fetch-api
+- name: '@qilin-agent/web-deepseek-api'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+```
+
+| Field | Default | Meaning |
+|---|---|---|
+| `apiKey` | omitted | Literal API key; prefer a credential reference |
+| `apiKeyEnv` | `DEEPSEEK_API_KEY` | Credential reference resolved for each operation |
+| `baseURL` | `https://api.deepseek.com/v1/tools` | Search and Fetch API base including its deployment path prefix; append `/search` or `/fetch` |
+| `count` | `10` | Search API results per search, an integer from 1 to 50; a smaller `maxResults` on the request wins |
+| `sendOriginalQuestion` | `true` | Send the triggering human prompt, cut to 128 characters, as the Search API's `ori_question` |
+
+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.
+
+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.
+
+### Authentication
+
+A non-empty literal `apiKey` wins over `apiKeyEnv`; the reference resolves through `ctx.credentials`, or the launch environment when that service is absent. Requests carry `Authorization: Bearer`. Credential resolution and endpoint selection share one settings snapshot. QiLin ships no account-token route, so every operation authenticates with this key.
+
+### Results and failures
+
+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` directly and maps nullable `date` to optional `publishedAt`. 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.
+
+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. Dispatch failures identify the endpoint and the `baseURL` settings field. No automatic retry or provider fallback occurs.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+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. Search and Fetch API calls emit no auxiliary request event: the Search API needs no auxiliary model turn, so there is no request to record. Tool calls and results retain their normal Session logging.
+
+See the [web subsystem](../../../docs/subsystems/web.md) for service types and [tool-web](../tool-web/README.md) for bounded model output.
+
+</details>
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Conversation tool results
+
+#### What the model sees
+
+The `web_search` and `web_fetch` tools render sources or Markdown with an external-content notice. Fetch results carry the requested URL and HTTP 200. Errors retain actionable credential or endpoint guidance. Search sends the query, with the triggering question, directly to the Search API.
+
+#### Token effect
+
+No auxiliary model tokens are consumed. Conversation result tokens scale with returned snippets or Markdown and are bounded by the consumer. API retrieval billing is independent of model tokens.
+
+#### KV Cache effect
+
+Tool results append after the existing conversation prefix. Provider registration adds no model context.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- The shared search request does not expose `localization`; the provider requests snippets only and does not consume `summary`, `site_name`, `site_icon`, or full search content.
+- The provider sends `ori_question` because the guide documents it as an intent signal; the adapter ignores any response term that would rank by it.
+- API query and URL constraints are enforced by the remote service. 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.
+- Availability checks cannot query asynchronous credential stores. A configured resolver can still fail with a missing-credential error when called.
+
+<a id="dev-note"></a>
+### Dev Note
+
+None.

package/README.zh.md

@@ -0,0 +1,106 @@
+---
+description: "DeepSeek Search 与 Fetch API 提供方：共享的认证与传输、端点配置与归一化结果。"
+kind: "package-reference"
+---
+
+# @qilin-agent/web-deepseek-api
+
+[English](README.md) | 中文
+
+## 概述
+
+通过 DeepSeek Search 与 Fetch API 搜索网页、抓取网页正文：每个操作一次直接请求，不需要辅助模型轮次。插件注册 `deepseek-search-api` 与 `deepseek-fetch-api`，两者共享同一凭据与同一 API 基础地址，并在每次操作解析 API Key 完成认证。搜索返回标题、URL、可用的摘要与可用的发布日期；Fetch 返回网页 Markdown。Messages 搜索仍由 [qilin-web-search-deepseek](../web-search-deepseek/README.zh.md) 提供；面向模型的工具位于 [qilin-tool-web](../tool-web/README.zh.md)。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [了解实现](#understand-the-implementation)
+- [模型体验](#model-experience)
+- [已知限制与延后工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+把插件与 `qilin-web` 一起挂载并选择它的提供方。随包部署挂载它，同时仍选择 Messages 搜索与本地 HTTP 抓取。在 **Plugins > Built-in plugin settings > Web search** 打开 **启用新版 Web 搜索 API** 并保存，会同时选中本包的两个提供方；关闭后恢复随包选择。保存的选择作用于下一次操作。
+
+```yaml
+- name: '@qilin-agent/web'
+  config:
+    searchProvider: deepseek-search-api
+    fetchProvider: deepseek-fetch-api
+- name: '@qilin-agent/web-deepseek-api'
+  config:
+    apiKeyEnv: DEEPSEEK_API_KEY
+```
+
+| 字段 | 默认值 | 含义 |
+|---|---|---|
+| `apiKey` | 省略 | 字面 API Key；优先使用凭据引用 |
+| `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`）的部署需要填写自己的完整地址。
+
+用 `DEEPSEEK_API_KEY` 与 `DEEPSEEK_SEARCH_API_TEST_BASE_URL` 运行真实 API 测试：两者都必须提供，后者包含 API 路径前缀。
+
+### 认证
+
+非空字面 `apiKey` 优先于 `apiKeyEnv`；凭据引用经 `ctx.credentials` 解析，该服务缺席时回落到启动环境。请求携带 `Authorization: Bearer`。凭据解析与端点选择共享同一份设置快照。QiLin 不提供账号令牌路径，因此每个操作都用该 Key 认证。
+
+### 结果与失败
+
+Search API 接收 `query`、`count`（配置的条数，或请求上更小的 `maxResults`）、`need_content: false`，以及 `ori_question`（`sendOriginalQuestion` 关闭时省略）：发起 Session 最近一条人类提示词的文本，空白折叠后截断到 128 个字符。不在 Session 内或没有此类提示词时省略。提供方直接映射 `results[].snippet`，把可为 null 的 `date` 映射为可选 `publishedAt`。结果数组为空视为成功。Fetch 发送 `url`，把原始 Markdown 作为文本主体返回，状态码为 HTTP 200，因为目标没有可用内容时 API 会以错误状态应答。其 URL 就是请求的 URL：API 不报告最终重定向地址。
+
+`baseURL` 为空或不可解析会使两个提供方不可用；`count` 超出 1 到 50 会使搜索不可用。凭据缺失以 `WEB_PROVIDER_CREDENTIAL_MISSING` 失败；取消使用 `WEB_ABORTED`；传输、HTTP 与畸形响应失败使用 `WEB_PROVIDER_ERROR`。重定向会在接触目标之前被拒绝。Fetch API 的非成功状态是检索失败，不是目标页面的状态。请求发出后的失败会指出端点与 `baseURL` 设置字段。不进行自动重试，也不回落到其他提供方。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 了解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+[插件](src/index.ts)在每次操作读取一次设置并注册两个提供方。[Search 提供方](src/search.ts)在返回服务结果前校验响应 JSON；[Fetch 提供方](src/fetch.ts)校验 Markdown 主体。[传输层](src/transport.ts)负责凭据解析、取消、重定向拒绝与失败指引。Search 与 Fetch API 调用不产生辅助请求事件：Search API 不需要辅助模型轮次，因此没有需要记录的请求。工具调用与结果保持常规的 Session 记录。
+
+服务类型见 [web 子系统](../../../docs/subsystems/web.zh.md)，受限的模型输出见 [tool-web](../tool-web/README.zh.md)。
+
+</details>
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 会话工具结果
+
+#### 模型看到的内容
+
+`web_search` 与 `web_fetch` 工具会附带外部内容提示渲染来源或 Markdown。Fetch 结果携带请求的 URL 与 HTTP 200。错误保留可执行的凭据或端点指引。搜索把查询与触发问题直接发送给 Search API。
+
+#### Token 影响
+
+不消耗辅助模型 token。会话结果 token 随返回的摘要或 Markdown 规模变化，并由消费方设上限。API 检索计费独立于模型 token。
+
+#### KV Cache 影响
+
+工具结果追加在已有会话前缀之后。提供方注册不增加模型上下文。
+
+## 已知限制与延后工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- 共享的搜索请求不暴露 `localization`；提供方只请求摘要，不使用 `summary`、`site_name`、`site_icon` 或完整搜索内容。
+- 提供方发送 `ori_question`，因为指南把它记录为意图信号；适配器不消费任何按它排序的响应项。
+- API 的查询与 URL 约束由远端服务执行。Fetch 不暴露目标状态，也不暴露最终重定向 URL，因此结果报告 HTTP 200 与请求的 URL；提供方丢弃 API 的页面标题。
+- 可用性检查无法查询异步凭据存储。已配置的解析器在调用时仍可能以凭据缺失错误失败。
+
+<a id="dev-note"></a>
+### 开发备注
+
+无。

package/lib/index.js

@@ -0,0 +1,372 @@
+import z from "@qilin-agent/schemastery";
+import { credentialRef } from "@qilin-agent/credentials";
+import { launchEnvironmentOf } from "@qilin-agent/launch-environment";
+import { WebError } from "@qilin-agent/web";
+//#region lib/types/transport.js
+const USER_AGENT = "deepseek-harness/0.0.1";
+/**
+* Resolve credential sources for one operation without retaining secret values.
+* @param ctx - Provider context with request routing and credential services.
+* @param config - Literal key and credential reference from the settings snapshot.
+* @returns Authentication sources for one operation.
+*/
+function deepSeekWebAuth(ctx, config) {
+	const apiKeyEnv = credentialRef(config.apiKeyEnv);
+	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
+	};
+}
+/**
+* Check whether an authentication source exists; does not resolve credentials.
+* @param auth - Sources for the operation.
+* @returns Whether a literal key or resolver is present.
+*/
+function hasDeepSeekWebCredential(auth) {
+	return (auth.apiKey?.length ?? 0) > 0 || auth.resolveApiKey !== void 0;
+}
+/** Narrow a remote JSON object.
+* @param value - Untrusted JSON.
+* @returns Whether readable object fields exist.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/** Report malformed upstream JSON without embedding response content.
+* @returns The stable provider error.
+*/
+function invalidResponse() {
+	return new WebError("DeepSeek returned an invalid response body", "WEB_PROVIDER_ERROR");
+}
+/** Dispatch one operation using a single settings and credential snapshot.
+* @param options - Authentication sources for this operation.
+* @param request - Resolved endpoint, JSON payload, and response decoder.
+* @param signal - Caller cancellation signal.
+* @returns The validated provider result.
+*/
+async function dispatchDeepSeekWeb(options, request, signal) {
+	const { endpoint, body, decode, recordRequest, guidance } = request;
+	const headers = await authHeaders(options, request, signal);
+	throwIfSearchAborted(signal);
+	recordRequest?.(endpoint);
+	throwIfSearchAborted(signal);
+	let response;
+	try {
+		response = await fetch(endpoint, {
+			method: "POST",
+			redirect: "error",
+			headers: {
+				...headers,
+				...request.headers,
+				"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(guidance, endpoint, `DeepSeek web request failed: ${String(error)}`, error);
+	}
+	if (!response.ok) {
+		let message = `DeepSeek API error (HTTP ${response.status})`;
+		try {
+			const parsed = await response.json();
+			if (isRecord(parsed)) {
+				const detail = typeof parsed.error === "string" ? parsed.error : isRecord(parsed.error) ? parsed.error.message : parsed.message;
+				if (typeof detail === "string" && detail.length > 0) message += `: ${detail}`;
+			}
+		} catch (error) {
+			if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+		}
+		throw searchEndpointError(guidance, endpoint, message);
+	}
+	try {
+		const payload = await response.json();
+		throwIfSearchAborted(signal);
+		return decode(payload);
+	} catch (error) {
+		if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+		throw searchEndpointError(guidance, endpoint, error instanceof WebError ? error.message : `DeepSeek returned an unprocessable response body: ${String(error)}`, error);
+	}
+}
+/**
+* Add endpoint recovery instructions to failures that occur after request dispatch begins.
+* @param options - the plugin, settings field, and settings page the guidance names.
+* @param endpoint - the dispatched endpoint.
+* @param message - the failure description.
+* @param cause - the underlying failure, when one exists.
+* @returns the provider failure with recovery instructions.
+*/
+function searchEndpointError(options, endpoint, message, cause) {
+	return new WebError(`${message}\n\nThe web request used endpoint ${JSON.stringify(endpoint)}. ${options.subject} endpoint configuration is separate from chat. If that endpoint is not intended, guide the user to Plugins > Built-in plugin settings > ${options.page}, where they can change and save ${options.label}. If that settings page is unavailable, the user can set ${options.plugin}.${options.field} to a trusted DeepSeek endpoint. Only the user should choose or change the endpoint.`, "WEB_PROVIDER_ERROR", cause === void 0 ? void 0 : { cause });
+}
+/**
+* Resolve one operation's authentication headers without retaining a credential on the provider.
+* @param options - the caller's snapshot, so the credential and the endpoint it is sent to come from one section.
+* @param request - the resolved request.
+* @param signal - abort signal for the surrounding operation.
+* @returns the API-key headers for this operation.
+*/
+async function authHeaders(options, request, signal) {
+	const apiKey = await resolveApiKey(options, request.guidance.plugin, signal);
+	return {
+		...request.apiKeyHeaders?.(apiKey),
+		"authorization": `Bearer ${apiKey}`
+	};
+}
+/**
+* Resolve one operation's API key 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 plugin - configuration namespace named by the missing-key diagnostic.
+* @param signal - abort signal for the surrounding operation.
+* @returns the resolved key.
+*/
+async function resolveApiKey(options, plugin, signal) {
+	throwIfSearchAborted(signal);
+	if (options.apiKey !== void 0 && options.apiKey.length > 0) return options.apiKey;
+	const { resolveApiKey } = options;
+	const resolved = resolveApiKey === void 0 ? void 0 : await resolveCredential(resolveApiKey, signal);
+	if (resolved !== void 0 && resolved.length > 0) return resolved;
+	throw new WebError(`DeepSeek web access 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 ${plugin} config`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+}
+/**
+* Run one credential resolver under the search's cancellation signal. An
+* already-cancelled search never starts the resolver.
+* @param resolve - the resolver; a synchronous throw is mapped like a rejection.
+* @param signal - abort signal for the surrounding search.
+* @returns the resolved credential, or undefined when the resolver supplied none.
+* @throws {@link WebError} `WEB_ABORTED` on cancellation, `WEB_PROVIDER_ERROR` when the resolver fails.
+*/
+async function resolveCredential(resolve, signal) {
+	throwIfSearchAborted(signal);
+	try {
+		return await abortable(resolve(), signal);
+	} catch (error) {
+		if (signal?.aborted === true || isAbortError(error)) throw searchAborted(signal, error);
+		throw new WebError(`DeepSeek web credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+	}
+}
+/**
+* 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 web request 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";
+}
+//#endregion
+//#region lib/types/search.js
+/** Stable id the Search API provider registers under in the search registry. */
+const DEEPSEEK_SEARCH_API_PROVIDER_ID = "deepseek-search-api";
+/** Default Search and Fetch API base, including its `/v1/tools` prefix; `/search` and `/fetch` are appended. */
+const DEEPSEEK_WEB_API_BASE_URL = "https://api.deepseek.com/v1/tools";
+/** Default Search API result count, the service's own default. */
+const DEEPSEEK_DEFAULT_COUNT = 10;
+/** Longest `ori_question` the Search API accepts, in characters. */
+const ORIGINAL_QUESTION_MAX_CHARS = 128;
+/** Settings named by endpoint failures of either API in this package. */
+const DEEPSEEK_WEB_API_GUIDANCE = {
+	plugin: "web-deepseek-api",
+	field: "baseURL",
+	label: "Search / Fetch API base URL",
+	page: "Web search"
+};
+/**
+* Validate a Search API response and project its sources into the web service.
+* @param response - untrusted JSON from the Search endpoint.
+* @returns sources with provider order and nullable publication dates preserved.
+* @throws {@link WebError} when the response does not contain valid search results.
+*/
+function mapSearchResponse(response) {
+	if (!isRecord(response) || !Array.isArray(response.results)) throw invalidResponse();
+	return {
+		sources: response.results.map((item) => {
+			if (!isRecord(item) || typeof item.url !== "string" || item.url.length === 0 || typeof item.title !== "string" || typeof item.snippet !== "string" || item.date !== null && typeof item.date !== "string") throw invalidResponse();
+			return {
+				url: item.url,
+				...item.title.length > 0 ? { title: item.title } : {},
+				...item.snippet.length > 0 ? { snippet: item.snippet } : {},
+				...item.date !== null && item.date.length > 0 ? { publishedAt: item.date } : {}
+			};
+		}),
+		truncated: false
+	};
+}
+/**
+* Search through the DeepSeek Search API. HTTP redirects fail as `WEB_PROVIDER_ERROR`;
+* failures after dispatch name the endpoint and tell the model how the user can configure it.
+*/
+var DeepSeekSearchApiProvider = class {
+	resolveOptions;
+	id = DEEPSEEK_SEARCH_API_PROVIDER_ID;
+	/**
+	* @param resolveOptions - the options for the NEXT search, read once at each
+	* search's entry so one search never mixes two settings sections.
+	*/
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	available() {
+		const options = this.resolveOptions();
+		return hasDeepSeekWebCredential(options) && URL.canParse(options.baseURL) && isPositiveInteger(options.count);
+	}
+	search(request, signal) {
+		const options = this.resolveOptions();
+		const question = boundedQuestion(options.originalQuestion?.());
+		return dispatchDeepSeekWeb(options, {
+			endpoint: `${options.baseURL.replace(/\/+$/u, "")}/search`,
+			body: {
+				query: request.query,
+				count: Math.min(options.count, request.maxResults ?? options.count),
+				need_content: false,
+				...question === void 0 ? {} : { ori_question: question }
+			},
+			decode: mapSearchResponse,
+			guidance: {
+				subject: "Search",
+				...DEEPSEEK_WEB_API_GUIDANCE
+			}
+		}, signal);
+	}
+};
+/**
+* Bound the triggering question to what `ori_question` accepts: whitespace
+* collapses to single spaces and the first 128 characters remain.
+* @param question - the user question, when one exists.
+* @returns the bounded question, or undefined when nothing remains.
+*/
+function boundedQuestion(question) {
+	const collapsed = question?.replace(/\s+/gu, " ").trim() ?? "";
+	if (collapsed.length === 0) return void 0;
+	return Array.from(collapsed).slice(0, ORIGINAL_QUESTION_MAX_CHARS).join("");
+}
+/** True for positive integral request limits. */
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+//#endregion
+//#region lib/types/fetch.js
+/** Stable id the Fetch API provider registers under in the fetch registry. */
+const DEEPSEEK_FETCH_API_PROVIDER_ID = "deepseek-fetch-api";
+/**
+* Fetch page Markdown through the DeepSeek Fetch API. The API reports neither the
+* target's status nor a final URL, and it fails when the target yields no usable
+* content, so a success is the requested page retrieved with HTTP 200.
+*/
+var DeepSeekFetchApiProvider = class {
+	resolveOptions;
+	id = DEEPSEEK_FETCH_API_PROVIDER_ID;
+	/** @param resolveOptions - the options for the NEXT fetch, read once at each fetch's entry. */
+	constructor(resolveOptions) {
+		this.resolveOptions = resolveOptions;
+	}
+	available() {
+		const options = this.resolveOptions();
+		return hasDeepSeekWebCredential(options) && URL.canParse(options.baseURL);
+	}
+	fetch(request, signal) {
+		const options = this.resolveOptions();
+		return dispatchDeepSeekWeb(options, {
+			endpoint: `${options.baseURL.replace(/\/+$/u, "")}/fetch`,
+			body: { url: request.url },
+			decode: (payload) => {
+				if (!isRecord(payload) || typeof payload.content !== "string") throw invalidResponse();
+				return {
+					url: request.url,
+					statusCode: 200,
+					body: {
+						kind: "text",
+						content: payload.content
+					},
+					truncated: false
+				};
+			},
+			guidance: {
+				subject: "Fetch",
+				...DEEPSEEK_WEB_API_GUIDANCE
+			}
+		}, signal);
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/** Cordis plugin name used by loader diagnostics. */
+const name = "web-deepseek-api";
+/** The web seam both providers register into. */
+const inject = ["web"];
+const Config = z.object({
+	apiKey: z.string().role("secret").volatile(),
+	apiKeyEnv: z.string().role("credential-ref").default("DEEPSEEK_API_KEY").volatile(),
+	baseURL: z.string().default(DEEPSEEK_WEB_API_BASE_URL).volatile(),
+	count: z.number().step(1).min(1).max(50).default(10).volatile(),
+	sendOriginalQuestion: z.boolean().default(true).volatile()
+});
+/**
+* Read the text of the latest human prompt, the question that triggered the
+* current turn. Injected user-role context carries another source kind.
+* @param session - the initiating Session, when the search runs inside one.
+* @returns the prompt's joined text blocks, or undefined without a prompt.
+*/
+function latestUserQuestion(session) {
+	const prompt = session?.deriveMessages().findLast((message) => message.role === "user" && message.source.kind === "user");
+	if (prompt === void 0) return void 0;
+	return prompt.content.flatMap((block) => block.type === "text" ? [block.text] : []).join("\n");
+}
+/**
+* Register the Search API and Fetch API providers over one live settings section.
+* @param ctx - plugin context owning both registrations.
+* @param config - live settings, read once per operation.
+*/
+function apply(ctx, config) {
+	const auth = () => deepSeekWebAuth(ctx, {
+		apiKey: config.apiKey.get(),
+		apiKeyEnv: config.apiKeyEnv.get()
+	});
+	ctx.web.registerSearchProvider(new DeepSeekSearchApiProvider(() => ({
+		...auth(),
+		baseURL: config.baseURL.get(),
+		count: config.count.get(),
+		...config.sendOriginalQuestion.get() ? { originalQuestion: () => latestUserQuestion(ctx.get("agents")?.currentInitiator()?.session) } : {}
+	})));
+	ctx.web.registerFetchProvider(new DeepSeekFetchApiProvider(() => ({
+		...auth(),
+		baseURL: config.baseURL.get()
+	})));
+}
+//#endregion
+export { Config, DEEPSEEK_DEFAULT_COUNT, DEEPSEEK_FETCH_API_PROVIDER_ID, DEEPSEEK_SEARCH_API_PROVIDER_ID, DEEPSEEK_WEB_API_BASE_URL, DeepSeekFetchApiProvider, DeepSeekSearchApiProvider, apply, inject, mapSearchResponse, name };

package/lib/types/fetch.d.ts

@@ -0,0 +1,28 @@
+/**
+ * DeepSeek Fetch API provider: page Markdown through one direct request, without
+ * a model request.
+ * @module @qilin-agent/web-deepseek-api/fetch
+ */
+import type { WebFetchProvider, WebFetchRequest, WebFetchResult } from '@qilin-agent/web';
+import { type DeepSeekWebAuth } from './transport.ts';
+/** Stable id the Fetch API provider registers under in the fetch registry. */
+export declare const DEEPSEEK_FETCH_API_PROVIDER_ID = "deepseek-fetch-api";
+/** Authentication and endpoint settings snapshotted for one fetch. */
+export interface DeepSeekFetchApiOptions extends DeepSeekWebAuth {
+    /** API base including its path prefix; `/fetch` is appended. */
+    baseURL: string;
+}
+/**
+ * Fetch page Markdown through the DeepSeek Fetch API. The API reports neither the
+ * target's status nor a final URL, and it fails when the target yields no usable
+ * content, so a success is the requested page retrieved with HTTP 200.
+ */
+export declare class DeepSeekFetchApiProvider implements WebFetchProvider {
+    private readonly resolveOptions;
+    readonly id = "deepseek-fetch-api";
+    /** @param resolveOptions - the options for the NEXT fetch, read once at each fetch's entry. */
+    constructor(resolveOptions: () => DeepSeekFetchApiOptions);
+    available(): boolean;
+    fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>;
+}
+//# sourceMappingURL=fetch.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Register the DeepSeek Search and Fetch APIs in `ctx.web` as `deepseek-search-api`
+ * and `deepseek-fetch-api`. Each operation is one direct API request without an
+ * auxiliary model request; both providers read this section's credential and API
+ * base. `web.searchProvider` and `web.fetchProvider` select them. Every request
+ * authenticates with the configured key; QiLin ships no account-token route.
+ * @module @qilin-agent/web-deepseek-api
+ */
+import type { Context, Volatile } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+export { DEEPSEEK_FETCH_API_PROVIDER_ID, DeepSeekFetchApiProvider } from './fetch.ts';
+export type { DeepSeekFetchApiOptions } from './fetch.ts';
+export { DEEPSEEK_DEFAULT_COUNT, DEEPSEEK_SEARCH_API_PROVIDER_ID, DEEPSEEK_WEB_API_BASE_URL, DeepSeekSearchApiProvider, mapSearchResponse, } from './search.ts';
+export type { DeepSeekSearchApiOptions } from './search.ts';
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "web-deepseek-api";
+/** The web seam both providers register into. */
+export declare const inject: string[];
+/** Settings read by the next search or fetch without re-registering either provider. */
+export interface Config {
+    /** Literal DeepSeek API key; prefer {@link apiKeyEnv} so no secret enters configuration files. */
+    apiKey: Volatile<string | undefined>;
+    /** Credential reference resolved for each operation; defaults to `DEEPSEEK_API_KEY`. */
+    apiKeyEnv: Volatile<string>;
+    /** API base including its path prefix; `/search` and `/fetch` are appended. */
+    baseURL: Volatile<string>;
+    /** Search API results per search, from 1 through 50; a smaller request bound wins. Defaults to 10. */
+    count: Volatile<number>;
+    /** Send the triggering user question, bounded to 128 characters, as `ori_question`. Defaults to true. */
+    sendOriginalQuestion: Volatile<boolean>;
+}
+export declare const Config: z<Schemastery.ObjectS<NoInfer<{
+    apiKey: z<string, string, "volatile">;
+    apiKeyEnv: z<string, string, "volatile-defined">;
+    baseURL: z<string, string, "volatile-defined">;
+    count: z<number, number, "volatile-defined">;
+    sendOriginalQuestion: z<boolean, boolean, "volatile-defined">;
+}>>, Schemastery.ObjectT<NoInfer<{
+    apiKey: z<string, string, "volatile">;
+    apiKeyEnv: z<string, string, "volatile-defined">;
+    baseURL: z<string, string, "volatile-defined">;
+    count: z<number, number, "volatile-defined">;
+    sendOriginalQuestion: z<boolean, boolean, "volatile-defined">;
+}>>, "plain">;
+/**
+ * Register the Search API and Fetch API providers over one live settings section.
+ * @param ctx - plugin context owning both registrations.
+ * @param config - live settings, read once per operation.
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/search.d.ts

@@ -0,0 +1,47 @@
+/**
+ * DeepSeek Search API provider: one direct request per search, without an
+ * auxiliary model request.
+ * @module @qilin-agent/web-deepseek-api/search
+ */
+import type { WebSearchProvider, WebSearchRequest, WebSearchResult } from '@qilin-agent/web';
+import { type DeepSeekWebAuth, type DeepSeekWebGuidance } from './transport.ts';
+/** Stable id the Search API provider registers under in the search registry. */
+export declare const DEEPSEEK_SEARCH_API_PROVIDER_ID = "deepseek-search-api";
+/** Default Search and Fetch API base, including its `/v1/tools` prefix; `/search` and `/fetch` are appended. */
+export declare const DEEPSEEK_WEB_API_BASE_URL = "https://api.deepseek.com/v1/tools";
+/** Default Search API result count, the service's own default. */
+export declare const DEEPSEEK_DEFAULT_COUNT = 10;
+/** Settings named by endpoint failures of either API in this package. */
+export declare const DEEPSEEK_WEB_API_GUIDANCE: Omit<DeepSeekWebGuidance, 'subject'>;
+/** Authentication, endpoint, and result settings snapshotted for one search. */
+export interface DeepSeekSearchApiOptions extends DeepSeekWebAuth {
+    /** API base including its path prefix; `/search` is appended. */
+    baseURL: string;
+    /** Results requested per search, from 1 through 50; a smaller request bound wins. */
+    count: number;
+    /** Read the user question that triggered the search; undefined or blank sends none. */
+    originalQuestion?: () => string | undefined;
+}
+/**
+ * Validate a Search API response and project its sources into the web service.
+ * @param response - untrusted JSON from the Search endpoint.
+ * @returns sources with provider order and nullable publication dates preserved.
+ * @throws {@link WebError} when the response does not contain valid search results.
+ */
+export declare function mapSearchResponse(response: unknown): WebSearchResult;
+/**
+ * Search through the DeepSeek Search API. 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 DeepSeekSearchApiProvider implements WebSearchProvider {
+    private readonly resolveOptions;
+    readonly id = "deepseek-search-api";
+    /**
+     * @param resolveOptions - the options for the NEXT search, read once at each
+     * search's entry so one search never mixes two settings sections.
+     */
+    constructor(resolveOptions: () => DeepSeekSearchApiOptions);
+    available(): boolean;
+    search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+}
+//# sourceMappingURL=search.d.ts.map

package/lib/types/transport.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Authentication and redirect-rejecting transport shared by the Search and
+ * Fetch API providers in this package. Credential resolution, the dispatch
+ * call, and the cancellation helpers deliberately repeat
+ * `qilin-web-search-deepseek`, so neither plugin depends on the other; the
+ * `jscpd:ignore` regions mark those repeats
+ * ([rationale](../../../../.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.md)).
+ * @module @qilin-agent/web-deepseek-api/transport
+ */
+import type { Context } from '@qilin-agent/kylin';
+import { type CredentialRef } from '@qilin-agent/credentials';
+import { WebError } from '@qilin-agent/web';
+/** Authentication sources resolved once for an operation. */
+export interface DeepSeekWebAuth {
+    /** Literal API key; takes precedence over the credential resolver. */
+    apiKey?: string;
+    /** Resolve the current API key without retaining it. */
+    resolveApiKey?: () => Promise<string | undefined>;
+    /** Credential reference named by missing-key diagnostics. */
+    apiKeyEnv?: CredentialRef;
+}
+/** User-owned endpoint settings named by dispatch failures. */
+export interface DeepSeekWebGuidance {
+    /** Capability whose endpoint failed. */
+    subject: 'Search' | 'Fetch';
+    /** Plugin configuration namespace. */
+    plugin: string;
+    /** Endpoint configuration field. */
+    field: string;
+    /** Local settings label. */
+    label: string;
+    /** Built-in settings page title. */
+    page: string;
+}
+/** One fully resolved web API request. */
+interface DeepSeekWebRequest<T> {
+    /** Absolute dispatch URL. */
+    endpoint: string;
+    /** JSON request body. */
+    body: object;
+    /** Protocol headers without credentials. */
+    headers?: Readonly<Record<string, string>>;
+    /** Additional API-key headers. */
+    apiKeyHeaders?: (key: string) => Readonly<Record<string, string>>;
+    /** Validate and project the response. */
+    decode: (payload: unknown) => T;
+    /** Endpoint recovery settings. */
+    guidance: DeepSeekWebGuidance;
+    /** Record model input before dispatch; a throw prevents dispatch. */
+    recordRequest?: (endpoint: string) => void;
+}
+/**
+ * Resolve credential sources for one operation without retaining secret values.
+ * @param ctx - Provider context with request routing and credential services.
+ * @param config - Literal key and credential reference from the settings snapshot.
+ * @returns Authentication sources for one operation.
+ */
+export declare function deepSeekWebAuth(ctx: Context, config: {
+    apiKey: string | undefined;
+    apiKeyEnv: string;
+}): DeepSeekWebAuth;
+/**
+ * Check whether an authentication source exists; does not resolve credentials.
+ * @param auth - Sources for the operation.
+ * @returns Whether a literal key or resolver is present.
+ */
+export declare function hasDeepSeekWebCredential(auth: DeepSeekWebAuth): boolean;
+/** Narrow a remote JSON object.
+ * @param value - Untrusted JSON.
+ * @returns Whether readable object fields exist.
+ */
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+/** Report malformed upstream JSON without embedding response content.
+ * @returns The stable provider error.
+ */
+export declare function invalidResponse(): WebError;
+/** Dispatch one operation using a single settings and credential snapshot.
+ * @param options - Authentication sources for this operation.
+ * @param request - Resolved endpoint, JSON payload, and response decoder.
+ * @param signal - Caller cancellation signal.
+ * @returns The validated provider result.
+ */
+export declare function dispatchDeepSeekWeb<T>(options: DeepSeekWebAuth, request: DeepSeekWebRequest<T>, signal?: AbortSignal): Promise<T>;
+export {};
+//# sourceMappingURL=transport.d.ts.map

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "web-deepseek-api"
+  }
+}

package/locale/zh.json

@@ -0,0 +1,6 @@
+{
+  "meta": {
+    "title": "DeepSeek 网页搜索与抓取 API",
+    "description": "通过 DeepSeek Search API 搜索网页、Fetch API 抓取网页正文。"
+  }
+}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@qilin-agent/web-deepseek-api",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "DeepSeek Search and Fetch API providers for the QiLin web capability seam (ctx.web)",
+  "version": "3.1.6",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/web/web-deepseek-api"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "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",
+    "./locale/*.json": "./locale/*.json"
+  },
+  "files": [
+    "locale/*.json",
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/agent": "3.1.6",
+    "@qilin-agent/web": "3.1.6",
+    "@qilin-agent/launch-environment": "3.1.6",
+    "@qilin-agent/kylin": "~4.0.5",
+    "@qilin-agent/credentials": "3.1.6",
+    "@qilin-agent/session": "3.1.6"
+  },
+  "dependencies": {
+    "@qilin-agent/schemastery": "~3.18.5"
+  },
+  "devDependencies": {
+    "@qilin-agent/credentials": "3.1.6",
+    "@qilin-agent/credentials-local": "3.1.6",
+    "@qilin-agent/agent": "3.1.6",
+    "@qilin-agent/launch-environment": "3.1.6",
+    "@qilin-agent/session": "3.1.6",
+    "@qilin-agent/web": "3.1.6",
+    "@qilin-agent/http-proxy": "3.1.6",
+    "@qilin-agent/kylin": "~4.0.5"
+  }
 }