@vfvrpq/dsh-search 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+## 0.1.0 — 2026-10-17
+
+首个版本。
+
+- `deepseek_search`：结构化搜索结果，支持 `site:` / `-site:` / 排除词 / 精确短语 / `lang:` / `after:` / `before:`，`count` 1–50，可选 `need_content`。
+- `deepseek_fetch`：单页转 Markdown，正文按 `maxChars` 截断并标注。
+- `deepseek_research`：搜索 + 抓前 N 页正文，返回 `1 + N` 计费口径。
+- key 四层解析（配置 / 环境变量 / `~/.secrets/keys.env` / `$DSH_HOME/.credentials.yaml`），key 不落 profile。
+- 超时、429/5xx 退避重试、状态码到可执行提示的翻译。
+- 单测 22 项（mock fetch）+ 真机自测脚本。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 439436269-ctrl
+
+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

@@ -1,3 +1,96 @@
-# Temporary Holding Version
+# @vfvrpq/dsh-search
 
-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.
+DeepSeek 官方 Search / Fetch 接口的 DeepSeek Harness 插件：三个工具、一个配置项、零运行时依赖。
+
+给 agent 的是**结构化**网页结果——rerank 分、权威度、发布时间、模型友好长摘要——而不是一坨 HTML。
+比内置 `web_search` / `web_fetch` 多出来的东西：搜索语法、条数与正文可控、成本可推算。
+
+## 装
+
+```sh
+# 从 npm（已发布版本）
+dsh plugin --profile desktop add @vfvrpq/dsh-search@0.1.0
+
+# 或从源码包（插件 import 了 @deepseek-ai/*，必须走 tgz，目录软链会让宿主包解析不到）
+pnpm pack
+dsh plugin --profile desktop add /绝对路径/vfvrpq-dsh-search-0.1.0.tgz
+```
+
+装完工具即出现在工具表里，**不用重启**（升级才需要重启）。
+
+## 三个工具
+
+| 工具 | 干什么 | 计费请求数 |
+|---|---|---|
+| `deepseek_search` | 搜索，返回标题/URL/snippet/summary/可选正文/日期/权威度/rerank 分 | 1 |
+| `deepseek_fetch` | 单页转 Markdown（标题 + 正文） | 1 |
+| `deepseek_research` | 搜索 + 抓前 N 页正文，一次给结论 | 1 + N |
+
+`deepseek_search` 支持的操作符，写在 `query` 里或用参数：`site:`、`-site:`、`-词`、`-"短语"`、`"精确"`、`lang:`、`after:`、`before:`。
+
+```text
+deepseek_search  query="llama.cpp 安装" site="github.com" after=2025 count=5
+deepseek_fetch   url="https://api-docs.deepseek.com/zh-cn/guides/search"
+deepseek_research query="DeepSeek V4 上下文长度" count=5 top=2
+```
+
+判读口径：`rerankScore >= 1.5` 为优质（渲染里标 ★），`authority >= 3` 为高权威。
+`summary` 是二手摘要，版本号/日期/价格/API 字段一律 `deepseek_fetch` 原文核实；引用给原始 URL。
+
+## 配置
+
+| 键 | 默认 | 说明 |
+|---|---|---|
+| `apiKey` | `""` | 空则运行时按下面四层解析，**不要把 key 写进 profile** |
+| `baseUrl` | `https://api.deepseek.com` | 仅兼容代理时才改 |
+| `defaultCount` | `5` | 调用没给 `count` 时的条数 |
+| `maxContentChars` | `8000` | `deepseek_search` 每条正文上限 |
+| `fetchMaxChars` | `20000` | `deepseek_fetch` 正文上限 |
+| `timeoutMs` | `30000` | 单请求超时 |
+| `maxRetries` | `2` | 408 / 429 / 5xx 重试次数 |
+| `promptEnabled` | `true` | 是否向系统提示贡献用法章节 |
+| `promptOrder` | `55` | 该章节排序 |
+
+key 解析顺序（**key 不落 profile**）：
+
+1. 插件配置 `apiKey`
+2. `$DEEPSEEK_API_KEY`
+3. `~/.secrets/keys.env` 里的 `DEEPSEEK_API_KEY=...`
+4. `$DSH_HOME/.credentials.yaml` 的 `refs: DEEPSEEK_API_KEY: sk-...`
+
+## 成本
+
+- 5 元 / 1000 次成功请求 ≈ **0.005 元 / 次**；Search 与 Fetch 同价。
+- 只有 HTTP 200 且产生结果才计费；空结果、失败、超时不计费。
+- `count` 不影响单价——一次取够，别拆成多次小请求。
+- 限速：Search 与 Fetch **各自** 5 QPS（账号级）；超过抛 429，插件按退避重试。
+
+## 结构
+
+```
+lib/index.js     入口：只接线（校验配置、持有 client、注册工具、贡献提示章节）
+lib/config.js    Config schema + 代码侧默认值 + 加载期校验
+lib/keys.js      四层 key 解析
+lib/query.js     query 拼装与 site: 展开
+lib/client.js    HTTP：超时 / 重试 / 错误翻译
+lib/format.js    结果归一化与渲染
+lib/prompt.js    系统提示章节
+lib/tools/       一能力一文件（search / fetch / research / shared）
+```
+
+## 开发
+
+```sh
+node --test test/*.test.js     # 单测：mock fetch，不联网、不花钱
+node scripts/live-selftest.js  # 真机自测：1 次搜索 + 1 次抓取（约 0.01 元）
+```
+
+## 已知边界
+
+- 抓不了需要登录态、点击交互、或返回非 HTML 的页面 → 用浏览器自动化插件。
+- SPA 文档站可能对不存在的路径返回 200 + 站点壳内容而不是 404；正文里出现首页标语即说明是 fallback。
+- Fetch 返回的 Markdown 会把 `\/`、`\.`、`\#` 等标点反斜杠转义，属上游产物，按需 unescape。
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,26 @@
+# dsh-search bundle patch: one row inserted over whatever layers came before it.
+#
+# A patch replaces the targeted row's whole `config`, so a profile that overrides
+# this row must restate every key it wants to keep.
+#
+# The API key is NOT stored here. Leave `apiKey` empty and the plugin resolves it
+# at call time from, in order: $DEEPSEEK_API_KEY, `~/.secrets/keys.env`,
+# `$DSH_HOME/.credentials.yaml`. That keeps the key out of profile files that get
+# copied, shared, or committed.
+#
+# Every value below has a code-side default, so this patch stays valid on a host
+# that cannot evaluate helpers.
+
+- insert:
+    - id: deepseek-search
+      name: "@vfvrpq/dsh-search"
+      config:
+        apiKey: ""
+        baseUrl: https://api.deepseek.com
+        defaultCount: 5
+        maxContentChars: 8000
+        fetchMaxChars: 20000
+        timeoutMs: 30000
+        maxRetries: 2
+        promptEnabled: true
+        promptOrder: 55

package/lib/client.js

@@ -0,0 +1,167 @@
+/**
+ * HTTP client for the DeepSeek Search / Fetch endpoints.
+ *
+ * Both are plain JSON APIs behind the same Bearer auth as the chat API:
+ *   POST /v1/tools/search   { query, count, ori_question, need_content }
+ *   POST /v1/tools/fetch    { url }
+ *
+ * The client owns timeout, retry, and error translation, so tool files only see
+ * successes or a thrown `SearchClientError` that already carries a hint.
+ *
+ * @module dsh-search/client
+ */
+
+import { resolveApiKey } from "./keys.js";
+
+/** Status codes worth retrying: transient by contract. */
+const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
+
+/** Operator-facing explanation per status. */
+const HINTS = {
+	400: "请求参数不合法（query 1~128 字符、count 1~50）",
+	401: "API Key 缺失或无效，检查 DEEPSEEK_API_KEY / ~/.secrets/keys.env / ~/.dsh/.credentials.yaml",
+	402: "账号余额不足，请先充值",
+	403: "Fetch 被目标站点的安全策略拒绝",
+	404: "抓不到可提取的正文（站点拦截、非 HTML、或页面没有 Markdown 正文）",
+	429: "超出限速（Search / Fetch 各自 5 QPS，账号级），稍等重试",
+	500: "服务端内部错误，稍后重试",
+	504: "下游超时，稍后重试",
+};
+
+export class SearchClientError extends Error {
+	/**
+	 * @param {string} message - human-readable failure.
+	 * @param {{status?: number, hint?: string}} [meta] - HTTP status and advice.
+	 */
+	constructor(message, meta = {}) {
+		super(message);
+		this.name = "SearchClientError";
+		this.status = meta.status;
+		this.hint = meta.hint;
+	}
+}
+
+export class SearchClient {
+	/**
+	 * @param {{baseUrl: string, apiKey?: string, timeoutMs?: number, maxRetries?: number, fetchImpl?: typeof fetch}} options - client options.
+	 */
+	constructor(options) {
+		this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+		this.apiKeyOption = options.apiKey ?? "";
+		this.timeoutMs = options.timeoutMs ?? 30_000;
+		this.maxRetries = options.maxRetries ?? 2;
+		this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+		if (typeof this.fetchImpl !== "function") {
+			throw new SearchClientError("deepseek-search: 运行环境没有 fetch 实现");
+		}
+		/** @type {(explicit: string) => {key: string, source: string}} */
+		this.keyResolver = options.keyResolver ?? ((explicit) => resolveApiKey({ explicit }));
+	}
+
+	/**
+	 * Resolve the key for this call and report its provenance.
+	 *
+	 * @returns {{key: string, source: string}} resolved key.
+	 */
+	keyInfo() {
+		return this.keyResolver(this.apiKeyOption);
+	}
+
+	/**
+	 * POST one JSON body with retry, timeout, and error translation.
+	 *
+	 * @param {string} path - endpoint path.
+	 * @param {Record<string, unknown>} body - request body.
+	 * @returns {Promise<Record<string, any>>} parsed response.
+	 */
+	async request(path, body) {
+		const { key, source } = this.keyInfo();
+		if (key === "") {
+			throw new SearchClientError("deepseek-search: 找不到 API Key", {
+				hint: "设置 DEEPSEEK_API_KEY 环境变量，或写入 ~/.secrets/keys.env 的 DEEPSEEK_API_KEY=...",
+			});
+		}
+
+		let lastError;
+		for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+			if (attempt > 0) await sleep(400 * 2 ** (attempt - 1));
+			let response;
+			try {
+				response = await this.fetchImpl(this.baseUrl + path, {
+					method: "POST",
+					headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
+					body: JSON.stringify(body),
+					signal: AbortSignal.timeout(this.timeoutMs),
+				});
+			} catch (error) {
+				lastError = new SearchClientError(`deepseek-search: 网络请求失败（${error?.name ?? "Error"}: ${error?.message ?? error}）`);
+				continue;
+			}
+
+			const text = await response.text();
+			if (response.ok) {
+				try {
+					return JSON.parse(text);
+				} catch {
+					throw new SearchClientError("deepseek-search: 响应不是合法 JSON", { status: response.status, hint: text.slice(0, 200) });
+				}
+			}
+
+			const message = parseErrorMessage(text) || `HTTP ${response.status}`;
+			const hint = HINTS[response.status];
+			lastError = new SearchClientError(`deepseek-search: ${message}（HTTP ${response.status}，key 来源 ${source}）`, {
+				status: response.status,
+				hint,
+			});
+			if (!RETRYABLE.has(response.status)) throw lastError;
+		}
+		throw lastError;
+	}
+
+	/**
+	 * Run one web search.
+	 *
+	 * @param {{query: string, count: number, oriQuestion?: string, needContent?: boolean}} args - search arguments.
+	 * @returns {Promise<Array<Record<string, any>>>} raw result objects.
+	 */
+	async search(args) {
+		const body = { query: args.query, count: args.count };
+		if (args.oriQuestion) body.ori_question = args.oriQuestion;
+		if (args.needContent) body.need_content = true;
+		const data = await this.request("/v1/tools/search", body);
+		return Array.isArray(data?.results) ? data.results : [];
+	}
+
+	/**
+	 * Fetch one page as Markdown.
+	 *
+	 * @param {string} url - http(s) URL.
+	 * @returns {Promise<{title: string, content: string}>} page title and body.
+	 */
+	async fetchPage(url) {
+		const data = await this.request("/v1/tools/fetch", { url });
+		return { title: String(data?.title ?? ""), content: String(data?.content ?? "") };
+	}
+}
+
+/**
+ * Pull `error.message` out of an OpenAI-shaped error body.
+ *
+ * @param {string} text - raw response body.
+ * @returns {string} message, or "" when unparseable.
+ */
+function parseErrorMessage(text) {
+	try {
+		return String(JSON.parse(text)?.error?.message ?? "");
+	} catch {
+		return "";
+	}
+}
+
+/**
+ * @param {number} ms - delay.
+ * @returns {Promise<void>} resolves after the delay.
+ */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/config.js

@@ -0,0 +1,90 @@
+/**
+ * Plugin configuration: the schema the host validates against, the code-side
+ * defaults (so direct construction works without the loader), and the bounds
+ * check that fails at load time instead of at the first tool call.
+ *
+ * @module dsh-search/config
+ */
+
+import z from "@deepseek-ai/schemastery";
+
+/**
+ * Code-side defaults.
+ *
+ * The Cordis loader already applies `Config`'s defaults, but `apply` is also
+ * reachable through direct construction (tests, tooling), so the plugin
+ * resolves its own defaults instead of trusting the caller.
+ *
+ * @type {Record<string, any>}
+ */
+const DEFAULTS = Object.freeze({
+	apiKey: "",
+	baseUrl: "https://api.deepseek.com",
+	defaultCount: 5,
+	maxContentChars: 8_000,
+	fetchMaxChars: 20_000,
+	timeoutMs: 30_000,
+	maxRetries: 2,
+	promptEnabled: true,
+	promptOrder: 55,
+});
+
+export const Config = z.object({
+	/** Explicit API key; empty means resolve from env / secrets files at call time. */
+	apiKey: z.string().default(""),
+	/** API origin. Point it elsewhere only for a compatible proxy. */
+	baseUrl: z.string().default("https://api.deepseek.com"),
+	/** Result count when the tool call omits `count`. */
+	defaultCount: z.natural().default(5),
+	/** Per-result ceiling for `content` returned by `deepseek_search`. */
+	maxContentChars: z.natural().default(8_000),
+	/** Ceiling for the Markdown returned by `deepseek_fetch`. */
+	fetchMaxChars: z.natural().default(20_000),
+	/** Per-request timeout in milliseconds. */
+	timeoutMs: z.natural().default(30_000),
+	/** Retries for 408 / 429 / 5xx responses. */
+	maxRetries: z.natural().default(2),
+	/** Whether to contribute the search guide to the system prompt. */
+	promptEnabled: z.boolean().default(true),
+	/** Ordering of that section. */
+	promptOrder: z.natural().default(55),
+});
+
+/**
+ * Merge caller config over the defaults, ignoring explicit `undefined`.
+ *
+ * @param {Record<string, any>|undefined} config - caller config.
+ * @returns {Record<string, any>} effective config.
+ */
+export function resolveConfig(config) {
+	const given = Object.fromEntries(Object.entries(config ?? {}).filter(([, value]) => value !== undefined));
+	return { ...DEFAULTS, ...given };
+}
+
+/**
+ * Reject unusable configuration at load time instead of at the first tool call.
+ *
+ * @param {Record<string, any>} config - schema-validated config.
+ * @throws {Error} when a bound is not a positive integer or an origin is malformed.
+ */
+export function validateConfig(config) {
+	const bounds = [
+		["defaultCount", config.defaultCount, 1],
+		["maxContentChars", config.maxContentChars, 200],
+		["fetchMaxChars", config.fetchMaxChars, 500],
+		["timeoutMs", config.timeoutMs, 1_000],
+		["maxRetries", config.maxRetries, 0],
+		["promptOrder", config.promptOrder, 0],
+	];
+	for (const [field, value, min] of bounds) {
+		if (!Number.isInteger(value) || value < min) {
+			throw new Error(`deepseek-search: 配置项 ${field}=${value} 必须是 >= ${min} 的整数`);
+		}
+	}
+	if (!/^https?:\/\//.test(config.baseUrl)) {
+		throw new Error(`deepseek-search: baseUrl 必须以 http:// 或 https:// 开头（当前 ${config.baseUrl}）`);
+	}
+	if (config.defaultCount > 50) {
+		throw new Error(`deepseek-search: defaultCount=${config.defaultCount} 超出接口上限 50`);
+	}
+}

package/lib/format.js

@@ -0,0 +1,105 @@
+/**
+ * Presentation helpers: normalize one API result into the tool's output shape,
+ * clip text, and render the plain-text card body the GUI shows.
+ *
+ * Keeping formatting here means every tool file stays a thin capability.
+ *
+ * @module dsh-search/format
+ */
+
+/** Score at or above this counts as a good hit (per the API docs). */
+export const GOOD_SCORE = 1.5;
+
+/** Authority at or above this counts as highly authoritative. */
+export const STRONG_AUTHORITY = 3;
+
+/**
+ * Clip text to a character budget.
+ *
+ * @param {unknown} text - candidate text.
+ * @param {number} max - character ceiling.
+ * @returns {{text: string, truncated: boolean}} clipped text and whether it was cut.
+ */
+export function clip(text, max) {
+	const value = String(text ?? "");
+	if (value.length <= max) return { text: value, truncated: false };
+	return { text: value.slice(0, max) + "\n…（已截断）", truncated: true };
+}
+
+/**
+ * Normalize one raw search result.
+ *
+ * @param {Record<string, any>} raw - API result object.
+ * @param {number} rank - 1-based position.
+ * @param {{contentLimit?: number}} [options] - clipping options.
+ * @returns {Record<string, any>} normalized result.
+ */
+export function normalizeResult(raw, rank, options = {}) {
+	const content = clip(raw?.content ?? "", options.contentLimit ?? 0);
+	return {
+		rank,
+		title: String(raw?.title ?? ""),
+		url: String(raw?.url ?? ""),
+		snippet: String(raw?.snippet ?? ""),
+		summary: String(raw?.summary ?? ""),
+		content: content.text,
+		siteName: raw?.site_name == null ? "" : String(raw.site_name),
+		date: raw?.date == null ? "" : String(raw.date),
+		authority: Number.isInteger(raw?.authority) ? raw.authority : -1,
+		rerankScore: Number.isFinite(raw?.rerank_score) ? Number(raw.rerank_score) : 0,
+		good: Number(raw?.rerank_score ?? 0) >= GOOD_SCORE,
+	};
+}
+
+/**
+ * Format a score for display.
+ *
+ * @param {number} score - rerank score.
+ * @returns {string} two-decimal score.
+ */
+export function fmtScore(score) {
+	return Number(score ?? 0).toFixed(2);
+}
+
+/**
+ * Format an RFC 3339 timestamp as a date.
+ *
+ * @param {string} iso - timestamp.
+ * @returns {string} `YYYY-MM-DD`, or "—" when absent.
+ */
+export function fmtDate(iso) {
+	return iso ? String(iso).slice(0, 10) : "—";
+}
+
+/**
+ * One result as display lines.
+ *
+ * @param {Record<string, any>} result - normalized result.
+ * @returns {string} multi-line block.
+ */
+export function resultBlock(result) {
+	const head = `${result.good ? "★" : " "}[${result.rank}] ${result.title || "(无标题)"}`;
+	const meta = `    ${fmtScore(result.rerankScore)} 分 · 权威 ${result.authority} · ${fmtDate(result.date)} · ${result.siteName || "—"}`;
+	const body = result.summary || result.snippet;
+	return [head, `    ${result.url}`, meta, body ? `    ${String(body).replace(/\n+/g, " ")}` : ""].filter(Boolean).join("\n");
+}
+
+/**
+ * Render a search report body.
+ *
+ * @param {Record<string, any>} value - tool output.
+ * @returns {string} card text.
+ */
+export function renderSearchReport(value) {
+	if (value.results.length === 0) {
+		return `query: ${value.query}\n没有匹配结果（本次请求不计费）。换个关键词，或用 site: / after: 收窄范围后重试。`;
+	}
+	const blocks = value.results.map(resultBlock).join("\n\n");
+	return [
+		`query: ${value.query}   命中 ${value.total} 条`,
+		"",
+		blocks,
+		"",
+		"★ = rerank ≥ 1.5 优质；正文用 deepseek_fetch <url> 取全文。",
+	].join("\n");
+}

package/lib/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Public surface of dsh-search.
+ */
+
+import type { SearchClient } from "./client.js";
+
+export declare const name: string;
+export declare const inject: string[];
+export declare const Config: unknown;
+export { SearchClient };
+export declare function apply(ctx: any, config: Record<string, any>): void;

package/lib/index.js

@@ -0,0 +1,79 @@
+/**
+ * dsh-search — DeepSeek first-party Search / Fetch tools for
+ * DeepSeek Harness.
+ *
+ * This entry point only wires things together: it validates config, owns the
+ * client lifecycle, contributes the guide section, and registers the tools
+ * described in `./tools/`. Configuration lives in `./config.js`, key resolution
+ * in `./keys.js`, the HTTP protocol in `./client.js`, the guide text in
+ * `./prompt.js`.
+ *
+ * @module dsh-search
+ */
+
+import { defineTool } from "@deepseek-ai/dsh-tools";
+
+import { SearchClient } from "./client.js";
+import { Config, resolveConfig, validateConfig } from "./config.js";
+import { guideText } from "./prompt.js";
+import { createToolSpecs } from "./tools.js";
+
+export const name = "deepseek-search";
+
+export const inject = ["tools", "systemPrompt"];
+
+export { Config, SearchClient };
+
+export function apply(ctx, config) {
+	const settings = resolveConfig(config);
+	validateConfig(settings);
+
+	/** @type {SearchClient|undefined} */
+	let client;
+	ctx.effect(() => {
+		client = new SearchClient({
+			baseUrl: settings.baseUrl,
+			apiKey: settings.apiKey,
+			timeoutMs: settings.timeoutMs,
+			maxRetries: settings.maxRetries,
+		});
+		return () => {
+			client = undefined;
+		};
+	});
+
+	/**
+	 * The live client, or a loud failure — reached only while the fiber is active.
+	 *
+	 * @returns {SearchClient} live client.
+	 */
+	const getClient = () => {
+		if (!client) throw new Error("deepseek-search: client is not available");
+		return client;
+	};
+
+	if (settings.promptEnabled) {
+		ctx.systemPrompt.section({
+			name: "deepseek-search:guide",
+			order: settings.promptOrder,
+			text: () => guideText(settings),
+		});
+	}
+
+	for (const spec of createToolSpecs({ client: getClient(), config: settings })) {
+		ctx.tools.register(
+			defineTool({
+				name: spec.name,
+				description: spec.description,
+				parameters: spec.parameters,
+				output: {
+					schema: spec.outputSchema,
+					render: spec.render,
+					...(spec.presentationMeta ? { presentationMeta: spec.presentationMeta } : {}),
+				},
+				...(spec.call ? { presentCall: spec.call } : {}),
+				execute: spec.execute,
+			}),
+		);
+	}
+}

package/lib/keys.js

@@ -0,0 +1,70 @@
+/**
+ * API key resolution — three layers, in order, so no key ever lives in the
+ * plugin's own config file:
+ *
+ *   1. `apiKey` from the plugin config (explicit opt-in)
+ *   2. `$DEEPSEEK_API_KEY`
+ *   3. `~/.secrets/keys.env`            (`DEEPSEEK_API_KEY=...`)
+ *   4. `$DSH_HOME/.credentials.yaml`    (`refs: DEEPSEEK_API_KEY: sk-...`)
+ *
+ * @module dsh-search/keys
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Read one key out of a dotenv-style file.
+ *
+ * @param {string} file - absolute path.
+ * @param {string} name - variable name.
+ * @returns {string} the value, or "" when absent.
+ */
+function fromDotEnv(file, name) {
+	if (!existsSync(file)) return "";
+	const pattern = new RegExp(`^\\s*(?:export\\s+)?${name}\\s*=\\s*(.+?)\\s*$`, "m");
+	const match = readFileSync(file, "utf8").match(pattern);
+	return match ? match[1].replace(/^["']|["']$/g, "").trim() : "";
+}
+
+/**
+ * Read one key out of DSH's credentials store (`refs:` block).
+ *
+ * @param {string} file - absolute path.
+ * @param {string} name - variable name.
+ * @returns {string} the value, or "" when absent.
+ */
+function fromCredentials(file, name) {
+	if (!existsSync(file)) return "";
+	const pattern = new RegExp(`^\\s*${name}:\\s*(\\S+)\\s*$`, "m");
+	const match = readFileSync(file, "utf8").match(pattern);
+	return match ? match[1].replace(/^["']|["']$/g, "").trim() : "";
+}
+
+/**
+ * Resolve the API key and report which layer answered.
+ *
+ * @param {{explicit?: string, env?: NodeJS.ProcessEnv, home?: string, dshHome?: string}} [options] - lookup overrides.
+ * @returns {{key: string, source: string}} resolved key plus provenance.
+ */
+export function resolveApiKey(options = {}) {
+	const env = options.env ?? process.env;
+	const home = options.home ?? homedir();
+	const dshHome = options.dshHome ?? env.DSH_HOME ?? join(home, ".dsh");
+	const name = "DEEPSEEK_API_KEY";
+
+	const explicit = String(options.explicit ?? "").trim();
+	if (explicit !== "") return { key: explicit, source: "plugin config" };
+
+	const fromEnv = String(env[name] ?? "").trim();
+	if (fromEnv !== "") return { key: fromEnv, source: `env ${name}` };
+
+	const dotenv = fromDotEnv(join(home, ".secrets", "keys.env"), name);
+	if (dotenv !== "") return { key: dotenv, source: "~/.secrets/keys.env" };
+
+	const cred = fromCredentials(join(dshHome, ".credentials.yaml"), name);
+	if (cred !== "") return { key: cred, source: "~/.dsh/.credentials.yaml" };
+
+	return { key: "", source: "missing" };
+}

package/lib/prompt.js

@@ -0,0 +1,25 @@
+/**
+ * The system-prompt section this plugin contributes.
+ *
+ * Short on purpose: it only states when the tools beat the built-in ones and
+ * what each successful call costs, since the tool descriptions carry the rest.
+ *
+ * @module dsh-search/prompt
+ */
+
+/**
+ * @param {Record<string, any>} config - effective plugin config.
+ * @returns {string} prompt section text.
+ */
+export function guideText(config) {
+	const key = "（key 从 DEEPSEEK_API_KEY / ~/.secrets/keys.env / ~/.dsh/.credentials.yaml 解析）";
+	return [
+		"联网搜索与抓取默认走 DeepSeek 官方接口，而不是内置 web_search / web_fetch：",
+		"- deepseek_search：要线索。返回 rerank 分、权威度、发布时间，可用 site: / after: / before: / lang: / 精确短语 / 排除词。",
+		"- deepseek_fetch：要原文。单页转 Markdown，核实版本号、日期、价格、API 字段时用。",
+		"- deepseek_research：要结论。一次搜索＋抓前 N 页正文（默认 2）。",
+		"判读：rerankScore ≥ 1.5 为优质，authority ≥ 3 为高权威；summary 是二手摘要，关键事实必须 fetch 原文核实；引用给原始 URL。",
+		`成本：每次成功请求计费（约 5 元/千次），count 不影响单价——一次取够，别拆分多次；空结果不计费。限速 Search/Fetch 各 5 QPS。${key}`,
+		"仅在不想计费、或需要登录态/点击交互的页面时，才回退内置通道或浏览器自动化。",
+	].join("\n");
+}

package/lib/query.js

@@ -0,0 +1,53 @@
+/**
+ * Query assembly: turn the tool's structured arguments into one DeepSeek query
+ * string, applying the operators the search backend understands.
+ *
+ * @module dsh-search/query
+ */
+
+/** Longest query the endpoint accepts. */
+export const MAX_QUERY_CHARS = 128;
+
+/**
+ * Expand a site argument into `site:` clauses joined by OR.
+ *
+ * A caller may pass `github.com`, `github.com huggingface.co`, or
+ * `github.com,huggingface.co`; a value that already carries an operator
+ * (`site:`, a leading `-`, or an explicit `OR`) is passed through untouched.
+ *
+ * @param {string} site - raw argument.
+ * @returns {string} clause(s) appended to the query.
+ */
+export function normalizeSite(site) {
+	const raw = String(site ?? "").trim();
+	if (raw === "") return "";
+	if (/(^|\s)site:/.test(raw) || /^(?:-|\+|OR\b)/i.test(raw)) return raw;
+	return raw
+		.split(/[\s,]+/)
+		.filter(Boolean)
+		.map((host) => `site:${host}`)
+		.join(" OR ");
+}
+
+/**
+ * Build the final query string.
+ *
+ * @param {{query: string, site?: string, lang?: string, after?: string, before?: string}} args - tool arguments.
+ * @returns {string} query with operators appended.
+ * @throws {Error} when the query is blank or too long.
+ */
+export function buildQuery(args) {
+	const base = String(args.query ?? "").trim();
+	if (base === "") throw new Error("deepseek-search: `query` 不能为空");
+	const parts = [base];
+	const site = normalizeSite(args.site);
+	if (site !== "") parts.push(site);
+	if (args.lang) parts.push(`lang:${String(args.lang).trim()}`);
+	if (args.after) parts.push(`after:${String(args.after).trim()}`);
+	if (args.before) parts.push(`before:${String(args.before).trim()}`);
+	const query = parts.join(" ").trim();
+	if ([...query].length > MAX_QUERY_CHARS) {
+		throw new Error(`deepseek-search: query 超长（${[...query].length} > ${MAX_QUERY_CHARS} 字符），请精简后重试`);
+	}
+	return query;
+}

package/lib/tools/fetch.js

@@ -0,0 +1,57 @@
+/**
+ * `deepseek_fetch` — one page as Markdown.
+ *
+ * @module dsh-search/tools
+ */
+
+import { clip } from "../format.js";
+import { guarded, requireText } from "./shared.js";
+
+export function createFetchTool(ctx) {
+	const { client, config } = ctx;
+	return {
+		name: "deepseek_fetch",
+		description:
+			"Fetch one web page and get its main content as Markdown (title plus body), extracted by DeepSeek. Use it to read the full text behind a search result, verify a version number / date / price / API field, or quote a page exactly — a search result's summary is a second-hand digest. Cost: one billed request per successful fetch (empty or blocked pages are not billed). JSON API endpoints, PDFs without text, and login-gated pages usually fail with a clear error; those need a browser instead.",
+		parameters: {
+			url: { type: "string", required: true, description: "Absolute http(s) URL, no embedded username/password." },
+			maxChars: { type: "integer", description: "Body ceiling in characters (default from config, usually 20000). The reply says whether it was truncated." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				url: { type: "string", required: true },
+				title: { type: "string", required: true },
+				content: { type: "string", required: true },
+				chars: { type: "integer", required: true },
+				truncated: { type: "boolean", required: true },
+				billed: { type: "boolean", required: true },
+			},
+		},
+		call: (args) => ({ card: "generic", title: `deepseek_fetch ${args.url}`, kind: "search" }),
+		render: (_args, value) => {
+			const header = `# ${value.title || "(无标题)"}\n${value.url}\n`;
+			const footer = value.truncated ? `\n\n…（正文 ${value.chars} 字符处截断，可调大 maxChars）` : "";
+			return [{ type: "text", text: value.content ? header + "\n" + value.content + footer : `${header}\n（没有可提取的正文，本次不计费）` }];
+		},
+		execute: (args) =>
+			guarded(async () => {
+				const url = requireText(args.url, "url");
+				if (!/^https?:\/\//i.test(url)) throw new Error("deepseek-search: `url` 必须是 http:// 或 https:// 开头的绝对地址");
+				const limit = Number.isFinite(Number(args.maxChars)) && Number(args.maxChars) > 0
+					? Math.trunc(Number(args.maxChars))
+					: config.fetchMaxChars;
+				const page = await client.fetchPage(url);
+				const body = clip(page.content, limit);
+				return {
+					url,
+					title: page.title,
+					content: body.text,
+					chars: page.content.length,
+					truncated: body.truncated,
+					billed: page.content.length > 0,
+				};
+			}),
+	};
+}

package/lib/tools/research.js

@@ -0,0 +1,155 @@
+/**
+ * `deepseek_research` — search once, then fetch the top pages, in one call.
+ *
+ * Saves the model a round trip when it needs a conclusion rather than links:
+ * one billed search plus one billed fetch per fetched page.
+ *
+ * @module dsh-search/tools
+ */
+
+import { normalizeResult, resultBlock } from "../format.js";
+import { buildQuery } from "../query.js";
+import { clampInt, guarded, requireText } from "./shared.js";
+
+/** Space between fetches, keeping well inside the account-wide 5 QPS. */
+const FETCH_GAP_MS = 220;
+
+export function createResearchTool(ctx) {
+	const { client, config } = ctx;
+	return {
+		name: "deepseek_research",
+		description:
+			"Search and read in one call: run the query, then fetch the top N pages and return their opening text alongside the summaries. Use it when the answer needs page content, not just links. Cost: one billed search + one billed fetch per fetched page, so keep `top` small (1-2 is usually enough; `top: 0` skips fetching entirely). Prefer `deepseek_search` when you only need candidate URLs, and `deepseek_fetch` when you already know which page to read.",
+		parameters: {
+			query: { type: "string", required: true, description: "Search terms, 1-128 characters; operators allowed." },
+			count: { type: "integer", description: "Results to list, 1-50 (default from config, usually 5)." },
+			top: { type: "integer", description: "How many top results to fetch full text for, 0-5 (default 2). Each fetched page is billed separately." },
+			excerptChars: { type: "integer", description: "Characters of body kept per fetched page (default 3000)." },
+			site: { type: "string", description: "Restrict to sites, e.g. `github.com` or `github.com huggingface.co`." },
+			lang: { type: "string", description: "Restrict to languages, comma separated." },
+			after: { type: "string", description: "Only pages published after this date." },
+			before: { type: "string", description: "Only pages published before this date." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				query: { type: "string", required: true },
+				total: { type: "integer", required: true },
+				fetched: { type: "integer", required: true },
+				billedRequests: { type: "integer", required: true },
+				results: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							rank: { type: "integer", required: true },
+							title: { type: "string", required: true },
+							url: { type: "string", required: true },
+							snippet: { type: "string", required: true },
+							summary: { type: "string", required: true },
+							content: { type: "string", required: true },
+							siteName: { type: "string", required: true },
+							date: { type: "string", required: true },
+							authority: { type: "integer", required: true },
+							rerankScore: { type: "number", required: true },
+							good: { type: "boolean", required: true },
+							excerpt: { type: "string", required: true },
+							fetchError: { type: "string", required: true },
+						},
+					},
+				},
+			},
+		},
+		call: (args) => ({ card: "generic", title: `deepseek_research ${args.query}`, kind: "search" }),
+		render: (_args, value) => {
+			if (value.results.length === 0) {
+				return [{ type: "text", text: `query: ${value.query}\n没有匹配结果（本次请求不计费）。` }];
+			}
+			const blocks = value.results
+				.map((result) => {
+					const base = resultBlock(result);
+					if (result.excerpt) return `${base}\n    ── 正文节选 ──\n${indent(result.excerpt)}`;
+					if (result.fetchError) return `${base}\n    ⚠ 抓取失败：${result.fetchError}`;
+					return base;
+				})
+				.join("\n\n");
+			return [
+				{
+					type: "text",
+					text: [
+						`query: ${value.query}   命中 ${value.total} 条，抓取 ${value.fetched} 页正文（计费 ${value.billedRequests} 次请求）`,
+						"",
+						blocks,
+						"",
+						"引用请带原始 URL；正文是节选，长文用 deepseek_fetch 取全文。",
+					].join("\n"),
+				},
+			];
+		},
+		execute: (args) =>
+			guarded(async () => {
+				const query = buildQuery({
+					query: requireText(args.query, "query"),
+					site: args.site,
+					lang: args.lang,
+					after: args.after,
+					before: args.before,
+				});
+				const count = clampInt(args.count, config.defaultCount, 1, 50);
+				const top = clampInt(args.top, 2, 0, 5);
+				const excerptChars = clampInt(args.excerptChars, 3_000, 200, config.maxContentChars);
+
+				const raw = await client.search({ query, count });
+				const results = raw.map((item, index) => ({
+					...normalizeResult(item, index + 1, { contentLimit: 0 }),
+					excerpt: "",
+					fetchError: "",
+				}));
+
+				let fetched = 0;
+				for (const result of results.slice(0, top)) {
+					if (fetched > 0) await sleep(FETCH_GAP_MS);
+					try {
+						const page = await client.fetchPage(result.url);
+						result.excerpt = page.content.slice(0, excerptChars);
+						fetched += 1;
+					} catch (error) {
+						result.fetchError = String(error?.message ?? error);
+					}
+				}
+
+				return {
+					query,
+					total: results.length,
+					fetched,
+					billedRequests: results.length === 0 ? 0 : 1 + fetched,
+					results,
+				};
+			}),
+	};
+}
+
+/**
+ * Indent an excerpt for display.
+ *
+ * @param {string} text - body excerpt.
+ * @returns {string} indented, blank-line-collapsed text.
+ */
+function indent(text) {
+	return text
+		.replace(/\n{3,}/g, "\n\n")
+		.split("\n")
+		.map((line) => `    ${line}`)
+		.join("\n");
+}
+
+/**
+ * @param {number} ms - delay.
+ * @returns {Promise<void>} resolves after the delay.
+ */
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/lib/tools/search.js

@@ -0,0 +1,78 @@
+/**
+ * `deepseek_search` — web search with structured, reranked results.
+ *
+ * @module dsh-search/tools
+ */
+
+import { normalizeResult, renderSearchReport } from "../format.js";
+import { buildQuery } from "../query.js";
+import { clampInt, guarded, requireText } from "./shared.js";
+
+export function createSearchTool(ctx) {
+	const { client, config } = ctx;
+	return {
+		name: "deepseek_search",
+		description:
+			"Search the web through DeepSeek's first-party search engine and get structured, reranked results (title, url, snippet, model-ready summary, optional page content, publish date, authority, rerank score). Supports the operators site:, -site:, -, -\"phrase\", \"exact\", lang:, after:, before: — pass them inside `query` or use the dedicated arguments. Cost: one billed request per successful call (empty results are not billed), so ask for every result you need in one call instead of calling repeatedly. Result count does not change the price. Use `deepseek_fetch` when you need a full page rather than a summary.",
+		parameters: {
+			query: { type: "string", required: true, description: "Search terms, 1-128 characters. Operators are allowed, e.g. `DeepSeek -site:csdn.net after:2025`." },
+			count: { type: "integer", description: "How many results to return, 1-50 (default from config, usually 5)." },
+			site: { type: "string", description: "Restrict to sites: `github.com` or `github.com huggingface.co` (becomes `site:a OR site:b`)." },
+			lang: { type: "string", description: "Restrict to languages, comma separated, e.g. `zh,en`." },
+			after: { type: "string", description: "Only pages published after this date, `2025` or `2025-01-01`." },
+			before: { type: "string", description: "Only pages published before this date, `2026` or `2026-06-01`." },
+			oriQuestion: { type: "string", description: "The user's original question verbatim; helps the engine infer intent on noisy queries." },
+			needContent: { type: "boolean", description: "Also return page body for each result (bigger payload, same price). Prefer `deepseek_fetch` for one specific page." },
+		},
+		outputSchema: {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				query: { type: "string", required: true },
+				total: { type: "integer", required: true },
+				billed: { type: "boolean", required: true },
+				results: {
+					type: "array",
+					required: true,
+					items: {
+						type: "object",
+						additionalProperties: false,
+						properties: {
+							rank: { type: "integer", required: true },
+							title: { type: "string", required: true },
+							url: { type: "string", required: true },
+							snippet: { type: "string", required: true },
+							summary: { type: "string", required: true },
+							content: { type: "string", required: true },
+							siteName: { type: "string", required: true },
+							date: { type: "string", required: true },
+							authority: { type: "integer", required: true },
+							rerankScore: { type: "number", required: true },
+							good: { type: "boolean", required: true },
+						},
+					},
+				},
+			},
+		},
+		call: (args) => ({ card: "generic", title: `deepseek_search ${args.query}`, kind: "search" }),
+		render: (_args, value) => [{ type: "text", text: renderSearchReport(value) }],
+		execute: (args) =>
+			guarded(async () => {
+				const query = buildQuery({
+					query: requireText(args.query, "query"),
+					site: args.site,
+					lang: args.lang,
+					after: args.after,
+					before: args.before,
+				});
+				const count = clampInt(args.count, config.defaultCount, 1, 50);
+				const oriQuestion = args.oriQuestion ? String(args.oriQuestion).trim() : "";
+				const needContent = args.needContent === true;
+				const raw = await client.search({ query, count, oriQuestion, needContent });
+				const results = raw.map((item, index) =>
+					normalizeResult(item, index + 1, { contentLimit: needContent ? config.maxContentChars : 0 }),
+				);
+				return { query, total: results.length, billed: results.length > 0, results };
+			}),
+	};
+}

package/lib/tools/shared.js

@@ -0,0 +1,51 @@
+/**
+ * Helpers every tool file shares: argument clamping, error surfacing, and the
+ * "this argument must be a non-blank string" guard.
+ *
+ * @module dsh-search/tools
+ */
+
+/**
+ * Clamp a numeric argument into range.
+ *
+ * @param {unknown} value - candidate value.
+ * @param {number} fallback - default when absent or non-numeric.
+ * @param {number} min - lower bound.
+ * @param {number} max - upper bound.
+ * @returns {number} clamped integer.
+ */
+export function clampInt(value, fallback, min, max) {
+	const numeric = Number(value);
+	if (!Number.isFinite(numeric)) return fallback;
+	return Math.min(Math.max(Math.trunc(numeric), min), max);
+}
+
+/**
+ * Require a non-blank string argument.
+ *
+ * @param {unknown} value - candidate value.
+ * @param {string} field - argument name, for the error message.
+ * @returns {string} trimmed value.
+ * @throws {Error} when the value is missing or blank.
+ */
+export function requireText(value, field) {
+	const text = String(value ?? "").trim();
+	if (text === "") throw new Error(`deepseek-search: \`${field}\` 不能为空`);
+	return text;
+}
+
+/**
+ * Wrap a tool body so client failures carry their actionable hint.
+ *
+ * @param {() => Promise<any>} body - tool body.
+ * @returns {Promise<any>} body result.
+ */
+export async function guarded(body) {
+	try {
+		return await body();
+	} catch (error) {
+		const hint = /** @type {{hint?: string}} */ (error)?.hint;
+		if (hint) throw new Error(`${error.message} — ${hint}`);
+		throw error;
+	}
+}

package/lib/tools.js

@@ -0,0 +1,21 @@
+/**
+ * Tool registry: one tool per file, in the order the model should see them.
+ *
+ * @module dsh-search/tools
+ */
+
+import { clampInt, guarded, requireText } from "./tools/shared.js";
+import { createSearchTool } from "./tools/search.js";
+import { createFetchTool } from "./tools/fetch.js";
+import { createResearchTool } from "./tools/research.js";
+
+/**
+ * Build every tool spec for one plugin instance.
+ *
+ * @param {{client: import("./client.js").SearchClient, config: Record<string, any>}} deps - plugin deps.
+ * @returns {Array<Record<string, any>>} tool specs in presentation order.
+ */
+export function createToolSpecs({ client, config }) {
+	const ctx = { client, config, clampInt, guarded, requireText };
+	return [createSearchTool(ctx), createFetchTool(ctx), createResearchTool(ctx)];
+}

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@vfvrpq/dsh-search",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "DeepSeek first-party Search/Fetch API for DeepSeek Harness: three tools (deepseek_search / deepseek_fetch / deepseek_research) that return structured, reranked web results with search operators, page-to-Markdown fetching, and cost-aware defaults.",
+  "type": "module",
+  "license": "MIT",
+  "author": "439436269-ctrl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/439436269-ctrl/dsh-search.git"
+  },
+  "homepage": "https://github.com/439436269-ctrl/dsh-search#readme",
+  "bugs": {
+    "url": "https://github.com/439436269-ctrl/dsh-search/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "deepseek",
+    "search",
+    "fetch",
+    "web-search",
+    "rag"
+  ],
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "CHANGELOG.md",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.2.0-rc.2 || ^0.2.1-rc.1 || ^0.2.2-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.2.0-rc.2 || ^0.2.1-rc.1 || ^0.2.2-rc.1"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "compatibility": {
+      "dshReleases": {
+        "0.2.0-rc.2": "compatible",
+        "0.2.1-rc.2": "compatible",
+        "0.2.2-rc.1": "compatible"
+      }
+    }
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "selftest": "node scripts/live-selftest.js"
+  }
+}