@fffangchenghao/dsh-web-search 0.19.2 → 0.20.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.
Files changed (60) hide show
  1. package/CHANGELOG.md +160 -0
  2. package/README.md +195 -34
  3. package/README.zh-CN.md +171 -34
  4. package/SECURITY.md +42 -7
  5. package/client.js +131 -9
  6. package/docs/store-evidence.md +10 -5
  7. package/lib/advanced-search.d.ts +107 -0
  8. package/lib/advanced-search.js +255 -0
  9. package/lib/bridge.d.ts +16 -0
  10. package/lib/bridge.js +160 -0
  11. package/lib/cache.d.ts +11 -4
  12. package/lib/cache.js +9 -5
  13. package/lib/config.d.ts +19 -3
  14. package/lib/config.js +24 -0
  15. package/lib/domain-tool.d.ts +5 -0
  16. package/lib/domain-tool.js +45 -6
  17. package/lib/engine-test.d.ts +116 -0
  18. package/lib/engine-test.js +256 -0
  19. package/lib/engines.d.ts +11 -1
  20. package/lib/engines.js +122 -20
  21. package/lib/errors.d.ts +16 -2
  22. package/lib/errors.js +40 -1
  23. package/lib/index.d.ts +24 -2
  24. package/lib/index.js +304 -20
  25. package/lib/inject.d.ts +43 -0
  26. package/lib/inject.js +1 -0
  27. package/lib/markdown.js +18 -1
  28. package/lib/mirrors.d.ts +23 -0
  29. package/lib/mirrors.js +69 -0
  30. package/lib/official-feed.d.ts +114 -0
  31. package/lib/official-feed.js +288 -0
  32. package/lib/official-support.d.ts +74 -0
  33. package/lib/official-support.js +134 -0
  34. package/lib/platform-tool.d.ts +77 -0
  35. package/lib/platform-tool.js +173 -0
  36. package/lib/platforms.d.ts +178 -0
  37. package/lib/platforms.js +1035 -0
  38. package/lib/query-router.d.ts +29 -0
  39. package/lib/query-router.js +58 -0
  40. package/lib/read-page.js +2 -1
  41. package/lib/research-cache.d.ts +115 -0
  42. package/lib/research-cache.js +275 -0
  43. package/lib/research.d.ts +45 -4
  44. package/lib/research.js +505 -22
  45. package/lib/search-many.d.ts +7 -1
  46. package/lib/search-many.js +7 -2
  47. package/lib/system-prompt.d.ts +27 -0
  48. package/lib/system-prompt.js +50 -0
  49. package/lib/tool-suite.d.ts +97 -0
  50. package/lib/tool-suite.js +224 -0
  51. package/lib/transport.d.ts +33 -2
  52. package/lib/transport.js +42 -9
  53. package/lib/types.d.ts +20 -0
  54. package/lib/types.js +9 -1
  55. package/lib/untrusted.d.ts +33 -0
  56. package/lib/untrusted.js +42 -0
  57. package/lib/verticals.d.ts +3 -1
  58. package/lib/verticals.js +26 -7
  59. package/package.json +5 -3
  60. package/skills/dsh-web-search/SKILL.md +21 -6
package/lib/bridge.js ADDED
@@ -0,0 +1,160 @@
1
+ import { runEngineTestValue } from "./engine-test.js";
2
+ import { HOSTS } from "./engines.js";
3
+ /** Route prefix the client fetches; kept stable for the shipped settings page. */
4
+ export const ENGINE_TEST_BRIDGE_PATH = '/api/dsh-web-search/engine-test';
5
+ /** Largest request body the bridge will read. */
6
+ const MAX_BODY_BYTES = 16 * 1024;
7
+ /** Whether an address is loopback. */
8
+ function isLoopback(address) {
9
+ return address === '127.0.0.1' || address === '::1' || address === '::ffff:127.0.0.1';
10
+ }
11
+ /** Parse a Host header without throwing. */
12
+ function hostOf(value) {
13
+ if (typeof value !== 'string' || value.length === 0)
14
+ return undefined;
15
+ try {
16
+ return new URL(`http://${value}`).host;
17
+ }
18
+ catch {
19
+ return undefined;
20
+ }
21
+ }
22
+ /**
23
+ * Refuse cross-site and non-loopback callers.
24
+ *
25
+ * The Host already authenticates its own `/api` surface; this guard keeps the
26
+ * plugin from widening it. A remote settings page therefore cannot use the
27
+ * button, but it also cannot reach a search runner with no authentication.
28
+ */
29
+ function isAllowed(request) {
30
+ if (!isLoopback(request.socket.remoteAddress))
31
+ return false;
32
+ if (request.headers['sec-fetch-site'] === 'cross-site')
33
+ return false;
34
+ const origin = request.headers.origin;
35
+ if (origin !== undefined) {
36
+ try {
37
+ if (new URL(origin).host !== hostOf(request.headers.host))
38
+ return false;
39
+ }
40
+ catch {
41
+ return false;
42
+ }
43
+ }
44
+ return true;
45
+ }
46
+ /** Send one JSON response. */
47
+ function writeJson(response, status, body) {
48
+ const payload = JSON.stringify(body);
49
+ response.writeHead(status, {
50
+ 'content-type': 'application/json; charset=utf-8',
51
+ 'cache-control': 'no-store',
52
+ 'referrer-policy': 'no-referrer',
53
+ });
54
+ response.end(payload);
55
+ }
56
+ /** Read a bounded JSON body. */
57
+ async function readJson(request) {
58
+ const chunks = [];
59
+ let size = 0;
60
+ for await (const chunk of request) {
61
+ const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
62
+ size += buffer.length;
63
+ if (size > MAX_BODY_BYTES)
64
+ return undefined;
65
+ chunks.push(buffer);
66
+ }
67
+ if (size === 0)
68
+ return {};
69
+ try {
70
+ return JSON.parse(Buffer.concat(chunks).toString('utf8'));
71
+ }
72
+ catch {
73
+ return undefined;
74
+ }
75
+ }
76
+ /** Parse and validate the request body. */
77
+ function parseBody(body) {
78
+ if (typeof body !== 'object' || body === null || Array.isArray(body)) {
79
+ throw new Error('body must be a JSON object');
80
+ }
81
+ const record = body;
82
+ const engine = record['engine'];
83
+ const query = record['query'];
84
+ if (engine !== undefined && (typeof engine !== 'string' || engine.trim().length === 0)) {
85
+ throw new Error('engine must be a non-empty string');
86
+ }
87
+ if (query !== undefined && (typeof query !== 'string' || query.trim().length === 0)) {
88
+ throw new Error('query must be a non-empty string');
89
+ }
90
+ if (engine !== undefined && !HOSTS.some((host) => host.id === engine.trim())) {
91
+ throw new Error(`unknown engine ${JSON.stringify(engine)}`);
92
+ }
93
+ return {
94
+ ...(engine === undefined ? {} : { engine: engine.trim() }),
95
+ ...(query === undefined ? {} : { query: query.trim() }),
96
+ };
97
+ }
98
+ /**
99
+ * Register the engine-test endpoint.
100
+ * @param ctx - injectable plugin context.
101
+ * @param runTest - engine test runner shared with the model tool.
102
+ * @returns a disposer, or `undefined` when the host has no injectable server.
103
+ */
104
+ export function registerEngineTestBridge(ctx, runTest) {
105
+ if (typeof ctx.inject !== 'function')
106
+ return undefined;
107
+ try {
108
+ ctx.inject(['webServer'], (services) => {
109
+ const webServer = services?.webServer;
110
+ if (webServer === undefined || typeof webServer.register !== 'function')
111
+ return;
112
+ const mount = () => {
113
+ const off = webServer.register({
114
+ kind: 'exact',
115
+ path: ENGINE_TEST_BRIDGE_PATH,
116
+ async handler(request, response) {
117
+ if (request.method !== 'POST') {
118
+ writeJson(response, 405, { ok: false, code: 'method-not-allowed', message: 'POST only' });
119
+ return;
120
+ }
121
+ if (!isAllowed(request)) {
122
+ writeJson(response, 403, { ok: false, code: 'forbidden', message: 'loopback settings only' });
123
+ return;
124
+ }
125
+ const body = await readJson(request);
126
+ if (body === undefined) {
127
+ writeJson(response, 400, { ok: false, code: 'invalid-json', message: 'malformed or oversized JSON body' });
128
+ return;
129
+ }
130
+ try {
131
+ const parsed = parseBody(body);
132
+ const query = parsed.query ?? 'DeepSeek Harness';
133
+ const engines = parsed.engine === undefined ? HOSTS.map((host) => host.id) : [parsed.engine];
134
+ const result = await runEngineTestValue(runTest, engines, query);
135
+ writeJson(response, 200, { ok: true, value: result });
136
+ }
137
+ catch (error) {
138
+ writeJson(response, 400, {
139
+ ok: false,
140
+ code: 'test-failed',
141
+ message: error instanceof Error ? error.message : String(error),
142
+ });
143
+ }
144
+ },
145
+ });
146
+ return typeof off === 'function' ? off : undefined;
147
+ };
148
+ if (typeof services.effect === 'function')
149
+ services.effect(mount);
150
+ else
151
+ mount();
152
+ });
153
+ return () => {
154
+ // The injected disposer owns the route; nothing else to release here.
155
+ };
156
+ }
157
+ catch {
158
+ return undefined;
159
+ }
160
+ }
package/lib/cache.d.ts CHANGED
@@ -44,6 +44,12 @@ export interface CacheKeyParts {
44
44
  engines: string[];
45
45
  /** Active publication window; omitted and `off` share a key. */
46
46
  timeRange?: TimeRange;
47
+ /** Content-filter level; omitted and `off` share a key. */
48
+ safeSearch?: string;
49
+ /** Fallback policy; omitted and the full policy share a key. */
50
+ fallbackOn?: readonly string[];
51
+ /** Domain blocklist; omitted and an empty list share a key. */
52
+ blockedDomains?: readonly string[];
47
53
  }
48
54
  /**
49
55
  * Build the cache key for one search request.
@@ -52,10 +58,11 @@ export interface CacheKeyParts {
52
58
  * `' PostgreSQL Replication '` and `'postgresql replication'` share an
53
59
  * entry. Engine order never matters because the ids are sorted; every other
54
60
  * field is positional, so differing `limit`, `wait`, `lead`, `timeRange` or
55
- * engine set yields a different key. `timeRange` is appended only when it is
56
- * active, which keeps the key for an unfiltered search unchanged. The query is
57
- * last so a query containing the field separator cannot collide with a
58
- * different request's prefix.
61
+ * engine set yields a different key. `timeRange`, `safeSearch`, `fallbackOn`
62
+ * and `blockedDomains` are appended only when they are non-default, which keeps
63
+ * the key for an ordinary search unchanged. The query is last so a query
64
+ * containing the field separator cannot collide with a different request's
65
+ * prefix.
59
66
  *
60
67
  * @param parts - the logical request.
61
68
  * @returns a deterministic, comparison-safe cache key.
package/lib/cache.js CHANGED
@@ -12,10 +12,11 @@ const DEFAULT_PERSIST_THROTTLE_MS = 2_000;
12
12
  * `' PostgreSQL Replication '` and `'postgresql replication'` share an
13
13
  * entry. Engine order never matters because the ids are sorted; every other
14
14
  * field is positional, so differing `limit`, `wait`, `lead`, `timeRange` or
15
- * engine set yields a different key. `timeRange` is appended only when it is
16
- * active, which keeps the key for an unfiltered search unchanged. The query is
17
- * last so a query containing the field separator cannot collide with a
18
- * different request's prefix.
15
+ * engine set yields a different key. `timeRange`, `safeSearch`, `fallbackOn`
16
+ * and `blockedDomains` are appended only when they are non-default, which keeps
17
+ * the key for an ordinary search unchanged. The query is last so a query
18
+ * containing the field separator cannot collide with a different request's
19
+ * prefix.
19
20
  *
20
21
  * @param parts - the logical request.
21
22
  * @returns a deterministic, comparison-safe cache key.
@@ -24,7 +25,10 @@ export function cacheKey(parts) {
24
25
  const query = parts.query.trim().toLowerCase().replace(/\s+/gu, ' ');
25
26
  const engines = [...parts.engines].sort().join('+');
26
27
  const window = parts.timeRange === undefined || parts.timeRange === 'off' ? '' : `${parts.timeRange}|`;
27
- return `${parts.lead}|${parts.wait}|${parts.limit}|${engines}|${window}${query}`;
28
+ const safe = parts.safeSearch === undefined || parts.safeSearch === 'off' ? '' : `safe=${parts.safeSearch}|`;
29
+ const fallback = parts.fallbackOn === undefined ? '' : `fallback=${[...parts.fallbackOn].sort().join(',')}|`;
30
+ const blocked = parts.blockedDomains === undefined ? '' : `blocked=${[...parts.blockedDomains].sort().join(',')}|`;
31
+ return `${parts.lead}|${parts.wait}|${parts.limit}|${engines}|${window}${safe}${fallback}${blocked}${query}`;
28
32
  }
29
33
  /**
30
34
  * Copy the array and each source.
package/lib/config.d.ts CHANGED
@@ -21,12 +21,12 @@
21
21
  */
22
22
  import z from '@deepseek-ai/schemastery';
23
23
  import type { RenderMode } from './render.ts';
24
- import type { RankOptions, TimeRange, WaitPolicy } from './types.ts';
24
+ import type { FailureKind, RankOptions, SafeSearch, TimeRange, WaitPolicy } from './types.ts';
25
25
  /** Schema of the plugin's configuration section. */
26
26
  export declare const Config: z<Schemastery.ObjectS<NoInfer<{
27
27
  hosts: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
28
28
  timeoutMs: z<number, number, "volatile-defined">;
29
- fetchFormat: z<"markdown" | "text", "markdown" | "text", "volatile-defined">;
29
+ fetchFormat: z<"text" | "markdown", "text" | "markdown", "volatile-defined">;
30
30
  fetchMaxLength: z<number, number, "volatile-defined">;
31
31
  renderJs: z<"off" | "auto" | "always", "off" | "auto" | "always", "volatile-defined">;
32
32
  renderTimeoutMs: z<number, number, "volatile-defined">;
@@ -39,6 +39,9 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
39
39
  freshnessBoost: z<number, number, "volatile-defined">;
40
40
  freshnessDays: z<number, number, "volatile-defined">;
41
41
  timeRange: z<"off" | "day" | "week" | "month" | "year", "off" | "day" | "week" | "month" | "year", "volatile-defined">;
42
+ blockedDomains: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
43
+ safeSearch: z<"off" | "moderate" | "strict", "off" | "moderate" | "strict", "volatile-defined">;
44
+ fallbackOn: z<NoInfer<("quota" | "auth" | "bot-wall" | "transient" | "invalid-response" | "unknown")[]>, NoInfer<("quota" | "auth" | "bot-wall" | "transient" | "invalid-response" | "unknown")[]>, "volatile-defined">;
42
45
  cacheTtlMs: z<number, number, "volatile-defined">;
43
46
  cacheEntries: z<number, number, "volatile-defined">;
44
47
  cachePersist: z<boolean, boolean, "volatile-defined">;
@@ -50,10 +53,11 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
50
53
  domainSources: z<NoInfer<string | string[]>, NoInfer<string | string[]>, "volatile-defined">;
51
54
  domainLimit: z<number, number, "volatile-defined">;
52
55
  domainTimeoutMs: z<number, number, "volatile-defined">;
56
+ toolSurface: z<"unified" | "legacy", "unified" | "legacy", "volatile-defined">;
53
57
  }>>, Schemastery.ObjectT<NoInfer<{
54
58
  hosts: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
55
59
  timeoutMs: z<number, number, "volatile-defined">;
56
- fetchFormat: z<"markdown" | "text", "markdown" | "text", "volatile-defined">;
60
+ fetchFormat: z<"text" | "markdown", "text" | "markdown", "volatile-defined">;
57
61
  fetchMaxLength: z<number, number, "volatile-defined">;
58
62
  renderJs: z<"off" | "auto" | "always", "off" | "auto" | "always", "volatile-defined">;
59
63
  renderTimeoutMs: z<number, number, "volatile-defined">;
@@ -66,6 +70,9 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
66
70
  freshnessBoost: z<number, number, "volatile-defined">;
67
71
  freshnessDays: z<number, number, "volatile-defined">;
68
72
  timeRange: z<"off" | "day" | "week" | "month" | "year", "off" | "day" | "week" | "month" | "year", "volatile-defined">;
73
+ blockedDomains: z<NoInfer<string[]>, NoInfer<string[]>, "volatile-defined">;
74
+ safeSearch: z<"off" | "moderate" | "strict", "off" | "moderate" | "strict", "volatile-defined">;
75
+ fallbackOn: z<NoInfer<("quota" | "auth" | "bot-wall" | "transient" | "invalid-response" | "unknown")[]>, NoInfer<("quota" | "auth" | "bot-wall" | "transient" | "invalid-response" | "unknown")[]>, "volatile-defined">;
69
76
  cacheTtlMs: z<number, number, "volatile-defined">;
70
77
  cacheEntries: z<number, number, "volatile-defined">;
71
78
  cachePersist: z<boolean, boolean, "volatile-defined">;
@@ -77,6 +84,7 @@ export declare const Config: z<Schemastery.ObjectS<NoInfer<{
77
84
  domainSources: z<NoInfer<string | string[]>, NoInfer<string | string[]>, "volatile-defined">;
78
85
  domainLimit: z<number, number, "volatile-defined">;
79
86
  domainTimeoutMs: z<number, number, "volatile-defined">;
87
+ toolSurface: z<"unified" | "legacy", "unified" | "legacy", "volatile-defined">;
80
88
  }>>, "plain">;
81
89
  /** What the schema resolves a field to: a live reference, not the value. */
82
90
  export interface LiveRef<T> {
@@ -121,6 +129,12 @@ export interface ResolvedConfig {
121
129
  wait: WaitPolicy;
122
130
  /** Rolling publication window; `off` disables time filtering. */
123
131
  timeRange: TimeRange;
132
+ /** Domains the caller never wants in a result list. */
133
+ blockedDomains: string[];
134
+ /** Content-filter level forwarded to engines that support it. */
135
+ safeSearch: SafeSearch;
136
+ /** Failure classes that may trigger the fallback tier. */
137
+ fallbackOn: FailureKind[];
124
138
  /** AnySearch credential, or an empty string for anonymous access. */
125
139
  anysearchApiKey: string;
126
140
  /** AnySearch vertical domain, or an empty string for the open web. */
@@ -145,6 +159,8 @@ export interface ResolvedConfig {
145
159
  domainLimit: number;
146
160
  /** Per-source deadline for vertical requests. */
147
161
  domainTimeoutMs: number;
162
+ /** Whether the model sees one unified tool or the legacy eight names. */
163
+ toolSurface: 'unified' | 'legacy';
148
164
  }
149
165
  /**
150
166
  * Normalise the validated config into the shape the engine layer consumes.
package/lib/config.js CHANGED
@@ -77,6 +77,21 @@ export const Config = z.object({
77
77
  .default('off')
78
78
  .description('只保留多久以内发布的结果:off 不限时间、day 最近 24 小时、week 最近 7 天、month 最近 30 天、year 最近 1 年。开启后只返回窗口内发布的结果;若一条带日期的都没落进窗口,会退回无日期的结果避免空手;不确定保持 off。')
79
79
  .volatile(),
80
+ blockedDomains: z
81
+ .array(z.string())
82
+ .default([])
83
+ .description('永远不要出现在结果里的网站(如 spam.example、ads.example),多个用逗号分隔;子域名也会被排除。留空表示不屏蔽任何网站。')
84
+ .volatile(),
85
+ safeSearch: z
86
+ .union(['off', 'moderate', 'strict'])
87
+ .default('off')
88
+ .description('内置引擎的安全搜索级别:off 保持引擎默认,moderate 过滤成人内容,strict 使用最严格过滤。只影响 Bing 和 DuckDuckGo;其它引擎没有对应参数。')
89
+ .volatile(),
90
+ fallbackOn: z
91
+ .array(z.union(['quota', 'auth', 'bot-wall', 'transient', 'invalid-response', 'unknown']))
92
+ .default(['quota', 'auth', 'bot-wall', 'transient', 'invalid-response', 'unknown'])
93
+ .description('哪些失败允许切换到备用引擎:默认全部允许,搜索不会因为一个引擎失败而中断。取消某一类后,遇到该类失败会直接报告错误,不再换引擎;留空表示任何失败都不回退。')
94
+ .volatile(),
80
95
  cacheTtlMs: z.natural().default(600000).description('同一问题多久内复用上次结果(缓存,即存一份备用),毫秒。想早点看到新内容就调小;保持 600000(10 分钟)即可。').volatile(),
81
96
  cacheEntries: z.natural().default(100).description('最多存多少条旧结果备用(缓存,即存起来省得重复查)。存满后先丢最久没用的;一般保持 100 即可。').volatile(),
82
97
  cachePersist: z
@@ -106,6 +121,11 @@ export const Config = z.object({
106
121
  .volatile(),
107
122
  domainLimit: z.natural().min(1).max(20).default(5).description('domain_search 一次最多返回几条(1-20);默认 5 条,想多看可调到 10。').volatile(),
108
123
  domainTimeoutMs: z.natural().min(500).default(8000).description('每个专用源最多等多久(毫秒);网络慢可加到 15000,平时 8000 即可。').volatile(),
124
+ toolSurface: z
125
+ .union(['unified', 'legacy'])
126
+ .default('unified')
127
+ .description('模型工具面:unified 只注册一个 web_tools,用 action 选择 search_many/domain_search/research 等能力(推荐,省上下文);legacy 保留原来的八个独立工具名,供旧提示词兼容。修改后需要重启插件。')
128
+ .volatile(),
109
129
  });
110
130
  /**
111
131
  * Read one field, whichever shape it arrived in.
@@ -165,11 +185,15 @@ export function resolveConfig(config, callLimit) {
165
185
  limit,
166
186
  wait: settings.wait,
167
187
  timeRange: settings.timeRange,
188
+ blockedDomains: settings.blockedDomains.map((domain) => domain.trim()).filter((domain) => domain.length > 0),
189
+ safeSearch: settings.safeSearch,
190
+ fallbackOn: [...settings.fallbackOn],
168
191
  anysearchApiKey: settings.anysearchApiKey.trim(),
169
192
  anysearchDomain: settings.anysearchDomain.trim(),
170
193
  domainSourceIds: domainSources.length > 0 ? domainSources : [...DEFAULT_VERTICAL_IDS],
171
194
  domainLimit: settings.domainLimit,
172
195
  domainTimeoutMs: settings.domainTimeoutMs,
196
+ toolSurface: settings.toolSurface,
173
197
  rank: {
174
198
  rrfConstant: settings.rrfConstant,
175
199
  ...(settings.authorityDomains.length > 0 ? { authorityDomains: [...settings.authorityDomains] } : {}),
@@ -20,6 +20,7 @@
20
20
  */
21
21
  import type { Source } from './types.ts';
22
22
  import type { FetchLike } from './verticals.ts';
23
+ import type { TimeRange } from './types.ts';
23
24
  /** The name this tool prefers. */
24
25
  export declare const DOMAIN_TOOL_NAME = "domain_search";
25
26
  /** The name used when another plugin already registered `domain_search`. */
@@ -64,6 +65,10 @@ export interface DomainToolValue {
64
65
  sources: Source[];
65
66
  failures: string[];
66
67
  truncated: boolean;
68
+ /** Present only when this call asked for a publication window. */
69
+ timeRange?: TimeRange;
70
+ /** Why the window did or did not narrow the rows. */
71
+ note?: string;
67
72
  }
68
73
  /** Settings the tool reads live for every call. */
69
74
  export interface DomainToolSettings {
@@ -1,4 +1,6 @@
1
+ import { wrapUntrustedContent } from "./untrusted.js";
1
2
  import { resolveProxy } from "./proxy.js";
3
+ import { TIME_RANGES, filterByTimeRange } from "./freshness.js";
2
4
  import { DEFAULT_VERTICAL_IDS, searchVerticals, isVerticalId, VERTICAL_IDS } from "./verticals.js";
3
5
  /** The name this tool prefers. */
4
6
  export const DOMAIN_TOOL_NAME = 'domain_search';
@@ -32,6 +34,11 @@ function parameterSchema() {
32
34
  type: 'integer',
33
35
  description: 'Results wanted per source, 1–20. Omit to use the deployment default.',
34
36
  },
37
+ timeRange: {
38
+ type: 'string',
39
+ enum: [...TIME_RANGES],
40
+ description: 'Optional publication window: off, day, week, month or year. Sources without publication dates are kept only when no dated row falls inside the window.',
41
+ },
35
42
  },
36
43
  required: ['query'],
37
44
  };
@@ -58,6 +65,8 @@ function outputSchema() {
58
65
  },
59
66
  failures: { type: 'array', items: { type: 'string' } },
60
67
  truncated: { type: 'boolean' },
68
+ timeRange: { type: 'string', enum: [...TIME_RANGES] },
69
+ note: { type: 'string' },
61
70
  },
62
71
  required: ['sources', 'failures', 'truncated'],
63
72
  };
@@ -81,14 +90,22 @@ function parseArgs(args, settings) {
81
90
  const limit = typeof args.limit === 'number'
82
91
  ? clampToolLimit(args.limit, settings.limit)
83
92
  : clampToolLimit(settings.limit, 5);
93
+ const rawRange = args['timeRange'];
94
+ if (rawRange !== undefined) {
95
+ if (typeof rawRange !== 'string' || !TIME_RANGES.includes(rawRange)) {
96
+ throw new Error(`domain_search timeRange must be one of ${TIME_RANGES.join(', ')}`);
97
+ }
98
+ return { query, ids, limit, timeRange: rawRange };
99
+ }
84
100
  return { query, ids, limit };
85
101
  }
86
102
  /** Format the model-facing result text. */
87
103
  export function formatDomainValue(args, value) {
88
104
  const query = isRecord(args) && typeof args.query === 'string' ? args.query : 'the query';
105
+ const window = value.timeRange === undefined ? '' : ` (timeRange=${value.timeRange})`;
89
106
  const head = value.sources.length === 0
90
- ? `No dedicated source returned a result for ${JSON.stringify(query)}.`
91
- : `Dedicated search for ${JSON.stringify(query)}: ${value.sources.length} result(s)${value.truncated ? ' (truncated)' : ''}.`;
107
+ ? `No dedicated source returned a result for ${JSON.stringify(query)}${window}.`
108
+ : `Dedicated search for ${JSON.stringify(query)}${window}: ${value.sources.length} result(s)${value.truncated ? ' (truncated)' : ''}.`;
92
109
  const lines = value.sources.map((source, index) => {
93
110
  const title = source.title !== undefined && source.title.length > 0 ? source.title : source.url;
94
111
  const body = [`${index + 1}. ${title}`, ` ${source.url}`];
@@ -98,6 +115,8 @@ export function formatDomainValue(args, value) {
98
115
  body.push(` ${source.publishedAt}`);
99
116
  return body.join('\n');
100
117
  });
118
+ if (value.note !== undefined && value.note.length > 0)
119
+ lines.push(`Note: ${value.note}`);
101
120
  if (value.failures.length > 0) {
102
121
  lines.push('', 'Unavailable sources:', ...value.failures.map((failure) => `- ${failure}`));
103
122
  }
@@ -118,7 +137,7 @@ export function createDomainToolDefinition(name, readSettings, options = {}) {
118
137
  parameters: parameterSchema(),
119
138
  output: {
120
139
  schema: outputSchema(),
121
- render: (args, value) => [{ type: 'text', text: formatDomainValue(args, value) }],
140
+ render: (args, value) => [{ type: 'text', text: wrapUntrustedContent(formatDomainValue(args, value)) }],
122
141
  },
123
142
  timeoutMs: 30_000,
124
143
  isConcurrencySafe: () => true,
@@ -127,18 +146,38 @@ export function createDomainToolDefinition(name, readSettings, options = {}) {
127
146
  const parsed = parseArgs(args, settings);
128
147
  const explicit = typeof settings.proxy === 'string' ? settings.proxy.trim() : '';
129
148
  const proxy = explicit.length > 0 ? explicit : await detectProxy();
149
+ // Ask for more than the caller needs when a window is active, so filtering
150
+ // does not turn a date-ordered source into a one-row answer.
151
+ const searchLimit = parsed.timeRange === undefined || parsed.timeRange === 'off'
152
+ ? parsed.limit
153
+ : Math.min(20, parsed.limit * 3);
130
154
  const outcome = await searchVerticals(parsed.query, {
131
155
  ids: parsed.ids,
132
- limit: parsed.limit,
156
+ limit: searchLimit,
133
157
  timeoutMs: settings.timeoutMs,
134
158
  ...(proxy === undefined || proxy.length === 0 ? {} : { proxy }),
135
159
  ...(exec.signal === undefined ? {} : { signal: exec.signal }),
160
+ ...(parsed.timeRange === undefined ? {} : { timeRange: parsed.timeRange }),
136
161
  ...(options.fetch === undefined ? {} : { fetch: options.fetch }),
137
162
  });
163
+ if (parsed.timeRange === undefined || parsed.timeRange === 'off') {
164
+ return {
165
+ sources: outcome.sources.slice(0, parsed.limit),
166
+ failures: outcome.failures,
167
+ truncated: outcome.truncated || outcome.sources.length > parsed.limit,
168
+ ...(parsed.timeRange === undefined ? {} : { timeRange: parsed.timeRange }),
169
+ };
170
+ }
171
+ const filtered = filterByTimeRange(outcome.sources, parsed.timeRange);
172
+ const note = filtered.length === 0
173
+ ? `No result was dated inside the ${parsed.timeRange} window.`
174
+ : `${filtered.length} of ${outcome.sources.length} result(s) were dated inside the ${parsed.timeRange} window; undated rows are kept only when no dated row qualified.`;
138
175
  return {
139
- sources: outcome.sources,
176
+ sources: filtered.slice(0, parsed.limit),
140
177
  failures: outcome.failures,
141
- truncated: outcome.truncated,
178
+ truncated: outcome.truncated || outcome.sources.length > parsed.limit,
179
+ timeRange: parsed.timeRange,
180
+ note,
142
181
  };
143
182
  },
144
183
  };
@@ -0,0 +1,116 @@
1
+ /**
2
+ * The model-facing `engine_test` tool: ask every configured engine one tiny
3
+ * query and report which ones answered, how quickly, and why the others did
4
+ * not.
5
+ *
6
+ * This is deliberately separate from `web_search`: a test must not cool an
7
+ * engine down, must not fill the result cache, and must not fall through to a
8
+ * different engine. The caller gets one row per engine, with the same
9
+ * `FailureKind` the fallback policy uses, so "why is my search slow?" has a
10
+ * concrete answer instead of a long `failures` string.
11
+ *
12
+ * @module @fangchenghao/dsh-web-search/engine-test
13
+ */
14
+ import type { EngineFailure, FailureKind, Source } from './types.ts';
15
+ import type { ToolContent, ToolJsonSchema } from './domain-tool.ts';
16
+ /** The name this tool prefers. */
17
+ export declare const ENGINE_TEST_TOOL_NAME = "engine_test";
18
+ /** The name used when another plugin already registered `engine_test`. */
19
+ export declare const ENGINE_TEST_FALLBACK_NAME = "web_engine_test";
20
+ /** Default query; broad enough that every engine has an answer. */
21
+ export declare const ENGINE_TEST_DEFAULT_QUERY = "DeepSeek Harness";
22
+ /** One engine's test result. */
23
+ export interface EngineTestResult {
24
+ engine: string;
25
+ ok: boolean;
26
+ latencyMs: number;
27
+ count: number;
28
+ failureKind?: FailureKind;
29
+ code?: string;
30
+ status?: number;
31
+ reason?: string;
32
+ sample?: string;
33
+ }
34
+ /** What the runner reports for one engine. */
35
+ export interface EngineTestOutcome {
36
+ sources: Source[];
37
+ failureDetails: EngineFailure[];
38
+ failures: string[];
39
+ }
40
+ /** Run one engine through the normal search path with no cache or fallback. */
41
+ export type EngineTestRunner = (engine: string, query: string, signal?: AbortSignal) => Promise<EngineTestOutcome>;
42
+ /** A tool definition in the host registry's native shape. */
43
+ export interface EngineTestDefinition {
44
+ name: string;
45
+ description: string;
46
+ parameters: ToolJsonSchema;
47
+ output: {
48
+ schema: ToolJsonSchema;
49
+ render: (args: unknown, value: EngineTestValue) => ToolContent[];
50
+ };
51
+ timeoutMs?: number;
52
+ isConcurrencySafe?: (args: unknown) => boolean;
53
+ execute: (args: unknown, exec: {
54
+ signal?: AbortSignal;
55
+ }) => Promise<EngineTestValue>;
56
+ }
57
+ /** What the tool returns to the model. */
58
+ export interface EngineTestValue {
59
+ query: string;
60
+ results: EngineTestResult[];
61
+ ok: number;
62
+ failed: number;
63
+ }
64
+ /** The slice of the tool registry this module needs. */
65
+ export interface EngineTestRegistryLike {
66
+ register(definition: EngineTestDefinition): unknown;
67
+ get?(name: string, scope?: unknown): unknown;
68
+ }
69
+ /** Construction seams. */
70
+ export interface EngineTestOptions {
71
+ /** Registration diagnostics. */
72
+ warn?: (message: string) => void;
73
+ }
74
+ /** A successful registration plus the exact way to undo it. */
75
+ export interface EngineTestRegistration {
76
+ name: string;
77
+ dispose: () => void;
78
+ }
79
+ /** Format the model-facing result text. */
80
+ export declare function formatEngineTestValue(value: EngineTestValue): string;
81
+ /**
82
+ * Run a list of engines and assemble the tool value.
83
+ *
84
+ * Exported so the Settings bridge and the model tool share one implementation
85
+ * of latency, sample and failure reporting.
86
+ *
87
+ * @param runTest - tests one engine through the normal search path.
88
+ * @param engines - engine ids to test, in display order.
89
+ * @param query - probe query.
90
+ * @param signal - cancellation from the caller.
91
+ * @returns per-engine results plus counts.
92
+ */
93
+ export declare function runEngineTestValue(runTest: EngineTestRunner, engines: readonly string[], query: string, signal?: AbortSignal): Promise<EngineTestValue>;
94
+ /**
95
+ * Build the tool definition the host registry accepts.
96
+ * @param name - `engine_test`, or the fallback when that name is taken.
97
+ * @param runTest - tests one engine through the normal search path.
98
+ * @returns a registry-ready definition.
99
+ */
100
+ export declare function createEngineTestDefinition(name: string, runTest: EngineTestRunner): EngineTestDefinition;
101
+ /**
102
+ * Pick the tool name this deployment can accept.
103
+ * @param tools - the live registry.
104
+ * @returns the preferred or fallback name.
105
+ */
106
+ export declare function pickEngineTestToolName(tools: EngineTestRegistryLike): string;
107
+ /** Report a registration failure without throwing out of the plugin. */
108
+ export declare function warnEngineTest(message: string): void;
109
+ /**
110
+ * Register the tool and return its undo handle.
111
+ * @param tools - the host tool registry.
112
+ * @param runTest - tests one engine.
113
+ * @param options - diagnostics hook.
114
+ * @returns the registration, or `undefined` when the registry refused it.
115
+ */
116
+ export declare function registerEngineTestTool(tools: EngineTestRegistryLike, runTest: EngineTestRunner, options?: EngineTestOptions): EngineTestRegistration | undefined;