@next-open-ai/openclawx 0.8.32 → 0.8.40

package/dist/core/mcp/index.d.ts

@@ -7,12 +7,16 @@ import type { McpServerConfig, McpServersStandardFormat } from "./types.js";
 export type { McpServerConfig, McpServerConfigStdio, McpServerConfigSse, McpServerConfigStandardEntry, McpServersStandardFormat, McpTool, } from "./types.js";
 export { resolveMcpServersForSession, standardFormatToArray, arrayToStandardFormat, stdioConfigKey, sseConfigKey, mcpConfigKey, } from "./config.js";
 export { McpClient } from "./client.js";
-export { getMcpToolDefinitions, shutdownMcpClients } from "./operator.js";
+export { getMcpToolDefinitions, shutdownMcpClients, type GetMcpToolDefinitionsOptions } from "./operator.js";
 export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js";
 /**
  * 根据会话选项中的 mcpServers 配置，返回该会话可用的 MCP 工具（ToolDefinition 数组）。
  * 支持数组或标准 JSON 对象格式；在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 若提供 sessionId，MCP 连接/重试进度将经全局 sendSessionMessage 以系统消息推送。
  */
 export declare function createMcpToolsForSession(options: {
     mcpServers?: McpServerConfig[] | McpServersStandardFormat;
+    sessionId?: string;
+    /** 单次 MCP 工具返回最大 token；不配置则不限制 */
+    mcpMaxResultTokens?: number;
 }): Promise<ToolDefinition[]>;

package/dist/core/mcp/index.js

@@ -11,10 +11,14 @@ export { mcpToolToToolDefinition, mcpToolsToToolDefinitions } from "./adapter.js
 /**
  * 根据会话选项中的 mcpServers 配置，返回该会话可用的 MCP 工具（ToolDefinition 数组）。
  * 支持数组或标准 JSON 对象格式；在 AgentManager.getOrCreateSession 中调用，并入 customTools。
+ * 若提供 sessionId，MCP 连接/重试进度将经全局 sendSessionMessage 以系统消息推送。
  */
 export async function createMcpToolsForSession(options) {
     const configs = resolveMcpServersForSession(options.mcpServers);
     if (configs.length === 0)
         return [];
-    return getMcpToolDefinitions(configs);
+    return getMcpToolDefinitions(configs, {
+        sessionId: options.sessionId,
+        maxResultTokens: options.mcpMaxResultTokens,
+    });
 }

package/dist/core/mcp/operator.d.ts

@@ -4,11 +4,28 @@
  */
 import type { McpServerConfig } from "./types.js";
 import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+/** getMcpToolDefinitions 的可选参数：超时、重试与 sessionId（用于经 sendSessionMessage 推送进度） */
+export interface GetMcpToolDefinitionsOptions {
+    /** 连接或 list_tools 失败时的重试次数（不含首次，默认 1） */
+    connectRetries?: number;
+    /** 重试间隔（毫秒，默认 3000） */
+    retryDelayMs?: number;
+    /** stdio 初始化超时（毫秒） */
+    initTimeoutMs?: number;
+    /** stdio 初始化重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio 初始化重试间隔（毫秒，默认 3000） */
+    initRetryDelayMs?: number;
+    /** 会话 ID，用于经全局 sendSessionMessage 推送 MCP 进度系统消息 */
+    sessionId?: string;
+    /** 单次 MCP 工具返回最大 token；超过则从尾部裁剪并打日志；不配置则不限制 */
+    maxResultTokens?: number;
+}
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。
- * 连接失败或 list_tools 失败的 server 会被跳过并打日志，不阻塞整体。
+ * 连接失败或 list_tools 失败的 server 会按 options 重试，仍失败则跳过并打日志，不阻塞整体。
  */
-export declare function getMcpToolDefinitions(serverConfigs: McpServerConfig[]): Promise<ToolDefinition[]>;
+export declare function getMcpToolDefinitions(serverConfigs: McpServerConfig[], options?: GetMcpToolDefinitionsOptions): Promise<ToolDefinition[]>;
 /**
  * 关闭并移除所有缓存的 MCP 客户端（进程退出或显式清理时调用）。
  */

package/dist/core/mcp/operator.js

@@ -5,6 +5,7 @@
 import { mcpConfigKey } from "./config.js";
 import { McpClient } from "./client.js";
 import { mcpToolsToToolDefinitions } from "./adapter.js";
+import { sendSessionMessage } from "../session-outlet/index.js";
 /** 按配置键缓存的客户端 */
 const clientCache = new Map();
 function configLabel(config) {
@@ -12,53 +13,119 @@ function configLabel(config) {
         return config.command;
     return config.url;
 }
+/** 用于系统消息展示的 MCP 名称：stdio 优先用首参（如 akshare-tools），否则 command；sse 用 URL 主机或路径末段 */
+function mcpDisplayName(config) {
+    if (config.transport === "stdio") {
+        const args = config.args;
+        const first = args?.[0];
+        if (typeof first === "string" && first.trim() && !first.includes("/") && !first.includes("\\")) {
+            return first.trim();
+        }
+        return config.command;
+    }
+    try {
+        const u = new URL(config.url);
+        const host = u.hostname || u.pathname?.replace(/\/$/, "").split("/").pop() || "MCP";
+        return host;
+    }
+    catch {
+        return config.url;
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
 /**
  * 为给定 MCP 服务器配置列表获取或创建客户端，并返回其工具对应的 ToolDefinition 数组。
- * 连接失败或 list_tools 失败的 server 会被跳过并打日志，不阻塞整体。
+ * 连接失败或 list_tools 失败的 server 会按 options 重试，仍失败则跳过并打日志，不阻塞整体。
  */
-export async function getMcpToolDefinitions(serverConfigs) {
+export async function getMcpToolDefinitions(serverConfigs, options = {}) {
+    const connectRetries = options.connectRetries ?? 1;
+    const retryDelayMs = options.retryDelayMs ?? 3_000;
+    const sessionId = options.sessionId;
+    const clientOptions = {
+        initTimeoutMs: options.initTimeoutMs,
+        initRetries: options.initRetries,
+        initRetryDelayMs: options.initRetryDelayMs,
+    };
+    const emitProgress = (displayMessage, phase, detail) => {
+        if (sessionId) {
+            sendSessionMessage(sessionId, {
+                type: "system",
+                code: "mcp.progress",
+                payload: { phase, message: displayMessage, serverLabel: detail },
+            });
+        }
+    };
     const allTools = [];
     for (let i = 0; i < serverConfigs.length; i++) {
         const config = serverConfigs[i];
         const key = mcpConfigKey(config);
+        const label = configLabel(config);
+        const displayName = mcpDisplayName(config);
         let client = clientCache.get(key);
-        if (!client) {
-            client = new McpClient(config);
-            try {
-                await client.connect();
-                clientCache.set(key, client);
+        if (!client || !client.isConnected) {
+            if (client) {
+                clientCache.delete(key);
+                try {
+                    await client.close();
+                }
+                catch { }
             }
-            catch (err) {
-                console.warn(`[mcp] 连接失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-                continue;
+            emitProgress(`${displayName} MCP connecting`, "connecting");
+            let connected = false;
+            for (let attempt = 0; attempt <= connectRetries; attempt++) {
+                if (attempt > 0) {
+                    emitProgress(`${displayName} MCP retrying (${attempt + 1}/${connectRetries + 1})`, "retrying", "connect");
+                    await sleep(retryDelayMs);
+                }
+                try {
+                    client = new McpClient(config, clientOptions);
+                    await client.connect();
+                    clientCache.set(key, client);
+                    connected = true;
+                    emitProgress(`${displayName} MCP ready`, "ready");
+                    break;
+                }
+                catch (err) {
+                    if (client)
+                        try {
+                            await client.close();
+                        }
+                        catch { }
+                    if (attempt === connectRetries) {
+                        console.warn(`[mcp] 连接失败 (${label}):`, err instanceof Error ? err.message : err);
+                        const errMsg = err instanceof Error ? err.message : String(err);
+                        emitProgress(`${displayName} MCP failed: ${errMsg}`, "skipped", errMsg);
+                    }
+                }
             }
+            if (!connected)
+                continue;
         }
-        if (!client.isConnected) {
-            clientCache.delete(key);
-            try {
-                await client.close();
+        client = clientCache.get(key);
+        let toolsListed = false;
+        for (let attempt = 0; attempt <= connectRetries; attempt++) {
+            if (attempt > 0) {
+                emitProgress(`${displayName} MCP retrying list tools (${attempt + 1}/${connectRetries + 1})`, "retrying", "list_tools");
+                await sleep(retryDelayMs);
             }
-            catch { }
-            const newClient = new McpClient(config);
             try {
-                await newClient.connect();
-                clientCache.set(key, newClient);
-                client = newClient;
+                const tools = await client.listTools();
+                const serverId = `mcp${i}`;
+                const definitions = mcpToolsToToolDefinitions(tools, client, serverId, options.maxResultTokens);
+                allTools.push(...definitions);
+                toolsListed = true;
+                break;
             }
             catch (err) {
-                console.warn(`[mcp] 重连失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-                continue;
+                if (attempt === connectRetries) {
+                    console.warn(`[mcp] list_tools 失败 (${label}):`, err instanceof Error ? err.message : err);
+                    const errMsg = err instanceof Error ? err.message : String(err);
+                    emitProgress(`${displayName} MCP list tools failed: ${errMsg}`, "skipped", errMsg);
+                }
             }
         }
-        try {
-            const tools = await client.listTools();
-            const serverId = `mcp${i}`;
-            const definitions = mcpToolsToToolDefinitions(tools, client, serverId);
-            allTools.push(...definitions);
-        }
-        catch (err) {
-            console.warn(`[mcp] list_tools 失败 (${configLabel(config)}):`, err instanceof Error ? err.message : err);
-        }
     }
     return allTools;
 }

package/dist/core/mcp/transport/index.d.ts

@@ -2,6 +2,10 @@ import type { McpServerConfig, IMcpTransport } from "../types.js";
 export interface TransportOptions {
     initTimeoutMs?: number;
     requestTimeoutMs?: number;
+    /** stdio：初始化失败时的重试次数（默认 1） */
+    initRetries?: number;
+    /** stdio：初始化重试间隔毫秒（默认 3000） */
+    initRetryDelayMs?: number;
 }
 /**
  * 根据配置创建对应的传输层实例。

package/dist/core/mcp/transport/index.js

@@ -5,7 +5,12 @@ import { SseTransport } from "./sse.js";
  */
 export function createTransport(config, options) {
     if (config.transport === "stdio") {
-        return new StdioTransport(config, options);
+        return new StdioTransport(config, {
+            initTimeoutMs: options?.initTimeoutMs,
+            requestTimeoutMs: options?.requestTimeoutMs,
+            initRetries: options?.initRetries,
+            initRetryDelayMs: options?.initRetryDelayMs,
+        });
     }
     if (config.transport === "sse") {
         return new SseTransport(config, options);

package/dist/core/mcp/transport/stdio.d.ts

@@ -8,12 +8,18 @@ export interface StdioTransportOptions {
     initTimeoutMs?: number;
     /** 单次请求超时（毫秒） */
     requestTimeoutMs?: number;
+    /** 初始化失败时的重试次数（不含首次，默认 1，即最多 2 次尝试） */
+    initRetries?: number;
+    /** 初始化重试间隔（毫秒，默认 3000） */
+    initRetryDelayMs?: number;
 }
 export declare class StdioTransport {
     private process;
     private config;
     private initTimeoutMs;
     private requestTimeoutMs;
+    private initRetries;
+    private initRetryDelayMs;
     private nextId;
     private pending;
     private buffer;

package/dist/core/mcp/transport/stdio.js

@@ -8,6 +8,8 @@ export class StdioTransport {
     config;
     initTimeoutMs;
     requestTimeoutMs;
+    initRetries;
+    initRetryDelayMs;
     nextId = 1;
     pending = new Map();
     buffer = "";
@@ -15,6 +17,8 @@ export class StdioTransport {
         this.config = config;
         this.initTimeoutMs = options.initTimeoutMs ?? 10_000;
         this.requestTimeoutMs = options.requestTimeoutMs ?? 30_000;
+        this.initRetries = options.initRetries ?? 1;
+        this.initRetryDelayMs = options.initRetryDelayMs ?? 3_000;
     }
     /** 启动子进程并完成 MCP initialize 握手 */
     async start() {
@@ -43,7 +47,24 @@ export class StdioTransport {
             this.rejectAll(new Error(`MCP process exited: code=${code} signal=${signal}`));
             this.process = null;
         });
-        await this.initialize();
+        const maxAttempts = 1 + this.initRetries;
+        let lastErr = null;
+        for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+            try {
+                await this.initialize();
+                lastErr = null;
+                break;
+            }
+            catch (e) {
+                lastErr = e instanceof Error ? e : new Error(String(e));
+                const isTransient = lastErr.message.includes("timeout") || lastErr.message.includes("MCP process exited");
+                if (!isTransient || attempt >= maxAttempts) {
+                    throw lastErr;
+                }
+                console.warn(`[mcp stdio] initialize 超时或失败，${this.initRetryDelayMs}ms 后重试 (${attempt}/${maxAttempts}):`, lastErr.message);
+                await new Promise((r) => setTimeout(r, this.initRetryDelayMs));
+            }
+        }
     }
     flushLines() {
         const lines = this.buffer.split("\n");

package/dist/core/session-outlet/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * 会话消息统一出口：各模块仅需 sessionId + 消息即可通过统一出口准确送达当前会话对应的 Web/Desktop 或通道。
+ */
+import type { SessionMessageInput, ISessionOutlet } from "./types.js";
+export type { SessionMessage, SessionMessageInput, SessionMessageConsumer, ISessionOutlet } from "./types.js";
+export { SessionOutlet } from "./outlet.js";
+/**
+ * 获取当前使用的出口实例（Gateway 启动时通过 setSessionOutlet 注入）。
+ */
+export declare function getSessionOutlet(): ISessionOutlet | null;
+/**
+ * 设置全局出口实例；传 null 可清空（测试用）。
+ */
+export declare function setSessionOutlet(outlet: ISessionOutlet | null): void;
+/**
+ * 解耦 API：任意模块携带 sessionId 即可发送会话消息，由统一出口路由到正确端。
+ * 若未设置出口或 sessionId 为空，则静默忽略。
+ */
+export declare function sendSessionMessage(sessionId: string, message: Omit<SessionMessageInput, "sessionId">): void;

package/dist/core/session-outlet/index.js

@@ -0,0 +1,33 @@
+/**
+ * 会话消息统一出口：各模块仅需 sessionId + 消息即可通过统一出口准确送达当前会话对应的 Web/Desktop 或通道。
+ */
+export { SessionOutlet } from "./outlet.js";
+let defaultOutlet = null;
+/**
+ * 获取当前使用的出口实例（Gateway 启动时通过 setSessionOutlet 注入）。
+ */
+export function getSessionOutlet() {
+    return defaultOutlet;
+}
+/**
+ * 设置全局出口实例；传 null 可清空（测试用）。
+ */
+export function setSessionOutlet(outlet) {
+    defaultOutlet = outlet;
+}
+/**
+ * 解耦 API：任意模块携带 sessionId 即可发送会话消息，由统一出口路由到正确端。
+ * 若未设置出口或 sessionId 为空，则静默忽略。
+ */
+export function sendSessionMessage(sessionId, message) {
+    if (!sessionId || !message)
+        return;
+    const outlet = getSessionOutlet();
+    if (!outlet)
+        return;
+    outlet.emit(sessionId, {
+        type: message.type,
+        code: message.code,
+        payload: message.payload ?? {},
+    });
+}

package/dist/core/session-outlet/outlet.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 会话消息出口实现：按 sessionId 维护消费者集合，emit 时扇出到该会话所有消费者。
+ */
+import type { SessionMessage, SessionMessageConsumer } from "./types.js";
+export declare class SessionOutlet {
+    private readonly consumersBySession;
+    /**
+     * 向指定会话注册消费者；返回取消注册函数。
+     */
+    registerConsumer(sessionId: string, consumer: SessionMessageConsumer): () => void;
+    /**
+     * 向指定会话发送消息；将 sessionId、timestamp 注入后扇出到该会话所有消费者。
+     */
+    emit(sessionId: string, message: Omit<SessionMessage, "sessionId" | "timestamp">): void;
+}

package/dist/core/session-outlet/outlet.js

@@ -0,0 +1,49 @@
+/**
+ * 会话消息出口实现：按 sessionId 维护消费者集合，emit 时扇出到该会话所有消费者。
+ */
+export class SessionOutlet {
+    consumersBySession = new Map();
+    /**
+     * 向指定会话注册消费者；返回取消注册函数。
+     */
+    registerConsumer(sessionId, consumer) {
+        let set = this.consumersBySession.get(sessionId);
+        if (!set) {
+            set = new Set();
+            this.consumersBySession.set(sessionId, set);
+        }
+        set.add(consumer);
+        return () => {
+            const s = this.consumersBySession.get(sessionId);
+            if (s) {
+                s.delete(consumer);
+                if (s.size === 0)
+                    this.consumersBySession.delete(sessionId);
+            }
+        };
+    }
+    /**
+     * 向指定会话发送消息；将 sessionId、timestamp 注入后扇出到该会话所有消费者。
+     */
+    emit(sessionId, message) {
+        const full = {
+            ...message,
+            sessionId,
+            timestamp: Date.now(),
+        };
+        const set = this.consumersBySession.get(sessionId);
+        if (!set || set.size === 0)
+            return;
+        for (const consumer of set) {
+            try {
+                const result = consumer.send(full);
+                if (result && typeof result.catch === "function") {
+                    result.catch((err) => console.warn("[SessionOutlet] consumer.send rejected:", err));
+                }
+            }
+            catch (err) {
+                console.warn("[SessionOutlet] consumer.send threw:", err);
+            }
+        }
+    }
+}

package/dist/core/session-outlet/types.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 会话消息出口：统一消息类型与消费者接口。
+ * 所有发给各端（Web/Desktop、通道）的会话消息经此抽象，由出口按 sessionId 路由到已注册的消费者。
+ */
+/** 消息类型：对话内容 vs 系统消息（MCP 进度、// 命令结果等） */
+export type SessionMessageType = "chat" | "system";
+/** 系统消息子类型，便于各端区分展示 */
+export type SessionMessageCode = "agent.chunk" | "agent.tool" | "turn_end" | "message_complete" | "agent_end" | "conversation_end" | "mcp.progress" | "command.result";
+/**
+ * 统一会话消息：出口只认 sessionId + 本结构，不关心具体传输。
+ */
+export interface SessionMessage {
+    type: SessionMessageType;
+    code?: SessionMessageCode;
+    payload: Record<string, unknown>;
+    sessionId: string;
+    timestamp?: number;
+}
+/** 发送时调用方可不带 sessionId，由出口注入 */
+export type SessionMessageInput = Omit<SessionMessage, "sessionId"> & {
+    sessionId?: string;
+};
+/**
+ * 消费者接口：各端（Web、通道）注册后，出口将消息推送给 send(message)。
+ */
+export interface SessionMessageConsumer {
+    send(message: SessionMessage): void | Promise<void>;
+}
+/**
+ * 出口接口：支持注册消费者与发送消息，便于注入与测试。
+ */
+export interface ISessionOutlet {
+    emit(sessionId: string, message: Omit<SessionMessage, "sessionId" | "timestamp">): void;
+    registerConsumer(sessionId: string, consumer: SessionMessageConsumer): () => void;
+}

package/dist/core/session-outlet/types.js

@@ -0,0 +1,5 @@
+/**
+ * 会话消息出口：统一消息类型与消费者接口。
+ * 所有发给各端（Web/Desktop、通道）的会话消息经此抽象，由出口按 sessionId 路由到已注册的消费者。
+ */
+export {};

package/dist/core/tools/index.d.ts

@@ -6,3 +6,4 @@ export { createSwitchAgentTool } from "./switch-agent-tool.js";
 export { createListAgentsTool } from "./list-agents-tool.js";
 export { createCreateAgentTool } from "./create-agent-tool.js";
 export { createGetBookmarkTagsTool, createSaveBookmarkTool, createAddBookmarkTagTool, } from "./bookmark-tool.js";
+export { createWebSearchTool } from "./web-search/index.js";

package/dist/core/tools/index.js

@@ -6,3 +6,4 @@ export { createSwitchAgentTool } from "./switch-agent-tool.js";
 export { createListAgentsTool } from "./list-agents-tool.js";
 export { createCreateAgentTool } from "./create-agent-tool.js";
 export { createGetBookmarkTagsTool, createSaveBookmarkTool, createAddBookmarkTagTool, } from "./bookmark-tool.js";
+export { createWebSearchTool } from "./web-search/index.js";

package/dist/core/tools/truncate-result.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 工具返回结果按 token 估算截断：超过 maxTokens 时从尾部裁剪并打日志。
+ * 用于 MCP、web_search 等单次返回可能过大的场景。
+ */
+/** 粗略按字符估算 token（中英混合约 1/3） */
+export declare function estTokensFromChars(chars: number): number;
+/**
+ * 若 text 估算 token 超过 maxTokens，则保留前 maxTokens 对应字符并打日志，否则返回原 text。
+ * @param text 原始文本
+ * @param maxTokens 最大保留 token 数（仅当 > 0 时生效）
+ * @param toolLabel 工具标识，用于日志
+ * @returns 截断后的文本（可能为原 text）
+ */
+export declare function truncateTextToMaxTokens(text: string, maxTokens: number, toolLabel: string): string;

package/dist/core/tools/truncate-result.js

@@ -0,0 +1,27 @@
+/**
+ * 工具返回结果按 token 估算截断：超过 maxTokens 时从尾部裁剪并打日志。
+ * 用于 MCP、web_search 等单次返回可能过大的场景。
+ */
+const LOG_PREFIX = "[tool-result]";
+/** 粗略按字符估算 token（中英混合约 1/3） */
+export function estTokensFromChars(chars) {
+    return Math.ceil(chars / 3);
+}
+/**
+ * 若 text 估算 token 超过 maxTokens，则保留前 maxTokens 对应字符并打日志，否则返回原 text。
+ * @param text 原始文本
+ * @param maxTokens 最大保留 token 数（仅当 > 0 时生效）
+ * @param toolLabel 工具标识，用于日志
+ * @returns 截断后的文本（可能为原 text）
+ */
+export function truncateTextToMaxTokens(text, maxTokens, toolLabel) {
+    if (!text || maxTokens <= 0)
+        return text;
+    const est = estTokensFromChars(text.length);
+    if (est <= maxTokens)
+        return text;
+    const keepChars = Math.max(1, maxTokens * 3);
+    const truncated = text.slice(0, keepChars);
+    console.log(`${LOG_PREFIX} ${toolLabel} 返回超限 estTokens=${est} maxTokens=${maxTokens} 已从尾部裁剪，保留约 ${maxTokens} token`);
+    return truncated;
+}

package/dist/core/tools/web-search/create-web-search-tool.d.ts

@@ -0,0 +1,17 @@
+import type { ToolDefinition } from "@mariozechner/pi-coding-agent";
+export interface WebSearchToolOptions {
+    enabled: boolean;
+    provider: "brave" | "duck-duck-scrape";
+    apiKey?: string;
+    timeoutSeconds?: number;
+    cacheTtlMinutes?: number;
+    maxResults?: number;
+    /** 单次搜索返回内容最大 token；超过则从尾部裁剪并打日志；不配置则不限制 */
+    maxResultTokens?: number;
+}
+/**
+ * 创建 web_search 工具。
+ * - enabled 为 false 时返回 null，调用方不应将工具加入 customTools。
+ * - enabled 为 true 但当前 provider 不可用（如 Brave 无 Key）时仍返回工具，执行时空转，返回固定提示。
+ */
+export declare function createWebSearchTool(options: WebSearchToolOptions): ToolDefinition | null;

package/dist/core/tools/web-search/create-web-search-tool.js

@@ -0,0 +1,87 @@
+import { Type } from "@sinclair/typebox";
+import { getWebSearchProvider } from "./providers/index.js";
+import { truncateTextToMaxTokens } from "../truncate-result.js";
+const WebSearchSchema = Type.Object({
+    query: Type.String({
+        description: "搜索关键词或问题，例如：当前天气、最新新闻、某概念解释等",
+    }),
+    count: Type.Optional(Type.Number({
+        description: "返回结果条数，1-10，默认 5",
+        minimum: 1,
+        maximum: 10,
+    })),
+    country: Type.Optional(Type.String({
+        description: "可选，地区代码（如 us、cn），部分 Provider 支持",
+    })),
+    freshness: Type.Optional(Type.String({
+        description: "可选，时间范围（如 pd、pw、pm），部分 Provider 支持",
+    })),
+});
+const WEB_SEARCH_NOOP_MESSAGE = "当前在线搜索不可用：所选 Provider 未配置或不可用（如选择了 Brave 但未配置 API Key）。请在设置中配置 Brave API Key，或将智能体在线搜索 Provider 改为 DuckDuckGo。";
+/**
+ * 创建 web_search 工具。
+ * - enabled 为 false 时返回 null，调用方不应将工具加入 customTools。
+ * - enabled 为 true 但当前 provider 不可用（如 Brave 无 Key）时仍返回工具，执行时空转，返回固定提示。
+ */
+export function createWebSearchTool(options) {
+    if (!options || options.enabled !== true)
+        return null;
+    const provider = getWebSearchProvider(options.provider);
+    const apiKey = options.provider === "brave" ? options.apiKey : undefined;
+    const available = provider.isAvailable({ apiKey });
+    const timeoutSeconds = options.timeoutSeconds ?? 15;
+    const cacheTtlMinutes = options.cacheTtlMinutes ?? 5;
+    const maxResults = options.maxResults ?? 5;
+    return {
+        name: "web_search",
+        label: "Web Search",
+        description: "联网搜索：根据查询词从互联网获取最新结果（标题、链接、摘要）。无 API Key 时使用 DuckDuckGo；配置 Brave API Key 后可选用 Brave。在回答需要实时信息、新闻、天气、概念解释等问题前可调用本工具。",
+        parameters: WebSearchSchema,
+        execute: async (_toolCallId, params, _signal, _onUpdate, _ctx) => {
+            if (!available) {
+                return {
+                    content: [{ type: "text", text: WEB_SEARCH_NOOP_MESSAGE }],
+                    details: undefined,
+                };
+            }
+            const query = (params.query ?? "").trim();
+            if (!query) {
+                return {
+                    content: [{ type: "text", text: "请提供搜索关键词（query）。" }],
+                    details: undefined,
+                };
+            }
+            const count = Math.min(10, Math.max(1, params.count ?? maxResults));
+            try {
+                const result = await provider.search({
+                    query,
+                    count,
+                    apiKey,
+                    timeoutSeconds,
+                    cacheTtlMinutes,
+                    country: params.country,
+                    freshness: params.freshness,
+                });
+                const lines = result.results.map((r, i) => `${i + 1}. ${r.title}\n   ${r.url}${r.description ? `\n   ${r.description}` : ""}`);
+                let text = (result.cached ? "[缓存] " : "") +
+                    `搜索「${result.query}」共 ${result.count} 条（${result.provider}${result.tookMs != null ? `, ${result.tookMs}ms` : ""}）：\n\n` +
+                    (lines.length ? lines.join("\n\n") : "未找到结果。");
+                const maxResultTokens = options.maxResultTokens;
+                if (typeof maxResultTokens === "number" && maxResultTokens > 0) {
+                    text = truncateTextToMaxTokens(text, maxResultTokens, "web_search");
+                }
+                return {
+                    content: [{ type: "text", text }],
+                    details: { query: result.query, count: result.count, provider: result.provider },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `在线搜索失败: ${msg}` }],
+                    details: undefined,
+                };
+            }
+        },
+    };
+}

package/dist/core/tools/web-search/index.d.ts

@@ -0,0 +1,4 @@
+export { createWebSearchTool } from "./create-web-search-tool.js";
+export type { WebSearchToolOptions } from "./create-web-search-tool.js";
+export type { WebSearchProviderId, WebSearchResultItem, WebSearchProviderResult, IWebSearchProvider, WebSearchSearchParams, } from "./types.js";
+export { getWebSearchProvider } from "./providers/index.js";

package/dist/core/tools/web-search/index.js

@@ -0,0 +1,2 @@
+export { createWebSearchTool } from "./create-web-search-tool.js";
+export { getWebSearchProvider } from "./providers/index.js";

package/dist/core/tools/web-search/providers/brave.d.ts

@@ -0,0 +1,2 @@
+import type { IWebSearchProvider } from "../types.js";
+export declare const braveProvider: IWebSearchProvider;