@wjm200509/dsh-web-search 0.0.0-stage → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +135 -3
- package/lib/client.js +461 -0
- package/lib/dispatch.js +50 -0
- package/lib/engines/model-native.js +135 -0
- package/lib/engines/tavily.js +89 -0
- package/lib/errors.js +32 -0
- package/lib/http.js +129 -0
- package/lib/index.js +123 -0
- package/lib/options.js +75 -0
- package/package.json +56 -4
- package/patch.yml +23 -0
package/lib/dispatch.js
ADDED
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The switchable multi-engine `WebSearchProvider` registered into `ctx.web` as
|
|
3
|
+
* `web-search`. Engine selection is re-read from the live settings source at
|
|
4
|
+
* every search entry (one snapshot per call, so a mid-flight engine switch
|
|
5
|
+
* never mixes two configurations). Pure module (no `@deepseek-ai/*` imports);
|
|
6
|
+
* the Host half injects the seam's real `WebError` factories via `deps`.
|
|
7
|
+
*/
|
|
8
|
+
import { engineAvailable } from "./options.js";
|
|
9
|
+
|
|
10
|
+
/** Stable provider id, pinned by the `web` row's `searchProvider`. */
|
|
11
|
+
export const WEB_SEARCH_PROVIDER_ID = "web-search";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* A search provider that dispatches to the settings-selected engine.
|
|
15
|
+
*/
|
|
16
|
+
export class DispatchProvider {
|
|
17
|
+
/**
|
|
18
|
+
* @param {() => { engine: string, tavily: object, model: object }} resolveOptions - live options source.
|
|
19
|
+
* @param {Record<string, (options: object, request: { query: string, maxResults?: number }, signal: AbortSignal | undefined, deps: object) => Promise<object>>} engines - engine runners by id.
|
|
20
|
+
* @param {{ fetch: typeof fetch, errors: { provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error } }} deps - transport and error deps.
|
|
21
|
+
*/
|
|
22
|
+
constructor(resolveOptions, engines, deps) {
|
|
23
|
+
this.resolveOptions = resolveOptions;
|
|
24
|
+
this.engines = engines;
|
|
25
|
+
this.deps = deps;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** Stable id this provider registers under. */
|
|
29
|
+
id = WEB_SEARCH_PROVIDER_ID;
|
|
30
|
+
|
|
31
|
+
/** Cheap local usability check for the currently selected engine. */
|
|
32
|
+
available() {
|
|
33
|
+
const options = this.resolveOptions();
|
|
34
|
+
return engineAvailable(options.engine, options);
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/**
|
|
38
|
+
* Run one search through the selected engine.
|
|
39
|
+
* @param {{ query: string, maxResults?: number }} request - the seam's search request.
|
|
40
|
+
* @param {AbortSignal | undefined} [signal] - cancellation signal forwarded to the engine.
|
|
41
|
+
* @returns {Promise<object>} the normalized result.
|
|
42
|
+
*/
|
|
43
|
+
async search(request, signal) {
|
|
44
|
+
const options = this.resolveOptions();
|
|
45
|
+
const engine = options.engine;
|
|
46
|
+
const run = this.engines[engine];
|
|
47
|
+
if (run === undefined) throw this.deps.errors.provider(`unknown web search engine "${engine}"`, "WEB_PROVIDER_ERROR");
|
|
48
|
+
return run(options[engine], request, signal, this.deps);
|
|
49
|
+
}
|
|
50
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Model-native web search engine: one minimal chat completion carrying the
|
|
3
|
+
* model API's server-side `web_search` tool (MiMo / openai-compatible), with
|
|
4
|
+
* structured citation extraction only — never URLs scraped out of model prose.
|
|
5
|
+
*
|
|
6
|
+
* Billing is per search round at the provider (MiMo: ¥16 per 1000 plugin
|
|
7
|
+
* calls plus token fees), so the request pins `max_keyword: 1` to cap cost.
|
|
8
|
+
* Pure module (no `@deepseek-ai/*` imports); transport and error factories
|
|
9
|
+
* arrive via `deps`.
|
|
10
|
+
*/
|
|
11
|
+
import { missingKeyError, postJson, readErrorDetail, readJson, resolveApiKey } from "../http.js";
|
|
12
|
+
|
|
13
|
+
/** Tokens reserved for the model's summary over the retrieved sources. */
|
|
14
|
+
const MAX_COMPLETION_TOKENS = 1024;
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Build the chat-completions request for one forced web search.
|
|
18
|
+
* @param {{ modelId: string }} options - normalized model-native options.
|
|
19
|
+
* @param {string} query - the search query.
|
|
20
|
+
* @param {number | undefined} maxResults - the seam's source cap.
|
|
21
|
+
* @returns {Record<string, unknown>} the request body.
|
|
22
|
+
*/
|
|
23
|
+
export function buildModelRequest(options, query, maxResults) {
|
|
24
|
+
return {
|
|
25
|
+
model: options.modelId,
|
|
26
|
+
messages: [{ role: "user", content: query }],
|
|
27
|
+
max_completion_tokens: MAX_COMPLETION_TOKENS,
|
|
28
|
+
stream: false,
|
|
29
|
+
thinking: { type: "disabled" },
|
|
30
|
+
tools: [{
|
|
31
|
+
type: "web_search",
|
|
32
|
+
max_keyword: 1,
|
|
33
|
+
force_search: true,
|
|
34
|
+
...(maxResults !== undefined ? { limit: maxResults } : {})
|
|
35
|
+
}]
|
|
36
|
+
};
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
/** Collect one candidate citation object into a normalized source. */
|
|
40
|
+
function pushSource(out, seen, item) {
|
|
41
|
+
if (item === null || typeof item !== "object") return;
|
|
42
|
+
const candidate = /** @type {{ url?: unknown, link?: unknown, title?: unknown, name?: unknown, snippet?: unknown, content?: unknown, description?: unknown, cited_text?: unknown, publishedAt?: unknown, date?: unknown, page_age?: unknown, url_citation?: unknown }} */ (item);
|
|
43
|
+
const nested = candidate.url_citation !== null && typeof candidate.url_citation === "object" ? /** @type {Record<string, unknown>} */ (candidate.url_citation) : undefined;
|
|
44
|
+
const record = nested ?? candidate;
|
|
45
|
+
const url = typeof record.url === "string" ? record.url : typeof record.link === "string" ? record.link : undefined;
|
|
46
|
+
if (url === undefined || url.length === 0 || seen.has(url)) return;
|
|
47
|
+
seen.add(url);
|
|
48
|
+
const title = typeof record.title === "string" ? record.title : typeof record.name === "string" ? record.name : undefined;
|
|
49
|
+
const snippet = typeof record.snippet === "string" ? record.snippet : typeof record.content === "string" ? record.content : typeof record.description === "string" ? record.description : typeof record.cited_text === "string" ? record.cited_text : undefined;
|
|
50
|
+
const publishedAt = record.publishedAt ?? record.date ?? record.page_age;
|
|
51
|
+
out.push({
|
|
52
|
+
url,
|
|
53
|
+
...title !== undefined && title.length > 0 ? { title } : {},
|
|
54
|
+
...snippet !== undefined && snippet.length > 0 ? { snippet } : {},
|
|
55
|
+
...publishedAt != null && String(publishedAt).length > 0 ? { publishedAt: String(publishedAt) } : {}
|
|
56
|
+
});
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Walk the known structured citation sites of a chat-completions response. */
|
|
60
|
+
function collectSources(payload) {
|
|
61
|
+
const out = [];
|
|
62
|
+
const seen = new Set();
|
|
63
|
+
const body = /** @type {Record<string, unknown>} */ (payload);
|
|
64
|
+
const messages = [body, ...(Array.isArray(body.choices) ? body.choices.map((choice) => /** @type {{ message?: unknown }} */ (choice)?.message).filter((message) => message !== null && typeof message === "object") : [])];
|
|
65
|
+
for (const message of messages) {
|
|
66
|
+
const record = /** @type {Record<string, unknown>} */ (message);
|
|
67
|
+
for (const key of ["annotations", "citations", "search_results", "web_search_results", "url_citation"]) {
|
|
68
|
+
const value = record[key];
|
|
69
|
+
if (Array.isArray(value)) for (const item of value) pushSource(out, seen, item);
|
|
70
|
+
else if (value !== null && typeof value === "object") pushSource(out, seen, value);
|
|
71
|
+
}
|
|
72
|
+
}
|
|
73
|
+
for (const key of ["search_results", "web_search_results"]) {
|
|
74
|
+
const value = body[key];
|
|
75
|
+
if (Array.isArray(value)) for (const item of value) pushSource(out, seen, item);
|
|
76
|
+
}
|
|
77
|
+
return out;
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/**
|
|
81
|
+
* Map a chat-completions response to the seam's normalized result.
|
|
82
|
+
* @param {unknown} payload - the parsed response body.
|
|
83
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error }} errors - error factory pair.
|
|
84
|
+
* @returns {{ content?: string, sources: Array<{ url: string, title?: string, snippet?: string, publishedAt?: string }>, truncated: boolean }} normalized result.
|
|
85
|
+
*/
|
|
86
|
+
export function mapModelResponse(payload, errors) {
|
|
87
|
+
if (payload === null || typeof payload !== "object") throw errors.provider("the model API returned an unprocessable response body", "WEB_PROVIDER_ERROR");
|
|
88
|
+
const body = /** @type {{ choices?: Array<{ message?: { content?: unknown } }>, error?: unknown, message?: { content?: unknown } }} */ (payload);
|
|
89
|
+
const message = body.choices?.[0]?.message ?? body.message;
|
|
90
|
+
const content = typeof message?.content === "string" && message.content.length > 0 ? message.content : undefined;
|
|
91
|
+
const sources = collectSources(payload);
|
|
92
|
+
if (sources.length === 0) {
|
|
93
|
+
throw errors.provider(`the model API returned no structured search citations (top-level keys: ${Object.keys(payload).join(", ") || "none"}); the web search plugin may be disabled for this API key or the response shape is unrecognized`, "WEB_PROVIDER_ERROR");
|
|
94
|
+
}
|
|
95
|
+
return { ...content !== undefined ? { content } : {}, sources, truncated: false };
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* Run one model-native web search.
|
|
100
|
+
* @param {{ apiKey?: string, resolveKey?: () => Promise<string | undefined>, baseURL: string, modelId: string }} options - normalized model-native options.
|
|
101
|
+
* @param {{ query: string, maxResults?: number }} request - the seam's search request.
|
|
102
|
+
* @param {AbortSignal | undefined} signal - cancellation signal.
|
|
103
|
+
* @param {{ fetch: typeof fetch, errors: { provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error } }} deps - transport and error deps.
|
|
104
|
+
* @returns {Promise<{ content?: string, sources: Array<{ url: string, title?: string, snippet?: string, publishedAt?: string }>, truncated: boolean }>} the normalized result.
|
|
105
|
+
*/
|
|
106
|
+
export async function searchModel(options, request, signal, deps) {
|
|
107
|
+
const { errors } = deps;
|
|
108
|
+
const apiKey = await resolveApiKey(options, signal, errors);
|
|
109
|
+
if (apiKey === undefined || apiKey.length === 0) throw missingKeyError("model-native web search", "MIMO1_API_KEY", "modelApiKey", errors);
|
|
110
|
+
const endpoint = `${options.baseURL.replace(/\/+$/, "")}/chat/completions`;
|
|
111
|
+
const response = await postJson(endpoint, {
|
|
112
|
+
headers: {
|
|
113
|
+
"authorization": `Bearer ${apiKey}`,
|
|
114
|
+
"api-key": apiKey,
|
|
115
|
+
"content-type": "application/json",
|
|
116
|
+
"accept": "application/json"
|
|
117
|
+
},
|
|
118
|
+
body: buildModelRequest(options, request.query, request.maxResults),
|
|
119
|
+
...signal !== undefined ? { signal } : {}
|
|
120
|
+
}, deps);
|
|
121
|
+
if (!response.ok) {
|
|
122
|
+
let detail = await readErrorDetail(response, signal, errors, (payload) => {
|
|
123
|
+
const message = payload?.error;
|
|
124
|
+
return typeof message === "string" ? message : typeof message?.param === "string" ? message.param : typeof message?.message === "string" ? message.message : typeof payload?.message === "string" ? payload.message : undefined;
|
|
125
|
+
});
|
|
126
|
+
if (/webSearchEnabled/i.test(detail)) {
|
|
127
|
+
detail += ". Activate the Web Search plugin in the model provider's console (Console > Plugin Management) first; it bills per search round";
|
|
128
|
+
}
|
|
129
|
+
if (response.status === 401 || response.status === 403) {
|
|
130
|
+
throw errors.provider(`the model API rejected the API key or the web search plugin is not activated (HTTP ${response.status})${detail}; activate the Web Search plugin in the provider console and check the key`, "WEB_PROVIDER_CREDENTIAL_MISSING");
|
|
131
|
+
}
|
|
132
|
+
throw errors.provider(`the model API error (HTTP ${response.status})${detail}`, "WEB_PROVIDER_ERROR");
|
|
133
|
+
}
|
|
134
|
+
return mapModelResponse(await readJson(response, signal, errors), errors);
|
|
135
|
+
}
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tavily search engine (`https://api.tavily.com/search`, free tier: 1000
|
|
3
|
+
* credits/month). Pure module (no `@deepseek-ai/*` imports) so `node --test`
|
|
4
|
+
* can run it standalone; transport and error factories arrive via `deps`.
|
|
5
|
+
*/
|
|
6
|
+
import { missingKeyError, postJson, readErrorDetail, readJson, resolveApiKey } from "../http.js";
|
|
7
|
+
|
|
8
|
+
/** The Tavily Search endpoint. */
|
|
9
|
+
export const TAVILY_ENDPOINT = "https://api.tavily.com/search";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Map a Tavily Search response to the seam's normalized result.
|
|
13
|
+
* `answer` becomes `content`, each result becomes one citeable source
|
|
14
|
+
* (`content` → `snippet`, `published_date` → `publishedAt`).
|
|
15
|
+
* @param {unknown} payload - the parsed response body.
|
|
16
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error }} errors - error factory pair.
|
|
17
|
+
* @returns {{ content?: string, sources: Array<{ url: string, title?: string, snippet?: string, publishedAt?: string }>, truncated: boolean }} normalized result.
|
|
18
|
+
*/
|
|
19
|
+
export function mapTavilyResponse(payload, errors) {
|
|
20
|
+
if (payload === null || typeof payload !== "object") throw errors.provider("Tavily returned an unprocessable response body", "WEB_PROVIDER_ERROR");
|
|
21
|
+
const body = /** @type {{ answer?: unknown, results?: unknown }} */ (payload);
|
|
22
|
+
const results = Array.isArray(body.results) ? body.results : undefined;
|
|
23
|
+
const answer = typeof body.answer === "string" && body.answer.length > 0 ? body.answer : undefined;
|
|
24
|
+
if (results === undefined && answer === undefined) throw errors.provider(`Tavily returned no recognizable search results (top-level keys: ${Object.keys(body).join(", ") || "none"})`, "WEB_PROVIDER_ERROR");
|
|
25
|
+
const sources = [];
|
|
26
|
+
for (const item of results ?? []) {
|
|
27
|
+
if (item === null || typeof item !== "object") continue;
|
|
28
|
+
const result = /** @type {{ url?: unknown, title?: unknown, content?: unknown, published_date?: unknown }} */ (item);
|
|
29
|
+
if (typeof result.url !== "string" || result.url.length === 0) continue;
|
|
30
|
+
sources.push({
|
|
31
|
+
url: result.url,
|
|
32
|
+
...(typeof result.title === "string" && result.title.length > 0 ? { title: result.title } : {}),
|
|
33
|
+
...(typeof result.content === "string" && result.content.length > 0 ? { snippet: result.content } : {}),
|
|
34
|
+
...(result.published_date != null && String(result.published_date).length > 0 ? { publishedAt: String(result.published_date) } : {})
|
|
35
|
+
});
|
|
36
|
+
}
|
|
37
|
+
return { ...answer !== undefined ? { content: answer } : {}, sources, truncated: false };
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Run one Tavily search.
|
|
42
|
+
* @param {{ apiKey?: string, resolveKey?: () => Promise<string | undefined>, searchDepth: string }} options - normalized Tavily options.
|
|
43
|
+
* @param {{ query: string, maxResults?: number }} request - the seam's search request.
|
|
44
|
+
* @param {AbortSignal | undefined} signal - cancellation signal.
|
|
45
|
+
* @param {{ fetch: typeof fetch, errors: { provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error } }} deps - transport and error deps.
|
|
46
|
+
* @returns {Promise<{ content?: string, sources: Array<{ url: string, title?: string, snippet?: string, publishedAt?: string }>, truncated: boolean }>} the normalized result.
|
|
47
|
+
*/
|
|
48
|
+
export async function searchTavily(options, request, signal, deps) {
|
|
49
|
+
const { errors } = deps;
|
|
50
|
+
const apiKey = await resolveApiKey(options, signal, errors);
|
|
51
|
+
if (apiKey === undefined || apiKey.length === 0) throw missingKeyError("Tavily search", "TAVILY_API_KEY", "tavilyApiKey", errors);
|
|
52
|
+
const response = await postJson(TAVILY_ENDPOINT, {
|
|
53
|
+
headers: {
|
|
54
|
+
"authorization": `Bearer ${apiKey}`,
|
|
55
|
+
"content-type": "application/json",
|
|
56
|
+
"accept": "application/json"
|
|
57
|
+
},
|
|
58
|
+
body: {
|
|
59
|
+
query: request.query,
|
|
60
|
+
search_depth: options.searchDepth === "advanced" ? "advanced" : "basic",
|
|
61
|
+
include_answer: true,
|
|
62
|
+
...(request.maxResults !== undefined ? { max_results: request.maxResults } : {})
|
|
63
|
+
},
|
|
64
|
+
...signal !== undefined ? { signal } : {}
|
|
65
|
+
}, deps);
|
|
66
|
+
if (!response.ok) throw await statusError(response, signal, errors);
|
|
67
|
+
return mapTavilyResponse(await readJson(response, signal, errors), errors);
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Map a non-2xx Tavily status to actionable guidance.
|
|
72
|
+
* @param {Response} response - the raw response.
|
|
73
|
+
* @param {AbortSignal | undefined} signal - cancellation signal.
|
|
74
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error }} errors - error factory pair.
|
|
75
|
+
* @returns {Promise<Error>} the coded error to throw.
|
|
76
|
+
*/
|
|
77
|
+
async function statusError(response, signal, errors) {
|
|
78
|
+
const detail = await readErrorDetail(response, signal, errors, (payload) => {
|
|
79
|
+
const message = payload?.detail?.error;
|
|
80
|
+
return typeof message === "string" ? message : undefined;
|
|
81
|
+
});
|
|
82
|
+
if (response.status === 401 || response.status === 403) {
|
|
83
|
+
return errors.provider(`Tavily rejected the API key (HTTP ${response.status})${detail}`, "WEB_PROVIDER_CREDENTIAL_MISSING");
|
|
84
|
+
}
|
|
85
|
+
if (response.status === 429 || response.status === 432) {
|
|
86
|
+
return errors.provider(`Tavily rate limit or plan quota reached (HTTP ${response.status})${detail}. The free tier allows 1000 credits per month; switch the web search engine in Settings > Plugins > Plugin configuration > Web search when exhausted`, "WEB_PROVIDER_ERROR");
|
|
87
|
+
}
|
|
88
|
+
return errors.provider(`Tavily API error (HTTP ${response.status})${detail}`, "WEB_PROVIDER_ERROR");
|
|
89
|
+
}
|
package/lib/errors.js
ADDED
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Provider-neutral error vocabulary shared by the engine modules.
|
|
3
|
+
*
|
|
4
|
+
* Every engine receives this factory through its dependency seam. It creates
|
|
5
|
+
* the real `WebError` exported by `@deepseek-ai/dsh-web`, preserving the
|
|
6
|
+
* `HarnessError` prototype used by the tool runtime for structured metadata.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
import { WebError } from "@deepseek-ai/dsh-web";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Build a coded web failure with the seam's real `WebError` type.
|
|
13
|
+
* @param {string} message - human-readable failure text.
|
|
14
|
+
* @param {string} [code] - machine-routable code; defaults to provider failure.
|
|
15
|
+
* @param {unknown} [cause] - optional underlying failure.
|
|
16
|
+
* @returns {WebError} the coded error.
|
|
17
|
+
*/
|
|
18
|
+
function provider(message, code = "WEB_PROVIDER_ERROR", cause = undefined) {
|
|
19
|
+
return new WebError(message, code, cause === undefined ? undefined : { cause });
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Build the stable cancellation error (`WEB_ABORTED`), retaining the reason.
|
|
24
|
+
* @param {unknown} [cause] - the caller's abort reason, when any.
|
|
25
|
+
* @returns {Error} the coded error.
|
|
26
|
+
*/
|
|
27
|
+
function aborted(cause = undefined) {
|
|
28
|
+
return provider("web search aborted", "WEB_ABORTED", cause);
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/** Web-error factory pair injected into every engine. */
|
|
32
|
+
export const webErrors = { provider, aborted };
|
package/lib/http.js
ADDED
|
@@ -0,0 +1,129 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Transport helpers shared by the search engines: JSON POSTs with strict
|
|
3
|
+
* cancellation classification (caller abort is `WEB_ABORTED`, everything else
|
|
4
|
+
* after dispatch is `WEB_PROVIDER_ERROR`) and no redirect following.
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Throw the stable cancellation error when the caller already aborted.
|
|
9
|
+
* @param {AbortSignal | undefined} signal - the caller's cancellation signal.
|
|
10
|
+
* @param {{ aborted: (cause?: unknown) => Error }} errors - error factory pair.
|
|
11
|
+
*/
|
|
12
|
+
export function throwIfAborted(signal, errors) {
|
|
13
|
+
if (signal?.aborted === true) throw errors.aborted(signal.reason);
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Resolve an operation's API key while racing asynchronous credential lookup
|
|
18
|
+
* against caller cancellation. Resolver failures keep the web error contract.
|
|
19
|
+
* @param {{ apiKey?: string, resolveKey?: () => Promise<string | undefined> }} options - key sources.
|
|
20
|
+
* @param {AbortSignal | undefined} signal - caller cancellation signal.
|
|
21
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error }} errors - error factories.
|
|
22
|
+
* @returns {Promise<string | undefined>} the resolved key.
|
|
23
|
+
*/
|
|
24
|
+
export async function resolveApiKey(options, signal, errors) {
|
|
25
|
+
throwIfAborted(signal, errors);
|
|
26
|
+
if ((options.apiKey?.length ?? 0) > 0) return options.apiKey;
|
|
27
|
+
if (options.resolveKey === undefined) return undefined;
|
|
28
|
+
const operation = Promise.resolve().then(() => options.resolveKey());
|
|
29
|
+
try {
|
|
30
|
+
if (signal === undefined) return await operation;
|
|
31
|
+
return await new Promise((resolve, reject) => {
|
|
32
|
+
const onAbort = () => reject(errors.aborted(signal.reason));
|
|
33
|
+
signal.addEventListener("abort", onAbort, { once: true });
|
|
34
|
+
operation.then((value) => {
|
|
35
|
+
signal.removeEventListener("abort", onAbort);
|
|
36
|
+
resolve(value);
|
|
37
|
+
}, (error) => {
|
|
38
|
+
signal.removeEventListener("abort", onAbort);
|
|
39
|
+
reject(error);
|
|
40
|
+
});
|
|
41
|
+
});
|
|
42
|
+
} catch (error) {
|
|
43
|
+
if (signal?.aborted === true || isAbortError(error) || /** @type {{ code?: unknown }} */ (error)?.code === "WEB_ABORTED") {
|
|
44
|
+
throw /** @type {Error} */ (/** @type {unknown} */ (error));
|
|
45
|
+
}
|
|
46
|
+
throw errors.provider(`web search credential resolution failed: ${String(error)}`, "WEB_PROVIDER_ERROR", error);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* True for a fetch/`AbortSignal` abort.
|
|
52
|
+
* @param {unknown} error - the thrown value.
|
|
53
|
+
* @returns {boolean} whether the failure is an abort.
|
|
54
|
+
*/
|
|
55
|
+
export function isAbortError(error) {
|
|
56
|
+
return error !== null && typeof error === "object" && /** @type {{ name?: unknown }} */ (error).name === "AbortError";
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* POST one JSON body and return the raw response. Non-2xx responses are
|
|
61
|
+
* returned (not thrown): each engine maps its own status codes to guidance.
|
|
62
|
+
* @param {string} url - the endpoint.
|
|
63
|
+
* @param {{ headers: Record<string, string>, body: unknown, signal?: AbortSignal }} request - request parts.
|
|
64
|
+
* @param {{ fetch: typeof fetch, errors: { provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error } }} deps - transport and error deps.
|
|
65
|
+
* @returns {Promise<Response>} the raw response.
|
|
66
|
+
*/
|
|
67
|
+
export async function postJson(url, request, deps) {
|
|
68
|
+
const { fetch, errors } = deps;
|
|
69
|
+
throwIfAborted(request.signal, errors);
|
|
70
|
+
try {
|
|
71
|
+
return await fetch(url, {
|
|
72
|
+
method: "POST",
|
|
73
|
+
redirect: "error",
|
|
74
|
+
headers: request.headers,
|
|
75
|
+
body: JSON.stringify(request.body),
|
|
76
|
+
...(request.signal !== undefined ? { signal: request.signal } : {})
|
|
77
|
+
});
|
|
78
|
+
} catch (error) {
|
|
79
|
+
if (request.signal?.aborted === true || isAbortError(error)) throw errors.aborted(request.signal?.aborted === true ? request.signal.reason : error);
|
|
80
|
+
throw errors.provider(`web search request failed: ${String(error)}`, "WEB_PROVIDER_ERROR", error);
|
|
81
|
+
}
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Parse a response body as JSON, classifying aborts and parse failures.
|
|
86
|
+
* @param {Response} response - the raw response.
|
|
87
|
+
* @param {AbortSignal | undefined} signal - the caller's cancellation signal.
|
|
88
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error }} errors - error factory pair.
|
|
89
|
+
* @returns {Promise<unknown>} the parsed payload.
|
|
90
|
+
*/
|
|
91
|
+
export async function readJson(response, signal, errors) {
|
|
92
|
+
throwIfAborted(signal, errors);
|
|
93
|
+
try {
|
|
94
|
+
return await response.json();
|
|
95
|
+
} catch (error) {
|
|
96
|
+
if (signal?.aborted === true || isAbortError(error)) throw errors.aborted(signal?.aborted === true ? signal.reason : error);
|
|
97
|
+
throw errors.provider(`web search returned an unprocessable response body: ${String(error)}`, "WEB_PROVIDER_ERROR", error);
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
|
|
101
|
+
/**
|
|
102
|
+
* Build the missing-API-key failure every engine raises before dispatch.
|
|
103
|
+
* @param {string} label - the engine's display name in the message.
|
|
104
|
+
* @param {string} envName - the default credential reference.
|
|
105
|
+
* @param {string} literalField - the literal-key config field.
|
|
106
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error }} errors - error factory pair.
|
|
107
|
+
* @returns {Error} the coded error.
|
|
108
|
+
*/
|
|
109
|
+
export function missingKeyError(label, envName, literalField, errors) {
|
|
110
|
+
return errors.provider(`${label} has no API key; store one through Settings > 第三方搜索 (enter the key and save), export it as ${envName} in the launching environment, or set a literal "${literalField}" in the web-search config. Alternatively, turn off third-party search in Settings > 第三方搜索 to use DSH's built-in DeepSeek search`, "WEB_PROVIDER_CREDENTIAL_MISSING");
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Read a non-2xx body for an error message, as a `: <text>` suffix ("" when
|
|
115
|
+
* the body is unreadable or carries no message).
|
|
116
|
+
* @param {Response} response - the raw non-2xx response.
|
|
117
|
+
* @param {AbortSignal | undefined} signal - the caller's cancellation signal.
|
|
118
|
+
* @param {{ provider: (m: string, c?: string, cause?: unknown) => Error, aborted: (cause?: unknown) => Error }} errors - error factory pair.
|
|
119
|
+
* @param {(payload: any) => unknown} pick - extracts the engine's message field.
|
|
120
|
+
* @returns {Promise<string>} the detail suffix.
|
|
121
|
+
*/
|
|
122
|
+
export async function readErrorDetail(response, signal, errors, pick) {
|
|
123
|
+
try {
|
|
124
|
+
const text = pick(await readJson(response, signal, errors));
|
|
125
|
+
return text != null && String(text).length > 0 ? `: ${String(text)}` : "";
|
|
126
|
+
} catch {
|
|
127
|
+
return "";
|
|
128
|
+
}
|
|
129
|
+
}
|
package/lib/index.js
ADDED
|
@@ -0,0 +1,123 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* dsh-web-search — host half.
|
|
3
|
+
*
|
|
4
|
+
* Registers ONE switchable third-party search provider (`web-search`) into the
|
|
5
|
+
* `ctx.web` seam and the durable `web-search` settings form behind it. Engines
|
|
6
|
+
* are Tavily (free tier) and model-native web search (MiMo); DSH's own
|
|
7
|
+
* DeepSeek search stays in charge whenever the plugin's master switch is off.
|
|
8
|
+
*
|
|
9
|
+
* The bundle patch layer makes the provider the default; the client switch
|
|
10
|
+
* either clears that user-layer override (on) or writes a built-in DeepSeek
|
|
11
|
+
* provider group back (off), so the plugin id never has to persist in user
|
|
12
|
+
* settings. See `patch.yml` and `lib/client.js`.
|
|
13
|
+
*
|
|
14
|
+
* Runtime imports explicitly include the public web and launch-environment
|
|
15
|
+
* contracts as bundle-local dependencies, so a `link:` installation resolves
|
|
16
|
+
* the same APIs without reaching through the Host's private dependency tree.
|
|
17
|
+
* Errors are real `WebError`/`HarnessError` instances for routing on `code`.
|
|
18
|
+
*/
|
|
19
|
+
import z from "@deepseek-ai/schemastery";
|
|
20
|
+
import { launchEnvironmentOf } from "@deepseek-ai/dsh-launch-environment";
|
|
21
|
+
import { webErrors as errors } from "./errors.js";
|
|
22
|
+
import { DispatchProvider, WEB_SEARCH_PROVIDER_ID } from "./dispatch.js";
|
|
23
|
+
import { searchTavily } from "./engines/tavily.js";
|
|
24
|
+
import { searchModel } from "./engines/model-native.js";
|
|
25
|
+
import { normalizeSection, DEFAULTS } from "./options.js";
|
|
26
|
+
|
|
27
|
+
/** Stable Cordis plugin name; also the provider id and settings namespace. */
|
|
28
|
+
const name = "web-search";
|
|
29
|
+
|
|
30
|
+
/** The web seam this provider registers into. */
|
|
31
|
+
const inject = ["web"];
|
|
32
|
+
|
|
33
|
+
/** Settings namespace owned by this plugin (key of its settings card). */
|
|
34
|
+
const WEB_SEARCH_SETTINGS_NAMESPACE = "web-search";
|
|
35
|
+
|
|
36
|
+
/** Default credential references per engine (environment-variable names). */
|
|
37
|
+
const DEFAULT_KEY_REFS = {
|
|
38
|
+
tavily: "TAVILY_API_KEY",
|
|
39
|
+
model: "MIMO1_API_KEY"
|
|
40
|
+
};
|
|
41
|
+
|
|
42
|
+
/**
|
|
43
|
+
* Durable settings schema: engine selection, per-engine options, and the
|
|
44
|
+
* remembered built-in group the client restores when the master switch is
|
|
45
|
+
* turned off. Every field is volatile: the settings form only edits volatile
|
|
46
|
+
* fields, and each read goes through the live reference, so a saved switch
|
|
47
|
+
* reaches the running provider without a remount.
|
|
48
|
+
*
|
|
49
|
+
* `deepseek` stays in the engine union as a deprecated value: dropping it would
|
|
50
|
+
* make a saved `engine: deepseek` fail schema validation and prevent the plugin
|
|
51
|
+
* from loading, leaving no UI to turn the switch off. Normalization maps it to
|
|
52
|
+
* Tavily.
|
|
53
|
+
*/
|
|
54
|
+
const Config = z.object({
|
|
55
|
+
engine: z.union(["tavily", "model", "deepseek"]).default(DEFAULTS.engine).volatile(),
|
|
56
|
+
tavilyApiKey: z.string().role("secret").volatile(),
|
|
57
|
+
tavilyApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_REFS.tavily).volatile(),
|
|
58
|
+
tavilySearchDepth: z.union(["basic", "advanced"]).default(DEFAULTS.tavilySearchDepth).volatile(),
|
|
59
|
+
modelApiKey: z.string().role("secret").volatile(),
|
|
60
|
+
modelApiKeyEnv: z.string().role("credential-ref").default(DEFAULT_KEY_REFS.model).volatile(),
|
|
61
|
+
modelBaseUrl: z.string().default(DEFAULTS.modelBaseUrl).volatile(),
|
|
62
|
+
modelId: z.string().default(DEFAULTS.modelId).volatile(),
|
|
63
|
+
builtin: z.union(["messages", "api"]).default("messages").volatile()
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Build one engine's credential resolver: the credentials service first (the
|
|
68
|
+
* reference is the plain environment-variable name — `credentialRef` brands at
|
|
69
|
+
* type level only), the launching environment second.
|
|
70
|
+
* @param {object} ctx - plugin context supplying the credential plane.
|
|
71
|
+
* @param {() => string} envName - the credential reference for the next operation.
|
|
72
|
+
* @returns {() => Promise<string | undefined>} the resolver.
|
|
73
|
+
*/
|
|
74
|
+
function makeKeyResolver(ctx, envName) {
|
|
75
|
+
return async () => {
|
|
76
|
+
const ref = envName();
|
|
77
|
+
const credentials = ctx.get("credentials");
|
|
78
|
+
if (credentials !== undefined) return (await credentials.resolve(ref))?.value;
|
|
79
|
+
const ambient = launchEnvironmentOf(ctx).get(ref);
|
|
80
|
+
return ambient !== undefined && ambient.value.length > 0 ? ambient.value : undefined;
|
|
81
|
+
};
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Mount the switchable search provider and its settings form.
|
|
86
|
+
* @param {object} ctx - Host plugin context.
|
|
87
|
+
* @param {object} config - the resolved composition entry; volatile fields are
|
|
88
|
+
* live references, so `current()` snapshots the section per operation.
|
|
89
|
+
*/
|
|
90
|
+
function apply(ctx, config) {
|
|
91
|
+
/* Volatile Config fields arrive as readonly references (`Ref.get()`); the
|
|
92
|
+
* loader commits a settings write into them without remounting this plugin,
|
|
93
|
+
* which is what keeps the engine switch restart-free. */
|
|
94
|
+
const current = () => Object.fromEntries(Object.keys(Config.dict).map((field) => [field, config[field].get()]));
|
|
95
|
+
const resolveKeys = {
|
|
96
|
+
tavily: makeKeyResolver(ctx, () => config.tavilyApiKeyEnv.get() ?? DEFAULT_KEY_REFS.tavily),
|
|
97
|
+
model: makeKeyResolver(ctx, () => config.modelApiKeyEnv.get() ?? DEFAULT_KEY_REFS.model)
|
|
98
|
+
};
|
|
99
|
+
const options = () => normalizeSection(current(), resolveKeys);
|
|
100
|
+
/* The bundle renders its own configuration page (plugins.row.config), so the
|
|
101
|
+
* automatically generated config page for this entry is suppressed. */
|
|
102
|
+
ctx.inject(["settings"], (child) => {
|
|
103
|
+
child.effect(() => child.settings.configure({ auto: false }, ctx.fiber));
|
|
104
|
+
});
|
|
105
|
+
const engines = {
|
|
106
|
+
tavily: searchTavily,
|
|
107
|
+
model: searchModel
|
|
108
|
+
};
|
|
109
|
+
ctx.web.registerSearchProvider(new DispatchProvider(options, engines, {
|
|
110
|
+
fetch: (input, init) => globalThis.fetch(input, init),
|
|
111
|
+
errors
|
|
112
|
+
}));
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export {
|
|
116
|
+
apply,
|
|
117
|
+
name,
|
|
118
|
+
inject,
|
|
119
|
+
Config,
|
|
120
|
+
WEB_SEARCH_PROVIDER_ID,
|
|
121
|
+
WEB_SEARCH_SETTINGS_NAMESPACE,
|
|
122
|
+
DEFAULT_KEY_REFS
|
|
123
|
+
};
|
package/lib/options.js
ADDED
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Settings-section normalization and per-engine usability checks.
|
|
3
|
+
*
|
|
4
|
+
* Pure module (no `@deepseek-ai/*` imports) so `node --test` can run it
|
|
5
|
+
* standalone. The Host half supplies credential resolvers; a resolver's
|
|
6
|
+
* presence is what lets `available()` stay synchronous and network-free while
|
|
7
|
+
* still permitting an operation-time `WEB_PROVIDER_CREDENTIAL_MISSING`.
|
|
8
|
+
*
|
|
9
|
+
* The deprecated `engine: "deepseek"` value (from the 0.3.x official engine)
|
|
10
|
+
* normalizes to Tavily instead of failing the whole plugin: the settings schema
|
|
11
|
+
* still accepts it so the plugin keeps loading and the master switch stays
|
|
12
|
+
* reachable.
|
|
13
|
+
*/
|
|
14
|
+
|
|
15
|
+
/** Engine ids offered by the settings card, in display order. */
|
|
16
|
+
export const ENGINES = ["tavily", "model"];
|
|
17
|
+
|
|
18
|
+
/** Schema defaults, mirrored here so normalization also holds outside the seam. */
|
|
19
|
+
export const DEFAULTS = {
|
|
20
|
+
engine: "tavily",
|
|
21
|
+
tavilySearchDepth: "basic",
|
|
22
|
+
modelBaseUrl: "https://api.xiaomimimo.com/v1",
|
|
23
|
+
modelId: "mimo-v2.6-flash"
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/** Optional-secret field pairs: literal key first, resolver as the fallback. */
|
|
27
|
+
function keySource(section, literal, resolveKey) {
|
|
28
|
+
const apiKey = typeof section?.[literal] === "string" && section[literal].length > 0 ? section[literal] : undefined;
|
|
29
|
+
return { ...apiKey !== undefined ? { apiKey } : {}, resolveKey };
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* Normalize one resolved settings section into per-engine options.
|
|
34
|
+
* @param {Record<string, unknown>} [section] - the resolved `web-search` section.
|
|
35
|
+
* @param {{ tavily?: () => Promise<string | undefined>, model?: () => Promise<string | undefined> }} [resolveKeys] - credential resolvers.
|
|
36
|
+
* @returns {{ engine: string, tavily: object, model: object }} normalized options.
|
|
37
|
+
*/
|
|
38
|
+
export function normalizeSection(section = {}, resolveKeys = {}) {
|
|
39
|
+
const engine = ENGINES.includes(/** @type {string} */ (section?.engine)) ? /** @type {string} */ (section.engine) : DEFAULTS.engine;
|
|
40
|
+
return {
|
|
41
|
+
engine,
|
|
42
|
+
tavily: {
|
|
43
|
+
...keySource(section, "tavilyApiKey", resolveKeys.tavily),
|
|
44
|
+
searchDepth: section?.tavilySearchDepth === "advanced" ? "advanced" : DEFAULTS.tavilySearchDepth
|
|
45
|
+
},
|
|
46
|
+
model: {
|
|
47
|
+
...keySource(section, "modelApiKey", resolveKeys.model),
|
|
48
|
+
baseURL: typeof section?.modelBaseUrl === "string" && section.modelBaseUrl.length > 0 ? /** @type {string} */ (section.modelBaseUrl) : DEFAULTS.modelBaseUrl,
|
|
49
|
+
modelId: typeof section?.modelId === "string" && section.modelId.length > 0 ? /** @type {string} */ (section.modelId) : DEFAULTS.modelId
|
|
50
|
+
}
|
|
51
|
+
};
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** Whether an engine has any key source (literal or resolver) — sync, no I/O. */
|
|
55
|
+
function hasKeySource(options) {
|
|
56
|
+
return (options.apiKey?.length ?? 0) > 0 || typeof options.resolveKey === "function";
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* Cheap local usability check for one engine (the seam's `available()`
|
|
61
|
+
* semantics): synchronous, no network calls.
|
|
62
|
+
* @param {string} engine - the engine id under test.
|
|
63
|
+
* @param {{ tavily: object, model: object }} options - normalized options.
|
|
64
|
+
* @returns {boolean} whether the engine can be selected right now.
|
|
65
|
+
*/
|
|
66
|
+
export function engineAvailable(engine, options) {
|
|
67
|
+
switch (engine) {
|
|
68
|
+
case "tavily":
|
|
69
|
+
return hasKeySource(options.tavily);
|
|
70
|
+
case "model":
|
|
71
|
+
return hasKeySource(options.model) && URL.canParse(options.model.baseURL) && options.model.modelId.length > 0;
|
|
72
|
+
default:
|
|
73
|
+
return false;
|
|
74
|
+
}
|
|
75
|
+
}
|