@morlay/dsh-web-search-ollama 0.0.1-alpha.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 morlay
+
+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.md

@@ -0,0 +1,100 @@
+# @morlay/dsh-web-search-ollama
+
+往 `ctx.web` 注册一个搜索后端：`web_search` 的检索走 Ollama 自己的
+`POST https://ollama.com/api/web_search`，用与 `llm-pi-ai` 的 ollama route 同一个
+`OLLAMA_API_KEY`。
+
+## 为什么不是"复用上游的 messages 后端"
+
+上游 `@deepseek-ai/dsh-web-search-deepseek` 走 Anthropic Messages 的
+`web_search_20250305` server tool，看起来只要把 `baseURL` 指到 `https://ollama.com/v1` 就能白拿
+Ollama 的搜索。**实测不行**：真发一次
+
+```sh
+curl https://ollama.com/v1/messages -H "Authorization: Bearer $OLLAMA_API_KEY" \
+  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
+  -d '{"model":"deepseek-v4.1-flash","max_tokens":4096,
+       "messages":[{"role":"user","content":[{"type":"text","text":"Perform a web search for the query: cordis plugin framework"}]}],
+       "tools":[{"type":"web_search_20250305","name":"web_search","max_uses":5}]}'
+```
+
+回的 `content` 块只有 `thinking` + `tool_use`（`stop_reason: tool_use`）——**Ollama 把这个 server
+tool 降级成普通客户端工具，它不自己执行搜索**，要求调用方执行后再回传 `tool_result`。而那个上游
+provider 只认服务端自执行后返回的 `web_search_tool_result` 块，找不到就报
+`WEB_PROVIDER_ERROR`（"returned no web_search_tool_result blocks"）。Ollama 官方文档那句
+"hosted web search are not fully supported"（[docs.ollama.com/api/anthropic-compatibility](https://docs.ollama.com/api/anthropic-compatibility)）
+就是这个意思，[issue #17283](https://github.com/ollama/ollama/issues/17283) 里说的
+`WebSearchAnthropicWriter` 拦截只发生在本地 server 的 cloud 模型路径上。
+
+Ollama 真正对外提供搜索的是它自己的 REST 接口——同一个 key、一次 HTTP、返回扁平
+`{results:[{title,url,content}]}`：
+
+```sh
+curl https://ollama.com/api/web_search -H "Authorization: Bearer $OLLAMA_API_KEY" \
+  -H "content-type: application/json" -d '{"query":"cordis plugin framework"}'
+```
+
+本包就是把这一条接进 `ctx.web`，代价只有一个 ~200 行的 provider。
+
+## 配置
+
+| 字段         | 默认                     | 含义                                                       |
+| ------------ | ------------------------ | ---------------------------------------------------------- |
+| `apiKey`     | —                        | 字面 key；优先用下面那个引用，别把密钥写进配置文件         |
+| `apiKeyEnv`  | `OLLAMA_API_KEY`         | 每次搜索解析一次的凭证引用（凭证服务，缺席时回退启动环境） |
+| `baseURL`    | `https://ollama.com`     | 端点根；`/api/web_search` 由 provider 拼                   |
+| `maxResults` | —（Ollama 自己的默认 5） | 请求没带 `maxResults` 时的默认结果数                       |
+
+## 行为
+
+- **结果映射**：每条 `results[]` 给一个 source；`title` / `content` 空串视为缺失
+  （`content` → `snippet`），**没有 `url` 的条目直接丢掉**（seam 的 source 必须有 url）。
+  Ollama 不返回生成式答案，所以结果里没有 `content` 字段。
+- **`max_results` 上限 10**：Ollama 的硬上限；请求与配置给出的更大值在发出前压到 10。
+- **错误码**：HTTP 失败 → `WEB_PROVIDER_ERROR`（优先用响应体里的 `error` 文案，非 JSON 体退回
+  `Ollama API error (HTTP <status>)`）；网络失败 → `WEB_PROVIDER_ERROR`；取消 → `WEB_ABORTED`
+  （任何阶段，含读体）；取不到 key → `WEB_PROVIDER_CREDENTIAL_MISSING` 且不发请求。
+- **可用性检查不联网**：`available()` 只看 key 有没有来源、`baseURL` 能否解析。
+
+## 验证
+
+`src/__tests__/provider.spec.ts` 是 mock 单测，默认 `just test` 覆盖它。链路是否真的成立由
+[`e2e/provider.e2e.spec.ts`](./e2e/provider.e2e.spec.ts) 打真端点守——**它刻意放在 `src/__tests__/` 之外**：
+根 `vitest.config.ts` 的 include 收不到它，默认全量测试不会去打外网，只由显式命令触发（`OLLAMA_API_KEY`
+从启动环境注入，缺席则整体跳过）：
+
+```sh
+mise exec -- pnpm --filter @morlay/dsh-web-search-ollama run test:e2e
+```
+
+两条都过才算通过：provider 直连拿回可引用 source，以及 provider 装进 `ctx.web` 后选中它再搜一次。别用
+mock 全绿替代它——这个包的第一版就是"配置指到 Ollama 的 messages 端点"、mock 也全绿，真调用却是错的。
+触发方式、门控与判据的 home 是[包层规范](./.agents/standards/how-to-verify.md)。
+
+## 装配
+
+注册行由 [`@morlay/dsh-preset`](../../preset/dsh-preset/README.md) 的 bundle patch 插在 **host 层**，
+并把基础 bundle 的 `web` 行 `searchProvider` 切到 `ollama`：
+
+```yaml
+- id: web
+  config:
+    searchProvider: ollama
+    fetchProvider: http
+- insert:
+    - id: web-search-ollama
+      name: "@morlay/dsh-web-search-ollama"
+      config:
+        apiKeyEnv: OLLAMA_API_KEY
+```
+
+注册行不能放进 preset：preset 是每个 agent 各挂一份，同一个 provider id 注册两次会撞
+`WEB_DUPLICATE_PROVIDER`；选择权在 `web` 行的 `searchProvider`，而那一行本来就是 host 行。
+
+## 边界
+
+- **只注册搜索后端**：`web_fetch` 仍走基础 bundle 的 `web-fetch-http`，本包不碰抓取。
+- **一次只选一个后端**：`ctx.web` 的 `searchProvider` 是单选，默认 `ollama`；
+  `deepseek-official` 后端仍由基础 bundle 注册着，改写那一行即可切回（但它需要 `DEEPSEEK_API_KEY`）。
+- **不做设置页 section**：配置面就是那一行 patch（见
+  [dsh-preset 的设计记录](../../preset/dsh-preset/.agents/designs/20260917-host层部署配置.md)）。

package/dist/index.d.mts

@@ -0,0 +1,68 @@
+import z from "@deepseek-ai/schemastery";
+import { WebSearchProvider, WebSearchRequest, WebSearchResult, WebSearchSource } from "@deepseek-ai/dsh-web";
+import { Context } from "@deepseek-ai/cordis";
+//#region src/types.d.ts
+/** `results[]` 的一条；字段都可能缺失或为空串。 */
+interface OllamaSearchResult {
+  title?: string | null;
+  url?: string | null;
+  content?: string | null;
+}
+/** 成功响应信封。 */
+interface OllamaSearchResponse {
+  results?: OllamaSearchResult[];
+}
+//#endregion
+//#region src/provider.d.ts
+/** 注册进 `ctx.web` 的 id；与 llm route 同名，配置里看到的就是同一个"ollama"。 */
+declare const OLLAMA_PROVIDER_ID = "ollama";
+/** 默认端点；`/api/web_search` 是操作。 */
+declare const OLLAMA_DEFAULT_BASE_URL = "https://ollama.com";
+/** Ollama 服务端自己的默认结果数。 */
+declare const OLLAMA_DEFAULT_MAX_RESULTS = 5;
+/** Ollama `max_results` 的硬上限；超过它的值不发给服务端。 */
+declare const OLLAMA_MAX_RESULTS_LIMIT = 10;
+interface OllamaSearchProviderOptions {
+  /** 字面 key；给了就压过 {@link resolveApiKey}。 */
+  apiKey?: string;
+  /** 运行期取 key 的入口（凭证服务 / 环境）；返回空表示取不到。 */
+  resolveApiKey?: () => Promise<string | undefined>;
+  /** 取不到 key 时报出来的引用名，便于用户知道去哪配。 */
+  apiKeyEnv: string;
+  baseURL: string;
+  /** 请求没给 `maxResults` 时用的默认值；省略表示让 Ollama 用它自己的默认。 */
+  maxResults?: number;
+}
+/** 一条 Ollama 结果 → 一个 source；没有 url 就丢掉（seam 的 source 必须有 url）。 */
+declare function mapOllamaResult(result: OllamaSearchResult): WebSearchSource | undefined;
+/** 响应信封 → 归一化结果；形状不对就抛（由调用方包成 `WEB_PROVIDER_ERROR`）。 */
+declare function mapOllamaResponse(response: OllamaSearchResponse): WebSearchResult;
+/** Ollama 的搜索后端；HTTP 重定向按 `WEB_PROVIDER_ERROR` 失败。 */
+declare class OllamaSearchProvider implements WebSearchProvider {
+  private readonly options;
+  readonly id = "ollama";
+  constructor(options: OllamaSearchProviderOptions);
+  available(): boolean;
+  search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>;
+  /** 一次操作一份 key，不留在 provider 上；没有可用的 key 就点名引用，而不是发无授权请求。 */
+  private apiKey;
+}
+//#endregion
+//#region src/index.d.ts
+declare const name = "web-search-ollama";
+/** 只往 `ctx.web` 注册后端，不发布服务。 */
+declare const inject: string[];
+interface Config {
+  /** 字面 key；优先用 `apiKeyEnv` 走凭证服务，别把密钥写进配置文件。 */
+  apiKey?: string;
+  /** 每次搜索解析一次的凭证引用；缺省 `OLLAMA_API_KEY`。 */
+  apiKeyEnv?: string;
+  /** 端点根；`/api/web_search` 由 provider 拼。缺省 ollama.com。 */
+  baseURL?: string;
+  /** 请求没带 `maxResults` 时的默认结果数；省略表示让 Ollama 用自己的默认。 */
+  maxResults?: number;
+}
+declare const Config: z<Config>;
+declare function apply(ctx: Context, config: Config): void;
+//#endregion
+export { Config, OLLAMA_DEFAULT_BASE_URL, OLLAMA_DEFAULT_MAX_RESULTS, OLLAMA_MAX_RESULTS_LIMIT, OLLAMA_PROVIDER_ID, OllamaSearchProvider, type OllamaSearchProviderOptions, apply, inject, mapOllamaResponse, mapOllamaResult, name };

package/dist/index.mjs

@@ -0,0 +1,147 @@
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import z from "@deepseek-ai/schemastery";
+import { WebError } from "@deepseek-ai/dsh-web";
+//#region src/provider.ts
+/** 注册进 `ctx.web` 的 id；与 llm route 同名，配置里看到的就是同一个"ollama"。 */
+const OLLAMA_PROVIDER_ID = "ollama";
+/** 默认端点；`/api/web_search` 是操作。 */
+const OLLAMA_DEFAULT_BASE_URL = "https://ollama.com";
+/** Ollama 服务端自己的默认结果数。 */
+const OLLAMA_DEFAULT_MAX_RESULTS = 5;
+/** Ollama `max_results` 的硬上限；超过它的值不发给服务端。 */
+const OLLAMA_MAX_RESULTS_LIMIT = 10;
+/** 每次请求带的归属头。 */
+const USER_AGENT = "morlay-dsh-plugin/0.0.1";
+/** 一条 Ollama 结果 → 一个 source；没有 url 就丢掉（seam 的 source 必须有 url）。 */
+function mapOllamaResult(result) {
+	const url = result.url;
+	if (typeof url !== "string" || url.length === 0) return void 0;
+	const title = typeof result.title === "string" && result.title.length > 0 ? result.title : void 0;
+	const snippet = typeof result.content === "string" && result.content.length > 0 ? result.content : void 0;
+	return {
+		url,
+		...title === void 0 ? {} : { title },
+		...snippet === void 0 ? {} : { snippet }
+	};
+}
+/** 响应信封 → 归一化结果；形状不对就抛（由调用方包成 `WEB_PROVIDER_ERROR`）。 */
+function mapOllamaResponse(response) {
+	const results = response.results;
+	if (results !== void 0 && !Array.isArray(results)) throw new TypeError("Ollama returned a non-array `results` field");
+	return {
+		sources: (results ?? []).map((result) => mapOllamaResult(result)).filter((source) => source !== void 0),
+		truncated: false
+	};
+}
+/** Ollama 的搜索后端；HTTP 重定向按 `WEB_PROVIDER_ERROR` 失败。 */
+var OllamaSearchProvider = class {
+	options;
+	id = OLLAMA_PROVIDER_ID;
+	constructor(options) {
+		this.options = options;
+	}
+	available() {
+		const { apiKey, resolveApiKey, baseURL, maxResults } = this.options;
+		return (apiKey !== void 0 && apiKey.length > 0 || resolveApiKey !== void 0) && URL.canParse(baseURL) && (maxResults === void 0 || isPositiveInteger(maxResults));
+	}
+	async search(request, signal) {
+		const apiKey = await this.apiKey();
+		const maxResults = clampMaxResults(request.maxResults ?? this.options.maxResults);
+		let response;
+		try {
+			response = await fetch(`${this.options.baseURL}/api/web_search`, {
+				method: "POST",
+				redirect: "error",
+				headers: {
+					authorization: `Bearer ${apiKey}`,
+					"content-type": "application/json",
+					accept: "application/json",
+					"user-agent": USER_AGENT
+				},
+				body: JSON.stringify({
+					query: request.query,
+					...maxResults === void 0 ? {} : { max_results: maxResults }
+				}),
+				...signal === void 0 ? {} : { signal }
+			});
+		} catch (error) {
+			if (isAbortError(error)) throw searchAborted(error);
+			throw new WebError(`Ollama search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (!response.ok) {
+			let message = `Ollama API error (HTTP ${response.status})`;
+			try {
+				const detail = (await response.json()).error;
+				if (typeof detail === "string" && detail.length > 0) message = detail;
+			} catch (error) {
+				if (isAbortError(error)) throw searchAborted(error);
+			}
+			throw new WebError(message, "WEB_PROVIDER_ERROR");
+		}
+		try {
+			return mapOllamaResponse(await response.json());
+		} catch (error) {
+			if (isAbortError(error)) throw searchAborted(error);
+			throw new WebError(`Ollama returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+	}
+	/** 一次操作一份 key，不留在 provider 上；没有可用的 key 就点名引用，而不是发无授权请求。 */
+	async apiKey() {
+		const literal = this.options.apiKey;
+		if (literal !== void 0 && literal.length > 0) return literal;
+		let resolved;
+		try {
+			resolved = await this.options.resolveApiKey?.();
+		} catch (error) {
+			if (isAbortError(error)) throw searchAborted(error);
+			throw new WebError(`Ollama search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", { cause: error });
+		}
+		if (resolved !== void 0 && resolved.length > 0) return resolved;
+		throw new WebError(`Ollama search has no API key for "${this.options.apiKeyEnv}"; 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-ollama config`, "WEB_PROVIDER_CREDENTIAL_MISSING");
+	}
+};
+function clampMaxResults(maxResults) {
+	if (maxResults === void 0) return void 0;
+	return Math.min(maxResults, 10);
+}
+function isPositiveInteger(value) {
+	return Number.isInteger(value) && value > 0;
+}
+function isAbortError(error) {
+	return error instanceof DOMException && error.name === "AbortError";
+}
+function searchAborted(cause) {
+	return new WebError("Ollama search aborted", "WEB_ABORTED", { cause });
+}
+//#endregion
+//#region src/index.ts
+const name = "web-search-ollama";
+/** 只往 `ctx.web` 注册后端，不发布服务。 */
+const inject = ["web"];
+/** 与 `llm-pi-ai` 的 ollama route 共用同一个 key 引用。 */
+const DEFAULT_API_KEY_ENV = "OLLAMA_API_KEY";
+const Config = z.object({
+	apiKey: z.string().role("secret"),
+	apiKeyEnv: z.string().role("credential-ref"),
+	baseURL: z.string(),
+	maxResults: z.number().step(1).min(1)
+});
+function apply(ctx, config) {
+	const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
+	const literal = config.apiKey !== void 0 && config.apiKey.length > 0 ? config.apiKey : void 0;
+	ctx.web.registerSearchProvider(new OllamaSearchProvider({
+		...literal === void 0 ? {} : { apiKey: literal },
+		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 ?? "https://ollama.com",
+		...config.maxResults === void 0 ? {} : { maxResults: config.maxResults }
+	}));
+}
+//#endregion
+export { Config, OLLAMA_DEFAULT_BASE_URL, OLLAMA_DEFAULT_MAX_RESULTS, OLLAMA_MAX_RESULTS_LIMIT, OLLAMA_PROVIDER_ID, OllamaSearchProvider, apply, inject, mapOllamaResponse, mapOllamaResult, name };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@morlay/dsh-web-search-ollama",
+  "version": "0.0.1-alpha.2",
+  "description": "Ollama-backed search provider for the DeepSeek Harness web seam (ctx.web): one web_search backend calling POST https://ollama.com/api/web_search.",
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "ollama",
+    "web-search"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/morlay/dsh-plugin.git"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!**/__tests__"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "3.18.3"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.3",
+    "@deepseek-ai/dsh-credentials": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-launch-environment": "0.1.7-alpha.1",
+    "@deepseek-ai/dsh-web": "0.1.7-alpha.1"
+  },
+  "scripts": {
+    "build": "pnpm exec tsdown",
+    "test:e2e": "pnpm exec vitest run --config vitest.e2e.config.ts"
+  }
+}

package/src/index.ts

@@ -0,0 +1,64 @@
+import type { Context } from "@deepseek-ai/cordis";
+import { credentialRef } from "@deepseek-ai/dsh-credentials";
+import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
+import type {} from "@deepseek-ai/dsh-web";
+import z from "@deepseek-ai/schemastery";
+import { OLLAMA_DEFAULT_BASE_URL, OllamaSearchProvider } from "./provider.ts";
+
+export {
+  OLLAMA_DEFAULT_BASE_URL,
+  OLLAMA_DEFAULT_MAX_RESULTS,
+  OLLAMA_MAX_RESULTS_LIMIT,
+  OLLAMA_PROVIDER_ID,
+  OllamaSearchProvider,
+  mapOllamaResponse,
+  mapOllamaResult,
+} from "./provider.ts";
+export type { OllamaSearchProviderOptions } from "./provider.ts";
+
+export const name = "web-search-ollama";
+
+/** 只往 `ctx.web` 注册后端，不发布服务。 */
+export const inject = ["web"];
+
+/** 与 `llm-pi-ai` 的 ollama route 共用同一个 key 引用。 */
+const DEFAULT_API_KEY_ENV = "OLLAMA_API_KEY";
+
+export interface Config {
+  /** 字面 key；优先用 `apiKeyEnv` 走凭证服务，别把密钥写进配置文件。 */
+  apiKey?: string;
+  /** 每次搜索解析一次的凭证引用；缺省 `OLLAMA_API_KEY`。 */
+  apiKeyEnv?: string;
+  /** 端点根；`/api/web_search` 由 provider 拼。缺省 ollama.com。 */
+  baseURL?: string;
+  /** 请求没带 `maxResults` 时的默认结果数；省略表示让 Ollama 用自己的默认。 */
+  maxResults?: number;
+}
+
+export const Config: z<Config> = z.object({
+  apiKey: z.string().role("secret"),
+  apiKeyEnv: z.string().role("credential-ref"),
+  baseURL: z.string(),
+  maxResults: z.number().step(1).min(1),
+});
+
+export function apply(ctx: Context, config: Config): void {
+  const apiKeyEnv = credentialRef(config.apiKeyEnv ?? DEFAULT_API_KEY_ENV);
+  const literal =
+    config.apiKey !== undefined && config.apiKey.length > 0 ? config.apiKey : undefined;
+  ctx.web.registerSearchProvider(
+    new OllamaSearchProvider({
+      ...(literal === undefined ? {} : { apiKey: literal }),
+      resolveApiKey: async () => {
+        const credentials = ctx.get("credentials");
+        if (credentials !== undefined) return (await credentials.resolve(apiKeyEnv))?.value;
+        // 没有凭证服务时环境就是整个凭证面。
+        const ambient = launchEnvironmentOf(ctx).get(apiKeyEnv);
+        return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined;
+      },
+      apiKeyEnv,
+      baseURL: config.baseURL ?? OLLAMA_DEFAULT_BASE_URL,
+      ...(config.maxResults === undefined ? {} : { maxResults: config.maxResults }),
+    }),
+  );
+}

package/src/provider.ts

@@ -0,0 +1,178 @@
+import { WebError } from "@deepseek-ai/dsh-web";
+import type {
+  WebSearchProvider,
+  WebSearchRequest,
+  WebSearchResult,
+  WebSearchSource,
+} from "@deepseek-ai/dsh-web";
+import type { OllamaError, OllamaSearchResponse, OllamaSearchResult } from "./types.ts";
+
+/** 注册进 `ctx.web` 的 id；与 llm route 同名，配置里看到的就是同一个"ollama"。 */
+export const OLLAMA_PROVIDER_ID = "ollama";
+
+/** 默认端点；`/api/web_search` 是操作。 */
+export const OLLAMA_DEFAULT_BASE_URL = "https://ollama.com";
+
+/** Ollama 服务端自己的默认结果数。 */
+export const OLLAMA_DEFAULT_MAX_RESULTS = 5;
+
+/** Ollama `max_results` 的硬上限；超过它的值不发给服务端。 */
+export const OLLAMA_MAX_RESULTS_LIMIT = 10;
+
+/** 每次请求带的归属头。 */
+const USER_AGENT = "morlay-dsh-plugin/0.0.1";
+
+export interface OllamaSearchProviderOptions {
+  /** 字面 key；给了就压过 {@link resolveApiKey}。 */
+  apiKey?: string;
+  /** 运行期取 key 的入口（凭证服务 / 环境）；返回空表示取不到。 */
+  resolveApiKey?: () => Promise<string | undefined>;
+  /** 取不到 key 时报出来的引用名，便于用户知道去哪配。 */
+  apiKeyEnv: string;
+  baseURL: string;
+  /** 请求没给 `maxResults` 时用的默认值；省略表示让 Ollama 用它自己的默认。 */
+  maxResults?: number;
+}
+
+/** 一条 Ollama 结果 → 一个 source；没有 url 就丢掉（seam 的 source 必须有 url）。 */
+export function mapOllamaResult(result: OllamaSearchResult): WebSearchSource | undefined {
+  const url = result.url;
+  if (typeof url !== "string" || url.length === 0) return undefined;
+  const title =
+    typeof result.title === "string" && result.title.length > 0 ? result.title : undefined;
+  const snippet =
+    typeof result.content === "string" && result.content.length > 0 ? result.content : undefined;
+  return {
+    url,
+    ...(title === undefined ? {} : { title }),
+    ...(snippet === undefined ? {} : { snippet }),
+  };
+}
+
+/** 响应信封 → 归一化结果；形状不对就抛（由调用方包成 `WEB_PROVIDER_ERROR`）。 */
+export function mapOllamaResponse(response: OllamaSearchResponse): WebSearchResult {
+  const results = response.results;
+  if (results !== undefined && !Array.isArray(results)) {
+    throw new TypeError("Ollama returned a non-array `results` field");
+  }
+  const sources = (results ?? [])
+    .map((result) => mapOllamaResult(result))
+    .filter((source): source is WebSearchSource => source !== undefined);
+  // Ollama 不返回生成式答案（content 是每条结果的片段），所以没有 result.content；
+  // 截断由 seam 负责，这里照实报 false。
+  return { sources, truncated: false };
+}
+
+/** Ollama 的搜索后端；HTTP 重定向按 `WEB_PROVIDER_ERROR` 失败。 */
+export class OllamaSearchProvider implements WebSearchProvider {
+  readonly id = OLLAMA_PROVIDER_ID;
+
+  constructor(private readonly options: OllamaSearchProviderOptions) {}
+
+  available(): boolean {
+    const { apiKey, resolveApiKey, baseURL, maxResults } = this.options;
+    const hasKey = (apiKey !== undefined && apiKey.length > 0) || resolveApiKey !== undefined;
+    return (
+      hasKey && URL.canParse(baseURL) && (maxResults === undefined || isPositiveInteger(maxResults))
+    );
+  }
+
+  async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult> {
+    const apiKey = await this.apiKey();
+    const maxResults = clampMaxResults(request.maxResults ?? this.options.maxResults);
+    let response: Response;
+    try {
+      response = await fetch(`${this.options.baseURL}/api/web_search`, {
+        method: "POST",
+        redirect: "error",
+        headers: {
+          authorization: `Bearer ${apiKey}`,
+          "content-type": "application/json",
+          accept: "application/json",
+          "user-agent": USER_AGENT,
+        },
+        body: JSON.stringify({
+          query: request.query,
+          ...(maxResults === undefined ? {} : { max_results: maxResults }),
+        }),
+        ...(signal === undefined ? {} : { signal }),
+      });
+    } catch (error: unknown) {
+      if (isAbortError(error)) throw searchAborted(error);
+      throw new WebError(`Ollama search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", {
+        cause: error,
+      });
+    }
+
+    if (!response.ok) {
+      const status = response.status;
+      let message = `Ollama API error (HTTP ${status})`;
+      try {
+        const parsed = (await response.json()) as OllamaError;
+        const detail = parsed.error;
+        if (typeof detail === "string" && detail.length > 0) message = detail;
+      } catch (error: unknown) {
+        // 取消不能吞成"HTTP 错误"：取消是 seam 的取消契约，不是 provider 故障。
+        if (isAbortError(error)) throw searchAborted(error);
+        // 其余情况状态行已经在 message 里，错误体不是 JSON 只损失一句更细的说明。
+      }
+      throw new WebError(message, "WEB_PROVIDER_ERROR");
+    }
+
+    try {
+      return mapOllamaResponse((await response.json()) as OllamaSearchResponse);
+    } catch (error: unknown) {
+      if (isAbortError(error)) throw searchAborted(error);
+      throw new WebError(
+        `Ollama returned an unprocessable response body: ${String(error)}`,
+        "WEB_PROVIDER_ERROR",
+        {
+          cause: error,
+        },
+      );
+    }
+  }
+
+  /** 一次操作一份 key，不留在 provider 上；没有可用的 key 就点名引用，而不是发无授权请求。 */
+  private async apiKey(): Promise<string> {
+    const literal = this.options.apiKey;
+    if (literal !== undefined && literal.length > 0) return literal;
+    let resolved: string | undefined;
+    try {
+      resolved = await this.options.resolveApiKey?.();
+    } catch (error: unknown) {
+      if (isAbortError(error)) throw searchAborted(error);
+      throw new WebError(
+        `Ollama search credential resolution failed: ${String(error)}`,
+        "WEB_PROVIDER_ERROR",
+        {
+          cause: error,
+        },
+      );
+    }
+    if (resolved !== undefined && resolved.length > 0) return resolved;
+    throw new WebError(
+      `Ollama search has no API key for "${this.options.apiKeyEnv}"; 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-ollama config",
+      "WEB_PROVIDER_CREDENTIAL_MISSING",
+    );
+  }
+}
+
+function clampMaxResults(maxResults: number | undefined): number | undefined {
+  if (maxResults === undefined) return undefined;
+  return Math.min(maxResults, OLLAMA_MAX_RESULTS_LIMIT);
+}
+
+function isPositiveInteger(value: number): boolean {
+  return Number.isInteger(value) && value > 0;
+}
+
+function isAbortError(error: unknown): boolean {
+  return error instanceof DOMException && error.name === "AbortError";
+}
+
+function searchAborted(cause: unknown): WebError {
+  return new WebError("Ollama search aborted", "WEB_ABORTED", { cause });
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * POST https://ollama.com/api/web_search 的 wire 类型。只有类型，没有运行期代码。
+ *
+ * 响应是扁平 `results[]`，每条带 title / url / content；`content` 是 Ollama 自己截出来的
+ * 网页片段（不是生成式答案），所以它只映射到 `WebSearchSource.snippet`。
+ */
+
+/** 请求体。`max_results` 缺省时由服务端按自己的默认值（5）处理。 */
+export interface OllamaSearchRequest {
+  query: string;
+  max_results?: number;
+}
+
+/** `results[]` 的一条；字段都可能缺失或为空串。 */
+export interface OllamaSearchResult {
+  title?: string | null;
+  url?: string | null;
+  content?: string | null;
+}
+
+/** 成功响应信封。 */
+export interface OllamaSearchResponse {
+  results?: OllamaSearchResult[];
+}
+
+/** 错误响应信封；Ollama 失败时给 `{"error": "..."}`。 */
+export interface OllamaError {
+  error?: string;
+}