minimal-agent 0.13.0 → 0.14.0

package/src/tools/webfetch/preapproved.js

@@ -104,8 +104,6 @@ const PREAPPROVED_HOSTS = new Set([
     'dev.mysql.com',
     'docs.mongodb.com',
     'www.mongodb.com',
-    'sqlite.org',
-    'www.sqlite.org',
     // 工具类
     'regex101.com',
     'ihateregex.io',

package/src/tools/webfetch/preapproved.ts

@@ -105,8 +105,6 @@ const PREAPPROVED_HOSTS = new Set<string>([
   'dev.mysql.com',
   'docs.mongodb.com',
   'www.mongodb.com',
-  'sqlite.org',
-  'www.sqlite.org',
   // 工具类
   'regex101.com',
   'ihateregex.io',

package/src/tools/websearch/websearch.js

@@ -21,6 +21,9 @@
  *    max_results   可选，默认 5（Tavily 上限 20）
  *    search_depth  可选 'basic' | 'advanced'，默认 basic
  *    topic         可选 'general' | 'news'，默认 general
+ *    recency       可选自动/相对/本年时间窗口
+ *    start_date    可选 YYYY-MM-DD 绝对起始日期
+ *    end_date      可选 YYYY-MM-DD 绝对结束日期
  *
  *  输出：
  *    每条结果一段：
@@ -35,6 +38,16 @@ import { configService } from '../../config/configService.js';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 // ---------------- 1. Zod 输入 schema ----------------
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+function isValidIsoDate(value) {
+    if (!ISO_DATE.test(value))
+        return false;
+    const [year, month, day] = value.split('-').map(Number);
+    const date = new Date(Date.UTC(year, month - 1, day));
+    return date.getUTCFullYear() === year
+        && date.getUTCMonth() === month - 1
+        && date.getUTCDate() === day;
+}
 const inputSchema = z.object({
     query: z
         .string()
@@ -56,6 +69,27 @@ const inputSchema = z.object({
         .enum(['general', 'news'])
         .optional()
         .describe('general=通用网页；news=偏新闻源；默认 general'),
+    recency: z
+        .enum(['auto', 'none', 'day', 'week', 'month', 'year', 'current_year'])
+        .optional()
+        .describe('时效范围：auto 根据查询识别；none 不限时间；day/week/month/year 为相对窗口；current_year 今年优先且结果不足时扩展到去年'),
+    start_date: z
+        .string()
+        .refine(isValidIsoDate, 'start_date 必须是有效的 YYYY-MM-DD 日期')
+        .optional()
+        .describe('只返回该日期之后发布或更新的结果；与 end_date 配合使用'),
+    end_date: z
+        .string()
+        .refine(isValidIsoDate, 'end_date 必须是有效的 YYYY-MM-DD 日期')
+        .optional()
+        .describe('只返回该日期之前发布或更新的结果；与 start_date 配合使用'),
+}).superRefine((input, ctx) => {
+    if (input.start_date && input.end_date && input.start_date > input.end_date) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['end_date'], message: 'end_date 不能早于 start_date' });
+    }
+    if ((input.start_date || input.end_date) && input.recency && !['auto', 'none'].includes(input.recency)) {
+        ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['recency'], message: '绝对日期范围与相对 recency 不能同时使用' });
+    }
 });
 // ---------------- 2. JSON Schema（由 Zod 自动派生） ----------------
 const parameters = toToolParameters(inputSchema);
@@ -65,9 +99,62 @@ const description = `Searches the public web through Tavily and returns structur
 - It does not open or operate a browser. Use returned URLs with WebFetch when full source text is needed.
 - Results contain title, URL and a text snippet. They are discovery evidence, not a substitute for reading a high-value source in full.
 - Keep each query focused on one sub-question. When another search is needed, change the keywords, source, or angle instead of repeating the same query.
-- Add an explicit date or year only when recency matters; stable concepts and exact names should remain exact.
+- Stable concepts and explicit historical queries remain unfiltered. Use recency="day" for today, and recency="current_year" for current/latest/this-year facts; current-year searches widen to the previous year only when the current-year result set is sparse. recency="auto" is a convenience classifier when the query still contains its temporal wording.
+- Use recency="none" to explicitly disable automatic freshness, or start_date/end_date for an exact historical range.
 - \`search_depth: "advanced"\` is slower but can return a synthesized answer; \`topic: "news"\` favors news sources.
 - Requires a configured Tavily API key.`;
+function localIsoDate(now) {
+    const parts = new Intl.DateTimeFormat('en-CA', {
+        timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+        year: 'numeric', month: '2-digit', day: '2-digit',
+    }).formatToParts(now);
+    const part = (type) => parts.find((item) => item.type === type)?.value ?? '';
+    return `${part('year')}-${part('month')}-${part('day')}`;
+}
+function resolveSearchWindow(input, now) {
+    if (input.start_date || input.end_date) {
+        return {
+            ...(input.start_date ? { startDate: input.start_date } : {}),
+            ...(input.end_date ? { endDate: input.end_date } : {}),
+            label: `${input.start_date ?? '最早'} 至 ${input.end_date ?? '今天'}`,
+            source: 'explicit',
+        };
+    }
+    const requested = input.recency ?? 'auto';
+    if (requested === 'none')
+        return { source: 'none' };
+    const today = localIsoDate(now);
+    const year = Number(today.slice(0, 4));
+    const makeCurrentYear = (source) => ({
+        startDate: `${year}-01-01`, endDate: today,
+        currentYearFallback: { expandedStartDate: `${year - 1}-01-01`, minimumResults: 3 },
+        label: `${year}-01-01 至 ${today}`,
+        source,
+    });
+    if (requested === 'current_year')
+        return makeCurrentYear('explicit');
+    const relativeLabel = (range) => ({
+        day: '最近一天', week: '最近一周', month: '最近一个月', year: '最近一年',
+    })[range];
+    if (requested !== 'auto')
+        return { timeRange: requested, label: relativeLabel(requested), source: 'explicit' };
+    const query = input.query.toLowerCase();
+    // An explicit past year means the user is asking about history; do not let a
+    // nearby word such as "current comparison" erase that requested period.
+    const explicitYears = [...query.matchAll(/(?:19|20)\d{2}/g)].map((match) => Number(match[0]));
+    if (explicitYears.some((value) => value !== year))
+        return { source: 'none' };
+    if (/(?:今天|今日|当天|\btoday\b)/i.test(query))
+        return { timeRange: 'day', label: relativeLabel('day'), source: 'auto' };
+    if (/(?:本周|这周|最近一周|\bthis week\b|\bpast week\b)/i.test(query))
+        return { timeRange: 'week', label: relativeLabel('week'), source: 'auto' };
+    if (/(?:本月|这个月|最近一个月|近期|\bthis month\b|\bpast month\b|\brecent(?:ly)?\b)/i.test(query))
+        return { timeRange: 'month', label: relativeLabel('month'), source: 'auto' };
+    if (/(?:今年|本年|当前|目前|现任|最新|最新版|实时|截至现在|\bthis year\b|\bcurrent\b|\blatest\b|\bnewest\b|\bup[- ]to[- ]date\b)/i.test(query)) {
+        return makeCurrentYear('auto');
+    }
+    return { source: 'none' };
+}
 // ---------------- 4b. 退避重试 ----------------
 //
 // 为什么需要（与单发 fetch 零重试的旧行为对比）：WebSearch 是 isConcurrencySafe 工具，
@@ -180,7 +267,7 @@ async function fetchTavilyWithRetry(body, signal) {
     };
 }
 // ---------------- 5. call() ----------------
-async function call(input, signal, getApiKey = async () => (await configService.tool('webSearch'))?.apiKey) {
+async function call(input, signal, getApiKey = async () => (await configService.tool('webSearch'))?.apiKey, now = () => new Date()) {
     // 5a. 取 key
     const apiKey = await getApiKey();
     if (!apiKey) {
@@ -190,7 +277,8 @@ async function call(input, signal, getApiKey = async () => (await configService.
                 '请在 KakadeAI 设置 → 工具 → 联网搜索中配置，或在 env 模式提供 TAVILY_API_KEY。',
         };
     }
-    const body = {
+    const window = resolveSearchWindow(input, now());
+    const baseBody = {
         api_key: apiKey,
         // Preserve the exact research query. The prompt layer adds a date only
         // when recency matters; unconditional mutation hurts exact names,
@@ -202,21 +290,53 @@ async function call(input, signal, getApiKey = async () => (await configService.
         // 让 advanced 模式自动给 answer；basic 不会有
         include_answer: input.search_depth === 'advanced',
     };
+    const buildBody = (selected) => ({
+        ...baseBody,
+        ...(selected.timeRange ? { time_range: selected.timeRange } : {}),
+        ...(selected.startDate ? { start_date: selected.startDate } : {}),
+        ...(selected.endDate ? { end_date: selected.endDate } : {}),
+    });
     // 5c. 发请求（带退避重试，吸收 dev/免费 key 在并发突发下的 socket 切断 + 429/5xx）
-    const fetched = await fetchTavilyWithRetry(body, signal);
+    const fetched = await fetchTavilyWithRetry(buildBody(window), signal);
     if (!fetched.ok)
         return { ok: false, error: fetched.error };
-    const data = fetched.data;
+    let data = fetched.data;
+    let effectiveWindow = window;
+    let fallbackNote = '';
+    const fallback = window.currentYearFallback;
+    const minimumResults = Math.min(fallback?.minimumResults ?? 0, input.max_results ?? 5);
+    if (fallback && (data.results?.length ?? 0) < minimumResults) {
+        const expanded = {
+            ...window,
+            startDate: fallback.expandedStartDate,
+            label: `${fallback.expandedStartDate} 至 ${window.endDate}`,
+        };
+        const wider = await fetchTavilyWithRetry(buildBody(expanded), signal);
+        if (wider.ok) {
+            data = wider.data;
+            effectiveWindow = expanded;
+            fallbackNote = `今年结果不足 ${minimumResults} 条，已自动扩展到上一年。`;
+        }
+        else if ((data.results?.length ?? 0) === 0) {
+            return { ok: false, error: wider.error };
+        }
+        else {
+            fallbackNote = `今年结果不足 ${minimumResults} 条；扩展到上一年的检索失败，以下保留今年结果。`;
+        }
+    }
     // 5d. 取结果
     const results = data.results ?? [];
     if (results.length === 0) {
         return {
             ok: true,
-            content: `(no results for "${input.query}")`,
+            content: `${effectiveWindow.label ? `【检索时间范围】${effectiveWindow.label}\n` : ''}(no results for "${input.query}")`,
         };
     }
     // 5e. 拼输出
     const parts = [];
+    if (effectiveWindow.label) {
+        parts.push(`【检索时间范围】${effectiveWindow.label}${fallbackNote ? `；${fallbackNote}` : ''}`);
+    }
     if (data.answer) {
         parts.push(`【综合回答】\n${data.answer}\n`);
     }
@@ -234,12 +354,13 @@ async function call(input, signal, getApiKey = async () => (await configService.
     return { ok: true, content };
 }
 // ---------------- 6. 导出 ----------------
-export function createWebSearchTool(getApiKey = async () => (await configService.tool('webSearch'))?.apiKey) {
+export function createWebSearchTool(getApiKey = async () => (await configService.tool('webSearch'))?.apiKey, now = () => new Date()) {
     return {
         name: 'WebSearch', description, inputSchema, parameters, isReadOnly: true,
         isConcurrencySafe: true, maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
         interruptBehavior: () => 'cancel',
-        call: (input, signal) => call(input, signal, getApiKey),
+        call: (input, signal) => call(input, signal, getApiKey, now),
     };
 }
 export const webSearchTool = createWebSearchTool();
+export { resolveSearchWindow as _resolveSearchWindow };

package/src/tools/websearch/websearch.ts

@@ -21,6 +21,9 @@
  *    max_results   可选，默认 5（Tavily 上限 20）
  *    search_depth  可选 'basic' | 'advanced'，默认 basic
  *    topic         可选 'general' | 'news'，默认 general
+ *    recency       可选自动/相对/本年时间窗口
+ *    start_date    可选 YYYY-MM-DD 绝对起始日期
+ *    end_date      可选 YYYY-MM-DD 绝对结束日期
  *
  *  输出：
  *    每条结果一段：
@@ -39,6 +42,17 @@ import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
 
 // ---------------- 1. Zod 输入 schema ----------------
+const ISO_DATE = /^\d{4}-\d{2}-\d{2}$/;
+
+function isValidIsoDate(value: string): boolean {
+  if (!ISO_DATE.test(value)) return false;
+  const [year, month, day] = value.split('-').map(Number);
+  const date = new Date(Date.UTC(year!, month! - 1, day));
+  return date.getUTCFullYear() === year
+    && date.getUTCMonth() === month! - 1
+    && date.getUTCDate() === day;
+}
+
 const inputSchema = z.object({
   query: z
     .string()
@@ -60,6 +74,27 @@ const inputSchema = z.object({
     .enum(['general', 'news'])
     .optional()
     .describe('general=通用网页；news=偏新闻源；默认 general'),
+  recency: z
+    .enum(['auto', 'none', 'day', 'week', 'month', 'year', 'current_year'])
+    .optional()
+    .describe('时效范围：auto 根据查询识别；none 不限时间；day/week/month/year 为相对窗口；current_year 今年优先且结果不足时扩展到去年'),
+  start_date: z
+    .string()
+    .refine(isValidIsoDate, 'start_date 必须是有效的 YYYY-MM-DD 日期')
+    .optional()
+    .describe('只返回该日期之后发布或更新的结果；与 end_date 配合使用'),
+  end_date: z
+    .string()
+    .refine(isValidIsoDate, 'end_date 必须是有效的 YYYY-MM-DD 日期')
+    .optional()
+    .describe('只返回该日期之前发布或更新的结果；与 start_date 配合使用'),
+}).superRefine((input, ctx) => {
+  if (input.start_date && input.end_date && input.start_date > input.end_date) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['end_date'], message: 'end_date 不能早于 start_date' });
+  }
+  if ((input.start_date || input.end_date) && input.recency && !['auto', 'none'].includes(input.recency)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ['recency'], message: '绝对日期范围与相对 recency 不能同时使用' });
+  }
 });
 type WebSearchInput = z.infer<typeof inputSchema>;
 
@@ -72,7 +107,8 @@ const description = `Searches the public web through Tavily and returns structur
 - It does not open or operate a browser. Use returned URLs with WebFetch when full source text is needed.
 - Results contain title, URL and a text snippet. They are discovery evidence, not a substitute for reading a high-value source in full.
 - Keep each query focused on one sub-question. When another search is needed, change the keywords, source, or angle instead of repeating the same query.
-- Add an explicit date or year only when recency matters; stable concepts and exact names should remain exact.
+- Stable concepts and explicit historical queries remain unfiltered. Use recency="day" for today, and recency="current_year" for current/latest/this-year facts; current-year searches widen to the previous year only when the current-year result set is sparse. recency="auto" is a convenience classifier when the query still contains its temporal wording.
+- Use recency="none" to explicitly disable automatic freshness, or start_date/end_date for an exact historical range.
 - \`search_depth: "advanced"\` is slower but can return a synthesized answer; \`topic: "news"\` favors news sources.
 - Requires a configured Tavily API key.`;
 
@@ -90,6 +126,65 @@ interface TavilyResponse {
   results?: TavilyResult[];
 }
 
+type RelativeRange = 'day' | 'week' | 'month' | 'year';
+type SearchWindow = {
+  timeRange?: RelativeRange;
+  startDate?: string;
+  endDate?: string;
+  currentYearFallback?: { expandedStartDate: string; minimumResults: number };
+  label?: string;
+  source: 'none' | 'auto' | 'explicit';
+};
+
+function localIsoDate(now: Date): string {
+  const parts = new Intl.DateTimeFormat('en-CA', {
+    timeZone: Intl.DateTimeFormat().resolvedOptions().timeZone,
+    year: 'numeric', month: '2-digit', day: '2-digit',
+  }).formatToParts(now);
+  const part = (type: Intl.DateTimeFormatPartTypes): string =>
+    parts.find((item) => item.type === type)?.value ?? '';
+  return `${part('year')}-${part('month')}-${part('day')}`;
+}
+
+function resolveSearchWindow(input: WebSearchInput, now: Date): SearchWindow {
+  if (input.start_date || input.end_date) {
+    return {
+      ...(input.start_date ? { startDate: input.start_date } : {}),
+      ...(input.end_date ? { endDate: input.end_date } : {}),
+      label: `${input.start_date ?? '最早'} 至 ${input.end_date ?? '今天'}`,
+      source: 'explicit',
+    };
+  }
+  const requested = input.recency ?? 'auto';
+  if (requested === 'none') return { source: 'none' };
+  const today = localIsoDate(now);
+  const year = Number(today.slice(0, 4));
+  const makeCurrentYear = (source: SearchWindow['source']): SearchWindow => ({
+    startDate: `${year}-01-01`, endDate: today,
+    currentYearFallback: { expandedStartDate: `${year - 1}-01-01`, minimumResults: 3 },
+    label: `${year}-01-01 至 ${today}`,
+    source,
+  });
+  if (requested === 'current_year') return makeCurrentYear('explicit');
+  const relativeLabel = (range: RelativeRange): string => ({
+    day: '最近一天', week: '最近一周', month: '最近一个月', year: '最近一年',
+  })[range];
+  if (requested !== 'auto') return { timeRange: requested, label: relativeLabel(requested), source: 'explicit' };
+
+  const query = input.query.toLowerCase();
+  // An explicit past year means the user is asking about history; do not let a
+  // nearby word such as "current comparison" erase that requested period.
+  const explicitYears = [...query.matchAll(/(?:19|20)\d{2}/g)].map((match) => Number(match[0]));
+  if (explicitYears.some((value) => value !== year)) return { source: 'none' };
+  if (/(?:今天|今日|当天|\btoday\b)/i.test(query)) return { timeRange: 'day', label: relativeLabel('day'), source: 'auto' };
+  if (/(?:本周|这周|最近一周|\bthis week\b|\bpast week\b)/i.test(query)) return { timeRange: 'week', label: relativeLabel('week'), source: 'auto' };
+  if (/(?:本月|这个月|最近一个月|近期|\bthis month\b|\bpast month\b|\brecent(?:ly)?\b)/i.test(query)) return { timeRange: 'month', label: relativeLabel('month'), source: 'auto' };
+  if (/(?:今年|本年|当前|目前|现任|最新|最新版|实时|截至现在|\bthis year\b|\bcurrent\b|\blatest\b|\bnewest\b|\bup[- ]to[- ]date\b)/i.test(query)) {
+    return makeCurrentYear('auto');
+  }
+  return { source: 'none' };
+}
+
 // ---------------- 4b. 退避重试 ----------------
 //
 // 为什么需要（与单发 fetch 零重试的旧行为对比）：WebSearch 是 isConcurrencySafe 工具，
@@ -215,6 +310,7 @@ async function call(
   input: WebSearchInput,
   signal?: AbortSignal,
   getApiKey: () => Promise<string | undefined> = async () => (await configService.tool('webSearch'))?.apiKey,
+  now: () => Date = () => new Date(),
 ): Promise<ToolResult> {
   // 5a. 取 key
   const apiKey = await getApiKey();
@@ -227,7 +323,8 @@ async function call(
     };
   }
 
-  const body = {
+  const window = resolveSearchWindow(input, now());
+  const baseBody = {
     api_key: apiKey,
     // Preserve the exact research query. The prompt layer adds a date only
     // when recency matters; unconditional mutation hurts exact names,
@@ -240,22 +337,54 @@ async function call(
     include_answer: input.search_depth === 'advanced',
   };
 
+  const buildBody = (selected: SearchWindow): Record<string, unknown> => ({
+    ...baseBody,
+    ...(selected.timeRange ? { time_range: selected.timeRange } : {}),
+    ...(selected.startDate ? { start_date: selected.startDate } : {}),
+    ...(selected.endDate ? { end_date: selected.endDate } : {}),
+  });
+
   // 5c. 发请求（带退避重试，吸收 dev/免费 key 在并发突发下的 socket 切断 + 429/5xx）
-  const fetched = await fetchTavilyWithRetry(body, signal);
+  const fetched = await fetchTavilyWithRetry(buildBody(window), signal);
   if (!fetched.ok) return { ok: false, error: fetched.error };
-  const data = fetched.data;
+  let data = fetched.data;
+  let effectiveWindow = window;
+  let fallbackNote = '';
+
+  const fallback = window.currentYearFallback;
+  const minimumResults = Math.min(fallback?.minimumResults ?? 0, input.max_results ?? 5);
+  if (fallback && (data.results?.length ?? 0) < minimumResults) {
+    const expanded: SearchWindow = {
+      ...window,
+      startDate: fallback.expandedStartDate,
+      label: `${fallback.expandedStartDate} 至 ${window.endDate}`,
+    };
+    const wider = await fetchTavilyWithRetry(buildBody(expanded), signal);
+    if (wider.ok) {
+      data = wider.data;
+      effectiveWindow = expanded;
+      fallbackNote = `今年结果不足 ${minimumResults} 条，已自动扩展到上一年。`;
+    } else if ((data.results?.length ?? 0) === 0) {
+      return { ok: false, error: wider.error };
+    } else {
+      fallbackNote = `今年结果不足 ${minimumResults} 条；扩展到上一年的检索失败，以下保留今年结果。`;
+    }
+  }
 
   // 5d. 取结果
   const results = data.results ?? [];
   if (results.length === 0) {
     return {
       ok: true,
-      content: `(no results for "${input.query}")`,
+      content: `${effectiveWindow.label ? `【检索时间范围】${effectiveWindow.label}\n` : ''}(no results for "${input.query}")`,
     };
   }
 
   // 5e. 拼输出
   const parts: string[] = [];
+  if (effectiveWindow.label) {
+    parts.push(`【检索时间范围】${effectiveWindow.label}${fallbackNote ? `；${fallbackNote}` : ''}`);
+  }
   if (data.answer) {
     parts.push(`【综合回答】\n${data.answer}\n`);
   }
@@ -280,13 +409,16 @@ async function call(
 // ---------------- 6. 导出 ----------------
 export function createWebSearchTool(
   getApiKey: () => Promise<string | undefined> = async () => (await configService.tool('webSearch'))?.apiKey,
+  now: () => Date = () => new Date(),
 ): Tool<WebSearchInput> {
   return {
     name: 'WebSearch', description, inputSchema, parameters, isReadOnly: true,
     isConcurrencySafe: true, maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'cancel',
-    call: (input, signal) => call(input, signal, getApiKey),
+    call: (input, signal) => call(input, signal, getApiKey, now),
   };
 }
 
 export const webSearchTool = createWebSearchTool();
+
+export { resolveSearchWindow as _resolveSearchWindow };